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
This commit is contained in:
1 parent
425d737ca0
commit
5f124fcb3a
2 files changed
+1322
No files matched your search
@@ -0,0 +1,799 @@
|
||||
# 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`
|
||||
|
||||
```jsonc
|
||||
// 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`
|
||||
|
||||
```jsonc
|
||||
{ "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`
|
||||
|
||||
```jsonc
|
||||
{} // 无参
|
||||
```
|
||||
返回 `{ 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`
|
||||
|
||||
```jsonc
|
||||
{ "keyword": "terminal", "type": "mcp", "since": "2026-11-12T00:00:00Z", "limit": 100, "offset": 0 }
|
||||
```
|
||||
复用 `web/audit_query.go` 的查询器,返回 `{ total, returned, records[] }`。
|
||||
|
||||
#### `get_screenshot`
|
||||
|
||||
```jsonc
|
||||
{ "id": "...", "max_width": 1600 }
|
||||
// output: content[] 里一项 image(mimeType=image/jpeg, base64 data)
|
||||
// structuredContent: { width, height, bytes, format, source: "preview" }
|
||||
```
|
||||
细节见 §7。
|
||||
|
||||
#### `terminal_exec`
|
||||
|
||||
```jsonc
|
||||
// 执行
|
||||
{ "id": "...", "command": "sc query AssemblyManager", "timeout_ms": 20000, "session_id": "..." }
|
||||
// 轮询(不带 command)
|
||||
{ "id": "...", "session_id": "s-3f2a", "timeout_ms": 20000 }
|
||||
// output
|
||||
{ "session_id": "s-3f2a", "output": "...", "exit_code": 0, "done": true,
|
||||
"offset": 1843, "truncated": false, "is_pty": true, "reused": false }
|
||||
```
|
||||
超时未完成时 `done=false`、无 `exit_code`、`output` 是已产生的部分输出,**会话保留**。
|
||||
|
||||
#### `terminal_close`
|
||||
|
||||
```jsonc
|
||||
{ "session_id": "s-3f2a" } // 幂等:会话不存在也返回成功
|
||||
```
|
||||
|
||||
#### `list_files`
|
||||
|
||||
```jsonc
|
||||
{ "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`
|
||||
|
||||
```jsonc
|
||||
{ "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 里加一行:
|
||||
|
||||
```go
|
||||
mux.HandleFunc("/mcp", s.mcp.Handle)
|
||||
```
|
||||
|
||||
**不能复用 `s.requireBearer`**:它校验的是浏览器会话令牌(`s.auth.ValidateToken`),
|
||||
MCP 用的是独立的静态令牌,两套凭据语义不同。鉴权在 `mcp.Handle` 内部自己做
|
||||
(§4.2)。`basePath` 由 `s.mount` 统一处理,`/mcp` 不需要自己感知前缀。
|
||||
|
||||
协议形态:
|
||||
|
||||
| 项 | 取值 |
|
||||
|---|---|
|
||||
| 协议版本 | `2025-06-18`(与 MFC `tools.json` 的 `protocolVersion` 一致) |
|
||||
| 会话 | **无状态**。不生成、不校验 `Mcp-Session-Id` |
|
||||
| `POST` 响应 | `Content-Type: application/json`,单条 JSON-RPC 响应 |
|
||||
| `GET /mcp` | `405 Method Not Allowed`(v1 无服务端主动推送流;MCP 规范允许此返回) |
|
||||
| `DELETE /mcp` | `405` |
|
||||
| 批量请求 | 不支持(数组入参返回 `-32600`) |
|
||||
| 通知(无 `id`) | 一律 `204 No Content`,不返回体 |
|
||||
|
||||
无状态的代价是**没有 `notifications/progress` / `notifications/cancelled`**。
|
||||
取消靠 HTTP 请求断开——`r.Context()` 被取消时,处理函数释放设备锁、终端会话按
|
||||
§6.6 处理(不销毁)。这与 MFC 的 `-32800 请求被取消` 语义对齐。
|
||||
|
||||
### 4.2 令牌
|
||||
|
||||
```
|
||||
YAMA_MCP_TOKEN=<32 位十六进制> # 必填;未设置 = MCP 端点不注册(/mcp 返回 404)
|
||||
YAMA_MCP_READONLY=1 # 可选,只读模式(隐藏 terminal_exec / terminal_close)
|
||||
YAMA_MCP_TERM_IDLE=180 # 可选,终端会话空闲回收秒数
|
||||
YAMA_MCP_MAX_CONCURRENCY=16 # 可选,全局并发上限
|
||||
YAMA_MCP_READ_MAX=2097152 # 可选,read_file 文件大小门(字节,默认 2 MiB)
|
||||
```
|
||||
|
||||
- 未设置时**不注册路由**,并在启动日志打一行 `MCP endpoint disabled: YAMA_MCP_TOKEN not set`。
|
||||
不自动生成——生成的令牌若只落在日志里,等于没有密钥管理。
|
||||
- 比较用 `subtle.ConstantTimeCompare`,长度不等直接失败(不 leak 长度)。
|
||||
- principal 固定为 `{actor: "mcp", role: "admin"}`。审计记录里 `actor=mcp`,
|
||||
`source=mcp`,与浏览器会话(`actor=<username>`)可区分。
|
||||
- 不做失败计数封禁:令牌是 32 位十六进制(128 bit),且端点不对外暴露时无爆破面。
|
||||
若将来暴露到公网,按 `web/ws_handlers.go` 的登录节流同款加计数(记入 §12 R6)。
|
||||
|
||||
### 4.3 错误码
|
||||
|
||||
与 MFC 完全对齐(`McpServer.cpp:296-312` 的官方说明),Go 侧只实现用得到的:
|
||||
|
||||
| 码 | 语义 | Go 侧触发点 |
|
||||
|---:|---|---|
|
||||
| `-32001` | 超时 | 等子连接/等响应超时;`done=false` 不算此码 |
|
||||
| `-32002` | 主机离线或不存在 | `hub.IsOnline` 为假 |
|
||||
| `-32003` | 主机忙 | 设备锁被占 / 终端槽位被浏览器持有 |
|
||||
| `-32004` | 命令未送达 | `hub.SendToDevice` 返回错误 |
|
||||
| `-32005` | 主机不支持该能力 | 缺 `CLIENT_CAP_SCREEN_PREVIEW`(截屏);非 PTY 客户端用 `terminal_exec` |
|
||||
| `-32006` | 策略拒绝 | 只读模式下调用写工具 |
|
||||
| `-32009` | 目标不存在 | `list_files` 的 `TOKEN_FILE_LIST_ERROR` 且 win32err∈{2,3} |
|
||||
| `-32010` | 权限不足 | `TOKEN_FILE_LIST_ERROR` 且 win32err=5 |
|
||||
| `-32602` | 参数错误 | schema 校验失败 |
|
||||
| `-32601` | 方法不存在 | 未知 method / 未知工具名 |
|
||||
| `-32000` | 内部错误 | 其余 |
|
||||
|
||||
### 4.4 审计
|
||||
|
||||
每次 `tools/call` 产出一条记录,字段沿用 `web/audit.go` 的形状:
|
||||
|
||||
```
|
||||
event=mcp.tool.call actor=mcp role=admin source=mcp
|
||||
tool=<name> device=<id|-> ok=<bool> code=<err|0> ms=<duration>
|
||||
args=<截断到 512 字节的摘要> result=<ok 时的体积摘要 / 失败时的 message>
|
||||
```
|
||||
|
||||
`args` 里的敏感值(`command` 全文可能含密码)**不入审计**——只记命令首词与长度,
|
||||
与 MFC 的做法一致(MFC 审计只记 `host <id> <tool>`)。完整命令进 `debug` 级日志。
|
||||
|
||||
---
|
||||
|
||||
## 5. 四条设备通道
|
||||
|
||||
```
|
||||
MCP client ──HTTP POST /mcp──▶ mcp.Server
|
||||
├─ 本机:hub.ListDevices / devicehistory / audit_query
|
||||
├─ 主连接 RPC SendToDevice(247) ─────────▶ 设备主连接
|
||||
├─ 终端 OpenTerminalSession ───────▶ 终端子连接
|
||||
├─ 文件管理器 COMMAND_LIST_DRIVE(1) ─────▶ 文件管理器子连接
|
||||
└─ V2 CMD_DOWN_FILES_V2(94) ─────▶ V2 流式子连接
|
||||
```
|
||||
|
||||
### 5.1 主连接 RPC(`get_screenshot`)
|
||||
|
||||
请求走 `hub.SendToDevice(deviceID, pkt)`,响应在 `cmd/main.go` 的 `OnReceive`
|
||||
里按 `data[0] == TOKEN_SCREEN_PREVIEW_RSP` 分派。**不走子连接,不占任何槽位。**
|
||||
|
||||
需要一个请求表:
|
||||
|
||||
```go
|
||||
type pendingRPC struct {
|
||||
reqID uint16
|
||||
ch chan []byte // 缓冲 1,迟到的响应写不进去就丢弃
|
||||
}
|
||||
m := map[uint64]*pendingRPC{} // key = deviceID(每设备同时只允许一个,与设备锁一致)
|
||||
```
|
||||
|
||||
`reqID` 用 `atomic.Uint32` 自增后取低 16 位;**必须校验响应里的 `reqId` 与在途请求一致**,
|
||||
否则丢弃——MFC 的 `TakePreviewResponse(devId, reqId, ...)` 就是干这个的
|
||||
(`2015RemoteDlg.cpp:7520`),原因是主连接上可能同时有别的预览在飞。
|
||||
|
||||
### 5.2 终端子连接(`terminal_exec` / `terminal_close`)
|
||||
|
||||
完全复用 `hub` 现有设施,**不改 hub**:
|
||||
|
||||
| 动作 | 调用 |
|
||||
|---|---|
|
||||
| 开会话 | `hub.OpenTerminalSession(deviceID)`;已存在返回 `ErrTerminalBusy` |
|
||||
| 等就绪 | 订阅 `EventHandler.OnTerminalReady(deviceID, isPTY)` |
|
||||
| 发输入 | `hub.SendToTerminal(deviceID, bytes)`;行尾按 §6.4 区分 `\n` / `\r\n` |
|
||||
| 收输出 | 订阅 `EventHandler.OnTerminalData(deviceID, packet)`,剥掉 4 字节 `TRM1` 前缀 |
|
||||
| 关会话 | `hub.CloseTerminalSession(deviceID)` |
|
||||
|
||||
`mcp.Server` 在启动时 `hub.Subscribe(self)` 一次,作为常驻订阅者;
|
||||
只有"当前有 MCP 终端会话的设备"才把数据写进环形缓冲,其余直接丢弃(零开销)。
|
||||
|
||||
### 5.3 文件管理器子连接(`list_files`)
|
||||
|
||||
时序:
|
||||
|
||||
```
|
||||
MCP ──▶ 主连接: COMMAND_LIST_DRIVE(1) [1 字节]
|
||||
客户端 ──▶ 新子连接(EnableSubConnAuth)
|
||||
└─ TOKEN_CONN_AUTH(246) ──▶ Go: 校验 + 把 clientID 钉在 ctx 上 + 回 ack
|
||||
└─ TOKEN_DRIVE_LIST(103) ──▶ Go: 解析盘符(子连接保持打开)
|
||||
MCP ──▶ 同一子连接: COMMAND_LIST_FILES(2) [cmd][path\0]
|
||||
└─ TOKEN_FILE_LIST(104) ──▶ Go: 解析目录项
|
||||
或 TOKEN_FILE_LIST_ERROR(171) ──▶ Go: 按 win32err 翻译
|
||||
└─ Go: 关子连接(COMMAND_BYE → 500ms → Close)
|
||||
```
|
||||
|
||||
注意 `TOKEN_DRIVE_LIST` 到达后**不能立刻关子连接**——列目录还要在同一个子连接上发
|
||||
`COMMAND_LIST_FILES`。MFC 的注释写得很明确:*此时不关子链接,交给 TOKEN_FILE_LIST
|
||||
分支收尾*(`2015RemoteDlg.cpp:7647`)。
|
||||
|
||||
关键点:
|
||||
|
||||
- **子连接带 ConnAuth**(`client/KernelManager.cpp:1773` 对 `COMMAND_LIST_DRIVE`
|
||||
调了 `EnableSubConnAuth()`),所以 `handleConnAuth` 已把 `ClientID` 钉在 ctx 上,
|
||||
Go **不需要** MFC 那套 `IsPending(devId)` 守卫。按 `ctx.GetInfo().ClientID` 路由即可。
|
||||
- 子连接由客户端创建、**由服务端关闭**(MFC 注释:*此时不关子链接,交给
|
||||
TOKEN_FILE_LIST 分支收尾*)。关闭用 `hub` 同款优雅关闭:发 `COMMAND_BYE(204)`,
|
||||
500 ms 后 `ctx.Close()`。
|
||||
- `TOKEN_DRIVE_LIST` 与 `TOKEN_FILE_LIST` 的记录格式见附录 A,直接照 MFC 的
|
||||
`ParseDriveList` / `ParseFileList`(`McpServer.cpp:506/548`)移植。
|
||||
- 文件名是**客户端 ANSI**,用 `protocol.DecodeClientString(data, hub.Capability(id), "")` 解码。
|
||||
|
||||
### 5.4 V2 流式子连接(`read_file`)
|
||||
|
||||
时序:
|
||||
|
||||
```
|
||||
MCP ──▶ 主连接: COMMAND_LIST_DRIVE(1)
|
||||
└─ 文件管理器子连接建立(同 §5.3)
|
||||
MCP ──▶ 文件管理器子连接: CMD_DOWN_FILES_V2(94) [cmd][targetDir\0][path\0][\0]
|
||||
└─ 服务端关掉文件管理器子连接
|
||||
客户端 ──▶ 新子连接(EnableSubConnAuth)
|
||||
└─ COMMAND_SEND_FILE_V2(85) × N ──▶ Go: 校验路径 → 落盘
|
||||
└─ COMMAND_FILE_COMPLETE_V2(91) ──▶ Go: 校验 SHA-256 → 完成
|
||||
MCP: 读临时文件 → 返回 → 删临时目录
|
||||
```
|
||||
|
||||
- `targetDir` 是**主控本机**的保存目录,由服务端指定;客户端把它拼进每个 chunk 的
|
||||
`filename` 回填。所以服务端必须用一个**每次请求新建的临时目录**
|
||||
(`os.MkdirTemp("", "yama-mcp-read-*")`),并在 `defer` 里 `RemoveAll`。
|
||||
- **路径校验是硬性安全要求**:`filename` 由客户端提供,必须校验它落在 `targetDir` 之内
|
||||
(**用 `filepath.Rel` 判越界,不能用字符串前缀比较**,见 §8.3),否则拒收并中止传输。
|
||||
没有这一步,被控端可以把任意文件写到主控磁盘任意位置。
|
||||
- **没有可用的能力门**。`CLIENT_CAP_V2` 在 `common/commands.h:1289` 的
|
||||
`DefaultCaps()` 里被**所有平台无条件声明**,拿它做门等于没门。MFC 侧的 V2 是
|
||||
**服务端开关**(`2015RemoteDlg.cpp:2822` 的 `EnableFileV2`,默认关),不是客户端能力。
|
||||
Go 侧不设这个开关,恒用 V2。
|
||||
- 真正的失败模式是**老客户端不认识 94 号命令**:它收到 `CMD_DOWN_FILES_V2` 后
|
||||
不建子连接、不回任何包,表现为 `-32001` 超时。工具描述里要写明这条,
|
||||
避免模型反复重试。
|
||||
|
||||
---
|
||||
|
||||
## 6. 终端会话
|
||||
|
||||
### 6.1 会话对象
|
||||
|
||||
```go
|
||||
type termSession struct {
|
||||
id string // "s-" + 6 位 hex
|
||||
deviceID string
|
||||
isPTY bool
|
||||
createdAt time.Time
|
||||
lastUsed time.Time
|
||||
|
||||
mu sync.Mutex
|
||||
buf []byte // 环形,cap 256 KiB
|
||||
base uint64 // buf[0] 的绝对偏移
|
||||
total uint64 // 累计写入字节
|
||||
delivered uint64 // 已交付给客户端的绝对偏移
|
||||
|
||||
pending *pendingCmd // 在途命令;nil = 空闲
|
||||
}
|
||||
|
||||
type pendingCmd struct {
|
||||
sentinel string
|
||||
deadline time.Time
|
||||
done bool
|
||||
exitCode int
|
||||
raw []byte // 从 sentinel 之前回切出的原始片段
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 租约与争用
|
||||
|
||||
- `hub.OpenTerminalSession` 本身就是互斥(`ErrTerminalBusy`),MCP 直接复用它。
|
||||
- 撞上 `ErrTerminalBusy` → `-32003`,message 写
|
||||
`terminal busy: another viewer (web console or another MCP call) holds it; retry later`。
|
||||
- **v1 不做抢占**。理由:抢占会把正在敲命令的人踢下线,而模型无法判断"人是不是在忙"。
|
||||
需要抢占时由运维在 Web 控制台关掉那个终端。
|
||||
- 空闲释放:`lastUsed` 超过 `YAMA_MCP_TERM_IDLE`(默认 180 s)由后台 ticker 调
|
||||
`CloseTerminalSession`。这是防止模型忘了 `terminal_close` 把人的终端锁死。
|
||||
|
||||
### 6.3 环形缓冲与游标
|
||||
|
||||
- 容量 256 KiB,超出丢弃最旧数据,`base` 前移,丢弃量记 `droppedBytes` 并在
|
||||
返回体里体现(`truncated=true`)。
|
||||
- 绝对偏移 `total` 单调递增,`offset` 参数与返回里的 `offset` 都用绝对偏移。
|
||||
- 缓冲随会话存在:会话关闭(`terminal_close` / 空闲回收 / 设备掉线)时整体释放。
|
||||
|
||||
### 6.4 哨兵与退出码
|
||||
|
||||
沿用 MFC 的两种形态(`McpServer.cpp:3991-3998`),**必须分两行下发**:
|
||||
|
||||
| 客户端 | 下发 | 哨兵 |
|
||||
|---|---|---|
|
||||
| POSIX PTY(Linux/Android) | `cmd\n` + `echo "__MCP_DONE_<id>__$?"\n` | `__MCP_DONE_<id>__<n>` |
|
||||
| ConPTY(新 Windows) | `cmd\r\n` + `echo __MCP_DONE_<id>__%errorlevel%\r\n` | 同上 |
|
||||
|
||||
为什么要分两行:`rem` / `cmd` / `exit` / `if` / `for` 这类"吞行"命令会把同一行后面的
|
||||
内容一起吞掉(MFC 的 P1 教训)。分两行后哨兵独立执行,退出码才可信。
|
||||
|
||||
`<id>` 用 6 位随机 hex,每次命令重新生成——避免上一条命令的输出里残留同名哨兵被误命中。
|
||||
|
||||
### 6.5 输出清洗
|
||||
|
||||
三段清洗,顺序不能变(MFC `McpServer.cpp:3946-4040`):
|
||||
|
||||
1. **剥回显**:PTY 会把输入整行回显。删掉命令行本身与哨兵行。
|
||||
2. **剥 ANSI**:`\x1b[...m`、`\x1b[?25h/l` 等 CSI/OSC 序列。
|
||||
3. **剥哨兵**:把哨兵文本及其后的退出码切掉,`exit_code` 单独解析。
|
||||
|
||||
ConPTY 是"屏幕渲染流"而不是字节流,光标重绘会让同一行出现两次,剥完 VT 后
|
||||
文字会重复(MFC 实测 `rem hello` 只剩哨兵、`cmd /c echo abc` 变成
|
||||
`abc__MCP_DONE_x__0`)。**这三段必须整体移植,不能自己重写**——这是踩过坑的代码。
|
||||
|
||||
### 6.6 轮询模式
|
||||
|
||||
`terminal_exec` 不带 `command`、只带 `session_id` 时进入轮询:从 `delivered` 开始
|
||||
取增量,等到 `done` 或超时。
|
||||
|
||||
- 超时**不销毁会话**(MFC 优化的核心结论):命令可能还在跑,销毁等于毁掉现场
|
||||
(cwd、环境变量、后台任务)。MFC 在优化前两次 `-32002` 都是这么来的。
|
||||
- HTTP 请求被客户端断开(`r.Context()` done)时同样只标记放弃,不动会话。
|
||||
- 会话内已有在途命令时,再带 `command` 调用 → `-32003`(同一会话单命令)。
|
||||
|
||||
### 6.7 平台范围
|
||||
|
||||
**v1 只支持 PTY 客户端**(ConPTY / POSIX PTY)。老的非 PTY cmd-pipe 路径
|
||||
(`TOKEN_SHELL_START(128)`)在 `OnTerminalReady` 里能识别(`isPTY=false`),
|
||||
此时 `terminal_exec` 直接返回 `-32005` 并在 message 里说明"该客户端版本不支持"。
|
||||
|
||||
理由:非 PTY 路径的回显跳过依赖"按写入长度跳过",且单行哨兵会被吞行命令吃掉,
|
||||
Go 侧没有实测数据支撑,先不开放比做错好。
|
||||
|
||||
若客户端根本不支持 shell(`COMMAND_SHELL` 发出后迟迟没有子连接),
|
||||
`OpenTerminalSession` 会一直停在 pending,表现为 `-32001` 超时。这里**不设能力门**——
|
||||
`CLIENT_CAP_TERMINAL` 只有新版 Android 声明,Windows/Linux 一直支持却不声明
|
||||
(`common/commands.h:151` 的注释),拿它做门会误拒所有桌面客户端。message 里加一句
|
||||
"若反复超时,可能该客户端版本不支持远程 shell"。
|
||||
|
||||
---
|
||||
|
||||
## 7. `get_screenshot`
|
||||
|
||||
### 7.1 为什么不用屏幕流
|
||||
|
||||
屏幕流是 H.264:`TOKEN_FIRSTSCREEN(116)` 是裸 BGRA 首帧,之后全是
|
||||
`TOKEN_NEXTSCREEN(117)` / `TOKEN_KEYFRAME(134)` 的编码帧。**不采用首帧方案**,原因不是
|
||||
解码(首帧本来就是裸的),而是**代价**:拿首帧必须先发 `COMMAND_SCREEN_SPY` 建立屏幕
|
||||
子连接、等客户端绑定、等首帧到达,用完还要拆——它占着每设备唯一的屏幕会话槽位,
|
||||
和正在看画面的人直接冲突,而且拆不干净就会一直推流。
|
||||
|
||||
`COMMAND_SCREEN_PREVIEW_REQ(247)` 是**主连接 RPC**:客户端自己抓屏、自己缩放、
|
||||
自己编码 JPEG 回包(`TOKEN_SCREEN_PREVIEW_RSP(248)`),不建子连接、不占槽位、
|
||||
一次请求一次响应。这是 MFC `get_screenshot` 的既有实现
|
||||
(`McpServer.cpp:2199`、`2015RemoteDlg.cpp:10449`),Go 照做即可。
|
||||
|
||||
### 7.2 请求 / 响应
|
||||
|
||||
```c
|
||||
struct ScreenPreviewReq { // 8 字节
|
||||
uint8_t cmd; // 247
|
||||
uint16_t reqId;
|
||||
uint16_t maxWidth;
|
||||
uint8_t jpegQuality; // 1..100
|
||||
uint16_t reserved;
|
||||
};
|
||||
|
||||
struct ScreenPreviewRspHeader { // 16 字节
|
||||
uint8_t token; // 248
|
||||
uint16_t reqId;
|
||||
uint8_t status; // 0=OK 1=抓屏失败 2=编码失败 3=不支持 4=目标无效
|
||||
uint8_t format; // 0=JPEG 3=BGRX
|
||||
uint16_t width, height;
|
||||
uint32_t bytes;
|
||||
uint8_t reserved[3];
|
||||
// 后接 data[bytes],可选再跟 ScreenCaptureMeta
|
||||
};
|
||||
```
|
||||
|
||||
v1 只发 8 字节基础请求(等价于整虚拟桌面),**不发 v2 扩展**——`region/window/monitor`
|
||||
需要 `CLIENT_CAP_SCREEN_REGION`,属后续增强。
|
||||
|
||||
参数映射:`max_width` 默认 1600,钳制到 `[320, 3840]`;`jpegQuality` 固定 80。
|
||||
|
||||
### 7.3 BGRX → JPEG
|
||||
|
||||
Linux 客户端没有 JPEG 编码库,回 `format=3`(BGRX,自上而下逐行、每像素 4 字节
|
||||
`B,G,R,X`,无行填充,`bytes == width*height*4`)。Go 用标准库转:
|
||||
|
||||
```go
|
||||
img := image.NewRGBA(image.Rect(0, 0, w, h))
|
||||
for i := 0; i < w*h; i++ {
|
||||
img.Pix[i*4+0] = src[i*4+2] // R ← B
|
||||
img.Pix[i*4+1] = src[i*4+1] // G
|
||||
img.Pix[i*4+2] = src[i*4+0] // B ← R
|
||||
img.Pix[i*4+3] = 0xFF
|
||||
}
|
||||
jpeg.Encode(&buf, img, &jpeg.Options{Quality: 80})
|
||||
```
|
||||
|
||||
`bytes != w*h*4` 时按畸形包丢弃(返回 `-32000`)。
|
||||
|
||||
### 7.4 能力门与超时
|
||||
|
||||
- 缺 `CLIENT_CAP_SCREEN_PREVIEW(0x0004)` → `-32005`。
|
||||
MFC 同款门(描述里写明"老客户端返回 -32005")。
|
||||
- 超时 8 s。**不做取消**:MFC 明确写了"屏幕预览 = 主连接 RPC,不能 CancelIO"
|
||||
(`2015RemoteDlg.cpp:7514`)。超时后把请求表项删掉,迟到的响应按 `reqId` 不匹配丢弃。
|
||||
- 响应 `status != 0` 时按码翻译:1/2 → `-32000`(带 status 文案),3 → `-32005`,
|
||||
4 → `-32602`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 文件工具
|
||||
|
||||
### 8.1 `list_files`
|
||||
|
||||
见 §5.3。解析细节:
|
||||
|
||||
- `TOKEN_DRIVE_LIST`:`[token][letter:1][type:1][totalMB:4][freeMB:4][typeName\0][fileSystem\0]` 循环,
|
||||
`letter=='\0'` 终止。
|
||||
- `TOKEN_FILE_LIST`:`[token]([attr:1][name\0][sizeHigh:4][sizeLow:4][ftLow:4][ftHigh:4])*`,
|
||||
空名终止(尾部零填充)。`attr & 0x10` 为目录。
|
||||
- `TOKEN_FILE_LIST_ERROR`:`[token][win32err:4 LE]`,按 §4.3 映射。这是**新客户端**才有的
|
||||
失败回执;老客户端路径不存在时直接不回包,表现为 `-32001` 超时(message 里要提示
|
||||
"路径可能不存在,先用 list_files 确认")。
|
||||
|
||||
`total` 与 `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` 由客户端提供。必须:
|
||||
|
||||
```go
|
||||
clean := filepath.Clean(filepath.Join(targetDir, filepath.FromSlash(name)))
|
||||
rel, err := filepath.Rel(targetDir, clean)
|
||||
if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) {
|
||||
abortTransfer() // 拒收并中止
|
||||
}
|
||||
```
|
||||
|
||||
`filepath.HasPrefix` 字符串前缀比较不够——`/tmp/ab` 会匹配 `/tmp/abc`。用 `filepath.Rel` 判越界。
|
||||
|
||||
同理 `list_files` 的 `path` 与 `read_file` 的 `path` 不做本地校验(它们在远端),
|
||||
但**不允许包含 NUL 与换行**——那会截断/拆开 C 字符串协议字段。
|
||||
|
||||
---
|
||||
|
||||
## 9. 并发、配额、生命周期
|
||||
|
||||
| 项 | 规则 |
|
||||
|---|---|
|
||||
| 每设备单请求 | `map[deviceID]*sync.Mutex` 的 `TryLock`;占用返回 `-32003`,message 带占用工具名与已持续时长 |
|
||||
| 全局并发 | `YAMA_MCP_MAX_CONCURRENCY`(默认 16)信号量;超出直接 `-32003` |
|
||||
| 单次请求上限 | `terminal_exec` 120 s,`read_file` 120 s,`get_screenshot` 8 s,其余 10 s |
|
||||
| 设备锁释放 | `defer` 释放;HTTP ctx 取消也走同一条 defer |
|
||||
| 终端空闲回收 | ticker 30 s 扫一次,`lastUsed` 超 180 s 关闭 |
|
||||
| 进程退出 | `mcp.Server.Close()` 关闭所有终端会话(避免留下孤儿 shell 子连接) |
|
||||
|
||||
设备锁的粒度是"整台设备"而不是"每通道",与 MFC 一致(`-32003` 说明里写明
|
||||
"列表、截屏、文件、管理动作共用这一道锁")。理由是主连接 RPC 与子连接命令
|
||||
在客户端侧可能共用同一份状态,并发只会让现场更难读。
|
||||
|
||||
---
|
||||
|
||||
## 10. 代码结构与依赖方向
|
||||
|
||||
```
|
||||
server/go/mcp/
|
||||
server.go # /mcp handler、JSON-RPC 分发、鉴权、tools/list
|
||||
tools.go # 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` 零改动。
|
||||
@@ -0,0 +1,523 @@
|
||||
# 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 没有的(`authStatus/tls/location/install_time/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`:`{version,commit,uptime_s,devices_online,devices_offline_known,
|
||||
mcp:{readonly,tools}}`;`version`/`commit` 取 `buildinfo`(§1.2),`uptime` 用 `mcp.Config.StartedAt`。
|
||||
- `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` 与 `returned` 分离。
|
||||
- `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 字节)→ 读窗口(负 `offset` 从尾部倒数)→ 编码判定
|
||||
(`utf8.Valid` 优先,失败回退 `simplifiedchinese.GBK`,`latin1` 逐字节)→ 返回
|
||||
`{path,size,bytes_read,truncated,encoding,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`**(Go 不做);名字集合必须恰好等于期望的 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 侧测试(`%TEMP%\yama_step1_scripts\*`)本计划不改 C++ 代码,只在 M8 之后回归一次
|
||||
`verify_live_6555.py` 确认没被共享常量改动影响(本计划只加常量,理论上无影响)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 整体验收(对齐设计 §11)
|
||||
|
||||
- [ ] 9 个工具全部可调用;`tools/list` 响应 < 24 KB
|
||||
- [ ] `terminal_exec` 连续 20 条命令零失败;超时后轮询取回完整输出
|
||||
- [ ] 浏览器开着终端时 `terminal_exec` → `-32003`,人的会话不受影响
|
||||
- [ ] `read_file` 读 `.env` 字节级一致,SHA-256 与远端 `sha256sum` 相同
|
||||
- [ ] `get_screenshot` Windows / Linux 各一张,Linux 走 BGRX→JPEG
|
||||
- [ ] 审计每次 `mcp.tool.call` 一条,`device/tool/code/ms` 齐全
|
||||
- [ ] `verify_tools.py --subset` 通过(9 个 / 只读 7 个两种模式)
|
||||
- [ ] `go test -race ./mcp/...` 无数据竞争
|
||||
- [ ] `hub` 零改动(`git diff --stat server/go/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,不堆补丁提交。
|
||||
Reference in new issue
Block a user