get-shit-done SDK Runtime Bridge 深度解析：native-first 分发接缝、子进程回退策略与结构化调度可观测性

人工智能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-doneGSD仓库中 changeset 记录.changeset/eager-badgers-purr.md对应 PR #3158声明的SDK Runtime Bridge seam deepening展开GSD 将 SDK 侧GSDTools的查询命令分发集中收敛到一个 native-first 的 Runtime Bridge Module 之后并显式引入allowFallbackToSubprocess子进程回退策略、strictSdk严格 native-only 模式以及onDispatchEvent结构化调度可观测事件。读完本文你将掌握该接缝的完整调用链GSDTools→QueryRuntimeBridge→QueryExecutionPolicy→GSDTransport、三个关键策略选项的语义与取值边界、热路径hotpath分发与超时防重入的底层原理并能直接在自己的 SDK 编程与 workflow 编排中落地使用。一、变更背景一次 Changed 类型的 seams 深化该 changeset 属于Changed类型关联 PR #3158其原始描述为SDK Runtime Bridge seam deepened— dispatch is now centralized behind a native-first Runtime Bridge Module with explicit fallback policy (allowFallbackToSubprocess), strict native-only mode (strictSdk), and structured dispatch observability events; architecture/ADR docs updated to reflect the seam.它并非一次全新功能上线而是对既有架构接缝的一次深化deepenGSD 在 SDK 可发布面publishable seam上把原本分散在 CLI 与 SDK 两套路径中的调度行为统一收口到单一模块背后从而保证调度策略具备单一事实来源single seam避免 native 与 subprocess 行为漂移调用方退化为薄适配器thin adapters不再各自实现回退逻辑每一次调度决策都可以通过结构化事件被观测。这条演进方向在 ADR 0001 中有完整记录先是把查询调度结果收敛为 Dispatch Policy Module结构化 union 结果成功ok或带类型化kind/details/exit_code的失败随后通过三次 Amendment 逐步深化相邻接缝。最后一次 Amendment2026-05-05正是本次 changeset 的内容收敛GSDTools调度到 SDK Runtime Bridge Module并把策略接线policy wiring一并收进该接缝。二、Runtime Bridge Module接缝的接口与数据结构Runtime Bridge 的核心实现位于 sdk/src/query-runtime-bridge.ts以QueryRuntimeBridge类暴露。它统一承载三类职责命令解析resolve、普通调度execute、热路径调度dispatchHotpath。2.1 构造依赖export class QueryRuntimeBridge { constructor( private readonly registry: QueryRegistry, private readonly executionPolicy: QueryExecutionPolicy, private readonly nativeHotpathAdapter: QueryNativeHotpathAdapter, private readonly shouldUseNativeQuery: () boolean, private readonly options?: RuntimeBridgeOptions, ) {} }从源码结构看桥接器是纯编排层它不自己执行命令而是把决策委托给QueryExecutionPolicy普通调度与QueryNativeHotpathAdapter热路径自身只负责策略门禁 事件发射 结果回传。2.2 关键数据结构调度输入RuntimeBridgeExecuteInput同时携带 legacy 命令CJS 风格的state load与 registry 命令点分形式的state.load因为同一语义在两个层面分别存在export interface RuntimeBridgeExecuteInput { legacyCommand: string; legacyArgs: string[]; registryCommand: string; registryArgs: string[]; mode: TransportMode; // json | raw projectDir: string; workstream?: string; }可观测事件分两类query_dispatch普通调度与query_hotpath_dispatch热路径共同携带 dispatch mode、回退原因、耗时、结果与错误类型export interface RuntimeBridgeDispatchEvent { type: query_dispatch; command: string; legacyCommand: string; mode: TransportMode; dispatchMode: native | subprocess | native_hotpath; reason?: TransportDecision[reason]; durationMs: number; outcome: success | error; errorKind?: timeout | failure; }桥接选项RuntimeBridgeOptions正是本次 changeset 点名的三个开关export interface RuntimeBridgeOptions { strictSdk?: boolean; // 严格 native-only 模式 allowFallbackToSubprocess?: boolean; // 显式子进程回退策略 onDispatchEvent?: (event: RuntimeBridgeEvent) void; // 结构化可观测回调 }三、三个关键策略选项详解3.1strictSdk严格 native-only 模式fail-fast语义当strictSdk: true时若目标命令在查询注册表QueryRegistry中没有原生适配器立即抛错而不是尝试任何回退。对应错误信息Strict SDK mode: command registryCommand has no native adapter该模式用于 SDK 发布/就绪检查等需要确定性结果的场景把能不能用原生能力跑变成一次可复现的硬性校验而不是依赖隐式回退。测试 sdk/src/runtime-bridge-options.test.ts 用gsd.createTools().exec(nonexistent-command)验证了该错误抛出并断言伴随的query_dispatch事件outcome: error、reason: native_unregistered。值得注意的是实现细节strictSdk检查发生在execute()的第一步、任何策略计算之前且失败时也会先发射事件再抛错见 query-runtime-bridge.ts保证观测不缺失。3.2allowFallbackToSubprocess显式子进程回退策略这是本次变更的核心语义变化回退不再由底层 transport 隐式决定而是在接缝处显式声明。缺省未设置时实际值由逐命令的 transport policy 决定——gsd-transport-policy.ts 的DEFAULT_POLICY为allowFallbackToSubprocess: trueSDK 侧注释明确指出 Explicit subprocess bridge policy.Default false for SDK-native mode见 gsd-tools.ts即在纯 SDK 场景下默认偏向 native设置为false时若某命令没有原生适配器且不可 native 分发则抛出Subprocess fallback disabled: command cmd cannot run without native dispatch热路径hotpath中还有一个更细粒度的分支当 native 查询未激活如设置了 workstream 导致shouldUseNativeQuery()返回 false且allowFallbackToSubprocess false时直接以reason: policy_blocked抛错见 query-runtime-bridge.ts测试 query-runtime-bridge.test.ts 的第 5 条用例完整覆盖了该路径。3.3onDispatchEvent结构化调度可观测性onDispatchEvent提供结构化的调度观测事件字段覆盖dispatchModenative/subprocess/native_hotpath—— 本次调度实际走了哪条路reasonnative_unregistered未注册、native_not_preferred策略不偏好、native_failure_fallback原生失败后回退、native_disablednative 未激活、policy_blocked策略拦截等durationMs调度耗时outcomesuccess/errorerrorKindtimeout/failure失败时的类型化分类。实现上事件发射包裹在 try/catch 中query-runtime-bridge.ts注释明确 Observability must never break dispatch behavior——观测回调的异常绝不会影响调度主流程。这是可观测性接缝设计中的一个关键防御性约束。四、分发全链路普通调度与热路径4.1 普通调度execute()完整流程query-runtime-bridge.tsstrictSdk门禁未注册命令直接抛错并发射native_unregistered事件委托QueryExecutionPolicy.execute()传入preferNativeQuery由shouldUseNativeQuery()决定与allowFallbackToSubprocess通过onTransportDecision回调捕获 transport 层实际做出的决策dispatchMode reason成功发射outcome: success事件失败发射outcome: error事件并带errorKind。其中QueryExecutionPolicysdk/src/query-execution-policy.ts是一个薄封装先由resolveTransportPolicy(command)取出逐命令策略再以preferNative: request.preferNativeQuery policy.preferNative与allowFallbackToSubprocess: request.allowFallbackToSubprocess ?? policy.allowFallbackToSubprocess组合出最终策略交给GSDTransport.run()。逐命令策略的默认值与覆盖机制定义在 gsd-transport-policy.ts内置命令策略如TRANSPORT_RAW_COMMANDS对应的 raw 输出命令来自query-policy-capability.ts运行时可通过setTransportPolicy(command, override)动态覆盖clearTransportPolicy()清除。对应测试 gsd-transport-policy.test.ts 验证了未知命令走 legacy-safe 默认preferNative: true、allowFallbackToSubprocess: true、outputMode: jsonconfig-set、verify-summary等别名命中 raw 覆盖。4.2 底层 transport 决策GSDTransportgsd-transport.ts 是实际执行 native/subprocess 选择的引擎其决策矩阵如下条件决策policy.preferNative registry.has(command)native 分发native 分发抛错且allowFallbackToSubprocess: true且非超时错误回退 subprocessreason: native_failure_fallbacknative 分发抛错且allowFallbackToSubprocess: false直接重抛不回退未注册且allowFallbackToSubprocess: false抛Subprocess fallback disabled未注册且允许回退subprocessreason: native_unregisteredpreferNative: falsesubprocessreason: native_not_preferred超时防重入关键设计shouldRethrowNativeError中有一处刻意为之的不对称——超时错误绝不回退gsd-transport.ts因为超时并不会取消仍在后台运行的原生 handler此时若回退到子进程会触发同一条命令的双重执行double-execution race。测试 gsd-transport.test.ts 分别用字符串错误与类型化GSDToolsError.timeout验证了这一行为。workstream 语义修正源码注释记录了 Phase 5.0/6.0 的修复——workstream 命令不再强制走 subprocessdispatchNative闭包会逐请求把projectDir与workstream透传给registry.dispatch()见 query-gsd-tools-runtime.ts 的 #3591 说明native 分发同样适用于 workstream 场景且 raw 模式下由formatNativeRaw/toRaw完成输出投影。4.3 热路径dispatchHotpath()GSDTools的 runner 级便捷方法如phaseComplete、commit、initPhaseOp、phasePlanIndex、initNewProject、configSet、configGet走QueryHotpathMethods→dispatchHotpathquery-runtime-bridge.ts跳过 argv 解析直接以 canonical key 分发native 查询激活时走native_hotpath未激活时经QueryNativeHotpathAdaptersdk/src/query-native-hotpath-adapter.ts回退到execJsonFallback/execRawFallback即GSDTools.exec/execRaw回退被禁时以reason: policy_blocked抛错。该路径发射query_hotpath_dispatch事件reason取native_disabled或policy_blocked测试 query-runtime-bridge.test.ts 的第 3–5 条用例覆盖了 native_hotpath 成功、subprocess 回退成功、policy_blocked 失败三种形态。五、消费方接线GSDTools编程接口GSDToolssdk/src/gsd-tools.ts是 Runtime Bridge 的主要消费者构造选项与 bridge 选项一一对应const gsd new GSD({ projectDir: /path/to/project, strictSdk: true, // 无原生适配器即失败 allowFallbackToSubprocess: false, // 显式关闭子进程回退 sessionId: my-session, }); gsd.onEvent((event) { /* 订阅 mutation/调度事件 */ }); const tools gsd.createTools(); const roadmap await tools.roadmapAnalyze(); // 走 native registry也可直接使用底层GSDToolsimport { GSDTools } from gsd-build/sdk; const tools new GSDTools({ projectDir, strictSdk: true, allowFallbackToSubprocess: true, onDispatchEvent: (event) { // dispatchMode / reason / durationMs / outcome / errorKind console.log(event.dispatchMode, event.outcome, event.durationMs); }, }); await tools.stateLoad(); // 普通调度 await tools.phaseComplete(12); // 热路径内部组装逻辑位于 query-gsd-tools-runtime.ts 的createGSDToolsRuntime()创建注册表、subprocess 适配器、native 直接适配器、transport、execution policy、hotpath adapter最后注入QueryRuntimeBridge。这符合 ADR 0001 确立的deep policy Modules, thin Adapters, high locality设计目标。CLI 侧等价物是gsd-sdk query argv…它按同样的 longest-prefix 规则解析 argv见 sdk/src/query/QUERY-HANDLERS.md 与 docs/CLI-TOOLS.md 的 SDK and programmatic access 一节未注册命令默认 fail-fastgraphify、from-gsd2等少数命令刻意保持 CLI-only。六、测试验证矩阵本次接缝深化附带的测试构成了完整的行为契约均位于 sdk/src测试文件验证点runtime-bridge-options.test.tsstrictSdk在createTools().exec分发接缝生效query_dispatch事件含native_unregistered原因query-runtime-bridge.test.ts普通调度成功/失败事件的dispatchMode、errorKindtimeouthotpath 三种形态native_hotpath / subprocess / policy_blockedgsd-transport-policy.test.ts默认策略、raw 覆盖config-set、verify-summary别名、setTransportPolicy逐命令覆盖gsd-transport.test.tsnative 优先、失败回退、禁回退硬失败、超时不回退、raw 输出投影、workstream native 分发gsd-tools.test.tsGSDTools整体分发面与 bridge 选项接线Golden parity 层面SDK 调度输出与get-shit-done/bin/gsd-tools.cjs的 JSON 对照策略记录在 sdk/src/query/QUERY-HANDLERS.md 的 Golden parity 一节其中state.load、state.json、init.*、roadmap.analyze等均为全量toEqual校验。七、架构上下文与相关资源ADR 演进docs/adr/0001-dispatch-policy-module.md 记录了 Dispatch Policy Module 从提出到三次 Amendment 的完整脉络本次 seam deepening 是第三次 Amendment 的正式落档架构文档docs/ARCHITECTURE.md 的 SDK Runtime Bridge Module 一节将其列为 CLI Tools Layer 的核心组件并说明调用方保持薄适配器、transport 决策集中化以支撑 SDK 可发布性CLI 参考docs/CLI-TOOLS.md 的 SDK 编程访问一节给出GSDTools/createRegistry/gsd-sdk query三种接入方式的对比与迁移示例注册表契约sdk/src/query/QUERY-HANDLERS.md 记录了注册表覆盖范围、Dispatch Policy Module 的结构化 union 契约成功{ ok: true, stdout, stderr, exit_code: 0 }与带kind的失败、错误kind枚举unknown_command、native_failure、native_timeout、fallback_failure、validation_error、internal_error以及 mutation 事件约定。八、实战建议小结发布/就绪校验在 SDK 包发布前用strictSdk: true跑一遍能力冒烟确保每个对外承诺的命令都有原生适配器杜绝装上了却要偷偷回退 CJS的隐性依赖嵌入编排工具在自己编写的 workflow 或 Agent 工具层里接入GSDTools时明确选择allowFallbackToSubprocess——纯 SDK 场景建议false默认偏 native混合环境保留true并依赖逐命令 transport policy 精细控制线上诊断用onDispatchEvent采集dispatchMode/reason/durationMs/errorKind出现非预期回退时reason字段能直接区分native_unregistered缺适配器与native_failure_fallback原生执行失败两类根因注意超时语义native 调度超时后系统不会回退 subprocess防双重执行超时类问题应优先排查原生 handler 本身的耗时而不是期望回退兜底。赞分享人工智能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点击查看免费下载相关推荐gsd-core SDK Runtime Bridge 深度解析native-first 双运行时调度接缝的设计、回退策略与观测体系gsd core SDK Runtime Bridge 深度解析native first 双运行时调度接缝的设计、回退策略与观测体系 gsd core 在 Pget-shit-done SDK 架构接缝地图Query/Runtime 表面的模块化边界设计解析get shit done SDK 架构接缝地图Query/Runtime 表面的模块化边界设计解析 导读 本文解析 docs/adr/0005 sdk ar人工智能AI 应用提示工程开发工具工作流自动化AI AgentGet Shit Done SDK Query 迁移深度解析从无类型 gsd-tools 子进程到类型化查询注册表Get Shit Done SDK Query 迁移深度解析从无类型 gsd tools 子进程到类型化查询注册表 导读 gsd build/sdk 的 q人工智能AI 应用提示工程开发工具工作流自动化AI Agent上一篇如何快速上手OpenSuperWhisper从Homebrew安装到第一次按住⌘说出第一句话的完整入门教程下一篇Seedance 2.5接入AI短剧平台:PRINTFILM分镜生视频与口播合成深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考