MCP clients that surface only content[].text saw just count summaries from list_hosts and get_audit_log; the 64-bit host id lived only in structuredContent. Without the id, read_file, get_host_detail and terminal_exec cannot be addressed, so the tools were unusable from those clients. Append a tab-separated table after the summary for every list-shaped local tool: list_hosts (id first, then name/ip/group/os/online/clientType/ last_seen), get_audit_log (time/type/msg), list_files (drives and directory entries) and get_host_detail (compact host JSON; id/ok/detail rows for a batch call). Only the returned page is rendered, cells are flattened to one line, and the truncation note stays on its own line before the table. structuredContent is unchanged and remains the authoritative copy. Tests cover row contents, paging, escaping and truncation ordering; a live run against a Debug client confirmed the id is now visible in text. The MFC server needs no equivalent change: BuildResult already appends the full structuredContent as a second text item, so text-only clients there already receive host ids. Go's envelope emits a single text item, which is why the rows go into it. Co-Authored-By: deepseek-flash
861 lines
48 KiB
Markdown
861 lines
48 KiB
Markdown
# 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=<username>`)可区分。
|
||
- 不做失败计数封禁:令牌是 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=<name> device=<id|-> ok=<bool> code=<err|0> ms=<duration>
|
||
args=<截断到 512 字节的摘要> result=<ok 时的体积摘要 / 失败时的 message>
|
||
```
|
||
|
||
`args` 里的敏感值(`command` 全文可能含密码)**不入审计**——只记命令首词与长度,
|
||
与 MFC 的做法一致(MFC 审计只记 `host <id> <tool>`)。完整命令进 `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_<id>__$?"\n` | `__MCP_DONE_<id>__<n>` |
|
||
| ConPTY(新 Windows) | `cmd\r\n` + `echo __MCP_DONE_<id>__%errorlevel%\r\n` | 同上 |
|
||
|
||
为什么要分两行:`rem` / `cmd` / `exit` / `if` / `for` 这类"吞行"命令会把同一行后面的
|
||
内容一起吞掉(MFC 的 P1 教训)。分两行后哨兵独立执行,退出码才可信。
|
||
|
||
`<id>` 用 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` 零改动。
|