Files
SimpleRemoter/docs/Mcp_Go_Minimal_Design.md
T
yuanyuanxianganddeepseek-flash 5f124fcb3a Docs(mcp): add Go minimal MCP design and implementation plan
Add the v1.0 design for the Go-side minimal MCP server (nine read-only
tools over hub, audit log, terminal and file channels) and the staged
plan that turns it into eight commits.

Record the five decisions settled before construction: extract the audit
query scanner into server/go/auditquery, inject version and commit via a
buildinfo package plus go-winres, treat mcp/tools.json as the only tool
schema contract, verify against a real client, and expose seven tools in
readonly mode.

Add the M0 findings: TestRun.exe cannot log in, because it needs
ServerDll.dll loaded through MemoryDllRunner and the release build deletes
itself when started outside its install path. A Debug ghost.exe came
online against a local Go server in trial signer mode within ten seconds.

Co-Authored-By: deepseek-flash
2026-11-12 20:17:54 +01:00

42 KiB
Raw Blame History

Go 服务端 MCP 最小工具集设计

版本:v1.0(定稿) 状态:已自审(22 项问题全部修入正文),可施工 日期:2026-11-12

前置文档:Mcp_Tool_Optimization_Plan.md(MFC 侧工具优化,已全部落地)、 Mcp_FileTransfer_Design.md(V2 文件传输协议与无头接收端)、 Mcp_Design.md(MCP 协议/错误码基线)、FILE_TRANSFER_V2.md(V2 协议清单)。

适用范围:server/go 新增 MCP 端点与 9 个工具。不改客户端——所有用到的 命令与令牌均为 common/commands.h 既有定义,客户端已实现。

本文与 MFC 侧的差异只有一个来源:Go 服务端的协议实现面比 MFC 窄。MFC 有 54 个 工具,是因为它把 20 多条客户端命令都接进了服务端;Go 目前只接了 4 条。所以这里的 "最小"不是"先做简单的",而是"按 Go 已具备的协议能力面裁剪,剩下的按需补齐"。


0. 结论摘要

  1. v1 交付 9 个工具,全部命名、参数、错误码与 MFC 对齐,同一句提示词在两个后端都能跑通: list_hosts / get_host_detail / get_server_status / get_audit_log / get_screenshot / terminal_exec / terminal_close / list_files / read_file。
  2. 四条设备通道,三种是既有基础设施:终端(hub 已有,只需加哨兵与输出缓冲)、 主连接 RPC(hub.SendToDevice)、文件管理器子连接(TOKEN_CONN_AUTH 已把 clientID 钉在 ctx 上,按 clientID 路由即可,不需要 MFC 那套 pending + CancelIO)。 只有 V2 流式子连接的接收端是全新的。
  3. get_screenshot 走主连接 RPC(COMMAND_SCREEN_PREVIEW_REQ),不碰屏幕流。 屏幕流是持续推的 H.264(首帧裸 BGRA),取一帧就得建屏幕子连接、占住每设备唯一的 屏幕槽位、用完再拆——代价远大于收益。预览 RPC 是主连接上的一次性请求响应, 客户端自己抓屏编码回 JPEG(Linux 客户端回 BGRX,服务端编码)。不占任何槽位。
  4. 终端槽位是 Go 独有的硬约束:hub.go:86 写明 at most one web terminal per device。 v1 不做抢占——浏览器开着终端时 MCP 返回 -32003,空闲 3 分钟自动释放。 这是安全默认,代价是"人在用终端时 AI 用不了",写进工具描述让模型自己换路。
  5. MCP 端点零新增端口:挂在现有 Web 服务的 /mcp(web/server.go:126 的 mux 里加一行), 无状态 JSON-RPC,不引入 Mcp-Session-Id。鉴权用单一静态令牌(YAMA_MCP_TOKEN), 映射到固定 principal mcp(role=admin)。
  6. 明确不做:remote_*、chat_*、host_*、进程/服务/注册表/窗口枚举、文件写操作、 exec_command(白名单一次性执行,被 terminal_exec 覆盖)、outputSchema。

