前言¶

在 DeepSeek Harness（DSH）里接 OpenAI 兼容端点时，常见问题不是「连不上」，而是配置细节对不上：手写 baseURL、密钥引用失效、reasoningEfforts 多配或少配导致每次请求 400、默认模型指向不存在的 provider。这些问题往往要翻 YAML、对照文档、再试一轮请求才能定位。

dsh-framework-doctor 是社区维护者 lj100886 发布的 DSH 插件（分类：模型推理），在独立设置页里完成端点探测、框架体检、对话式排查和可点击修复，并可选地在会话层做同模型跨通道 failover。插件不在后台轮询，也不自动改配置；写入均需你点击确认。

这是什么¶

插件在 Web 端增加 Settings → Framework doctor 一页，面向「把 llm-pi-ai 提供商配准、把 Harness 运行时状态查清楚」这一件事。密钥经 Harness 凭证服务保存，配置里只保留 apiKeyEnv 引用，不把明文 key 写进配置。

• 维护者：lj100886
• 目录页：https://www.skillhub.cn/plugins/lj100886/dsh-framework-doctor
• 源码：https://github.com/lj100886/dsh-framework-doctor
• 当前 package 版本：0.1.0（MIT）
• 运行要求：Node >=20.18，DSH >=0.2.0，兼容 web / desktop profile

DSH 生态是「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。安装插件前请自行查看源码与许可证，插件以当前 dsh 进程权限运行。

核心功能¶

设置页分为四块，下面按 README 已说明的能力介绍。

1. Connect a model（连接模型）¶

粘贴 endpoint URL 与 API key，点 Probe。插件请求 {baseURL}/models 拉取模型列表，并推导能力字段：

端点未声明且族表无法推断的项会留空而非猜测——错误的 reasoning-effort 映射会导致整个 provider 请求失败。表格会标明每项是端点声明还是推断。

已配置的 provider 可从下拉选择再探测：表单会回填，复用已存凭证；写入时为合并——手写模型保留，新 advertised 模型追加，能力字段由端点补全。

2. Framework checkup（框架体检）¶

对当前配置与运行时执行 23 项检查：18 项针对 llm-pi-ai provider 配置，5 项针对运行时（插件加载阶段、已注册 provider、默认模型等）。覆盖例如：缺少 baseURL、凭证引用解析为空、headers 里残留明文 key、推理模型缺少 effort 映射、非推理模型却带了 effort 映射、重复 model id、默认模型指向不存在的 provider 等。

由其他插件注册的 provider 会标为 external-provider（信息级），不因「未出现在本插件维护的配置片段」而误报缺失——以模型服务里是否注册为准。

3. Talk to the doctor（与助手对话）¶

页面提供聊天框。助手在回答前会先查真实状态，可通过六个只读工具按需取数（最多 4 轮工具往返）：

助手以 TOOL: {"name":"...","args":{...}} 请求执行；页面上会显示调用了哪些工具。凡涉及修改的建议都会渲染成按钮（重跑体检、自动修复、修复单项、探测端点、探测并写入 provider），模型不会自行改配置。

4. Repair（修复）¶

可自动修复的项可一键应用。修复通过 settings.mutate 生成，原则上只做 set； deliberate 例外包括：去掉重复 model id、对不应有 reasoning 的模型将 reasoningEfforts 设为 false。

Session failover（会话 failover）¶

当模型调用因可重试错误失败（RATE_LIMIT/QUOTA/SERVER/TIMEOUT/TRANSPORT/EMPTY_RESPONSE 等）时，插件会在已配置的其他通道上寻找同一 model id 重试，避免会话卡死。挂钩 Harness 事件 agent/request-error（决定是否 failover，返回 { kind: 'retry' } 可在同轮内重试）与 agent/request（为重试替换 provider/model）。

选择策略较保守：先同 id 的另一 provider（需有 baseURL 且已注册）；否则尝试去掉厂商前缀后的同名模型；都没有则保持原错误，不悄悄换成别的模型。失败路由进入冷却，时长随错误类型变化；端点 Retry-After 优先。可在插件行配置中开关或限制冷却：

- id: framework-doctor
  config:
    failover: true
    failoverMaxCooldownMs: 3600000

失败会记入通道健康记录；聊天区可通过 channel-health 工具查询。failover 决策本身不调用模型，说明由聊天模型事后生成。

体检页使用的模型¶

聊天区可不共用会话默认模型，可配置 fallback 链：

- id: framework-doctor
  config:
    model:
      chain:
        - provider: cheap-chan
          model: deepseek-v4.1-flash
        - provider: reliable-chan
          model: deepseek-v4.1-flash
      fallbackToDefaultModel: true

未配置 model.chain 时沿用默认模型。页面会按顺序展示解析后的链，处于冷却的跳数会变暗。

计费类失败（配额、限流）会在页面上提示，并引导到实际管理余额的页面；插件不能读取其他插件的账单详情（README 中有专门说明）。

刻意不做的事¶

• 无后台定时扫描；体检在你点击时运行。
• 无自动改配置；写入均需你在向导或助手建议按钮上确认。
• 不把明文密钥写入配置；并会检查 headers 中的明文 key。

安装与启用¶

官方安装命令如下（将 <your-profile> 换成你的 profile）：

dsh plugin --profile <your-profile> add dsh-framework-doctor

若使用本地目录（需绝对路径）：

dsh plugin --profile <your-profile> add /absolute/path/to/dsh-framework-doctor

若安装后看不到页面，重启 dsh web，再打开 Settings → Framework doctor。

典型用法¶

1. 新接一家 OpenAI 兼容网关：在 Connect 区填 base URL 与 key → Probe → 核对推断列与端点声明 → 写入 provider。
2. 老配置莫名 400：Framework checkup → 看 reasoning / 重复 id / 默认模型项 → 对可修复项点 Repair，或在 Talk 里描述现象，按助手给出的探测/修复按钮操作。
3. 多通道同一模型：开启 failover，主通道 429 时由插件在同 model id 的其他 provider 上重试；在聊天里用 channel-health 了解哪条通道在冷却、是否像计费问题。
4. 体检助手本身怕被打满：配置 model.chain，把便宜通道放前面，并视需要设 fallbackToDefaultModel: true。

适用场景与注意¶

适合：经常在 DSH 里增删改 model provider、混用多家网关、需要核对 reasoning/thinking 兼容字段的开发者；也希望在 Web UI 里完成排查而不是纯手改 YAML 的场景。

注意：

• 插件能力以 README 与当前版本行为为准；探测依赖端点 /models 与内置模型族表，推断不到的字段会留空。
• 助手建议的修复仍需你点击；不要把未审阅的 mutate 当批处理脚本。
• failover 只换通道不换模型 id，不能替代「默认模型配错」类问题的修复。
• 安装前阅读 https://github.com/lj100886/dsh-framework-doctor 源码与 MIT 许可证；插件权限等同运行 dsh 的用户/进程。

结尾¶

dsh-framework-doctor 把「探端点、查配置、对话排查、可点击修复」和可选的会话层 failover 收进一页设置界面，且默认不后台扫、不静默改配置。若要安装或看更新说明，可访问社区目录页 https://www.skillhub.cn/plugins/lj100886/dsh-framework-doctor 与 GitHub 仓库 https://github.com/lj100886/dsh-framework-doctor。