# MCP 能力扩展与优化方案(P10 起) > 版本:v2(已按代码核对修订) 状态:评审通过,按 §6 顺序施工 > 前置文档:`Mcp_Design.md`(协议/架构/配置/错误码)、`Mcp_Phase2_Design.md`(双模式无头驱动)、 > `Mcp_Manage_Design.md`(P7 写工具范式)、`Mcp_Machine_Design.md`(P8 会话抽象)、 > `Mcp_Terminal_Design.md`、`Mcp_RemoteControl_Design.md`、`Mcp_FileTransfer_Design.md`、`Mcp_Chat_Design.md`、 > `Mcp_Test_Report_2026-10-25.md`(实测结论与已修问题) > > 本文回答两个问题:**还能做哪些工具**、**现有工具还能怎么优化**。所有结论都落到具体文件与行号, > 并区分「客户端零改动」「需客户端改动」「客户端尚未实现」三种可行性。 > > **v2 修订要点**(逐条核对代码后更正,详见各节开头的「初稿的错误」): > §5.2 的 `mode=offline` 前提不成立(历史数据本来就会回传);§2.3 低估了服务端接线工作量; > §5.6 的「一码四义」不成立;§5.1 的 `serverGates` 与 `get_server_status` 重复;§3.2 应给出明确优先级。 --- ## 0. 结论摘要 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` 范式即可, **客户端零改动**,一次性补齐「AI 能整理远程磁盘」这个最常用场景。 注意这不等于「照抄 P7」:文件管理器子连接的就绪包是 `TOKEN_DRIVE_LIST` 不是 `TOKEN_SYSTEM_READY`,且三个完成 token 在服务端顶层分发里**还没有 case**——真正的接线 工作量在这里,详见 §2.3。 3. **最大的非工具类短板是「能力自述」**:`get_host_detail` 不告诉模型这台主机支持什么, 模型只能靠 `-32005` 试错(`list_registry`、`get_screenshot`、`remote_*`、`upload_file` 各有平台/能力位门槛)。 补一个 `capabilities` 对象是**纯服务端改动、几十行代码**,但直接减少一整类无效调用。 服务端开关态不必另开字段——`get_server_status` 的 `switches` 已经完整暴露(`McpServer.cpp:3142`), `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`)价值最高但工程量大,建议单独立项。 > **一处需要纠正的常见误解**:进程「挂起 / 恢复」**已经实现**,不需要新工具—— > 它是 `host_control_process` 的 `action=freeze|thaw`(`McpMachine.cpp:2107`), > 且已带「动作后重拉进程列表复核」的验证逻辑。本轮不再重复造这个工具。 --- ## 1. 现状盘点 ### 1.1 工具族(60 个) 登记表在 `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`)。 | 族 | 数 | 工具 | 门控条件 | |---|---|---|---| | 服务端本机只读 | 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`;`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`。 - **接管子连接 → 发写命令 → 收确认**(`PendingRequest::followUp` / `followUpSent`):`kill_process` / `operate_window` / `control_service`(`Mcp_Manage_Design.md §3`)。 - **多步会话抽象**(`PendingKind::Machine` / `ConnMgr`):`host_list_*` / `host_control_*`(`Mcp_Machine_Design.md §3`)。 - **流式会话**(`TermSession` / `ScreenCtrlSession` / `FileTransferSession` / `ChatSession`):终端、远程控制、文件传输、聊天。 - **迟到首包吸收**(`MarkLateFirstPacketForTool` / `TakeToolFirstPacket`):防超时后误弹 MFC 窗口。 ### 1.2 协议层能力 | 能力 | 现状 | 证据 | |---|---|---| | `initialize` / `ping` / `tools/list` / `tools/call` | ✅ | `McpServer.cpp:7633` 起 | | `initialize.instructions` | ❌ 未实现 | 全文 0 处 `instructions` | | `tools/list` 的 `annotations` | ✅ 四类 hint 齐备 | `McpInternal.cpp:437` `ApplyToolAnnotations` | | `outputSchema` | ✅ 48 处 | — | | `resources` / `prompts` | ❌ 未实现 | 0 处 | | `notifications/progress` | ❌ 未实现 | 0 处 `progressToken` | | `notifications/cancelled` | ❌ 未实现 | 0 处 `cancelled` | | `Mcp-Session-Id` | ❌ 无状态 | 0 处 | | 分页 | 用 `limit`/`offset`,非 MCP `cursor` | 全部列表工具一致 | | 传输 | Streamable HTTP `POST /mcp`;可选内置 TLS 终结(`McpTlsProxy`) | `Mcp_Design.md §13` | | 认证 | 静态 Bearer token + 失败计数封禁 | `Mcp_Design.md §3.5` | | 错误码 | `-32700` … `-32011` 共 14 个 | `Mcp_Design.md §12` | ### 1.3 客户端能力 → MCP 覆盖矩阵 对 `common/commands.h` 中 Windows 客户端**已实现**的命令逐个核对(`client/KernelManager.cpp`、`client/MachineManager.cpp`、`client/file/FileManager.cpp`、`client/ScreenManager.cpp`、`client/KeyboardManager.cpp`): | 客户端能力 | 命令 | MCP 现状 | 可行性 | |---|---|---|---| | 列目录 / 列盘 | `COMMAND_LIST_FILES` / `COMMAND_LIST_DRIVE` | ✅ `list_files` | — | | 搜索文件 | `COMMAND_SEARCH_FILE` | ✅ `search_file` | — | | 下载 / 上传 | `CMD_DOWN_FILES_V2` / `COMMAND_SEND_FILE_V2` | ✅ `download_file` / `upload_file` | — | | 客户端间直传 | `COMMAND_C2C_SEND_FILES` | ✅ `copy_files_c2c` | — | | **删除文件** | `COMMAND_DELETE_FILE` → `TOKEN_DELETE_FINISH` | ❌ **缺** | **零客户端改动** | | **删除目录(递归)** | `COMMAND_DELETE_DIRECTORY` → `TOKEN_DELETE_FINISH` | ❌ **缺** | **零客户端改动** | | **新建目录** | `COMMAND_CREATE_FOLDER` → `TOKEN_CREATEFOLDER_FINISH` | ❌ **缺** | **零客户端改动** | | **重命名 / 同卷移动** | `COMMAND_RENAME_FILE` → `TOKEN_RENAME_FINISH` | ❌ **缺** | **零客户端改动** | | 进程列表 / 结束 | `COMMAND_PSLIST` / `COMMAND_KILLPROCESS` | ✅ `list_processes` / `kill_process` | — | | 进程挂起 / 恢复 | `COMMAND_PROCESS_FREEZING` / `COMMAND_PROCESS_THAW` | ✅ `host_control_process(action=freeze\|thaw)` | — | | 窗口列表 / 控制 | `COMMAND_WSLIST` / `CMD_WINDOW_CLOSE` / `CMD_WINDOW_TEST` | ✅ `list_windows` / `operate_window` | — | | 服务列表 / 控制 | `TOKEN_SERVERLIST` / `COMMAND_SERVICECONFIG` | ✅ `list_services` / `control_service` | — | | 计划任务 / 软件 / 驱动 / 浏览器记录 / 收藏 / hosts 读 | `COMMAND_MACHINE_*` | ✅ `host_list_*`(10 个) | — | | **写 hosts 文件** | `COMMAND_HOSTS_SET` | ❌ **缺** | 零客户端改动,但**整文件覆盖**,高风险 | | **卸载软件** | `COMMAND_APPUNINSTALL`(`WinExec`,无回包) | ❌ **缺** | 零客户端改动,风险高 | | 连接列表 / 断开连接 | `COMMAND_CONNECTION` / `COMMAND_KILL_CONNECTION` | ✅ `list_network_connections` / `kill_network_connection` | — | | 屏幕截图 | `COMMAND_SCREEN_PREVIEW_REQ` | ✅ `get_screenshot` | — | | 鼠标 / 键盘 / 剪贴板写 | `COMMAND_SCREEN_CONTROL` + `MSG64` | ✅ `remote_*` | — | | **锁定对端键鼠** | `COMMAND_SCREEN_BLOCK_INPUT`(2 字节) | ❌ **缺** | **零客户端改动**(无回包) | | 黑屏 / Ctrl+Alt+Del | `COMMAND_SCREEN_BLANK` / `COMMAND_SCREEN_CTRL_ALT_DEL` | ❌ | **客户端未实现**,需客户端改动 | | 窗口级 / 区域捕获 | `COMMAND_SCREEN_WINDOW` / `COMMAND_SCREEN_ROI` | ❌ | 流式接口,需评估(见 §4.2) | | 注册表读 | `COMMAND_REGEDIT` + `COMMAND_REG_FIND` | ✅ `list_registry`(子键 + 值) | — | | **注册表写** | 无命令 | ❌ | **需客户端改动** | | 键盘记录(实时) | `COMMAND_KEYBOARD` | ✅ `get_keylog` | — | | **键盘记录(离线常驻)** | `COMMAND_KEYBOARD_OFFLINE` / `COMMAND_KEYBOARD_CLEAR` | ❌ **缺** | **零客户端改动**(见 §5.2) | | 客户端日志 | `COMMAND_QUERY_LOG` | ✅ `get_client_log` | — | | 电源操作 | `TOKEN_MACHINE_MANAGE` | ✅ `power_action` | — | | 远程交谈 | `COMMAND_CHAT` | ✅ `chat_*` | — | | **客户端升级** | `COMMAND_UPDATE` | ❌ | 零客户端改动,需独立评审(见 §4.4) | | **上传执行 / 下载执行** | `COMMAND_UPLOAD_EXEC` / `COMMAND_DOWN_EXEC` | ❌ | 零客户端改动,需独立评审(见 §4.4) | | **代理映射** | `COMMAND_PROXY` | ❌ | 需独立设计(见 §4.3) | | 摄像头 / 语音 | `COMMAND_WEBCAM` / `COMMAND_AUDIO` | ❌ | 需流式解码,建议后置 | | 清除事件日志 / 隐藏开网页 / 卸载后门 | `COMMAND_CLEAN_EVENT` / `COMMAND_OPEN_URL_*` / `COMMAND_REMOVE` | ❌ | **当前 Windows 客户端未实现**,为死命令 | **结论**:客户端已实现、但 MCP 还没接的能力共 **14 项**,其中 **9 项属「零客户端改动、可常规批次接入」**: - 文件写 4 项(删除文件 / 删除目录 / 建目录 / 改名移动) - 键鼠锁定 1 项(`remote_block_input`) - 离线键盘记录 2 项(开关 / 清空) - 主机侧 2 项(写 hosts、卸载软件)—— 零改动但风险高,建议后置或不做 另有 5 项(代理、升级、上传执行、摄像头、窗口级捕获)虽也零客户端改动,但工程量或风险远超常规批次,需单独立项(§4)。 --- ## 2. 新工具(P10-A):文件系统写操作 ### 2.1 为什么是最高优先级 MCP 现在能读、能传、能搜,**唯独不能删、不能改名、不能建目录**。任何「整理远程磁盘」「清理临时文件」「归档日志」「部署目录准备」类任务都会卡在最后一步,只能退回 `exec_command`(`del` / `move` / `mkdir`)——而 `exec_command` 受命令白名单约束(`McpCmdWhitelist`),`del` 默认不在白名单里,且无法处理中文路径与超长路径的编码问题。 用原生文件通道做,还能绕开 shell 白名单、拿到确定的 ack、复用已有的 `TOKEN_*_FINISH` 协议。 ### 2.2 工具定义 | 工具 | 入参 | 客户端命令 | 完成 ack | |---|---|---|---| | `delete_path` | `id`、`path`、`recursive`(默认 `false`) | `recursive=true` → `COMMAND_DELETE_DIRECTORY`;否则 `COMMAND_DELETE_FILE` | `TOKEN_DELETE_FINISH` | | `move_path` | `id`、`from`、`to` | `COMMAND_RENAME_FILE` + `[from\0][to\0]` | `TOKEN_RENAME_FINISH` | | `create_folder` | `id`、`path` | `COMMAND_CREATE_FOLDER` + `[path\0]` | `TOKEN_CREATEFOLDER_FINISH` | 输出统一为 `{id, path, ok:true, verified?:bool}`,并附一句可读摘要。 ### 2.3 复用链路(与 P7 同构,但**不是**照抄 P7) ``` 主连接 COMMAND_LIST_DRIVE → 客户端建文件管理器子连接 → 子连接回 TOKEN_DRIVE_LIST →(followUp)下发 COMMAND_DELETE_FILE / _DIRECTORY / _CREATE_FOLDER / _RENAME_FILE → 等 TOKEN_*_FINISH → 关闭子连接 ``` - 服务端已有现成的三段式入口:`list_files`(`McpServer.cpp:2419`)、`search_file`(`McpServer.cpp:8050`)、`download_file`(`McpServer.cpp:6430`)都走 `COMMAND_LIST_DRIVE` 开子连接。 - `PendingRequest` 的 `followUp` / `followUpSent` / `subCtx` 字段(`McpServer.h:584-587`)足够承载「先等就绪首包、再发写命令、再等确认」的两阶段语义,**数据结构不用改**。 - 路径编码:客户端工程是 MultiByte,路径必须 `Utf8ToCpExact` 严格转 GBK(同 `search_file` 的做法),不可表示即 `-32602`。 **但接入点必须新写三处,这是本节的主要工作量:** 1. **就绪包分流走 `OnDriveList`,不是 `OnSystemReady`。** `OnSystemReady`(`McpServer.cpp:8070`)里有工具名硬门(只认 `kill_process` / `operate_window`),且文件管理器子连接的就绪包是 `TOKEN_DRIVE_LIST`,根本不会进那个分支。 `OnDriveList`(`McpServer.cpp:7832`)当前对空 `path` 一律判定为「只列盘」并把 `TOKEN_DRIVE_LIST` 当数据取走(`:7846-7851`),所以必须在它最前面按 `tool` 分流:文件写工具 → 下发 `followUp`、保持子连接、返回 `false`。 2. **三个完成 token 需要在服务端顶层分发新增 case。** `TOKEN_DELETE_FINISH` / `TOKEN_RENAME_FINISH` / `TOKEN_CREATEFOLDER_FINISH` 目前只在 `server/2015Remote/FileManagerDlg.cpp:983-995` 的 hDlg 路径里处理。MCP 的子连接 `hDlg == NULL`(`NotifyProc` 只有 hDlg 存在才交给对话框),三个包会落到 `2015RemoteDlg.cpp:7249` 的 `default:`——只打一行 "unknown command"、**并不关闭子连接**。必须新增 case:`TakeMainResponse` + `CancelIO`。 3. **`MarkLateFirstPacketForTool` 要登记新工具。** 否则工具超时后迟到的 `TOKEN_DRIVE_LIST` 会当成人工操作,**弹出 MFC 文件管理器窗口**。把新工具名加入 `TOKEN_DRIVE_LIST` 那条分支(`McpServer.cpp:7760`)即可。 ### 2.4 已知限制(必须写进工具描述) | 限制 | 原因 | 缓解 | |---|---|---| | **ack 只代表「已执行」,不代表「成功」** | 客户端忽略 `DeleteFile` / `MoveFile` / `MakeSureDirectoryPathExists` 的返回值,无条件 `SendToken(..._FINISH)` | 文档明确要求「调用后用 `list_files` 复核」;可选增强见 §5.7 | | **`move_path` 仅同卷** | 客户端用 `::MoveFile`(`client/file/FileManager.cpp:990`),非 `MoveFileEx` | 描述里写「跨盘请改用 `download_file` + `upload_file`」 | | **删除无回收站、目录递归** | `COMMAND_DELETE_DIRECTORY` → `DeleteDirectory` 递归删除 | 工具描述加显著警告;`recursive` 必须显式传 `true` | | **删除单个只读文件会静默失败** | `COMMAND_DELETE_FILE` 直接 `DeleteFile`(`:101`),不像 `DeleteDirectory` 那样先 `SetFileAttributes(...NORMAL)`(`:659`) | 描述里提示「只读文件请先改属性」 | | **`create_folder` 会自动建中间层** | `MakeSureDirectoryPathExists`,语义是「确保路径存在」而非「只建最后一级」 | 写进描述:传入已含文件名的路径会建出同名目录 | | **深目录递归删除可能压垮客户端** | `DeleteDirectory` 用无界 `wsprintf` 拼 `MAX_PATH` 栈缓冲(`:643/653/657`);`SearchFiles` 已在 8f718d9 加长度预判,删除/`FixedUploadList` 尚未 | 服务端拒绝超过 MAX_PATH 的 `recursive` 目标;彻底修复归 P12 | | 路径不存在时**不会**快速失败 | 客户端不回报 win32 码 | 需要客户端补 `TOKEN_FILE_OP_ERROR`(见 §5.7 与 §6 的 P12 批次) | ### 2.5 安全门 新增单一开关 **`McpFileWrite`**(默认 `0`),要求 `McpReadonly=0` 同时成立: - 不复用 `McpFileTransfer`:上传是「覆盖」,删除是「毁灭」,风险等级不同,必须能分别关。 - 三个工具全部登记 `readOnlyHint=false, destructiveHint=true`(`delete_path`)/ `false`(`move_path`、`create_folder`)。 - 审计:沿用 `AuditManageAction`,记录 `path=` 与 `recursive=`,**不记录文件内容**。 - 建议追加服务端侧保护:拒绝 `path` 落在系统关键目录(`C:\Windows`、`C:\Windows\System32`、`C:\Program Files`)下的 `delete_path`,除非另开 `McpFileWriteDangerous`。这一条可在实现时按需取舍,但**至少要把 `C:\Windows` 与盘根目录挡住**(`delete_path` 传 `C:\` + `recursive=true` 是灾难级误操作)。 --- ## 3. 新工具(P10-C):远程控制补全 + 工具族去重 ### 3.1 `remote_block_input`(P10-C,零客户端改动) | 项 | 内容 | |---|---| | 入参 | `id`、`session_id`、`block`(`true` / `false`) | | 命令 | 屏幕子连接上 `[COMMAND_SCREEN_BLOCK_INPUT][0\|1]`(2 字节,`client/ScreenManager.cpp:1198`) | | 门控 | 随 `remote_open`(`McpRemoteControl=1` + `McpReadonly=0`),不单独设开关 | **价值**:AI 做 GUI 自动化时,真人碰一下鼠标就会把流程打断;锁定对端键鼠是标准做法。 **必须做的两件事**(否则会把人锁在电脑外): 1. `remote_close` 与 idle 回收时**强制补发 `block=false`**; 2. 会话内 `block=true` 超过 `max_block_ms`(建议默认 300s)自动解锁并在结果里标注 `auto_unblocked=true`。 `BlockInput` 在进程退出时会自动解除,所以真正的死锁风险只出现在「客户端进程活着但会话丢了」——上面两条正好覆盖。 ### 3.2 工具族重叠:`list_*` vs `host_list_*`(P10-A,纯文档/描述改动) **这是当前最容易被忽略、但对模型影响最大的问题**。同一件事有两套工具,走两条完全不同的链路,门控也不同: | 能力 | 设备管理族(P2/P7) | 主机管理族(P8) | 差异 | |---|---|---|---| | 进程列表 | `list_processes`(`COMMAND_SYSTEM`→`CSystemManager`) | `host_list_processes`(`COMMAND_MACHINE_PROCESS`→`MachineManager`) | 后者字段更全(优先级、线程数、用户、工作集、文件大小),**且已有 `name`/`pid` 服务端过滤**(`McpMachine.cpp:2733-2741`) | | 窗口列表 | `list_windows`(`COMMAND_WSLIST`) | `host_list_windows`(`COMMAND_MACHINE_WINDOWS`) | 同上,后者也带过滤 | | 服务列表 | `list_services`(`COMMAND_SERVICES`→`ServicesManager`) | `host_list_win32_services`(`COMMAND_MACHINE_WIN32SERVICE`) | 后者含描述、登录身份 | | 窗口控制 | `operate_window`(含 `close`) | `host_control_window`(**无** `close`) | 门控不同 | 门控差异是关键:`host_list_*` 需要 `McpMachine=1`,而 `list_*` 只需 `McpReadonly`。所以: - `McpMachine=0` 时 `host_list_*` **不出现在 `tools/list`**,模型只能用 `list_*`; - `McpMachine=1` 时两套都在,模型**没有任何依据**判断该用哪个。 **结论比初稿更强:`host_list_*` 是首选而非平级备选**——字段更全、且过滤能力本来就已存在(`list_*` 要等 §5.3 补完过滤才追平)。`list_*` 的定位是「`McpMachine=0` 时的降级路径」。 **做法**(不需要合并工具,只改描述,风险极低): 1. 在两套工具的 `description` 里互相指路,且措辞要给出明确优先级: - `list_processes` → 「`McpMachine=0` 时的降级路径,字段较少;若 `host_list_processes` 在 `tools/list` 里,一律优先用它」; - `host_list_processes` → 「首选;与 `list_processes` 同源但字段更全并支持服务端过滤,仅在不可用时退回」。 2. 在 `initialize.instructions`(§5.8)里写一条选型规则,一次性讲清四组关系。 **不建议合并**:两族走不同子连接、不同能力位、不同门控,合并会破坏既有安全模型(`McpMachine` 开关的意义就是「单独关掉一套」)。 --- ## 4. 大能力(需独立立项,不建议并入本轮) ### 4.1 分级原则 下面这些能力「能做」但**不适合和文件写工具混在一个批次**:要么工程量大(代理、摄像头),要么安全边界必须单独评审(升级、执行、卸载)。按建议顺序列出。 | 能力 | 客户端改动 | 工程量 | 风险 | 建议 | |---|---|---|---|---| | 注册表写(set/delete value) | **需要**(无现成命令) | 中 | 高(可持久化篡改) | P12,独立开关 + 白名单键路径 | | Windows 事件日志读取 | **需要** | 中 | 低(只读) | P12,优先于注册表写 | | 进程模块 / 启动项 / 网络共享 | **需要** | 中 | 低(只读) | P12,补「主机取证」维度 | | 剪贴板只读 | **需要**(客户端只有写) | 小 | 中(读即泄密) | 维持 `Mcp_Design.md §10.7` 的「不做」结论 | | 窗口级一次性截图 | 需评估 | 中 | 低 | 见 §4.2 | | 代理隧道 `proxy_*` | 否(`COMMAND_PROXY` 已有) | **大** | 高 | 见 §4.3 | | 客户端升级 `upgrade_client` | 否(`COMMAND_UPDATE` 已有) | 中 | 高 | 见 §4.4 | | 上传执行 `upload_exec` | 否(已有) | 小 | **极高** | 默认不做,或仅 `McpMachineDangerous` 下 | | 摄像头快照 / 语音采集 | 否(已有流) | 大 | 中 | 后置 | | 写 hosts 文件 | 否(已有) | 小 | 高 | 见 §4.5 | ### 4.2 窗口级截图 `COMMAND_SCREEN_WINDOW`(`client/ScreenManager.cpp:894`)接的是**屏幕流**(按窗口标题捕获,空串恢复全屏),不是一次性 JPEG。要做 `get_screenshot(window_title=...)` 需要服务端在屏幕子连接上收若干帧再截一张,本质上是「起一个临时屏幕会话」——比现有 `get_screenshot`(主连接一次 RPC)重得多。 **建议**:先做「AI 侧的替代方案」——`remote_open` 已能拿全屏,`list_windows` 能给窗口句柄与标题,模型可以据此用 `remote_mouse` 点击。等 `remote_*` 在真实任务里被证明「全屏截图不够用」再投入。 ### 4.3 代理隧道(价值最高的「新维度」) `COMMAND_PROXY`(`client/KernelManager.cpp:1039` + `client/proxy/ProxyManager.cpp`)能把客户端当 SOCKS/端口转发跳板。MCP 化的形态是: ``` proxy_open(id, target_host, target_port, local_port) → 服务端本地监听 → AI 用普通 HTTP/DB 客户端访问 127.0.0.1:local_port → 流量经客户端转发到内网 target proxy_close(session_id) ``` **这会让 AI 从「操作主机」升级为「进入主机所在内网」**——价值远高于再加几个只读工具。 但代价是:服务端要起本地监听(防火墙/端口冲突/生命周期管理)、要做并发与超时、审计粒度要细到「连接目标」,而且这是一个**新的攻击面**(本机任意进程都能用这个监听)。建议单独立项,先出安全设计再动手。 ### 4.4 客户端升级 / 上传执行 - `upgrade_client`:`COMMAND_UPDATE` 链路完整,但升级失败会让主机**永久失联**,且没有回滚。至少要「先校验包完整性 + 保留旧版本 + 升级后 N 分钟无心跳则告警」。 - `upload_exec` / `download_exec`:等价于任意代码执行,**绕过 `exec_command` 的全部白名单约束**。这与现有安全模型(`McpCmdWhitelist` 逐条加白)根本冲突。**建议维持不做**;确有需要时只允许 `McpMachineDangerous` 下、且必须显式传 `confirm=true`。 ### 4.5 写 hosts 文件 `COMMAND_HOSTS_SET`(`client/MachineManager.cpp:318`)用 `CREATE_ALWAYS` **整文件覆盖**,且无回包、失败静默。MCP 化必须是「读-改-写」语义: - 入参只接受 `entries[]` 追加/删除,服务端先 `host_get_hosts_file` 读全文,服务端合并,再整文件下发; - 必须备份原文件(服务端存一份到 `%TEMP%`); - 门控 `McpMachineDangerous` + `McpReadonly=0`。 **建议**:本轮不做。误覆盖 hosts 会导致目标机 DNS 全断,恢复成本高。 --- ## 5. 现有工具优化 按「影响面 ÷ 成本」排序。P0 = 建议本轮做,P1 = 下一轮,P2 = 择机。 > 另有一项「两套工具族重叠」的优化放在 §3.2(因为要顺带说明它为什么不合并),同样是 P0。 ### 5.1 【P0,已完成 `bb55f52`】`get_host_detail` 增加 `capabilities` **问题**:模型拿到 `clientType=WIN` 就以为所有工具都能用,于是反复撞 `-32005`: | 工具 | 隐藏门槛 | 报错位置 | |---|---|---| | `get_screenshot` | `CLIENT_CAP_SCREEN_PREVIEW` 能力位 | `McpServer.cpp:2328` | | `remote_*` | 同上 + 单显示器(多屏现在报 `-32005`,不是 `-32008`) | `McpServer.cpp:3715` 附近 | | `list_registry` | 非 LNX/MAC | `McpServer.cpp:2569` | | `upload_file` | 客户端 `SupportsFileV2()` | `McpServer.cpp:4972` | | `get_keylog` | `McpKeylog=1` | 门控 | | `host_list_*` | `McpMachine=1` | 门控 | **做法**:在 `AppendHostTechnicalDetail`(`McpServer.cpp:2018`)末尾追加。只写**主机自身**的能力, 服务端开关不重复——`get_server_status` 的 `switches` 已经完整暴露(`McpServer.cpp:3142`), `monitors` 也已经有了(`:2048-2053`): ```cpp Json::Value caps(Json::objectValue); caps["platform"] = clientType; // WIN / LNX / MAC / APK caps["screenPreview"] = ctx->SupportsScreenPreview(); caps["remoteControl"] = ctx->SupportsScreenPreview() && monitors == 1; caps["fileTransferV2"] = ctx->SupportsFileV2(); caps["c2cPaths"] = ctx->SupportsC2CPaths(); caps["registry"] = (clientType != "LNX" && clientType != "MAC" && clientType != "APK"); host["capabilities"] = caps; ``` **收益**:模型在规划阶段就能排除不可用工具,把「试错 → 报错 → 换工具」的三轮往返压缩成一次。 **成本**:约 30 行,零客户端改动,`outputSchema` 加一个对象。 ### 5.2 【P0,已完成 `bb55f52`】`get_keylog`:补离线开关与真实状态(**已重写,初稿前提有误**) > **初稿的错误**:原文断言「现在只能采 1–15 秒窗口,对『昨天谁敲了什么』完全无用,需要新增 `mode=offline`」。 > 这是错的。`CKeyboardManager1` 构造时就 `new CircularBuffer(m_strRecordFile)`,而 `CircularBuffer` > 的构造函数直接 `LoadDataFromFile()`(`client/KeyboardManager.h:31-38`);`SendData` 每次(重)连上后 > 从 `pos=0` 把整个缓冲区推给服务端(`client/KeyboardManager.cpp:504-516`),缓冲区 10 MB > (`KeyboardManager.h:15`)。**只要目标机 `kbrecord=Yes`,现有的 `get_keylog` 已经把落盘历史 > (含无人在线的时段)一并返回了**——工具描述自己就写着「先把缓冲区里已有的记录(含历史)推给服务端」 > (`McpServer.cpp:1559`)。所以 `mode=offline` 不用做,做了也是重复实现。 **真正缺的两件事**: 1. **开关**:`COMMAND_KEYBOARD_OFFLINE`(2 字节)与 `COMMAND_KEYBOARD_CLEAR`(1 字节) 已实现于 `client/KeyboardManager.cpp:125` / `:131`,就在 `get_keylog` 已经建立的那条 键盘子连接上,MCP 侧从未下发过。 2. **状态自述**:客户端在就绪包 `TOKEN_KEYBOARD_START` 的 `byte[1]` 里已经带了「离线记录是否开启」 (`client/KeyboardManager.cpp:164`),服务端 `get_keylog` 拿到了这个包却没解析。 模型因此不知道「我看到的这些历史是不是全量」。 **做法**: | 参数 | 语义 | |---|---| | `offlineRecord`(**输出**) | 客户端当前是否开着离线常驻记录,取自 `TOKEN_KEYBOARD_START` 的 `byte[1]`;`false` 时历史只覆盖本进程启动后的在线时段 | | `set_offline`(输入,`true`/`false`) | 下发 `COMMAND_KEYBOARD_OFFLINE` 改变常驻状态。写操作:需 `McpReadonly=0` | | `clear`(输入,`true`) | 下发 `COMMAND_KEYBOARD_CLEAR` 清空客户端缓冲区与落盘文件。破坏性:需 `McpReadonly=0`,且应排在采集之前 | 两个写动作都必须**先于采集窗口下发**,且失败要如实返回(`Send2Client` 的返回值要检查)。 ### 5.3 【P0,已完成 `bb55f52`】`list_processes` / `list_windows` 增加服务端过滤 **问题**:`BuildPagedHostListInputSchema` 只有 `{id, limit, offset}`(`McpServer.cpp:776`,调用点在 `:1477` 等)。一台正常 Windows 有 200–400 个进程、几十个窗口,模型要翻 3–4 页才能找到目标;每页都是完整字段,上下文开销很大。 **做法**:加可选 `name`(进程名/窗口标题子串,ASCII 不区分大小写)与 `pid`,在服务端分页**之前**过滤,`total` 为命中数、`totalAll` 为总数。口径照抄 `BuildSearchHosts`(`McpServer.cpp:1878-1887`): ```cpp ApplyPageWindow(matched, page, pageItems); if (filtered) page.totalAll = (int)all.size(); // 过滤前总数 ``` **收益**:`list_processes(name="chrome")` 从 3 页变 1 条;两套工具族的能力也对齐了(`host_list_*` 本来就有这两个参数)。 ### 5.4 【P1,已完成 `1c832ff`】`power_action` 增加结果验证 **问题**:`power_action` 是「发完即走、无响应」(`McpServer.cpp:5812` 附近注释),返回 `ok:true` 只代表**命令写进了 socket**。模型会误以为「已重启」,紧接着调 `list_processes` 却拿到旧进程列表。 **做法**:加 `wait`(默认 `false`)与 `wait_ms`(默认 60000): - `wait=true`:轮询主连接是否断开 → 再轮询是否重新上线,返回 `{sent:true, went_offline:true, came_back:true, elapsed_ms}`; - 超时不算失败,返回 `came_back:false` 让模型自己决定。 ### 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,已完成 `1c832ff`(`-32012`,`-32008` 留作别名)】错误码:`-32008` 其实只有两种语义 > **初稿的错误**:原文说 `-32008` 一码四义(含「老客户端格式」「多显示器不支持」)。核对后全文件只有两处 > `-32008`:`exec_command` 的 shell 元字符(`McpServer.cpp:2901`)与 `terminal_exec` 的 `&`/`|`/换行 > (`McpServer.cpp:3465`)——**两者都是「改参数可修」**。多显示器早就改成 `-32005` 了,代码注释明说 > 「这是能力限制、改参数也修不好」(`McpServer.cpp:3715`)。能力类错误已经统一走 `-32005`。 因此拆分只剩一个干净的诉求:把「参数非法」从 `-32008` 换成 MCP 语义更准确的 `-32012`。 | 新码 | 语义 | 模型动作 | |---|---|---| | `-32012` | Validation rejected(参数非法,改参数可修) | 修参数重试 | `-32008` 保留为历史别名(不破坏既有客户端与已发布的文档)。这是一次纯常量替换,收益是让模型 不必读英文 message 就能区分「改参数」与「换主机」,但**优先级低于 P0 各项**。 ### 5.7 【P1,部分完成 `27b5431`:`verified` 三态已落地,`verify_hint` 字段未加】写工具的 ack 语义显式化 现状:`delete_path` / `move_path` / `create_folder` / `kill_process` / `operate_window` / `control_service` 的 ack 都是**客户端无条件回包**,不代表操作成功。 两条路,建议都做: 1. **文档层**:`outputSchema` 里加 `verified: bool`(可为 `null`)与 `verify_hint: string`("call list_files on the parent directory to confirm"); 2. **实现层**(低成本高收益):`delete_path` / `move_path` 在收到 ack 后,**在同一个子连接上**再补一次 `COMMAND_LIST_FILES` 校验父目录,把 `verified` 填成真实结果。注意不是"多开一次子连接":子连接还开着,客户端收到 finish 后就在等下一条命令,所以代价只是同一连接上的一次往返(约 50–150ms)。实现要点是重新登记一个 `list_files` 挂起(`BeginPending(devId, "list_files", path)`,`McpServer.cpp:7795` 已有该重载),再直接 `Send2Client`;`TOKEN_FILE_LIST` 的现有 case 会在投递结果后 `CancelIO` 收尾,正好完成清场。校验本身失败(超时/连接断)时 `verified` 返回 `null`,**不要谎报 false**。 彻底的做法是客户端补 `TOKEN_FILE_OP_ERROR`(带 win32 码),归入 §4.1 的 P12 批次。 ### 5.8 【P1,已完成 `bb55f52`】`initialize` 返回 `instructions` **问题**:模型对这套服务端的「隐性知识」全靠工具描述拼凑:主机 id 是 64 位雪花值(不能猜)、要先 `list_online_hosts` 再操作、`-32003` 是单设备单飞行、`-32006` 不要重试、远程控制要先 `remote_open` 拿 `session_id`。`Mcp_Design.md` 把这些写在文档里,但**模型看不到文档**。 **做法**:`initialize` 响应里加 `instructions`(纯文本,建议 600–900 字),内容: 1. 主机 id 的获取方式与形态(禁止猜测); 2. 工具族与开关关系(哪些工具可能不在 `tools/list` 里,为什么); 3. 错误码 → 动作的对照(只列 6 个高频码); 4. 典型任务编排(文件整理、进程排查、GUI 自动化各一段); 5. 「同一主机同时只能有一个远程请求」的约束。 **收益**:这是**单点投入、全局收益**的改动——所有客户端的每一次会话都受益,且零风险。优先级应当排在所有新工具之前。 ### 5.9 【P2,已完成 `1c832ff`】`notifications/progress` 与 `notifications/cancelled` **问题**: - `download_file` 默认超时 600s、`upload_file` / `copy_files_c2c` 同类、`search_file` 最长 120s、`chat_wait` 最长 55s。这段时间里客户端**收不到任何信号**,模型和用户都以为卡死。 - 客户端取消请求(用户按 Esc / 关闭会话)时,服务端**不会中止**正在进行的传输,主机会被锁到超时为止(实测报告 P2 的 600 秒锁定就是这类后果)。 **做法**: - 长任务在 `tools/call` 的 `_meta.progressToken` 存在时,按 1–2 秒节流推送 `notifications/progress`(`progress` = 已传字节 / 总字节); - 维护「进行中的请求 → 会话」映射,收到 `notifications/cancelled` 时走既有的清理路径(清 pending、关子连接、删半成品文件)。 这两项都在 `McpServer.cpp` 的 HTTP 处理器层,**不动任何工具实现**。 ### 5.10 【P2,已完成 `1c832ff`】会话可观测与自救 `-32003 Device busy` 现在是死路:模型不知道是谁占着这台主机、也不知道等多久。建议加两个纯服务端工具: | 工具 | 作用 | |---|---| | `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` 体积 **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)会挤占绝大部分预算,且**每轮对话都要重传**(多数客户端不缓存)。 三个可选做法(不建议同时上): 1. **精简描述**(推荐):把「实现细节、限制、已知问题」从 `description` 移到 `instructions` 或工具文档,`description` 只保留「做什么 + 关键约束」一两句。可省 30–40%。 2. **工具族合并**:`host_list_processes` … `host_get_hosts_file` 这 10 个合并为 `host_list(tab, id, limit, offset)`。省 9 个工具、约 20% 体积,代价是 `annotations` 与 `outputSchema` 变粗(10 个 tab 的条目结构不同),**discoverability 也会下降**——模型看到 `tab` 枚举才知道有哪些能力。**不建议**。 3. **可配置 profile**:`McpToolProfile=full|compact`,compact 只出 `name + 一句话 + 必填参数`。适合小模型客户端,但要维护两套描述。 ### 5.12 【P2】`control_service` 的逐项 `Sleep(500)` `client/ServicesManager.cpp:213` 的 `ServicesConfig` 对每一项 `Sleep(500)` 后再回列表。批量控制 10 个服务 = 至少 5 秒。服务端可以在 `action` 里支持 `items[]` 批量下发(一次子连接、一个 payload),把 N 次往返压成 1 次。**前提是确认客户端能解析多条目 payload**——按现有实现它只处理单条,需要客户端改动,因此列为 P2。 ### 5.13 【P0,已修】`kToolHints` 表头注释过期 原注释写「53 个工具的语义登记表」,与数组实际长度不符。P10-A(`bb55f52`)先改成 54, P10-C(`3d388f8`)加工具时索性去掉数字——避免每加一个工具就要改一次注释; 核对方式见 §1.1,60 个工具与 60 项注解逐条对应。 ### 5.14 其他小项 | 项 | 位置 | 说明 | |---|---|---| | ~~`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` | 已正确标注非幂等,无需改 | --- ## 6. 批次与验收建议 | 批次 | 状态 | 内容 | 客户端改动 | 规模 | 验收方式 | |---|---|---|---|---|---| | **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,**每批独立提交**(已于 2026-10-28 按序完成; 未推送前按批次合并了零碎提交,故每批各一个提交,见上表)。 理由:P10-A 全是**几十行代码换全局体验**的改动(能力自述 + 使用说明 + 描述互指),先落地能立刻降低后续所有工具的试错率,且几乎不引入回归风险;P10-B 是最大的功能缺口,但涉及删除语义,需要更充分的测试与开关灰度;P10-C 小而独立,可随时插入。 --- ## 7. 明确不做(本轮) | 项 | 理由 | |---|---| | 剪贴板只读 | 常含口令/令牌/私钥,「读即泄密」,且客户端无只读链路(维持 `Mcp_Design.md §10.7`) | | 上传执行 / 下载执行 | 等价任意代码执行,与 `McpCmdWhitelist` 逐条加白的安全模型冲突 | | 写 hosts 文件 | `CREATE_ALWAYS` 整文件覆盖 + 无回包,误操作导致目标机 DNS 全断 | | 卸载软件 | `WinExec` 卸载串,无回包、可能弹 UAC 阻塞,无法确认结果 | | 清除事件日志 / 隐藏开网页 / 卸载后门 | 当前 Windows 客户端**未实现**这些命令(死命令) | | `Ctrl+Alt+Del` / 黑屏 | 客户端未实现,需客户端改动 | | 10 个 `host_list_*` 合并为 1 个 | 体积收益 20%,discoverability 损失更大(见 §5.11) | --- ## 附录 A:本轮核对过的客户端命令清单 Windows 客户端**已实现**、可作为新工具基础、MCP 尚未使用: ``` COMMAND_DELETE_FILE → TOKEN_DELETE_FINISH client/file/FileManager.cpp:97 COMMAND_DELETE_DIRECTORY → TOKEN_DELETE_FINISH client/file/FileManager.cpp:106 COMMAND_CREATE_FOLDER → TOKEN_CREATEFOLDER_FINISH client/file/FileManager.cpp:116 COMMAND_RENAME_FILE → TOKEN_RENAME_FINISH client/file/FileManager.cpp:119 COMMAND_HOSTS_SET → (无回包, 整文件覆盖) client/MachineManager.cpp:318 COMMAND_APPUNINSTALL → (无回包, WinExec) client/MachineManager.cpp:160 COMMAND_SCREEN_BLOCK_INPUT → (无回包, 2 字节) client/ScreenManager.cpp:1198 COMMAND_KEYBOARD_OFFLINE → (无回包, 2 字节) client/KeyboardManager.cpp:125 COMMAND_KEYBOARD_CLEAR → (无回包, 1 字节) client/KeyboardManager.cpp:131 COMMAND_UPDATE → 升级链路 client/KernelManager.cpp:1466 COMMAND_UPLOAD_EXEC → 执行上传文件 client/KernelManager.cpp:880 COMMAND_PROXY → 端口转发 client/KernelManager.cpp:1039 COMMAND_SCREEN_WINDOW / _ROI → 流式窗口/区域捕获 client/ScreenManager.cpp:894 / :886 COMMAND_WEBCAM / COMMAND_AUDIO→ 流式音视频 client/KernelManager.cpp:1399 / :1414 ``` > 已排除 `COMMAND_PROCESS_FREEZING` / `COMMAND_PROCESS_THAW`——它们**已被 `host_control_process` 使用** > (`McpMachine.cpp:2107`),不属于缺口。 **定义了但 Windows 客户端未实现**(不可用):`COMMAND_CLEAN_EVENT`、`COMMAND_OPEN_URL_HIDE`、`COMMAND_OPEN_URL_SHOW`、`COMMAND_REMOVE`、`COMMAND_SCREEN_CTRL_ALT_DEL`、`COMMAND_SCREEN_BLANK`。 --- ## 附录 B:本轮核对过的关键代码位置 | 主题 | 位置 | |---|---| | 工具注解登记表(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` | | 文件链路(列目录/搜索/下载) | `McpServer.cpp:2419` / `:8050` / `:6430` | | 机器管理写工具范式 | `McpMachine.cpp:2531` `AddTool` / `:2127` `host_control_process` | | `power_action`(发完即走) | `McpServer.cpp:5812` | | `get_keylog`(固定窗口) | `McpServer.cpp:1558` / `:5985` | | 配置键全集 | `2015RemoteDlg.cpp:2416` 起 + `McpSettingsDlg.cpp:227` / `:383` | | 错误码表 | `docs/Mcp_Design.md §12` | | 已修问题与实测 | `docs/Mcp_Test_Report_2026-10-25.md §0` | --- ## 附录 C:服务端接线点(P10-B 施工前必读) MCP 子连接的分包路由有三层,新增一个「用子连接完成一次写操作」的工具时,**必须三处都改**, 少改任何一处都会出现「命令发不出去」「子连接泄漏」或「弹 MFC 窗口」: | 层 | 位置 | 作用 | 不改的后果 | |---|---|---|---| | 1. 就绪包分流 | `McpServer::OnDriveList`(`McpServer.cpp:7832`) | 子连接建好后的第一个包(`TOKEN_DRIVE_LIST`)到达;按 `tool` 决定下发什么 | 沿用「空 path = 只列盘」判定 → 写命令永远发不出去,工具超时 | | 2. 完成包投递 | `CMy2015RemoteDlg::MessageHandle`(`2015RemoteDlg.cpp:6003` 的 switch) | 三个 `TOKEN_*_FINISH` 目前无 case | 落到 `default:` 只打日志、不关子连接 → 子连接泄漏 + 工具等到超时 | | 3. 迟到吸收 | `CMcpServer::MarkLateFirstPacketForTool`(`McpServer.cpp:7760`) | 工具放弃后吸收迟到的就绪包 | 目标机上**弹出 MCP 自己触发的文件管理器窗口** | 另一处相关:`NotifyProc`(`2015RemoteDlg.cpp:5581`)在 `ContextObject->hDlg` 非空时把包转给对话框, MCP 路径的 `hDlg` 恒为 `NULL`,所以第 2 层一定会命中——这一点已核对,不是假设。 配置开关的接线也是三处:读取(`2015RemoteDlg.cpp:2416` 块)、对话框回填(`McpSettingsDlg.cpp:227`)、 落盘(`McpSettingsDlg.cpp:383`)。对话框是**纯代码构建**的(`McpSettingsDlg.cpp:128-186`), 插入一个 checkbox 需要重排其下所有控件的 y 坐标与窗口高度。 --- ## 附录 D:P11 施工记录(2026-10-28) 零客户端改动,全部落在服务端(`McpServer.cpp` / `McpServer.h` / `McpMachine.cpp` / `McpChat.cpp` / `McpInternal.{h,cpp}`)。 ### D.1 `power_action` 的结果验证(§5.4) - 新入参 `wait`(bool,默认 false)与 `wait_ms`(1000–600000,默认 60000),`wait_ms` 是 「等离线」与「等回线」**各自**的时限;`wait=false` 时也会校验 `wait_ms` 的取值范围。 - 输出从 `{ok}` 扩展为 `{ok, sent, went_offline, came_back, elapsed_ms}`: `sent` 恒为 true(命令写进 socket),`went_offline` / `came_back` 由主连接的出现/消失判定 (`FindMainContext`,200ms 轮询),`elapsed_ms` 为整次调用的耗时。 - **超时不是错误**:`wait=true` 但没等到离线/回线时仍返回 `ok:true` 并在正文里写清「仍在 线」或「已离线但未回线」,让模型据此决定是否再等,而不是把「没等到」当成失败重试。 - `logout` 之后主机不会自动回线(需要人工登录),正文单独提示。 ### D.2 破坏性工具统一 `dry_run`(§5.5) | 工具 | `dry_run=true` 时的行为 | |---|---| | `kill_process` | 只取一次进程列表,回 `{ok, dry_run, targets:[{pid,name,path}], missing:[pid...]}`,**不下发终止命令**;一个都匹配不到返回 `-32009` | | `operate_window` | 只取一次窗口列表,回 `{ok, dry_run, action, window}`;窗口不存在返回 `-32009` | | `host_control_process` / `_window` / `_service` / `_task` | 只做目标存在性校验,回 `{ok, dry_run, action, target, state, detail}`(detail 是被影响对象的原始字段) | 实现要点:dry run 的挂起项以 `"/dryrun"` 登记,`OnSystemReady` 只认 `kill_process` / `operate_window` 两个**精确**工具名,因此不会误发后续写命令;迟到首包仍按既有逻辑吸收。 ### D.3 `-32012` 与 `-32008` 别名(§5.6) - 两个真实站点(`exec_command` 的 shell 元字符、`terminal_exec` 的 `&`/`|`/换行)改为 `McpInternal::kErrValidation = -32012`;`kErrValidationOld = -32008` 保留为历史别名,不再新增使用。 - `initialize.instructions` 的错误码表与 `docs/Mcp_Design.md §12` 同步;`-32800` 一并登记。 ### D.4 `notifications/progress` 与 `notifications/cancelled`(§5.9) **传输**:本服务端原本每个 POST 只回一个 JSON。带 `params._meta.progressToken` 的 `tools/call` 改走 MCP Streamable HTTP 允许的 `text/event-stream`(同一个 POST): 1. 工具在独立线程执行,`McpCallContext` 经 FLS(Fiber Local Storage)暴露给工具实现 ——**不能用 `thread_local`**:本工程有 shellcode/MemoryModule 手工映射出来的线程,没有 PE 的 TLS 初始化,加一个静态 `thread_local` 就会让服务端启动约 1s 后跳飞(实测); 2. 进度通知与最终响应都从这个 SSE 流写出(`McpProgressChannel`,背压队列上限 64 条, 满了丢最旧——进度是「最新值有意义」的信号); 3. 不带 token 的请求完全不变(一次性 JSON)。 **进度上报点**(`McpCallProgress`,内部 1s 节流): | 工具 | 进度含义 | |---|---| | `download_file` | `filesDone / (totalFiles - directoryCount)`;总量未知时退回已收字节数 | | `upload_file` | 已发数据字节 / 待发数据字节总数(在 worker 的分块回调里累加) | | `copy_files_c2c` | 源端只在最后回一包结果,因此不报中间进度;取消/超时按既有路径收尾 | | `search_file` | 命中数在客户端,服务端只在收尾时报一次结果(见下) | | `chat_wait` | 等待期无中间量,取消即时生效 | **取消**:三条入口共用一个取消位(`McpCallContext::cancelled`) - `notifications/cancelled`(`params.requestId` 按 JSON-RPC id 精确匹配,字符串与数字不混用); - `mcp_cancel_session`(按 request_id / host id / session_id); - SSE 流写失败(客户端已断开)。 所有长等待都改成「≤500ms 一片 + 每片检查取消位」(`WaitWithCancel`),取消后直接落到各函数 **既有的超时/放弃分支**:`MarkLateFirstPacketForTool` 照登、子连接照关、挂起项照删。因此取消 不需要第二套清理逻辑,也满足「取消后主机 1s 内释放」。取消导致的失败结果由分发层统一改写成 `-32800`(已经拿到成功结果则照实返回)。 ### D.5 `mcp_list_sessions` / `mcp_cancel_session`(§5.10) - `mcp_list_sessions`:一次快照列出在飞 `tools/call`(含 JSON-RPC `request_id`)、挂起中的一次性 请求、终端、远程控制、文件传输、远程交谈;字段 `host_id/kind/tool/session_id/request_id/busy/ elapsed_ms/idle_ms`,可选 `kind` 过滤。纯本地,**不受功能开关与只读模式限制**。 - `mcp_cancel_session`:按 `request_id`(精确)或 `id`/`session_id`(条件)取消,返回 `{cancelled, released, waited_ms, matched}`;最多等 2s 让工具线程走完清理,`released` 说明 主机是否真的松开。 - `-32003` 的文案统一追加占用者:`Device busy: another request is pending for this host (tool=download_file, elapsed=12s)`。`DescribeBusy` 会排除发起本次错误的那个调用自身。 ### D.6 已知边界 - SSE 请求会占住 httplib 的一个 worker 线程直到工具结束(线程池 32);单机管理场景足够, 不作为多租户端点使用。 - `search_file` 被取消时返回**已收到的部分结果**(`finished=false`),不是 `-32800`:搜索是只读 累积操作,部分结果对调用方更有用;它同样在 ≤1s 内释放主机。 - `mcp_cancel_session` 找不到匹配项时返回 `cancelled:0`(不是错误)——请求可能已经结束, 或 `request_id` 的 JSON 类型与调用时不一致。