1. 范围

1.1 做

层 内容
端点 POST /mcp(JSON-RPC 2.0 / MCP 2025-06-18),initialize / notifications/initialized / ping / tools/list / tools/call
鉴权 Authorization: Bearer $YAMA_MCP_TOKEN,常量时间比较
工具 9 个(见 §3)
审计 每次调用一条 mcp.tool.call 记录,进既有审计通道
设施 每设备单请求互斥、终端会话表、主连接 RPC 请求表、V2 接收端

1.2 不做

不做 理由
remote_open / remote_keyboard / remote_mouse 等 Go 有屏幕流但没有"注入结果回执",做出来无法验证;且属高风险写操作,先不开放给模型
chat_* Go 无 COMMAND_CHAT 实现
host_inspect / host_control_* / 进程/服务/注册表/窗口枚举 Go 协议层完全没有这些命令(protocol/commands.go 只声明了 4 条命令族)
文件写(delete_path / move_path / upload_file / create_folder) V2 上传方向需要服务端作 sender,工作量与本期的接收端不对称;先只读
download_file 接收端与 read_file 完全共用,v1.1 加约 20 行即可(差别只是落盘后不删)。v1 先只做"读",避免多一个往主控磁盘写文件的入口
exec_command(白名单一次性执行) terminal_exec 已覆盖同一场景且无白名单摩擦(MFC 实测 -32007 全是白名单误拒)
outputSchema MFC 实测 outputSchema 占 tools/list 的 49,320 / 136,692 字节。9 个工具没必要背这个体积
多用户令牌 / 按分组授权 v1 单 principal;多用户留到 Go 侧真正多租户部署时(见 §12 R6)

2. 基线

2.1 MFC 侧已交付(可直接对标的参照)

mcp/tools.json 当前 toolCount=54(优化前 63),默认配置下可见 21 个。 Mcp_Tool_Optimization_Plan.md 的八项已全部落地,其中三项对 Go 有直接约束力:

MFC 改动 对 Go 的约束
terminal_exec 的 session_id 可变可选、无会话时隐式创建 Go 不设 terminal_open,terminal_exec 隐式建会话
超时保留会话、返回部分输出、session_id 轮询续取 Go 同款语义,见 §6.6
read_file 复用 download_file 的 V2 接收端 Go 的 read_file = 下载到临时目录 + 读 + 删,两者共用一份接收端

2.2 Go 侧现状

protocol/commands.go:105-140 声明的命令常量里,真正有发送点的只有三处:

能力 状态 位置
屏幕查看 / 控制 / 剪贴板 已实现(H.264 流 + 鼠标键盘) cmd/main.go handleScreenFrame
PTY 终端(每设备单会话) 已实现,仅浏览器流式转发 hub.go:756 / hub.go:983 / cmd/main.go:101-109
卸载被控端 已实现 web/ws_handlers.go:1139
设备 / 用户 / 分组 / 审计 已实现 hub.ListDevices / devicehistory.Offline / web/audit_query.go
子连接鉴权(clientID 绑定) 已实现 cmd/main.go handleConnAuth
文件管理器(列盘/列目录/读/写) 完全没有 —
一次性命令执行 完全没有 —
屏幕预览 RPC 完全没有 —

2.3 两条可直接复用的结论

  1. 终端是"跑命令"的唯一入口。MFC 实测 186 次调用里 109 次是 terminal_exec (58.6%),且 59% 的命令本质是"读"。Go 没有必要先做一堆专用只读工具, 把 terminal_exec 做扎实就是最高性价比。
  2. 但 read_file 不能省。MFC 的优化结论是"read_file 是唯一真正的功能缺口"—— 终端读文件会被 PTY 回显、ANSI 转义、ConPTY 重绘污染,.env 这类文件读出来是脏的。 Go 既然要上文件管理器,就一次做对。

