Files
SimpleRemoter/docs/Mcp_Next_Plan.md
T
yuanyuanxiang cdd9c56b3d Feature: Add window/region capture targets to remote_open
Pass the target HWND through the COMMAND_SCREEN_SPY token and send
COMMAND_SCREEN_ROI after session start, so MCP remote control can stream
just the target window or region instead of the scaled virtual desktop.
The session records the target kind, remote_mouse refuses a redundant
window_hwnd basis, and the cached resolution is refreshed per action so
resized windows keep mapping correctly. Cold starts now clear the stale
resolution cache used by the region handshake.
2026-11-10 19:13:45 +01:00

55 KiB
Raw Blame History

MCP 能力扩展与优化方案(P10 起)

版本:v2(已按代码核对修订) 状态:评审通过,按 §6 顺序施工 前置文档:Mcp_Design.md(协议/架构/配置/错误码)、Mcp_Phase2_Design.md(双模式无头驱动)、 Mcp_Manage_Design.md(P7 写工具范式)、Mcp_Machine_Design.md(P8 会话抽象)、 Mcp_Terminal_Design.md、Mcp_RemoteControl_Design.md、Mcp_FileTransfer_Design.md、Mcp_Chat_Design.md、 Mcp_Test_Report_2026-10-25.md(实测结论与已修问题)

本文回答两个问题:还能做哪些工具、现有工具还能怎么优化。所有结论都落到具体文件与行号, 并区分「客户端零改动」「需客户端改动」「客户端尚未实现」三种可行性。

v2 修订要点(逐条核对代码后更正,详见各节开头的「初稿的错误」): §5.2 的 mode=offline 前提不成立(历史数据本来就会回传);§2.3 低估了服务端接线工作量; §5.6 的「一码四义」不成立;§5.1 的 serverGates 与 get_server_status 重复;§3.2 应给出明确优先级。


0. 结论摘要

  1. 工具面已经覆盖「看 + 管 + 连」三层(本方案写作时 54 个工具、8 个功能族;P10-A/B/C 与 P11 之后为 60 个工具、9 个功能族,见 §1.1)。写作时的三处结构性缺口都已关闭: 文件系统只有读没有写(P10-B 补了 delete_path / move_path / create_folder)、 远程控制缺「防人工干扰」与「能力自述」(P10-C 补 remote_block_input,P10-A 补 get_host_detail.capabilities)、同一能力存在两套重叠工具(P10-A 用描述互指解决,未合并工具)。
  2. 最高性价比的一批新工具是文件系统写操作(delete_path / move_path / create_folder): 客户端四个命令 + 三个完成 token 全部已实现(client/file/FileManager.cpp:97-121; TOKEN_DELETE_FINISH 被删文件与删目录复用)。MCP 侧复用 P7 的 followUp 范式即可, 客户端零改动,一次性补齐「AI 能整理远程磁盘」这个最常用场景。 注意这不等于「照抄 P7」:文件管理器子连接的就绪包是 TOKEN_DRIVE_LIST 不是 TOKEN_SYSTEM_READY,且三个完成 token 在服务端顶层分发里还没有 case——真正的接线 工作量在这里,详见 §2.3。
  3. 最大的非工具类短板是「能力自述」:get_host_detail 不告诉模型这台主机支持什么, 模型只能靠 -32005 试错(list_registry、get_screenshot、remote_*、upload_file 各有平台/能力位门槛)。 补一个 capabilities 对象是纯服务端改动、几十行代码,但直接减少一整类无效调用。 服务端开关态不必另开字段——get_server_status 的 switches 已经完整暴露(McpServer.cpp:3142), capabilities 只描述「这台主机本身能做什么」,两者分工明确。
  4. 协议层有四个空白:initialize.instructions、notifications/progress、notifications/cancelled、 logging。其中前两个直接影响「长任务(下载/上传/搜索/chat_wait)时模型以为卡死」的体验。 现状(2026-10-28):前三项已落地——instructions(P10-A)、progress/cancelled(P11,附录 D.4); logging 仍未做(服务端不声明 capabilities.logging,也不发 notifications/message)。
  5. 不建议现在做的:注册表写、Windows 事件日志、进程模块/启动项、剪贴板读——都需要客户端改, 且安全边界要单独评审;代理隧道(COMMAND_PROXY)价值最高但工程量大,建议单独立项。

一处需要纠正的常见误解:进程「挂起 / 恢复」已经实现,不需要新工具—— 它是 host_control_process 的 action=freeze|thaw(McpMachine.cpp:2107), 且已带「动作后重拉进程列表复核」的验证逻辑。本轮不再重复造这个工具。


1. 现状盘点

1.1 工具族(60 个)

登记表在 server/2015Remote/McpInternal.cpp:375 的 kToolHints[](60 项,与下表的工具逐条对应)。 下表是 P11 之后的口径;写作时是 54 个、8 个族,P10-B 加 3 个(文件系统写)、P10-C 加 1 个 (remote_block_input)、P11 加 2 个(mcp_list_sessions / mcp_cancel_session)。

