Hindsight 核心版本发布完全指南：从 release.sh 切割、Changelog 生成到博客 PR 的完整工作流

Hindsight 核心版本发布完全指南从 release.sh 切割、Changelog 生成到博客 PR 的完整工作流【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsightAgent Memory That Learns仓库中封装了一套面向 AI 助手的核心版本发布技能位于 .claude/skills/hs-release/SKILL.md它定义了一次core release的完整操作流程在干净的main上执行scripts/release.sh切割版本并直推main触发 CI 发布随后以独立 PR 补上 Changelog 与发布博客。本文以该技能文档为主体结合仓库中 scripts/release.sh、scripts/generate-clients.sh、scripts/generate-docs-skill.sh 及 hindsight-dev/hindsight_dev/generate_changelog.py 的源码实现还原每一步背后的脚本逻辑与工程细节让读者不仅能照做更能理解为什么这样做。先厘清什么是“核心发布”什么不是在进入流程前技能文档首先划定了发布边界——核心core发布只针对产品本体APIhindsight-api系列、各语言客户端Python / TypeScript / Go / Rust、CLIhindsight-cli、控制平面hindsight-control-plane以及 Helm Chart。集成integrations是独立版本化的。仓库中hindsight-integrations/下每一个集成如litellm、pydantic-ai、claude-code、openai-agents等都有自己的版本号和发布通道必须使用 scripts/release-integration.sh 单独发布而不是本技能。从源码看集成发布的 tag 命名也完全不同核心发布打vversion如v0.9.0而集成发布打integrations/integration/vversion如integrations/litellm/v0.2.0且集成脚本内置了约 50 个合法集成名的白名单校验VALID_INTEGRATIONS数组见 scripts/release-integration.sh未知集成名会直接拒绝执行。另一个必须提前建立的认知是核心发布不可逆、且面向外部。release.sh会打 tag 并直接推送main推送动作触发ReleaseGitHub Actions 工作流进而把包发布到 PyPI / npm / Helm。这意味着发布前必须确认两件事版本号正确无误计划包含的修复已经合并进main。Step 0 — 发布前预检Pre-flight1. 决定发布基准base发布永远从最新的origin/main切割绝不允许从功能分支发布。预检命令如下git fetch origin --tags git log vprev..origin/main --oneline第一条同步远端 tag第二条用来确认用户口中那几个修复确实已经落在main上vprev是上一个发布 tag。只有确认修复已合入才能继续。2. 找到main所在的工作树由于 git 的限制main往往已经以兄弟 worktree的形式被检出用git worktree list查看。你不能在第二个 worktree 中再次检出main——必须在已经持有它的那个 worktree 里执行发布。如果那个 worktree 里残留了临时杂物比如.next-*的 tsconfig 路径、截图等先暂存再快进git stash push -u git pull --ff-only origin main # 或 git merge --ff-only origin/main # ……执行发布…… git stash pop3. 一个著名坑不要用管道链做 checkout技能文档明确警告永远不要把 checkout 塞进链并用| tail管道例如git checkout main 21 | tail git reset --hard ...问题在于管道的退出码是tail的恒为 0。当 checkout 失败时链不会被中断随后的reset --hard会在错误的分支上执行——这是灾难性的。正确做法是checkout 单独成命令并且在 reset 之前用git branch --show-current确认当前分支确实是main。Step 1 — 切割发布release.sh做了什么在干净clean的mainworktree 中执行./scripts/release.sh version # 例如 ./scripts/release.sh 0.8.1不要带前导 v阅读 scripts/release.sh 源码可以看到脚本从入口就建立了四道防线版本格式校验VERSION必须匹配^[0-9]\.[0-9]\.[0-9]$语义化版本见 scripts/release.sh分支检查git branch --show-current非main时交互式确认scripts/release.sh工作区清洁检查git status -s有输出则直接报错退出scripts/release.shtag 冲突检查git rev-parse v$VERSION已存在则拒绝发布scripts/release.sh。通过四道检查后脚本依次完成以下动作1为所有组件统一 bump 版本。Python 包列表为hindsight-api、hindsight-api-slim、hindsight-all-slim、hindsight-dev、hindsight-all、hindsight-embedscripts/release.sh逐一改写pyproject.toml的version字段。此外还更新三处 Python__init__.py中的__version__含hindsight-api-slim/hindsight_api/__init__.py、hindsight-embed/hindsight_embed/__init__.py、hindsight-clients/python/hindsight_client_api/__init__.py以及 Rust CLI 的hindsight-cli/Cargo.toml、Helm Chart 的 helm/hindsight/Chart.yaml同时更新version与appVersion、控制平面的hindsight-control-plane/package.json、npm 包装包hindsight-all-npm/package.json、Python 与 TypeScript 客户端清单。2re-pin 元包依赖。hindsight-api、hindsight-all、hindsight-all-slim是纯 shim 元包必须精确锁定对应的 slim/api 版本$VERSION否则pip install -U会留下旧版 slim导致服务端上报过期的__version__。同理hindsight-all还捆绑嵌入式 daemon会同步把hindsight-embed锁到本版本hindsight-dev则锁hindsight-apiscripts/release.sh。3刷新根package-lock.json。通过npm install --ignore-scripts --no-audit --no-fund让 workspace 版本与 bump 后的package.json一致。源码注释解释了原因若不刷新CI 里的npm ci会因 Missing vectorize-io/hindsight-client from lock file 失败连带 npm-publish 与 docs-deploy 两个 job 一起挂掉 scripts/release.sh。4更新文档版本。调用 scripts/update-docs-version.sh其行为由 patch 号决定patch 发布如 0.8.1把hindsight-docs/docs/用rsync -av --delete同步到已有的versioned_docs/version-0.8/并用 Node 把sidebars.ts编译成versioned_sidebars/version-0.8-sidebars.jsonminor/major 发布如 0.9.0执行npx docusaurus docs:version 0.9创建全新的version-0.9快照并更新versions.json。5重新生成 OpenAPI spec 与全部客户端 SDK。先由 scripts/generate-openapi.sh 执行uv run generate-openapi来自hindsight-dev的命令并npm run build构建文档站点再由 scripts/generate-clients.sh 生成四种客户端Rust客户端在构建时由build.rs基于 progenitor自动生成脚本通过cargo build --release --locked触发再生成--locked保证依赖解析可复现Python用 Docker 固定版本openapitools/openapi-generator-cli:v7.10.0--platform linux/amd64保证 macOS 与 Linux CI 输出一致并 patchrest.py把 aiohttp 初始化延迟到首次请求规避 no running event loop 错误TypeScript用hey-api/openapi-tsnpm run generate版本锁在package.json再 patchclient.gen.ts以兼容 Denoclient字段在 Deno 的RequestInit中是保留字Go同样走 Docker openapi-generator但保留手写的hindsight_client.go、go.mod/go.sum等维护文件并修复生成器的两个已知问题union 类型MarshalJSON改为值接收者、api_files.go补充缺失的os导入。若客户端再生成失败脚本会交互询问是否继续选择取消则git checkout .回滚所有改动scripts/release.sh。6提交、打 tag、推送。最后脚本git add -A用--no-verify提交信息为Release vversion含组件清单与文档同步说明创建 annotated tagvversion然后直接git push origin main与git push origin vversionscripts/release.sh。再次强调这一步不是 PR推送即触发 CI 构建发布制品。发布后验证推送完成后立即验证两条gh run list --limit 5 # 应能看到 Release vversion 工作流正在运行 git ls-remote --tags origin vversion # 应能返回该 tagStep 2 — Changelog 博客 PR独立进行这一步必须在 tag 已存在之后执行并且是独立的 PR仓库先例v0.8.0 PR #2053v0.8.1 PR #2080。从新main拉分支git checkout -b docs-changelog-version origin/main只有当main被其他 worktree 占用、当前工作区又有不想打扰的改动时才考虑单独 worktreegit worktree add ../hindsight-changelog-version -b docs-changelog-version origin/main分支命名为什么必须用docs-分支名必须采用docs-连字符约定例如docs-changelog-0.8.1。原因很具体远端已存在一个字面名为docs的分支任何docs/...形式的分支在 push 时都会被 git 以directory file conflict拒绝。这是本仓库最容易踩的命名坑。生成 Changeloguv run --directory hindsight-dev generate-changelog version该命令实现见 hindsight-dev/hindsight_dev/generate_changelog.py会拉取上一个 tag 到vversion之间的全部 commit调用 LLM 总结并把新条目prepend到 hindsight-docs/src/pages/changelog/index.md在条目末尾追加Database Migrations小节。关于 Database Migrations 小节有几点值得注意它由 git 确定性枚举对hindsight_api/alembic/versions/做--diff-filterA找出新增迁移文件不是 LLM 生成的因此不要手工编辑如果发现某个迁移缺失应去检查对应 commit 是否真的在 tag 区间内新增了该文件hindsight-dev/hindsight_dev/generate_changelog.py源码中甚至维护了一张TABLE_VOLUME分级表把memory_units、memory_links、entities等表按高/中/低数据量标注用于提示迁移锁范围与耗时hindsight-dev/hindsight_dev/generate_changelog.py并有测试保证新建表必须被分类运行需要OPENAI_API_KEY仓库.env中已就绪生成范围排除hindsight-integrations/源码但新集成的 commit 若顺带改了文档仍会出现——这符合既有先例保留在 changelog 中即可。手写发布博客在 hindsight-docs/blog/ 下手写YYYY-MM-DD-version-X-Y-Z.md可以镜像已有博客的格式patch 发布通常很短可参考 hindsight-docs/blog/2026-06-02-version-0-7-2.md大版本可参考 hindsight-docs/blog/2026-08-06-hindsight-0-9-0.md。写作规范有三条硬性要求讲用户影响不讲内部机制开头就要说明用户现在能做什么、要配置什么。配置项与环境变量名可以出现面向开发者但代码符号与内部实现不要写博客中不要列集成核心博客只覆盖核心引擎 / API / 运维变化每个集成有自己的 changelog。集成出现在生成的changelog/index.md中没问题只是不要进博客正文。有运维或数据完整性修复时明确给出升级建议。格式校验npx prettier --check blog file同步 docs skill./scripts/generate-docs-skill.sh该脚本scripts/generate-docs-skill.sh把hindsight-docs/docs、src/pages含 best-practices、faq、changelog与docs-integrations转换为 AI Agent 可消费的 skills/hindsight-docs/ 技能目录.mdx转.md、内联示例代码、把LLMProvidersTable /等 JSX 组件渲染为 Markdown 表格、并把 Docusaurus 绝对路径链接重写为相对路径、最后做链接越界校验。运行后会刷新 skills/hindsight-docs/references/changelog/index.md同时把 skills/hindsight-docs/references/openapi.json 的版本号 1。背景是release.sh在OpenAPI bump 之前就再生成了 skill所以发布 commit 里 skill 的openapi.json会滞后一个版本这一步正是为了把它同步回来——预期会有一行version的 diff保留它。提交、推送、建 PRgit add -A git commit --no-verify -m docs: changelog and blog post for vversion git push -u origin docs-changelog-version gh pr create --base main --title docs: changelog and blog post for vversion --body ...PR 中应包含四类文件changelog 新条目hindsight-docs/src/pages/changelog/index.md新增的博客文件再生成的 skill changelog 镜像skillopenapi.json的版本同步 diff。收尾Cleanup如果 Step 2 中创建了临时 worktreePR 建立后应移除分支保留在 origin 上git worktree remove ../hindsight-changelog-version同时恢复 Step 0 中 pop 出来的 stash。附发布核对清单一次完整的核心发布按技能文档归纳为以下顺序供 AI 助手与维护者自查git fetch origin --tags确认目标修复已在maingit log vprev..origin/main --oneline定位持有main的 worktreegit worktree list脏文件先git stash push -ucheckout 单独成命令git branch --show-current确认在main执行./scripts/release.sh versionsemver 格式不带vgh run list --limit 5看到Release vversion在跑git ls-remote --tags origin vversion返回 tag从新main建docs-changelog-version分支勿用docs/...命名uv run --directory hindsight-dev generate-changelog version勿手改 Database Migrations 小节手写发布博客并按npx prettier --check校验./scripts/generate-docs-skill.sh同步 skill保留 openapi.json 的一行版本 diff提交--no-verify→ push →gh pr createPR 含 changelog、博客、skill 镜像三部分清理临时 worktree、恢复 stash这套流程的精髓在于切割与文档分离release.sh负责把所有机械性工作版本 bump、SDK 再生成、tag、推送一次性原子完成而 changelog 与博客走独立 PR让发布文档可以在 tag 落定后从容补写、接受 review。对任何需要维护多语言 SDK Helm Chart 文档站点的开源项目来说这个一步切割 一步文档的双阶段模式都值得直接借鉴。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考