dsh-llm-codebuddy 1.3.3 → 1.3.4

package/README.md

@@ -1,163 +1,176 @@
-# DSH CodeBuddy Provider
-
-为 DeepSeek Harness（DSH）增加 `CodeBuddy 中国区` Provider。安装后可直接在
-DSH WebUI 中填写 API Key、获取模型、调整模型参数并使用 CodeBuddy 模型。
-
-> [!IMPORTANT]
-> API Key 由 **WorkBuddy** 提供，本插件使用该 Key 调用供 CodeBuddy 使用的模型服务。
-> DSH 中的 Provider 名称仍为 `CodeBuddy 中国区`。本项目是第三方适配器，并非
-> WorkBuddy、CodeBuddy 或 DSH 官方插件。
-
-## 功能
-
-- WebUI 中直接添加 `CodeBuddy 中国区`；
-- 只需填写从 WorkBuddy 获取的 API Key；
-- 自动获取 CodeBuddy 当前可用模型；
-- 支持编辑模型 ID、名称、上下文窗口和最大输出 Token；
-- 支持添加、删除模型以及重新同步模型目录；
-- 支持 `minimal / low / medium / high / xhigh / max` 思考程度；
-- 输入新 API Key 可替换旧值，留空保存则保留原值；
-- 模型接口暂时不可用时使用内置目录兜底；
-- 独立安装，不修改 DSH 全局安装目录。
-
-## 环境要求
-
-- Windows、Linux 或 macOS；
-- Node.js `>= 22.19.0`；
-- 已安装 DSH；
-- 已验证 DSH `0.1.0-rc.6`。
-
-安装器已自带 DSH 所需的 `pnpm`，无需全局安装。
-
-> 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 配置
-
-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
-minimal / low / medium / high / xhigh / max
-```
-
-当前不提供 `off`，因为 CodeBuddy 模型目录中的模型属于推理模型。未选择档位时，
-使用 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 并点击“获取可用模型”。
-接口临时不可用时，插件仍会提供内置模型目录。
-
-### 卸载后仍显示旧页面
-
-关闭正在运行的 DSH，再重新启动。已经运行的进程不会自动卸载内存中的插件。
-
-## 工作原理
-
-```text
-WorkBuddy 提供 API Key
-          ↓
-DSH Agent → 本插件 → CodeBuddy /v2/chat/completions
-                    ↘ CodeBuddy /v3/config（获取模型）
-```
-
-- DSH：负责 Agent 循环、上下文、工具调用和权限；
-- WorkBuddy：提供 API Key；
-- 插件：负责 Provider 注册、模型目录转换和请求兼容；
-- CodeBuddy：负责模型推理并返回结果。
-
-## License
-
-[MIT](./LICENSE)
+# DSH CodeBuddy Provider
+
+为 DeepSeek Harness（DSH）增加 `CodeBuddy 中国区` Provider。安装后可直接在
+DSH WebUI 中填写 API Key、获取模型、调整模型参数并使用 CodeBuddy 模型。
+
+> [!IMPORTANT]
+> API Key 由 **WorkBuddy** 提供，本插件使用该 Key 调用供 CodeBuddy 使用的模型服务。
+> DSH 中的 Provider 名称仍为 `CodeBuddy 中国区`。本项目是第三方适配器，并非
+> WorkBuddy、CodeBuddy 或 DSH 官方插件。
+
+## 功能
+
+- WebUI 中直接添加 `CodeBuddy 中国区`；
+- 只需填写从 WorkBuddy 获取的 API Key；
+- 自动获取 CodeBuddy 当前可用模型；
+- 支持编辑模型 ID、名称、上下文窗口和最大输出 Token；
+- 支持添加、删除模型以及重新同步模型目录；
+- 按模型目录声明各模型自己的思考能力、可选档位和默认档位；
+- 输入新 API Key 可替换旧值，留空保存则保留原值；
+- 模型接口暂时不可用时使用内置目录兜底；
+- 独立安装，不修改 DSH 全局安装目录。
+
+## 环境要求
+
+- Windows、Linux 或 macOS；
+- Node.js `>= 22.19.0`；
+- 已安装 DSH；
+- 已验证 DSH `0.1.0-rc.6`。
+
+安装器已自带 DSH 所需的 `pnpm`，无需全局安装。
+
+> 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 配置
+
+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 未授权的模型。
+
+## 开发文档
+
+需要开发其他 Agent 或 Provider 时，请阅读
+[CodeBuddy 调用 WorkBuddy API 开发文档](./docs/CodeBuddy调用WorkBuddy-API开发文档.md)。
+
+### 卸载后仍显示旧页面
+
+关闭正在运行的 DSH，再重新启动。已经运行的进程不会自动卸载内存中的插件。
+
+## 工作原理
+
+```text
+WorkBuddy 提供 API Key
+          ↓
+DSH Agent → 本插件 → CodeBuddy /v2/chat/completions
+                    ↘ CodeBuddy /v3/config（获取模型）
+```
+
+- 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" />
+
+## License
+
+[MIT](./LICENSE)

package/docs/CodeBuddy/350/260/203/347/224/250WorkBuddy-API/345/274/200/345/217/221/346/226/207/346/241/243.md

@@ -0,0 +1,576 @@
+# CodeBuddy 调用 WorkBuddy API 开发文档
+
+> 适用对象：需要在其他 Agent、CLI、IDE 插件或本地代理中接入 CodeBuddy 模型的开发者  
+> 验证日期：2026-08-14  
+> 验证客户端：`@tencent-ai/codebuddy-code 2.136.0`  
+> 文档性质：基于已安装客户端、实际接口响应和本项目适配代码整理的第三方开发说明，不是腾讯官方 API 承诺。
+
+## 1. 先说明名称关系
+
+日常说的“调用 WorkBuddy API”实际包含两个不同角色：
+
+| 名称 | 实际作用 |
+|---|---|
+| WorkBuddy | 提供或签发 API Key |
+| CodeBuddy | 使用该 Key 的 Agent/CLI 产品 |
+| `copilot.tencent.com` | 当前实际提供模型目录和推理接口的服务端 |
+| 本项目 | 把上述服务适配为 DSH Provider |
+
+因此，当前观察到的调用链是：
+
+```mermaid
+flowchart LR
+    A["WorkBuddy 提供 API Key"] --> B["CodeBuddy 或第三方 Agent"]
+    B --> C["GET /v3/config\n获取当前 Key 的模型权限"]
+    B --> D["POST /v2/chat/completions\n发起模型推理"]
+    C --> E["copilot.tencent.com"]
+    D --> E
+```
+
+不存在一个需要额外调用的“WorkBuddy 换取 CodeBuddy Token”步骤。开发者拿到有效 Key
+后，直接把它用于模型目录和聊天请求。
+
+## 2. 重要边界
+
+1. 接口目前不是公开、稳定承诺的开发者 API，路径、Header 和字段可能随 CodeBuddy 更新。
+2. 只能使用本人或组织授权的 API Key，不要绕过账号、额度、模型权限或企业策略。
+3. 模型列表与 API Key 绑定，不同 Key 返回的模型 ID 可能不同。
+4. 不要把模型目录写死在代码中；每次添加或替换 Key 后应重新获取 `/v3/config`。
+5. API Key 只能放在环境变量、凭据服务或 Secret Manager 中，不能提交到 Git。
+
+## 3. 接口总览
+
+| 用途 | 方法 | 地址 | 协议 |
+|---|---|---|---|
+| 获取模型与产品配置 | `GET` | `https://copilot.tencent.com/v3/config` | JSON |
+| 模型推理 | `POST` | `https://copilot.tencent.com/v2/chat/completions` | OpenAI Chat Completions 兼容，推荐 SSE 流式 |
+
+当前不是 OpenAI Responses API，也不是 Anthropic Messages API。第三方 Agent 应优先实现
+`openai-completions` / Chat Completions 适配。
+
+## 4. API Key 管理
+
+推荐环境变量：
+
+```text
+CODEBUDDY_API_KEY=<从 WorkBuddy 获取的 Key>
+```
+
+Windows PowerShell 设置用户环境变量：
+
+```powershell
+[Environment]::SetEnvironmentVariable(
+  "CODEBUDDY_API_KEY",
+  "<在本机填写，不要提交到仓库>",
+  "User"
+)
+```
+
+新进程才能读取新设置。不要在日志中输出 Key；诊断两个 Key 是否相同时，可以比较
+SHA-256 指纹，而不是打印明文。
+
+## 5. 获取当前 Key 可用的模型
+
+### 5.1 请求
+
+```http
+GET /v3/config HTTP/1.1
+Host: copilot.tencent.com
+Accept: application/json
+X-API-Key: <API_KEY>
+User-Agent: CLI/unknown CodeBuddy/2.136.0
+X-Product: SaaS
+```
+
+其中：
+
+- `X-API-Key`：模型目录接口的关键鉴权 Header；
+- `User-Agent`：按当前 CodeBuddy CLI 行为填写，建议版本升级时同步验证；
+- `X-Product: SaaS`：标识当前产品部署类型；
+- Header 名大小写不敏感。
+
+### 5.2 响应骨架
+
+成功时 HTTP 通常为 `200`，同时还要检查业务字段 `code`：
+
+```json
+{
+  "code": 0,
+  "msg": "OK",
+  "data": {
+    "agents": [
+      {
+        "name": "cli",
+        "models": ["hy3", "glm-5.3", "deepseek-v4-flash"]
+      }
+    ],
+    "models": [
+      {
+        "id": "deepseek-v4-flash",
+        "name": "Deepseek-V4-Flash",
+        "maxInputTokens": 1000000,
+        "maxOutputTokens": 50000,
+        "maxAllowedSize": 1000000,
+        "supportsImages": true,
+        "supportsReasoning": true,
+        "onlyReasoning": true,
+        "reasoning": {
+          "effort": "high",
+          "summary": "auto"
+        }
+      }
+    ]
+  }
+}
+```
+
+示例只展示与适配有关的字段；实际响应还可能包含企业信息和产品功能开关。
+
+### 5.3 正确的模型筛选算法
+
+不能直接把 `data.models` 全部暴露给用户。正确流程是：
+
+1. 在 `data.agents` 中找到 `name === "cli"` 的 Agent；
+2. 读取该 Agent 的 `models`，这是当前 Key 对 CLI 开放的模型 ID；
+3. 用这些 ID 与 `data.models[].id` 关联；
+4. 丢弃没有容量信息或没有对应配置的异常条目；
+5. 保留服务端顺序，避免客户端自行重排造成默认模型变化。
+
+兼容旧响应时，可以同时检查：
+
+```javascript
+const agents = Array.isArray(data.agents)
+  ? data.agents
+  : data.agent?.agents;
+```
+
+### 5.4 Node.js 获取模型示例
+
+Node.js 22 以上可直接使用内置 `fetch`，不需要 SDK：
+
+```javascript
+const apiKey = process.env.CODEBUDDY_API_KEY;
+if (!apiKey) throw new Error("缺少 CODEBUDDY_API_KEY");
+
+const response = await fetch("https://copilot.tencent.com/v3/config", {
+  headers: {
+    accept: "application/json",
+    "x-api-key": apiKey,
+    "user-agent": "CLI/unknown CodeBuddy/2.136.0",
+    "x-product": "SaaS",
+  },
+  signal: AbortSignal.timeout(20_000),
+});
+
+if (!response.ok) {
+  throw new Error(`模型目录 HTTP ${response.status}`);
+}
+
+const body = await response.json();
+if (body?.code !== 0) {
+  throw new Error(`模型目录业务错误：${body?.msg ?? body?.code}`);
+}
+
+const agents = Array.isArray(body.data?.agents)
+  ? body.data.agents
+  : body.data?.agent?.agents;
+const allowedIds = agents?.find((agent) => agent?.name === "cli")?.models ?? [];
+const byId = new Map((body.data?.models ?? []).map((model) => [model.id, model]));
+
+const models = allowedIds.flatMap((id) => {
+  const model = byId.get(id);
+  if (!model) return [];
+  const contextWindow = model.maxInputTokens ?? model.maxAllowedSize;
+  const maxTokens = model.maxOutputTokens;
+  if (!Number.isSafeInteger(contextWindow) || !Number.isSafeInteger(maxTokens)) return [];
+  return [{
+    id,
+    name: model.name ?? id,
+    contextWindow,
+    maxTokens,
+    supportsImages: model.supportsImages === true,
+    supportsReasoning: model.supportsReasoning === true,
+    onlyReasoning: model.onlyReasoning === true,
+    defaultReasoningEffort: model.reasoning?.effort,
+    thinkingLevelMap: model.thinkingLevelMap,
+    thinkingFormat: model.thinkingFormat,
+  }];
+});
+
+console.table(models);
+```
+
+## 6. 为什么不同账号看到的模型不同
+
+`agents[name=cli].models` 是 Key 级别的授权结果，不是全平台公共目录。
+
+2026-08-14 实测，同一台电脑上的两把有效 Key 返回了不同结果：
+
+| 现象 | Key A | Key B |
+|---|---|---|
+| GLM 新版本 | 包含 `glm-5.3` | 最高为 `glm-5.2` |
+| MiniMax ID | `minimax-m3-pay` | `minimax-m3` |
+| Kimi ID | `kimi-k3-2` | `kimi-k3-1` |
+
+因此，出现“CodeBuddy 能看到 `glm-5.3`，另一个 Agent 看不到”时，先确认两个程序实际使用
+的是不是同一把 Key。不要通过硬编码 `glm-5.3` 解决，否则请求阶段仍会被服务端拒绝。
+
+## 7. 发起 Chat Completions 请求
+
+### 7.1 请求地址
+
+```text
+POST https://copilot.tencent.com/v2/chat/completions
+```
+
+### 7.2 鉴权 Header
+
+当前 CodeBuddy CLI 会为模型请求同时准备：
+
+```http
+Authorization: Bearer <API_KEY>
+X-API-Key: <API_KEY>
+Content-Type: application/json
+Accept: text/event-stream
+```
+
+本项目基于 OpenAI SDK 的适配路径使用 `Authorization: Bearer` 即可完成请求；为了更贴近
+CodeBuddy CLI 并兼容服务端策略变化，独立开发的新客户端建议同时发送 `Authorization`
+和 `X-API-Key`。不要把 Key 放进 URL Query。
+
+CodeBuddy CLI 还会添加请求 ID、会话 ID、IDE 名称、产品类型等内部 Header。第三方开发的
+最小客户端不应伪造这些字段；只有在服务端明确要求时再增加。
+
+### 7.3 最小请求体
+
+```json
+{
+  "model": "deepseek-v4-flash",
+  "messages": [
+    { "role": "user", "content": "请只回复：连接成功" }
+  ],
+  "stream": true,
+  "stream_options": { "include_usage": true },
+  "max_tokens": 1024
+}
+```
+
+注意：
+
+- 使用 `max_tokens`，不是 `max_completion_tokens`；
+- `model` 必须来自当前 Key 的 CLI 模型列表；
+- 推荐 `stream: true`，这是 CodeBuddy Agent 的主要工作模式；
+- `max_tokens` 不应超过目录中的 `maxOutputTokens`；
+- 输入和预期输出总量不能超过模型上下文限制。
+
+## 8. 思考能力必须逐模型处理
+
+不能为所有模型统一写死 `high`，也不能假设所有模型都支持 `xhigh` 或 `max`。至少读取：
+
+| 字段 | 含义 | 处理方式 |
+|---|---|---|
+| `supportsReasoning` | 模型是否支持推理 | `false` 时不显示思考档位，不发送推理参数 |
+| `onlyReasoning` | 是否只能以推理模式工作 | `true` 时不提供 `off` |
+| `reasoning.effort` | 该模型的默认思考档位 | 用户未选择时使用；不要拿一个模型的默认值套给其他模型 |
+| `thinkingLevelMap` | UI 档位到线上参数的逐模型映射 | 存在时严格按映射提供选项和转换 |
+| `thinkingFormat` | 推理参数协议 | 存在时按该格式转换；缺失时才使用当前端点的兼容默认 |
+
+当前实测就存在不同默认值：部分模型为 `high`，部分模型为 `medium`。
+
+### 8.1 选择规则
+
+1. 用户显式选择档位：发送该模型声明支持的档位；
+2. 用户选择“默认”或未选择：使用该模型自己的 `reasoning.effort`；
+3. 服务端没有声明默认值：省略思考参数，让服务端决定；
+4. `supportsReasoning === false`：删除所有推理参数；
+5. `onlyReasoning === true`：不要提供 `off`；
+6. `thinkingLevelMap` 存在：未出现在 Map 中的档位视为不支持；
+7. 不要自动把不支持的档位静默替换成另一个档位，最好在请求前报错。
+
+### 8.2 OpenAI 风格
+
+当前适配使用的默认格式是：
+
+```json
+{
+  "reasoning_effort": "medium"
+}
+```
+
+常见候选值为：
+
+```text
+minimal / low / medium / high / xhigh / max
+```
+
+候选值不等于所有模型均支持。以当前模型的能力声明为准。
+
+### 8.3 其他思考格式
+
+如果未来目录返回不同 `thinkingFormat`，适配器可能需要转换，例如：
+
+```json
+{ "reasoning": { "effort": "high" } }
+```
+
+或：
+
+```json
+{ "thinking": { "type": "enabled" }, "reasoning_effort": "high" }
+```
+
+不要同时无条件发送所有格式。应为每个模型只生成一种服务端声明的格式。
+
+## 9. 工具调用
+
+请求中的工具遵循 OpenAI Chat Completions 格式：
+
+```json
+{
+  "tools": [
+    {
+      "type": "function",
+      "function": {
+        "name": "get_weather",
+        "description": "查询天气",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "city": { "type": "string" }
+          },
+          "required": ["city"],
+          "additionalProperties": false
+        }
+      }
+    }
+  ],
+  "tool_choice": "auto"
+}
+```
+
+流式响应中的工具参数会分段出现在：
+
+```text
+choices[0].delta.tool_calls[].function.arguments
+```
+
+客户端必须按 `tool_calls[].index` 累积字符串，结束后再解析 JSON。执行工具后，把结果作为
+`role: "tool"`、带相同 `tool_call_id` 的消息加入下一轮请求。
+
+## 10. 图片输入
+
+只有 `supportsImages === true` 的模型才能接收图片。OpenAI 兼容格式示例：
+
+```json
+{
+  "role": "user",
+  "content": [
+    { "type": "text", "text": "描述这张图片" },
+    {
+      "type": "image_url",
+      "image_url": {
+        "url": "data:image/png;base64,<BASE64>"
+      }
+    }
+  ]
+}
+```
+
+发送前应限制文件大小和 MIME 类型，不要仅根据扩展名判断图片。
+
+## 11. SSE 流式响应解析
+
+服务端返回 `text/event-stream`。每个事件通常形如：
+
+```text
+data: {"id":"...","choices":[{"delta":{"content":"你"}}]}
+
+data: {"id":"...","choices":[{"delta":{"content":"好"},"finish_reason":"stop"}]}
+
+data: [DONE]
+```
+
+需要处理的字段：
+
+| 字段 | 用途 |
+|---|---|
+| `choices[0].delta.content` | 最终回答文本增量 |
+| `choices[0].delta.reasoning_content` | 思考内容增量之一 |
+| `choices[0].delta.reasoning` | 部分模型使用的思考内容字段 |
+| `choices[0].delta.reasoning_text` | 另一种兼容思考字段 |
+| `choices[0].delta.tool_calls` | 工具调用增量 |
+| `choices[0].finish_reason` | `stop`、`length`、`tool_calls` 等结束原因 |
+| `usage` | Token 用量，通常在开启 `include_usage` 后的尾部 Chunk 返回 |
+
+同一个 Chunk 可能没有 `choices`，只有 `usage`，不能因此判定响应异常。
+
+## 12. 完整 Node.js 流式示例
+
+```javascript
+const apiKey = process.env.CODEBUDDY_API_KEY;
+if (!apiKey) throw new Error("缺少 CODEBUDDY_API_KEY");
+
+const response = await fetch("https://copilot.tencent.com/v2/chat/completions", {
+  method: "POST",
+  headers: {
+    authorization: `Bearer ${apiKey}`,
+    "x-api-key": apiKey,
+    "content-type": "application/json",
+    accept: "text/event-stream",
+  },
+  body: JSON.stringify({
+    model: "deepseek-v4-flash",
+    messages: [{ role: "user", content: "请只回复：连接成功" }],
+    stream: true,
+    stream_options: { include_usage: true },
+    max_tokens: 1024,
+    // reasoning_effort: "high", // 只在当前模型明确支持且用户选择时添加
+  }),
+  signal: AbortSignal.timeout(300_000),
+});
+
+if (!response.ok) {
+  const detail = await response.text();
+  throw new Error(`推理接口 HTTP ${response.status}: ${detail.slice(0, 500)}`);
+}
+
+const decoder = new TextDecoder();
+let buffer = "";
+let answer = "";
+let reasoning = "";
+
+for await (const chunk of response.body) {
+  buffer += decoder.decode(chunk, { stream: true });
+  let boundary;
+  while ((boundary = buffer.indexOf("\n\n")) !== -1) {
+    const event = buffer.slice(0, boundary);
+    buffer = buffer.slice(boundary + 2);
+
+    for (const line of event.split(/\r?\n/)) {
+      if (!line.startsWith("data:")) continue;
+      const data = line.slice(5).trim();
+      if (!data || data === "[DONE]") continue;
+
+      const payload = JSON.parse(data);
+      const delta = payload.choices?.[0]?.delta;
+      if (typeof delta?.content === "string") {
+        answer += delta.content;
+        process.stdout.write(delta.content);
+      }
+      const thought = delta?.reasoning_content ?? delta?.reasoning ?? delta?.reasoning_text;
+      if (typeof thought === "string") reasoning += thought;
+      if (payload.usage) console.error("\nusage:", payload.usage);
+    }
+  }
+}
+
+console.log("\n\nanswer:", answer);
+console.log("reasoning length:", reasoning.length);
+```
+
+生产代码还需要按 `tool_calls[].index` 累积工具参数，并处理单个 SSE 事件跨网络 Chunk 的情况。
+
+## 13. 错误处理与重试
+
+### 13.1 模型目录
+
+同时检查 HTTP 状态和 JSON 业务状态：
+
+```javascript
+if (!response.ok) throw new Error(`HTTP ${response.status}`);
+if (body.code !== 0) throw new Error(body.msg ?? String(body.code));
+```
+
+### 13.2 常见分类
+
+| 情况 | 建议处理 |
+|---|---|
+| `401` / `403` | Key 无效、过期或无权限；停止重试并要求重新填写 |
+| `408` / 网络断开 | 指数退避重试 |
+| `429` | 遵守 `Retry-After`；提示额度或频率限制 |
+| `5xx` | 短暂退避后有限重试 |
+| 模型不在 CLI 列表 | 刷新目录，不要强制调用 |
+| 流结束但没有结束原因 | 视为不完整响应，不要保存为成功回答 |
+
+流式请求只应在“尚未收到任何有效增量”时自动重试。收到文本或工具调用后再次自动重试，
+可能造成重复输出或重复执行工具。
+
+### 13.3 推荐超时
+
+- 模型目录：20 秒总超时；
+- 建立推理连接：30–60 秒；
+- 流空闲超时：300 秒；
+- 用户取消：通过 `AbortController` 立即向上游传播。
+
+## 14. 缓存策略
+
+模型目录可以按 Key 指纹缓存，但不能跨 Key 共用：
+
+```text
+cache key = SHA-256(API Key) + 客户端产品类型
+```
+
+建议：
+
+- 缓存 5–15 分钟；
+- 用户点击“刷新模型”时绕过缓存；
+- 更换 Key 后立即清除旧缓存；
+- 缓存失败时可以使用最近一次成功目录，但 UI 必须标注“可能过期”；
+- 不要把完整 Key 写进缓存键或日志。
+
+## 15. 适配其他 Agent 的最小接口
+
+一个可维护的 Provider 只需要四个职责：
+
+```text
+resolveCredential()  -> 安全读取 Key
+discoverModels()     -> 获取并按 CLI 权限过滤模型
+describeModel(id)    -> 返回该模型容量、模态、思考档位和默认值
+stream(request)      -> 转换消息并解析 SSE
+```
+
+DSH、OpenCode 或其他 Agent 自己负责：
+
+- Agent 循环；
+- 上下文裁剪与压缩；
+- 工具实际执行；
+- 权限确认；
+- 会话持久化；
+- 重试策略和用户取消。
+
+CodeBuddy 服务端负责模型推理，不会替第三方 Agent 自动执行本地工具。
+
+## 16. 验收清单
+
+开发完成后至少验证：
+
+- [ ] Key 不出现在源码、Git、日志和异常堆栈中；
+- [ ] 两把不同 Key 的模型目录不会串用；
+- [ ] 只显示 `agents[name=cli].models` 授权的模型；
+- [ ] 新模型无需发布新代码即可出现；
+- [ ] 旧模型下线后不会继续从缓存永久显示；
+- [ ] 上下文窗口和最大输出来自逐模型字段；
+- [ ] 非图片模型会在请求前拒绝图片；
+- [ ] 非推理模型不显示思考控件；
+- [ ] `onlyReasoning` 模型不显示 `off`；
+- [ ] 每个模型使用自己的默认思考档位；
+- [ ] 用户显式档位会转换为该模型自己的线上值；
+- [ ] 能累计文本、思考和工具调用 SSE 增量；
+- [ ] 用户取消能中止网络请求；
+- [ ] 429 和 5xx 有限重试，不会无限循环；
+- [ ] 工具调用不会因自动重试而重复执行。
+
+## 17. 版本漂移检查
+
+升级 CodeBuddy CLI 后，应重新核对：
+
+1. `product.json` 和 CLI 版本；
+2. 配置接口是否仍为 `/v3/config`；
+3. 推理接口是否仍为 `/v2/chat/completions`；
+4. 鉴权是否仍接受 `Authorization` / `X-API-Key`；
+5. 模型能力字段是否新增 `thinkingLevelMap`、`thinkingFormat` 等；
+6. SSE 推理和工具字段是否变化；
+7. 当前 Key 实际返回的 CLI 模型目录。
+
+本项目的可执行实现位于 [`index.js`](../index.js)，安装和使用说明见
+[`README.md`](../README.md)。

