Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

publish

Publish the octop-browser Python package: cut a release branch from develop, bump version, update CHANGELOG / README, open a PR to main; after merge, Actions tag on main (PyPI + GitHub Release) and sync main into develop. Use when the user asks to publish, release, bump version, cut a release, or run /publish.

TencentCloud · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add TencentCloud/octop-browser --skill publish

About this skill


name: publish description: >- Publish the octop-browser Python package: cut a release branch from develop, bump version, update CHANGELOG / README, open a PR to main; after merge, Actions tag on main (PyPI + GitHub Release) and sync main into develop. Use when the user asks to publish, release, bump version, cut a release, or run /publish. disable-model-invocation: true

Publish

自动化 octop-browser(PyPI: octop-browser)的完整发布流程。

开始时宣告: "正在使用 publish 技能发布版本 {VERSION}。"

配置项

以下配置有默认值,可在项目的 .cursor/skills/publish/SKILL.md 或 .codebuddy/skills/publish/SKILL.md 中覆盖。

配置项默认值说明
CHANGELOG_FILECHANGELOG.md相对于仓库根目录的路径,文件不存在则跳过
VERSION_FILEpyproject.toml包含版本号的文件
VERSION_PATTERN^\s*version\s*=\s*"[^"]+"匹配版本行的正则表达式
README_FILEREADME.md发版时同步检查/更新的 README(见步骤 4b)
README_CN_FILEREADME_CN.md若存在则同样同步;缺失则跳过
INIT_VERSION_FILE(none — package metadata)含硬编码 __version__ 时同步;本包通常由 importlib.metadata 读取,缺失/元数据驱动则跳过
TAG_PREFIXvGit tag 前缀;工作流监听 v*
REMOTEoriginGit 远程仓库名(推送 release 分支与创建 PR)
INTEGRATION_BRANCHdevelop日常集成分支;release 必须从最新 tip 切出
TARGET_BRANCHmain合并请求的目标分支(生产真源)
RELEASE_BRANCH_PREFIXrelease/release 分支名前缀
PYPI_PACKAGEoctop-browserPyPI 包名(仅用于提示文案)

调用方式

/publish 0.1.14

目标版本号是唯一必填参数,其余均从配置或自动检测获取。

发布流程

顺序硬约束: 先 PR 合入 main,再在 main tip 打并推送 v* tag。
禁止在 release 分支未合入 main 前推送生产 tag。
禁止在本地直接 twine upload / make publish — 公开发布由 GitHub Action 负责。
禁止将 develop 直接 push / merge 进 main。

步骤 1 — 读取配置并确认版本

  1. 获取仓库根目录:git rev-parse --show-toplevel
  2. 记录当前分支为 {original_branch}。
  3. git fetch {REMOTE} {INTEGRATION_BRANCH} {TARGET_BRANCH}
  4. 从 VERSION_FILE 读取当前版本(在即将基于的 integration tip 上):
    git show {REMOTE}/{INTEGRATION_BRANCH}:pyproject.toml | grep -E '^\s*version\s*=\s*"[^"]+"'
    
  5. 检查未提交的更改:
    git status --short
    
    若工作树不干净:中止并要求用户先提交或 stash。发布不得夹带无关脏文件。
  6. 查找最近的 git tag:
    git tag --sort=-creatordate | head -1
    
    如果没有 tag,视为首次发布(在步骤 3 中使用从仓库初始到 HEAD 的所有提交)。
  7. 展示确认信息:
当前版本 (pyproject.toml @ develop): X.Y.Z
目标版本:                           A.B.C
上次发布 tag:                       vX.Y.Z (YYYY-MM-DD)
Release 分支:                       release/A.B.C
集成起点:                           develop
合入目标:                           main
Tag 时机:                           main 合并之后(不会在 release 上先打 tag)
PyPI 包:                            octop-browser

确认发布 X.Y.Z → A.B.C?[y/N]

如果用户未输入 y 确认,立即中止。

步骤 2 — 从 develop 创建 release 分支

git checkout -B {RELEASE_BRANCH_PREFIX}{version} {REMOTE}/{INTEGRATION_BRANCH}

如果本地或远程已存在同名 release 分支,中止:

✗ 分支 {RELEASE_BRANCH_PREFIX}{version} 已存在。
请手动删除后再运行 /publish。

