gsd-2 渐进式规划与执行中升级（ADR-011）：从全量预分解到 sketch-then-refine 与 manual-attention 门控

人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载导读本文围绕 gsd-2 的架构决策记录 ADR-011渐进式规划与执行中升级 展开介绍该决策如何在 Unified Orchestration KernelUOK见 ADR-009的 Plan Plane 与 Gate Plane 上落地两项能力Progressive Planning草图-再精化规划与Mid-Execution Escalation执行中升级。读完本文你将理解 gsd-2 如何解决里程碑先行全量分解导致计划陈旧和执行歧义只能猜或阻塞两个核心问题掌握 sketch slice 的声明方式、refining 相位与 refine-slice 派发链路、T##-ESCALATION.json工件的结构与continueWithDefault语义以及这些机制在源码中的实现位置与测试覆盖。一、背景两个让长期自主执行不可靠的问题ADR-011 的直接动因来自 ADR-009 引入的 UOK 六控制面。该决策把两个能力分别映射到其中的两个控制面Progressive Planning—— 扩展 Plan Plane 的compile步骤用草图-再精化替代一次性全量切片分解Mid-Execution Escalation—— 将 Gate Plane 的manual-attention门控结果落实为执行阶段任务级歧义的暂停/恢复语义。问题 1前置全量分解产生陈旧计划plan-milestone运行时会一次性把所有切片都分解到完整细节。对一个 4 切片里程碑而言S03、S04 在 S01 尚未执行前就被精细规划。等到 S03 派发时S01、S02 已交付代码库已经变化规划器对文件结构、API 形态、数据模型的假设可能早已失效。仓库中确实存在reassess-roadmap相位来兜底但正如 ADR-003pipeline 简化 所记录它几乎总是说 roadmap 没有问题——粒度太粗它评估的是整个 roadmap而非下一个切片的具体假设 vs. 之前切片实际构建的成果。ADR-011 引用了两项研究支撑Zylos Research2026-02指出 20 步中每步 95% 的可靠性最终只有约 36% 的整体成功率基于陈旧快照规划 S04 会在每一步叠加不可靠性ETH Zurich2026-02则强调上下文质量大于数量基于陈旧代码库快照的计划属于会主动伤害执行的低质量上下文。问题 2二元化升级要么猜要么阻塞原execute-task提示词对歧义只有两种处理Guess猜测——做合理假设并在任务摘要中记录Blocker阻塞——设置blocker_discovered: true触发整个切片重新规划。两者之间没有中间地带。琐碎可解与计划失效之间的大片空间全部落入 guess 桶执行器遇到通知应该用独立表还是用户表上的 JSON 数组这种问题时只能猜三个任务之后集成测试失败因为其他组件假设了另一种做法。ADR-009 的 Gate Plane 定义了manual-attention这一门控结果但此前只适用于门控级决策策略、验证、收尾并不适用于执行期间的任务级歧义。ADR-011 引用的支撑研究包括Zylos65% 的 AI 失败源于上下文漂移、OpenAI2025-09训练鼓励自信猜测而非校准的不确定性、METR2025感知与实际的 39 点质量差距。二、Change 1渐进式规划Sketch-Then-Refine2.1 两层级切片规格渐进式规划用两层级切片规格替代全有或全无的里程碑规划在plan-milestone阶段Plan Plane 的compile步骤S01 完整规划任务分解、must-haves、验证标准S02 及后续切片只产出sketch草图标题、目标、风险级别、依赖、粗略范围2-3 句、关键约束——不包含任务分解、任务计划、详细验证。在每个切片完成后Execution Plane 的新refine节点派发下一个切片的plan-slice之前调度器先派发一个refine-slice单元refine-slice接收sketch、已完成前序切片的摘要与发现、当前代码库状态它把 sketch 转换成完整计划——输出与plan-slice相同但上下文更好。2.2 Execution Plane 中的新节点类型ADR 给出了refine节点的规格refine — converts a sketch into a full plan using current codebase state inputs: sketch (from roadmap), prior slice summary, current codebase outputs: PLAN.md, T##-PLAN.md files dependencies: prior slice completion gate: plan-gate (same as plan-slice)在源码中这个节点对应src/resources/extensions/gsd/prompts/refine-slice.md的完整提示词。该提示词明确说明这不是空白页规划sketch 是权威边界前序切片产出是权威上下文见 refine-slice.md并要求单元注意依赖切片的Forward Intelligence部分脆弱性、变化假设、watch-outs把前序切片实际构建的东西对计划进行调和。它还支持用subagentscout / planner做侦察和子分解但禁止派发实现层代理worker、refactorer、tester——实现属于execute-task。2.3 状态推导refining 相位ADR 定义refining相位在以下条件同时满足时触发下一个切片以 sketch 形式存在有 roadmap 条目但没有 PLAN.md前序切片已完成有 SUMMARY.md里程碑未被阻塞。在 state.ts 中deriveStateFromDb以DB 切片元数据为权威当activeSliceRow?.is_sketch 1时直接返回phase: refining并把nextAction设为使用前序切片上下文精化 sketch 切片。注意PLAN.md 与偏好标志只是投影/配置故意不参与判断切片是否为 sketch。2.4 派发链路与优雅降级auto-dispatch.ts 中名为refining → refine-slice的调度规则体现了完整链路相位为refining时优先匹配崩溃恢复若 PLAN 文件已存在但 DB 仍标记 sketch先setSliceSketchFlag(mid, sid, false)自愈并skip让下一轮循环基于修正后的 DB 状态重新推导相位偏好关闭降级若phases.progressive_planning为 false则把 sketch 当作需要计划的普通切片走plan-slice同时把 DB 中的sketch_scope作为soft scope hint传入避免范围信号被静默丢弃偏好开启时buildRefineSlicePrompt组装提示词并派发refine-slice单元。2.5 关键实现细节源码印证Schemaslices 表新增is_sketch INTEGER NOT NULL DEFAULT 0与sketch_scope TEXT NOT NULL DEFAULT 两列见 db-base-schema.ts。工具层三值语义plan-milestone.ts 中validateSlices刻意保留isSketch的 true / false / 缺席 三值语义。缺席时必须把undefined传给insertSlice使 ON CONFLICT 子句保留已有行的is_sketch值而不是静默覆盖掉合法 sketch。校验规则isSketch: true时sketchScope必须为非空字符串非 sketch 时则必须提供successCriteria、proofLevel、integrationClosure、observabilityImpact等完整规划字段——sketch 切片被允许把这四个重量级字段推迟到 refine 阶段。提示词模板plan-milestone.md 的 Progressive Planning (ADR-011) 章节给出可直接使用的声明约定gsd_plan_milestone调用中对 sketch 切片设置isSketch: true与sketchScope: 2-3 sentence scope并规定S01 永远不能是 sketch必须在本单元完整分解。sketch 切片保留 title、risk、depends、demo line 与 2-3 句sketchScopegoal 只需一句话其余字段留空。偏好开关phases.progressive_planning在 types.ts 中定义在 preferences-validation.ts 中被严格布尔校验。注意另一项相邻偏好phases.reassess_after_slice位于同一校验块L347。ROADMAP 徽标markdown-renderer.ts 对slice.is_sketch 1的切片在risk:之前渲染[sketch]徽标PR #5763窄终端中一眼可见哪些切片仍在等待 refine-slice 展开。drift 自愈sketch-flag.ts 注册了stale-sketch-flag类型的 drift handler覆盖两种场景① 在gsd_plan_slice写入 PLAN.md 与翻转 sketch 标志之间崩溃② 偏好关闭的降级场景——plan-slice写出了 PLAN.md 但is_sketch1残留下一次对账清掉。该 handler 在deriveStateFromDb中由autoHealSketchFlags回调state.ts在尊重 DB 权威之前先做自愈。测试progressive-planning.test.ts 共 12 个测试覆盖 sketch 检测 → refining 相位、派发路由、auto-heal、迁移幂等性。例如第一条测试验证sketch 切片 progressive_planning ON → phaserefining第二条验证偏好缺失时 DB sketch 元数据仍然权威地产生 refining 相位对应代码注释flag absent must not override DB sketch metadata。三、Change 2执行中升级Mid-Execution Escalation3.1 第三种选项升级而非猜测/阻塞在猜与阻塞之间增加第三个选项。执行器遇到任务级歧义时可写出新工件T##-ESCALATION.jsonADR 给出了完整示例{ escalationId: ESC-M001-S02-T03-001, timestamp: 2026-04-17T14:32:00Z, taskId: T03, sliceId: S02, milestoneId: M001, question: Should notifications be stored in a separate table or as a JSON array on the user table?, options: [ { label: Separate table, tradeoffs: More flexible for querying, filtering, pagination. Requires migration., recommendation: false }, { label: JSON array on user, tradeoffs: Simpler schema, faster single-user reads. Limited to ~1000 notifications., recommendation: true } ], recommendation: JSON array — scope is single-user display, not cross-user analytics., continueWithDefault: true }源码中的类型定义types.ts对该工件做了更严格的规范化EscalationOption使用稳定的短id如 A、B同时作为/gsd escalate resolve taskId id的choice值EscalationArtifact包含version: 1、recommendation必须引用某个 option id、recommendationRationale、continueWithDefault以及由 resolve 命令回填的respondedAt、userChoice取值可以是 option id、accept或reject-blocker和userRationale。3.2 与 Gate Plane 的集成流程ADR 描述了 7 步闭环执行器写出T##-ESCALATION.jsonGate Plane 的execution-gate检测到升级工件门控结果manual-attention通知系统持久通知面板PR #3587将升级呈现给用户用户通过通知面板响应调度器把用户的决策注入 carry-forward 上下文后恢复执行决策通过gsd_decision_save记录source: escalation。源码侧escalation.ts完整实现了这套 I/O 与状态机路径规范escalationArtifactPath生成.gsd/milestones/{M}/slices/{S}/tasks/{T}-ESCALATION.json与T##-SUMMARY.md平行构建与校验buildEscalationArtifact服务端强校验 option 数量2-4 个、id 唯一、recommendation 必须命中某个 option idreadEscalationArtifact对读取做完整 schema 校验畸形文件返回 null保证下游展示/解决/carry-forward 永不因脏数据崩溃原子写writeEscalationArtifact通过atomicWriteSync写临时文件再 rename落盘随后按continueWithDefault翻转 DB 标志awaiting_review 或 pending并发出category: gate、type: escalation-manual-attention-created的 UOK 审计事件——这正是 ADR 中审计日志先于文件写入记录意图提供恢复信号的落地门控语义gate-runner.ts 的GateExecutionInput明确允许outcome取pass | fail | retry | manual-attention四值之一RETRY_MATRIX 中manual-attention的 retry 次数为 0不自动重试等待人工run在未知门控或缺省结果时默认回退为manual-attentionL195-204即无法判定时请人介入。3.3continueWithDefault语义true执行器先按其推荐选项继续。若用户稍后选择不同当前任务如 T03仍在进行 → 把 ESCALATION OVERRIDE: User chose [X] instead of executors [Y] 注入当前任务 carry-forward当前任务已完成 → 把覆盖挂到同切片下一个待处理任务如 T04切片内已无任务 → 挂到执行平面上下一个排程任务。false调度器暂停执行平面用户响应前不推进任何工作。源码中claimOverrideForInjectionescalation.ts实现了 carry-forward 注入的原子认领先查未应用的覆盖findUnappliedEscalationOverride认领前先校验工件文件避免坏文件导致 DB 行被标记为已应用而永久吞掉覆盖认领通过 DB UPDATE 原子完成多调用者竞争时只有一个成功幂等。formatOverrideBlock生成注入块的 Markdown包含稳定 option id 供下游提示词与解析器做机器可读引用并要求将用户的决策作为当前任务的硬约束若与任务计划冲突在摘要中说明冲突而非静默偏离。3.4 与 Audit Plane 的集成每次升级都会在审计账本中记录三个阶段升级创建timestamp、question、options、recommendation用户响应timestamp、chosen option、override status决策持久化DECISIONS.md 条目source:escalation。源码对应writeEscalationArtifact、resolveEscalation中分别发出的escalation-manual-attention-created、escalation-user-responded、escalation-rejected-to-blocker审计事件escalation.ts。3.5 CLI 交互/gsd escalate除了通知面板升级也可通过 CLI 管理commands/handlers/escalate.ts/gsd escalate — manage mid-execution escalations (ADR-011 Phase 2) Subcommands: list [--all] show pending escalations (use --all to include resolved) show taskId print the escalation artifact resolve taskId choice [rationale...] resolve an escalation — choice is an option id, accept (use recommendation), or reject-blocker (convert to a blocker and trigger slice replan)resolveEscalationescalation.ts支持三种响应accept采用推荐、直接选某个 option id、reject-blocker把升级转为 blockersetTaskBlockerSource(..., reject-escalation)下一次/gsd auto会重规划该切片。resolve的返回值包含status枚举resolved | not-found | already-resolved | invalid-choice | rejected-to-blocker其中invalid-choice会列出所有合法取值。注意命令帮助信息还提示关闭phases.mid_execution_escalation不会清除已挂起的升级——需先重新启用、逐一 resolve 再关闭否则产生积压。四、风险与缓解原文完整保留 源码印证风险缓解措施源码/机制R1渐进式规划给 DAG 调度器增加新节点类型refine节点在机制上与plan-slice完全相同——派发到 prompt builder 并写 PLAN.md唯一区别是收到的上下文sketch 前序摘要 vs roadmap 条目。调度器按标准单元与标准 gate 要求处理见 refine-slice.md 与 auto-dispatch.tsR2sketch 对精化器过于模糊sketch 包含 title、goal、risk、dependencies、rough scope2-3 句、key constraints精化器把 sketch 视为范围约束并在其内规划既有 plan-gate 校验保证精化后计划在开始执行前达到质量标准R3升级造成通知疲劳execute-task提示词约束升级条件仅当答案实质影响下游任务且无法从任务计划、CONTEXT.md、DECISIONS.md 或代码库证据推导时才升级升级格式强制 options权衡推荐执行器必须分析后才能升级R4continueWithDefault: true超时造成分歧用户延迟选择后的修正只向前传播注入当前任务 carry-forward否则注入同切片下一个待处理任务再否则注入执行平面下一个排程任务对不可接受分歧的关键决策执行器应设continueWithDefault: false偏好escalation_default_pause: true可全局强制R5与 ADR-003pipeline 简化的交互兼容合并后的 plan-milestone 会话产出 S01 详细 S02 sketchrefine节点用更好上下文运行同一规划提示词升级正交——在既有 blocker 机制旁增加暂停机制R6并行任务并发升级通知面板按到达顺序排队每个升级独立用户逐个解决调度器只暂停发起升级的那个执行分支其他无升级的并行分支不受影响R7升级工件持久化失败原子文件操作写临时文件再 rename任务失败后工件缺失按标准失败重试处理升级意图在文件写入前已记入审计账本提供恢复信号对应writeEscalationArtifact先审计后落盘的顺序见 escalation.tsR8continueWithDefault: true的竞态修正只向前传播已完成任务不回溯覆盖注入下一任务的 carry-forward 向前调整方向对需要追溯修正的决策应设continueWithDefault: false五、备选方案回顾为何拒绝ADR 评估了四个备选方案并逐一拒绝A. 保留全量规划改进 reassess-roadmap让 reassess-roadmap 用前序切片摘要对比具体下一个切片的计划——拒绝这是事后发现陈旧而非事前预防refine-slice 方案避免了在 S01 尚未交付时精细规划 S04。B. 升级仅做偏好配置不集成调度器allow_escalation偏好只在 execute-task 加指令——拒绝没有manual-attention门控集成升级只是建议性的——执行器写 JSON 但继续前进价值在于暂停而非通知。C. 用 blocker 机制承载升级用元数据重载blocker_discovered: true表达是问题、不是计划失效——拒绝blocker 触发整个切片重规划而升级应恢复当前任务而非重规划重载会污染 Gate Plane 失败重试矩阵。D. 只规划 S01不写 S02 sketch——拒绝roadmap 仍需高层分解供用户在讨论阶段审批sketch 正是已获批的范围约束精化器在约束内工作。六、实施状态、行动项与遗留问题6.1 两阶段实施状态已交付摘自 ADR 状态表Phase 1 — Progressive Planning构件证据路径Schemais_sketchsketch_scope列db-base-schema.tsplan-milestone 提示词中的渐进式规划章节plan-milestone.md执行器 3 值isSketchON CONFLICT 语义plan-milestone.ts偏好phases.progressive_planningtypes.ts、preferences-validation.ts状态推导is_sketch1 → phase:refiningstate.tsROADMAP[sketch]徽标markdown-renderer.tsPR #5763Phase 2 — Mid-Execution Escalation构件证据路径升级工件类型types.ts升级工件 I/Oescalation.tsGate Planemanual-attention接线与缺省回退gate-runner.tsrefine-slice提示词 buildRefineSlicePromptrefine-slice.md、auto-prompts.tsrefining → refine-slice或降级plan-slice派发auto-dispatch.tsPLAN 写入后的is_sketch自动清除sketch-flag.tssketchFlagHandler注册于 DRIFT_REGISTRY各构件隔离测试12 个测试progressive-planning.test.ts遗留#5754覆盖完整链路sketch → refining → dispatch → PLAN 写入 → drift 清除 → execute-task的端到端测试目前各构件为隔离测试升级派发与完成时的 UOK 审计事件category: plantype: refine-slice-start / refine-slice-complete。6.2 行动项清单Phase 11-9 项sketch 格式进 plan-milestone 模板sketch 检测进状态推导UokNodeKind扩展refine调度器派发逻辑更新Execution Plane DAG 增加 refine 节点buildRefineSlicePrompt()内联前序摘要发现sketchrefine-slice 提示词模板refined 计划走 plan-gate 校验sketch 检测/refine 派发/计划质量测试。Phase 210-18 项T##-ESCALATION.jsonschemaexecute-task 增加升级指令介于 guess 与 blocker 之间映射 Gate Planemanual-attentionpost-unit 处理中检测升级通知面板交互式展示用户响应注入 carry-forwardgsd_decision_savesource 标记escalationAudit Plane 账本事件升级暂停/响应注入/continueWithDefault行为/审计轨迹测试。Phase 3 集成测试19-26 项3 切片里程碑端到端验证 refine-slice 吸收前序发现执行器写 ESCALATION.json → 调度器暂停 → 用户响应 → 恢复同一任务中升级blocker 共存blocker 优先与 ADR-009 控制面契约交互并行升级排队与仅升级分支暂停continueWithDefault: true超时晚响应的覆盖注入位置工件写失败与恢复原子写、审计回退、重试refine 节点延迟基准对比直接 plan-slice。6.3 开放问题sketch 是否应包含粗略任务数约 3 个任务能给精化器范围信号但可能过度约束**升级是否应有每里程碑上限**一个里程碑出现 10 次升级暗示计划质量不足——系统是否应检测并建议重规划**continueWithDefault是否应可配置为偏好级别**有些用户希望所有升级都暂停安全另一些希望全部继续快速。七、使用方式小结在 gsd-2 中启用并观察这两项能力启用渐进式规划在.gsd/PREFERENCES.md的phases下设置progressive_planning: true严格布尔校验见 preferences-validation.ts。此后plan-milestone只完整分解 S01S02 以isSketch: truesketchScope声明为草图ROADMAP 中可见[sketch]徽标。启用执行中升级设置phases.mid_execution_escalation: true。执行器在任务歧义时写出T##-ESCALATION.json门控回退为manual-attention通过/gsd escalate list / show / resolve或通知面板响应。resolve 时accept采纳推荐、选 option id 指定具体选项、reject-blocker转 blocker 触发切片重规划。偏好切换的边界行为progressive_planning中途关闭时调度规则优雅降级为plan-slice并把sketch_scope作为 soft hint 传入auto-dispatch.tsmid_execution_escalation关闭不会清除已挂起的升级需要重新启用后逐一解决。参考与延伸决策原文ADR-011 Progressive Planning and Mid-Execution Escalation上游架构ADR-009 Orchestration Kernel Refactor、ADR-003 Pipeline Simplification用户侧操作auto-mode 文档 与 mintlify 版 auto-mode 指南相关数据模型docs/db-map.md、docs/prompt-map.md赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐Vue.js渐进式迁移从Vue 2到Vue 3的升级指南Vue.js渐进式迁移从Vue 2到Vue 3的升级指南 你是否正面临Vue 2项目升级的困境担心重构风险太高本文将带你通过官方迁移工具 vue/com前端Web框架GSD 规划文档分类引擎 gsd-doc-classifier 深度解析从 ADR/PRD/SPEC/DOC 到结构化智能档案GSD 规划文档分类引擎 gsd doc classifier 深度解析从 ADR/PRD/SPEC/DOC 到结构化智能档案 导读 get shit don人工智能AI 应用提示工程开发工具工作流自动化AI AgentEgg2 升级指南从 Generator 到 Async 的渐进式迁移实战Egg2 升级指南从 Generator 到 Async 的渐进式迁移实战 随着 Node.js 8 LTS 的发布ES2017 的 Async Func后端Web框架上一篇终极指南使用GitHub Actions与Vercel自动化部署giscus评论系统下一篇如何在SSVM边缘环境中实现高效gRPC通信告别微服务通信痛点的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考