企业官网建设流程全解析

• 人工智能
• 大模型
• AI 应用
• 后端
• AI Agent
• RAG
• 流程编排
• 微服务

导读：本文以 FIT 框架（ModelEngine/fit-framework）仓库内create-release-note.md命令文件为蓝本，系统讲解如何用一条/prompts:create-release-note <version>命令，从 PR、commit 与 Issue 中自动收集变更信息，按模块与类型分类并生成符合项目格式的 Release Notes，甚至可选地直接创建 GitHub Draft Release。读完本文，你将掌握该命令的参数规则、15 步完整执行流程、模块/类型分类策略、x.y.0 版本合并路径，以及配套的release、commit、create-pr命令如何协同完成一次标准的版本发布闭环。

一、命令背景：为什么需要自动化生成 Release Notes

FIT 框架是一个多模块、多语言的大型企业级 AI 开发框架，仓库横跨 Java、Python 等多个生态（可参考 项目 README）。它的版本管理遵循多版本Git-Flow模式（详见 CONTRIBUTING.md）：

• 纯数字版本分支以v开头，例如v3.6.0；
• 发布分支形如fit-java-1.0.0、waterflow-python-2.1.1；
• 版本分支则形如fit-java-1.0.x、waterflow-python-2.1.x，代表该主版本下所有修订版本的汇聚点。

在这样的多平台（FIT Function Platform、FIT Expression for LLM、Waterflow Flow Scheduling Platform 等）同步迭代的工程里，每次发版都要面对大量 PR 与 commit。若靠人工整理，极易出现漏记、误分类、贡献者遗漏等问题。因此仓库在.codex目录下维护了一套 Codex 项目级 prompts，其中create-release-note.md就是专门负责"自动生成 Release Notes + 可选创建 GitHub Draft Release"的命令。

该命令的核心价值可以概括为三点：

1. 自动收集：基于版本 tag 之间的日期范围，用ghCLI 自动拉取合并的 PR，并补充没有关联 PR 的直接 commit；
2. 智能分类：按「模块优先级 → 平台映射」和「conventional commit type → 类型映射」两套规则自动归类；
3. 版本分流：对x.y.0这类大版本自动走合并路径（聚合前一 minor 系列的已发布 release notes），对修订版本走常规路径（按日期范围收集 PR）。

适用前提：该命令依赖 GitHub CLI（gh）且要求相关 tag 已存在；它属于仓库 AI 工程化实践的一部分，需要先按.codex/README.md安装 prompts 后方可使用（详见后文"使用前置条件"）。

二、命令安装与基础用法

2.1 安装 Codex Prompts

Codex CLI 的自定义 prompts 默认只从用户目录（~/.codex/prompts/）读取，因此仓库内的 prompts 需要先安装到本地才能生效。安装脚本位于.codex/scripts/install-prompts.sh：

bash .codex/scripts/install-prompts.sh

脚本会完成如下动作：

• 将.codex/commands/下的全部.mdprompt 文件复制到~/.codex/prompts/；
• 预先统计会被覆盖的文件数量并提示；
• 安装完成后，解析每个文件的description字段，打印已安装命令清单。

安装完成后，即可在 Codex CLI 中用/prompts:<name>调用，例如/prompts:create-release-note 3.6.3。注意：文件名即为 prompt 名称，调用时不含.md扩展名。

2.2 Prompt 文件格式

create-release-note.md采用仓库统一的"混合格式"（YAML frontmatter + Markdown 正文）：

--- description: 从 PR/commit 中自动生成结构化的 Release Notes，并可选创建 GitHub Draft Release usage: /prompts:create-release-note <version> [prev-version] argument-hint: <version> [prev-version] ---

字段含义（与.codex/README.md的规范一致）：

2.3 参数规则与版本格式验证

命令支持两种调用形式：

# 单参数：自动推断上一版本 /prompts:create-release-note 3.6.3 # 双参数：手动指定版本范围 /prompts:create-release-note 3.6.3 3.6.2 # x.y.0 大版本：合并 3.6.x 系列的所有 release notes /prompts:create-release-note 3.7.0

