# @goodandready/dsh-clinebot 中文文档

规范地址：https://npmcn.com/package/%40goodandready/dsh-clinebot/

版本：0\.6\.37
npm 元数据更新时间：2026-11-16T19:17:39.893Z
中文译文更新时间：2026-11-16T19:18:33.948Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：950 kB，49 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：react ^18\.2\.0，@deepseek-ai/cordis ~4\.0\.5 \|\| ~4\.1\.0，@deepseek-ai/dsh-llm \>=0\.2\.1-rc\.2 \<0\.2\.3-0，@deepseek-ai/dsh-web \>=0\.2\.1-rc\.2 \<0\.2\.3-0，@deepseek-ai/schemastery ~3\.18\.5，@deepseek-ai/dsh-commands \>=0\.2\.1-rc\.2 \<0\.2\.3-0，@deepseek-ai/dsh-settings \>=0\.2\.1-rc\.2 \<0\.2\.3-0，@deepseek-ai/dsh-attachment \>=0\.2\.1-rc\.2 \<0\.2\.3-0，@deepseek-ai/dsh-credentials \>=0\.2\.1-rc\.2 \<0\.2\.3-0，@deepseek-ai/dsh-host-webserver \>=0\.2\.1-rc\.2 \<0\.2\.3-0
- 首次发布：2026-09-04T23:40:55.414Z
- 最新版本发布：2026-11-16T19:17:39.664Z
- 近 30 天下载量：10338（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：108（近 12 个月 108 个）

## 中文简介

ClineBot / ClinePass 的 DeepSeek Harness 伴侣:动态订阅模式同步,配额耗尽警告,会话度量,专用设置页面,活用限制,和/cline slash-command.

## 安装

```sh
npm install @goodandready/dsh-clinebot
```

也可以使用：`pnpm add @goodandready/dsh-clinebot`、`yarn add @goodandready/dsh-clinebot`、`bun add @goodandready/dsh-clinebot`

## README

# 📦 @goodandready/dsh-clinebot

### 适用于 DeepSeek Harness 的 ClineBot / ClinePass 原生模型提供商伴侣插件

**0.6.35** 改进了错误可观测性与仓库规范性：将模型缓存持久化与账户变更队列中的静默异常捕获替换为结构化日志告警，补充标准化的 AGENTS.md、index.md 与 deploy.sh，并将内部构建脚本与测试排除在 GitHub 公开镜像之外（#327、#328、#329）。完整保留与 DSH `0.2.2-rc.1` / cordis 4.1.0 的兼容性、按模型路由优先级及原生 `ctx.llm` 适配器。

