dsh-token-console
DiscoveredLocal read-only AI token usage and account quota dashboard (DSH / Claude Desktop / Codex), runs as a DSH plugin
AI Token 观测站 · Token Observatory
一个跑在本机、只读记录的 AI token 用量与账号额度控制台。 支持客户端:DSH(DeepSeek Harness)、Claude 桌面端、Codex(ChatGPT 桌面端); 支持提供方额度:DeepSeek、Claude、OpenCode Go、OpenAI/Codex。

上图为本机真实数据。v2「令牌账簿」极简版(暖纸、衬线数字、陶土强调、「消费墨痕」Hero)。更多尺寸见
docs/shots/;设计规格见SPEC-v2-design.md。也可以作为 DeepSeek Harness 插件运行(DSH 侧边栏入口 + 主面板内嵌仪表盘):
快速开始
cd token-console
node server/index.mjs # Node.js >= 22.5
# 打开 http://127.0.0.1:8787
macOS 上也可以直接双击 start.command:自动找 Node、启动服务并打开浏览器。
关闭终端窗口即停止记录(数据都保存在本地,重新启动会继续增量采集)。
作为 DSH 插件运行
除独立服务外,本项目还包含一个 DSH Host + Client 插件(dsh-plugin/):
- Host:在 DSH 进程内启动同一套只读采集/额度运行时,通过
ctx.webServer在 DSH Web 的/token-console/提供仪表盘与 API; - Client:在 DSH Web 侧边栏注册「令牌账簿」入口,主面板内嵌
/token-console/(同源、零样式冲突)。
安装(本地 link:,需先拿到本仓库完整代码):
cd ~/.dsh/profiles/desktop
pnpm add "link:/ABSOLUTE/PATH/TO/token-console/dsh-plugin"
# 在 profile 的 cordis.patch.yml 末尾追加:
# - insert:
# - id: token-console
# name: dsh-token-console
# 然后重启 DSH
完整说明(配置项/卸载/兼容性)见 dsh-plugin/README.md;集成方案与 DSH 插件机制调研见 docs/DSH-PLUGIN-PLAN.md。
自动化验收(隔离 DSH_HOME,不碰你的真实 profile):
node scripts/test-plugin.mjs # HTTP 级(13 项断言)
node scripts/test-plugin.mjs --browser # + headless Chrome 验证侧边栏/iframe
功能
- 按客户端记录:DSH / Claude 桌面端 / Codex 的 token 用量(输入、输出、缓存读/写、按天/小时/会话/模型)。
- 按提供方记录(真实消耗口径):DeepSeek / Claude / OpenCode Go / OpenAI 的消耗 = OpenCodeX 网关账单 + 各客户端直连,独立于客户端本地日志口径(Codex 本地日志可能不完整,网关才是完整账单)。
- 两种口径分开呈现、不会混淆:客户端卡片 = 本地日志口径;额度卡上的「今日/30 日/全量」消耗 +
网关账单pill = 网关+直连口径。API 返回basis字段说明。 - 账号剩余额度:
- DeepSeek:平台账户余额(CNY) + API 余额
- Claude:5 小时 / 每周用量百分比(优先 Anthropic OAuth 活取,兜底读 Claude 桌面端的本地上报)
- OpenCode Go:rolling(5 小时)/ weekly / monthly 百分比与重置时间
- OpenAI / Codex:5 小时 / 每周用量百分比、credits、重置时间
- 可视化(v2「令牌账簿」):暖纸色 + 衬线大数字 + 陶土强调的极简编辑式界面。核心 Hero「消费墨痕」——90 天每日消耗是一根按客户端堆叠的墨痕(√ 刻度),今天那根随采集实时生长、笔尖呼吸;其余:7/30/90/全部 细线趋势图、24 小时细柱、客户端三卡 + sparkline、模型排名条、30 天点阵热力图、实时台账。中文界面,支持深色模式与
prefers-reduced-motion。 - 记录:SQLite(
data/console.db,WAL),每 20 秒增量采集一次,额度每 3 分钟探测一次;重启不重复计数。
数据从哪来(只读)
| 客户端 | 来源 |
|---|---|
| DSH | ~/.dsh/sessions/**/session.v4.jsonl.zstd(逐次 LLM 调用的 usage 事件) |
| Claude 桌面端 | ~/.claude/projects/**/*.jsonl(每条 assistant 消息的 usage) |
| Codex | ~/.codex/sessions/**、~/.codex/archived_sessions/**(token_count 事件与 rate_limits) |
| OpenCode Go / 网关 | ~/.opencodex/usage.jsonl、~/.opencodex/codex-quota-cache.json |
额度探测只调用:api.deepseek.com、platform.deepseek.com、opencode.ai/zen/go/v1/usage、api.anthropic.com(仅在存在 OAuth token 时),凭证全部从本机既有配置读取,不会上传或写入日志/接口响应/前端。
口径说明
- 总 token = 输入 + 输出 + 缓存读 + 缓存写(
reasoning是输出的子集,不重复计)。 - “今日总量”= 三个客户端之和;网关日志用于提供方维度与独立账单,不与 Codex 客户端日志重复相加。
- “等效 API 价值”按
config/pricing.json的公开单价估算,不代表实际订阅账单。 - Claude 额度若来自
plan-usage-history.json,会标注「Claude 桌面端上报」及采样时间。
目录结构
token-console/
├── start.command # 双击启动
├── server/
│ ├── index.mjs # HTTP 服务 + 调度
│ ├── api.mjs / store.mjs / util.mjs / config.mjs
│ ├── collect.mjs # 采集编排
│ ├── collectors/ # dsh / claude / codex / opencodex
│ ├── probes/ # deepseek / claude / opencodego / openai-codex
│ └── credentials.mjs # 本机凭证发现(只在内存中使用)
├── web/ # 前端(原生 ESM + Canvas + three.js)
├── config/
│ ├── default.json # 默认配置(端口、间隔、路径)
│ └── pricing.json # 单价估算表
├── docs/ # 截图 / DSH 插件集成方案(DSH-PLUGIN-PLAN.md)
├── SPEC-v2-design.md # v2「令牌账簿」设计规格
├── dsh-plugin/ # DSH 插件(Host: lib/index.js + Client: lib/client.js)
├── data/ # 运行期生成:console.db / console.log
└── scripts/
├── smoke-test.mjs # 端到端自检
├── test-collectors.mjs # 采集器单测
└── test-probes.mjs # 额度探测单测
配置
编辑 config/default.json(或新建 config/local.json 覆盖同名键):
port:默认8787,仅监听127.0.0.1collectIntervalMs:采集间隔,默认20000probeIntervalMs:额度探测间隔,默认180000sources.*:各数据源路径(默认已在上面列出)probes.enabled:设为false可完全关闭联网额度探测
命令行参数:node server/index.mjs --port 8788 --no-probes
自检
node scripts/smoke-test.mjs # 全链路:采集→幂等→探测→API→HTTP→静态资源
node scripts/test-collectors.mjs # 只测采集
node scripts/test-probes.mjs # 只测额度探测
node scripts/seed-demo-db.mjs # 生成脱敏演示数据库(公开截图用)
node scripts/test-plugin.mjs [--browser] # DSH 插件集成测试(隔离 DSH_HOME)
node scripts/cdp-check.mjs # 页面 DOM/无横向滚动/颜色采样等 CDP 检查
./scripts/screenshot.sh 8787 docs/shots # 多尺寸截图(Chrome headless)
验收状态(本机实测)
node scripts/smoke-test.mjs→ 19/19 通过:4 源采集、增量幂等(重复采集 0 新增)、额度 4 提供方、overview/timeseries/limits/live/sessions、HTTP 接口、静态资源、POST /api/collect。node scripts/test-collectors.mjs→ 17/17 通过;全量首扫约 0.7s,二次采集inserted=0。node scripts/test-probes.mjs→ PASS(真实网络,4 个提供方均返回可用/降级状态,零密钥泄露)。- 重启幂等:重启服务后事件数无重复计数(仅新增数据)。
- DSH 插件集成测试
node scripts/test-plugin.mjs --browser→ 13/13 通过:隔离 profile 物化、pnpm link、patch 注入、DSH Web 启动、/token-console/api/*(health/limits/overview/collect)、静态资源、侧边栏「令牌账簿」入口、iframe 面板加载与数据渲染、0 console error。 - 前端(v2):4 种宽度(1024/1440/1600/1920)0 console error / 0 warning,无横向滚动;
?static=1、?range=7|90|all、reduced-motion 均验证通过;关键 DOM(墨痕 90 根/额度 4 行/热力 720 点/台账 40 行)齐全,详见docs/shots/self-check.json。 - 数据为演示/脱敏样例(见
docs/shots/):示例客户端口径 DSH 61.3M / Claude 142.7M / Codex 43.7M tokens;提供方口径 OpenCode Go 52.5M / OpenAI 54.0M / Claude 142.7M / DeepSeek 28.3M(均为合成数据,可用node scripts/seed-demo-db.mjs复现)。 - 额度为演示样例:DeepSeek 余额 ¥128.40;OpenCode Go 5h 18% / 每周 42% / 每月 9%;Claude 5h 34% / 每周 61%(示例);OpenAI 5h 22% / 每周 9% / credits 12。
Claude 实时额度(可选,默认关闭)
默认情况下 Claude 额度来自 Claude 桌面端自己写入的 ~/Library/Application Support/Claude/plan-usage-history.json(面板会标注「Claude 桌面端上报 · 采样于 X 前」),不联网、零风险,但可能滞后(取决于你多久打开一次 Claude 桌面端)。
如果希望更实时,可以提供 Claude Code 的 OAuth access token,让控制台直接查询官方只读的用量接口:
# 方式 A:环境变量(不落盘,进程重启后需重新设置)
export CLAUDE_CODE_OAUTH_TOKEN="<你的 Claude Code access token>"
node server/index.mjs
# 方式 B:~/.claude/.credentials.json(Claude Code 自己维护的文件,含 claudeAiOauth.accessToken)
# 控制台会自动只读该文件
只会发生:每 3 分钟一次 GET https://api.anthropic.com/api/oauth/usage(Authorization: Bearer <token>),解析 five_hour / seven_day 百分比。
不会发生:
- 不调用任何模型/推理接口(不消耗额度、不产生对话);
- 不刷新/轮换/写回 token(不碰
~/.claude/.credentials.json,不写钥匙串); - 不读 Cookie、不登录、不修改 Claude 的任何文件;
- token 只在内存里用一次,不写日志、不写数据库、不返回给前端(代码里有全链路脱敏)。
- 钥匙串读取默认关闭(
config.probes.claudeKeychain=false),只有你显式改成true才会读。
关于封号风险(如实说明):读取自己账号的用量百分比不是滥用行为,这个接口正是 Claude Code 官方 /usage 指令使用的只读接口;每 3 分钟一次的频率等同于正常使用,正常风险极低。但客观地说:在第三方程序中直接使用 Claude 的 OAuth token,属于官方文档未承诺的用法,因此不能保证 100% 零风险(这是所有第三方客户端共有的灰色地带,与「用量监控」本身无关)。如果你对风险敏感,保持默认的桌面端上报即可。
安全提醒:token 等同于账号凭证。不要粘贴到聊天/截图/公开仓库;建议用本地环境变量或 ~/.claude/.credentials.json,不要写进项目配置。若怀疑泄露,在 Claude 账号里退出所有设备后重新登录,旧 token 会随之失效。
实测:本机没有可用的 Claude OAuth token(keychain 里 41 个条目均为 MCP OAuth,无
claudeAiOauth)。用假 token 做降级测试时,接口返回 403 且控制台自动回退到桌面端上报,无崩溃、无密钥泄露。因此「实时额度」这条路径在本机尚未用真实 token 验证过。
隐私与账号安全(重点)
这个控制台对 Claude / DSH / Codex 只做本地只读采集,不会修改任何第三方文件,也不会登录、刷新 token、发消息或调用任何模型接口。 具体来说:
- Claude 用量:只
read~/.claude/projects/**/*.jsonl(Claude 桌面端自己写的会话日志),只读,不写、不改、不移动。 - Claude 额度:只
read~/Library/Application Support/Claude/plan-usage-history.json(Claude 桌面端自己写入的额度采样)。 - 默认完全不访问 macOS 钥匙串(
config.probes.claudeKeychain=false)。即使开启,security find-generic-password -w也只是读取、不修改任何条目。 - 默认不会向 Anthropic 发任何网络请求:只有当用户显式提供
CLAUDE_CODE_OAUTH_TOKEN或~/.claude/.credentials.json时,才会做一次只读 GETapi.anthropic.com/api/oauth/usage(与 Claude Code 内/usage命令同源的额度查询,不涉及推理、不计入额度消耗、不改变账号状态)。 - DSH / Codex / OpenCodeX 同理:只读各自的会话/日志/额度缓存文件;OpenCodeX 的
usage.jsonl只读不截断。 - 唯一会写入的路径是本项目内
token-console/data/(SQLite + 日志)。 - 所有密钥只在内存中用于额度查询:不落盘、不写日志、不返回给前端;服务仅监听
127.0.0.1。
可以自行审计(在项目目录执行):
# 1) 采集器/探测器里不存在任何写文件调用
grep -rn "writeFile\|appendFile\|createWriteStream\|unlink\|rename" \
server/collectors server/probes server/credentials.mjs server/collect.mjs | grep -v node_modules
# 2) 对 Claude 目录只有 read
grep -rn "readFile\|openSync\|readdir" server/collectors/claude.mjs
# 3) 唯一的第三方网络请求(额度只读查询)都在 probes/ 里
grep -rn "https://" server/probes/
- 删除
data/目录即可清空全部本地记录,不影响任何第三方应用。
开机自动记录(可选)
默认不会自动安装。若希望登录后自动在后台记录:
# 1) 确认路径后复制模板
cp scripts/com.tokenobservatory.plist.example ~/Library/LaunchAgents/com.tokenobservatory.plist
# 2) 编辑其中的绝对路径(node 可执行文件 + 项目目录)
# 3) 加载
launchctl load ~/Library/LaunchAgents/com.tokenobservatory.plist
# 卸载
launchctl unload ~/Library/LaunchAgents/com.tokenobservatory.plist
常见问题
- 端口被占用:
node server/index.mjs --port 8788。 - 额度显示 unavailable/stale:对应凭据不可用或探测超时;额度面板会显示来源与最后更新时间,不影响用量记录。
- Claude 额度只有「桌面端上报」:说明本机没有可用的 Claude Code OAuth token,控制台会使用 Claude 桌面端写入
plan-usage-history.json的采样;打开 Claude 桌面端后会更新。想更实时见上文「Claude 实时额度(可选)」。 - 首次启动数据为空:首次全量扫描需要几秒,之后每 20 秒增量刷新;DSH 正在写入的会话会在下次采集时补齐。
- Node 版本:需要 >= 22.5(
node:sqlite/ zstd)。用node -v检查。
Comments
Loading…
Similar plugins
by zhubaodian1027
DSH Web GUI panel: AI quota (Kimi Coding, Codex Plus, DeepSeek…) + merged local token usage (DSH, Codex, Claude Code, Kimi Code, Hermes, Pi…).
★ 0
Apache-2.0
JavaScript
Aug 22, 2026
dsh plugin --profile web add @zhubaodian/dsh-token-panelby jcleener
DSH 插件:常驻 API 用量监控 —— DeepSeek/SiliconFlow/OpenCode Go/火山引擎 余额与配额、会话树 token 与花费(侧边栏入口 + 浮动窗)
★ 0
MIT
JavaScript
Oct 10, 2026
dsh plugin --profile web add api-monitorby yunshu-iii
DSH Harness 桌面端插件:窗口底部状态栏显示 DeepSeek API 余额与 token 用量 | Desktop plugin for DeepSeek Harness
★ 0
MIT
JavaScript
Oct 23, 2026
dsh plugin --profile web add dsh-api-usage-meterby HrxSpace
DSH 插件,扫描管理电脑本地所有终端的会话(Claude Code、Codex、Workbuddy、DSH等)
★ 0
MIT
TypeScript
Sep 8, 2026
dsh plugin --profile web add dsh-session-sweeperby tianxia--
Stop pasting API keys into DeepSeek Harness — reuse the OAuth tokens your local Codex CLI and Claude Code already hold as model routes, with subscription usage built in.
★ 2
↓ 65/wk
MIT
JavaScript
Nov 3, 2026
dsh plugin --profile web add dsh-llm-local-tokenby Aisland-SJL
🌊 Persistent dock & fully-customizable balance/usage panel for DeepSeek Harness — activity heatmap, dual-channel comparison, local-only & privacy-first
★ 153
↓ 133/wk
MIT
JavaScript
Oct 28, 2026
dsh plugin --profile web add dsh-usage