发布说明智能体

自动收集已合并的 PR 和问题、策划具有适当分类的发布说明、以及准备好发货的 Changelog 草稿。

每次发布时，你都需要告诉用户发生了什么变化。这意味着阅读已合并的 PR、将其分类（功能、修复、安全、内部）、编写用户友好的摘要，以及将所有内容打包成发布说明。

一个发布说明智能体自动化这个工作流程。它收集自上次发布以来的提交和 PR，按类型分组，并生成准备好供你审查的打磨草稿。

智能体的功能

当触发时（按需或在发布前），发布智能体会：

收集提交 — 列出自上次 git 标签或发布以来的所有已合并 PR
对变更进行分类 — 根据标签和提交信息将 PR 分类为功能、修复、安全、内部、文档
编写摘要 — 将 PR 描述转换为简洁、用户友好的要点
突出显示破坏性变更 — 标记需要迁移的主要版本 bump 或 API 变更
起草 Changelog — 将发布格式化为 ## [v1.2.0] - 2025-06-22，包含所有部分
打开 PR — 将草稿提交到 CHANGELOG.md 和 docs/releases/v1.2.0.md，准备最终审查

设置

前提条件

具有活跃智能体的 AACWorkflow 工作区
具有标签发布的 Git 仓库（或 CHANGELOG.md）
已配置 GitHub 集成
PR 一致地标记（例如，type:feature、type:fix、type:security）

步骤 1：创建发布说明智能体

转到 Settings → Agents 并单击 New Agent
选择你的运行时和提供商
将其命名为 release-notes 或 changelog-bot
添加这个系统提示：

Role: Release notes curator
Task: When assigned a "Prepare Release" task:
1. Find the last git tag (e.g., v1.2.0)
2. List all merged PRs since that tag
3. For each PR:
   - Extract title and author
   - Check labels (type:feature, type:fix, type:security, type:docs, type:chore)
   - Read description for context
   - Flag if it's a breaking change
4. Categorize into sections:
   - 🎉 Features (type:feature)
   - 🐛 Bug Fixes (type:fix)
   - 🔒 Security (type:security)
   - 📚 Documentation (type:docs)
   - 🔧 Internal / Chores (type:chore) — optional, show if significant
5. Write 1-2 line summary per PR (user perspective, not technical jargon)
6. Highlight migration guide if breaking changes exist
7. Include contributor credits
8. Create branch "release/v<VERSION>" and PR with:
   - Updated CHANGELOG.md (prepend new release)
   - New file docs/releases/v<VERSION>.md (full details)
9. Add PR to AACWorkflow for team review before merge

Output format:
## [1.2.0] - 2025-06-22

### Features
- **Workspace invites** — invite team members via email link (via @anna-dev in #123)
- **Custom agent skills** — attach reusable workflows to agents (via @devops-team in #456)

### Bug Fixes
- Fixed pagination token expiry causing 401 errors (via @alice in #789)
- Corrected timestamp display in non-UTC timezones (via @bob in #890)

### Security
- **CVE-2025-1234 (High)** — Patched request validation bypass in agent API (via @security-team in #1001)

### Breaking Changes ⚠️
- **Agent API v1 deprecated** — migrate to v2 by July 1st
  See [migration guide](/docs/api/v1-to-v2.md)

### Contributors
Thanks to @anna-dev, @devops-team, @alice, @bob, @security-team, and 3 more contributors.

步骤 2：要求 PR 标签

确保你的仓库对所有 PR 强制执行标签。添加 GitHub Actions 工作流程 .github/workflows/require-pr-label.yml：

name: Require PR Label
on: pull_request
jobs:
  check-labels:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v4
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}
      - name: Verify label applied
        if: ${{ !contains(github.event.pull_request.labels.*.name, 'type:*') }}
        run: |
          echo "❌ PR must have a 'type:' label"
          exit 1

步骤 3：按需或按计划触发

按需： 转到 Settings → Releases 并单击 Prepare Release。分配给 release-notes 智能体，它唤醒并开始。

计划（例如，每月）： 在 AACWorkflow 或 GitHub 中添加 cron 任务：

# 每个月的第一个星期一上午 9 点
0 9 * * 1 [ $(date +%d) -le 7 ] && \
  curl -X POST https://aacworkflow.com/api/tasks \
    -H "Authorization: Bearer $TOKEN" \
    -d '{"agent_id": "release-notes", "title": "Prepare monthly release"}'

步骤 4：配置发布规则

添加 .aacworkflow/release-config.yml：

release_notes:
  # Git tag pattern for finding last release
  tag_pattern: "v*"
  
  # Sections to include (in order)
  sections:
    - title: "🎉 Features"
      labels: ["type:feature"]
      hide_if_empty: false
    
    - title: "🐛 Bug Fixes"
      labels: ["type:fix"]
      hide_if_empty: false
    
    - title: "🔒 Security"
      labels: ["type:security"]
      hide_if_empty: true
    
    - title: "📚 Documentation"
      labels: ["type:docs"]
      hide_if_empty: true
    
    - title: "🔧 Internal"
      labels: ["type:chore"]
      hide_if_empty: true
  
  # Breaking changes
  breaking_changes_label: "breaking-change"
  breaking_changes_section: true
  
  # Include contributor credits
  include_contributors: true
  
  # Output files
  output_files:
    - CHANGELOG.md
    - docs/releases/v{VERSION}.md

示例发布说明输出

PR title: docs: release notes for v1.2.0

Body:

## Release Summary

**v1.2.0** — June 22, 2025

📊 **Stats:** 23 PRs merged, 12 features, 8 fixes, 3 security patches, 15 contributors

---

## 🎉 Features

- **Workspace invites** — Send email invitations to teammates; they auto-join when they click. (PR #1234)
- **Custom agent skills** — Bundle reusable workflows as skills and attach to agents. (PR #1235)
- **Workspace audit log** — Track all team activity in Settings → Audit Log. (PR #1236)

## 🐛 Bug Fixes

- Fixed agent runtime not reconnecting after network drop
- Corrected issue timestamp display in non-UTC timezones
- Pagination tokens no longer expire prematurely
- Agent comments now show in correct order (newest first)

## 🔒 Security

- **CVE-2025-1234 (High)** — Patched request validation bypass in the Agent API. All users should upgrade.
- Fixed CSRF token rotation on login.

## ⚠️ Breaking Changes

**Agent API v1 is now deprecated.** Migrate to v2 by July 1st.
[See migration guide →](/docs/agents/api-migration.md)

## Contributors

Thanks to @anna-dev, @alice, @bob, @charlie, @devops-team, @security-team, and 9 more contributors for making v1.2.0 possible.

---

**Next step:** Review the release notes above. This PR updates `CHANGELOG.md` and creates `docs/releases/v1.2.0.md`.

Merge when ready, then run `git tag v1.2.0 && git push --tags` to publish the release.

提示和最佳实践

标记每个 PR。 发布说明的质量只取决于你的 PR 标签的好坏。养成标记的习惯。

标记前起草 — 在标记发布前准备发布说明，这样它们就准备好了
破坏性变更标注 — 对任何破坏性变更使用 ⚠️ 表情符号和清晰的迁移说明
用户优先的语言 — 从用户的角度而不是技术术语来写（"邀请现在自动工作"而不是"实现了异步邀请工作流"）
感谢贡献者 — 认可每个人；这建立士气和社区
链接文档 — 在发布说明中链接到相关文档、迁移指南和升级说明
在多个渠道发布 — 将发布说明复制到 GitHub Releases、Slack、Twitter、你的博客