[![npm version](https://img.shields.io/npm/v/@goodandready/dsh-clinebot.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b)](https://www.npmjs.com/package/@goodandready/dsh-clinebot) [![license](https://img.shields.io/github/license/GooDAnDReaDY/dsh-clinebot.svg?style=for-the-badge&color=10b981&labelColor=064e3b)](https://npmcn.com/package/%40goodandready/LICENSE) [![DSH Plugin](https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065)](https://github.com/topics/dsh-plugin) [![Node version](https://img.shields.io/badge/Node-22%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03)](https://nodejs.org/)

[![所有项目](https://img.shields.io/badge/%E4%BD%9C%E8%80%85%E6%89%80%E6%9C%89%E5%BC%80%E6%BA%90%E9%A1%B9%E7%9B%AE-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e)](https://goodandready.app/)

[**🇬🇧 English**](https://npmcn.com/package/%40goodandready/dsh-clinebot/README.md) • [**🇷🇺 Русский**](https://npmcn.com/package/%40goodandready/dsh-clinebot/README.ru.md) • [**🇨🇳 中文说明**](https://npmcn.com/package/%40goodandready/dsh-clinebot/README.zh.md)

<table><tbody><tr><td align="center">⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。<br><br>🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。</td></tr></tbody></table>

* * *

## ⚡ 概述与解决的核心痛点

**ClinePass** (`https://cline.bot`) 是一项高性价比订阅服务，为开发者提供主流开源代码模型与推理模型 2–5 倍的高并发调用限额，统一通过 OpenAI 兼容接口 (`https://api.cline.bot/api/v1`) 提供服务。

在将 ClinePass 接入 DeepSeek Harness (DSH) 时存在以下挑战：

1.  **缺失 `/v1/models` 接口**：`api.cline.bot` 的 `GET /v1/models` 会直接返回 `404 Not Found`，导致动态模型同步失败或模型列表为空。
2.  **专属模型前缀**：所有模型 ID 均需前缀 `cline-pass/`（如 `cline-pass/deepseek-v4.1-flash`, `cline-pass/kimi-k3`）。
3.  **用量额度监控**：5 小时滑动窗口与每周限额需要清晰直观的可视化进度监控。
4.  **安全凭据隔离**：禁止在明文配置中直接填写密钥。

**`@goodandready/dsh-clinebot`** 完美解决以上痛点：

-   🚀 **应用内一键更新**：直接在 DSH 界面检查并升级插件，或通过受保护的 `/dsh-clinebot/update` 进行本地安全更新。
-   ⚡ **SWR 配额与健康状态缓存**：状态查询毫秒级响应（<2ms），并在后台静默更新，不阻塞前端渲染。
-   🔀 **智能配额故障转移 (Smart Failover)**：在流式请求遇到 HTTP 429 或配额耗尽时自动轮换多账号（具备 30 秒防风暴保护；当前失败请求不自动重试，后续对话请求无缝使用下一个账号）。
-   🖥️ **插件配置页**：打开已安装的 ClineBot，进入配置。页面包含凭据名、模型、配额和账号，不单独占用侧边栏。
-   🔄 **订阅模型动态同步**：从官方 `GET /api/v1/users/me/plan` 自动提取真实包含模型，一键原子级同步至 DSH 提供商配置。DSH 严格仅注册当前套餐模型，内置目录作为特性参考并在未同步时作为备用。
-   ⚠️ **额度耗尽实时预警**：当 5 小时滑动窗口达到 80%（警告黄色）和 95%（即将耗尽红色）时展示醒目预警横幅与重置倒计时。
-   📈 **会话统计与指标看板**：实时监控进程启动后经由 ClineBot 提供商发出的真实 DSH 对话请求、Prompt/Completion Token 消耗、流式延迟及错误统计。
-   📊 **实时用量仪表盘**：调用官方 `GET /users/me/plan/usage-limits` API，实时渲染 5 小时与每周额度进度条及重置倒计时。
-   🔑 **界面直存密钥**：在 UI 中直接粘贴 API 密钥，通过 `ctx.credentials.set()` 自动安全保存至 `~/.dsh/.credentials.yaml`。
-   🎯 **模型选择器管理**：支持勾选开启/关闭特定模型在聊天选择器中的显示。
-   💬 **聊天斜杠指令 `/cline`**：在任意聊天框快速查询当前配额、预警横幅、会话指标统计、网络延迟与活跃模型。

* * *

## 🏛️ 架构设计

```mermaid
graph LR
    subgraph UI [DSH Web 前端界面]
        Page["独立配置页 (设置 -> ClineBot)"]
        QuotaBar["5小时与每周额度进度条 + 额度预警横幅"]
        KeyInput["API 密钥直填与安全保存"]
        ModelPick["模型动态同步与选择器管控"]
        StatsCard["会话指标监控看板"]
    end

    subgraph PluginHost [dsh-clinebot 宿主运行环境]
        HttpEndpoints["API 路由: /dsh-clinebot/*"]
        ClientCore["lib/cline-client.js"]
        ModelCatalog["lib/models.js (内置精选 + 动态订阅解析)"]
        SlashCmd["斜杠指令: /cline"]
    end

    subgraph DSHCore [DSH 核心系统服务]
        Credentials["凭据存储服务 (~/.dsh/.credentials.yaml)"]
    end

    subgraph Upstream [Cline 官方云端]
        ClinePass["api.cline.bot/api/v1/chat/completions"]
        ClineQuota["api.cline.bot/api/v1/users/me/plan/usage-limits"]
        ClinePlan["api.cline.bot/api/v1/users/me/plan"]
    end

    Page -->|GET /status & /usage| HttpEndpoints
    KeyInput -->|POST /save-key| HttpEndpoints
    ModelPick -->|POST /models/sync| HttpEndpoints
    HttpEndpoints --> Credentials
    HttpEndpoints --> ClientCore
    ClientCore --> ModelCatalog
    ClientCore -->|模型对话| ClinePass
    ClientCore -->|额度查询| ClineQuota
    ClientCore -->|套餐信息| ClinePlan
```

* * *

## ✨ 核心模块与功能

-   **`lib/models.js`**：管理动态订阅模型目录与内置精选模板（提供完整的 `Off` / `Low` / `Medium` / `High` / `Max` 思考强度映射、上游 200k 上下文容量标注、自定义模型支持）以及套餐模型动态解析器（`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`）。
-   **价格与模型**：模型行中的 **Ping** 调用 `POST /models/probe` 并显示 TTFT；**应用可见模型** 通过 `POST /models/visible` 保存可见模型和套餐过滤。新模型缺少价格时可通过 `priceAutoSync` 开关自动从 models.dev 获取公开价格；关闭后仍可使用手动同步。
-   **`lib/cline-client.js`**：
    -   `fetchUsageLimits`：高效并发轮询 `GET /users/me/plan/usage-limits`、`GET /users/me/plan` 与 `GET /users/me` 并进行内存缓存。
    -   `sessionStats` / `recordSessionRequest`：内存级会话度量记录器（请求次数、Token 估算、延迟、时间戳）。
    -   `saveCredentialKey`：将密钥安全写入 `~/.dsh/.credentials.yaml`。
    -   `smokeChat`：毫秒级网络探活与非流式延迟测试，并记录会话指标。
-   **`lib/index.js`**：Cordis 插件主生命周期服务，注册后端 REST API 路由（含 `/dsh-clinebot/models/sync`）、额度预警计算与 `/cline` 聊天斜杠指令。
-   **`lib/client.js`**：插件行配置页（`plugins.row.config`），含预警横幅、会话指标、一键模型同步，以及后备插件卡片（`settings.plugin.item`）。没有 `settings.section` 侧边栏项。

* * *

## 📦 快速安装

在 DeepSeek Harness Web 配置中安装：

```bash
dsh plugin --profile web add @goodandready/dsh-clinebot
```

重启 DeepSeek Harness 实例并刷新浏览器页面。

* * *

## 💬 聊天斜杠指令 `/cline`

在任何聊天会话中输入 `/cline` 即可即时检查配额、预警状态与会话指标：

```text
### 🤖 ClinePass Status (ClinePass)
* 响应延迟: ✅ 210 ms
* 活跃密钥: CLINEBOT_API_KEY (credentials)
* 默认模型: `cline-pass/deepseek-v4.1-flash`

⏱ 5 小时窗口: [████░░░░░░] 42% (重置时间: 18:00)
📅 每周窗口:   [██████░░░░] 60% (重置时间: 09月08日)
* 绑定账号: `developer@example.com`

📈 当前会话统计:
* 请求次数: 14 次
* Token 估算: ~8,450 (Prompt: 6,100 | Completion: 2,350)
* 最近延迟: 210 ms
```

* * *

## ⚙️ 配置项参考 (DSH 设置与 Web UI)

在 DeepSeek Harness 0.2.x（本插件支持 `>=0.2.1-rc.2 <0.2.3-0`）中，各项配置通过 Web UI 或 `PUT /dsh-clinebot/config` 原生管理，密钥安全存储于 DSH Credentials 凭据中心 (`~/.dsh/.credentials.yaml`)。

```yaml
dsh-clinebot:
  enabled: true
  baseUrl: https://api.cline.bot/api/v1
  apiKeyEnv: CLINEBOT_API_KEY
  defaultModel: your-default-model
  disabledModels: []
  customModels: []
  modelReasoningDefaults:
    your-reasoning-model: high
  modelContextOverrides: []
  statsPath: ~/.dsh/clinebot-stats.json
  statsRetentionDays: 95
  dailyBudgetUsd: 0
  monthlyBudgetUsd: 0
  timeoutMs: 30000
  smokeTimeoutMs: 60000
  streamIdleTimeoutMs: 60000
  accounts:
    - label: Team Key
      apiKeyEnv: CLINEBOT_API_KEY_2
```

### 配置参数说明

| 参数项 | 类型 | 默认值 | 说明 |
| :-- | :-- | :-- | :-- |
| `enabled` | `boolean` | `true` | 是否在 DSH 中启用 ClineBot 桥接插件 |
| `baseUrl` | `string` | `"https://api.cline.bot/api/v1"` | ClinePass OpenAI 兼容接口地址 |
| `apiKeyEnv` | `string` | `"CLINEBOT_API_KEY"` | 凭据管理系统中的密钥名称 |
| `defaultModel` | `string` | `"cline-pass/deepseek-v4.1-flash"` | 默认选中的模型 ID（用于对话及探活） |
| `disabledModels` | `array` | `[]` | 在选择器中隐藏的模型 ID 列表（新订阅模型默认自动启用） |
| `customModels` | `array` | `[]` | 用户自定义网关模型 (`[{ id, name, contextLength, maxTokens, category, isReasoning }]`) |
| `modelReasoningDefaults` | `object` | `{}` | 各模型默认思考强度配置 (`low`, `medium`, `high`, `max`) |
| `modelContextOverrides` | `array` | `[]` | 用户自定义模型上下文窗口与最大 Token 数量覆盖 |
| `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | 本地持久化 Token 用量统计文件路径 |
| `statsRetentionDays` | `number` | `95` | 日/小时/会话遥测保留天数；0 表示永久保留 |
| `dailyBudgetUsd` | `number` | `0` | 可选的每日估算花费上限；0 表示关闭 |
| `monthlyBudgetUsd` | `number` | `0` | 可选的每月估算花费上限；0 表示关闭 |
| `accounts` | `array` | `[]` | 额外轮转账号池 (`[{ label, apiKeyEnv }]`) |
| `activeAccount` | `string` | `""` | 手动指定的主账号（为空时自动按最低配额消耗优先路由） |
| `timeoutMs` | `number` | `15000` | HTTP 请求探测超时时间（毫秒） |
| `smokeTimeoutMs` | `number` | `25000` | 探活测试超时时间（毫秒） |
| `streamIdleTimeoutMs` | `number` | `30000` | SSE 流式输出块间空闲超时时间（毫秒） |
| `enabledModels` | `array` | _(已废弃)_ | 仅在 public config 中只读提供，`PUT /config` 时禁止写入并请使用 `disabledModels` |
| `dynamicModels` | `array` | `[]` | 从官方套餐中自动同步的动态模型列表 |

* * *

## 🌐 HTTP API 接口说明

所有接口挂载于 `/dsh-clinebot/*` 路径，并受到跨站请求防护（仅放行同源或环回请求）。管理接口限制请求体上限 256 KiB：

### 管理与控制接口（上限 256 KiB）

-   `GET /dsh-clinebot/status` — 服务运行状态，包括健康探活、当前凭据名称、配额限制及会话统计。
-   `GET /dsh-clinebot/config` — 诊断接口，安全获取脱敏后的公共配置（不含敏感密钥）。
-   `PUT /dsh-clinebot/config` — 更新配置项（严格校验模式，未知字段与已废弃的 `enabledModels` 返回 `400`）。自定义模型通过此处的 `customModels` 管理，没有单独的自定义模型路由。
-   `POST /dsh-clinebot/save-key` — 将 API 密钥安全写入 DSH 凭据服务。
-   `POST /dsh-clinebot/key/verify` — 实时验证 API 密钥有效性，返回绑定邮箱及套餐名称。
-   `POST /dsh-clinebot/smoke` — 发起快速探测并返回 TTFT。
-   `GET /dsh-clinebot/usage` — 当前活动账号的滚动配额窗口。
-   `GET /dsh-clinebot/accounts/usage` — 账号池中所有账号的实时配额。
-   `GET /dsh-clinebot/accounts/history` — 事件环形缓冲区中的冷却、恢复与路由决策记录。
-   `POST /dsh-clinebot/accounts` — 添加多账号备用凭据。
-   `POST` / `DELETE /dsh-clinebot/accounts/delete` — 删除账号（具备原子化凭据保护）。
-   `POST /dsh-clinebot/accounts/active` — 指定活动账号（为空时自动启用最低用量优先路由）。
-   `POST /dsh-clinebot/accounts/rename` — 重命名账号，不触碰密钥。
-   `POST /dsh-clinebot/accounts/key/clear` — 删除账号密钥但保留账号池记录。
-   `GET /dsh-clinebot/keys/discovered` — 本地发现的 Cline 密钥，已脱敏并以不透明 id 标识。
-   `POST /dsh-clinebot/keys/discovered/import` — 按 id 在服务端导入发现的密钥，密钥不会进入浏览器。
-   `POST /dsh-clinebot/models/sync` — 手动同步官方套餐动态模型列表。
-   `POST /dsh-clinebot/models/toggle` — 批量切换模型可用性（更新 `disabledModels` 并保留 Volatile 引用）。
-   `POST /dsh-clinebot/models/context` — 设置上下文窗口与最大输出 Token、恢复默认或厂商上限、批量应用。重置使用同一路由并传入 `reset: true`，不存在 `DELETE` 变体。
-   `POST /dsh-clinebot/models/visible` — 指定在 DSH 模型选择器中显示的确切模型集合（`visibleModels`）。
-   `POST /dsh-clinebot/models/probe` — 测量单个模型的 TTFT。
-   `GET /dsh-clinebot/stats` — 持久化的请求与 Token 统计。
-   `GET /dsh-clinebot/stats/session?sessionId=...` — 单个 DSH 会话的 ClineBot 专属聚合数据。
-   `POST /dsh-clinebot/stats/reset` — 重置会话与 Token 消耗统计。
-   `GET /dsh-clinebot/stats/export` — 导出 CSV，或使用 `format=json`（`detailed=1` 增加列）导出 JSON。
-   `GET /dsh-clinebot/analytics` — 按天、小时、模型、账号与会话聚合；支持 `errorsOnly=1` 与日期区间。
-   `GET /dsh-clinebot/prices` — 供输入框与分析使用的价格表。
-   `POST /dsh-clinebot/prices/sync` — 下载公开价格目录（白名单 https 来源，手动处理重定向）。
-   `GET`, `HEAD` / `POST /dsh-clinebot/update` — `GET`/`HEAD` 返回更新状态；`POST` 启动精确版本的后台安装，含进程组清理与配置锁。

`/dsh-clinebot/register`、`/dsh-clinebot/unregister`、`/dsh-clinebot/v1/chat/completions` 与 `/dsh-clinebot/v1/models` 这些路由并不存在。对话通过原生 `ctx.llm` 适配器完成，不经过 HTTP 代理。

* * *

## 🧪 测试

运行自动化测试套件：

```bash
npm test
```

* * *

## 📄 许可证

MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

## 常见问题

### @goodandready/dsh-clinebot 是什么？

ClineBot / ClinePass 的 DeepSeek Harness 伴侣:动态订阅模式同步,配额耗尽警告,会话度量,专用设置页面,活用限制,和/cline slash-command\.

### 如何安装 @goodandready/dsh-clinebot？

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

### @goodandready/dsh-clinebot 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/goodandready\_\_dsh-clinebot 是否存在。

### @goodandready/dsh-clinebot 支持 ESM 还是 CommonJS？

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

### @goodandready/dsh-clinebot 需要什么版本的 Node\.js？

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

### @goodandready/dsh-clinebot 可以商用吗？

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

### @goodandready/dsh-clinebot 的下载量有多少？

根据 npm 官方下载统计，@goodandready/dsh-clinebot 在 2026/10/17 – 2026/11/15 这 30 天内被下载 10,338 次，日均约 345 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @goodandready/dsh-clinebot 还在维护吗？

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

