【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本文以仓库变更集存档 .changeset/archived/blue-stones-topology.md 为线索结合 ADR-0001 分发策略模块、CONTEXT.md 与 Command Routing Hub 源码完整解析 gsd-core 中 query 命令分发如何收敛到「命令拓扑模块」这一单一接缝从命令令牌解析、策略投影、原生 Handler Adapter 绑定到结构化无匹配诊断与封闭错误分类的落地实现。读完本文你将掌握该模块在 CLI 与 SDK 两条执行路径中的真实调用链、Result 判别联合体的设计约束以及如何在后续开发中避免分发接缝漂移。一、变更公告说了什么一次面向「拓扑接缝」的加深改造.changeset/archived/blue-stones-topology.md是一份type: Changed的变更集存档全文如下--- type: Changed --- **Query command dispatch deepened with Command Topology Module** — query dispatch now consumes a single topology seam that resolves command tokens, binds native handler adapters, and returns structured no-match diagnosis, improving locality and reducing dispatch seam drift.这段话是理解整个改造的钥匙它声明了三件事单一拓扑接缝single topology seamquery 分发不再在各调用点各自拼装查找逻辑而是统一消费一个接缝三个核心能力解析命令令牌resolve command tokens、绑定原生 Handler 适配器bind native handler adapters、返回结构化的无匹配诊断structured no-match diagnosis两个目标提升局部性locality与降低分发接缝漂移dispatch seam drift。它对应的是 docs/adr/0001-dispatch-policy-module.md 2026-05-03 修正案中正式落地的Command Topology Module。也就是说这份变更集是对 ADR 决策的一次实现收尾——把策略深度保持在显式模块内让 Adapter 保持薄层。二、背景Dispatch Policy Module 与结构化结果契约要理解拓扑模块必须先看它的上游决策。ADR-0001 的核心结论是将 query 分发结果集中到一个 Dispatch Policy Module返回结构化判别联合structured union result——成功为ok失败则携带类型化的kind、details与最终exit_code——取代以往在 CLI 与 SDK 路径中混用 throw 与零散错误映射的做法。这样做的好处是回退策略、超时分类与退出码映射集中在同一处locality原生行为与回退行为之间不会各自漂移prevent drift调用方退化为薄 Adapter面向稳定接口编程。2026-05-03 修正案在此基础上「加深相邻接缝」抽出四个模块其中就包括 Command Topology Module模块职责Query Runtime Context Module拥有projectDirws的解析策略Native Dispatch Adapter Module让 Dispatch Policy 消费稳定的原生分发接口Query CLI Output Module负责把分发结果/错误投影为 CLI 输出契约Command Topology Module解析命令、投影命令策略、绑定 Handler Adapter、产出无匹配诊断供 Dispatch Policy 消费修正案还锁定了「项目前 query 配置策略」当.planning/config.json缺失时使用内置默认值并对齐 parity 的空模型 id并把真实 CLI SDK E2E 套件显式置于GSD_ENABLE_E2E1环境变量门后。三、Command Topology Module 的职责定义CONTEXT.md 第 111112 行给出了仓库内对该模块的权威定义Command Topology ModuleModule owning command resolution, policy projection (mutation,output_mode), unknown-command diagnosis, and handler Adapter binding at one seam for query dispatch.拆解这四个职责命令解析command resolution把用户输入的命令令牌归一化确定 family / subcommand 组合即「拓扑」中的节点定位策略投影policy projection在分发接缝上投影mutation与output_mode等命令策略与 Query Execution Policy Module负责preferNative、回退策略、workstream 子进程强制形成分工无匹配诊断unknown-command diagnosis当命令在注册表中找不到时产出结构化诊断信息而不是笼统抛错Handler Adapter 绑定handler adapter binding把已解析命令绑定到对应命令族的原生处理器适配器上。这四项都在「一个接缝」内完成从而避免各命令族路由器各自重复「查找 错误分支」的临时逻辑——这正是变更集所说的「降低分发接缝漂移」。四、单一分发接缝的落地Command Routing Hub拓扑模块之下真正的路由内核是Command Routing Hubsrc/command-routing-hub.cts。它的设计目标写在该文件头部注释中一个「纯结果分发中枢pure-result dispatch hub」集中化 CJS 路由、错误分类学与所有命令族路由器此前各自重复的 no-throw 契约。4.1 核心接口createHub({ cjsRegistry, manifest, logger }) - hub hub.dispatch({ family, subcommand, args, cwd, raw, parentTraceId? }) - Result其中Result是封闭的判别联合Result { ok: true, data } | { ok: false, kind: UnknownCommand, command: string } | { ok: false, kind: InvalidArgs, arg: string, reason: string, exitReason?: string } | { ok: false, kind: HandlerRefusal, reason: string } | { ok: false, kind: HandlerFailure, message: string, cause?: Error }4.2 封闭错误分类学closed kind taxonomyERROR_KINDS以冻结对象导出调用方必须基于ERROR_KINDS.UnknownCommand等常量做 switch而不是裸字符串UnknownCommand请求的 family/subcommand 组合不在 manifest 中InvalidArgshandler 在执行前拒绝了传入参数可携带可选的exitReason即ERROR_REASON枚举值与人类可读的reason分离见makeInvalidArgs(arg, reason, exitReason?)工厂的第三参数HandlerRefusalCJS handler 显式返回拒绝如不支持的子命令HandlerFailurehandler 抛出了意外异常。4.3 类型化载荷与严格键不变量每个错误变体只携带自己的类型化载荷不允许跨变体泄漏message/details#176的 Typed-payload 设计所有工厂返回都被Object.freeze调用方无法破坏变体结构makeInvalidArgs只有在第三个参数为真值时才会附加exitReason从而保证「2 参数调用必然产出 4 键冻结结果」的严格键不变量该不变量在tests/command-routing-hub.test.cjs中有断言覆盖。4.4 运行时结构校验Hub 通过_VARIANT_SCHEMA在运行时校验 handler 返回的ok: false变体每个 kind 有必填字段集合与允许字段集合。若 handler 返回了未知 kind、缺失必填字段或携带越界字段Hub 会把违规结果强制转为HandlerFailure并附带详细诊断信息而不是静默放行。4.5 no-throw 契约与 ExitError 例外Hub 自身永不打印、永不调用process.exit、对普通 handler 异常绝不 throw统一转为HandlerFailure。唯一的例外ADR-3889handler 直接抛出ExitErrorsrc/cli-exit.cts 中的进程退出接缝时会被故意重抛——因为该 handler 已经写过自己的 stderr 并要以特定退出码终止若包装成HandlerFailure会重复输出一行错误的 stderr。ExitError会一路传播到 CLI 入口的runMain()那里才是唯一被允许捕获它的位置。4.6 可观测性接缝dispatch()每次调用都会通过makeDispatchEvent({ command, args, result, parentTraceId })生成 DispatchEvent 并交给注入的 logger。logger 默认是 no-op保证默认分发字节级静默只有可观测性显式开启如GSD_AUDIT或config.audit.enabled见 src/cjs-command-router-adapter.cts 中对isAuditEnabled()的注入逻辑时才接入参考实现createDefaultLogger({ cwd })。logger 自身出错也永远不会打断分发——降级为一条 stderr warn。五、Adapter 绑定routeHubCommandFamily 与 routeCjsCommandFamily拓扑接缝的「Handler Adapter 绑定」落在 src/cjs-command-router-adapter.cts 中它是各命令族路由器与 Hub 之间的薄适配层提供两个入口routeCjsCommandFamily(...)兼容旧调用形态内部委托给 Hub 版本family 固定为__legacy_cjs_family__routeHubCommandFamily({ family, args, subcommands, handlers, defaultSubcommand, unsupported, unknownMessage, error, cwd, raw })Hub 版命令族路由。routeHubCommandFamily的完整流程是拓扑接缝的真实调用链取args[1] || defaultSubcommand作为子命令命中unsupported表则直接error(unsupported[subcommand])返回计算可用子命令列表available把每个 handler 包装成返回{ ok: true, data }形状的注册表函数若 handler 本身已返回{ ok: ... }对象则原样透传否则以data: null补齐——结构兼容即可因为 Hub 的_validateErrResult会做运行时校验createHub({ cjsRegistry, manifest, logger })后调用hub.dispatch({ family, subcommand, args, cwd, raw })结果翻译ok直接返回UnknownCommand走error(unknownMessage(subcommand, available), ERROR_REASON.SDK_UNKNOWN_COMMAND)——第二个参数保证GSD_JSON_ERRORS1的 JSON 错误信封能保留类型化 reason能力路由器测试断言reason sdk_unknown_commandInvalidArgs若有exitReason则透传为error(reason, exitReason)HandlerRefusal取reason其余按message兜底。这条链完整印证了变更集所说的「解析命令令牌 → 绑定 handler 适配器 → 返回结构化无匹配诊断」无匹配不再是裸报错而是带command载荷的UnknownCommand变体 可枚举available的友好诊断消息。六、调用方命令族路由器的大规模收敛该接缝已被仓库内几乎所有命令族路由器采纳例如src/audit-command-router.cts第 33、93、124 行调用routeHubCommandFamilysrc/graphify-command-router.ctssrc/intel-command-router.ctssrc/eval-command-router.cts、src/init-command-router.cts、src/phases-command-router.cts、src/planning-command-router.ctssrc/phase-command-router.cts 的注释还记录了迁移背景#3788之前未知子命令是经routeCjsCommandFamily解析的Hub 化后统一收敛到单一拓扑接缝。这正是「减少分发接缝漂移」在实现层面的体现——每个命令族不再维护自己的一套查找与错误处理分支。七、配套接缝与策略锁定从 ADR 到落地7.1 死包装模块收敛Dead-wrapper convergenceADR-0001 修正案在调用点收敛后删除了一批包装模块避免「命令解析/策略」逻辑在多处重复normalize-query-command.tscommand-resolution.tspolicy-convergence.tsquery-policy-snapshot.tsquery-registry-capability.ts删除后内部 query/transport 路径统一面向 CONTEXT.md 记录的 Query Command Resolution Module 的规范接口query-command-resolution-strategy。7.2 项目前配置策略锁定修正案同时锁定了pre-project query config policy对 parity 敏感的 query 接口当.planning/config.json缺失时使用内置默认值并对模型解析面使用对齐 parity 的空模型 id保证有无配置文件两种场景行为一致。7.3 E2E 门控真实 CLI SDK E2E 套件被显式门控在GSD_ENABLE_E2E1之后默认 CI/本地验证保持确定性跳过全路径 E2E需要完整路径校验时再显式开启。7.4 SDK 侧深化SDK Runtime Bridge第二修正案2026-05-05 修正案把同一设计目标延伸到 SDK 侧GSDTools分发收敛到SDK Runtime Bridge Modulesdk/src/query-runtime-bridge.ts并在接缝上显式化allowFallbackToSubprocess显式回退策略取代隐式传输行为strictSdk严格仅原生模式命令缺少原生 adapter 时快速失败onDispatchEvent结构化桥接可观测事件分发模式、回退原因、延迟、结果与错误 kind。这延续了 Dispatch Policy 的一贯设计原则策略模块保持深度、Adapter 保持薄层、行为变更高度局部化。八、如何在仓库中验证与继续深读变更集原文.changeset/archived/blue-stones-topology.md决策文档docs/adr/0001-dispatch-policy-module.md含 2026-05-03 与 2026-05-05 两次修正案模块权威定义CONTEXT.md「Command Topology Module」「Command Routing Hub」两节路由内核实现src/command-routing-hub.ctsResult 判别联合、ERROR_KINDS封闭枚举、运行时结构校验、ExitError 重抛策略Adapter 绑定实现src/cjs-command-router-adapter.ctsrouteHubCommandFamily全流程调用方样本src/audit-command-router.cts、src/graphify-command-router.cts、src/intel-command-router.cts测试锚点tests/command-routing-hub.test.cjs严格键不变量与变体结构校验的断言所在结语Command Topology Module 不是一次孤立的重构而是 gsd-core 分发架构「深策略、薄适配、高局部性」路线图的一环上层由 Dispatch Policy Module 统一产出结构化结果中层由 Command Topology Module 在单一接缝完成令牌解析、策略投影、Adapter 绑定与无匹配诊断底层由 Command Routing Hub 以封闭错误分类学与 no-throw 契约保证行为一致。理解这条链路就能在新增命令族或调整分发行为时把改动精确落在这一个接缝内而不是散落在各路由器中再次制造漂移。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐get-shit-done 查询分发架构升级Command Topology 单一接缝如何统一命令解析、适配器绑定与无匹配诊断get shit done 查询分发架构升级Command Topology 单一接缝如何统一命令解析、适配器绑定与无匹配诊断 本仓库get shit do人工智能AI 应用提示工程开发工具工作流自动化AI Agentgsd-core 查询命令元数据统一Command Definition Module 接缝与 CJS 回退错误映射解析gsd core 查询命令元数据统一Command Definition Module 接缝与 CJS 回退错误映射解析 导读 本文围绕仓库归档变更记录 .cGSD Shell Command Projection 模块解读用运行时感知的统一接缝终结跨平台命令串拼接回归GSD Shell Command Projection 模块解读用运行时感知的统一接缝终结跨平台命令串拼接回归 本篇文章围绕 GSDget shit do人工智能AI 应用提示工程开发工具工作流自动化AI Agent上一篇思源宋体终极指南7种粗细免费开源字体完整解决方案下一篇3分钟解决BT下载慢trackerslist项目让你的下载速度提升300%创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考