dsh-commandcode-quota: DeepSeek Harness Command Code Balance and Quota Dashboard

前言¶

在使用 DeepSeek Harness (DSH) 进行开发或交互时，实时监控 Command Code 的账户余额以及配额窗口（5 小时、每周、每月）的使用情况非常重要。dsh-commandcode-quota 插件通过在 DSH Composer 下方渲染一个紧凑的状态行，解决了这一需求，让配额监控无需离开主界面。

插件介绍¶

该插件由用户 fuqiancheng 维护，是一款单账户设计的状态面板工具。

它不会在浏览器中接收或存储 API Key，所有凭证处理均在本地进程中进行。插件会在 DSH 界面上显示余额，并以实时百分比展示 5 小时、每周和每月的使用窗口。点击状态行可展开查看详细的账单、Token 使用量、成功率、订阅信息及账户详情。

安装与启用¶

基础安装¶

推荐从 npm 安装：

dsh plugin add dsh-commandcode-quota

DSH 会自动将打包的 cordis.patch.yml 扩展到你的配置中，无需手动编辑补丁文件。

本地开发安装¶

如果从本地代码仓库安装：

dsh plugin add file:/path/to/dsh-commandcode-quota

桌面应用手动安装¶

Electron 桌面应用的管理方式与 Web 客户端不同，dsh plugin add 命令不会自动处理插件的挂载。你需要手动创建 Junction 并编辑配置文件。

创建 Junction
在 PowerShell 中执行以下命令，将本地包链接到 DSH 的共享解析池：

   New-Item -ItemType Junction `
     -Path "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-commandcode-quota" `
     -Target "C:\path\to\dsh-commandcode-quota"

配置补丁
编辑 ~/.dsh/profiles/<profile>/cordis.patch.yml，添加以下内容：

   - insert:
       - id: dsh-commandcode-quota
         name: 'dsh-commandcode-quota'
         config:
           apiKeyEnv: COMMANDCODE_API_KEY

注意：Junction 的名称必须与包名完全一致，否则宿主无法解析导入。

安装或修改插件后，请刷新插件树（在插件页面点击刷新，或重启客户端）。

配置说明¶

插件依赖 Command Code 的 API Key，该 Key 通过 DSH 的凭证服务解析，不会暴露给浏览器。

配置项	默认值	说明
`apiKeyEnv`	`COMMANDCODE_API_KEY`	凭证解析的环境变量名
`fallbackEnv`	—	当第一个变量缺失时使用的备用环境变量名（可选）
`baseURL`	`https://api.commandcode.ai`	Command Code API 的基础地址
`timeoutMs`	`30000`	单次请求的超时时间（毫秒）

凭证文件位于 ~/.dsh/.credentials.yaml 或在 DSH 设置 → 凭证中管理。切勿将包含凭证的文件提交到版本控制系统。

功能特性¶

状态行展示
在 Composer 下方渲染一个紧凑的状态行，实时显示可用余额以及 5 小时、每周、每月的使用率百分比。
展开详情
点击状态行可展开详细数据面板，包含：
* 已使用/限制/剩余额度及重置时间
* 总花费
* Token 统计
* 成功率
* 订阅状态
* 账户信息
安全设计
* 单账户设计，无账户切换器。
* API Key 仅在本地进程内存中读取，绝不发送至浏览器端。

工作原理¶

插件采用“主机-客户端”分离架构：

主机端：负责解析凭证，注册一个只读的 HTTP 端点，将请求转发至 Command Code API，并将结果聚合为单一 Payload。
客户端：将状态行注入到 DSH 的 Dock Slot 中，定时轮询主机端点，并根据 DSH 的主题 Tokens 进行渲染，确保适配浅色/深色模式。

数据来源于四个 Command Code API 端点：
* /alpha/billing/credits：余额及 5 小时/每周限制
* /alpha/usage/summary：花费、Token 及成功率
* /alpha/billing/subscriptions：订阅状态及周期
* /alpha/whoami：账户信息

故障处理策略¶

插件在请求异常时的行为如下：

并行请求：四个 API 请求并行执行，总延迟取决于最慢的那个，而非总和。
重试机制：连接层失败会重试一次；超时请求不重试。
缓存回退：当所有请求失败时，面板会显示最后一次成功获取的数据（在进程内存中保留 6 小时），并标记为过期。
错误提示：HTTP 401（认证失败）不会使用缓存数据，会立即提示错误，确保用户能发现 Key 配置问题。

注意事项¶

环境要求
* 需要运行 DeepSeek Harness 的 Web 客户端（dsh web）或桌面应用。
* 本地需要安装 Node.js 20 或更高版本。
* 需要有效的 Command Code API Key。
桌面应用特殊说明
桌面应用默认不运行 dsh plugin add 的同步逻辑，因此必须按照上述“桌面应用手动安装”章节中的步骤手动配置 Junction 和 cordis.patch.yml。
许可证
本插件遵循 MIT 许可证，开源托管在 GitHub。安装前建议检查源码以确保符合你的项目需求。