Files
SimpleRemoter/docs/Mcp_Go_Minimal_Implementation_Plan.md
T
yuanyuanxianganddeepseek-flash 70556391dd Docs(mcp): record the Go MCP overall acceptance
Run the section 5 checklist end to end against the debug Go server and a
Windows debug ghost: nine tools called, tools/list at 22578 B, twenty
consecutive terminal_exec calls with zero failures, read_file SHA-256
matched, 30 audit entries with device/tool/code/ms, and --subset passing
in both 9-tool and readonly 7-tool modes. Race tests stay clean.

Two checklist items get corrected rather than ticked: hub did change
(SendToConn in M6 and the terminal lease generation in M4a, both needed
and unit tested), and the MFC regression has no target because the whole
milestone range touches no C++ file. Note the running Release binary is
an older build reporting the old tool names; it was left alone.

Co-Authored-By: deepseek-flash
2026-11-12 23:12:29 +01:00

546 lines
35 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Go 服务端 MCP 实施计划
> 版本:v1(草稿,待评审) 日期:2026-11-12
>
> 依据:`docs/Mcp_Go_Minimal_Design.md` v1.0(下称"设计文档")。
> 本文只回答**怎么施工**:顺序、改动面、完成定义、验证手段、提交边界。
> 设计取舍一律以设计文档为准,本文不重复论证;与设计文档不一致的地方在 §1 单列。
>
> 工作方式:沿用本项目既有节奏——**做一段、验一段、审一段、提交一段**,每段一个可独立
> 回滚的提交。Go 侧提交前缀用仓库既有约定 `Feature(Go):` / `Fix(Go):`。
---
## 0. 交付面与总量
| 类别 | 内容 | 规模 |
|---|---|---:|
| 新包 | `server/go/mcp/`(server / tools / errors / audit / lock / session / term / screen / filemgr / filev2) | ≈2,300 行(含测试 ≈900) |
| 抽包 | `server/go/auditquery/`(从 `web/audit_query.go` 提出查询器,见 §1.1) | ≈180 行搬移 |
| 接线 | `web/server.go`(`WithMCP` + 一行路由)、`cmd/main.go`(构造/注入/六个 case/版本变量)、`protocol/commands.go`(常量)、`build.ps1` + `Makefile`(`-X` 注入) | ≈120 行 |
| 工具校验 | `tools/mcp_tools/verify_tools.py` 增 `--subset` | ≈80 行 |
| 文档 | `deploy/yama-server.env.example` 补 5 个变量;`docs/Mcp_Go_Minimal_Design.md` 状态改"已实施" | — |
**8 个提交,8 个里程碑,预估 62 小时**(明细见 §3 / §7)。`hub` 零改动——这是设计文档
自审后的结论,本计划沿用;若施工中发现必须改 `hub`,先停下来改设计文档。
---
## 1. 开工前必须先定的 5 件事
这 5 项都会阻塞某个里程碑,且都需要一次性拍板。建议按顺序在本计划评审时定掉。
### 1.1 `get_audit_log` 的代码复用方式(阻塞 M2)
设计文档 §3.2 要求"复用 `web/audit_query.go` 的查询器",§10 又要求"`mcp` 不 import `web`"。
两者冲突:查询器 `queryAuditLog` 及其类型/过滤/时间解析全是 `web` 包私有(`web/audit_query.go:158-328`)。
| 方案 | 做法 | 代价 |
|---|---|---|
| **A(推荐)** | 新增 `server/go/auditquery` 包,把 `queryAuditLog` + `auditQueryRequest/Result` + `auditRecordMatches` / `auditEventFilterMatches` / `auditStringField` / `parseAuditTime` / `clamp*` 整体搬过去并导出(`Scan(path string, q Query) (Result, error)`);`web/audit_query.go` 只留 handler 与回包整形 | 搬移 + `web/audit_query_test.go`(294 行)机械改调用名;依赖方向保持不变 |
| B | `mcp` 自己实现一个精简扫描器(keyword/type/limit/offset) | 少动 `web`,但审计格式一旦变就有两份实现 |
| C | `mcp` import `web` | 破环:`web → mcp` 已存在(`WithMCP`),反向成环直接编译失败 |
**已确认:采用 A**。M2 的第一步就是搬包,`go test ./web/...` 全绿后再写工具。
### 1.2 版本号与提交号注入(阻塞 M2 的 `get_server_status`)
`cmd/main.go` 目前没有版本常量(全文件 grep 不到)。**已确认**的做法:
- 新增 `server/go/buildinfo`,只放 `var Version, Commit string`(零值空串)+ `Snapshot()`。
不塞 `main`:`mcp` 不能依赖 `main`,也不该为两个字符串在装配链上多传两层。
- 注入:`-X github.com/yuanyuanxiang/SimpleRemoter/server/go/buildinfo.Version=…`,同样注入 `.Commit`。
取值 `Version=$(git describe --tags --always --dirty)`、`Commit=$(git rev-parse --short HEAD)`
(现在是 `v1.4.2-72-g425d737-dirty` / `425d737`)。
- `build.ps1`:Debug/Release **都**拼 `-X`(Debug 只是不剥符号);`Makefile` 的 `LDFLAGS`
用 `$(shell git …)` 同步。
- 取不到(无 git、源码包构建)就保持空串,`get_server_status` 原样返回空串,**不伪造**。
- Windows 资源同步:`cmd/winres/winres.json` 里的版本号改成占位,构建前跑
`go-winres make --in cmd/winres/winres.json --out cmd/rsrc --product-version git-tag --file-version git-tag`
(实测会把 manifest identity / FileVersion / ProductVersion 三处一起覆盖成 `1.4.2`);
`go-winres` 不存在时警告并跳过。`server/go/cmd/*.syso` 加进 `.gitignore`,不再出现在
`git status` 里。文件属性 = 干净 tag,运行时 `version` = `git describe` 全串,各司其职。
### 1.3 工具 schema 用哪一份(阻塞 M2/M5/M6/M7)
设计文档 §3.2 给的参数集与 `mcp/tools.json`(MFC 现网 schema)**并不完全一致**:
| 工具 | 设计文档 §3.2 | `mcp/tools.json` 实际 |
|---|---|---|
| `list_hosts` | `group` `name` `online_only` `limit` `offset` | `client_type` `group` `include_offline` `ip` `limit` `name` `offset` `online` `os` `query` |
| `get_host_detail` | `id` | `id` `ids` |
| `get_audit_log` | `keyword` `type` `since` `limit` `offset` | `keyword` `limit` `offset` `type` |
| `get_screenshot` | `id` `max_width` | `id` `max_width` `height` `hwnd` `mode` `monitor` `width` `x` `y` |
| `terminal_exec` | 一致 | 一致 |
| `terminal_close` | `session_id` | `id` `session_id` |
| `list_files` | `id` `path` `limit` | `id` `ids` `limit` `offset` `path` |
| `read_file` | `id` `path` `offset` `limit` `encoding` | 同 + `max_bytes` |
设计文档自称"全部命名、参数、错误码与 MFC 对齐",实际只有 naming 与错误码对齐。
**已确认:`mcp/tools.json` 是唯一契约**——`name` / `description` / `inputSchema` /
`outputSchema` 和工具顺序都按它来(`verify_tools.py:12` 的比对口径)。
- 9 个工具的这四份字段由 `tools/mcp_tools/gen_go_tools.py` 从 `mcp/tools.json` 抽取(保持相对顺序),
写到 `server/go/mcp/tools_minimal.json`,Go 侧 `//go:embed` 原样回 `tools/list`;脚本支持
`--check`(子集与抽取结果不等则非零退出),加一个 Go 单测锁名字与顺序。
- `tools.json` 里没有 `annotations`,MFC 也不发,Go 不发(M1 的测试相应改为"不带 annotations")。
- 输出按对应 `outputSchema` 的字段名组装,**不套用设计文档 §3.2 的自造形状**。
| 参数 | Go 侧处理 |
|---|---|
| `list_hosts` 全部 10 个 | 全部实现(`DeviceInfo` 上做字符串过滤,成本可忽略) |
| `get_host_detail.ids` | 实现批量(≤50),按 `outputSchema` 的 `{tool,total,succeeded,failed,skipped,results[]}` 汇总 |
| `get_audit_log` | `keyword` / `type`(映射 `auditquery.Event`)/ `limit` / `offset`;**没有 `since`**(MFC 的 schema 里就没有) |
| `get_screenshot` 的非整屏参数 | `mode=region/window/monitor` 或 `hwnd/x/y/width/height` 任一出现 → `-32005`,报文点名参数并说明需要 `CLIENT_CAP_SCREEN_REGION` 扩展请求;不静默忽略 |
| `get_screenshot.max_width` | 钳制 `[64,1920]`(schema 与 `McpServer.cpp:3386` 一致);缺省/0 → Go v1 固定 1024(没有 MFC 的 RTT 自适应档位) |
| `terminal_close.id` | 必需;用于定位设备,`session_id` 用于匹配会话 |
| `list_files` 的 `id/ids/path/limit/offset` | 全部实现;`offset` 是服务端在完整列表上做窗口裁剪;批量走 results 汇总 |
| `read_file` 的语义 | **行语义**:`offset` 起始行(负数=末尾 N 行)、`limit` 行数、`max_bytes` 字节上限;`encoding` 支持 `auto/utf-8/gbk/gb18030/latin1` |
| 输出字段 | `list_hosts` → `hosts/total/totalAll/limit/offset/hasMore`;`list_files` → `files`(不是 `entries`)/`drives`;`get_host_detail.capabilities` → `screenPreview/screenRegion/windowInfo/fileTransferV2/c2cPaths/registry/remoteControl/platform`;`read_file` → `encoding/eol/lines_total/lines_returned/sha256/size/text/truncated` |
| hub 没有的字段 | `authStatus/tls/location/install_time/remark` 不伪造、直接不给(`outputSchema` 只强制 `hosts`) |
`read_file` 的整文件下载仍受 `YAMA_MCP_READ_MAX`(2 MiB)硬门约束,超过 → `-32602`(schema 描述同款口径)。
### 1.4 测试环境与"真机"路径(阻塞 M4 起的全部验收)
**已确认并已由 M0 实测**(详见 §4.3):本机真客户端用 **`x64\Debug\ghost.exe`**,
`TestRun.exe` 不可用(依赖 `ServerDll.dll` 内存加载;Release 版从非安装路径启动会走安装
流程并自删)。Go 服务端默认 **trial** 签名即可,客户端已上线;屏幕/文件能力是否解锁
在 M5/M6 实测(`YAMA_LICENSE_DISABLED=1` 的 NoOp 会让客户端拒绝这两类功能,不要用于
M5 之后的验收)。
### 1.5 只读模式下的工具集合(阻塞 M8)
`YAMA_MCP_READONLY=1` 时 `tools/list` 只出 7 个。`--subset` 必须支持"期望集合 7 或 9"两种,
由环境变量或 `--readonly` 参数决定;不能写成硬编码 9。
---
## 2. 里程碑与提交边界
| 里程碑 | 提交标题(建议) | 设计文档 § | 依赖 | 完成定义(可验收) | 预估 |
|---|---|---|---|---:|
| M1 | `Feature(Go): MCP endpoint with bearer auth and tools/list` | §4、§3.1 | — | `curl` 打通 initialize/ping/tools/list;错误令牌 401;GET 405;通知 204 | 6h |
| M2 | `Feature(Go): four local MCP read tools and a shared audit query package` | §3.2、§1.1 | M1 | 4 个工具返回真实数据;`go test ./web/...` 与新增用例全绿 | 10h |
| M3 | `Feature(Go): per-device locks, concurrency cap and MCP audit trail` | §9、§4.4 | M1 | 并发调用返回 -32003;每次调用一条 `mcp.tool.call` | 4h |
| M4a | `Feature(Go): MCP terminal sessions with a ring buffer` | §6.1-§6.3 | M3 | 会话表 + 订阅 + 缓冲;浏览器开终端时 MCP 返回 -32003 | 6h |
| M4b | `Feature(Go): terminal_exec with sentinel cleaning and polling` | §6.4-§6.6 | M4a | 20 条连续命令零失败;超时后轮询取回完整输出 | 8h |
| M4c | `Feature(Go): terminal_close, idle sweep and legacy-client guard` | §6.2、§6.7 | M4b | 关闭幂等;空闲 180s 回收;非 PTY 返回 -32005 | 2h |
| M5 | `Feature(Go): get_screenshot over the maintenance-free preview RPC` | §7 | M3 | Windows/Linux 各出一张图;BGRX 分支有单测 | 6h |
| M6 | `Feature(Go): list_files over the file-manager sub-connection` | §5.3、§8.1 | M3 | 盘符/目录/错误三种路径;老客户端超时有明确 message | 8h |
| M7 | `Feature(Go): read_file over the V2 stream receiver` | §5.4、§8.2-§8.3 | M6 | `.env` 字节一致且 SHA-256 匹配;路径穿越全部拒收 | 10h |
| M8 | `Feature(Go): verify_tools --subset and MCP deployment docs` | §10、§4.2 | M1 | 9(或 7)个工具的 schema/description 与 `tools.json` 严格一致 | 3h |
M4 拆成三个提交是因为它占全量工作量的 1/4,一次提交无法审查;其余里程碑按设计文档
§11 的 10 个施工序合并(§11 的 3 并进 M3,4/5/6 并成 M4a/b/c,7 是 M5,8 是 M6,9 是 M7,10 是 M8)。
---
## 3. 里程碑细则
### M1 骨架与鉴权(设计 §4)
**新增文件**
```
server/go/mcp/server.go // Config、Server、New、Enabled、Handle、Close
server/go/mcp/jsonrpc.go // 请求/响应结构、错误对象、批量拒绝
server/go/mcp/tools.go // //go:embed tools_minimal.json,tools/list 原样返回
server/go/mcp/tools_minimal.json // gen_go_tools.py 从 mcp/tools.json 抽取的 9 个工具
server/go/mcp/errors.go // -32001…-32602 常量与 message 模板
tools/mcp_tools/gen_go_tools.py // 抽取脚本,--check 模式供验收
```
**实现要点**
1. `Config` 从环境变量读全(`cmd/main.go` 解析后传入,`mcp` 包不直接读 env):
`Token` / `Readonly` / `TermIdle` / `MaxConcurrency` / `ReadMax`。
2. `Handle` 分支表:`POST` 之外一律 `405`(带 `Allow: POST`);无 `id` 的通知 `204`;
数组入参 `-32600`;未知 `method` `-32601`;`tools/call` 未知工具名 `-32601`。
3. 鉴权:`subtle.ConstantTimeCompare`,长度不等直接失败;缺令牌 → `401` +
`WWW-Authenticate: Bearer realm="mcp"`,不带 JSON-RPC 体(规范要求传输层失败)。
4. 体积:`http.MaxBytesReader(w, r.Body, 8<<20)`,超限 `413`。
5. `initialize` 回 `protocolVersion=2025-06-18`、`capabilities.tools={listChanged:false}`、
`serverInfo={name:"yama", version:<build>}`、`instructions=<Go 后端差异说明>`。
`serverInfo.name` 与 MFC 一致,Go 差异只写 `instructions`——避免客户端按 name 分叉。
6. 路由注册:`web/server.go` 加 `WithMCP`,`Start()` 里
`if s.mcp != nil && s.mcp.Enabled() { mux.HandleFunc("/mcp", s.mcp.Handle) }`,
否则打一行 `MCP endpoint disabled: YAMA_MCP_TOKEN not set`。
7. `cmd/main.go`:在 `web.New(...)` 之前构造 `mcpSrv`,再 `.WithMCP(mcpSrv)` +
`handler.mcp = mcpSrv`(`MyHandler` 加字段);`mcp` 只依赖 `hub`/`protocol`/`devicehistory`/`logger`。
**测试**(`mcp/server_test.go`,`httptest` + fake hub)
- 令牌:正确 / 错误 / 长度不同 / 缺失 → 200 / 401 / 401 / 401。
- 方法:`initialize`、`ping`、`tools/list`、`notifications/initialized`(204)、未知方法(-32601)。
- 形态:批量数组 → -32600;GET/DELETE → 405;超大体 → 413。
- `tools/list`:数目与 `Readonly` 相符;工具定义与 `tools_minimal.json` 逐字一致且顺序不变
(无 `annotations`,与 MFC 一致)。
**验收命令**
```bash
cd server/go
go build ./... && go test ./mcp/...
curl -s -X POST localhost:18090/mcp -H "Authorization: Bearer $YAMA_MCP_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
### M2 本机只读四工具(设计 §3.2)
**改动**
1. 先做 §1.1 的 `auditquery` 抽包:搬移 → `web` 改调用 → `go test ./web/...` 全绿。
2. 新增 `mcp/tools_local.go`:
- `list_hosts`:`hub.ListDevices()` + `history.Offline(onlineSet)` 合并;`include_offline`
决定是否并入历史;`online/ip/os/group/name/client_type/query` 全为过滤(`name`/`query`
大小写不敏感子串);按 `outputSchema` 返回 `{hosts,total,totalAll,limit,offset,hasMore}`,
host 字段按 schema 命名组装,hub/历史里确有的 `location/install_time/screen/version` 照填,
两边都没有的 `authStatus/tls/remark` 不伪造。
- `get_host_detail`:`id` 或 `ids`(≤50,批量走 `{tool,total,succeeded,failed,skipped,results[]}`);
`capabilities{screenPreview,screenRegion,windowInfo,fileTransferV2,c2cPaths,registry,remoteControl,platform}`
(`protocol.SupportsCap` 逐位)——**不含 `v2`**(恒真,列出来误导)。
- `get_server_status`:按 `outputSchema` 的字段名组装,Go 只填能如实取到的
`version / uptime_sec / hosts / sessions / port / bind`(其余 MFC 专有字段不给);
`version` 取 `buildinfo`(§1.2),`uptime_sec` 用 `mcp.Config.StartedAt`,`commit`
只进日志,不塞进 schema 未定义的返回字段。
- `get_audit_log`:`auditquery.Scan`;`type` 映射事件过滤;无 `since`。
3. `buildinfo` 包 + `build.ps1` / `Makefile` 的 `-X` + winres 重建(§1.2)。
**测试**(`mcp/tools_local_test.go`)
- `devicehistory.New(t.TempDir()+"/devices.json", 10, log)` + `hub.Register` 造 3 台在线、2 台历史
离线;断言过滤/分页,以及 `total`(命中数)、`totalAll`(过滤前)、`hasMore` 三者分离。
- `get_host_detail` 的能力位:给一个 capability 串(含/不含 `0x0004`)两种。
- `get_audit_log`:用 `logger.Audit` 写临时文件后查询(`auditquery` 的用例在搬包时一并迁)。
### M3 锁、并发与审计(设计 §9、§4.4)
**新增** `mcp/lock.go`、`mcp/audit.go`。
1. 设备锁:`map[string]*sync.Mutex` + `TryLock`,占用即 `-32003`,message 带占用工具名与
已持续时长(`since` 记录在持锁结构里)。
2. 全局信号量:`chan struct{}` 容量 `MaxConcurrency`,`TryAcquire` 失败 `-32003`。
3. 审计:每次 `tools/call` 一条 `log.Audit("mcp.tool.call", …)`,字段
`actor=mcp role=admin source=mcp tool device ok code ms args=<首词+长度> result=<体积摘要>`;
**不记命令全文**(进 debug 日志)。HTTP `r.Context()` 取消同样走 defer 释放锁。
**测试**:并发两个同设备调用 → 第二个 -32003;`close(cancel)` 后锁被释放;审计行字段齐全
(读临时审计文件断言)。
### M4a 终端会话(设计 §6.1-§6.3)
**新增** `mcp/session.go`(会话表 + 空闲回收)、`mcp/term.go`(环形缓冲 + 哨兵检测骨架)。
1. `mcp.Server` 实现 `hub.EventHandler` 全接口(`OnDeviceOnline/Offline/Update`、
`OnScreenFrame`、`OnResolutionChange`、`OnCursorChange`、`OnClipboardText`、
`OnTerminalReady/Data/Closed`),只有终端三个方法做事,其余空实现;
`cmd/main.go` 里 `deviceHub.Subscribe(mcpSrv)`,退出时 `hub.Unsubscribe` + `Close()`。
2. `OnTerminalData` 在 TCP 读循环上执行,**必须不阻塞**:只做"查会话 → 追加环形缓冲 →
剥 4 字节 `TRM1` 前缀 → 哨兵扫描 → `sync.Cond` 唤醒",任何长操作都不允许(设计 §6.3)。
非 MCP 会话的设备直接丢弃(零开销)。
3. 环形缓冲 256 KiB + `base/total/delivered` 绝对偏移;溢出丢最旧并累计 `droppedBytes`。
4. 会话表 key 用 `deviceID`;`session_id` 为 `"s-"+6hex`;对外只暴露 `session_id`。
**测试**:`hub.PublishTerminalData` 灌 1 MB → 缓冲不涨、`truncated` 语义正确;关闭后释放;
浏览器(另建一个订阅者 `OpenTerminalSession`)占用时 `OpenSession` 返回 busy。
### M4b `terminal_exec` 执行与轮询(设计 §6.4-§6.6)
1. 打开:`hub.OpenTerminalSession(deviceID)`;`ErrTerminalBusy` → `-32003`;等
`OnTerminalReady`(带超时 → `-32001`);非 PTY → `-32005`(M4c 收紧)。
2. 下发:行尾按 `isPTY`/平台(设计 §6.4 的表);`hub.SendToTerminal`。
3. 清洗三段**整体移植**:`StripEchoedInput` → `StripAnsi` → `StripSentinelText`
(对应 MFC `McpServer.cpp:3946-4040`),顺序不可换。Go 侧用表驱动单测锁住行为。
4. 等待与交付:`done`/`closed`/超时三分支;超时**不销毁会话**,`delivered` 游标支持
`terminal_exec` 不带 `command` 的轮询;`max_output_bytes` 按行截断(保留换行)并置
`truncated`(防止把 UTF-8/GBK 多字节字符切坏)。
5. 返回体:`{session_id, output, exit_code?, done, offset, truncated, is_pty, reused}`。
**单测**(表驱动,样例来自 MFC 实测)
`rem hello`、`cmd /c echo abc`、`type .env`、SPAM 循环、`ping -n 30` 超时后轮询、
`cmd /\c` 折行回显、退出码 0/1 与非 PTY 单行哨兵。
**集成**(假设备,§4.2):模拟 `TOKEN_TERMINAL_START` → 输出 → 哨兵,断言 `exit_code`。
### M4c 关闭、回收与老客户端(设计 §6.2、§6.7)
1. `terminal_close`:**幂等**(会话不存在也 200);只关 MCP 自己创建的会话(`hub.CloseTerminalSession`
只有在会话表里有该设备且 `hub.TerminalIsPTY` 一致时才调用,避免误关浏览器会话——实现上
以"会话表命中"为准)。
2. 在途命令被 `terminal_close` 撞上:对齐 C++ 的 `waiters` 教训(`McpServer.cpp:12611`)——
置 `closed` 唤醒等待者交付剩余缓冲,无等待者则立即擦会话并 `CloseTerminalSession`。
3. 空闲回收 ticker 30s 扫一次,`lastUsed > TermIdle` 关闭;`Close()` 关掉全部会话。
4. 非 PTY(`TOKEN_SHELL_START`)→ `terminal_exec` 直接 `-32005`,message 写明"该客户端版本
不支持 PTY 会话"。不支持 shell 的客户端不设能力门,超时文案带一句提示(设计 §6.7)。
**测试**:closing 幂等;关闭后立刻重开 <1s;空闲回收(把 `TermIdle` 调成 100ms);
在途关闭与无等待者两条分支(各一个用例)。
### M5 `get_screenshot`(设计 §7)
**新增** `mcp/screen.go`;`protocol/commands.go` 加 `CommandScreenPreviewReq=247`、
`TokenScreenPreviewRsp=248`;`cmd/main.go` `OnReceive` 加两个 case 转 `mcp.OnPacket`。
1. 请求表 `map[deviceID]*pendingPreview{reqID uint16; ch chan []byte}`,
`reqID` 用 `atomic.Uint32` 取低 16 位;**响应 reqID 不匹配直接丢弃**(对齐 MFC
`TakePreviewResponse`)。
2. 能力门:缺 `protocol.ClientCapScreenPreview` → `-32005`。
3. 8 字节请求体;`max_width` 钳制 `[64,1920]`、缺省/0 → 1024;`jpegQuality` 固定 80。
4. 响应:`status != 0` → 1/2 `-32000`、3 `-32005`、4 `-32602`;`format=0` 直接返回 JPEG,
`format=3`(BGRX)→ 先 `image.RGBA` 再 `jpeg.Encode`;`bytes != w*h*4` 视为畸形包 `-32000`。
5. 超时 8s,超时删表项,**不 CancelIO**(主连接 RPC,MFC 同款)。
6. 返回 `content[]` 一项 `image`(base64 JPEG)+ `structuredContent{width,height,bytes,format,source}`。
**测试**:JPEG 魔数(`FF D8 FF`)、BGRX→JPEG 像素抽样、reqID 错包被丢弃、status 映射、
超时。
### M6 `list_files`(设计 §5.3、§8.1)
**新增** `mcp/filemgr.go`;`protocol` 加 `CommandListDrive=1`、`CommandListFiles=2`、
`TokenDriveList=103`、`TokenFileList=104`、`TokenFileListError=171`(**加一个常量唯一性单测**:
新值不得与既有 `protocol` 常量重复,`103/104` 紧邻 `TOKEN_LOGIN=102`,值写错会吃主连接登录包)。
1. 主连接 `hub.SendToDevice(dev, []byte{CommandListDrive})`;等文件子连接:在
`OnReceive` 顶部(终端 short-circuit 之后)先喂 `mcp.OnPacket(ctx, data)`,`mcp` 按
`ctx.GetInfo().ClientID` 找到 pending 请求并**记住 ctx**(后续 `COMMAND_LIST_FILES` 要用它)。
2. `TOKEN_DRIVE_LIST` 到达后**不关子连接**,同一 ctx 下发 `[CommandListFiles][path\0]`;
`TOKEN_FILE_LIST` / `TOKEN_FILE_LIST_ERROR` 才收尾。
3. 解析按设计附录 A;`attr & 0x10` 判目录;文件名 `protocol.DecodeClientString(data, capability, "")`。
4. 错误映射:`win32err ∈ {2,3}` → `-32009`;`5` → `-32010`;其它 → `-32000`。
老客户端无 `TOKEN_FILE_LIST_ERROR` → 超时;message 提示"路径可能不存在,先列目录确认"。
5. 收尾:`COMMAND_BYE` → 500ms → `ctx.Close()`(`hub` 同款优雅关闭)。
**测试**:盘符/文件/错误三种黄金字节(照 MFC `ParseDriveList`/`ParseFileList` 的样例抓真实包,
存为 `testdata/*.bin`);`offset/limit` 语义;客户端中途断开 → `-32001` 且 pending 表被清。
### M7 `read_file`(设计 §5.4、§8.2-§8.3)
**新增** `mcp/filev2.go`;`protocol` 加 `CommandSendFileV2=85`、`CommandFileCompleteV2=91`、
`CmdDownFilesV2=94`;`cmd/main.go` 加两个 case。
1. 流程:列盘(复用 M6 的子连接)→ 同一子连接发 `[CmdDownFilesV2][targetDir\0][path\0][\0]`
→ 服务端关掉文件子连接 → 客户端建 V2 子连接(`ConnAuth` 已钉 `ClientID`)→
`COMMAND_SEND_FILE_V2 × N` → `COMMAND_FILE_COMPLETE_V2`。
2. `targetDir := os.MkdirTemp("", "yama-mcp-read-*")`,`defer os.RemoveAll`。
3. **大小门**:首个 chunk 的 `fileSize` 超 `ReadMax` → 立即中止、删目录、`-32602`
(不要先落盘再报错)。
4. **路径校验**(安全,必须单测):`filepath.Clean(filepath.Join(targetDir, FromSlash(name)))`
+ `filepath.Rel` 判越界;另拒 NUL / 换行;`name` 允许客户端回填为相对路径。
5. SHA-256 校验(完成包 32 字节)→ 编码判定(BOM → `utf8.Valid` → 回退
`simplifiedchinese.GBK`,`latin1` 逐字节)→ 按行切分并取
`offset`/`limit`/`max_bytes` 窗口 → 返回
`{path,size,encoding,eol,lines_total,offset,lines_returned,truncated,text,sha256}`。
6. 超时/断流:`-32001`;工具描述写明"超时可能是不支持 V2 的旧客户端"(设计 R3)。
**测试**:路径穿越用例集(`../x`、`..\\..\\x`、绝对路径、UNC、混合分隔符、`a/../../b`);
大小门;SHA 不符;GBK 文件;负 offset;`transferID` 不匹配的迟到 chunk 被丢弃。
### M8 校验工具与文档(设计 §10)
1. `verify_tools.py --subset <tools.json> [token] [port] [--readonly]`:
抓 Go 服务端 `tools/list`,与 `tools.json` 同名工具逐字段比 `description` / `inputSchema` /
`outputSchema`(与 `verify_tools.py` 的 `FIELDS` 口径一致);名字集合必须恰好等于
期望的 9(或 7),多一个少一个都失败。
2. 同批更新:`deploy/yama-server.env.example` 加 `YAMA_MCP_TOKEN` / `YAMA_MCP_READONLY` /
`YAMA_MCP_TERM_IDLE` / `YAMA_MCP_MAX_CONCURRENCY` / `YAMA_MCP_READ_MAX`;
设计文档状态改"已实施"。
---
## 4. 测试与验证
### 4.1 三档测试
| 档 | 跑什么 | 覆盖 | 何时跑 |
|---|---|---|---|
| 1 纯函数单测 | 清洗三段、哨兵、环形缓冲、解析器、路径校验、schema 校验、JSON-RPC | 全部逻辑分支 | 每次提交 |
| 2 假设备集成(进程内) | 真 `hub` + 假设备 ctx + `httptest` 的 `/mcp` | 九工具端到端、并发、取消、审计 | 每次提交 |
| 3 真客户端 smoke | `x64\Debug\ghost.exe`(§4.3)或 Linux ghost → 本机 Go 服务端 | 真实 PTY/文件/截屏链路 | 每个里程碑收尾 + 整体验收 |
档 2 是主力:不依赖网络、可在 CI 跑,且能精确控制入站包的字节。
### 4.2 假设备 harness(`mcp/harness_test.go`)
```go
h := hub.New()
sent := make(chan []byte, 16) // 出站包,带缓冲 channel 避免数据竞争
h.SetSender(func(ctx *connection.Context, data []byte) error {
sent <- append([]byte(nil), data...); return nil
})
cfg := logger.DefaultConfig(); cfg.Level = logger.LevelError
mcpSrv := mcp.New(mcpCfg, h, history, logger.New(cfg))
unsubscribe := h.Subscribe(mcpSrv) // Subscribe 返回退订闭包(hub 没有 Unsubscribe 方法)
ts := httptest.NewServer(http.HandlerFunc(mcpSrv.Handle))
// 假设备:拿到 sent 里的 COMMAND_SHELL 后,模拟回 TOKEN_TERMINAL_START 与输出:
mcpSrv.OnPacket(devCtx, append([]byte{protocol.TokenTerminalStart}, ...))
h.PublishTerminalData(devID, []byte("hello\r\n__MCP_DONE_ab12cd__0\r\n"))
```
要点:
- 造设备:`h.Register(&hub.Device{ID:"dev", PeerIP:"10.0.0.1"}, devCtx)`;
`devCtx` 的 `Info.ClientID` 按子连接需要设置(模拟 `handleConnAuth` 的钉值)。
- `sent` 用带缓冲 channel(上面写法),测试里 `select` 带超时地读,不 sleep。
- 收尾:`defer unsubscribe()` + `defer mcpSrv.Close()`;再断言没有残留会话
(`mcpSrv.SessionCount()==0`,为此在会话表上留一个只读访问器给测试用)。
### 4.3 真客户端 smoke(M0 已实测,2026-11-12)
**结论:Windows 真客户端用 `x64\Debug\ghost.exe`,`TestRun.exe` 不可用。**
- `test.cpp` 用 `MemoryDllRunner` 加载同目录的 `ServerDll.dll`(`client/test.cpp:448`);
没有它时静默每 3 秒重试,Go 侧也没有这条内存 DLL 链路。
- Release `TestRun.exe` 从非安装路径启动时 `RegisterStartup()` 返回 0 → `self_del()`
自删(`client/test.cpp:323-334`);M0 第一次尝试确实删掉了 `release\TestRun.exe`,
已用 Release 重建恢复(359936 → 425472 字节)。`-cmd=0` 绕不过安装流程。
- Release `ghost.exe` 同样会走安装流程(dst = `%ProgramData%\Windows Ghost\WinGhost.exe`),
因此本机测试统一用 Debug ghost:`RegisterStartup` 在 `_DEBUG` 下直接返回 1(`reg_startup.c:413`)。
**M0 实测记录**:
- 服务端 `Bin\YamaGo_x64.exe -port 16543 -http-port 18090`(18080 被 python/wslrelay 占用),
`YAMA_DEVICES_FILE` 指向临时文件;默认签名模式 **TRIAL**(`https://web.just-do-it.icu:8080`)。
- `x64\Debug\ghost.exe 127.0.0.1 16543` → 10 秒内设备上线:
`event=device.online computer=A6/default device_id=445427540237756328 os="Windows 11"`,
`devices.json` 写入 `first_seen/last_seen`,服务端无错误日志。
- 清理:Debug ghost 的 `SetSelfStart` 会在 `HKCU\...\Run` 写一条哈希名,按运行前快照删除新增项;
用户既有的 `Client Demo` 计划任务与 `C:\ProgramData\Client Demo\ClientDemo.exe` 未被改动。
- 待办:trial 签名下客户端是否解锁屏幕/文件能力,要在 M5/M6 端到端确认
(`YAMA_LICENSE_DISABLED=1` 的 NoOp 已知会被客户端拒绝)。
```powershell
cd C:\github\YAMA
.\build.ps1 -GoServer -Config Debug
$msb = "C:\Program Files\Microsoft Visual Studio\18\Insiders\MSBuild\Current\Bin\MSBuild.exe"
& $msb client\ghost_vs2015.vcxproj -p:Configuration=Debug -p:Platform=x64 -p:SolutionDir=C:/github/YAMA/ -m -v:m
$env:YAMA_MCP_TOKEN="<32hex>"; $env:YAMA_DEVICES_FILE="$env:TEMP\yama_m0\devices.json"
Start-Process .\Bin\YamaGo_x64.exe -ArgumentList '-port','16543','-http-port','18090'
Start-Process .\x64\Debug\ghost.exe -ArgumentList '127.0.0.1','16543'
curl -s -X POST localhost:18090/mcp -H "Authorization: Bearer $env:YAMA_MCP_TOKEN" ...
```
注意:Debug ghost 的 `Mprintf` 走 `TRACE`(`common/logger.h:379`),客户端侧没有日志文件,
验收以服务端 audit/日志为准。
### 4.4 与 MFC 的对照验收
同一批命令在两个后端各跑一遍,比对 `exit_code` 与清洗后的文本(不一致就是移植缺陷):
```
sc query AssemblyManager rem hello cmd /c echo abc
type C:\...\.env ping -n 30 127.0.0.1 for /L %i in (1,1,1000000) do @echo SPAM-%i
```
### 4.5 每个提交前必跑
```bash
cd server/go
gofmt -l . ; go vet ./... ; go test ./... ; go test -race ./mcp/...
go build ./cmd
```
MFC 侧测试:M0–M8 的改动全在 `server/go`、`tools/mcp_tools` 与文档,**没有触碰任何
C++ / 客户端文件**(`git diff --name-only 5f124fc..HEAD` 可证),因此原计划的
`verify_live_6555.py` 回归没有对象。注意:本机在跑的 Release `Yama_x64.exe` 是更早的
构建(`tools/list` 仍是 `list_online_hosts` 旧名),按约束未重启它;这与本次改动无关,
也不影响上述结论。
---
## 5. 整体验收(对齐设计 §11)
验收日期 2026-11-12。现场:`Bin\YamaGo_x64.exe -port 16543 -http-port 18090` +
`x64\Debug\ghost.exe`(Windows 11)+ WSL Ubuntu 24.04 ghost,临时 token/devices/audit。
- [x] 9 个工具全部可调用;`tools/list` 响应 < 24 KB
—— 22578 B(只读 18288 B);九个工具逐一实调通过
- [x] `terminal_exec` 连续 20 条命令零失败;超时后轮询取回完整输出
—— 同一会话 20 条 `echo ACCEPT_n` 全部取回哨兵(M4b 另有超时轮询实测)
- [x] 浏览器开着终端时 `terminal_exec` → `-32003`,人的会话不受影响
—— `session_test.go:192` 证明浏览器持租约时返回 `ErrTerminalBusy`,
`tools_term.go:273` 映射为 `-32003`;另有 `terminal_close` 不动浏览器租约的用例
- [x] `read_file` 读 `.env` 字节级一致,SHA-256 与远端 `sha256sum` 相同
—— Windows 与 WSL 两边分别实测(M7);本轮 CRLF/单引号样本再验一次
- [x] `get_screenshot` Windows / Linux 各一张,Linux 走 BGRX→JPEG
—— Windows 1024x304 JPEG 本轮实测;Linux 在 M5 实测(WSLg 下画面全黑是
Xwayland 的已知限制,屏幕子连接与 BGRX→JPEG 链路本身通过)
- [x] 审计每次 `mcp.tool.call` 一条,`device`/`tool`/`code`/`ms` 齐全
—— 本轮 30 条,样例含 `"device"`/`"tool"`/`"code"`/`"ms"`
- [x] `verify_tools.py --subset` 通过(9 个 / 只读 7 个两种模式)
—— 读写 9、`YAMA_MCP_READONLY=1` 7 均 PASS;两种反向错配均按预期 FAIL
- [x] `go test -race ./mcp/...` 无数据竞争
- [ ] `hub` 零改动 —— **不成立且不可取**:`hub` 新增 `SendToConn`(M6,往任意子连接
回包必须走编码器)与终端租约代数 `terminalGen` / `OpenTerminalSessionLease`
(M4a,防止失去租约的查看者关掉别人的 shell)。两项都是设计遗漏、实现阶段补的,
均有单测;`hub` 原有对外行为不变。
---
## 6. 风险(在设计 R1-R8 之上新增)
| # | 风险 | 影响 | 处置 |
|---:|---|---|---|
| R9 | `OnTerminalData` 在 TCP 读循环上阻塞 | 整个设备通道卡死(浏览器画面/终端一起停) | 只做内存追加与唤醒;缓冲满丢最旧;禁止在回调里调用 `hub` 的会加锁方法 |
| R10 | 文件子连接 ctx 生命周期 | 客户端中途断开 → 后续发送到已关闭 ctx / pending 表泄漏 | pending 表带超时与 `OnDisconnect` 清理;发送失败即失败收尾 |
| R11 | `103/104` 常量与主连接 token 相邻 | 值写错会把登录包当文件列表(反之亦然) | 常量唯一性单测 + 解析前校验最小长度 |
| R12 | Windows 路径与 `filepath.Rel` | 路径穿越(被控端写主控任意位置) | 单测覆盖 `..`/绝对路径/UNC/混合分隔符;拒 NUL 与换行 |
| R13 | 客户端断开(`r.Context()`)后锁未释放 | 设备永久 `-32003` | `defer` 释放;单测用 cancel 验证 |
| R14 | 单测 goroutine 泄漏 | `-race` 偶发失败 | `Close()` 幂等;测试里 `defer Close()` |
| R15 | 真机 smoke 用 Debug ghost,与 Release 客户端有差异 | 安装/许可行为可能在 Release 上不同,本地验收未覆盖 | M0 已确认 Debug ghost 可上线;M5/M6 用 trial 签名验证屏幕/文件能力;交付说明写明该差异 |
---
## 7. 工时估算
| 里程碑 | 编码 | 测试 | 小计 |
|---|---:|---:|---:|
| M1 | 3h | 3h | 6h |
| M2 | 6h | 4h | 10h |
| M3 | 2h | 2h | 4h |
| M4a | 4h | 2h | 6h |
| M4b | 5h | 3h | 8h |
| M4c | 1h | 1h | 2h |
| M5 | 4h | 2h | 6h |
| M6 | 5h | 3h | 8h |
| M7 | 6h | 4h | 10h |
| M8 | 2h | 1h | 3h |
| 整体联调 + 真机验收 | — | — | 6h(含在 §5) |
| **合计** | **38h** | **25h** | **≈63h ≈ 8 人日** |
---
## 附录 A:`protocol/commands.go` 新增常量
| 常量 | 值 | 方向 | 里程碑 |
|---|---:|---|---|
| `CommandListDrive` | 1 | S→C 主连接 | M6 |
| `CommandListFiles` | 2 | S→C 文件子连接 | M6 |
| `CommandSendFileV2` | 85 | C→S V2 子连接 | M7 |
| `CommandFileCompleteV2` | 91 | C→S V2 子连接 | M7 |
| `CmdDownFilesV2` | 94 | S→C 文件子连接 | M7 |
| `TokenDriveList` | 103 | C→S 文件子连接 | M6 |
| `TokenFileList` | 104 | C→S 文件子连接 | M6 |
| `TokenFileListError` | 171 | C→S 文件子连接 | M6 |
| `CommandScreenPreviewReq` | 247 | S→C 主连接 | M5 |
| `TokenScreenPreviewRsp` | 248 | C→S 主连接 | M5 |
## 附录 B:环境变量
| 变量 | 默认 | 说明 | 引入里程碑 |
|---|---|---|---|
| `YAMA_MCP_TOKEN` | 空(端点不注册) | 32 位十六进制静态令牌 | M1 |
| `YAMA_MCP_READONLY` | 0 | 隐藏 `terminal_exec` / `terminal_close` | M1 |
| `YAMA_MCP_TERM_IDLE` | 180 | 终端会话空闲回收秒数 | M4c |
| `YAMA_MCP_MAX_CONCURRENCY` | 16 | 全局并发上限 | M3 |
| `YAMA_MCP_READ_MAX` | 2097152 | `read_file` 大小门(字节) | M7 |
## 附录 C:提交前自检清单(每个里程碑)
1. `gofmt -l .` 无输出;`go vet ./...` 干净。
2. `go test ./...` 与 `go test -race ./mcp/...` 全绿。
3. 新增的每个错误码都有触发它的单测(错误码不是装饰)。
4. 新增的每条审计事件都能在临时审计文件里被 `get_audit_log` 查到。
5. 提交标题用 `Feature(Go):` / `Fix(Go):`,正文说明"为什么",trailer 用当前会话模型名。
6. 未推送前发现问题用 `--amend`/squash,不堆补丁提交。