wx-win-agent/AGENTS.md

AGENTS.md

项目目标

• 使用 C#/.NET 独立实现 wxautox4 商业版的业务功能，只兼容功能，不兼容其 Python API。
• 当前阶段实现 Desktop Agent、CLI 和业务层，不实现 Windows Service、正式 Web/UI、授权和自动升级。
• 仅通过 Windows UI Automation、Win32 和正常桌面交互实现；允许为本地数据库只读访问而读取 Weixin.exe 内存并进行 SQLCipher 解密；禁止协议破解、DLL 注入、进程内存修改、数据库写入、登录或风控绕过。
• 开发前先阅读 docs/WxAgent-CSharp-开发计划.md，功能范围、里程碑和参考对象以该文档为准。

技术约束

• 使用 .NET 8；Windows 项目目标为 net8.0-windows10.0.19041.0、win-x64。
• UI 自动化优先使用 FlaUI.UIA3；只有 FlaUI 明确缺失能力时才直接调用 UIA COM。
• Win32 API 优先通过 Microsoft.Windows.CsWin32 按需生成，不维护大批手写 P/Invoke。
• JSON 使用 System.Text.Json，日志使用 Microsoft.Extensions.Logging，并发使用 Channel<T>、Task 和 IAsyncEnumerable<T>。
• 数据库能力只读：候选密钥必须通过目标数据库 page 1 HMAC 校验后才能保存或使用；日志和普通 CLI 输出不得包含完整密钥。
• 不提前引入微服务、插件系统、消息队列、Redis 或新的 UI 框架。

项目边界

src/WxAgent.Core       net8.0：模型、解析、去重、状态机和业务用例
src/WxAgent.Windows    net8.0-windows：FlaUI、UIA 和 Win32
src/WxAgent.Host       net8.0-windows：Desktop Agent 和 CLI
tests/WxAgent.Core.Tests           Linux 可执行的纯逻辑测试
tests/WxAgent.Windows.Tests        Windows 真机测试，需要时再创建

• 保持 Windows 专用代码与纯业务逻辑分离，使 Core 测试可在 Linux 执行。
• 不为单一实现建立无实际用途的通用框架；跨平台边界和真机测试所需的最小抽象除外。

Linux 开发与构建

• Linux 负责主要开发、代码检查、全部项目编译和 Core 测试。
• Windows UIA 代码可在 Linux 编译，但不能在 Linux 执行。
• Windows 项目必须设置 <EnableWindowsTargeting>true</EnableWindowsTargeting>。
• 暂不使用 NativeAOT；发布时关闭 trimming。

dotnet restore WxAgent.sln -p:EnableWindowsTargeting=true
dotnet test tests/WxAgent.Core.Tests -c Release
dotnet build WxAgent.sln -c Release -p:EnableWindowsTargeting=true
dotnet publish src/WxAgent.Host -c Release -r win-x64 --self-contained true \
  -p:EnableWindowsTargeting=true -p:PublishSingleFile=true -p:PublishTrimmed=false

Windows 真机操作

连接信息

• Windows 主机：10.1.1.101
• 计算机名：DESKTOP-EGI7QCK
• 登录用户：rogee
• 用户目录：C:\Users\Rogee
• SSH：ssh rogee@10.1.1.101，当前 Linux 主机的 SSH 密钥可直接登录。
• PowerShell：ssh rogee@10.1.1.101 "powershell -NoProfile -Command '<命令>'"
• Windows MCP：http://10.1.1.101:8765/mcp，配置见 .mcp.json。
• 微信程序：C:\Program Files\Tencent\Weixin\Weixin.exe
• 当前 Windows 未发现全局 dotnet 命令，优先上传 Linux 生成的 self-contained 发布包；需要 Windows SDK 时可直接安装。
• 建议部署目录：C:\Users\Rogee\wx-agent。

不得删除或模糊以上真机连接信息；开发产物必须能够上传到该主机执行生产前真机验证。

• 优先使用 Windows MCP 操作和检查 Windows 主机。
• MCP 无法满足需求或明显不便时，改用 SSH/PowerShell 上传产物、执行命令和收集日志。
• 调试需要的应用、SDK、检查工具或依赖可以直接安装，无需事先确认。
• 微信自动化必须运行在微信所在的已登录、未锁定用户会话中，不能在 Session 0 中验证。
• 默认只使用“文件传输助手” "Hao 豪" "吉祥三宝" "消息测试专用群组"这几个进行消息收发测试，其中“消息测试专用群组” 可测试 @所有人 功能；未经用户明确要求，不操作真实联系人和群聊。

上传示例：

ssh rogee@10.1.1.101 'powershell -NoProfile -Command "New-Item -ItemType Directory -Force C:\Users\Rogee\wx-agent | Out-Null"'
scp -r src/WxAgent.Host/bin/Release/net8.0-windows10.0.19041.0/win-x64/publish/* \
  rogee@10.1.1.101:'C:/Users/Rogee/wx-agent/'

每次 Windows 发布至少执行：

WxAgent.Host doctor
WxAgent.Host inspect-ui --output artifacts/ui-tree.json
WxAgent.Host smoke

UI Automation 规则

• 同一个微信窗口的点击、输入、滚动及页面切换必须进入单一命令队列，禁止并发写操作。
• UIA 事件回调只采集必要信息并快速返回，不在回调线程执行耗时业务逻辑。
• 不长期持有 UIA 元素对象；控件可能因页面虚拟化随时失效。
• 消息监听采用“UIA 事件 + 低频轮询 + 可见快照比较 + 有界去重”。
• 读取和查找操作可以有限重试；发送消息、联系人变更、群成员变更和朋友圈操作不得盲目重试。

控件定位顺序固定为：

AutomationId
→ ControlType + Name
→ 稳定祖先节点 + 相对关系
→ UIA Pattern
→ 集中维护的坐标兜底

• 禁止在业务代码中散落绝对坐标。
• 定位器、消息识别规则和控件路径集中维护。
• 当前已知关键节点包括 MainView、session_list、chat_message_page、chat_message_list、chat_input_field 和 tool_bar_accessible；完整基线见开发计划。

测试与完成标准

• 非平凡解析、去重、状态机或分支逻辑必须留下一个最小可运行测试。
• UIA 节点应尽早转换为脱敏、可序列化的快照，使消息解析和定位规则能在 Linux 离线测试。
• 每项功能必须具备：公共调用方式、超时/取消行为、明确错误码、测试或真机检查、当前微信版本验收记录和失败诊断信息。
• 变更完成前先运行相关 dotnet test、dotnet build；涉及 Windows 自动化时还必须在真机执行对应 smoke。
• 日志默认不得记录完整消息内容、联系人名称、附件内容或未脱敏 UI 树。

功能实现原则

• 公开行为以 wxautox4 官方文档和 docs/WxAgent-CSharp-开发计划.md 中的功能复制矩阵为验收基线。
• 优先复用 FlaUI、CsWin32 和 .NET 标准库，不从零重写已有能力。
• 修复 UI 兼容问题时应修改共享定位器或解析规则，禁止只给单个调用路径打补丁。
• 微信版本变化时先运行 doctor/smoke、比较 UI 树快照，再集中更新定位器并执行真机回归。