版本号格式验证：如果传入的版本号不满足X.Y.Z格式，命令会报错退出，错误信息为：

错误：版本号格式不正确，期望格式为 X.Y.Z（例如 3.6.3）

三、执行流程总览：双路径分流的 15 步流水线

命令的执行步骤并非线性直落，而是按版本的 PATCH 段分流，结构如下：

步骤 1-3（公共：解析参数 → 确定版本范围 → 判断版本类型） │ ├── PATCH == 0（如 3.7.0）→ 合并路径：步骤 4-7 → 跳到步骤 14 │ └── PATCH > 0（如 3.6.3）→ 常规路径：步骤 8-13 → 继续步骤 14 步骤 14-15（公共：展示确认 → 创建 Draft Release）

两条路径的分流依据：

• PATCH == 0（x.y.0，如3.7.0）：视为 Major release，走合并路径，聚合前一 minor 系列（如3.6.x）的全部已发布 release notes；
• PATCH > 0（如3.6.3）：走常规路径，基于 tag 之间的日期范围收集 PR 和 commit 生成。

两种路径的差异点，在于数据来源：合并路径复用 GitHub 上已发布的 release body，常规路径则直接从 PR / commit 中现场收集。二者殊途同归，最终都汇入公共的"展示确认 → 创建 Draft Release"环节。

四、公共前置步骤：参数解析与版本范围确定

4.1 步骤 1：解析参数

从$ARGUMENTS（Codex CLI 注入的全部参数拼接字符串）中提取<version>与可选的<prev-version>。关于占位符机制，.codex/README.md有明确说明：结构化参数（如版本号）使用空格分隔的位置参数，命令正文中直接用$1、$ARGUMENTS等占位符引用，Codex CLI 展开 prompt 时会将占位符替换为实际参数值。

4.2 步骤 2：确定版本范围

当前版本 tag固定为v<version>（如v3.6.3）。

当未显式指定<prev-version>时，通过 tag 排序推断上一版本：

# 获取所有已排序的 tag git tag --sort=-v:refname

推断规则有两种：

• PATCH > 0（如3.6.3）：查找同一 minor 系列中的前一个 tag（如v3.6.2）；
• PATCH == 0（如3.6.0）：查找前一个 minor 系列的最后一个 tag（如v3.5.x中最大的那个）。

Tag 存在性验证：

git rev-parse v<version> git rev-parse v<prev-version>

如果任一 tag 不存在，命令报错退出：

错误：Tag v<version> 不存在，请确认 tag 已创建

这一点与发布流程强耦合：tag 通常由配套的/prompts:release命令创建（见 release.md 步骤 5：git tag vX.Y.Z），因此正确的操作顺序是先发布、后生成 Release Notes。

五、合并路径（PATCH == 0，x.y.0 大版本）

x.y.0版本在语义上等同于"一个 minor 系列的综合发布"。为了避免重复统计（每个修订版本都已有各自的 release notes），命令采用"复用 + 聚合"策略。

5.1 步骤 4：查找前一 minor 系列的所有已发布 release

gh release list --limit 50 --json tagName,isDraft,isPrerelease

从结果中筛选满足以下全部条件的条目：

• tagName以vX.(Y-1).开头（例如版本3.7.0则筛选v3.6.前缀）；
• isDraft == false（非草稿）；
• isPrerelease == false（非预发布）。

如果未找到任何已发布的 release，命令会提示用户并回退到常规路径（步骤 8），而不是强行拼接。

5.2 步骤 5：按版本号升序获取各 release body

对筛选出的每个 release tag，按版本号升序（v3.6.1、v3.6.2、v3.6.3…）逐一拉取其内容：

gh release view v<tag> --json body --jq .body

5.3 步骤 6：合并所有 release body

合并遵循三条规则：

1. 按版本顺序拼接：严格按照版本号升序处理，保证时间线语义；
2. 同平台同类型条目合并：将各版本中相同平台（如 FIT Function Platform）的相同类型（如 Enhancement）条目合并到一起，避免碎片化；
3. 去重 Contributors：合并所有❤️ Contributors段落中的贡献者，去重后按贡献量（出现次数）降序排列。

