[Bug] Gemini 3.x 在调用 cordis_inspect_query 后永久报 HTTP 400：工具返回的 JSON Schema $ref: "#/$defs/loaderExpression" 被误判为多模态 display_name（附根因与修复建议）

[Kisaragi911]

问题描述 / Symptom

当模型配置为 Google Gemini（3.x） 时，一旦会话中触发了只读配置查询工具 cordis_inspect_query（如 Config.listConfigs），下一轮及之后的每一次请求都会固定返回 HTTP 400，导致当前会话彻底卡死（历史重放持续触发同一校验错误）：

400: {
  "message": "The referenced name `#/$defs/loaderExpression` in function_response.response does not match to a display_name in the function_response.parts.",
  "type": "upstream_error",
  "param": "",
  "code": 400
}

---

根因定位 / Root Cause

1. Gemini API 的 $ref 校验机制冲突
   Gemini 在接收 function_response 时，会扫描 function_response.response 对象中的 $ref 字段，并将其视为对 function_response.parts 中多模态附件 display_name 的引用。当工具返回值本身包含 JSON Schema 的内部引用（如 #/$defs/...）且以结构化对象原样回传时，Gemini 在 parts 中找不到同名附件，直接拒绝请求并返回 400 INVALID_ARGUMENT。

2. #/$defs/loaderExpression 的具体来源
   在 @deepseek-ai/dsh-tool-cordis（app.asar/dsh/node_modules/@deepseek-ai/dsh-tool-cordis/lib/types/config.js）中，cordis_inspect_query 会将投影出的完整 JSON Schema 作为工具结果返回：

   return toJson({ ...listed, acceptsMissing, limitations, schema: {
       $schema: 'https://json-schema.org/draft/2020-12/schema',
       $defs: { ...definitions, loaderExpression: LOADER_EXPRESSION_SCHEMA },
       ...schema,
   } });

   （其中 LOADER_EXPRESSION_SCHEMA 来自 @deepseek-ai/dsh-app-boot。）

   当返回的配置 schema 中包含 "$ref": "#/$defs/loaderExpression" 时，该结果写入会话历史，并在下一轮请求重放给 Gemini 时引爆 400 报错。

---

复现步骤 / Reproduction

1. 将当前模型切换为 Gemini（走原生 Google function_response 结构化回传路径）。
2. 让 Agent 调用 cordis_inspect_query（查询 Config.listConfigs 等会返回带 loaderExpression 引用 schema 的项）。
3. 工具执行成功返回后，继续下一轮对话或模型自动续行，立即触发上述 HTTP 400，且该 Session 后续每轮请求均失败。
4. 使用的版本是桌面端0.2.1-rc.2

---

外部同类先例 / Prior Art

该问题在其他 Agent / SDK 项目中已有完全一致的记录与修复：

• Gemini rejects $ref/$defs in function response content (400 INVALID_ARGUMENT) vercel/ai#14369：The referenced name '#/$defs/__schema0' in function_response.response does not match to a display_name in the function_response.parts
• hermes-agent#93014 / PR #93015：同样因工具返回 JSON Schema 触发 Gemini $ref 误判。

---

修复建议 / Suggested Fix

• 方案 A（推荐，Adapter 层通用兜底）：
  在将工具结果构造为 Gemini function_response.response 时，扫描对象中是否包含 JSON Schema 的 $ref / $defs 指针（如匹配 ^#/ 的 $ref）；若命中，则将返回值包装/序列化为不透明纯文本（opaque text string）回传，避免触发 Gemini 的多模态指针解析（与 vercel/ai#14369 及 hermes-agent#93015 做法一致）。

  这样可以同时保护 cordis_inspect_query 以及任何未来可能返回 JSON Schema 的 MCP / 内置工具。

• 方案 B（工具层最小改动）：
  在 @deepseek-ai/dsh-tool-cordis 返回 schema 前将 loaderExpression 内联展开（dereference），或将 schema 字段直接序列化为 JSON 字符串。

[PerryLink]

根因链的前半段我核到了，而且比你写的更具体一点；但**"改成不返回 schema" 不是唯一的修法**，还有一处更便宜的位置。

已核实

packages/extensions/tool-cordis/src/config.ts:117：

$defs: { ...definitions, loaderExpression: LOADER_EXPRESSION_SCHEMA },

:90 的文档也自陈这是「JSON Schema 2020-12 document whose $defs carry the shared and loaderExpression definitions」。LOADER_EXPRESSION_SCHEMA 从 @deepseek-ai/dsh-app-boot 导入（同文件 :6）。所以工具结果里确实带 $defs，$ref: "#/$defs/loaderExpression" 也确实会出现在返回值里 —— 这一步你说得对。

