fix(release): 修复语义化发版审查问题

- 修复 semantic-release 配置，切换到 conventionalcommits preset 并显式声明 breaking、revert、patch 语义 - 更新 auto-tag workflow，补充 preview 成功守卫、PAT 存活性校验、snapshot 说明与 release notes summary 输出 - 更新 AGENTS 与 semantic-release topic 的 tracking/trace，记录当前发版规则、验证结果与恢复点
2026-05-06 16:16:44 +08:00 · 2026-04-26 10:36:27 +08:00 · 2026-04-26 10:36:27 +08:00 · 9f04c0b5f8
commit 9f04c0b5f8
parent 3ca095e987
5 changed files with 141 additions and 60 deletions
--- a/.github/workflows/auto-tag.yml
+++ b/.github/workflows/auto-tag.yml
@ -27,13 +27,6 @@ jobs:
          persist-credentials: false
          ref: ${{ github.sha }}

-      - name: Validate release branch
-        run: |
-          if [ "${GITHUB_REF}" != "refs/heads/main" ]; then
-            echo "::error::Semantic Release Version and Tag only supports workflow_dispatch on main."
-            exit 1
-          fi
-
      # preview 始终先运行，用于给当前 SHA 生成待发布版本预览。
      - name: Semantic release preview
        id: semantic_release
@ -41,6 +34,8 @@ jobs:
        with:
          dry_run: true
          ci: false
+          extra_plugins: |
+            conventional-changelog-conventionalcommits@9.1.0
        env:
          GITHUB_TOKEN: ${{ github.token }}

@ -52,6 +47,9 @@ jobs:
          echo "next_tag=${{ steps.semantic_release.outputs.new_release_git_tag }}"

      - name: Write preview summary
+        env:
+          RELEASE_PUBLISHED: ${{ steps.semantic_release.outputs.new_release_published }}
+          RELEASE_NOTES: ${{ steps.semantic_release.outputs.new_release_notes }}
        run: |
          {
            echo "## Semantic Release Preview"
@ -61,6 +59,15 @@ jobs:
            echo "- Last tag: \`${{ steps.semantic_release.outputs.last_release_git_tag }}\`"
            echo "- Next version: \`${{ steps.semantic_release.outputs.new_release_version }}\`"
            echo "- Next tag: \`${{ steps.semantic_release.outputs.new_release_git_tag }}\`"
+            echo "- Snapshot semantics: this preview is pinned to dispatch SHA \`${{ github.sha }}\`; commits added to \`main\` after the run starts are not included."
+            if [ "${RELEASE_PUBLISHED}" = "true" ] && [ -n "${RELEASE_NOTES}" ]; then
+              echo
+              echo "<details><summary>Preview release notes</summary>"
+              echo
+              printf '%s\n' "${RELEASE_NOTES}"
+              echo
+              echo "</details>"
+            fi
            echo
            echo "If the version looks correct, approve the \`release-approval\` environment to continue."
          } >> "${GITHUB_STEP_SUMMARY}"
@ -68,6 +75,7 @@ jobs:
  release:
    if: >
      github.ref == 'refs/heads/main' &&
+      needs.preview.result == 'success' &&
      needs.preview.outputs.published == 'true'
    needs:
      - preview
@ -85,17 +93,46 @@ jobs:
          ref: ${{ github.sha }}

      - name: Validate PAT token
+        env:
+          PAT_TOKEN: ${{ secrets.PAT_TOKEN }}
+          REPO_API_URL: ${{ github.api_url }}/repos/${{ github.repository }}
        run: |
          if [ -z "${PAT_TOKEN}" ]; then
            echo "::error::PAT_TOKEN is required because a tag created with GITHUB_TOKEN will not trigger publish.yml."
            exit 1
          fi
