本文由本站基于该插件已收录的字段自动派生（wiki / faq / compatibility_json / readme），非 AI 即时创作。每节末尾标源字段。

快速上手

dsh-usage

— 源: plugin_wiki.wiki_content

安装与验证

dsh plugin --profile web add dsh-usage

复制以上命令在 DSH Web Profile 内运行。安装完成后在「插件列表」启用即可。

— 源: plugins.install

关键要点

• 🟢 余额 — 健康时绿色，欠费时红色
• 📊 今日 / 本月 / 缓存命中 — 一眼尽收的用量数字
• ⚙ 齿轮开详情 · ↻ 一键刷新
• 🧲 与 pin 设置同步 — 每次调整立即生效
• API Key 永不进入浏览器响应、插件缓存或日志；凭据由 Harness credentials seam 在请求时解析。

— 源: plugin_wiki.readme_zh (fallback readme_raw)

常见问题

安装后看不到悬浮窗怎么办？

安装或更新本插件后必须重启 dsh web 并在浏览器硬刷新（Ctrl/Cmd+Shift+R）。三个服务端路由和客户端 bundle 都在 dsh web 启动时挂载，仅刷新浏览器不会重新装载。cordis.patch.yml 只向 web profile 追加 1 行 Loader，重复运行 dsh plugin --profile web add 是幂等的，不会重复挂载（cordis.patch.yml:1-5 / package.json:29-41 / README.md:67-80）。

不配置任何 Key 能用吗？

可以。Token 用量、缓存命中、活跃热力图和用量记录完全无需凭据，会自动从所有会话的事件流聚合。没有公开余额接口的 provider 在余额卡片显示"该供应商无公开余额接口"，插件不会乱猜；缺 Key 的 provider 显示"未配置"，并在提示里写出对应的凭据引用名（如 DEEPSEEK_API_KEY），让你直接去 ~/.dsh/.credentials.yaml 补齐（lib/index.js:191-244 / lib/balance.js:20-87 / README.md:82-101）。

余额走哪些供应商接口？需要哪种 Key？

内置 4 套余额 scheme：DeepSeek 官方 GET {origin}/user/balance 用 DEEPSEEK_API_KEY、OpenRouter GET {origin}/api/v1/credits 用独立的 OPENROUTER_MANAGEMENT_KEY（不能用推理 Key 试探）、Moonshot/Kimi GET {origin}/v1/users/me/balance 自动复用 pi-ai provider profile 里的 apiKeyEnv、Z.ai/GLM GET {origin}/api/paas/v4/balance 用 ZAI_API_KEY；通过 Harness 的 credentials seam 在请求时实时解析，Key 值从不进入缓存、日志或浏览器响应（lib/balance.js:20-87 / lib/index.js:130-140 / README.md:82-101）。

数据存在哪里？会不会上传？

服务端缓存写到 $DSH_HOME/storages/usage-cache.json（DSH 用量聚合，版本 v2）和 $DSH_HOME/storages/usage-cache-claude.json（Claude Code 聚合，版本 v1），采用临时文件 + 原子 rename 写入；只保存 Token 数、provider/model 折叠结果与文件读游标。客户端设置（主题、widget 顺序、显隐、pin 状态、停靠偏移）持久化在浏览器 localStorage 的 dsh-usage:settings:v1。Claude Code 日志逐行解析即弃，只有数字进入缓存，对话文本永不落盘（lib/index.js:291-305 / lib/claude.js:60-103 / lib/client.js:313 / README.md:123-128）。

"通道占比"是怎么算出来的？

通道占比 widget（dual）对比两组 Token 数：DSH 通道来自 Harness 当前活跃 + 持久化会话的事件折叠（增量），Claude Code 通道来自扫描 $CLAUDE_CONFIG_DIR/projects/**/*.jsonl（默认 ~/.claude/projects），每条 assistant 消息里的 usage 字段聚合进同样的按天/按小时桶。如果 ~/.claude/projects 不存在，widget 显示"未检测到 Claude Code 日志"而不是数字（lib/claude.js:14-16 / lib/claude.js:193-214 / lib/client.js:949-973）。

悬浮窗里能 pin 哪些 widget？

7 个 widget 中只有 4 个可以固定到底栏：余额、今日用量、本月用量、缓存命中。活跃热力图、通道占比、用量记录按设计就是大尺寸展示型，pin 按钮会隐藏（代码常量 WIDGET_PINABLE 在 lib/client.js:319 写死）。默认 5 个 widget 已开启可见，其中前 4 个默认 pin，热力图默认可见但不 pin，通道占比和用量记录默认可见且不 pin，全部可在面板顶部"上移/下移/固定/隐藏"逐项调整（lib/client.js:317-336）。

反向代理能否把端点暴露到公网？

不建议。三个端点（/api/usage/{providers,balance,usage}）只校验 peer socket 是否回环 + Host header 是否 localhost 或 127.0.0.1，不做身份认证；如果挂在反代后面，插件看到的 peer 会是代理自己的回环地址，安全边界就被绕过了。README 明确"不要把端点经反向代理暴露到局域网或公网；确需代理时必须在代理层增加可靠认证与访问控制"（lib/index.js:81-125 / README.md:129）。

如何卸载？

dsh plugin --profile web remove dsh-usage 重启 dsh web 即可。两份缓存文件（usage-cache.json 与 usage-cache-claude.json）留在磁盘上，需要时手动删除；浏览器 localStorage 里的 dsh-usage:settings:v1 不会自动清理。安装 / 更新时不需要重启浏览器侧任何其他状态（README.md:75-80）。

— 源: plugin_wiki.faq_json

兼容性

• DSH: >=0.1.0-rc.6
• Node: 未声明
• Platforms: 跨平台

— 源: plugin_wiki.compatibility_json

踩坑提醒

安装前请审阅上游仓库；本指南基于已收录字段自动派生，可能滞后于最新版本。如发现与官方文档冲突，请以上游为准。

— 来源：通用规则