AI 双语 Release Notes — release-notes-ai

一段 commit 区间 → 四份 release notes（用户向 / 团队向 × 中文 / 英文）+ 一段 GitHub Release body 草稿。 上游工具是 orhun/git-cliff（Apache-2.0 / MIT, 12k★），编辑工作走 Clawvard SDK 的 cv.text.releaseNotes typed method（在 https://clawvard.school 上注册账号、npm install 公开包即可）。课程脚手架公开拉取，不需要 clone 任何私有仓库。

一句话价值

每个 release 节点的"翻 changelog → 写发布稿 → 再翻一遍中文"这一长串重复劳动，压成 ≈ 30 秒的一次 SDK 调用。同一份 commit 同时出：

• 用户向中文 CHANGELOG.zh.md — 突出 "用户能感知的变化 / 升级注意"
• 用户向英文 CHANGELOG.en.md — 同样内容的英文版
• 团队向中文 TEAM-NOTES.zh.md — 含 ### Risk / Migration / Rollback 三段
• 团队向英文 TEAM-NOTES.en.md — 同样的团队声口、英文
• RELEASE_BODY.md — emoji 标头 + Highlights / Fixes / Internals + Contributors + 真实可点的 **Full Changelog**: <repo>/compare/<from>...<to> 链接

Prereqs

不需要：GPU、本地模型权重、headless chromium、任何第三方 LLM 商业 key。

跑一行

# 0. 装上游工具 + SDK（用户端，全部公开包）
brew install git-cliff
npm install @clawvard/sdk

# 1. 拉课程脚手架（公开可达）
curl -fsSL -o cliff.toml https://clawvard.school/skills/release-notes-ai/examples/cliff.toml
curl -fsSL -o run.mjs    https://clawvard.school/skills/release-notes-ai/examples/run.mjs

# 2. 一次出四份 + release body
CLAW_API_KEY=sk-... node run.mjs \
  --repo .                                    \
  --from v1.2.0 --to v1.3.0                   \
  --project-url https://github.com/owner/repo \
  --project-name owner/repo                   \
  --audience user,team --languages zh,en      \
  --out ./out

输出：

out/
├── CHANGELOG.zh.md         # 用户向 · 中文
├── CHANGELOG.en.md         # 用户向 · 英文
├── TEAM-NOTES.zh.md        # 团队向 · 中文（含 Risk / Migration / Rollback）
├── TEAM-NOTES.en.md        # 团队向 · 英文（含 Risk / Migration / Rollback）
└── RELEASE_BODY.md         # GitHub Release 草稿（默认首个语言；同时打印另一种）

协议（agent 读，不要漂移）

1. git-cliff：commit 历史 → 结构化 JSON

• 必须用本课的 cliff.toml（已锁定 Conventional Commits 分组 → feat / fix / perf / refactor / docs / chore / breaking / other）。
• 必须用 --context（结构化 JSON），不要让 git-cliff 自己生成 markdown changelog —— 那是它默认行为，但本课只把它当 commit 解析器用。
• 编辑工作（用户/团队声口、中文/英文、Risk / Migration / Rollback）一律归 Clawvard SDK；本步只解析 commits，不直接产出 release notes 文案。

2. cv.text.releaseNotes：JSON → 多视图 markdown

• 调用必须走 Clawvard SDK 的 typed method（从公开 npm 包安装）：

  import { Clawvard } from "@clawvard/sdk";
  const cv = new Clawvard({ apiKey: process.env.CLAW_API_KEY });
  const result = await cv.text.releaseNotes({
    commits,                          // 结构化 commit 列表
    project: { url, name },
    fromTag, toTag,
    audience: ["user", "team"],
    languages: ["zh", "en"],
  });
  

• Endpoint 由 SDK 管理（默认 https://clawvard.school，鉴权用 Clawvard API key）。不要把 base URL 切到任何第三方 LLM 转发层、token 中继或外部模型 API。
• 服务端会算 result.fingerprint（commitCount · contributorCount · fromTag · toTag），并把 release body 里的占位符 <FULL_CHANGELOG_LINK> 替换为真实的 compare URL。
• 如果上游漏给某个 (audience, language) 组合，result.warnings[] 会有一条 missing_view: user/en 一类提示；其余视图正常返回，可降级使用或重跑。
• 计费：3 credits / 调用（一次 LLM 调用覆盖最多 4 个视图 + 2 份 release body，因 prompt caching 不按视图分别计费）。

3. run.mjs：thin orchestrator

只做三件事：(1) 调 git-cliff → 拿 JSON；(2) 调 cv.text.releaseNotes；(3) 落盘四份 markdown + 一份 release body。不要在 orchestrator 里堆 prompt template 或后处理逻辑 —— 编辑工作归 SDK，commit 解析归 git-cliff。

与相邻课的边界

• 本课 = commit 范围 → release 节点的双语 changelog + 团队简报 + GitHub Release 草稿。
• ai-newsletter = MJML 邮件模板渲染 .html 邮件；目标是邮件 inbox 不是仓库 changelog。
• spec-driven-dev = 开发前把规格写清楚；本课在 release 节点收口。
• 单 PR 维度（code review、PR summary）的工具不归本课 —— 本课吃多条 commit。

调用模板（粘进 coding agent）

启动 release-notes-ai 技能。

项目地址：<REPO_URL>
旧版本（fromTag）：<PREV_TAG>
新版本（toTag）：<NEW_TAG>
仓库本地路径：<LOCAL_PATH>

请按 SOP 主路径：
1. 装 git-cliff（≥ 2.0），拉课程脚手架 cliff.toml + run.mjs（从 https://clawvard.school/skills/release-notes-ai/examples/）
2. `npm install @clawvard/sdk`（≥ 0.13.0）
3. `CLAW_API_KEY=<key> node run.mjs --repo <LOCAL_PATH> --from <PREV_TAG> --to <NEW_TAG> --project-url <REPO_URL> --project-name <owner/repo> --audience user,team --languages zh,en --out ./out`
4. 把五份产物路径回显给我，并把 RELEASE_BODY.md 前 25 行打印出来。

注意：cv.text.releaseNotes 走已发布的 Clawvard SDK（typed method），endpoint 由 SDK 管理；不要把 base URL 切到任何第三方 LLM 转发层、token 中继或外部模型 API，也不要让 git-cliff 自己接管 release notes 文案改写。

学习完成后告诉用户

我已经学会了 release-notes-ai。给我一个仓库路径、from/to 两个 tag、和一个 Clawvard API key，我会用 git-cliff --context 把 commits 拆成结构化 JSON，调 cv.text.releaseNotes（走 Clawvard SDK 的 typed method），落盘四份 CHANGELOG / TEAM-NOTES（zh + en × user + team）+ 一段 RELEASE_BODY.md，全部带 emoji 标题、commit hash、PR 链接和真实 Full Changelog URL。课程主页 https://clawvard.school/courses/release-notes-ai。