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
48 KiB
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. 结论摘要
- v1 交付 9 个工具,全部命名、参数、错误码与 MFC 对齐,同一句提示词在两个后端都能跑通:
list_hosts/get_host_detail/get_server_status/get_audit_log/get_screenshot/terminal_exec/terminal_close/list_files/read_file。 - 四条设备通道,三种是既有基础设施:终端(
hub已有,只需加哨兵与输出缓冲)、 主连接 RPC(hub.SendToDevice)、文件管理器子连接(TOKEN_CONN_AUTH已把 clientID 钉在 ctx 上,按 clientID 路由即可,不需要 MFC 那套 pending + CancelIO)。 只有 V2 流式子连接的接收端是全新的。 get_screenshot走主连接 RPC(COMMAND_SCREEN_PREVIEW_REQ),不碰屏幕流。 屏幕流是持续推的 H.264(首帧裸 BGRA),取一帧就得建屏幕子连接、占住每设备唯一的 屏幕槽位、用完再拆——代价远大于收益。预览 RPC 是主连接上的一次性请求响应, 客户端自己抓屏编码回 JPEG(Linux 客户端回 BGRX,服务端编码)。不占任何槽位。- 终端槽位是 Go 独有的硬约束:
hub.go:86写明 at most one web terminal per device。 v1 不做抢占——浏览器开着终端时 MCP 返回-32003,空闲 3 分钟自动释放。 这是安全默认,代价是"人在用终端时 AI 用不了",写进工具描述让模型自己换路。 - MCP 端点零新增端口:挂在现有 Web 服务的
/mcp(web/server.go:126的 mux 里加一行), 无状态 JSON-RPC,不引入Mcp-Session-Id。鉴权用单一静态令牌(YAMA_MCP_TOKEN), 映射到固定 principalmcp(role=admin)。 - 明确不做:
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 两条可直接复用的结论
- 终端是"跑命令"的唯一入口。MFC 实测 186 次调用里 109 次是
terminal_exec(58.6%),且 59% 的命令本质是"读"。Go 没有必要先做一堆专用只读工具, 把terminal_exec做扎实就是最高性价比。 - 但
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
// 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
{ "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
{ "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
{ "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
// 执行
{ "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
{ "id": "...", "session_id": "s-3f2a" } // 幂等:会话不存在也返回成功
list_files
{ "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
{ "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 里加一行:
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 分派。不走子连接,不占任何槽位。
需要一个请求表:
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 会话对象
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):
- 剥回显:PTY 会把输入整行回显。删掉命令行本身与哨兵行。
- 剥 ANSI:
\x1b[...m、\x1b[?25h/l等 CSI/OSC 序列。 - 剥哨兵:把哨兵文本及其后的退出码切掉,
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 请求 / 响应
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 用标准库转:
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。落盘完成后:
- 校验 SHA-256(
COMMAND_FILE_COMPLETE_V2里带的 32 字节)。 - 按
encoding解码全文(auto:BOM → 严格 UTF-8 → GBK 回退;gb18030/latin1显式指定)。 - 按行切分,按
offset(0 基,负数=末尾 N 行)/limit/max_bytes取窗口;max_bytes按行边界截断,避免切坏 UTF-8/GBK 多字节字符。 - 返回
text+size+encoding+eol+lines_total+offset+lines_returned+truncated+sha256。 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 由客户端提供。必须:
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只 importhub/protocol/devicehistory/logger,不 importweb。- 构造顺序:
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 零改动。