DeepSeek HarnessHub
플러그인 제출

Limooning/DSH-API-Hub ↗★ 1

dsh-api-hub

API Hub — manage and call local API providers (keys, models, balances) and skills from inside DeepSeek Harness 适合需要统一管理多平台API密钥、模型路由及技能的DSH用户。

스킬금융 데이터
패키지
dsh-api-hub
호환성
미검증
Cordis peer 범위
~4.0.5
버전
0.8.3
라이선스
MIT
최근 업데이트
2026. 10. 24.

설치

$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:Limooning/DSH-API-Hub

문서

전체 README 읽기 ↗

API Hub icon

API Hub

npm CI License: MIT

跑在 DeepSeek Harness 里的本机 API 与技能管理台。

散在各个配置文件里的服务商——官方的、中转的、云厂商的——收进同一个面板：看余额、改 Key、选模型、测连通、发调试请求；顺手管理 DSH 会加载的技能。面板里启用的对话接口会自动变成 DSH 自己的模型路由，在对话的模型选择器里直接可选。

API Hub 面板

它是什么形态

侧边栏里的一行 + 一个原生 React 页面，后端逻辑跑在 DSH 进程内，挂在 DSH 自己的 HTTP 服务 /api-hub 下：

  • 不额外开端口、不起子进程、不加载任何网页、没有 iframe
  • 颜色全部来自 CSS 变量，深色 / 浅色各一份，跟着 DSH 的主题设置一起切
  • 运行时数据都在 ~/.dsh/api-hub/，仓库里没有任何密钥

package.json 里的 dsh.client.platform: "web" 是 DSH 对「客户端插件」的称呼，指跑在渲染进程里，不是「这是个网页」。

安装

dsh plugin 会把包装进 profile，并自动把包名登记到该 profile 的 dsh.profile.bundles：

dsh plugin --profile desktop add dsh-api-hub          # 从 npm
dsh plugin --profile desktop add C:\path\dsh-api-hub-.tgz   # 从 Release 附件
dsh plugin --profile desktop add link:C:\path\to\DSH-API-Hub      # 从源码，改动即时生效

装完重启 DSH，左侧边栏「插件」下方出现 API Hub。Windows / macOS 命令相同，只有路径写法不同。

卸载：

dsh plugin --profile desktop remove dsh-api-hub
# 若 profile 的 dsh.profile.bundles 里仍留着 "dsh-api-hub"，手动删掉再重启

不用 CLI 的话：cd ~/.dsh/profiles/desktop，pnpm add link:（或 pnpm add ），把 "dsh-api-hub" 加进该 profile package.json 的 dsh.profile.bundles，重启。

三分钟上手

  1. 打开左侧边栏的 API Hub
  2. ＋ 添加接口：填 Base URL 和 Key → 自动拉模型目录，每个模型旁标出能力（文本 / 视觉 / 图片 / 视频 / 语音 / 向量）→ 勾选要开放的模型 → 保存。类型不用选，按勾中的模型自动显示
  3. 回到对话，在模型选择器里就能看到这个接口了

接口页

整理

  • 拖动卡片排序；双击卡片标题改名（id 与 Key 文件不动）
  • 启用 / 停用：停用只淡化正文，标题和开关保持清晰
  • 接口多了只滚列表：页头与标签页固定，滚到底不会带着整个设置页一起走
  • 类型标签按能力分列：文本 视觉 图片 视频 语音 向量，多模态写成「文本 · 视觉」
  • 视觉 是实测出来的：添加时真的发一张 16×16 纯红图问「什么颜色」，答得出来才标上；悬停能看到是实测通过、实测失败，还是仅按名字推断

密钥与连通

  • Key 掩码显示在卡片上，双击就地改：粘贴后 Enter 保存，Esc 取消；失败时输入框保留并显示服务端原话
  • .toml / .env 里的 Key 只读不写，会提示你直接改原文件
  • 测试连接：用真 Key 请求一次模型目录，显示状态码 / 耗时 / 模型数
  • 查余额：按 balance 配置查询；没有余额接口的服务商显示 —，不编造数字

