Add a third mode to verify_tools.py that validates the Go server end to end: it fetches /mcp tools/list and requires the name set to equal the nine implemented tools exactly (seven in readonly mode), compares description / inputSchema / outputSchema field by field against mcp/tools.json, and also checks the published order. Unlike --live, extra or missing tools are failures, not notes. The field-comparison loop is factored into report_field_diffs so --offline / --live and --subset share one comparison, diff printer and FIELDS tuple. Document and deploy the endpoint: the systemd env example gains YAMA_MCP_TOKEN / READONLY / TERM_IDLE / MAX_CONCURRENCY / READ_MAX, the design doc moves to implemented and its section 10 now matches the code (embedded tools_minimal.json, the three packet dispatch groups). The tools README explains gen_go_tools.py --check and --subset. Verified against a freshly built debug Go server on 16543/18090: read-write mode passes with 9 tools, YAMA_MCP_READONLY=1 passes with 7, and both mismatch directions (extra tools, missing tools) fail with exit 1. gen_go_tools.py --check stays clean; no Go code changed. Co-Authored-By: deepseek-flash
46 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 是下载后的窗口裁剪,绕不过这个门。
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 零改动。