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

- 修复 semantic-release 配置，切换到 conventionalcommits preset 并显式声明 breaking、revert、patch 语义

- 更新 auto-tag workflow，补充 preview 成功守卫、PAT 存活性校验、snapshot 说明与 release notes summary 输出

- 更新 AGENTS 与 semantic-release topic 的 tracking/trace，记录当前发版规则、验证结果与恢复点

.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}"

.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",

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.

ai-plan/public/semantic-release-versioning/todos/semantic-release-versioning-tracking.md

@@ -13,18 +13,20 @@
 
 ## 当前恢复点
 
-- 恢复点编号：`SEMREL-RP-001`
+- 恢复点编号：`SEMREL-RP-002`
-- 当前阶段：`Phase 1`
+- 当前阶段：`Phase 2`
 - 当前焦点：
-  - 增加 `.releaserc.json`，仅启用版本分析与 release notes 生成，不启用 GitHub Release 发布插件
+  - 让 `.releaserc.json` 对 `BREAKING CHANGE` 与 `feat!:` / `feat(scope)!:` 的 `major` 语义与文档保持一致
-  - 将 `auto-tag.yml` 改成同一次 `workflow_dispatch` 里先 `preview`，再等待 environment 审批后继续 `release`
+  - 将 `auto-tag.yml` 的 preview / release 输出与 PR review 建议对齐，避免 release notes 被静默丢弃
-  - 明确 `PAT_TOKEN` 与 `GITHUB_TOKEN` 的职责边界，确保 tag 继续触发 `publish.yml`
+  - 提前校验 `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 后真正暂停
+1. 复核当前 PR review 的 open threads 是否只剩等待 push 的已修复项
-2. 复核 Actions summary 呈现方式是否还需要更醒目的版本展示
+2. 将本轮修复提交到当前分支，等待 GitHub reviewer 重新评估
-3. 若本轮验证通过，按仓库要求创建补充提交并等待你审阅同次 run 的手动发版流程细节
+3. 若后续需要，再在真实仓库主线最新快照上复验一次 `semantic-release` dry-run 结果展示

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