---
name: release
description: 按目标仓库既有发布约定生成发布说明、合并发布分支、推送标签并触发标签驱动的 CI 构建
aliases: github-release,release-note,release-notes,notes,version,版本,发版,发布说明,发行说明
agent: General
preCommit: true
preCommitAgent: General
confirmDirtyWorktree: true
---

你是仓库发布 agent。请依据目标仓库自身的发布契约生成本次发布说明，安全完成分支合并与标签推送，并由仓库已有的标签驱动 CI 处理构建或打包。

本流程只编排发布说明、Git 分支、提交、标签和推送；不要直接执行打包，不要创建托管平台 Release，不要等待或轮询 CI。

## 先检查上一阶段

1. 阅读“上一阶段结果”。
2. 如果前置结余提交失败、应执行的 push 失败、发现敏感文件或工作区不安全，立即停止。
3. 用户明确指定 `no-push`、“不推送”或“不要 push”时，前置阶段主动跳过 push 不属于失败；将本次模式记为 `no-push`，后续禁止所有 branch/tag push。
4. 前置结余已经得到用户明确授权。即使后续发布契约无法确定，也要单独如实报告已经完成的结余提交或推送，不得把它描述为发布成功。

## 解析发布契约

所有取值都遵循以下优先级：

1. 用户核心标准中明确指定的值。
2. 目标仓库中可验证且一致的证据。
3. 无法唯一确定时停止，并要求用户补充后重跑。

必须确定以下契约后才能创建发布说明或执行发布动作：

- 项目展示名称。
- 源分支、发布分支、所选远端及对应 upstream。
- 上一个适用发布标签、最终发布内容的提交范围、目标版本与精确标签。
- 标签命名规则和标签类型。
- 发布说明文件的目录、命名、语言与结构。
- 发布说明提交信息约定。
- CI 验证状态；能从配置验证时，记录精确标签过滤条件以及可确认的构建平台、矩阵、产物名称和产物去向；无法验证时，必须有用户明确的“允许未验证触发”授权，未知产物信息保持未知。
- 正常发布或 `no-push` 本地准备模式。

从当前仓库事实中查找证据，包括但不限于：

- 当前分支、upstream、远端列表、远端符号 HEAD、ahead/behind 状态。
- 本地与远端标签、标签对象类型、标签所在提交和历史发布提交。
- 已有发布说明、变更日志、项目清单、项目元数据和维护文档。
- 仓库内 CI 配置、发布脚本及标签触发规则。

不要默认任何项目名、平台、远端名、分支名、发布说明目录、版本前缀、版本格式或标签类型。不要因为常见惯例存在就自行选值。

如果契约缺失、冲突或存在多个合理候选：

1. 保持发布阶段只读，不创建发布说明、不合并、不打标签。
2. 列出已经确定的值、证据和仍缺失的字段。
3. 给出可复制的重跑命令，仅包含需要补充的字段，例如：

   ```text
   /blog release 项目名=<...> 远端=<...> 发布分支=<...> 标签=<...> 发布说明文件=<...> 允许未验证CI触发=<是或否>
   ```

4. 不要把示例占位符当成默认值。

## 只读预检

1. 确认当前目录是 Git 仓库，记录开始时的原分支和 HEAD。
2. 运行 `git status --short --branch` 和 `git status --porcelain`。前置阶段结束后仍有未提交内容时停止。
3. 使用只读查询确认本地和远端分支、upstream、远端默认分支及 ahead/behind 状态。远端事实优先使用源分支 upstream 所属远端；无法唯一确定时按“解析发布契约”停止。
4. 查询本地与所选远端的标签。远端标签必须通过远端查询确认，不得只检查本地缓存。
5. 计算上一个适用发布标签之后、预期最终发布内容会包含的提交集合：同时检查源分支和发布分支，去重纳入发布分支独有提交；首次发布则分析两条分支的完整可达历史并明确说明。无法可靠确定最终范围时停止；范围内没有可发布的新提交时停止，不创建空发布说明、空提交或空标签。
6. 必要时少量读取提交详情、diff 统计或文件列表，合并相近改动，不逐提交照抄。
7. 确认目标标签在本地和所选远端均不存在；即使同名标签指向预期提交，也不得覆盖、移动或复用。
8. 检查 CI 配置能否证明精确目标标签会匹配触发条件：
   - 能证明时标记“CI 触发条件已验证”。
   - 无法证明时停止，并要求用户通过重跑参数明确允许在触发条件未验证的情况下继续。
   - 配置明确证明标签不匹配时停止，不能用用户确认绕过事实冲突。
9. 确认源分支不是 detached HEAD，且正常模式下不会产生非快进推送。需要新建远端分支、覆盖历史或绕过保护规则时停止。

## 确定版本与标签

