New Windows clients advertise CLIENT_CAP_SCREEN_REGION and accept a 24-byte ScreenPreviewReqEx appended to the existing 8-byte preview request, so get_screenshot can capture a region, a window or a single monitor at 1:1 resolution instead of only the scaled virtual desktop. Successful v2 responses append an optional ScreenCaptureMeta block reporting the source rect and scale, letting callers map coordinates back for remote input. Old clients and old servers keep the v1 byte stream unchanged. The 8192 px per-side bound only applies to native (1:1) capture, where it guards bitmap memory; scaled captures are unaffected so ultra-wide virtual desktops (for example triple 4K) still produce thumbnails and previews. max_width is clamped to [64,1920] as before instead of rejected, matching the documented schema. Co-Authored-By: deepseek-flash
54 KiB
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. 结论摘要
- 工具面已经覆盖「看 + 管 + 连」三层(本方案写作时 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 用描述互指解决,未合并工具)。 - 最高性价比的一批新工具是文件系统写操作(
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。 - 最大的非工具类短板是「能力自述」:
get_host_detail不告诉模型这台主机支持什么, 模型只能靠-32005试错(list_registry、get_screenshot、remote_*、upload_file各有平台/能力位门槛)。 补一个capabilities对象是纯服务端改动、几十行代码,但直接减少一整类无效调用。 服务端开关态不必另开字段——get_server_status的switches已经完整暴露(McpServer.cpp:3142),capabilities只描述「这台主机本身能做什么」,两者分工明确。 - 协议层有四个空白:
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)。 - 不建议现在做的:注册表写、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。
但接入点必须新写三处,这是本节的主要工作量:
- 就绪包分流走
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。 - 三个完成 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。 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 自动化时,真人碰一下鼠标就会把流程打断;锁定对端键鼠是标准做法。 必须做的两件事(否则会把人锁在电脑外):
remote_close与 idle 回收时强制补发block=false;- 会话内
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 时的降级路径」。
做法(不需要合并工具,只改描述,风险极低):
- 在两套工具的
description里互相指路,且措辞要给出明确优先级:list_processes→ 「McpMachine=0时的降级路径,字段较少;若host_list_processes在tools/list里,一律优先用它」;host_list_processes→ 「首选;与list_processes同源但字段更全并支持服务端过滤,仅在不可用时退回」。
- 在
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 窗口级截图
已完成(2026-11-10,CLIENT_CAP_SCREEN_REGION):get_screenshot 新增 mode=window
(按 hwnd 原生分辨率抓取)以及 mode=region / mode=monitor,走主连接 v2 RPC + 客户端
GetWindowRect / StretchBlt,一次性返回 JPEG 并附源矩形元数据,不需要为单张截图起
屏幕流子会话。COMMAND_SCREEN_WINDOW 仍适用于需要持续窗口视频流的场景,与一次性
JPEG 不冲突;详见 Mcp_Design.md §21。
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):
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不用做,做了也是重复实现。
真正缺的两件事:
- 开关:
COMMAND_KEYBOARD_OFFLINE(2 字节)与COMMAND_KEYBOARD_CLEAR(1 字节) 已实现于client/KeyboardManager.cpp:125/:131,就在get_keylog已经建立的那条 键盘子连接上,MCP 侧从未下发过。 - 状态自述:客户端在就绪包
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):
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 都是客户端无条件回包,不代表操作成功。
两条路,建议都做:
- 文档层:
outputSchema里加verified: bool(可为null)与verify_hint: string("call list_files on the parent directory to confirm"); - 实现层(低成本高收益):
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 字),内容:
- 主机 id 的获取方式与形态(禁止猜测);
- 工具族与开关关系(哪些工具可能不在
tools/list里,为什么); - 错误码 → 动作的对照(只列 6 个高频码);
- 典型任务编排(文件整理、进程排查、GUI 自动化各一段);
- 「同一主机同时只能有一个远程请求」的约束。
收益:这是单点投入、全局收益的改动——所有客户端的每一次会话都受益,且零风险。优先级应当排在所有新工具之前。
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)会挤占绝大部分预算,且每轮对话都要重传(多数客户端不缓存)。
三个可选做法(不建议同时上):
- 精简描述(推荐):把「实现细节、限制、已知问题」从
description移到instructions或工具文档,description只保留「做什么 + 关键约束」一两句。可省 30–40%。 - 工具族合并:
host_list_processes…host_get_hosts_file这 10 个合并为host_list(tab, id, limit, offset)。省 9 个工具、约 20% 体积,代价是annotations与outputSchema变粗(10 个 tab 的条目结构不同),discoverability 也会下降——模型看到tab枚举才知道有哪些能力。不建议。 - 可配置 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 无区域裁剪 |
— | 已完成(2026-11-10):新增 mode=region/window/monitor,默认原生分辨率并返回 capture 源矩形元数据;见 Mcp_Design.md §21 |
| 审计不含调用参数 | 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 的挂起项以 "<tool>/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):
- 工具在独立线程执行,
McpCallContext经 FLS(Fiber Local Storage)暴露给工具实现 ——不能用thread_local:本工程有 shellcode/MemoryModule 手工映射出来的线程,没有 PE 的 TLS 初始化,加一个静态thread_local就会让服务端启动约 1s 后跳飞(实测); - 进度通知与最终响应都从这个 SSE 流写出(
McpProgressChannel,背压队列上限 64 条, 满了丢最旧——进度是「最新值有意义」的信号); - 不带 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-RPCrequest_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 类型与调用时不一致。