feat: add tray settings and local console access
This commit is contained in:
+12
-13
@@ -2,8 +2,15 @@
|
||||
|
||||
## 启动
|
||||
|
||||
1. 在已登录、未锁定的 Windows 用户会话中准备目录和凭据文件；不要通过 HTTP 生成 Token。
|
||||
2. `credentials.json` 只保存 SHA-256 大写十六进制摘要，例如：
|
||||
1. 在已登录、未锁定的 Windows 用户会话中运行发布包中的 `WxAgent-Setup.exe`。安装器会创建桌面/开始菜单快捷方式和可选的登录启动项，不需要 PowerShell 或管理员权限。
|
||||
2. 启动托盘程序后，首次运行会生成远程访问 Token，并在一次性窗口中提供复制按钮。后续通过托盘菜单“访问凭据...”新建或撤销 Token，通过“服务设置...”配置监听和服务参数；不需要手工编辑配置文件。
|
||||
3. 如需无托盘运行，仍可复制 `docs/webui-mcp-config.example.json` 后使用：
|
||||
|
||||
```powershell
|
||||
WxAgent.Host.exe serve --config C:\Users\USERNAME\wx-agent\service.json
|
||||
```
|
||||
|
||||
`credentials.json` 只保存 SHA-256 大写十六进制摘要，例如：
|
||||
|
||||
```json
|
||||
[{"PrincipalId":"local-read","TokenSha256":"<64-hex-sha256>","Permissions":["read"],"AccountIds":[]}]
|
||||
@@ -11,17 +18,9 @@
|
||||
|
||||
`AccountIds: []` 不授予任何显式数据库账号范围；需要联系人/群成员等账号范围调用时，必须填入已验证的 account fingerprint。凭据文件应使用当前用户 ACL，禁止提交仓库。
|
||||
|
||||
3. 复制 `docs/webui-mcp-config.example.json`，修改本机路径后启动：
|
||||
服务运行后使用托盘菜单中的“服务设置...”配置监听地址、端口、远程访问、队列和监听事件；使用“访问凭据...”新建或撤销 Token，不需要手工编辑 `service.json`/`credentials.json`。若需要保持微信 UI 会话不自动锁屏，在安装器的可选项中启用“防止自动锁屏”；该设置不阻止用户手动锁定。默认只监听 `127.0.0.1:5088`，本机访问控制台不需要 Token，会自动进入。外部监听必须启用远程访问并自行配置防火墙，服务不会自动开放端口。Host/Origin（CORS）限制不再校验；HTTP 不加密 Token、Cookie、消息或附件，不直接暴露公网。
|
||||
|
||||
```powershell
|
||||
WxAgent.Host.exe serve --config C:\Users\USERNAME\wx-agent\service.json
|
||||
```
|
||||
|
||||
需要正常安装、登录后自动启动、创建桌面/开始菜单快捷方式并常驻托盘时，运行发布包中的 `WxAgent-Setup.exe`。安装器会创建当前用户的登录启动项，不需要 PowerShell 或管理员权限；首次启动托盘程序时生成本地管理 Token，并在一次性窗口中提供复制按钮。
|
||||
|
||||
服务运行后可在托盘菜单中打开控制台、打开 `service.json`、停止/启动服务或重新加载配置。若需要保持微信 UI 会话不自动锁屏，在安装器的可选项中启用“防止自动锁屏”；该设置不阻止用户手动锁定。默认只监听 `127.0.0.1:5088`。外部监听必须同时设置 `AllowExternal=true`、明确 IP/端口和精确 `AllowedHosts`/`AllowedOrigins`；自行配置防火墙，服务不会自动开放端口。HTTP 不加密 Token、Cookie、消息或附件，不直接暴露公网。
|
||||
|
||||
浏览器访问 `/`，输入 Token 登录。HTTP/MCP 客户端使用：
|
||||
远程浏览器访问 `/` 后输入 Token 登录。HTTP/MCP 客户端使用：
|
||||
|
||||
```text
|
||||
Authorization: Bearer <TOKEN>
|
||||
@@ -31,7 +30,7 @@ MCP Streamable HTTP 地址为 `/mcp`。不要把 Token 放在 URL、MCP session
|
||||
|
||||
## 凭据更换与撤销
|
||||
|
||||
原子替换凭据文件并保留相同 `PrincipalId` 可保留幂等记录；服务在每个请求、任务执行和事件批次重新读取凭据。旧 Token、Cookie、SSE/MCP 授权立即失效，不存在重叠窗口。变更后删除旧浏览器会话并重新登录。
|
||||
在托盘“访问凭据...”中创建新 Token 或撤销旧 Token。明文 Token 只在创建时显示一次；服务在每个请求、任务执行和事件批次重新读取凭据。旧 Token、Cookie、SSE/MCP 授权立即失效，不存在重叠窗口。变更后删除旧浏览器会话并重新登录。
|
||||
|
||||
## 多账号显式绑定
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@
|
||||
|
||||
## 运行边界
|
||||
|
||||
- 通过 `WxAgent.Host serve --config <file>` 启动；默认监听 `127.0.0.1`，外部 IP 必须显式 `allowExternal: true`。
|
||||
- HTTP API、Streamable HTTP MCP (`/mcp`) 和浏览器登录共用 Bearer Token；Token 只放 `Authorization`，不放 URL。
|
||||
- 浏览器登录后仅保留短期 HttpOnly SameSite Cookie，写请求需 CSRF；普通日志不记录正文、Token、Cookie、密钥或完整 UI 树。
|
||||
- 可通过 `WxAgent.Host serve --config <file>` 启动；安装版使用托盘程序，服务设置和 Token 管理均通过系统 UI 完成。默认监听 `127.0.0.1`，外部 IP 必须显式 `allowExternal: true`。
|
||||
- 本机回环访问 Web UI、HTTP API 和 Streamable HTTP MCP (`/mcp`) 不需要 Token；远程访问仍使用 Bearer Token，Token 只放 `Authorization`，不放 URL。
|
||||
- 远程浏览器登录后仅保留短期 HttpOnly SameSite Cookie，写请求需 CSRF；普通日志不记录正文、Token、Cookie、密钥或完整 UI 树。
|
||||
- 明文 HTTP 不提供传输保密性，只适合可信隔离网络；不应直接暴露公网。
|
||||
|
||||
@@ -164,10 +164,10 @@ Queued → Running → Succeeded / Failed / Cancelled / Unconfirmed
|
||||
|
||||
### 5.1 本机与外部入口鉴权
|
||||
|
||||
1. 默认绑定 `127.0.0.1`/`::1`；允许显式配置非回环 IP、`0.0.0.0`/`::`、端口和允许的访问域名。外部 HTTP 监听必须先配置有效 Token，否则启动失败；不自动开放防火墙。不要求 HTTPS，不开发证书管理及反向代理适配。
|
||||
2. HTTP API 与 MCP 共用高熵 Token、principalId、权限和撤销机制，同一 Token 可以调用两种协议。直接客户端使用 `Authorization: Bearer <TOKEN>`，不得将 Token 放入 URL、查询参数、日志或 MCP session ID。Token 首次生成/配置及授权在 Windows 主机本地完成，文件由当前用户 ACL 保护；不通过匿名网络接口生成或提权。
|
||||
3. 本机和外部 Web UI 统一输入 Token 登录，不实现配对码。只匿名提供无业务数据的登录页及静态资源；浏览器通过 POST 换取短期 `HttpOnly`、`SameSite=Strict` 会话 Cookie，随后清空输入，不把 Token 写入 localStorage/sessionStorage 或持久缓存。明文 HTTP 下 Cookie 不设置 Secure，因此不具备传输保密性。会话继承 Token 身份和权限；SSE 使用该 Cookie，写请求另校验 CSRF。API/MCP 无 Token 或有效派生会话时拒绝，错误/状态接口不得匿名泄露环境信息。
|
||||
4. Token 登录失败限流；校验配置的 Host 与精确 Origin 白名单，不设置通配 CORS。原生 MCP/HTTP 客户端可无 Origin，但仍须 Bearer 认证；有 Origin 则必须通过检查。本机专用入口仅接受直接回环连接，不信任客户端自报 Host、Origin 或 X-Forwarded-For 作为来源证明。
|
||||
1. 默认绑定 `127.0.0.1`/`::1`；通过托盘“服务设置...”配置非回环 IP、端口和远程访问，不自动开放防火墙。不要求 HTTPS，不开发证书管理及反向代理适配。
|
||||
2. HTTP API 与 MCP 共用高熵 Token、principalId、权限和撤销机制，同一 Token 可以调用两种协议。直接客户端使用 `Authorization: Bearer <TOKEN>`，不得将 Token 放入 URL、查询参数、日志或 MCP session ID。Token 的生成、撤销和服务设置均通过 Windows 托盘系统 UI 完成；凭据文件由当前用户 ACL 保护。
|
||||
3. 本机回环 Web UI/API/MCP 不需要 Token，服务仅信任操作系统提供的直接回环地址；远程 Web UI 仍输入 Token 登录。远程浏览器通过 POST 换取短期 `HttpOnly`、`SameSite=Strict` 会话 Cookie，随后清空输入，不把 Token 写入 localStorage/sessionStorage 或持久缓存。明文 HTTP 下 Cookie 不设置 Secure，因此不具备传输保密性。会话继承 Token 身份和权限；SSE 使用该 Cookie，写请求另校验 CSRF。
|
||||
4. Token 登录失败限流；不校验 Host/Origin，客户端可不提供 Origin。远程请求仍必须通过 Bearer 或有效派生会话；本机专用入口仅接受直接回环连接，不信任客户端自报 X-Forwarded-For 作为来源证明。
|
||||
5. 首版权限区分只读、内容读取、普通写、管理写和本机诊断管理；凭据默认只读。共享 Token 即共享身份，不能隔离共享者；需要隔离时配置不同身份的 Token。密钥扫描、保存等本机专用动作不能因外部 Token 有管理权限而开放。
|
||||
6. 更换或撤销 Token 立即使旧 Token、派生 Cookie 和 MCP 会话授权失效，关闭相关 SSE/事件流，不实现新旧 Token 重叠窗口；稳定身份和幂等记录保留。每次资源访问及每个事件输出批次检查授权；执行及实际提交副作用前重新检查。未执行任务失败且不执行；已提交任务保留真实/不确定结果，不承诺撤销微信动作。
|
||||
|
||||
@@ -229,7 +229,7 @@ Queued → Running → Succeeded / Failed / Cancelled / Unconfirmed
|
||||
1. 增加 serve 分支和最小 HTTP Host，CLI 行为保持兼容。
|
||||
2. 提取必要共享处理逻辑，使 REST、MCP 不复制参数校验和微信操作实现。
|
||||
3. 接入有界队列、现有门禁、超时取消和任务记录，核查库 API 未受门禁保护的路径。
|
||||
4. 实现默认回环及显式外部 HTTP 监听、HTTP/MCP 共用 Token、统一浏览器 Token 登录、权限、CSRF、Host/Origin 检查和脱敏日志。
|
||||
4. 实现默认回环及显式外部 HTTP 监听、HTTP/MCP 共用 Token、本机免 Token、远程 Token 登录、权限、CSRF 和脱敏日志。
|
||||
5. 先接 status、capabilities、operations 查询和取消。
|
||||
|
||||
验收：
|
||||
@@ -340,7 +340,7 @@ Queued → Running → Succeeded / Failed / Cancelled / Unconfirmed
|
||||
2. Linux restore/test/build/publish 后上传 Windows，同一已登录用户会话启动 serve。
|
||||
3. 执行 doctor/inspect-ui/smoke 及本期实际接入功能回归，记录 Windows/微信/浏览器/MCP 客户端版本。
|
||||
4. 验证关闭、崩溃重启、凭据撤销、端口冲突、锁屏、微信退出及版本不支持路径。
|
||||
5. 从另一主机验证外部 HTTP Web UI、HTTP API 和 MCP：同一 Token 可访问，缺失/错误/撤销 Token 被拒绝，本机专用入口不可访问；验证 Host/Origin、限流和防火墙部署要求，不以 localhost 自测代替。
|
||||
5. 从另一主机验证外部 HTTP Web UI、HTTP API 和 MCP：同一 Token 可访问，缺失/错误/撤销 Token 被拒绝，本机专用入口不可访问；验证限流和防火墙部署要求，不以 localhost 自测代替。
|
||||
6. 输出使用说明、HTTP/MCP 共用 Token 配置样例（只用占位值）、显式监听配置、明文风险提示、凭据更换、回滚步骤及本轮验收报告。
|
||||
|
||||
验收：
|
||||
|
||||
@@ -27,8 +27,8 @@
|
||||
|
||||
## 安全/失败路径
|
||||
|
||||
- 无 Bearer Token：401。
|
||||
- 非 allowlist Host/Origin：403。
|
||||
- 回环本机无 Bearer Token：允许直接访问；远程无 Bearer Token：401。
|
||||
- Host/Origin 不再作为认证条件；远程仍必须通过 Bearer Token，URL 查询中的 token 仍拒绝。
|
||||
- URL 查询中出现 token 参数：400，拒绝凭据泄漏路径。
|
||||
- 旧 Token 轮换后：旧 Bearer 与浏览器 Cookie 均 401；身份与幂等记录保留。
|
||||
- 写能力：保持 disabled；当前服务不模拟成功、不执行微信写入。
|
||||
|
||||
@@ -1,8 +1,6 @@
|
||||
{
|
||||
"ListenUrl": "http://127.0.0.1:5088",
|
||||
"AllowExternal": false,
|
||||
"AllowedHosts": ["127.0.0.1:5088", "localhost:5088", "[::1]:5088"],
|
||||
"AllowedOrigins": ["http://127.0.0.1:5088", "http://localhost:5088", "http://[::1]:5088"],
|
||||
"CredentialFile": "C:/Users/USERNAME/wx-agent/credentials.json",
|
||||
"DataDirectory": "C:/Users/USERNAME/wx-agent/data",
|
||||
"QueueCapacity": 100,
|
||||
|
||||
Reference in New Issue
Block a user