企业官网建设流程全解析

Novu 开源仓库中的 Park and Review 技能：基于 Git Worktree 的原子化代码审查与重构工作流

【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu

导读

本文深入解析 Novu 开源仓库（the open-source communication infrastructure for agents and products）为 AI 编程 Agent 内置的一套名为nv-park-and-review的代码审查技能（技能定义文件）。它以"基线提交（baseline commit）→ 一次性审查 worktree → 单提交粒度的核弹级质量审查 → 独立重构提交 → 合并回主线"五步闭环为核心，专门用于审查本地未提交改动中的 AI 生成痕迹（AI slop）与冗余代码。读完本文，你将掌握这套可复制的 Git 工作流：如何用 worktree 隔离审查现场、如何把审查结论固化为行为保持的独立重构提交、以及如何用快进合并让功能差异与审查差异在历史中清晰可分。

为什么需要"Park and Review"：把审查从功能开发中解耦

在 Novu 这样的超大型 monorepo（包含apps/api、apps/worker、apps/dashboard、apps/ws、packages/*等数十个可发布包）中，AI 辅助开发会引入一个典型问题：功能改动与代码质量修复混杂在同一个 diff 中，评审者难以区分"这个改动是业务逻辑"还是"这是为了讨好 linter 的冗余重构"。nv-park-and-review的解法非常明确：

1. 先把当前未提交的功能改动冻结为一个基线提交（baseline commit）；
2. 立刻跳入一个轻量的审查 worktree，让主 checkout 恢复空闲；
3. 在 worktree 内只针对那一个提交运行核弹级代码质量审查（thermo-nuclear review）；
4. 把审查产出的修复整理成另一个独立的重构提交；
5. 最后把重构提交合并回原分支并拆除 worktree。

这样形成的提交历史是feature 提交 → refactor 提交两段式结构，功能差异与审查驱动的重构始终分别可审。技能文档明确声明：调用本技能即授权它创建的这两个提交（步骤 1 与步骤 4），且不得 amend 或 squash 基线提交。

该技能并非孤立存在，它嵌入了 Novu 的 Agent 技能生态。在 nv-implement 技能 中，/nv-park-and-review被规定为每个切片（slice）子代理的收尾动作："Closing step: commit withtype(scope): why, then run/nv-park-and-reviewfrom the worktree"；在 novu-prepare-pr 技能 中，提交规范被进一步约束为type(scope): concise why fixes NV-XXX，scope 取值包括dashboard、api-service、worker、shared等（见 pullrequest.mdc 规则）。也就是说，nv-park-and-review是 Novu 从"切片实现"到"PR 准备"整条流水线的质量闸门。

工作流总览：五步闭环

技能以一张可勾选的进度清单定义整体流程：

- [ ] 1. Baseline commit（要审查的功能提交） - [ ] 2. Exit to a review worktree（一条命令跳入审查工作区） - [ ] 3. Thermo-nuclear review（仅针对该提交的核弹级审查） - [ ] 4. Triage + fix, then a separate refactor commit（分诊修复 + 独立重构提交） - [ ] 5. Land back on the original branch + teardown（合并回原分支 + 拆除）

下面按步骤逐一展开，并补充可直接复制的命令。

步骤 1：创建基线提交（Baseline commit）

这是整个流程的锚点，后续所有审查都只针对这一个提交。技能规定的动作顺序是：

1. 先并行检查现状，确认要提交的内容范围：

   git status git diff # 暂存区 + 未暂存区 git log --oneline -15 # 观察本仓库的提交信息风格

2. 只暂存内聚的改动：如果用户已经暂存了文件，就直接提交这些；否则暂存相关的已修改文件。明确排除无关的本地编辑——技能要求"Stage the cohesive change only"，防止把无关文件卷进基线。
3. 按仓库的 conventional 风格提交，格式为type(scope): concise why，scope 沿用dashboard、api-service、worker、shared等。建议用 HEREDOC 写提交信息，避免引号转义问题：

   git commit -m "$(cat <<'EOF' feat(dashboard): add workflow trigger button <why 说明> EOF )"

4. 留意提交钩子：Novu 仓库的 package.json 中通过 husky 配置了"pre-commit": "lint-staged"钩子，同时声明了"lint-staged": "lint-staged"与"check": "biome check ."、"check:fix": "biome check --write ."等脚本（依赖@biomejs/biome）。技能明确提示：lint-staged与biome check --write会在提交时运行并可能自动格式化暂存文件，提交依然成功；但如果钩子失败，必须修复后重新提交，绝不使用--amend。
5. 提交后立刻捕获基线 SHA——这是唯一的审查目标：

   git rev-parse HEAD # 得到 BASE_SHA

技能强调："Invoking this skill authorizes the two commits it creates (steps 1 and 4). Do not amend or squash the baseline commit."——amend/squash 基线会破坏"审查只针对该提交"的精确边界，因此被严格禁止。

步骤 2：一条命令跳入审查 worktree

基线提交完成后，立即把后续的审查、分诊编辑与重构提交全部搬到独立 worktree，让主 checkout 恢复空闲、可以并行处理其他工作。这里刻意不使用仓库里更重的nv-worktree-create（技能文档 中该技能会复制.env*、初始化 enterprise 子模块、执行pnpm symlink:submodules等），因为审查通过不需要环境复制、依赖安装或构建，一条轻量命令即可：

git worktree add -b review/<branch>-<BASE_SHA:0:7> ../review-<BASE_SHA:0:7> <BASE_SHA>

命令拆解：

从这一步起，所有命令与文件编辑都必须在 worktree 路径内执行，绝不碰主 checkout，直到步骤 5。如果目标 worktree 路径已存在（磁盘上或git worktree list中），技能要求中止并回退到原地审查，不要强行覆盖。

关于 worktree 的路径命名规范、.env复制与依赖安装细节，可参考配套的 nv-worktree-commands 技能：它给出REPO_ROOT/REPO_PARENT的推导公式、DIR_NAME = sanitize(BRANCH)（小写、/→-）的命名规则，以及git worktree list、git -C <path> status -sb等检查命令。Novu 特有的注意事项是该文档强调的：worktree 不会自动携带被 gitignore 的.env文件，若需要本地密钥，应从父 checkout 复制（绝不能运行node scripts/setup-env-files.js，因为那会重新生成STORE_ENCRYPTION_KEY，导致 worktree 与父环境、共享的本地 Mongo/Redis 密钥不一致）。

步骤 3：Thermo-nuclear review——仅针对 BASE_SHA 的核弹级审查

进入 worktree 后，先用两条命令收集精确的审查范围：

git show <BASE_SHA> --stat # 变更文件清单 git show <BASE_SHA> # 完整提交 diff，用于粘贴进子代理 prompt

然后启动一个thermo-nuclear-code-quality-review子代理（Task 工具，readonly: true，前台运行以便拿到结果后立即行动）。技能内置了完整的子代理 prompt 模板，核心要点如下：

• 范围控制（最关键）：只审查<BASE_SHA>这一个提交改动的行；可以阅读整个文件获取上下文，但每条 findings必须指向该提交引入/修改的具体行，不得报告既有代码或整个分支的问题；
• 审查焦点：AI slop（AI 生成痕迹）、冗余/死代码、重复逻辑、不必要的抽象或 props、反转/含义混淆的布尔命名、状态管理异味（冗余 state 与派生值、effect 误用、stale-closure/依赖数组问题）；
• 输出要求：每条 finding 给出文件、具体符号/行号、严重级别、为什么是问题、以及一个具体的最小修复方案；区分 must-fix 与 optional，跳过不影响正确性或可维护性的吹毛求疵；只返回 findings，不得修改任何文件。

这个"thermo-nuclear"审查词同时出现在 Novu 的其他技能中，构成了统一的质量审查标准：nv-implement在步骤 5 对整条 feature 分支 diff 也启动同一个子代理；novu-prepare-pr在质量关卡（Quality passes）中同样要求"load the skill, review the branch diff for structure/maintainability"，并紧随其后运行deslop技能清除 AI slop（冗余注释、防御性噪音、多余 cast、重复测试）。

步骤 4：分诊、修复与独立重构提交（在 worktree 内完成）

拿到审查结果后，不要盲信，先做验证与分诊：

1. 删除前先验证：对每一条死代码/冗余断言，用 Grep 确认调用点、setter、其他调用方，确认确实无引用后才删除；
2. 只应用 must-fix 与高价值 finding，所有编辑必须是**行为保持（behavior-preserving）**的；有意的或低价值的 finding 予以推迟，并向用户说明原因；
3. 不扩大范围：分诊期间不得顺手加功能；
4. 编辑完成后，对每个改动过的文件运行ReadLints；任何重命名后要用 Grep 检查残留的旧标识符；只修必要的既有 lint；
5. 只暂存分诊改动的文件，新建一个提交（再次强调：绝不 amend BASE_SHA）：

   git commit -m "$(cat <<'EOF' refactor(<scope>): <删除了什么/重命名了什么以及为什么> EOF )"

6. 用git log --oneline -3确认历史形态：先出现 BASE_SHA，随后是重构提交。

如果审查没有发现值得修复的问题，直接跳过步骤 4，进入步骤 5 只拆除 worktree 与分支（无需合并），并向用户报告"审查干净"。

步骤 5：合并回原分支并拆除（Land back + teardown）

回到主 checkout，用快进合并把原分支推进到审查分支上，然后拆除 worktree——技能明确说用普通命令即可，无需专门的清理技能：

git merge --ff-only review/<branch>-<BASE_SHA:0:7> git worktree remove ../review-<BASE_SHA:0:7> git branch -d review/<branch>-<BASE_SHA:0:7>

关键失败处理：如果--ff-only失败，说明审查期间原分支发生了移动——此时绝不强制合并，而是报告分叉情况，把审查分支留在原地交给用户自行协调。这与仓库内 nv-worktree-cleanup 技能 的安全原则一脉相承：该技能规定绝不未经用户确认--force移除 worktree、绝不删除主 worktree 或 Agent 当前所在的 worktree、默认用git branch -d安全删除。

贯穿全程的 Guardrails（护栏）

技能在末尾总结了四条不可逾越的边界，它们是整个工作流正确性的保障：

1. 提交必须分离：基线提交（步骤 1）与重构提交（步骤 4）保持独立，永远不要 squash 二者，也不要--amend基线；
2. 审查只针对单一基线提交：永远不是整个分支——这保证了审查结论可追溯、可复现；
3. 空审查结果优雅退出：若审查无可修之处，跳过步骤 4，步骤 5 只拆除 worktree 与分支（无内容可合并），报告干净结果即可；
4. 不主动推送：除非用户明确要求，不 push、不开 PR。

此外，从调用上下文（nv-implement）还能提炼出配套约束：切片提交与审查重构提交在合并过程中同样必须保持分离，子代理一旦越过自己 worktree 的边界编辑了兄弟切片，就必须被纠正。

与相关技能的关系图谱

nv-park-and-review位于 Novu Agent 技能体系的质量保障中枢，技能文档末尾列出其配套技能：

• thermo-nuclear-code-quality-review：步骤 3 使用的审查评分标准（rubric），本技能只负责"圈定范围、提交现场"，审查本身完全委托给它；
• deslop：从 diff 中移除 AI slop 的配套技能，与核弹级审查在novu-prepare-pr的质量关卡中先后使用；
• nv-worktree-commands：worktree 命令速查手册，当轻量设置需要排障时查阅（路径命名、创建/移除/prune、.env*复制、依赖安装等）；
• novu-prepare-pr：实现完成后的完整 PR 准备流程，与本技能前后衔接。

如果从更宏观的流水线看，这一整套技能串成了 Novu 仓库 AI 协作开发的完整闭环：nv-worktree-create（建隔离环境）→nv-implement（切片并行实现，每片收尾跑/nv-park-and-review）→nv-park-and-review（本次主题，提交级原子审查）→novu-prepare-pr（PR 准备与 CI 分诊）→nv-worktree-cleanup（回收过期 worktree）。nv-park-and-review恰好处于"实现质量"与"交付质量"的接缝处，用两个分离的提交把"做了什么"和"修了什么"永久性地记录在历史中。

实践要点速查

• 记住核心不变式：基线提交只做一次、绝不 amend/squash；审查只针对这一提交；修复永远以新提交落盘。
• worktree 分支命名review/<branch>-<BASE_SHA:0:7>、目录../review-<BASE_SHA:0:7>，保证多轮审查互不冲突、可快速对应到源提交。
• 审查子代理必须readonly: true，只返回 findings 不落盘修改，防止审查环节污染现场。
• 合并回主线一律--ff-only，失败即报告分叉、绝不强推。
• 仓库的 pre-commit 钩子（husky + lint-staged + biome）会在提交时自动格式化暂存文件，这是正常现象；钩子失败要新提交修复，而不是回改历史。

这套工作流不依赖任何第三方平台，全部由原生 Git worktree 能力与任务委托构成，可直接移植到任何遵循 conventional commits 的 Git 仓库中，用于把"AI 辅助开发"的产出纳入与人类开发者同等严格的审查纪律。

【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu