# AGENTS.md ## 项目目标 - 使用 C#/.NET 独立实现 wxautox4 商业版的业务功能，只兼容功能，不兼容其 Python API。 - 当前阶段实现 Desktop Agent、CLI 和业务层，不实现 Windows Service、正式 Web/UI、授权和自动升级。 - 仅通过 Windows UI Automation、Win32 和正常桌面交互实现；允许为本地数据库只读访问而读取 `Weixin.exe` 内存并进行 SQLCipher 解密；禁止协议破解、DLL 注入、进程内存修改、数据库写入、登录或风控绕过。 - Agent 安装并成功连接控制面即完成节点及数据同步授权，不再要求额外用户确认；连接授权仅覆盖已验证账号的规范化只读数据，仍禁止上传原始微信数据库、密钥和未脱敏内容。 - 开发前先阅读 `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`、`Task` 和 `IAsyncEnumerable`。 - 数据库能力只读：候选密钥必须通过目标数据库 page 1 HMAC 校验后才能保存或使用；日志和普通 CLI 输出不得包含完整密钥。 - 不提前引入微服务、插件系统、消息队列、Redis 或新的 UI 框架。 ## 项目边界 ```text node-agent/WxAgent.Core net8.0：模型、解析、去重、状态机和业务用例 node-agent/WxAgent.Windows net8.0-windows：FlaUI、UIA 和 Win32 node-agent/WxAgent.Host net8.0-windows：Desktop Agent 和 CLI node-agent/WxAgent.Tray net8.0-windows：托盘常驻与生命周期管理 node-agent/WxAgent.Service net8.0：节点本地服务兼容层 control-plane/ Go：远程中心控制面；测试与 Go 代码同目录 tests/node-agent/WxAgent.Core.Tests Linux 可执行的纯逻辑测试 tests/node-agent/WxAgent.Service.Tests 节点本地服务测试 ``` - 保持 Windows 专用代码与纯业务逻辑分离，使 Core 测试可在 Linux 执行。 - 不为单一实现建立无实际用途的通用框架；跨平台边界和真机测试所需的最小抽象除外。 ## Linux 开发与构建 - Linux 负责主要开发、代码检查、全部项目编译和 Core 测试。 - Windows UIA 代码可在 Linux 编译，但不能在 Linux 执行。 - Windows 项目必须设置 `true`。 - 暂不使用 NativeAOT；发布时关闭 trimming。 ```bash dotnet restore WxAgent.sln -p:EnableWindowsTargeting=true dotnet test tests/node-agent/WxAgent.Core.Tests -c Release dotnet build WxAgent.sln -c Release -p:EnableWindowsTargeting=true dotnet publish node-agent/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 豪" "吉祥三宝" "消息测试专用群组"这几个进行消息收发测试，其中“消息测试专用群组” 可测试 @所有人 功能；未经用户明确要求，不操作真实联系人和群聊。 上传示例： ```bash ssh rogee@10.1.1.101 'powershell -NoProfile -Command "New-Item -ItemType Directory -Force C:\Users\Rogee\wx-agent | Out-Null"' scp -r node-agent/WxAgent.Host/bin/Release/net8.0-windows10.0.19041.0/win-x64/publish/* \ rogee@10.1.1.101:'C:/Users/Rogee/wx-agent/' ``` 每次 Windows 发布至少执行： ```powershell WxAgent.Host doctor WxAgent.Host inspect-ui --output artifacts/ui-tree.json WxAgent.Host smoke ``` ## UI Automation 规则 - 同一个微信窗口的点击、输入、滚动及页面切换必须进入单一命令队列，禁止并发写操作。 - UIA 事件回调只采集必要信息并快速返回，不在回调线程执行耗时业务逻辑。 - 不长期持有 UIA 元素对象；控件可能因页面虚拟化随时失效。 - 消息监听采用“UIA 事件 + 低频轮询 + 可见快照比较 + 有界去重”。 - 读取和查找操作可以有限重试；发送消息、联系人变更、群成员变更和朋友圈操作不得盲目重试。 控件定位顺序固定为： ```text 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 树快照，再集中更新定位器并执行真机回归。