package/index.js

@@ -22,10 +22,7 @@ const USER_AGENT = "CLI/unknown CodeBuddy/2.136.0";
 const STREAM_IDLE_TIMEOUT_MS = 300_000;
 const NO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
 const EFFORTS = ["minimal", "low", "medium", "high", "xhigh", "max"];
-const THINKING_LEVEL_MAP = Object.fromEntries([
-  ["off", null],
-  ...EFFORTS.map((effort) => [effort, effort]),
-]);
+const THINKING_LEVELS = ["off", ...EFFORTS];
 const COMPAT = {
   supportsStore: false,
   supportsDeveloperRole: false,
@@ -50,23 +47,60 @@ const FALLBACK_MODELS = [
   codeBuddyModel({ id, name: modelName, contextWindow, maxTokens, images }),
 );
 
-function codeBuddyModel({ id, name: modelName, contextWindow, maxTokens, images }) {
+function codeBuddyModel({ id, name: modelName, contextWindow, maxTokens, images, reasoning = true, thinkingLevelMap = { off: null }, defaultReasoningEffort, thinkingFormat }) {
   return {
     id,
     name: modelName,
     api: "openai-completions",
     provider: PROVIDER,
     baseUrl: BASE_URL,
-    reasoning: true,
-    thinkingLevelMap: { ...THINKING_LEVEL_MAP },
+    reasoning,
+    ...(reasoning ? { thinkingLevelMap: { ...thinkingLevelMap } } : {}),
+    ...(defaultReasoningEffort ? { defaultReasoningEffort } : {}),
     input: images ? ["text", "image"] : ["text"],
     cost: { ...NO_COST },
     contextWindow,
     maxTokens,
-    compat: { ...COMPAT },
+    compat: { ...COMPAT, ...(thinkingFormat ? { thinkingFormat } : {}) },
+  };
+}
+
+function remoteReasoning(raw, fallback) {
+  const reasoning = raw.supportsReasoning ?? fallback?.reasoning ?? raw.onlyReasoning === true;
+  if (!reasoning) return { reasoning: false };
+  const declared = raw.thinkingLevelMap && typeof raw.thinkingLevelMap === "object" ? raw.thinkingLevelMap : undefined;
+  const thinkingLevelMap = declared
+    ? Object.fromEntries(THINKING_LEVELS.map((level) => [level,
+        Object.hasOwn(declared, level) && (typeof declared[level] === "string" || declared[level] === null) ? declared[level] : null]))
+    : { ...(fallback?.thinkingLevelMap ?? {}), ...(raw.onlyReasoning === true ? { off: null } : {}) };
+  const effort = raw.reasoning?.effort;
+  const defaultReasoningEffort = EFFORTS.includes(effort) && thinkingLevelMap[effort] !== null ? effort : undefined;
+  return {
+    reasoning: true,
+    thinkingLevelMap,
+    ...(defaultReasoningEffort ? { defaultReasoningEffort } : {}),
+    ...(typeof raw.thinkingFormat === "string" ? { thinkingFormat: raw.thinkingFormat } : {}),
   };
 }
 
+function configuredReasoning(entry, base) {
+  if (entry.reasoningEfforts === false) return { reasoning: false };
+  if (!entry.reasoningEfforts || typeof entry.reasoningEfforts !== "object") {
+    return base ? {
+      reasoning: base.reasoning,
+      thinkingLevelMap: base.thinkingLevelMap,
+      defaultReasoningEffort: base.defaultReasoningEffort,
+      thinkingFormat: base.compat?.thinkingFormat,
+    } : { reasoning: false };
+  }
+  const map = {};
+  for (const level of THINKING_LEVELS) {
+    if (!Object.hasOwn(entry.reasoningEfforts, level)) map[level] = null;
+    else if (!(level === "off" && entry.reasoningEfforts[level] === null)) map[level] = entry.reasoningEfforts[level];
+  }
+  return { reasoning: true, thinkingLevelMap: map, thinkingFormat: entry.compat?.thinkingFormat };
+}
+
 function positiveInteger(...values) {
   return values.find((value) => Number.isSafeInteger(value) && value > 0);
 }
@@ -94,6 +128,7 @@ function modelsFromConfig(data) {
       contextWindow,
       maxTokens,
       images: raw.supportsImages === true || fallback?.input.includes("image") === true,
+      ...remoteReasoning(raw, fallback),
     })];
   });
 }