3. 工具集

3.1 清单

# 工具 通道 只读 依赖能力位
1 list_hosts 本机 ✅ —
2 get_host_detail 本机 ✅ —
3 get_server_status 本机 ✅ —
4 get_audit_log 本机 ✅ —
5 get_screenshot 主连接 RPC ✅ CLIENT_CAP_SCREEN_PREVIEW
6 terminal_exec 终端子连接 ❌ —
7 terminal_close 终端子连接 ❌ —
8 list_files 文件管理器子连接 ✅ —
9 read_file V2 流式子连接 ✅ —(见 §5.4 的说明)

YAMA_MCP_READONLY=1 时只暴露 1/2/3/4/5/8/9 七个(6/7 隐藏)。

3.2 逐个定义

list_hosts

// input
{ "group": "asm", "name": "ASM-", "online_only": true, "limit": 50, "offset": 0 }
// output.structuredContent
{ "total": 7, "returned": 7, "hosts": [ /* hub.DeviceInfo */ ] }

hub.DeviceInfo 已含 id/name/group/version/capability/os/rtt/activeWindow/ip/peer_ip/screen/connected_at/online/last_seen, 直接序列化,不裁剪字段——模型排障需要的正是这些。online_only=false 时合并 devicehistory.Store.Offline(online) 的历史条目。

group 与 name 都是子串匹配(与 MFC list_hosts 一致),name 大小写不敏感。

get_host_detail

{ "id": "7888521104752806905" }

返回 DeviceInfo + capabilities: { utf8, screen_preview, screen_region, window_info }(由 protocol.SupportsCap 逐位解出)。这是 MFC 优化里被验证过的高价值字段: 模型不用靠 -32005 试错就知道这台机器能不能截图。

注意不要把 v2 放进 capabilities:CLIENT_CAP_V2 在 DefaultCaps() 里全平台恒真 (common/commands.h:1289),列出来只会误导模型。

get_server_status

{} // 无参

返回 { version, commit, uptime_s, devices_online, devices_offline_known, mcp: { readonly, tools } }。 version/commit 取 -ldflags -X 注入的构建变量——Go 侧目前没有这两个变量 (cmd/main.go 里查不到版本常量),需要新增两行 var version, commit string 并在 Makefile 里注入;拿不到时返回空串,不要伪造。

get_audit_log

{ "keyword": "terminal", "type": "mcp", "since": "2026-11-12T00:00:00Z", "limit": 100, "offset": 0 }

复用 web/audit_query.go 的查询器,返回 { total, returned, records[] }。

get_screenshot

{ "id": "...", "max_width": 1600 }
// output: content[] 里一项 image(mimeType=image/jpeg, base64 data)
//         structuredContent: { width, height, bytes, format, source: "preview" }

细节见 §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", "output": "...", "exit_code": 0, "done": true,
  "offset": 1843, "truncated": false, "is_pty": true, "reused": false }

超时未完成时 done=false、无 exit_code、output 是已产生的部分输出,会话保留。

terminal_close

{ "session_id": "s-3f2a" }  // 幂等:会话不存在也返回成功

list_files

{ "id": "...", "path": "C:\\ProgramData\\AssemblyManager", "limit": 200 }
// output
{ "path": "...", "total": 42, "returned": 42, "entries": [
   { "name": "settings.ini", "isDir": false, "size": 1204, "mtime": 1699999999 } ] }

path 为空或 "drives" 时返回盘符列表 { drives: [{ drive, typeName, fileSystem, totalMB, freeMB }] }。

read_file

{ "id": "...", "path": "C:\\ProgramData\\AssemblyManager\\.env",
  "offset": 0, "limit": 262144, "encoding": "auto" }
// output
{ "path": "...", "size": 4096, "bytes_read": 4096, "truncated": false,
  "encoding": "utf-8", "text": "IR_ENDPOINT=...", "sha256": "..." }

