# dsh-workbuddy-provider 中文文档

规范地址：https://npmcn.com/package/dsh-workbuddy-provider/

版本：0\.2\.4
npm 元数据更新时间：2026-11-03T12:31:15.465Z
中文译文更新时间：2026-11-03T13:20:26.654Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/dsh-workbuddy-provider
原文对照：https://npmcn.com/package/dsh-workbuddy-provider/?lang=original
项目主页：https://github.com/zerolzg/dsh-workbuddy#readme
源码仓库：https://github.com/zerolzg/dsh-workbuddy

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：472 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.19\.0 \|\| \>=24\.0\.0
- 运行依赖：0 个
- peer 依赖：react ^18\.3\.1，@deepseek-ai/cordis ^4\.0\.6-alpha\.1，@deepseek-ai/dsh-llm \>=0\.2\.1-rc\.1 \<=0\.2\.1-rc\.5 \|\| \>=0\.2\.2-alpha\.2 \<=0\.2\.2-alpha\.3，@deepseek-ai/schemastery ^3\.18\.5，@deepseek-ai/dsh-settings \>=0\.2\.1-rc\.1 \<=0\.2\.1-rc\.5 \|\| \>=0\.2\.2-alpha\.2 \<=0\.2\.2-alpha\.3，@deepseek-ai/dsh-llm-pi-ai \>=0\.2\.1-rc\.1 \<=0\.2\.1-rc\.5 \|\| \>=0\.2\.2-alpha\.2 \<=0\.2\.2-alpha\.3，@deepseek-ai/dsh-attachment \>=0\.2\.1-rc\.1 \<=0\.2\.1-rc\.5 \|\| \>=0\.2\.2-alpha\.2 \<=0\.2\.2-alpha\.3，@deepseek-ai/dsh-home-paths \>=0\.2\.1-rc\.1 \<=0\.2\.1-rc\.5 \|\| \>=0\.2\.2-alpha\.2 \<=0\.2\.2-alpha\.3，@deepseek-ai/dsh-host-webserver \>=0\.2\.1-rc\.1 \<=0\.2\.1-rc\.5 \|\| \>=0\.2\.2-alpha\.2 \<=0\.2\.2-alpha\.3
- 首次发布：2026-10-31T18:52:57.731Z
- 最新版本发布：2026-11-03T12:31:15.255Z
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

将WorkBuddy桌面应用程序模型（WorkBuddy CN和WorkBuddy AI）带入DeepSeek Harness，重用每个应用程序自己的登录：没有单独的密钥，没有第二次登录。

## 安装

```sh
npm install dsh-workbuddy-provider
```

也可以使用：`pnpm add dsh-workbuddy-provider`、`yarn add dsh-workbuddy-provider`、`bun add dsh-workbuddy-provider`

## README

# dsh-workbuddy-provider

