get-shit-done /gsd-graphify 内联构建修复知识图谱产物丢失的根因与结构性回归防线#3166【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done本篇聚焦 get-shit-doneGSD中/gsd-graphify build命令的一次关键修复issue #3166graphify v0.7 将构建拆分为快速 AST 提取 聚类/报告写入两个阶段后子代理隔离导致第二阶段被 SIGTERM 终止、.planning/graphs/下产物丢失的问题。读完本篇你将理解该故障的完整机制、修复后的内联前台构建链含完整命令与超时取值依据以及仓库如何用解析 skill YAML frontmatter 的结构性测试永久封禁Task子代理派生的回归手法。一、变更背景graphify v0.7 把构建拆成了两阶段GSD 通过/gsd-graphify命令在项目中维护一张位于.planning/graphs/的知识图谱命令本体定义在 commands/gsd/graphify.mdCLI 层实现在 get-shit-done/bin/lib/graphify.cjsCLI 用法记录在 docs/CLI-TOOLS.md。graphify v0.7 之后graphify update .的执行被拆成两个阶段AST 提取阶段fast AST-extraction phase速度快结果会被缓存聚类 报告写入阶段clustering report-write phase在提取完成之后独立运行最终产出graph.json、graph.html、GRAPH_REPORT.md三个工件。这个拆分本身是合理的性能优化但它把构建是否完成的判断从单一进程的生命周期转移到了调用方如何管理该进程上——这正是 #3166 故障的埋点。二、故障机制子代理隔离如何杀掉第二阶段修复前的 skill 行为是执行build时通过Task工具派生一个子代理sub-agent由子代理在后台运行 graphify 构建。问题出在 Claude Code 的子代理隔离语义上提取阶段因为带缓存而幸存子代理存活期间快速的 AST 提取阶段已经完成并写入缓存写入阶段被 SIGTERM 打断当子代理任务结束、代理退出时其后台 bash 进程收到 SIGTERM正在运行的聚类 报告写入阶段被截断最终状态极具迷惑性graphify 的缓存目录是已填充的缓存命中看起来像构建过但.planning/graphs/目录下没有graph.json、graph.html、GRAPH_REPORT.md任何一个工件落盘。后续如果再次构建缓存命中还可能让失败表现得更加隐蔽。changeset 对这一现象的原始记录见 .changeset/3166-graphify-inline-build.md。三、修复方案单条前台 Bash 链跑完整个流水线修复的核心思路是取消子代理派生把构建改为 skill 内联执行inline build并把整条流水线合并为一个前台foregroundBash 调用保证所有阶段在同一个进程树中运行、随调用一起存活到完成。3.1 前置检查pre-flight仍然走 CLI构建前先运行预检命令node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs graphify build解析其 JSON 输出disabled: true→ 显示禁用提示并停止error字段存在 → 显示错误并停止action: spawn_agent→ 预检通过进入内联构建。这里有一个容易误解的细节spawn_agent这个 action 名是历史遗留。从源码 get-shit-done/bin/lib/graphify.cjs 的graphifyBuild()可以看到它在完成配置开关检查 →graphify可执行文件存在性检查 → 版本兼容性检查 → 确保.planning/graphs/输出目录存在之后仍然返回return { action: spawn_agent, graphs_dir: graphsDir, graphify_out: path.join(cwd, graphify-out), timeout_seconds: timeoutSec, version: version.version, version_warning: version.warning, artifacts: [graph.json, graph.html, GRAPH_REPORT.md], };CLI 层刻意保持发出spawn_agent信号是为了让外部调用方和既有测试继续按原契约工作真正不再派生代理的约束落在 skill 提示词层面。artifacts字段列出的正是 #3166 中曾经丢失的三个文件。3.2 内联构建链一条命令、一个前台进程预检通过后skill 要求显示GSD Building knowledge graph...然后执行如下一条完整的 bash 链摘自 commands/gsd/graphify.mdgraphify update . \ cp graphify-out/graph.json .planning/graphs/graph.json \ cp graphify-out/graph.html .planning/graphs/graph.html \ cp graphify-out/GRAPH_REPORT.md .planning/graphs/GRAPH_REPORT.md \ node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs graphify build snapshot \ node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs graphify status这条链依次完成五件事任何一步失败非零退出整链即停步骤作用graphify update .运行完整的两阶段构建提取 聚类/报告写入产出写入graphify-out/三条cp把graph.json/graph.html/GRAPH_REPORT.md拷贝到.planning/graphs/gsd-tools.cjs graphify build snapshot写入 diff 基线快照.last-build-snapshot.json供后续diff模式使用gsd-tools.cjs graphify status输出末尾的 JSON 状态摘要供 skill 解析后展示节点/边/超边计数关于超时取值skill 中给出了明确依据整条链使用timeout: 600000ms10 分钟因为 CLI 侧build_timeout的配置上限默认为 300 秒——见 get-shit-done/bin/lib/graphify.cjs// Read build timeout from config -- default 300s per D-02 const config safeReadJson(path.join(planningDir, config.json)) || {}; const timeoutSec (config.graphify config.graphify.build_timeout) || 300;10 分钟的外层超时覆盖了graphify.build_timeout默认 300 s并留出余量同时容纳了三份文件拷贝、快照写入与 status 查询。skill 同时给出两条硬性约束commands/gsd/graphify.md 的 Anti-Patterns 一节不得对构建链传run_in_background: true——典型构建 15–60 秒即可完成整条链必须前台运行链失败时不得删除.planning/graphs/——上一次的有效图谱仍可供使用skill 应显示## GRAPHIFY BUILD FAILED加捕获到的 stderr 后停止。从源码结构看graphify子命令并未注册进gsd-sdk query而是 CJS-only 工具统一通过node gsd-tools.cjs graphify …调用见 docs/CLI-TOOLS.md 与命令头部的 CJS-only 声明。3.3 配置门Config Gate所有 graphify 操作前置一个配置检查用 Read 工具直接读.planning/config.json仅当config.graphify.enabled true时才继续。skill 明确要求不要使用gsd-tools config get-value做这一步检查因为该命令在 key 缺失时会硬退出hard-exit。CLI 侧的判断逻辑在 get-shit-done/bin/lib/graphify.cjs 的isGraphifyEnabled()无配置、无graphify键或读取出错时一律返回false即默认禁用。四、结构性回归测试解析 frontmatter 封禁 Taskchangeset 强调修复不止是改提示词还新增了结构性回归测试解析 skill 的 YAML frontmatter防止Task被重新加入allowed-tools。对应实现位于 tests/graphify-visualization.test.cjs其策略值得借鉴解析而非字符串匹配测试把 commands/gsd/graphify.md 解析成 (a) 一份 YAML frontmatter 键值映射含列表项(b) 正文中所有 fenced code block 列表断言全部针对解析后的结构执行避免被措辞变化绕开。封禁子代理派生断言allowed-tools必须是块列表、非空且不得包含Task——测试注释直接引用了 #3166 的故障机理sub-agent isolation truncates graphify v0.7 post-extraction phase。保留内联构建前置条件断言allowed-tools仍包含Read配置门需要和Bash内联构建链需要。封禁代码块内的Task(调用语法遍历所有 fenced block任何代码块内容包含Task(即失败注释明确说明正文提到 Task 一词没有问题禁止的只是代码块中的调用表达式——即只封调用语法不封散文词汇。正向锚定修复行为断言存在 bash 代码块且其中包含graphify update .与gsd-tools.cjs … graphify build snapshot确保内联流水线不会被改回去。这套把提示词当源码来测的做法本质上是把 #3166 的教训固化成了可执行不变量只要有人试图恢复Task派生CI 会立刻失败。五、实操要点与适用前提结合 changeset、skill 与源码实际使用/gsd-graphify build时需要注意前置条件graphifyCLI 需已安装源码中给出的安装提示为uv pip install graphifyy graphify install见 get-shit-done/bin/lib/graphify.cjs版本经测试的区间为0.4.0,1.0checkGraphifyVersion()不在此区间会带 warning 但流程继续。超时预算CLI 侧默认build_timeout300 s可通过.planning/config.json的graphify.build_timeout调整skill 外层固定 600 s。失败语义构建链失败时旧的.planning/graphs/保留不动graphify status会在后续操作中显示 STALE/FRESH 指示。兼容性契约graphify build预检仍返回action: spawn_agent依赖该字段的旧调用方与既有测试不受本次修复影响但 skill 层的所有操作build / query / status / diff均已内联执行不再派生任何代理。六、小结#3166 的修复看似只是把后台子代理改成前台 Bash实际解决的是一个通用的 Agent 工程问题当底层工具把长任务拆分为可缓存的多阶段流水线后由谁保证第二阶段不被宿主环境的进程隔离机制杀掉。get-shit-done 的解法是把进程生命周期收拢到前台调用内用链保证原子性推进用解析 frontmatter 与代码块的结构性测试把不得派生子代理固化为可回归的不变量——这三层内联执行、超时留余量、结构测试封禁缺一不可。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 get-shit-done /gsd-graphify 内联构建修复：知识图谱产物丢失的根因与结构性回归防线（3166）
get-shit-done /gsd-graphify 内联构建修复知识图谱产物丢失的根因与结构性回归防线#3166【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done本篇聚焦 get-shit-doneGSD中/gsd-graphify build命令的一次关键修复issue #3166graphify v0.7 将构建拆分为快速 AST 提取 聚类/报告写入两个阶段后子代理隔离导致第二阶段被 SIGTERM 终止、.planning/graphs/下产物丢失的问题。读完本篇你将理解该故障的完整机制、修复后的内联前台构建链含完整命令与超时取值依据以及仓库如何用解析 skill YAML frontmatter 的结构性测试永久封禁Task子代理派生的回归手法。一、变更背景graphify v0.7 把构建拆成了两阶段GSD 通过/gsd-graphify命令在项目中维护一张位于.planning/graphs/的知识图谱命令本体定义在 commands/gsd/graphify.mdCLI 层实现在 get-shit-done/bin/lib/graphify.cjsCLI 用法记录在 docs/CLI-TOOLS.md。graphify v0.7 之后graphify update .的执行被拆成两个阶段AST 提取阶段fast AST-extraction phase速度快结果会被缓存聚类 报告写入阶段clustering report-write phase在提取完成之后独立运行最终产出graph.json、graph.html、GRAPH_REPORT.md三个工件。这个拆分本身是合理的性能优化但它把构建是否完成的判断从单一进程的生命周期转移到了调用方如何管理该进程上——这正是 #3166 故障的埋点。二、故障机制子代理隔离如何杀掉第二阶段修复前的 skill 行为是执行build时通过Task工具派生一个子代理sub-agent由子代理在后台运行 graphify 构建。问题出在 Claude Code 的子代理隔离语义上提取阶段因为带缓存而幸存子代理存活期间快速的 AST 提取阶段已经完成并写入缓存写入阶段被 SIGTERM 打断当子代理任务结束、代理退出时其后台 bash 进程收到 SIGTERM正在运行的聚类 报告写入阶段被截断最终状态极具迷惑性graphify 的缓存目录是已填充的缓存命中看起来像构建过但.planning/graphs/目录下没有graph.json、graph.html、GRAPH_REPORT.md任何一个工件落盘。后续如果再次构建缓存命中还可能让失败表现得更加隐蔽。changeset 对这一现象的原始记录见 .changeset/3166-graphify-inline-build.md。三、修复方案单条前台 Bash 链跑完整个流水线修复的核心思路是取消子代理派生把构建改为 skill 内联执行inline build并把整条流水线合并为一个前台foregroundBash 调用保证所有阶段在同一个进程树中运行、随调用一起存活到完成。3.1 前置检查pre-flight仍然走 CLI构建前先运行预检命令node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs graphify build解析其 JSON 输出disabled: true→ 显示禁用提示并停止error字段存在 → 显示错误并停止action: spawn_agent→ 预检通过进入内联构建。这里有一个容易误解的细节spawn_agent这个 action 名是历史遗留。从源码 get-shit-done/bin/lib/graphify.cjs 的graphifyBuild()可以看到它在完成配置开关检查 →graphify可执行文件存在性检查 → 版本兼容性检查 → 确保.planning/graphs/输出目录存在之后仍然返回return { action: spawn_agent, graphs_dir: graphsDir, graphify_out: path.join(cwd, graphify-out), timeout_seconds: timeoutSec, version: version.version, version_warning: version.warning, artifacts: [graph.json, graph.html, GRAPH_REPORT.md], };CLI 层刻意保持发出spawn_agent信号是为了让外部调用方和既有测试继续按原契约工作真正不再派生代理的约束落在 skill 提示词层面。artifacts字段列出的正是 #3166 中曾经丢失的三个文件。3.2 内联构建链一条命令、一个前台进程预检通过后skill 要求显示GSD Building knowledge graph...然后执行如下一条完整的 bash 链摘自 commands/gsd/graphify.mdgraphify update . \ cp graphify-out/graph.json .planning/graphs/graph.json \ cp graphify-out/graph.html .planning/graphs/graph.html \ cp graphify-out/GRAPH_REPORT.md .planning/graphs/GRAPH_REPORT.md \ node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs graphify build snapshot \ node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs graphify status这条链依次完成五件事任何一步失败非零退出整链即停步骤作用graphify update .运行完整的两阶段构建提取 聚类/报告写入产出写入graphify-out/三条cp把graph.json/graph.html/GRAPH_REPORT.md拷贝到.planning/graphs/gsd-tools.cjs graphify build snapshot写入 diff 基线快照.last-build-snapshot.json供后续diff模式使用gsd-tools.cjs graphify status输出末尾的 JSON 状态摘要供 skill 解析后展示节点/边/超边计数关于超时取值skill 中给出了明确依据整条链使用timeout: 600000ms10 分钟因为 CLI 侧build_timeout的配置上限默认为 300 秒——见 get-shit-done/bin/lib/graphify.cjs// Read build timeout from config -- default 300s per D-02 const config safeReadJson(path.join(planningDir, config.json)) || {}; const timeoutSec (config.graphify config.graphify.build_timeout) || 300;10 分钟的外层超时覆盖了graphify.build_timeout默认 300 s并留出余量同时容纳了三份文件拷贝、快照写入与 status 查询。skill 同时给出两条硬性约束commands/gsd/graphify.md 的 Anti-Patterns 一节不得对构建链传run_in_background: true——典型构建 15–60 秒即可完成整条链必须前台运行链失败时不得删除.planning/graphs/——上一次的有效图谱仍可供使用skill 应显示## GRAPHIFY BUILD FAILED加捕获到的 stderr 后停止。从源码结构看graphify子命令并未注册进gsd-sdk query而是 CJS-only 工具统一通过node gsd-tools.cjs graphify …调用见 docs/CLI-TOOLS.md 与命令头部的 CJS-only 声明。3.3 配置门Config Gate所有 graphify 操作前置一个配置检查用 Read 工具直接读.planning/config.json仅当config.graphify.enabled true时才继续。skill 明确要求不要使用gsd-tools config get-value做这一步检查因为该命令在 key 缺失时会硬退出hard-exit。CLI 侧的判断逻辑在 get-shit-done/bin/lib/graphify.cjs 的isGraphifyEnabled()无配置、无graphify键或读取出错时一律返回false即默认禁用。四、结构性回归测试解析 frontmatter 封禁 Taskchangeset 强调修复不止是改提示词还新增了结构性回归测试解析 skill 的 YAML frontmatter防止Task被重新加入allowed-tools。对应实现位于 tests/graphify-visualization.test.cjs其策略值得借鉴解析而非字符串匹配测试把 commands/gsd/graphify.md 解析成 (a) 一份 YAML frontmatter 键值映射含列表项(b) 正文中所有 fenced code block 列表断言全部针对解析后的结构执行避免被措辞变化绕开。封禁子代理派生断言allowed-tools必须是块列表、非空且不得包含Task——测试注释直接引用了 #3166 的故障机理sub-agent isolation truncates graphify v0.7 post-extraction phase。保留内联构建前置条件断言allowed-tools仍包含Read配置门需要和Bash内联构建链需要。封禁代码块内的Task(调用语法遍历所有 fenced block任何代码块内容包含Task(即失败注释明确说明正文提到 Task 一词没有问题禁止的只是代码块中的调用表达式——即只封调用语法不封散文词汇。正向锚定修复行为断言存在 bash 代码块且其中包含graphify update .与gsd-tools.cjs … graphify build snapshot确保内联流水线不会被改回去。这套把提示词当源码来测的做法本质上是把 #3166 的教训固化成了可执行不变量只要有人试图恢复Task派生CI 会立刻失败。五、实操要点与适用前提结合 changeset、skill 与源码实际使用/gsd-graphify build时需要注意前置条件graphifyCLI 需已安装源码中给出的安装提示为uv pip install graphifyy graphify install见 get-shit-done/bin/lib/graphify.cjs版本经测试的区间为0.4.0,1.0checkGraphifyVersion()不在此区间会带 warning 但流程继续。超时预算CLI 侧默认build_timeout300 s可通过.planning/config.json的graphify.build_timeout调整skill 外层固定 600 s。失败语义构建链失败时旧的.planning/graphs/保留不动graphify status会在后续操作中显示 STALE/FRESH 指示。兼容性契约graphify build预检仍返回action: spawn_agent依赖该字段的旧调用方与既有测试不受本次修复影响但 skill 层的所有操作build / query / status / diff均已内联执行不再派生任何代理。六、小结#3166 的修复看似只是把后台子代理改成前台 Bash实际解决的是一个通用的 Agent 工程问题当底层工具把长任务拆分为可缓存的多阶段流水线后由谁保证第二阶段不被宿主环境的进程隔离机制杀掉。get-shit-done 的解法是把进程生命周期收拢到前台调用内用链保证原子性推进用解析 frontmatter 与代码块的结构性测试把不得派生子代理固化为可回归的不变量——这三层内联执行、超时留余量、结构测试封禁缺一不可。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考