herdr 预发布审计全指南：从提交历史到可发布状态的完整检查流程

herdr 预发布审计全指南：从提交历史到可发布状态的完整检查流程

【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr

herdr 是一套面向 AI 编码 Agent 的终端运行时。在其仓库.agents/skills/herdr-pre-release-audit/references/pre-release-audit.md中定义了一套可执行、可复用的预发布审计流程：通过对比自上一个版本标签以来的提交历史、合并 PR 与docs/next暂存文档，判定"本仓库是否已具备发布条件"。本篇文章以该审计参考文档为主体，结合仓库内的 justfile、scripts/changelog.py、docs/versions/manifest.json 与 nix/package.nix 等实现细节，完整讲解审计的 9 个步骤、判定输出格式，以及发布操作者需要遵守的最终化规则。读完你既能独立执行一次 herdr 的预发布审计，也能把这套"变更盘点 → 双份文档核对 → 门禁检查 → 格式化报告"的流程复用到其他以文档为发布物的开源项目上。

这套审计流程要解决什么问题

发布一个以"长生命周期运行"为核心体验的终端工具，真正的风险往往不在编译器，而在"变更没有被正确讲述"：

• 用户可见的新功能、修复、破坏性变更没有进入下个版本的 changelog；
• docs/next下已暂存的下一版文档与已发布的稳定文档之间出现漂移；
• 合并 PR 引用了 issue，但 release CI 发布后会自动关闭它们，而 changelog 里没有对应的条目；
• 面向 Agent 的内置技能文件与实际 CLI 行为不再一致，误导模型去调用错误的命令。

本审计的目标是：在运行just release之前，把以上每一项都变成可核对、可回答的问题，并产出一份一眼可读的发布就绪报告（Release readiness report）。它通过技能入口.agents/skills/herdr-pre-release-audit/SKILL.md被调用，真正的工作流定义在其引用的 pre-release-audit.md 中，SKILL.md 明确定义该参考文件是"source of truth"，并限定它只用于 herdr 仓库内部。

仓库文档分层的关键前提

审计的第一步不是看代码，而是先理解本仓库独特的三层文档体系。只有分清每一层的角色，才能知道该把变更"对"到哪里：

• 根CHANGELOG.md：最新已发布版本的 changelog。
• docs/next/CHANGELOG.md：人工撰写的下一版 changelog 草稿，是发布准备阶段唯一负责完整更新 changelog 的文件。常态功能开发不维护该文件，这样长生命的 PR 不会在同一个共享文件上互相冲突——整个 changelog 的归并只发生在稳定发布准备期间。
• docs/next/README.md与docs/next/website/src/content/docs/：未发布的下一版根 README 与完整网站文档草稿。发布 CI 会在发布后把带标签的 README 提升为正式版本。
• docs/preview/website/：由机器人维护的活动预览发布输出，审计过程中绝不编辑，也不作为稳定发布来源。
• docs/versions/manifest.json：记录当前稳定版本与来源。以本仓库现状为例，current为0.8.2，其文档来源正是docs/next/website/src/content/docs——这是发布流程把docs/next提升为稳定文档的直接证据。

第一步：确定审计基线（base ref）

审计范围是一个提交区间<base>..HEAD，所以先要确定 base：

• 如果显式传入$1且看起来像 ref 或 tag，直接使用它；
• 否则使用仓库语义版本标签风格下的最新发布标签：

git describe --tags --abbrev=0

在 herdr 的实际工作流里，标签形如v0.8.2（见 docs/versions/manifest.json 中的"tag": "v0.8.2"）。确定 base 后，所有后续的提交盘点、文档核对都以该区间为准。

第二步与第三步：盘点区间内的一手历史与合并 PR

审计不能依赖"凭印象回忆这个版本改了什么"，必须从 Git 历史重建权威清单。

先用 first-parent 历史还原发布主线（合并与 squash 提交的主干，能反映每个 PR 的合入顺序）：

git log --first-parent --reverse --format='%H%x09%s' <base>..HEAD

需要提交正文等细节时再展开完整提交：

git log --reverse --format='%H%x09%s%n%b' <base>..HEAD

检测合并 PR 的规则非常具体：

