The master's voice monitoring menu sends COMMAND_AUDIO; the client opens a ConnAuth sub-connection with TOKEN_AUDIO_START, the server opens CAudioDlg and answers COMMAND_NEXT, then audio flows both ways. The protocol matches the Windows client, so the server needs no changes. The server's ACM format was read from Audio.cpp and AudioDlg.cpp first: WAVE_FORMAT_GSM610, 8000 Hz mono, 65-byte blocks of 320 samples (40 ms), about 1625 B/s. libgsm 1.0.13 (AOSP external/libgsm mirror) is vendored under cpp/gsm and built with -DSASR -DWAV49 so its MS-GSM packing is byte-identical to ACM GSM610. Encode and decode use separate gsm states because frame_index/frame_chain live in the state. Uplink packets are always exactly 1000 bytes: CAudio::PlayBuffer copies 1000 bytes from the buffer start regardless of packet length, so a short packet would over-read. Since 1000 is not a multiple of 65, blocks straddle packets; the stream is continuous and codec state carries over. AudioMonitor.kt owns AudioRecord (8 kHz/16-bit/mono, 320 samples a read) and AudioTrack playback of decoded downlink PCM. RECORD_AUDIO is requested with POST_NOTIFICATIONS before the projection dialog, and CaptureService adds the microphone FGS type only when held, falling back on failure. An 8-second dialog wait or missing microphone reports a tip to the master instead of failing silently. Verified on an Android 15 emulator against the Debug server: dialog opened, uplink started, server receive counter grew at ~1.6 KB/s. Downlink playback was not exercised (the test machine has no recording device); that path is code-reviewed only. Co-Authored-By: deepseek-flash
58 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 工具族(63 个)
登记表在 server/2015Remote/McpInternal.cpp:479 的 kToolHints[](63 项,与下表的工具逐条对应)。
下表是 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) |
| 主机只读 | 22 | 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 个标签页)+ host_get_hosts_file |
除下列四类外始终在列表里: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 |
| 远程控制 | 7 | remote_open remote_close remote_mouse remote_keyboard remote_clipboard remote_lock_screen 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 |
| 设备管理 | 5 | kill_process operate_window control_service power_action uninstall_host |
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+22+4+7+2+3+5+7+4 = 63。默认配置(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);其余各族依赖开关,全部不可见。
开关全开且关闭只读时为 63 个。
已有的工程范式(新工具直接复用,不必重新设计):
- 一次性子连接 + 首包即数据:
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 字节) |
✅ remote_block_input(Windows BlockInput();Android 无障碍全屏透明 overlay,CLIENT_CAP_PRIVACY_OVERLAY) |
无回包;Android 侧在注入手势期间临时放行(等价 Windows 的 BlockInput(false) 包裹) |
| 黑屏 / Ctrl+Alt+Del | COMMAND_SCREEN_BLANK / COMMAND_SCREEN_CTRL_ALT_DEL |
Ctrl+Alt+Del → ✅ remote_lock_screen(仅 Android,映射为锁屏);黑屏 → Android 客户端已实现处理,未暴露为 MCP 工具 |
见 §3.1 注:Android 的黑色 overlay 会被 MediaProjection 一起抓走,主控画面同步变黑,无法做成「对端看不见、主控看得见」 |
| 窗口级 / 区域捕获 | 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 |
— |
| 卸载主机(被控程序) | TOKEN_UNINSTALL |
✅ uninstall_host(win + apk) |
Android 新版拉起系统卸载确认框,需人工确认 |
| 远程交谈 | COMMAND_CHAT |
✅ chat_*(win + apk) |
Android 新版弹应用内聊天窗口(能力位 CLIENT_CAP_REMOTE_CHAT),老 APK 返回 -32005 |
| 远程终端 | COMMAND_SHELL |
✅ exec_command / terminal_*(win + lnx + apk) |
Android 新版复用 common/PTYHandler.h(/system/bin/sh,能力位 CLIENT_CAP_TERMINAL),老 APK 返回 -32005 |
| 客户端升级 | COMMAND_UPDATE |
❌ | 零客户端改动,需独立评审(见 §4.4) |
| 上传执行 / 下载执行 | COMMAND_UPLOAD_EXEC / COMMAND_DOWN_EXEC |
❌ | 零客户端改动,需独立评审(见 §4.4) |
| 代理映射 | COMMAND_PROXY |
❌ | 需独立设计(见 §4.3) |
| 摄像头 / 语音 | COMMAND_WEBCAM / COMMAND_AUDIO |
语音 → ✅ Android 新版(主控 UI,无 MCP 工具);摄像头 ❌ | Android 用随包编译的 libgsm(WAV49)编 8kHz GSM 6.10,上行严格 1000 字节/包;需 RECORD_AUDIO + microphone 前台服务类型,详见 Mcp_RemoteControl_Design.md §5.5 |
| 清除事件日志 / 隐藏开网页 / 卸载后门 | 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;Windows 零客户端改动,Android 需新版 APK)
| 项 | 内容 |
|---|---|
| 入参 | 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 在进程退出时会自动解除,所以真正的死锁风险只出现在「客户端进程活着但会话丢了」——上面两条正好覆盖。
Android 版(CLIENT_CAP_PRIVACY_OVERLAY):客户端在无障碍服务上挂一个全屏透明
TYPE_ACCESSIBILITY_OVERLAY 吃掉触摸,服务端注入的手势在飞行期间把 overlay 临时置
FLAG_NOT_TOUCHABLE(相当于 Windows 在 ProcessCommand 前后 BlockInput(false) 再恢复)。
子连接断开时客户端自己撤掉 overlay——Android 没有「随调用线程退出自动解除」这层兜底。
黑屏(COMMAND_SCREEN_BLANK)为什么没有做成工具:Windows 上黑屏窗口可以用
WDA_EXCLUDEFROMCAPTURE 从抓屏里排除,所以「本机全黑、主控照常看画面」成立;Android 的
MediaProjection 抓的是合成后的帧缓冲,无障碍 overlay 无论是否 FLAG_SECURE 都会被抓到
(后者在画面里就是黑的),做了也是把主控一起弄瞎。客户端仍实现该命令(协议完整性,
将来 MFC 界面若加「隐私屏」菜单项可直接下发),但 MCP 侧不提供对应工具。
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 开关的意义就是「单独关掉一套」)。
3.3 Android 主机的远程桌面调参(CMD_QUALITY_LEVEL / CMD_FPS / CMD_QUALITY_PROFILES)
这一项不新增工具,修的是Android 客户端把调参命令当日志丢弃的问题,但直接决定
remote_open 会话的画质:Android 上报的 ScreenSettings.QualityLevel 原来写死为 Good,
服务端据此把会话判定为「固定档位」,m_AdaptiveQuality.enabled 永远为 false——
自适应质量在 Android 主机上从未启动。
客户端现在(ScreenTuning.kt + ScreenHandler.h):档位/帧率/6 档配置表存
SharedPreferences,下次建子连接时随 TOKEN_BITMAPINFO 上报;具体档位切换用
MediaCodec.setParameters(PARAMETER_KEY_VIDEO_BITRATE) 平滑改码率。帧率只进
KEY_FRAME_RATE 码控提示(下次开抓生效),CMD_SCREEN_SIZE 与
CMD_SCREEN_TUNING 的四个开关在 Android 上没有对应实现,客户端不声明
SCREEN_CAP_TUNING_FLAGS,服务端继续用主控端按设备保存的副本。设计与限制详见
Mcp_RemoteControl_Design.md §5.4。
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 |
| — | 已完成(2026-11-10):remote_mouse 新增 window_hwnd 基准,窗口信息响应追加虚拟桌面矩形尾块;见 Mcp_Design.md §22 |
|
| — | 已完成(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 / 黑屏 |
黑屏客户端未实现;Ctrl+Alt+Del 只在 Android 上映射为锁屏(remote_lock_screen),Windows 侧要发 SAR 需要 SYSTEM/UIAccess,本轮不做 |
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(Android 已实现,映射为锁屏)、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 类型与调用时不一致。