5.4 步骤 7：生成 Overview

x.y.0版本始终视为 Major release，因此需要生成总结性内容：

1. 顶部🌟 Overview总结段落：由 AI 根据合并内容生成 2-3 句话，概括整个 minor 系列的核心主题和亮点；
2. 每个平台🚀 Features Overview要点列表：从该平台的 Enhancement 条目中提炼 3-5 个关键特性要点。

完成后直接跳到步骤 14，不再走常规路径的数据收集。

六、常规路径（PATCH > 0，修订版本）

6.1 步骤 8：收集合并的 PR

主要数据源：先获取两个 tag 的提交日期，再以日期范围查询合并到目标分支的 PR：

# 获取两个 tag 的日期 git log v<prev-version> --format=%aI -1 git log v<version> --format=%aI -1 # 获取目标分支（从当前版本号推断，如 3.6.x；分支名格式: X.Y.x） # 获取合并到目标分支的 PR gh pr list --state merged --base <branch> \ --json number,title,body,author,labels,mergedAt,url \ --limit 200 --search "merged:YYYY-MM-DD..YYYY-MM-DD"

补充数据源：收集没有关联 PR 的直接 commit（例如直接 push 到分支的提交）：

git log v<prev-version>..v<version> --format="%H %s" --no-merges

命令会把 PR 列表与 commit 列表做对比，找出"没有关联 PR 的 commit"，这些提交同样纳入 release notes。

6.2 步骤 9：收集关联的 Issue

从每个 PR 的 body 中提取关联的 Issue，匹配模式（不区分大小写）：

• 标准形式：Closes #N、Fixes #N、Resolves #N；
• 动词原形及复数形式：close #N、fix #N、resolve #N等。

对每个提取到的 Issue 编号，拉取详情以丰富描述：

gh issue view <N> --json number,title,labels,url

这些 Issue 信息会在生成条目时作为"关联 Issue"呈现（对应模板中的in #Issue and #PR格式）。

6.3 步骤 10：分类 — 按模块分组（四层优先级）

每个 PR / commit 归属哪个平台，按以下优先级从高到低判断：

模块到平台的映射表：

6.4 步骤 11：分类 — 按类型分组

根据 PR title 的 conventional commit type 归类：

该分类规则与仓库提交规范一脉相承。CONTRIBUTING.md 要求 commit message 采用type(scope): subject的 Conventional Commits 格式，例如feat(fit): 支持 HTTPS 双向认证、fix(waterflow): 修复调度引擎的空指针异常。规范的 commit 是自动化分类准确性的前提——scope 被直接用于模块判断，type 被直接用于类型判断。

6.5 步骤 12：判断发布级别

根据变更数量与性质决定输出详细程度：

• Major release（合并 PR 数 > 15 个）：
  • 生成🌟 Overview总结段落（2-3 句话概括本次发布核心主题）；
  • 每个平台生成🚀 Features Overview要点列表；
• Regular release：直接列出 Enhancement / Bugfix 条目，不加 Overview。

七、Release Notes 标准格式模板与书写规则

7.1 完整模板

命令在步骤 13 按项目已有格式输出 markdown，完整模板如下：

## FIT Function Platform ### ✨ Enhancement - [fit] 描述内容 by @author1 and @author2 in #123 - Upgrade xxx from v1 to v2 by @author in #456 ### ✅ Bugfix - [fit] 修复xxx问题 by @author in #100 and #789 ## FIT Expression for LLM ### ✨ Enhancement - [FEL] 描述内容 by @author in #234 ## Waterflow Flow Scheduling Platform ### ✨ Enhancement - [waterflow] 描述内容 by @author in #345 ## 🤖 AI Development Configuration ### ✨ Enhancement - 描述内容 by @author in #567 ## ❤️ Contributors @contributor1, @contributor2, @contributor3

7.2 七条格式规则

