AI 应用CLI【免费下载链接】Claude-Code-Usage-MonitorReal-time Claude Code usage monitor with predictions and warnings项目地址https://gitcode.com/gh_mirrors/cl/Claude-Code-Usage-Monitor点击查看免费下载本指南以仓库根目录的 RELEASE.md 为骨架完整讲解 Claude Code Usage MonitorPyPI 包名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 是否已存在查询vversion形式的 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_releasefalse后续release任务不会执行——这保证了同一个版本号永远不会重复发布。release任务发布执行声明permissions: contents: write创建 tag 与 Release 的权限和id-token: write用于 PyPI 可信发布通过astral-sh/setup-uvv4安装 uv、用uv build构建Release Notes 由sed从 CHANGELOG.md 中按版本段截取若未找到则回退为占位文案PyPI 上传使用pypa/gh-action-pypi-publishrelease/v1并设置了skip-existing: true避免重复版本导致失败。notify-success任务仅在成功发布后输出 GitHub Release 与 PyPI 页面链接便于在 Actions 日志中确认产物位置。2.3 自动化发布的前置条件自动化发布能否成功取决于两个前置条件见 RELEASE.mdPyPI API Token必须配置为名为PYPI_API_TOKEN的 GitHub secret。Token 在 PyPI 的账户管理API tokens页面生成然后在仓库的 Settings → Secrets and variables → Actions → New repository secret 中新增。注意工作流实际使用 trusted publishingOIDC时会走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.0MAJOR不兼容的 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-under70。步骤 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# 创建附注annotatedtag 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.whlwheel纯 Python 通用平台包py3-none-any表明不依赖特定 Python 版本补丁号与操作系统claude_monitor-1.0.9.tar.gzsdist 源码包。构建配置由 pyproject.toml 的[build-system]setuptools wheel与[tool.setuptools.packages.find]where [src]仅打包claude_monitor*决定。构建前建议确认uv sync --extra dev已安装build依赖dev extras 中包含build0.10.0。步骤 7创建 GitHub Release在仓库的 Releases → New release 页面选择 tagv1.0.9Release 标题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-tokenuv tool install twine将 twine 装入隔离的工具环境不污染项目环境使用 API Token 时用户名固定为__token__密码为在 PyPI 生成的 token仓库devextras 中也包含twine4.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版本一致可确认安装链路完整。五、故障排查Troubleshooting5.1 GitHub Actions 发布失败打开 Actions 选项卡查看错误日志常见原因PYPI_API_TOKEN缺失或无效检查仓库 Secrets 与 Token 权限范围版本已存在于 PyPIskip-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变更已提交并推送到maingit 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。手动流程保留为自动化失败的兜底方案其中步骤 3/5/7/8CHANGELOG 与版本号一致、tag 命名vversion、twine 上传是自动化流程复用同一约定的关键保持两者行为一致可显著降低发布事故率。赞分享AI 应用CLI【免费下载链接】Claude-Code-Usage-MonitorReal-time Claude Code usage monitor with predictions and warnings项目地址https://gitcode.com/gh_mirrors/cl/Claude-Code-Usage-Monitor点击查看免费下载相关推荐PyMC 发布流程指南从版本号提升到 PyPI 自动发布与发布后收尾PyMC 发布流程指南从版本号提升到 PyPI 自动发布与发布后收尾 本篇指南以 PyMC 官方文档 release_checklist.md https:/人工智能机器学习科学计算NetBox 版本发布全流程指南从 Release Checklist 到 PyPI 发布实战NetBox 版本发布全流程指南从 Release Checklist 到 PyPI 发布实战 本篇技术指南围绕 NetBox 官方开发文档中的发布清单Re后端网络数据建模Visdom 发布流程指南版本号管理、CI 校验与 PyPI 自动化发布Visdom 发布流程指南版本号管理、CI 校验与 PyPI 自动化发布 本篇技术指南面向 Visdom 的维护者、贡献者与自动化 Agent系统讲解该仓库数据可视化前端上一篇VVDEC 开源项目教程下一篇Uncle小说PC版终极指南三步搞定全网小说下载与阅读创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考