Claude Code Usage Monitor 发布流程指南：从版本号到 PyPI 的全自动化发布实战-平芜编程栈

AI 应用
CLI

【免费下载链接】Claude-Code-Usage-Monitor

Real-time Claude Code usage monitor with predictions and warnings

项目地址：https://gitcode.com/gh_mirrors/cl/Claude-Code-Usage-Monitor

本指南以仓库根目录的 RELEASE.md 为骨架，完整讲解 Claude Code Usage Monitor（PyPI 包名claude-monitor）的发布流程：包括基于 GitHub Actions 的自动化发布、前置条件配置、9 步手动发布流程、语义化版本管理、常见故障排查与最终检查清单。读完本文，你将掌握从修改pyproject.toml版本号、更新CHANGELOG.md、创建 git tag、构建 wheel/sdist 到发布 GitHub Release 并上传 PyPI 的完整闭环，同时理解仓库底层是如何保证版本单一来源、测试通过和产物可验证的。

一、发布流程总览

Claude Code Usage Monitor 支持两条发布路径：

自动化发布（推荐）：把变更推送到main分支后，由 release.yml 工作流自动完成打 tag、生成 Release Notes、构建包并发布到 PyPI。
手动发布（兜底）：当自动化流程失败或需要特殊处理时，按 9 个步骤手动完成全流程。

两条路径共用同一套「版本单一来源」机制：版本号只维护在pyproject.toml一处，发布流程中的一切判断（是否已打 tag、构建产物名、PyPI 包版本）都从它派生，避免多处置版本导致发布错版。

二、自动化发布：GitHub Actions 工作流

2.1 触发与执行流程

根据 RELEASE.md，自动化发布在向main分支推送变更时触发（工作流同时保留了workflow_dispatch手动触发入口）。整个工作流依次完成：

提取版本号：从pyproject.toml读取version字段；
检查 tag 是否已存在：查询v<version>形式的 git tag；
若不存在，则依次：
- 创建新的 git tag；
- 从CHANGELOG.md中提取对应版本的 Release Notes；
- 创建 GitHub Release；
- 构建包并发布到 PyPI。

2.2 工作流源码级拆解

仓库中实际的 .github/workflows/release.yml 实现了上述逻辑，关键设计如下：

check-version任务（版本门禁）：用grep '^version = ' pyproject.toml提取版本，并通过git rev-parse "v$VERSION"判断 tag 是否已存在。若 tag 已存在，则输出should_release=false，后续release任务不会执行——这保证了同一个版本号永远不会重复发布。
release任务（发布执行）：声明permissions: contents: write（创建 tag 与 Release 的权限）和id-token: write（用于 PyPI 可信发布）；通过astral-sh/setup-uv@v4安装 uv、用uv build构建；Release Notes 由sed从 CHANGELOG.md 中按版本段截取，若未找到则回退为占位文案；PyPI 上传使用pypa/gh-action-pypi-publish@release/v1，并设置了skip-existing: true避免重复版本导致失败。
notify-success任务：仅在成功发布后输出 GitHub Release 与 PyPI 页面链接，便于在 Actions 日志中确认产物位置。

2.3 自动化发布的前置条件

自动化发布能否成功，取决于两个前置条件（见 RELEASE.md）：

PyPI API Token：必须配置为名为PYPI_API_TOKEN的 GitHub secret。Token 在 PyPI 的账户管理（API tokens）页面生成，然后在仓库的 Settings → Secrets and variables → Actions → New repository secret 中新增。注意：工作流实际使用 trusted publishing（OIDC）时会走id-token权限，此时 API Token 作为兜底/备用凭据仍然建议配置完整。
发布权限：GitHub Actions 需要具备创建 Release 的权限，在 Settings → Actions → General → Workflow permissions 中开启Read and write permissions。

三、版本号管理：语义化版本与单一来源

3.1 语义化版本规则

仓库遵循语义化版本（SemVer），格式为MAJOR.MINOR.PATCH（如1.0.9、当前pyproject.toml为4.0.0）：

