dsh-llm-codebuddy

Readme

# DSH CodeBuddy Provider

为 DeepSeek Harness（DSH）增加 `CodeBuddy 中国区` Provider。支持 WorkBuddy
API Key 和 CodeBuddy 中国站账号令牌两种认证方式，并可在 DSH WebUI 中获取、
选择和调整模型。

> [!IMPORTANT]
> API Key 由 **WorkBuddy** 提供，本插件使用该 Key 调用供 CodeBuddy 使用的模型服务。
> DSH 中的 Provider 名称仍为 `CodeBuddy 中国区`。本项目是第三方适配器，并非
> WorkBuddy、CodeBuddy 或 DSH 官方插件。

## 功能

- WebUI 中直接添加 `CodeBuddy 中国区`；
- 支持从 WorkBuddy 获取的 API Key；
- API Key 输入框旁可显式切换 `API Key` / `令牌登录`；
- 支持从 WebUI 拉起浏览器登录 CodeBuddy 中国站，并自动复用、刷新登录令牌；
- 自动获取 CodeBuddy 当前可用模型；
- 支持编辑模型 ID、名称、上下文窗口和最大输出 Token；
- 支持添加、删除模型以及重新同步模型目录；
- 按模型目录声明各模型自己的思考能力、可选档位和默认档位；
- 输入新 API Key 可替换旧值，留空保存则保留原值；
- 模型接口暂时不可用时使用内置目录兜底；
- 独立安装，不修改 DSH 全局安装目录。

## 环境要求

- Windows、Linux 或 macOS；
- Node.js `>= 22.19.0`；
- 已安装 DSH；
- 已验证 DSH `0.1.0-rc.6`。

安装器已自带 DSH 所需的 `pnpm`，无需全局安装；令牌登录也不需要安装 CodeBuddy CLI。

> DSH 仍处于预发布阶段。未来版本如果调整插件接口，本插件可能需要同步升级；
> DSH 普通更新不会覆盖本插件。

## 安装

推荐使用一键安装命令：

```powershell
npx --yes dsh-llm-codebuddy@latest install
```

该命令会为 DSH 的 `web` 和 `headless` Profile 安装插件。完成后重启 DSH。

也可以分别安装：

```powershell
dsh plugin --profile web add dsh-llm-codebuddy@latest
dsh plugin --profile headless add dsh-llm-codebuddy@latest
```

只使用 WebUI 时，仅执行第一条即可。

## WebUI 配置

### CodeBuddy 账号令牌登录（新用户推荐）

1. 打开“设置 → 模型”。
2. 添加或编辑 `CodeBuddy 中国区`。
3. 点击 API Key 输入框右侧的“令牌登录”。
4. 在自动打开的浏览器中完成 CodeBuddy 中国站登录。
5. WebUI 显示“令牌已登录”后即可获取模型并保存自定义目录。

如果 WebUI 无法打开浏览器，也可以使用命令行入口：

```powershell
npx --yes dsh-llm-codebuddy@latest login
```

插件会调用 CodeBuddy 官方认证流程。完成登录后，插件会自动把
`CodeBuddy 中国区` Provider 切换为令牌模式，无需 API Key。点击同一行的
“API Key”可以切回 API Key 模式；已经保存的 API Key 不会被删除。
两种凭据彼此独立保留，之后再次点击“令牌登录”会优先复用已保存令牌；仅在没有
令牌或主动重新登录时才需要再次打开浏览器。

插件直接调用 CodeBuddy 中国站官方网页登录和令牌刷新接口，不依赖本机
`codebuddy` 命令。访问令牌和刷新令牌保存在 DSH 凭据服务中，不会写入
`settings.yaml` 或模型目录。

### WorkBuddy API Key

1. 打开“设置 → 模型”。
2. 点击“添加提供方”。
3. 选择 `CodeBuddy 中国区`。
4. 输入从 WorkBuddy 获取的 API Key 并保存。
5. 点击该 Provider 的“编辑”，展开“自定义设置”。
6. 点击“获取可用模型”，选择需要的模型并导入。
7. 按需修改模型参数，然后保存。

再次编辑已配置的 Provider 时，会直接显示上次保存的模型目录。

## API Key 替换

- 输入新的 API Key 并保存：替换原 Key；
- API Key 输入框留空并保存：保留原 Key；
- 更换 Key 后建议重新点击“获取可用模型”，同步新账号的模型权限。

API Key 由 DSH 凭据服务保存，不会写入模型目录或插件源码。

