5.4 KiB
5.4 KiB
分层分支交付与规范精简 r1
- 状态：已批准实施（2026-10-18 用户指示按计划实施）；推进中
- 负责人：weichen（需求与批准）
- 实施：Dev 治理大任务
feature/delivery-model-v3 - 适用范围：Agent-System-Dev 开发流程与规范
- 更新时间：2026-10-18
1. 背景
用户提出的需求：
- 减少合入 Dev main 的次数，让其他分支不必反复同步、反复跑 CI。
- L2 合入 L1 要轻；按任务类别分别处理，修复优先。
- 测试、验收、审批放在合适的层级，不在每一层重复。
- 去掉 Agent 的长时间 sleep 等待；精简膨胀的规范。
2026-10-18 只读基线（均为 SELF 观察）：
- main 推进：14 天共 410 次（first-parent），峰值 85 次/天。按 PR 标题粗分，闭合任务卡约 40%、功能约 30%、组件 pin 约 20%、修复约 6%。 10-14 启用合入窗口后仍约 17 次/天，闭合 PR 仍占约 40%。
- 分层使用：近期 291 个已合入 PR 中 288 个 base 为 main，initiative/child 模型只用过一次。
- CI：3.3 天跑了 200 次，单次中位 8.3 分钟；闭合相关运行约占 31% 机时；main 的 push CI 有 95% 在复测与 PR head 完全相同的树；每个 PR 平均 2.4 次 CI。
- 等待：Git 远端往返约 0.35 秒。长等待来自 Agent 手写
sleep N; curl轮询 CI，以及串行克隆 105 个嵌套子模块（实际只有 13 个不同仓；并行--jobs 8实测约 26 秒）。 - 规范体量：日常必读规范约 4.6 万字符；同一段 Agent 路由规则写了 7 处；归档任务卡中位 113 KB，原因是证据工具把完整 JSON 收据写进了卡。
结论：频繁触发的主因不是层级不够，而是记账类改动也在推进 main，加上每一层都执行同样重的门禁。
2. 目标与成功标准
- 任务卡在合入前随 PR 折叠闭合，不再单独开闭合 PR。
- 统一一个阻塞式的 CI 等待入口，按精确 SHA 等待结果。
- 完整门禁只在进入 main 时执行；L2 合入 L1 只做轻量检查。
- 任务分通道：修复直接进 main 并优先；其他类别按主题聚合进 L1。
- 规范单一权威、更精简；任务卡变小。
成功标准：采纳两周后按本次基线复测。main 推进次数、CI 次数与机时、每 PR 平均 CI 次数均下降；闭合 PR 数降到零（存量清理除外）。
3. 方案要点
3.1 固定两级分支
- L1 大任务：从 main 切出，最终一次合入 main。L2 子任务：从 L1 切出，合入 L1。
- L2 内部用 agent-exec 单元控制上下文长度，单元不开 PR，是最轻的一层。
- 不再加深层级：main 的推进次数只取决于根层交付次数；每多一层就多一条同步链，集成也被推迟；现行 Guidelines 与工具只定义了两级。
- 太大时横向拆：L1 超过约 2 周或 6–8 个子任务时拆成多个并列 L1；L2 太大就拆成兄弟 L2 或更多单元。
3.2 L1 章程
- 章程写在 L1 任务卡顶部：用途与目标、接纳范围与非目标、方案和计划链接、子任务登记、分级测试策略、验收条件、追加的领域规则、生命周期。
- 建 L1 时立即开一个 base 为 main 的 [WIP] PR，用于分流发现，评论区同时作为仓外调度记录。
- L1 不追 main，只在三种情况下合入最新 main：最终交付窗口；需要 main 上的某个修复；长周期 L1 到达里程碑或每周一次。
3.3 任务通道
- 修复：
fix/直接进 main 并优先排队；P0 用hotfix/。 - 完善：按领域放进“完善列车” L1。
- 扩展：加入（JOIN）同主题的在途 L1。
- 新增：新建 L1 并写章程。
- 治理与规范：集中在一个治理 L1 中。
- 记录类改动不单独推进 main；组件 pin 跟随用到它的 L1 一起推进。
3.4 按层级分配门禁
- 单元合入 L2：worker 自检，host 做最小直接检查。
- L2 合入 L1：先同步 L1 头，跑受影响模块的测试，由一个全新会话做独立 Review，轻量 CI 作为 GATE。 不排合入窗口，不需要分流收据、三段证据和人工审批。
- L1 的 WIP PR：完整 CI 照常运行，作为不阻塞任何人的提前预警。
- L1 或修复合入 main：合入窗口、完整 CI、整体 Review、三段证据，以及一次用户专属验收。
- 人工审批只保留三处：L1 章程确认、L1 最终的用户专属验收、高后果双钥匙操作。
4. 阶段与关联任务
| 阶段 | 内容 | 状态 |
|---|---|---|
| R | 本主记录、PROJECT.md 链接、治理 L1 及其 WIP PR | 推进中 |
| P1 | 合入前折叠闭合并清理存量卡；make ci-wait 与等待规则；子模块并行物化 |
待实施 |
| P2 | CI 按 PR base 区分完整与轻量；L2 免分流、免合入窗口、免三段证据；三种卡模板；通道写入 delivery.md | 待实施 |
| P3 | 规范精简：AGENTS.md 改为入口；delivery.md 作为单一权威并并入 merge-queue；矩阵与采纳记录改为引用；证据摘要入卡、完整收据出卡 | 待实施 |
| M | 采纳两周后按本次基线复测 | 待执行 |
实时进度以 Dev 治理大任务的任务卡和 PR 为准；本记录只在阶段完成时更新。
5. 未纳入与限制
- 分支保护等平台设置不在本方案范围内；如需变更，由用户按双钥匙规则亲手执行。
- 不引入自动合入队列、合入列车或调度服务。
- 基线数字按 PR 标题粗分，只用于判断方向；实际效果以复测结果为准。