wx-win-agent/docs/WebUI-MCP-使用说明.md

Web UI + MCP 使用说明

当前版本已实施基础迁移：Token 不按 AccountIds 做账号级授权，调用方负责业务隔离；Agent 已校验可信 Host/Origin，并对浏览器写请求执行 CSRF/本机请求头检查。完整的普通用户交互和批次写操作仍按 普通用户重构指导 分阶段实施。

启动

1. 在已登录、未锁定的 Windows 用户会话中运行发布包中的 WxAgent-Setup.exe。安装器会创建桌面/开始菜单快捷方式和可选的登录启动项，不需要 PowerShell 或管理员权限。
2. 启动托盘程序后，首次运行会生成唯一的远程访问 Token，并自动打开“服务设置...”窗口。Token 在该窗口中明文展示，可复制或重新生成；不需要单独的凭据窗口，也不支持多 Token。
3. 如需无托盘运行，仍可复制 docs/webui-mcp-config.example.json 后使用：

WxAgent.Host.exe serve --config C:\Users\USERNAME\wx-agent\service.json

credentials.json 只保存 SHA-256 大写十六进制摘要，例如：

[{"PrincipalId":"local-read","TokenSha256":"<64-hex-sha256>","Permissions":["read"],"AccountIds":[]}]

AccountIds 仅为旧凭据格式保留，不再作为账号级数据授权边界；[] 可以保留。凭据文件应使用当前用户 ACL，禁止提交仓库。调用方仍必须显式携带 account fingerprint 选择数据和目标，Agent 会验证绑定、窗口和目标一致性。托盘模式的 service.json 会保存 AccessToken 明文，以便服务设置窗口随时展示；该文件同样只应保存在本机。

服务运行后通过托盘菜单中的“服务设置...”配置监听地址、端口、远程访问和唯一 Token，不需要手工编辑 service.json/credentials.json。队列容量、监听会话和监听事件开关属于内部实现/验收策略，不作为用户配置项。若需要保持微信 UI 会话不自动锁屏，在安装器的可选项中启用“防止自动锁屏”；该设置不阻止用户手动锁定。默认只监听 127.0.0.1:5088，本机访问控制台不需要 Token，会自动进入。外部监听必须启用远程访问并自行配置防火墙，服务不会自动开放端口；外部监听使用具体 IP，不能使用 0.0.0.0/::。服务校验可信 Host/Origin；远程浏览器写请求需要 Cookie、CSRF 和可信 Origin，本机浏览器写请求还需要 X-WxAgent-Local: 1。HTTP 不加密 Token、Cookie、消息或附件，不直接暴露公网。

远程浏览器访问 / 后输入 Token 登录。HTTP/MCP 客户端使用：

Authorization: Bearer <TOKEN>

MCP Streamable HTTP 地址为 /mcp。不要把 Token 放在 URL、MCP session ID、浏览器持久存储或日志中。事件流默认关闭，是否启用属于内部验收开关，不作为用户配置项；真机消息验证最多发送 3 条。

凭据更换与撤销

在托盘“服务设置...”中查看唯一 Token；点击“重新生成”后保存，旧 Token、Cookie、SSE/MCP 授权立即失效，不存在重叠窗口。服务在每个请求、任务执行和事件批次重新读取凭据。

多账号显式绑定

1. 在未锁定的交互式 Windows 会话中读取 GET /api/v1/accounts 和 GET /api/v1/ui-targets。
2. 用户选择一个数据库 accountId 和一个当前窗口 targetId（PID+HWND），调用 POST /api/v1/accounts/bind；服务会重新读取 UI 微信号/昵称，并与已验证 contact.db 身份匹配，重复、过期或不匹配均拒绝。
3. 绑定状态保存在服务数据目录的 account-bindings.json。微信进程/窗口消失、身份变化或重启后窗口句柄失效时，必须重新绑定；调用 POST /api/v1/accounts/unbind 可主动解除。
4. 会话、可见消息、联系人和任务筛选等操作必须显式携带要查看或操作的 accountId；它是调用方的数据/目标选择，不是 Token 授权边界。未绑定返回 AccountNotBound/AccountWindowUnavailable，不会猜测窗口。任务列表按当前 principal 返回，可用 accountId 做视图筛选。

只读边界

状态、账号、窗口目标、会话、摘要消息、联系人和任务查询通过 REST 或同一 MCP 工具访问；任务列表使用 GET /api/v1/operations 或 MCP operations_list，详情/取消仍按当前 principal 校验。正文需 content 权限。当前文本发送、@所有人、管理和朋友圈能力保持 disabled；不会把入队、UI 点击或数据库指纹描述成已发送。

回滚

停止新服务并等待正在执行的 UI 操作结束，保留 data/operations.sqlite 和脱敏诊断；恢复旧版本发布目录后再启动。旧版本不会自动重放新版本未完成任务。删除临时 artifacts 目录前确认没有活动任务占用。