claude-usage开发者指南3个Python文件、零依赖背后的完整架构与测试体系【免费下载链接】claude-usageA local dashboard for tracking your Claude Code token usage, costs, and session history. Pro and Max subscribers get a progress bar. This gives you the full picture.项目地址: https://gitcode.com/gh_mirrors/cl/claude-usageclaude-usage 是一个用于追踪 Claude Code token 用量、成本与会话历史的本地仪表盘只需 3 个 Python 文件、零第三方依赖即可运行。本文从架构设计、数据流、SQLite 存储到测试体系完整拆解这个极简项目的实现逻辑帮助你理解如何用纯标准库构建一个实用的用量监控工具。项目定位为什么零依赖是核心卖点Claude Code 会在本地写入详细的 JSONL 用量日志——token 数、模型、会话、项目无论你的订阅计划是什么。claude-usage 读取这些日志将其转化为图表和成本估算并支持 API、Pro 和 Max 三种计划。它的关键设计哲学是任何在跑 Claude Code 的人都已经装了 Python。因此项目只使用标准库sqlite3、http.server、json、pathlib无需pip install、无需虚拟环境、无构建步骤。这个承诺在 pyproject.toml 中被显式固化dependencies []并注释说明the tool stays stdlib-only at runtime该工具在运行时保持纯标准库。核心架构3 个 Python 文件的职责划分整个项目主体由 3 个扁平的顶层模块组成这也是pyproject.toml中py-modules [cli, scanner, dashboard]的由来文件职责scanner.py解析 JSONL 会话记录写入 SQLite 数据库cli.py提供scan/today/week/stats/dashboard终端命令dashboard.py单文件 HTTP 服务器 内嵌 HTML/JS 单页仪表盘数据流全景项目的数据流在 AGENTS.md 中有一条清晰的链路~/.claude/projects/**/*.jsonl → scanner.parse_jsonl_file() 聚合 → upsert_sessions() insert_turns() ↓ ~/.claude/usage.db (SQLite) ↓ cli.py 查询 ←──────────→ dashboard.py /api/datascanner.pyparse_jsonl_file 解析每条assistant类型记录中的 token 字段input、output、cache_read、cache_creation与模型名scan 函数负责增量扫描cli.py终端报表calc_cost按 turn 逐条计费后求和dashboard.pyDashboardHandler 基于http.server.BaseHTTPRequestHandler提供两个端点——GET /api/data返回 JSON 快照和POST /api/rescan删除数据库并全量重扫整个 UI 以HTML_TEMPLATE原始字符串形式内嵌Chart.js 从 CDN 加载每 30 秒自动刷新存储设计3 张表撑起增量扫描SQLite 数据库位于~/.claude/usage.db由 scanner.py 的init_db创建并自动迁移turns表——每个 assistant API 响应一行是 token 数与模型归属的事实来源sessions表——按会话聚合的冗余汇总总额 主模型processed_files表——增量扫描跟踪记录(path, mtime, lines)mtime 不变则跳过文件增长时只处理新增行这使得重复运行python cli.py scan非常快。此外turns.message_id上的条件唯一索引让INSERT OR IGNORE能低成本地跨重扫去重。三个必须知道的非显而易见不变量AGENTS.md 特别列出了三个容易踩坑的设计点流式去重Claude Code 每个 API 响应会写多条 JSONL 记录只有同一message.id的最后一条才有最终用量统计。解析器只保留每个 message_id 的最后一条记录切勿跨记录累加会话总额重算增量扫描中 token 是累加的扫描结束时会用turns表重算sessions总额防止重复 turn 导致数据漂移会话主模型优先级opus sonnet haiku见 _model_priority避免子代理的 haiku turn 覆盖会话的 opus 模型成本计算按 turn 计费而非按总量一个常见错误是先聚合 token 再用单一价格计费——这对跨多模型的会话是错误的。claude-usage 的做法是每个 turn 都知道自己的模型逐条计费后求和。价格表在 cli.py 的PRICING字典Python和 dashboard.pyHTML_TEMPLATE内的PRICING常量JavaScript中各存一份测试test_prices_match强制两者保持一致。测试体系纯 unittest 覆盖全部关键路径项目测试只依赖标准库unittest完整测试套件运行方式简单python -m unittest discover -s tests -vCI 在 Python 3.9 / 3.11 / 3.12 三个版本上运行。测试目录 tests/ 的分工测试文件覆盖内容test_scanner.py解析、去重、增量扫描、schema 迁移、标题回填test_dashboard.pyAPI 数据结构、HTML 模板完整性、前后端价格表同步test_cli.py定价解析的三级匹配精确 → 前缀 → 子串、成本计算、数字格式化test_subagent.py子代理识别sidechain 标记、agent_id、路径判断与 dispatch 提取test_cli_subagent.py终端命令在旧 schema 下不崩溃test_dashboard_subagent.py子代理 token 数据接口test_version.py三处版本号强同步校验其中 test_version.py 值得单独一提它校验scanner.py中的VERSION当前为1.5.5、CHANGELOG 标题、以及 VS Code 扩展 package.json 三处版本一致——这正是发布流程三处版本 lockstep的守护。测试约定同样记录在 AGENTS.mdscanner 和 dashboard 测试使用tempfile.NamedTemporaryFile建立隔离数据库绝不触碰用户真实的~/.claude/usage.db/api/rescan测试通过 monkey-patchdashboard.DB_PATH和scanner.DEFAULT_PROJECTS_DIRS工作这个契约必须保持Windows 上全新检出可能没有~/.claude/目录get_db的mkdir(parentsTrue, exist_okTrue)不可移除否则sqlite3.connect会在 CI 中失败周边生态Docker 与 VS Code 扩展Dockerscripts/run-docker.sh 构建镜像并以只读方式挂载~/.claude容器可读不可改用命名卷持久化 SQLite 数据库仪表盘运行在 http://localhost:9898镜像定义见 DockerfileVS Code 扩展vscode-extension/ 将同一 UI 以活动栏侧边栏形式嵌入编辑器Python 源码直接打包进.vsix最终用户只需 PATH 上有 Python 3.8。其中 port-allocator.ts 通过workspaceState记住并复用上次端口保证 iframe 内的localStorage状态在窗口重载后不丢失快速上手克隆并跑起来git clone https://gitcode.com/gh_mirrors/cl/claude-usage cd claude-usage python3 cli.py dashboard浏览器将自动打开 http://localhost:8080看到会话数、输入/输出 token、缓存读写、估算成本等统计卡片以及按模型过滤、按日期范围缩放的交互图表。总结值得借鉴的极简工程范式claude-usage 展示了几个对独立开发者很有参考价值的做法约束驱动设计把零依赖写成pyproject.toml里的硬约束空依赖 注释说明让每个贡献者都无法绕开文档即契约AGENTS.md 不只写怎么做更写哪些不变量不能破坏把踩坑经验固化为团队与 AI 编码代理共享的知识单一事实来源 校验测试版本号、价格表这类容易漂移的数据都配有强制同步的测试守护扁平优于分层3 个顶层模块、无包目录与仓库结构一一对应阅读路径极短一个工具3 个 Python 文件17 个测试类——这正是小项目也要有完整工程体系的最好示范。【免费下载链接】claude-usageA local dashboard for tracking your Claude Code token usage, costs, and session history. Pro and Max subscribers get a progress bar. This gives you the full picture.项目地址: https://gitcode.com/gh_mirrors/cl/claude-usage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考