企业官网建设流程全解析

• 人工智能
• AI 应用
• 提示工程
• 开发工具
• 工作流自动化
• AI Agent

导读

本文围绕 get-shit-done（GSD）仓库中 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.

它并非一次全新功能上线，而是对既有架构接缝的一次"深化"（deepen）：GSD 在 SDK 可发布面（publishable seam）上，把原本分散在 CLI 与 SDK 两套路径中的调度行为，统一收口到单一模块背后，从而保证：

• 调度策略具备单一事实来源（single seam），避免 native 与 subprocess 行为漂移；
• 调用方退化为薄适配器（thin adapters），不再各自实现回退逻辑；
• 每一次调度决策都可以通过结构化事件被观测。

这条演进方向在 ADR 0001 中有完整记录：先是把查询调度结果收敛为 Dispatch Policy Module（结构化 union 结果：成功ok或带类型化kind/details/exit_code的失败），随后通过三次 Amendment 逐步深化相邻接缝。最后一次 Amendment（2026-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: true；
• SDK 侧注释明确指出 "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提供结构化的调度观测，事件字段覆盖：

• dispatchMode：native/subprocess/native_hotpath—— 本次调度实际走了哪条路；
• reason：native_unregistered（未注册）、native_not_preferred（策略不偏好）、native_failure_fallback（原生失败后回退）、native_disabled（native 未激活）、policy_blocked（策略拦截）等；
• durationMs：调度耗时；
• outcome：success/error；
• errorKind：timeout/failure（失败时的类型化分类）。

实现上，事件发射包裹在 try/catch 中（query-runtime-bridge.ts），注释明确 "Observability must never break dispatch behavior"——观测回调的异常绝不会影响调度主流程。这是可观测性接缝设计中的一个关键防御性约束。

四、分发全链路：普通调度与热路径

4.1 普通调度execute()

完整流程（query-runtime-bridge.ts）：

1. strictSdk门禁：未注册命令直接抛错并发射native_unregistered事件；
2. 委托QueryExecutionPolicy.execute()，传入preferNativeQuery（由shouldUseNativeQuery()决定）与allowFallbackToSubprocess；
3. 通过onTransportDecision回调捕获 transport 层实际做出的决策（dispatchMode + reason）；
4. 成功发射outcome: 'success'事件，失败发射outcome: 'error'事件并带errorKind。

其中QueryExecutionPolicy（sdk/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: 'json'），config-set、verify-summary等别名命中 raw 覆盖。

4.2 底层 transport 决策：GSDTransport

gsd-transport.ts 是实际执行 native/subprocess 选择的引擎，其决策矩阵如下：

超时防重入（关键设计）：shouldRethrowNativeError中有一处刻意为之的不对称——超时错误绝不回退（gsd-transport.ts），因为超时并不会取消仍在后台运行的原生 handler，此时若回退到子进程会触发同一条命令的双重执行（double-execution race）。测试 gsd-transport.test.ts 分别用字符串错误与类型化GSDToolsError.timeout验证了这一行为。

workstream 语义修正：源码注释记录了 Phase 5.0/6.0 的修复——workstream 命令不再强制走 subprocess，dispatchNative闭包会逐请求把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→dispatchHotpath（query-runtime-bridge.ts），跳过 argv 解析直接以 canonical key 分发：

• native 查询激活时走native_hotpath；
• 未激活时经QueryNativeHotpathAdapter（sdk/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编程接口

GSDTools（sdk/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

也可直接使用底层GSDTools：

import { 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-fast，graphify、from-gsd2等少数命令刻意保持 CLI-only。

六、测试验证矩阵

本次接缝深化附带的测试构成了完整的行为契约（均位于 sdk/src）：

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 事件约定。

八、实战建议小结

1. 发布/就绪校验：在 SDK 包发布前用strictSdk: true跑一遍能力冒烟，确保每个对外承诺的命令都有原生适配器，杜绝"装上了却要偷偷回退 CJS"的隐性依赖；
2. 嵌入编排工具：在自己编写的 workflow 或 Agent 工具层里接入GSDTools时，明确选择allowFallbackToSubprocess——纯 SDK 场景建议false（默认偏 native），混合环境保留true并依赖逐命令 transport policy 精细控制；
3. 线上诊断：用onDispatchEvent采集dispatchMode/reason/durationMs/errorKind，出现非预期回退时，reason字段能直接区分native_unregistered（缺适配器）与native_failure_fallback（原生执行失败）两类根因；
4. 注意超时语义：native 调度超时后系统不会回退 subprocess（防双重执行），超时类问题应优先排查原生 handler 本身的耗时，而不是期望回退兜底。

• 人工智能
• AI 应用
• 提示工程
• 开发工具
• 工作流自动化
• AI Agent