xieyi-weixin-/WXWORK_PROTOCOL_ANALYSIS.md

本机企业微信协议分析与当前实现

日期：2026-09-14
结论：已实现内置 SDK 的通信层和诊断接入；本机 SDK 运行时尚未连通，原账号客户单聊发送、身份和回执均未验证，P0 未通过，暂不能使用协议自动回复。

最新直接协议尝试见 本机加密协议实测：已定位本地 TCP 加密结构并实际尝试初始化，连接在发送数据前被关闭，尚未进入消息发送阶段。

用户反馈后的复查（17:19）

用户截图确认协议自动回复不可用。这不是用户漏配参数：本项目尚未实现并验证适配 5.0.10.6023 的原账号发送器。 上一轮的通信层测试、EXE 构建与检测成功均不能表示核心需求完成。将内置 SDK 视作可直接接入的员工单聊发送通道，目前证据不足。

本次实际修复：页头操作区缺省值导致右上角显示 undefined；已修改实际加载的 console-app.js，并同步到用户正在运行的 dist/ZhenAI-WeCom-Assistant-v1.4.9/_internal/assets/ui/console-app.js。SDK 未连接徽标不再提示用户等待授权启动。52 项相关页面与控制台回归通过，真实 Qt 页面断言包含不显示 undefined。现有 EXE 主体未重新编译；重新打开应用后加载更新的资源。没有重启用户的监听，没有发送真实消息。

进一步核对：

• 客户端代理启动代码包含灰度开关、系统配置与签名检查；客户端负责生成 agent-client-config.json 与工作目录。静态分支只能证明存在这些条件，不能推断本账号开关实际值。
• 当前没有运行的 wecom-agent.exe；在已检查的 WXWork/Tencent 专用文档、Roaming、Local、ProgramData 目录中未发现 agent-client-config.json 或 openclaw.json。独立 EXE 无法凭程序已安装就自动继承代理 Python 工具的 RPC 参数。
• 内置代理中可见 aibot_send_msg 字符串，没有定位到旧 CLI 文档中三个消息命令的同名字符串；字符串扫描不足以证明方法不存在，也不足以确定原员工发送作用域。
• 已核对 wxhook 的企微版本说明，列出至 5.0.3.6005；其公开示例主要是个人微信。另两个候选 WeChatWork-API 和 wxwork_pc_api 分别声明 5.0.0、3.0.27.2701。它们均未提供本次已验证的 5.0.10.6023 原账号收发适配。没有将旧版 DLL 注入当前客户端，也没有降级现有企业微信。

后续需完成当前版本内部发送接口的独立适配，或取得确切支持本版本的原账号桥接实现，再进行已授权的目标会话实测。当前没有可以通过修改页面状态或填写猜测参数来启用协议发送的已知方法。

本次证据：tmp/protocol-native-launch-strings.json、tmp/protocol-followup-launch-evidence.json、tmp/protocol-bundled-cli-send-contract.json、tmp/protocol-followup-ui-validation.json；改动前备份在 tmp/protocol-followup-before。

本轮实际结果

验收项	结果与证据
安装组件	企业微信 5.0.10.6023，x86；发现 WeComAgent 程序和 Python SDK 源码
通信契约	已按安装包 _rpc.py 实现 TCP NDJSON 握手及 wecom.exec 请求/响应
本机 SDK 连接	未获得正常运行时提供的连接参数；实际报告为 sdk_runtime_unavailable
正常启动入口	用户反馈未看到“智能助手／本地智能体（WeClaw）”入口；没有确认其他可用的正常启动方式
原账号、原客户会话	尚未由在线 SDK 验证；历史数据库记录不能证明当前在线身份
真实文本发送	未执行；用户已指定可用测试会话“小迷糊”或“高瑞”，预定文本“协议通道测试，请忽略”
发送回执	未验证；没有已关联到原账号、原会话和发送事务的服务端消息 ID
产品状态	显示“SDK 运行时待连接”；协议启动仍被拦截，canSend、sendVerified、receiptVerified 均为 false
EXE	已构建 1.4.9，包内自检和精简 PATH 下的实际 EXE 协议诊断通过；协议能力仍不可用

没有看到入口不能单独证明账号不在灰度范围，连接重置也不能单独证明某种加密配置已启用。当前能够确认的限制是：本项目没有获得客户端正常提供的 SDK 运行时连接参数，也没有成功握手或发送证据。

