前言¶

在 DeepSeek Harness（DSH）里跑智能体时，上游一旦返回 401 或 403，客户端会把错误归类为 AUTH，界面统一显示「API 密钥无效」。token 过期、会话失效、目录需要重新探测等真实原因都被同一句文案盖住了，开发者只能猜是哪家 provider 出了问题、手动去续期。

dsh-api-heal 是社区插件，监听认证类失败，按 provider 调用各自的续期入口，再让 agent loop 原地重发请求；多数情况下用户看不到报错。下面介绍它的定位、能力与安装方式。

这是什么¶

• 名称：dsh-api-heal（npm 包名同目录名）
• 维护者：YSwo-fei
• 分类：admin-security（SkillHub 目录）
• 版本：0.1.0（MIT）
• 仓库：https://github.com/YSwo-fei/dsh-api-heal

插件不改 DSH 本体，也不改那句「API 密钥无效」的文案；它在错误冒到 UI 之前尝试修好凭据链，并暴露只读状态路由与手动工具供模型或运维调用。

核心功能¶

自动自愈¶

监听 agent/request-error。失败若像认证问题，就地对对应 provider 重新续期或重取凭据，返回 { kind: "retry" }，让 agent loop 原地重发同一个请求。

可通过 profile 里 cordis.patch.yml 关闭自动行为（autoHeal: false），此时仍可使用手动工具。

手动工具 heal_api¶

模型或脚本可主动调用。可选参数 provider：qoder、workbuddy-ai、our-free-model；不传则三家依次处理。

状态路由¶

只读：GET /plugins/dsh-api-heal/status。路由在 DSH 进程启动时注册，重启前访问会 404。

三家 provider 的自愈动作¶

our-free-model 的 /api/our-free-model/* 挂在 connection 准入围栏后，裸 POST 会 401。插件读取 .credentials.yaml 里 client-connection/browser-session 的签名密钥，按 dsh-client-connection 同样算法（HMAC-SHA256 + base64url，payload {version:1, authority, issuedAt, expiresAt}）自铸会话 cookie，无需浏览器或已登录 Web 会话。

安装与启用¶

官方 README 面向 Windows：本机 PowerShell 5.1、执行策略 RemoteSigned 时，不宜直接用未签名的 install.ps1，应使用 install.cmd：

E:\DSH CODE\dsh-api-heal\install.cmd

脚本会备份 profile 的 package.json，复制插件到数据目录下的 .dsh/plugins/dsh-api-heal，以 file: 形式写入 dependencies 并加入 dsh.profile.bundles，执行 pnpm install 并做装后自检。路径以你本机克隆或解压位置为准，上例来自 README。

装完后完全重启 DSH（托盘也要退出）。验证：

GET http://127.0.0.1:19387/plugins/dsh-api-heal/status

回滚：

E:\DSH CODE\dsh-api-heal\install.cmd -Uninstall

插件以当前 DSH 进程权限运行，安装前请阅读仓库源码与 MIT 许可证，确认符合你的安全策略。Node 引擎要求：^22.19.0 || >=24.0.0（见 package.json）。

配置¶

可在 profile 的 cordis.patch.yml 中覆盖插件配置：

示例片段：

- id: api-heal
  name: dsh-api-heal
  config:
    cooldownMs: 15000
    autoHeal: true

典型用法与验证¶

不装插件，先探三家入口¶

设置 DSH_HOME 与 DSH 自带的 node.exe，在插件目录执行：

cd /d "E:\DSH CODE\dsh-api-heal"
set DSH_HOME=E:\dsh-data\.dsh
set NODE=D:\DSH\resources\runtime\primary-runtime\dependencies\node\bin\node.exe
%NODE% probe.mjs

成功时输出类似：qoder / workbuddy-ai / our-free-model 各一行 [OK] 及耗时说明。

装插件后的完整测试¶

%NODE% selftest.mjs
%NODE% smoke.mjs
%NODE% loadtest.mjs

loadtest.mjs 需从 app.asar 抽取真实依赖（README 中 stage_deps.mjs 步骤，只需一次）。

运行时若仍遇认证失败，可让 agent 调用 heal_api，或指定 provider 只修一家。

适用场景与边界¶

适合：长期开 DSH 智能体、依赖 qoder / workbuddy-ai / our-free-model 之一或多家，且偶发凭据过期导致界面统一报「API 密钥无效」的环境。

边界（README 原文要点）：

1. 只能救「流已建立之后才失败」的请求。 连接阶段就抛错（started === false）时，agent/request-error 监听器不会跑，需手动 heal_api 或重发消息。
2. probeKey 每次进程重启都会变，插件每次通过 GET .../status 现取，不硬编码。
3. 自动自愈默认 60 秒冷却，同一错误短时间内不会疯狂打上游。
4. our-free-model 的 cookie 用本机 .credentials.yaml 密钥签名，仅在 127.0.0.1 使用，不落盘、不外发。

DSH 生态强调「一切皆插件」；SkillHub 等社区目录独立于 DeepSeek / 幻方，本文介绍的是社区维护的 admin-security 类插件，非官方应用商店条目。

结尾¶

dsh-api-heal 把被 UI 吞掉的认证失败拆回三家 provider 的可执行续期步骤，并在 agent loop 里自动重试，减少误读「API 密钥无效」带来的排查成本。目录与源码：

• SkillHub：https://www.skillhub.cn/plugins/YSwo-fei/dsh-api-heal
• GitHub：https://github.com/YSwo-fei/dsh-api-heal