-        env:
-          PAT_TOKEN: ${{ secrets.PAT_TOKEN }}
+
+          response_file="$(mktemp)"
+          status_code="$(
+            curl -sS -o "${response_file}" -w "%{http_code}" \
+              -H "Authorization: Bearer ${PAT_TOKEN}" \
+              -H "Accept: application/vnd.github+json" \
+              -H "X-GitHub-Api-Version: 2022-11-28" \
+              "${REPO_API_URL}"
+          )"
+
+          case "${status_code}" in
+            200)
+              ;;
+            401|403)
+              echo "::error::PAT_TOKEN is invalid or lacks access to ${GITHUB_REPOSITORY} (HTTP ${status_code})."
+              cat "${response_file}"
+              exit 1
+              ;;
+            *)
+              echo "::error::Failed to validate PAT_TOKEN against ${REPO_API_URL} (HTTP ${status_code})."
+              cat "${response_file}"
+              exit 1
+              ;;
+          esac

      - name: Semantic release
        id: semantic_release
        uses: cycjimmy/semantic-release-action@v6
+        with:
+          dry_run: false
+          extra_plugins: |
+            conventional-changelog-conventionalcommits@9.1.0
        env:
          GITHUB_TOKEN: ${{ secrets.PAT_TOKEN }}

@ -110,6 +147,9 @@ jobs:
          echo "next_tag=${{ steps.semantic_release.outputs.new_release_git_tag }}"

      - name: Write release summary
+        env:
+          RELEASE_PUBLISHED: ${{ steps.semantic_release.outputs.new_release_published }}
+          RELEASE_NOTES: ${{ steps.semantic_release.outputs.new_release_notes }}
        run: |
          {
            echo "## Semantic Release Publish"
@ -122,4 +162,13 @@ jobs:
            echo "- Last tag: \`${{ steps.semantic_release.outputs.last_release_git_tag }}\`"
            echo "- Next version: \`${{ steps.semantic_release.outputs.new_release_version }}\`"
            echo "- Next tag: \`${{ steps.semantic_release.outputs.new_release_git_tag }}\`"
+            echo "- Snapshot semantics: this publish run still uses dispatch SHA \`${{ github.sha }}\`; commits added to \`main\` after the preview started are excluded."
+            if [ "${RELEASE_PUBLISHED}" = "true" ] && [ -n "${RELEASE_NOTES}" ]; then
+              echo
+              echo "<details><summary>Published release notes</summary>"
+              echo
+              printf '%s\n' "${RELEASE_NOTES}"
+              echo
+              echo "</details>"
+            fi
          } >> "${GITHUB_STEP_SUMMARY}"