步骤 3 — 分析变更并生成 CHANGELOG 草稿

  1. 获取上次 tag 以来的提交(相对当前 release HEAD,即 develop tip):

    git log {last_tag}..HEAD --oneline
    # 首次发布时:
    git log --oneline
    
  2. 如果没有找到提交:

    ⚠ 自上次发布 tag ({last_tag}) 以来没有新提交。
    是否继续?[y/N]
    

    用户未确认则中止。

  3. 按提交前缀分类,生成 Keep a Changelog 格式的条目。

    CHANGELOG 内容必须用中文书写。 将每个提交总结为简洁的中文要点 — 不要逐字翻译提交信息。适当合并相关提交。

    分类规则:

    • 以 feat: 或 feat( 开头 → 新增
    • 以 fix: 或 fix( 开头 → 修复
    • 以 refactor: 或 perf: 开头 → 变更
    • 包含 !: 或提交正文含 BREAKING CHANGE: → 变更,加 **Breaking:** 前缀
    • 以 docs: 开头 → 变更
    • 以 chore:、test:、ci: 开头 → 忽略(基础设施噪音)
    • 其他所有提交 → 变更
    • 移除的功能 → 移除
    • 安全修复 → 安全

    输出格式:

    ## [A.B.C] - YYYY-MM-DD
    
    ### 新增
    - 中文描述新增功能
    
    ### 修复
    - 中文描述修复内容
    
    ### 变更
    - 中文描述行为变更
    
    ### 移除
    - 中文描述移除内容
    
    ### 安全
    - 中文描述安全修复
    

    省略空的分类。日期使用 ISO 8601 格式(当天日期)。日期行与第一个分类之间、各分类之间保留空行。

  4. 向用户展示草稿并请求确认:

    CHANGELOG 草稿:
    
    {draft}
    
    添加到 CHANGELOG.md?[y/N/edit]
    
    • y → 继续
    • n → 中止
    • edit 或其他反馈 → 询问用户:"需要什么修改?" — 等待回复后重新生成,再次展示确认。循环直到 y 或 n。
  5. 如果 CHANGELOG_FILE 不存在,跳过此步骤(无需警告)。

步骤 4 — 更新文件、提交并推送 release 分支

按顺序执行:

4a. 更新 CHANGELOG:

在 CHANGELOG_FILE 中找到 ## [Unreleased] 标题,在其后插入新版本条目(保持 [Unreleased] 为空):

## [Unreleased]

## [A.B.C] - YYYY-MM-DD
### 新增
- ...

如果 ## [Unreleased] 标题不存在,在 # Changelog 标题行之后插入新条目(若无标题则插入到文件顶部)。

4b. 升级版本号并同步 README:

发布版本号必须保持多文件一致。依次处理:

  1. VERSION_FILE(pyproject.toml)— wheel / PyPI 的唯一版本源:
    grep -n '^\s*version\s*=\s*"[^"]+"' pyproject.toml
    # 用 Edit 工具将该行的 "X.Y.Z" 替换为 "A.B.C"
    
  2. README_FILE / README_CN_FILE(若存在):
    • 若存在静态 shields 徽标 version-X.Y.Z-orange(或同类),升级为 version-A.B.C-orange。
    • 若仅使用动态 shields.io/pypi/v/octop-browser 徽标,无需改徽标(PyPI 发布后自动更新),但仍须检查 README 中是否有硬编码安装示例版本(如 pip install octop-browser==X.Y.Z)并同步。
    • 用户可见的发版说明若写在 README,按需补一行指向 CHANGELOG.md 对应版本。
    • 文件不存在则跳过并提示(不中止)。
  3. INIT_VERSION_FILE — 仅当文件内存在硬编码 __version__ = "..." 时升级;若通过 importlib.metadata / _version.py 读包元数据则跳过。

4c. 提交:

git status --short
  • 如果有更改:暂存并提交:
    git add -A
    git commit -m "chore: release {version}"
    
  • 如果工作树已干净:无需提交,跳过。

4d. 推送 release 分支:

git push -u {REMOTE} {RELEASE_BRANCH_PREFIX}{version}

推送失败则中止。

步骤 5 — 创建合入 main 的 Pull Request(先合,后自动 tag)

使用 gh CLI(--repo 指向 GitHub 上的本仓):

gh pr create \
  --repo TencentCloud/octop-browser \
  --base {TARGET_BRANCH} \
  --head {RELEASE_BRANCH_PREFIX}{version} \
  --title "chore: release {version}" \
  --body "$(cat <<'EOF'
{步骤 3 生成的 CHANGELOG 条目}

## Release checklist
- [ ] CI green
- [ ] Merge this PR into main with a **merge commit** (not squash)
- [ ] After merge, GitHub Action auto-pushes v{version} tag on main tip
- [ ] Release workflow publishes octop-browser to PyPI and syncs main → develop
EOF
)"
  • 成功时展示 PR URL,并明确告知:
    • 合并前不要手动打 tag;
    • 合并请用 merge commit;
    • 合并后会自动发版(自动打 tag → PyPI → sync develop)。
  • 若 gh 失败:中止(此时尚未发版),提示手动创建 PR:
Read the complete source ↗