人工智能AI 应用提示工程开发工具工作流自动化AI Agent【免费下载链接】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-done简称 GSD仓库.changeset/merry-moles-chatter.mdPR #3060所记录的一次核心架构调整展开CLI query 的 CJS fallback 执行逻辑被提取为专用适配器模块在保留日志与--help透传行为的同时显著提升了 fallback 路径的局部性与可测试性。读完本文你将理解gsd-sdk query从命令归一化、native 注册表匹配到 CJS 子进程兜底的全部分发链路掌握适配器模块的入参契约、子进程执行细节、输出分类与结构化错误处理并能用环境变量与测试用例验证该路径的完整行为。背景一次关于 Fallback 可测性的架构提取changeset 原文如下CLI query CJS fallback execution extracted to dedicated adapter module— preserves logs/help passthrough behavior while improving fallback locality and testability.这句话对应一次真实的重构在此之前CLI query 的 CJS fallback 执行逻辑散落在分发流程中难以独立验证提取后fallback 的执行被收敛到sdk/src/query/query-fallback-bridge-adapter.ts进程桥接原语与sdk/src/query/query-fallback-executor.ts分发级执行器两个专职模块中。两者共同构成了gsd-sdk query在 native 注册表未命中时通往旧版gsd-tools.cjs的透明桥。gsd-sdk query 分发全景native 注册表与 CJS Fallback 两条路径gsd-sdk query的分发由sdk/src/query/query-dispatch.ts中的runQueryDispatch()统一编排整体分为三个阶段输入校验validateQueryDispatchInput()检查是否提供了命令、解析--pick field字段提取参数缺失值时报validation_error见 query-dispatch.ts。命令归一化与拓扑匹配planQueryDispatch()先经normalizeQueryCommand()将state load、init execute-phase 9、scaffold x等写法映射为注册表键如state.load、phase.scaffold再由command-topology.ts的createCommandTopology()做最长前缀匹配dotted/spaced 两种形态见 query-command-resolution-strategy.ts 与 command-topology.ts。按计划分发匹配到 native handler 走内存注册表直派未命中且 fallback 开启则进入 CJS 子进程路径两者都失败则产出结构化错误。在runQueryDispatch()中CJS fallback 分支的触发逻辑清晰可见query-dispatch.tsif (plan.mode cjs) { if (canUseCjsFallback({ cjsFallbackEnabled: deps.cjsFallbackEnabled })) { const gsdPath deps.resolveGsdToolsPath(deps.projectDir); return await runCjsFallbackDispatch({ projectDir: deps.projectDir, gsdToolsPath: gsdPath, normCmd, normArgs, ws: deps.ws, pickField, }); } return toDispatchFailure(mapFallbackDispatchError( new Error(CJS fallback denied by policy), normCmd, normArgs)); }这里resolveGsdToolsPath由 sdk-package-compatibility.ts 实现依次探测 SDK 自带捆绑的gsd-tools.cjsBUNDLED_GSD_TOOLS_PATH、项目内.claude/get-shit-done/bin/gsd-tools.cjs、~/.claude/get-shit-done/bin/gsd-tools.cjs取首个存在的路径即使全部不存在也返回兜底路径让子进程报错仍能给出具体位置。适配器模块拆解query-fallback-bridge-adapterquery-fallback-bridge-adapter.ts是本次提取的核心成果负责在项目目录下以子进程方式执行 CJS 命令并规范化输出这一底层原语。入参契约export interface FallbackBridgeRunInput { projectDir: string; // 子进程 cwd所有 .planning/ 相对路径的基准 gsdToolsPath: string; // gsd-tools.cjs 的绝对路径 normCmd: string; // 归一化后的命令可能含点号如 state.load normArgs: string[]; // 归一化后的参数 ws?: string; // 可选 workstream映射为 --ws name } export interface FallbackBridgeOutput { mode: json | text; // 分类结果子进程输出被判定为 JSON 还是纯文本 output: unknown; stderr: string; }点号命令到 CJS argv 的转换旧版gsd-tools.cjs以空格分隔子命令而 SDK 内部使用点号归一化如state.load。dottedCommandToCjsArgv()query-fallback-bridge-adapter.ts负责反向拼接命令含点号时按.拆成多段否则原样保留最终把--ws追加为[--ws, ws]。子进程执行细节execBridge()query-fallback-bridge-adapter.ts基于node:child_process的execFile执行以process.execPath当前 Node 进程作为可执行文件gsd-tools.cjs作为第一个参数保证与宿主运行时版本一致cwd指向projectDir使 CJS 侧的工作目录语义与 SDK 完全对齐maxBuffer: 10 * 1024 * 102410MB防止大输出截断timeout: 30_00030 秒配合killSignal: SIGKILL强制终止超时进程继承process.env使GSD_WORKSTREAM等既有环境变量继续生效失败时优先携带 stderr 文本构造错误便于上层直接定位子进程真实报错。输出分类runFallbackBridge()在拿到 stdout 后调用classifyFallbackOutput()query-fallback-output-classifier.ts空白输出直接判为text尝试JSON.parse成功则mode: json支持file:相对路径协议先经resolvePathUnderProject()校验路径不越出项目根helpers.ts再读取文件内容做 JSON 解析——这延续了 CJS 侧通过文件传递大对象输出的习惯解析失败则回落为text原样透传。执行器与分发契约query-fallback-executorquery-fallback-executor.ts的runCjsFallbackDispatch()是分发层直接调用的入口query-fallback-executor.ts职责包括调用桥接模块拿到FallbackBridgeOutput收集 fallback 提示日志stderr若子进程自身写了 stderr 也一并并入通过formatFallbackOutput()统一格式化text模式保证末尾换行json模式经formatSuccess()以 2 空格缩进输出并支持pickField--pick字段提取——注意text模式不支持--pickquery-dispatch.ts成功返回{ ok: true, stdout, stderr, exit_code: 0 }失败返回toDispatchFailure(mapFallbackDispatchError(...))。执行器与桥接模块的分层让进程原语与分发语义解耦前者只负责执行与分类后者负责格式化、字段提取与错误映射——这正是 changeset 中 fallback locality局部性的落地方式。策略开关与可观测性fallback 是否启用由query-fallback-policy.ts的canUseCjsFallback()决定其状态来自 CLI 适配层的环境变量解析query-cli-adapter.tsfunction queryFallbackToCjsEnabled(): boolean { const v process.env.GSD_QUERY_FALLBACK?.toLowerCase(); if (v off || v never || v false || v 0) return false; return true; // 默认开启 }即默认开启 CJS 兜底需要严格模式仅允许 native handler如 parity 测试场景时设置GSD_QUERY_FALLBACKoff。关闭后未命中命令会走diagnoseUnknownCommand()的诊断路径错误消息中会追加CJS fallback is disabled (GSD_QUERY_FALLBACKregistered).的说明query-fallback-policy.ts。每次进入 fallback 路径query-dispatch-observability.ts 会向 stderr 写入两条提示[gsd-sdk] state.load not in native registry; falling back to gsd-tools.cjs. [gsd-sdk] Transparent bridge — prefer adding a native handler when parity matters.这就是 changeset 所强调的logs passthroughfallback 的提示日志随结果返回既不影响 stdout 的数据纯净性又让调用方清楚当前结果来自桥接而非 native。帮助信息透传--help 的双层路由help passthrough 行为由 CLI 解析层保证cli.ts-h / --help不再被无条件消费解析器会把 help 标志推入 queryArgv交给注册表 handler 或 CJS fallback 渲染上下文相关的子命令帮助当 queryArgv 中只有 help 标志没有真实子命令时才在main()短路到顶层 USAGE因此gsd-sdk query --help展示顶层用法而gsd-sdk query phase add --help会到达phase.add或 CJS fallback展示该子命令帮助此外分发层还包含一个 fail-closed 保护query-dispatch.ts当匹配到的是写操作型mutation命令且携带--help时直接返回非写操作的帮助占位防止milestone.complete --help这类调用意外落盘。错误处理与结构化结果fallback 失败统一映射为结构化错误query-error-taxonomy.ts{ kind: fallback_failure, code: 1, message: Error: gsd-tools.cjs fallback failed: 原因, details: { command, args, backend: cjs } }子进程超时经由 query-failure-classification.ts 识别为timeout信号最终落在native_timeout类错误上。所有结果遵循 query-dispatch-contract.ts 的联合契约成功为{ ok: true, stdout, stderr, exit_code: 0 }失败为{ ok: false, error: { kind, code, message, details }, stderr, exit_code }。完整错误kind枚举包括unknown_command、native_failure、native_timeout、fallback_failure、validation_error、internal_error。测试与验证本次提取的直接收益是 fallback 路径可被独立、单元化验证仓库提供了两组针对性测试query-fallback-bridge-adapter.test.ts构造一个向 stderr 写bridge boom并以 exit code 2 退出的临时.cjs脚本断言runFallbackBridge抛出的错误包含该 stderr 文本验证子进程失败时携带 stderr的契约。query-fallback-executor.test.ts覆盖四个关键场景——写 JSON 的脚本返回格式化后的 JSON stdout写纯文本的脚本返回带尾换行的文本USAGE: help text\n对应 help 透传场景ws参数被拼装为[state, load, --ws, ws-1]传递给子进程脚本缺失时返回{ ok: false }error.kind fallback_failureerror.details含{ command: state, args: [load], backend: cjs }。实战如何观察与使用 Fallback 路径观察命中执行gsd-sdk query 未注册命令stderr 中出现not in native registry; falling back to gsd-tools.cjs.即表示走了桥接graphify、gsd2-import等刻意保持 CLI-only 的命令依赖该路径见 QUERY-HANDLERS.md。开启/关闭默认开启GSD_QUERY_FALLBACKoff进入严格模式未命中直接报unknown_command并提供诊断与提示。调试子进程fallback 失败时检查details.backend cjs与错误消息中的 stderr 片段必要时直接运行node gsdToolsPath cmd args复现 CJS 侧行为。parity 考量桥接是透明兜底当输出一致性parity至关重要时应优先为命令添加 native handler——这是 stderr 提示中 prefer adding a native handler 的建议所在。从模块边界看query-fallback-bridge-adapter.ts进程执行→query-fallback-executor.ts分发语义→query-dispatch.ts策略编排→query-cli-adapter.tsCLI 接线构成了一条职责单一、逐层可测的 fallback 链路这也正是本次 changeset 提取适配器模块的架构意义所在。赞分享人工智能AI 应用提示工程开发工具工作流自动化AI Agent【免费下载链接】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-done SDK 查询层完全指南从 gsd-sdk query 到注册表分发的奇偶校验架构get shit done SDK 查询层完全指南从 gsd sdk query 到注册表分发的奇偶校验架构 导读 本文以 sdk/HANDOVER QUER人工智能AI 应用提示工程开发工具工作流自动化AI Agentget-shit-done 查询层 Golden Parity 指南gsd-tools.cjs 与 SDK 注册表的覆盖异常与 CJS-only 矩阵get shit done 查询层 Golden Parity 指南gsd tools.cjs 与 SDK 注册表的覆盖异常与 CJS only 矩阵 本篇指人工智能AI 应用提示工程开发工具工作流自动化AI Agentget-shit-done MVP 解析语义统一gsd-sdk query 三个新查询动词与 roadmap.get-phase SDK mode 修复get shit done MVP 解析语义统一 gsd sdk query 三个新查询动词与 roadmap.get phase SDK mode 修复 导人工智能AI 应用提示工程开发工具工作流自动化AI Agent上一篇OpenCore Legacy Patcher完整教程4步让旧Mac焕发新生下一篇Azure AKS中Nvidia A10 GPU设备许可证异常问题分析与解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/10 5:14:57 · 阅读 1.2k get-shit-done gsd-sdk 查询分发的 CJS Fallback 适配器架构解析
人工智能AI 应用提示工程开发工具工作流自动化AI Agent【免费下载链接】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-done简称 GSD仓库.changeset/merry-moles-chatter.mdPR #3060所记录的一次核心架构调整展开CLI query 的 CJS fallback 执行逻辑被提取为专用适配器模块在保留日志与--help透传行为的同时显著提升了 fallback 路径的局部性与可测试性。读完本文你将理解gsd-sdk query从命令归一化、native 注册表匹配到 CJS 子进程兜底的全部分发链路掌握适配器模块的入参契约、子进程执行细节、输出分类与结构化错误处理并能用环境变量与测试用例验证该路径的完整行为。背景一次关于 Fallback 可测性的架构提取changeset 原文如下CLI query CJS fallback execution extracted to dedicated adapter module— preserves logs/help passthrough behavior while improving fallback locality and testability.这句话对应一次真实的重构在此之前CLI query 的 CJS fallback 执行逻辑散落在分发流程中难以独立验证提取后fallback 的执行被收敛到sdk/src/query/query-fallback-bridge-adapter.ts进程桥接原语与sdk/src/query/query-fallback-executor.ts分发级执行器两个专职模块中。两者共同构成了gsd-sdk query在 native 注册表未命中时通往旧版gsd-tools.cjs的透明桥。gsd-sdk query 分发全景native 注册表与 CJS Fallback 两条路径gsd-sdk query的分发由sdk/src/query/query-dispatch.ts中的runQueryDispatch()统一编排整体分为三个阶段输入校验validateQueryDispatchInput()检查是否提供了命令、解析--pick field字段提取参数缺失值时报validation_error见 query-dispatch.ts。命令归一化与拓扑匹配planQueryDispatch()先经normalizeQueryCommand()将state load、init execute-phase 9、scaffold x等写法映射为注册表键如state.load、phase.scaffold再由command-topology.ts的createCommandTopology()做最长前缀匹配dotted/spaced 两种形态见 query-command-resolution-strategy.ts 与 command-topology.ts。按计划分发匹配到 native handler 走内存注册表直派未命中且 fallback 开启则进入 CJS 子进程路径两者都失败则产出结构化错误。在runQueryDispatch()中CJS fallback 分支的触发逻辑清晰可见query-dispatch.tsif (plan.mode cjs) { if (canUseCjsFallback({ cjsFallbackEnabled: deps.cjsFallbackEnabled })) { const gsdPath deps.resolveGsdToolsPath(deps.projectDir); return await runCjsFallbackDispatch({ projectDir: deps.projectDir, gsdToolsPath: gsdPath, normCmd, normArgs, ws: deps.ws, pickField, }); } return toDispatchFailure(mapFallbackDispatchError( new Error(CJS fallback denied by policy), normCmd, normArgs)); }这里resolveGsdToolsPath由 sdk-package-compatibility.ts 实现依次探测 SDK 自带捆绑的gsd-tools.cjsBUNDLED_GSD_TOOLS_PATH、项目内.claude/get-shit-done/bin/gsd-tools.cjs、~/.claude/get-shit-done/bin/gsd-tools.cjs取首个存在的路径即使全部不存在也返回兜底路径让子进程报错仍能给出具体位置。适配器模块拆解query-fallback-bridge-adapterquery-fallback-bridge-adapter.ts是本次提取的核心成果负责在项目目录下以子进程方式执行 CJS 命令并规范化输出这一底层原语。入参契约export interface FallbackBridgeRunInput { projectDir: string; // 子进程 cwd所有 .planning/ 相对路径的基准 gsdToolsPath: string; // gsd-tools.cjs 的绝对路径 normCmd: string; // 归一化后的命令可能含点号如 state.load normArgs: string[]; // 归一化后的参数 ws?: string; // 可选 workstream映射为 --ws name } export interface FallbackBridgeOutput { mode: json | text; // 分类结果子进程输出被判定为 JSON 还是纯文本 output: unknown; stderr: string; }点号命令到 CJS argv 的转换旧版gsd-tools.cjs以空格分隔子命令而 SDK 内部使用点号归一化如state.load。dottedCommandToCjsArgv()query-fallback-bridge-adapter.ts负责反向拼接命令含点号时按.拆成多段否则原样保留最终把--ws追加为[--ws, ws]。子进程执行细节execBridge()query-fallback-bridge-adapter.ts基于node:child_process的execFile执行以process.execPath当前 Node 进程作为可执行文件gsd-tools.cjs作为第一个参数保证与宿主运行时版本一致cwd指向projectDir使 CJS 侧的工作目录语义与 SDK 完全对齐maxBuffer: 10 * 1024 * 102410MB防止大输出截断timeout: 30_00030 秒配合killSignal: SIGKILL强制终止超时进程继承process.env使GSD_WORKSTREAM等既有环境变量继续生效失败时优先携带 stderr 文本构造错误便于上层直接定位子进程真实报错。输出分类runFallbackBridge()在拿到 stdout 后调用classifyFallbackOutput()query-fallback-output-classifier.ts空白输出直接判为text尝试JSON.parse成功则mode: json支持file:相对路径协议先经resolvePathUnderProject()校验路径不越出项目根helpers.ts再读取文件内容做 JSON 解析——这延续了 CJS 侧通过文件传递大对象输出的习惯解析失败则回落为text原样透传。执行器与分发契约query-fallback-executorquery-fallback-executor.ts的runCjsFallbackDispatch()是分发层直接调用的入口query-fallback-executor.ts职责包括调用桥接模块拿到FallbackBridgeOutput收集 fallback 提示日志stderr若子进程自身写了 stderr 也一并并入通过formatFallbackOutput()统一格式化text模式保证末尾换行json模式经formatSuccess()以 2 空格缩进输出并支持pickField--pick字段提取——注意text模式不支持--pickquery-dispatch.ts成功返回{ ok: true, stdout, stderr, exit_code: 0 }失败返回toDispatchFailure(mapFallbackDispatchError(...))。执行器与桥接模块的分层让进程原语与分发语义解耦前者只负责执行与分类后者负责格式化、字段提取与错误映射——这正是 changeset 中 fallback locality局部性的落地方式。策略开关与可观测性fallback 是否启用由query-fallback-policy.ts的canUseCjsFallback()决定其状态来自 CLI 适配层的环境变量解析query-cli-adapter.tsfunction queryFallbackToCjsEnabled(): boolean { const v process.env.GSD_QUERY_FALLBACK?.toLowerCase(); if (v off || v never || v false || v 0) return false; return true; // 默认开启 }即默认开启 CJS 兜底需要严格模式仅允许 native handler如 parity 测试场景时设置GSD_QUERY_FALLBACKoff。关闭后未命中命令会走diagnoseUnknownCommand()的诊断路径错误消息中会追加CJS fallback is disabled (GSD_QUERY_FALLBACKregistered).的说明query-fallback-policy.ts。每次进入 fallback 路径query-dispatch-observability.ts 会向 stderr 写入两条提示[gsd-sdk] state.load not in native registry; falling back to gsd-tools.cjs. [gsd-sdk] Transparent bridge — prefer adding a native handler when parity matters.这就是 changeset 所强调的logs passthroughfallback 的提示日志随结果返回既不影响 stdout 的数据纯净性又让调用方清楚当前结果来自桥接而非 native。帮助信息透传--help 的双层路由help passthrough 行为由 CLI 解析层保证cli.ts-h / --help不再被无条件消费解析器会把 help 标志推入 queryArgv交给注册表 handler 或 CJS fallback 渲染上下文相关的子命令帮助当 queryArgv 中只有 help 标志没有真实子命令时才在main()短路到顶层 USAGE因此gsd-sdk query --help展示顶层用法而gsd-sdk query phase add --help会到达phase.add或 CJS fallback展示该子命令帮助此外分发层还包含一个 fail-closed 保护query-dispatch.ts当匹配到的是写操作型mutation命令且携带--help时直接返回非写操作的帮助占位防止milestone.complete --help这类调用意外落盘。错误处理与结构化结果fallback 失败统一映射为结构化错误query-error-taxonomy.ts{ kind: fallback_failure, code: 1, message: Error: gsd-tools.cjs fallback failed: 原因, details: { command, args, backend: cjs } }子进程超时经由 query-failure-classification.ts 识别为timeout信号最终落在native_timeout类错误上。所有结果遵循 query-dispatch-contract.ts 的联合契约成功为{ ok: true, stdout, stderr, exit_code: 0 }失败为{ ok: false, error: { kind, code, message, details }, stderr, exit_code }。完整错误kind枚举包括unknown_command、native_failure、native_timeout、fallback_failure、validation_error、internal_error。测试与验证本次提取的直接收益是 fallback 路径可被独立、单元化验证仓库提供了两组针对性测试query-fallback-bridge-adapter.test.ts构造一个向 stderr 写bridge boom并以 exit code 2 退出的临时.cjs脚本断言runFallbackBridge抛出的错误包含该 stderr 文本验证子进程失败时携带 stderr的契约。query-fallback-executor.test.ts覆盖四个关键场景——写 JSON 的脚本返回格式化后的 JSON stdout写纯文本的脚本返回带尾换行的文本USAGE: help text\n对应 help 透传场景ws参数被拼装为[state, load, --ws, ws-1]传递给子进程脚本缺失时返回{ ok: false }error.kind fallback_failureerror.details含{ command: state, args: [load], backend: cjs }。实战如何观察与使用 Fallback 路径观察命中执行gsd-sdk query 未注册命令stderr 中出现not in native registry; falling back to gsd-tools.cjs.即表示走了桥接graphify、gsd2-import等刻意保持 CLI-only 的命令依赖该路径见 QUERY-HANDLERS.md。开启/关闭默认开启GSD_QUERY_FALLBACKoff进入严格模式未命中直接报unknown_command并提供诊断与提示。调试子进程fallback 失败时检查details.backend cjs与错误消息中的 stderr 片段必要时直接运行node gsdToolsPath cmd args复现 CJS 侧行为。parity 考量桥接是透明兜底当输出一致性parity至关重要时应优先为命令添加 native handler——这是 stderr 提示中 prefer adding a native handler 的建议所在。从模块边界看query-fallback-bridge-adapter.ts进程执行→query-fallback-executor.ts分发语义→query-dispatch.ts策略编排→query-cli-adapter.tsCLI 接线构成了一条职责单一、逐层可测的 fallback 链路这也正是本次 changeset 提取适配器模块的架构意义所在。赞分享人工智能AI 应用提示工程开发工具工作流自动化AI Agent【免费下载链接】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-done SDK 查询层完全指南从 gsd-sdk query 到注册表分发的奇偶校验架构get shit done SDK 查询层完全指南从 gsd sdk query 到注册表分发的奇偶校验架构 导读 本文以 sdk/HANDOVER QUER人工智能AI 应用提示工程开发工具工作流自动化AI Agentget-shit-done 查询层 Golden Parity 指南gsd-tools.cjs 与 SDK 注册表的覆盖异常与 CJS-only 矩阵get shit done 查询层 Golden Parity 指南gsd tools.cjs 与 SDK 注册表的覆盖异常与 CJS only 矩阵 本篇指人工智能AI 应用提示工程开发工具工作流自动化AI Agentget-shit-done MVP 解析语义统一gsd-sdk query 三个新查询动词与 roadmap.get-phase SDK mode 修复get shit done MVP 解析语义统一 gsd sdk query 三个新查询动词与 roadmap.get phase SDK mode 修复 导人工智能AI 应用提示工程开发工具工作流自动化AI Agent上一篇OpenCore Legacy Patcher完整教程4步让旧Mac焕发新生下一篇Azure AKS中Nvidia A10 GPU设备许可证异常问题分析与解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考