# YAMA 服务端 MCP 支持方案 > 版本:1.0 > 状态:Final(定稿) > 适用范围:`server/2015Remote/`(C++/MFC 服务端,生产主流) --- ## 1. 背景与目标 ### 1.1 背景 MCP(Model Context Protocol)是 Anthropic 提出的开放协议,让 AI 助手(Claude Code、Claude Desktop 等)通过标准化的工具调用接口访问外部系统的能力。 YAMA 服务端维护了「在线主机列表」这一核心数据,如果能通过 MCP 暴露出去,用户就能在 Claude Code 里直接问「现在有多少台机器在线?」「列出所有在线的 Windows 主机」等,由 AI 调用工具获取实时数据。 ### 1.2 本期范围(MVP) **只跑通 MCP,只实现一个工具**,把可扩展架构搭起来: - 传输方式:Streamable HTTP(`POST /mcp`,JSON-RPC 2.0 over HTTP) - 工具数量:1 个 —— `list_online_hosts`(获取在线主机列表) - 暴露范围:启用开关(默认关闭,经「扩展 → MCP设置」对话框开启)+ 绑定地址可配置(默认 `127.0.0.1` 仅本机)+ token 认证(env / THIS_CFG / 随机) - 后续:逐步添加工具(进程列表、命令执行、屏幕截图等),架构不动 ### 1.3 非目标(明确不做) - 不做 SSE 服务器推送(本期工具调用是 request/response 即可) - 不做多用户/角色体系(复用现有 WebService 认证或静态 token) - 不做写操作工具(操控主机的工具属于后续阶段,需单独评审安全边界) - 不碰现有 Web 控制台的 WebSocket 服务 --- ## 2. 现状分析 C++ 服务端已有大量可直接复用的资产,MCP 的落地成本因此大幅降低。 | 现成资产 | 位置 | 在 MCP 中的角色 | |---|---|---| | HTTP 服务器 | `httplib.h`(header-only,`file_server.h:34` 已用) | MCP 的 HTTP 传输层 | | JSON 库 | `jsoncpp/json.h`(`WebService.cpp` 已用) | JSON-RPC 编解码 | | Token 认证 | `WebServiceAuth.h`(`GenerateToken` / `ValidateToken` / `ComputeSHA256`) | 可选升级路径;MVP 用简单静态 token 比对(见 §3.5) | | 在线主机列表 → JSON | `CWebService::BuildDeviceListJson()`(`WebService.cpp:1506`) | **工具 `list_online_hosts` 的核心逻辑** | | 在线主机数据源 | `CMy2015RemoteDlg::m_HostList`(`2015RemoteDlg.h:345`,`m_cs` 保护)+ `context::IsLogin()` + `context::GetClientData()` | 取数入口 | | 配置系统 | `THIS_CFG.GetInt/GetStr("settings", ...)` | MCP 端口/token 配置 | ### 2.1 关键结论 - **HTTP、JSON、认证、主机列表 JSON 全部现成**,MCP 侧不需要重新造轮子。 - **唯一需要手写的是 MCP 的 JSON-RPC 2.0 协议层**,因为 C++ 没有官方 MCP SDK(官方仅有 TS/Python/Java/Kotlin/C#/Go)。 ### 2.2 `BuildDeviceListJson` 现状 `WebService.cpp:1506` 的 `CWebService::BuildDeviceListJson(const std::string& username)` 已实现: - 遍历 `m_pParentDlg->m_HostList`,过滤 `ctx->IsLogin()` - 输出字段:`id` / `name` / `remark` / `ip` / `os` / `location` / `rtt` / `version` / `activeWindow` / `online` / `group` / `screen` / `clientType` - 已处理 GBK/UTF-8 编码分叉(`activeWindow` 字段按客户端能力位选择编码页,见 `WebService.cpp:1581` 附近的 `GetClientEncoding`) **该方法是 `private`**(`WebService.h:160`,位于 private 段)。MCP 侧需通过公开入口复用(见 §3.4)。 --- ## 3. 方案设计 ### 3.1 总体架构 ``` 2015Remote.exe(MFC 服务端进程) ├─ IOCP TCP 服务(被控端连接,现有) ├─ WebService(ws::Server,Web 控制台,现有,8080) └─ McpServer(httplib,新增,默认禁用,经「MCP设置」开启后监听 127.0.0.1:6544) POST /mcp → JSON-RPC 分发 ├─ initialize ├─ tools/list └─ tools/call └─ list_online_hosts → 复用 BuildHostJson(公共函数,§3.4) ``` **核心决策:独立起一个 httplib server,不挂到现有 `ws::Server`。** 理由: - 现有 `ws::Server` 的 `HttpHandler` 只有 `path` 参数、无 POST body(`SimpleWebSocket.h:345`),强挂 MCP 需改动其底层,侵入大、有回归风险。 - 独立 server 零耦合、零风险,且天然满足「仅 127.0.0.1」的绑定需求。 ### 3.2 新增文件清单 | 文件 | 职责 | 估算量 | |---|---|---| | `McpServer.h` / `McpServer.cpp` | httplib 封装、`POST /mcp` 路由、token 校验、生命周期 | ~120 行 | | `McpProtocol.h` / `McpProtocol.cpp` | JSON-RPC 2.0 协议层:`initialize` / `tools/list` / `tools/call` 分发 | ~250 行 | | `McpTools.h` / `McpTools.cpp` | 工具注册表 + `list_online_hosts` 实现 | ~80 行 | | `McpSettingsDlg.h` / `McpSettingsDlg.cpp` | 「MCP设置」配置对话框(启用/端口/绑定/token + 重启提醒) | ~150 行 | | 修改 `2015RemoteDlg.cpp` / `.h` | 启动/停止 McpServer + 菜单项接线(`ID_MCP_SETTINGS` → `OnMcpSettings`) | ~30 行 | | 修改 `2015Remote.rc` / `resource.h` / `UIBranding.h` / `FeatureFlags.h` | `ID_MCP_SETTINGS` 菜单项 + `IDD_DIALOG_MCP_SETTINGS` 对话框资源 + `HIDE_MENU_MCP_SETTINGS` + `MF_MCP_SETTINGS` 许可位 | 少量 | > 头文件/实现可合并精简,实际以「一个 `McpServer` 类 + 一个工具注册表 + 一个协议分发函数」为最小形态,文件拆分仅为可读性。 ### 3.3 协议层设计(JSON-RPC 2.0) MCP 是 JSON-RPC 2.0。MVP 只需实现以下方法: #### 3.3.1 `initialize`(握手) 请求: ```json {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"claude","version":"..."}}} ``` 响应: ```json {"jsonrpc":"2.0","id":1,"result":{ "protocolVersion":"2025-06-18", "capabilities":{"tools":{}}, "serverInfo":{"name":"yama","version":""} }} ``` #### 3.3.2 `tools/list` 请求:`{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}` 响应: ```json {"jsonrpc":"2.0","id":2,"result":{"tools":[{ "name":"list_online_hosts", "description":"获取当前所有在线主机的列表,包含计算机名、IP、操作系统、版本、备注、分组、活动窗口、延迟等实时信息。", "inputSchema":{"type":"object","properties":{},"required":[]}, "outputSchema":{ "type":"object", "properties":{ "hosts":{ "type":"array", "items":{ "type":"object", "properties":{ "id":{"type":"string"}, "name":{"type":"string"}, "remark":{"type":"string"}, "ip":{"type":"string"}, "os":{"type":"string"}, "location":{"type":"string"}, "rtt":{"type":"string"}, "version":{"type":"string"}, "activeWindow":{"type":"string"}, "online":{"type":"boolean"}, "group":{"type":"string"}, "screen":{"type":"string"}, "clientType":{"type":"string"}, "tls":{"type":"boolean"} } } } }, "required":["hosts"] } }]}} ``` #### 3.3.3 `tools/call` 请求: ```json {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_online_hosts","arguments":{}}} ``` 响应(结构化输出:`structuredContent` 承载主机数组,`content` 是可读摘要 + 同一份结构的紧凑 JSON): ```json {"jsonrpc":"2.0","id":3,"result":{ "structuredContent":{ "hosts":[ {"id":"123","name":"DESKTOP-ABC","remark":"我的Windows","ip":"192.168.0.92", "os":"Windows 10","location":"上海市","rtt":"12","version":"...", "activeWindow":"WeChat","online":true,"group":"default","screen":"1:1920x1080","clientType":"EXE"} ] }, "content":[ {"type":"text","text":"共 1 台主机在线。"}, {"type":"text","text":"{\"hosts\":[{\"id\":\"123\",\"name\":\"DESKTOP-ABC\",...}]}"} ], "isError":false }} ``` 第二个文本块来自 §14:规范要求返回 `structuredContent` 时也把序列化 JSON 放进 TextContent,否则只读 `content` 的客户端拿不到 `id`。 #### 3.3.4 可选实现 - `ping`:返回空 result(便于健康检查) - `notifications/initialized`:客户端通知,可忽略 #### 3.3.5 错误响应(JSON-RPC 2.0 标准) 协议层必须处理以下错误,返回标准 `error` 结构(`id` 回填请求 id): | 场景 | code | message | |---|---|---| | 请求体不是合法 JSON | `-32700` | Parse error | | 请求结构不合法(缺 jsonrpc/method 等) | `-32600` | Invalid Request | | 方法未实现 | `-32601` | Method not found | | 参数非法 | `-32602` | Invalid params | | 内部错误 | `-32603` | Internal error | 示例(方法未实现): ```json {"jsonrpc":"2.0","id":1,"error":{"code":-32601,"message":"Method not found"}} ``` #### 3.3.6 传输层约定(Streamable HTTP 最小子集) - 客户端 `POST /mcp`,请求头 `Content-Type: application/json`、`Accept: application/json, text/event-stream`。 - 服务端返回 `Content-Type: application/json`(MVP 工具调用为 request/response,无需 SSE 流式)。 - `initialize` 响应可回填 `Mcp-Session-Id` 头用于会话管理;MVP 单会话可省略,实现时对照最新 MCP 规范确认。 - 仅接受 `POST /mcp`,其余路径/方法返回 404/405。 ### 3.4 工具设计:`list_online_hosts` #### 取数方案(已定:抽公共函数) `BuildDeviceListJson` 目前是 `CWebService` 的 private 方法,且依赖 `m_pParentDlg`。为满足「MCP 与 WebService 是平级数据消费者、不互相依赖」的原则,采用**方案 C:抽公共函数**。 ```cpp // 公共函数:提取单台在线主机的完整数据(含 GBK/UTF-8 编码处理),返回 UTF-8 的 Json::Value Json::Value BuildHostJson(context* ctx, _ClientList* clientMap); ``` - `CWebService::BuildDeviceListJson` 内部改调该公共函数,Web 侧签名与输出不变(零回归)。 - `McpServer` 侧持 `CMy2015RemoteDlg*`(`SetParentDlg`),在 `m_cs` 锁内遍历 `m_HostList`、`IsLogin()` 过滤,对每台主机调 `BuildHostJson`,组装为结构化输出。 - **职责边界**:用户名/分组过滤(`username` → `allowed_groups`)、`m_cs` 加锁、以及外层结构(Web 的 `{"cmd","devices"}` vs MCP 的 `{"hosts"}`)属于**调用方**,不进公共函数;`BuildHostJson` 只负责「单台主机 → `Json::Value`」的字段序列化与编码转换。其中 `remark` 依赖 `m_ClientMap->GetClientMapData(id, MAP_NOTE)`,故 `clientMap` 作为参数传入。 选型说明:方案 A(MCP 依赖 `CWebService` 单例)依赖方向错误,且 `WebSvrPort=0` 时 `m_pParentDlg` 为空导致取不到数;方案 B(MCP 自持父对话框复制逻辑)违反 DRY、重复易错的编码处理。故取 C。 #### 返回内容(全量,含实时信息) **保留 `BuildDeviceListJson` 的全部字段,不做精简**,以支持「AI 协助监督客户端运行状态」的场景: - 基础标识:`id` / `name` / `remark` / `ip` / `os` / `location` / `group` / `version` / `clientType` / `screen` - 实时信息:`rtt`(延迟)、`activeWindow`(当前活动窗口,即被控端正在做什么) - 连接凭据:`tls`(布尔,对应在线主机列表的 TLS 列;`true` 表示该客户端本轮以 TLS 模式登录,是**登录时的凭据**而非实时探测;老客户端/空值一律 `false`) 输出结构 `{"hosts": [...]}`,每台主机一个对象,字段与 §3.3.2 的 `outputSchema` 一致。 ### 3.5 安全设计 - **绑定地址**:默认 `127.0.0.1`(仅本机回环,其他机器无法访问);可经 `McpBind` 配置为 `0.0.0.0`(所有网卡)或内网 IP(如 `192.168.0.92`)以支持远程调用。 - 非回环绑定时 token 经明文 HTTP 传输,需强 token,并建议配合防火墙限制源 IP 或启用 HTTPS(项目已有 WebHTTPS 实践)。 - **静态 token 校验**:每个 `POST /mcp` 请求校验 `Authorization: Bearer ` header;不匹配返回 HTTP 401。 - **token 来源**(优先顺序):环境变量 `YAMA_MCP_TOKEN` → `THIS_CFG` 的 `McpToken` → 两者皆空则**随机生成**。 - 前两者任一非空即作为固定 token;仅当两者皆空时才随机生成(仅本次进程运行期间有效,进程重启后重新生成不同的 token)。 - 随机生成时**必须将 token 输出到日志**(`Mprintf`),否则用户无从获知、无法在 Claude Code 侧配置。 - 环境变量名 `YAMA_MCP_TOKEN` 建议同 `BRAND_WEB_ENV_VAR` 一样在 `UIBranding.h` 定义为宏(如 `BRAND_MCP_ENV_VAR`),避免散落硬编码字符串。 - **只读边界**:MVP 仅一个只读工具,不暴露任何写/操控能力。 - **HTTP 方法限制**:仅接受 `POST /mcp`,其余返回 404/405。 ### 3.6 配置设计 沿用现有 `THIS_CFG`(`settings` 节): | 配置键 | 默认值 | 说明 | |---|---|---| | `McpEnabled` | `0` | MCP 总开关:`0` = 禁用(默认),`1` = 启用。经「扩展 → MCP设置」对话框设置 | | `McpPort` | `6544` | MCP 监听端口;仅当 `McpEnabled=1` 时生效;未配置用默认 `6544` | | `McpBind` | `127.0.0.1` | 监听地址;默认仅本机;可设 `0.0.0.0`(所有网卡)或内网 IP(如 `192.168.0.92`)以支持远程 | | `McpToken` | 空(UI 默认随机值) | 静态 token;对话框内「token 必填、默认随机值」——首次打开若为空则预填随机并随保存持久化。运行时优先级:env `YAMA_MCP_TOKEN` → `McpToken` → 皆空则随机生成(见 §3.5) | | `McpKeylog` | `0` | 键盘记录工具 `get_keylog` 的独立开关(见 §9.3);与 `McpReadonly` 无关,改动需重启生效 | | `McpToolTimeoutMs` | `20000` | 工具等待客户端响应的默认超时(ms),clamp 到 `[1000, 600000]`;各工具自己的 `timeout_ms` 参数优先。**ini-only**(无设置界面控件),改动需重启生效 | | `McpHttps` | `0` | `1` = 对外端口说 HTTPS(native TLS,见 §13),httplib 退到 `127.0.0.1:McpInternalPort`;`0` = 保持明文。经「MCP设置」对话框的「启用 HTTPS」复选框设置,改动需重启生效 | | `McpCertPath` | 空(回退 `[tls] CertPath`) | MCP 专用证书(PEM)。面向公网客户端时应为公共 CA 证书(如 Let's Encrypt 的 `fullchain.pem`),不要复用设备端口的自签证书。对话框「证书路径」行可填/浏览;为空时按回退规则预填 `[tls]` 的值 | | `McpKeyPath` | 空(回退 `[tls] KeyPath`) | 与 `McpCertPath` 配对的私钥,须为 PKCS#8(`-----BEGIN PRIVATE KEY-----`)。对话框「私钥路径」行可填/浏览 | | `McpInternalPort` | 空(取 `McpPort+1`) | `McpHttps=1` 时 httplib 实际监听的回环端口,仅绑定 `127.0.0.1`。**ini-only**(对话框不暴露,自动取 `McpPort+1`) | > 对话框里「证书路径/私钥路径」两行仅在勾选「启用 HTTPS」后可编辑;保存时校验两者非空且文件存在(加载失败会导致 MCP 监听 fail-closed,故提前挡住),格式仍以服务端实际加载为准。 > 与旧版「`McpPort=0` 即禁用」不同:启用与否改由独立的 `McpEnabled` 开关控制,`McpPort` 回归纯端口语义,二者解耦。 ### 3.7 生命周期接入 在 `2015RemoteDlg.cpp` Web 服务启动块(约 `2048-2081`)之后,新增 MCP 启动逻辑。`McpServer` 与 `CWebService` 同为单例:提供 `static McpServer& Instance()` 与全局 `inline McpServer& McpServer()` 访问器(仿 `WebService()`,见 `WebService.h` 末尾的全局访问器写法)。 ```cpp auto mcpEnabled = THIS_CFG.GetInt("settings", "McpEnabled", 0); // 默认禁用 auto mcpPort = THIS_CFG.GetInt("settings", "McpPort", 6544); auto mcpBind = THIS_CFG.GetStr("settings", "McpBind", "127.0.0.1"); if (mcpEnabled) { // token 优先顺序:env YAMA_MCP_TOKEN → THIS_CFG McpToken → 皆空则随机(仅本次进程有效) const char* envTok = getenv("YAMA_MCP_TOKEN"); std::string mcpToken; if (envTok && *envTok) { mcpToken = envTok; } else { mcpToken = THIS_CFG.GetStr("settings", "McpToken", ""); } if (mcpToken.empty()) { mcpToken = GenerateRandomToken(); // 32 hex 随机串 Mprintf("[McpServer] YAMA_MCP_TOKEN / McpToken 均未设置,本次进程随机 token:%s\n", mcpToken.c_str()); } McpServer().SetParentDlg(this); // 方案 C:MCP 需遍历 m_HostList,须持父对话框指针 McpServer().SetToken(mcpToken); if (!McpServer().Start(mcpBind, mcpPort)) { Mprintf("McpServer start failed on %s:%d\n", mcpBind.c_str(), mcpPort); } } ``` 并在退出路径(`OnDestroy` / `ExitInstance` 对应位置)调用 `McpServer().Stop()`。 ### 3.8 「MCP设置」配置对话框 MCP 默认不启用,通过主对话框「扩展 → MCP设置」菜单项打开配置对话框来开启。菜单项位置:`2015Remote.rc` 扩展菜单(`POPUP "扩展(&X)"`)内、「地理信息(&L)」子菜单(纯真数据库 / IP2Region)的 `END` 之后、「插件设置」之前。 #### 3.8.1 菜单与资源接线 1. **`resource.h`**:新增命令 ID(取当前空闲段,经查 `33077` 空闲): ```cpp #define ID_MCP_SETTINGS 33077 ``` 2. **`2015Remote.rc`**:在「地理信息(&L)」子菜单 `END` 之后、`插件设置` 之前插入: ``` MENUITEM "MCP设置(&M)...", ID_MCP_SETTINGS ``` 并新增对话框资源 `IDD_DIALOG_MCP_SETTINGS`(「启用 MCP」复选框 + 端口/绑定地址/token 三个编辑框 + 确定/取消按钮)。 3. **`UIBranding.h`**:扩展菜单隐藏开关新增一行(默认 `0` 显示): ```cpp #define HIDE_MENU_MCP_SETTINGS 0 // MCP设置 ``` 4. **`FeatureFlags.h`**:新增运行时许可位,占用 MenuFlags 保留段 `[43-63]` 的首位(紧跟 `MF_REQUEST_AUTH` 之后): ```cpp #define MF_MCP_SETTINGS (1ULL << 43) // HIDE_MENU_MCP_SETTINGS ``` 5. **`2015RemoteDlg.cpp`**:`#include "McpSettingsDlg.h"`,然后消息映射 + 处理器 + 剪枝: ```cpp ON_COMMAND(ID_MCP_SETTINGS, &CMy2015RemoteDlg::OnMcpSettings) // ... void CMy2015RemoteDlg::OnMcpSettings() { CMcpSettingsDlg dlg(this); dlg.DoModal(); } ``` 并在扩展菜单剪枝块(`pExtMenu`,约 `2015RemoteDlg.cpp:1225` 之后)追加: ```cpp if (SHOULD_HIDE_MENU(HIDE_MENU_MCP_SETTINGS, MF_MCP_SETTINGS)) pExtMenu->DeleteMenu(ID_MCP_SETTINGS, MF_BYCOMMAND); ``` > **实现注意**:`2015Remote.rc` 为 UTF-16 编码,菜单与对话框资源须由 VS 资源编辑器维护(手工改文本易破坏编码与资源 ID 引用)。`IDD_DIALOG_MCP_SETTINGS` 需在 `resource.h` 分配独立空闲的 `IDD_` 数值(与 `ID_MCP_SETTINGS` 分开);对话框内控件 ID(如 `IDC_CHK_ENABLE_MCP` / `IDC_EDIT_MCP_PORT` / `IDC_EDIT_MCP_BIND` / `IDC_EDIT_MCP_TOKEN`)同理。 #### 3.8.2 对话框字段与默认值 | 控件 | 绑定配置键 | 默认值 | 说明 | |---|---|---|---| | 「启用 MCP」复选框 | `McpEnabled` | 未勾选(`0`) | 勾选后持久化 `McpEnabled=1` | | 端口 | `McpPort` | `6544` | 数字编辑框,仅当启用时有效 | | 绑定地址 | `McpBind` | `127.0.0.1` | 默认仅本机;可改 `0.0.0.0` / 内网 IP | | Token | `McpToken` | 随机值 | 必填;为空时预填随机 token | | 「启用 HTTPS」复选框 | `McpHttps` | 未勾选(`0`) | 勾选后本端口同时接受 TLS(§13);未勾选时下面两行置灰 | | 证书路径 | `McpCertPath` | 空(回退 `[tls] CertPath`) | PEM;带「浏览」按钮。为空时按回退规则预填 `[tls]` 的值 | | 私钥路径 | `McpKeyPath` | 空(回退 `[tls] KeyPath`) | PKCS#8;带「浏览」按钮 | 保存时若勾选了 HTTPS,证书/私钥必须非空且文件存在,否则弹提示并留在对话框(身份加载失败会让 MCP 监听 fail-closed,故提前挡住);HTTPS 改动与其它项一样重启生效。 #### 3.8.3 初始化与保存 打开时读 `THIS_CFG` 回填;token 为空则当场生成随机值预填(32 hex)。保存时落盘并弹重启提醒: ```cpp BOOL CMcpSettingsDlg::OnInitDialog() { CDialogLangEx::OnInitDialog(); int enabled = THIS_CFG.GetInt("settings", "McpEnabled", 0); int port = THIS_CFG.GetInt("settings", "McpPort", 6544); std::string bind = THIS_CFG.GetStr("settings", "McpBind", "127.0.0.1"); std::string tok = THIS_CFG.GetStr("settings", "McpToken", ""); if (tok.empty()) tok = GenerateRandomToken(); // 预填随机,随保存持久化 // 回填到控件:m_bEnabled / m_nPort / m_strBind / m_strToken return TRUE; } void CMcpSettingsDlg::OnBnClickedBtnSave() { // 从控件收集:enabled / port / bind / token if (enabled && token.empty()) { MessageBoxL(_TR("Token 不能为空"), _TR("提示"), MB_ICONWARNING); return; } THIS_CFG.SetInt("settings", "McpEnabled", enabled ? 1 : 0); THIS_CFG.SetInt("settings", "McpPort", port); THIS_CFG.SetStr("settings", "McpBind", bind); THIS_CFG.SetStr("settings", "McpToken", token); MessageBoxL(_TR("MCP 设置已保存。\n启用/端口/绑定地址/Token 的改动需重启程序生效。"), _TR("提示"), MB_ICONINFORMATION); CDialogLangEx::OnOK(); } ``` #### 3.8.4 与运行时 token 逻辑的衔接 对话框的「默认随机 token」是把随机值**写入 `McpToken` 并持久化**,于是下次启动走 `env → McpToken` 的固定 token 分支;运行时「两者皆空则随机」分支仅在用户从未通过对话框设置过(或手动清空 token)时兜底,两者不冲突。`GenerateRandomToken()` 为 MCP 侧新增的小工具函数(32 hex 随机串,可用 `rand_s` / `BCryptGenRandom` 实现;如需可复用 `WebServiceAuth.h` 的 `ComputeSHA256` 派生)。 --- ## 4. 实施步骤 | 步骤 | 内容 | 验收 | |---|---|---| | 1 | 新建 `McpProtocol`:JSON-RPC 分发 + `initialize`/`tools/list`/`tools/call`(含 jsoncpp 解析/序列化) | 单元自测:手写请求串,验证响应 | | 2 | 新建 `McpServer`:httplib 起 `127.0.0.1:6544`,`POST /mcp` 路由 + token 校验(含随机生成) | curl 请求返回 401/正常 | | 3 | 抽公共函数 `BuildHostJson`,`CWebService::BuildDeviceListJson` 改调之 | Web 输出不变,零回归 | | 4 | 注册 `list_online_hosts` 工具:handler 持父对话框、`m_cs` 锁内遍历、调 `BuildHostJson` 组装 | `tools/call` 返回主机列表 | | 5 | 新增 `McpSettingsDlg` + 菜单项接线(`ID_MCP_SETTINGS` / `OnMcpSettings` / `HIDE_MENU_MCP_SETTINGS` / `IDD_DIALOG_MCP_SETTINGS` 资源) | 对话框可启用/禁用、配置端口/绑定/token,保存落盘并提示重启 | | 6 | 接入 `2015RemoteDlg` 启动/停止(按 `McpEnabled` 门控)+ 配置 | 服务端启动后端口监听正常 | | 7 | Claude Code 接入验证(见 §5) | 见验收标准 | --- ## 5. 验收标准 1. 在「MCP设置」对话框启用并重启服务端后,`127.0.0.1:6544` 监听正常,外部地址无法访问;未启用时该端口不监听。 2. 无 token 的请求返回 HTTP 401;错误 token 返回 401;正确 token 通过。 3. `curl` 模拟 `initialize` → `tools/list` → `tools/call` 全流程,返回符合 JSON-RPC 2.0 与 MCP 规范。 4. Claude Code 侧: ```bash claude mcp add yama --transport http http://127.0.0.1:6544/mcp -H "Authorization: Bearer " ``` `claude mcp list` 能看到 `yama`,在对话中问「列出在线主机」能正确触发工具并返回列表。 5. 现有 Web 控制台、IOCP 主服务功能无回归。 --- ## 6. 风险与约束 | 风险 | 说明 | 应对 | |---|---|---| | 无官方 C++ MCP SDK | 需手写 JSON-RPC 协议层 | 仅实现 3 个方法,量小可控;协议稳定后再考虑抽库 | | MCP 规范版本演进 | protocolVersion 字符串需与客户端匹配 | 实现时对照最新规范;`initialize` 返回可协商版本 | | 并发安全 | 遍历 `m_HostList` 需持 `m_cs` | MCP 与 WebService 采用相同的「`m_cs` 锁内遍历」模式 | | 字符编码 | GBK/UTF-8 分叉 | 复用公共函数 `BuildHostJson` 的编码处理,不自造 | | token 存储 | `THIS_CFG` 的 token 会明文落盘;随机 token 会打印到日志 | 本地回环 + 只读,风险可控;敏感场景建议仅用 env 并妥善保管 | --- ## 7. 后续扩展规划(本期不做) - 工具:`get_host_processes`(进程列表)、`execute_command`(命令执行)、`capture_screen`(截图)等 - 写操作工具的安全边界评审(操作对象、权限、审计) - 认证升级:复用 `WebServiceAuth` 的签名 token / 过期机制 - 分组过滤:`list_online_hosts` 加 `group` 参数 - P9 远程交谈(已实现):`chat_open` / `chat_send` / `chat_wait` / `chat_close`,独立开关 `McpChat`(默认 `0`,与只读开关无关);协议不变,客户端聊天窗口改为 Unicode 对话框以支持非中文系统(见 `docs/Mcp_Chat_Design.md`) --- ## 8. 决策记录 **决策记录(全部已定):** - ✅ **启用开关**:新增 `McpEnabled`,默认 `0`(禁用)。MCP 默认不启动,须用户在「扩展 → MCP设置」对话框手动开启。 - ✅ **端口**:`McpPort` 可配置,未配置默认 `6544`(纯端口语义,不再兼任启用开关)。 - ✅ **token**:优先顺序 env `YAMA_MCP_TOKEN` → `THIS_CFG.McpToken` → 皆空则随机生成(仅本次进程有效,打印到日志)。对话框内 token 必填、默认随机值(预填并随保存持久化到 `McpToken`)。 - ✅ **绑定地址**:默认 `127.0.0.1`(仅本机);可配置为 `0.0.0.0` 或内网 IP(如 `192.168.0.92`)以支持多人协作跨机调用。 - ✅ **配置入口**:主对话框「扩展」菜单,位于「地理信息(&L)」子菜单下方新增「MCP设置」菜单项,打开独立配置对话框。 - ✅ **生效方式**:MCP 启用/端口/绑定/token 的改动均需重启服务端生效,对话框保存后弹窗提醒「重启程序生效」。 - ✅ **取数方案**:C(抽公共函数 `BuildHostJson`,MCP 与 WebService 平级复用)。 - ✅ **返回字段**:全量,含实时信息(`rtt` / `activeWindow`),支持 AI 监督场景。 - ✅ **序列化**:`structuredContent` + `outputSchema`,`content` 附带可读摘要(2026-10-26 起再追加一份紧凑 JSON,见 §14)。 --- ## 9. 增补(2026-10-25:N1–N5) 本轮在既有工具族(P2–P9)之上补齐「能找到主机、能一次查多台、输出不撑爆上下文、认证可追溯」四件事,全部为服务端改动,客户端零改动。 ### 9.1 N1 离线主机可见 - 新增工具 `list_all_hosts`(`online` / `offline` 两个布尔过滤,默认都为 `true`),数据源是 `m_ClientMap`(主机列表历史记录,`GetAll()` 快照 + `m_cs` 保护),在线条目复用 `BuildHostJson`,离线条目由 `BuildOfflineHostJson` 生成,字段:`id` / `name` / `remark` / `ip` / `os` / `location` / `online` / `group` / `last_seen` / `install_time` / `authStatus`。 - `search_hosts` 的 `online` 参数:`true` = 仅在线,`false` = 仅离线(修复此前 `online=false` 永远返回空列表的问题),缺省 = 仅在线(与改动前一致,不改变既有调用方看到的结果)。两类都要请用 `list_all_hosts`。 - `authStatus` 是 `ClientValue::Authorized` 的三态枚举(`unauthorized` / `authorized_by_super` / `authorized_by_admin` / `forbidden`),不是布尔值。 - `get_host_detail` 对「在 `m_ClientMap` 里但当前离线」的 id 不再返回 `-32002`,改为返回该主机的最后记录(`online=false`),使 `list_all_hosts` 的结果可直接消费。 ### 9.2 N2 批量只读调用 - 只读工具支持 `ids: []`(最多 50 个),与 `id` 二选一(inputSchema 用 `anyOf` 表达)。命中批量的工具:`get_host_detail` / `list_processes` / `list_windows` / `list_services` / `list_files` / `list_registry` / `get_client_log` / `get_activity_history` / `list_network_connections` / 全部 `host_list_*` / `host_get_hosts_file`。 - 写操作工具传 `ids` 直接 `-32602` 拒绝(不逐个执行,避免误操作扩散)。 - 返回:`{tool, total, succeeded, failed, results:[{id, ok, data|error, text}]}`;`content` 里是「共 N 台,成功 X 台,失败 Y 台」+ 最多 ~1200 字节的失败明细。 - `limit` / `offset` 对每台主机各自生效;批量是串行执行,单台超时会占用整批等待时间。 - **outputSchema 必须声明批量形状**:只声明单机形状会让客户端把批量结果判为不合规 (`-32602: data must have required property 'host'`)。现在由 `ApplyBatchOutputSchema` 统一补成 `anyOf:[单机, 批量]`,见 §18.1。 ### 9.3 N3 `get_keylog` - 复用客户端既有键盘记录链路:主连接下发 `COMMAND_KEYBOARD(169)` → 客户端建子连接 → 子连接回 `TOKEN_KEYBOARD_START(293)` 作为就绪包绑定 → 之后每约 1 秒推一包 `TOKEN_KEYBOARD_DATA(294)`。 - 服务端把击键流**累积**(不是一问一答),窗口 `duration_ms`(默认 4000,1000–15000)或字节上限 `max_bytes`(默认 64 KiB,1024–256 KiB)先到者结束;结束时 `EndManagedSession(..., cancelIo=true)` 关闭子连接 —— 与 MFC 关对话框同一路径,客户端据此停止记录。 - 复用 P8 的挂起会话表(新增 `PendingKind::Keylog`,仍受「单设备单飞行」约束),就绪包绑定、迟到包墓碑、子连接断开唤醒全部沿用 P8 逻辑;绑定后服务端回 `COMMAND_NEXT`,让客户端 `WaitForDialogOpen` 立即返回(本工具不开 UI)。 - 返回 `{id, duration_ms, bytes, lines, lineCount, truncated}`,文本按客户端代码页转 UTF-8(`GetClientEncoding`)。**注意**:客户端连上后会先把缓冲区里已有的历史记录推过来,所以结果既含历史也含窗口期内的新击键。 - 独立开关 `McpKeylog`(默认 `0`,不要求只读关)。工具只在开关打开时出现在 `tools/list`,关闭时直接调用返回 `-32006`。 - 隐私:击键内容只进本次响应;审计只记 `CALL_OK tool=get_keylog ms=… bytes=…`,不落任何正文。 ### 9.4 N4 认证加固 - 静态 token 校验失败:返回 401,并按来源 IP 计数;60 秒窗口内失败 10 次即封禁该 IP 900 秒,封禁期内返回 429 + `Retry-After`。失败表上限 1024,满时先清理过期项。 - 环回来源(`127.0.0.1` / `::1`)**只记账不封禁**:内置 frpc 把 MCP 端口映射出去时是「本机连本机」,且这条转发没开 Proxy Protocol(httplib 不解析),服务端看到的源地址恒为环回。若按 IP 封禁,一次外部扫描就能把隧道后面所有客户端(包括自己)锁死 15 分钟。审计里这类封禁触发记为 `AUTH_BLOCK ... scope=proxy-source-exempt`。 - 审计文件 `\logs\mcp_audit.log`(追加写,5 MB 轮转为 `.1`),每行:时间戳(毫秒)、事件、来源 IP、详情。 - `AUTH_FAIL`:UA(截断/清洗)、body 大小、是否因此被封禁。 - `AUTH_BLOCK`:封禁生效。 - `CALL_OK` / `CALL_FAIL`:`tool=`、耗时 `ms=`、响应字节数 `bytes=`。 - `CALL_DENIED`:被策略拒绝的调用(`-32006`)另记一条,含 `tool=` 与固定原因文本,见 §10.8。 - 审计**不记录** token、密码、哈希、剪贴板内容或工具返回正文。 ### 9.5 N5 列表输出治理 - 列表类工具统一 `limit` / `offset`:默认 `limit=100`,硬上限 `1000`,`offset` 默认 0;非正数按默认值处理。 - `structuredContent` 统一附 `total` / `totalAll` / `offset` / `limit` / `hasMore`,与 `McpMachine.cpp` 既有约定一致(`host_list_*` / `list_network_connections` 本来就是这样)。 - `content` 摘要统一为「共 N <单位>,本次返回第 a-b 条(还有更多,可用 offset 继续取)。」;`hasMore=false` 时不再出现「继续取」的误导提示;`offset` 越界时明确写「offset 超出范围,本次返回 0 条」。 - 实现集中在 `McpInternal.h/.cpp`:`PageWindow` / `ResolvePageWindow` / `ApplyPageWindow` / `WritePageFields` / `AppendPagingProps` / `PageSummary`。 - `list_files` 整目录解析后再分页:`ParseFileList` 的上限是 100000 条,只用于兜住病态目录;到上限时 `structuredContent.truncated=true`,摘要与 `total` 也会说明 `total` 只是上限内的数量。`total` / `hasMore` 反映真实目录条目数,`offset` 可翻到 500 条之后。分页由服务端完成(`limit` 默认 100、上限 1000),客户端仍一次性回全量。 --- ## 10. 增补(2026-10-25:A 批加固 / B 批非破坏性能力) A 批只改服务端传输、元数据与校验,不动任何既有工具语义;B 批新增三个工具(两个写主机库、一个远程搜索)。**客户端零改动。** ### 10.1 A1/A2 传输层加固(`CMcpServer::Start`) httplib 默认值对 MCP 场景不合适,改为显式配置: | 项 | 默认 | 现在 | 原因 | |---|---|---|---| | 请求体上限 | 不限(`SIZE_MAX`) | 2 MB(超出 413 `RequestEntityTooLarge`) | 只收 JSON 参数,文件内容走子连接分块,绝不进 HTTP body | | 读超时 | 5s | 15s | 经 frp 隧道上传参数时,单次 recv 不该 5s 就断 | | 写超时 | 5s | 60s | `get_screenshot` 大图 base64、慢链路下 5s 会写断响应 | | 线程池 | `max(8, 核数-1)` | 固定 32 | `chat_wait`(最长 55s)与批量只读会长期占线程 | 读超时是 **socket 空闲读超时**,不是「处理时长上限」:`search_file` 阻塞 20s、`chat_wait` 阻塞 55s 都正常返回(已实测)。 ### 10.2 A3 工具注解(`McpInternal::ApplyToolAnnotations`) - `tools/list` 每个工具都带 `annotations`:`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`,由 `McpInternal.cpp` 的 `kToolHints` 表按名登记,末尾统一补一次。 - 未登记的工具按规范默认值处理(`destructiveHint=true`),即**新增工具必须显式登记**,漏登记只会更保守,不会误标成只读。 - 只读工具的 `destructiveHint` 一律 `false`(按规范对只读工具无意义,避免客户端误报「破坏性」)。 - `openWorldHint=false` 只给「只读服务端本机状态」的工具(`list_online_hosts` / `search_hosts` / `list_all_hosts` / `get_host_detail` / `get_activity_history` / `get_audit_log` / `get_server_status`),其余都会触达外部主机。 ### 10.3 A4 `get_host_detail` 字段补全 在线主机现在返回:`id` / `name` / `online` / `ip` / `publicIp` / `location` / `group` / `os` / `version` / `exeVersion` / `clientType` / `clientPath` / `systemBits` / `programBits` / `cpuCores` / `memoryGB` / `monitors` / `screen` / `user` / `isAdmin` / `pid` / `installTime` / `activeWindow` / `rtt` / `tls`;离线主机返回 `authStatus` / `last_seen` / `install_time` 等最后记录。 注意 `memoryGB` 是 **double**:客户端 `GetMemorySizeGB()` 上报的就是浮点字符串(如 `"27.800000000000001"` 的原始形态),不能按整数解析。服务端按 1 位小数规范化,并给 jsoncpp 写入器设 15 位有效数字,避免输出 17 位噪声。 ### 10.4 B1 主机库写入:`host_set_remark` / `host_set_watch_level` - 写的是服务端本机的 `_ClientList`(`MAP_NOTE` / `MAP_LEVEL`),**只影响主控端自己的展示**:不下发命令、不改远端状态。 - 门控:`McpReadonly=0` 即可(不要求 `McpManage`);在线/离线(历史记录)主机都能写,id 在主机库中存在即可。 - `host_set_remark`:`remark` 必填(空串 = 清除),**严格 GBK 转换**(emoji、`ö` 等不可表示字符报 `-32602`),长度上限 63 GBK 字节(主机库列 `char Note[64]`)。 - `host_set_watch_level`:`level` 0–3。重复写同一值幂等。 - 写后 `SaveToFile(GetDbPath())` 落库,并用 `LVM_REDRAWITEMS` 让在线列表那一行立刻刷新(MCP 线程不直接碰 `CListCtrl`)。 - 审计只记「set/cleared + 字节数」与 `level=`,**不记录备注正文**。 ### 10.5 B2 远程文件搜索:`search_file` **链路**(旧文件管理器,不是 SimplePlugins 版): ``` 主连接 COMMAND_LIST_DRIVE → 客户端建子连接 → 子连接回 TOKEN_DRIVE_LIST → 服务端 OnDriveList 下发 COMMAND_SEARCH_FILE [根目录 \0][模式 \0](ANSI/GBK 两个 C 串) → N × TOKEN_SEARCH_FILE_LIST(分片)→ TOKEN_SEARCH_FILE_FINISH ``` 协议来自 `client/FileManager.cpp`(`COMMAND_LIST_DRIVE` → `LoopFileManager` → `CFileManager`)。客户端工程是 MultiByte,所有字段都是 GBK,服务端用 `Utf8ToCpExact` 严格转换,不可表示即 `-32602`。 要点: - **模式**:不含 `*` / `?` 时客户端当成 `*pattern*`(不区分大小写的子串),含通配符时走 `WildcardMatch`。 - **递归**:客户端只有递归搜索(深度 32,最多 10000 条,跳过隐藏/系统目录与重解析点)。`recursive=false` 由**服务端按「父目录 == 根目录」过滤**实现。 - **路径归一化**:客户端用 `wsprintf("%s\\*.*")` 枚举,根目录带尾部反斜杠会拼成 `C:\\*.*` 导致 `FindFirstFile` 失败、搜索秒回 0 条。服务端统一切成正斜杠→反斜杠并去尾斜杠(`C:\` → `C:`,客户端再拼回 `C:\*.*`)。 - **超时**:`timeout_ms` 默认 20000(1000–120000)。到点先下发 `COMMAND_FILES_SEARCH_STOP`,再等 5s 收尾;收不到 `FINISH` 也返回已收到的部分结果,`finished=false`。 - **收集上限**:5000 条 / 4 MB 原始包,超出即让客户端停搜并置 `truncated=true`(保护服务端内存,整盘搜索能命中几十万条)。 - **子连接身份校验**:`TOKEN_SEARCH_FILE_LIST` / `TOKEN_SEARCH_FILE_FINISH` 都按 `context*` 比对当前 pending 的子链接,旧搜索(已放弃)的尾包一律不受理,避免迟到的 FINISH 终止新搜索。 - **已知风险(客户端既有缺陷,仓库内已修)**:`client/FileManager.cpp` 的 `SearchFilesRecursive` 曾用无界 `wsprintf` 往 `char[MAX_PATH]` 里拼路径(`strPath`、`szFullPath`),全程没有长度检查。目录一深(累计路径超过 260)就栈溢出:Debug 客户端弹 `Run-Time Check Failure #2 - Stack around the variable 'strPath' was corrupted` 并挂住搜索线程,Release 客户端静默破坏栈。MFC 文件管理器的「搜索」走同一函数,**与 MCP 无关**。源码已于 2026-10-25 修掉(commit 8f718d9,入口/逐条目长度预判);**已部署的老客户端仍带这个缺陷**,所以 `tools/mcp_smoke.ps1` 的搜索用例仍是 opt-in(`-SearchPath`)。 - **无头路由**:MFC 对话框存在时搜索结果走 `OnReceiveComplete`;只有无头子连接(MCP 调用)才会进 `MessageHandle`,所以这两条 case 只影响 MCP。`TOKEN_SEARCH_FILE_LIST` 分支**绝不 CancelIO**(后面还有 FINISH 与剩余分片)。 - 输出:`{files:[{path,name,dir,size,modified}], finished, truncated, total, totalAll, offset, limit, hasMore}`。 ### 10.6 A5 冒烟测试脚本 `tools/mcp_smoke.ps1`:只调只读工具(列表/详情/搜索 + 传输层负例),断言分页字段、注解、401/413、批量汇总。 ```powershell $env:YAMA_MCP_TOKEN = '' powershell -ExecutionPolicy Bypass -File tools\mcp_smoke.ps1 # 默认 6544(Release) powershell -ExecutionPolicy Bypass -File tools\mcp_smoke.ps1 -Base http://127.0.0.1:6545/mcp ``` token 只从 `-Token` / env 读取,不落仓库、不打印;无在线主机时加 `-SkipHost`。退出码 0/1,可接 CI。 ### 10.7 明确不做的两项 - `get_clipboard`:剪贴板常含口令/令牌/私钥,属"读即泄密",且客户端没有"只读不覆盖"的现成链路;已有 `remote_clipboard` 覆盖写。需要时用 `get_screenshot` + 人工确认。 - `close_window`:`operate_window` 的 `close` 动作已覆盖(同一 `COMMAND_WINDOW_CONTROL` 链路),不重复造工具。 ### 10.8 D 批:拒绝也入审计 动机:策略拒绝(只读模式、`Mcp*` 开关关闭,以及老客户端 V2 这类能力缺失)返回 `-32006`;平台/能力位不匹配的多数返回 `-32005`。此前审计里只有 `CALL_FAIL`——和「参数错」「主机离线」「超时」混在一起,事后分不清「没人调过」和「被策略拦下」。 - 实现放在 `tools/call` 的统一出口(`CMcpServer` 的 HTTP 处理器),不在 24 个 `-32006` 分支里逐个埋点:成功解析响应体后多取 `error.code` / `error.message`,`code == -32006` 就追加一条 ``` <时间> CALL_DENIED ip=<来源> tool=<工具名> reason=<固定英文原因> ``` 同一调用仍会留下原有的 `CALL_FAIL` 行,所以 `CALL_FAIL` 的统计口径不变。 - `reason` 全部是各分支写死的英文句子(如 `File transfer is disabled: requires McpFileTransfer=1`),不含调用参数或用户输入,落盘安全;审计依旧不记录 token、参数或返回正文。 - 其他错误码(`-32602` 参数、`-32002` 主机离线、`-32001` 超时等)不额外记事件,靠 `CALL_FAIL` 行即可。 - 验证(Debug 实例):把 `McpFileTransfer` 临时置 0 重启后调 `download_file`,审计立刻出现 `CALL_FAIL ... tool=download_file ms=1 bytes=114` 紧跟 `CALL_DENIED ... reason=File transfer is disabled: requires McpFileTransfer=1`;恢复 `McpFileTransfer=1` 重启后同一调用恢复 `CALL_OK` 且无 `CALL_DENIED`。冒烟脚本 20/20 通过(未指定 `-SearchPath` 时跳过 2 个搜索用例)。 --- ## 11. 增补(C 批:读侧增强,不改客户端) ### 11.1 C1 `get_audit_log` 分页与过滤 改动前每次调用都返回镜像里的全部条目(环形缓冲上限 1000 条),调用方没法只看关心的部分,日志一多就会把工具返回值撑大。 - 新增入参:`type`(类型列子串,不区分大小写,如 `MCP` 能匹配 `MCP命令执行`)、`keyword`(正文子串,不区分大小写)、`limit` / `offset`(沿用统一分页,默认 100、上限 1000)。 - 过滤在分页之前生效:`total` 是命中条数、`totalAll` 是镜像里的全部条数;`hasMore` 针对命中的条目。摘要会补一句「过滤前共 N 条」,方便判断是不是过滤写错了。 - 读取仍在 `m_cs` 临界区内完成(UI 线程会并发写入),过滤循环里先做 GBK→UTF-8 转换再比对,避免拿两种编码互相比。 - outputSchema 补 `total/totalAll/offset/limit/hasMore`(与其它列表工具一致)。 - 注意 `get_audit_log` 读的是**主界面消息镜像**,不是 `logs\mcp_audit.log`;两者的条目内容和保留策略都不同(前者是 1000 条环形缓冲,后者是 5 MB 文件滚动)。 - 验证(Debug 实例):`limit=2` 两页分别返回第 1-2 / 3-4 条且 `hasMore=true`,`offset=999` 返回「offset 超出范围」;`type=mcp` 命中 `MCP命令执行`(大小写不敏感)、`type=提示` 命中「使用提示 / 提示信息」、`keyword=监听` 命中「监听端口: 6543成功」;冒烟脚本 23/23 通过(新增分页字段、条数上限、过滤未命中 3 项断言)。 ### 11.2 C2 新工具 `get_server_status` 排查「改动到底生效没有」「为什么某个工具被拒」时,原先只能靠 `list_online_hosts` 加 `get_audit_log` 侧面推断;现在有一个服务端自身的状态快照。纯内存、只读、不建子连接。 返回(`structuredContent` 顶层,与 outputSchema 字段一一对应;早期版本曾多包一层 `status`,已修): | 字段 | 含义 | |---|---| | `app_name` / `version` | 品牌名与 `BRAND_VERSION`(当前 1.4.1) | | `exe_build_time` | exe 文件的最后写入时间=链接时间(比 `__DATE__`/`__TIME__` 可靠,后者是编译单个 .cpp 的时间) | | `uptime_sec` | 进程已运行秒数(`GetProcessTimes` 的创建时间起算,不是开机时间,也不受 MCP 启停影响) | | `bind` / `port` | MCP 实际监听的地址与端口(`Start` 时记录,非从配置回读) | | `switches` | `readonly` / `terminal` / `remote_control` / `file_transfer` / `manage` / `machine` / `machine_dangerous` / `keylog` / `chat` | | `hosts` | `online` / `offline` 台数(与 `list_all_hosts` 同源) | | `sessions` | `pending`(一次性/管理/键盘记录挂起) / `terminal` / `remote_control` / `file_transfer` / `chat` 在飞会话数 | | `blocked_auth_ips` | 当前处于鉴权封禁期的来源 IP 数 | - **不返回** token、`McpCmdWhitelist` 内容或任何配置原文;`switches` 只报布尔值。 - `sessions` 各项各取各自的锁、取完即放,是「大致同一时刻」的估算值,不能当一致性快照用。 - 工具注解登记为只读 + 非破坏性 + 幂等 + 不触达外部主机;`tools/list` 总数变为 53。 - 验证(Debug 实例):返回 `Yama v1.4.1,已运行 17 秒,监听 127.0.0.1:6545;在线主机 1 台、离线 3160 台`;`terminal_open` 期间 `sessions.terminal=1`、`terminal_close` 后回到 0;冒烟脚本 26/26 通过(新增 3 项:正常返回、版本/端口/开关齐全、不含 token)。 ### 11.3 C3 主机列表过滤:`list_online_hosts` / `list_all_hosts` 这两个工具原先只有分页,想找「某个分组」「某个平台」的主机只能翻页或改用 `search_hosts`(后者不支持 `client_type`,且对在线/离线的取舍规则不同)。 - 新增三个可选入参(两个工具共用同一套实现):`group` / `os` / `client_type`,均为子串匹配、ASCII 不区分大小写、AND 组合,口径与 `search_hosts` 一致。 - 过滤在分页之前生效:`total` 为命中台数、`totalAll` 为过滤前总数(`list_online_hosts` 是全部在线数,`list_all_hosts` 是主机库总数);摘要改用「共 N 台主机匹配」并补一句过滤前规模,写错条件时一眼能看出来。 - `list_all_hosts` 摘要里的在线/离线拆分也按命中条目统计。 - **离线主机没有 `clientType`**(历史记录里不存这个字段),所以带 `client_type` 条件时离线主机不会命中——按平台筛历史主机用 `os`。 - 验证(Debug 实例):`client_type=exe` 命中 1 台(`EXE`/`os=Windows 11`),`client_type=lnx` 命中 0 台但 `totalAll` 仍为 1;`list_all_hosts` 带 `group=default` 命中 3161 台并正确拆分在线 1 / 离线 3160,`os=zzz` 命中 0 台;冒烟脚本 28/28 通过(新增过滤未命中、totalAll 不变 2 项断言)。 ### 11.4 C4 `search_file` 结果侧过滤 `search_file` 的搜索条件(根目录 + 通配模式)由客户端执行,改不动;但把匹配项拿回服务端后可以再筛一遍,省掉 AI 端逐条比对。 - 新增四个可选入参,**都在服务端对已收集的匹配项做过滤**,不减少客户端侧搜索耗时: - `min_size` / `max_size`:字节数,整数,闭区间;负数或非数字返回 `-32602`;两者都给出且 `min_size > max_size` 返回 `-32602`。 - `modified_after`:接受 `YYYY-MM-DD`(当天 00:00:00 之后)或 `YYYY-MM-DD HH:MM:SS`;格式不符返回 `-32602`。客户端返回的 `modified` 是定宽 `"YYYY-MM-DD HH:MM:SS"`,可直接字典序比较,所以两种写法都合法(`"2026-01-01" <= "2026-01-01 08:00:00"`)。 - `name_only`:布尔,命中项只保留 `path` / `name` 两个字段,适合只要文件清单时省 token。 - 过滤在分页之前:`total` 为命中条数、`totalAll` 为过滤前条数;摘要补一句「过滤前共 N 条(大小/修改时间/精简字段过滤在服务端进行,不减少客户端搜索耗时)」。 - 过滤只看服务端已收到的条目,所以仍受 `max_results` / `timeout_ms` 截断:客户端没搜完时,过滤结果也是部分的(`truncated` / `finished` 字段照旧反映这一点)。 - 验证(Debug 实例,根目录 `C:\Windows\Fonts`、`*.ttf`):基线 255 条;`min_size=1000000` → 39 条且 `totalAll=255`;`name_only=true` 每条只有 `path`/`name`;`modified_after=2026-01-01` → 165 条、`2026-06-03 00:00:00` → 130 条、`2027-01-01` → 0 条;`min_size=-5`、`min_size=10 & max_size=5`、`modified_after=2026/01/01`、`modified_after=2026-01-01 12:00` 均返回预期的 `-32602`。冒烟脚本 33/33 通过(新增 3 项:`min_size` 过滤后 `totalAll` 不变、`name_only` 精简字段、非法 `modified_after` 返回 `-32602`;后三项需带 `-SearchPath` 才执行)。 ## 12. 错误码速查(E 批:冒烟与文档) 工具的失败分三类,AI 端应按 `code` 决定下一步,而不是读 `message` 文本。`message` 是给人看的英文说明,随实现变化,不作为契约。 | code | 含义 | 典型触发 | 建议动作 | |---|---|---|---| | `-32700` | Parse error | 请求体不是合法 JSON | 修正客户端序列化 | | `-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 / 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*` 开关关闭;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`)确认目标存在 | | `-32010` | Access denied | 目标存在但权限不足(win32 `5`):非提权客户端的服务枚举(`OpenSCManager`)、受保护目录(如 `System Volume Information`)、受保护注册表键(如 `HKLM\SAM`) | **不要重试**:需客户端提权(管理员运行)或换目标 | | `-32011` | Destination write failed | 文件传输的**目标端**已收到数据但写盘失败:`copy_files_c2c` / `upload_file` 的目标主机回了回执且 `status != 0`(`message` 带 status、首个 errno、实收文件数) | **不要原样重试**:按文案判断(errno 13/1→权限、2→路径不存在、28→磁盘满),先修目标端目录/权限 | | `-32800` | Request cancelled | 客户端取消了这次调用:`notifications/cancelled`、`mcp_cancel_session` 或 SSE 流断开(检测到断开会置同一个取消位)。工具在 ≤1s 内退出等待并走既有的超时清理路径,主机占用已释放 | 不是主机故障,可直接重试;终止类命令可能已经执行,重试前先读一次现状 | - **命令超时会销毁持久会话**(`terminal_exec`):等服务端收集到哨兵超时返回 `-32001`,会话随即被销毁并留 600 秒「墓碑」;对同一 `session_id` 再发命令返回 `-32002`,文案明确写 `Terminal session was destroyed after this command timed out (waited N ms); call terminal_open again`,与「id 写错」(`Terminal session not found: `)区分开。 - **新客户端把失败改成结构化回报**(`TOKEN_SERVICE_ERROR=170` / `TOKEN_FILE_LIST_ERROR=171` / `TOKEN_REG_ERROR=172` / `TOKEN_DOWNLOAD_ERROR=173`,布局 `[token:1][win32 码:4 LE]`):`list_services`(未提权)、`list_files`/`list_registry`(路径/键不存在或拒绝访问)、`download_file`(远端路径全部不存在)都在客户端侧就失败并立即回报,服务端转译成 `-32009`/`-32010`,**亚秒级返回**,不再靠超时猜。老客户端不发这些包,成功路径报文一律不变,因此老客户端/老服务端的行为与改造前完全一致(老服务端把未知 token 走 `default` 丢弃)。 - **工具放弃后的「迟到首包」一律吸收,不会弹 MFC 窗口**:文件/服务/注册表/进程/日志/终端这几族的子连接都是「建成即发首包」。工具超时清理挂起后,客户端可能才把首包发上来,此时没有挂起会话,`MessageHandle` 只能把它当成人手点击,于是弹出文件管理器/服务管理器/注册表/进程管理器/日志/终端窗口(构造超时场景时实测出现过文件管理器窗口)。现在各等待函数在**放弃分支**登记「设备 → 该工具的首包 token」(`CMcpServer::MarkLateFirstPacketForTool`),包到达时 `TakeToolFirstPacket` 一次性吸收并关子连接:`list_files`/`download_file`/`upload_file`/`search_file` → `TOKEN_DRIVE_LIST`;`list_services`/`control_service` → `TOKEN_SERVERLIST`;`list_registry` → `TOKEN_REGEDIT`;`list_processes`/`kill_process` → `TOKEN_PSLIST`;`list_windows`/`operate_window` → `TOKEN_WSLIST`;`get_client_log` → `TOKEN_REPORT_LOG`;`get_activity_history` → `TOKEN_REPORT_ACTIVITY`(主连接,只丢包不关连接);`exec_command`/`terminal_open` → `TOKEN_SHELL_START` + `TOKEN_TERMINAL_START`。成功路径不登记,命中即消费,标记 5 分钟后过期。**已知代价**:同一主机在工具超时后 5 分钟内手动点开对应窗口,可能被这枚标记吞掉一次(再点即可)——比误弹窗口更可接受。 - **MCP 工具在飞时不弹客户端的老式提示框**:新客户端在失败分支同时发结构化 token 和老的 `ClientMsg`(只为兼容老服务端),后者会 `PostMessageA(WM_SHOWERRORMSG)` 在服务端 UI 上弹框。`TOKEN_CLIENT_MSG` 分支现在发现该设备有挂起请求/文件传输时就只记日志不弹框。实测 `list_services`(未提权)时客户端子连接已被服务端关掉,`ClientMsg` 根本发不出来,这条属兜底。 - **`download_file` 有停滞看门狗兜底**:60 秒没收到任何数据即失败,返回 `-32001` 且文案带 `File transfer stalled: no data received for 60s ...`。新客户端的 `TOKEN_DOWNLOAD_ERROR` 让这条路基本不再触发,看门狗只用来兜住「客户端卡住/老客户端」。 - `-32006` 会额外在审计日志里记一条 `CALL_DENIED`(§10.8),其余错误只体现在 `CALL_FAIL` 行。 - 批量调用(带 `ids[]`)**整体不报错**:每个 id 的结果单独带 `error`,顶层用 `succeeded` / `failed` / `skipped` 汇总;只有整批请求本身非法(超过 50 个 id、写操作传 `ids`)才返回顶层 `-32602`。 - 冒烟脚本 `tools/mcp_smoke.ps1` 覆盖了上表的可复现项:`-32601`(未知 method)、`-32602`(未知工具/缺参数/51 个 id)、`-32002`(不存在的主机)、`-32006`(任一开关关闭时自动挑一个关着的功能验证,并断言审计里出现 `CALL_DENIED`;全部开启时跳过)、`-32009`(新客户端的 `list_files`/`list_registry`/`download_file` 不存在路径负例)。其余码由各批次的功能验证覆盖(`-32001`/`-32003` 等需要构造竞态或超时,不进冒烟)。 - 本次验证(Debug 实例):冒烟 **40/40 通过**(原 37 项 + 3 条 `-32009` 负例);`-32010` 由 `list_services`(未提权客户端,win32=5)、`list_files "C:\System Volume Information"`、`list_registry "HKLM\SAM\SAM\Domains\Account"` 三条实测覆盖。 ### 12.1 命令哨兵与输出清洗(测试报告 P1/P3/P4 的修复) `exec_command` 与 `terminal_exec` 都靠哨兵判断「命令已执行完、退出码是多少」。哨兵有三种形态: | 客户端 | 下发内容 | 退出码 | |---|---|---| | POSIX PTY(Linux,`RES_CLIENT_TYPE=LNX`) | 第一行 `PS1=`;第二行 ``;第三行 `echo __MCP_DONE___$?` | 命令的真实退出码 | | ConPTY(`is_pty=true`,新版 Windows 客户端) | 第一行 `@echo off & `;第二行单独 `echo __MCP_DONE___%errorlevel%` | 命令的真实退出码 | | 老 ShellManager 管道(`is_pty=false`) | 单行 ` 2>&1 && echo __MCP_DONE___0 || echo __MCP_DONE___1` | 仅 0 / 非 0 | POSIX 形态与 Windows 的差别: - **不能用 `@echo off & ` / `%errorlevel%`**:Linux 的 `bash -i` 把它们当字面量,哨兵永远不会出现,必然超时。 - **先发一行 `PS1=`**:交互式 bash 每读一行都打印提示符(`user@host:cwd$`),提示符会混进 stdout(Windows ConPTY 不会)。清空 `PS1` 后提示符消失。这一行的回显排在下发的命令行回显之前,会被「从缓冲区开头删到命令行回显结束」那一步一并切掉,不进入返回文本。 - **`$?` 是上一行的退出码**:`PS1=` 与命令各占一行,哨兵只取命令那一行的状态,未被 `PS1=` 干扰。 **为什么 PTY 要分两行下发**:`rem hello`、`cmd /c exit 0`、`if`、`for` 这类「吞行」命令会把同一行里的 `&& echo 哨兵` 一起吞掉(`rem`/`cmd /c` 把行内剩余文本当作自己的参数),哨兵永不出现,于是必然超时并销毁会话。哨兵独立成行后由 shell 自己执行,不再受命令行影响。老客户端只能维持单行形态:`client/ShellManager.cpp` 按「写入字节数」跳过回显,多写一行会吃掉上一行的输出。 **为什么用 `%errorlevel%`**:ConPTY 会把输入整行回显进输出流(80 列会折行)。回显文本里是字面 `%errorlevel%` 而不是数字,而 `FindSentinel` 只认「标记 + 数字」,折行回显再也不可能被误判成哨兵(评审 P3:`ver` 曾因回显里的 `__1` 被判成 `exit_code=1`),同时还能拿到真实退出码(如 `nosuchcmd` 的 9009)。 **输出清洗顺序**:剥 ANSI(OSC 序列以 `ESC\` 结尾时两字节一起吞,否则会残留 `\`)→ CRLF 归一 → 从缓冲区开头删到「我们下发的命令行回显」结束(顺带清掉 shell 启动画面与提示符)→ 删哨兵行回显 → **按 nonce 擦掉残留的哨兵文本** → 去首尾空行。最后一步是必需的:ConPTY 送回来的是**屏幕渲染流**(带光标移动/擦除序列),剥掉序列后同一行可能重复出现,哨兵会留下副本(实测不擦时 `rem hello` 只剩哨兵、`cmd /c echo abc` 成了 `abc__MCP_DONE_x__0`)。nonce 每条命令随机生成,命令的真实输出不可能包含它,所以按 nonce 擦除不会误伤业务输出。 **已知边界**:屏幕渲染流里「光标下移空行」会被剥成紧邻行(例如 `ping` 的统计块会贴在最后一条回复后面),不影响语义。 **PTY 会话允许管道与串联**(2026-11-10):哨兵独立成行后,命令行里的 `|`、`&&`、`||`(POSIX 还允许 `;`)都由 shell 正常解析,不会再吞掉哨兵,因此 `is_pty=true` 的会话不再拒绝这些字符,退出码取整条管道/串联的结果。被拒绝的只剩两类: - **老非 PTY 客户端**(单行 ` 2>&1 && echo 哨兵 || echo 哨兵`):`&`/`|` 仍会破坏单行哨兵语义,维持 `-32012` 并提示「拆成多条调用或升级客户端」。 - **POSIX 会话里的裸后台 `&`**:`cmd & echo 哨兵` 会让哨兵在命令真正完成前执行,stdout 与退出码都不可信;`&&`、`&>`、`>&`/`2>&1` 不受影响(判别器 `HasPosixBackgroundAmpersand` 跳过引号与转义,只拦裸后台符;`$((...))`、`${...}` 展开里的 `&` 会被保守拒绝,误报只会让调用方改写命令)。 判定发生在 `BeginTermCommand` 之前:`PeekTermSession` 只读查询会话是否存在、是否 PTY,不置 `busy`、不改状态,因此不支持的语法在碰会话之前就被拒绝。 ## 13. 增补(2026-10-26:MCP HTTPS / native TLS) ### 13.1 目标与取舍 公网 MCP 客户端(Claude Desktop、WorkBuddy 等)多数只接受 `https://` 端点,而 MCP 一直是明文 `httplib`。三条路里选了第三条: | 方案 | 结论 | |---|---| | 在 vps 上用 nginx 反代加 TLS | 不行:vps 的 80/443/6544 都由 frps 持有,nginx 只在 8080,且反代会让 token 以明文经过 vps | | 引入 OpenSSL / cpp-httplib 的 `CPPHTTPLIB_OPENSSL_SUPPORT` | 新增第三方依赖与证书/私钥加载路径,仓库已有 Schannel 实现 | | **复用仓库既有的 Schannel 入站实现,在 MCP 端口上终结 TLS** | ✅ 零新依赖,`ServerTlsSession`/`ServerTlsIdentity` 已在设备端口跑通 | ### 13.2 结构:同端口嗅探 + 明文直通 ``` 客户端 ──TLS──▶ [McpTlsProxy] :McpPort ──明文──▶ httplib 127.0.0.1:McpInternalPort 客户端 ──明文─▶ │ 0x16 0x03 ? (只绑回环,不对外) ``` - `McpTlsProxy`(`McpTlsProxy.h/.cpp`)在 `McpBind:McpPort` 上监听,首包用 `MSG_PEEK` 判 TLS(首字节 `0x16` 且次字节 `0x03`,与设备端口 §5.2 同一套路):TLS 走 `ServerTlsSession::HandshakeWithCred` + `Decrypt`/`Encrypt`,否则按字节原样转发。 - 因此**同一端口两种用法并存**:本机既有的 `http://127.0.0.1:6544/mcp` 不用改,远端可以用 `https://host:6544/mcp`。 - `McpHttps=0` 时完全不启动前端,行为与改造前一致(httplib 直接监听 `McpBind:McpPort`)。 ### 13.3 身份:第二份证书,独立 CNG 键名 `ServerTlsLoadIdentityFromPem(cert, key, L"YamaMcpTlsKey", id)` 构造进程内第二份入站身份,与设备端口的 `ServerTlsIdentity`(`YamaServerTlsKey`、通常自签 `CN=localhost`)并存:证书/私钥各读各的,持久化私钥用不同键名,互不覆盖。`HandshakeWithCred` 是新增的重载,设备端口仍用 `Handshake`(同一份逻辑,只是取凭据的方式不同)。 **fail-closed**:证书/私钥读不出来、CNG 导入失败、端口被占任一项失败,`McpServer::Start` 会把 httplib 一起停掉并返回 false——绝不允许「以为在跑 HTTPS、其实没在监听」。 ### 13.4 实测(Debug 实例,自签证书) | 场景 | 结果 | |---|---| | `https://127.0.0.1:6545/mcp`(`--cacert server.crt`)无 token | `401`,证书校验通过 | | 同一端口 `http://127.0.0.1:6545/mcp` 无 token | `401`(明文直通未受影响) | | TLS + token:`initialize` / `tools/list` / `tools/call get_server_status` | 正常,53 个工具 | | 同一条 TLS 连接上连发两个请求(keep-alive) | 两次都 `200`,复用连接 | | 错误 token | `401`(回环来源的鉴权封禁豁免仍生效) | | 内部端口 `6546` | 只监听 `127.0.0.1` | | `McpCertPath` 指向不存在的文件后重启 | MCP 整体不启动,无任何监听(fail-closed) | | 公共 CA 的 ECDSA 证书(Let's Encrypt P-256 fullchain + PKCS#8 私钥) | 身份加载成功,TLS 无 token `401`、带 token `initialize`/`tools/list` 正常(53 工具) | | 本地 CA 三级链(叶 + 中间,中间证书不在系统库) | 服务端下发 2 张证书,`openssl s_client -CAfile root.crt` 得 `Verify return code: 0` | | 设备端口 `6543` TLS(回归) | 握手正常 | | `McpHttps` 删除后重启(回归) | 明文明监听,无内部端口 | ### 13.5 Schannel 的一个坑(已修在共用层) `ServerTlsSession` 原先把「首次收到的字节」直接喂给 `AcceptSecurityContext`。如果这批字节只是**半条 ClientHello**,Schannel 会先建出一个坏上下文,补齐后再送返回 `SEC_E_UNKNOWN_CREDENTIALS (0x80090301)`,握手必失败。设备端口因为累积了整包才分类、且客户端 ClientHello 通常一次到齐,一直没暴露;MCP 前端按 8 字节嗅探后接手,稳定触发。 现在 `HandshakeWithCred` 在首次 ASC 之前先凑齐**一整条 TLS 记录**(5 字节头 + 负载,上限 18432 字节,首字节非 `0x16` 或缺字节超时则 fail-closed),调用方给多少字节都行。这也顺带修好了设备端口在「ClientHello 被 TCP 分片」时的同类隐患。 ### 13.6 部署公网证书 1. 把公共 CA 签发的证书链与私钥(PKCS#8)放到本机,例如 `Bin\certs\mcp-fullchain.pem` / `Bin\certs\mcp-key.pem`。证书支持 RSA 与 ECDSA(P-256/P-384/P-521),可以写成「叶证书 + 中间证书」的 fullchain(见 13.8)。 2. 「扩展 → MCP设置」勾选「启用 HTTPS」,在两行里填/浏览证书与私钥(也可直接改 ini:`McpHttps=1`、`McpCertPath=<证书>`、`McpKeyPath=<私钥>`),保存后重启 YAMA。注意「端口」填的是对外端口,httplib 自动退到 `127.0.0.1:McpPort+1`。 3. frp 的 `YAMA-MCP-*` 映射指向本机 `McpPort` 不变——TLS 在 YAMA 内终结,vps 只转发密文。 4. 证书续期后需重新拷贝 + 重启 YAMA(当前不做热加载)。 客户端配置形如: ```json { "mcpServers": { "yama": { "type": "http", "url": "https://web.just-do-it.icu:6544/mcp", "headers": { "Authorization": "Bearer " } } } } ``` ### 13.7 已知限制 - **按 IP 的鉴权封禁对远端不生效**:`IsAuthBlocked` 按来源 IP 计数,而经 frp 或本前端转发的请求来源都是 `127.0.0.1`,命中既有的「代理来源豁免」。因此远端的暴力尝试不受「10 次失败 / 60 秒 → 封 15 分钟」约束,真正的防线是 token 熵(32 hex ≈ 128 bit)与审计日志里的 `AUTH_FAIL` 记录。经 frp 暴露时改造前就已如此;但若改造前是把 `McpPort` 直接绑在公网地址(不经 frp),远端 IP 原本会被封禁,开启本前端后一律变成环回、不再封禁——按部署方式评估这一差异。要补需在本前端把真实来源 IP 以受信头注入 httplib 请求,属于后续工作。 - 证书不热加载:换/续证书需重启 YAMA。 - 只支持 HTTP/1.1(与 httplib 一致),不做 ALPN h2。 ### 13.8 证书类型与证书链(2026-10-26 补齐) 早期实现只认 RSA:私钥一律按 `BCRYPT_RSAFULLPRIVATE_BLOB` 导出后再写入持久化键,遇到 ECDSA 证书(Let's Encrypt 自 2024 年起默认签发 P-256)会在导出处拿 `NTE_BAD_TYPE (0x8009000a)` 并报错退出。现在按**证书公钥类型**分两路落盘(`ServerTlsSession.cpp` 的 `BuildIdentity`): | 证书公钥 | 落盘方式 | |---|---| | RSA | 导入 PKCS#8 为临时键 → 导出 `BCRYPT_RSAFULLPRIVATE_BLOB` → `NCryptCreatePersistedKey` + `NCryptSetProperty` + `NCryptFinalizeKey` | | ECDSA(P-256/P-384/P-521) | 导入 PKCS#8 时在参数表里给出键名(`NCRYPTBUFFER_PKCS_KEY_NAME`),MS Software KSP 直接持久化 | ECDSA 这条是 MS Software KSP 唯一可行的一条,其余几条均已实测不通:`NCryptCreatePersistedKey` 后写 EC 私钥 BLOB,`SetProperty` 返回 0 但 `Finalize` 给 `NTE_INVALID_PARAMETER (0x80090027)`;导入后再 `NCryptSetProperty(NCRYPT_NAME_PROPERTY)` 给 `NTE_NOT_SUPPORTED (0x80090029)`(不带键名即匿名临时键,Schannel 用不上);把临时键句柄经 `CERT_KEY_CONTEXT_PROP_ID` 挂到证书上,Schannel 报 `SEC_E_NO_CREDENTIALS (0x8009030e)`。`NCRYPTBUFFER_PKCS_KEY_NAME` 的值必须**含结尾 NUL**,少了同样报 0x80090027。曲线只支持具名 P-256/P-384/P-521,显式参数形式的曲线会带明确报错退出。 **证书链**:Schannel 的握手在进程外完成,建链时只查系统证书库——fullchain 里的中间证书塞进叶证书自带的内存库或 `paCred` 数组都不会被下发(实测只发叶证书,缺中间证书的客户端建链失败)。因此加载身份时把 fullchain 第 2 张起的证书补进「当前用户\中间证书颁发机构」库(`Cert:\CurrentUser\CA`,已在库中则跳过;.NET 的 `SslStreamCertificateContext` 也是这么做的),Schannel 建好链后随握手下发。证书文件因此可以、也建议写成「叶证书 + 中间证书」的 fullchain(Let's Encrypt 的 `fullchain.pem` 即如此)。副作用:进程所在账户的 CA 库里会多出这些中间证书(公开信息,留在库里无害)。 ## 14. 增补(2026-10-26:结果外露 —— `content` 同时携带结构化 JSON) ### 14.1 问题 改造前,列表/查询类工具的 `content` 只有一句可读摘要(“共 1 台主机匹配。”),真正的载荷(`hosts[]`、`processes[]`、`files[]`、`session_id`……)只在 `structuredContent` 里。MCP 规范(Tools → Structured Content)明确建议:**返回 `structuredContent` 的工具应同时把序列化后的 JSON 放进一个 `TextContent` 块**,正是为了这种只把 `content` 交给模型的客户端。实测 WorkBuddy 就属这类:它把 `search_hosts` 的结果格式化成“共 1 台主机匹配”交给模型,`id` 完全不可见,于是后续 `get_host_detail` / `exec_command` / 终端 / 远程控制全部无从下手(用户侧表现为模型去猜 1–3100 的 id,而主机 id 是 64 位雪花值,如 `986530101822679521`,猜测不可能命中)。 ### 14.2 实现 - `McpInternal::BuildResult` 统一收口:结果里 `structuredContent` 为非空对象/数组时,追加一个 `{type:"text", text:"<紧凑JSON>"}` 块到 `content` 末尾。所有工具(含 `McpMachine.cpp` / `McpChat.cpp` 的 `BuildStructuredResult` 漏斗)自动生效,新增工具无需额外处理;空 `{}`(`remote_mouse` 这类动作结果)不追加。 - 正文已经承载同一份载荷的工具用 `SetStructuredTextPayload(result, payload)` 只外露差异部分,避免同一内容在上下文里出现两三次: | 工具 | 外露的文本块 | |---|---| | `exec_command` / `terminal_exec` | `{"exit_code":N}`(stdout 已在正文里) | | `get_keylog` | `id` / `duration_ms` / `bytes` / `lineCount` / `truncated`(行内容已在正文里,最多 16 KB) | | `get_activity_history` | `{"records":[…]}`(`activityHistory` 与 `records` 是同一份数据的两种形态) | | `host_get_hosts_file` | `lines` + 元数据(不再重复 `content` 原文) | - 控制键以 `$structuredTextPayload` 成员的形式挂在 result 上,`BuildResult` 消费后立即 `removeMember`,不会出现在响应里。 - 列表类工具本就有 `limit/offset` 分页,补出来的 JSON 与 `structuredContent` 同量级,不会失控。 ### 14.3 验证 Debug 实例(`Bin\Yama_x64d.exe`,临时端口)实测:`list_all_hosts` 的 `content[1]` 含完整主机 JSON(`id` / `ip` / `last_seen` …),`search_hosts` 空结果时是 `{"hasMore":false,"hosts":[],…}`;`content[0]` 的既有摘要文案一字未改。`get_server_status` 的 `content[1]` 是状态对象本身(与 outputSchema 的顶层字段一致;早期版本多包了一层 `status`,已修)。 ### 14.4 影响面 - 响应体积:列表类工具约翻倍(分页上限内),执行类工具只多一个退出码字段。 - 既有断言不受影响:摘要仍在 `content[0]`,内部批量工具(`ids` 批量调用)仍只读 `content[0].text` 并另取 `structuredContent`。 ## 15. 增补(2026-10-26:`copy_files_c2c` 客户端间直传) 第 54 个工具:把文件从一台客户端**直接**发到另一台,服务端只做包中继,不落盘。复用 V2 文件传输的 C2C 通道(`FileChunkPacketV2.dstClientID != 0`),新增协议号 `COMMAND_C2C_SEND_FILES=174`(服务端给源端下路径清单)、`TOKEN_C2C_SEND_RESULT=175`(源端回传发送结果),以及能力位 `CLIENT_CAP_C2C_PATHS=0x0008`(老客户端因此被提前拒绝并提示升级)。 - 工具契约:`src_id` / `dst_id` / `paths[]` / `dst_dir` / 可选 `timeout_ms`;返回 `transfer_id` / `file_count` / `total_bytes` / `receiver_ack`。 - 开关:`McpFileTransfer=1 && McpReadonly=0`(会写远程),注解登记为破坏性 + 非只读,`McpInternal` 的 gating 表同步。 - 源端必须是 Windows 客户端(`-32005`);目标端可以是 Windows / Linux / macOS(2026-10-27 起)。POSIX 目标给绝对 POSIX `dst_dir`(`/tmp/recv`),服务端在建会话前校验形态,非法 `-32602`。 - `receiver_ack`:Linux 目标端落盘后会回一包 `TOKEN_C2C_RECV_RESULT=176`(能力位 `CLIENT_CAP_C2C_RECV_ACK=0x0010`),`true` 表示目标端确认写入、`total_bytes` 是实收值;写入失败统一 `-32011`(带 status/errno)。Windows/macOS 目标端不回执,仍为 `false`,需 `list_files` 复核。 - 实施中一个坑:服务端既有的 C2C 中继分支会在源端子连接上挂进度对话框,而 `NotifyProc` 对挂了 `hDlg` 的连接会把后续包交给对话框——源端最后那包结果就被当 V1 文件块吃掉,工具只能超时。现按「该 host 是否有 MCP 的 C2C 会话」跳过对话框,MFC 手动 C2C 不变。 - 协议细节、落盘路径语义(`dst_dir` + 相对公共父目录,Windows 与 POSIX 两种目标端)、回执与错误码映射(含 `-32011`)、限制与实测见 [Mcp_FileTransfer_Design.md](./Mcp_FileTransfer_Design.md) §14。 ## 16. 增补(2026-10-27:`download_file` / `upload_file` 支持 Linux/macOS 主机) 此前两个工具把 LNX/MAC 目标端直接拒掉(`-32005`)。现在放开,改动集中在服务端的路径门禁与 POSIX 接收端: - **`upload_file` 不需要客户端新指令**:Linux/macOS 的文件接收走 `common/FileTransferV2.h`,`dstClientID != 0` 的包按 C2C 语义落盘,目录由包里的 name 派生。服务端按 `RES_CLIENT_TYPE` 校验 `remote_dir`:POSIX 目标必须是绝对 `/…`、不含 `\`、不含 `..` 段(`-32602`);Windows 目标行为不变。 - **`download_file`**:POSIX 文件管理器(`common/FileManager.h`)补齐两块——每个文件末尾发 `FileCompletePacketV2`(流式 SHA-256,新增 `common/sha256_posix.h`;读失败/截断不发,不谎报校验通过),以及下载失败时回 `TOKEN_DOWNLOAD_ERROR`(errno→win32,服务端转成 `-32009`/`-32010`,不用等停滞看门狗)。 - **`upload_file` 的 `receiver_ack`**:Linux 目标端会回 `TOKEN_C2C_RECV_RESULT=176`,服务端在发送完成后等 ≤5 s,`true` 表示已确认写入;回执报错 `-32011`;声明会回执却不回(且传输含字节)`-32001`。Windows/macOS 目标端仍恒为 `false`。 - **空文件**:worker 对 0 字节文件只发完成包(无路径字段),POSIX 接收端无从建文件。服务端只对 POSIX 目标补一个长度 0 的末块,接收端据此建空文件;Windows 目标的空文件仍不落地(V2 协议既有边界,未改)。 - 顺带修掉一个下载完成判定的边界:条目顺序由客户端决定,目录可能排在文件之后(如空子目录),`OnFileChunkV2` 改为按 `filesDone + directoryCount >= totalFiles` 判完成,不再出现「文件全部收完还干等超时」。 - 协议细节、POSIX 路径规则、错误码新语义与实测(含 3 MB 二进制、中文名、空文件、空目录的 SHA-256 往返)见 [Mcp_FileTransfer_Design.md](./Mcp_FileTransfer_Design.md) §15。 ## 17. 增补(2026-10-27:档 1 工具支持 Linux 客户端) Linux 客户端(`LNX`)早已实现下面这些工具的**线上协议**,只是服务端按客户端类型一律拒绝。本次只放开服务端的判定,**不改 Linux 客户端、不加能力位**: | 工具 | 线上协议(已存在) | 服务端改动 | |---|---|---| | `kill_process` | 主连接 `COMMAND_SYSTEM` → 子连接 `TOKEN_PSLIST` → `COMMAND_KILLPROCESS` + PID 数组 → 刷新列表(`linux/SystemManager.h`,`kill(SIGKILL)`,忽略 `pid<=1`) | 只拒绝 `MAC`/`APK` | | `exec_command` | `COMMAND_SHELL` → `TOKEN_TERMINAL_START` → PTY(`common/PTYHandler.h`,`bash -i`) | 只拒绝 `MAC`;POSIX 白名单 / 元字符集 / 哨兵(§12.1) | | `terminal_open` / `terminal_exec` / `terminal_close` | 同上,`CMD_TERMINAL_RESIZE` + `COMMAND_NEXT` 启动读线程 | 只拒绝 `MAC`;`posix` 透传到哨兵与编码(UTF-8) | | `remote_open` / `remote_close` / `remote_mouse` / `remote_keyboard` / `remote_clipboard` | `COMMAND_SCREEN_SPY` → `TOKEN_BITMAPINFO` → `COMMAND_SCREEN_CONTROL` + `MSG64_LNX`(`linux/ScreenHandler.h`,XTest 注入);剪贴板 `COMMAND_SCREEN_SET_CLIPBOARD` | 只拒绝 `MAC`;输入事件改为**一条一包**(见下) | 要点: - **POSIX 默认白名单是独立的一份**(`kDefaultCmdWhitelistPosix`):同名的 POSIX 命令语义与 Windows 不同(`find` 能 `-exec`、`hostname` 能改名、`sort -o` 能写文件),因此只收「参数也基本只读」的命令。`env` **刻意不收**——`env <程序>` 等于执行任意命令,会让白名单形同虚设。管理员显式配置 `McpCmdWhitelist` 时两种平台共用配置(配置者自负其责)。 - **元字符集按平台分开**:Linux 拒绝 `& | < > ;` 与反引号、`$(` `${` `!`(`!` 在交互式 bash 里触发历史展开);`^` 在 POSIX 里不是元字符,因此 `grep -v ^# /etc/hosts` 这类只读命令在 Linux 上可用,Windows 上仍按原规则拒绝。 - **输入事件一条一包**:协议允许 `[COMMAND_SCREEN_CONTROL][MSG64*N]` 批量,Windows 客户端(`CScreenManager::ProcessCommand`)也支持批量;但 `linux/ScreenHandler.h` 只处理包内第一条,批量会让 `key_press` 只按下不抬起(X11 自动重复)、`click` 只按下、`type` 只打首字符。服务端因此按消息拆包(`SendScreenCtrlEvents`),对 Windows 完全等价(它本来就一条一条处理),新老 Linux 客户端也都不用升级。 - **`remote_keyboard` 的 `type` 仍是 ASCII-only**:Linux 侧 `VKtoKeySym` 把 VK 映射为 keysym 后走 XTest,IME 组合输入做不到;非 ASCII 走 `remote_clipboard` + `Ctrl+V`(Linux 客户端把服务端下发的 GBK 转回 UTF-8 再调 `xclip`/`xsel`,需要 X11 桌面)。 - **限制**:纯 Wayland 会话无法抓屏/注入(要 X11 或 XWayland);多显示器仍按 §7.2 拒绝(Linux 客户端心跳里 `RES_RESOLUTION` 依赖 `xrandr`,没有 `xrandr` 的系统上报 `0:0*0`,按「无法判定」放行);`remote_*` 需要安装 `libX11` + `libXtst`,剪贴板需要 `xclip`/`xsel`。 - **验收**(Debug 实例 + WSL Ubuntu 24.04 客户端,WSLg `DISPLAY=:0`):`exec_command` 真实退出码(`ls` 不存在路径 → 2)、`-32007`/`-32008` 负例、`grep -v ^#` 放行、输出无提示符噪声;持久终端 `cd`/环境变量保持、`false` → 1、`;` 串联取末条、`close` 幂等;`kill_process` 杀死自己起的 `sleep` 且 `remaining` 为空、`pid 1` 被跳过;`remote_open` 返回 3840x1140、`remote_mouse` 归一化 (0.5,0.5) 落在 (1920,570)、`xev` 观测到按键/按钮成对、剪贴板中文往返 UTF-8 一致。Windows 客户端同批工具回归无变化。 ## 18. 增补(2026-10-29:修掉实测报告的三个 P0) `docs/Mcp_Test_Report_2026-10-29.md` 的 P0-1/P0-2/P0-3 有三个共同点:**inputSchema 与 outputSchema 不是同一份契约**,或者**输出体积没有上限**。三者都只改服务端(P0-3 的 Linux 半边另需客户端补一段)。 ### 18.1 批量只读的 outputSchema(P0-1) `tools/call` 带 `ids[]` 时走 `BuildBatchCall`,返回的是 `{tool, total, succeeded, failed, skipped, results[]}`;而每个工具声明的 `outputSchema` 只有单机形状。客户端按声明校验 `structuredContent`,于是**任何** `ids` 调用都以 `-32602: data must have required property 'host'` 失败——inputSchema 明写「支持 ids」, outputSchema 却把它判死,十余个只读工具的批量能力整条不可用。 修法:`McpInternal::ApplyBatchOutputSchema(tools)` 在 `tools/list` 的最后一步(与 `ApplyToolAnnotations` 并列)给 `IsBatchReadOnlyTool` 命中的工具把 `outputSchema` 改写成 `{type:object, anyOf:[单机形状, 批量形状]}`。放最后一步是为了让三个注册点 (本文件内联 / `McpMachine` / `McpChat`)一视同仁,新增工具只要进批量清单就自动生效。 `IsBatchReadOnlyTool` 也随之从 `McpServer.cpp` 移到 `McpInternal.cpp`——清单现在同时被 `tools/call`(入口判定)和 `tools/list`(补 schema)使用,两处必须共用一份。 批量形状里的 `results[].data` 只能声明成 `object`:它就是该工具单机的 `structuredContent`,字段随工具而定。 ### 18.2 `list_registry` 的根键分支(P0-2) `path` 为空时 `BuildRegistryRoots` 只回 `keys`,而 outputSchema 把 `values` 也列进了 `required`——于是文档写的**第一种用法**(省略 path 列根键)必然 `-32602`,AI 必须先猜一个 真实键路径才能进注册表。现在 `required` 只保留 `keys`,`values` 在根键分支不返回,并在 schema 里写明这一点;同时根键分支补上 `path: ""`,让两个分支返回同一组字段(`path` / `keys`),调用方不必按分支判断。 ### 18.3 `get_client_log` 的体积与平台(P0-3) 两个症状、两个原因: | 平台 | 症状 | 原因 | |---|---|---| | Windows | 返回 90,473 字符,超出客户端工具结果上限 | 快照是客户端 ring buffer 全量(最多 1000 行),工具没有 limit | | Linux/macOS | `-32001` 稳定超时 | 客户端**根本没有处理** `COMMAND_QUERY_LOG`(只有 Windows 的 `ClientLogManager` 有),服务端永远等不到 `TOKEN_REPORT_LOG` | 服务端:`get_client_log` 新增 `limit`(默认 200,上限 2000)与 `filter`(子串,ASCII 不区分大小写),**从末尾往前取**——排障看的是最后发生了什么,不是开机第一行。返回补 `lines_total` / `lines_matched` / `lines_returned` / `truncated`。除行数外还有 64 KB 字节预算:单行可能是超长的堆栈或报文转储,只按行数截断仍会撑爆结果;末尾一行自己就超 预算时回它的尾部并置 `truncated=true`。超时文案也改成可诊断的(点明「客户端版本可能 不支持日志上报」并给出两条替代路径),而不是一句 `Timeout waiting for client log`。 客户端:新增 `common/ClientLogHandler.h`(POSIX 版,与 Windows 的 `CClientLogManager` 对应),`linux/main.cpp` 与 `macos/main.mm` 在 `COMMAND_QUERY_LOG` 分支开子连接、首包发 `TOKEN_REPORT_LOG` + `Logger::DumpMemoryLogFrom(0)`。**必须走子连接**:服务端 `MessageHandle` 的 `TOKEN_REPORT_LOG` 分支取走首包后会 `CancelIO` 关掉这条连接,回在 主连接上就是把主连接关掉(客户端当场掉线)。 macOS 还有第二层问题,只影响日志内容,2026-11-14 修:处理器虽然接上了,但 `Logger` 的 ring 只能被 `Mprintf` 写入,而 macOS 的 `Mprintf` 当时直接走 `NSLog`/`fprintf(stderr)`, 从不经过 `Logger`——ring 恒为空,菜单和 `get_client_log` 拿到的都是空快照。现在 macOS 的 `Mprintf`(由 `common/logger.h` 定义)与 Linux 一样写 `Logger`(ring;`enable=false` 不另 建日志文件),再由 `Logger` 把同一行镜像到 stderr(即 `/tmp/ghost.log`),同一条 Mprintf 在文件与菜单里的文本、前缀、时间戳完全一致;ring 只留最近 1000 行,更早的内容只在文件 里。`macos/main.mm` 里原先用 `NSLog` 的启动/配置/权限等生命周期行也一并改成 `Mprintf`, 否则菜单里看不到现场最常翻的那几行;`ScreenHandler`/`H264Encoder`/`InputHandler` 等 ObjC 模块的 `NSLog` 不动,它们和两条直接 `write(2)` 的启动横幅仍只出现在 `/tmp/ghost.log`。 MFC 的「运行日志」对话框与 MCP 的 `get_client_log` 走同一条链路,两端同时可用。 ### 18.4 验证与未覆盖 - 服务端 21:17:21 构建 + 两端客户端重编后实测:`ids` 批量(`get_host_detail` / `host_list_processes` / `get_client_log`)全部 `succeeded=全数`;`list_registry` 省略 `path` 返回 5 个根键;`get_client_log` 在 Windows 上 `1000→200` 行(`truncated=true`)、 在 Linux 上正常返回 8 行,且客户端日志里 `Enter/Leave ClientLogThread` 成对、无泄漏。 明细见测试报告 §7。 - `get_activity_history` 仍是全量返回(实测 501 条),与 P0-3 同一类问题,但不在本次 三个 P0 内,留待下一轮。 - 连接器会缓存 `tools/list`,`limit`/`filter` 在重连前对模型不可见(默认参数已覆盖 P0-3 的场景),与既有的 `overwrite` 缓存问题同源。 ## 19. 增补(2026-10-29:`get_activity_history` 分页,P2-1) ### 19.1 问题 `get_activity_history` 是全仓库唯一没有分页的列表类工具。客户端 `ACTIVITY_HISTORY_MAX` = 500,`Dump()` 还会把进行中的当前窗口作为第 1 条,所以一次返回上限约 501 条——实测 正是 501 条。每行含窗口标题(可能很长),501 行直接把上下文冲爆;而报告里那份数据还 混着大量个人浏览、求职、签证页面,属于「不该被整包塞进模型上下文」的典型。 ### 19.2 顺序:为什么可以直接用 `limit`/`offset` `ActivityHistory::Loop()` 用 `m_records.push_front(...)` 维护,`Dump()` 又把当前进行中 的窗口拼在最前面——**返回顺序天然是「新在前」**。于是 `offset=0` 就是最近 `limit` 条, 不必像「新在后」的日志那样先取一次 `total` 再倒算 `offset=total-limit`。这条顺序不是 本次新增的约定,是客户端本来就这样,写进描述是为了让模型敢直接用 `offset=0`。 ### 19.3 实现 - `inputSchema` 从 `BuildGetHostDetailInputSchema()` 换成 `BuildPagedHostListInputSchema()` (`{ id | ids }` + `limit`/`offset`,与 `list_processes` / `list_windows` 同一套); - `outputSchema` 追加 `AppendPageOutputProps()` 与 `truncated`; - 实现里把原来的 `records` 改名 `all`(全量拆行结果),再 `ResolvePageWindow` + `ApplyPageWindow` 切出 `records`,`WritePageFields` 写回 `total`/`totalAll`/`offset`/ `limit`/`hasMore`; - **`activityHistory` 必须按窗口重建**:它原来是 `Dump()` 的整包原文,如果原样返回, 501 行的正文照样进上下文,等于没分页。现在它是窗口内 `records` 的按行拼接,语义仍是 「同一份数据的纯文本形态」; - 再加 64 KB 字节预算(与 `get_client_log` 同口径),从窗口**末尾**裁——保留最新的那些。 裁断时 `truncated=true`;`hasMore` 按 `offset + returned < total` 算,而不是一律置 true (末尾单条自己超预算时不该再报还有下一页)。调用方用 `offset + returned` 继续取; - 至少保留 1 条:单条超预算时若不保底,`returned=0` 会让调用方在同一个 `offset` 上原地 打转。窗口标题达到 64 KB 几乎不可能,这是纯兜底。 ### 19.4 批量 `get_activity_history` 在 `IsBatchReadOnlyTool` 名单里,`BuildBatchCall` 会把 `ids` 摘掉、 其余参数原样透传给单机调用,所以 `ids` + `limit` 等于「每台各取最近 N 条」,不需要额外 处理。P0-1 的 `anyOf:[单机, 批量]` 包装也自动覆盖新增字段。 ### 19.5 未做 - 没有 `filter`(按窗口标题子串)。报告没提,且客户端标题是 UTF-8、过滤要按字节子串做, 与 `get_client_log` 的 `filter` 不同源,等有实际需求再加。 - 没有 `since`(按时间起点取)。记录里的时间是 `[YYYY-MM-DD HH:MM:SS]` 文本前缀,做时间 过滤得先解析每行;当前 `limit/offset` 已够用。 ## 20. 增补(2026-11-10:窗口信息 RPC 与前台窗口校验) ### 20.1 问题 GUI 自动化的失败大多不是「事件没发出去」,而是「事件进了别的窗口」:后台窗口 `ShowWindow` 不会升到前台,`remote_keyboard` / `remote_mouse` 又只能按屏幕坐标注入, 调用方无法确认焦点是否在目标窗口上。旧的窗口列表(tab 1 / `COMMAND_WSLIST`)只有 标题和尺寸,没有屏幕坐标、前后台与 z 序,且标题是 ANSI/GBK。 ### 20.2 协议 新增能力位 `CLIENT_CAP_WINDOW_INFO=0x0100`(仅 Windows 客户端在 `DefaultCaps()` 置位)。 声明该能力位的客户端支持一个**主连接** RPC: ``` 请求 [COMMAND_MCP_WINDOW_INFO(179)][mode:1] // mode 0 = 可见顶层窗口 响应 [TOKEN_MCP_WINDOW_INFO(180)][mode:1][count:u16 LE][WINDOWINFO_MCP × count] [WINDOWINFO_MCP_DESKTOP?] // 新客户端可选尾块,20 字节(§22.2) ``` `WINDOWINFO_MCP` 为 1056 字节 packed:`hwnd/pid/left/top/right/bottom/flags/zorder/title[1024]`, 标题 UTF-8;`flags` 含 `VISIBLE/MINIMIZED/MAXIMIZED/FOREGROUND`。客户端在 worker 线程 枚举(`GetWindowTextW` 会给挂死的窗口发消息),单机同时只允许一次枚举在飞,最多返回 96 个窗口(约 101 KB,低于 `MAX_SEND_BUFFER`);可见窗口更多时响应把 `mode` 的最高位 (`0x80`)置 1,表示返回的 `count` 条只是前缀、列表不完整。服务端复用主连接的 `BeginPending` / `WaitPending`,由 `2015RemoteDlg::MessageHandle` 的 `TOKEN_MCP_WINDOW_INFO` 分支调用 `TakeMainResponse`,不建子连接、不弹框。 新客户端在 `count` 条记录后追加可选的 `WINDOWINFO_MCP_DESKTOP` 尾块(20 字节,magic `'VDCP'`,报告虚拟桌面矩形);服务端按包长判定是否存在,老服务端只读 `count` 条记录、 忽略尾部。布局与用途见 §22.2。 老客户端不认识 179,服务端按能力位提前拒绝(`-32005`),不会白等超时。 ### 20.3 新工具与参数 - **`get_foreground_window`**(第 61 个工具,仅 Windows):返回 `{windowCount, window|null}`,`window` 含 hwnd/pid/title/rect/flags/z 序。 - **`host_list_windows`**:能力位存在时改走新 RPC,字段扩展为 `left/top/right/bottom/visible/minimized/maximized/isForeground/zOrder`;否则回落旧的 tab 1(字段不变)。过滤与分页完全不变。 - **`host_control_window` / `operate_window` 新增 `activate`**:下发 `CMD_WINDOW_ACTIVATE_FLAG(0xFFFFFFFF)` 哨兵。客户端用 `AttachThreadInput + BringWindowToTop + SetForegroundWindow` 把窗口真正升到前台; 动作后服务端再发一次窗口信息 RPC 复核 `GetForegroundWindow`,未成功返回 `ok=false, reason=not_foreground`,而不是「已下发」。 - **`remote_keyboard` / `remote_mouse` 新增可选参数**: - `expect_hwnd`:注入前确认窗口仍在可见列表里;`require_foreground=true` 还要求它是 前台,否则**不发注入**并返回 `-32000`; - `report_foreground`:注入后回报前台窗口(`structuredContent.foreground`);给了 `expect_hwnd` 时默认开启。回报失败只写 `foregroundError`,不把已发生的注入判失败。 ### 20.4 兼容与代价 - 所有新能力都挂在 `CLIENT_CAP_WINDOW_INFO` 后面;老客户端行为逐字节不变。 - 每次窗口信息 RPC 是一次主连接往返;只在 `host_list_windows`、`get_foreground_window`、 `activate` 和显式给了 `expect_hwnd` / `report_foreground` 时发生。 - `activate` 仍可能被 Windows 前台锁定策略拒绝(用户正在操作、目标进程有模态框), 工具如实返回失败;`hide` 后窗口从可见列表消失、无法再被 `activate`,这一旧限制不变。 - 窗口列表只含**可见**顶层窗口,且按 z 序从上到下截取前 96 个:被 `hide`、最小化到托盘 等不可见窗口查不到;桌面窗口超过 96 个时,排在后面的窗口不会出现。客户端会在响应 里置截断位,服务端据此如实报告:`host_list_windows` 返回 `truncated=true` 且正文说明 列表不完整;`expect_hwnd` 查不到时 `-32009` 的文案区分「窗口可能还在、只是没返回」 与「隐藏/已关闭」;`activate` 复核时目标不在返回的这一批里则记 `state=unknown`、 `reason=list_truncated`,而不是 `missing`。任何情况下都不要据截断的列表断定窗口已销毁。 ## 21. 增补(2026-11-10:区域/窗口/显示器原生分辨率截图) ### 21.1 问题 旧的 `get_screenshot` 只有「整个虚拟桌面 + `max_width` 缩放」一种形态。GUI 自动化真正 需要的往往是某个窗口或某块 ROI 的原始像素:整屏缩到 1024 后聊天正文、按钮小字都糊了, OCR 与视觉定位同时退化;把 `max_width` 抬到 1920 对 4K 屏仍不够,而且传的依旧是全屏。 ### 21.2 协议 新增能力位 `CLIENT_CAP_SCREEN_REGION=0x0200`(Windows 客户端 `DefaultCaps()` 置位; Linux 客户端只有 v1 处理分支,不声明)。请求在原有 8 字节 `ScreenPreviewReq` 之后追加 24 字节 `ScreenPreviewReqEx`(共 32 字节): ``` u8 mode ScreenCaptureMode: VDESKTOP=0 / REGION=1 / WINDOW=2 / MONITOR=3 u8 flags SCREEN_CAPTURE_F_NATIVE=0x01(按源矩形 1:1,忽略 maxWidth) u16 monitor mode=MONITOR 的序号 i32 x, y, w, h mode=REGION 的矩形(虚拟桌面坐标) u32 hwnd mode=WINDOW 的窗口句柄 ``` 响应仍是 `ScreenPreviewRspHeader`(16) + JPEG;v2 成功时客户端在 JPEG 之后追加 24 字节 `ScreenCaptureMeta`(magic `'SCM2'`=0x324D4353,`x/y/w/h` + `scale` + `mode`),如实回报 实际抓取的源矩形与缩放百分比。老服务端只按 `header.bytes` 取图,会忽略尾块;老客户端 忽略请求尾巴、按 v1 抓整屏。服务端只对声明能力位的主机发 v2,两个方向都不需要版本协商。 ### 21.3 抓取语义 | mode | 参数 | 源矩形 | 默认尺寸 | |---|---|---|---| | `screen` | — | 虚拟桌面 `SM_*VIRTUALSCREEN` | 沿用 RTT 自适应(≤1024),可传 `max_width` | | `region` | `x/y/width/height` | 与虚拟桌面求交后裁剪(`x/y` 可为负) | 1:1 原生分辨率 | | `window` | `hwnd` | `GetWindowRect` 后与虚拟桌面求交;`IsWindow` 且非 `IsIconic` | 1:1 原生分辨率 | | `monitor` | `monitor` | 0=主显示器(`MonitorFromPoint`);1..N 按 `EnumDisplayMonitors` 顺序跳过主屏 | 1:1 原生分辨率 | - `region/window/monitor` 只有显式传 `max_width`(钳制到 64..1920) 才等比缩小;缺省即原生分辨率, 1:1 抓取单边硬上限 8192 像素(覆盖 8K 显示器,同时拦住异常区域打爆内存)。缩放路径不受此限, 整屏同样适用——三屏 4K 这类超宽虚拟桌面仍能正常抓缩略图。 - 需要缩放时目标宽高做偶数对齐(JPEG 更省),1:1 时不改尺寸。 - 抓屏与注入共用虚拟桌面坐标系(多显示器时原点可为负),`structuredContent.capture` 回报的就是实际源矩形,可直接用于换算点击坐标。 - 窗口抓取是 GDI 抓屏语义:被其他窗口遮挡的部分截到的是遮挡物,不是 `PrintWindow` 式的重绘;需要无遮挡内容时先 `activate` 目标窗口。矩形含非客户区。 ### 21.4 工具参数与返回 `get_screenshot` 的 `inputSchema` 新增 `mode`(枚举 `screen|region|window|monitor`,默认 `screen`)与 `x/y/width/height/hwnd/monitor`;`max_width` 的描述按模式分叉。`hwnd` 直接 取 `host_list_windows` / `get_foreground_window` 返回的句柄,同时接受整数与 `0x` 字符串。 返回值在 `image` 之外新增 `structuredContent.capture = {mode,x,y,width,height,scale,native}` (老客户端不回尾块时只有 `mode`)。`screen` 模式对新客户端也走 v2,因此同样能拿到源矩形。 ### 21.5 错误 | 场景 | code | 说明 | |---|---|---| | 客户端无 `CLIENT_CAP_SCREEN_REGION` 却要 region/window/monitor | `-32005` | 换 `mode=screen` 或升级客户端,改别的参数修不好 | | `window` 的 hwnd 不存在、已最小化、完全在虚拟桌面外或单边超过 8192 px | `-32009` | 先 `activate` / `restore`,或重新取 hwnd;超大窗口改用 `region` 分段截取 | | `monitor` 序号越界、`region` 裁剪后为空 | `-32602` | 参数问题 | | 抓屏/编码失败 | `-32000` | 主机侧失败(如无桌面会话) | | 超时 / 设备忙 | `-32001` / `-32003` | 同其他主连接工具 | ### 21.6 兼容与代价 - 全部挂在能力位后面:老客户端、老服务端的字节流逐字节不变;Linux 仍走 v1 全屏。 - 客户端对抓屏请求保持单飞(同一时刻 1 个),并投递到工作线程编码,不阻塞接收线程; 并发请求直接丢弃,表现为服务端超时。 - 原生分辨率意味着更大的 JPEG 与 base64 体积:区域越大、越多窗口细节,单次响应越贵。 只截需要的 ROI,比整屏 1920 更省也更快。 ## 22. 增补(2026-11-10:窗口相对坐标 —— 看屏即点) ### 22.1 问题 `get_screenshot mode=window` 能拿到窗口原始像素,但 `remote_mouse` 只接受**屏幕**归一化坐标 (0..1 相对整个虚拟桌面)。模型想点窗口截图里 (0.5, 0.4) 的按钮,得自己把像素换算回 虚拟桌面坐标,还要处理多显示器导致的负原点;换算错一位,点击就落到别的窗口或别的屏幕上。 ### 22.2 协议:窗口信息响应的桌面尾块 窗口信息响应在 `count` 条记录之后追加一个**可选**尾块(布局见 §20.2): ``` 响应 [TOKEN_MCP_WINDOW_INFO][mode:1][count:u16 LE][WINDOWINFO_MCP × count] [WINDOWINFO_MCP_DESKTOP?] // 20 字节,magic 'VDCP'(0x56444350) ``` `WINDOWINFO_MCP_DESKTOP` 为 packed 的 `magic/left/top/width/height`,取 `SM_*VIRTUALSCREEN`,即抓屏与注入共用的虚拟桌面矩形。服务端按**包长**判定尾块是否存在: 老客户端不发尾块,服务端按旧布局解析、`window_hwnd` 返回 `-32005`;老服务端只读 `count` 条记录,尾部字节被忽略。不新增能力位——尾块本身就是新客户端的标志。 ### 22.3 `remote_mouse` 的 `window_hwnd` 基准 `remote_mouse` 新增可选 `window_hwnd`(整数或 `0x` 字符串)。给定后 `x/y`(以及 `drag` 的 `x2/y2`)改为**相对该窗口的归一化坐标**,服务端换算成发送帧坐标: ``` clip_left = max(window.left, desktop.left) clip_right = min(window.right, desktop.left + desktop.width) physical_x = clip_left + n × (clip_right - clip_left) frame_x = (physical_x - desktop.left) / desktop.width ``` (Y 方向同理;窗口完全移出虚拟桌面时交集为空,直接 `-32009`。) 基准矩形取**窗口矩形与虚拟桌面的交集**:`get_screenshot mode=window` 的源矩形也是这个 交集(§21.3),因此窗口截图上的比例点可直接映射为 `window_hwnd` 坐标;窗口部分移出 虚拟桌面时,被裁掉的那部分不会让点击整体偏移。`frame_x/frame_y` 钳制到 0..1 后交给 既有的发送帧 → 客户端 `PointConversion`(ROI 偏移、缩放、DPI、虚拟桌面原点)。 安全默认值: - **默认要求目标窗口是前台**(`require_foreground=true` 隐式生效):非前台窗口的坐标 点击会落到遮挡它的窗口上。显式传 `require_foreground=false` 可关闭。 - `window_hwnd` 与 `expect_hwnd` 同时给出时必须指向同一窗口,否则 `-32602`。 - 窗口不存在 / 不可见 / 最小化 / 矩形为空 / 完全移出虚拟桌面 → `-32009`;窗口不是前台 → `-32000`; 客户端窗口信息响应没有桌面尾块(老客户端)→ `-32005`。 - 返回 `structuredContent.coordinateWindow`(**未裁剪**的窗口原始快照)与 `resolved` 里的 `frame_x/frame_y`(drag 另有 `frame_x2/frame_y2`)和 `basis`(实际坐标基准矩形,即 窗口 ∩ 虚拟桌面,与 `get_screenshot mode=window` 的 `capture` 源矩形一致)。 窗口部分移出虚拟桌面时 `coordinateWindow` 与 `basis` 不同,核对换算请以 `basis` 为准。 ### 22.4 代价 - 每次带 `window_hwnd` 的调用多一次窗口信息 RPC(一次主连接往返);不带时行为与 字节流完全不变。 - 窗口在前台且未被缩放时,比例点与窗口截图 1:1 对应;窗口被其他窗口部分遮挡时, 截图本身也是遮挡内容(GDI 语义,见 §21.3),需要无遮挡内容时先 `activate`。 ## 23. 增补(2026-11-10:`remote_open` 的 window / region 目标) ### 23.1 问题 `remote_open` 默认推整屏/整虚拟桌面,客户端默认还会把画面等比缩到长边 ≤1920、 短边 ≤1080 再编码。在 4K 屏上,屏幕上 1 个像素对应发送帧不足 1 个像素,模型按截图比例点出来的坐标 天然带量化误差;同时整屏画面里绝大部分像素与本次操作无关,带宽和编码延迟都在为 它们付钱。目标明确时(点某个窗口里的按钮、看某个面板)只推目标窗口或 ROI, 带宽、延迟、点击精度三赢。 ### 23.2 window 目标 `remote_open` 新增可选 `window_hwnd`(整数或 `0x` 字符串,与 `region` 互斥): ``` COMMAND_SCREEN_SPY token(32 字节) [0]=cmd [1]=GDI/DXGI [2]=algo [3]=多屏 [4..11]=HWND uint64 LE // 非 0 = 只推该窗口 [12]=forceVirtualDesktop // window 目标时不使用 ``` 客户端已有窗口抓屏(人类远程控制的「只显示窗口」同一条路径):帧尺寸取 DWM 可见边框(含标题栏),窗口左上角作为注入原点(`m_iScreenX/Y`),因此 `remote_mouse` 的归一化坐标直接相对窗口帧;客户端强制 GDI 抓取,并在每批注入前 自动 `SetForegroundWindow`。最小化窗口会冻结画面,服务端在开会话前用窗口信息 RPC (§20.2)校验:窗口不存在 / 最小化 / 矩形为空 → `-32009`;窗口信息响应不带 虚拟桌面尾块(老客户端)→ `-32005`(能力位 `CLIENT_CAP_WINDOW_INFO`)。 window 目标**不受多显示器门限制**:帧来自目标窗口本身,与虚拟桌面抓屏能力无关。 ### 23.3 region 目标 `remote_open` 新增可选 `region`(对象,`x`/`y` 可选、`width`/`height` 必填, 1..8192;与 `window_hwnd` 互斥): 1. 参数按虚拟桌面物理像素解释,服务端先取窗口信息响应里的桌面尾块(§22.2), 把矩形裁剪到桌面范围;裁剪后为空 → `-32009`; 2. 按正常流程 `StartRemoteDesktop` 建立整屏会话,拿到发送帧尺寸 `screenW/H`; 3. 把物理矩形按桌面比例换算成**发送帧坐标**(客户端 ROI 坐标与 `screenW/H` 同口径, 已包含缩放),发 `COMMAND_SCREEN_ROI [cmd][RECT]`,客户端据此裁剪抓屏; 4. **等客户端重发 `TOKEN_BITMAPINFO` 且尺寸恰好等于 ROI 尺寸**才标记会话就绪并 返回;超时 → `-32001`。提前返回会让紧随其后的注入仍按旧的全屏 ROI 解释。 region 同样要求新 Windows 客户端(桌面尾块是 `CLIENT_CAP_WINDOW_INFO` 的标志), 老客户端 → `-32005`;多显示器门照旧生效(整屏抓屏能力仍然是前提)。 ### 23.4 会话状态与 `remote_mouse` 交互 - `remote_open` 返回 `target`(`screen` / `window` / `region`);window 目标另返回 `window_hwnd`,region 目标返回实际生效的 `region`(已裁剪,虚拟桌面坐标)。 审计记录同样带 `target=` / `window=` / `region=`。 - 目标会话里 `x/y` 就是**相对目标帧**的 0..1,不需要再传 `window_hwnd` (传了会二次换算,服务端直接 `-32602` 并释放 busy)。 - 目标窗口可能被拖动/缩放:客户端会原地重建并按新尺寸重发 `TOKEN_BITMAPINFO`。 `remote_mouse` 每次注入前对目标会话重新读一次 `GetScreenSize`,用最新帧尺寸 换算,而不是沿用 open 时的快照。 - `remote_keyboard` 的 `expect_hwnd` / `require_foreground` 仍可用;`window_hwnd` 在目标会话里仅作为冗余参数被拒绝。 ### 23.5 分辨率缓存的冷启动清理 `screen_width/height` 缓存跨会话保留。`StartRemoteDesktop` 在**冷启动**分支清空 关键帧缓存的同时也清空尺寸缓存:否则 `remote_open` 可能先用上一会话的尺寸 判定 region 握手成功(尤其是目标窗口尺寸恰好接近旧全屏尺寸时)。复用已有子连接的 路径在清空前就 return,Web 观看行为不受影响。 ### 23.6 兼容与代价 - 客户端无改动:window 目标复用既有窗口抓屏;region 目标复用 `COMMAND_SCREEN_ROI`。 - 老客户端、Linux 主机不支持 `window_hwnd` / `region`(窗口信息 RPC 仅新 Windows 客户端),返回 `-32005`;默认整屏目标行为与字节流完全不变。 - window/region 目标各自多一次窗口信息 RPC;region 目标还要多等一次 `TOKEN_BITMAPINFO` 到达(通常几十毫秒)。