人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载导读本文围绕 gsd-2gh_mirrors/gs/gsd-2仓库中已落地实施的架构决策记录 ADR-007: Model Catalog Split and Provider API Encapsulation完整讲解pi-ai包如何将一个 13,848 行的单体模型目录models.generated.ts拆分为按 Provider 组织的多个文件并移除从包根入口index.tsbarrel re-export Provider 内部实现的公共 API 卫生问题。读完本文你将掌握 ADR 决策的完整背景、两处核心变更的落地方式含对应源码路径、生成脚本的工作机制、以及如何在不改变任何运行时行为的前提下完成一次纯结构性的大型代码组织重构。一、决策背景两个真实存在的结构性问题ADR-007 的开篇立场非常明确pi-ai的模型/Provider 系统并非从根本上坏掉——SDK 懒加载、基于注册表的调度、扩展式注册这些重型机制早已设计良好。需要修复的是两个摩擦点。1.1 当前架构快照重构前文档给出了重构前的加载拓扑stream.ts └─ import ./providers/register-builtins.js ← side-effect import at load time ├─ import anthropic.ts (6.8 KB) ├─ import anthropic-vertex.ts (3.9 KB) ├─ import openai-completions.ts (26 KB) ├─ import openai-responses.ts (6.4 KB) ├─ import openai-codex-responses.ts (29 KB) ├─ import azure-openai-responses.ts (7.8 KB) ├─ import google.ts (13.6 KB) ├─ import google-vertex.ts (14.5 KB) ├─ import google-gemini-cli.ts (30 KB) ├─ import mistral.ts (18.9 KB) └─ amazon-bedrock.ts (24 KB) ← only lazy-loaded provider models.ts └─ import models.generated.ts ← 13,848 lines, ALL providers, loaded at init └─ import models.custom.ts ← 197 lines, additional providers1.2 已经做得好的部分本次不动ADR 特意花篇幅澄清哪些机制不应该被改动SDK 懒加载每个 Provider 文件都使用async function getXxxClass()配合缓存的动态import()。anthropic-ai/sdk、openai、google/genai、aws-sdk/*、mistralai/*这些重型 npm 包只在首次 API 调用时加载——真正的启动开销已经被处理掉了。基于注册表的调度api-registry.ts将 API 类型干净地映射到 stream 函数。调用方只需stream(model, context)由注册表路由到正确的 Provider。这一模式是健全的。扩展式注册Ollama、Claude Code CLI 通过registerApiProvider()在运行时注册扩展点工作正常。Provider 实现代码的解析成本虽然所有 Provider 都是 eager 加载但 V8 解析本地.js文件只需个位数毫秒/文件全部 Provider 文件的总解析成本约 10–30ms——对一个即将发起数秒级 API 调用的 CLI 而言完全不可感知。1.3 Problem 1单体模型目录开发体验问题models.generated.ts是单文件 13,848 行。这带来的摩擦是纯开发工作流层面的PR 评审痛苦生成脚本一跑diff 就是横跨无关 Provider 的一大片改动评审者无法分辨某个 Provider 到底改了什么导航缓慢要在几千行静态对象字面量中滚动/搜索才能找到某个模型合并冲突频繁任何两个触碰模型生成的 PR 都会在同一个单体文件上冲突git blame失效每一行都显示last changed by generation script掩盖了单个 Provider 增量的历史。文档明确量化了运行时代价约 200 个模型对象的 Map 大约只有 50–100KB 堆内存加载全部模型定义的运行时成本可忽略不计。问题纯粹是代码组织与开发者工作流层面的。1.4 Problem 2barrel export 泄露 Provider 内部API 设计问题重构前packages/pi-ai/src/index.ts把每个 Provider 模块的内部全部 re-exportexport * from ./providers/anthropic.js; export * from ./providers/google.js; export * from ./providers/google-gemini-cli.js; export * from ./providers/google-vertex.js; export * from ./providers/mistral.js; export * from ./providers/openai-completions.js; export * from ./providers/openai-responses.js; // ... etc这是公共 API 层面的问题消费者可以绕过注册表任何import { streamAnthropic } from pi-ai的代码都直接依赖了本应属于内部的实现细节重构被阻塞在 Provider 文件内重命名一个函数因为它从包根被 re-export就成了破坏性变更semver breaking changeAPI 表面积不必要地膨胀公共 API 本应只有stream()、streamSimple()、registerApiProvider()、模型工具函数和类型。1.5 明确不做的事惰性 Provider 加载文档专门用一节解释为什么不把register-builtins.ts改成异步按需加载Bedrock 模式的全盘推广SDK 已经是懒加载的重成本已被处理异步化会给热路径增加复杂性——stream.ts目前是同步Map.get()把resolveApiProvider变 async 会给每次 API 调用不只是首次增加一次微任务跳转小而可测却无用户可见收益波及面大、收益低——同时动stream.ts、api-registry.ts和注册生命周期会对核心流式路径带来回归风险Bedrock 的懒加载是特例而非模板——它存在是因为aws-sdk/client-bedrock-runtime体量特殊地巨大。这一节体现了 ADR 的成熟度先确认不该改什么再决定改什么把变更范围收敛到最小。二、核心决策两处针对性改进零运行时变化Decision对代码组织与 API 卫生做两处针对性改进不改变运行时加载行为。2.1 Change 1把models.generated.ts拆成按 Provider 的文件目标目录结构重构后packages/pi-ai/src/models/ ├── index.ts ← re-exports combined registry, same public API ├── generated/ │ ├── anthropic.ts ← Anthropic model definitions │ ├── openai.ts ← OpenAI model definitions │ ├── google.ts ← Google model definitions │ ├── mistral.ts ← Mistral model definitions │ ├── amazon-bedrock.ts ← Bedrock model definitions │ ├── groq.ts ← Groq model definitions │ ├── xai.ts ← xAI model definitions │ ├── cerebras.ts ← Cerebras model definitions │ ├── openrouter.ts ← OpenRouter model definitions │ └── ... ← one file per provider in the catalog ├── custom.ts ← replaces models.custom.ts (unchanged content) └── capability-patches.ts ← CAPABILITY_PATCHES extracted for clarity关键约束加载保持同步且 eager。所有模型文件静态导入Map 在模块初始化时照旧构建。不做 async、不做懒加载、不做运行时行为变更——这纯粹是一次文件组织层面的变更。仓库中的实际落地形态可作为证据核对当前仓库中packages/pi-ai/src/models/generated/已存在 23 个按 Provider 拆分的生成文件加一个汇总index.tsamazon-bedrock.ts、anthropic.ts、azure-openai-responses.ts、cerebras.ts、github-copilot.ts、google.ts、google-antigravity.ts、google-gemini-cli.ts、google-vertex.ts、groq.ts、huggingface.ts、kimi-coding.ts、minimax.ts、minimax-cn.ts、mistral.ts、openai.ts、openai-codex.ts、opencode.ts、opencode-go.ts、openrouter.ts、vercel-ai-gateway.ts、xai.ts、zai.ts例如 packages/pi-ai/src/models/generated/anthropic.ts 文件头注明auto-generated by scripts/generate-models.ts内部是ANTHROPIC_MODELS常量每个模型条目形如claude-3-5-haiku-20241022: { id: claude-3-5-haiku-20241022, name: Claude Haiku 3.5, api: anthropic-messages, provider: anthropic, baseUrl: https://api.anthropic.com, reasoning: false, input: [text, image], cost: { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1, }, contextWindow: 200000, maxTokens: 8192, } satisfies Modelanthropic-messages,而 packages/pi-ai/src/models/generated/index.ts 则逐 Provider import 并合并成MODELS常量export const MODELS { amazon-bedrock: AMAZON_BEDROCK_MODELS, anthropic: ANTHROPIC_MODELS, azure-openai-responses: AZURE_OPENAI_RESPONSES_MODELS, // ... } as const;对外保持完全相同的同步公共 APIpackages/pi-ai/src/models/index.ts 是拆分后的核心入口其职责与文档中的设计完全对应import { MODELS } from ./generated/index.js; import { CUSTOM_MODELS } from ./custom.js; import { CAPABILITY_PATCHES, applyCapabilityPatches } from ./capability-patches.js; import { FAKE_MODEL, FAKE_MODEL_ID, FAKE_PROVIDER } from ./fake-model.js; import type { Api, KnownProvider, Model, Usage } from ../types.js; const modelRegistry: Mapstring, Mapstring, ModelApi new Map(); // Initialize registry from auto-generated MODELS (models.dev catalog) for (const [provider, models] of Object.entries(MODELS)) { const providerModels new Mapstring, ModelApi(); for (const [id, model] of Object.entries(models)) { providerModels.set(id, model as ModelApi); } modelRegistry.set(provider, providerModels); }模块初始化流程源码可见分四步全部是同步 eager 的从MODELS生成目录汇总构建每个 Provider 的Mapstring, ModelApi合并手动维护的CUSTOM_MODELScustom 是纯增量的绝不覆盖生成条目源码注释引用了 issue #2339当环境变量GSD_FAKE_LLM_TRANSCRIPT被设置时注册一个用于 E2E 测试的 fake 模型该环境变量必须在模块被 import 之前设置见providers/fake.ts在模块加载时对静态注册表应用CAPABILITY_PATCHES。随后导出的公共工具函数与文档列出的清单一一对应getModel(provider, modelId)——带强类型的按 ProviderID 查询getProviders()——返回全部已知 ProvidergetModels(provider)——返回某 Provider 的模型列表calculateCost(model, usage)——按每百万 token 单价计算 input/output/cacheRead/cacheWrite 四部分成本并累加 totalsupportsXhigh(model)——读取model.capabilities.supportsXhigh通过 CAPABILITY_PATCHES 或自定义模型声明设置源码注释明确要求不要在这里做模型 ID 或 Provider 名的硬编码判断请改 CAPABILITY_PATCHESmodelsAreEqual(a, b)——比较 id 与 provider 是否都相同任一为空返回 false。另外packages/pi-ai/src/models.ts 现在只剩三行注释 一行 re-export作为向后兼容入口// Backward-compatible entrypoint. // ADR-007 moved model registry internals to src/models/*. export * from ./models/index.js;CAPABILITY_PATCHES 的独立抽取packages/pi-ai/src/models/capability-patches.ts 将能力补丁独立成文件内部是匹配函数 能力集合的数组export const CAPABILITY_PATCHES: CapabilityPatch[] [ // GPT-5.2-5.4 support xhigh thinking and OpenAI service tiers { match: (m) m.id.includes(gpt-5.2) || m.id.includes(gpt-5.3) || m.id.includes(gpt-5.4), caps: { supportsXhigh: true, supportsServiceTier: true }, }, // Anthropic Opus 4.6 supports xhigh thinking { match: (m) m.api anthropic-messages ( m.id.includes(opus-4-6) || m.id.includes(opus-4.6) || ... ), caps: { supportsXhigh: true }, }, ];其中applyCapabilityPatches(models)工具函数专门服务于静态注册表之外的模型如models.json自定义模型、扩展注册模型、发现模型——它们不会经过模块初始化的 patch 循环所以在组装任意模型列表后应调用该函数补齐能力标记同时模型上已经显式声明的capabilities优先于补丁。2.2 Change 2停止 barrel-export Provider 内部实现文档给出的before / after对比// Before (current — 17 re-exports including all providers): export * from ./providers/anthropic.js; export * from ./providers/azure-openai-responses.js; export * from ./providers/google.js; export * from ./providers/google-gemini-cli.js; export * from ./providers/google-vertex.js; export * from ./providers/mistral.js; export * from ./providers/openai-completions.js; export * from ./providers/openai-responses.js; export * from ./providers/register-builtins.js; // ... // After (clean public API): export * from ./api-registry.js; export * from ./env-api-keys.js; export * from ./models/index.js; export * from ./providers/register-builtins.js; // resetApiProviders() is public export * from ./stream.js; export * from ./types.js; export * from ./utils/event-stream.js; export * from ./utils/json-parse.js; export type { OAuthAuthInfo, OAuthCredentials, /* ... */ } from ./utils/oauth/types.js; export * from ./utils/overflow.js; export * from ./utils/typebox-helpers.js; export * from ./utils/repair-tool-json.js; export * from ./utils/validation.js;仓库中的实际落地形态当前 packages/pi-ai/src/index.ts 已完全遵循重构后的形态只 re-exportapi-registry.js、env-api-keys.js、models/index.js、register-builtins.js、stream.js、types.js以及若干utils/*工具模块。Provider 专属的 stream 函数如streamAnthropic、streamGoogle已从公共 API 中移除。注意register-builtins.js仍保留在 barrel 中是因为resetApiProviders()是公开的测试辅助函数。仓库中的实现见 packages/pi-ai/src/providers/register-builtins.tsexport function resetApiProviders(): void { clearApiProviders(); registerBuiltInApiProviders(); registerFakeProviderIfEnabled(); }它把清空 重新注册内建 Provider 按需注册 fake Provider封装为一步供测试在用例间重置状态使用。为什么这很重要强制执行注册表模式调用 Provider 的正确姿势是stream(model, context)直接 import Provider 函数会造成脆弱耦合为未来重构铺路Provider 内部函数签名可以在不破坏包 API 的前提下演进——过去重命名streamAnthropic就是一次 semver 破坏性变更收窄 API 表面积消费者只需要看到stream、streamSimple、registerApiProvider、模型工具与类型。2.3 明确不变的部分ADR 用清单形式划定了不变项这些在源码中均可交叉验证运行时行为——所有 Provider 依旧 eager 加载ModelTApi类型系统——所有类型、接口、泛型保持不变ApiProvider接口——Provider 依旧实现{ api, stream, streamSimple }见 api-registry.ts 中的ApiProviderTApi, TOptions定义api-registry.ts注册表——同步Map.get()调度不变stream.ts——流式入口零改动register-builtins.ts——仍 eager import 并注册所有 Provider仅resetApiProviders保留在 barrel 中扩展系统——registerApiProvider()继续支持 Ollama、Claude Code CLI 等models.json用户配置——自定义模型、override、Provider 设置不受影响模型发现——discovery adapters 本就懒加载且独立模型路由——ADR-004 的能力感知路由与此正交。三、生成脚本从单文件输出到按 Provider 输出ADR 指出generate-models.ts内部本就按 Provider 分组只需改为分文件写出。仓库中的 packages/pi-ai/scripts/generate-models.ts约 1671 行已完整实现该逻辑const generatedDir join(packageRoot, src/models/generated); rmSync(generatedDir, { recursive: true, force: true }); mkdirSync(generatedDir, { recursive: true }); for (const providerId of sortedProviderIds) { const providerModels providers[providerId]; const constName toConstName(providerId); const providerOutput // This file is auto-generated by scripts/generate-models.ts // Do not edit manually - run npm run generate-models to update import type { Model } from ../../types.js; export const ${constName} ${renderModelEntries(providerModels)} as const satisfies Recordstring, Modelany; ; writeFileSync(join(generatedDir, ${providerId}.ts), providerOutput); console.log(Generated src/models/generated/${providerId}.ts); }关键细节先清空再重建脚本用rmSync(generatedDir, { recursive: true })删除整个generated/目录再逐 Provider 写出保证不留陈旧文件每 Provider 一个常量toConstName(providerId)将amazon-bedrock转成AMAZON_BEDROCK_MODELS这样的常量名自动生成汇总 index随后脚本再生成generated/index.ts逐个import并组装MODELS常量与手写版本行为一致legacy 文件清理脚本检测到旧的src/models.generated.ts存在时自动删除完成迁移收尾统计输出脚本结尾打印总模型数、推理模型数及每个 Provider 的模型数量便于核对生成结果。模型条目由renderModelEntries渲染字段覆盖id、name、api、provider、可选baseUrl、可选headers、可选compat、reasoning、input如[text,image]、costinput/output/cacheRead/cacheWrite 四项单价、contextWindow、maxTokens并以satisfies Model${api}做静态类型校验。模型定义来源于 models.dev 目录并通过CUSTOM_MODELSpackages/pi-ai/src/models/custom.ts补充目录中不存在的自定义 Provider。合并规则在models/index.ts中可见custom 模型只做增量添加绝不覆盖生成条目避免手工维护内容被自动生成内容意外冲掉。四、为什么这样做收益与代价的完整账本4.1 正面收益维度重构前重构后PR diff13K 行文件的整体变化仅影响被改动的 Provider 文件合并冲突任何并发模型更新都可能冲突只有同时触碰同一 Provider 才冲突git blame每行都显示regenerate models可见每个 Provider 的历史演进查找模型在 13K 行中搜索直接打开对应 Provider 文件评审上下文评审者必须理解所有 Provider评审者只需关注受影响的 Provider加上 API 层面的四项收益更干净的 PR模型目录变更被限定在受影响的 Provider 上更少的合并冲突不同 Provider 的更新不再在同一文件上打架更好的可导航性开发者可直接跳到models/generated/anthropic.ts查看 Anthropic 模型定义更干净的包 API 面向未来的重构能力 零运行时风险。4.2 负面代价文件数变多从1 个生成文件 1 个 custom 文件变成约 15–20 个生成文件仓库实际落地为 23 个 Provider 文件 index边际复杂度略有上升但每个文件聚焦且短小生成脚本需要更新generate-models.ts需改为分文件写出已实现并附带测试barrel export 变更的 import 审计直接import { streamAnthropic } from pi-ai的代码需要迁移。ADR 指出主要消费者是register-builtins.ts本身——它直接不经 barrelimport Provider外部使用应极少。4.3 被否定的备选方案全量惰性 Provider 加载原 ADR-005 提案将 Bedrock 模式推广到所有 Provider。被否决理由即前文明确不做的事四连SDK 已懒加载、实现解析仅 ~10–30ms、为同步热路径引入 async 复杂度、迁移成本高且收益不可测插件架构独立 npm 包如gsd/provider-anthropic。隔离度最高但构建/发布/版本管理复杂度剧增对所有 Provider 一起发布的 monorepo 而言过度设计什么都不做ADR 承认当前架构可用do nothing是合法选项。拆分的理由是开发体验摩擦13K 行文件、合并冲突、失效的 blame与 API 卫生泄露 Provider 内部而非运行时问题——如果团队并未遭遇这些摩擦推迟拆分也是合理的。这段备选方案评审展示了 ADR 的决策严谨性连不做都被当作正式选项认真评估过。五、分波实施计划与验证路径ADR 给出的实施计划分为三波与仓库现状可逐一对照Wave 1拆分模型目录低-中风险更新generate-models.ts向models/generated/输出每 Provider 文件——已落地见 generate-models.ts创建models/index.tsimport 所有 Provider 文件并构建同一注册表——已落地将CAPABILITY_PATCHES抽取到models/capability-patches.ts——已落地将models.custom.ts迁移为models/custom.ts——已落地更新models.ts或由新models/index.ts替代——已落地为向后兼容 re-export 入口验证npm run build与npm run test通过删除models.generated.ts与models.custom.ts——生成脚本已含 legacy 文件自动清理逻辑。Wave 2清理 barrel export低风险从index.ts移除 Provider re-export——已落地全代码库 grep 直接来自pi-ai的 Provider import将发现的用法迁移到通过注册表的stream()/streamSimple()验证构建与测试。Wave 3验证跑全量测试套件验证扩展注册Ollama、Claude Code CLI仍工作验证resetApiProviders()测试辅助函数仍工作端到端抽查若干 Provider。仓库中的验证证据仓库内 packages/pi-ai/src/models.generated.test.ts 提供了拆分后注册表的回归测试样例直接 importMODELS、getModel、getModels、getProviders来自./models/index.js即新入口例如对 OpenRouter 上qwen/qwen3.6-plusissue #3582与z-ai/glm-5.1issue #4069的回归断言覆盖存在性、getModel()可达性、id/provider一致性、reasoning标记与contextWindow数值。这类测试正是 Wave 3跑全量测试套件的落地载体也印证了拆分后公共 API 与注册表行为完全兼容旧入口。此外 packages/pi-ai/src/models.test.ts 继续对模型注册表与工具函数进行常规测试二者共同为零运行时行为变更提供保障。六、给读者的实践要点ADR 是变更边界的最好教材本文展示了一个成熟重构的范式——先精确识别已经好的机制SDK 懒加载、注册表调度、扩展注册再定位真正值得改的摩擦点单文件目录、API 泄露最后明确列出不改清单并评估什么都不做选项。这比为了重构而重构高一个量级。拆分模式可复用任何单个自动生成的大文件 频繁并发改动 blame 失效 PR diff 失控的场景都可以套用本 ADR 的模式——按逻辑单元拆分、保留汇总入口、维持完全相同的公共 API、生成脚本改为分文件输出并自动清理 legacy 文件。API 封装要管住 barrel exportexport * from看似省事实则把每个实现细节固化进公共 API任何内部重命名都变成破坏性变更。正确做法是把注册表/门面作为唯一公共入口Provider 内部函数留在包内。可验证的落地路径在 gsd-2 仓库中读者可以沿以下文件路径核对本文所有结论——拆分后的目录packages/pi-ai/src/models/含generated/、custom.ts、capability-patches.ts、fake-model.ts、index.ts向后兼容入口packages/pi-ai/src/models.ts干净公共 APIpackages/pi-ai/src/index.ts注册表核心packages/pi-ai/src/api-registry.ts生成脚本packages/pi-ai/scripts/generate-models.ts回归测试packages/pi-ai/src/models.generated.test.ts、packages/pi-ai/src/models.test.ts。相关 ADR 脉络本决策与 ADR-004 能力感知模型路由 正交ADR 明确说明路由机制不受影响扩展模块化演进见 ADR-006若想了解模型目录之上的一层——编排内核的演进可参考 ADR-009 编排内核重构。结语ADR-007 是一次教科书式的纯结构性重构它没有引入新的运行时机制没有改变任何加载、注册、流式或调度行为也没有扩大系统能力它只做两件事——把 13,848 行的单体模型目录拆成 23 个按 Provider 聚焦的生成文件以及把 Provider 内部实现从包根公共 API 中请出去。前者的收益是可读性、可维护性与协作效率后者则把一个隐含的公共契约所有内部函数都可被外部 import收窄为经过设计的门面。正如 ADR 自己所说如果团队没有经历这些摩擦点推迟拆分也是合理的。而 gsd-2 的落地代码证明当这些摩擦真实存在时一次低风险、零运行时影响的组织级重构可以换来长期的可维护性红利。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐深入解析 GSD-2 的 ADR-016Worktree Lifecycle 与 State Projection 模块化拆分深入解析 GSD 2 的 ADR 016Worktree Lifecycle 与 State Projection 模块化拆分 导读 本文完整解读 GSD 2人工智能AI Agent代码智能体Agent 编排CLIAI 应用GSD-2 外部状态目录 ADR-002 为何未采纳DB 权威运行时模型与投影架构解析GSD 2 外部状态目录 ADR 002 为何未采纳DB 权威运行时模型与投影架构解析 导读 本文围绕 GSD 2 开源仓库中的架构决策记录 ADR 002人工智能AI Agent代码智能体Agent 编排CLIAI 应用GSD-2 ADR-016 Phase 2 设计解读并行合并整合形状与 Session 变异动词拆分GSD 2 ADR 016 Phase 2 设计解读并行合并整合形状与 Session 变异动词拆分 导读 本文围绕 GSD 2 仓库中的架构决策补充文档人工智能AI Agent代码智能体Agent 编排CLIAI 应用上一篇Zephyr 驱动 96Boards Aerocore2 无人机扩展板STM32F427 硬件详解与 DFU 烧录实战下一篇mold 链接器中的 oneTBB global_control深入解析线程池控制机制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考