24 KiB
企业微信原账号协议自动回复功能规划
日期：2026-09-14
状态：检测、SDK 通信层、通道配置与 ID 上下文读取已实现；本机 SDK 运行时未连通，真实协议发送尚未验证
代码基线：项目 APP_VERSION 为 1.4.9；本机企业微信 5.0.10.6023（x86），发送桥接尚未验证。
本轮已实现范围、客户端证据与剩余工作见 本机协议分析与实现状态。下文保留完整目标，不能视为全部已实现。
1. 产品目标与首版范围
用户已明确：继续使用现在的员工账号，回复已经添加的客户，消息出现在原客户会话中。新增“协议模式”，与现有视觉模式共享 AI、审核、队列和档案能力。
首版采用“数据库增量读取 + 已登录客户端收发能力桥接”。界面称为“协议模式”，旁注“需要企业微信客户端在线”。桥接可能依赖客户端内部接口或 Hook，具体实现和支持版本由 P0 验证确定；本规划没有认定任何私有发送入口已经可用。
| 范围 | 首版决定 |
|---|---|
| 平台 | Windows，本机企业微信已登录 |
| 账号 | 每个运行实例只托管一个明确选定的在线员工账号 |
| 会话 | 已有客户的一对一会话，按账号与会话 ID 选择托管范围 |
| 内容 | 文本接收与文本回复；其他内容进入人工处理 |
| 回复方式 | 自动发送、审核后发送 |
| 接收来源 | 真实本地消息数据库；客户端消息事件安排在后续版本 |
| 发送方式 | 客户端桥接；现有视觉通道可单独选择 |
| AI 与业务 | 复用当前模型、知识、工具、内容审核和业务处理规则 |
| 后续扩展 | 图片/文件、客户端事件、多账号并发、满足条件的自动切换 |
| 不属于首版 | 群聊、批量营销、添加客户、脱离客户端的独立登录与完整网络协议 |
官方应用消息、微信客服和客户群发不能直接代替本需求中的原员工即时单聊。完整网络私有协议另行评估；数据库解密、写入本地消息表均不能证明消息已发送。
2. 现有基础与改造点
| 现有组件 | 已核对的能力 | 规划改造 |
|---|---|---|
| wxwork_db.py、reply_database.py | 增量读取；返回 account、conv_id、server_id、rowid；上下文仍按名称匹配 | 增加按准确账号/会话 ID 查询、持久化游标与数据库重建处理；保留视觉名称查询路径 |
| engine_b.py | 数据库/档案检测后入队；依赖昵称指纹且存在同名过滤 | 协议路径直接保留真实身份；数据库不可用时不得退化成依赖视觉回写的档案监听 |
| wechat_bot.py | 入队、合并、AI、审核、视觉发送和结果核对 | 抽取业务调度与发送接口，视觉检查留在视觉发送器内部 |
| gui_runtime.py | BotThread 启动时连接窗口，再运行 A/B 引擎 | 增加独立协议运行路径，启动、消费队列和恢复均不要求截图、激活或切换聊天窗口 |
| send_lock.py | 本机跨进程窗口发送互斥 | 保留视觉资源锁，新增覆盖两个通道的统一回复事务占用 |
| conversation_store.py、queue_log.py | 档案、有限历史范围内的 exchange_id 排重、队列事件 | 复用展示格式；新增持久发送账本作为长期排重依据 |
| wechat_gui_qt.py、assets/ui/console-app.js、assets/ui/zhenyang-ai-console.html | 控制台、队列、审核、消息库、设置和日志 | 扩展现有页面，通过真实 Qt 数据和动作接口驱动 |
3. 功能清单
P0 为可行性验证；P1 为首个可用版本的必备功能；P2 为后续扩展。
| 编号 | 功能 | 行为 | 阶段 |
|---|---|---|---|
| F01 | 运行通道选择 | 视觉/协议互斥，与自动发送/审核后发送分别配置 | P1 |
| F02 | 账号与客户端检测 | 展示企业、员工、在线状态、客户端版本及适配结果 | P0/P1 |
| F03 | 桥接连接管理 | 检测、重连、停止；恢复后重新核对账号和会话映射 | P0/P1 |
| F04 | 托管会话管理 | 从真实会话选择客户，支持同名客户和逐会话暂停 | P1 |
| F05 | 新消息监听 | 按账号、数据库代次持久化游标；消息落盘后才确认消费 | P1 |
| F06 | 连续消息合并 | 复用当前等待时间；补充消息更新版本，淘汰过期回复 | P1 |
| F07 | AI 回复生成 | 复用模型、知识、工具、审核；失败可见，取消后丢弃未发送结果 | P1 |
| F08 | 协议文本发送 | 固定原账号和原会话；长度按验证能力校验，不静默截断或拆成多条 | P0/P1 |
| F09 | 审核后发送 | 草稿保存在软件内，可查看、编辑、批准和转人工 | P1 |
| F10 | 人工接管 | 持久化会话托管权；识别人工已发消息，停止后续自动发送 | P1 |
| F11 | 发送结果核对 | 区分提交、受理、确认和结果不明；按可关联证据确认发送 | P0/P1 |
| F12 | 暂停与恢复 | 停止新处理和新发送，已提交请求继续只读核对；恢复前核对身份 | P1 |
| F13 | 失败与重试 | 仅明确未提交/未送出的可重试错误允许重试，结果不明禁止重发 | P1 |
| F14 | 任务、档案和日志 | 展示来源、通道、身份、耗时、错误与核对证据，可导出脱敏诊断 | P1 |
| F15 | 版本兼容 | 未适配版本不可用；升级、账号变化后重新检测 | P0/P1 |
| F16 | 模式切换 | 保存事务，交接未提交任务，保留原通道未决请求的核对责任 | P1 |
| F17 | 客户端事件监听 | 事件接收与数据库补漏共用消息账本 | P2 |
| F18 | 图片与文件 | 按消息类型验证上传、接收和发送结果，逐项开放 | P2 |
| F19 | 多账号与自动切换 | 账号独立调度；满足未发送证据与身份映射条件才自动更换通道 | P2 |
4. 页面和交互
4.1 自动化设置
新增“运行通道”区域，保留现有“发送方式”区域。
| 设置 | 首版行为 |
|---|---|
| 运行通道 | 视觉模式 / 协议模式；已有用户升级后保持视觉模式 |
| 发送方式 | 沿用 send_mode=auto/review，切换通道不改变审核方式 |
| 托管账号 | 显示真实在线身份，不按员工姓名或历史数据目录自动选择 |
| 托管会话 | 搜索并选择已有客户，可排除或暂停；默认空范围，不接管全部历史客户 |
| 接收来源 | 协议首版固定“数据库增量读取”，不可用时明确暂停 |
| 合并和发送前等待 | 复用现有配置及限制，显示实际运行值 |
| 通道检测 | 只检测连接、身份、数据库和发送能力，不向客户发送测试消息 |
| 测试发送 | 单独入口；选择测试会话、查看发送身份和完整文本后点击发送 |
适配未完成时显示“当前版本尚未支持”及原因，不能仅保存协议开关后继续执行视觉发送。窗口、DPI、鼠标空闲、输入框草稿等参数只在视觉模式下生效。
通道或账号切换执行 F16，不改变正在提交请求的目标或出口。普通参数在下一个处理批次生效。首版不展示尚未实现的“协议优先自动回退”。
4.2 自动化控制台
- 顶部同时展示运行通道、在线员工、发送方式与监听状态。
- 协议模式把“企业微信窗口状态”替换为账号在线、客户端版本、桥接连接、数据库状态、最近收消息时间与待核对数量。
- 执行链路显示“接收 → 合并 → AI → 审核/待发送 → 提交 → 核对”，不显示虚假的截图或回填步骤。
- “已确认发送”只统计确认后的消息；已受理、待核对、明确失败分别展示。确认发送不等于客户已读。
- 断开、版本不兼容、需要人工等状态发生变化时通知；重复轮询不重复刷屏。
4.3 任务队列与审核
列表增加来源、通道、员工和会话；技术 ID 放在详情中。
| 操作 | 行为 |
|---|---|
| 批准发送 | 批准当前所见草稿版本，发送前复核新消息、托管权和原账号；失效则重新生成/审核 |
| 编辑回复 | 保存新草稿版本，使旧批准失效；编辑后可点击批准发送 |
| 立即重试 | 只对明确可重试任务开放；已提交、已受理、结果不明禁止重试 |
| 取消任务 | 撤销未提交回复；已经提交则停止后续动作并保留核对，不声称消息已撤回 |
| 转人工 | 暂停会话自动发送，保留上下文并继续收录后续新消息 |
| 恢复自动 | 用户主动恢复，读取最新上下文，从最新待处理客户轮次继续 |
| 查看核对详情 | 展示请求 ID、提交时间、可用的消息 ID 与结果证据 |
协议审核草稿保存在软件内；现有视觉输入框草稿行为保持兼容，说明随通道变化。切换自动发送不能放行被业务规则强制审核的草稿。
4.4 消息库、档案与日志
- 消息库增加“托管此会话/暂停此会话”，使用真实账号与会话 ID。
- 昵称变化不新建客户，同名客户不合并档案。
- 客户消息正常归档；AI 草稿、受理中回复和确认发送分别标记，只有确认后才计为已发送。
- 已确认但归档失败只补归档，不重发。
- 日志按账号、会话、通道、任务和错误筛选。诊断导出默认不含密钥、登录凭证和完整聊天正文，复用已有脱敏能力。
5. 主流程与人工协作
- 用户选择协议模式、在线账号和托管客户，启动监听。
- 验证客户端适配、数据库、实际在线身份与 ID 映射；不可用时显示具体原因。
- 接收新消息，在同一事务内写入消息账本及游标，再创建或更新会话任务。
- 等待配置的合并窗口，按 ID 读取上下文；我方消息、系统消息、非托管会话不触发回复。
- 调用现有 AI，记录生成所依据的消息版本；图片、文件或内容缺失进入人工处理，不根据占位文本猜测内容。
- 按审核方式和业务规则展示草稿或进入待发送。
- 最终复核任务、托管权、账号、消息版本、通道和限频。
- 占用统一发送事务，先落盘请求与状态，再向原会话提交。
- 收集返回和后续证据，进入确认、失败或待核对，更新档案与界面。
- 新客户轮次独立记录；已有未决发送的会话暂缓新发送，其他会话继续处理。
首次启用以当前消息位置建立基线，历史只作上下文，不自动回复所有历史。重启按已确认消费游标恢复；过期且未发送的积压任务交人工检查，已提交的请求始终保留核对记录。
人工接管为持久会话状态。我方消息先与自动发送账本匹配；无法匹配的按人工行为处理，避免自身回写触发循环。匹配不能只比较文本。
首版不能承诺感知其他设备上的“正在输入”。操作人员接手前可点击“转人工”；检测到人工已发送消息则取消未提交草稿。若人工发送与协议提交同时发生，记录竞争并停止后续自动发送，不承诺已提交请求可撤销。
6. 发送状态与异常处理
| 状态 | 含义 | 可执行动作 |
|---|---|---|
| queued / collecting / generating | 等待、合并、生成 | 取消、转人工，后续消息可更新版本 |
| review | 等待审核 | 编辑、批准、取消、转人工 |
| ready | 已通过业务检查，尚未提交 | 提交前复核，可取消或更换通道 |
| submitted | 已持久化发送意图，调用可能已进入客户端 | 查询或等待，不直接重发 |
| accepted | 客户端受理，最终发送未确认 | 等待证据，不算客户收到 |
| uncertain | 超时、中断或证据不足 | 只读核对，冻结本会话后续发送，不阻塞其他会话 |
| confirmed | 达到 P0 定义的发送确认标准 | 幂等归档，不表示客户已读 |
| retry_wait | 明确未发出的可恢复失败 | 退避重试或立即重试 |
| failed / manual / cancelled / expired | 失败、人工、取消或未发送任务过期 | 记录原因，按具体情况人工处理 |
确认标准由 P0 实测：优先使用可关联请求的服务端结果，或具有明确发送成功语义的客户端状态。数据库出现我方消息、方法返回 true、同样文本出现，均不能单独证明成功；接收端实测用于检验这些证据是否可靠。
只有明确未进入发送入口且不会晚到执行的失败，才能判为未提交。IPC 断开、超时、租约过期都不能自行推断未发送。若桥接不支持可证明的幂等，保留不确定状态，不承诺端到端严格一次投递。
| 异常 | 处理 |
|---|---|
| 未登录、登录失效、客户端验证 | 暂停该账号发送，提示处理客户端，恢复后重验身份 |
| 数据库断开或解析失败 | 暂停生成和新发送，保留游标，恢复后补齐 |
| 桥接或客户端退出 | 停止提交，有限退避重连，未决请求继续保留 |
| 客户端升级不兼容 | 协议不可用，用户可选择视觉通道并执行事务交接 |
| AI 超时 | 保留消息版本，按现有重试和人工规则处理 |
| 目标映射缺失或冲突 | 转人工，不按昵称猜目标 |
| 明确拒绝发送 | 分类重试、暂停账号或转人工，不统一无限重试 |
| 长时间无法核对 | 显示待人工核对，可关闭此轮并保留不明账本，不提供自动重发 |
| 停止、取消或切换通道 | 未提交任务停止，已提交请求继续核对 |
7. 技术接口与数据
7.1 分层
flowchart TD
A[数据库增量读取] --> C[消息账本与回复调度]
B[客户端事件：后续扩展] --> C
C --> D[上下文、AI、审核、人工接管]
D --> E[统一发送事务]
E --> F[协议发送器]
E --> G[视觉发送器]
F --> H[本机桥接与已登录客户端]
H --> I[结果核对]
G --> I
I --> J[账本、档案与控制台]
以下为拟新增模块，不代表已有实现。现有 model_protocol.py 属于模型功能，不复用它承载企业微信通信。
| 拟新增模块 | 职责 |
|---|---|
| reply_types.py | 账号/会话/消息身份、草稿版本、发送请求与结果 |
| reply_service.py | 无窗口依赖的合并、上下文、AI、审核、取消 |
| reply_runtime_store.py | 消息、游标、任务、发送账本、托管权与身份别名 |
| reply_dispatcher.py | 通道选择、事务占用、版本核对、失败分类和结果核对 |
| reply_transports.py | 统一发送接口和视觉兼容适配 |
| wxwork_protocol_client.py | 本机桥接通信、能力检测、账号绑定、结果查询 |
| wxwork_protocol_runtime.py | 协议启动、停止、重连、健康状态 |
| wxwork_protocol_bridge/ | 客户端版本相关的原生桥接，语言与交付物由 P0 确定 |
桥接最小接口：health、capabilities、get_account、resolve_conversation、send_text、query_send_result。查询不足明确返回“不支持/未知”，不能伪造确认；消息订阅为 P2。
本机通信首选限制当前用户访问的 Windows 命名管道，请求携带协议版本、请求 ID 与运行会话标识。登录态留在客户端；服务重启不重放发送请求。独立服务便于恢复，但若需要在客户端内执行代码，仍需在 P0 验证客户端崩溃风险。
7.2 统一身份和请求
| 数据 | 必须信息 |
|---|---|
| AccountIdentity | 验证后的账号键、企业范围（可用时）、员工 ID、进程与登录会话代次 |
| ConversationIdentity | 账号键、真实会话 ID、会话类型、显示名；数据库/桥接 ID 显式映射 |
| IncomingMessage | 账号、会话、来源、消息 ID、发送者、方向、时间、类型和内容 |
| ReplyTask | task_id、会话键、客户消息集合/水位、生成版本、草稿版本、审核、托管状态、通道 |
| SendAttempt | attempt_id、task_id、账号/会话、通道、内容摘要、幂等键、提交时间、状态与证据 |
数据目录名不直接视为在线身份。跨企业相同员工 ID、同名客户和切换账号必须区分；先暂停旧账号任务，再切换账号。
优先以账号范围内服务端消息 ID 去重；缺失时使用来源数据库代次、会话和本地行 ID。数据库重建后 rowid 重用不能与旧消息混淆。视觉来源无法对应稳定消息 ID 时只补充已映射任务；映射不唯一的会话禁止两个通道同时消费。
批准记录绑定 task_id、input_revision、draft_revision、content_hash。模型、审核期间或提交前消息变化，使旧回复和旧批准失效。请求重查保持 attempt_id，不能超时后换一个 ID 重新提交。
7.3 持久化、兼容与回退
拟在 application_data_dir() 下新增 reply_runtime.sqlite，事务维护消息、游标、任务、发送尝试、会话托管权和身份映射；不存客户端凭证。索引和保留周期按数据量确定，首版不自动清除未决发送账本。
- 消息与游标同事务提交；读取/入库失败不确认消费。改造读取器 checkpoint/ack，避免内存游标先前进后丢消息。
- 发送尝试先落盘再触发客户端；重启后 submitted/accepted/uncertain 先核对。
- 每会话只允许一个待提交或未决回复；不同会话独立收消息和生成，首版同账号发送按序执行并沿用限频。
- 协议与视觉共用发送账本；视觉窗口另有资源锁。占用过期只触发恢复检查，不赋予重新发送资格。
- pending_replies.json 一次性迁移后作为兼容展示快照，不再与 SQLite 双向独立写任务；Qt、经典界面及离线任务操作都改用统一存储接口。
- 迁移在监听停止时进行，保留原文件、未知字段和迁移标识；无法准确映射的任务留在视觉/人工路径，不按昵称强行合并。
- 档案通过身份别名兼容；旧档案对应多个真实会话时不自动复制或混入任一客户上下文。
- 首版回退指新版内切回视觉。降级旧 EXE 前需处理未决请求并生成无歧义快照，不能让旧 EXE 用过期 JSON 恢复发送。
7.4 配置
| 字段 | 首版行为 |
|---|---|
| reply_transport | visual / protocol，默认 visual |
| send_mode | 沿用 auto / review |
| protocol_account_key | 默认空，要求实际身份绑定 |
| protocol_managed_conversations | 托管会话集合，默认空 |
| protocol_receive_source | 固定 database |
| protocol_auto_fallback | 首版固定 false，界面不开放 |
| 合并、等待、限频 | 复用当前配置，新增参数单独校验 |
配置覆盖 Qt 默认值/加载/保存、经典界面和 BotThread 传参；账号或来源未就绪时不能静默沿用其他账号/通道。
8. 分阶段开发顺序
| 阶段 | 工作项 | 交付和完成条件 |
|---|---|---|
| P0 能力验证 | 实际版本/架构、在线身份、ID 映射、文本发送、确认依据、断线重登 | 可复现实验报告、支持矩阵、最小桥接原型；原账号原会话实测成立，结果可判别 |
| P1-A 基础服务 | 数据类型、统一存储、ID 上下文、确认游标、身份/历史迁移、发送事务 | 共用消息与发送账本；故障模拟无重复消费/发送，视觉回归通过 |
| P1-B 收发闭环 | 桥接发送器、协议运行时、合并与 AI、核对、暂停恢复、人工接管 | 单账号文本闭环真实通过，不要求窗口激活、截图或键鼠输入 |
| P1-C 产品入口 | 通道设置、真实状态、托管客户、审核编辑、队列动作、日志、打包 | 界面可配置、审核、接管、定位失败和切回视觉；源码与 EXE 行为一致 |
| P1-D 稳定验证 | 故障注入、重启、竞争场景、连续运行、安装升级 | 必测验收通过，发布说明明确支持版本与运行条件 |
| P2 扩展 | 客户端事件、媒体、多账号、受约束自动切换 | 按能力单独验证，不作为首版前提 |
P0 建议以 2—3 个工作日作为探索预算，不是成功承诺。无法取得可靠发送或确认能力时，交付验证结论与缺口，协议功能保持不可用。P1 工期在 P0 后根据桥接复杂度、确认能力和兼容范围估算。
9. 验收矩阵
以下验收尚未执行。模拟适配器用于故障测试，不能替代真实企业微信发送验证。
| 编号 | 场景 | 通过标准 | 功能 |
|---|---|---|---|
| A01 | 原员工回复现有测试客户 | 接收端收到，身份、原会话正确，记录版本与证据 | F02/F08/F11 |
| A02 | 遮挡、最小化、鼠标操作其他软件 | 支持环境中不调用截图、激活、剪贴板、键鼠；锁屏独立验证后才列为支持 | F01/F08 |
| A03 | 同名客户、昵称改变 | 上下文、草稿、发送、档案对应正确会话 | F04/F05/F08 |
| A04 | 同秒多条、迟到入库、跨页、数据库重建 | 无漏读，崩溃后按确认游标恢复，无旧消息误判 | F05 |
| A05 | 重启、重复检测、相同内容多次发送 | 同消息 ID 只处理一次，不同 ID 不因文本相同被丢弃 | F05/F11 |
| A06 | 首次启用、旧队列迁移 | 不回复全部历史，未决任务不降级为可重试，同名历史不串档 | F04/F05/F16 |
| A07 | 合并、生成、审核时客户补充消息 | 更新轮次，过期草稿与批准失效，旧回复不提交 | F06/F09 |
| A08 | 编辑后批准、重复点击批准 | 发送最新获批版本，不产生第二次发送 | F09/F11 |
| A09 | 人工接管、手机回复、机器人自身回写 | 停止后续自动发送，自身回写不触发循环 | F10 |
| A10 | 提交后超时、桥接崩溃/重启 | 不重发，保留不明状态，其他会话继续 | F11/F12/F13 |
| A11 | 返回成功但接收端未收到 | 不把受理计为确认，显示核对/失败 | F11/F14 |
| A12 | 已发送但归档失败、历史裁剪 | 只补归档，长期账本继续阻止重发 | F11/F14 |
| A13 | 发送中暂停、取消、转人工、切换通道 | 不声称已提交请求撤销，后续发送停止，无跨通道重复提交 | F10/F12/F16 |
| A14 | 断网、掉线、换账号、重新登录 | 错误可见，重验身份，旧账号任务不发到新账号 | F02/F03/F12 |
| A15 | 升级、未适配版本 | 协议不可用，可明确选择视觉并完成事务交接 | F15/F16 |
| A16 | 图片/文件、超限文本、映射缺失 | 明确交人工，不按占位内容回答 | F07/F08/F13 |
| A17 | 桥接/读取卡住、连续 UI 操作 | UI 可操作，超时可见，无重复监听进程与占用泄漏 | F03/F12/F14 |
| A18 | EXE 安装、重启、升级、切回视觉 | 数据持久保存，通道和审核方式保持，迁移可核查 | F01/F15/F16 |
稳定性目标：单账号、至少 10 个独立测试会话、200 个受控消息轮次和连续 24 小时运行，包含断线、进程重启及人工竞争。错账号、错会话、可归因于系统的重复发送为零；每轮有可追踪结果。分别记录检测、合并等待、AI、提交和确认耗时，实测后制定性能指标，不把配置等待算作性能故障。
实施时按改动选取已有回归：test_dual_engine.py、test_database_reply_priority.py、test_self_reply_loop.py、test_send_lock.py、test_runtime_settings.py、test_qt_console_bridge.py，以及相关队列、档案和打包测试。新增测试聚焦身份冲突、提交边界崩溃、游标提交、恢复及跨通道竞争。
10. 实施清单与下一步
- P0：验证实际客户端、桥接收发及真实确认依据。
- P1-A：统一身份、消息账本、游标、发送事务和迁移。
- P1-B：实现数据库接收、AI、协议文本发送、核对和人工接管。
- P1-C：接入设置、控制台、队列、审核、档案、诊断、打包。
- P1-D：完成验收矩阵、稳定运行、升级与视觉回归。
- P2：逐项扩展事件、媒体、多账号和自动切换。
下一项工作为 P0。本文和任务索引不代表协议发送功能已经完成。
11. 已核对的官方能力参考
这些链接用于界定官方接口范围，不是私有桥接接口规范，内容已在本次方案讨论中核对。