前言¶
DeepSeek Harness (DSH) 采用插件化架构，旨在将功能扩展与核心应用解耦。在使用 Ollama Cloud 服务时，开发者需要关注会话窗口、每周额度以及具体的请求成本。原生的 ollama.com 设置页与 DSH 界面分离，无法直接在开发环境中查看剩余额度或管理 API Key。
dsh-ollama-cloud-usage 插件通过注册 settings.section，在 DSH 设置页的“账号与余额”下方新增了一个名为 ollama-quota 的配置区块（order: -9）。该区块直接展示 Cloud 配额数据，并集成了 API Key 的编辑功能，解决了监控与配置割裂的问题。
插件定位¶
- 名称:
dsh-ollama-cloud-usage - 作者: adamaik
- 定位: DeepSeek Harness 插件，用于在本地 DSH 界面中查看 Ollama Cloud 剩余额度及管理 API Key。
- 解决的问题: 解决了在 DSH 环境下无法查看 Cloud 配额、无法快速切换或编辑 API Key 的痛点。
核心功能¶
该插件通过轮询 ollama.com/api/usage 接口获取数据，并利用 DSH 的 Remote 机制处理凭证。
配额显示¶
在设置页的 ollama-quota 区块中，插件显示以下信息：
* Session 窗口剩余: 数值范围为 [0, 1]。
* Weekly 窗口剩余: 直接数值。
* 每模型请求计数: 针对各个窗口的 limits.<window>.models[].request_count。
* 最近 4 周成本: 显示 activity.cost 和 activity.period。
API Key 管理¶
- 编辑器: 提供一个输入框，用于编辑或替换 API Key。
- 写入机制: 仅编辑列表中第一个
keyEnvs引用的 Key。 - 存储路径: 保存至
$DSH_HOME/.credentials.yaml。 - 安全机制: Key 从不在浏览器中渲染，输入框始终为空，API 返回的数据中不包含明文 Key。
安装与启用¶
从 npm 仓库安装该插件：
dsh plugin --profile <profile> add dsh-ollama-cloud-usage
注意：
1. 如果安装后 Host 行未出现，请重启 DSH 应用。
2. 客户端更新通常需要刷新页面生效（桌面应用目前不支持客户端热重载）。
配置说明¶
插件支持通过配置文件自定义行为。默认配置如下：
| 配置项 | 默认值 | 说明 |
|---|---|---|
keyEnvs |
["OLLAMA_CLOUD_API_KEY", "OLLAMA_API_KEY"] |
优先尝试读取的凭证引用顺序，仅第一个可编辑 |
refreshMs |
60000 |
快照刷新间隔，最小 5000 |
timeoutMs |
15000 |
请求超时时间 |
示例配置¶
在 DSH 的配置文件中，可以通过 YAML 语法覆盖上述默认值：
- id: ollama-cloud-usage
config:
refreshMs: 120000
凭证配置¶
插件通过 ctx.credentials 读取 Key，支持环境变量、$DSH_HOME/.env 或 $DSH_HOME/.credentials.yaml 中的 refs。
$DSH_HOME/.credentials.yaml 示例：
version: 1
refs:
OLLAMA_CLOUD_API_KEY: ollama_cloud_api_key_here
注意事项¶
- 平台限制: 仅支持 Web 平台。
- 环境要求: 需要 Node.js 版本
>= 22.19.0。 - 编辑限制: 仅
keyEnvs列表中的第一个引用支持编辑，后续引用仅作只读展示。 - 更新机制: 采用轮询方式获取数据，而非推送更新。在凭证更新时会自动触发刷新。
- 数据缺失:
ollama.com/api/usage接口不返回计划名称和重置时间戳，因此插件界面只显示窗口剩余量。 - 验证脚本: 项目包含
scripts/verify.mjs，可离线验证 Host 路由和 Client 组件渲染逻辑。
结语¶
dsh-ollama-cloud-usage 插件为 DSH 用户提供了原生的 Cloud 配额监控入口，并兼顾了 API Key 的安全性管理。它通过标准的 DSH Remote 接口与凭证系统交互，适合需要在本地开发环境中频繁切换或监控 Ollama Cloud 资源的使用者。
- 插件目录: SkillHub 插件目录
- 源码地址: GitHub
