企业官网建设流程全解析

• 音视频
• AI 应用
• 后端
• 前端

本文以 AutoClip 仓库根目录下的 RELEASE_CHECKLIST.md 为核心骨架，结合scripts/发版工具、.github/workflows/desktop-build.yml构建流水线及CHANGELOG.md实际格式，完整还原这套「每周一版、25 分钟自动出包」的发版方法论。读完你可以直接照搬这套流程：掌握bump_version.py的四处版本号统一机制、release_notes.py的 Release 正文自动生成原理、tag 触发双平台打包的 CI 编排，以及哪些环节必须由人亲自验证。

一、发版哲学：每周一版，版本号只是周次编号

AutoClip 的发版节奏写在 RELEASE_CHECKLIST.md 开头，核心信条可以概括为三句话：

• 节奏固定：每周一版，版本号1.3.0 → 1.4.0 → …递增，周中热修用x.y.1（如1.2.1）。
• 目标不是"这版把什么做完"，而是「把 main 上已验证的改动每周发出去」。HANDOFF.md里的 v1.3 / v1.4 分组只是优先级队列，不是发版承诺。
• 一次完整发版约 25 分钟：从打 tag 到 Release 出包，全部由desktop-build.yml自动完成，人只需要按清单打勾。

这套理念直接反映在版本号语义上：主版本号1.3.0 → 1.4.0的递进不意味着功能大版本，而是第几周的周次编号。比如仓库当前 CHANGELOG 显示1.3.0 - 2026-09-20、1.2.1 - 2026-09-06，间隔恰好一周。

二、周中（周一至周五）：合 PR 的三条纪律

清单对「平时」只有三条要求，但每一条都有明确的可执行标准：

1. 只合并 CI 全绿 + 有验证记录的 PR

PR 描述里必须写清楚「怎么验的」。外部 PR 按 HANDOFF.md 第三节的原则处理——AutoClip 对外部 PR 采取「谨慎对待，能不合入就不合入；采纳的改动以 cherry-pick 进自己的 PR 并保留原作者署名」的策略。

2. 每个合入的 PR 都在 CHANGELOG 的[未发布]留一行

写给用户看，不写内部实现。这保证了 CHANGELOG.md 顶部的## [未发布]段落始终是下一版 Release 正文的原料。以当前仓库为例，[未发布]段落在没有改动时会被bump_version.py自动填入_（本周尚无改动）_占位符。

3. 每版至少带一条失败态改善或安装体验改善

这是 issue 区「最缺的两类」改进。从 CHANGELOG 的1.3.0段落可以看到具体落地形态：例如「失败要像失败」——LLM 未配置、字幕缺失、大纲提取失败、时间线为空、ffmpeg 零产出时，流水线一律进入failed状态并携带阶段（SUBTITLE / ANALYZE / EXPORT）与可执行的提示文案，杜绝「Completed · 0 切片」这类误导性状态。

另外，周报（scripts/weekly_digest.py）里新出现的高频问题，当周能修就进这版，修不了写进HANDOFF.md待办。这个脚本合并 GitHub 新 issue、飞书表单新条目与 PostHog 反馈事件，输出 markdown 周报，是「问题驱动发版」的数据来源。

三、切版（周六/周日，冻结后 24 小时内）：四道关卡

切版是流程的核心，冻结后 24 小时内按顺序完成以下动作：

关卡 1：确认 main CI 绿

gh run list --branch main --limit 1

仓库的 CI 由 .github/workflows/ci.yml 承担（backend / frontend / docker-smoke 三个维度），main 分支最新一次 run 必须全绿才允许进入下一步。

关卡 2：本地跑全量验证

清单明确要求跑三件套：

python -m pytest backend/tests cd frontend && npm run lint && npm run typecheck && npm run build python -m backend.eval

其中pytest backend/tests覆盖仓库 20+ 个测试文件（如test_pipeline_failures.py、test_cli.py、test_settings_web_mode.py等）；python -m backend.eval是出片质量回归入口，用 backend/eval/cases/ 下的合成用例约束 step1–step5 的提示词与评分行为不退化。

关卡 3：通读 CHANGELOG[未发布]段落

三个检查点：措辞面向用户、每条能对应到 issue 或 PR、没有泄露内部路径/密钥。这一步是防「发版翻车」的人肉闸门——Release 正文直接由这段生成，写不好就发布到所有用户面前。

关卡 4：统一版本号 + 滚动 CHANGELOG