族 数 工具 门控条件
服务端本机只读 9 list_online_hosts search_hosts list_all_hosts get_host_detail get_activity_history get_audit_log get_server_status mcp_list_sessions mcp_cancel_session 全部始终在列表里、只读模式下照常可用;mcp_list_sessions / mcp_cancel_session 还不受任何开关或只读限制(卡住请求的唯一出路,见附录 D.5)
主机只读 21 list_processes list_windows list_files list_services get_client_log get_keylog get_screenshot list_registry download_file search_file list_network_connections + host_list_*(10 个标签页) 除下列四类外始终在列表里:get_keylog 需 McpKeylog=1(其 clear / set_offline 还需 McpReadonly=0)、download_file 需 McpFileTransfer=1、list_network_connections 与 host_list_* 需 McpMachine=1
终端 4 terminal_open terminal_exec terminal_close exec_command terminal_*:McpTerminal=1 且 McpReadonly=0;exec_command 只要求 McpReadonly=0
远程控制 6 remote_open remote_close remote_mouse remote_keyboard remote_clipboard remote_block_input McpRemoteControl=1 且 McpReadonly=0
文件传输 2 upload_file copy_files_c2c McpFileTransfer=1 且 McpReadonly=0(download_file 只要求此开关)
文件系统写 3 delete_path move_path create_folder McpFileWrite=1 且 McpReadonly=0
设备管理 4 kill_process operate_window control_service power_action McpManage=1 且 McpReadonly=0
主机/连接管理 7 kill_network_connection host_control_process host_control_window host_control_service host_control_task host_set_remark host_set_watch_level 前 5 个:McpMachine=1 + McpMachineDangerous=1 + McpReadonly=0;host_set_remark / host_set_watch_level 始终在列表里,调用要求 McpReadonly=0
远程交谈 4 chat_open chat_send chat_wait chat_close McpChat=1(与 McpReadonly 无关)

合计 9+21+4+6+2+3+4+7+4 = 60。默认配置(McpReadonly=1、其余开关 0)下 tools/list 19 个 = 服务端本机只读 9 + 主机只读 8(去掉 get_keylog / download_file / list_network_connections / host_list_*)+ 主机/连接管理 2(host_set_remark / host_set_watch_level);其余各族依赖开关,全部不可见。 开关全开且关闭只读时为 60 个。

已有的工程范式(新工具直接复用,不必重新设计):

  • 一次性子连接 + 首包即数据:list_processes / list_windows / list_services / list_registry / get_client_log。
  • 接管子连接 → 发写命令 → 收确认(PendingRequest::followUp / followUpSent):kill_process / operate_window / control_service(Mcp_Manage_Design.md §3)。
  • 多步会话抽象(PendingKind::Machine / ConnMgr):host_list_* / host_control_*(Mcp_Machine_Design.md §3)。
  • 流式会话(TermSession / ScreenCtrlSession / FileTransferSession / ChatSession):终端、远程控制、文件传输、聊天。
  • 迟到首包吸收(MarkLateFirstPacketForTool / TakeToolFirstPacket):防超时后误弹 MFC 窗口。

1.2 协议层能力

能力 现状 证据
initialize / ping / tools/list / tools/call ✅ McpServer.cpp:7633 起
initialize.instructions ❌ 未实现 全文 0 处 instructions
tools/list 的 annotations ✅ 四类 hint 齐备 McpInternal.cpp:437 ApplyToolAnnotations
outputSchema ✅ 48 处 —
resources / prompts ❌ 未实现 0 处
notifications/progress ❌ 未实现 0 处 progressToken
notifications/cancelled ❌ 未实现 0 处 cancelled
Mcp-Session-Id ❌ 无状态 0 处
分页 用 limit/offset,非 MCP cursor 全部列表工具一致
传输 Streamable HTTP POST /mcp;可选内置 TLS 终结(McpTlsProxy) Mcp_Design.md §13
认证 静态 Bearer token + 失败计数封禁 Mcp_Design.md §3.5
错误码 -32700 … -32011 共 14 个 Mcp_Design.md §12

1.3 客户端能力 → MCP 覆盖矩阵

对 common/commands.h 中 Windows 客户端已实现的命令逐个核对(client/KernelManager.cpp、client/MachineManager.cpp、client/file/FileManager.cpp、client/ScreenManager.cpp、client/KeyboardManager.cpp):

