# Go 服务端 MCP 最小工具集设计 > 版本:v1.0(定稿) 状态:**已实施(M0–M8 全部落地,2026-11-12)** 日期:2026-11-12 > > 实施计划与各里程碑验收口径见 `Mcp_Go_Minimal_Implementation_Plan.md`。 > > 前置文档:`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 逐个定义 本节只用于阅读;**参数名与返回字段的唯一契约是 `mcp/tools.json` 的 `inputSchema` / `outputSchema`**(M1 起 `tools/list` 原样返回这些定义)。Go 取不到的字段省略,不伪造。 #### `list_hosts` ```jsonc // input(全部可选) { "client_type": "EXE", "group": "asm", "include_offline": false, "ip": "10.", "limit": 100, "name": "ASM-", "offset": 0, "online": true, "os": "Windows", "query": "asm" } // output.structuredContent { "hosts": [ /* ... */ ], "total": 7, "totalAll": 9, "limit": 100, "offset": 0, "hasMore": false } ``` `client_type/group/ip/os` 为大小写不敏感子串过滤;`name` 只匹配计算机名,`query` 同时匹配 计算机名、备注与 IP;`online=true`(默认)只列在线,`false` 只列历史中存在但当前离线的; `include_offline=true` 时再合并 `devicehistory.Store.Offline(online)`。`total` 是过滤后命中数, `totalAll` 是过滤前总数,`hasMore` 表示同一条件下还有下一页。 `hosts[]` 的字段按 `outputSchema`:`id/name/group/version/clientType/os/ip/rtt/activeWindow/ screen/online/last_seen`,以及 hub 或历史记录里确有的 `location/install_time`;两个服务端都 没有 `authStatus/tls/remark`,不输出。离线历史条目不存 `clientType`,也没有 `rtt/activeWindow`。 #### `get_host_detail` ```jsonc { "id": "7888521104752806905" } // 或 { "ids": ["…", "…"] }(≤50 台,批量) ``` 单台返回 `{ host: {...} }`;批量返回 `{ tool, total, succeeded, failed, skipped, results[] }`。 `host.capabilities` 由 `protocol.SupportsCap` 逐位解出,字段名与 schema 一致: `screenPreview / screenRegion / windowInfo / fileTransferV2 / c2cPaths / registry / remoteControl / platform`。 注意**不要把 `v2` 放进 capabilities**:`CLIENT_CAP_V2` 在 `DefaultCaps()` 里全平台恒真 (`common/commands.h:1289`),列出来只会误导模型。 #### `get_server_status` 无参。返回字段按 `outputSchema`:`version / uptime_sec / hosts / sessions / port / bind / switches / blocked_auth_ips / exe_build_time / app_name`。Go v1 只填能如实取到的: `version`(buildinfo)、`uptime_sec`、`hosts`(在线/历史计数)、`sessions`(MCP 活动调用, M3 起)、`port`、`bind`;其余属 MFC 专有,直接不给(schema 的 `required` 为空)。 `version` 取 `-ldflags -X` 注入的 `buildinfo.Version`——**Go 侧目前没有版本变量** (`cmd/main.go` 里查不到),需要新增 `buildinfo` 包并在 `Makefile` / `build.ps1` 里注入; 拿不到时返回空串,不要伪造。`commit` 只用于日志与排障,不塞进 schema 未定义的返回字段。 #### `get_audit_log` ```jsonc { "keyword": "terminal", "type": "mcp", "limit": 100, "offset": 0 } ``` 复用 `web/audit_query.go` 的查询器(M2 抽成 `auditquery`),返回 `{ entries, total, totalAll, limit, offset, hasMore }`。**没有 `since`**:MFC 的 schema 里就没有。 #### `get_screenshot` ```jsonc { "id": "...", "max_width": 1024 } // output: content[] 里一项 image(mimeType=image/jpeg, base64 data) // structuredContent: { image: { mimeType, width, height, bytes }, // capture: { mode, x, y, width, height, scale, native } } ``` `max_width` 钳制到 `[64,1920]`;缺省/0 时 Go v1 固定 1024(没有 MFC 的 RTT 自适应档位)。 `mode=region/window/monitor` 与 `hwnd/x/y/width/height` 需要 `CLIENT_CAP_SCREEN_REGION` 扩展, M5 之前传任一参数都返回 `-32005` 并在 message 里点名。细节见 §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", "stdout": "...", "done": true, "exit_code": 0, "is_pty": true, "reused": false, "truncated": false, "dropped_bytes": 0, "elapsed_ms": 412 } ``` 超时未完成时 `done=false`、无 `exit_code`;`stdout` 是已产生的部分输出,**会话保留**, 用同一 `session_id` 轮询。`max_output_bytes`(1024..1048576,默认 65536)按行截断并置 `truncated`,剩余内容下次轮询取。 #### `terminal_close` ```jsonc { "id": "...", "session_id": "s-3f2a" } // 幂等:会话不存在也返回成功 ``` #### `list_files` ```jsonc { "id": "...", "path": "C:\\ProgramData\\AssemblyManager", "limit": 100, "offset": 0 } // output { "files": [ { "name": "settings.ini", "isDir": false, "size": 1204, "mtime": 1699999999 } ], "total": 42, "totalAll": 42, "limit": 100, "offset": 0, "hasMore": false } ``` `path` 为空时返回盘符列表 `{ drives: [{ drive, typeName, fileSystem, totalMB, freeMB }] }`。 批量传 `ids` 时结果按台汇总在 `results` 里。注意返回数组字段是 `files`,不是 `entries`。 #### `read_file` ```jsonc { "id": "...", "path": "C:\\ProgramData\\AssemblyManager\\.env", "offset": 0, "limit": 2000, "max_bytes": 262144, "encoding": "auto" } // output { "path": "...", "size": 4096, "encoding": "utf-8", "eol": "lf", "lines_total": 120, "offset": 0, "lines_returned": 120, "text": "IR_ENDPOINT=...", "sha256": "...", "truncated": false } ``` **行语义**:`offset` 是起始行(0 基,负数表示末尾 N 行),`limit` 是行数(1..200000,默认 2000),`max_bytes` 是本次返回文本的字节上限(1024..2097152,默认 262144=256KB), 超出按行截断并置 `truncated`。`encoding`:`auto`(BOM → UTF-8 合法性 → GBK 回退)/ `utf-8` / `gbk` / `gb18030` / `latin1`;`eol` 为 `crlf/lf/cr/mixed/none`。 **整文件上限 2 MiB**(`YAMA_MCP_READ_MAX`):V2 下载没有区间参数,只能整文件拉,超过就拒绝 (`-32602`)。`offset`/`limit` 是下载后的窗口裁剪,绕不过这个门。 ### 3.3 文本块(`content[].text`) `structuredContent` 是权威数据,但部分 MCP 客户端只把 `content[].text` 交给模型, `structuredContent` 不会出现在模型上下文里。因此列表类工具的文本块不能只有「共 N 台」 这样的汇总——主机 64 位 id 是 `read_file`、`get_host_detail`、`terminal_exec` 等后续调用 的寻址键,模型拿不到就等于工具不可用。 | 工具 | 汇总行之后 | |---|---| | `list_hosts` | 表头 `id name ip group os online clientType last_seen`,随后每台一行 | | `get_host_detail` | 单台:主机 JSON(compact);批量:`id ok detail`,成功行是主机 JSON,失败行是错误信息 | | `list_files` | 盘符 `drive typeName fileSystem totalMB freeMB`;目录 `name isDir size mtime` | | `get_audit_log` | `time type msg`,`msg` 是去掉信封字段后的 compact JSON | 列用制表符分隔,首列一定是后续调用的寻址键(主机 id / 文件名)。单元格内的制表符与换行 替换成空格,精确值以 `structuredContent` 为准;空值显示 `-`。分页只渲染当前页,不会把 全表塞进文本块。 MFC 端不需要同样的改动:`McpInternal.cpp` 的 `BuildResult` 会把整个 `structuredContent` 作为**第二个** `type:"text"` 项追加到 `content`(除非 builder 用 `SetStructuredTextPayload` 指定了更小的载荷)。实测线上 `list_hosts` / `get_audit_log` 的 `content[1]` 已是完整 JSON(含主机 id),文本型客户端本来就能拿到。Go 的 `newToolResult` 只写一个 text 项,所以把行放进第一项。 --- ## 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()` 里被**所有现代客户端无条件声明**,拿它做真门等于没门。Go 侧保留 `SupportsCap(…, CLIENT_CAP_V2)` 检查的唯一作用,是让"能力串为空"的极老客户端直接 得到 `-32005`,而不是等到 94 号命令静默超时(见下一条)。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` 钳制到 `[64, 1920]`,缺省/0 时 Go v1 固定 1024;`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` 与本次返回条数分开:客户端一次返回全部,服务端做 `limit`/`offset` 窗口裁剪并在 `structuredContent` 里如实给出 `total`/`totalAll`/`hasMore`(与 MFC 的分页语义一致)。 ### 8.2 `read_file` 见 §5.4。落盘完成后: 1. 校验 SHA-256(`COMMAND_FILE_COMPLETE_V2` 里带的 32 字节)。 2. 按 `encoding` 解码全文(`auto`:BOM → 严格 UTF-8 → GBK 回退;`gb18030`/`latin1` 显式指定)。 3. 按行切分,按 `offset`(0 基,负数=末尾 N 行)/`limit`/`max_bytes` 取窗口;`max_bytes` 按行边界截断,避免切坏 UTF-8/GBK 多字节字符。 4. 返回 `text` + `size` + `encoding` + `eol` + `lines_total` + `offset` + `lines_returned` + `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 # //go:embed tools_minimal.json;只读过滤、工具表 tools_minimal.json # gen_go_tools.py 从 mcp/tools.json 抽取的 9 个工具(勿手改) tools_local.go # list_hosts / get_host_detail / get_server_status / get_audit_log tools_term.go # terminal_exec / terminal_close errors.go # 错误码 + JSON-RPC 错误映射 audit.go # mcp.tool.call 审计 lock.go # 设备锁 + 全局信号量 session.go # 终端会话表、空闲回收 term.go # 哨兵、环形缓冲 clean.go # 终端输出清洗(逐字节移植 MFC 的 CleanTerminalOutput) 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`)按到达的连接分成三组,未命中在途请求就丢弃: - `mcp.Server.OnPacket`:`TokenScreenPreviewRsp(248)`(主连接上的截图 RPC 回包) - `mcp.Server.OnFilePacket`:`TokenDriveList(103)` / `TokenFileList(104)` / `TokenFileListError(171)`(文件管理器子连接) - `mcp.Server.OnTransferPacket`:`CommandSendFileV2(85)` / `CommandFileCompleteV2(91)` (独立数据子连接或 POSIX 的文件管理器子连接)与 `TokenDownloadError(173)` **为什么 embed 一份生成的 `tools_minimal.json`、而不是手写或直接引用 `mcp/tools.json`**: `mcp/tools.json` 在仓库根,`//go:embed` 不能引用父目录;手写 9 个 schema 又无法证明 与 MFC 的 JSON 一致。所以由 `tools/mcp_tools/gen_go_tools.py` 从 `mcp/tools.json` 原样 抽取(保持顺序,只留 name/description/inputSchema/outputSchema)生成 go 包内的副本并 嵌入二进制——改工具定义必须改 `mcp/tools.json` 再重新生成,不存在两份手写文字漂移的余地。 两道防漂移检查:`gen_go_tools.py --check`(生成副本是否为最新)与 `verify_tools.py --subset`(线上 `tools/list` 是否与 `mcp/tools.json` 同名工具逐字段 一致、名字集合是否恰好 9 个/只读 7 个)。 --- ## 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` 冲突 | **改** 为按平台分行尾 | | 23 | §3.2 的输入/输出形状是自造结构,与 `mcp/tools.json` 不一致(`online_only`、`entries`、`since`、`bytes_read`、`output`、capabilities 下划线命名、`max_width` 1600/[320,3840]) | **改**。已确认 `mcp/tools.json` 是唯一契约,§3.2 按 `inputSchema`/`outputSchema` 重写:`list_files` 返回 `files`、`read_file` 为行语义、审计无 `since`、capabilities 用 camelCase、`max_width` 钳制 `[64,1920]` 默认 1024;M1 起 `tools/list` 原样回显该 schema | **结论**:以上 23 处已全部修入正文,无遗留。v1 对 `server/go` 的改动是 **新增 `mcp` 包 + `web/server.go` 一行路由 + `web.Server` 一个 `WithMCP` + `cmd/main.go` 六个 case + `protocol` 六个常量 + 两个版本变量**, `hub` 零改动。