Docs: revise MCP tool optimization plan against measured baseline
The v1 plan was written without measuring the live server. Re-measure and fix it against the code: - tools/list response is 193,008 B (tools array 136,692 B; description 31,874 / inputSchema 44,192 / outputSchema 49,320), not 103,158 B; the >=15% goal now refers to this baseline. - TermSession::sentPos is the sentinel offset, not a delivered cursor, so P0-2 introduces a real `delivered` cursor instead of reusing it. - The whitelist additions icacls / net user / net localgroup are writes under prefix matching; only sc qc / enumdepend / sdshow qualify. - "file too large" uses -32602, not the invented -32011 (destination write failure). - P0-3 gains four prerequisites (size pre-check, McpFileTransfer gate, RAII cleanup, sha256/lines_total semantics); P0-1 spells out the default-session slot hazard; the stage order is P0-4 first since it is the cheapest win. Appendix B records how the baseline was measured (verify_tools.py --live). Co-Authored-By: deepseek-flash
This commit is contained in:
1 parent
23fb50b7d4
commit
f5ac7ba45f
1 file changed
+567
@@ -0,0 +1,567 @@
|
||||
# MFC MCP 工具优化方案(基于 ASM 工位实操数据)
|
||||
|
||||
> 版本:v2(2026-11-12 评审后修订) 状态:待评审 日期:2026-11-12
|
||||
>
|
||||
> v1 → v2 的实质修正(均以代码/实测为准,修订处在段首标「v2」):
|
||||
> `tools/list` 基线改为实测 193,008 字节(v1 的 103,158 对不上任何历史版本);
|
||||
> P0-2 的前提「`sentPos` 是已发送偏移」不成立(它是哨兵在 `data` 中的位置),并补齐
|
||||
> 调用方 `CancelIO`、取消/超时分离、输出上限、busy 兜底四处实现细节;P0-4 白名单
|
||||
> 剔除 `icacls` / `net user` / `net localgroup`(三者在带参数时是写命令);P1-2 说明
|
||||
> 其实现仍需走 shell;P1-1/P2 的别名方案补齐平台表、instructions、网站页面等同步项。
|
||||
>
|
||||
> 数据来源:2026-11-12 一次完整的 7 机 ASM 工位故障处理 + 批量配置会话。
|
||||
> 该会话共 **186 次 MCP 调用**,63 个工具里实际用到 **9 个**。本文所有使用频次、
|
||||
> 命令分类、失败码都来自该会话的调用记录逐条统计,不是推断;凡属推断的地方会标注。
|
||||
>
|
||||
> 前置文档:`Mcp_Design.md`(协议/错误码)、`Mcp_Terminal_Design.md`(持久终端)、
|
||||
> `Mcp_Next_Plan.md`(P10 起的能力扩展)、`Mcp_Machine_Design.md`(会话抽象)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论摘要
|
||||
|
||||
1. **工具不缺,粒度不对。** 186 次调用里 109 次(58.6%)是 `terminal_exec`;按命令分类,
|
||||
118 条里有 59% 是「读」(读文件/日志 37%、查服务状态 14%、查注册表 4%、列目录 4%),
|
||||
这部分全部压在 `terminal_exec` 上;同时有 **30 个纯只读工具零调用**。原因是专用工具
|
||||
一个标签页一个、粒度太细,而真实故障处理是「一条命令拿三样东西」。
|
||||
2. **最大的单点浪费是会话管理。** `terminal_open` 20 次 + `terminal_close` 17 次 = **37 次调用(20%)**,
|
||||
零信息产出。其中 9 个会话只跑了 1 条命令,即 3 次调用换 1 条命令。
|
||||
3. **`terminal_exec` 超时会销毁会话,这是设计错误。** 命令超时说明进程可能还在跑,
|
||||
此时丢掉 shell 恰好毁掉全部现场(cwd、环境变量、后台任务)。本次两次 `-32002`
|
||||
都由此产生,每次都要重开会话并重跑命令。
|
||||
4. **`read_file` 是唯一真正的功能缺口。** 读文件靠 `type`(`exec_command`,5 次)和
|
||||
`Get-Content`/`Select-String`(`terminal_exec`,39 次),`.env` 对比还得 `download_file`
|
||||
落盘再本地解析。而「读」正是最高频的需求。
|
||||
5. **`exec_command` 的命令白名单在拦只读命令。** `sc qc AssemblyManager` 被拒(`-32007`),
|
||||
而 109 次不受白名单约束的 `terminal_exec` 畅通无阻——这个安全门在当前用法下不产生保护,
|
||||
只产生摩擦。根因是 `powershell` 完全不在白名单里,任何 PowerShell 一行都过不去。
|
||||
|
||||
---
|
||||
|
||||
## 1. 实测数据
|
||||
|
||||
### 1.1 工具使用分布(186 次调用 / 63 个工具)
|
||||
|
||||
| 调用数 | 工具 | 占比 |
|
||||
|---:|---|---:|
|
||||
| 109 | `terminal_exec` | 58.6% |
|
||||
| 20 | `terminal_open` | 10.8% |
|
||||
| 17 | `terminal_close` | 9.1% |
|
||||
| 10 | `list_files` | 5.4% |
|
||||
| 9 | `exec_command` | 4.8% |
|
||||
| 7 | `get_screenshot` | 3.8% |
|
||||
| 7 | `download_file` | 3.8% |
|
||||
| 4 | `upload_file` | 2.2% |
|
||||
| 3 | `search_hosts` | 1.6% |
|
||||
|
||||
**未调用 54 个,其中 30 个是纯只读**(`write=false && manage=false`)。30 个里有 26 个是
|
||||
主机/服务端枚举类,另 4 个是 `chat_*`:
|
||||
|
||||
```
|
||||
list_online_hosts list_all_hosts get_host_detail get_activity_history
|
||||
get_foreground_window get_client_log get_keylog get_audit_log get_server_status
|
||||
mcp_list_sessions mcp_cancel_session
|
||||
list_processes list_windows list_services list_registry list_network_connections
|
||||
host_list_processes host_list_windows host_list_network_state host_list_software
|
||||
host_list_browser_history host_list_favorites host_list_win32_services
|
||||
host_list_driver_services host_list_scheduled_tasks host_get_hosts_file
|
||||
```
|
||||
|
||||
### 1.2 命令用途分布(118 条:109 条 `terminal_exec` + 9 条 `exec_command`)
|
||||
|
||||
| 目的 | 条数 | 占比 |
|
||||
|---|---:|---:|
|
||||
| 读文件 / 日志 | 44 | 37% |
|
||||
| HTTP 探测本机 8003 | 25 | 21% |
|
||||
| 查服务状态 | 17 | 14% |
|
||||
| 其他 | 14 | 12% |
|
||||
| 跑脚本 | 5 | 4% |
|
||||
| 查注册表 | 5 | 4% |
|
||||
| 列目录 | 5 | 4% |
|
||||
| 查进程 | 2 | 2% |
|
||||
| 写 / 复制 | 1 | 1% |
|
||||
|
||||
注意最后一行:**整场只有 1 条写命令(1%)**。危险操作占比极低,但权限模型把它和只读操作
|
||||
混在同一档。
|
||||
|
||||
### 1.3 失败与超时
|
||||
|
||||
| 错误码 | 次数 | 场景 |
|
||||
|---|---:|---|
|
||||
| `-32002` | 2 | 命令超时/取消 → **会话被销毁** |
|
||||
| `-32001` | 1 | `Timeout waiting for command output` |
|
||||
| `-32007` | 1 | `sc qc AssemblyManager` 被白名单拒 |
|
||||
| `-32009` | 2 | `download_file` 路径不存在(ASM-07 未装 ASM,属环境问题非工具问题) |
|
||||
|
||||
**真实失败率 6/186 = 3%**。工具稳定性没有问题,问题在效率和语义。
|
||||
|
||||
另有 **9 组完全重复的命令**(重复 `sc query`、重复 `Restart-Service`、重复 grep 日志),
|
||||
全部是超时后重试——修掉 §2.2 后自然消失。
|
||||
|
||||
### 1.4 会话开销
|
||||
|
||||
- 20 次 `terminal_open` vs 17 次 `terminal_close` → **3 个会话没关**
|
||||
- 会话粒度分布:19/16/13/11/9/7/7/6/5/4/3/1/1/1/1/1/1/1/1/1 条命令
|
||||
(20 个会话、合计 109 条,与 §1.2 的 109 条 `terminal_exec` 自洽)
|
||||
→ **9 个会话只跑了 1 条命令**
|
||||
- 109 次 `terminal_exec` 里 **41 次(38%)显式传了 `timeout_ms`**
|
||||
- 命令长度中位数 349 字符,最长 1302 字符;74 条命令含 ≥2 个分号(手工串联)
|
||||
|
||||
### 1.5 上下文成本
|
||||
|
||||
**v2 修订(实测)**:对运行中的服务端发一次 `tools/list`(只读请求,测法见附录 B),
|
||||
响应 **193,008 字节**,其中 tools 数组本身 136,692 字节:
|
||||
|
||||
| 组成 | 字节 |
|
||||
|---|---:|
|
||||
| description 合计 | 31,874 |
|
||||
| inputSchema 合计 | 44,192 |
|
||||
| outputSchema 合计 | 49,320 |
|
||||
|
||||
按中英混合粗估 **40k–60k tokens**,每次会话建立 `tools/list` 都要付一遍;其中 30 个
|
||||
零调用的只读工具贡献了相当一部分。
|
||||
|
||||
两个陷阱:
|
||||
1. **不能拿 `mcp/tools.json` 当基线**——它是 222,803 字节的文件,且 `make_tools_json.py`
|
||||
额外追加了 `_readme` / `gate` / `platforms` / `impl` 等**线上响应里没有**的元信息。
|
||||
2. v1 写的 103,158 字节对不上任何历史版本(近 8 个提交的 `mcp/tools.json` 都在
|
||||
217–223KB),应作废。
|
||||
|
||||
---
|
||||
|
||||
## 2. 五个问题(带代码位置)
|
||||
|
||||
### 2.1 会话管理占 20%,且没有「无会话执行」通道
|
||||
|
||||
**根因**:`BuildTerminalExec`(`McpServer.cpp:4920`)把 `session_id` 设为必填:
|
||||
|
||||
```
|
||||
4932: std::string sessionId = GetStringArg(args, "session_id");
|
||||
4933: if (sessionId.empty())
|
||||
4934: return BuildError(id, -32602, "Missing required parameter: session_id");
|
||||
```
|
||||
|
||||
要跑一条命令就必须先 `terminal_open`,跑完还要 `terminal_close`(否则靠
|
||||
`kTermIdleTimeoutSec = 300`(`McpServer.cpp:4673`)五分钟回收)。一次性任务因此固定付
|
||||
2 次额外调用。
|
||||
|
||||
### 2.2 超时销毁会话(设计错误)
|
||||
|
||||
**根因**:`WaitTermCommand`(`McpServer.cpp:10949`)在等待未命中时无条件销毁(`10958` 起):
|
||||
|
||||
```cpp
|
||||
if (!signaled) { // 超时/取消 → 清理会话+路由
|
||||
context* subCtx = it->second.subCtx;
|
||||
MarkTermDestroyedLocked(device_id, it->second.sessionId,
|
||||
McpCallCancelled()
|
||||
? "Terminal session was destroyed because the request was cancelled; ..."
|
||||
: "Terminal session was destroyed after this command timed out (waited "
|
||||
+ std::to_string(timeoutMs) + " ms); call terminal_open again");
|
||||
m_TermContextToDevice.erase(subCtx);
|
||||
m_TermSessions.erase(it);
|
||||
return false;
|
||||
}
|
||||
```
|
||||
|
||||
超时意味着「本次调用不愿再等」,**不意味着「命令失败了」**。`robocopy` 搬 30MB、
|
||||
`Wait-AsmReady 180` 这类命令必然超时,但它们还在正常跑。此时 `erase(it)` 把
|
||||
`subCtx`、已收集的 `data`、`sentPos` 全扔了。
|
||||
|
||||
**v2 更正:`sentPos` 不是「已发送偏移」。** 它是**哨兵在 `data` 中的位置**
|
||||
(`McpServer.h:820` 注释;`McpServer.cpp:10768` 由 `FindSentinel` 写入),成功分支用它
|
||||
把输出**截断到哨兵之前**,并不记录「已经交给调用方多少字节」:
|
||||
|
||||
```
|
||||
10989: if (it->second.sentPos <= it->second.data.size())
|
||||
10990: out.assign(it->second.data.begin(), it->second.data.begin() + it->second.sentPos);
|
||||
```
|
||||
|
||||
而且 `BeginTermCommand` 在每条新命令开始时 `data.clear(); sentPos = 0`(`10925-10926`)。
|
||||
所以「增量回传」需要新增一个真正的交付游标,见 P0-2。
|
||||
|
||||
另外,超时路径的问题不止少了一个游标:调用方在 `WaitTermCommand` 返回 false 后
|
||||
**立即 `subCtx->CancelIO()`**(`McpServer.cpp:4999`),shell 进程随即退出。只改
|
||||
`WaitTermCommand` 而不改这一行,会话即使留着也是死壳。
|
||||
|
||||
### 2.3 默认超时与真实任务不匹配
|
||||
|
||||
`McpToolTimeoutMs` 默认 **20000ms**(`McpServer.h:968`),上限 600000(`McpServer.h:541`)。
|
||||
本次 38% 的调用要手工调大。升级脚本、服务重启、包复制都超过 20 秒。
|
||||
|
||||
顺带:`McpServer.h:541` 的注释写的是「调到 60s 更实用」,但成员初始值仍是 20000,
|
||||
`2015RemoteDlg.cpp:2588` 读 ini 的缺省值也是 20000——注释与代码不一致,实现时统一。
|
||||
|
||||
### 2.4 没有 `read_file`
|
||||
|
||||
现状三条路都不合适:
|
||||
|
||||
| 路径 | 问题 |
|
||||
|---|---|
|
||||
| `exec_command` + `type` | 白名单里有 `type`,但只能整文件输出,无法分页;GBK 文件直接乱码 |
|
||||
| `terminal_exec` + `Get-Content` | 要开会话、要处理引号转义、编码不可控、输出混着提示符回显 |
|
||||
| `download_file` 落盘再读 | 3.6KB 的 `.env` 也要走完整 V2 传输 + 主控落盘 + 本地解析 |
|
||||
|
||||
`download_file` 在本次用了 7 次且 0 失败,说明**服务端作为 V2 接收端已经可用**——
|
||||
这是实现 `read_file` 的现成基础(见 §3 P0-3)。
|
||||
|
||||
### 2.5 白名单在拦只读命令
|
||||
|
||||
**根因**:`kDefaultCmdWhitelist`(`McpServer.cpp:3817`):
|
||||
|
||||
```cpp
|
||||
"dir,type,cd,chdir,ver,hostname,whoami,where,tasklist,systeminfo,ipconfig,netstat,"
|
||||
"path,set,find,findstr,reg query,sc query,"
|
||||
"ping,tracert,nslookup,getmac,driverquery,query,gpresult,"
|
||||
"arp -a,route print,schtasks /query";
|
||||
```
|
||||
|
||||
- 有 `sc query`,**没有 `sc qc`** → 本次被拒(`McpServer.cpp:4115`)
|
||||
- **`powershell` 完全不在表里** → 任何 PowerShell 一行都过不去,这才是根因。
|
||||
本次 9 次 `exec_command` 里 5 次是 `type`、3 次是 `sc query`/`sc qc`、1 次 `whoami`,
|
||||
全是 cmd 内置;所有需要 PowerShell 的都改走不受约束的 `terminal_exec`。
|
||||
|
||||
白名单用前缀匹配(`IsCommandAllowed`,`McpServer.cpp:3862`),所以补 `sc qc` 是一行的事。
|
||||
但补 `powershell` 等于放开一切,必须单独评审。
|
||||
|
||||
---
|
||||
|
||||
## 3. 优化方案
|
||||
|
||||
### P0-1 `terminal_exec` 允许不带 `session_id`
|
||||
|
||||
**改法**:`session_id` 从必填改为可选。
|
||||
|
||||
```
|
||||
terminal_exec(id, command?, session_id?, timeout_ms?)
|
||||
```
|
||||
|
||||
- 给 `command` + 不给 `session_id`:复用该 host 的「默认会话」;不存在则内部走
|
||||
`terminal_open` 的同一路径建一个,**不对外暴露 open/close**。
|
||||
- 默认会话与普通会话同受 `kTermIdleTimeoutSec = 300` 回收,无需新的回收逻辑。
|
||||
- 输出新增 `session_id` 与 `reused: true|false`,让调用方能判断是否可继续复用。
|
||||
- 现有调用全部带 `session_id`,行为不变;`session_id` 写错仍返回 `-32002`。
|
||||
|
||||
**影响**:本次 37 次 open/close 里,至少 9 个单命令会话(27 次调用)可压到 9 次,省 18 次。
|
||||
批量配置那类「每台 6 次」的流程可压到每台 2–3 次。
|
||||
|
||||
**风险**:与 `-32003 Device busy` 的交互。默认会话正在跑别的命令时,仍应返回 `-32003`
|
||||
而不是排队——排队会让调用方无从判断要等多久。
|
||||
|
||||
**风险 2(v2 补充):默认会话会悄悄占住整台主机的终端槽。** `m_TermSessions` 每设备
|
||||
只有一条,`BeginTermPending` 在已有会话时直接拒绝(`McpServer.cpp:10792`),所以自动创建
|
||||
的默认会话会让后续 `exec_command` 和用户主动的 `terminal_open` 都报 `-32003`,而调用方
|
||||
看不到任何显式会话。处理方式:`terminal_open` 撞上默认会话时**返回该 session_id
|
||||
(`reused: true`)而不是报错**,并在它的 description 里写明这一点。
|
||||
|
||||
**验收**:同一 host 连续 3 条命令,调用序列为 3 次 `terminal_exec`,无 open/close。
|
||||
|
||||
### P0-2 超时改为「返回部分输出 + 可继续轮询」,不销毁会话
|
||||
|
||||
**改法**:`WaitTermCommand`(`McpServer.cpp:10949`)的超时分支(`10958`)不再 `erase`,
|
||||
并补齐 v1 漏掉的实现细节。
|
||||
|
||||
超时后:
|
||||
1. 保留 `m_TermSessions` 条目,`busy` 保持 `true`(命令确实还在跑)
|
||||
2. 把已收集的 `data` 从**新增的交付游标 `delivered`** 起返回(v1 误以为 `sentPos` 是
|
||||
这个游标,实际它是哨兵位置),返回后 `delivered = data.size()`
|
||||
3. 返回**成功**结果:`isError:false` + `{session_id, done:false, output, elapsed_ms}`。
|
||||
`BuildError` 只能产出 `{error:{code,message}}`(`McpInternal.cpp:83`),错误响应里没有
|
||||
`structuredContent`,模型侧也会按失败处理——「超时但命令还在跑」不该是错误
|
||||
4. 不必新增 `overdue` 字段:`SweepIdleTerminals` 本来就跳过 `busy` 会话(`11026`)
|
||||
|
||||
继续取输出的方式:**同一个工具,只传 `session_id` 不传 `command`**,进入 wait 模式:
|
||||
- 再次等待,命中哨兵则返回增量 + `done:true` + `exit_code`
|
||||
- 再次超时则继续返回增量 + `done:false`,不销毁
|
||||
|
||||
**v2 必须同时改的三处**:
|
||||
|
||||
- **调用方不再杀 shell**:`BuildTerminalExec` 在 `WaitTermCommand` 返回 false 后调用
|
||||
`subCtx->CancelIO()`(`4999-5000`),必须改成只在「真正失败」时取消;超时保留路径不取消。
|
||||
- **取消与超时分开**:`McpCallCancelled()` 为真表示处理线程已经走了、不会有人再来轮询,
|
||||
必须照旧销毁(与 `-32800` 的语义一致);只有真超时才保留。
|
||||
- **输出上限**:`TermSession::data` 现在无界(全仓没有上限常量)。轮询设计下
|
||||
`robocopy` / `tail -f` 能堆到 MB 级,而工具结果本身也有客户端上限(`get_client_log`
|
||||
的注释已踩过这个坑,`McpServer.cpp:4243`)。需要:每次返回截到 `max_output_bytes`
|
||||
(默认 64KB,带 `truncated:true`);给 `data` 一个硬上限(如 8MB),达到后停止收集
|
||||
并追加标记;`delivered` 只前进不后退,丢弃的字节数要如实上报。
|
||||
|
||||
**v2 补充:busy 会话的最大存活时间。** `SweepIdleTerminals` 只回收 `!busy`(`11026`),
|
||||
调用方超时后再也不轮询时,该主机的 `-32003` 会永久不消失。需要 `busySince` 兜底
|
||||
(如 1 小时)强制清理,或让 `terminal_close` 能强杀 busy 会话。
|
||||
|
||||
**为什么不开新工具**:`terminal_poll` 之类会让工具数 +1,用参数形态区分(有无 `command`)
|
||||
即可,且与 P0-1 天然一致。
|
||||
|
||||
**兼容性**:现有调用都传 `command`,走原路径。`command` 从必填改为「与 `session_id` 二选一」。
|
||||
注意 `data` 在 `BeginTermCommand` 里被 `clear()`(`10925`),所以下一条带 `command` 的调用
|
||||
必须先确认上一条输出已取完,否则会静默丢输出——建议上一条 `done` 但未取完时返回 `-32003`
|
||||
并提示先轮询。
|
||||
|
||||
**验收**:跑一条 90 秒的命令,`timeout_ms=20000`,连续轮询 5 次后拿到完整输出与退出码,
|
||||
会话未被销毁;`delivered` 单调递增、无重复无丢失;中途取消(`-32800`)后会话被销毁;
|
||||
不再轮询时,该主机的终端槽在 busy 兜底时间后释放。
|
||||
|
||||
### P0-3 新增 `read_file`
|
||||
|
||||
```
|
||||
read_file(id, path, offset?=0, limit?=2000, encoding?="auto", max_bytes?=262144)
|
||||
```
|
||||
|
||||
返回:
|
||||
```json
|
||||
{ "path": "...", "size": 3792, "encoding": "utf-8", "eol": "crlf",
|
||||
"lines_total": 72, "offset": 0, "lines_returned": 72, "truncated": false,
|
||||
"text": "...", "sha256": "..." }
|
||||
```
|
||||
|
||||
- `offset` 支持负数(`-200` = 最后 200 行),覆盖「看日志尾部」这个最高频场景
|
||||
- `encoding: auto` 按 BOM → UTF-8 合法性 → GBK 回退探测;显式可传 `utf-8`/`gbk`/`latin1`
|
||||
- 单次上限 256KB,超出按 `truncated: true` 截断并给 `lines_total`
|
||||
|
||||
**第一阶段实现(客户端零改动)**:复用 `download_file` 的 V2 通道把文件拉到
|
||||
`<服务端数据目录>\mcp\tmp\<device_id>\`,读完即删。理由:本次 7 次 `download_file` 全部成功,
|
||||
说明服务端作为 V2 接收端已可用;新增客户端命令的成本远高于收益。
|
||||
**第二阶段**(可选):新增 `COMMAND_READ_FILE` 走内存,省掉落盘。
|
||||
|
||||
**v2 补充的四个前提**:
|
||||
- **先看大小再下载**:`download_file` 是「整文件落到服务端磁盘」(默认 600s 超时),一个
|
||||
2GB 日志会先占满主控磁盘。V2 的元数据到达后先判 `size > max_bytes`(默认 2MB)就直接
|
||||
返回 `-32602`(附「改用 download_file」提示)并 `CancelIO`,不要开始传输。不新增错误码
|
||||
——`-32011` 已被「目标写入失败」占用。
|
||||
- **开关与平台门**:依赖 V2,必须 `McpFileTransfer=1` 且客户端 `SupportsFileV2`
|
||||
(否则 `-32006`);只读模式下是否放行要明确(建议放行,它不写远端)。
|
||||
- **临时目录清理**:用 RAII 覆盖成功/超时/取消/异常四条路径。`devId` 是 `uint64_t`,
|
||||
拼路径没有注入风险;但并发调用共用文件传输槽(`BeginFileTransferPending`),会 `-32003`。
|
||||
- **`sha256` 与 `lines_total` 的语义**:`sha256` 是**整个文件**的哈希(不是返回片段的);
|
||||
`lines_total` 需要完整解码,`offset=-N` 也依赖它,所以第一步仍然是完整取回。
|
||||
|
||||
**为什么值得单开工具而不并入 `exec`**:本次 `.env` 事故就是「用 shell 改配置文件」的
|
||||
典型翻车——PowerShell 的 `.Split($nl)` 绑到 `Split(char[])`,把 72 行拆成 144 行。
|
||||
读侧同理:`type` 出来的 GBK 是乱码、`Get-Content` 会把行尾归一化。
|
||||
字节级的读接口把编码、行尾、引号这三类坑一次性绕开。
|
||||
|
||||
**验收**:读一份 87 行、含 GBK 字符、CRLF 行尾的配置文件,`lines_total` 与
|
||||
`Get-Content | Measure-Object -Line` 一致,`sha256` 与 `certutil -hashfile` 一致。
|
||||
|
||||
### P0-4 白名单补齐只读动词
|
||||
|
||||
**最小改动(推荐先做)**:在 `kDefaultCmdWhitelist` 补只读项
|
||||
|
||||
```
|
||||
sc qc, sc enumdepend, sc sdshow
|
||||
```
|
||||
|
||||
`sc qc` 是本次被拒的那条,属明确的漏项。
|
||||
|
||||
**v2 更正:`icacls` / `net user` / `net localgroup` 不能加。** 这三项都是「只读用法之外
|
||||
还有写用法」,而 `IsCommandAllowed` 是**前缀匹配**(`McpServer.cpp:3862`),无法区分:
|
||||
|
||||
- `icacls X /grant everyone:F` 改 ACL
|
||||
- `net user bob pwd /add` 建本地账号;`net localgroup administrators bob /add` 提权
|
||||
- `whoami /priv` 已被现有 `whoami` 前缀覆盖,加了是冗余
|
||||
|
||||
要在 `exec_command` 里做这三类查询,只能等参数级过滤(白名单项 + 参数正则),那是另一个
|
||||
改动面,不要混进本次。
|
||||
|
||||
**关于 `powershell`**:不建议直接加入白名单——那等于放开一切,且与 `exec_command`
|
||||
「只读白名单」的定位矛盾。真正需要 PowerShell 的场景应通过 P0-3 的 `read_file` 和
|
||||
P1-2 的 `http_probe` 覆盖掉。若后续确有需要,应另立 `kDefaultCmdWhitelistPS`,
|
||||
对 `Get-*` 只读动词做 cmdlet 级白名单,并单独安全评审。
|
||||
|
||||
**验收**:`sc qc <svc>` 返回 `-32007` 消失;`powershell -Command ...` 仍被拒。
|
||||
|
||||
### P1-1 合并三个主机列表工具
|
||||
|
||||
`list_online_hosts` + `search_hosts` + `list_all_hosts` → `list_hosts`。
|
||||
|
||||
本次 `search_hosts` 用了 3 次,另两个各 0 次。三者的差异只在「是否含离线」,
|
||||
用参数即可表达:
|
||||
|
||||
```
|
||||
list_hosts(query?, online?=true, include_offline?=false, group?, os?, client_type?, limit?, offset?)
|
||||
```
|
||||
|
||||
旧名保留为别名(同一 handler,`tools/list` 只暴露 `list_hosts`),避免破坏现有调用方。
|
||||
|
||||
### P1-2 新增 `http_probe`
|
||||
|
||||
本次 **25/118 条命令(21%)** 是手写 `Invoke-WebRequest http://127.0.0.1:8003/...`,
|
||||
每条都要处理 `-UseBasicParsing`、`-TimeoutSec`、引号转义、JSON 解析。
|
||||
|
||||
```
|
||||
http_probe(id, url, method?="GET", headers?, body?, timeout_ms?=10000, max_bytes?=65536)
|
||||
```
|
||||
|
||||
**实现路径(v2 补充)**:没有客户端 HTTP 命令,这个工具只能**在 shell 里执行**:Windows 拼
|
||||
`Invoke-WebRequest`(PTY 会话),Linux/macOS 用 `curl`。也就是说它仍然依赖 exec/terminal 的
|
||||
通道、会占终端槽,并要分别维护两种平台的命令模板与输出解析(`-UseBasicParsing`、超时、
|
||||
编码、JSON/非 JSON 两种返回)。客户端仍然零改动,但工作量不是「新增一个 handler」,
|
||||
验收要覆盖两个平台。
|
||||
|
||||
**安全边界(必须硬编码,不可配置)**:
|
||||
- 只允许 `http` / `https`
|
||||
- **只接受 IP 字面量**(外加 `localhost` 特判)。校验在执行侧完成:请求是在**被管主机**上
|
||||
发出的,服务端解析域名得到的是服务端自己的 DNS 结果,对目标主机没有意义;接受任意域名
|
||||
等于校验形同虚设。允许 `127.0.0.0/8`、`::1`、`10/8`、`172.16/12`、`192.168/16`,其余拒绝
|
||||
- 不跟随跨网段重定向;响应体上限 64KB
|
||||
|
||||
说明:被管主机本来就能跑任意命令,所以这不是严格意义上的 SSRF 跳板;限制私网段的价值在于
|
||||
防止「用一条错误 URL 把主机当代理去打别处」,顺带避免误用。
|
||||
|
||||
**价值**:把「探本机业务健康」从「写一段 PowerShell」变成一次结构化调用,直接消掉 21% 的命令量。
|
||||
|
||||
### P1-3 `get_client_log` 的语义澄清
|
||||
|
||||
`get_client_log` 的描述(`McpServer.cpp:2265`)写的是「**YAMA 客户端的内存运行日志**
|
||||
(客户端 ring buffer)」。本次需要的是**被管业务程序的日志**
|
||||
(`C:\ProgramData\AssemblyManager\logs\assembly_manager.log`),两者完全不同。
|
||||
|
||||
建议不改名(改名破坏兼容),只做两件事:
|
||||
1. 在 `get_client_log` 描述开头加一句「这不是被管业务程序的日志;读业务日志用 `read_file`」
|
||||
2. 在 `read_file` 描述里点明「看日志尾部用 `offset=-N`」
|
||||
|
||||
### P2-1 合并 `host_list_*` 十个工具
|
||||
|
||||
十个 `host_list_*` 是「主机管理」各标签页的一一映射,本次零调用。
|
||||
|
||||
```
|
||||
host_inspect(id, aspects[]) // processes|windows|network|software|browser_history|
|
||||
// favorites|win32_services|driver_services|
|
||||
// scheduled_tasks|hosts_file
|
||||
```
|
||||
|
||||
旧名保留为别名。同时把与之重复的 `list_processes` / `list_windows` / `list_services` /
|
||||
`list_network_connections` 一并折叠进来。
|
||||
|
||||
### P2-2 六对语义重复的工具
|
||||
|
||||
| 快捷版 | 主机管理版 | 建议 |
|
||||
|---|---|---|
|
||||
| `list_processes` | `host_list_processes` | 并入 `host_inspect` |
|
||||
| `list_windows` | `host_list_windows` | 并入 `host_inspect` |
|
||||
| `list_services` | `host_list_win32_services` | 并入 `host_inspect` |
|
||||
| `list_network_connections` | `host_list_network_state` | 并入 `host_inspect` |
|
||||
| `operate_window` | `host_control_window` | 保留一套,另一套做别名 |
|
||||
| `control_service` | `host_control_service` | 保留一套,另一套做别名 |
|
||||
|
||||
对模型来说两套实现是纯噪音:同一个意图有两个工具名,选哪个要靠读两段长描述。
|
||||
|
||||
### P2-3 `tools/list` 体积
|
||||
|
||||
当前 **193,008 字节**(约 40k–60k tokens,实测口径见 §1.5 / 附录 B)。按上面合并估算:
|
||||
|
||||
| 改动 | 工具数变化 |
|
||||
|---|---:|
|
||||
| 三个主机列表 → `list_hosts` | −2 |
|
||||
| `host_list_*` 十个 → `host_inspect` | −9 |
|
||||
| 四个 `list_*` 折叠进 `host_inspect` | −4 |
|
||||
| 两对控制类工具各留一 | −2 |
|
||||
| **合计** | **63 → 46** |
|
||||
|
||||
**v2 更正**:v1 的「约降 27%」是按错误的 103KB 基线算的。按实测基线(193,008 B)看,
|
||||
outputSchema 占 49,320 B 且合并后要保留,被删掉的主要是 17 个工具的 description +
|
||||
inputSchema,乐观估计降 25–35KB(**约 −15%**)。实际值以改动后用附录 B 的方法重测为准。
|
||||
|
||||
### P2-4 别名/合并的同步项(v2 新增)
|
||||
|
||||
「旧名保留为别名、`tools/list` 只暴露新名」听起来只是一张别名表,但工具名在服务端还有
|
||||
五处硬编码的消费点,漏一处就是静默降级:
|
||||
|
||||
| 位置 | 漏掉的后果 |
|
||||
|---|---|
|
||||
| `kToolPlatforms`(`McpServer.cpp:10251`) | `CheckToolPlatform` 查不到名字就**放行**(`10420`),别名会绕过平台门禁 |
|
||||
| `IsBatchReadOnlyTool`(`McpInternal.cpp:594`) | 旧名走 `ids[]` 批量调用会被拒 |
|
||||
| `McpMachine::Handles` / `CollectTargetReqs` | `host_list_*` 族走独立分派,改名后分派不到 |
|
||||
| `kServerInstructions`(`McpServer.cpp:283` 起) | §4/§5 正文点名 `terminal_open`/`exec_command`/`host_list_processes`,模型会指向不存在的工具 |
|
||||
| 文档与清单 | `mcp/tools.json` 需重新生成(`make_tools_json.py`),`check_platform_table.py` / `verify_tools.py` 回归,网站 MCP 页(v1.4.2 那套 11 组)同步 |
|
||||
|
||||
建议把「改名/合并」单独作为一次提交,别名在分派层保留一个版本,下个版本再删。
|
||||
|
||||
---
|
||||
|
||||
## 4. 明确不做(数据不支持)
|
||||
|
||||
| 不做 | 理由 |
|
||||
|---|---|
|
||||
| 改 `download_file` / `upload_file` / `get_screenshot` | 本次 0 失败、调用顺畅,没有证据支持改动 |
|
||||
| 动 `remote_*` / `chat_*` | 本次零调用,无使用数据,改了也无从验证 |
|
||||
| 直接放行 `powershell` | 等于白名单失效,须单独安全评审(见 P0-4) |
|
||||
| 加 `secret_ref` 机制 | 属 Go 侧多租户需求;MFC 是单主控单用户,没有对应场景 |
|
||||
| 新客户端命令 `COMMAND_READ_FILE` | 第一阶段用 `download_file` 复用即可,不值得为省落盘改客户端 |
|
||||
| 砍掉写操作工具的权限门 | 本次只有 1 条写命令,但那是任务性质决定的,不是风险消失 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 对 Go 侧最小工具集的影响
|
||||
|
||||
本次讨论同时确认了 Go 侧的最小工具集,两者共享同一批结论:
|
||||
|
||||
1. **P0-1 / P0-2 / P0-3 同时是 Go 侧的前置结论**:Go 侧 `hub` 已有 PTY 终端子连接
|
||||
(`COMMAND_SHELL` → `TOKEN_TERMINAL_START`),但没有一次性执行的输出收集器,
|
||||
也没有文件读写。MFC 侧这三项的实现路径可以直接复用。
|
||||
2. **并发约束两边一致**:MFC 用 `-32003 Device busy` 保证每 host 单终端会话;
|
||||
Go 侧 `hub.go` 注释写明 *at most one web terminal per device (MVP constraint shared
|
||||
with the C++ server)*。Go 侧多用户场景下这个约束需要显式排队或租约,MFC 侧单用户则不必。
|
||||
3. **命名对齐**:MFC 若落地 `read_file` / `http_probe`,Go 侧沿用同名同参数,
|
||||
使同一句提示词在两个后端都能跑通。
|
||||
4. **Go 侧不需要 MFC 的接口**:主机分享是客户端双宿(`COMMAND_SHARE(59)` +
|
||||
`SHARE_TYPE_YAMA`,载荷 `ip:port[:shine[:transport]]`),Go 是与 MFC 同级的服务端,
|
||||
不是下游消费者。详见 `common/host_share.h`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 施工顺序与验收
|
||||
|
||||
| 序 | 项 | 改动面 | 客户端 | 预估收益(按本次数据) |
|
||||
|---:|---|---|---|---|
|
||||
| 1 | P0-4 白名单补 `sc qc`/`sc enumdepend`/`sc sdshow` | `McpServer.cpp:3817` 一行 | 零 | 消除 `-32007` 误拒 |
|
||||
| 2 | P0-2 超时不销毁 + 轮询 | `WaitTermCommand` + 调用方 CancelIO + `delivered` 游标 + 输出上限 | 零 | 消除 2 次 `-32002`、9 组重试 |
|
||||
| 3 | P0-1 免会话执行 | `BuildTerminalExec` 参数校验 + 默认会话 + `terminal_open` 复用 | 零 | −18 次调用(9.7%) |
|
||||
| 4 | P0-3 `read_file` | 新增 handler,复用 V2 接收端 | 零 | 覆盖 44/118 条读命令 |
|
||||
| 5 | P1-2 `http_probe` | 新增 handler(内部走 shell,Windows/POSIX 两套模板) | 零 | 覆盖 25/118 条命令 |
|
||||
| 6 | P1-1 合并列表工具 | 别名 + 平台表 + `tools/list` 收敛 | 零 | −2 工具 |
|
||||
| 7 | P1-3 描述澄清 | 两处 description | 零 | 减少误选 |
|
||||
| 8 | P2-1/2/3/4 合并与收敛 | 别名表 + 清单生成 + instructions + 网站 | 零 | 63 → 46 工具 |
|
||||
|
||||
**顺序说明(v2)**:P0-2 排在 P0-1 之前——它会改动 `terminal_exec` 的会话形态(新增
|
||||
`delivered`/`busySince` 状态),P0-1 的默认会话直接复用同一套状态,反过来做要改两遍。
|
||||
|
||||
**全部八项都不需要改客户端。** 这是本方案最重要的性质——所有收益都来自服务端。
|
||||
|
||||
**整体验收标准**:用同一套 ASM 工位任务重跑一遍,目标:
|
||||
|
||||
- MCP 调用总数从 186 降到 **110 以内**
|
||||
- `terminal_open` / `terminal_close` 降到 **各 3 次以内**
|
||||
- `timeout_ms` 手工覆盖次数从 41 降到 **10 以内**
|
||||
- 零 `-32002`(会话被销毁);超时后能轮询续取
|
||||
- `tools/list` 响应体积**较实测基线 193,008 B 下降 ≥15%**(≈ ≤164KB)。不要沿用
|
||||
「80KB」:按本次合并范围做不到,见 P2-3
|
||||
|
||||
---
|
||||
|
||||
## 附录 A:本次数据可复现的统计口径
|
||||
|
||||
- 调用记录:会话 jsonl 中 `function_call` 且 `name=DeferExecuteTool`,取
|
||||
`arguments.toolName` 去掉 `mcp__YAMA__` 前缀
|
||||
- 错误识别:结果文本里匹配 `MCP error (-?\d+):`,避免把输出正文里的 "Error" 误判
|
||||
- 用途分类:对命令字符串做正则归类(服务状态/进程/注册表/读文件/HTTP/写/控制/列目录/跑脚本)
|
||||
- 重复命令:对完整命令字符串精确去重
|
||||
|
||||
> 注意:不能用「结果里含 timeout 字样」判超时——本次有 29 条命令的**命令正文**里带
|
||||
> `-TimeoutSec`,会被误判。只有匹配到 `MCP error` 前缀才算工具层失败。
|
||||
|
||||
## 附录 B:`tools/list` 体积测法(v2 新增)
|
||||
|
||||
一次只读请求即可,不会影响运行中的服务端:
|
||||
|
||||
```
|
||||
POST http://127.0.0.1:6545/mcp # 明文后端;TLS 前端是 6544
|
||||
Authorization: Bearer <token> # 取自 HKCU\SOFTWARE\YAMA\settings\McpToken,勿打印
|
||||
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
|
||||
```
|
||||
|
||||
2026-11-12 实测:响应 **193,008 字节**,tools 数组 136,692 字节,63 个工具;其中
|
||||
description 31,874 / inputSchema 44,192 / outputSchema 49,320。
|
||||
|
||||
建议给 `tools/mcp_tools/verify_tools.py --live` 增加一行体积打印(当前只比对
|
||||
name/description/schema 与顺序),让「清单体积」变成可回归的指标,而不是一次性手算。
|
||||
Reference in new issue
Block a user