diff --git a/docs/Mcp_Next_Plan.md b/docs/Mcp_Next_Plan.md index 82715a7..cc19f25 100644 --- a/docs/Mcp_Next_Plan.md +++ b/docs/Mcp_Next_Plan.md @@ -17,10 +17,11 @@ ## 0. 结论摘要 -1. **工具面已经覆盖「看 + 管 + 连」三层**(54 个工具,8 个功能族),但仍有三处结构性缺口: - **文件系统只有读没有写**(能列、能搜、能传,不能删/改名/建目录)、 - **远程控制缺「防人工干扰」与「能力自述」**(无法锁定对端键鼠、模型不知道主机支持什么)、 - **同一能力存在两套重叠工具**(`list_processes` vs `host_list_processes` 等 4 组,模型不知该选哪个)。 +1. **工具面已经覆盖「看 + 管 + 连」三层**(本方案写作时 54 个工具、8 个功能族;P10-A/B/C 与 P11 之后为 + **60 个工具、9 个功能族**,见 §1.1)。写作时的三处结构性缺口都已关闭: + **文件系统只有读没有写**(P10-B 补了 `delete_path` / `move_path` / `create_folder`)、 + **远程控制缺「防人工干扰」与「能力自述」**(P10-C 补 `remote_block_input`,P10-A 补 + `get_host_detail.capabilities`)、**同一能力存在两套重叠工具**(P10-A 用描述互指解决,未合并工具)。 2. **最高性价比的一批新工具是文件系统写操作**(`delete_path` / `move_path` / `create_folder`): 客户端四个命令 + 三个完成 token **全部已实现**(`client/file/FileManager.cpp:97-121`; `TOKEN_DELETE_FINISH` 被删文件与删目录复用)。MCP 侧复用 P7 的 `followUp` 范式即可, @@ -35,6 +36,8 @@ `capabilities` 只描述「这台主机本身能做什么」,两者分工明确。 4. **协议层有四个空白**:`initialize.instructions`、`notifications/progress`、`notifications/cancelled`、 `logging`。其中前两个直接影响「长任务(下载/上传/搜索/chat_wait)时模型以为卡死」的体验。 + **现状**(2026-10-28):前三项已落地——`instructions`(P10-A)、progress/cancelled(P11,附录 D.4); + `logging` 仍未做(服务端不声明 `capabilities.logging`,也不发 `notifications/message`)。 5. **不建议现在做**的:注册表写、Windows 事件日志、进程模块/启动项、剪贴板读——都需要客户端改, 且安全边界要单独评审;代理隧道(`COMMAND_PROXY`)价值最高但工程量大,建议单独立项。 @@ -46,22 +49,29 @@ ## 1. 现状盘点 -### 1.1 工具族(54 个) +### 1.1 工具族(60 个) -登记表在 `server/2015Remote/McpInternal.cpp:368` 的 `kToolHints[]`。 -注意:**表头注释写「53 个工具」,实际数组是 54 项**(注释已过期,属一处文档瑕疵,见 §5.13)。 +登记表在 `server/2015Remote/McpInternal.cpp:375` 的 `kToolHints[]`(60 项,与下表的工具逐条对应)。 +下表是 P11 之后的口径;写作时是 54 个、8 个族,P10-B 加 3 个(文件系统写)、P10-C 加 1 个 +(`remote_block_input`)、P11 加 2 个(`mcp_list_sessions` / `mcp_cancel_session`)。 | 族 | 数 | 工具 | 门控条件 | |---|---|---|---| -| 服务端本机只读 | 7 | `list_online_hosts` `search_hosts` `list_all_hosts` `get_host_detail` `get_activity_history` `get_audit_log` `get_server_status` | `McpReadonly`(默认 1 = 只读) | -| 主机只读 | 21 | `list_processes` `list_windows` `list_files` `list_services` `get_client_log` `get_keylog` `get_screenshot` `list_registry` `download_file` `search_file` `list_network_connections` + `host_list_*`(10 个标签页) | `McpReadonly`;`get_keylog` 另需 `McpKeylog=1`;`host_list_*` 另需 `McpMachine=1` | -| 终端 | 4 | `terminal_open` `terminal_exec` `terminal_close` `exec_command` | `McpTerminal=1` **且** `McpReadonly=0` | -| 远程控制 | 5 | `remote_open` `remote_close` `remote_mouse` `remote_keyboard` `remote_clipboard` | `McpRemoteControl=1` **且** `McpReadonly=0` | -| 文件传输 | 2 | `upload_file` `copy_files_c2c` | `McpFileTransfer=1`(`download_file` 只要求此开关,不要求 `McpReadonly=0`) | +| 服务端本机只读 | 9 | `list_online_hosts` `search_hosts` `list_all_hosts` `get_host_detail` `get_activity_history` `get_audit_log` `get_server_status` `mcp_list_sessions` `mcp_cancel_session` | 全部始终在列表里、只读模式下照常可用;`mcp_list_sessions` / `mcp_cancel_session` 还**不受任何开关或只读限制**(卡住请求的唯一出路,见附录 D.5) | +| 主机只读 | 21 | `list_processes` `list_windows` `list_files` `list_services` `get_client_log` `get_keylog` `get_screenshot` `list_registry` `download_file` `search_file` `list_network_connections` + `host_list_*`(10 个标签页) | 除下列四类外始终在列表里:`get_keylog` 需 `McpKeylog=1`(其 `clear` / `set_offline` 还需 `McpReadonly=0`)、`download_file` 需 `McpFileTransfer=1`、`list_network_connections` 与 `host_list_*` 需 `McpMachine=1` | +| 终端 | 4 | `terminal_open` `terminal_exec` `terminal_close` `exec_command` | `terminal_*`:`McpTerminal=1` **且** `McpReadonly=0`;`exec_command` 只要求 `McpReadonly=0` | +| 远程控制 | 6 | `remote_open` `remote_close` `remote_mouse` `remote_keyboard` `remote_clipboard` `remote_block_input` | `McpRemoteControl=1` **且** `McpReadonly=0` | +| 文件传输 | 2 | `upload_file` `copy_files_c2c` | `McpFileTransfer=1` **且** `McpReadonly=0`(`download_file` 只要求此开关) | +| 文件系统写 | 3 | `delete_path` `move_path` `create_folder` | `McpFileWrite=1` **且** `McpReadonly=0` | | 设备管理 | 4 | `kill_process` `operate_window` `control_service` `power_action` | `McpManage=1` **且** `McpReadonly=0` | -| 主机/连接管理 | 7 | `kill_network_connection` `host_control_process` `host_control_window` `host_control_service` `host_control_task` `host_set_remark` `host_set_watch_level` | 前 5 个:`McpMachine=1` + `McpMachineDangerous=1` + `McpReadonly=0`;后 2 个只要求 `McpReadonly=0` | +| 主机/连接管理 | 7 | `kill_network_connection` `host_control_process` `host_control_window` `host_control_service` `host_control_task` `host_set_remark` `host_set_watch_level` | 前 5 个:`McpMachine=1` + `McpMachineDangerous=1` + `McpReadonly=0`;`host_set_remark` / `host_set_watch_level` 始终在列表里,调用要求 `McpReadonly=0` | | 远程交谈 | 4 | `chat_open` `chat_send` `chat_wait` `chat_close` | `McpChat=1`(与 `McpReadonly` 无关) | +合计 9+21+4+6+2+3+4+7+4 = 60。默认配置(`McpReadonly=1`、其余开关 0)下 `tools/list` **19 个** += 服务端本机只读 9 + 主机只读 8(去掉 `get_keylog` / `download_file` / `list_network_connections` / +`host_list_*`)+ 主机/连接管理 2(`host_set_remark` / `host_set_watch_level`);其余各族依赖开关,全部不可见。 +开关全开且关闭只读时为 **60 个**。 + **已有的工程范式**(新工具直接复用,不必重新设计): - **一次性子连接 + 首包即数据**:`list_processes` / `list_windows` / `list_services` / `list_registry` / `get_client_log`。 @@ -311,7 +321,7 @@ proxy_close(session_id) > 另有一项「两套工具族重叠」的优化放在 §3.2(因为要顺带说明它为什么不合并),同样是 P0。 -### 5.1 【P0】`get_host_detail` 增加 `capabilities` +### 5.1 【P0,已完成 `bb55f52`】`get_host_detail` 增加 `capabilities` **问题**:模型拿到 `clientType=WIN` 就以为所有工具都能用,于是反复撞 `-32005`: @@ -342,7 +352,7 @@ host["capabilities"] = caps; **收益**:模型在规划阶段就能排除不可用工具,把「试错 → 报错 → 换工具」的三轮往返压缩成一次。 **成本**:约 30 行,零客户端改动,`outputSchema` 加一个对象。 -### 5.2 【P0】`get_keylog`:补离线开关与真实状态(**已重写,初稿前提有误**) +### 5.2 【P0,已完成 `bb55f52`】`get_keylog`:补离线开关与真实状态(**已重写,初稿前提有误**) > **初稿的错误**:原文断言「现在只能采 1–15 秒窗口,对『昨天谁敲了什么』完全无用,需要新增 `mode=offline`」。 > 这是错的。`CKeyboardManager1` 构造时就 `new CircularBuffer(m_strRecordFile)`,而 `CircularBuffer` @@ -371,7 +381,7 @@ host["capabilities"] = caps; 两个写动作都必须**先于采集窗口下发**,且失败要如实返回(`Send2Client` 的返回值要检查)。 -### 5.3 【P0】`list_processes` / `list_windows` 增加服务端过滤 +### 5.3 【P0,已完成 `bb55f52`】`list_processes` / `list_windows` 增加服务端过滤 **问题**:`BuildPagedHostListInputSchema` 只有 `{id, limit, offset}`(`McpServer.cpp:776`,调用点在 `:1477` 等)。一台正常 Windows 有 200–400 个进程、几十个窗口,模型要翻 3–4 页才能找到目标;每页都是完整字段,上下文开销很大。 @@ -384,7 +394,7 @@ if (filtered) page.totalAll = (int)all.size(); // 过滤前总数 **收益**:`list_processes(name="chrome")` 从 3 页变 1 条;两套工具族的能力也对齐了(`host_list_*` 本来就有这两个参数)。 -### 5.4 【P1】`power_action` 增加结果验证 +### 5.4 【P1,已完成 `1c832ff`】`power_action` 增加结果验证 **问题**:`power_action` 是「发完即走、无响应」(`McpServer.cpp:5812` 附近注释),返回 `ok:true` 只代表**命令写进了 socket**。模型会误以为「已重启」,紧接着调 `list_processes` 却拿到旧进程列表。 @@ -393,13 +403,13 @@ if (filtered) page.totalAll = (int)all.size(); // 过滤前总数 - `wait=true`:轮询主连接是否断开 → 再轮询是否重新上线,返回 `{sent:true, went_offline:true, came_back:true, elapsed_ms}`; - 超时不算失败,返回 `came_back:false` 让模型自己决定。 -### 5.5 【P1】破坏性工具统一 `dry_run` +### 5.5 【P1,已完成 `1c832ff`】破坏性工具统一 `dry_run` `kill_network_connection` 有 `dry_run`(实测报告「观察项」明确肯定了这个设计),但 `kill_process`、`operate_window(close)`、`host_control_*` 都没有。建议统一:`dry_run=true` 时只做「目标存在性校验 + 返回将被影响的对象」,不执行。 对 AI 尤其重要:模型可以在执行前把「我要杀这 3 个进程」摆给用户看。 -### 5.6 【P2,收益被初稿高估】错误码:`-32008` 其实只有两种语义 +### 5.6 【P2,已完成 `1c832ff`(`-32012`,`-32008` 留作别名)】错误码:`-32008` 其实只有两种语义 > **初稿的错误**:原文说 `-32008` 一码四义(含「老客户端格式」「多显示器不支持」)。核对后全文件只有两处 > `-32008`:`exec_command` 的 shell 元字符(`McpServer.cpp:2901`)与 `terminal_exec` 的 `&`/`|`/换行 @@ -415,7 +425,7 @@ if (filtered) page.totalAll = (int)all.size(); // 过滤前总数 `-32008` 保留为历史别名(不破坏既有客户端与已发布的文档)。这是一次纯常量替换,收益是让模型 不必读英文 message 就能区分「改参数」与「换主机」,但**优先级低于 P0 各项**。 -### 5.7 【P1】写工具的 ack 语义显式化 +### 5.7 【P1,部分完成 `27b5431`:`verified` 三态已落地,`verify_hint` 字段未加】写工具的 ack 语义显式化 现状:`delete_path` / `move_path` / `create_folder` / `kill_process` / `operate_window` / `control_service` 的 ack 都是**客户端无条件回包**,不代表操作成功。 @@ -426,7 +436,7 @@ if (filtered) page.totalAll = (int)all.size(); // 过滤前总数 彻底的做法是客户端补 `TOKEN_FILE_OP_ERROR`(带 win32 码),归入 §4.1 的 P12 批次。 -### 5.8 【P1】`initialize` 返回 `instructions` +### 5.8 【P1,已完成 `bb55f52`】`initialize` 返回 `instructions` **问题**:模型对这套服务端的「隐性知识」全靠工具描述拼凑:主机 id 是 64 位雪花值(不能猜)、要先 `list_online_hosts` 再操作、`-32003` 是单设备单飞行、`-32006` 不要重试、远程控制要先 `remote_open` 拿 `session_id`。`Mcp_Design.md` 把这些写在文档里,但**模型看不到文档**。 @@ -440,7 +450,7 @@ if (filtered) page.totalAll = (int)all.size(); // 过滤前总数 **收益**:这是**单点投入、全局收益**的改动——所有客户端的每一次会话都受益,且零风险。优先级应当排在所有新工具之前。 -### 5.9 【P2】`notifications/progress` 与 `notifications/cancelled` +### 5.9 【P2,已完成 `1c832ff`】`notifications/progress` 与 `notifications/cancelled` **问题**: @@ -454,20 +464,25 @@ if (filtered) page.totalAll = (int)all.size(); // 过滤前总数 这两项都在 `McpServer.cpp` 的 HTTP 处理器层,**不动任何工具实现**。 -### 5.10 【P2】会话可观测与自救 +### 5.10 【P2,已完成 `1c832ff`】会话可观测与自救 `-32003 Device busy` 现在是死路:模型不知道是谁占着这台主机、也不知道等多久。建议加两个纯服务端工具: | 工具 | 作用 | |---|---| -| `mcp_list_sessions` | 列出所有在飞会话:`{host_id, tool, session_id, started_at, idle_ms, kind}` | -| `mcp_cancel_session` | 按 `session_id` 强制中止(等价于 `notifications/cancelled` 的内部路径) | +| `mcp_list_sessions` | 列出所有在飞会话,每项 `{host_id, kind, tool, session_id, request_id, busy, elapsed_ms, idle_ms}` | +| `mcp_cancel_session` | 按 `request_id`(精确)或 `id`/`session_id`(条件)取消,返回 `{cancelled, released, waited_ms, matched}`;与 `notifications/cancelled` 走同一个取消位 | + +实装口径以附录 D.5 为准。写作时设想的字段是 `{host_id, tool, session_id, started_at, idle_ms, kind}`, +落地时去掉了 `started_at`,补了 `request_id`(供 `mcp_cancel_session` 精确回传)、`busy`、`elapsed_ms`。 `-32003` 的 message 里带上「当前占用者与已持续时间」,模型就能自己决定「等」还是「取消」。 ### 5.11 【P2】`tools/list` 体积 -54 个工具、每个都带完整中文描述 + 双 schema。实测**工具描述与属性说明文本合计约 23 KB**(54 条 `description` + 158 条 schema 属性说明),叠加 JSON 结构与 schema 骨架后,`tools/list` 响应实际在 **45–60 KB** 量级。 +**60** 个工具(P11 之后的口径,见 §1.1)、每个都带完整中文描述 + 双 schema。按 54 个工具时(P10-A)实测, +**工具描述与属性说明文本合计约 23 KB**(54 条 `description` + 158 条 schema 属性说明),叠加 JSON +结构与 schema 骨架后,`tools/list` 响应在 **45–60 KB** 量级;多出的 6 个工具只会让它更大。 对 200K 上下文的模型不算致命,但对小上下文客户端(8K–32K)会挤占绝大部分预算,且**每轮对话都要重传**(多数客户端不缓存)。 @@ -481,17 +496,19 @@ if (filtered) page.totalAll = (int)all.size(); // 过滤前总数 `client/ServicesManager.cpp:213` 的 `ServicesConfig` 对每一项 `Sleep(500)` 后再回列表。批量控制 10 个服务 = 至少 5 秒。服务端可以在 `action` 里支持 `items[]` 批量下发(一次子连接、一个 payload),把 N 次往返压成 1 次。**前提是确认客户端能解析多条目 payload**——按现有实现它只处理单条,需要客户端改动,因此列为 P2。 -### 5.13 【P0,顺手修】`kToolHints` 表头注释过期 +### 5.13 【P0,已修】`kToolHints` 表头注释过期 -`McpInternal.cpp:367` 注释写「53 个工具的语义登记表」,实际数组 **54 项**。一行修复。 +原注释写「53 个工具的语义登记表」,与数组实际长度不符。P10-A(`bb55f52`)先改成 54, +P10-C(`3d388f8`)加工具时索性去掉数字——避免每加一个工具就要改一次注释; +核对方式见 §1.1,60 个工具与 60 项注解逐条对应。 ### 5.14 其他小项 | 项 | 位置 | 说明 | |---|---|---| -| `list_windows` 无 `pid` 过滤 | `McpServer.cpp:2201` | 见 §5.3 | -| `search_file` 无深度/大小上限参数 | `McpServer.cpp:8050` | 客户端固定深度 32 / 10000 条,服务端可加 `max_depth` 但需客户端支持;暂不做 | -| `search_file` 的描述仍写着「会栈溢出」 | `McpServer.cpp:1850` | 客户端侧已于 8f718d9 修复,描述与 `tools/mcp_smoke.ps1` 的注释都过期,应一并更正 | +| ~~`list_windows` 无 `pid` 过滤~~ | — | **已完成**(P10-A,`bb55f52`):`list_processes` / `list_windows` 都加了 `name` + `pid` | +| `search_file` 无深度/大小上限参数 | `McpServer.cpp:8050` | 客户端固定深度 32 / 10000 条,服务端可加 `max_depth` 但需客户端支持;暂不做(P12) | +| ~~`search_file` 的描述仍写着「会栈溢出」~~ | — | **已完成**(P10-A,`bb55f52`):描述改为「超过 260 字节的路径会被静默跳过(既不记录也不继续向下递归)」,`tools/mcp_smoke.ps1` 的两处注释改为「MAX_PATH 的条目会被客户端静默跳过(8f718d9 起不再栈溢出)」 | | `get_screenshot` 无区域裁剪 | `McpServer.cpp:2085` | 有 `max_width`;ROI 需客户端改动,收益有限,不做 | | 审计不含调用参数 | `Mcp_Design.md §10.8` | 有意设计(防泄漏),维持 | | `chat_wait` 会取走 inbox | `McpInternal.cpp:431` | 已正确标注非幂等,无需改 | @@ -500,16 +517,17 @@ if (filtered) page.totalAll = (int)all.size(); // 过滤前总数 ## 6. 批次与验收建议 -| 批次 | 内容 | 客户端改动 | 预估规模 | 验收方式 | -|---|---|---|---|---| -| **P10-A(优化,先做)** | `instructions`、`capabilities`、`list_*` 过滤、`get_keylog` 离线开关与状态、工具族互指、`kToolHints` 注释、`search_file` 过期描述 | 无 | 服务端 ~450 行 | 冒烟断言 `instructions` 非空;`capabilities` 与平台一致;`list_processes(name=...)` 命中数 < 全量且 `totalAll` 正确;`get_keylog.offlineRecord` 与实际 `kbrecord` 一致 | -| **P10-B** | `delete_path` / `move_path` / `create_folder` + `McpFileWrite` 开关 + 系统目录保护 + §2.3 的三处接线 + `verified` 复核 | 无 | ~700 行 | 冒烟新增:建目录→传文件→改名→删除→删目录→越界拒绝;中文路径 + 超长路径各一条;超时后确认**不弹**文件管理器窗口 | -| **P10-C** | `remote_block_input`(含强制解锁与超时自动解锁) | 无 | ~200 行 | 会话内 block→截图对比→unblock;`remote_close` 后确认已解锁 | -| **P11(已完成 2026-10-28,见附录 D)** | `power_action` 验证、`dry_run` 统一、`-32012`、progress/cancelled、`mcp_list_sessions` | 无 | ~700 行 | 长任务 progress 回调计数 > 0;取消后主机 1s 内释放(`get_server_status` 可查) | -| **P12** | 注册表写、事件日志、进程模块/启动项、`TOKEN_FILE_OP_ERROR`、`DeleteDirectory` 的路径长度防御 | **需要** | 客户端 + 服务端 | 单独设计文档 | -| **独立立项** | 代理隧道、客户端升级、摄像头/语音 | 视方案 | 大 | 单独安全评审 | +| 批次 | 状态 | 内容 | 客户端改动 | 规模 | 验收方式 | +|---|---|---|---|---|---| +| **P10-A** | 已完成 `bb55f52` | `instructions`、`capabilities`、`list_*` 过滤、`get_keylog` 离线开关与状态、工具族互指、`kToolHints` 注释(去数字这一步实际随 P10-C 落地,见 §5.13)、`search_file` 过期描述 | 无 | 服务端 ~450 行 | 冒烟断言 `instructions` 非空;`capabilities` 与平台一致;`list_processes(name=...)` 命中数 < 全量且 `totalAll` 正确;`get_keylog.offlineRecord` 与实际 `kbrecord` 一致 | +| **P10-B** | 已完成 `27b5431` | `delete_path` / `move_path` / `create_folder` + `McpFileWrite` 开关 + 系统目录保护 + §2.3 的三处接线 + `verified` 复核 | 无 | ~700 行 | 冒烟新增:建目录→传文件→改名→删除→删目录→越界拒绝;中文路径 + 超长路径各一条;超时后确认**不弹**文件管理器窗口 | +| **P10-C** | 已完成 `3d388f8` | `remote_block_input`(含强制解锁与超时自动解锁) | 无 | ~200 行 | 会话内 block→截图对比→unblock;`remote_close` 后确认已解锁 | +| **P11** | 已完成 `1c832ff`,见附录 D | `power_action` 验证、`dry_run` 统一、`-32012`、progress/cancelled、`mcp_list_sessions` | 无 | ~700 行 | 长任务 progress 回调计数 > 0;取消后主机 1s 内释放(`get_server_status` 可查) | +| **P12** | **待做** | 注册表写、事件日志、进程模块/启动项、`TOKEN_FILE_OP_ERROR`、`DeleteDirectory` 的路径长度防御、`control_service` 批量 payload、`search_file.max_depth` | **需要** | 客户端 + 服务端 | 单独设计文档 | +| **独立立项** | 未立项 | 代理隧道、客户端升级、摄像头/语音 | 视方案 | 大 | 单独安全评审 | -**建议顺序**:P10-A → P10-B → P10-C → P11,**每批独立提交**。 +**建议顺序**:P10-A → P10-B → P10-C → P11,**每批独立提交**(已于 2026-10-28 按序完成; +未推送前按批次合并了零碎提交,故每批各一个提交,见上表)。 理由:P10-A 全是**几十行代码换全局体验**的改动(能力自述 + 使用说明 + 描述互指),先落地能立刻降低后续所有工具的试错率,且几乎不引入回归风险;P10-B 是最大的功能缺口,但涉及删除语义,需要更充分的测试与开关灰度;P10-C 小而独立,可随时插入。 @@ -561,7 +579,7 @@ COMMAND_WEBCAM / COMMAND_AUDIO→ 流式音视频 client/K | 主题 | 位置 | |---|---| -| 工具注解登记表(54 项) | `server/2015Remote/McpInternal.cpp:368` | +| 工具注解登记表(60 项) | `server/2015Remote/McpInternal.cpp:375` | | `tools/list` 构造 | `server/2015Remote/McpServer.cpp:1408` | | `initialize` 结果构造 / HTTP 方法分派 | `McpServer.cpp:46` `BuildInitializeResult` / `:7622` 起 | | 主机技术字段补全 | `server/2015Remote/McpServer.cpp:2018` `AppendHostTechnicalDetail` |