终极发布管理实践claude-usage的CHANGELOG驱动自动打Tag与Homebrew自引用SHA之谜【免费下载链接】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 用量、成本与会话历史的本地仪表盘。本文拆解它的发布管理实践CHANGELOG 驱动的自动打 Tag 机制以及 Homebrew 公式里自引用 SHA之谜的破解方法。一眼看懂 claude-usage免费的本地用量仪表盘Claude Code 会把每次会话的用量日志token 数、模型、项目写到本地但 Anthropic 的界面并不展示完整细节。claude-usage 读取这些日志把数据变成图表和成本估算——支持 API、Pro、Max 三种订阅Pro/Max 用户还能看到进度条。它非常轻纯 Python 标准库实现无需pip install。核心就三个文件scanner.py解析 JSONL 日志写入 SQLite 数据库cli.py终端命令scan/today/stats/dashboarddashboard.py本地网页仪表盘默认localhost:8080CHANGELOG 驱动自动打 Tag三步发布流程这个项目最精妙的设计CHANGELOG 是唯一的版本事实来源Tag 只是它的投影。维护者几乎不需要手动打 Tag发布流程只有三步积累开发分支DEV上CHANGELOG 顶部的## vX.Y.Z — TBD标题不断收集更新条目定稿准备发布时把TBD改成日期、同步三处版本号见下文并运行公式更新脚本然后DEV → main合并自动发布.github/workflows/tag-on-merge.yml 监听到 push发现 diff 中新增了新的## vX.Y.Z标题就自动创建轻量级 Tag、构建 VS Code 扩展.vsix并把它作为附件发布到对应的 Release——Release 说明直接取自 CHANGELOG 对应章节。整个流程是幂等的Tag 已存在就跳过Release 已存在也跳过没有新增版本标题的 push比如纯文档修改则完全不做任何事。一句话总结你只写 CHANGELOGTag 和 Release 自动跟上。格式即契约工作流依赖的 CHANGELOG 规则自动化建立在严格的格式约定之上规则细节见 AGENTS.md字段要求格式为什么标题## vX.Y.Z严格 SemVer三段数字工作流正则只认这种格式v1.1、V1.1.0会被静默忽略分隔符—em-dash 前后留空格保持一致工作流忽略版本后的内容日期积累期为TBD合并到 main 时替换为日期这是唯一需要人工记住的步骤子章节### Dashboard/### Scanner/### Packaging等让 CHANGELOG 保持可扫读条目过去时态 #N关联 thanks 作者方便读者溯源贡献来源一个真实案例v1.5.2 就只做了一件事——把 Homebrew 公式的 pin 从 v1.1.0 追赶到 v1.5.1见 CHANGELOG.md然后顺手把更新流程脚本化了从此不再靠人工记忆。三处版本同步一致性测试锁死版本号版本号出现在三个地方scanner.VERSION运行时版本、CHANGELOG 顶部标题、VS Code 扩展的package.json。扩展把三个 Python 文件打包进.vsix而 CHANGELOG 不打包所以运行时版本必须来自代码。tests/test_version.py 里的并行测试parity test会在 CI 中断言三处完全一致——漏改任何一处测试套件直接失败。此外 pyproject.toml 通过dynamic [version]从scanner.VERSION动态读取版本连打包元数据都不硬编码。Homebrew 公式的自引用 SHA之谜macOS/Linux 用户可以直接brew install安装公式就在仓库内Formula/claude-usage.rb。这里藏着一个优雅的难题公式文件要写下载包的 sha256但公式本身又包含在这个下载包里——一个包含自身哈希的文件的哈希是算不出来的。破解方法只有一条写在公式的注释里Formula/claude-usage.rb#L4-L8发布版本的公式必须指向上一个已冻结 release 的 tag 压缩包永远不指自己。代价是 Homebrew 通道天然落后一个版本——但这是自动的每次发布公式随新 merge 前进一步永不错位。具体怎么做到不手改scripts/bump-formula.sh 脚本一键完成拉取上一个 release 的 tag 压缩包 → 计算 sha256 → 精确改写公式中url/version/sha256三行其余行原样保留。脚本在DEV分支上运行改动通过DEV → main的正常合并抵达main——而 Homebrew 只读取 tap 默认分支main的最新内容所以这条时间线恰好让新发布携带指向上一版的 pin自然成立。全程不直接碰main也绕开了分支保护。历史上人工手改 pin 曾让它悄悄腐烂在 v1.1.0 好几个月v1.5.2 才追赶回来并固化了这个流程——这正是能用脚本的绝不动手的典型案例。关键文件速查文件作用CHANGELOG.md版本事实来源Tag 的唯一输入.github/workflows/tag-on-merge.yml自动打 Tag 发布 Release 的工作流scripts/bump-formula.sh自动更新 Homebrew 公式的 pin 与 sha256Formula/claude-usage.rbHomebrew 公式含自引用 SHA 的注释说明tests/test_version.py三处版本号一致性测试AGENTS.md完整的版本化与发布规范文档总结三个可迁移的发布管理要点单一事实来源让 CHANGELOG 成为唯一权威Tag、Release、版本号都是它的确定性投影杜绝改了 A 忘了 B格式即契约自动化工作流对格式零容忍正则匹配标题、并行测试锁版本格式约定写进文档并让测试守护用后退一步破解自引用sha256 不能指自己就指上一个已冻结的版本——落后一版不是缺陷而是被脚本化保证自动前进的机制。【免费下载链接】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），仅供参考