MAJOR：不兼容的 API 变更（如 CHANGELOG.md 中记录的 3.0.0 包名从claude-usage-monitor改为claude-monitor、4.0.0 快照协议正式化等重大变化）；
MINOR：向后兼容的新功能；
PATCH：向后兼容的缺陷修复。

3.2 版本单一来源机制

VERSION_MANAGEMENT.md 明确了设计原则：pyproject.toml是版本号的唯一定义处，源码中不再硬编码。其实现位于 src/claude_monitor/_version.py，采用两级回退：

已安装环境：通过importlib.metadata.version("claude-monitor")读取包元数据；
开发环境（未安装）：向上最多查找 5 层目录定位pyproject.toml，用 Python 3.11+ 内置的tomllib（或 3.9/3.10 下的tomli依赖）读取project.version；均失败时返回"unknown"。

src/claude_monitor/__init__.py通过from claude_monitor._version import __version__暴露版本，cli/main.py 中--version/-v参数即输出该值（格式为claude-monitor <version>）。因此发布时只需改动pyproject.toml一处，安装后的 CLI 版本、PyPI 版本、git tag 全部自动同步。

该机制有对应测试保障：src/tests/test_version.py 覆盖了元数据读取、pyproject 回退、unknown兜底、跨导入一致性以及（集成标记的）与 pyproject.toml 一致性校验。

3.3 版本自动递增辅助工作流

仓库还提供了 .github/workflows/version-bump.yml 作为手动触发的版本号递增辅助工具：在 Actions 页面手动运行，选择patch/minor/major并填写 changelog 摘要，工作流会自动解析当前版本、按规则递增、同步更新pyproject.toml与 CHANGELOG.md，最后创建一个名为version-bump-<新版本>的 PR。合并该 PR 推送到main后，即可触发 2.1 节的自动化发布。

四、手动发布流程（9 步全解析）

自动化失败或需要特殊处理时，按 RELEASE.md 的以下步骤手动发布：

步骤 1：准备发布

# 确保位于 main 分支且代码最新 git checkout main git pull origin main # 运行测试与代码规范检查 uv sync --extra dev uv run ruff check . uv run ruff format --check .

uv sync --extra dev安装 pyproject.toml 中[project.optional-dependencies].dev声明的开发依赖（black、isort、mypy、pre-commit、pytest 全家桶、ruff、build、twine 等）。
测试套件按 pyproject.toml 中[tool.pytest.ini_options]的约定运行：testpaths = ["src/tests"]，默认-m "not integration"，并启用覆盖率门槛（--cov-fail-under=70）。

步骤 2：更新版本号

编辑pyproject.toml中的版本：

version = "1.0.9" # 改为你的新版本

由于单一来源机制，此处修改会同步影响claude-monitor --version输出与安装元数据。

步骤 3：更新 CHANGELOG.md

在 CHANGELOG.md 顶部新增版本段，格式如下（链接行按仓库实际情况替换为对应 tag）：

## [1.0.9] - 2025-06-21 ### Added - Description of new features ### Changed - Description of changes ### Fixed - Description of fixes [1.0.9]: <仓库 releases/tag/v1.0.9 的链接>

注意 release.yml 会用 sed 按## [<版本>]段截取 Release Notes，因此版本段标题必须与pyproject.toml中的版本号完全一致，否则自动提取会回退为占位文案。

步骤 4：提交版本变更

git add pyproject.toml CHANGELOG.md git commit -m "Bump version to 1.0.9" git push origin main

步骤 5：创建 git tag

# 创建附注（annotated）tag git tag -a v1.0.9 -m "Release v1.0.9" # 推送 tag 到远程 git push origin v1.0.9

推荐使用-a创建附注 tag，它携带作者、时间与提交信息，便于追溯。

步骤 6：构建包

# 清理上一次构建产物 rm -rf dist/ # 使用 uv 构建 uv build # 校验构建产物 ls -la dist/

预期产物为：

