Files
SimpleRemoter/docs/Mcp_Tool_Optimization_Plan.md
T
yuanyuanxianganddeepseek-flash 5841f27df9 Feature(mcp): unify window and service controls behind one name per state
operate_window / host_control_window and control_service / host_control_service were two
implementations of the same intent. tools/list now exposes exactly one of each pair,
chosen by McpMachine: the host_control_* names when host management is enabled, the
main-connection names when it is not.

The advertised tool accepts the union of actions. host_control_window routes close/show
to the main-connection implementation, which stays the only path with close/show
semantics and requires McpManage; the machine path keeps its post-action verification
for restore/hide/maximize/minimize/activate. host_control_service routes
set_auto/set_manual the same way and rejects dry_run for them instead of pretending to
run one. Both old names remain callable aliases, and service_name is accepted as an
alias for the machine tool's name parameter.

The manifest generator treats the two main-connection tools as !machine entries, so the
two-capture union still covers both states. tools/list is 49 entries when everything is
on (was 51) and 47 when host management is off; the response shrinks from 193,008 B to
168,634 B (-12.6%), short of the 15% estimate because state-conditional tools must stay
in the manifest. The plan document records that measurement and the reason.

Verified with a dedicated two-state test: visibility matrix, close/show and
set_auto/set_manual routing through dry_run and validation paths, alias dispatch, and
-32006 for host_* names when host management is off. Step 8a/8b regressions and
verify_tools --live still pass.

Co-Authored-By: deepseek-flash
2026-11-12 17:40:51 +01:00

577 lines
31 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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.
# 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 的方法重测为准。
**实测结果(2026-11-12,P2-1/2 落地后)**:开启全部开关时 `tools/list` 响应
**168,634 B / 49 个工具**,较基线降 24,374 B(**−12.6%**),未达到 15%。原因是清单
必须同时描述两种开关状态:`list_processes` / `list_windows` / `list_services` /
`operate_window` / `control_service` 在 McpMachine=0 时是唯一可用路径,因此以
`gate: "!machine"` 留在清单里(见 P2-4),所有状态下的实际列表都是 49 或 47 个,
到不了估算里的 46。若还要再降,只有两条路:删掉降级路径(关掉主机管理就失去列进程/
窗口/服务的能力)或压缩 description/outputSchema 正文——两者都不建议为凑 15% 去做。
### 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。**实测 168,634 B(−12.6%)**,未达标,
原因见 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 与顺序),让「清单体积」变成可回归的指标,而不是一次性手算。