API Hub

跑在 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 <tgz 路径>），把 "dsh-api-hub" 加进该 profile package.json 的 dsh.profile.bundles，重启。

三分钟上手

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

接口页

整理

拖动卡片排序；双击卡片标题改名（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 <0.3.0-0" }

DSH 安装时会拿它和运行时版本比对，不满足直接拒绝安装（incompatible-version），不会先装进去再出问题。所以这个范围写保守：只在真的对着新版跑过之后才放宽。

面板页头右上角显示 DSH <版本> · v<插件版本>，悬停可看声明的范围；对不上时页头下方出一条红字，而不是让接口悄悄调不通。数据来自 /api/health 的 plugin 与 dsh 字段（dsh.version 为 null 表示当前环境读不到，此时不报警）。

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

npm run check:dsh
# ok: @deepseek-ai/dsh@<版本> satisfies engines.dsh ">=0.2.1-rc.2 <0.3.0-0"

它去 registry 取 @deepseek-ai/dsh 的 latest，用与 DSH 同一套规则比对：落在范围外就以非零退出码失败（提示先手工装新版试一遍再放宽）；网络不通只警告，不判红。

主题

面板的颜色全部是 CSS 变量（--ahb-*），浅色在 body、深色在 body[data-ds-dark-theme] 各给一份。DSH 切换主题时浏览器直接重算，不需要监听事件或重建组件。

为什么入口在侧边栏，而不是设置页

DSH 的设置页导航图标按分区 id 硬编码，第三方分区一律回退成齿轮，且 settings.section 没有 icon 字段；而 sidebar.panellist 的第二个参数就是图标组件。所以本插件只注册侧边栏席位，不在设置页留一个重复条目。上游需求整理在 docs/upstream/settings-section-icon.md。

数据存在哪

全部在 ~/.dsh/api-hub/（随 $DSH_HOME 走），都不进版本库：

文件	内容
`providers.json`	注册表：服务商、默认项、模型选择、缓存
`keys/<id>.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.<ref>`，写入交给 `ctx.credentials`（持锁、原子落盘、广播更新）
`json`	任意 JSON 文件的某个字段（`path` + `jsonPath`）
`env`	环境变量名，适合从 shell 传 Key
面板添加的接口	`~/.dsh/api-hub/keys/<id>.json` 的 `apiKey`

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

providers.json 参考

{
  "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 未验证

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

文档

变更记录
故障排查
安全说明 — 回环与鉴权的取舍，如何私下报告问题
发布指引 — npm 发布与版本流程（维护者用）
上架材料 — 插件市场 PR 的条目内容与要求
上游需求 — 让设置分区支持自定义图标

License

MIT

API Hub

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

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"，手动删掉再重启

三分钟上手

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

接口页

整理

拖动卡片排序；双击卡片标题改名（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 <0.3.0-0" }

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

npm run check:dsh
# ok: @deepseek-ai/dsh@<版本> satisfies engines.dsh ">=0.2.1-rc.2 <0.3.0-0"

主题

为什么入口在侧边栏，而不是设置页

数据存在哪

全部在 ~/.dsh/api-hub/（随 $DSH_HOME 走），都不进版本库：

文件	内容
`providers.json`	注册表：服务商、默认项、模型选择、缓存
`keys/<id>.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.<ref>`，写入交给 `ctx.credentials`（持锁、原子落盘、广播更新）
`json`	任意 JSON 文件的某个字段（`path` + `jsonPath`）
`env`	环境变量名，适合从 shell 传 Key
面板添加的接口	`~/.dsh/api-hub/keys/<id>.json` 的 `apiKey`

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

providers.json 参考

{
  "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 未验证

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

文档

变更记录
故障排查
安全说明 — 回环与鉴权的取舍，如何私下报告问题
发布指引 — npm 发布与版本流程（维护者用）
上架材料 — 插件市场 PR 的条目内容与要求
上游需求 — 让设置分区支持自定义图标

License

MIT

Limooning/DSH-API-Hub

API Hub

它是什么形态

安装

三分钟上手

接口页

技能页

和 DSH 的关系

模型自动接入，没有按钮

兼容范围

主题

为什么入口在侧边栏，而不是设置页

数据存在哪

Key 存哪里

providers.json 参考

开发

目录结构

已知限制

文档

License

Community comments

Limooning/DSH-API-Hub

API Hub

它是什么形态

安装

三分钟上手

接口页

技能页

和 DSH 的关系

模型自动接入，没有按钮

兼容范围

主题

为什么入口在侧边栏，而不是设置页

数据存在哪

Key 存哪里

providers.json 参考

开发

目录结构

已知限制

文档

License

Community comments