claude_monitor-1.0.9-py3-none-any.whl（wheel，纯 Python 通用平台包，py3-none-any表明不依赖特定 Python 版本补丁号与操作系统）；
claude_monitor-1.0.9.tar.gz（sdist 源码包）。

构建配置由 pyproject.toml 的[build-system]（setuptools + wheel）与[tool.setuptools.packages.find]（where = ["src"]，仅打包claude_monitor*）决定。构建前建议确认uv sync --extra dev已安装build依赖（dev extras 中包含build>=0.10.0）。

步骤 7：创建 GitHub Release

在仓库的 Releases → New release 页面：

选择 tag：v1.0.9；
Release 标题：Release v1.0.9；
从CHANGELOG.md复制对应版本段作为描述；
（可选）附加dist/中的构建产物；
点击 Publish release。

步骤 8：发布到 PyPI

# 如未安装 twine uv tool install twine # 上传到 PyPI（会提示输入凭据） uv tool run twine upload dist/* # 或使用 API Token uv tool run twine upload dist/* --username __token__ --password <your-pypi-token>

uv tool install twine将 twine 装入隔离的工具环境，不污染项目环境；
使用 API Token 时用户名固定为__token__，密码为在 PyPI 生成的 token；
仓库devextras 中也包含twine>=4.0.0，亦可直接使用项目环境中的 twine。

步骤 9：验证发布结果

在 PyPI 上确认claude-monitor已出现新版本；
在全新环境测试安装：

# 在全新环境中 uv tool install claude-monitor claude-monitor --version # 测试所有命令别名 cmonitor --version ccm --version

命令别名的来源见 pyproject.toml 的[project.scripts]：claude-monitor、claude-code-monitor、cmonitor、ccmonitor、ccm五个入口全部指向claude_monitor.__main__:main。发布后逐一验证--version输出与pyproject.toml版本一致，可确认安装链路完整。

五、故障排查（Troubleshooting）

5.1 GitHub Actions 发布失败

打开 Actions 选项卡查看错误日志；
常见原因：
- PYPI_API_TOKEN缺失或无效（检查仓库 Secrets 与 Token 权限范围）；
- 版本已存在于 PyPI（skip-existing会跳过重复，但首次发布时版本冲突会失败）；
- CHANGELOG.md格式异常（版本段标题与pyproject.toml不一致，导致 Release Notes 提取异常）。

5.2 PyPI 上传失败

认证错误：检查 PyPI Token 是否有效、是否仍有上传权限；
版本已存在：PyPI 不允许重复使用版本号，需递增版本后再发布；
包名被占用：claude-monitor可能被保留或已存在同名包，需确认包名归属。

5.3 tag 已存在

当v1.0.9已被占用（可能来自失败的重试）时：

# 删除本地 tag git tag -d v1.0.9 # 删除远程 tag git push --delete origin v1.0.9 # 重新创建并推送 git tag -a v1.0.9 -m "Release v1.0.9" git push origin v1.0.9

删除远程 tag 属于破坏性操作，仅应在确认该 tag 从未对应正式 Release、且无下游引用时执行。

六、发布检查清单

RELEASE.md 末尾给出了完整发布清单，建议发布前逐项确认：

所有测试通过（uv run pytest，默认排除 integration 标记）
代码格式正确（ruff 检查与格式化校验通过）
pyproject.toml中版本号已更新
CHANGELOG.md已更新 Release Notes
变更已提交并推送到main
git tag 已创建并推送
GitHub Release 已创建
包已发布到 PyPI
已在全新环境验证安装与--version

七、自动化与手动流程的协同建议

综合仓库现状（RELEASE.md、release.yml、version-bump.yml、VERSION_MANAGEMENT.md），推荐的标准发布路径为：

本地完成uv sync --extra dev、ruff check、ruff format --check、测试通过；
更新pyproject.toml版本号与CHANGELOG.md，提交推送到main；
由 release 工作流自动完成打 tag、生成 Release、uv build与 PyPI 上传；
在全新环境执行uv tool install claude-monitor并验证claude-monitor --version、cmonitor --version、ccm --version。