diff --git a/docs/Mcp_Go_Minimal_Design.md b/docs/Mcp_Go_Minimal_Design.md new file mode 100644 index 0000000..e8ba811 --- /dev/null +++ b/docs/Mcp_Go_Minimal_Design.md @@ -0,0 +1,799 @@ +# Go 服务端 MCP 最小工具集设计 + +> 版本:v1.0(定稿) 状态:**已自审(22 项问题全部修入正文),可施工** 日期:2026-11-12 +> +> 前置文档:`Mcp_Tool_Optimization_Plan.md`(MFC 侧工具优化,已全部落地)、 +> `Mcp_FileTransfer_Design.md`(V2 文件传输协议与无头接收端)、 +> `Mcp_Design.md`(MCP 协议/错误码基线)、`FILE_TRANSFER_V2.md`(V2 协议清单)。 +> +> 适用范围:`server/go` 新增 MCP 端点与 9 个工具。**不改客户端**——所有用到的 +> 命令与令牌均为 `common/commands.h` 既有定义,客户端已实现。 +> +> 本文与 MFC 侧的差异只有一个来源:**Go 服务端的协议实现面比 MFC 窄**。MFC 有 54 个 +> 工具,是因为它把 20 多条客户端命令都接进了服务端;Go 目前只接了 4 条。所以这里的 +> "最小"不是"先做简单的",而是"按 Go 已具备的协议能力面裁剪,剩下的按需补齐"。 + +--- + +## 0. 结论摘要 + +1. **v1 交付 9 个工具**,全部命名、参数、错误码与 MFC 对齐,同一句提示词在两个后端都能跑通: + `list_hosts` / `get_host_detail` / `get_server_status` / `get_audit_log` / + `get_screenshot` / `terminal_exec` / `terminal_close` / `list_files` / `read_file`。 +2. **四条设备通道,三种是既有基础设施**:终端(`hub` 已有,只需加哨兵与输出缓冲)、 + 主连接 RPC(`hub.SendToDevice`)、文件管理器子连接(`TOKEN_CONN_AUTH` 已把 clientID + 钉在 ctx 上,按 clientID 路由即可,**不需要** MFC 那套 pending + CancelIO)。 + 只有 V2 流式子连接的接收端是全新的。 +3. **`get_screenshot` 走主连接 RPC(`COMMAND_SCREEN_PREVIEW_REQ`),不碰屏幕流。** + 屏幕流是持续推的 H.264(首帧裸 BGRA),取一帧就得建屏幕子连接、占住每设备唯一的 + 屏幕槽位、用完再拆——代价远大于收益。预览 RPC 是主连接上的一次性请求响应, + 客户端自己抓屏编码回 JPEG(Linux 客户端回 BGRX,服务端编码)。不占任何槽位。 +4. **终端槽位是 Go 独有的硬约束**:`hub.go:86` 写明 *at most one web terminal per device*。 + v1 不做抢占——浏览器开着终端时 MCP 返回 `-32003`,空闲 3 分钟自动释放。 + 这是安全默认,代价是"人在用终端时 AI 用不了",写进工具描述让模型自己换路。 +5. **MCP 端点零新增端口**:挂在现有 Web 服务的 `/mcp`(`web/server.go:126` 的 mux 里加一行), + 无状态 JSON-RPC,不引入 `Mcp-Session-Id`。鉴权用单一静态令牌(`YAMA_MCP_TOKEN`), + 映射到固定 principal `mcp`(role=admin)。 +6. **明确不做**:`remote_*`、`chat_*`、`host_*`、进程/服务/注册表/窗口枚举、文件写操作、 + `exec_command`(白名单一次性执行,被 `terminal_exec` 覆盖)、`outputSchema`。 + +--- + +## 1. 范围 + +### 1.1 做 + +| 层 | 内容 | +|---|---| +| 端点 | `POST /mcp`(JSON-RPC 2.0 / MCP 2025-06-18),`initialize` / `notifications/initialized` / `ping` / `tools/list` / `tools/call` | +| 鉴权 | `Authorization: Bearer $YAMA_MCP_TOKEN`,常量时间比较 | +| 工具 | 9 个(见 §3) | +| 审计 | 每次调用一条 `mcp.tool.call` 记录,进既有审计通道 | +| 设施 | 每设备单请求互斥、终端会话表、主连接 RPC 请求表、V2 接收端 | + +### 1.2 不做 + +| 不做 | 理由 | +|---|---| +| `remote_open` / `remote_keyboard` / `remote_mouse` 等 | Go 有屏幕流但没有"注入结果回执",做出来无法验证;且属高风险写操作,先不开放给模型 | +| `chat_*` | Go 无 `COMMAND_CHAT` 实现 | +| `host_inspect` / `host_control_*` / 进程/服务/注册表/窗口枚举 | Go 协议层完全没有这些命令(`protocol/commands.go` 只声明了 4 条命令族) | +| 文件写(`delete_path` / `move_path` / `upload_file` / `create_folder`) | V2 上传方向需要服务端作 sender,工作量与本期的接收端不对称;先只读 | +| `download_file` | 接收端与 `read_file` 完全共用,v1.1 加约 20 行即可(差别只是落盘后不删)。v1 先只做"读",避免多一个往主控磁盘写文件的入口 | +| `exec_command`(白名单一次性执行) | `terminal_exec` 已覆盖同一场景且无白名单摩擦(MFC 实测 `-32007` 全是白名单误拒) | +| `outputSchema` | MFC 实测 outputSchema 占 `tools/list` 的 49,320 / 136,692 字节。9 个工具没必要背这个体积 | +| 多用户令牌 / 按分组授权 | v1 单 principal;多用户留到 Go 侧真正多租户部署时(见 §12 R6) | + +--- + +## 2. 基线 + +### 2.1 MFC 侧已交付(可直接对标的参照) + +`mcp/tools.json` 当前 `toolCount=54`(优化前 63),默认配置下可见 21 个。 +`Mcp_Tool_Optimization_Plan.md` 的八项已全部落地,其中三项对 Go 有直接约束力: + +| MFC 改动 | 对 Go 的约束 | +|---|---| +| `terminal_exec` 的 `session_id` 可变可选、无会话时隐式创建 | Go 不设 `terminal_open`,`terminal_exec` 隐式建会话 | +| 超时保留会话、返回部分输出、`session_id` 轮询续取 | Go 同款语义,见 §6.6 | +| `read_file` 复用 `download_file` 的 V2 接收端 | Go 的 `read_file` = 下载到临时目录 + 读 + 删,两者共用一份接收端 | + +### 2.2 Go 侧现状 + +`protocol/commands.go:105-140` 声明的命令常量里,真正有发送点的只有三处: + +| 能力 | 状态 | 位置 | +|---|---|---| +| 屏幕查看 / 控制 / 剪贴板 | 已实现(H.264 流 + 鼠标键盘) | `cmd/main.go` `handleScreenFrame` | +| PTY 终端(每设备单会话) | 已实现,**仅浏览器流式转发** | `hub.go:756` / `hub.go:983` / `cmd/main.go:101-109` | +| 卸载被控端 | 已实现 | `web/ws_handlers.go:1139` | +| 设备 / 用户 / 分组 / 审计 | 已实现 | `hub.ListDevices` / `devicehistory.Offline` / `web/audit_query.go` | +| 子连接鉴权(clientID 绑定) | 已实现 | `cmd/main.go` `handleConnAuth` | +| 文件管理器(列盘/列目录/读/写) | **完全没有** | — | +| 一次性命令执行 | **完全没有** | — | +| 屏幕预览 RPC | **完全没有** | — | + +### 2.3 两条可直接复用的结论 + +1. **终端是"跑命令"的唯一入口**。MFC 实测 186 次调用里 109 次是 `terminal_exec` + (58.6%),且 59% 的命令本质是"读"。Go 没有必要先做一堆专用只读工具, + 把 `terminal_exec` 做扎实就是最高性价比。 +2. **但 `read_file` 不能省**。MFC 的优化结论是"`read_file` 是唯一真正的功能缺口"—— + 终端读文件会被 PTY 回显、ANSI 转义、ConPTY 重绘污染,`.env` 这类文件读出来是脏的。 + Go 既然要上文件管理器,就一次做对。 + +--- + +## 3. 工具集 + +### 3.1 清单 + +| # | 工具 | 通道 | 只读 | 依赖能力位 | +|---:|---|---|:--:|---| +| 1 | `list_hosts` | 本机 | ✅ | — | +| 2 | `get_host_detail` | 本机 | ✅ | — | +| 3 | `get_server_status` | 本机 | ✅ | — | +| 4 | `get_audit_log` | 本机 | ✅ | — | +| 5 | `get_screenshot` | 主连接 RPC | ✅ | `CLIENT_CAP_SCREEN_PREVIEW` | +| 6 | `terminal_exec` | 终端子连接 | ❌ | — | +| 7 | `terminal_close` | 终端子连接 | ❌ | — | +| 8 | `list_files` | 文件管理器子连接 | ✅ | — | +| 9 | `read_file` | V2 流式子连接 | ✅ | —(见 §5.4 的说明) | + +`YAMA_MCP_READONLY=1` 时只暴露 1/2/3/4/5/8/9 七个(6/7 隐藏)。 + +### 3.2 逐个定义 + +#### `list_hosts` + +```jsonc +// input +{ "group": "asm", "name": "ASM-", "online_only": true, "limit": 50, "offset": 0 } +// output.structuredContent +{ "total": 7, "returned": 7, "hosts": [ /* hub.DeviceInfo */ ] } +``` + +`hub.DeviceInfo` 已含 `id/name/group/version/capability/os/rtt/activeWindow/ip/peer_ip/screen/connected_at/online/last_seen`, +直接序列化,**不裁剪字段**——模型排障需要的正是这些。`online_only=false` 时合并 +`devicehistory.Store.Offline(online)` 的历史条目。 + +`group` 与 `name` 都是子串匹配(与 MFC `list_hosts` 一致),`name` 大小写不敏感。 + +#### `get_host_detail` + +```jsonc +{ "id": "7888521104752806905" } +``` +返回 `DeviceInfo` + `capabilities: { utf8, screen_preview, screen_region, window_info }`(由 +`protocol.SupportsCap` 逐位解出)。**这是 MFC 优化里被验证过的高价值字段**: +模型不用靠 `-32005` 试错就知道这台机器能不能截图。 + +注意**不要把 `v2` 放进 capabilities**:`CLIENT_CAP_V2` 在 `DefaultCaps()` 里全平台恒真 +(`common/commands.h:1289`),列出来只会误导模型。 + +#### `get_server_status` + +```jsonc +{} // 无参 +``` +返回 `{ version, commit, uptime_s, devices_online, devices_offline_known, mcp: { readonly, tools } }`。 +`version`/`commit` 取 `-ldflags -X` 注入的构建变量——**Go 侧目前没有这两个变量** +(`cmd/main.go` 里查不到版本常量),需要新增两行 `var version, commit string` 并在 +`Makefile` 里注入;拿不到时返回空串,不要伪造。 + +#### `get_audit_log` + +```jsonc +{ "keyword": "terminal", "type": "mcp", "since": "2026-11-12T00:00:00Z", "limit": 100, "offset": 0 } +``` +复用 `web/audit_query.go` 的查询器,返回 `{ total, returned, records[] }`。 + +#### `get_screenshot` + +```jsonc +{ "id": "...", "max_width": 1600 } +// output: content[] 里一项 image(mimeType=image/jpeg, base64 data) +// structuredContent: { width, height, bytes, format, source: "preview" } +``` +细节见 §7。 + +#### `terminal_exec` + +```jsonc +// 执行 +{ "id": "...", "command": "sc query AssemblyManager", "timeout_ms": 20000, "session_id": "..." } +// 轮询(不带 command) +{ "id": "...", "session_id": "s-3f2a", "timeout_ms": 20000 } +// output +{ "session_id": "s-3f2a", "output": "...", "exit_code": 0, "done": true, + "offset": 1843, "truncated": false, "is_pty": true, "reused": false } +``` +超时未完成时 `done=false`、无 `exit_code`、`output` 是已产生的部分输出,**会话保留**。 + +#### `terminal_close` + +```jsonc +{ "session_id": "s-3f2a" } // 幂等:会话不存在也返回成功 +``` + +#### `list_files` + +```jsonc +{ "id": "...", "path": "C:\\ProgramData\\AssemblyManager", "limit": 200 } +// output +{ "path": "...", "total": 42, "returned": 42, "entries": [ + { "name": "settings.ini", "isDir": false, "size": 1204, "mtime": 1699999999 } ] } +``` +`path` 为空或 `"drives"` 时返回盘符列表 `{ drives: [{ drive, typeName, fileSystem, totalMB, freeMB }] }`。 + +#### `read_file` + +```jsonc +{ "id": "...", "path": "C:\\ProgramData\\AssemblyManager\\.env", + "offset": 0, "limit": 262144, "encoding": "auto" } +// output +{ "path": "...", "size": 4096, "bytes_read": 4096, "truncated": false, + "encoding": "utf-8", "text": "IR_ENDPOINT=...", "sha256": "..." } +``` +`encoding`:`auto`(默认,先 UTF-8 严格解码,失败回退 GBK)/ `utf-8` / `gbk` / `latin1`。 +`offset` 支持负数表示"从尾部倒数 N 字节"(MFC 同款,读日志尾部最常用)。 + +**上限 2 MiB**(`YAMA_MCP_READ_MAX`):V2 下载没有区间参数,只能整文件拉,超过就拒绝。 +`offset`/`limit` 是下载后的窗口裁剪,绕不过这个门。 + +--- + +## 4. 端点 + +### 4.1 `POST /mcp` + +在 `web/server.go:126` 起的 mux 里加一行: + +```go +mux.HandleFunc("/mcp", s.mcp.Handle) +``` + +**不能复用 `s.requireBearer`**:它校验的是浏览器会话令牌(`s.auth.ValidateToken`), +MCP 用的是独立的静态令牌,两套凭据语义不同。鉴权在 `mcp.Handle` 内部自己做 +(§4.2)。`basePath` 由 `s.mount` 统一处理,`/mcp` 不需要自己感知前缀。 + +协议形态: + +| 项 | 取值 | +|---|---| +| 协议版本 | `2025-06-18`(与 MFC `tools.json` 的 `protocolVersion` 一致) | +| 会话 | **无状态**。不生成、不校验 `Mcp-Session-Id` | +| `POST` 响应 | `Content-Type: application/json`,单条 JSON-RPC 响应 | +| `GET /mcp` | `405 Method Not Allowed`(v1 无服务端主动推送流;MCP 规范允许此返回) | +| `DELETE /mcp` | `405` | +| 批量请求 | 不支持(数组入参返回 `-32600`) | +| 通知(无 `id`) | 一律 `204 No Content`,不返回体 | + +无状态的代价是**没有 `notifications/progress` / `notifications/cancelled`**。 +取消靠 HTTP 请求断开——`r.Context()` 被取消时,处理函数释放设备锁、终端会话按 +§6.6 处理(不销毁)。这与 MFC 的 `-32800 请求被取消` 语义对齐。 + +### 4.2 令牌 + +``` +YAMA_MCP_TOKEN=<32 位十六进制> # 必填;未设置 = MCP 端点不注册(/mcp 返回 404) +YAMA_MCP_READONLY=1 # 可选,只读模式(隐藏 terminal_exec / terminal_close) +YAMA_MCP_TERM_IDLE=180 # 可选,终端会话空闲回收秒数 +YAMA_MCP_MAX_CONCURRENCY=16 # 可选,全局并发上限 +YAMA_MCP_READ_MAX=2097152 # 可选,read_file 文件大小门(字节,默认 2 MiB) +``` + +- 未设置时**不注册路由**,并在启动日志打一行 `MCP endpoint disabled: YAMA_MCP_TOKEN not set`。 + 不自动生成——生成的令牌若只落在日志里,等于没有密钥管理。 +- 比较用 `subtle.ConstantTimeCompare`,长度不等直接失败(不 leak 长度)。 +- principal 固定为 `{actor: "mcp", role: "admin"}`。审计记录里 `actor=mcp`, + `source=mcp`,与浏览器会话(`actor=`)可区分。 +- 不做失败计数封禁:令牌是 32 位十六进制(128 bit),且端点不对外暴露时无爆破面。 + 若将来暴露到公网,按 `web/ws_handlers.go` 的登录节流同款加计数(记入 §12 R6)。 + +### 4.3 错误码 + +与 MFC 完全对齐(`McpServer.cpp:296-312` 的官方说明),Go 侧只实现用得到的: + +| 码 | 语义 | Go 侧触发点 | +|---:|---|---| +| `-32001` | 超时 | 等子连接/等响应超时;`done=false` 不算此码 | +| `-32002` | 主机离线或不存在 | `hub.IsOnline` 为假 | +| `-32003` | 主机忙 | 设备锁被占 / 终端槽位被浏览器持有 | +| `-32004` | 命令未送达 | `hub.SendToDevice` 返回错误 | +| `-32005` | 主机不支持该能力 | 缺 `CLIENT_CAP_SCREEN_PREVIEW`(截屏);非 PTY 客户端用 `terminal_exec` | +| `-32006` | 策略拒绝 | 只读模式下调用写工具 | +| `-32009` | 目标不存在 | `list_files` 的 `TOKEN_FILE_LIST_ERROR` 且 win32err∈{2,3} | +| `-32010` | 权限不足 | `TOKEN_FILE_LIST_ERROR` 且 win32err=5 | +| `-32602` | 参数错误 | schema 校验失败 | +| `-32601` | 方法不存在 | 未知 method / 未知工具名 | +| `-32000` | 内部错误 | 其余 | + +### 4.4 审计 + +每次 `tools/call` 产出一条记录,字段沿用 `web/audit.go` 的形状: + +``` +event=mcp.tool.call actor=mcp role=admin source=mcp +tool= device= ok= code= ms= +args=<截断到 512 字节的摘要> result= +``` + +`args` 里的敏感值(`command` 全文可能含密码)**不入审计**——只记命令首词与长度, +与 MFC 的做法一致(MFC 审计只记 `host `)。完整命令进 `debug` 级日志。 + +--- + +## 5. 四条设备通道 + +``` +MCP client ──HTTP POST /mcp──▶ mcp.Server + ├─ 本机:hub.ListDevices / devicehistory / audit_query + ├─ 主连接 RPC SendToDevice(247) ─────────▶ 设备主连接 + ├─ 终端 OpenTerminalSession ───────▶ 终端子连接 + ├─ 文件管理器 COMMAND_LIST_DRIVE(1) ─────▶ 文件管理器子连接 + └─ V2 CMD_DOWN_FILES_V2(94) ─────▶ V2 流式子连接 +``` + +### 5.1 主连接 RPC(`get_screenshot`) + +请求走 `hub.SendToDevice(deviceID, pkt)`,响应在 `cmd/main.go` 的 `OnReceive` +里按 `data[0] == TOKEN_SCREEN_PREVIEW_RSP` 分派。**不走子连接,不占任何槽位。** + +需要一个请求表: + +```go +type pendingRPC struct { + reqID uint16 + ch chan []byte // 缓冲 1,迟到的响应写不进去就丢弃 +} +m := map[uint64]*pendingRPC{} // key = deviceID(每设备同时只允许一个,与设备锁一致) +``` + +`reqID` 用 `atomic.Uint32` 自增后取低 16 位;**必须校验响应里的 `reqId` 与在途请求一致**, +否则丢弃——MFC 的 `TakePreviewResponse(devId, reqId, ...)` 就是干这个的 +(`2015RemoteDlg.cpp:7520`),原因是主连接上可能同时有别的预览在飞。 + +### 5.2 终端子连接(`terminal_exec` / `terminal_close`) + +完全复用 `hub` 现有设施,**不改 hub**: + +| 动作 | 调用 | +|---|---| +| 开会话 | `hub.OpenTerminalSession(deviceID)`;已存在返回 `ErrTerminalBusy` | +| 等就绪 | 订阅 `EventHandler.OnTerminalReady(deviceID, isPTY)` | +| 发输入 | `hub.SendToTerminal(deviceID, bytes)`;行尾按 §6.4 区分 `\n` / `\r\n` | +| 收输出 | 订阅 `EventHandler.OnTerminalData(deviceID, packet)`,剥掉 4 字节 `TRM1` 前缀 | +| 关会话 | `hub.CloseTerminalSession(deviceID)` | + +`mcp.Server` 在启动时 `hub.Subscribe(self)` 一次,作为常驻订阅者; +只有"当前有 MCP 终端会话的设备"才把数据写进环形缓冲,其余直接丢弃(零开销)。 + +### 5.3 文件管理器子连接(`list_files`) + +时序: + +``` +MCP ──▶ 主连接: COMMAND_LIST_DRIVE(1) [1 字节] +客户端 ──▶ 新子连接(EnableSubConnAuth) + └─ TOKEN_CONN_AUTH(246) ──▶ Go: 校验 + 把 clientID 钉在 ctx 上 + 回 ack + └─ TOKEN_DRIVE_LIST(103) ──▶ Go: 解析盘符(子连接保持打开) +MCP ──▶ 同一子连接: COMMAND_LIST_FILES(2) [cmd][path\0] + └─ TOKEN_FILE_LIST(104) ──▶ Go: 解析目录项 + 或 TOKEN_FILE_LIST_ERROR(171) ──▶ Go: 按 win32err 翻译 + └─ Go: 关子连接(COMMAND_BYE → 500ms → Close) +``` + +注意 `TOKEN_DRIVE_LIST` 到达后**不能立刻关子连接**——列目录还要在同一个子连接上发 +`COMMAND_LIST_FILES`。MFC 的注释写得很明确:*此时不关子链接,交给 TOKEN_FILE_LIST +分支收尾*(`2015RemoteDlg.cpp:7647`)。 + +关键点: + +- **子连接带 ConnAuth**(`client/KernelManager.cpp:1773` 对 `COMMAND_LIST_DRIVE` + 调了 `EnableSubConnAuth()`),所以 `handleConnAuth` 已把 `ClientID` 钉在 ctx 上, + Go **不需要** MFC 那套 `IsPending(devId)` 守卫。按 `ctx.GetInfo().ClientID` 路由即可。 +- 子连接由客户端创建、**由服务端关闭**(MFC 注释:*此时不关子链接,交给 + TOKEN_FILE_LIST 分支收尾*)。关闭用 `hub` 同款优雅关闭:发 `COMMAND_BYE(204)`, + 500 ms 后 `ctx.Close()`。 +- `TOKEN_DRIVE_LIST` 与 `TOKEN_FILE_LIST` 的记录格式见附录 A,直接照 MFC 的 + `ParseDriveList` / `ParseFileList`(`McpServer.cpp:506/548`)移植。 +- 文件名是**客户端 ANSI**,用 `protocol.DecodeClientString(data, hub.Capability(id), "")` 解码。 + +### 5.4 V2 流式子连接(`read_file`) + +时序: + +``` +MCP ──▶ 主连接: COMMAND_LIST_DRIVE(1) + └─ 文件管理器子连接建立(同 §5.3) +MCP ──▶ 文件管理器子连接: CMD_DOWN_FILES_V2(94) [cmd][targetDir\0][path\0][\0] + └─ 服务端关掉文件管理器子连接 +客户端 ──▶ 新子连接(EnableSubConnAuth) + └─ COMMAND_SEND_FILE_V2(85) × N ──▶ Go: 校验路径 → 落盘 + └─ COMMAND_FILE_COMPLETE_V2(91) ──▶ Go: 校验 SHA-256 → 完成 +MCP: 读临时文件 → 返回 → 删临时目录 +``` + +- `targetDir` 是**主控本机**的保存目录,由服务端指定;客户端把它拼进每个 chunk 的 + `filename` 回填。所以服务端必须用一个**每次请求新建的临时目录** + (`os.MkdirTemp("", "yama-mcp-read-*")`),并在 `defer` 里 `RemoveAll`。 +- **路径校验是硬性安全要求**:`filename` 由客户端提供,必须校验它落在 `targetDir` 之内 + (**用 `filepath.Rel` 判越界,不能用字符串前缀比较**,见 §8.3),否则拒收并中止传输。 + 没有这一步,被控端可以把任意文件写到主控磁盘任意位置。 +- **没有可用的能力门**。`CLIENT_CAP_V2` 在 `common/commands.h:1289` 的 + `DefaultCaps()` 里被**所有平台无条件声明**,拿它做门等于没门。MFC 侧的 V2 是 + **服务端开关**(`2015RemoteDlg.cpp:2822` 的 `EnableFileV2`,默认关),不是客户端能力。 + Go 侧不设这个开关,恒用 V2。 +- 真正的失败模式是**老客户端不认识 94 号命令**:它收到 `CMD_DOWN_FILES_V2` 后 + 不建子连接、不回任何包,表现为 `-32001` 超时。工具描述里要写明这条, + 避免模型反复重试。 + +--- + +## 6. 终端会话 + +### 6.1 会话对象 + +```go +type termSession struct { + id string // "s-" + 6 位 hex + deviceID string + isPTY bool + createdAt time.Time + lastUsed time.Time + + mu sync.Mutex + buf []byte // 环形,cap 256 KiB + base uint64 // buf[0] 的绝对偏移 + total uint64 // 累计写入字节 + delivered uint64 // 已交付给客户端的绝对偏移 + + pending *pendingCmd // 在途命令;nil = 空闲 +} + +type pendingCmd struct { + sentinel string + deadline time.Time + done bool + exitCode int + raw []byte // 从 sentinel 之前回切出的原始片段 +} +``` + +### 6.2 租约与争用 + +- `hub.OpenTerminalSession` 本身就是互斥(`ErrTerminalBusy`),MCP 直接复用它。 +- 撞上 `ErrTerminalBusy` → `-32003`,message 写 + `terminal busy: another viewer (web console or another MCP call) holds it; retry later`。 +- **v1 不做抢占**。理由:抢占会把正在敲命令的人踢下线,而模型无法判断"人是不是在忙"。 + 需要抢占时由运维在 Web 控制台关掉那个终端。 +- 空闲释放:`lastUsed` 超过 `YAMA_MCP_TERM_IDLE`(默认 180 s)由后台 ticker 调 + `CloseTerminalSession`。这是防止模型忘了 `terminal_close` 把人的终端锁死。 + +### 6.3 环形缓冲与游标 + +- 容量 256 KiB,超出丢弃最旧数据,`base` 前移,丢弃量记 `droppedBytes` 并在 + 返回体里体现(`truncated=true`)。 +- 绝对偏移 `total` 单调递增,`offset` 参数与返回里的 `offset` 都用绝对偏移。 +- 缓冲随会话存在:会话关闭(`terminal_close` / 空闲回收 / 设备掉线)时整体释放。 + +### 6.4 哨兵与退出码 + +沿用 MFC 的两种形态(`McpServer.cpp:3991-3998`),**必须分两行下发**: + +| 客户端 | 下发 | 哨兵 | +|---|---|---| +| POSIX PTY(Linux/Android) | `cmd\n` + `echo "__MCP_DONE___$?"\n` | `__MCP_DONE___` | +| ConPTY(新 Windows) | `cmd\r\n` + `echo __MCP_DONE___%errorlevel%\r\n` | 同上 | + +为什么要分两行:`rem` / `cmd` / `exit` / `if` / `for` 这类"吞行"命令会把同一行后面的 +内容一起吞掉(MFC 的 P1 教训)。分两行后哨兵独立执行,退出码才可信。 + +`` 用 6 位随机 hex,每次命令重新生成——避免上一条命令的输出里残留同名哨兵被误命中。 + +### 6.5 输出清洗 + +三段清洗,顺序不能变(MFC `McpServer.cpp:3946-4040`): + +1. **剥回显**:PTY 会把输入整行回显。删掉命令行本身与哨兵行。 +2. **剥 ANSI**:`\x1b[...m`、`\x1b[?25h/l` 等 CSI/OSC 序列。 +3. **剥哨兵**:把哨兵文本及其后的退出码切掉,`exit_code` 单独解析。 + +ConPTY 是"屏幕渲染流"而不是字节流,光标重绘会让同一行出现两次,剥完 VT 后 +文字会重复(MFC 实测 `rem hello` 只剩哨兵、`cmd /c echo abc` 变成 +`abc__MCP_DONE_x__0`)。**这三段必须整体移植,不能自己重写**——这是踩过坑的代码。 + +### 6.6 轮询模式 + +`terminal_exec` 不带 `command`、只带 `session_id` 时进入轮询:从 `delivered` 开始 +取增量,等到 `done` 或超时。 + +- 超时**不销毁会话**(MFC 优化的核心结论):命令可能还在跑,销毁等于毁掉现场 + (cwd、环境变量、后台任务)。MFC 在优化前两次 `-32002` 都是这么来的。 +- HTTP 请求被客户端断开(`r.Context()` done)时同样只标记放弃,不动会话。 +- 会话内已有在途命令时,再带 `command` 调用 → `-32003`(同一会话单命令)。 + +### 6.7 平台范围 + +**v1 只支持 PTY 客户端**(ConPTY / POSIX PTY)。老的非 PTY cmd-pipe 路径 +(`TOKEN_SHELL_START(128)`)在 `OnTerminalReady` 里能识别(`isPTY=false`), +此时 `terminal_exec` 直接返回 `-32005` 并在 message 里说明"该客户端版本不支持"。 + +理由:非 PTY 路径的回显跳过依赖"按写入长度跳过",且单行哨兵会被吞行命令吃掉, +Go 侧没有实测数据支撑,先不开放比做错好。 + +若客户端根本不支持 shell(`COMMAND_SHELL` 发出后迟迟没有子连接), +`OpenTerminalSession` 会一直停在 pending,表现为 `-32001` 超时。这里**不设能力门**—— +`CLIENT_CAP_TERMINAL` 只有新版 Android 声明,Windows/Linux 一直支持却不声明 +(`common/commands.h:151` 的注释),拿它做门会误拒所有桌面客户端。message 里加一句 +"若反复超时,可能该客户端版本不支持远程 shell"。 + +--- + +## 7. `get_screenshot` + +### 7.1 为什么不用屏幕流 + +屏幕流是 H.264:`TOKEN_FIRSTSCREEN(116)` 是裸 BGRA 首帧,之后全是 +`TOKEN_NEXTSCREEN(117)` / `TOKEN_KEYFRAME(134)` 的编码帧。**不采用首帧方案**,原因不是 +解码(首帧本来就是裸的),而是**代价**:拿首帧必须先发 `COMMAND_SCREEN_SPY` 建立屏幕 +子连接、等客户端绑定、等首帧到达,用完还要拆——它占着每设备唯一的屏幕会话槽位, +和正在看画面的人直接冲突,而且拆不干净就会一直推流。 + +`COMMAND_SCREEN_PREVIEW_REQ(247)` 是**主连接 RPC**:客户端自己抓屏、自己缩放、 +自己编码 JPEG 回包(`TOKEN_SCREEN_PREVIEW_RSP(248)`),不建子连接、不占槽位、 +一次请求一次响应。这是 MFC `get_screenshot` 的既有实现 +(`McpServer.cpp:2199`、`2015RemoteDlg.cpp:10449`),Go 照做即可。 + +### 7.2 请求 / 响应 + +```c +struct ScreenPreviewReq { // 8 字节 + uint8_t cmd; // 247 + uint16_t reqId; + uint16_t maxWidth; + uint8_t jpegQuality; // 1..100 + uint16_t reserved; +}; + +struct ScreenPreviewRspHeader { // 16 字节 + uint8_t token; // 248 + uint16_t reqId; + uint8_t status; // 0=OK 1=抓屏失败 2=编码失败 3=不支持 4=目标无效 + uint8_t format; // 0=JPEG 3=BGRX + uint16_t width, height; + uint32_t bytes; + uint8_t reserved[3]; + // 后接 data[bytes],可选再跟 ScreenCaptureMeta +}; +``` + +v1 只发 8 字节基础请求(等价于整虚拟桌面),**不发 v2 扩展**——`region/window/monitor` +需要 `CLIENT_CAP_SCREEN_REGION`,属后续增强。 + +参数映射:`max_width` 默认 1600,钳制到 `[320, 3840]`;`jpegQuality` 固定 80。 + +### 7.3 BGRX → JPEG + +Linux 客户端没有 JPEG 编码库,回 `format=3`(BGRX,自上而下逐行、每像素 4 字节 +`B,G,R,X`,无行填充,`bytes == width*height*4`)。Go 用标准库转: + +```go +img := image.NewRGBA(image.Rect(0, 0, w, h)) +for i := 0; i < w*h; i++ { + img.Pix[i*4+0] = src[i*4+2] // R ← B + img.Pix[i*4+1] = src[i*4+1] // G + img.Pix[i*4+2] = src[i*4+0] // B ← R + img.Pix[i*4+3] = 0xFF +} +jpeg.Encode(&buf, img, &jpeg.Options{Quality: 80}) +``` + +`bytes != w*h*4` 时按畸形包丢弃(返回 `-32000`)。 + +### 7.4 能力门与超时 + +- 缺 `CLIENT_CAP_SCREEN_PREVIEW(0x0004)` → `-32005`。 + MFC 同款门(描述里写明"老客户端返回 -32005")。 +- 超时 8 s。**不做取消**:MFC 明确写了"屏幕预览 = 主连接 RPC,不能 CancelIO" + (`2015RemoteDlg.cpp:7514`)。超时后把请求表项删掉,迟到的响应按 `reqId` 不匹配丢弃。 +- 响应 `status != 0` 时按码翻译:1/2 → `-32000`(带 status 文案),3 → `-32005`, + 4 → `-32602`。 + +--- + +## 8. 文件工具 + +### 8.1 `list_files` + +见 §5.3。解析细节: + +- `TOKEN_DRIVE_LIST`:`[token][letter:1][type:1][totalMB:4][freeMB:4][typeName\0][fileSystem\0]` 循环, + `letter=='\0'` 终止。 +- `TOKEN_FILE_LIST`:`[token]([attr:1][name\0][sizeHigh:4][sizeLow:4][ftLow:4][ftHigh:4])*`, + 空名终止(尾部零填充)。`attr & 0x10` 为目录。 +- `TOKEN_FILE_LIST_ERROR`:`[token][win32err:4 LE]`,按 §4.3 映射。这是**新客户端**才有的 + 失败回执;老客户端路径不存在时直接不回包,表现为 `-32001` 超时(message 里要提示 + "路径可能不存在,先用 list_files 确认")。 + +`total` 与 `returned` 分开:客户端一次返回全部,服务端做 `limit` 截断并在 +`structuredContent` 里如实说明(与 MFC 的分页语义一致)。 + +### 8.2 `read_file` + +见 §5.4。落盘完成后: + +1. 校验 SHA-256(`COMMAND_FILE_COMPLETE_V2` 里带的 32 字节)。 +2. 打开临时文件,按 `offset`/`limit` 读取(负 `offset` 从尾部倒数)。 +3. 按 `encoding` 解码:`auto` 先试严格 UTF-8(`utf8.Valid`),失败回退 GBK + (`golang.org/x/text/encoding/simplifiedchinese`,go.mod 已有)。 +4. 返回 `text` + `size` + `bytes_read` + `truncated` + `sha256`。 +5. `defer os.RemoveAll(tmpDir)`。 + +**大小门**:`CMD_DOWN_FILES_V2` **没有区间参数,只能整文件下载**,所以大小门必须卡在 +下载前——在首个 `COMMAND_SEND_FILE_V2` chunk 里读 `fileSize`,超过 +`YAMA_MCP_READ_MAX`(默认 2 MiB,与 MFC 的 `kReadFileSizeGate` 一致)立即中止传输、 +删临时目录、返回 `-32602`,message 说明"文件超过 2 MiB,本工具不支持"。不要先落盘 +200 MB 再报错。 + +`offset` / `limit` 是**下载完成之后**对返回窗口的裁剪(`limit` 默认 256 KiB、 +上限 4 MiB),不能用来绕过大小门——大文件在 Go 侧目前无解,这是协议限制, +工具描述里要写明。 + +### 8.3 路径校验(安全,必读) + +V2 的 `filename` 由客户端提供。必须: + +```go +clean := filepath.Clean(filepath.Join(targetDir, filepath.FromSlash(name))) +rel, err := filepath.Rel(targetDir, clean) +if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) { + abortTransfer() // 拒收并中止 +} +``` + +`filepath.HasPrefix` 字符串前缀比较不够——`/tmp/ab` 会匹配 `/tmp/abc`。用 `filepath.Rel` 判越界。 + +同理 `list_files` 的 `path` 与 `read_file` 的 `path` 不做本地校验(它们在远端), +但**不允许包含 NUL 与换行**——那会截断/拆开 C 字符串协议字段。 + +--- + +## 9. 并发、配额、生命周期 + +| 项 | 规则 | +|---|---| +| 每设备单请求 | `map[deviceID]*sync.Mutex` 的 `TryLock`;占用返回 `-32003`,message 带占用工具名与已持续时长 | +| 全局并发 | `YAMA_MCP_MAX_CONCURRENCY`(默认 16)信号量;超出直接 `-32003` | +| 单次请求上限 | `terminal_exec` 120 s,`read_file` 120 s,`get_screenshot` 8 s,其余 10 s | +| 设备锁释放 | `defer` 释放;HTTP ctx 取消也走同一条 defer | +| 终端空闲回收 | ticker 30 s 扫一次,`lastUsed` 超 180 s 关闭 | +| 进程退出 | `mcp.Server.Close()` 关闭所有终端会话(避免留下孤儿 shell 子连接) | + +设备锁的粒度是"整台设备"而不是"每通道",与 MFC 一致(`-32003` 说明里写明 +"列表、截屏、文件、管理动作共用这一道锁")。理由是主连接 RPC 与子连接命令 +在客户端侧可能共用同一份状态,并发只会让现场更难读。 + +--- + +## 10. 代码结构与依赖方向 + +``` +server/go/mcp/ + server.go # /mcp handler、JSON-RPC 分发、鉴权、tools/list + tools.go # 9 个工具的定义表(name/description/inputSchema) + errors.go # 错误码 + JSON-RPC 错误映射 + audit.go # mcp.tool.call 审计 + lock.go # 设备锁 + 全局信号量 + session.go # 终端会话表、空闲回收 + term.go # 哨兵、环形缓冲、输出清洗 + screen.go # 主连接预览 RPC + filemgr.go # 文件管理器子连接(list_files) + filev2.go # V2 流式接收端(read_file) +``` + +依赖方向(无环): + +``` +cmd/main.go ──▶ web ──▶ mcp ──▶ hub ──▶ connection / protocol + │ └──▶ devicehistory + └──▶ wsauth +``` + +- `mcp` 只 import `hub` / `protocol` / `devicehistory` / `logger`,**不 import `web`**。 +- **构造顺序**:`mcp.Server` 在 `cmd/main.go` 里先建,再分别注入两侧—— + `web.New(...).WithMCP(mcpSrv)`(沿用 `WithDeviceHistory` / `WithConfig` 的链式风格, + `web/server.go:94`),以及 `MyHandler.mcp = mcpSrv`(TCP 分派侧)。 + 这样 `web` 和 `cmd` 都只依赖 `mcp`,不存在 `mcp → web` 的反向依赖。 +- TCP 侧的分派(`cmd/main.go` 的 `OnReceive`)新增六个 case: + `TokenScreenPreviewRsp(248)` / `TokenDriveList(103)` / `TokenFileList(104)` / + `TokenFileListError(171)` / `CommandSendFileV2(85)` / `CommandFileCompleteV2(91)`, + 统一转给 `mcp.Server.OnPacket(ctx, data)`,未命中在途请求就丢弃。 + +**为什么工具定义手写在 Go 里、不 embed `mcp/tools.json`**:9 个工具的 schema 手写约 +300 行,而 embed 需要跨语言目录同步(`mcp/tools.json` 在仓库根,`//go:embed` 不能 +引用父目录),要么加 Makefile 同步步骤、要么提交一份副本。手写 + 校验脚本更简单。 +防漂移靠 `tools/mcp_tools/verify_tools.py` 增加 `--subset` 模式:把 Go 的 +`tools/list` 抓下来,与 `mcp/tools.json` 里同名的工具逐字段比对,多一个少一个都报错。 + +--- + +## 11. 施工顺序与验收 + +| 序 | 内容 | 依赖 | 可独立验收 | +|---:|---|---|---| +| 1 | `mcp` 包骨架 + `/mcp` + 鉴权 + `initialize`/`ping`/`tools/list` | — | ✅ `curl` 打通 | +| 2 | 4 个本机只读工具(`list_hosts`/`get_host_detail`/`get_server_status`/`get_audit_log`) | 1 | ✅ 不碰设备即可测 | +| 3 | 设备锁 + 全局信号量 + 审计 | 1 | ✅ | +| 4 | 终端会话表 + 订阅 + 环形缓冲 | 3 | ✅ 浏览器开终端时能观察到缓冲 | +| 5 | 哨兵 + 输出清洗 + `terminal_exec` 执行/轮询 | 4 | ✅ 对照 MFC 同款命令的输出现象 | +| 6 | `terminal_close` + 空闲回收 | 5 | ✅ | +| 7 | 主连接 RPC 请求表 + `get_screenshot` | 3 | ✅ | +| 8 | 文件管理器子连接 + `list_files` | 3 | ✅ | +| 9 | V2 接收端 + `read_file` + 路径校验 | 8 | ✅ | +| 10 | `verify_tools.py --subset` | 1 | ✅ | + +**整体验收**(用同一套 ASM 工位任务重跑): + +- 9 个工具全部可调用,`tools/list` 响应 < 24 KB(无 outputSchema 的直接收益) +- `terminal_exec` 连续 20 条命令零失败;超时后轮询能取回完整输出 +- 浏览器开着终端时 `terminal_exec` 返回 `-32003` 而不是把人的会话踢掉 +- `read_file` 读 `.env`(含单引号、CRLF)字节级一致,SHA-256 与远端 `sha256sum` 相同 +- `get_screenshot` 在 Windows / Linux 各出一张图,Linux 走 BGRX→JPEG 分支 +- 审计里每次调用一条 `mcp.tool.call`,`device`/`tool`/`code`/`ms` 齐全 + +--- + +## 12. 风险与未决 + +| # | 风险 | 影响 | 处置 | +|---:|---|---|---| +| R1 | 哨兵清洗移植不完整 | 输出带垃圾/退出码错 | 按 MFC 三段顺序整体移植,用 MFC 记录的实测样例做 Go 单测(`rem hello`、`cmd /c echo abc`、`type .env`) | +| R2 | 终端槽位被 MCP 长期占用 | 人用不了终端 | 空闲 180 s 回收 + `-32003` 明确告知 + 工具描述写明 | +| R3 | 老客户端不认识 `CMD_DOWN_FILES_V2(94)` | `read_file` 静默超时 | 工具描述写明"超时可能是不支持 V2 的旧客户端";§5.4 | +| R4 | 老客户端缺 `CLIENT_CAP_UTF8` | 文件名 GBK 解码 | 新客户端 `DefaultCaps()` 恒带此位(`commands.h:1289`),只有很老的客户端会缺;与既有 `activeWindow` 路径同源,后续在 `hub.DeviceInfo` 暴露 `clientType` 后一并修 | +| R5 | 非 PTY 老客户端 | 无法用 `terminal_exec` | v1 明确 `-32005`,描述里说明 | +| R6 | 多用户 / 分组授权缺失 | 所有 MCP 调用都是 admin | v1 明确单 principal;多租户部署前必须补 token 表 + `allowedGroups` 校验 | +| R7 | 无 `notifications/progress` | 长任务(`read_file` 大文件)模型以为卡死 | 工具描述写明预期耗时;v2 再上 SSE | +| R8 | `read_file` 只能整文件下载,2 MiB 封顶 | 读大日志无解 | 与 MFC 同款限制(`kReadFileSizeGate`)。绕法是 `terminal_exec` + `tail`,工具描述里给出这个替代路径 | + +--- + +## 附录 A:协议速查 + +| 名称 | 值 | 方向 | 载荷 | +|---|---:|---|---| +| `COMMAND_LIST_DRIVE` | 1 | S→C 主连接 | `[cmd]` | +| `COMMAND_LIST_FILES` | 2 | S→C 文件子连接 | `[cmd][path\0]` | +| `COMMAND_SCREEN_SPY` | 16 | S→C 主连接 | `[cmd]` | +| `COMMAND_BYE` | 204 | S→C 任意 | `[cmd]` | +| `COMMAND_SCREEN_PREVIEW_REQ` | 247 | S→C 主连接 | `ScreenPreviewReq`(8B) | +| `COMMAND_SEND_FILE_V2` | 85 | C→S V2 子连接 | `FileChunkPacketV2`(77B)+ name + data | +| `COMMAND_FILE_COMPLETE_V2` | 91 | C→S V2 子连接 | `FileCompletePacketV2`(69B) | +| `CMD_DOWN_FILES_V2` | 94 | S→C 文件子连接 | `[cmd][targetDir\0][path\0][\0]` | +| `TOKEN_DRIVE_LIST` | 103 | C→S 文件子连接 | `[token]` + 盘符记录 | +| `TOKEN_FILE_LIST` | 104 | C→S 文件子连接 | `[token]` + 文件记录 | +| `TOKEN_FILE_LIST_ERROR` | 171 | C→S 文件子连接 | `[token][win32err:4 LE]` | +| `TOKEN_CONN_AUTH` | 246 | C→S 子连接 | `ConnAuthPacket`(512B) | +| `TOKEN_SCREEN_PREVIEW_RSP` | 248 | C→S 主连接 | `ScreenPreviewRspHeader`(16B)+ data | + +`FileChunkPacketV2` 字段:`cmd(1) transferID(8) srcClientID(8) dstClientID(8) +fileIndex(4) totalFiles(4) fileSize(8) offset(8) dataLength(8) nameLength(8) +flags(2) checksum(2) reserved(8)` = 77 字节。 + +--- + +## 附录 B:自审记录 + +写完初稿后按"每个结论都必须能在代码里指到行"重核了一遍,发现并修掉以下问题: + +| # | 问题 | 处置 | +|---:|---|---| +| 1 | 初稿写"文件管理器子连接不带 ConnAuth,需要 pending 标记",照搬了 MFC 的做法 | **错**。`client/KernelManager.cpp:1773` 对 `COMMAND_LIST_DRIVE` 调了 `EnableSubConnAuth()`,Go 的 `handleConnAuth` 已把 clientID 钉在 ctx 上。改为按 clientID 路由,删掉 pending 方案,省掉一个 hub 改动 | +| 2 | 初稿把 `get_screenshot` 设计成"抓 `TOKEN_FIRSTSCREEN` 原始帧" | **改**。`TOKEN_FIRSTSCREEN` 虽注释为 raw BGRA,但它依附于屏幕会话(占槽位、要建子连接)。改用 `COMMAND_SCREEN_PREVIEW_REQ` 主连接 RPC——与 MFC 一致,不占任何槽位 | +| 3 | 初稿写"终端槽位需要给 hub 加 owner 字段" | **简化**。`hub.OpenTerminalSession` 的 `ErrTerminalBusy` 本身就是互斥,v1 不抢占就不需要 owner。删掉 hub 改动,v1 对 `hub` **零改动** | +| 4 | 初稿写 `read_file` 用 `filepath.HasPrefix` 校验路径 | **错**。字符串前缀会让 `/tmp/ab` 匹配 `/tmp/abc`。改为 `filepath.Rel` 判越界 | +| 5 | 初稿漏了非 PTY 客户端的处理 | **补** §6.7:v1 明确 `-32005`,不做半吊子支持 | +| 6 | 初稿写"审计记录完整 command" | **改**。命令全文可能含密码,改为只记首词与长度,全文进 debug 日志 | +| 7 | 初稿的 `list_files` 没写 `total` 与 `returned` 的区别 | **补** §8.1,避免模型把截断当成"目录里只有这么多" | +| 8 | 初稿写"`terminal_exec` 的 reqId 用时间戳" | **改**。时间戳在并发下会撞;改 `atomic.Uint32` 取低 16 位,并**必须**校验响应 reqId(MFC `TakePreviewResponse` 同款) | +| 9 | 初稿把 `get_screenshot` 的 `max_width` 固定 1600 | **改** 为可传,钳制 `[320,3840]`,与 MFC 的 `max_width` 参数对齐 | +| 10 | 初稿没写"客户端 V2 开关关闭会静默超时" | **改**。核查后发现 V2 开关是**服务端**的(`2015RemoteDlg.cpp:2822` `EnableFileV2`,默认关),不是客户端。且 `CLIENT_CAP_V2` 在 `DefaultCaps()` 里全平台无条件声明,做门等于没门。改为"无能力门 + 老客户端不认识 94 号命令会静默超时",见 §5.4 | +| 11 | 初稿把 `read_file` 的能力门写成 `CLIENT_CAP_V2` | **删**。同 #10,该位恒为真。表格与 §5.4 一并改 | +| 12 | 初稿写 `/mcp` 用 `s.requireBearer` 包一层 | **错**。`requireBearer` 校验的是浏览器会话令牌(`web/server.go:269` 的 `s.auth.ValidateToken`),MCP 静态令牌过不去。改为 `mux.HandleFunc("/mcp", s.mcp.Handle)`,鉴权在 handler 内做 | +| 13 | 初稿写"`mcp` 在 `web.Start()` 里构造" | **错**。TCP 侧 `cmd/main.go` 的 `OnReceive` 也要把包转给 `mcp`,两边需要同一实例。改为在 `cmd/main.go` 先建,再 `web.New(...).WithMCP(srv)` + `MyHandler.mcp = srv` | +| 14 | 初稿写"非 PTY 客户端 `-32005`",但没说"根本不支持 shell 的客户端怎么办" | **补** §6.7:不设能力门(`CLIENT_CAP_TERMINAL` 只有 Android 声明),走 `-32001` 超时 + message 提示 | +| 15 | §5.3 时序图自相矛盾:`TOKEN_DRIVE_LIST` 后写"关子连接",下一行又写"同一子连接"发 `COMMAND_LIST_FILES` | **改**。列目录必须复用同一个子连接(`2015RemoteDlg.cpp:7647` 的注释),改为"保持打开,`TOKEN_FILE_LIST` 分支收尾" | +| 16 | §5.4 仍写 `filepath.HasPrefix` 校验路径,与 §8.3 自相矛盾 | **改**。统一指向 §8.3 的 `filepath.Rel` 判越界 | +| 17 | §7.1 说"屏幕流全是 H.264",据此否掉首帧方案 | **错两处**:首帧 `TOKEN_FIRSTSCREEN` 本来就是裸 BGRA,不需要解码;否掉它的真正理由是**要建屏幕子连接、占唯一槽位、还要拆**。改为按代价论证 | +| 18 | §8.2 建议大文件"直接用 `download_file`" | **错**。`download_file` 在 v1 不做(§1.2),不能建议一个不存在的工具。改为"卡在下载前的大小门 + 用 `terminal_exec` 兜底" | +| 19 | §8.2 只说"`limit` 上限 4 MiB",没意识到 V2 是整文件下载 | **补**。`CMD_DOWN_FILES_V2` 无区间参数,大小门必须卡在首个 chunk 的 `fileSize` 上(2 MiB,与 MFC `kReadFileSizeGate` 一致),否则会先落盘再报错 | +| 20 | §3.2 `get_server_status` 返回 `version`/`commit`,但 Go 侧没有这两个变量 | **补**。`cmd/main.go` 查不到版本常量,需新增 `var version, commit string` + Makefile `-X` 注入;拿不到返回空串 | +| 21 | §3.2 `get_host_detail.capabilities` 里列了 `v2` | **删**。该位全平台恒真(同 #10),列出来误导模型。换成 `utf8`/`screen_preview`/`screen_region`/`window_info` | +| 22 | §5.2 写死 `SendToTerminal(cmd+"\n")`,与 §6.4 的 ConPTY `\r\n` 冲突 | **改** 为按平台分行尾 | + +**结论**:以上 22 处已全部修入正文,无遗留。v1 对 `server/go` 的改动是 +**新增 `mcp` 包 + `web/server.go` 一行路由 + `web.Server` 一个 `WithMCP` + `cmd/main.go` 六个 case + `protocol` 六个常量 + 两个版本变量**, +`hub` 零改动。 diff --git a/docs/Mcp_Go_Minimal_Implementation_Plan.md b/docs/Mcp_Go_Minimal_Implementation_Plan.md new file mode 100644 index 0000000..c82014c --- /dev/null +++ b/docs/Mcp_Go_Minimal_Implementation_Plan.md @@ -0,0 +1,523 @@ +# Go 服务端 MCP 实施计划 + +> 版本:v1(草稿,待评审) 日期:2026-11-12 +> +> 依据:`docs/Mcp_Go_Minimal_Design.md` v1.0(下称"设计文档")。 +> 本文只回答**怎么施工**:顺序、改动面、完成定义、验证手段、提交边界。 +> 设计取舍一律以设计文档为准,本文不重复论证;与设计文档不一致的地方在 §1 单列。 +> +> 工作方式:沿用本项目既有节奏——**做一段、验一段、审一段、提交一段**,每段一个可独立 +> 回滚的提交。Go 侧提交前缀用仓库既有约定 `Feature(Go):` / `Fix(Go):`。 + +--- + +## 0. 交付面与总量 + +| 类别 | 内容 | 规模 | +|---|---|---:| +| 新包 | `server/go/mcp/`(server / tools / errors / audit / lock / session / term / screen / filemgr / filev2) | ≈2,300 行(含测试 ≈900) | +| 抽包 | `server/go/auditquery/`(从 `web/audit_query.go` 提出查询器,见 §1.1) | ≈180 行搬移 | +| 接线 | `web/server.go`(`WithMCP` + 一行路由)、`cmd/main.go`(构造/注入/六个 case/版本变量)、`protocol/commands.go`(常量)、`build.ps1` + `Makefile`(`-X` 注入) | ≈120 行 | +| 工具校验 | `tools/mcp_tools/verify_tools.py` 增 `--subset` | ≈80 行 | +| 文档 | `deploy/yama-server.env.example` 补 5 个变量;`docs/Mcp_Go_Minimal_Design.md` 状态改"已实施" | — | + +**8 个提交,8 个里程碑,预估 62 小时**(明细见 §3 / §7)。`hub` 零改动——这是设计文档 +自审后的结论,本计划沿用;若施工中发现必须改 `hub`,先停下来改设计文档。 + +--- + +## 1. 开工前必须先定的 5 件事 + +这 5 项都会阻塞某个里程碑,且都需要一次性拍板。建议按顺序在本计划评审时定掉。 + +### 1.1 `get_audit_log` 的代码复用方式(阻塞 M2) + +设计文档 §3.2 要求"复用 `web/audit_query.go` 的查询器",§10 又要求"`mcp` 不 import `web`"。 +两者冲突:查询器 `queryAuditLog` 及其类型/过滤/时间解析全是 `web` 包私有(`web/audit_query.go:158-328`)。 + +| 方案 | 做法 | 代价 | +|---|---|---| +| **A(推荐)** | 新增 `server/go/auditquery` 包,把 `queryAuditLog` + `auditQueryRequest/Result` + `auditRecordMatches` / `auditEventFilterMatches` / `auditStringField` / `parseAuditTime` / `clamp*` 整体搬过去并导出(`Scan(path string, q Query) (Result, error)`);`web/audit_query.go` 只留 handler 与回包整形 | 搬移 + `web/audit_query_test.go`(294 行)机械改调用名;依赖方向保持不变 | +| B | `mcp` 自己实现一个精简扫描器(keyword/type/limit/offset) | 少动 `web`,但审计格式一旦变就有两份实现 | +| C | `mcp` import `web` | 破环:`web → mcp` 已存在(`WithMCP`),反向成环直接编译失败 | + +**已确认:采用 A**。M2 的第一步就是搬包,`go test ./web/...` 全绿后再写工具。 + +### 1.2 版本号与提交号注入(阻塞 M2 的 `get_server_status`) + +`cmd/main.go` 目前没有版本常量(全文件 grep 不到)。**已确认**的做法: + +- 新增 `server/go/buildinfo`,只放 `var Version, Commit string`(零值空串)+ `Snapshot()`。 + 不塞 `main`:`mcp` 不能依赖 `main`,也不该为两个字符串在装配链上多传两层。 +- 注入:`-X github.com/yuanyuanxiang/SimpleRemoter/server/go/buildinfo.Version=…`,同样注入 `.Commit`。 + 取值 `Version=$(git describe --tags --always --dirty)`、`Commit=$(git rev-parse --short HEAD)` + (现在是 `v1.4.2-72-g425d737-dirty` / `425d737`)。 +- `build.ps1`:Debug/Release **都**拼 `-X`(Debug 只是不剥符号);`Makefile` 的 `LDFLAGS` + 用 `$(shell git …)` 同步。 +- 取不到(无 git、源码包构建)就保持空串,`get_server_status` 原样返回空串,**不伪造**。 +- Windows 资源同步:`cmd/winres/winres.json` 里的版本号改成占位,构建前跑 + `go-winres make --in cmd/winres/winres.json --out cmd/rsrc --product-version git-tag --file-version git-tag` + (实测会把 manifest identity / FileVersion / ProductVersion 三处一起覆盖成 `1.4.2`); + `go-winres` 不存在时警告并跳过。`server/go/cmd/*.syso` 加进 `.gitignore`,不再出现在 + `git status` 里。文件属性 = 干净 tag,运行时 `version` = `git describe` 全串,各司其职。 + +### 1.3 工具 schema 用哪一份(阻塞 M2/M5/M6/M7) + +设计文档 §3.2 给的参数集与 `mcp/tools.json`(MFC 现网 schema)**并不完全一致**: + +| 工具 | 设计文档 §3.2 | `mcp/tools.json` 实际 | +|---|---|---| +| `list_hosts` | `group` `name` `online_only` `limit` `offset` | `client_type` `group` `include_offline` `ip` `limit` `name` `offset` `online` `os` `query` | +| `get_host_detail` | `id` | `id` `ids` | +| `get_audit_log` | `keyword` `type` `since` `limit` `offset` | `keyword` `limit` `offset` `type` | +| `get_screenshot` | `id` `max_width` | `id` `max_width` `height` `hwnd` `mode` `monitor` `width` `x` `y` | +| `terminal_exec` | 一致 | 一致 | +| `terminal_close` | `session_id` | `id` `session_id` | +| `list_files` | `id` `path` `limit` | `id` `ids` `limit` `offset` `path` | +| `read_file` | `id` `path` `offset` `limit` `encoding` | 同 + `max_bytes` | + +设计文档自称"全部命名、参数、错误码与 MFC 对齐",实际只有 naming 与错误码对齐。 +**已确认:`mcp/tools.json` 是唯一契约**——`name` / `description` / `inputSchema` / +`outputSchema` 和工具顺序都按它来(`verify_tools.py:12` 的比对口径)。 + +- 9 个工具的这四份字段由 `tools/mcp_tools/gen_go_tools.py` 从 `mcp/tools.json` 抽取(保持相对顺序), + 写到 `server/go/mcp/tools_minimal.json`,Go 侧 `//go:embed` 原样回 `tools/list`;脚本支持 + `--check`(子集与抽取结果不等则非零退出),加一个 Go 单测锁名字与顺序。 +- `tools.json` 里没有 `annotations`,MFC 也不发,Go 不发(M1 的测试相应改为"不带 annotations")。 +- 输出按对应 `outputSchema` 的字段名组装,**不套用设计文档 §3.2 的自造形状**。 + +| 参数 | Go 侧处理 | +|---|---| +| `list_hosts` 全部 10 个 | 全部实现(`DeviceInfo` 上做字符串过滤,成本可忽略) | +| `get_host_detail.ids` | 实现批量(≤50),按 `outputSchema` 的 `{tool,total,succeeded,failed,skipped,results[]}` 汇总 | +| `get_audit_log` | `keyword` / `type`(映射 `auditquery.Event`)/ `limit` / `offset`;**没有 `since`**(MFC 的 schema 里就没有) | +| `get_screenshot` 的非整屏参数 | `mode=region/window/monitor` 或 `hwnd/x/y/width/height` 任一出现 → `-32005`,报文点名参数并说明需要 `CLIENT_CAP_SCREEN_REGION` 扩展请求;不静默忽略 | +| `get_screenshot.max_width` | 钳制 `[64,1920]`(schema 与 `McpServer.cpp:3386` 一致);缺省/0 → Go v1 固定 1024(没有 MFC 的 RTT 自适应档位) | +| `terminal_close.id` | 必需;用于定位设备,`session_id` 用于匹配会话 | +| `list_files` 的 `id/ids/path/limit/offset` | 全部实现;`offset` 是服务端在完整列表上做窗口裁剪;批量走 results 汇总 | +| `read_file` 的语义 | **行语义**:`offset` 起始行(负数=末尾 N 行)、`limit` 行数、`max_bytes` 字节上限;`encoding` 支持 `auto/utf-8/gbk/gb18030/latin1` | +| 输出字段 | `list_hosts` → `hosts/total/totalAll/limit/offset/hasMore`;`list_files` → `files`(不是 `entries`)/`drives`;`get_host_detail.capabilities` → `screenPreview/screenRegion/windowInfo/fileTransferV2/c2cPaths/registry/remoteControl/platform`;`read_file` → `encoding/eol/lines_total/lines_returned/sha256/size/text/truncated` | +| hub 没有的字段 | `authStatus/tls/location/install_time/remark` 不伪造、直接不给(`outputSchema` 只强制 `hosts`) | + +`read_file` 的整文件下载仍受 `YAMA_MCP_READ_MAX`(2 MiB)硬门约束,超过 → `-32602`(schema 描述同款口径)。 + +### 1.4 测试环境与"真机"路径(阻塞 M4 起的全部验收) + +**已确认并已由 M0 实测**(详见 §4.3):本机真客户端用 **`x64\Debug\ghost.exe`**, +`TestRun.exe` 不可用(依赖 `ServerDll.dll` 内存加载;Release 版从非安装路径启动会走安装 +流程并自删)。Go 服务端默认 **trial** 签名即可,客户端已上线;屏幕/文件能力是否解锁 +在 M5/M6 实测(`YAMA_LICENSE_DISABLED=1` 的 NoOp 会让客户端拒绝这两类功能,不要用于 +M5 之后的验收)。 + +### 1.5 只读模式下的工具集合(阻塞 M8) + +`YAMA_MCP_READONLY=1` 时 `tools/list` 只出 7 个。`--subset` 必须支持"期望集合 7 或 9"两种, +由环境变量或 `--readonly` 参数决定;不能写成硬编码 9。 + +--- + +## 2. 里程碑与提交边界 + +| 里程碑 | 提交标题(建议) | 设计文档 § | 依赖 | 完成定义(可验收) | 预估 | +|---|---|---|---|---:| +| M1 | `Feature(Go): MCP endpoint with bearer auth and tools/list` | §4、§3.1 | — | `curl` 打通 initialize/ping/tools/list;错误令牌 401;GET 405;通知 204 | 6h | +| M2 | `Feature(Go): four local MCP read tools and a shared audit query package` | §3.2、§1.1 | M1 | 4 个工具返回真实数据;`go test ./web/...` 与新增用例全绿 | 10h | +| M3 | `Feature(Go): per-device locks, concurrency cap and MCP audit trail` | §9、§4.4 | M1 | 并发调用返回 -32003;每次调用一条 `mcp.tool.call` | 4h | +| M4a | `Feature(Go): MCP terminal sessions with a ring buffer` | §6.1-§6.3 | M3 | 会话表 + 订阅 + 缓冲;浏览器开终端时 MCP 返回 -32003 | 6h | +| M4b | `Feature(Go): terminal_exec with sentinel cleaning and polling` | §6.4-§6.6 | M4a | 20 条连续命令零失败;超时后轮询取回完整输出 | 8h | +| M4c | `Feature(Go): terminal_close, idle sweep and legacy-client guard` | §6.2、§6.7 | M4b | 关闭幂等;空闲 180s 回收;非 PTY 返回 -32005 | 2h | +| M5 | `Feature(Go): get_screenshot over the maintenance-free preview RPC` | §7 | M3 | Windows/Linux 各出一张图;BGRX 分支有单测 | 6h | +| M6 | `Feature(Go): list_files over the file-manager sub-connection` | §5.3、§8.1 | M3 | 盘符/目录/错误三种路径;老客户端超时有明确 message | 8h | +| M7 | `Feature(Go): read_file over the V2 stream receiver` | §5.4、§8.2-§8.3 | M6 | `.env` 字节一致且 SHA-256 匹配;路径穿越全部拒收 | 10h | +| M8 | `Feature(Go): verify_tools --subset and MCP deployment docs` | §10、§4.2 | M1 | 9(或 7)个工具的 schema/description 与 `tools.json` 严格一致 | 3h | + +M4 拆成三个提交是因为它占全量工作量的 1/4,一次提交无法审查;其余里程碑按设计文档 +§11 的 10 个施工序合并(§11 的 3 并进 M3,4/5/6 并成 M4a/b/c,7 是 M5,8 是 M6,9 是 M7,10 是 M8)。 + +--- + +## 3. 里程碑细则 + +### M1 骨架与鉴权(设计 §4) + +**新增文件** + +``` +server/go/mcp/server.go // Config、Server、New、Enabled、Handle、Close +server/go/mcp/jsonrpc.go // 请求/响应结构、错误对象、批量拒绝 +server/go/mcp/tools.go // //go:embed tools_minimal.json,tools/list 原样返回 +server/go/mcp/tools_minimal.json // gen_go_tools.py 从 mcp/tools.json 抽取的 9 个工具 +server/go/mcp/errors.go // -32001…-32602 常量与 message 模板 +tools/mcp_tools/gen_go_tools.py // 抽取脚本,--check 模式供验收 +``` + +**实现要点** + +1. `Config` 从环境变量读全(`cmd/main.go` 解析后传入,`mcp` 包不直接读 env): + `Token` / `Readonly` / `TermIdle` / `MaxConcurrency` / `ReadMax`。 +2. `Handle` 分支表:`POST` 之外一律 `405`(带 `Allow: POST`);无 `id` 的通知 `204`; + 数组入参 `-32600`;未知 `method` `-32601`;`tools/call` 未知工具名 `-32601`。 +3. 鉴权:`subtle.ConstantTimeCompare`,长度不等直接失败;缺令牌 → `401` + + `WWW-Authenticate: Bearer realm="mcp"`,不带 JSON-RPC 体(规范要求传输层失败)。 +4. 体积:`http.MaxBytesReader(w, r.Body, 8<<20)`,超限 `413`。 +5. `initialize` 回 `protocolVersion=2025-06-18`、`capabilities.tools={listChanged:false}`、 + `serverInfo={name:"yama", version:}`、`instructions=`。 + `serverInfo.name` 与 MFC 一致,Go 差异只写 `instructions`——避免客户端按 name 分叉。 +6. 路由注册:`web/server.go` 加 `WithMCP`,`Start()` 里 + `if s.mcp != nil && s.mcp.Enabled() { mux.HandleFunc("/mcp", s.mcp.Handle) }`, + 否则打一行 `MCP endpoint disabled: YAMA_MCP_TOKEN not set`。 +7. `cmd/main.go`:在 `web.New(...)` 之前构造 `mcpSrv`,再 `.WithMCP(mcpSrv)` + + `handler.mcp = mcpSrv`(`MyHandler` 加字段);`mcp` 只依赖 `hub`/`protocol`/`devicehistory`/`logger`。 + +**测试**(`mcp/server_test.go`,`httptest` + fake hub) + +- 令牌:正确 / 错误 / 长度不同 / 缺失 → 200 / 401 / 401 / 401。 +- 方法:`initialize`、`ping`、`tools/list`、`notifications/initialized`(204)、未知方法(-32601)。 +- 形态:批量数组 → -32600;GET/DELETE → 405;超大体 → 413。 +- `tools/list`:数目与 `Readonly` 相符;工具定义与 `tools_minimal.json` 逐字一致且顺序不变 + (无 `annotations`,与 MFC 一致)。 + +**验收命令** + +```bash +cd server/go +go build ./... && go test ./mcp/... +curl -s -X POST localhost:18090/mcp -H "Authorization: Bearer $YAMA_MCP_TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' +``` + +### M2 本机只读四工具(设计 §3.2) + +**改动** + +1. 先做 §1.1 的 `auditquery` 抽包:搬移 → `web` 改调用 → `go test ./web/...` 全绿。 +2. 新增 `mcp/tools_local.go`: + - `list_hosts`:`hub.ListDevices()` + `history.Offline(onlineSet)` 合并;`include_offline` + 决定是否并入历史;`online/ip/os/group/name/client_type/query` 全为过滤(`name`/`query` + 大小写不敏感子串);按 `outputSchema` 返回 `{hosts,total,totalAll,limit,offset,hasMore}`, + host 字段按 schema 命名组装,hub 没有的(`authStatus/tls/location/install_time/remark`)不伪造。 + - `get_host_detail`:`id` 或 `ids`(≤50,批量走 `{tool,total,succeeded,failed,skipped,results[]}`); + `capabilities{screenPreview,screenRegion,windowInfo,fileTransferV2,c2cPaths,registry,remoteControl,platform}` + (`protocol.SupportsCap` 逐位)——**不含 `v2`**(恒真,列出来误导)。 + - `get_server_status`:`{version,commit,uptime_s,devices_online,devices_offline_known, + mcp:{readonly,tools}}`;`version`/`commit` 取 `buildinfo`(§1.2),`uptime` 用 `mcp.Config.StartedAt`。 + - `get_audit_log`:`auditquery.Scan`;`type` 映射事件过滤;无 `since`。 +3. `buildinfo` 包 + `build.ps1` / `Makefile` 的 `-X` + winres 重建(§1.2)。 + +**测试**(`mcp/tools_local_test.go`) + +- `devicehistory.New(t.TempDir()+"/devices.json", 10, log)` + `hub.Register` 造 3 台在线、2 台历史 + 离线;断言过滤/分页/`total` 与 `returned` 分离。 +- `get_host_detail` 的能力位:给一个 capability 串(含/不含 `0x0004`)两种。 +- `get_audit_log`:用 `logger.Audit` 写临时文件后查询(`auditquery` 的用例在搬包时一并迁)。 + +### M3 锁、并发与审计(设计 §9、§4.4) + +**新增** `mcp/lock.go`、`mcp/audit.go`。 + +1. 设备锁:`map[string]*sync.Mutex` + `TryLock`,占用即 `-32003`,message 带占用工具名与 + 已持续时长(`since` 记录在持锁结构里)。 +2. 全局信号量:`chan struct{}` 容量 `MaxConcurrency`,`TryAcquire` 失败 `-32003`。 +3. 审计:每次 `tools/call` 一条 `log.Audit("mcp.tool.call", …)`,字段 + `actor=mcp role=admin source=mcp tool device ok code ms args=<首词+长度> result=<体积摘要>`; + **不记命令全文**(进 debug 日志)。HTTP `r.Context()` 取消同样走 defer 释放锁。 + +**测试**:并发两个同设备调用 → 第二个 -32003;`close(cancel)` 后锁被释放;审计行字段齐全 +(读临时审计文件断言)。 + +### M4a 终端会话(设计 §6.1-§6.3) + +**新增** `mcp/session.go`(会话表 + 空闲回收)、`mcp/term.go`(环形缓冲 + 哨兵检测骨架)。 + +1. `mcp.Server` 实现 `hub.EventHandler` 全接口(`OnDeviceOnline/Offline/Update`、 + `OnScreenFrame`、`OnResolutionChange`、`OnCursorChange`、`OnClipboardText`、 + `OnTerminalReady/Data/Closed`),只有终端三个方法做事,其余空实现; + `cmd/main.go` 里 `deviceHub.Subscribe(mcpSrv)`,退出时 `hub.Unsubscribe` + `Close()`。 +2. `OnTerminalData` 在 TCP 读循环上执行,**必须不阻塞**:只做"查会话 → 追加环形缓冲 → + 剥 4 字节 `TRM1` 前缀 → 哨兵扫描 → `sync.Cond` 唤醒",任何长操作都不允许(设计 §6.3)。 + 非 MCP 会话的设备直接丢弃(零开销)。 +3. 环形缓冲 256 KiB + `base/total/delivered` 绝对偏移;溢出丢最旧并累计 `droppedBytes`。 +4. 会话表 key 用 `deviceID`;`session_id` 为 `"s-"+6hex`;对外只暴露 `session_id`。 + +**测试**:`hub.PublishTerminalData` 灌 1 MB → 缓冲不涨、`truncated` 语义正确;关闭后释放; +浏览器(另建一个订阅者 `OpenTerminalSession`)占用时 `OpenSession` 返回 busy。 + +### M4b `terminal_exec` 执行与轮询(设计 §6.4-§6.6) + +1. 打开:`hub.OpenTerminalSession(deviceID)`;`ErrTerminalBusy` → `-32003`;等 + `OnTerminalReady`(带超时 → `-32001`);非 PTY → `-32005`(M4c 收紧)。 +2. 下发:行尾按 `isPTY`/平台(设计 §6.4 的表);`hub.SendToTerminal`。 +3. 清洗三段**整体移植**:`StripEchoedInput` → `StripAnsi` → `StripSentinelText` + (对应 MFC `McpServer.cpp:3946-4040`),顺序不可换。Go 侧用表驱动单测锁住行为。 +4. 等待与交付:`done`/`closed`/超时三分支;超时**不销毁会话**,`delivered` 游标支持 + `terminal_exec` 不带 `command` 的轮询;`max_output_bytes` 按行截断(保留换行)并置 + `truncated`(防止把 UTF-8/GBK 多字节字符切坏)。 +5. 返回体:`{session_id, output, exit_code?, done, offset, truncated, is_pty, reused}`。 + +**单测**(表驱动,样例来自 MFC 实测) +`rem hello`、`cmd /c echo abc`、`type .env`、SPAM 循环、`ping -n 30` 超时后轮询、 +`cmd /\c` 折行回显、退出码 0/1 与非 PTY 单行哨兵。 + +**集成**(假设备,§4.2):模拟 `TOKEN_TERMINAL_START` → 输出 → 哨兵,断言 `exit_code`。 + +### M4c 关闭、回收与老客户端(设计 §6.2、§6.7) + +1. `terminal_close`:**幂等**(会话不存在也 200);只关 MCP 自己创建的会话(`hub.CloseTerminalSession` + 只有在会话表里有该设备且 `hub.TerminalIsPTY` 一致时才调用,避免误关浏览器会话——实现上 + 以"会话表命中"为准)。 +2. 在途命令被 `terminal_close` 撞上:对齐 C++ 的 `waiters` 教训(`McpServer.cpp:12611`)—— + 置 `closed` 唤醒等待者交付剩余缓冲,无等待者则立即擦会话并 `CloseTerminalSession`。 +3. 空闲回收 ticker 30s 扫一次,`lastUsed > TermIdle` 关闭;`Close()` 关掉全部会话。 +4. 非 PTY(`TOKEN_SHELL_START`)→ `terminal_exec` 直接 `-32005`,message 写明"该客户端版本 + 不支持 PTY 会话"。不支持 shell 的客户端不设能力门,超时文案带一句提示(设计 §6.7)。 + +**测试**:closing 幂等;关闭后立刻重开 <1s;空闲回收(把 `TermIdle` 调成 100ms); +在途关闭与无等待者两条分支(各一个用例)。 + +### M5 `get_screenshot`(设计 §7) + +**新增** `mcp/screen.go`;`protocol/commands.go` 加 `CommandScreenPreviewReq=247`、 +`TokenScreenPreviewRsp=248`;`cmd/main.go` `OnReceive` 加两个 case 转 `mcp.OnPacket`。 + +1. 请求表 `map[deviceID]*pendingPreview{reqID uint16; ch chan []byte}`, + `reqID` 用 `atomic.Uint32` 取低 16 位;**响应 reqID 不匹配直接丢弃**(对齐 MFC + `TakePreviewResponse`)。 +2. 能力门:缺 `protocol.ClientCapScreenPreview` → `-32005`。 +3. 8 字节请求体;`max_width` 钳制 `[64,1920]`、缺省/0 → 1024;`jpegQuality` 固定 80。 +4. 响应:`status != 0` → 1/2 `-32000`、3 `-32005`、4 `-32602`;`format=0` 直接返回 JPEG, + `format=3`(BGRX)→ 先 `image.RGBA` 再 `jpeg.Encode`;`bytes != w*h*4` 视为畸形包 `-32000`。 +5. 超时 8s,超时删表项,**不 CancelIO**(主连接 RPC,MFC 同款)。 +6. 返回 `content[]` 一项 `image`(base64 JPEG)+ `structuredContent{width,height,bytes,format,source}`。 + +**测试**:JPEG 魔数(`FF D8 FF`)、BGRX→JPEG 像素抽样、reqID 错包被丢弃、status 映射、 +超时。 + +### M6 `list_files`(设计 §5.3、§8.1) + +**新增** `mcp/filemgr.go`;`protocol` 加 `CommandListDrive=1`、`CommandListFiles=2`、 +`TokenDriveList=103`、`TokenFileList=104`、`TokenFileListError=171`(**加一个常量唯一性单测**: +新值不得与既有 `protocol` 常量重复,`103/104` 紧邻 `TOKEN_LOGIN=102`,值写错会吃主连接登录包)。 + +1. 主连接 `hub.SendToDevice(dev, []byte{CommandListDrive})`;等文件子连接:在 + `OnReceive` 顶部(终端 short-circuit 之后)先喂 `mcp.OnPacket(ctx, data)`,`mcp` 按 + `ctx.GetInfo().ClientID` 找到 pending 请求并**记住 ctx**(后续 `COMMAND_LIST_FILES` 要用它)。 +2. `TOKEN_DRIVE_LIST` 到达后**不关子连接**,同一 ctx 下发 `[CommandListFiles][path\0]`; + `TOKEN_FILE_LIST` / `TOKEN_FILE_LIST_ERROR` 才收尾。 +3. 解析按设计附录 A;`attr & 0x10` 判目录;文件名 `protocol.DecodeClientString(data, capability, "")`。 +4. 错误映射:`win32err ∈ {2,3}` → `-32009`;`5` → `-32010`;其它 → `-32000`。 + 老客户端无 `TOKEN_FILE_LIST_ERROR` → 超时;message 提示"路径可能不存在,先列目录确认"。 +5. 收尾:`COMMAND_BYE` → 500ms → `ctx.Close()`(`hub` 同款优雅关闭)。 + +**测试**:盘符/文件/错误三种黄金字节(照 MFC `ParseDriveList`/`ParseFileList` 的样例抓真实包, +存为 `testdata/*.bin`);`offset/limit` 语义;客户端中途断开 → `-32001` 且 pending 表被清。 + +### M7 `read_file`(设计 §5.4、§8.2-§8.3) + +**新增** `mcp/filev2.go`;`protocol` 加 `CommandSendFileV2=85`、`CommandFileCompleteV2=91`、 +`CmdDownFilesV2=94`;`cmd/main.go` 加两个 case。 + +1. 流程:列盘(复用 M6 的子连接)→ 同一子连接发 `[CmdDownFilesV2][targetDir\0][path\0][\0]` + → 服务端关掉文件子连接 → 客户端建 V2 子连接(`ConnAuth` 已钉 `ClientID`)→ + `COMMAND_SEND_FILE_V2 × N` → `COMMAND_FILE_COMPLETE_V2`。 +2. `targetDir := os.MkdirTemp("", "yama-mcp-read-*")`,`defer os.RemoveAll`。 +3. **大小门**:首个 chunk 的 `fileSize` 超 `ReadMax` → 立即中止、删目录、`-32602` + (不要先落盘再报错)。 +4. **路径校验**(安全,必须单测):`filepath.Clean(filepath.Join(targetDir, FromSlash(name)))` + + `filepath.Rel` 判越界;另拒 NUL / 换行;`name` 允许客户端回填为相对路径。 +5. SHA-256 校验(完成包 32 字节)→ 读窗口(负 `offset` 从尾部倒数)→ 编码判定 + (`utf8.Valid` 优先,失败回退 `simplifiedchinese.GBK`,`latin1` 逐字节)→ 返回 + `{path,size,bytes_read,truncated,encoding,text,sha256}`。 +6. 超时/断流:`-32001`;工具描述写明"超时可能是不支持 V2 的旧客户端"(设计 R3)。 + +**测试**:路径穿越用例集(`../x`、`..\\..\\x`、绝对路径、UNC、混合分隔符、`a/../../b`); +大小门;SHA 不符;GBK 文件;负 offset;`transferID` 不匹配的迟到 chunk 被丢弃。 + +### M8 校验工具与文档(设计 §10) + +1. `verify_tools.py --subset [token] [port] [--readonly]`: + 抓 Go 服务端 `tools/list`,与 `tools.json` 同名工具逐字段比 `description` / `inputSchema`; + **忽略 `outputSchema`**(Go 不做);名字集合必须恰好等于期望的 9(或 7); + 多一个少一个都失败。 +2. 同批更新:`deploy/yama-server.env.example` 加 `YAMA_MCP_TOKEN` / `YAMA_MCP_READONLY` / + `YAMA_MCP_TERM_IDLE` / `YAMA_MCP_MAX_CONCURRENCY` / `YAMA_MCP_READ_MAX`; + 设计文档状态改"已实施"。 + +--- + +## 4. 测试与验证 + +### 4.1 三档测试 + +| 档 | 跑什么 | 覆盖 | 何时跑 | +|---|---|---|---| +| 1 纯函数单测 | 清洗三段、哨兵、环形缓冲、解析器、路径校验、schema 校验、JSON-RPC | 全部逻辑分支 | 每次提交 | +| 2 假设备集成(进程内) | 真 `hub` + 假设备 ctx + `httptest` 的 `/mcp` | 九工具端到端、并发、取消、审计 | 每次提交 | +| 3 真客户端 smoke | `x64\Debug\ghost.exe`(§4.3)或 Linux ghost → 本机 Go 服务端 | 真实 PTY/文件/截屏链路 | 每个里程碑收尾 + 整体验收 | + +档 2 是主力:不依赖网络、可在 CI 跑,且能精确控制入站包的字节。 + +### 4.2 假设备 harness(`mcp/harness_test.go`) + +```go +h := hub.New() +sent := make(chan []byte, 16) // 出站包,带缓冲 channel 避免数据竞争 +h.SetSender(func(ctx *connection.Context, data []byte) error { + sent <- append([]byte(nil), data...); return nil +}) +cfg := logger.DefaultConfig(); cfg.Level = logger.LevelError +mcpSrv := mcp.New(mcpCfg, h, history, logger.New(cfg)) +unsubscribe := h.Subscribe(mcpSrv) // Subscribe 返回退订闭包(hub 没有 Unsubscribe 方法) +ts := httptest.NewServer(http.HandlerFunc(mcpSrv.Handle)) +// 假设备:拿到 sent 里的 COMMAND_SHELL 后,模拟回 TOKEN_TERMINAL_START 与输出: +mcpSrv.OnPacket(devCtx, append([]byte{protocol.TokenTerminalStart}, ...)) +h.PublishTerminalData(devID, []byte("hello\r\n__MCP_DONE_ab12cd__0\r\n")) +``` + +要点: +- 造设备:`h.Register(&hub.Device{ID:"dev", PeerIP:"10.0.0.1"}, devCtx)`; + `devCtx` 的 `Info.ClientID` 按子连接需要设置(模拟 `handleConnAuth` 的钉值)。 +- `sent` 用带缓冲 channel(上面写法),测试里 `select` 带超时地读,不 sleep。 +- 收尾:`defer unsubscribe()` + `defer mcpSrv.Close()`;再断言没有残留会话 + (`mcpSrv.SessionCount()==0`,为此在会话表上留一个只读访问器给测试用)。 + +### 4.3 真客户端 smoke(M0 已实测,2026-11-12) + +**结论:Windows 真客户端用 `x64\Debug\ghost.exe`,`TestRun.exe` 不可用。** + +- `test.cpp` 用 `MemoryDllRunner` 加载同目录的 `ServerDll.dll`(`client/test.cpp:448`); + 没有它时静默每 3 秒重试,Go 侧也没有这条内存 DLL 链路。 +- Release `TestRun.exe` 从非安装路径启动时 `RegisterStartup()` 返回 0 → `self_del()` + 自删(`client/test.cpp:323-334`);M0 第一次尝试确实删掉了 `release\TestRun.exe`, + 已用 Release 重建恢复(359936 → 425472 字节)。`-cmd=0` 绕不过安装流程。 +- Release `ghost.exe` 同样会走安装流程(dst = `%ProgramData%\Windows Ghost\WinGhost.exe`), + 因此本机测试统一用 Debug ghost:`RegisterStartup` 在 `_DEBUG` 下直接返回 1(`reg_startup.c:413`)。 + +**M0 实测记录**: + +- 服务端 `Bin\YamaGo_x64.exe -port 16543 -http-port 18090`(18080 被 python/wslrelay 占用), + `YAMA_DEVICES_FILE` 指向临时文件;默认签名模式 **TRIAL**(`https://web.just-do-it.icu:8080`)。 +- `x64\Debug\ghost.exe 127.0.0.1 16543` → 10 秒内设备上线: + `event=device.online computer=A6/default device_id=445427540237756328 os="Windows 11"`, + `devices.json` 写入 `first_seen/last_seen`,服务端无错误日志。 +- 清理:Debug ghost 的 `SetSelfStart` 会在 `HKCU\...\Run` 写一条哈希名,按运行前快照删除新增项; + 用户既有的 `Client Demo` 计划任务与 `C:\ProgramData\Client Demo\ClientDemo.exe` 未被改动。 +- 待办:trial 签名下客户端是否解锁屏幕/文件能力,要在 M5/M6 端到端确认 + (`YAMA_LICENSE_DISABLED=1` 的 NoOp 已知会被客户端拒绝)。 + +```powershell +cd C:\github\YAMA +.\build.ps1 -GoServer -Config Debug +$msb = "C:\Program Files\Microsoft Visual Studio\18\Insiders\MSBuild\Current\Bin\MSBuild.exe" +& $msb client\ghost_vs2015.vcxproj -p:Configuration=Debug -p:Platform=x64 -p:SolutionDir=C:/github/YAMA/ -m -v:m +$env:YAMA_MCP_TOKEN="<32hex>"; $env:YAMA_DEVICES_FILE="$env:TEMP\yama_m0\devices.json" +Start-Process .\Bin\YamaGo_x64.exe -ArgumentList '-port','16543','-http-port','18090' +Start-Process .\x64\Debug\ghost.exe -ArgumentList '127.0.0.1','16543' +curl -s -X POST localhost:18090/mcp -H "Authorization: Bearer $env:YAMA_MCP_TOKEN" ... +``` + +注意:Debug ghost 的 `Mprintf` 走 `TRACE`(`common/logger.h:379`),客户端侧没有日志文件, +验收以服务端 audit/日志为准。 + +### 4.4 与 MFC 的对照验收 + +同一批命令在两个后端各跑一遍,比对 `exit_code` 与清洗后的文本(不一致就是移植缺陷): + +``` +sc query AssemblyManager rem hello cmd /c echo abc +type C:\...\.env ping -n 30 127.0.0.1 for /L %i in (1,1,1000000) do @echo SPAM-%i +``` + +### 4.5 每个提交前必跑 + +```bash +cd server/go +gofmt -l . ; go vet ./... ; go test ./... ; go test -race ./mcp/... +go build ./cmd +``` + +MFC 侧测试(`%TEMP%\yama_step1_scripts\*`)本计划不改 C++ 代码,只在 M8 之后回归一次 +`verify_live_6555.py` 确认没被共享常量改动影响(本计划只加常量,理论上无影响)。 + +--- + +## 5. 整体验收(对齐设计 §11) + +- [ ] 9 个工具全部可调用;`tools/list` 响应 < 24 KB +- [ ] `terminal_exec` 连续 20 条命令零失败;超时后轮询取回完整输出 +- [ ] 浏览器开着终端时 `terminal_exec` → `-32003`,人的会话不受影响 +- [ ] `read_file` 读 `.env` 字节级一致,SHA-256 与远端 `sha256sum` 相同 +- [ ] `get_screenshot` Windows / Linux 各一张,Linux 走 BGRX→JPEG +- [ ] 审计每次 `mcp.tool.call` 一条,`device/tool/code/ms` 齐全 +- [ ] `verify_tools.py --subset` 通过(9 个 / 只读 7 个两种模式) +- [ ] `go test -race ./mcp/...` 无数据竞争 +- [ ] `hub` 零改动(`git diff --stat server/go/hub` 为空) + +--- + +## 6. 风险(在设计 R1-R8 之上新增) + +| # | 风险 | 影响 | 处置 | +|---:|---|---|---| +| R9 | `OnTerminalData` 在 TCP 读循环上阻塞 | 整个设备通道卡死(浏览器画面/终端一起停) | 只做内存追加与唤醒;缓冲满丢最旧;禁止在回调里调用 `hub` 的会加锁方法 | +| R10 | 文件子连接 ctx 生命周期 | 客户端中途断开 → 后续发送到已关闭 ctx / pending 表泄漏 | pending 表带超时与 `OnDisconnect` 清理;发送失败即失败收尾 | +| R11 | `103/104` 常量与主连接 token 相邻 | 值写错会把登录包当文件列表(反之亦然) | 常量唯一性单测 + 解析前校验最小长度 | +| R12 | Windows 路径与 `filepath.Rel` | 路径穿越(被控端写主控任意位置) | 单测覆盖 `..`/绝对路径/UNC/混合分隔符;拒 NUL 与换行 | +| R13 | 客户端断开(`r.Context()`)后锁未释放 | 设备永久 `-32003` | `defer` 释放;单测用 cancel 验证 | +| R14 | 单测 goroutine 泄漏 | `-race` 偶发失败 | `Close()` 幂等;测试里 `defer Close()` | +| R15 | 真机 smoke 用 Debug ghost,与 Release 客户端有差异 | 安装/许可行为可能在 Release 上不同,本地验收未覆盖 | M0 已确认 Debug ghost 可上线;M5/M6 用 trial 签名验证屏幕/文件能力;交付说明写明该差异 | + +--- + +## 7. 工时估算 + +| 里程碑 | 编码 | 测试 | 小计 | +|---|---:|---:|---:| +| M1 | 3h | 3h | 6h | +| M2 | 6h | 4h | 10h | +| M3 | 2h | 2h | 4h | +| M4a | 4h | 2h | 6h | +| M4b | 5h | 3h | 8h | +| M4c | 1h | 1h | 2h | +| M5 | 4h | 2h | 6h | +| M6 | 5h | 3h | 8h | +| M7 | 6h | 4h | 10h | +| M8 | 2h | 1h | 3h | +| 整体联调 + 真机验收 | — | — | 6h(含在 §5) | +| **合计** | **38h** | **25h** | **≈63h ≈ 8 人日** | + +--- + +## 附录 A:`protocol/commands.go` 新增常量 + +| 常量 | 值 | 方向 | 里程碑 | +|---|---:|---|---| +| `CommandListDrive` | 1 | S→C 主连接 | M6 | +| `CommandListFiles` | 2 | S→C 文件子连接 | M6 | +| `CommandSendFileV2` | 85 | C→S V2 子连接 | M7 | +| `CommandFileCompleteV2` | 91 | C→S V2 子连接 | M7 | +| `CmdDownFilesV2` | 94 | S→C 文件子连接 | M7 | +| `TokenDriveList` | 103 | C→S 文件子连接 | M6 | +| `TokenFileList` | 104 | C→S 文件子连接 | M6 | +| `TokenFileListError` | 171 | C→S 文件子连接 | M6 | +| `CommandScreenPreviewReq` | 247 | S→C 主连接 | M5 | +| `TokenScreenPreviewRsp` | 248 | C→S 主连接 | M5 | + +## 附录 B:环境变量 + +| 变量 | 默认 | 说明 | 引入里程碑 | +|---|---|---|---| +| `YAMA_MCP_TOKEN` | 空(端点不注册) | 32 位十六进制静态令牌 | M1 | +| `YAMA_MCP_READONLY` | 0 | 隐藏 `terminal_exec` / `terminal_close` | M1 | +| `YAMA_MCP_TERM_IDLE` | 180 | 终端会话空闲回收秒数 | M4c | +| `YAMA_MCP_MAX_CONCURRENCY` | 16 | 全局并发上限 | M3 | +| `YAMA_MCP_READ_MAX` | 2097152 | `read_file` 大小门(字节) | M7 | + +## 附录 C:提交前自检清单(每个里程碑) + +1. `gofmt -l .` 无输出;`go vet ./...` 干净。 +2. `go test ./...` 与 `go test -race ./mcp/...` 全绿。 +3. 新增的每个错误码都有触发它的单测(错误码不是装饰)。 +4. 新增的每条审计事件都能在临时审计文件里被 `get_audit_log` 查到。 +5. 提交标题用 `Feature(Go):` / `Fix(Go):`,正文说明"为什么",trailer 用当前会话模型名。 +6. 未推送前发现问题用 `--amend`/squash,不堆补丁提交。