Docs(mcp): correct claims in the server instructions agents rely on

The initialize.instructions text is the only guide a model gets (it cannot
read docs/), and several statements disagreed with the code:

- get_keylog was described as always visible; it is gated by McpKeylog and
  hidden when the switch is off.
- Dangerous machine actions were not mentioned: freeze/thaw and
  stop/restart stay in tools/list but need McpMachineDangerous and return
  -32006 at call time.
- -32006 was described as policy/admin-only; MFC also returns it when an
  old client lacks CLIENT_CAP_V2. The Go server returns -32005 for that
  case, so its own instructions now say so.
- -32001 advice assumed every failure is a timeout; it also covers
  cancellations, http_probe parse failures and unconfirmed writes.
- "Unsupported combos always return -32005 immediately" ignored paths that
  surface as -32001 once a sub-connection is involved.
- Linux matrix listed all host_* as unsupported, but host_set_remark and
  host_set_watch_level only touch server-local data.
- local_dir / local_path are paths on the controller, not the user's box.

Also align the error table and platform distribution in the docs, and note
that hidden fallback aliases remain callable. Debug build green; go test,
check_platform_table and gen_go_tools --check pass.

Co-Authored-By: deepseek-flash
This commit is contained in:
yuanyuanxianganddeepseek-flash committed 2026-11-13 12:32:33 +01:00
1 parent 292c3191dc
commit d49ebe521d
4 files changed
+37 -18

No files matched your search