已实现功能

功能	当前行为
独立回复通道	自动化设置中分别保存视觉/协议模式与自动发送/人工审核模式
SDK 通信层	仅连接本机回环地址；支持带令牌的 hello/welcome 握手、顺序请求 ID、UTF-8 和有界响应帧
SDK 异常处理	拒绝无效地址、无效响应和错误 ID；请求写出后断连/超时标记为可能已执行，不自动重发
只读运行时探测	有正常运行时参数时，仅握手并请求 --help；RPC 连通也不标记登录、发送或回执已验证
后台检测与状态	读取企业微信进程、版本、PE 架构、程序文件及内置 SDK；增加独立 SDK 连接状态
报告导出	JSON 原子写入；包含元数据与诊断，不记录令牌值、账号目录、聊天正文
EXE 诊断命令	新增 --protocol-diagnostics REPORT.json，在创建 Qt 界面、登录及监听前执行诊断后退出
启动保护	未适配时禁止协议启动，后台线程在构造视觉机器人之前独立拦截
配置保护	监听时禁止切换通道；未知通道不回退到视觉；配置写入失败恢复内存值
精确上下文	增加按 account + conv_id 查询的接口；区分同名客户与不同账号，保留数据库读取异常
构建路径	为外置归档源码增加仅用于构建的 WECOM_BUILD_EXPORTER_DIR，不影响包内运行时发现与自检

入口：Qt 客户端 → 自动化设置 → 回复通道 → 检测本机协议。选择协议模式后，“启动”只执行检测；视觉模式继续沿用现有能力。

本轮代码：wecom_sdk_client.py、wxwork_protocol_probe.py、wechat_gui_qt.py、assets/ui/console-app.js、wechat_rpa.spec、test_wecom_sdk_client.py。前轮已改 reply_transport.py、gui_runtime.py、wxwork_db.py、reply_database.py、wechat_gui.py 等基础模块。

本机接口证据

实际程序：C:\Program Files (x86)\WXWork\WXWork.exe，版本 5.0.10.6023，架构 x86 / 32 位。SHA-256：47b5dfafc8def0b41a648610f1ba08bbf15f710c6f81c08d36c485bd82ce2842。当前项目 Python 是 64 位，不能直接在其中加载该客户端的 32 位 DLL。

安装目录中的 SDK：5.0.10.6023\WeComAgent\python\3.10\site-packages\wecomagent\_rpc.py。源码说明代理向其启动的 Python 工具注入 WECOMAGENT_RPC_HOST、WECOMAGENT_RPC_PORT、WECOMAGENT_RPC_TOKEN；先发送 hello 并接收 welcome，再以 wecom.exec 和 argv 调用。已实现该通信契约，但该 Python 文件本身没有提供已验证的原员工客户单聊发送方法。

主程序静态信息包含 MCP/WeClaw 服务、TCP AES 密钥生成分支、功能开关和连接签名检查。观察到的回环监听包括 9882、9883、50018、50010；普通 HTTP GET、JSON-RPC initialize 和 TLS 连接尝试均被重置/中断，没有获得标准 MCP 会话、工具列表或 SDK 授权参数。这是普通连接未能建立的证据，不是成功识别或解密传输协议的证据。

程序中出现 SendTextMessage、sendChatMessage、WeClawMcpToolManager 等名字，涉及 RTTI、JS API 处理器和内部日志；没有据此确认可调用函数签名、参数结构或原账号发送语义。WXWorkCommand.exe 的已观察命令与云盘、图片预览有关，未发现已验证的文本发送命令。

前次运行 wecom-agent.exe --help 没有返回帮助，而是初始化独立工作目录；该次进程已停止，生成的工作目录已清理。本轮未继续直接启动该程序，未修改客户端功能开关或关闭连接认证。

公开接口交叉核对

WecomTeam/wecom-cli 当前仓库提供的消息能力围绕机器人会话与身份，不能证明能以当前员工身份回复已有外部联系人；当前动态服务发现也不等于本机内置 SDK 已开放同一接口。

历史版本曾记录 msg send_message：其说明中的返回仅有 errcode/errmsg。即使这些旧命令仍可调用，也还需要核对身份、外部联系人作用域和可关联的消息结果，不能把旧文档中的“成功”直接当作本项目已验证的发送回执。因此没有按历史接口猜测参数向客户试发。