客户端能力 命令 MCP 现状 可行性
列目录 / 列盘 COMMAND_LIST_FILES / COMMAND_LIST_DRIVE ✅ list_files —
搜索文件 COMMAND_SEARCH_FILE ✅ search_file —
下载 / 上传 CMD_DOWN_FILES_V2 / COMMAND_SEND_FILE_V2 ✅ download_file / upload_file —
客户端间直传 COMMAND_C2C_SEND_FILES ✅ copy_files_c2c —
删除文件 COMMAND_DELETE_FILE → TOKEN_DELETE_FINISH ❌ 缺 零客户端改动
删除目录(递归) COMMAND_DELETE_DIRECTORY → TOKEN_DELETE_FINISH ❌ 缺 零客户端改动
新建目录 COMMAND_CREATE_FOLDER → TOKEN_CREATEFOLDER_FINISH ❌ 缺 零客户端改动
重命名 / 同卷移动 COMMAND_RENAME_FILE → TOKEN_RENAME_FINISH ❌ 缺 零客户端改动
进程列表 / 结束 COMMAND_PSLIST / COMMAND_KILLPROCESS ✅ list_processes / kill_process —
进程挂起 / 恢复 COMMAND_PROCESS_FREEZING / COMMAND_PROCESS_THAW ✅ host_control_process(action=freeze|thaw) —
窗口列表 / 控制 COMMAND_WSLIST / CMD_WINDOW_CLOSE / CMD_WINDOW_TEST ✅ list_windows / operate_window —
服务列表 / 控制 TOKEN_SERVERLIST / COMMAND_SERVICECONFIG ✅ list_services / control_service —
计划任务 / 软件 / 驱动 / 浏览器记录 / 收藏 / hosts 读 COMMAND_MACHINE_* ✅ host_list_*(10 个) —
写 hosts 文件 COMMAND_HOSTS_SET ❌ 缺 零客户端改动,但整文件覆盖,高风险
卸载软件 COMMAND_APPUNINSTALL(WinExec,无回包) ❌ 缺 零客户端改动,风险高
连接列表 / 断开连接 COMMAND_CONNECTION / COMMAND_KILL_CONNECTION ✅ list_network_connections / kill_network_connection —
屏幕截图 COMMAND_SCREEN_PREVIEW_REQ ✅ get_screenshot —
鼠标 / 键盘 / 剪贴板写 COMMAND_SCREEN_CONTROL + MSG64 ✅ remote_* —
锁定对端键鼠 COMMAND_SCREEN_BLOCK_INPUT(2 字节) ❌ 缺 零客户端改动(无回包)
黑屏 / Ctrl+Alt+Del COMMAND_SCREEN_BLANK / COMMAND_SCREEN_CTRL_ALT_DEL ❌ 客户端未实现,需客户端改动
窗口级 / 区域捕获 COMMAND_SCREEN_WINDOW / COMMAND_SCREEN_ROI ❌ 流式接口,需评估(见 §4.2)
注册表读 COMMAND_REGEDIT + COMMAND_REG_FIND ✅ list_registry(子键 + 值) —
注册表写 无命令 ❌ 需客户端改动
键盘记录(实时) COMMAND_KEYBOARD ✅ get_keylog —
键盘记录(离线常驻) COMMAND_KEYBOARD_OFFLINE / COMMAND_KEYBOARD_CLEAR ❌ 缺 零客户端改动(见 §5.2)
客户端日志 COMMAND_QUERY_LOG ✅ get_client_log —
电源操作 TOKEN_MACHINE_MANAGE ✅ power_action —
远程交谈 COMMAND_CHAT ✅ chat_* —
客户端升级 COMMAND_UPDATE ❌ 零客户端改动,需独立评审(见 §4.4)
上传执行 / 下载执行 COMMAND_UPLOAD_EXEC / COMMAND_DOWN_EXEC ❌ 零客户端改动,需独立评审(见 §4.4)
代理映射 COMMAND_PROXY ❌ 需独立设计(见 §4.3)
摄像头 / 语音 COMMAND_WEBCAM / COMMAND_AUDIO ❌ 需流式解码,建议后置
清除事件日志 / 隐藏开网页 / 卸载后门 COMMAND_CLEAN_EVENT / COMMAND_OPEN_URL_* / COMMAND_REMOVE ❌ 当前 Windows 客户端未实现,为死命令

结论:客户端已实现、但 MCP 还没接的能力共 14 项,其中 9 项属「零客户端改动、可常规批次接入」:

  • 文件写 4 项(删除文件 / 删除目录 / 建目录 / 改名移动)
  • 键鼠锁定 1 项(remote_block_input)
  • 离线键盘记录 2 项(开关 / 清空)
  • 主机侧 2 项(写 hosts、卸载软件)—— 零改动但风险高,建议后置或不做

另有 5 项(代理、升级、上传执行、摄像头、窗口级捕获)虽也零客户端改动,但工程量或风险远超常规批次,需单独立项(§4)。


2. 新工具(P10-A):文件系统写操作

2.1 为什么是最高优先级

MCP 现在能读、能传、能搜,唯独不能删、不能改名、不能建目录。任何「整理远程磁盘」「清理临时文件」「归档日志」「部署目录准备」类任务都会卡在最后一步,只能退回 exec_command(del / move / mkdir)——而 exec_command 受命令白名单约束(McpCmdWhitelist),del 默认不在白名单里,且无法处理中文路径与超长路径的编码问题。

用原生文件通道做,还能绕开 shell 白名单、拿到确定的 ack、复用已有的 TOKEN_*_FINISH 协议。

2.2 工具定义

