【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本篇文章以变更记录 .changeset/archived/sturdy-rams-forage.mdtype: FixedPR #3329为骨架展开深入讲解 gsd-core 在 execute-phase 中引入的执行器停滞检测executor stall detection与安全恢复契约safe-resume contracts当一次执行被中断、执行器在写完实现提交却未提交SUMMARY.md时下一次运行如何在不盲目重新派发执行器的前提下先暴露部分计划漂移partial-plan drift。读完本文你将掌握相关配置项、恢复路径、底层判定规则以及对应的测试与排查手段。这篇变更记录在讲什么.changeset/archived/sturdy-rams-forage.md全文只有一句主旨Add executor stall detection and safe-resume contracts so interrupted execute-phase runs surface partial-plan drift before dispatching duplicate executor work.翻译过来即为 execute-phase 增加执行器停滞检测与安全恢复契约使得被中断的执行能够在派发重复执行器工作之前先暴露部分计划漂移。这属于典型的崩溃恢复正确性补丁——它不是新增一个功能开关而是定义了一条运行时不变量在提交了生产代码但没有提交SUMMARY.md的情况下恢复执行必须先识别并处理这个半完成状态绝不能直接再派发一个执行器把工作重做一遍。在 gsd-core 的规划工件模型中一个计划的合法收尾顺序是固定的见 gsd-core/workflows/execute-plan.md 的atomic_close_out_invariantproduction-code commit(s) - SUMMARY commit - STATE/ROADMAP update对于同步执行器唯一合法的半状态half-state是正在生产提交过程中mid-production-commits。一旦某个计划的实现提交已经存在执行器却带着未提交的SUMMARY.md返回就构成了非法的部分计划状态illegal partial-plan state——而下一次 execute-phase 恢复时必须先检测到这个状态再派发新执行器正是 PR #3329 定义的契约。问题背景被中断的 execute-phase 为何会产生重复工作在 gsd-core 中execute-phase 会按照波次wave并行派发多个gsd-executor子代理执行计划gsd-core/workflows/execute-phase.md 的execute_waves步骤。执行器可以在harness-worktree、orchestrator-worktree或none内联顺序执行三种隔离模式下运行详见 gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md 的ISOLATION分支表。一次执行中断可能发生在任意时刻子代理会话被中断、终止、关闭、被杀、超时或turn_aborted。若中断恰好落在生产提交已经落盘、但SUMMARY.md尚未写入的窗口内仓库就遗留了一个部分计划计划的实际代码变更已经在 git 历史中形如feat(01-02): ...的提交但计划的SUMMARY.md缺失导致STATE.md/ROADMAP.md中的进度与实际产物不一致。如果恢复运行时不检查这个状态就直接重新派发执行器新执行器会在旧提交之上再做一遍同样的事造成重复工作、冲突甚至历史污染。这正是 safe-resume 契约要拦截的场景。机制一可配置的执行器停滞检测配置项停滞检测通过两个配置键控制定义在 docs/CONFIGURATION.md默认值同时注册在 src/config.cts 与 gsd-core/bin/shared/config-schema.manifest.json配置键类型默认值说明executor.stall_detect_interval_minutesnumber5执行器活跃期间两次停滞检查之间的间隔分钟数。execute-phase 编排器按此节奏检查近期提交避免对沉默的执行器无限等待。executor.stall_threshold_minutesnumber10执行器既无完成信号、预期分支上也无提交活动持续达到该分钟数后execute-phase 提供针对可能停滞执行器的恢复选项。两个键都已纳入配置 Schema 的validKeys可用gsd_run query config-get key --raw读取execute-phase 正是这样做的也可用gsd config-set key value调整项目文档中planner.stall_detection_enabled展示了同样的设置方式见 docs/CONFIGURATION.md。等待循环中的停滞监视在 execute-phase 步骤 4等待波次内所有代理完成时gsd-core/workflows/execute-phase.md编排器先读取配置EXECUTOR_STALL_INTERVAL_MINUTES$(gsd_run query config-get executor.stall_detect_interval_minutes --raw 2/dev/null || echo 5) EXECUTOR_STALL_THRESHOLD_MINUTES$(gsd_run query config-get executor.stall_threshold_minutes --raw 2/dev/null || echo 10)然后进入停滞监视循环每EXECUTOR_STALL_INTERVAL_MINUTES分钟检查一次git log ${EXPECTED_BRANCH} --since${DISPATCH_TS}自派发时间戳以来预期分支上是否有新提交。当满足以下全部条件时暂停并询问用户选择恢复路径没有收到完成信号没有SUMMARY.md预期分支上超过EXECUTOR_STALL_THRESHOLD_MINUTES分钟没有新提交。提供的三条恢复路径为选项含义continue waiting继续等待不做任何干预kill and retry终止当前执行器并在干净环境中重试是彻底重启不是催促kill and switch to inline execution终止并切换到内联执行注意它会直接编辑主工作区需要显式确认值得注意的实现细节是停滞检查依赖DISPATCH_TS派发时间戳与EXPECTED_BRANCH预期分支而不是依赖对本地进程的观测——这一点与下文一个在工作中的执行器永远不会被指挥的判定规则互为表里。停滞阈值度量的是无进展时长而非总运行时长gsd-core/workflows/execute-phase/steps/executor-progress-policy.md#4218明确规定停滞阈值度量的是没有有意义的进展的时间段既不是最大总运行时长也不是执行器必须在其内完成的时间预算。一个带有长验证或收尾尾巴的计划合法地在最后一次提交与SUMMARY.md之间度过很多分钟。该策略给出了三条硬性规则提交存在且SUMMARY.md缺失但有近期有意义的活动 → 继续保持等待不得指挥、不得打断、不得重新派发。近期 RED/GREEN/REFACTOR 提交、通过的验证、来自子代理的推理/工具遥测都属于有意义的活动。只有在${EXECUTOR_STALL_THRESHOLD_MINUTES}分钟内毫无有意义进展之后——从最后一次进展迹象算起而不是从派发算起——暂停才允许触发且它询问用户不自行行动。尽快收尾你现在太慢了一类的催促信息被禁止它们在验证中途到达会把一次正确的运行变成一次被截断的运行。若必须停止执行器第 3 步的暂停是唯一途径。同时本地没有可见的 OS 测试/构建进程并不等于空闲原生子代理运行在运行时自身的会话中不是可见的本地进程执行器在两次工具调用之间推理、读文件、等待运行时往返根本不显示任何进程。判定进展只能依据本工作流点名的信号预期分支上的提交、SUMMARY.md、以及子代理自身的活动——进程列表不是其中之一。机制二safe-resume gate 与部分计划漂移暴露恢复门的位置与判定safe-resume gate 是 execute-phase 的第一个执行步骤step namesafe_resume_gate见 gsd-core/workflows/execute-phase.md在信任STATE.md或派发任何执行器之前运行。它从INIT中活跃的未完成计划推导CURRENT_PLAN_ID然后搜索近期历史SUMMARY_PATH{phase_dir}/{plan_padded}-SUMMARY.md # #4003: 提交协议中没有补零规则因此对两部分都去零并在提交范围内做锚定匹配 # 同时以最新的可达 tag里程碑标记为界。 PHASE_NUMBER{phase_number} PHASE_INT${PHASE_NUMBER%%[!0-9]*}; PHASE_REST${PHASE_NUMBER#$PHASE_INT} PHASE_N$((10#$PHASE_INT))${PHASE_REST//./\\.} PLAN_N$((10#{plan_padded})) PLAN_SCOPE_RE^[a-z]\((0*${PHASE_N})-(0*${PLAN_N})\): MILESTONE_BASE$(git describe --tags --abbrev0 2/dev/null || echo ) PLAN_COMMITS$(git log --oneline -E ${MILESTONE_BASE:$MILESTONE_BASE..HEAD} --grep${PLAN_SCOPE_RE} -30)这里的PLAN_SCOPE_RE是一个锚定、零填充容忍的计划作用域正则^[a-z]\((0*PHASE_N)-(0*PLAN_N)\):。它只匹配当前计划 ID 自身的提交#4003修复过一个缺陷早期实现用未锚定的、带填充的计划作用域去 grep导致引用了其他里程碑的提交却永远匹配不到计划自己的提交。同时阶段号可能带小数段如01.1或字母后缀如03A因此只对前导整数段做零剥离其余部分按转义点号字符串参与 ERE#4619/#4748。当满足以下条件时在派生新执行器之前停止存在生产提交并且SUMMARY.md缺失并且没有匹配的.planning/async-jobs/*.json清单若有匹配则是合法的external_job_waiting延期须按 docs/reference/planning-artifacts.md 对账绝不重新派发。继续下去的风险是重复工作以及STATE.md/ROADMAP 进度陈旧。恢复门提供三个恢复选项选项做法close out manually人工检查提交、撰写SUMMARY.md再更新 STATE/ROADMAPre-execute from scratch在派发新执行器之前回退或取代部分提交mark-and-skip记录该异常并继续但必须获得用户显式确认用户手册中同样记载了这三种选项见 docs/how-to/debug-a-failed-execution.md 的 If the executor committed code but did not write SUMMARY.md 一节以及 docs/how-to/execute-a-phase.md。原子收尾不变量safe-resume gate 的判定依据来自 gsd-core/workflows/execute-plan.md 中形式化的atomic_close_out_invariant唯一的完整收尾顺序是生产提交 - SUMMARY 提交 - STATE/ROADMAP 更新一旦某计划的实现提交存在执行器不提交SUMMARY.md就返回即构成非法部分计划状态下一次 execute-phase 恢复必须先检测到它再派发另一个执行器。契约中还保留了一个异步例外external_job_waiting见下文合法延期一节。完成对账先对账后分类safe-resume gate 处理的是下一次运行的入口而在同一次运行的波次等待阶段gsd-core/workflows/execute-phase/steps/completion-reconciliation.md#4217定义了完成对账策略核心原则是先对账reconcile后分类classify子代理会话如何结束只是关于传输层的记账而它写到磁盘和 git 的内容才是关于工作的证据。对账会按波次中的每个计划运行两个探针SUMMARY_EXISTS$(test -f {phase_dir}/{plan_number}-{plan_padded}-SUMMARY.md echo true || echo false) # #4003: 锚定、零填充容忍的作用域与 safe_resume_gate 一致--since 保留。 COMMITS_FOUND$(git log --oneline --all -E --grep^[a-z]\((0*${SPOT_PHASE_N})-(0*${SPOT_PLAN_N})\): --since1 hour ago | head -1) COMMITS_SINCE_DISPATCH$(git log ${EXPECTED_BRANCH} --since${DISPATCH_TS} --oneline | head -1)判定结论verdictSUMMARY.md存在且找到匹配提交→ 计划视为完成即使没有收到子代理的终止响应也无需再等直接进入步骤 5不要为此计划重新派发新执行器工作已提交第二个执行器会在自己之上重做。合理等待后SUMMARY.md仍不存在→ 执行器可能仍在运行或已静默失败。检查git log --oneline -5若提交仍在出现继续等待若无活动将计划报告为失败并进入失败处理器。证据必须二者兼备只有SUMMARY.md而无匹配提交、或只有匹配提交而无SUMMARY.md都是不完整证据绝不基于其中之一自动完成。异常结束时若对账不到完成证据保持失败状态交给下一次运行的 safe-resume gate 处理任何未总结的提交。该策略适用于每种运行时与每条隔离路径harnessAgent()派发、orchestrator-worktree 进程派生、顺序派发并且绝不无限期阻塞等待信号而是通过文件系统与 git 状态验证。边界与例外external_job_waiting 合法延期safe-resume 契约有一个被显式承认的合法例外。当执行器派发了一个异步外部任务长时间计算如 HPC 求解器/训练任务时它提交一个.planning/async-jobs/job.json清单并返回——没有SUMMARY.md。此时无 SUMMARY状态是合法的延期状态external_job_waiting而非非法的部分计划状态SUMMARY.md被推迟到外部任务达到终止状态、且其expected_artifacts通过验证之后。恢复运行execute-phase safe-resume、resume-project、pause-work会针对清单对账而不是重新派发——重新派发会复制外部计算。该清单是带版本的稳定性契约详见 docs/reference/planning-artifacts.md 与 docs/how-to/async-external-jobs.md。这一机制的引入在 CHANGELOG.md 中有完整记载#1165 / #1221它正是 safe-resume 契约中有清单匹配 → 合法延期 → 绝不重新派发那条分支的实现基础。测试验证契约的可执行证据PR #3329 引入的契约在 tests/config.test.cjs 中由一组专门的测试锁定该组由tests/bug-3212-execute-phase-stall-safe-resume.test.cjs折叠而来归属整合史诗 #1969Schema 注册executor.stall_detect_interval_minutes与executor.stall_threshold_minutes必须同时存在于 CJS 运行时的VALID_CONFIG_KEYS与 SDK 侧的 manifestvalidKeys中文档默认值docs/CONFIGURATION.md必须记载5与10两个默认值config-get 实读在空.planning/config.json上运行config-get两个键必须分别返回5与10safe-resume gate 存在性与锚定正则execute-phase 必须定义safe_resume_gate步骤必须包含锚定的PLAN_SCOPE_RE^[a-z]\((0*${PHASE_N})-(0*${PLAN_N})\):、--grep${PLAN_SCOPE_RE}、SUMMARY.md is missing检测以及close out manually/re-execute from scratch/mark-and-skip三个恢复选项停滞监视execute-phase 必须读取两个配置键、记录DISPATCH_TS与EXPECTED_BRANCH、执行git log ${EXPECTED_BRANCH} --since${DISPATCH_TS}并提供continue waiting/kill and retry/kill and switch to inline execution原子收尾不变量execute-plan 必须包含atomic_close_out_invariant并命名合法收尾序列与唯一合法半状态取证联动gsd-core/workflows/forensics.md 必须包含部分计划漂移检测Partial-plan Drift Detection其信号正是提交存在但SUMMARY.md缺失并复用 safe-resume 验证器的同一比较逻辑识别活跃计划 → 按计划 ID 搜索 git 历史 → 与预期SUMMARY.md路径对比。这些测试把契约必须存在变成可机械验证的断言防止未来重构悄悄删掉恢复门或改掉恢复选项。调参与排查实践结合上述机制遇到执行被中断场景时的排查路径如下看 git 历史区分完成度git log --oneline -20。已提交工作的计划会有feat(01-02): ...形式的条目无提交的计划会在下次运行时被重新执行docs/how-to/debug-a-failed-execution.md。执行器提交了代码但没写SUMMARY.md下一次运行会命中 safe-resume gate此时选择close out manually人工补写SUMMARY.md后重跑、re-execute from scratch先回退/取代部分提交再派发或mark-and-skip显式确认后继续。怀疑执行器停滞检查executor.stall_threshold_minutes默认 10 分钟与executor.stall_detect_interval_minutes默认 5 分钟是否适合你的执行器节奏长时间验证/收尾计划应调高阈值因为阈值度量的是无进展时长而非总运行时长。主动诊断漂移在取证工作流forensics中提交存在但SUMMARY.md缺失被标记为高置信度的部分计划漂移异常通常意味着执行器在实现提交之后、原子收尾之前被打断gsd-core/workflows/forensics.md。留意合法延期若.planning/async-jobs/job.json清单存在且任务未达终止状态SUMMARY.md缺失是合法的external_job_waiting状态恢复会针对清单对账不应人工补写或强制重跑。此外编排侧的研究文档建议将运行时速率限制信号如rejected与executor.stall_threshold_minutes#3329结合使编排器在运行时已经发出拒绝信号时不必等待完整的停滞间隔docs/research/provider-rate-limit-signals.md——这说明停滞检测的设计从一开始就为等待成本与及时恢复之间的权衡保留了调整空间。小结PR #3329变更记录 .changeset/archived/sturdy-rams-forage.md为 gsd-core 的 execute-phase 建立了两条互补的契约停滞检测在运行中持续观察预期分支上是否有进展并给出可配置的恢复选项safe-resume 契约在每次运行入口先验证是否存在生产提交但缺SUMMARY.md的部分计划漂移再决定派发。两者共同保证中断后的恢复优先暴露证据、与用户确认而不是盲目重做——这正是避免重复执行器工作、保持STATE.md/ROADMAP 进度与仓库实际产物一致的关键。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐gsd-core 阶段移除重编号修复phase remove --force 如何避免 ROADMAP 折叠gsd core 阶段移除重编号修复 phase remove force 如何避免 ROADMAP 折叠 导读 本篇文章讲解 gsd core 中 phasgsd-core Route 0 恢复不完整阶段resume-incomplete-phase不变量的设计与实现gsd core Route 0 恢复不完整阶段resume incomplete phase不变量的设计与实现 导读 本文深入剖析 gsd core 中由gsd-core 修复 Phase 目录 project_code 前缀漂移3298 让 import 与 backlog 工作流统一遵守目录命名约定gsd core 修复 Phase 目录 project_code 前缀漂移 3298 让 import 与 backlog 工作流统一遵守目录命名约定 本篇上一篇终极指南如何在mysql33/mysql中建立安全的SSL加密连接下一篇Obsidian Sample Plugin 模态框开发指南构建交互式界面创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考