encoding:auto(默认,先 UTF-8 严格解码,失败回退 GBK)/ utf-8 / gbk / latin1。 offset 支持负数表示"从尾部倒数 N 字节"(MFC 同款,读日志尾部最常用)。

上限 2 MiB(YAMA_MCP_READ_MAX):V2 下载没有区间参数,只能整文件拉,超过就拒绝。 offset/limit 是下载后的窗口裁剪,绕不过这个门。


4. 端点

4.1 POST /mcp

在 web/server.go:126 起的 mux 里加一行:

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() 里被所有平台无条件声明,拿它做门等于没门。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):

  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 请求 / 响应

struct ScreenPreviewReq {       // 8 字节
    uint8_t  cmd;               // 247
    uint16_t reqId;
    uint16_t maxWidth;
    uint8_t  jpegQuality;       // 1..100
    uint16_t reserved;
};

struct ScreenPreviewRspHeader { // 16 字节
    uint8_t  token;             // 248
    uint16_t reqId;
    uint8_t  status;            // 0=OK 1=抓屏失败 2=编码失败 3=不支持 4=目标无效
    uint8_t  format;            // 0=JPEG 3=BGRX
    uint16_t width, height;
    uint32_t bytes;
    uint8_t  reserved[3];
    // 后接 data[bytes],可选再跟 ScreenCaptureMeta
};

v1 只发 8 字节基础请求(等价于整虚拟桌面),不发 v2 扩展——region/window/monitor 需要 CLIENT_CAP_SCREEN_REGION,属后续增强。

参数映射:max_width 默认 1600,钳制到 [320, 3840];jpegQuality 固定 80。

7.3 BGRX → JPEG

Linux 客户端没有 JPEG 编码库,回 format=3(BGRX,自上而下逐行、每像素 4 字节 B,G,R,X,无行填充,bytes == width*height*4)。Go 用标准库转:

img := image.NewRGBA(image.Rect(0, 0, w, h))
for i := 0; i < w*h; i++ {
    img.Pix[i*4+0] = src[i*4+2] // R ← B
    img.Pix[i*4+1] = src[i*4+1] // G
    img.Pix[i*4+2] = src[i*4+0] // B ← R
    img.Pix[i*4+3] = 0xFF
}
jpeg.Encode(&buf, img, &jpeg.Options{Quality: 80})

bytes != w*h*4 时按畸形包丢弃(返回 -32000)。

7.4 能力门与超时

  • 缺 CLIENT_CAP_SCREEN_PREVIEW(0x0004) → -32005。 MFC 同款门(描述里写明"老客户端返回 -32005")。
  • 超时 8 s。不做取消:MFC 明确写了"屏幕预览 = 主连接 RPC,不能 CancelIO" (2015RemoteDlg.cpp:7514)。超时后把请求表项删掉,迟到的响应按 reqId 不匹配丢弃。
  • 响应 status != 0 时按码翻译:1/2 → -32000(带 status 文案),3 → -32005, 4 → -32602。

8. 文件工具

8.1 list_files

见 §5.3。解析细节:

  • TOKEN_DRIVE_LIST:[token][letter:1][type:1][totalMB:4][freeMB:4][typeName\0][fileSystem\0] 循环, letter=='\0' 终止。
  • TOKEN_FILE_LIST:[token]([attr:1][name\0][sizeHigh:4][sizeLow:4][ftLow:4][ftHigh:4])*, 空名终止(尾部零填充)。attr & 0x10 为目录。
  • TOKEN_FILE_LIST_ERROR:[token][win32err:4 LE],按 §4.3 映射。这是新客户端才有的 失败回执;老客户端路径不存在时直接不回包,表现为 -32001 超时(message 里要提示 "路径可能不存在,先用 list_files 确认")。

total 与 returned 分开:客户端一次返回全部,服务端做 limit 截断并在 structuredContent 里如实说明(与 MFC 的分页语义一致)。