但时间线要说清：坏的不是这一轮，是下一轮

cordis_inspect_query 正常返回、工具调用成功；问题在于这段 JSON 被写进会话历史，下一轮作为 function_response 重放给 Gemini 时才炸。所以你观察到的"触发之后每一轮都 400"是必然的：历史只增不减，那条 $ref 永远在重放队列里。这也解释了为什么换个会话就好 —— 是会话级污染，不是进程级。

三个修法，我按代价排序

1. （最便宜）把 $ref 内联掉，只在这一条工具的输出上。 $defs 里那几份定义是有限集合（definitions + loaderExpression），在 toJson() 之前做一次 $ref → 目标对象 的替换即可，输出体积略增，语义完全不变。Gemini 拿到的仍是完整 schema，只是没有引用。

2. （次便宜）把 schema 从"返回值"挪到"工具描述"。 这是 schema 该在的地方 —— cordis_inspect_query 的职责是"查询配置"，返回一个 schema 文档属于把类型信息塞进数据。改法上它可以返回摘要 + 一个句柄，schema 通过工具定义暴露。代价是改契约，所有消费方要跟着改。

3. （要动宿主）让工具结果在投影时做 $ref 消解。 通用但要区分内容类型，风险最大。

我倾向 1：它能立刻止血，而且不需要改 cordis_inspect_query 的语义；2 是正确方向但属于后续整理。

两个要注意的点

• 你写的 LOADER_EXPRESSION_SCHEMA 来自 dsh-app-boot 是对的，但 definitions（...definitions 那个）来自配置投影器，两部分都要遍历，别只处理 loaderExpression 一个引用。
• 报告里建议明确写「这是 Gemini 原生 function_response 结构化回传路径特有的」——如果哪天这条路改成把结果当文本塞进去，这个 bug 会自己消失，但那时也会丢掉其它结构化能力。说清"被什么机制引爆"，比说"某个字段有毒"更容易被受理。

最后一个提醒：这个缺陷的严重度在于不可自救 —— 用户没有任何手段让一个已经中毒的会话恢复，只能弃会话。这一点值得单独强调，它是这条报告真正的分量。

[angel12538]

补充一条相邻证据：同一个 $ref / $defs 家族，但触发在工具声明侧，比本贴描述的路径更早，也更彻底。

与本贴的区别

	本贴 #10167	本条补充
触发位置	function_response.response（工具返回的结果）	functionDeclarations[].parameters（工具的定义）
报错原文	The referenced name '#/$defs/...' ... does not match to a display_name	Unknown name "$ref" at 'tools[0].function_declarations[0].parameters...'
引爆时机	调用 cordis_inspect_query 之后，历史重放时才炸	第一轮请求就 400，一个工具都不用调

也就是说：会话里只要挂着一个 schema 含 $ref / $defs / additionalProperties 的 MCP 工具（例如 REA，一百多个工具几乎全带 $defs），连「你好」都发不出去 —— 根本走不到本贴描述的那一步。因此方案 A（把工具结果序列化为不透明文本）修不到这一侧。

绕开 DSH、直接打 API 的隔离结果

直接 POST /v1beta/models/gemini-3.8-flash:generateContent，只改 tools，其余不变：

schema 关键字	结果
无工具	200
扁平 object / properties / string	200
$ref	400 Unknown name "$ref"
$defs	400 Unknown name "$defs"
additionalProperties	400 Unknown name "additionalProperties"
oneOf	200

注意 oneOf 是放行的 —— 所以社区里常见的「去掉 oneOf」并不是这里的病灶。

与其它已开议题的关联

• [Bug] mcp-client: 工具 inputSchema 缺少与 outputSchema 对称的子集规范化 #6876 [Bug] mcp-client: 工具 inputSchema 缺少与 outputSchema 对称的子集规范化
• mcp-client: one unsupported tool inputSchema keyword rejects the entire MCP server (Playwright MCP registers zero tools) #7401 mcp-client: one unsupported tool inputSchema keyword rejects the entire MCP server
• mcp-client: normalise union-typed tool parameter schemas to one type before they reach the model #9745 mcp-client: normalise union-typed tool parameter schemas to one type before they reach the model

这几条已经指出 mcp-client 缺少「按 provider 对 inputSchema 做子集规范化」。Gemini 的 functionDeclarations[].parameters 恰好是最严格的子集之一（$ref / $defs / additionalProperties 一律 Cannot find field），正是这些议题所缺校验的落点。

建议

本贴的方案 A / B 之外，在构造 functionDeclarations 时同样需要 deref $ref / $defs 并剔除 additionalProperties，或者直接复用 mcp-client 的子集规范化。

完整复现、原始报错、curl、环境版本见新帖 #10904。