模型与默认

  • 模型：拉目录、勾选允许的模型、单选默认模型
  • 默认：点一下设为默认，再点取消；文本与图片各有一个默认
  • 只把这些勾选过的对话模型交给 DSH（见下文）

调试

  • 请求：GET / POST + JSON 请求体，带 Key 直发，显示状态码、耗时、响应体
  • 移除：确认后移出面板，面板自己管理的 Key 文件一并删除

检索本机

只列本机已有、面板里还没有的接口与技能：

  • 自动扫描只覆盖 DSH 自己的目录——凭据库 refs、环境变量里的 *_API_KEY / *_KEY、$DSH_HOME 下的 JSON / TOML / .env
  • 放在别处的（D 盘、别的工具目录）用「扫描范围 → 手动导入」加一次路径；Key 仍留在原文件，只记录位置与字段
  • 调通才允许导入：每行都会拿它的 Key 真打一次接口，2xx 才点亮「导入」；调不通直接显示原因（Key 被接口拒绝（HTTP 401）、Base URL 不对、连不上），服务端写入前还会再验一次
  • 鉴权头按实测结果定：Authorization: Bearer 被 401/403 拒掉时改试 x-api-key / api-key，能通的写法记在 provider 上
  • Anthropic 原生（/v1/messages）与 Gemini 原生（models?key=）会明确告知「面板只调 OpenAI 兼容接口」，不假装成功

技能页

  • 列出 DSH 会加载的全部技能：$DSH_HOME/skills、$DSH_AGENTS_HOME/skills，以及已打开项目里的 .dsh/skills、.agents/skills——同一 id 以优先级高的根为准，与 DSH 的加载顺序一致
  • 只读范围：项目和 ~/.agents 里的技能带「只读」标记，面板不启停、不删除，只动 $DSH_HOME/skills 里的
  • 名字不合规会提示：DSH 只加载 ^[a-z0-9]+(-[a-z0-9]+)*$ 的 name:
  • 拖动排序：顺序存在 ~/.dsh/api-hub/skill-order.json，新技能排在已排序的后面
  • 双击改名：只改 SKILL.md 顶部的 name:，描述与正文原样保留，行尾跟随文件（CRLF / LF）
  • 打标签分类：最多 12 个标签，存在 ~/.dsh/api-hub/skill-tags.json，不动技能目录；顶部可按标签筛选，包括「未分类」
  • 查看 SKILL.md 原文、启停（在 skills/ 与 skills/.disabled/ 之间移动）、删除

和 DSH 的关系

模型自动接入，没有按钮

每次拿到新状态，面板都会和 DSH 的 llm-pi-ai 设置章节比一次：

  • 启用中的对话接口注册成 DSH 的模型路由，写完 DSH 自己校验并热加载
  • 只有不一致时才写一次；停用或删掉的接口会从 DSH 模型列表里一并撤掉
  • 你在「设置 → 模型」里手加的 provider 不会被碰：只动面板自己拥有的那几条
  • 只接你勾选过的对话模型；图片 / 视频 / 语音 / 向量按名字分类后排除
  • Key 通过 DSH 凭据服务落成 ref，不落到配置文件里

兼容范围

package.json 声明了 engines.dsh：

