Docs: Plan the next MCP phase, with its claims checked against the code
Mcp_Next_Plan.md lays out what the MCP surface can still gain and how the
existing tools can be improved: a full client-command coverage matrix, a
file-system write batch, a remote-control gap, and a list of protocol-level
blanks. Every conclusion is tied to a file and line so the next step can be
implemented without re-deriving the analysis.
The first draft was written from a read of the code but not verified against
it. Auditing it turned up four claims that would have sent the work in the
wrong direction, and they are corrected here rather than left to be discovered
during implementation:
- The draft wanted a mode=offline for get_keylog because "the tool only sees a
1-15s live window". That premise is false. CKeyboardManager1 builds its
CircularBuffer from the on-disk record file, and SendData replays the whole
buffer from position zero on every (re)connect, so the existing tool already
returns the persisted history whenever kbrecord=Yes. What is actually missing
is only the on/off switch, the clear command, and reporting the state the
client already sends in TOKEN_KEYBOARD_START byte 1.
- Unlike P7, the file-write tools do not plug into OnSystemReady: their ready
packet is TOKEN_DRIVE_LIST, which lands in OnDriveList, where an empty path
is currently read as "list drives" and consumed. Worse, the three finish
tokens have no case at all in the top-level dispatch, so on the MCP path
(hDlg == NULL) they fall into default: and the sub-connection is never
closed. Appendix C now spells out the three wiring layers that every
sub-connection write tool has to touch.
- -32008 carries two meanings, not four: both remaining sites are argument
validation, and the multi-monitor rejection was already moved to -32005.
Dropping the proposed -32013 removes a whole error-code split.
- The draft put server gate state into get_host_detail, duplicating the
switches object that get_server_status already returns; monitors and most
per-host facts are already there too, so capabilities shrinks to the
client's own ability bits.
It also records what the audit added: delete_path inherits the client's
unbounded wsprintf when recursing (the search path got a length guard in
8f718d9, DeleteDirectory and FixedUploadList did not), a single read-only file
fails silently while a directory delete clears the attribute first, and
create_folder means "ensure this path exists" rather than "create the last
component".
Co-Authored-By: deepseek-flash
This commit is contained in:
1 parent
106ac2ff0f
commit
4a3cded174
1 file changed
+594
@@ -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 坐标与窗口高度。
|
||||
Reference in new issue
Block a user