8.2 read_file

见 §5.4。落盘完成后:

  1. 校验 SHA-256(COMMAND_FILE_COMPLETE_V2 里带的 32 字节)。
  2. 打开临时文件,按 offset/limit 读取(负 offset 从尾部倒数)。
  3. 按 encoding 解码:auto 先试严格 UTF-8(utf8.Valid),失败回退 GBK (golang.org/x/text/encoding/simplifiedchinese,go.mod 已有)。
  4. 返回 text + size + bytes_read + truncated + sha256。
  5. defer os.RemoveAll(tmpDir)。

大小门:CMD_DOWN_FILES_V2 没有区间参数,只能整文件下载,所以大小门必须卡在 下载前——在首个 COMMAND_SEND_FILE_V2 chunk 里读 fileSize,超过 YAMA_MCP_READ_MAX(默认 2 MiB,与 MFC 的 kReadFileSizeGate 一致)立即中止传输、 删临时目录、返回 -32602,message 说明"文件超过 2 MiB,本工具不支持"。不要先落盘 200 MB 再报错。

offset / limit 是下载完成之后对返回窗口的裁剪(limit 默认 256 KiB、 上限 4 MiB),不能用来绕过大小门——大文件在 Go 侧目前无解,这是协议限制, 工具描述里要写明。

8.3 路径校验(安全,必读)

V2 的 filename 由客户端提供。必须:

clean := filepath.Clean(filepath.Join(targetDir, filepath.FromSlash(name)))
rel, err := filepath.Rel(targetDir, clean)
if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) {
    abortTransfer()   // 拒收并中止
}

filepath.HasPrefix 字符串前缀比较不够——/tmp/ab 会匹配 /tmp/abc。用 filepath.Rel 判越界。

同理 list_files 的 path 与 read_file 的 path 不做本地校验(它们在远端), 但不允许包含 NUL 与换行——那会截断/拆开 C 字符串协议字段。


9. 并发、配额、生命周期

项 规则
每设备单请求 map[deviceID]*sync.Mutex 的 TryLock;占用返回 -32003,message 带占用工具名与已持续时长
全局并发 YAMA_MCP_MAX_CONCURRENCY(默认 16)信号量;超出直接 -32003
单次请求上限 terminal_exec 120 s,read_file 120 s,get_screenshot 8 s,其余 10 s
设备锁释放 defer 释放;HTTP ctx 取消也走同一条 defer
终端空闲回收 ticker 30 s 扫一次,lastUsed 超 180 s 关闭
进程退出 mcp.Server.Close() 关闭所有终端会话(避免留下孤儿 shell 子连接)

设备锁的粒度是"整台设备"而不是"每通道",与 MFC 一致(-32003 说明里写明 "列表、截屏、文件、管理动作共用这一道锁")。理由是主连接 RPC 与子连接命令 在客户端侧可能共用同一份状态,并发只会让现场更难读。


10. 代码结构与依赖方向

server/go/mcp/
  server.go     # /mcp handler、JSON-RPC 分发、鉴权、tools/list
  tools.go      # 9 个工具的定义表(name/description/inputSchema)
  errors.go     # 错误码 + JSON-RPC 错误映射
  audit.go      # mcp.tool.call 审计
  lock.go       # 设备锁 + 全局信号量
  session.go    # 终端会话表、空闲回收
  term.go       # 哨兵、环形缓冲、输出清洗
  screen.go     # 主连接预览 RPC
  filemgr.go    # 文件管理器子连接(list_files)
  filev2.go     # V2 流式接收端(read_file)

依赖方向(无环):

