127 lines
7.0 KiB
Markdown
127 lines
7.0 KiB
Markdown
# 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<T>`、`Task` 和 `IAsyncEnumerable<T>`。
|
||
- 数据库能力只读：候选密钥必须通过目标数据库 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 项目必须设置 `<EnableWindowsTargeting>true</EnableWindowsTargeting>`。
|
||
- 暂不使用 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 树快照，再集中更新定位器并执行真机回归。
|