前言¶
在 DeepSeek Harness（DSH）里接 workbuddy2api-panel 时，常见做法是在 ~/.dsh/profiles/<profile>/cordis.patch.yml 里为 llm-pi-ai 手写 providers.workbuddy2api.models：每个模型的 id、name、contextWindow、maxTokens 都要从面板抄一遍。面板一增删模型，配置就要重抄，漏项也不容易发现。
jerry9692/dsh-workbuddy2api-panel 是 DSH 社区目录里归类为「联网工具」的客户端插件：只读面板的 HTTP 接口，把模型列表（含倍率、国内/国际分区、思考档位）写入 DSH 的 llm-pi-ai 配置，并在设置页展示剩余额度与用量。若你只需要一个 OpenAI 兼容的 /v1 端点、不关心倍率和额度，更轻的桥接方式即可；本文介绍的是需要与面板模型、积分策略对齐时的用法。
这是什么¶
dsh-workbuddy2api-panel（npm 包名 dsh-workbuddy2api-panel，当前版本 1.0.3，MIT 许可证）由维护者 jerry9692 发布。它是客户端插件：不修改、不代理面板本身，通过 Bearer 认证调用面板的 /panel/api/*，把结果同步到 DSH 自己的 llm-pi-ai 配置（cordis.patch.yml 中插件 bundle 为 id: workbuddy-panel）。
README 写明适用面板为 workbuddy2api-panel 1.13.0-panel（实测通过）；适用 DSH 为 @deepseek-ai/dsh-desktop-runtime 0.2.0-rc.2（与 llm-pi-ai、dsh-settings、dsh-credentials 按该版本对齐）。运行环境要求 Node >=20（CI 徽章标注 20 / 22 / 24）。
核心功能¶
下面按 README 已描述的能力归纳，不涉及未在资料中出现的功能。
模型同步¶
- 从面板
GET /panel/api/models拉取模型（cn:/global:前缀、倍率、思考档位、上下文等）。 - 按你在设置页的勾选，重写
providers.workbuddy2api下的models数组；选择器中的名称会带上分区与倍率，例如Deepseek-V4.1-Flash · 国内版 · ×0.11。 - 默认每 2 分钟自动同步一次，面板增删模型后无需重启 DSH（改插件配置、改模型选择 likewise）。
- 可为每个模型单独关闭某一思考档位；倍率展示以面板
credits（促销倍率优先）为准。
插件会为局域网 baseURL 显式写入 compat: { supportsReasoningEffort: true, thinkingFormat: 'openai' }，避免 pi-ai 误判导致 reasoning_effort 静默失效。
连接与嗅探¶
设置页 WorkBuddy 面板 卡片支持：
- 多行面板地址，按顺序试连，第一个可用即采用；支持自动纠正
192.168.x.x:7863、http://…/v1、http://…/panel等形式，行尾可加超时秒数。 - 自动探测：依次尝试已填地址、当前主机 + 7863、
127.0.0.1:7863、localhost:7863。 - API Key 存入 DSH 凭据库，引用名与 llm-pi-ai 一致：
WORKBUDDY2API_API_KEY；留空可沿用已有环境变量或凭据。面板auth_required: false时可留空。 - 若插件尚未保存地址，首次启动会读取你已有
cordis.patch.yml里的providers.workbuddy2api.baseURL与apiKeyEnv。
额度、用量与告警¶
- 剩余额度：按国内版/国际版汇总积分与账号健康状态（数据来自
/panel/api/overview、/panel/api/packages）。 - 用量：请求数、积分消耗、缓存命中率、延迟，及按模型统计（
/panel/api/usage?hours=N，支持 24h / 72h / 168h）。 - 顶部告警条：Key 失效（401/403）、面板连续不可达、域额度不足、积分包即将到期等；底部「策略」可配置新上架模型默认勾选行为、额度不足标注、清除插件写入的配置等。
侧边栏徽标¶
挂在宿主 sidebar.footer.action 插槽：显示 WB 与状态圆点，点击弹出分域剩余、告警数、面板版本等；展示模式（剩余/总额、分域、仅剩余、隐藏）可在策略里切换，与设置页通过 bundle 内 store 同步，不必等 60 秒轮询。
安装与启用¶
官方安装命令（来自 README）：
dsh plugin --profile desktop add dsh-workbuddy2api-panel
dsh plugin add 会把包写入 profile 的 dependencies 和 dsh.profile.bundles，并加载插件自带的 cordis.patch.yml。首次安装后需重启一次 DeepSeek Harness 以加载宿主侧代码；之后改插件配置或模型选择一般不需要重启。
本地开发可用 link 方式（路径换成你的 clone 目录）：
dsh plugin --profile desktop add "link:$PWD"
卸载：
dsh plugin --profile desktop remove dsh-workbuddy2api-panel
临时停用可在 cordis.patch.yml 中为该 bundle 设置 disabled: true 后重启。
插件以当前 DSH 进程权限运行，安装前建议查看 GitHub 仓库 源码与 MIT 许可证，并理解 README「安全模型」一节：写接口 /workbuddy-panel/api/* 依赖本机回环、同源与 JSON 三道校验；DSH 若绑定到 0.0.0.0 或经反向代理对外暴露时，需在代理层自行加固。
典型用法¶
1. 连接并首次同步¶
- 重启 DSH 后打开 设置 → WorkBuddy 面板。
- 在「面板地址」填写可访问的地址（例如
http://192.168.1.10:7863），按需填写面板 API Key（或与现有WORKBUDDY2API_API_KEY共用）。 - 点「保存并同步」或启用「自动探测」；确认「自动同步到 DSH」为开启时，模型会写入 llm-pi-ai。
- 面板默认模型较多，README 建议首次先「全不选」，再勾选常用模型，避免选择器过长。
2. 日常维护¶
- 面板变更模型后，等待自动同步或手动保存即可；下架模型有 24 小时宽限期，显示
· 已下架。 - 在「额度与用量」查看各域积分与 72 小时内消耗；侧边栏徽标可快速扫一眼剩余情况。
- 若只需清空插件写入的 provider 配置，使用策略区的「清除插件写入的配置」（需两次确认）。
3. 与手写配置的对比¶
装插件前，典型片段类似：
- id: llm-pi-ai
config:
providers:
workbuddy2api:
baseURL: http://192.168.1.10:7863/v1
apiKeyEnv: WORKBUDDY2API_API_KEY
models:
- id: cn:deepseek-v4.1-flash
name: Deepseek-V4.1-Flash
contextWindow: 1000000
maxTokens: 393216
# ……面板有 50 多个模型，得一个个抄
装插件后，models 由面板 API 驱动维护；provider 键固定为 workbuddy2api，状态文件为 workbuddy-panel.json（不含 API Key 明文）。
适用场景与注意¶
适合：
- 本机或局域网内已部署 workbuddy2api-panel，且 DSH 所在机器能访问面板 HTTP 接口。
- 需要在 DSH 模型选择器里直接看到国内/国际分区、积分倍率，并要在 Harness 内查看账号池额度与用量，而不是只填一个
/v1baseURL。
注意：
- 面板 API Key 同时保护
/v1/*与/panel/api/*，权限面大，勿外泄。 - 插件只维护
providers.workbuddy2api，不会修改agent-default-model；若默认模型已在面板删除，DSH 仍会报模型不存在，需自行改默认项。 - 面板字段或接口变更时，插件需随 workbuddy2api-panel 版本调整（依赖接口见 README「依赖的面板接口」表）。
- DeepSeek Harness 生态强调「一切皆插件」；SkillHub 目录页 为社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-workbuddy2api-panel 把 workbuddy2api-panel 的模型元数据与运营侧额度、用量搬进 DSH 设置界面，省掉手写 cordis.patch.yml 里长 models 列表的维护成本。安装命令为 dsh plugin --profile desktop add dsh-workbuddy2api-panel，首次装完重启一次即可按上文连接面板并开始同步。
