Fix(mcp): make declared schemas match what the handlers return

Several tool contracts disagreed with the runtime shape, which forces an
agent to guess instead of following outputSchema:

- get_server_status returned {"status": {...}} while outputSchema has the
  fields at top level; return the status object directly.
- get_screenshot description claimed structuredContent.image carries the
  base64 data; it only carries mimeType/width/height/bytes, the bytes are
  in the content image block.
- host_control_service accepted service_name silently, but not in schema;
  document the alias and add anyOf [{required:[name]},{required:[service_name]}]
  so a call missing both fails at validation, not at execution.
- kill_network_connection dry_run invented dryRun/connection fields absent
  from ActionOutputSchema; use the shared BuildDryRunResult shape.
- search_file outputSchema left files.items untyped; declare
  path/name/modified/dir/size and the paging fields it already emits.
- chat_* id hints still named the removed list_online_hosts/search_hosts.

tools.json hunks keep the live-dump key order (alphabetical inside schemas),
tools_minimal.json is regenerated, and mcp_smoke.ps1 now reads the flat
structuredContent. Debug build green; check_platform_table, gen_go_tools
--check and go test ./... pass.

Co-Authored-By: deepseek-flash
This commit is contained in:
yuanyuanxianganddeepseek-flash committed 2026-11-13 12:23:39 +01:00
1 parent 5e012019ba
commit 292c3191dc
7 files changed
+93 -23

No files matched your search

