gsd-core 修复解读：3381 修复 —— /gsd-verify-work --ws 通过 SDK 解析工作流阶段

【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本篇文章基于 .changeset/archived/fix-3381-init-verify-work-ws.mdtype: FixedPR #3386展开剖析 gsd-core 中/gsd-verify-work --ws name的缺陷根因、修复实现与回归验证。读完本文你将理解工作流workstream模式下阶段验证的目录作用域问题掌握init.verify-work、MVP 模式查询与阶段目标查询如何接收到选中工作流从而不再错误回退到根目录.planning/。一、变更速览一条 changeset 背后的问题该 changeset 全文只有一句话却指向一个真实且影响面明确的缺陷/gsd-verify-work --ws namenow resolves workstream phases through the SDK—init.verify-work, MVP-mode lookup, and phase-goal lookup all receive the selected workstream instead of falling back to root.planning/.拆解这句话可以得到三个事实修复对象是命令/gsd-verify-work --ws name即在指定工作流workstream中对某个阶段执行验证修复方式是通过 SDK 解析工作流阶段——即由 gsd-core 的查询命令query init.verify-work等承担阶段解析而不是让工作流脚本自行猜测路径修复涉及三个查询点init.verify-work初始化阶段上下文、MVP 模式查询phase.mvp-mode、阶段目标查询roadmap.get-phase修复前它们会回退到根目录.planning/修复后都接收到用户选中的工作流。这条修复之所以成立需要先理解两个背景/gsd-verify-work命令本身以及 gsd-core 的工作流workstream目录作用域模型。二、背景/gsd-verify-work 与工作流作用域2.1 verify-work 命令是做什么的命令契约定义在 commands/gsd/verify-work.md 中其 frontmatter 声明name: gsd:verify-work description: Validate built features through conversational UAT argument-hint: [phase number, e.g., 4] [--ws name] requires: [execute-phase, phase]它的职责是通过会话式 UAT 验证已构建的功能一次一个测试、纯文本回答、不搞审问式提问发现问题后自动诊断、规划修复并为执行做准备。输出为{phase_num}-UAT.md测试结果追踪文件若发现问题则产出已诊断的差距与可直接交给/gsd:execute-phase的修复计划。命令本身可带两个参数阶段号如4与--ws name工作流名。2.2 工作流模式的目录作用域gsd-core 在项目根.planning/之外支持多工作流布局。从 src/init.cts 的相关注释与实现可以看到每个工作流拥有自己的规划根.planning/workstreams/ws/其中phases/、ROADMAP.md、STATE.md、REQUIREMENTS.md都是工作流作用域的workstream-scoped例外是PROJECT.md它是跨工作流共享的PROJECT.md is shared across workstreams见 src/init.cts 中cmdInitCompleteMilestone相关注释planningDir(cwd)是工作流感知的当存在激活的工作流时它解析到该工作流的规划目录而不是根.planning/。这里的关键机制是GSD_WORKSTREAM环境变量。从 src/init.cts 的注释可以确认显式传入--ws会设置GSD_WORKSTREAM从而满足工作流模式的检查而没有激活工作流又没有--ws时planningDir(cwd)会解析到根.planning/——这正是静默报告一个过期的根里程碑的危险路径。三、缺陷根因--ws 未被 SDK 查询消费修复前的缺陷链条如下用户在/gsd-verify-work --ws name中显式指定了工作流但工作流脚本gsd-core/workflows/verify-work.md没有从$ARGUMENTS中提取--ws并转发给下游 SDK 查询于是GSD_WORKSTREAM从未被设置planningDir(cwd)继续解析到根.planning/结果是init.verify-work的阶段查找、phase.mvp-mode的 MVP 模式判定、roadmap.get-phase的阶段目标读取全部落在错误的目录上——要么找不到工作流内的阶段阶段在.planning/workstreams/ws/phases/下要么读到根目录的同名阶段/目标产生张冠李戴的验证上下文。从 src/init-command-router.cts 的注释也能印证这条边界--ws在发布的工作流中指向独立的query init.verify-work查询接口seam并在到达init verify-work命令族之前被剥离。也就是说--ws的消费点本来就在查询层工作流若不在调用查询时把它带上去它就彻底丢失。四、修复的工程实现三层收口修复将--ws从用户参数一路收口到SDK 查询参数共三层。4.1 工作流层从 $ARGUMENTS 提取 --ws 并派生阶段参数gsd-core/workflows/verify-work.md 的initialize步骤现在包含以下解析逻辑GSD_WS echo $ARGUMENTS | grep -qE -- --ws[[:space:]][A-Za-z0-9._-] GSD_WS$(echo $ARGUMENTS | grep -oE -- --ws[[:space:]][A-Za-z0-9._-]) PHASE_ARG$(echo $ARGUMENTS | sed -E s/--ws[[:space:]][A-Za-z0-9._-]//g | xargs) INIT$(gsd_run query init.verify-work ${PHASE_ARG} ${GSD_WS})要点GSD_WS默认置空只有当$ARGUMENTS中出现--ws name形态时才提取整对 token--ws连同工作流名作为GSD_WSPHASE_ARG通过sed删除--ws name后经xargs去空白得到保证阶段号参数纯净随后query init.verify-work ${PHASE_ARG} ${GSD_WS}把工作流名原样转发给 SDK 查询GSD_WS展开后即--ws name两个 token未加引号以正确分词。值得注意的细节--ws值的工作流 slug 字符类被刻意收窄为[A-Za-z0-9._-]而非宽泛的[^[:space:]]因为工作流 slug 由这些字符构成收窄可以避免误吞后续参数也保证了GSD_WS能可靠到达每一个工作流敏感的查询。4.2 SDK 查询层init.verify-work 接收工作流并解析阶段query init.verify-work由 src/init.cts 的cmdInitVerifyWork实现。收到带工作流作用域的cwd后它通过共享原语解析阶段const config loadConfig(cwd); let phaseInfo guardedFindPhase(cwd, phase, config.project_code); const roadmapPhase guardedGetRoadmapPhase(cwd, phase, config.project_code); phaseInfo applyRoadmapFallback(phaseInfo, roadmapPhase, (rp) { /* 合成回退对象 */ });guardedFindPhasesrc/init.cts封装findPhaseInternal并附加#2056外来前缀防护当查询携带了项目代码前缀而阶段不匹配时返回nullguardedGetRoadmapPhase是对路线图阶段读取的同等防护封装applyRoadmapFallbacksrc/init.cts是归档/未命中回退若磁盘阶段已归档而路线图仍有记录则置空若磁盘未命中而路线图命中则用路线图合成阶段信息phase_number、phase_name、phase_slug、空plans/summaries等。该共享回退同样被execute-phase、plan-phase、code-review、review等命令复用保证行为一致。在拿到阶段信息后cmdInitVerifyWork继续组装验证上下文phase_dir、phase_number、phase_name、has_verificationstate_path/roadmap_path经由工作流感知的planningDir(cwd)解析STATE.md、ROADMAP.md供verify-work.md的plan_gap_closure步骤读取而不是硬编码根.planning/字面量对应#2376的修复phase_completion内含buildPhaseCompletionProjection的结果implementation_complete、verification_status、verification_passed、phase_complete、verification_next_action、verification_next_command等以及 UAT 状态uat_passed、uat_blockers、ready_to_transitionui_phase_active与section_manifest供 UI 验证与mvp-uat-framing小节门控使用。正因为GSD_WS即--ws name被传到了这条查询链路GSD_WORKSTREAM得以生效planningDir(cwd)解析到.planning/workstreams/ws/findPhaseInternal才能在正确的作用域下找到阶段目录——修复前这一步恰恰回退到了根.planning/。4.3 作用域查询MVP 模式与阶段目标除了初始化查询工作流还把工作流转发给另外两个查询# MVP 模式检测集中式 phase.mvp-mode 解析器 MVP_MODE$(gsd_run query phase.mvp-mode ${phase_number} ${GSD_WS} --pick active)以及回归测试断言中的阶段目标查询gsd_run query roadmap.get-phase ${phase_number} ${GSD_WS} --pick goalphase.mvp-mode判定当前阶段是否为 MVP 模式。修复前它读取根.planning/下路线图中的**Mode:** mvp标记工作流内阶段会得到错误答案修复后工作流被转发模式判定按工作流作用域进行。工作流注释还说明verify-work没有--mvp命令行开关模式从已规划阶段继承因此查询省略--cli-flag走 roadmap → config → false 的回落链。roadmap.get-phase提取阶段目标goal。其解析依据位于 src/roadmap-parser.cts通过**Goal:**区块正则提取目标文本。该查询在verify-work的verify_phase_goal步骤中被消费——验证器gsd-verifier需要拿到正确的阶段目标与需求 ID 才能核对实现是否达标。三个查询全部拿到GSD_WS正是 changeset 中init.verify-work、MVP-mode lookup、phase-goal lookup all receive the selected workstream的落地形态。五、验证结果如何被路由verification 状态机阶段解析正确之后验证结果本身由 src/verification.cts 统一裁决。该模块是验证状态路由的唯一事实源定义在VERIFICATION_ROUTING_TABLEsrc/verification.ctsstatus语义推荐下一步passed验证通过继续gaps_found发现差距运行plan-phase N --gaps规划修复重新执行后再发布human_needed需要人工验证完成*-UAT.md中的手工测试后重跑verify-workstale覆盖的源文件在验证后发生了变化重跑execute-phase在验证门处恢复并重新运行验证器刷新 VERIFICATION.md 与摘要missing无验证报告运行execute-phase是安全的不会重跑已有 SUMMARY.md 的计划unparseable报告 frontmatter 不是合法 YAML直接修复报告中的语法错误重跑 execute-phase 无法修复unknown非标准的自定义状态若是手工标记则无需处理否则运行execute-phase重新生成验证其中passed/gaps_found/human_needed是验证器gsd-verifieragent真正会写出的值VERIFIER_STATUSESstale/missing/unparseable/unknown是内部构造的哨兵状态。next_command统一经过formatGsdSlash投影为当前运行时的命令形态如/gsd-execute-phase、$gsd-execute-phase避免硬编码废弃的/gsd:冒号形式。readVerificationStatus只读取*-VERIFICATION.mdfrontmatter中的status解析器锚定在文件字节 0正文里的status:不会误读并支持#4155引入的覆盖输入指纹covered_filescovered_digest作为比 mtime 更强的过期判定依据。这些路由结果最终通过cmdInitVerifyWork的phase_completion暴露给工作流驱动 UAT 会话与差距闭环。六、回归测试--ws 转发链路被锁死修复不是只改脚本了事还配了回归测试。当前测试位于 tests/verify-work-auto-transition.test.cjs标题即bug #3381: verify-work forwards workstream context测试注释说明它由tests/bug-3381-verify-work-workstream.test.cjs折叠而来合并史诗 #1969。该测试用正则逐条断言工作流源码中必须存在的转发契约assert.match(workflow, /GSD_WS/, verify-work must initialize GSD_WS); assert.match(workflow, /grep -qE -- --ws[[:space:]][A-Za-z0-9._-]/, verify-work must detect --ws in $ARGUMENTS); assert.match(workflow, /grep -oE -- --ws[[:space:]][A-Za-z0-9._-]/, verify-work must extract the --ws flag pair from $ARGUMENTS); assert.match(workflow, /PHASE_ARG\$\(echo \$ARGUMENTS \| sed -E s\/--ws[[:space:]][A-Za-z0-9._-]\/\/g \| xargs\)/, verify-work must derive PHASE_ARG after removing --ws); assert.match(workflow, /gsd_run query init\.verify-work \$\{PHASE_ARG\} \$\{GSD_WS\}/, init.verify-work must receive GSD_WS so phase_dir resolves in workstreams); assert.match(workflow, /gsd_run query phase\.mvp-mode \$\{phase_number\} \$\{GSD_WS\} --pick active/, phase.mvp-mode must receive GSD_WS so roadmap mode is workstream-scoped); assert.match(workflow, /gsd_run query roadmap\.get-phase \$\{phase_number\} \$\{GSD_WS\} --pick goal/, roadmap.get-phase must receive GSD_WS so goals are workstream-scoped);这份断言同时锁死了三类东西解析逻辑GSD_WS初始化、--ws检测与提取、PHASE_ARG的派生sed删除--ws name对转发对象三个工作流敏感查询必须无一遗漏地收到GSD_WS语义承诺注释明确写明了每条断言的动机——init.verify-work收到GSD_WS才能让phase_dir在工作流内正确解析phase.mvp-mode收到它路线图模式才是工作流作用域roadmap.get-phase收到它目标才是工作流作用域。任何未来的重构若删掉其中一条转发测试就会立刻失败从而防止缺陷 #3381 以回归形式复活。七、使用方式与适用前提修复后的命令形态与使用方式如下# 在根项目上验证阶段 4 /gsd-verify-work 4 # 在指定工作流 my-ws 中验证阶段 4本次修复的核心场景 /gsd-verify-work 4 --ws my-ws工作流 slug 由[A-Za-z0-9._-]字符构成--ws与工作流名之间需以空白分隔。适用前提与限制该命令依赖 gsd-core 的 SDK 查询能力gsd_run query ...需要已完成 gsd-core 安装并在$ARGUMENTS中携带阶段号或存在活跃会话工作流模式要求显式工作流无活跃工作流且未传--ws时planningDir(cwd)解析到根.planning/是旧行为请务必显式指定本修复保证的是工作流内阶段解析正确验证的裁决仍遵循 src/verification.cts 的状态机passed/gaps_found/human_needed等UAT 输出仍是{phase_num}-UAT.md差距闭环路径不变发现问题后plan_gap_closure步骤使用{state_path}、{roadmap_path}二者已由工作流感知的planningDir(cwd)解析拉起gsd-planner --gaps生成带gap_closure: true与gap_ids的计划供后续verify-work恢复时对账。结语fix-3381-init-verify-work-ws.md是一条小而完整的修复它把一个命令参数--ws通过工作流脚本的提取、SDK 查询的转发、GSD_WORKSTREAM的作用域生效最终传导到三个查询点init.verify-work、phase.mvp-mode、roadmap.get-phase彻底消除了用户明明指定了工作流、SDK 却读根.planning/的静默错误。若你的项目使用 gsd-core 的多工作流模式并在工作流内执行阶段验证请确认版本包含此修复PR #3386并在调用时始终显式传递--ws name。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐gsd-core 修复 3135/gsd-capture --backlog 路由与 add-backlog 工作流的完整实现gsd core 修复 3135 /gsd capture backlog 路由与 add backlog 工作流的完整实现 导读 /gsd capturegsd-core 修复实战init.milestone-op 与 roadmap.analyze 的 Workstream 作用域解析修复PR 3196gsd core 修复实战 init.milestone op 与 roadmap.analyze 的 Workstream 作用域解析修复PR 3196gsd-core 嵌套 Git 仓库检测修复解析/gsd-new-project 与 /gsd-ingest-docs 如何通过 git rev-parse 语义避免误建 .gitgsd core 嵌套 Git 仓库检测修复解析 /gsd new project 与 /gsd ingest docs 如何通过 git rev parse上一篇gh_mirrors/es/es6features实战对象属性遍历方法对比下一篇7步实现Druid监控数据持久化从日志到MySQL的无缝方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考