## 模型配置

- 没有自定义目录：使用 CodeBuddy 在线目录，失败时使用内置目录；
- 保存自定义目录：仅向 DSH 提供目录中保留的模型；
- 已知模型字段留空：继承在线目录或内置目录中的值；
- 新模型缺少容量：上下文窗口默认 `262144`，最大输出默认 `32768`；
- 点击“恢复默认模型”：删除自定义目录并恢复适配器目录。

配置值超过服务端真实限制时，CodeBuddy 仍可能拒绝请求。

## 思考程度

DSH 显示的思考程度来自当前模型自身的能力声明，插件把选中的档位转换为
`reasoning_effort` 并发送给 CodeBuddy。模型推理由 CodeBuddy 云端执行。

```text
off / minimal / low / medium / high / xhigh / max
```

实际显示哪些档位由 `/v3/config` 中该模型的 `supportsReasoning`、`onlyReasoning`、
`thinkingLevelMap` 和 `reasoning.effort` 决定，不能跨模型共用一套固定档位。未手动
选择时，使用 CodeBuddy 为该模型返回的默认档位；服务端没有声明时则不强行指定。

## 更新

重新运行安装命令即可更新到最新版：

```powershell
npx --yes dsh-llm-codebuddy@latest install
```

更新完成后重启 DSH。模型配置和 API Key 不会被覆盖。

## 卸载

```powershell
npx --yes dsh-llm-codebuddy@latest uninstall
```

卸载命令会：

1. 备份 `~/.dsh/settings.yaml`；
2. 只删除 `llm-pi-ai.providers.codebuddy-cn` 配置；
3. 保留其他 Provider 和 DSH 设置；
4. 从 `web`、`headless` Profile 移除插件；
5. 保留 API Key 和登录令牌凭据，方便以后重新安装。

完成后重启 DSH。备份文件名类似：

```text
settings.yaml.codebuddy-backup-2026-08-14T12-00-00-000Z
```

源码仓库、本地安装包和 API Key 不会被删除。

## 常见问题

### 安装后看不到 CodeBuddy

确认已经重启 DSH，并检查 Web Profile：

```powershell
dsh plugin --profile web list --depth 0
```

### 获取模型失败

确认 API Key 来自 WorkBuddy 且仍然有效，然后重新输入 Key 并点击“获取可用模型”。
接口临时不可用时，插件仍会提供内置模型目录。

### 为什么别人能看到某个模型，我这里看不到

模型权限与 API Key 绑定。插件只导入 `/v3/config` 中 `agents[name=cli].models` 为
当前 Key 返回的模型；更换 Key 后请重新点击“获取可用模型”。插件不会强行显示
当前 Key 未授权的模型。

### 调用时报 `500 status code (no body)`

先更新到最新版并重启 DSH：

```powershell
npx --yes dsh-llm-codebuddy@latest install
```

旧版本可能被 DSH 覆盖 CodeBuddy 请求标识，导致服务端拒绝请求；最新版已在插件请求层
恢复 CodeBuddy 官方标识，同时适用于 API Key 和令牌模式。

### 卸载后仍显示旧页面

关闭正在运行的 DSH，再重新启动。已经运行的进程不会自动卸载内存中的插件。

## 开发文档

需要开发其他 Agent 或 Provider 时，请阅读
[反向代理调用 WorkBuddy API 开发文档](./docs/反向代理调用WorkBuddy-API开发文档.md)。

## 工作原理

```text
WorkBuddy 提供 API Key
          ↓
DSH Agent → 本插件 → CodeBuddy /v2/chat/completions
                    ↘ CodeBuddy /v3/config（获取模型）

CodeBuddy 中国站网页登录 → 本插件保存并刷新 DSH 登录凭据
                              ↓ 当前 access token
DSH Agent → 本插件 → CodeBuddy API（Authorization: Bearer）
```

- DSH：负责 Agent 循环、上下文、工具调用和权限；
- WorkBuddy：提供 API Key；
- 插件：负责 Provider 注册、模型目录转换和请求兼容；
- CodeBuddy：负责模型推理并返回结果。
<img width="1885" height="853" alt="image" src="https://github.com/user-attachments/assets/eda31b48-8412-414d-b552-1b7ce0a7c3a0" />
<img width="711" height="380" alt="屏幕截图 2026-08-20 145322" src="https://github.com/user-attachments/assets/541197e8-ac87-47f8-b7ca-f74239ca7c0f" />

## License

[MIT](./LICENSE)