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

Semantic Release 版本迁移跟踪

目标

将版本管理从固定 patch + 1 的自动打 tag 迁移到 semantic-release，同时保留现有 .github/workflows/publish.yml 的 tag 触发打包、NuGet 发布、GitHub Packages 发布和 GitHub Release 流程。

• 用 cycjimmy/semantic-release-action 替换 auto-tag.yml 的版本判断和打 tag 逻辑
• 保留 publish.yml 的现有发布实现，不重写 NuGet 流程
• 避免 semantic-release 与 publish.yml 重复创建 GitHub Release
• 将版本规则固定为 feat -> minor、fix/perf/refactor/deps/security -> patch、BREAKING CHANGE 或 ! -> major
• 为手动 workflow_dispatch 保留 dry-run 验证入口，先验证最近提交会算出什么版本

当前恢复点

• 恢复点编号：SEMREL-RP-007
• 当前阶段：修复 git-cliff 发布说明 PR 链接缺失
• 当前焦点：
  • .github/workflows/auto-tag.yml 的 preview / release job 增加 pull-requests: read
  • .github/workflows/auto-tag.yml 的 git-cliff-action 改用 ${{ github.token }} 读取 PR 元数据，PAT_TOKEN 只保留给 semantic-release 的 dry-run push 探测与真实打 tag
  • .github/workflows/publish.yml 的 GitHub Release job 增加 pull-requests: read
  • 保持 .github/cliff.toml 的 by @user in #PR 模板不变，只补足 GitHub PR 元数据读取权限
  • fix/release-notes-pr-links 分支映射到当前 active topic

已知风险

• GITHUB_TOKEN 推送 tag 不会再触发另一个 workflow，真实发布仍需要 PAT_TOKEN
• semantic-release preview 虽然不会真实推送 tag，但仍会执行远端 git push --dry-run 权限探测；如果 PAT 仅具备 read 权限、没有 contents:write，仍然会先于版本分析阶段失败
• semantic-release 的版本判断完全依赖 Conventional Commits；不规范提交会直接影响版本计算
• patch 级提交类型的发布语义需要同时维护在 .releaserc.json、AGENTS.md、公开贡献文档和 release-notes-generator 的 notes 类型映射中，避免版本升级原因与 workflow summary 漂移
• cycjimmy/semantic-release-action@v6 需要在 preview / release 两端都安装 conventional-changelog-conventionalcommits 以保证 conventionalcommits preset 在 GitHub Actions 中可解析
• git-cliff-action 的 OUTPUT 文件需要在 softprops/action-gh-release 执行时保留在当前工作目录，后续如调整 working-directory 或 artifact 路径，需要同步复查 body_path
• git-cliff-action 依赖 GitHub API 补充 commit.remote.pr_number；生成 release notes 的 workflow job 必须具备 pull-requests: read，否则模板只能稳定输出作者，不能稳定输出 in #PR
• auto-tag.yml 中 job 级 permissions 只约束 ${{ github.token }}，不约束 ${{ secrets.PAT_TOKEN }}；生成 release notes 时必须使用 ${{ github.token }} 才能让 pull-requests: read 声明真正生效

已完成

• 历史迁移结论与 SEMREL-RP-001 到 SEMREL-RP-003 的稳定完成项已归档到 ai-plan/public/semantic-release-versioning/archive/todos/semantic-release-versioning-2026-04-26.md
• 已将 preview / release 两段重复的 PAT 校验提取到 .github/actions/validate-pat/action.yml
• 已在 PAT 校验中补充 permissions.push 断言，避免 read-only token 通过 API 探活却在 semantic-release 的 git push --dry-run 阶段才失败
• 已为 PAT 校验的 mktemp 文件补充 trap 清理，避免异常退出时遗留临时文件路径干扰日志
• SEMREL-RP-004 的 release notes 模板修复、验证和合并后分支收尾已归档到 ai-plan/public/semantic-release-versioning/archive/todos/semantic-release-versioning-rp004-2026-05-02.md
• SEMREL-RP-005 已扩展 deps / security 的 patch 发布规则，并同步提交规范文档
• SEMREL-RP-006 已根据 PR review 复核结果补齐 release notes 类型映射，避免 patch 发布原因只触发版本而不进入 notes
• SEMREL-RP-007 已为所有 git-cliff-action release notes 生成 job 补齐 PR 读取权限，并让 auto-tag.yml 的 git-cliff-action 改用 ${{ github.token }}，避免未来 GitHub Release 正文缺失 PR 链接

验证

• SEMREL-RP-004 的本地验证结果已归档。
• SEMREL-RP-005 已完成本地验证：
  • jq . .releaserc.json 通过
  • semantic-release --dry-run --no-ci 已成功加载 commit-analyzer 和 release-notes-generator，随后因远端 tag fetch 会 clobber 本地既有 tags 而终止，未暴露配置解析错误
  • dotnet build GFramework.sln -c Release 通过，0 warning / 0 error
• SEMREL-RP-006 已完成本地验证：
  • jq . .releaserc.json 通过
  • semantic-release --dry-run --no-ci 已成功加载 commit-analyzer 和 release-notes-generator，随后因远端 tag fetch 会 clobber 本地既有 tags 而终止，未暴露 presetConfig.types 配置解析错误
  • dotnet build GFramework.sln -c Release 通过，0 warning / 0 error
• SEMREL-RP-007 已完成本地验证：
  • workflow 权限静态检查通过，所有 git-cliff-action 所在 job 均使用具备 pull-requests: read 的 ${{ github.token }}
  • .github/cliff.toml 通过 Python tomllib 解析
  • python3 scripts/license-header.py --check 通过
  • dotnet build GFramework.sln -c Release 通过，0 warning / 0 error
• 更早阶段的 dry-run / tag /抽象项目验证已归档到 ai-plan/public/semantic-release-versioning/archive/todos/semantic-release-versioning-2026-04-26.md

下一步

1. 推送 SEMREL-RP-007 的 PR review 修复，并重新抓取 PR review 确认重复标题线程和 PAT token 说明已收敛
2. 如后续需要回填当前 GitHub Release 正文，使用带 PR read 权限的 GitHub CLI 或 API token 重新生成并更新 notes