dsh-key-usage
DeepSeek Harness 侧边栏「使用情况」：按通道展示用量明细、活跃热力图、项目/会话用量与官方余额/配额（实时优先，失败回落快照）
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add dsh-key-usage@0.2.0Key Usage 以 dsh-key-usage 发布，当前版本为 0.2.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
DeepSeek Harness 的侧边栏用量面板 —— 按通道看 Token、缓存命中率、成本，以及余额与订阅窗口。
装上之后，左侧边栏会多一项「使用情况」，点开就是整页的用量面板：Key 清单 + 活跃热力图、使用明细、项目用量、会话用量、余额与配额。全部数据来自你自己的机器，默认不联网。
它和同类插件的两个区别：
/user/balance），查不到才回落本机快照，并把失败原因写在卡片上。dsh plugin --profile web add dsh-key-usage
装完三步：
桌面端：
--profile desktop由 Electron 应用独占，CLI 会拒绝，请在应用内的 Plugin Hub → 安装插件 里填dsh-key-usage。
# 从 GitHub 装（等价，包内含构建产物，不需要本地编译）
dsh plugin --profile web add github:xyl886/dsh-key-usage
# 本地开发：软链到本仓库，改文件即时生效
dsh plugin --profile web add link:/path/to/dsh-key-usage
# 卸载
dsh plugin --profile web remove dsh-key-usage
curl -s http://127.0.0.1:19387/dsh-key-usage/channels # 返回 { channels: [...] } 即已挂载
7 个端点全部只读 GET，且只接受 127.0.0.1 / ::1 回环请求，非回环一律 403。
总览
使用明细
项目用量
会话用量
余额与配额
演示数据，由设计稿原型渲染（
docs/prototype/）。
| 读取对象 | 用途 | 说明 |
|---|---|---|
$DSH_HOME/dsh-usage/usage-ledger.json | 用量台账 | 按天 × 通道 × 模型，含官方成本 |
$DSH_HOME/dsh-usage/provider-snapshots.json | 余额 / 窗口回落值 | 仅在实时查询失败时使用 |
$DSH_HOME/profiles/<profile>/cordis.yml | 通道清单 | 只做文本提取，不执行其中的 !!js 表达式；取不到时回退 cordis.patch.yml |
宿主 sessionPersistence 服务 | 项目 / 会话 / 按小时 | 只开只读句柄（open("read") → read(0) → close），不自行解压会话文件 |
宿主 credentials 服务 / 进程环境变量 | 查余额时的 API Key | 只用于拼 Authorization 请求头 |
会联网的唯一路径：打开「余额与配额」时按通道请求官方接口，结果缓存 60 秒（点「刷新」强制重查）：
| 通道 | 接口 |
|---|---|
opencode-go | GET https://opencode.ai/zen/go/v1/usage（rolling / weekly / monthly） |
deepseek-official | GET {baseURL}/user/balance |
openrouter / moonshotai / zai | 各自的官方余额接口 |
请求 6 秒超时、响应上限 64 KiB、只发 Authorization 与 Accept 两个头；任何失败都回落本机快照并在卡片上说明原因。
.credentials.yaml；密钥不落盘、不进日志、不返回给前端；界面只显示 apiKeyEnv 这类变量名。| 项 | 要求 |
|---|---|
| DeepSeek Harness | 桌面端 0.2.x（客户端 slot：sidebar.panellist + main）；web profile 同样支持 |
| Node.js | ≥ 22（宿主内置） |
| 运行时依赖 | 无。react / react/jsx-runtime 由宿主注入，服务端只用 Node 内置模块 |
| 必需服务 | 无 |
| 可选服务 | sessionPersistence（缺失时项目 / 会话 / 按小时降级为空态）、credentials（缺失时余额只能读快照） |
数据优先取宿主用量台账；台账长期不更新时，没有记录的日期会回退到本地会话事件折叠补齐（页脚口径说明会显示当前有多少天是会话补位的）。两套来源按天取舍、不相加，所以不会重复计数，但会话补位的那几天没有官方成本。
需要宿主 credentials 能解析该通道的 apiKeyEnv（如 OPENCODE_GO_API_KEY），或该变量存在于宿主进程环境里。解析不到时插件不会去读凭据文件，而是直接回落快照。
按可见区间内活跃日的三分位分档（p33 / p67），不是固定阈值 —— 这样低用量和高用量都能看出层次。
免费额度、本地端点没有成本概念；由会话事件补位的日期也没有官方成本。项目 / 会话 / 按小时视图统一不计成本（页脚口径里有说明）。
客户端资源需要刷新页面，服务端需要退出重开 DSH。桌面端的卸载同样在 Plugin Hub 里操作。
node node_modules/tsdown/dist/run.mjs && node scripts/normalize-client-banner.mjs # 构建客户端 → client/client.js
node node_modules/typescript/bin/tsc -p tsconfig.server.json # 构建服务端 → lib/
node node_modules/typescript/bin/tsc -p tsconfig.json --noEmit # 类型检查
node test/ledger.test.mjs # 其余：collect / channels / session-usage / sessions / merge / live-quota / routes
改动生效条件（最容易踩的坑）：
| 改动 | 生效方式 |
|---|---|
src/client/** | 重新构建 → 刷新页面 |
src/server/** | 重新编译 lib/ → 退出重开 DSH（无热重载） |
另外两个坑：tsc --noEmit 不会更新 lib/，而测试读的是 lib/*.js；cordis.yml 是应用重写的组合产物，插件集变化期间会短暂变成空模板，因此通道提取会回退到 cordis.patch.yml。
目录结构
src/client/ index.tsx（slot 注册）· UsagePage / UsageIcon · KeyUsageSection（Tab 外壳）
tabs/（5 个页面）· components/ · styles/（CSS Module，basename 全局唯一）
src/server/ index.ts（cordis apply）· routes.ts（7 个只读端点）
ledger.ts（台账）· collect.ts（通道判定）· merge.ts（台账 × 会话按天合并）
live-quota.ts（官方余额实时查询 + 缓存）· sessions.ts / session-usage.ts（会话折叠）
lib/ client/ 构建产物（发布必须带，git 与 npm 都提交）
客户端注册的是 sidebar.panellist（导航项）+ main（主区域整页），与官方 dsh-context「上下文洞察」同一套写法。
延伸文档：架构与数据契约 · 原型差异清单 · 按 Tab 重构方案 · 会话归档的影响 · AGENTS.md
MIT © 2026 xyl886
非官方社区插件，与 DeepSeek 无隶属关系。