wx-win-agent/docs/validation/M4-Management-History-2026-09-04.md

M4 联系人、群聊、子窗口与消息能力验证记录（2026-09-04）

范围

本次 M4 增加以下 C# 公共能力：

• 子窗口：枚举、按标题查找、双击会话打开、关闭。
• 联系人：切换通讯录、新朋友列表、接受/添加好友、好友列表与详情、修改备注、本人信息。
• 群聊：最近群聊、创建群、增删/邀请成员、成员列表、群名、群备注、群公告、群昵称、@所有人。
• 历史与消息动作：任意会话历史消息、转发、发送者资料、从消息添加/删除好友、下载、笔记附件保存、图片 OCR、语音转文字、消息右键菜单。
• 会话动作：删除、隐藏及通用右键菜单。

公开行为参考 wxautox4 官方 WeChat、Chat、Message 文档；C# API 不复制 Python 类型，统一使用强类型快照、WechatOperationResult 和 WxAgentException。

安全边界

• 所有发送、添加、接受、修改、删除、转发、下载/保存等有副作用操作均要求精确确认令牌 CONFIRM。
• 删除好友保留 clearChatHistory 显式参数；删除会话仍视为不可恢复操作。
• 真机检查只使用“文件传输助手”和只读页面，不操作真实联系人和群聊。
• CLI 的 m4-smoke 只输出数量、布尔状态、窗口类型和进程号，不输出联系人、群名、账号标识或消息正文。

Linux 验证

~/.dotnet/dotnet test tests/node-agent/WxAgent.Core.Tests -c Release --no-restore
Passed: 19, Failed: 0

~/.dotnet/dotnet build WxAgent.sln -c Release -p:EnableWindowsTargeting=true --no-restore
Build succeeded. 0 Warning(s), 0 Error(s)

~/.dotnet/dotnet publish node-agent/WxAgent.Host -c Release -r win-x64 --self-contained true \
  -p:EnableWindowsTargeting=true -p:PublishSingleFile=true -p:PublishTrimmed=false --no-restore
Publish succeeded.

新增 Core 测试覆盖：确认令牌严格匹配、缺失/错误令牌拒绝、成员名单输入校验、成功结果模型。

Windows 真机验证

主机：DESKTOP-EGI7QCK（微信登录用户会话，非 Session 0）

按发布要求执行：

WxAgent.Host doctor --timeout 30                       exit 0
WxAgent.Host inspect-ui --output artifacts-ui-tree.json --timeout 30  exit 0
WxAgent.Host smoke --output artifacts-smoke-ui.json --timeout 30      exit 0
WxAgent.Host m4-smoke --timeout 60                    exit 0

m4-smoke 结果：

{
  "subWindowOpened": true,
  "historyCount": 3,
  "contactCount": 14,
  "newFriendCount": 0,
  "recentGroupCount": 16,
  "accountDetected": true,
  "confirmationGuarded": true,
  "privacy": "names and account identifiers omitted"
}

验证后已关闭双击打开的“文件传输助手”子窗口，并切回微信聊天页；桌面仅保留微信主窗口。

本地脱敏证据位于 artifacts/m4-2026-09-04/：doctor、inspect、smoke、M4 smoke 的输出和退出码，以及脱敏 UI 树。

结论与限制

• M4 公共 API、取消/超时链路、明确错误码、命令串行化、确认保护、Linux 测试/构建/发布和 Windows 只读真机 smoke 均已完成。
• 涉及真实联系人或群聊的副作用路径未在现有个人账号执行；这是项目安全规则要求，不是缺失的默认行为。它们已通过编译和统一确认门禁检查，后续客户端版本回归应在专用测试账号/测试群中执行。
• 客户端菜单文字、权限、群人数限制和确认弹窗由当前微信版本决定；找不到节点时统一返回 ControlNotFound / UiStructureChanged，不进行盲目重试。