+2 -2
View File
@@ -628,7 +628,7 @@ token 只从 `-Token` / env 读取,不落仓库、不打印;无在线主机
排查「改动到底生效没有」「为什么某个工具被拒」时,原先只能靠 `list_online_hosts` 加 `get_audit_log` 侧面推断;现在有一个服务端自身的状态快照。纯内存、只读、不建子连接。
返回(`structuredContent.status`):
返回(`structuredContent` 顶层,与 outputSchema 字段一一对应;早期版本曾多包一层 `status`,已修):
| 字段 | 含义 |
|---|---|
@@ -848,7 +848,7 @@ ECDSA 这条是 MS Software KSP 唯一可行的一条,其余几条均已实测
### 14.3 验证
Debug 实例(`Bin\Yama_x64d.exe`,临时端口)实测:`list_all_hosts` 的 `content[1]` 含完整主机 JSON(`id` / `ip` / `last_seen` …),`get_server_status` 的 `content[1]` 是 `{"status":{…}}`,`search_hosts` 空结果时是 `{"hasMore":false,"hosts":[],…}`;`content[0]` 的既有摘要文案一字未改。
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 影响面
+49 -5
View File
@@ -506,7 +506,7 @@
},
{
"name": "get_screenshot",
"description": "截取指定在线主机的一帧画面,返回 base64 编码的 JPEG 图片(image 对象含 mimeType/data/width/height)。支持 Windows 与带 X11 桌面的 Linux 客户端(能力位 CLIENT_CAP_SCREEN_PREVIEW),主连接 RPC、一次性返回。Android 客户端用无障碍服务 takeScreenshot 抓屏(Android 11+ 且开启无障碍服务,此时登录会声明该能力位;只支持 mode=screen)。mode 可选 screen(默认,整虚拟桌面)/region(指定矩形)/window(指定 hwnd)/monitor(指定显示器);后三种默认按源尺寸 1:1 原生分辨率抓取(适合 OCR/视觉读字),需要较新的 Windows 客户端(CLIENT_CAP_SCREEN_REGION,否则 -32005),结果在 structuredContent.capture 里回报实际源矩形与缩放比例。",
"description": "截取指定在线主机的一帧画面,返回 base64 编码的 JPEG 图片:图片在 content 的 image 块(data 为 base64,mimeType=image/jpeg);structuredContent.image 只有 mimeType/width/height/bytes 元数据,不含图片数据。支持 Windows 与带 X11 桌面的 Linux 客户端(能力位 CLIENT_CAP_SCREEN_PREVIEW),主连接 RPC、一次性返回。Android 客户端用无障碍服务 takeScreenshot 抓屏(Android 11+ 且开启无障碍服务,此时登录会声明该能力位;只支持 mode=screen)。mode 可选 screen(默认,整虚拟桌面)/region(指定矩形)/window(指定 hwnd)/monitor(指定显示器);后三种默认按源尺寸 1:1 原生分辨率抓取(适合 OCR/视觉读字),需要较新的 Windows 客户端(CLIENT_CAP_SCREEN_REGION,否则 -32005),结果在 structuredContent.capture 里回报实际源矩形与缩放比例。",
"gate": null,
"platforms": [
"win",
@@ -2960,6 +2960,23 @@
"properties": {
"files": {
"items": {
"properties": {
"dir": {
"type": "boolean"
},
"modified": {
"type": "string"
},
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"size": {
"type": "integer"
}
},
"type": "object"
},
"type": "array"
@@ -2967,6 +2984,21 @@
"finished": {
"type": "boolean"
},
"hasMore": {
"type": "boolean"
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"total": {
"type": "integer"
},
"totalAll": {
"type": "integer"
},
"truncated": {
"type": "boolean"
}
@@ -4431,6 +4463,18 @@
],
"impl": "mfc",
"inputSchema": {
"anyOf": [
{
"required": [
"name"
]
},
{
"required": [
"service_name"
]
}
],
"properties": {
"action": {
"description": "start/stop/pause/continue/restart,以及 set_auto/set_manual(转主连接实现,需 McpManage=1)",
@@ -4617,7 +4661,7 @@
"inputSchema": {
"properties": {
"id": {
"description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段",
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
},
"timeout_ms": {
@@ -4662,7 +4706,7 @@
"inputSchema": {
"properties": {
"id": {
"description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段",
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
},
"message": {
@@ -4716,7 +4760,7 @@
"inputSchema": {
"properties": {
"id": {
"description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段",
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
},
"max_messages": {
@@ -4794,7 +4838,7 @@
"inputSchema": {
"properties": {
"id": {
"description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段",
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
},
"session_id": {
+1 -1
View File
@@ -175,7 +175,7 @@ Json::Value OutputSchema(Json::Value props, std::initializer_list<const char*> r
}
Json::Value HostIdProp() {
return PropStr(u8"主机 id,取 list_online_hosts / search_hosts 返回的 id 字段");
return PropStr(u8"主机 id,取 list_hosts 返回的 id 字段");
}
Json::Value SessionIdProp() {
+18 -8
View File
@@ -1537,14 +1537,11 @@ std::string BuildKillNetworkConnection(const Json::Value& id, const Json::Value&
if (pidFilter < 0) pidFilter = (int)found->pid;
if (dryRun) {
Json::Value sc(Json::objectValue);
sc["ok"] = true;
sc["dryRun"] = true;
sc["target"] = target;
sc["connection"] = targetJson;
AuditManageAction(parent, ht.dev, toolName, target + " pid=" + std::to_string(pidFilter) +
" result=dry_run");
return BuildStructuredResult(id, sc, "Dry run: target found, nothing was sent");
// 与其它动作工具的 dry_run 同一个形状:ok/dry_run/action/target/state/detail,
// 不再自造 dryRun/target/connection 字段(schema 里没有,模型也得猜)。
return BuildDryRunResult(id, "kill", target, "present", targetJson);
}
// 会话保持:取列表用的是第一条 255,断开后客户端会自动再回一条 255。
@@ -2581,8 +2578,9 @@ static std::string BuildHostControlService(const Json::Value& id, const Json::Va
if (dangerous && !RequireDangerous(id, errJson)) return errJson;
std::string serviceName = Trim(GetStringArg(args, "name"));
if (serviceName.empty()) serviceName = Trim(GetStringArg(args, "service_name"));
if (serviceName.empty())
return BuildError(id, -32602, "Missing required parameter: name (service name)");
return BuildError(id, -32602, "Missing required parameter: name (service name; service_name is an accepted alias)");
HostTool ht;
if (!ResolveHost(id, args, parent, ht, true, errJson)) return errJson;
@@ -3238,9 +3236,21 @@ void AppendTools(Json::Value& tools) {
props["name"] = PropStr(u8"服务名(ServiceName,不是显示名),取 host_inspect 的 win32_services / driver_services 项的 name;与 service_name 二选一");
props["service_name"] = PropStr(u8"name 的旧参数名别名(与 name 等价,二选一)");
props["dry_run"] = PropBool(u8"true 时只校验服务存在并返回当前状态,不下发控制命令,默认 false");
// name 与 service_name 等价、二选一:只在 required 里写 id/action 会让两者都缺的
// 调用也“符合 schema”,到执行期才报错;anyOf 让契约与实现一致。
Json::Value schema = MakeSchema(props, { "id", "action" });
Json::Value anyOf(Json::arrayValue);
for (const char* key : { "name", "service_name" }) {
Json::Value alt(Json::objectValue);
Json::Value req(Json::arrayValue);
req.append(key);
alt["required"] = req;
anyOf.append(alt);
}
schema["anyOf"] = anyOf;
AddTool(tools, "host_control_service",
u8"控制在线 Windows 主机的服务:start/stop/pause/continue/restart/set_auto/set_manual。start 等五个动作走主机管理链路:客户端对每次控制都会自动回一份刷新后的服务列表,工具据此复核状态并如实返回 ok;stop 与 restart 归入危险操作,需要同时开启 McpMachineDangerous;restart 先 stop 再 start。set_auto/set_manual 没有主机管理实现,转由主连接版 control_service 处理(ok 只表示已下发、需另查状态;McpManage=0 时返回 -32006)——它们只在 McpMachine=0 时才以 control_service 之名出现在 tools/list。不提供删除服务。dry_run=true 只核实服务并返回当前状态,不下发命令(是否已是目标状态由你按 state 判断);set_auto/set_manual 不支持 dry_run(返回 -32602)。",
MakeSchema(props, { "id", "action" }),
schema,
ActionOutputSchema());
}
{
+20 -4
View File
@@ -2235,7 +2235,7 @@ std::string BuildToolsListResult(const Json::Value& id) {
{
Json::Value tool(Json::objectValue);
tool["name"] = "get_screenshot";
tool["description"] = u8"截取指定在线主机的一帧画面,返回 base64 编码的 JPEG 图片(image 对象含 mimeType/data/width/height)。支持 Windows 与带 X11 桌面的 Linux 客户端(能力位 CLIENT_CAP_SCREEN_PREVIEW),主连接 RPC、一次性返回。Android 客户端用无障碍服务 takeScreenshot 抓屏(Android 11+ 且开启无障碍服务,此时登录会声明该能力位;只支持 mode=screen)。mode 可选 screen(默认,整虚拟桌面)/region(指定矩形)/window(指定 hwnd)/monitor(指定显示器);后三种默认按源尺寸 1:1 原生分辨率抓取(适合 OCR/视觉读字),需要较新的 Windows 客户端(CLIENT_CAP_SCREEN_REGION,否则 -32005),结果在 structuredContent.capture 里回报实际源矩形与缩放比例。";
tool["description"] = u8"截取指定在线主机的一帧画面,返回 base64 编码的 JPEG 图片:图片在 content 的 image 块(data 为 base64,mimeType=image/jpeg);structuredContent.image 只有 mimeType/width/height/bytes 元数据,不含图片数据。支持 Windows 与带 X11 桌面的 Linux 客户端(能力位 CLIENT_CAP_SCREEN_PREVIEW),主连接 RPC、一次性返回。Android 客户端用无障碍服务 takeScreenshot 抓屏(Android 11+ 且开启无障碍服务,此时登录会声明该能力位;只支持 mode=screen)。mode 可选 screen(默认,整虚拟桌面)/region(指定矩形)/window(指定 hwnd)/monitor(指定显示器);后三种默认按源尺寸 1:1 原生分辨率抓取(适合 OCR/视觉读字),需要较新的 Windows 客户端(CLIENT_CAP_SCREEN_REGION,否则 -32005),结果在 structuredContent.capture 里回报实际源矩形与缩放比例。";
tool["inputSchema"] = BuildGetScreenshotInputSchema(); // { id } 必填 + max_width 可选
tool["outputSchema"] = BuildScreenshotOutputSchema();
@@ -4585,9 +4585,9 @@ std::string BuildGetServerStatus(const Json::Value& id, CMy2015RemoteDlg* parent
status["blocked_auth_ips"] = blockedIps;
Json::Value result(Json::objectValue);
Json::Value structuredContent(Json::objectValue);
structuredContent["status"] = status;
result["structuredContent"] = structuredContent;
// outputSchema 声明的就是顶层字段;不要再套一层 "status",否则按 schema 取字段
// (structuredContent.version 等)的客户端拿不到任何东西。
result["structuredContent"] = status;
std::string text = std::string(BRAND_APP_NAME) + " v" + VERSION_STR +
std::string(u8",已运行 ") + std::to_string((long long)status["uptime_sec"].asInt64()) +
@@ -10938,6 +10938,19 @@ Json::Value BuildSearchFileOutputSchema() {
filesProp["type"] = "array";
Json::Value items(Json::objectValue);
items["type"] = "object";
Json::Value itemProps(Json::objectValue);
for (const char* f : { "path", "name", "modified" }) {
Json::Value s(Json::objectValue);
s["type"] = "string";
itemProps[f] = s;
}
Json::Value dirProp(Json::objectValue);
dirProp["type"] = "boolean";
itemProps["dir"] = dirProp;
Json::Value sizeProp(Json::objectValue);
sizeProp["type"] = "integer";
itemProps["size"] = sizeProp;
items["properties"] = itemProps;
filesProp["items"] = items;
props["files"] = filesProp;
Json::Value finProp(Json::objectValue);
@@ -10946,6 +10959,9 @@ Json::Value BuildSearchFileOutputSchema() {
Json::Value truncProp(Json::objectValue);
truncProp["type"] = "boolean";
props["truncated"] = truncProp;
// 分页字段:BuildSearchFile 一直会带 total/totalAll/offset/limit/hasMore,
// schema 补齐后客户端按输出契约取值才不会扑空。
AppendPageOutputProps(props);
Json::Value schema(Json::objectValue);
schema["type"] = "object";
schema["properties"] = props;
+1 -1
View File
@@ -326,7 +326,7 @@
},
{
"name": "get_screenshot",
"description": "截取指定在线主机的一帧画面,返回 base64 编码的 JPEG 图片(image 对象含 mimeType/data/width/height)。支持 Windows 与带 X11 桌面的 Linux 客户端(能力位 CLIENT_CAP_SCREEN_PREVIEW),主连接 RPC、一次性返回。Android 客户端用无障碍服务 takeScreenshot 抓屏(Android 11+ 且开启无障碍服务,此时登录会声明该能力位;只支持 mode=screen)。mode 可选 screen(默认,整虚拟桌面)/region(指定矩形)/window(指定 hwnd)/monitor(指定显示器);后三种默认按源尺寸 1:1 原生分辨率抓取(适合 OCR/视觉读字),需要较新的 Windows 客户端(CLIENT_CAP_SCREEN_REGION,否则 -32005),结果在 structuredContent.capture 里回报实际源矩形与缩放比例。",
"description": "截取指定在线主机的一帧画面,返回 base64 编码的 JPEG 图片:图片在 content 的 image 块(data 为 base64,mimeType=image/jpeg);structuredContent.image 只有 mimeType/width/height/bytes 元数据,不含图片数据。支持 Windows 与带 X11 桌面的 Linux 客户端(能力位 CLIENT_CAP_SCREEN_PREVIEW),主连接 RPC、一次性返回。Android 客户端用无障碍服务 takeScreenshot 抓屏(Android 11+ 且开启无障碍服务,此时登录会声明该能力位;只支持 mode=screen)。mode 可选 screen(默认,整虚拟桌面)/region(指定矩形)/window(指定 hwnd)/monitor(指定显示器);后三种默认按源尺寸 1:1 原生分辨率抓取(适合 OCR/视觉读字),需要较新的 Windows 客户端(CLIENT_CAP_SCREEN_REGION,否则 -32005),结果在 structuredContent.capture 里回报实际源矩形与缩放比例。",
"inputSchema": {
"properties": {
"height": {
+2 -2
View File
@@ -265,7 +265,7 @@ $auditFiltered = Rpc '' $null 'get_audit_log' @{ type = 'zzz-no-such-type'; limi
Check 'get_audit_log 过滤未命中返回 0 条' ($auditFiltered.error -eq $null -and @($auditFiltered.result.structuredContent.entries).Count -eq 0)
$status = Rpc '' $null 'get_server_status' @{}
$st = $status.result.structuredContent.status
$st = $status.result.structuredContent
Check 'get_server_status 正常返回' ($status.error -eq $null -and $null -ne $st)
$basePort = 6544
if ($Base -match ':(\d+)(/|$)') { $basePort = [int]$Matches[1] }
@@ -806,7 +806,7 @@ if (-not $longCall) {
([int]$jr.error.code -eq -32800)) $body
# 交叉核对:get_server_status 的 sessions.pending 应回到 0,主机能再次正常调用
$st2 = (Rpc '' $null 'get_server_status' @{}).result.structuredContent.status
$st2 = (Rpc '' $null 'get_server_status' @{}).result.structuredContent
Check '取消后 get_server_status 无挂起(sessions.pending=0)' `
([int]$st2.sessions.pending -eq 0) ("pending=" + $st2.sessions.pending)
if (HasTool 'list_processes') {