dsh-llm-compat-healer

August 23, 2026 · View on GitHub

LLM 兼容自愈插件：自动检测并修复「中转/网关未正确声明模型能力」导致的请求失败（reasoning_content、developer 角色等兼容问题），并为 llm-pi-ai 配置提供完整的设置页 UI 和中文错误摘要。

解决的问题

使用中转/聚合 API（如某公益中转、某聚合网关）时，如果 provider 的模型列表没有正确声明 reasoningEfforts / compat（如 thinkingFormat: deepseek、supportsDeveloperRole: false），DeepSeek 兼容接口可能会返回：

{"message":"The reasoning_content in the thinking mode must be passed back to the API.","type":"invalid_request_error"}

（400 错误）。本插件自动检测该错误并修复配置，无需手动编辑 settings.yaml。

三层机制

  1. agent/request-error 监听（自愈）：命中规则表 → 标记问题 provider + 异步幂等补齐或校正目标兼容字段； 未命中 → 记录到「未匹配错误」队列供 UI 查看（学习机制）。
  2. agent/request 拦截（当前会话立即恢复）：对问题 provider 的请求，在发出前把 thinking 关掉——模型声明了 off 档位则设 reasoningEffort: 'off'，否则删除该字段。配置修复会保留模型的 DeepSeek 推理协议能力，使历史 assistant 消息仍能补齐 reasoning_content。对于明确拒绝 developer 角色的 OpenAI 兼容端点，自动补 supportsDeveloperRole: false，把系统提示改发为 system。无需重启。
  3. RPC + 设置页 UI：读写 llm-pi-ai 全部字段、一键补全、扫描全部补齐、查看错误日志。

功能

  • 设置页新增「LLM 兼容」分区（settings.section，id=llm-compat-healer）
  • 每个 provider 卡片：
    • reasoning 下拉
    • 按 api 显示公开 compat 字段；布尔字段支持「未设置 / 启用 / 禁用」
    • 模型行 reasoningEfforts 和模型级 compat JSON 编辑 + 一键补全
  • 顶部：「扫描全部补齐」「刷新」按钮
  • 「未匹配错误」面板：把认证/权限、用量限制、网络、模型兼容和未知上游错误归类为中文摘要，同时保留脱敏后的原始详情，支持复制和清空

可配置 compat 字段

UI 只暴露 pi-ai 明确允许部署配置的 20 个字段；字段写在 provider 的 compat 下时作为默认值，写在模型的 compat 下时覆盖 provider 默认值。

协议字段
openai-completionssupportsStore、supportsDeveloperRole、supportsReasoningEffort、supportsUsageInStreaming、maxTokensField、requiresToolResultName、requiresAssistantAfterToolResult、requiresThinkingAsText、requiresReasoningContentOnAssistantMessages、thinkingFormat、chatTemplateKwargs、supportsStrictMode、cacheControlFormat、supportsLongCacheRetention
openai-responses、azure-openai-responses、openai-codex-responsessupportsDeveloperRole、supportsStrictMode、supportsLongCacheRetention
anthropic-messagessupportsEagerToolInputStreaming、supportsLongCacheRetention、supportsCacheControlOnTools、supportsTemperature、forceAdaptiveThinking、allowEmptySignature、supportsStrictTools
bedrock-converse-streamsupportsStrictMode

reasoningEfforts 是模型级字段，支持 { "off": null, "high": "high" } 或 false。只有 off 的 efforts map 不被 Harness 接受；真正的非推理模型应使用 false。但对命中 reasoning_content 400 的 DeepSeek 兼容模型，不能使用 false，因为这会同时关闭历史消息的 DeepSeek 重放适配；自动补全会保留已有的非 off 推理档位，补上 off，必要时增加 high 作为合法能力声明，并把 provider 级 reasoning 设为 off。这样当前轮默认不思考，历史 assistant 消息仍会附带空 reasoning_content。对于没有显式模型列表的 catalog provider，页面只编辑 provider 级配置。

pi-ai 明确 withheld 的内部字段不会被本插件自动猜测或写入，例如 openRouterRouting、vercelGatewayRouting、sessionAffinityFormat、supportsToolSearch、supportsExplicitPromptCacheMode、supportsToolReferences。

数据安全与未知错误

  • 自动补全和 UI 保存均使用 settings.mutate 的 path operation；模型数组由当前完整快照生成，不会因深合并数组而丢失其他模型。
  • 「扫描全部补齐」基于同一配置快照生成全部 provider 的 path operations，并只调用一次 settings.mutate，避免首次配置热更新中断当前 RPC。统一提交失败时，需要修改的 provider 一致报告脱敏错误，原本已完成的 provider 仍报告成功。
  • config/read 对 header、token、secret 等值脱敏；UI 回写时会从当前 Host 配置恢复脱敏字段，apiKeyEnv 等环境变量名称不会被误当作密钥。
  • 未匹配错误只记录，不猜测修改配置；队列最多保留 100 条，并持久化到 profile 目录的 dsh-llm-compat-healer-errors.jsonl，诊断文本会脱敏。
  • 未知未来接口错误可以从设置页面板复制或清空；补充新规则前不会自动改变请求行为。

安装

  1. 克隆到任意开发目录
  2. 在 profile 的 node_modules 下建 junction： 
    New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-llm-compat-healer" -Target "<插件仓库的完整路径>"
  3. 在 cordis.patch.yml 追加 insert 条目： 
    - id: dsh-llm-compat-healer
  name: dsh-llm-compat-healer
  4. 重启 dsh web

开发

npm test              # 可移植测试：规则、Host/RPC、脱敏、Client 字段契约
npm run test:harness  # Harness 安装绑定测试：schema 与最终 reasoning_content HTTP 重放
npm run test:all      # 运行全部测试

安装绑定测试会优先从当前 Node 依赖树解析 @deepseek-ai/dsh-llm-pi-ai 与 @earendil-works/pi-ai。如果插件源码不在 Harness 的依赖树内，可分别设置 DSH_LLM_PI_AI_ENTRY 和 PI_AI_OPENAI_COMPLETIONS_ENTRY 为当前 Harness 安装中的完整文件路径。

验证

  • shot-lch.cjs：页面验收（UI 渲染、无 JS 错误）
  • shot-lch-scan.cjs：scan-fix 功能验收（扫描全部补齐、settings.yaml 结构保持和幂等执行）

安全

  • 事件监听器绝不原位修改 payload（经验库十七）
  • settings.mutate 只修改命中规则所需的兼容字段，并从完整快照替换模型数组；不删除或覆盖无关 provider 字段和非目标模型
  • 未匹配错误只做记录，不做任何修改

License

MIT