feat: add remote control plane and whitelist reads

docs/validation/Agent-Install-2026-09-11.md

@@ -0,0 +1,46 @@
+# Agent 安装与真机验证（2026-09-11）
+
+## 安装
+
+- Windows 主机：`10.1.1.101`，已登录用户会话 `Session 1`。
+- 发布方式：Linux 上执行 .NET 8 `win-x64` self-contained single-file publish，复制到 `C:\Users\Rogee\wx-agent`。
+- 已部署并校验 SHA-256：`WxAgent.Host.exe`、`WxAgent.Tray.exe` 与本地发布产物一致。
+- 已注册 `WxAgent-Tray` 交互式登录启动任务；当前进程运行在 Session 1，服务监听 `127.0.0.1:5088`。
+
+## 验证结果
+
+| 命令 | 结果 | 证据 |
+| --- | --- | --- |
+| `WxAgent.Host.exe doctor` | 通过 | 5 个 Weixin 进程可读、1 个数据根目录、6/6 关键控件、无错误 |
+| `WxAgent.Host.exe inspect-ui --output ...` | 通过 | 157 个脱敏节点 |
+| `WxAgent.Host.exe smoke --output ...` | 通过 | 向“文件传输助手”发送唯一标记并确认，Fingerprint 已生成 |
+
+远端证据保存在 `C:\Users\Rogee\wx-agent\artifacts\install-*.json`；普通输出未记录完整消息内容。
+
+## 诊断记录
+
+首次执行时 Session 1 为断开状态，`doctor` 返回 `SessionLocked`、`InputDesktopAvailable=false`，因此 smoke 未执行发送。执行 `tscon 1 /dest:console` 恢复为活动 console 后重试，`doctor`、`inspect-ui`、`smoke` 均返回 0。
+
+## 本机 Docker 控制面连接验证
+
+- 启动本机镜像 `wxagent-control-plane:local`，映射 `127.0.0.1:18090 -> 8090`；`/healthz` 返回 `ok/v1`，首页返回 455 字节。
+- 通过 SSH 反向端口转发将 Windows 节点的 `127.0.0.1:18090` 接入本机容器；节点 `windows-e2e-20260911` 成功注册。
+- 连续两次查询的 `last_heartbeat_at` 从 `2026-09-11T14:36:46Z` 更新到 `2026-09-11T14:37:02Z`，证明节点持续心跳连接；状态为 `Degraded` 仅因本次连接验证未配置活动账号，不是传输失败。
+- 验证结束后已恢复节点原始 `service.json`，停止临时容器和 SSH 隧道；`WxAgent-Tray` 保持本机登录启动配置。
+
+## 内网直连复测
+
+- 控制面容器改为绑定 `10.1.1.104:18090 -> 8090`，Windows 主机直连健康检查返回 `ok/v1`。
+- Agent 使用 `http://10.1.1.104:18090`，并通过 `--allow-insecure-http` 显式启用私有网段 HTTP；节点 `windows-direct-20260911` 成功注册。
+- 连续心跳从 `2026-09-11T14:55:13Z` 更新到 `2026-09-11T14:55:28Z`；`wechat_running=true`、`wechat_logged_in=true`、`session_locked=false`。
+- 已移除临时脚本；当前 Docker 容器使用 `unless-stopped` 运行，Agent 保持直连配置。
+
+## 内网直连远程发送复测（2026-09-12）
+
+- 微信登录状态曾因安全策略失效，重新扫码登录后继续；未操作真实联系人。
+- 当前 WeChat 4.1.13.63 不再暴露旧的头像资料窗口。Agent 改为通过稳定的 `MainView.main_tabbar.tabbar_setting` 打开 `PreferenceWindow`，读取“账号”区的昵称和微信号，完成绑定实时身份校验。
+- 清理旧窗口绑定后，账户重新绑定到当前 UI target；控制面节点 `windows-direct-20260911` 状态为 `Online`，`wechat_running=true`、`wechat_logged_in=true`、`session_locked=false`、账户 `verified=true`。
+- 控制面 `send-text` 任务 `9d_vZnrEBd9h3w42flhOpw` 经 `Pending → Running → Succeeded`；目标为 `session_item_文件传输助手`，Agent 本地消息历史读回同一唯一标记，确认消息已实际写入。
+- Agent 本地只读 API 复核：群列表 115 条，包含 `消息测试专用群组`（`53271859539@chatroom`）；私聊联系人全量分页 10,584 条；当前可见会话 11 条；文件传输助手历史 3 条，包含本次标记。
+- Docker 控制面现已补充远程只读任务：`POST /v1/reads/sessions`、`POST /v1/reads/contacts`、`POST /v1/reads/messages`；结果通过 `GET /v1/tasks/{task_id}` 获取，并由节点在读取前执行严格白名单校验。历史仍是当前微信 UI 可见消息，不是数据库全量历史。
+- 真机远程读取复测通过：会话 1 条（文件传输助手），私聊白名单 1 条（`filehelper`），群白名单 1 条（`53271859539@chatroom`），文件传输助手历史 3 条且包含此前发送标记；四个读取任务均为 `Succeeded`。