中文 · [English](https://npmcn.com/package/dsh-workbuddy-provider/README.en.md)

把 WorkBuddy 桌面 App(国内版与国际版)的模型接进 DeepSeek Harness 的插件。它复用 App 自己的登录态,不需要单独的密钥或二次登录。

## 这是什么

模型选择器里多出两个分组:**WorkBuddy CN**(国内版)与 **WorkBuddy AI**(国际版),登录了哪个就有哪一组,两个都登录则两组并存。每组列出该网关的模型目录、账户剩余积分,以及每个模型的倍率与促销活动。两个 App 的账号、积分与模型互不相通。文本、图片与工具调用都走 App 自己的通道;流式与取消直达上游,中断回复即中断计费。

模型目录取自编程客户端,不是 App 内部智能体看到的那一份:目录请求携带桌面 User-Agent 与内置 CLI 版本号,网关据此返回编程用的模型名单。插件用 App 自带的 Electron 二进制读取 App 加密的登录文件,并把副本存到 `$DSH_HOME/dsh-workbuddy-provider/`,App 关掉后请求仍能继续。

本插件的详情页里只有一张卡片,两个 App 共用:顶部两个页签切换 WorkBuddy CN 与 WorkBuddy AI,下面是登录状态与积分摘要,再往下是「模型」与「余额」两个页签。会话使用本插件的模型时,输入框旁显示一枚积分徽章。

![插件卡片:顶部切换 WorkBuddy CN 与 WorkBuddy AI,下面是登录状态、积分摘要与「模型」「余额」页签](https://raw.githubusercontent.com/zerolzg/vblog-image01/main/picgo/20261101223531897.png)

## 安装

需要已安装并登录的 WorkBuddy 桌面 App:国内版对应 WorkBuddy CN 分组,国际版(WorkBuddy AI)对应 WorkBuddy AI 分组,装一个或两个都行。仅支持 macOS。

```sh
dsh plugin --profile web add dsh-workbuddy-provider
dsh web
```

从源码检出安装时,把工作区目录本身装进 profile 即可;`plugin_manager` 会把它链接进去。

## 运行与使用

安装后 `dsh web` 启动 Harness,启动输出会打印带 token 的页面地址。之后的操作都在页面里,不用再碰命令行:

-   **选模型**:模型选择器里挑 WorkBuddy 分组下的模型,像内置模型一样发起对话。
-   **管理模型**:在插件页打开本插件的卡片,选顶部的 WorkBuddy CN 或 WorkBuddy AI 页签。「模型」页签列出该 App 目录里的全部模型,开关决定哪些出现在选择器里,按账号保存。
-   **看余额**:「余额」页签显示该 App 可用余额与构成,只在打开时查询;打开卡片会分别读取两个 App 的余额。
-   **登录态变化**:桌面 App 里登录、登出或切换账号后,插件在一个轮询周期内(默认 30 秒)自动跟随,无需重启。
-   **排除故障**:App 未安装、登录文件读不出时,卡片给出原因和一个可复制的 Agent 修复提示词;目录拉取失败时,选择器退回上次保存的目录,卡片标明来源。

进阶:状态文档与写路由挂在 Harness 源上,路径如 `/plugins/dsh-workbuddy-provider/cn/status`(国际版为 `/ai/`)。状态文档可直接 `curl` 查看;写路由(刷新目录、设置模型显隐)要求随状态文档下发的进程内密钥,没有密钥的请求一律拒绝。环回绑定是网络边界,不是授权。

适配器通过绑定在 `127.0.0.1` 的环回 shim 通信,由环回 Host 与 Origin 校验加进程内 bearer 保护。bearer 不转发到上游:上游请求带的是凭据存储里的真实凭据,拿到 bearer 也换不到它。

## 配置

### 路径解析优先级

按下面的顺序取第一个给出该路径的来源:

1.  **配置**:profile 的 `cordis.yml` 中 `dsh-workbuddy-provider.variants.<App>.authFile` / `electronBinary`
2.  **环境变量**:`WORKBUDDY_CN_AUTH_FILE` / `WORKBUDDY_AI_AUTH_FILE`、`WORKBUDDY_CN_ELECTRON_BIN` / `WORKBUDDY_AI_ELECTRON_BIN`
3.  **默认路径**:各 App 在 macOS 上的安装位置(见下表)

配置或环境变量**显式指定**的路径不可用时报错,不会静默回退到默认值:点名要用某个文件,悄悄换成另一个会掩盖问题。默认路径不存在不算错误,只报告「未安装」。点名过的路径在卡片状态区标出来源;全走默认时不显示。

### 路径默认值

| 项目 | 国内版 `workbuddy-cn` | 国际版 `workbuddy-global` |
| --- | --- | --- |
| 桌面登录文件 `authFile` | `~/Library/Application Support/CodeBuddyExtension/Data/Public/auth/workbuddy-desktop.info` | 同目录 / `workbuddy-desktop-ai.info` |
| Electron 二进制 `electronBinary` | `/Applications/WorkBuddy.app/Contents/MacOS/Electron` | `/Applications/WorkBuddy AI.app/Contents/MacOS/Electron` |
| 环境变量(登录文件) | `WORKBUDDY_CN_AUTH_FILE` | `WORKBUDDY_AI_AUTH_FILE` |
| 环境变量(Electron) | `WORKBUDDY_CN_ELECTRON_BIN` | `WORKBUDDY_AI_ELECTRON_BIN` |

两个 App 把登录文件写进同一个 `CodeBuddyExtension` 目录,只靠文件名区分。插件只读这个文件,从不写入。Electron 二进制按 bundle id 校验(`com.tencent.workbuddy.mac` / `com.workbuddy.workbuddy-ai`),路径上换成别的 App 会直接报错。

插件还从 App 包读两项不来自配置的信息,同样按 App 区分:`Contents/Info.plist` 里的 App 版本(写进模型目录与对话请求的 User-Agent),以及 `Contents/Resources/app.asar.unpacked/cli/package.json` 里内置 CLI 的版本。

### 配置文件

```yaml
dsh-workbuddy-provider:
  # 重新读取桌面登录态的频率,毫秒。默认 30000。
  credentialPollMs: 30000
  # 按 App 覆盖路径;整个 variants 段可省略,省略即全部走默认路径。
  variants:
    workbuddy-cn:
      authFile: /path/to/workbuddy-desktop.info
      electronBinary: /path/to/WorkBuddy.app/Contents/MacOS/Electron
    workbuddy-global:
      authFile: /path/to/workbuddy-desktop-ai.info
      electronBinary: /path/to/WorkBuddy AI.app/Contents/MacOS/Electron
```

只覆盖一条时,另一条仍走默认值。`variants` 下的键就是模型选择器里的 provider id:国内版 `workbuddy-cn`,国际版 `workbuddy-global`。

### 插件状态文件

插件自己写的文件全部在 `$DSH_HOME/dsh-workbuddy-provider/` 一个目录里,每个 App 一套:

| 文件 | 作用 |
| --- | --- |
| `.workbuddy-cn-auth.json` / `.workbuddy-ai-auth.json` | 凭据副本:token 刷新成功后写入,App 关闭时作为回退 |
| `.workbuddy-cn-catalog.json` / `.workbuddy-ai-catalog.json` | 按账号保存的模型目录,拉取失败时的退路 |
| `.workbuddy-cn-model-visibility.json` / `.workbuddy-ai-model-visibility.json` | 每账号的模型显隐偏好 |

`$DSH_HOME` 默认为 `~/.dsh`,可用同名环境变量覆盖。启动时会把留在 `$DSH_HOME` 根下的文件移进这个目录,显隐偏好与目录缓存因此不丢。这些文件都能直接删,只丢缓存和偏好,下次启动重新生成。

## DSH 版本兼容

本插件支持内核窗口 `>=0.2.1-rc.1 <=0.2.1-rc.5 || >=0.2.2-alpha.2 <=0.2.2-alpha.3`,也就是 0.2.1 的 rc.1 到 rc.5,加上 0.2.2 的 alpha.2 到 alpha.3,以 `engines.dsh` 声明为准。loader 只校验这一条,跳过 peer 范围检查;内核超出窗口时启动直接失败,不降级。这两条线互不同源,已知差异(路由注册形式、剪贴板 hook、模型角标透传)与不做版本探测的原则,见 `docs/adr/0002-kernel-version-window.md`。

## 已知限制

-   **仅 macOS**:App 发现、Electron 定位与登录文件默认路径都按 macOS 实现;Windows 未实现。
-   **跟随桌面 App 登录**:凭据完全来自 App 自己的登录态,没有独立的密钥可用;App 未登录时对应分组不可用。
-   **积分徽标依赖内核**:模型的限免/折扣角标在 0.2.2 alpha 内核上显示,0.2.1 rc 内核静默不显示(见兼容 ADR)。
-   **目录短于 App 内**:按价格档位排除的条目会在卡片标注「已隐藏 n 个档位」,目录以编程客户端名单为准,与 App 内智能体的名单可能不同。

## 许可证

[MIT](https://npmcn.com/package/dsh-workbuddy-provider/LICENSE) © 2026 zerolu

## 本地开发

```sh
pnpm install
pnpm run check   # lint、typecheck、覆盖率阈值、构建与 tarball 校验,改动后提交前必须全绿
pnpm run build
pnpm run watch   # 监视构建,喂给本地 dsh web server 调试
pnpm exec vitest run tests/host/<name>.spec.ts   # 跑单个测试文件
```

发布走 npm trusted publishing:改好版本号并提交后 `pnpm run tag` 生成带注释的标签,推送标签触发工作流校验并发布;细节见 `.github/workflows/release.yml`。

架构与背后的决策见 [AGENTS.md](https://npmcn.com/package/dsh-workbuddy-provider/AGENTS.md)、[GLOSSARY.md](https://npmcn.com/package/dsh-workbuddy-provider/GLOSSARY.md) 与 [决策记录](https://github.com/zerolzg/dsh-workbuddy/tree/main/docs/adr)。

[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

## 常见问题

### dsh-workbuddy-provider 是什么？

将WorkBuddy桌面应用程序模型（WorkBuddy CN和WorkBuddy AI）带入DeepSeek Harness，重用每个应用程序自己的登录：没有单独的密钥，没有第二次登录。

### 如何安装 dsh-workbuddy-provider？

在项目目录运行 npm install dsh-workbuddy-provider，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.6-alpha\.1）、@deepseek-ai/dsh-llm（\>=0\.2\.1-rc\.1 \<=0\.2\.1-rc\.5 \|\| \>=0\.2\.2-alpha\.2 \<=0\.2\.2-alpha\.3）、@deepseek-ai/schemastery（^3\.18\.5）、@deepseek-ai/dsh-settings（\>=0\.2\.1-rc\.1 \<=0\.2\.1-rc\.5 \|\| \>=0\.2\.2-alpha\.2 \<=0\.2\.2-alpha\.3）、@deepseek-ai/dsh-llm-pi-ai（\>=0\.2\.1-rc\.1 \<=0\.2\.1-rc\.5 \|\| \>=0\.2\.2-alpha\.2 \<=0\.2\.2-alpha\.3）、@deepseek-ai/dsh-attachment（\>=0\.2\.1-rc\.1 \<=0\.2\.1-rc\.5 \|\| \>=0\.2\.2-alpha\.2 \<=0\.2\.2-alpha\.3）、@deepseek-ai/dsh-home-paths（\>=0\.2\.1-rc\.1 \<=0\.2\.1-rc\.5 \|\| \>=0\.2\.2-alpha\.2 \<=0\.2\.2-alpha\.3）、@deepseek-ai/dsh-host-webserver（\>=0\.2\.1-rc\.1 \<=0\.2\.1-rc\.5 \|\| \>=0\.2\.2-alpha\.2 \<=0\.2\.2-alpha\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### dsh-workbuddy-provider 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### dsh-workbuddy-provider 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### dsh-workbuddy-provider 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.19\.0 \|\| \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### dsh-workbuddy-provider 可以商用吗？

dsh-workbuddy-provider 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### dsh-workbuddy-provider 还在维护吗？

最新版本 0\.2\.4 发布于 2026/11/03（今天）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/11/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。