cmd/main.go ──▶ web ──▶ mcp ──▶ hub ──▶ connection / protocol
                 │       └──▶ devicehistory
                 └──▶ wsauth
  • mcp 只 import hub / protocol / devicehistory / logger,不 import web。
  • 构造顺序:mcp.Server 在 cmd/main.go 里先建,再分别注入两侧—— web.New(...).WithMCP(mcpSrv)(沿用 WithDeviceHistory / WithConfig 的链式风格, web/server.go:94),以及 MyHandler.mcp = mcpSrv(TCP 分派侧)。 这样 web 和 cmd 都只依赖 mcp,不存在 mcp → web 的反向依赖。
  • TCP 侧的分派(cmd/main.go 的 OnReceive)新增六个 case: TokenScreenPreviewRsp(248) / TokenDriveList(103) / TokenFileList(104) / TokenFileListError(171) / CommandSendFileV2(85) / CommandFileCompleteV2(91), 统一转给 mcp.Server.OnPacket(ctx, data),未命中在途请求就丢弃。

为什么工具定义手写在 Go 里、不 embed mcp/tools.json:9 个工具的 schema 手写约 300 行,而 embed 需要跨语言目录同步(mcp/tools.json 在仓库根,//go:embed 不能 引用父目录),要么加 Makefile 同步步骤、要么提交一份副本。手写 + 校验脚本更简单。 防漂移靠 tools/mcp_tools/verify_tools.py 增加 --subset 模式:把 Go 的 tools/list 抓下来,与 mcp/tools.json 里同名的工具逐字段比对,多一个少一个都报错。


11. 施工顺序与验收

序 内容 依赖 可独立验收
1 mcp 包骨架 + /mcp + 鉴权 + initialize/ping/tools/list — ✅ curl 打通
2 4 个本机只读工具(list_hosts/get_host_detail/get_server_status/get_audit_log) 1 ✅ 不碰设备即可测
3 设备锁 + 全局信号量 + 审计 1 ✅
4 终端会话表 + 订阅 + 环形缓冲 3 ✅ 浏览器开终端时能观察到缓冲
5 哨兵 + 输出清洗 + terminal_exec 执行/轮询 4 ✅ 对照 MFC 同款命令的输出现象
6 terminal_close + 空闲回收 5 ✅
7 主连接 RPC 请求表 + get_screenshot 3 ✅
8 文件管理器子连接 + list_files 3 ✅
9 V2 接收端 + read_file + 路径校验 8 ✅
10 verify_tools.py --subset 1 ✅

整体验收(用同一套 ASM 工位任务重跑):

  • 9 个工具全部可调用,tools/list 响应 < 24 KB(无 outputSchema 的直接收益)
  • terminal_exec 连续 20 条命令零失败;超时后轮询能取回完整输出
  • 浏览器开着终端时 terminal_exec 返回 -32003 而不是把人的会话踢掉
  • read_file 读 .env(含单引号、CRLF)字节级一致,SHA-256 与远端 sha256sum 相同
  • get_screenshot 在 Windows / Linux 各出一张图,Linux 走 BGRX→JPEG 分支
  • 审计里每次调用一条 mcp.tool.call,device/tool/code/ms 齐全

12. 风险与未决

# 风险 影响 处置
R1 哨兵清洗移植不完整 输出带垃圾/退出码错 按 MFC 三段顺序整体移植,用 MFC 记录的实测样例做 Go 单测(rem hello、cmd /c echo abc、type .env)
R2 终端槽位被 MCP 长期占用 人用不了终端 空闲 180 s 回收 + -32003 明确告知 + 工具描述写明
R3 老客户端不认识 CMD_DOWN_FILES_V2(94) read_file 静默超时 工具描述写明"超时可能是不支持 V2 的旧客户端";§5.4
R4 老客户端缺 CLIENT_CAP_UTF8 文件名 GBK 解码 新客户端 DefaultCaps() 恒带此位(commands.h:1289),只有很老的客户端会缺;与既有 activeWindow 路径同源,后续在 hub.DeviceInfo 暴露 clientType 后一并修
R5 非 PTY 老客户端 无法用 terminal_exec v1 明确 -32005,描述里说明
R6 多用户 / 分组授权缺失 所有 MCP 调用都是 admin v1 明确单 principal;多租户部署前必须补 token 表 + allowedGroups 校验
R7 无 notifications/progress 长任务(read_file 大文件)模型以为卡死 工具描述写明预期耗时;v2 再上 SSE
R8 read_file 只能整文件下载,2 MiB 封顶 读大日志无解 与 MFC 同款限制(kReadFileSizeGate)。绕法是 terminal_exec + tail,工具描述里给出这个替代路径

附录 A:协议速查

名称 值 方向 载荷
COMMAND_LIST_DRIVE 1 S→C 主连接 [cmd]
COMMAND_LIST_FILES 2 S→C 文件子连接 [cmd][path\0]
COMMAND_SCREEN_SPY 16 S→C 主连接 [cmd]
COMMAND_BYE 204 S→C 任意 [cmd]
COMMAND_SCREEN_PREVIEW_REQ 247 S→C 主连接 ScreenPreviewReq(8B)
COMMAND_SEND_FILE_V2 85 C→S V2 子连接 FileChunkPacketV2(77B)+ name + data
COMMAND_FILE_COMPLETE_V2 91 C→S V2 子连接 FileCompletePacketV2(69B)
CMD_DOWN_FILES_V2 94 S→C 文件子连接 [cmd][targetDir\0][path\0][\0]
TOKEN_DRIVE_LIST 103 C→S 文件子连接 [token] + 盘符记录
TOKEN_FILE_LIST 104 C→S 文件子连接 [token] + 文件记录
TOKEN_FILE_LIST_ERROR 171 C→S 文件子连接 [token][win32err:4 LE]
TOKEN_CONN_AUTH 246 C→S 子连接 ConnAuthPacket(512B)
TOKEN_SCREEN_PREVIEW_RSP 248 C→S 主连接 ScreenPreviewRspHeader(16B)+ data

FileChunkPacketV2 字段:cmd(1) transferID(8) srcClientID(8) dstClientID(8) fileIndex(4) totalFiles(4) fileSize(8) offset(8) dataLength(8) nameLength(8) flags(2) checksum(2) reserved(8) = 77 字节。


附录 B:自审记录

写完初稿后按"每个结论都必须能在代码里指到行"重核了一遍,发现并修掉以下问题:

# 问题 处置
1 初稿写"文件管理器子连接不带 ConnAuth,需要 pending 标记",照搬了 MFC 的做法 错。client/KernelManager.cpp:1773 对 COMMAND_LIST_DRIVE 调了 EnableSubConnAuth(),Go 的 handleConnAuth 已把 clientID 钉在 ctx 上。改为按 clientID 路由,删掉 pending 方案,省掉一个 hub 改动
2 初稿把 get_screenshot 设计成"抓 TOKEN_FIRSTSCREEN 原始帧" 改。TOKEN_FIRSTSCREEN 虽注释为 raw BGRA,但它依附于屏幕会话(占槽位、要建子连接)。改用 COMMAND_SCREEN_PREVIEW_REQ 主连接 RPC——与 MFC 一致,不占任何槽位
3 初稿写"终端槽位需要给 hub 加 owner 字段" 简化。hub.OpenTerminalSession 的 ErrTerminalBusy 本身就是互斥,v1 不抢占就不需要 owner。删掉 hub 改动,v1 对 hub 零改动
4 初稿写 read_file 用 filepath.HasPrefix 校验路径 错。字符串前缀会让 /tmp/ab 匹配 /tmp/abc。改为 filepath.Rel 判越界
5 初稿漏了非 PTY 客户端的处理 补 §6.7:v1 明确 -32005,不做半吊子支持
6 初稿写"审计记录完整 command" 改。命令全文可能含密码,改为只记首词与长度,全文进 debug 日志
7 初稿的 list_files 没写 total 与 returned 的区别 补 §8.1,避免模型把截断当成"目录里只有这么多"
8 初稿写"terminal_exec 的 reqId 用时间戳" 改。时间戳在并发下会撞;改 atomic.Uint32 取低 16 位,并必须校验响应 reqId(MFC TakePreviewResponse 同款)
9 初稿把 get_screenshot 的 max_width 固定 1600 改 为可传,钳制 [320,3840],与 MFC 的 max_width 参数对齐
10 初稿没写"客户端 V2 开关关闭会静默超时" 改。核查后发现 V2 开关是服务端的(2015RemoteDlg.cpp:2822 EnableFileV2,默认关),不是客户端。且 CLIENT_CAP_V2 在 DefaultCaps() 里全平台无条件声明,做门等于没门。改为"无能力门 + 老客户端不认识 94 号命令会静默超时",见 §5.4
11 初稿把 read_file 的能力门写成 CLIENT_CAP_V2 删。同 #10,该位恒为真。表格与 §5.4 一并改
12 初稿写 /mcp 用 s.requireBearer 包一层 错。requireBearer 校验的是浏览器会话令牌(web/server.go:269 的 s.auth.ValidateToken),MCP 静态令牌过不去。改为 mux.HandleFunc("/mcp", s.mcp.Handle),鉴权在 handler 内做
13 初稿写"mcp 在 web.Start() 里构造" 错。TCP 侧 cmd/main.go 的 OnReceive 也要把包转给 mcp,两边需要同一实例。改为在 cmd/main.go 先建,再 web.New(...).WithMCP(srv) + MyHandler.mcp = srv
14 初稿写"非 PTY 客户端 -32005",但没说"根本不支持 shell 的客户端怎么办" 补 §6.7:不设能力门(CLIENT_CAP_TERMINAL 只有 Android 声明),走 -32001 超时 + message 提示
15 §5.3 时序图自相矛盾:TOKEN_DRIVE_LIST 后写"关子连接",下一行又写"同一子连接"发 COMMAND_LIST_FILES 改。列目录必须复用同一个子连接(2015RemoteDlg.cpp:7647 的注释),改为"保持打开,TOKEN_FILE_LIST 分支收尾"
16 §5.4 仍写 filepath.HasPrefix 校验路径,与 §8.3 自相矛盾 改。统一指向 §8.3 的 filepath.Rel 判越界
17 §7.1 说"屏幕流全是 H.264",据此否掉首帧方案 错两处:首帧 TOKEN_FIRSTSCREEN 本来就是裸 BGRA,不需要解码;否掉它的真正理由是要建屏幕子连接、占唯一槽位、还要拆。改为按代价论证
18 §8.2 建议大文件"直接用 download_file" 错。download_file 在 v1 不做(§1.2),不能建议一个不存在的工具。改为"卡在下载前的大小门 + 用 terminal_exec 兜底"
19 §8.2 只说"limit 上限 4 MiB",没意识到 V2 是整文件下载 补。CMD_DOWN_FILES_V2 无区间参数,大小门必须卡在首个 chunk 的 fileSize 上(2 MiB,与 MFC kReadFileSizeGate 一致),否则会先落盘再报错
20 §3.2 get_server_status 返回 version/commit,但 Go 侧没有这两个变量 补。cmd/main.go 查不到版本常量,需新增 var version, commit string + Makefile -X 注入;拿不到返回空串
21 §3.2 get_host_detail.capabilities 里列了 v2 删。该位全平台恒真(同 #10),列出来误导模型。换成 utf8/screen_preview/screen_region/window_info
22 §5.2 写死 SendToTerminal(cmd+"\n"),与 §6.4 的 ConPTY \r\n 冲突 改 为按平台分行尾

结论:以上 22 处已全部修入正文,无遗留。v1 对 server/go 的改动是 新增 mcp 包 + web/server.go 一行路由 + web.Server 一个 WithMCP + cmd/main.go 六个 case + protocol 六个常量 + 两个版本变量, hub 零改动。