diff --git a/docs/Mcp_Next_Plan.md b/docs/Mcp_Next_Plan.md new file mode 100644 index 0000000..a1d1c8c --- /dev/null +++ b/docs/Mcp_Next_Plan.md @@ -0,0 +1,594 @@ +# 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 个功能族),但仍有三处结构性缺口: + **文件系统只有读没有写**(能列、能搜、能传,不能删/改名/建目录)、 + **远程控制缺「防人工干扰」与「能力自述」**(无法锁定对端键鼠、模型不知道主机支持什么)、 + **同一能力存在两套重叠工具**(`list_processes` vs `host_list_processes` 等 4 组,模型不知该选哪个)。 +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)时模型以为卡死」的体验。 +5. **不建议现在做**的:注册表写、Windows 事件日志、进程模块/启动项、剪贴板读——都需要客户端改, + 且安全边界要单独评审;代理隧道(`COMMAND_PROXY`)价值最高但工程量大,建议单独立项。 + +> **一处需要纠正的常见误解**:进程「挂起 / 恢复」**已经实现**,不需要新工具—— +> 它是 `host_control_process` 的 `action=freeze|thaw`(`McpMachine.cpp:2107`), +> 且已带「动作后重拉进程列表复核」的验证逻辑。本轮不再重复造这个工具。 + +--- + +## 1. 现状盘点 + +### 1.1 工具族(54 个) + +登记表在 `server/2015Remote/McpInternal.cpp:368` 的 `kToolHints[]`。 +注意:**表头注释写「53 个工具」,实际数组是 54 项**(注释已过期,属一处文档瑕疵,见 §5.13)。 + +| 族 | 数 | 工具 | 门控条件 | +|---|---|---|---| +| 服务端本机只读 | 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`) | +| 设备管理 | 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` | +| 远程交谈 | 4 | `chat_open` `chat_send` `chat_wait` `chat_close` | `McpChat=1`(与 `McpReadonly` 无关) | + +**已有的工程范式**(新工具直接复用,不必重新设计): + +- **一次性子连接 + 首包即数据**:`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】`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】`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】`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】`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】破坏性工具统一 `dry_run` + +`kill_network_connection` 有 `dry_run`(实测报告「观察项」明确肯定了这个设计),但 `kill_process`、`operate_window(close)`、`host_control_*` 都没有。建议统一:`dry_run=true` 时只做「目标存在性校验 + 返回将被影响的对象」,不执行。 + +对 AI 尤其重要:模型可以在执行前把「我要杀这 3 个进程」摆给用户看。 + +### 5.6 【P2,收益被初稿高估】错误码:`-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】写工具的 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】`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】`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】会话可观测与自救 + +`-32003 Device busy` 现在是死路:模型不知道是谁占着这台主机、也不知道等多久。建议加两个纯服务端工具: + +| 工具 | 作用 | +|---|---| +| `mcp_list_sessions` | 列出所有在飞会话:`{host_id, tool, session_id, started_at, idle_ms, kind}` | +| `mcp_cancel_session` | 按 `session_id` 强制中止(等价于 `notifications/cancelled` 的内部路径) | + +`-32003` 的 message 里带上「当前占用者与已持续时间」,模型就能自己决定「等」还是「取消」。 + +### 5.11 【P2】`tools/list` 体积 + +54 个工具、每个都带完整中文描述 + 双 schema。实测**工具描述与属性说明文本合计约 23 KB**(54 条 `description` + 158 条 schema 属性说明),叠加 JSON 结构与 schema 骨架后,`tools/list` 响应实际在 **45–60 KB** 量级。 + +对 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` 表头注释过期 + +`McpInternal.cpp:367` 注释写「53 个工具的语义登记表」,实际数组 **54 项**。一行修复。 + +### 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` 的注释都过期,应一并更正 | +| `get_screenshot` 无区域裁剪 | `McpServer.cpp:2085` | 有 `max_width`;ROI 需客户端改动,收益有限,不做 | +| 审计不含调用参数 | `Mcp_Design.md §10.8` | 有意设计(防泄漏),维持 | +| `chat_wait` 会取走 inbox | `McpInternal.cpp:431` | 已正确标注非幂等,无需改 | + +--- + +## 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** | `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 → P10-B → P10-C → P11,**每批独立提交**。 + +理由: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:本轮核对过的关键代码位置 + +| 主题 | 位置 | +|---|---| +| 工具注解登记表(54 项) | `server/2015Remote/McpInternal.cpp:368` | +| `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 坐标与窗口高度。