⚡ dsh-ollama-usage
Ollama Cloud 用量余量可视化 · DeepSeek Harness 插件
可视化你的 Ollama Cloud 用量余量 —— 每 5 小时会话用量 + 周用量，
侧边栏极简双横条常驻显示，设置页完整面板，Key 与快照持久化，自动刷新。
Ollama Cloud usage & remaining-quota visualization for DeepSeek Harness —
5-hour session + weekly quota, always-visible sidebar bars, a full settings
panel, persisted credentials & snapshots, auto-refresh.
兼容性 / Compatibility：v0.1.6 支持 DSH ≥0.1.2-alpha.4（真实 alpha.4 RPC envelope 探针全过）；旧版 DSH（0.1.0-rc.5 ~ rc.8）请使用最后兼容的 npm 版本 0.1.5。
v0.1.6 targets DSH ≥0.1.2-alpha.4; for older DSH releases use the last compatible npm version 0.1.5.
✨ 功能特性 Features
| 能力 | 说明 |
|---|
| 🎯 会话用量（每 5 小时） | Ollama Cloud 的 5 小时会话配额，置顶展示「已用 X% · 剩余 Y%」 |
| 📅 周用量（Weekly） | 本周配额进度，与会话用量并排展示 |
| 🎨 侧边栏双横条 | 极简透明风格：会话 5h 淡紫 + 周用量深紫，各带百分比数字，悬停显示详情，每 60 秒自动更新（窄栏自动隐藏） |
| 🖥️ 设置页完整面板 | 会话/周用量进度条、周用量重置倒计时、模型请求数排行、最近 5 条会话用量历史 |
| 💾 持久化 | API Key 与用量快照写入 $DSH_HOME/storages/ollama-usage/usage.json（权限 600，保留 24 条历史），跨对话 / 重启自动恢复 |
| 🔄 自动刷新 | Host 每 10 分钟自动查询（页面关闭也持续）；Key 失效（401）自动清除并提示 |
| 🔑 登录引导 | 未登录时一键打开 ollama.com/settings 登录、到 settings/keys 创建 API Key；兼容旧版 CLI 的 ~/.ollama/auth.json |
数据来源为 Ollama 官方接口 GET https://ollama.com/api/usage，与
ollama.com/settings 页面一致。
📦 安装 Install
dsh plugin --profile web add dsh-ollama-usage
dsh --profile web
也可手动把 dsh-ollama-usage 加入 profile package.json 的
dsh.profile.bundles 后重启。
🚀 使用 Usage
- 打开 设置 → Ollama 用量；
- 未登录时按面板指引：登录 ollama.com →
settings/keys 创建 API Key →
粘贴并点 检测（或终端
ollama signin 后点 重新检测本地凭证）；
- 检测成功后即持久化，展开侧边栏即可看到底部双横条，面板可随时查看详情与历史；
- 不再需要时点 清除已存 Key 移除本地凭证（历史保留）。
🔒 数据与隐私 Privacy
- 仅向
https://ollama.com/api/usage 发送带 Bearer 的查询请求；
- Key 以明文保存在本机
$DSH_HOME/storages/ollama-usage/usage.json（权限 600，
与 ~/.ollama/auth.json 同等级信任），随时可清除。
🏗️ 架构 Architecture
┌──────────────────────────┐ ┌─────────────────────────────┐
│ browser (client bundle) │ RPC │ host (lib/index.js) │
│ lib/client.js │◄──────►│ webServer /ollama-usage │
│ · sidebar dual bars │ 信封协议 │ · fetch api/usage (Bearer)│
│ · settings panel │ │ · $DSH_HOME 持久化(0600) │
│ · login guidance │ │ · 10min auto-refresh │
└──────────────────────────┘ └─────────────────────────────┘
- 宿主入口
lib/index.js：ESM，导出 name + 默认插件；webServer 前缀路由 +
Connection RPC 信封协议（check / snapshot / forget / auth-state）。
- 客户端入口
lib/client.js：window.__ModuleLoader__.load bundle，经
connection.rpc.call('/ollama-usage', endpoint, payload) 与宿主通信。
- 接线：
cordis.patch.yml（Loader 行）+ package.json 的
dsh.bundle.patch / dsh.client 声明。
🧪 测试 Tests
DSH_HOME=.tmp-dsh-home HOME=.tmp-home node test/bridge-smoke.mjs
17 项冒烟测试覆盖：路由注册、no-token / 401 分支、持久化读写与清理、
snapshot / forget / auth-state、非法信封与请求方法校验。
🛠️ 开发 / 发布 Develop & Publish
npm install # 安装依赖(@deepseek-ai/dsh-home-paths)
npm test # 冒烟测试(见上)
npm pack # 本地打包检查
npm publish # 发布到 npm
📄 License
MIT © 2026 dsh-ollama-usage contributors