@@ -169,16 +204,20 @@ function selectCodeBuddyModels(base, entries) {
   const byId = new Map(base.map((model) => [model.id, model]));
   return entries.map((entry) => {
     const model = byId.get(entry.id);
+    const reasoning = configuredReasoning(entry, model);
     return codeBuddyModel({
       id: entry.id,
       name: entry.name ?? model?.name ?? entry.id,
       contextWindow: entry.contextWindow ?? model?.contextWindow ?? 262144,
       maxTokens: entry.maxTokens ?? model?.maxTokens ?? 32768,
       images: entry.input?.includes("image") ?? model?.input.includes("image") ?? false,
+      ...reasoning,
     });
   });
 }
 
+export const __testing = Object.freeze({ modelsFromConfig, selectCodeBuddyModels });
+
 export function apply(ctx, config) {
   let current = () => config;
   let remoteModels;
@@ -246,6 +285,15 @@ export function apply(ctx, config) {
     resolveApiKey,
     resolveAttachments: () => ctx.get("attachments"),
   });
+  const resolveModel = adapter.resolveModel.bind(adapter);
+  adapter.resolveModel = async (provider, model, signal) => {
+    const resolved = await resolveModel(provider, model, signal);
+    if (provider !== PROVIDER || !resolved.reasoning) return resolved;
+    const configured = profiles().get(PROVIDER)?.piProvider.getModels().find((entry) => entry.id === model);
+    const effort = configured?.defaultReasoningEffort;
+    if (!effort || !resolved.reasoning.efforts.some((entry) => entry.id === effort)) return resolved;
+    return { ...resolved, reasoning: { ...resolved.reasoning, defaultEffort: effort } };
+  };
   const listModels = adapter.listModels.bind(adapter);
   let refreshPromise;
   adapter.listModels = async (provider) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-llm-codebuddy",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "description": "使用 WorkBuddy API Key 为 DeepSeek Harness 接入 CodeBuddy 模型",
   "author": "Axiaohungry",
   "keywords": [
@@ -31,11 +31,12 @@
     "index.js",
     "cli.js",
     "cordis.patch.yml",
+    "docs",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "check": "node --check index.js && node --check cli.js && node cli.js --self-test"
+    "check": "node --check index.js && node --check cli.js && node --test test.js && node cli.js --self-test"
   },
   "dsh": {
     "bundle": {