herdr 预发布审计全指南从提交历史到可发布状态的完整检查流程【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdrherdr 是一套面向 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 的预发布审计也能把这套变更盘点 → 双份文档核对 → 门禁检查 → 格式化报告的流程复用到其他以文档为发布物的开源项目上。这套审计流程要解决什么问题发布一个以长生命周期运行为核心体验的终端工具真正的风险往往不在编译器而在变更没有被正确讲述用户可见的新功能、修复、破坏性变更没有进入下个版本的 changelogdocs/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 --abbrev0在 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为下一版根 READMEdocs/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.mdrelease 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-checkpreview 与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