"engines": { "dsh": ">=0.2.1-rc.2  · v`，悬停可看声明的范围；对不上时页头下方出一条红字，而不是让接口悄悄调不通。数据来自 `/api/health` 的 `plugin` 与 `dsh` 字段（`dsh.version` 为 `null` 表示当前环境读不到，此时不报警）。

发布前和每周一 CI 都会跑：

```powershell
npm run check:dsh
# ok: @deepseek-ai/dsh@ satisfies engines.dsh ">=0.2.1-rc.2 .json` | 面板添加的接口的 Key |
| `dsh-routes.json` | 面板写进 DSH 的路由清单（用来判断能否安全撤掉） |
| `skill-order.json` | 技能排序 |
| `skill-tags.json` | 技能标签 |
| `scan-sources.json` | 手动添加的扫描位置 |

首次运行时 `providers.json` 不存在会自动从包内的 `providers.example.json` 复制一份（只含 DeepSeek 官方）。

### Key 存哪里

由 `keySource.type` 决定，面板只负责读写：

| 类型 | 位置 |
|---|---|
| `dsh-credentials` | DSH 凭据库的 `refs.`，写入交给 `ctx.credentials`（持锁、原子落盘、广播更新） |
| `json` | 任意 JSON 文件的某个字段（`path` + `jsonPath`） |
| `env` | 环境变量名，适合从 shell 传 Key |
| 面板添加的接口 | `~/.dsh/api-hub/keys/.json` 的 `apiKey` |

写入是就地更新：`refs` 之外的记录、JSON 的其它字段与缩进风格都保留，值没变时文件逐字节不变。

### providers.json 参考

```jsonc
{
  "defaults": { "llm": "deepseek-api", "image": null },
  "providers": [
    {
      "id": "deepseek-api",
      "name": "DeepSeek 官方",
      "kind": "llm",                          // llm | image
      "enabled": true,
      "baseURL": "https://api.deepseek.com",
      "protocol": "OpenAI Responses",         // 仅展示
      "keySource": { "type": "dsh-credentials", "ref": "DEEPSEEK_API_KEY" },
      "test": { "method": "GET", "path": "/models" },
      "defaultModel": "deepseek-flash",
      "balance": {
        "method": "GET",
        "path": "/user/balance",
        "extract": ["balance_infos", 0, "total_balance"],
        "currency": "CNY",
        "label": "账户余额"
      }
    }
  ]
}
字段含义
enabled是否启用；缺省视为启用
selectedModels允许调用的模型 id；不写 = 全部
defaultModel默认模型，必须在 selectedModels 里
balance余额查询，extract 是从响应 JSON 取值的路径
modelsCache拉取模型后的缓存（面板自动写入）

开发

不需要构建：

改什么生效方式
lib/server.mjs（后端）宿主按 mtime 自动重新 import，刷新页面即生效
lib/client.js（界面）保存后刷新；没变化就重启 DSH（客户端模块图在启动时确定）
lib/index.js（宿主半侧）需要重启 DSH
node --check lib/server.mjs
node --check lib/index.js
node --check lib/client.js
npm test          # 每个用例在子进程里用一次性 HOME 跑，不碰你的数据
npm run check:dsh # 声明的 DSH 范围是否还覆盖最新发布

CI 在 Windows / macOS / Linux × Node 20/22 上跑同一套检查，外加一个每周的 dsh-compat 任务（.github/workflows/ci.yml）。

想在不碰日常环境的前提下试：复制一个 profile，装好插件后 dsh --profile lab --port 17899 --no-open。

目录结构

仓库根目录就是 npm 包：

package.json                插件清单：dsh.bundle.patch + dsh.client + engines.dsh
cordis.patch.yml            自带 patch 层，插入 api-hub-plugin 条目
lib/index.js                宿主半侧：挂路由、注入 origin、把 DSH 服务接给后端
lib/client.js               客户端半侧：侧边栏入口 + 原生面板
lib/server.mjs              后端：providers / 余额 / 模型 / 技能 / 检索 / 接入 DSH
scripts/check-dsh-compat.mjs 发布前的兼容性检查
test/smoke.test.mjs         一次性 HOME 里的冒烟测试
providers.example.json      注册表示例，首次运行自动复制
assets/icon.svg             枢纽标记（纯色，跟随主题）

已知限制

  • 设置页没有入口：图标只能是齿轮，所以只保留侧边栏入口
  • 没有配置 schema：刷新间隔等仍是代码里的常量，未接入 cordis.patch.yml 的 config
  • 依赖 webServer 服务：拿不到该服务时面板无法工作，不会退化成子进程
  • 本地回环、无鉴权：只挂在 127.0.0.1 上，外部机器连不上；但同一浏览器里的网页能读 /api-hub/api/* 的响应（CORS 通配）。不要把 DSH 绑到 0.0.0.0 后暴露在不可信网络里——那种场景需要额外的 token 校验，目前没有
  • 只在 Windows 上实测过：代码无平台分支，macOS 未验证

遇到「面板打不开 / 显示找不到面板服务」，见 故障排查。

文档

License

MIT