工具 入参 客户端命令 完成 ack
delete_path id、path、recursive(默认 false) recursive=true → COMMAND_DELETE_DIRECTORY;否则 COMMAND_DELETE_FILE TOKEN_DELETE_FINISH
move_path id、from、to COMMAND_RENAME_FILE + [from\0][to\0] TOKEN_RENAME_FINISH
create_folder id、path COMMAND_CREATE_FOLDER + [path\0] TOKEN_CREATEFOLDER_FINISH

输出统一为 {id, path, ok:true, verified?:bool},并附一句可读摘要。

2.3 复用链路(与 P7 同构,但不是照抄 P7)

主连接 COMMAND_LIST_DRIVE  →  客户端建文件管理器子连接  →  子连接回 TOKEN_DRIVE_LIST
  →(followUp)下发 COMMAND_DELETE_FILE / _DIRECTORY / _CREATE_FOLDER / _RENAME_FILE
  →  等 TOKEN_*_FINISH  →  关闭子连接
  • 服务端已有现成的三段式入口:list_files(McpServer.cpp:2419)、search_file(McpServer.cpp:8050)、download_file(McpServer.cpp:6430)都走 COMMAND_LIST_DRIVE 开子连接。
  • PendingRequest 的 followUp / followUpSent / subCtx 字段(McpServer.h:584-587)足够承载「先等就绪首包、再发写命令、再等确认」的两阶段语义,数据结构不用改。
  • 路径编码:客户端工程是 MultiByte,路径必须 Utf8ToCpExact 严格转 GBK(同 search_file 的做法),不可表示即 -32602。

但接入点必须新写三处,这是本节的主要工作量:

  1. 就绪包分流走 OnDriveList,不是 OnSystemReady。 OnSystemReady(McpServer.cpp:8070)里有工具名硬门(只认 kill_process / operate_window),且文件管理器子连接的就绪包是 TOKEN_DRIVE_LIST,根本不会进那个分支。 OnDriveList(McpServer.cpp:7832)当前对空 path 一律判定为「只列盘」并把 TOKEN_DRIVE_LIST 当数据取走(:7846-7851),所以必须在它最前面按 tool 分流:文件写工具 → 下发 followUp、保持子连接、返回 false。
  2. 三个完成 token 需要在服务端顶层分发新增 case。 TOKEN_DELETE_FINISH / TOKEN_RENAME_FINISH / TOKEN_CREATEFOLDER_FINISH 目前只在 server/2015Remote/FileManagerDlg.cpp:983-995 的 hDlg 路径里处理。MCP 的子连接 hDlg == NULL(NotifyProc 只有 hDlg 存在才交给对话框),三个包会落到 2015RemoteDlg.cpp:7249 的 default:——只打一行 "unknown command"、并不关闭子连接。必须新增 case:TakeMainResponse + CancelIO。
  3. MarkLateFirstPacketForTool 要登记新工具。 否则工具超时后迟到的 TOKEN_DRIVE_LIST 会当成人工操作,弹出 MFC 文件管理器窗口。把新工具名加入 TOKEN_DRIVE_LIST 那条分支(McpServer.cpp:7760)即可。

2.4 已知限制(必须写进工具描述)

限制 原因 缓解
ack 只代表「已执行」,不代表「成功」 客户端忽略 DeleteFile / MoveFile / MakeSureDirectoryPathExists 的返回值,无条件 SendToken(..._FINISH) 文档明确要求「调用后用 list_files 复核」;可选增强见 §5.7
move_path 仅同卷 客户端用 ::MoveFile(client/file/FileManager.cpp:990),非 MoveFileEx 描述里写「跨盘请改用 download_file + upload_file」
删除无回收站、目录递归 COMMAND_DELETE_DIRECTORY → DeleteDirectory 递归删除 工具描述加显著警告;recursive 必须显式传 true
删除单个只读文件会静默失败 COMMAND_DELETE_FILE 直接 DeleteFile(:101),不像 DeleteDirectory 那样先 SetFileAttributes(...NORMAL)(:659) 描述里提示「只读文件请先改属性」
create_folder 会自动建中间层 MakeSureDirectoryPathExists,语义是「确保路径存在」而非「只建最后一级」 写进描述:传入已含文件名的路径会建出同名目录
深目录递归删除可能压垮客户端 DeleteDirectory 用无界 wsprintf 拼 MAX_PATH 栈缓冲(:643/653/657);SearchFiles 已在 8f718d9 加长度预判,删除/FixedUploadList 尚未 服务端拒绝超过 MAX_PATH 的 recursive 目标;彻底修复归 P12
路径不存在时不会快速失败 客户端不回报 win32 码 需要客户端补 TOKEN_FILE_OP_ERROR(见 §5.7 与 §6 的 P12 批次)

2.5 安全门

新增单一开关 McpFileWrite(默认 0),要求 McpReadonly=0 同时成立:

  • 不复用 McpFileTransfer:上传是「覆盖」,删除是「毁灭」,风险等级不同,必须能分别关。
  • 三个工具全部登记 readOnlyHint=false, destructiveHint=true(delete_path)/ false(move_path、create_folder)。
  • 审计:沿用 AuditManageAction,记录 path= 与 recursive=,不记录文件内容。
  • 建议追加服务端侧保护:拒绝 path 落在系统关键目录(C:\Windows、C:\Windows\System32、C:\Program Files)下的 delete_path,除非另开 McpFileWriteDangerous。这一条可在实现时按需取舍,但至少要把 C:\Windows 与盘根目录挡住(delete_path 传 C:\ + recursive=true 是灾难级误操作)。