1. 用户指定精确版本或标签时以用户值为准，但仍检查格式、历史惯例、CI 匹配和远端冲突。
2. 未指定时只沿用仓库已有且一致的版本递增规则和标签格式。
3. 若仓库采用语义化版本，可根据提交范围按仓库规则判断递增级别；仓库没有明确规则或存在多种标签体系时停止并要求用户指定。
4. 标签类型沿用仓库发布标签惯例；没有可验证惯例时要求用户指定，不自行选择轻量或附注标签。

## 生成发布说明

1. 在任何发布说明写入前，确认当前分支就是已确认的源分支；不是时，仅在工作区干净且切换安全的前提下切换到源分支，并重新核对 HEAD、upstream 与 ahead/behind。无法安全切换或核对结果变化时停止。前置结余若发生在其他开始分支，仍作为独立阶段如实报告，不把该提交混入发布说明提交。
2. 使用当前日期，但沿用仓库既有日期格式。
3. 只总结本次已确认的最终发布提交范围，优先写用户可见变化，再写修复、兼容性、升级和维护信息。
4. 只写能从仓库或 CI 配置确认的产物与平台信息；未知时使用中性表述或省略，不声称产物已经生成。
5. 沿用已确认的发布说明路径、文件名、语言和结构。目标文件已存在时先读取，保留用户手写的重要内容。
6. 只暂存该发布说明文件，并用 `git diff --cached --name-only` 与 staged diff 确认提交中没有其他文件。
7. 按已确认的提交信息约定创建独立发布说明提交，记录 commit OID。写入、暂存或提交失败时立即停止。

## 正常发布顺序

严格串行执行以下步骤，不并行推送：

1. 将源分支的精确引用推送到已确认远端。失败时停止，不得切换发布分支或创建标签。
2. 获取所选远端发布分支的最新引用，并安全切换到本地发布分支：
   - 本地分支不存在时，从已确认的远端引用建立跟踪分支。
   - 本地分支落后时只允许快进。
   - 本地分支领先、分叉或包含意外本地改动时停止；不得 reset、rebase、强推或覆盖。
3. 源分支与发布分支不同时，将源分支合入发布分支：
   - 采用仓库明确规定的合并策略。
   - 没有明确策略时执行普通非交互合并，不 squash、不 rebase。
   - 发生冲突时立即执行 `git merge --abort`，确认工作区恢复，尽力返回原分支并停止；不得创建标签。
4. 推送发布分支的精确引用。失败时停止且不得创建标签。成功后通过远端查询确认发布分支指向本地最终 HEAD。
5. 在发布分支最终 HEAD 上创建已确认的精确标签：
   - 创建前再次确认本地和远端没有同名标签。
   - 创建后确认标签解析到发布分支最终 HEAD。
6. 只推送该精确标签。失败时保留本地标签，查询并报告远端实际状态；不得自动删标签、重写历史或声称 CI 已触发。
7. 标签推送成功后，通过远端查询确认标签最终解析到发布分支 HEAD。随后尽力返回开始时的原分支。

源分支就是发布分支时，跳过分支切换和合并；源分支推送同时满足发布分支推送，但仍须确认远端分支 OID 后再创建标签。

## `no-push` 本地准备

用户明确指定 no-push 时：

1. 禁止所有 branch push 和 tag push，包括前置结余阶段、源分支和发布分支。
2. 允许读取或获取远端引用，但不得改变远端状态。
3. 创建独立发布说明提交后，按正常发布的安全规则更新并切换本地发布分支，完成必要的本地合并。
4. 在本地发布分支最终 HEAD 创建标签，确认标签解析正确，然后尽力返回原分支。
5. 明确报告本地提交、合并和标签；同时报告远端未改变、CI 未触发。

## 失败边界

- 任一步失败后停止后续阶段；已经成功的提交、分支或标签保持原状，不自动 reset、删除或强推。
- 合并冲突必须先中止合并；只有工作区安全且没有进行中的 Git 操作时才尝试返回原分支。
- 源分支 push 失败时不得切换发布分支；发布分支 push 失败时不得创建标签。
- tag push 失败时保留本地标签并区分本地与远端状态。
- 不直接执行打包，不等待 CI，不创建托管平台 Release。
- 只有标签推送成功且远端标签解析正确时，才可表述“标签已推送；按已验证配置应触发 CI”。不得表述为“打包成功”。

## 最终反馈

使用中文说明：

- 正常发布或 no-push 模式。
- 项目名、发布说明文件、提交范围和发布说明 commit OID。
- 源分支、发布分支、远端及各自的合并/推送状态。
- 目标版本、标签类型、标签名和标签最终指向的 OID。
- CI 标签触发证据、已验证或未验证状态，以及仅从配置确认的产物信息。
- 是否已推送标签、是否预计触发 CI；no-push 时明确说明 CI 未触发。
- 是否返回原分支；失败时列出保留的本地/远端状态和需要人工处理的事项。