+3 -3
View File
@@ -597,7 +597,7 @@ token 只从 `-Token` / env 读取,不落仓库、不打印;无在线主机
### 10.8 D 批:拒绝也入审计
动机:所有策略拒绝(只读模式、`Mcp*` 开关关闭、主机不支持某能力)都返回 `-32006`,而审计里只有 `CALL_FAIL`——和「参数错」「主机离线」「超时」混在一起,事后分不清「没人调过」和「被策略拦下」。
动机:策略拒绝(只读模式、`Mcp*` 开关关闭,以及老客户端 V2 这类能力缺失)返回 `-32006`;平台/能力位不匹配的多数返回 `-32005`。此前审计里只有 `CALL_FAIL`——和「参数错」「主机离线」「超时」混在一起,事后分不清「没人调过」和「被策略拦下」。
- 实现放在 `tools/call` 的统一出口(`CMcpServer` 的 HTTP 处理器),不在 24 个 `-32006` 分支里逐个埋点:成功解析响应体后多取 `error.code` / `error.message`,`code == -32006` 就追加一条
```
@@ -678,12 +678,12 @@ token 只从 `-Token` / env 读取,不落仓库、不打印;无在线主机
| `-32600` | Invalid Request | 缺 `jsonrpc` / `method` / 非法 `tools/call` 结构 | 修正请求 |
| `-32601` | Method not found | `method` 不是 `initialize` / `tools/list` / `tools/call` 等 | 修正请求 |
| `-32602` | Invalid params | 未知工具名、缺必填参数、参数类型/取值非法、批量 `ids` 超过 50 个、`search_file` 过滤参数非法、文本无法转 GBK | 改参数重试,重试同样的请求不会成功 |
| `-32001` | Timeout | 等客户端就绪/等子连接/等搜索结果超时(`timeout_ms` 内没等到) | 可加大 `timeout_ms` 重试;持续出现看主机是否卡住 |
| `-32001` | Timeout / execution failure | 多为等客户端就绪/等子连接/等搜索结果超时(`timeout_ms` 内没等到);也用于工具自身失败(`http_probe` 解析失败、目标端未确认写入)与已取消(`Request cancelled`) | 先看 `message`:超时且工具支持 `timeout_ms` 可加大重试;子连接没建立/反复超时通常重试无效;`Request cancelled` 可直接重试;其余按 `message` 处理 |
| `-32002` | Host offline / not found | 主机 id 不存在、主连接已断、会话 id 不存在或已关闭 | 先 `list_online_hosts` 刷新再选主机 |
| `-32003` | Busy | 该主机已有同类请求在飞(终端/截屏/文件/聊天会话),或同设备重复 `chat_open`。`message` 末尾带 `(tool=..., elapsed=Ns)` 点名占用者 | 用 `mcp_list_sessions` 看全部会话;等前一个结束、先 `*_close`,或 `mcp_cancel_session` 释放 |
| `-32004` | Send failed | 命令写入主连接失败(连接刚断) | 重试一次;仍失败按 `-32002` 处理 |
| `-32005` | Not supported on this host | 能力限制,改参数也修不好:需要 Windows 的工具用在 LNX/MAC/APK 主机上;`remote_open` 遇到多显示器(阶段一);主机无屏幕预览/控制能力位 | 换主机或换工具;不要改参数重试 |
| `-32006` | Policy refused | 只读模式 / 对应 `Mcp*` 开关关闭 / 主机不支持该能力(如 V2 文件传输) | **不要重试**:这是配置决定,需管理员改服务端配置 |
| `-32006` | Policy refused | 只读模式 / 对应 `Mcp*` 开关关闭;MFC 端还包括老客户端不支持 V2 文件传输(`download_file` / `upload_file` / `read_file` / `copy_files_c2c`;Go 端这种情况返回 `-32005`) | **不要重试**:开关/只读需管理员改服务端配置,老客户端需升级 |
| `-32007` | Not in command whitelist | `exec_command` 的命令不在 `McpCmdWhitelist` 里,或词边界不匹配(`dir` 过、`dirx` 拒) | **不要重试**:换成白名单内的命令,或请管理员加白名单项 |
| `-32012` | Rejected by validation | 只覆盖「参数被校验拒绝、改参数可修」:`exec_command` 含 shell 元字符(Windows `&\|<>^`;Linux `&\|<>;` 与反引号、`$(` `${` `!`)或控制字符(含 `\r\n`);`terminal_exec` 含控制字符(含换行),或**老非 PTY 会话**里含 `&`/`\|`,或 POSIX 会话里含裸后台 `&`;路径/参数含非法字符。**`-32008` 是同一语义的历史别名**(早期实现用它,已发布的客户端/文档可能仍在匹配),新代码一律用 `-32012` | 按 `message` 修正参数后重试 |
| `-32009` | Target not found | 远端路径/注册表键不存在(win32 `2`/`3`,由新客户端主动回报);`kill_network_connection` 的四元组在当前连接表里查不到(`dry_run` 传假四元组最常见) | 先用 `list_files`/`list_registry`(或 `host_list_network_state`)确认目标存在 |
+22 -7
View File
@@ -283,16 +283,21 @@ const char* kServerInstructions =
u8"2) 工具的可见性与开关\n"
u8"tools/list 只返回当前服务端开关允许的工具:终端(terminal)、远程控制(remote_control)、"
u8"文件传输(file_transfer)、文件写入(file_write)、管理动作(manage)、主机管理(machine)、键盘记录(keylog)、"
u8"远程交谈(chat)各有独立开关。工具不在列表里就是不可用,直接调用返回 -32006;"
u8"远程交谈(chat)各有独立开关。工具不在列表里通常就不可用,直接调用会被拒(-32006 或 -32005);"
u8"例外是下文提到的降级别名(list_processes / list_windows / list_services、operate_window / "
u8"control_service,以及 list_online_hosts / search_hosts / list_all_hosts 等旧名)——"
u8"它们不在列表里但仍可调用。"
u8"当前开关状态可查 get_server_status 的 switches。只读模式(readonly=true)会挡掉大部分写工具,"
u8"但只改服务端本地数据的 host_set_remark / host_set_watch_level 仍会列出,调用时才被拒;"
u8"get_keylog 也始终可见,只读模式下只是它的 clear / set_offline 参数被拒,读取不受影响。\n"
u8"get_keylog 只受 McpKeylog 开关控制(与只读模式无关):开关关闭时它不在列表里;只读模式下"
u8"只是它的 clear / set_offline 参数被拒,读取不受影响。\n"
u8"同一能力存在两套工具时优先用主机管理族:host_inspect(aspects 选 processes / windows / "
u8"win32_services 等,支持 pid/title/status 等服务端过滤,字段更全),list_processes / "
u8"list_windows / list_services 是它在 McpMachine=0 时的降级路径。窗口与服务控制同样只有一套"
u8"名字(需 McpManage=1):McpMachine=0 时是 operate_window / control_service,开启后是 "
u8"host_control_window / host_control_service;后者也接受 close/show 与 set_auto/set_manual"
u8"(转给前一套实现)。\n"
u8"(转给前一套实现)。危险的主机管理动作目前只有两类——冻结/恢复进程、stop/restart 服务——"
u8"另需 McpMachineDangerous=1:工具照常列出,调用时返回 -32006。\n"
u8"\n"
u8"3) 错误码与动作\n"
u8"-32002 主机离线或不存在:先刷新主机列表再选,不要拿旧快照反复重试。\n"
@@ -303,12 +308,18 @@ const char* kServerInstructions =
u8"chat → chat_close。pending / file_transfer 是某次在飞调用的等待态,取消那次调用就一并释放。\n"
u8"-32004 命令未能送达主机:多半是链路瞬断,可重试一次。\n"
u8"-32005 该主机不支持这项能力:换主机或换工具,改参数没有用。\n"
u8"-32006 策略拒绝:开关未开或只读模式,重试无效,需要管理员改服务端配置。\n"
u8"-32006 策略拒绝:开关未开、只读模式,或目标端能力不足(老客户端不声明 CLIENT_CAP_V2 时,"
u8"download_file / upload_file / read_file / copy_files_c2c 会返回 -32006),重试无效:"
u8"前者需管理员改服务端配置,后者需升级客户端。\n"
u8"-32007 不在命令白名单:换成白名单内的命令,重试无效。\n"
u8"-32012 参数被校验拒绝(命令里的 shell 元字符、控制字符等):按 message 修正参数后重试。"
u8"历史版本用 -32008 表示同一语义,遇到时按同样方式处理。\n"
u8"-32009 目标不存在(文件/目录等):先列一次确认目标,再重试。\n"
u8"-32001 超时:可加大 timeout_ms 重试一次;持续超时说明主机卡住。\n"
u8"-32001 多为超时,也可能是工具自身失败或已被取消:先看 message。是超时时,工具支持 timeout_ms "
u8"就先加大重试一次,不支持就缩小范围(分页、限定目录/单台)再试;子连接/会话没建立、同一主机"
u8"反复超时通常重试无效(主机卡住、链路断、老客户端不认命令),先用 mcp_list_sessions 观察;"
u8"message 写 Request cancelled 的表示客户端已中止,可直接重试;http_probe 解析失败、"
u8"目标端未确认写入等其他 -32001 按 message 处理,加大 timeout_ms 没用。\n"
u8"-32800 请求被取消:这是客户端自己取消(notifications/cancelled / mcp_cancel_session / 连接断开)"
u8"导致的中止,不是主机故障;主机占用已释放,可以直接重试。\n"
u8"-32602 参数错误:按 message 修正后重试。\n"
@@ -319,6 +330,7 @@ const char* kServerInstructions =
u8"文件:list_files 列盘(省略 path)或列目录 → search_file 按名字查找(递归深度 32、最多 1 万条,"
u8"从盘符根扫描很慢且易截断,尽量指定具体目录)→ 看文本内容用 read_file(按字节解码,自动识别 UTF-8/GBK,"
u8"offset=-N 看尾部,不要用 type/Get-Content 读配置和日志)→ download_file 取回、upload_file 送到目标。"
u8"注意 local_dir / local_path 指 MCP 服务端(主控)所在机器的本地路径,不是模型或用户所在机器的路径。"
u8"整理目标机上的东西用 delete_path / move_path / create_folder(需 McpFileWrite 开关),"
u8"它们的 ok 同样只代表客户端回了完成包,真实结果看 verified(true=复核确认生效、"
u8"false=复核确认未生效、null=复核没做成);删除不可恢复,recursive 必须显式传 true。"
@@ -348,7 +360,8 @@ const char* kServerInstructions =
u8"lnx(LNX):不支持服务、注册表、键日志、文件搜索/删除/移动/建目录、"
u8"窗口列表(list_windows)与窗口信息(get_foreground_window)、网络连接列表与断开"
u8"(list_network_connections / kill_network_connection)、"
u8"块输入、host_* 全族、chat_* 全族、operate_window、power_action、uninstall_host。远程控制与截屏要求目标机"
u8"块输入、host_* 全族(host_set_remark / host_set_watch_level 除外,它们只改服务端本地数据,"
u8"任何平台都可用)、chat_* 全族、operate_window、power_action、uninstall_host。远程控制与截屏要求目标机"
u8"有 X11/Xorg(或 XWayland)桌面,纯 Wayland 或无桌面的服务器不行。\n"
u8"mac(MAC):在 lnx 的基础上,还不支持远程控制全族(remote_open / remote_close / "
u8"remote_mouse / remote_keyboard / remote_clipboard)、get_screenshot、"
@@ -373,7 +386,9 @@ const char* kServerInstructions =
u8"(客户端未实现 SYSTEM 等命令)。\n"
u8"copy_files_c2c 是唯一有方向性的工具:源端 src_id 必须是 win,目标端 dst_id 可以是 "
u8"win / lnx / mac。Linux 和 macOS 只能当接收方,不能当发送方(反向不支持)。\n"
u8"这些不支持的组合会立刻返回 -32005,不会白等超时;反之,遇到超时不要当成平台不支持。\n"
u8"这些不支持的组合多数会立刻返回 -32005;少数要等子连接才暴露的(老客户端不认命令等)"
u8"可能表现为 -32001 超时,平台门禁 McpPlatformGuard=0 关闭时也会这样。反之,遇到超时"
u8"也别直接当成平台不支持,先按上面的矩阵确认平台。\n"
u8"\n"
u8"6) 安全约定\n"
u8"写操作前先读一次现状,动作后再用读工具复核;删改类工具的 ok 只表示命令已送达客户端,不代表成功。"
+1 -1
View File
@@ -408,7 +408,7 @@ const serverInstructions = `这是 YAMA 服务端的 MCP 端点(Go 实现)
1) 主机 id 是 64 位无符号十进制字符串,由服务端分配,无法从 IP 或计算机名推算。需要 id 时先用 list_hosts 取得,拿不到就向用户确认,不要猜。
2) tools/list 只返回当前模式允许的工具;只读模式隐藏 terminal_exec / terminal_close,直接调用被隐藏的工具返回 -32006。
3) 错误码与动作:-32002 主机离线或不存在(先刷新列表);-32003 主机忙(同一台主机同一时刻只允许一个操作,重试无效,等前一个结束);-32004 命令未送达(多为链路瞬断,可重试一次);-32005 主机不支持该能力(换主机或换工具,改参数无用);-32006 策略拒绝(重试无效,需管理员改服务端配置);-32001 超时(可加大 timeout_ms 重试一次);-32602 参数错误(按 message 修正)。
3) 错误码与动作:-32002 主机离线或不存在(先刷新列表);-32003 主机忙(同一台主机同一时刻只允许一个操作,重试无效,等前一个结束);-32004 命令未送达(多为链路瞬断,可重试一次);-32005 主机不支持该能力(换主机或换工具,改参数无用;老客户端不声明 CLIENT_CAP_V2 时 read_file 也返回 -32005,需升级客户端);-32006 只读模式拒绝(terminal_exec / terminal_close;重试无效,需管理员关掉只读);-32001 多为超时,也可能是工具自身失败或已被取消:工具支持 timeout_ms 时先加大重试一次;子连接/会话没建立或同一主机反复超时通常重试无效(主机卡住、链路断或老客户端不认命令);message 写 Request cancelled 的表示客户端已中止,可直接重试;-32602 参数错误(按 message 修正)。
4) get_screenshot 的 screen 模式按链路状况自适应缩放,max_width 省略时最大 1024;region/window/monitor 模式需要声明 CLIENT_CAP_SCREEN_REGION 的较新 Windows 客户端,否则返回 -32005。
5) list_files / read_file 走文件传输通道;read_file 只接受单个普通文件且不超过 2 MiB,目录用 list_files,大文件分段读取。
6) terminal_exec 需要客户端支持终端(CLIENT_CAP_TERMINAL),会在目标主机上创建持久会话;用完调用 terminal_close 释放,闲置会话由服务端回收。
+11 -7
View File
@@ -88,14 +88,17 @@ python tools/mcp_tools/verify_tools.py --live mcp/tools.json
| 命令分支 | `client/`、`linux/main.cpp`、`macos/main.mm`、`android/app/src/main/cpp/main.cpp` |
| 能力位 | `common/commands.h` 的 `LOGIN_INFOR::DefaultCaps()`;Linux 另在 `linux/main.cpp:RefreshLoginCaps` 追加 `SCREEN_PREVIEW` |
当前分布(61 个工具):
当前分布(54 个工具):
| platforms | 数量 | 典型工具 |
|---|---|---|
| `win+lnx+mac+apk` | 10 | 只读写服务端本地数据:`list_online_hosts` / `get_audit_log` / `mcp_*` |
| `win+lnx+mac` | 6 | 进程列表、文件列取、日志、V2 文件传输、`copy_files_c2c` |
| `win+lnx` | 12 | `remote_*` 全族、`get_screenshot`、`get_activity_history`、`exec_command` / `terminal_*` / `kill_process` |
| `win` | 33 | 服务 / 注册表 / 键日志 / 文件写 / **`list_windows`** / `get_foreground_window` / `host_*` / `chat_*` / `power_action` |
| `win+lnx+mac+apk` | 9 | 只读写服务端本地数据:`list_hosts` / `get_host_detail` / `get_client_log` / `get_audit_log` / `get_server_status` / `mcp_*` / `host_set_remark` / `host_set_watch_level` |
| `win+lnx+apk` | 11 | `remote_*` 全族、`exec_command` / `terminal_*`、`get_screenshot`、`get_activity_history` |
| `win+lnx+mac` | 6 | 进程列表、文件列取 / V2 文件传输(含 `read_file`)、`copy_files_c2c` |
| `win+lnx` | 2 | `http_probe`、`kill_process` |
| `win+apk` | 6 | `remote_block_input`、`uninstall_host`、`chat_*` 全族 |
| `win` | 19 | 服务 / 注册表 / 键日志 / 文件搜索与写入 / **`list_windows`** / `get_foreground_window` / `host_inspect` / `host_control_*` / `operate_window` / 网络连接 / `power_action` |
| `apk` | 1 | `remote_lock_screen` |
**注意 `exec_command` / `terminal_*` / `kill_process` 不在 `win+lnx+mac` 组**:
macOS 客户端其实有对应实现(`macos/main.mm:753` 的 `ShellworkingThread` 跑 PTY,
@@ -107,8 +110,9 @@ macOS 客户端其实有对应实现(`macos/main.mm:753` 的 `ShellworkingThre
`SystemManager.h:38` 和 macOS 的 `SystemManager.mm:39` 都有 `COMMAND_WSLIST`
的 `case` 分支,看起来是支持的。但 `BuildListWindows` 把命令发在**主连接**上
(`McpServer.cpp:2931`),而这两个平台的主循环只处理 `COMMAND_SYSTEM`
(起 SystemManager 子连接),`WSLIST` 在子连接里才被处理——走不到。实测 Linux
上直接超时 `-32001`。那两个 `case` 是给 SystemDlg 窗口管理用的,不是 MCP 这条路径。
(起 SystemManager 子连接),`WSLIST` 在子连接里才被处理——走不到。关掉平台门禁
(`McpPlatformGuard=0`)时实测 Linux 上直接超时 `-32001`;默认门禁开启时,这张表
会先拦下并返回 `-32005`。那两个 `case` 是给 SystemDlg 窗口管理用的,不是 MCP 这条路径。
Windows 是在主循环里处理的(`client/KernelManager.cpp:1491`),所以正常。
### 平台优先级(产品定位)