快速结论:当 Dify Agent 的结构化输出 schema 在根 $defs 中使用带 /、~ 或百分号编码字符的定义名,并通过 JSON Pointer 转义形式(如 Widget~1Info)引用时,契约构建会报 ValueError: Local $ref '#/$defs/Widget~1Info' could not be resolved from $defs.。较常出问题的是本地 $ref 解析逻辑没有按 JSON Pointer 规则解码,而把它当成字面量 `$defs` 键名去查找。
适用环境:Dify 自托管(源码方式),版本为 main 分支 commit f318dd01;问题定位在 dify-agent/src/dify_agent/layers/output/output_layer.py 的 _inline_local_defs_refs()。Issue 未提供操作系统、Python、CUDA 或显卡信息。
最快修复方案:暂无确认的一步修复方案。Issue 讨论中给出的临时绕过方式是改 schema:把定义名改为不含特殊字符的 WidgetInfo,引用同步改为 #/$defs/WidgetInfo,避开解码路径。该绕过为推测性方案,可优先尝试。
注意事项:改名会改变 schema 结构,可能影响下游依赖定义名的逻辑;绕过方案作者也说明未实际执行复现。真正的修复需要让解析器按 JSON Pointer 解释片段,并同时处理 /、~、百分号编码字符,以及定义名中字面量 ~1 的情况,避免双重反转义。
问题场景
用户在 Dify Agent 中配置结构化输出(structured-output)schema,根 $defs 里有一个带特殊字符的定义名,例如 Widget/Info,并在属性中用 JSON Pointer token Widget~1Info 引用它。在构建结构化输出契约或启动 Agent 运行该 schema 时触发报错。
报错原文
ValueError: Local $ref '#/$defs/Widget~1Info' could not be resolved from $defs.
Issue 正文同时说明:名称中包含 ~ 以及包含百分号编码片段字符时,也会出现同样的失败。
原因分析
Discussion 指出问题定位在 dify-agent/src/dify_agent/layers/output/output_layer.py 的 _inline_local_defs_refs():该函数去掉前缀 #/$defs/ 后,直接把剩余文本当作 $defs 的键名查找。因此 Widget~1Info 被当作字面键名,而不是先按 JSON Pointer 规则反转义成 Widget/Info。该路径上缺少百分号解码和 JSON Pointer 反转义,属于可能原因。
环境排查
- 确认 Dify 是否为源码自托管部署,并核对当前代码是否包含
dify-agent中output_layer.py的相关实现。 - 检查结构化输出 schema 的根
$defs键名是否包含/、~或百分号编码字符。 - 检查对应的
$ref是否使用了 JSON Pointer 转义(如~1表示/、~0表示~)。 - Issue 未提供 Python、CUDA、PyTorch、显卡或依赖版本信息,无需据此核对。
解决步骤
- 先确认报错来自本地
$ref解析:在 schema 中找到形如#/$defs/...的引用和对应$defs键名。 - 作为临时绕过(可优先尝试,未经验证):把定义名改为仅含普通字符的名称,例如
WidgetInfo。 - 同步更新所有引用该定义的位置,例如将
"$ref": "#/$defs/Widget~1Info"改为"$ref": "#/$defs/WidgetInfo",使引用与字面键名一致。 - 重新构建结构化输出契约或启动 Agent 运行,确认不再触发该 ValueError。
- 如需根本解决,需等待或提交代码修复:让解析器把 fragment 作为 JSON Pointer 解码,而不是直接用作定义名;回归测试应覆盖
/、~、百分号编码字符,以及定义名中字面量~1的场景,防止双重反转义。
验证方法
使用改名后的 schema 重新构建结构化输出契约并执行一次 Agent 运行,确认不再出现 could not be resolved from $defs 错误,且引用对象的结构(如 id 字段及其 required 约束)按预期生效。若要保持原始定义名,则需在修复后的代码上验证 Widget~1Info、含 ~ 的名称及百分号编码引用均可正确解析。
参考来源
AI 工具推荐
想把多个 AI 模型放在一个入口?
GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。
推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。
这个方案解决了吗?
可以继续搜索完整报错,或查看同一工具的其他排查指南。
![[Bug]: Groq 401 "Invalid API Key" is mapped to BadRequestError (stored as 400_INVALID_REQUEST)](https://www.chat-gpts.plus/wp-content/uploads/2026/11/51994-9ccf2e47-768x403.jpg)

![[Chore/Refactor] remove redundant-cast](https://www.chat-gpts.plus/wp-content/uploads/2026/11/24645-14ddc40c-768x403.jpg)