From 0d27fed0981282bf4b09857780b276d6b4edaef4 Mon Sep 17 00:00:00 2001 From: weichen Date: Sat, 17 Oct 2026 19:53:26 +0000 Subject: [PATCH] Record the layered delivery and spec slimming proposal Why: The user approved a two-level delivery model with fold-close, level-scoped gates, task lanes and spec slimming; it needs a planning master record. Evidence: git diff --check clean; baseline numbers are SELF read-only Git/API observations from 2026-10-18. Impact: Adds docs/proposals/2026-10-18-delivery-model-v3.md and an INDEX.md entry; no code change. Refs: Agent-System-Dev feature/delivery-model-v3 Co-authored-by: Cursor --- .../proposals/2026-10-18-delivery-model-v3.md | 88 +++++++++++++++++++ docs/proposals/INDEX.md | 3 + 2 files changed, 91 insertions(+) create mode 100644 docs/proposals/2026-10-18-delivery-model-v3.md diff --git a/docs/proposals/2026-10-18-delivery-model-v3.md b/docs/proposals/2026-10-18-delivery-model-v3.md new file mode 100644 index 0000000..607eae3 --- /dev/null +++ b/docs/proposals/2026-10-18-delivery-model-v3.md @@ -0,0 +1,88 @@ +# 分层分支交付与规范精简 r1 + +- 状态：已批准实施（2026-10-18，用户审阅建议后指示"按计划实施"）；推进中 +- 负责人：weichen（需求与批准）；实施：治理大任务 `feature/delivery-model-v3`（Agent-System-Dev） +- 适用范围：Agent-System-Dev 的开发流程与规范；组件仓按同一模型另行跟进 +- 更新时间：2026-10-18 + +## 背景 + +用户的诉求：减少向主仓（Dev `main`）合入的频率，避免其他工作分支反复同步、重跑 CI； +L2 合入 L1 要快、要轻；按任务类别区别对待，修复优先；测试、验收、审批放在合适的层级； +减少 Agent 设置的长时间等待；精简臃肿的规范。 + +2026-10-18 只读核查（来源 SELF，Git 与 Gitea API 观察）： + +- Dev `main` 14 天被推进 410 次（first-parent，峰值 85 次/天）。按 PR 标题粗分，闭合任务卡约 40%、 + 功能约 30%、组件 pin 约 20%、修复约 6%。10-14 启用合入窗口后仍约 17 次/天，其中闭合卡仍占 40%。 +- 近期 291 个已合入 PR 中有 288 个以 `main` 为 base；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，以及新建 worktree 时 + 串行克隆 105 个嵌套子模块（只有 13 个不同仓库；`--jobs 8` 并行实测约 26 秒）。 +- 常读规范约 4.6 万字符；同一段 Agent 路由规则写了 7 处；归档任务卡中位 113 KB， + 原因是证据工具把完整 JSON 收据写进了卡片。 + +结论：频繁触发的主因不是层级不够，而是"记账也在推进 main"，以及每一层门禁都一样重。 + +## 目标与成功标准 + +1. 任务卡不再单独推进 `main`：任务卡在合入前随本 PR 折叠闭合，不再开单独的闭合 PR。 +2. 统一的 CI 等待入口：一次阻塞调用等到精确 SHA 的检查结果，不再手写轮询。 +3. 门禁按层级分配：完整门禁只在进 `main` 时执行一次；L2 合入 L1 只做轻量检查。 +4. 任务按类别走通道：修复优先直达 `main`，其余类别按主题聚合进 L1。 +5. 规范收敛为单一权威，入口瘦身，任务卡与证据瘦身。 + +成功标准（采纳两周后对照本次基线复测）：`main` 推进次数、CI 次数与机时、每 PR 平均 CI 次数、 +闭合 PR 数量均明显下降；闭合 PR 数降为零（存量补救除外）。 + +## 方案要点 + +### 分支层级：固定两级，拆小靠单元 + +- L1 大任务（initiative）从 `main` 切出，最终一次合入 `main`；L2 子任务从 L1 切出，合入 L1。 +- L2 内部的 agent-exec 单元（私有克隆、快进集成、不开 PR）是最轻的一层，负责控制上下文长度。 +- 不放开更深层级：`main` 的推进次数只取决于根层交付次数；加深层级只会增加同步链、推迟集成， + 而且上游 draft.12 与现有工具只定义两级。 +- 太大时横向拆分：L1 超过约 2 周或 6–8 个子任务时，拆成多个并列 L1，用规划主记录串联； + L2 太大时拆成兄弟 L2 或更多单元。 + +### L1 章程 + +章程写在 L1 任务卡顶部，`make task-triage` 会摘录"目标与非目标"段。章程包括：用途与目标、 +接纳范围与非目标、方案和计划链接、子任务登记、分级测试策略、验收条件、追加的领域规则、生命周期。 +建立 L1 时立即开一个以 `main` 为 base 的 [WIP] PR，用于分流发现，评论区同时作为仓外调度记录。 +L1 不追 `main`，只在最终窗口、需要 `main` 上的修复、或长周期 L1 到里程碑/每周一次时同步。 + +### 任务分类与通道 + +修复（`fix/`、P0 用 `hotfix/`）优先直达 `main`；完善按领域进入"完善列车" L1；扩展优先 JOIN +同主题 L1；新增建立 L1；治理与规范集中在一个治理 L1；记录类不单独推进 `main`； +组件 pin 跟随用到它的 L1 推进。 + +### 测试、验收与审批的层级 + +- 单元合入 L2：worker 自检，host 跑最小直接检查。 +- L2 合入 L1：同步 L1 头、跑受影响模块测试、一次全新会话独立 Review、轻量 CI（GATE）； + 不排合入窗口，不需要分流收据和三段证据，不设人工审批。 +- L1 自身：WIP PR 的完整 CI 作为非阻塞预警。 +- L1 或修复合入 `main`：合入窗口、完整 CI、整体 Review、三段证据，以及一次性的用户专属验收。 +- 人工审批只保留三处：L1 章程确认、L1 最终的用户专属验收、高后果双钥匙操作。 + +## 阶段与关联任务 + +| 阶段 | 内容 | 状态 | +|---|---|---| +| R | 本主记录、PROJECT.md 链接、治理 L1 与 WIP PR | 推进中 | +| P1 | 合入前折叠闭合与存量清理；`make ci-wait` 与等待规则；子模块并行物化 | 待实施 | +| P2 | CI 按 base 区分完整/轻量；L2 免分流、免合入窗口、免三段证据；三种任务卡模板；任务通道写入 delivery.md | 待实施 | +| P3 | 规范精简：入口瘦身、单一权威、合入调度并入交付规范、矩阵与采纳记录改为引用、证据摘要入卡 | 待实施 | +| M | 采纳两周后按基线复测 | 待执行 | + +实际进展以 Dev 治理大任务的任务卡与 PR 为准；本记录只在阶段完成时更新。 + +## 未纳入与限制 + +- 分支保护等平台配置不在本次范围内；如需调整，由用户按双钥匙规则执行。 +- 不建设自动合并队列、合并列车或调度服务。 +- 上述数据为粗分统计（按 PR 标题分类），效果以实施后复测为准。 diff --git a/docs/proposals/INDEX.md b/docs/proposals/INDEX.md index b5d3f8b..4f65fd2 100644 --- a/docs/proposals/INDEX.md +++ b/docs/proposals/INDEX.md @@ -4,6 +4,9 @@ 本索引负责导航与差异提示，规划正文、批准范围和验收条件仍以链接的主记录及其批准版本为准。 合入授权不批准新方向、不调整里程碑范围、不启动新的业务任务。 +开发流程方向：[分层分支交付与规范精简 r1](2026-10-18-delivery-model-v3.md)：2026-10-18 用户批准实施； +固定两级分支、任务卡合入前折叠闭合、按层级分配门禁、任务分类通道与规范精简，由 Dev 治理大任务 `feature/delivery-model-v3` 推进。 + 待评审（收录不是批准）：[svc 插件组合部署（--with）方案 r1](2026-10-14-svc-plugin-compose-deploy.md)； [分层 Python 环境方案 r1](2026-10-15-layered-python-env.md)（8788 无法生成 docx 的环境层；白名单自动批准，其余审批）。 -- 2.54.0