3. 新工具(P10-C):远程控制补全 + 工具族去重

3.1 remote_block_input(P10-C,零客户端改动)

项 内容
入参 id、session_id、block(true / false)
命令 屏幕子连接上 [COMMAND_SCREEN_BLOCK_INPUT][0|1](2 字节,client/ScreenManager.cpp:1198)
门控 随 remote_open(McpRemoteControl=1 + McpReadonly=0),不单独设开关

价值:AI 做 GUI 自动化时,真人碰一下鼠标就会把流程打断;锁定对端键鼠是标准做法。 必须做的两件事(否则会把人锁在电脑外):

  1. remote_close 与 idle 回收时强制补发 block=false;
  2. 会话内 block=true 超过 max_block_ms(建议默认 300s)自动解锁并在结果里标注 auto_unblocked=true。

BlockInput 在进程退出时会自动解除,所以真正的死锁风险只出现在「客户端进程活着但会话丢了」——上面两条正好覆盖。

3.2 工具族重叠:list_* vs host_list_*(P10-A,纯文档/描述改动)

这是当前最容易被忽略、但对模型影响最大的问题。同一件事有两套工具,走两条完全不同的链路,门控也不同:

能力 设备管理族(P2/P7) 主机管理族(P8) 差异
进程列表 list_processes(COMMAND_SYSTEM→CSystemManager) host_list_processes(COMMAND_MACHINE_PROCESS→MachineManager) 后者字段更全(优先级、线程数、用户、工作集、文件大小),且已有 name/pid 服务端过滤(McpMachine.cpp:2733-2741)
窗口列表 list_windows(COMMAND_WSLIST) host_list_windows(COMMAND_MACHINE_WINDOWS) 同上,后者也带过滤
服务列表 list_services(COMMAND_SERVICES→ServicesManager) host_list_win32_services(COMMAND_MACHINE_WIN32SERVICE) 后者含描述、登录身份
窗口控制 operate_window(含 close) host_control_window(无 close) 门控不同

门控差异是关键:host_list_* 需要 McpMachine=1,而 list_* 只需 McpReadonly。所以:

  • McpMachine=0 时 host_list_* 不出现在 tools/list,模型只能用 list_*;
  • McpMachine=1 时两套都在,模型没有任何依据判断该用哪个。

结论比初稿更强:host_list_* 是首选而非平级备选——字段更全、且过滤能力本来就已存在(list_* 要等 §5.3 补完过滤才追平)。list_* 的定位是「McpMachine=0 时的降级路径」。

做法(不需要合并工具,只改描述,风险极低):

  1. 在两套工具的 description 里互相指路,且措辞要给出明确优先级:
    • list_processes → 「McpMachine=0 时的降级路径,字段较少;若 host_list_processes 在 tools/list 里,一律优先用它」;
    • host_list_processes → 「首选;与 list_processes 同源但字段更全并支持服务端过滤,仅在不可用时退回」。
  2. 在 initialize.instructions(§5.8)里写一条选型规则,一次性讲清四组关系。

不建议合并:两族走不同子连接、不同能力位、不同门控,合并会破坏既有安全模型(McpMachine 开关的意义就是「单独关掉一套」)。


4. 大能力(需独立立项,不建议并入本轮)

4.1 分级原则

下面这些能力「能做」但不适合和文件写工具混在一个批次:要么工程量大(代理、摄像头),要么安全边界必须单独评审(升级、执行、卸载)。按建议顺序列出。

能力 客户端改动 工程量 风险 建议
注册表写(set/delete value) 需要(无现成命令) 中 高(可持久化篡改) P12,独立开关 + 白名单键路径
Windows 事件日志读取 需要 中 低(只读) P12,优先于注册表写
进程模块 / 启动项 / 网络共享 需要 中 低(只读) P12,补「主机取证」维度
剪贴板只读 需要(客户端只有写) 小 中(读即泄密) 维持 Mcp_Design.md §10.7 的「不做」结论
窗口级一次性截图 需评估 中 低 见 §4.2
代理隧道 proxy_* 否(COMMAND_PROXY 已有) 大 高 见 §4.3
客户端升级 upgrade_client 否(COMMAND_UPDATE 已有) 中 高 见 §4.4
上传执行 upload_exec 否(已有) 小 极高 默认不做,或仅 McpMachineDangerous 下
摄像头快照 / 语音采集 否(已有流) 大 中 后置
写 hosts 文件 否(已有) 小 高 见 §4.5

4.2 窗口级截图