python scripts/bump_version.py X.Y.0 --commit git push origin main && git tag vX.Y.0 && git push origin vX.Y.0

第一条命令完成「改四处版本号 + 把[未发布]滚成[X.Y.0] - 日期」，第二条命令推 tag 触发构建流水线。注意：tag 由人打，脚本不代打。

四、bump_version.py 深入：四处版本号如何保持同步

scripts/bump_version.py 是整个发版流程的"版本号唯一事实源"工具，它保证以下四处版本号永远一致：

脚本的三种用法：

python scripts/bump_version.py 1.3.0 # 改文件、滚 CHANGELOG，不提交 python scripts/bump_version.py 1.3.0 --commit # 顺带 git commit（不打 tag，tag 由人打） python scripts/bump_version.py --check # 只检查各处版本号是否一致（CI 可用）

从源码实现看，有四个值得注意的细节：

1. 正则在 Cargo.toml / pyproject.toml 中只替换指定 section 段内的version =（_sub_section函数用[^\[]*?限定范围），避免误伤依赖表里的版本号；找不到目标段会直接SystemExit报错。
2. --check模式打印四处版本号并对比，不一致时返回退出码 1，可直接接入 CI 作为版本一致性闸门。
3. CHANGELOG 滚动（roll_changelog）把## [未发布]原地替换为## [未发布]\n\n_（本周尚无改动）_\n\n## [X.Y.Z] - 日期，并同步更新文件底部的 compare 链接：Unreleased指向新 tag 的compare/v{new}...HEAD，同时补一条compare/v{prev}...v{new}的版本对比链接。若 CHANGELOG 已存在该版本段则跳过，不会重复滚动。
4. --commit模式只git add那五个文件（四个版本文件 + CHANGELOG）并提交chore: release vX.Y.Z，打印下一步提示git tag v{new} && git push origin main v{new}。

值得一提：该脚本明确只用标准库，没有任何第三方依赖，任何环境都能直接跑。

五、打 tag 触发 desktop-build.yml：25 分钟出包的流水线

推送v*tag 后，.github/workflows/desktop-build.yml 被触发，这是整个自动化的核心。其编排结构如下：

触发方式（两种）

• push tagsv*：正式发版，构建 + 挂 Release。
• workflow_dispatch：手动触发，可以只勾选 macOS 或只勾选 Windows 做试构建（清单里"少一个 = 对应平台构建失败"的排查手段）。

两个并行构建 job

• build-macos-arm64：macos-14runner（Apple Silicon），跑scripts/build_macos_arm.sh，产物为AutoClip.Desktop_{ver}_aarch64.dmg。
• build-windows-x64：windows-latestrunner，在Git Bash下跑scripts/build_windows_x64.sh（workflow 里显式设置git config --global core.autocrlf false强制 LF 行尾，防止 CRLF 导致 shell 脚本$'\r': command not found），产物为 NSIS 安装包AutoClip.Desktop_{ver}_x64-setup.exe。

两个 job 都走PBS（python-build-standalone）路线：便携 Python + 后端源码 + 静态 ffmpeg/ffprobe 打进安装包，用户无需预装 Python 和 ffmpeg。macOS 构建完把python/ backend/ ffmpeg/注入.app再做 ad-hoc 签名；Windows 因安装包无法事后注入，资源在src-tauri/tauri.windows.conf.json的bundle.resources中声明，由 Tauri 打进 NSIS——这是两个平台唯一的结构差异（详见 scripts/README.md）。

release job：汇总 + 生成正文

releasejob 的设计有两个亮点：

• 单 job 汇总而不是每个平台各自上传，避免两个 job 竞争创建同一 tag 的 Release；
• needs: [build-macos-arm64, build-windows-x64]但if: startsWith(github.ref, 'refs/tags/v') && !cancelled()——即使某个平台构建失败，也不阻塞另一个平台的产物上传，对应清单里"少一个 = 对应平台构建失败，看 run 日志"的排查逻辑。

release job 调用python3 scripts/release_notes.py "${{ github.ref_name }}" -o release_body.md生成正文，再用softprops/action-gh-release@v2创建/更新 Release 并挂载dist/*全部产物。workflow 顶部还声明了permissions: contents: write——没有这个权限声明，默认只读的 GITHUB_TOKEN 会导致上传 403。

六、release_notes.py：Release 正文从 CHANGELOG 自动生成

scripts/release_notes.py 承担"不手工写 Release 正文"的承诺。它的机制是：

1. 抽段落：正则^## \[{version}\][^\n]*\n(.*?)(?=^## \[|\Z)从 CHANGELOG.md 中抽出目标版本段落的正文（不含标题行），直到下一个## [为止。
2. 拼平台说明：把该段落与内置的PLATFORM_NOTES模板拼接，输出形如## AutoClip Desktop v1.3.0的完整正文。
3. 兜底：CHANGELOG 里找不到该版本段时，只输出平台说明 + 指向 CHANGELOG 的提示，不让发版失败。

本地预览用法：

python scripts/release_notes.py v1.3.0 # 打印到 stdout python scripts/release_notes.py v1.3.0 -o body.md # 写到文件

生成的平台说明表格非常实战：macOS 包注明「未公证：右键应用 → 打开」，Windows 包注明「未签名：SmartScreen → 更多信息 → 仍要运行」，并强调两个包都内置便携 Python 与静态 ffmpeg、Windows 安装包按用户安装不需要管理员权限、缺 WebView2 会自动下载——这些正是 RELEASE_CHECKLIST.md「发版后真机验证」环节要核对的用户体验点。

七、发版后（当天）：人做的部分，CI 覆盖不到

清单明确强调：真机验证必须人做。CI 只能保证"构建成功"，验证不了"装到用户电脑上能不能用"。

• Windows（优先级最高）：干净机器装-setup.exe→ 能启动 → 设置页保存 provider → 跑通一条本地视频。清单特别标注「Windows 下载量是 DMG 的 3 倍，这一步不能省」。这与 HANDOFF.md 中"截至 2026-09-20 下载量 Windows 1136 / DMG 334"的数据互相印证——Windows 已是 AutoClip 的主力平台，最可能翻车点包括 NSIS 打包的几千个 Python 文件、WebView2 引导、%APPDATA%\AutoClip数据目录。
• macOS：右键打开 DMG 里的应用 → 同样跑一遍完整流程（ad-hoc 签名，需右键 → 打开绕过 Gatekeeper）。

随后是三类收尾工作：

1. 更新置顶帖 #96的版本号与「v1.x 修了什么」小节（该帖是 issue 区"用不了"类问题的统一引导入口）；
2. 关闭已修复 issue：上一版 Release 的needs-info/ 已修复 issue，引导用户升级后关闭，模板回复见 HANDOFF.md 第三节；
3. 同步 HANDOFF.md：头部「更新：日期 · main@sha」与第四节勾选状态同步，保证它始终是项目状态的单一事实来源。

八、热修流程：周中发现影响面大的 bug

不等周末，按一条最短路径处理：

单独分支 → PR → CI 绿 → 合入 → bump_version.py X.Y.1 --commit → 打 tag

即版本号从X.Y.0升到X.Y.1（周中热修用x.y.1的语义在此兑现），不攒到周末。仓库历史上1.2.1就是典型热修版——HANDOFF.md 记录它是"止血版：让 README 推荐的 docker compose 路径和本地脚本路径真正能跑通一次完整处理"，一口气修掉了 7 条可复现问题（.dockerignore 误排除、CRLF 行尾、硬编码路径、队列未消费、Redis 诊断硬编码 localhost 等）。

九、明确不做：三条红线

清单用「明确不做」小节划出边界，防止流程被"顺手"破坏：

1. 不在切版日合新功能：周六冻结后只合修 CI / 修 CHANGELOG 措辞的改动；
2. 不手工编辑四处版本号（用脚本）、不手工写 Release 正文（从 CHANGELOG 生成）；
3. 不为了凑一版大的推迟发版：main 上有可发的就发——这是"每周一版"理念的最后一道保障。

十、相关文件速查

小结

AutoClip 的周更流程本质上是把"发版"从一件需要人工记忆大量步骤的事，压缩成一份 20 余项的勾选清单 + 两个标准库脚本 + 一条双平台 CI 流水线。它的可复制经验有三点：版本号只由脚本改（消灭手工漂移）、Release 正文只从 CHANGELOG 生成（消灭重复劳动）、真机验证只由人做（补上 CI 覆盖不到的最后一公里）。对任何需要维护桌面端周更节奏的项目，这套「周中合绿 PR + 周末统一版本打 tag + 自动出包挂 Release + 当天真机验证」的组合拳都值得直接照搬。

• 音视频
• AI 应用
• 后端
• 前端