hs-release

Hindsight 发布

发布一个 core Hindsight 版本，并打开随附的 changelog/blog PR。这针对的是 core 产品版本（API、客户端、命令行、控制平面、Helm）。集成是独立进行版本管理的——请使用 scripts/release-integration.sh 处理这些，而不是本 skill。

发布是不可逆且面向外部的：它会为一个版本打上标签并直接推送到 main，这会触发 CI，将软件包发布到 PyPI / npm / Helm。在开始之前，请确认版本号 以及预期的修复已经合并到 main。

步骤 0 — 预检

1. 确定基线。 发布总是从最新的 origin/main 切出，绝不从功能 分支。先执行 git fetch origin --tags。确认用户所说的“几个修复” 确实已经合并到 main（git log v<prev>..origin/main --oneline）。
2. 找到 main 被检出的位置。 main 通常已经在某个同级 worktree 中被检出 （git worktree list）。你不能在第二个 worktree 中检出 main——请在 已经持有它的 worktree 中运行发布。如果那个 worktree 被一次性杂物弄脏了 （.next-* tsconfig 路径、截图），执行 git stash push -u，快进到 origin/main， 运行发布，然后执行 git stash pop。
3. 陷阱： 绝不要像 git checkout main 2>&1 | tail && git reset --hard ... 这样把检出的命令放进 && 链中——管道的退出状态是 tail 的 （始终为 0），所以失败的检出不会停止链条，reset 会在错误 分支上触发。请将检出作为单独命令执行，并在重置前验证 git branch --show-current。

步骤 1 — 切出发布

在干净的 main 上，从该 worktree 运行：

./scripts/release.sh <version>     # e.g. 0.8.1  (no leading v)

release.sh 会提升每个组件中的版本，重新生成 OpenAPI spec + 所有客户端 SDK， 更新文档版本，提交 Release v<version>，打标签 v<version>，并将提交 和标签直接推送到 main。该推送会触发 Release GitHub Actions 工作流，构建 并发布软件包。这不是 PR。

之后验证：gh run list --limit 5 应显示 Release v<version> 工作流正在运行，并且 git ls-remote --tags origin v<version> 应返回该标签。

步骤 2 — Changelog + blog PR（单独进行）

在标签存在之后完成，作为其自己的 PR（先例：v0.8.0 = #2053，v0.8.1 = #2080）。在新的 main 上 开一个分支进行工作：

git checkout -b docs-changelog-<version> origin/main

只有在否则无法获得干净检出时才单独开一个 worktree（git worktree add ../hindsight-changelog-<version> -b docs-changelog-<version> origin/main）——例如 main 被另一个 worktree 持有，而当前 worktree 有你不希望打扰的工作。

分支命名： 使用 docs-（连字符）约定，例如 docs-changelog-0.8.1。一个字面名为 docs 的远程 分支存在，因此任何 docs/... 分支都会在推送时因 directory file conflict 被拒绝。

Changelog

uv run --directory hindsight-dev generate-changelog <version>

LLM 会总结上一个标签与 v<version> 之间的提交，并在 hindsight-docs/src/pages/changelog/index.md 前部添加一个条目。

该条目以 Database Migrations 部分结尾，列出该范围内添加的每一个 Alembic migration， 每个都链接到引入它的 PR。该部分是从 git 确定性地枚举出来的（对 hindsight_api/alembic/versions/ 使用 --diff-filter=A），不是由 LLM 生成——不要手工编辑它， 如果缺少某个 migration，请检查其提交是否确实在标签范围内添加了该文件。需要 OPENAI_API_KEY（已在仓库 .env 中）。它排除 hindsight-integrations/ 源码，但其提交也 触及文档的新集成仍会出现——这与先例一致，将它们保留在 changelog 中。

博客文章

手写 hindsight-docs/blog/YYYY-MM-DD-version-X-Y-Z.md（参照现有的文章；补丁版本发布内容较短 — 参见 2026-06-02-version-0-7-2.md）。指引：

• 说明对用户的影响，而非内部实现/机制。 首先讲用户现在能做什么、需要设置什么。 配置/环境变量名称可以出现（面向开发者），代码符号和内部实现则不可以。
• 不要在发布博客中列出集成。 核心博客只涵盖核心引擎 / API / 运维变更；每个集成都有自己的更新日志。（集成仍可能出现在生成的 changelog/index.md 中 — 这没问题；只是不要把它们写进博客。）
• 当存在运维/数据完整性修复时，请明确给出升级建议。
• 校验格式：npx prettier --check <blog file>。

同步 docs skill

./scripts/generate-docs-skill.sh

刷新 skills/hindsight-docs/references/changelog/index.md。它还会将 skills/hindsight-docs/references/openapi.json 提升一个版本 — release.sh 在提升 OpenAPI 版本之前重新生成 skill，因此 skill 副本在发布提交中会滞后一个版本；这一步会将其同步。 预期那里会出现一行 version 差异；请保留它。

提交、推送、PR

git add -A
git commit --no-verify -m "docs: changelog and blog post for v<version>"
git push -u origin docs-changelog-<version>
gh pr create --base main --title "docs: changelog and blog post for v<version>" --body "..."

PR 中预期的文件：更新日志条目、新的博客文章、重新生成的 skill 更新日志镜像，以及 skill openapi.json 版本同步。

清理

如果你创建了临时工作树，请在 PR 提交后将其移除 （git worktree remove ../hindsight-changelog-<version>；分支仍保留在 origin 上）。恢复你在第 0 步中弹出的任何 stash。