SuperAPI AI 工具集

auto-build

编程与开发

查看项目

更新于 10-16 06:26

技能介绍

Auto Build 将「计划 → 构建」压缩为一次获批的自主推进:按纪律方式实现计划中的每个任务——测试先行、集成、评审、逐个提交,同时由 DAG 保证任何任务都不会在其依赖落地之前开始构建,检查点保证任何中断都可以继续。它去掉的是人在任务之间来回操作,而不是验证环节:每个任务仍须通过测试并拥有自己的提交。

用途与总体思路

它面向已获批的 DAG 计划执行实现工作,把多任务构建过程自动化,同时通过阶段划分、检查点和预算上限保持可控。核心机制包括:DAG 拓扑分层的依赖屏障、每任务独立工作树与任务分支、串行化的合并集成、按切片范围的对抗式评审、有界修复循环,以及可持久化恢复的检查点。

阶段 0:预检——计划、干净基线、工作分支

解析计划($plan,或最新的 .ulpi/plans/*)及其独立的 Phase-0 摄入快照(<stateDir>/intake/<run>.json,来自当前运行配置/检查点),然后运行确定性关卡:node <auto-plan-dir>/scripts/validate-plan.mjs <plan.json> --intake <absolute-snapshot.json>,非零退出即视为不合格(这与 auto-plan 和流水线预检使用同一套结构判定,是机器校验,不是仅凭文字描述)。无计划 → 转交 auto-plan。无摄入快照 → 停止并转交流水线摄入;计划无法自行确立范围权威。计划格式错误或存在环 → 停止(否则会在损坏的基础上构建)。

确认根目录是 git 工作树且 workingBranch 已提交;未经明确确认,绝不在受保护分支上构建。

要求干净的基线:git status --porcelain 只应显示预期的计划产物(.ulpi/spec/、.ulpi/plans/)。出现其他内容 → 停止并要求用户提交或暂存。

把先前运行的教训从已加载上下文中折叠进工程师简报——auto-learn 会将其路由到 CLAUDE.md / .claude/rules(对你自己是自动加载的),但子代理工程师从头开始,因此机器已经付出代价得到的教训(不稳定的服务、validate 的坑、会咬人的边界)必须复制到它的简报里,才能到达真正干活的代理。

用 budget-guard 声明本次运行的预算/上限(每任务最大修复迭代次数、并发上限、token/挂钟时间上限)。创建检查点恢复文件,每个任务一个单元。恢复时加载现有检查点并跳过已完成任务。

成功标准:计划有效、在已确认分支上有干净的 git 基线、预算与检查点已设置。

阶段 1:唯一一次批准关卡

展示完整计划(任务、分层、每个任务触及的内容)。等待毫不含糊的肯定答复(“approve”“go”“yes”);把含糊回应(“看起来合理”“我猜可以”)视为未批准。这是唯一的人工关卡。若计划是刚刚生成的,将其作为一个预备提交单独提交,避免混入任务 1。

成功标准:明确批准被记录;计划产物单独提交。

阶段 2:按层遍历 DAG

按拓扑顺序逐层处理(层与层之间有屏障),并行构建该层任务——跨工作树并行,由 fan-out-work 限制并发。当计划给某任务分配了专家(agent/skill/reviewer——auto-plan 按描述匹配已安装的代理/技能)时,以该专家身份生成工程师与评审者,并让工程师先调用领域技能;名称缺失时降级为通用工程师并记录,绝不作为硬失败。每个任务执行构建契约(references/build-contract.md):

依赖关卡——所有 dependsOn 是否已集成?否则标记 dep_blocked(指向根因),跳过。

隔离实现——全新工作树 + 任务分支;RED(针对该行为的失败测试)→ GREEN(最小代码)→ REFACTOR;保持在任务的写入范围内。

集成——把任务分支串行化合并到工作分支,并移除已合并的工作树。集成只做合并,不运行整个工作区的 validate。

评审——针对该切片自身的验收标准对已集成切片做对抗式验证(切片范围:由后续任务负责的、未满足的全代码库不变量只算观察,不阻塞本切片)。仅当用户禁用了逐任务评审时才可跳过。

修复循环——对任务写入范围内的发现运行 converge-loop(有界,MAX_FIX≈3),直到该切片的 validate 变绿;否则标记为 blocked 并注明原因(不要空转)。

提交 + 检查点——为该任务的文件及其状态做一个提交;把该单元标记为完成。

每个任务到达终态时更新检查点。

成功标准:该层每个任务都处于 done、blocked 或 dep_blocked——每个已集成任务测试通过并单独提交;进入下一层前屏障保持有效。

阶段 3:停下并询问的触发条件(贯穿全程)

遇到以下情况停止自主推进并询问用户,不要强行通过:

任务的测试/构建在没有明显修复方案时无法变绿(给出失败与诊断);

规格含糊,或任务需要规格未覆盖的决策;

任务高风险/不可逆(见规则 6)——继续前获取明确签署。

用户解决后,重新调用以从下一个待处理任务恢复。

成功标准:风险/含糊/无法修复的情况送达用户,而不是靠猜测提交通过。

阶段 4:最终 validate + 报告

DAG 走完后,在已集成树上运行一次整个工作区的 validate——这是承重的终态关卡(各切片可能各自通过,合并后却损坏)。然后按 Output Contract 报告:done/blocked/dep_blocked 的任务、新增测试、提交、最终 validate 结果,以及任何升级事项。失败即关闭:红色的最终 validate 绝不报告为干净构建。

常见合理化辩解与反驳

“批准意味着我现在可以强行推进任何事。”——批准授权的是计划,不是不可逆的意外。破坏性/含糊步骤仍要停下询问。

“我用 git add -A 省时间。”——那会把无关工作吸收进任务提交,破坏干净回滚。只暂存该任务的文件。

“依赖还没集成,但我先构建,回头再协调。”——那是在损坏的基础上构建。标记为 dep_blocked;不要在缺失的迁移/路由/符号上施工。

“切片 validate 是红的,但那是既有失败。”——那就把它归类为既有失败并说明;不要在红色状态上悄悄标记完成,也不要丢弃正确的工作。

“这个任务让评审淹没在整个代码库的缺口里。”——逐任务评审是切片范围的。把终态缺口归给负责它的任务作为观察;不要阻塞当前切片。

“最后做一次大提交更简单。”——那会破坏逐任务回滚,并隐藏是哪个任务弄坏了什么。每个任务一次提交。

危险信号

任务在切片 validate 为红、或测试被跳过/被弱化以通过的情况下被标记完成。

git add -A / 提交混合多个任务的文件。

在某个 dependsOn 仍处于 pending/blocked 时构建任务。

在本次推进中执行不可逆操作却没有停下询问。

两个代理在没有工作树隔离的情况下同时写工作树。

恢复时重建了已集成的任务(检查点被忽略/覆盖)。

红色的最终工作区 validate 被报告为干净构建。

强制施行(确定性,非文字约定)

本技能激活期间,一个技能范围的 PreToolUse 钩子会对每次 Bash 调用运行 scripts/guard-git-hygiene.sh:批量暂存(git add/stage -A/./--all 以及 :/ 之类的全仓库路径模式)、commit -a/--all、普通 git push --force(非 lease)、reset --hard、clean -f 都会在工具层被阻止(按 token 解析——--amend 与提交信息内容永不误报)。干净回滚契约由机器强制,而非靠好言相劝。因此上述规则 2–3 不是空想。

护栏

唯一人工关卡(计划批准);一切不可逆/含糊/无法修复的情况仍会升级。

要求干净基线;每任务一次提交;只暂存该任务的文件。

遵循 DAG;绝不在未集成依赖上构建;绝不在红色 validate 上发布/标记完成。

每个任务测试驱动;绝不弱化/跳测试来变绿。

隔离并行写入者;串行化集成;修剪已合并工作树。

持久恢复:跳过已完成,绝不覆盖检查点。

最终 validate 失败即关闭。

何时加载参考

references/build-contract.md——逐任务契约:工作树/分支、RED→GREEN→REFACTOR、集成(合并 + 移除工作树)、切片范围评审、有界修复循环、任务退出关卡。

converge-loop(技能)——有界的逐任务修复循环。

adversarial-verify(技能)——逐任务切片评审。

fan-out-work(技能)——并行、有上限、隔离的逐层任务执行。

checkpoint-resume(技能)——持久逐任务状态 + 跳过已完成的恢复。

budget-guard(技能)——运行级上限与升级契约。

输出契约

报告:已构建的计划 + 工作分支;记录的唯一次批准;每个任务的 done / blocked / dep_blocked(含原因)、新增测试、提交;最终整个工作区 validate 结果(绿/红——如实);任何升级给用户的事项(无法修复/含糊/不可逆);检查点文件路径(持久、可恢复的记录)。