已完成(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 不用做,做了也是重复实现。

真正缺的两件事:

  1. 开关:COMMAND_KEYBOARD_OFFLINE(2 字节)与 COMMAND_KEYBOARD_CLEAR(1 字节) 已实现于 client/KeyboardManager.cpp:125 / :131,就在 get_keylog 已经建立的那条 键盘子连接上,MCP 侧从未下发过。
  2. 状态自述:客户端在就绪包 TOKEN_KEYBOARD_START 的 byte[1] 里已经带了「离线记录是否开启」 (client/KeyboardManager.cpp:164),服务端 get_keylog 拿到了这个包却没解析。 模型因此不知道「我看到的这些历史是不是全量」。

做法:

参数 语义
offlineRecord(输出) 客户端当前是否开着离线常驻记录,取自 TOKEN_KEYBOARD_START 的 byte[1];false 时历史只覆盖本进程启动后的在线时段
set_offline(输入,true/false) 下发 COMMAND_KEYBOARD_OFFLINE 改变常驻状态。写操作:需 McpReadonly=0
clear(输入,true) 下发 COMMAND_KEYBOARD_CLEAR 清空客户端缓冲区与落盘文件。破坏性:需 McpReadonly=0,且应排在采集之前

两个写动作都必须先于采集窗口下发,且失败要如实返回(Send2Client 的返回值要检查)。

5.3 【P0,已完成 bb55f52】list_processes / list_windows 增加服务端过滤

问题:BuildPagedHostListInputSchema 只有 {id, limit, offset}(McpServer.cpp:776,调用点在 :1477 等)。一台正常 Windows 有 200–400 个进程、几十个窗口,模型要翻 3–4 页才能找到目标;每页都是完整字段,上下文开销很大。

做法:加可选 name(进程名/窗口标题子串,ASCII 不区分大小写)与 pid,在服务端分页之前过滤,total 为命中数、totalAll 为总数。口径照抄 BuildSearchHosts(McpServer.cpp:1878-1887):

ApplyPageWindow(matched, page, pageItems);
if (filtered) page.totalAll = (int)all.size();   // 过滤前总数

收益:list_processes(name="chrome") 从 3 页变 1 条;两套工具族的能力也对齐了(host_list_* 本来就有这两个参数)。

5.4 【P1,已完成 1c832ff】power_action 增加结果验证

问题:power_action 是「发完即走、无响应」(McpServer.cpp:5812 附近注释),返回 ok:true 只代表命令写进了 socket。模型会误以为「已重启」,紧接着调 list_processes 却拿到旧进程列表。

做法:加 wait(默认 false)与 wait_ms(默认 60000):

  • wait=true:轮询主连接是否断开 → 再轮询是否重新上线,返回 {sent:true, went_offline:true, came_back:true, elapsed_ms};
  • 超时不算失败,返回 came_back:false 让模型自己决定。

5.5 【P1,已完成 1c832ff】破坏性工具统一 dry_run

kill_network_connection 有 dry_run(实测报告「观察项」明确肯定了这个设计),但 kill_process、operate_window(close)、host_control_* 都没有。建议统一:dry_run=true 时只做「目标存在性校验 + 返回将被影响的对象」,不执行。

对 AI 尤其重要:模型可以在执行前把「我要杀这 3 个进程」摆给用户看。

5.6 【P2,已完成 1c832ff(-32012,-32008 留作别名)】错误码:-32008 其实只有两种语义

初稿的错误:原文说 -32008 一码四义(含「老客户端格式」「多显示器不支持」)。核对后全文件只有两处 -32008:exec_command 的 shell 元字符(McpServer.cpp:2901)与 terminal_exec 的 &/|/换行 (McpServer.cpp:3465)——两者都是「改参数可修」。多显示器早就改成 -32005 了,代码注释明说 「这是能力限制、改参数也修不好」(McpServer.cpp:3715)。能力类错误已经统一走 -32005。

因此拆分只剩一个干净的诉求:把「参数非法」从 -32008 换成 MCP 语义更准确的 -32012。

新码 语义 模型动作
-32012 Validation rejected(参数非法,改参数可修) 修参数重试

-32008 保留为历史别名(不破坏既有客户端与已发布的文档)。这是一次纯常量替换,收益是让模型 不必读英文 message 就能区分「改参数」与「换主机」,但优先级低于 P0 各项。

5.7 【P1,部分完成 27b5431:verified 三态已落地,verify_hint 字段未加】写工具的 ack 语义显式化

现状:delete_path / move_path / create_folder / kill_process / operate_window / control_service 的 ack 都是客户端无条件回包,不代表操作成功。

两条路,建议都做:

  1. 文档层:outputSchema 里加 verified: bool(可为 null)与 verify_hint: string("call list_files on the parent directory to confirm");
  2. 实现层(低成本高收益):delete_path / move_path 在收到 ack 后,在同一个子连接上再补一次 COMMAND_LIST_FILES 校验父目录,把 verified 填成真实结果。注意不是"多开一次子连接":子连接还开着,客户端收到 finish 后就在等下一条命令,所以代价只是同一连接上的一次往返(约 50–150ms)。实现要点是重新登记一个 list_files 挂起(BeginPending(devId, "list_files", path),McpServer.cpp:7795 已有该重载),再直接 Send2Client;TOKEN_FILE_LIST 的现有 case 会在投递结果后 CancelIO 收尾,正好完成清场。校验本身失败(超时/连接断)时 verified 返回 null,不要谎报 false。

彻底的做法是客户端补 TOKEN_FILE_OP_ERROR(带 win32 码),归入 §4.1 的 P12 批次。

5.8 【P1,已完成 bb55f52】initialize 返回 instructions

问题:模型对这套服务端的「隐性知识」全靠工具描述拼凑:主机 id 是 64 位雪花值(不能猜)、要先 list_online_hosts 再操作、-32003 是单设备单飞行、-32006 不要重试、远程控制要先 remote_open 拿 session_id。Mcp_Design.md 把这些写在文档里,但模型看不到文档。

做法:initialize 响应里加 instructions(纯文本,建议 600–900 字),内容:

  1. 主机 id 的获取方式与形态(禁止猜测);
  2. 工具族与开关关系(哪些工具可能不在 tools/list 里,为什么);
  3. 错误码 → 动作的对照(只列 6 个高频码);
  4. 典型任务编排(文件整理、进程排查、GUI 自动化各一段);
  5. 「同一主机同时只能有一个远程请求」的约束。

收益:这是单点投入、全局收益的改动——所有客户端的每一次会话都受益,且零风险。优先级应当排在所有新工具之前。

5.9 【P2,已完成 1c832ff】notifications/progress 与 notifications/cancelled

问题:

  • download_file 默认超时 600s、upload_file / copy_files_c2c 同类、search_file 最长 120s、chat_wait 最长 55s。这段时间里客户端收不到任何信号,模型和用户都以为卡死。
  • 客户端取消请求(用户按 Esc / 关闭会话)时,服务端不会中止正在进行的传输,主机会被锁到超时为止(实测报告 P2 的 600 秒锁定就是这类后果)。

做法:

  • 长任务在 tools/call 的 _meta.progressToken 存在时,按 1–2 秒节流推送 notifications/progress(progress = 已传字节 / 总字节);
  • 维护「进行中的请求 → 会话」映射,收到 notifications/cancelled 时走既有的清理路径(清 pending、关子连接、删半成品文件)。

这两项都在 McpServer.cpp 的 HTTP 处理器层,不动任何工具实现。

5.10 【P2,已完成 1c832ff】会话可观测与自救

-32003 Device busy 现在是死路:模型不知道是谁占着这台主机、也不知道等多久。建议加两个纯服务端工具:

工具 作用
mcp_list_sessions 列出所有在飞会话,每项 {host_id, kind, tool, session_id, request_id, busy, elapsed_ms, idle_ms}
mcp_cancel_session 按 request_id(精确)或 id/session_id(条件)取消,返回 {cancelled, released, waited_ms, matched};与 notifications/cancelled 走同一个取消位

实装口径以附录 D.5 为准。写作时设想的字段是 {host_id, tool, session_id, started_at, idle_ms, kind}, 落地时去掉了 started_at,补了 request_id(供 mcp_cancel_session 精确回传)、busy、elapsed_ms。

-32003 的 message 里带上「当前占用者与已持续时间」,模型就能自己决定「等」还是「取消」。

5.11 【P2】tools/list 体积

60 个工具(P11 之后的口径,见 §1.1)、每个都带完整中文描述 + 双 schema。按 54 个工具时(P10-A)实测, 工具描述与属性说明文本合计约 23 KB(54 条 description + 158 条 schema 属性说明),叠加 JSON 结构与 schema 骨架后,tools/list 响应在 45–60 KB 量级;多出的 6 个工具只会让它更大。

对 200K 上下文的模型不算致命,但对小上下文客户端(8K–32K)会挤占绝大部分预算,且每轮对话都要重传(多数客户端不缓存)。

三个可选做法(不建议同时上):

  1. 精简描述(推荐):把「实现细节、限制、已知问题」从 description 移到 instructions 或工具文档,description 只保留「做什么 + 关键约束」一两句。可省 30–40%。
  2. 工具族合并:host_list_processes … host_get_hosts_file 这 10 个合并为 host_list(tab, id, limit, offset)。省 9 个工具、约 20% 体积,代价是 annotations 与 outputSchema 变粗(10 个 tab 的条目结构不同),discoverability 也会下降——模型看到 tab 枚举才知道有哪些能力。不建议。
  3. 可配置 profile:McpToolProfile=full|compact,compact 只出 name + 一句话 + 必填参数。适合小模型客户端,但要维护两套描述。

5.12 【P2】control_service 的逐项 Sleep(500)

client/ServicesManager.cpp:213 的 ServicesConfig 对每一项 Sleep(500) 后再回列表。批量控制 10 个服务 = 至少 5 秒。服务端可以在 action 里支持 items[] 批量下发(一次子连接、一个 payload),把 N 次往返压成 1 次。前提是确认客户端能解析多条目 payload——按现有实现它只处理单条,需要客户端改动,因此列为 P2。

5.13 【P0,已修】kToolHints 表头注释过期

原注释写「53 个工具的语义登记表」,与数组实际长度不符。P10-A(bb55f52)先改成 54, P10-C(3d388f8)加工具时索性去掉数字——避免每加一个工具就要改一次注释; 核对方式见 §1.1,60 个工具与 60 项注解逐条对应。

5.14 其他小项

项 位置 说明
list_windows 无 pid 过滤 — 已完成(P10-A,bb55f52):list_processes / list_windows 都加了 name + pid
search_file 无深度/大小上限参数 McpServer.cpp:8050 客户端固定深度 32 / 10000 条,服务端可加 max_depth 但需客户端支持;暂不做(P12)
search_file 的描述仍写着「会栈溢出」 — 已完成(P10-A,bb55f52):描述改为「超过 260 字节的路径会被静默跳过(既不记录也不继续向下递归)」,tools/mcp_smoke.ps1 的两处注释改为「MAX_PATH 的条目会被客户端静默跳过(8f718d9 起不再栈溢出)」
get_screenshot 无区域裁剪 — 已完成(2026-11-10):新增 mode=region/window/monitor,默认原生分辨率并返回 capture 源矩形元数据;见 Mcp_Design.md §21
窗口截图坐标要手工换算成屏幕坐标 — 已完成(2026-11-10):remote_mouse 新增 window_hwnd 基准,窗口信息响应追加虚拟桌面矩形尾块;见 Mcp_Design.md §22
远程控制只能推整虚拟桌面(缩到 1920 宽,点击精度损失) — 已完成(2026-11-10):remote_open 新增 window_hwnd / region 目标,只推目标窗口或 ROI;返回 target 与实际矩形,remote_mouse 坐标相对目标帧;见 Mcp_Design.md §23
terminal_exec 不能用管道 — 已完成(2026-11-10):PTY 会话放开 | / && / ||(POSIX 还允许 ;),仅老非 PTY 客户端与 POSIX 裸后台 & 仍拒绝;见 Mcp_Design.md §12.1
审计不含调用参数 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):

  1. 工具在独立线程执行,McpCallContext 经 FLS(Fiber Local Storage)暴露给工具实现 ——不能用 thread_local:本工程有 shellcode/MemoryModule 手工映射出来的线程,没有 PE 的 TLS 初始化,加一个静态 thread_local 就会让服务端启动约 1s 后跳飞(实测);
  2. 进度通知与最终响应都从这个 SSE 流写出(McpProgressChannel,背压队列上限 64 条, 满了丢最旧——进度是「最新值有意义」的信号);
  3. 不带 token 的请求完全不变(一次性 JSON)。

进度上报点(McpCallProgress,内部 1s 节流):

工具 进度含义
download_file filesDone / (totalFiles - directoryCount);总量未知时退回已收字节数
upload_file 已发数据字节 / 待发数据字节总数(在 worker 的分块回调里累加)
copy_files_c2c 源端只在最后回一包结果,因此不报中间进度;取消/超时按既有路径收尾
search_file 命中数在客户端,服务端只在收尾时报一次结果(见下)
chat_wait 等待期无中间量,取消即时生效

取消:三条入口共用一个取消位(McpCallContext::cancelled)

  • notifications/cancelled(params.requestId 按 JSON-RPC id 精确匹配,字符串与数字不混用);
  • mcp_cancel_session(按 request_id / host id / session_id);
  • SSE 流写失败(客户端已断开)。

所有长等待都改成「≤500ms 一片 + 每片检查取消位」(WaitWithCancel),取消后直接落到各函数 既有的超时/放弃分支:MarkLateFirstPacketForTool 照登、子连接照关、挂起项照删。因此取消 不需要第二套清理逻辑,也满足「取消后主机 1s 内释放」。取消导致的失败结果由分发层统一改写成 -32800(已经拿到成功结果则照实返回)。

D.5 mcp_list_sessions / mcp_cancel_session(§5.10)

  • mcp_list_sessions:一次快照列出在飞 tools/call(含 JSON-RPC request_id)、挂起中的一次性 请求、终端、远程控制、文件传输、远程交谈;字段 host_id/kind/tool/session_id/request_id/busy/ elapsed_ms/idle_ms,可选 kind 过滤。纯本地,不受功能开关与只读模式限制。
  • mcp_cancel_session:按 request_id(精确)或 id/session_id(条件)取消,返回 {cancelled, released, waited_ms, matched};最多等 2s 让工具线程走完清理,released 说明 主机是否真的松开。
  • -32003 的文案统一追加占用者:Device busy: another request is pending for this host (tool=download_file, elapsed=12s)。DescribeBusy 会排除发起本次错误的那个调用自身。

D.6 已知边界

  • SSE 请求会占住 httplib 的一个 worker 线程直到工具结束(线程池 32);单机管理场景足够, 不作为多租户端点使用。
  • search_file 被取消时返回已收到的部分结果(finished=false),不是 -32800:搜索是只读 累积操作,部分结果对调用方更有用;它同样在 ≤1s 内释放主机。
  • mcp_cancel_session 找不到匹配项时返回 cancelled:0(不是错误)——请求可能已经结束, 或 request_id 的 JSON 类型与调用时不一致。