--- a/.releaserc.json
+++ b/.releaserc.json
@ -7,7 +7,16 @@
    [
      "@semantic-release/commit-analyzer",
      {
+        "preset": "conventionalcommits",
        "releaseRules": [
+          {
+            "breaking": true,
+            "release": "major"
+          },
+          {
+            "revert": true,
+            "release": "patch"
+          },
          {
            "type": "feat",
            "release": "minor"
@ -60,6 +69,7 @@
    [
      "@semantic-release/release-notes-generator",
      {
+        "preset": "conventionalcommits",
        "parserOpts": {
          "noteKeywords": [
            "BREAKING CHANGE",
--- a/AGENTS.md
+++ b/AGENTS.md
@ -59,9 +59,11 @@ All AI agents and contributors must follow these rules when writing, reviewing,
  - Use `feat` only for user-facing or consumer-facing capability additions that should raise the next released version's
    `minor` segment.
  - Use `fix` for behavior corrections, `perf` for observable performance improvements, and `refactor` only for
-    non-feature code restructuring.
+    non-feature code restructuring; these should raise the next released version's `patch` segment.
  - Use `docs`、`test`、`chore`、`build`、`ci`、`style` for their literal categories; do not encode these changes as
-    `feat` just because they feel important.
+    `feat` just because they feel important. These categories MUST NOT trigger a release.
+  - Use `BREAKING CHANGE` in the commit footer or `!` after the type / scope header (for example `feat!:` or
+    `feat(core)!:`) when the change should raise the next released version's `major` segment.
 - Documentation-only changes MUST NOT use `feat`, including new guides, refreshed examples, navigation updates, and
  adoption notes for existing capabilities. If a commit changes both product behavior and related docs, either split the
  commit or use `feat` only when the code/package behavior is the primary released change.
--- a/ai-plan/public/semantic-release-versioning/todos/semantic-release-versioning-tracking.md
+++ b/ai-plan/public/semantic-release-versioning/todos/semantic-release-versioning-tracking.md
@ -13,18 +13,20 @@

 ## 当前恢复点

- 恢复点编号：`SEMREL-RP-001`
- 当前阶段：`Phase 1`
+- 恢复点编号：`SEMREL-RP-002`
+- 当前阶段：`Phase 2`
 - 当前焦点：
-  - 增加 `.releaserc.json`，仅启用版本分析与 release notes 生成，不启用 GitHub Release 发布插件
-  - 将 `auto-tag.yml` 改成同一次 `workflow_dispatch` 里先 `preview`，再等待 environment 审批后继续 `release`
-  - 明确 `PAT_TOKEN` 与 `GITHUB_TOKEN` 的职责边界，确保 tag 继续触发 `publish.yml`
+  - 让 `.releaserc.json` 对 `BREAKING CHANGE` 与 `feat!:` / `feat(scope)!:` 的 `major` 语义与文档保持一致
+  - 将 `auto-tag.yml` 的 preview / release 输出与 PR review 建议对齐，避免 release notes 被静默丢弃
+  - 提前校验 `PAT_TOKEN` 的真实可用性，并把当前 PR review 修复结果同步回 `AGENTS.md` 与 active trace

 ### 已知风险

 - `GITHUB_TOKEN` 推送 tag 不会再触发另一个 workflow，真实发布仍需要 `PAT_TOKEN`
 - `semantic-release` 的版本判断完全依赖 Conventional Commits；不规范提交会直接影响版本计算
- 当前仓库本地 `dotnet clean/build` 仍受 WSL fallback NuGet 路径影响，验证时需要继续采用已知可用的直接构建命令
+- `cycjimmy/semantic-release-action@v6` 需要在 preview / release 两端都安装 `conventional-changelog-conventionalcommits`
+  以保证 `conventionalcommits` preset 在 GitHub Actions 中可解析
+- 当前仓库本地 `dotnet clean/build` 会带出既有 analyzer warnings；本轮仅修正发版配置与文档，不额外处理这些历史 warning

 ## 已完成

@ -34,15 +36,32 @@
 - 已确认 `v0.0.222..HEAD` 之间存在 `feat(...)` 提交，按目标规则首次 dry-run 预期版本应为 `v0.1.0`
 - 已新增 `.releaserc.json`，仅保留 `@semantic-release/commit-analyzer` 与
  `@semantic-release/release-notes-generator`，避免 `semantic-release` 直接创建 GitHub Release
+- 已将 `.releaserc.json` 的 `commit-analyzer` / `release-notes-generator` 同步切换到 `conventionalcommits`
+  preset，并显式声明：
+  - `breaking -> major`
+  - `revert -> patch`
+  - `feat -> minor`
+  - `fix/perf/refactor -> patch`
+  - `docs/test/chore/build/ci/style -> no release`
 - 已将 `.github/workflows/auto-tag.yml` 重写为：
  - `workflow_dispatch` 启动后总是先跑 `preview`
  - `preview` 只执行 dry-run，输出 `last_tag`、`next_version` 与 `next_tag`
  - `release` job 依赖 `preview` 输出，并通过 `release-approval` environment 暂停等待人工确认
  - 人工批准后，`release` 在同一 SHA 上执行真实打 tag，并把 preview / release 结果都写入 job summary
+- 已按 PR review 修复 `auto-tag.yml`：
+  - 删除 preview job 中与 job 级 `if` 重复的运行时分支校验
+  - 为 release job 增加 `needs.preview.result == 'success'` 守卫
+  - 为 preview / release 的 semantic-release action 显式安装 `conventional-changelog-conventionalcommits@9.1.0`
+  - 在 release 前通过 GitHub API 校验 `PAT_TOKEN` 是否真实可访问当前仓库
+  - 在 preview / release summary 中补充 snapshot 语义与生成的 release notes
 - 已明确真实打 tag 仍使用 `PAT_TOKEN`，因为 `GITHUB_TOKEN` 推送的 tag 不会继续触发 `publish.yml`
- 已更新 `AGENTS.md` 的 Conventional Commit 规则，显式禁止把纯文档变更写成 `feat(...)` 或 `feat(docs)`
+- 已更新 `AGENTS.md` 的 Conventional Commit 规则，显式补充：
+  - `fix/perf/refactor -> patch`
+  - `docs/test/chore/build/ci/style -> no release`
+  - `BREAKING CHANGE` 或 `!` header -> major
 - 已移除基于 `workflow_run` 和 `[release ci]` 的自动发版门闸，后续版本预览与真实发版都由维护者手动触发
 - 已将 release 流程从“两次独立 workflow_dispatch”收敛为“同一次 run 里 preview + 审批 + release”的链路
+- 已精简 active trace，移除已废弃的 `release_mode=preview|release` 中间方案，保留当前有效恢复点

 ## 验证

@ -64,12 +83,19 @@
 - `npx --yes semantic-release --dry-run --no-ci`（在 `/tmp/gframework-semrel-dryrun`）
  - 结果：通过
  - 备注：dry-run 成功识别 `v0.0.222` 为最新 release，并分析 `269` 个提交；按当前规则会提升到下一次 `minor` 发布，预期 tag 为 `v0.1.0`
+- `npx --yes -p semantic-release -p conventional-changelog-conventionalcommits@9.1.0 semantic-release --dry-run --no-ci`（在 `/tmp/gframework-semrel-dryrun`）
+  - 结果：通过
+  - 备注：成功加载 `@semantic-release/commit-analyzer` 与 `@semantic-release/release-notes-generator`，证明
+    `conventionalcommits` preset 包可被解析；本次 dry-run 未继续出版本，是因为干净克隆的 `main` 已落后远端
 - `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`（手动发版入口调整后复验）
  - 结果：通过
  - 备注：`0 warning / 0 error`
+- `dotnet build GFramework.sln -c Release`
+  - 结果：通过
+  - 备注：Release 构建完成，`639 warning / 0 error`；warning 为仓库既有基线，与本轮 workflow / doc 改动无新增关联项

 ## 下一步

-1. 在仓库 Settings -> Environments 中为 `release-approval` 配置 required reviewers，确保 workflow 会在 preview 后真正暂停
-2. 复核 Actions summary 呈现方式是否还需要更醒目的版本展示
-3. 若本轮验证通过，按仓库要求创建补充提交并等待你审阅同次 run 的手动发版流程细节
+1. 复核当前 PR review 的 open threads 是否只剩等待 push 的已修复项
+2. 将本轮修复提交到当前分支，等待 GitHub reviewer 重新评估
+3. 若后续需要，再在真实仓库主线最新快照上复验一次 `semantic-release` dry-run 结果展示
--- a/ai-plan/public/semantic-release-versioning/traces/semantic-release-versioning-trace.md
+++ b/ai-plan/public/semantic-release-versioning/traces/semantic-release-versioning-trace.md
@ -2,49 +2,43 @@

 ## 2026-04-26

-### 阶段：方案落地准备（SEMREL-RP-001）
+### 当前恢复点（SEMREL-RP-002）

- 读取当前 `auto-tag.yml` 与 `publish.yml`，确认最小侵入改法应只替换版本判断与打 tag，保留 tag 触发发布链
- 核对最近 tag 与提交历史：
-  - 最新 tag 为 `v0.0.222`
-  - `v0.0.222..HEAD` 含多条 `feat(...)`，按目标规则首次 dry-run 预期结果为 `v0.1.0`
- 补建本主题的 active tracking / trace 入口，并在 `ai-plan/public/README.md` 中为
-  `feat/semantic-release-versioning` 建立 worktree 映射
-
-### 阶段：配置落地与验证（SEMREL-RP-001）
-
- 新增 `.releaserc.json`，显式固定：
+- 当前链路：
+  - `workflow_dispatch` 手动启动
+  - `preview` 对 dispatch SHA 执行 dry-run
+  - `release-approval` environment 审批
+  - `release` 在同一次 run、同一 SHA 上执行真实打 tag
+- 当前规则：
+  - `conventionalcommits` preset 负责解析 `feat!:` / `feat(scope)!:` 与 `BREAKING CHANGE`
  - `feat -> minor`
  - `fix/perf/refactor -> patch`
  - `docs/test/chore/build/ci/style -> no release`
-  - `BREAKING CHANGE` / `BREAKING CHANGES` 作为 major 信号
- 重写 `auto-tag.yml`：
-  - 改为纯 `workflow_dispatch` 手动入口
-  - 增加 `release_mode=preview|release` 输入
-  - `preview` 只跑 dry-run 并输出 `last_tag`、`next_version`、`next_tag`
-  - `release` 由维护者手动触发真实打 tag，并要求 `PAT_TOKEN`
- 收紧 `AGENTS.md` 的提交信息约束，明确提交类型必须反映 release semantics，纯文档变更禁止写成 `feat(...)`
- 按用户反馈继续调整发版入口：
-  - 删除基于 `workflow_run` 的自动发版路径
-  - 统一改为 `workflow_dispatch` 手动触发
-  - 先在同一次 run 中执行 `preview`
-  - 再通过 `release-approval` environment 做人工确认
-  - 审批通过后继续同一 SHA 的真实 `release`
- 复验最小构建命令：
-  - `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`
-  - 结果：通过，`0 warning / 0 error`
- 完成最小构建验证：
-  - `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`
-  - 结果：通过，`0 warning / 0 error`
- 直接在当前工作树执行 `semantic-release --dry-run` 时命中本地 tag 抓取冲突：
-  - `git fetch --tags ... would clobber existing tag`
-  - 结论：当前工作树不适合作为 dry-run 验证环境
- 改用干净临时克隆 `/tmp/gframework-semrel-dryrun` 再跑 dry-run：
-  - 成功识别 `v0.0.222` 为最新 release
-  - 成功分析 `269` 个提交
-  - 按当前规则得出下一次应为 `minor` 发布，预期版本窗口从 `0.0.222` 提升到 `0.1.0`
+  - `breaking -> major`
+- 当前 workflow 加固：
+  - `release` 额外要求 `needs.preview.result == 'success'`
+  - `PAT_TOKEN` 在真实 release 前通过 GitHub API 做存活性校验
+  - preview / release summary 会展示 snapshot 语义与生成的 release notes
+
+### 本轮关键决策
+
+- 保留 `@semantic-release/release-notes-generator`，但不再让它白跑：
+  - 继续生成 notes
+  - 将 notes 写入 GitHub Actions summary
+- 不保留已废弃的 `release_mode=preview|release` 中间方案：
+  - active trace 只保留当前有效链路
+  - 历史演进以 tracking 文档的已完成项为准
+
+### 验证结论
+
+1. `npx --yes -p semantic-release -p conventional-changelog-conventionalcommits@9.1.0 semantic-release --dry-run --no-ci`
+   - 已确认新 preset 包可加载，`commit-analyzer` 与 `release-notes-generator` 正常初始化
+   - 本次 dry-run 未继续出版本，因为干净克隆的 `main` 已落后远端
+2. `dotnet build GFramework.sln -c Release`
+   - 通过，`639 warning / 0 error`
+   - warning 为仓库既有基线，本轮未新增关联 warning

 ### 下一步

-1. 复核变更 diff 并创建提交
-2. 向用户说明新的发版链路与可优化点
+1. 复查当前 PR 的 open review threads 是否只剩等待 push 的已修复项
+2. 创建提交并推送当前分支