验证记录

相关回归 118 项通过，JavaScript 语法检查通过。包含：

• SDK 实际回环 socket 测试：握手、Unicode 请求、认证拒绝、断连、超时、错误/布尔 ID、非法 JSON、超大帧、并发串行化及不自动重发。
• SDK 诊断只请求帮助，不误报账号登录、发送和回执；导出不包含测试令牌。
• EXE 诊断入口不创建 QApplication/MainWindow，不启动监听。
• 同名客户、跨账号和相同 server_id 的上下文隔离，数据库异常传播。
• 通道配置与启动拦截、保存失败恢复、真实 Qt WebEngine 页面按钮及既有数据库/控制台回归。

SDK 回环测试使用隔离的模拟服务。这些测试验证代码行为，不能替代本机 SDK 实连或原账号真实发送验收。

python -m pytest test_wecom_sdk_client.py test_protocol_features.py test_database_reply_priority.py test_runtime_settings.py test_qt_console_bridge.py -q
node --check assets\ui\console-app.js
python wxwork_protocol_probe.py --deep --output protocol_client_diagnostics.json

当前实机诊断见 protocol_client_diagnostics.json。诊断退出码 0 仅表示分析完成，不能据此判断协议可发送；应读取 canSend、sdkRuntime.rpcVerified、sendVerified、receiptVerified。

本机调查中间证据位于 tmp/wecom-sdk-runtime-check.json、tmp/wecom-mcp-initialize-check.json、tmp/wecom-local-tls-check.json 及 tmp/native-mcp-server-evidence.json。代码备份位于 tmp/protocol-before 和 tmp/protocol-sdk-before。

EXE 产物与复现

程序：ZhenAI-WeCom-Assistant-v1.4.9.exe。这是目录版，移动或分发时保留整个 ZhenAI-WeCom-Assistant-v1.4.9 文件夹，不能单独复制 EXE。包内附有“协议功能说明.txt”。

• 主 EXE 大小：17,137,545 字节。
• SHA-256：ddd7717e9c16683155b98f29fb8274a27a8ee1d141772a94add30c5c6486ba5e。
• 构建使用 Python 3.11.9、PyInstaller 6.22.2；构建脚本退出码 0。
• 包内 Qt WebEngine、自带运行库、HTTPS/证书验证与既有归档/数据库/视觉发送保护自检通过；业务模拟检查不等于真实客户发送验收。
• 独立更新器已打入目录；未配置签名证书，构建按原脚本跳过签名。
• 已核对 wecom_sdk_client、wxwork_protocol_probe 被收集，归档目录仅包含四个指定源码文件。
• 新 EXE 在精简 PATH 中实际运行协议诊断，退出码 0；报告仍为 sdk_runtime_unavailable，发送与回执标志均为 false。

实际结果：protocol_build_validation.json、新 EXE 诊断报告、构建日志。

本机构建时原脚本引用的相邻归档源码目录不存在；已在 C:\kefu\2026-08-19-18-27-34 找到原有组件。新增的是构建专用路径覆盖，运行时仍检查包内文件。

$env:WECOM_BUILD_EXPORTER_DIR = 'C:\kefu\2026-08-19-18-27-34'
.\build_windows_exe.ps1 -PythonPath 'C:\Users\isard\AppData\Local\Programs\Python\Python311\python.exe'
# EXE 只读诊断：不启动监听，不发送消息
& .\dist\ZhenAI-WeCom-Assistant-v1.4.9\ZhenAI-WeCom-Assistant-v1.4.9.exe --protocol-diagnostics C:\wechat_rpa\tmp\packaged-protocol-report.json

尚未完成与下一步

1. 获得客户端正常启动的 SDK 环境并成功握手；继续验证 CLI schema/帮助与接口作用域。
2. 读取在线员工身份，建立与数据库 account、客户 conv_id 的明确映射，不能只按显示名称试发。
3. 在用户已授权的“小迷糊”或“高瑞”会话中执行一次指定文本测试，验证原账号、原会话。
4. 用返回值及后续消息证据确认发送事务；区分请求受理、确认发送、拒绝和结果不明。结果不明不能自动重发。
5. P0 通过后再实现协议调度、持久发送账本、AI/审核、人工接管和暂停恢复，完成协议自动回复闭环。

本轮交付属于 SDK 通信与协议诊断实现，不能标为原账号协议自动回复已完成。