release-note-generation

发布说明生成技能

通过收集已合并的 PR、使用本地 CLI Agent 总结每个 PR、按标签分组并生成面向用户的摘要，生成专业的 PowerToys 发布说明。正式版和预览版发布使用相同的 PR 元数据、署名、分组和格式规则。

输出目录

所有生成的文件都放在仓库根目录下的 Generated Files/ReleaseNotes/ 中（已加入 gitignore）。

Generated Files/ReleaseNotes/
├── milestone_prs.json           # Raw PR data from GitHub
├── sorted_prs.csv               # Sorted PR list with Copilot summaries
├── prs_with_milestone.csv       # Milestone assignment tracking
├── grouped_csv/                 # PRs grouped by label (one CSV per label)
├── grouped_md/                  # Generated markdown summaries per label
└── v{VERSION}-release-notes.md  # Final consolidated release notes

预览版发布运行会使用独立的子目录：

Generated Files/ReleaseNotes/preview-<buildId>/
├── release-context.json
├── delta-commits.json
├── delta-prs.json
├── removed-prs.json
├── unattributed-commits.json
├── MemberList.md
├── milestone_prs.json
├── sorted_prs.csv
├── release-notes.md
├── hashes.md
├── release-manifest.json        # Local audit artifact; never uploaded
├── assets-manifest.json         # Local asset inventory; never uploaded
└── final-review.md

适用场景

• 为里程碑生成发布说明
• 总结某个版本中合并的 PR
• 在本地生成每个 PR 的审核摘要，用于撰写发布说明
• 为缺少里程碑的 PR 指定里程碑
• 收集两个提交或标签之间的 PR
• 为新版本更新 README.md
• 准备 GitHub 发布资源（下载安装程序和符号文件，并计算哈希值）
• 根据 ADO 构建 URL 或构建 ID 准备完整的预览版草稿
• 比较 main 和 stable 分支转换前后的预览版内容

前置条件

• 已安装并完成身份验证的 GitHub CLI（gh） — 收集脚本使用 gh pr view 和 gh api graphql 获取 PR 元数据和共同作者信息。运行 gh auth status 进行验证；如果尚未登录，请先运行 gh auth login。详情请参阅 步骤 1.0.0。
• MCP 服务：已安装 github-mcp-server（用于在本地 Agent 审核步骤中获取 PR 差异和文件）
• 对于预览版发布和 prepare-release-assets.ps1：Azure CLI 已通过 Microsoft 租户完成身份验证（az login），并安装 azure-devops 扩展；可访问 microsoft/Dart ADO 项目

必需变量

对于正式版发布，请在开始前与用户确认 {{ReleaseVersion}}。 对于预览版发布，请勿询问版本号：从候选 ADO 构建中推导。

变量	说明	示例
{{ReleaseVersion}}	目标发布版本	0.98

预览模式则需要一个 ADO 构建 URL 或数字构建 ID。系统会自动推导版本、源提交、分支和上一版本，无需询问用户。

场景路由

阅读场景索引，然后仅遵循所选场景：

• 正式版发布：适用于基于里程碑或版本的发布说明。
• 预览版发布：适用于从 ADO 构建到草稿的自动化工作流。

工作流概览

┌────────────────────────────────┐
│ 1.0 Verify gh auth + MemberList │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 1.1 Collect PRs (stable range) │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 1.2 Assign Milestones           │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 2.1–2.4 Label PRs (auto+human)  │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 3.1 Local-agent PR summaries    │
│ (writes CopilotSummary)         │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 3.2 (Optional) Refresh PR data  │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 3.3 Group by label              │
│ (grouped_csv)                   │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 4.1 Summarize (grouped_md)      │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 4.2 Final notes (v{VERSION}.md) │
└────────────────────────────────┘

步骤	操作	详情
1.0	验证前置条件	gh auth status 必须通过；生成 MemberList.md
1.1	收集 PR	从 stable 分支上的上一版本标签开始 → sorted_prs.csv
1.2	指定里程碑	确保所有 PR 都有正确的里程碑
2.1–2.4	标记 PR	自动建议 + 人工标记低置信度项
3.1–3.3	审核与分组	本地 Agent 将每个 PR 差异总结到 CopilotSummary →（可选刷新）→ 按标签分组
4.1–4.2	摘要与定稿	生成分组摘要，然后汇总

详细工作流文档

请勿一次性阅读所有步骤，只阅读当前要执行的步骤。

• 步骤 1：收集与里程碑
• 步骤 2：为 PR 添加标签
• 步骤 3：审核与分组
• 步骤 4：生成摘要

可用脚本

脚本	用途
dump-prs-since-commit.ps1	获取提交或标签之间的 PR
group-prs-by-label.ps1	将 PR 分组到 CSV 文件中
collect-or-apply-milestones.ps1	分配里程碑
diff_prs.ps1	增量 PR 差异
prepare-release-assets.ps1	从 ADO 构建中下载安装程序和符号，计算 SHA256，并生成 GitHub 发布页面上的“安装程序哈希” Markdown 表格
get-release-build-metadata.ps1	解析并验证候选构建的标识、版本、渠道、意图和源提交
get-previous-published-release.ps1	选择在候选项排队时间之前发布的最新正式版或预览版
get-preview-release-delta.ps1	计算确切发布提交之间语义上的新增和移除 PR
collect-pr-metadata.ps1	规范化明确指定的一组 PR 编号对应的 GitHub 元数据
new-preview-release-manifest.ps1	创建可审计的构建、基线和语义差异发布清单
upsert-draft-preview-release.ps1	创建或更新草稿预发布版本，但不公开发布操作
verify-draft-preview-release.ps1	验证草稿标记、目标提交、托管正文和已上传资源

参考资料

• 示例输出 - 摘要格式示例
• 详细说明 - 旧版完整文档

约定

• 终端使用：默认禁用；仅在用户明确要求时运行脚本
• 预览版自动化：明确要求准备预览版，或由 Prepare Preview Release Agent 调用，即授权使用规范的预览版脚本
• 预览版清单：将 release-manifest.json 和 assets-manifest.json 保留在本地审计包中；不要将任一文件上传为 GitHub 发布资源
• 预览版说明布局：将 Installer Hashes 部分放在标题和简短的公开介绍之后，紧接其后，并置于 Highlights 和所有变更部分之前
• 批量生成：一次性生成所有 grouped_md 文件，然后由人工审核
• PR 顺序：所有输出均保留 sorted_prs.csv 中的顺序
• 标签筛选：保留 Product-*、Area-*、GitHub*、*Plugin、Issue-*

故障排除

问题	解决方案
找不到 gh 命令	安装 GitHub CLI 并将其添加到 PATH
未返回 PR	确认里程碑标题完全匹配
许多 PR 的 CopilotSummary 为空	运行步骤 3.1（本地 Agent 摘要）。不要从 CLI 或编码 Agent 使用 mcp_github_request_copilot_review——GitHub API 会拒绝由机器人发起的审核请求，因此该列会一直为空。
许多 PR 未添加标签	返回标签步骤，然后再进行分组
prepare-release-assets.ps1 失败并提示“Failed to acquire ADO access token”	运行 az login，并确保你有权访问 microsoft/Dart ADO 项目
候选项没有 release-metadata.json	元数据解析器会回退到流水线日志；如果值含糊不清或相互冲突，则会停止运行
切换分支后首次预览出现意外变更	检查 removed-prs.json 和 unattributed-commits.json；参见预览差异解析