• 观察 first-parent subject 中表示 PR 合并的模式，尤其是形如title (#123)的 squash 合并；
• 若 GitHub CLI 可用且知道 PR 号，可拉取 PR 标题与正文补充上下文；
• 把一个合并 PR 视为发布的主要单元，不要再单独列出属于该 PR 的各个 commit（避免 changelog 里重复记账）。

区间内不属于任何合并 PR 的提交，则作为"直接提交"单独处理。

第四步与第五步：直接提交与重要性推断

直接提交各自独立评估。判断每个 PR 或直接提交是否"重要"的方法是：

• 查看其变更文件与 diff 统计；
• 需要理解用户可感知的影响时，完整阅读最相关的文件；
• 忽略纯 housekeeping（除非有发布价值）：版本号提升、release/tag 提交、纯 changelog 提交、仅格式调整、纯注释/文档变更（除非实质性影响用户）。

例如 docs/next/CHANGELOG.md 的Unreleased段里，#837, thanks @aneym（自定义主题明暗色覆盖）属于用户可见的新功能，而这类记录必须来自对 PR 内容的产品级判断，而非简单复制 subject。

第六步：构建发布 changelog 清单并核对 docs/next/CHANGELOG.md

这是整个审计最重的一步，可拆解为：

1. 建立完整 inventory。盘点区间内每一个合并 PR 与直接提交，材料来源包括：conventional commit subject、commit body、变更文件、关联 issue、PR body、贡献者身份。生成的提交列表只是"覆盖辅助手段"，不是最终发布文案。

2. 对每个发布单元归类，四类之一：用户可见且应进 changelog / 内部维护性 / 仅文档 / 需要决策。不确定的条目不得静默省略。

3. 逐条对照。把 inventory 中每个有意义的用户可见项与 docs/next/CHANGELOG.md 比对，标记缺失的条目，覆盖范围包括：

• 新功能、bug 修复、移除项、破坏性变更、默认值变化、兼容性变更；
• 用户可见的命令/配置/API 行为变化；
• 安全相关变更。

4. 文案质量要求。最终条目必须是"产品高度"的人工文案，描述用户获得什么或不再经历什么，而非抄 commit subject 或实现细节。同时有两个显式豁免：内部 client/server 协议版本号提升不需要changelog 条目（除非本次发布有意改变超出常规重启要求的用户兼容性指引）；不要为 changelog 条目添加fixes #n/closes #n/resolves #n这类 GitHub 关闭关键字。

5. 核对 issue 引用与致谢格式。检查 commit body 中的refs #<issue-number>行；对正常提交里使用fixes/closes/resolves #<issue>关键字的，要单独标记——因为它们合入master时会在发布前就关闭 issue。对每条随发布关闭的 issue，确认 changelog 有对应的用户可见条目并在合适位置提及#<issue-number>。对外部人工 PR：条目需提及 PR 号并按既有风格致谢，例如(#129, thanks @username)；若该 PR 主要交付某个 issue 修复，可同时给出 issue 与 PR 号，如(#128, #129, thanks @username)。维护者拥有的机器人或自动化账号（如kangal-bot、dependabot）不加致谢文字。

6. 输出关闭清单。将随发布关闭的 issue 引用列在Issue references to close after release:下，供发布操作者在 GitHub Release 发布后核实 release CI 将关闭哪些 issue。

7. 兜底检查。标记区间内不存在对应已合入变更的 stale 条目；标记过于实现导向、对最终用户含糊不清的条目。同时保持 changelog 既有章节结构与风格：Added、Changed、Fixed、Removed、必要时Breaking Changes——docs/next/CHANGELOG.md 的Unreleased段就是按### Added/### Fixed组织的活样本。

第七步：审计下一版公开文档

对照顺序是"先对下一版草稿，再横向比较"。

已发布文档的认定：根 README.md 与 docs/versions/manifest.json 选中的版本目录（本仓库当前为 docs/versions/0.8.2/）视为最新已发布文档；发布后的版本文档允许包含发布标签之后的事实性修正，因此审计以草稿对比为核心。

下一版文档草稿：docs/next/README.md为下一版根 README；docs/next/website/src/content/docs/为完整未发布网站文档草稿。把区间内有意义的用户可见变更先与草稿对比，标记下列缺失：

• 新功能或变更功能缺发布文档；
• 命令、配置键、协议行为、集成、默认值、兼容性说明缺文档。

本地化一致性：英文草稿必须与 docs/next/website/src/content/docs/ja/ 和 docs/next/website/src/content/docs/zh-cn/ 对比，标记缺失的本地化文件、陈旧（英文侧已删除但译文仍在）的本地化文件，以及标题大纲漂移（译文没有与英文相同的章节结构）。仓库脚本 scripts/docs_translation_parity.py 正是这套检查的实现：它遍历英文.mdx，逐一校验每个 locale 是否存在同名文件，并对每个英文文档提取纯标题层级（自动跳过代码围栏中的#），比对译文大纲是否与英文完全一致。

README 与草稿逐项判定：比较docs/next/README.md与网站草稿对稳定文档的差异，将每一项判定为"预期随发布（intended to ship）""陈旧（stale）"或"需要用户决策"。发布前不要求草稿树与稳定树完全一致。

配置示例片段同样纳入审计范围。

Agent 技能审计：将 skills/herdr/SKILL.md 与随本版本合入的 CLI、公开 ID、pane/agent 工作流、生命周期语义与安全指引变更比对，标记过时的命令、选项、示例或行为断言。该文件会被随二进制一起打包（见 nix/package.nix 中../skills/herdr/SKILL.md被纳入构建源文件集），因此审计关注"语义新鲜度"而非文件同步状态。

第八步：验证最终化状态（release 前的门禁）

发布准备阶段的机械性验证集中在 justfile 中定义的任务链上，审计文档要求发布操作者按次序确认：

1. 文档最终化位置。在运行just release之前，获批的 README 变更必须最终化到 docs/next/README.md；release CI 会在发布后提升那个带标签的文件。不要把草稿网站文档复制到website/src/content/docs/或docs/preview/。

2. Nix 打包集成。nix/package.nix 通过cargoLock.lockFile = ../Cargo.lock引用 Cargo.lock，常规版本号与 lockfile 更新不需要单独刷新 cargo hash；但一旦引入 git 依赖，必须验证所需的cargoLock.outputHashes条目已补齐。

3. 运行整合检查。推荐执行：

just pre-release-check

它由三层组成（对应 justfile 中的三个任务）：

• just release-docs-check：校验暂存草稿、本地化标题一致性、已发布 preview 与 stable 快照来源，并同时构建生产与草稿两个网站；
• just bench-render-scale：渲染规模基准（release 模式的render_scale_profile忽略测试）；
• just bench-release-smoke：端到端 CPU 对比冒烟。

4. 渲染基准的人工研判。渲染基准没有自动时间阈值，但审阅它是必需的发布检查点：记录 1/15/50 三种 pane 数量下"后台 workspace 调整大小/布局"与"活跃 pane"两个场景的 median 与 p95 结果，比较它们的扩展比；跨机器的绝对耗时不能作为依据，只有当扩展比出现实质性劣化时，才应视为阻塞发布的问题并先调查再发布。

5. 三重就绪条件。工作树干净、文档检查通过、渲染扩展比结果已审阅——三者齐备才运行just release。

第九步：审计只读，变更需显式授权

审计本身不编辑任何文件，除非用户明确要求应用修复。若被要求修复：

• 发布准备是唯一写 docs/next/CHANGELOG.md 的常规工作流——必须从完整 inventory 人工撰写获批的 changelog 条目；
• 更新docs/next/README.md及docs/next/website/src/content/docs/下任何需要调整的暂存网站文档；
• 被要求最终化发布文档时，只最终化docs/next/下的暂存文件，然后运行just release-docs-check；
• preview 与 stable 的发布归 CI 所有，本地不参与写入。

输出格式：一份可扫描的发布就绪报告

审计的最终产物是一份固定格式的 Markdown 报告。核心输出必须保持"一眼可读"，提交清单、被排除的 housekeeping 以及执行过的命令仅在确实有助于操作者时放入附录。

参考文档给出了完整模板，结构如下：

Release readiness: READY | NOT READY Base: <base ref> Range: <base ref>..HEAD Meaningful shipped changes: yes | no Changelog: OK | MISSING ENTRIES | NEEDS ATTENTION Missing: - <only user-facing shipped changes missing from docs/next/CHANGELOG.md> Docs: OK | MISSING | INACCURATE | NEEDS DECISION Missing: - <only required next-release public docs gaps> Wrong or questionable: - <docs that disagree with implementation, if any> Issue refs: OK | NEEDS ATTENTION Will close after release: - #<issue> Accepted/no action: - <items the user explicitly accepted, such as known closing-keyword commits> Root docs finalized: YES | NO <result of just release-docs-check or why it was not run> Agent skill: UP TO DATE | NEEDS UPDATE | NOT CHECKED <whether skills/herdr/SKILL.md matches the shipped CLI and agent-control behavior> Nix Cargo lock integration: OK | NEEDS ATTENTION | NOT CHECKED <result of nix flake check or any required cargoLock.outputHashes status> Render scaling: OK | NEEDS ATTENTION | NOT CHECKED <1, 15, and 50-count median/p95 results and ratios for background-workspace resize/layout and active panes> Required before release: 1. <short action>

这套模板的每一行都对应前文的一个审计维度：Meaningful shipped changes: no时直接说明"区间内没有有意义的用户可见变更"，不要强行制造条目——这是审计纪律的一部分，避免为发布而虚构 changelog 内容。

把流程固化为可执行技能

整个审计流程被封装进.agents/skills/herdr-pre-release-audit/SKILL.md，使发布操作者（或具备该技能的 Agent）可以反复以一致的方式执行：选择 base ref、走 first-parent 历史与 PR 合并分析、审计 changelog 与草稿文档、核对 issue 引用行、决定何时运行just pre-release-check及其子检查、运行与评估just bench-render-scale、最终产出标准格式的就绪报告。

从工程实践角度，这套设计的可借鉴之处在于把"发布质量"从人的记忆变成了可重复的流程：单一 changelog 所有权避免多 PR 冲突，三级文档（stable / next / preview）把"最终化"与"草稿"的职责彻底分离，read-only 审计与显式 apply 授权防止自动工具在审查中途污染发布状态。对任何维护公开文档的长期项目而言，这套"先盘点再对照、无事实不落笔"的审计方法都值得直接迁移。

【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr