Files
SimpleRemoter/docs/Mcp_Tool_Optimization_Plan.md
T
yuanyuanxianganddeepseek-flash f5ac7ba45f 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
2026-11-12 15:41:20 +01:00

30 KiB
Raw Blame History

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 起):

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):

"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)

返回:

{ "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 与顺序),让「清单体积」变成可回归的指标,而不是一次性手算。