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
31 KiB
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. 结论摘要
- 工具不缺,粒度不对。 186 次调用里 109 次(58.6%)是
terminal_exec;按命令分类, 118 条里有 59% 是「读」(读文件/日志 37%、查服务状态 14%、查注册表 4%、列目录 4%), 这部分全部压在terminal_exec上;同时有 30 个纯只读工具零调用。原因是专用工具 一个标签页一个、粒度太细,而真实故障处理是「一条命令拿三样东西」。 - 最大的单点浪费是会话管理。
terminal_open20 次 +terminal_close17 次 = 37 次调用(20%), 零信息产出。其中 9 个会话只跑了 1 条命令,即 3 次调用换 1 条命令。 terminal_exec超时会销毁会话,这是设计错误。 命令超时说明进程可能还在跑, 此时丢掉 shell 恰好毁掉全部现场(cwd、环境变量、后台任务)。本次两次-32002都由此产生,每次都要重开会话并重跑命令。read_file是唯一真正的功能缺口。 读文件靠type(exec_command,5 次)和Get-Content/Select-String(terminal_exec,39 次),.env对比还得download_file落盘再本地解析。而「读」正是最高频的需求。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_openvs 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 个
零调用的只读工具贡献了相当一部分。
两个陷阱:
- 不能拿
mcp/tools.json当基线——它是 222,803 字节的文件,且make_tools_json.py额外追加了_readme/gate/platforms/impl等线上响应里没有的元信息。 - 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 漏掉的实现细节。
超时后:
- 保留
m_TermSessions条目,busy保持true(命令确实还在跑) - 把已收集的
data从新增的交付游标delivered起返回(v1 误以为sentPos是 这个游标,实际它是哨兵位置),返回后delivered = data.size() - 返回成功结果:
isError:false+{session_id, done:false, output, elapsed_ms}。BuildError只能产出{error:{code,message}}(McpInternal.cpp:83),错误响应里没有structuredContent,模型侧也会按失败处理——「超时但命令还在跑」不该是错误 - 不必新增
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改 ACLnet 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),两者完全不同。
建议不改名(改名破坏兼容),只做两件事:
- 在
get_client_log描述开头加一句「这不是被管业务程序的日志;读业务日志用read_file」 - 在
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 侧的最小工具集,两者共享同一批结论:
- P0-1 / P0-2 / P0-3 同时是 Go 侧的前置结论:Go 侧
hub已有 PTY 终端子连接 (COMMAND_SHELL→TOKEN_TERMINAL_START),但没有一次性执行的输出收集器, 也没有文件读写。MFC 侧这三项的实现路径可以直接复用。 - 并发约束两边一致:MFC 用
-32003 Device busy保证每 host 单终端会话; Go 侧hub.go注释写明 at most one web terminal per device (MVP constraint shared with the C++ server)。Go 侧多用户场景下这个约束需要显式排队或租约,MFC 侧单用户则不必。 - 命名对齐:MFC 若落地
read_file/http_probe,Go 侧沿用同名同参数, 使同一句提示词在两个后端都能跑通。 - 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 与顺序),让「清单体积」变成可回归的指标,而不是一次性手算。