diff --git a/docs/Mcp_Design.md b/docs/Mcp_Design.md index 186fa4b..2e6efc2 100644 --- a/docs/Mcp_Design.md +++ b/docs/Mcp_Design.md @@ -259,6 +259,7 @@ Json::Value BuildHostJson(context* ctx, _ClientList* clientMap); | `McpBind` | `127.0.0.1` | 监听地址;默认仅本机;可设 `0.0.0.0`(所有网卡)或内网 IP(如 `192.168.0.92`)以支持远程 | | `McpToken` | 空(UI 默认随机值) | 静态 token;对话框内「token 必填、默认随机值」——首次打开若为空则预填随机并随保存持久化。运行时优先级:env `YAMA_MCP_TOKEN` → `McpToken` → 皆空则随机生成(见 §3.5) | | `McpKeylog` | `0` | 键盘记录工具 `get_keylog` 的独立开关(见 §9.3);与 `McpReadonly` 无关,改动需重启生效 | +| `McpToolTimeoutMs` | `20000` | 工具等待客户端响应的默认超时(ms),clamp 到 `[1000, 600000]`;各工具自己的 `timeout_ms` 参数优先。**ini-only**(无设置界面控件),改动需重启生效 | > 与旧版「`McpPort=0` 即禁用」不同:启用与否改由独立的 `McpEnabled` 开关控制,`McpPort` 回归纯端口语义,二者解耦。 @@ -492,7 +493,7 @@ void CMcpSettingsDlg::OnBnClickedBtnSave() - `structuredContent` 统一附 `total` / `totalAll` / `offset` / `limit` / `hasMore`,与 `McpMachine.cpp` 既有约定一致(`host_list_*` / `list_network_connections` 本来就是这样)。 - `content` 摘要统一为「共 N <单位>,本次返回第 a-b 条(还有更多,可用 offset 继续取)。」;`hasMore=false` 时不再出现「继续取」的误导提示;`offset` 越界时明确写「offset 超出范围,本次返回 0 条」。 - 实现集中在 `McpInternal.h/.cpp`:`PageWindow` / `ResolvePageWindow` / `ApplyPageWindow` / `WritePageFields` / `AppendPagingProps` / `PageSummary`。 -- `list_files` 仍受客户端单次 500 条的硬限制(`total=500` 表示客户端截断,不是服务端分页)。 +- `list_files` 仍受服务端 `ParseFileList` 的 500 条硬限制(`total=500` 且原目录确有更多条目时表示截断,不是服务端分页)。客户端侧不截断、按需扩缓冲一次性回全量;本轮未加 `truncated` 标记(要加得改服务端 `ParseFileList` 的调用约定),仍靠「`total=500` 且 `hasMore`」判断。 --- @@ -663,19 +664,21 @@ token 只从 `-Token` / env 读取,不落仓库、不打印;无在线主机 | `-32002` | Host offline / not found | 主机 id 不存在、主连接已断、会话 id 不存在或已关闭 | 先 `list_online_hosts` 刷新再选主机 | | `-32003` | Busy | 该主机已有同类请求在飞(终端/截屏/文件/聊天会话),或同设备重复 `chat_open` | 等前一个结束或先 `*_close` | | `-32004` | Send failed | 命令写入主连接失败(连接刚断) | 重试一次;仍失败按 `-32002` 处理 | -| `-32005` | Not supported on this host | 需要 Windows 的工具用在 LNX/MAC/APK 主机上 | 换 Windows 主机,或改用跨平台只读工具(`list_files` 等) | +| `-32005` | Not supported on this host | 能力限制,改参数也修不好:需要 Windows 的工具用在 LNX/MAC/APK 主机上;`remote_open` 遇到多显示器(阶段一);主机无屏幕预览/控制能力位 | 换主机或换工具;不要改参数重试 | | `-32006` | Policy refused | 只读模式 / 对应 `Mcp*` 开关关闭 / 主机不支持该能力(如 V2 文件传输) | **不要重试**:这是配置决定,需管理员改服务端配置 | | `-32007` | Not in command whitelist | `exec_command` 的命令不在 `McpCmdWhitelist` 里,或词边界不匹配(`dir` 过、`dirx` 拒) | **不要重试**:换成白名单内的命令,或请管理员加白名单项 | -| `-32008` | Rejected by validation | 同一码覆盖四类语义:`exec_command` 含 shell 元字符 `&\|<>^` 或控制字符(含 `\r\n`);路径/参数含非法字符;老客户端不支持 V2 文件传输格式;`remote_open` 遇到多显示器 | 按 `message` 修正参数;多显示器/老客户端属能力限制,换目标或换主机 | -| `-32009` | Target not found | `kill_network_connection` 的四元组在当前连接表里查不到(`dry_run` 传假四元组最常见) | 先用 `host_list_network_state` 取真实四元组再 `dry_run` 校验 | +| `-32008` | Rejected by validation | 只覆盖「参数被校验拒绝、改参数可修」:`exec_command` 含 shell 元字符 `&\|<>^` 或控制字符(含 `\r\n`);`terminal_exec` 含 `&`/`\|`/换行;路径/参数含非法字符 | 按 `message` 修正参数后重试 | +| `-32009` | Target not found | 远端路径/注册表键不存在(win32 `2`/`3`,由新客户端主动回报);`kill_network_connection` 的四元组在当前连接表里查不到(`dry_run` 传假四元组最常见) | 先用 `list_files`/`list_registry`(或 `host_list_network_state`)确认目标存在 | +| `-32010` | Access denied | 目标存在但权限不足(win32 `5`):非提权客户端的服务枚举(`OpenSCManager`)、受保护目录(如 `System Volume Information`)、受保护注册表键(如 `HKLM\SAM`) | **不要重试**:需客户端提权(管理员运行)或换目标 | - **命令超时会销毁持久会话**(`terminal_exec`):等服务端收集到哨兵超时返回 `-32001`,会话随即被销毁并留 600 秒「墓碑」;对同一 `session_id` 再发命令返回 `-32002`,文案明确写 `Terminal session was destroyed after this command timed out (waited N ms); call terminal_open again`,与「id 写错」(`Terminal session not found: `)区分开。 -- **`download_file` 有停滞看门狗**:60 秒没收到任何数据(远程路径不存在/不可访问最典型)即失败,返回 `-32001` 且文案带 `File transfer stalled: no data received for 60s ...`,主机立即释放,不必等 `timeout_ms`。真实的大文件传输只要还在持续收数据就不会触发。 +- **新客户端把失败改成结构化回报**(`TOKEN_SERVICE_ERROR=170` / `TOKEN_FILE_LIST_ERROR=171` / `TOKEN_REG_ERROR=172` / `TOKEN_DOWNLOAD_ERROR=173`,布局 `[token:1][win32 码:4 LE]`):`list_services`(未提权)、`list_files`/`list_registry`(路径/键不存在或拒绝访问)、`download_file`(远端路径全部不存在)都在客户端侧就失败并立即回报,服务端转译成 `-32009`/`-32010`,**亚秒级返回**,不再靠超时猜。老客户端不发这些包,成功路径报文一律不变,因此老客户端/老服务端的行为与改造前完全一致(老服务端把未知 token 走 `default` 丢弃)。 +- **`download_file` 有停滞看门狗兜底**:60 秒没收到任何数据即失败,返回 `-32001` 且文案带 `File transfer stalled: no data received for 60s ...`。新客户端的 `TOKEN_DOWNLOAD_ERROR` 让这条路基本不再触发,看门狗只用来兜住「客户端卡住/老客户端」。 - `-32006` 会额外在审计日志里记一条 `CALL_DENIED`(§10.8),其余错误只体现在 `CALL_FAIL` 行。 - 批量调用(带 `ids[]`)**整体不报错**:每个 id 的结果单独带 `error`,顶层用 `succeeded` / `failed` / `skipped` 汇总;只有整批请求本身非法(超过 50 个 id、写操作传 `ids`)才返回顶层 `-32602`。 -- 冒烟脚本 `tools/mcp_smoke.ps1` 覆盖了上表的可复现项:`-32601`(未知 method)、`-32602`(未知工具/缺参数/51 个 id)、`-32002`(不存在的主机)、`-32006`(任一开关关闭时自动挑一个关着的功能验证,并断言审计里出现 `CALL_DENIED`;全部开启时跳过)。其余码由各批次的功能验证覆盖(`-32001`/`-32003` 等需要构造竞态或超时,不进冒烟)。 -- 本次验证(Debug 实例,`McpKeylog` 临时置 0):`get_keylog` 返回 `-32006`,`Bin\logs\mcp_audit.log` 末尾出现 `CALL_DENIED ... tool=get_keylog reason=Keyboard log is disabled (McpKeylog=0)`;此时冒烟 34/34 通过。恢复开关后 `-32006` 与审计两条转为跳过,32/32 通过;带 `-SearchPath` 时 37/37 通过。 +- 冒烟脚本 `tools/mcp_smoke.ps1` 覆盖了上表的可复现项:`-32601`(未知 method)、`-32602`(未知工具/缺参数/51 个 id)、`-32002`(不存在的主机)、`-32006`(任一开关关闭时自动挑一个关着的功能验证,并断言审计里出现 `CALL_DENIED`;全部开启时跳过)、`-32009`(新客户端的 `list_files`/`list_registry`/`download_file` 不存在路径负例)。其余码由各批次的功能验证覆盖(`-32001`/`-32003` 等需要构造竞态或超时,不进冒烟)。 +- 本次验证(Debug 实例):冒烟 **40/40 通过**(原 37 项 + 3 条 `-32009` 负例);`-32010` 由 `list_services`(未提权客户端,win32=5)、`list_files "C:\System Volume Information"`、`list_registry "HKLM\SAM\SAM\Domains\Account"` 三条实测覆盖。 ### 12.1 命令哨兵与输出清洗(测试报告 P1/P3/P4 的修复) diff --git a/docs/Mcp_RemoteControl_Design.md b/docs/Mcp_RemoteControl_Design.md index 39dd1c0..0a63217 100644 --- a/docs/Mcp_RemoteControl_Design.md +++ b/docs/Mcp_RemoteControl_Design.md @@ -295,10 +295,8 @@ remote_open ──► 建立子连接 ──► [remote_mouse/remote_keyboard × | -32002 | 设备/会话不存在 | `id` 无在线主机、`session_id` 不存在或不匹配 | | -32003 | 设备/会话忙 | 已有控制会话、人类远程桌面占用、`get_screenshot` 在飞 | | -32004 | 发送失败 | 注入命令发送失败 | -| -32005 | 能力不支持 | 客户端无 `CLIENT_CAP_SCREEN_PREVIEW`(Observe)/ 不支持屏幕控制(Act) | +| -32005 | 能力不支持 | 客户端无 `CLIENT_CAP_SCREEN_PREVIEW`(Observe)/ 不支持屏幕控制(Act)/ **多显示器主机(阶段一)** | | -32006 | 被开关禁用 | `McpRemoteControl=0` 或 `McpReadonly=1` | -| -32008 | 非法/被拒参数 | 多显示器未支持时的 `remote_open` 降级拒绝(阶段一) | - --- ## 11. 配置项 @@ -317,7 +315,7 @@ remote_open ──► 建立子连接 ──► [remote_mouse/remote_keyboard × ### 12.1 阶段一(本期) -- **单显示器**:Observe 抓主屏,坐标空间与虚拟桌面重合;多显示器 `remote_open` 显式报错(`-32008`)。 +- **单显示器**:Observe 抓主屏,坐标空间与虚拟桌面重合;多显示器 `remote_open` 显式报错(`-32005`,能力限制而非参数错误)。 - 注入基于**绝对坐标** `SendInput`,要求客户端处于可注入的桌面会话(已登录、非锁屏/非 UAC 安全桌面);锁屏/UAC 提示场景注入无效(客户端 `SendInput` 限制),设计文档记录为已知限制。 - **代聊实验使能项**:窗口抓屏(`COMMAND_SCREEN_WINDOW`)、UTF-8 剪贴板、窗口聚焦随阶段一落地(§17)。 diff --git a/docs/Mcp_Test_Report_2026-10-25.md b/docs/Mcp_Test_Report_2026-10-25.md index c025e3b..61dc242 100644 --- a/docs/Mcp_Test_Report_2026-10-25.md +++ b/docs/Mcp_Test_Report_2026-10-25.md @@ -17,15 +17,15 @@ | 编号 | 复核结论 | 处置 | 验证证据(修复后实测) | |---|---|---|---| | P1 | 属实 | **已修**。ConPTY 下哨兵改为独立一行(`@echo off & ` + 单独 `echo __MCP_DONE___%errorlevel%`);会话因超时被销毁后留 600s 墓碑,报错文案区分「被销毁」与「id 写错」。老客户端(非 PTY)保持单行 `&&` 形态,行为不变。 | `rem hello` → exit 0(原 100% 超时);`cmd /c exit 0` → exit 0;`cmd /c echo abc` → `abc`。超时路径:`ping -n 40` 配 `timeout_ms=3000` → `-32001`,随后同一 session → `-32002 "Terminal session was destroyed after this command timed out (waited 3000 ms); call terminal_open again"`;假 id → `-32002 "Terminal session not found: (call terminal_open first)"`;销毁后 `terminal_open` 立即成功 | -| P2 | 属实(结论成立),但「10 个纯本地 DB 读取」的**表述有误**——被挡的是经主连接向目标机取数据的远程机器管理工具(`host_list_processes/windows/network_state/scheduled_tasks/services/…`、`host_get_hosts_file` 等,都走 `BeginPending`),属 single-flight 设计;纯服务端本地工具(`get_server_status`、`get_audit_log`、`host_set_remark` 等)不受影响 | **已修**(选了「快速失败」):文件传输加 60s 停滞看门狗,`timeout_ms` 内只要持续有数据就不受影响;默认超时保持 600s(避免误杀大文件)。互斥豁免未做——远程工具之间互斥本身就是有意的。 | 不存在路径 `C:/no_such_dir_zzz_mcp` → **60096ms** 失败,`-32001 "File transfer stalled: no data received for 60s (the remote path is probably missing or inaccessible; verify it with list_files first)"`(原为 `ms=600004`);挂起期间 `get_server_status` 2120ms OK、`get_audit_log` 20ms OK,远程 `list_files` 仍 `-32003`;失败后主机立刻释放,冒烟脚本随即 37/37 通过 | +| P2 | 属实(结论成立),但「10 个纯本地 DB 读取」的**表述有误**——被挡的是经主连接向目标机取数据的远程机器管理工具(`host_list_processes/windows/network_state/scheduled_tasks/services/…`、`host_get_hosts_file` 等,都走 `BeginPending`),属 single-flight 设计;纯服务端本地工具(`get_server_status`、`get_audit_log`、`host_set_remark` 等)不受影响 | **已修**(选了「快速失败」):文件传输加 60s 停滞看门狗,`timeout_ms` 内只要持续有数据就不受影响;默认超时保持 600s(避免误杀大文件)。互斥豁免未做——远程工具之间互斥本身就是有意的。 | 不存在路径 `C:/no_such_dir_zzz_mcp` → **60096ms** 失败,`-32001 "File transfer stalled: no data received for 60s (the remote path is probably missing or inaccessible; verify it with list_files first)"`(原为 `ms=600004`);挂起期间 `get_server_status` 2120ms OK、`get_audit_log` 20ms OK,远程 `list_files` 仍 `-32003`;失败后主机立刻释放,冒烟脚本随即 37/37 通过。**2026-10-25 二次修**:新客户端在建立传输子链接前就回 `TOKEN_DOWNLOAD_ERROR`(173),`download_file` 不存在路径现在 **0.07s → `-32009`**(`Remote path does not exist: ... (win32=3)`),60s 停滞看门狗降级为兜底 | | P3 | 属实 | **已修**。`%errorlevel%` 在回显文本里是字面模板而非数字,`FindSentinel` 改为「从后往前找第一个『标记+数字』」,不再依赖行首。 | `ver` → exit 0(原 1);`nosuchcmd_zzz` → 9009;`cmd /c exit 0` → 0;`set NOVAR` → 1 | | P4 | 属实 | **已修**。清洗改为三段:删到「命令行回显」结束(顺带清掉 shell 启动画面/提示符)→ 删哨兵行回显 → 按 nonce 擦掉渲染残留的哨兵文本;另修 `StripAnsi` 对 `OSC…ESC\` 的收尾(会残留 `\`)。设计见 `docs/Mcp_Design.md` §12.1。 | 上述命令的 stdout 全部无 `@echo off`、无 `__MCP_DONE_*`、无提示符/空行;`type` 报错文本无残留反斜杠 | | P5 | 属实 | **已修**(`McpInternal.cpp` 注解表 `get_activity_history` → `openWorld=true`,附代码注释说明它经 `COMMAND_QUERY_ACTIVITY` 触达远程主机) | 代码审查 + 与 §10.2 口径一致 | -| P6 | 属实(`OpenSCManager` 权限不足,客户端失败分支回普通消息包) | **暂搁置**:修它要改客户端(回传带失败标记的 `TOKEN_SERVERLIST`),按「暂不动客户端」原则留待后续批次;服务端当前只能报超时 | 第2轮 VM(提权)成功、第1轮非提权 3/3 超时,反证根因 | +| P6 | 属实(`OpenSCManager` 权限不足,客户端失败分支回普通消息包) | **已修**:新增 `TOKEN_SERVICE_ERROR`(170),客户端 `SendServicesList` 失败时回 `[170][win32:4]`(并保留原 `ClientMsg`,老服务端行为不变);服务端转译成 `-32010`,文案点明需要管理员权限 | 非提权客户端 `list_services` → **268ms `-32010`**(`Failed to enumerate services: access denied (win32=5). service enumeration requires the client to run elevated (administrator)`;原为 20s `-32001`) | | P7 | 属实 | **已修**(文档):`docs/Mcp_Design.md` §12 补齐 `-32007`/`-32008`/`-32009` 并注明 `-32008` 的四类语义 | 文档核对 | -| P8 | 属实 | **暂搁置**:服务端收到的响应与「空目录/空键」完全一致,无法区分;需客户端回报错误码,属客户端改动 | 代码审查(两条路径都只搬运客户端结果) | +| P8 | 属实 | **已修**:新增 `TOKEN_FILE_LIST_ERROR`(171) / `TOKEN_REG_ERROR`(172),客户端失败分支回 `[token][win32/lstatus:4]`;服务端按 `2/3 → -32009`、`5 → -32010` 转译,空目录/空键仍返回成功空列表 | `list_files C:\no_such_dir_xyz` → **0.22s `-32009`**、`list_files C:\System Volume Information` → **0.06s `-32010 (win32=5)`**;`list_registry HKLM\Software\NoSuchKeyXYZ` → **0.10s `-32009`**、`HKLM\SAM\SAM\Domains\Account` → **0.08s `-32010`**;空目录/正常目录/正常键返回不变 | -**结论**:报告的问题清单与根因分析全部成立(仅 P2 有一处表述需要更正);P1/P3/P4(同一处哨兵机制)与 P5/P7、P2 的「长时间锁定」已在服务端修复并端到端验证,P6/P8 需要客户端配合,按既定原则搁置。 +**结论**:报告的问题清单与根因分析全部成立(仅 P2 有一处表述需要更正);P1/P3/P4(同一处哨兵机制)与 P5/P7、P2 的「长时间锁定」已在服务端修复并端到端验证,P6/P8 已在放开「客户端可小改」后按结构化失败回报修复(见上表,均为亚秒级返回)。 --- @@ -139,7 +139,7 @@ 4. P6:客户端服务枚举失败结构化回传; 5. P7/P8 随批次顺手处理。 -**复核后状态**:1 → 已修(§0 P1/P3/P4);2 → 已修「停滞 60s 快速失败」,默认超时未下调、互斥豁免未做(远程工具互斥是有意设计,本地工具本就不受限);3 → 已修;4 → 搁置(需改客户端);5 → P7 已修(文档),P8 搁置(需客户端回报错误码)。 +**复核后状态**:1 → 已修(§0 P1/P3/P4);2 → 已修「停滞 60s 快速失败」,默认超时未下调、互斥豁免未做(远程工具互斥是有意设计,本地工具本就不受限);3 → 已修;4 → 已修(`TOKEN_SERVICE_ERROR` → `-32010`);5 → P7 已修(文档),P8 已修(`TOKEN_FILE_LIST_ERROR`/`TOKEN_REG_ERROR` → `-32009`/`-32010`)。 ## 附录 A:错误码实测一览