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

+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 只表示命令已送达客户端,不代表成功。"