1. 条目格式：- [module] 描述 by @author1 and @author2 in #N；
2. 关联 Issue 和 PR：in #Issue and #PR；
3. 无关联 PR 的 commit：省略in [#N]部分，直接写描述；
4. 描述内容：优先使用 PR title，去掉type(scope):前缀，首字母大写；
5. 贡献者列表：去重，按贡献量（PR 数量）降序排列；
6. 空平台：某平台没有任何变更时，不输出该平台章节；
7. 多作者：PR 有多个 co-author 时用and连接，如by @a and @b。

八、公共收尾步骤：展示确认与创建 Draft Release

8.1 步骤 14：展示并确认

将生成的 release notes完整输出给用户查看，然后询问两件事：

1. 是否需要调整内容（修改描述、调整分类、增删条目等）；
2. 是否创建 GitHub Draft Release。

用户要求调整时，根据反馈修改后重新输出，直到用户确认。

8.2 步骤 15：创建 Draft Release

用户确认后，将 release notes 写入临时文件，再创建草稿：

gh release create v<version> \ --title "v<version>" \ --notes-file /tmp/release-notes-v<version>.md \ --target <release-branch-or-tag> \ --draft

命令输出结果示例：

✅ Draft Release 已创建 - Release URL: <draft-release-url> - 版本: v<version> - 状态: Draft（草稿） ⚠️ 请在 GitHub 上最终审核并发布： 1. 打开上述 URL 2. 检查 Release Notes 内容 3. 确认无误后点击 "Publish release"

关键设计是Draft 模式：创建的是草稿 Release，不会自动发布，必须由人工在 GitHub 上最终审核后点击 "Publish release"。这保证了对外发布前始终存在一道人工把关。

九、注意事项、错误处理与相关命令

9.1 六项注意事项

1. 需要ghCLI：命令依赖 GitHub CLI，请确保已安装并完成认证；
2. Tag 必须已存在：运行前确保v<version>和上一版本 tag 已创建（通常由/prompts:release完成）；
3. Draft 模式：创建的是草稿，不会自动发布，需人工审核后发布；
4. PR 搜索范围：基于日期范围搜索，可能包含少量超出范围的 PR，命令会尽力过滤；
5. 模块分类准确性：自动分类基于 title/scope/文件路径推断，复杂 PR 可能需要人工调整；
6. x.y.0 合并路径：依赖前一 minor 系列的 release 已在 GitHub 上发布（非 Draft）；若没有已发布的 release，则回退到常规路径。

9.2 六类错误处理

9.3 与配套命令的协作闭环

create-release-note并不是孤立的，它与.codex/commands/下的其他命令共同构成发布链路：

• release.md：执行完整发布流程——校验工作区干净、全局替换X.Y.Z-SNAPSHOT→X.Y.Z、创建 Release commit 与轻量 tagvX.Y.Z、创建发布分支release-X.Y.Z、回退开发分支后准备下一 SNAPSHOT。它是 create-release-note 的前置步骤，负责产出 tag；
• commit.md：提交代码（提供最佳实践指南），保证 commit message 符合 Conventional Commits，为自动分类提供结构化输入；
• create-pr.md：创建 Pull Request，是 PR title/scope 规范的来源。

建议的完整发布闭环为：/prompts:commit提交 →/prompts:create-pr合入 →/prompts:release <version>打 tag →/prompts:create-release-note <version>生成 Notes 并创建 Draft → 人工审核发布。

十、总结

/prompts:create-release-note将 FIT 框架的多平台发版从"人工整理"升级为"半自动流水线"：它以 tag 为边界、以ghCLI 为数据源、以模块优先级 + conventional commit type 为分类引擎，并针对x.y.0大版本专门设计了"合并前一 minor 系列"的路径以避免重复统计。其精髓在于始终保留人工确认环节——自动生成、Draft 草稿、人工审核后发布，兼顾效率与质量。

对于希望在本仓库复刻这套实践的开发者，可以从三处入手：阅读 命令本体 理解执行细节，参考.codex/README.md了解 prompts 安装与占位符机制，对照 CONTRIBUTING.md 落实 Conventional Commits 提交规范与版本标签约定——三者齐备，Release Notes 的自动化方能行稳致远。

• 人工智能
• 大模型
• AI 应用
• 后端
• AI Agent
• RAG
• 流程编排
• 微服务