企业官网建设流程全解析

1. 这不是“Claude官方CLI”，而是一套可复用的代码生成骨架

“claude-code-templates”这个名称，第一眼容易让人误以为是Anthropic官方推出的命令行工具——毕竟关键词里反复出现claude cli、codex cli、anthropic，再加上大量用户在搜索unable to connect to anthropic services、failed to connect to api.anthropic.com这类报错，说明很多人正试图把本地开发流与Claude API强行耦合。但事实恰恰相反：claude-code-templates本质上是一组面向开发者自建AI编码工作流的工程化模板，它不封装API调用，不代理请求，也不处理认证密钥分发；它的核心价值，在于帮你绕过“每次写个脚本都要从零搭环境、配参数、写重试逻辑、处理超时和限流”的重复劳动。

我去年在三个不同团队落地过类似方案：一个做低代码平台的前端组，用它快速生成符合内部DSL规范的组件定义JSON；一个嵌入式IoT团队，靠它把自然语言需求（比如“当温度>85℃且持续3秒，触发蜂鸣器并上报告警”）自动转成C语言状态机代码框架；还有一个金融风控后台组，用它批量生成基于规则引擎的决策树桩代码。它们都没碰过anthropic域名，也没在代码里写过一行api_key，但都共享同一套模板结构、同一套参数注入机制、同一套输出后处理管道。

为什么需要这样一套东西？因为真实世界里的AI编码落地，90%的精力根本不在“调哪个模型”上，而卡在上下文组织、输入清洗、输出解析、错误兜底、结果校验、与现有工程链路集成这六个环节。比如你让Claude生成一段TypeScript接口定义，它可能返回带Markdown代码块的富文本，也可能混入解释性文字，还可能因token截断导致类型定义不完整——这些都不是API本身的问题，而是你作为集成方必须解决的工程问题。

所以claude-code-templates的定位非常清晰：它是一套可插拔的代码生成流水线骨架。你可以把它理解成Webpack的webpack.config.js——它不编译代码，但它定义了“从哪读输入、怎么喂给LLM、从哪取输出、怎么清洗、怎么写入目标文件、失败时怎么降级”。所有与Anthropic服务的交互，都由你自行选择的HTTP客户端（如Axios、Fetch）或SDK（如@anthropic-ai/sdk）完成；所有密钥管理，都交由你的环境变量、Vault或CI/CD secrets系统负责；所有网络异常处理，都在你自己的try/catch块里显式控制。

这也是为什么搜索热词里大量出现npm : 无法加载文件 d:\program files\nodejs\npm.ps1、npm run build、npm warn deprecated node-domexception@1.0.0——大家想用npm install claude-code-templates直接开箱即用，却发现它根本不是一个可执行的CLI包，而是一个需要git clone后手动npm install && npm run setup的模板仓库。它不提供claude-code --generate --prompt="..."这样的命令，它提供的是./scripts/generate.js这个可修改的入口脚本，以及templates/nextjs-api-route.ts这种可复制粘贴的模板文件。

提示：如果你在npm registry里搜不到claude-code-templates这个包，不是你镜像源配错了，也不是网络被拦截，而是它压根就没发布到npm。它的主战场在GitHub，最新版本永远在main分支的/templates目录下。别浪费时间查npm view claude-code-templates，直接去它的repo看README.md里的Usage章节——那里写的不是安装命令，而是“如何基于此模板创建你自己的生成器”。

2. 模板结构拆解：五个核心目录决定你的生成质量上限

当你git clone下claude-code-templates仓库，第一眼看到的是五个平行目录：/config、/lib、/scripts、/templates、/test。它们不是随意排列的，而是严格对应AI代码生成工作流的五个关键阶段。我带过的每个团队，在第一次fork这个仓库时，都会花至少半天时间逐个目录摸清职责边界——因为一旦搞反了某类逻辑该放哪，后续维护成本会指数级上升。

2.1/config：所有可变参数的唯一真相源

这里存放的是modelConfig.ts、promptConfig.ts、outputConfig.ts三类配置文件，它们共同构成整个生成流程的“策略中心”。很多人初看觉得简单，无非是几个常量对象，但实际踩坑最多的地方就在这里。

modelConfig.ts里最关键的不是model: "claude-3-haiku-20240307"这行，而是maxTokens: 2048和temperature: 0.1的组合。我们曾遇到一个场景：生成React组件时，Claude总在JSX闭合标签前突然中断。排查发现是maxTokens设得过大（4096），导致模型在长上下文里丢失了“必须生成完整组件”的约束；调低到2048后，配合stopSequences: ["```"]，生成完整性立刻提升到98%以上。这不是玄学，而是Claude的token计数机制对代码块标记特别敏感——它会把```当作独立token，如果剩余token不足容纳整个代码块，就会提前截断。

promptConfig.ts更值得深挖。它不只存systemPrompt字符串，而是用buildPrompt()函数动态组装。比如我们为金融团队定制的版本里，buildPrompt()会先读取/rules/fraud-detection-rules.json，把当前业务规则实时注入system prompt，再拼接用户输入。这样做的好处是：规则变更不用改代码，只需更新JSON；同时避免把全部规则硬编码进prompt导致token溢出。实测下来，动态注入比静态prompt的准确率高12%，因为Claude能聚焦在本次生成相关的3~5条规则上，而不是面对200行规则文档发呆。

outputConfig.ts则藏着最隐蔽的陷阱。outputFormat: "typescript"看似只是指定语言，但它联动着/lib/parsers/typescriptParser.ts的解析逻辑。我们曾因没同步更新outputConfig.outputFormat和parsers里的匹配规则，导致生成的TS接口里interface User { name: string; }被解析成{name: "string"}这样的运行时对象，而非类型声明——因为解析器默认按JSON Schema处理，而没切换到AST模式。后来我们在outputConfig里加了parserMode: "ast"字段，并强制要求所有新模板必须在/lib/parsers/里提供对应实现，才彻底解决。

注意：/config目录下严禁出现任何硬编码的API密钥、Endpoint URL或个人邮箱。所有敏感信息必须通过process.env.ANTHROPIC_API_KEY等环境变量注入，且.env.example文件里只留占位符（如ANTHROPIC_API_KEY=your_api_key_here），绝不允许示例值。

2.2/lib：可复用能力的原子化封装

如果说/config是大脑，/lib就是四肢——它把所有重复操作提炼成可测试、可替换的函数模块。这里没有“万能生成器”，只有高度专注的单一职责函数。

httpClient.ts是最常被魔改的模块。默认它用fetch调用https://api.anthropic.com/v1/messages，但很多企业内网不允许直连外网。我们的解决方案不是改URL，而是在httpClient.ts里暴露createClient()工厂函数，接受options: { adapter?: HttpAdapter }。然后在/adapters/internal-proxy-adapter.ts里实现一个适配器，把请求转发到公司内部的AI网关（该网关统一处理鉴权、审计、限流）。这样，业务代码里还是await httpClient.sendMessage(...)，但底层已无缝切换到内网通道。上线后，安全团队审核时只看到一个内部域名，完全没察觉背后连的是Anthropic。

promptBuilder.ts则解决“如何让Claude听懂人话”的问题。它不直接拼字符串，而是提供buildCodeGenerationPrompt()方法，接收{ language, framework, constraints, examples }对象。其中examples字段特别关键——我们发现，给Claude看2个高质量的TypeScript+Zod校验的接口定义示例，比写100字文字描述“要带Zod验证”有效得多。promptBuilder会自动把示例转成<example></example>XML块，并确保它们出现在prompt末尾——因为Claude对结尾的示例记忆最深刻。这个细节让生成代码的Zod校验覆盖率从63%提升到91%。

outputSanitizer.ts是最后一道防线。它不做“美化”，只做“保命”。比如当Claude返回Here's your code:\n\``ts\ninterface User {...}\n```时，sanitize()会精准提取```ts和```之间的内容，去掉所有非代码字符。更绝的是，它内置了validateSyntax()钩子：对TS代码调用ts.createSourceFile()做语法树校验，对JSON调用JSON.parse()，失败则触发重试或降级到// TODO: 生成失败，请人工补全`占位符。这个设计让我们在CI流水线里能自动拦截87%的语法错误生成物，避免污染主干代码。

2.3/scripts：生成动作的调度中枢

/scripts/generate.js是整个模板的“开关按钮”，但它绝不是简单的for循环调用API。它实现了三层调度逻辑：批处理队列 → 上下文感知重试 → 结果归档策略。

批处理队列解决了“一次生成多个文件”的痛点。比如你要为10个微服务生成OpenAPI Schema，传统做法是写10个独立脚本或手动循环。而generate.js支持--batch-config ./batch-configs/payment-service.json，该JSON里定义了[{ "input": "支付订单创建接口", "outputPath": "src/schemas/payment-create.ts" }, ...]。脚本会自动按concurrency: 3并发执行，每完成一个就写入./logs/generate-20240520-1423.log，包含时间戳、输入摘要、token消耗、耗时。这个日志不是为了debug，而是为了审计——当法务问“这个接口定义是谁、何时、基于什么提示生成的”，你能立刻给出完整证据链。

上下文感知重试机制，则针对Claude最让人头疼的rate_limit_exceeded错误。默认重试是简单sleep后重发，但generate.js会检查response.headers.get("x-ratelimit-remaining")，如果剩余配额<5，就主动降级到claude-3-haiku模型（便宜且快），并在日志里标记[DEGRADED] used haiku due to rate limit。这样既保证任务不中断，又避免因盲目重试导致整个账户被限流。我们线上集群跑批处理时，这个机制让成功率从76%稳定在99.2%。

结果归档策略则关乎协作效率。generate.js执行完默认把文件写入./dist，但加--archive参数后，它会：

1. 创建./archives/20240520-1423-payment-service/目录
2. 复制原始输入（batch-configs/payment-service.json）
3. 复制生成的全部文件
4. 生成metadata.json记录{ "generatedBy": "cli-v2.1.0", "anthropicModel": "claude-3-sonnet-20240229", "promptHash": "sha256:abc123..." }这样，三个月后有人质疑“这个接口为啥没Zod校验”，你只要查archives/.../metadata.json，就能确认当时用的prompt版本和模型，无需翻Git历史。

2.4/templates：领域知识的实体化容器

这是模板的灵魂所在，也是新手最容易陷入“复制粘贴陷阱”的地方。/templates里不是一堆.ts文件，而是按领域+技术栈+生成目标三维分类的目录树。比如/templates/frontend/react-component/下有basic.ts、with-zod.ts、with-testing.ts三个模板，分别对应不同复杂度的组件生成需求。

关键在于模板里的{{ }}占位符不是简单变量替换，而是上下文感知的表达式引擎。以with-zod.ts为例：

import { z } from 'zod'; export const {{ inputName | pascalCase }}Schema = z.object({ {{#each fields}} {{ this.name | camelCase }}: {{ this.type | zodType }}, {{/each}} }); export type {{ inputName | pascalCase }} = z.infer<typeof {{ inputName | pascalCase }}Schema>;

这里的{{#each fields}}是Handlebars语法，但pascalCase、camelCase、zodType都是我们注入的自定义Helper。zodTypeHelper会根据this.type值智能映射："string"→z.string()，"number"→z.number().int()，"date"→z.coerce.date()。这样，即使用户输入fields: [{name: "createdAt", type: "date"}]，生成的代码也自带日期转换逻辑，而不是裸写z.date()导致运行时报错。

更厉害的是/templates/backend/fastapi-route/下的streaming.ts模板。它专为需要SSE流式响应的场景设计，模板里有{{#if streamingEnabled}}...{{/if}}条件块。当generate.js传入{ streamingEnabled: true }时，它生成return StreamingResponse(...)；传入false则生成普通return JSONResponse(...)。这种“一个模板，两种形态”的设计，让团队不用维护两套几乎相同的模板，大幅降低出错概率。

提示：不要在模板里写业务逻辑！所有计算、判断、数据转换必须放在/lib或/scripts里。模板只负责“把已处理好的数据，按固定格式渲染出来”。我们曾有个团队在模板里写了{{#if user.role === 'admin'}}...{{/if}}，结果发现Handlebars不支持===，改成==后又因类型隐式转换出bug——这种本该在JavaScript层处理的逻辑，硬塞进模板只会让调试变成噩梦。

2.5/test：生成结果的可信度守门员

/test目录的存在，直接区分了“玩具模板”和“生产级模板”。这里不是测“脚本能跑”，而是测“生成的代码能用”。

integration.test.ts是核心。它不mock Anthropic API，而是用nock库录制真实API响应（record: true模式下首次运行会发起真请求并保存./fixtures/claude-responses.json），后续测试全部回放录制数据。这样，测试既覆盖真实模型行为（包括token截断、随机性、格式偏差），又保证100%可重现。我们发现Claude在temperature: 0.1下仍有约3%概率把interface User生成为type User，这个细微差异只有通过真实响应录制才能捕捉。

validation.test.ts则针对生成物做静态检查。比如对/templates/frontend/react-component/with-zod.ts的输出，它会：

1. 用ts-morph解析生成的TS文件
2. 验证是否存在export const XXXSchema = z.object({...})
3. 验证z.object的参数是否为对象字面量（排除z.object(schema)这种动态引用）
4. 验证z.infer的泛型参数是否与Schema变量名一致 这种检查比单纯expect(output).toContain("z.object")严谨得多，能提前发现模板里{{ inputName }}拼写错误导致的类型不匹配。

最后是performance.test.ts，它用benchmark.js测量generate.js单次执行耗时。阈值设为< 800ms（含网络延迟）。当某次PR导致平均耗时升至850ms，CI会直接失败。这个看似苛刻的要求，逼着我们优化了promptBuilder的字符串拼接逻辑——把template + input + examples的三次+操作，改为[template, input, examples].join("")，省下120ms。在日均生成2000次的流水线里，这每天节省4分钟。

3. CLI包装层：如何把模板变成真正可用的命令行工具

虽然claude-code-templates本身不是CLI包，但绝大多数团队最终都需要一个npx @myorg/claude-code generate --config payment.json这样的命令。这就需要你在模板基础上，构建一层轻量CLI包装。这个过程不是简单的bin字段配置，而涉及四个关键决策点。

3.1 包管理策略：为什么选择pnpm而非npm或yarn

在package.json里，我们强制要求"packageManager": "pnpm@8.15.3"，原因很实在：符号链接的确定性。claude-code-templates的/templates目录会被多个项目复用，如果用npm link或yarn link，不同项目的node_modules会指向同一个物理路径，导致require('zod')在A项目里是v3.22，在B项目里却是v3.21——因为link不隔离依赖版本。

pnpm的workspace协议完美解决这个问题。我们在根目录建pnpm-workspace.yaml：

packages: - 'packages/cli' - 'packages/templates'

packages/cli的package.json里写：

{ "name": "@myorg/claude-code", "version": "1.2.0", "bin": { "claude-code": "dist/cli.js" }, "dependencies": { "@myorg/claude-code-templates": "workspace:*" } }

这样，当用户pnpm add @myorg/claude-code时，pnpm会自动在node_modules/@myorg/claude-code-templates下创建符号链接，指向packages/templates，但@myorg/claude-code自身的node_modules/zod仍是独立安装的v3.22。我们线上23个服务共用同一套模板，从未因依赖冲突导致生成失败。

注意：npm install会忽略pnpm-workspace.yaml，所以必须在文档里明确写“请使用pnpm安装”，并在preinstall脚本里加检测：

# package.json "scripts": { "preinstall": "if ! command -v pnpm &> /dev/null; then echo 'Error: pnpm is required'; exit 1; fi" }

3.2 CLI参数解析：避开yargs的常见陷阱

我们选用commander而非更流行的yargs，原因只有一个：错误处理的可控性。yargs的.demandOption()在参数缺失时直接process.exit(1)，而我们的CLI必须支持--dry-run模式——即不调用API，只打印将要执行的操作。如果yargs一报错就退出，--dry-run就失去意义。

commander的.option()配合.action()则完全可控：

program .option('-c, --config <path>', 'Path to config file') .option('--dry-run', 'Print actions without executing') .action(async (opts) => { if (!opts.config) { console.error('Error: --config is required'); process.exitCode = 1; return; // 不退出，留给后续逻辑处理 } if (opts.dryRun) { console.log(`DRY RUN: Will generate using ${opts.config}`); return; } await runGenerator(opts.config); });

这种模式让--dry-run能和所有参数组合使用，比如claude-code generate --config payment.json --dry-run会输出“将调用Anthropic API，模型：sonnet，输入token：1248，预计输出：3个TS文件”，而不触发任何网络请求。这个功能在灰度发布新模板时至关重要——运维同学可以先看dry-run结果，确认无误后再正式执行。

3.3 环境变量注入：比.env文件更安全的密钥传递

ANTHROPIC_API_KEY不能只靠dotenv加载，因为.env文件可能被意外提交到Git。我们的方案是双通道密钥注入：

1. 开发环境：仍用.env，但.gitignore里明确包含.env*，且dotenv只在NODE_ENV=development时加载。
2. 生产环境（CI/CD）：强制要求通过--env-file参数指定密钥文件路径，且该文件路径必须在/secrets目录下（该目录在Git中被/secrets/**全局忽略）。

CLI启动时的校验逻辑：

if (!process.env.ANTHROPIC_API_KEY) { if (argv.envFile) { const envContent = fs.readFileSync(argv.envFile, 'utf8'); const keyMatch = envContent.match(/^ANTHROPIC_API_KEY=(.+)$/m); if (keyMatch) { process.env.ANTHROPIC_API_KEY = keyMatch[1]; } else { throw new Error(`ANTHROPIC_API_KEY not found in ${argv.envFile}`); } } else { throw new Error('ANTHROPIC_API_KEY not set. Use --env-file or set in environment.'); } }

这个设计让安全团队满意：密钥文件路径可审计（--env-file /secrets/prod-anthropic.key），内容不进Git，且CLI启动时明确报错，避免静默失败。

3.4 输出格式控制：从console.log到结构化报告

默认CLI输出是纯文本，但工程师需要机器可读的结果。我们在--format json选项里实现了完整的结构化输出：

{ "status": "success", "generatedFiles": [ { "path": "src/schemas/payment-create.ts", "size": 1248, "tokensUsed": { "input": 423, "output": 187 } } ], "anthropicResponse": { "id": "msg_...", "model": "claude-3-sonnet-20240229", "stopReason": "end_turn" } }

这个JSON不只是日志，更是CI流水线的输入。比如Jenkins的Post-build Action可以解析generatedFiles[].path，自动触发eslint --fix和prettier --write；或者用jq '.generatedFiles | length'统计本次生成了多少文件，超过10个就发Slack告警——因为正常需求不该一次生成太多文件，可能是配置错了。

更进一步，我们加了--report参数，生成HTML报告：

claude-code generate --config payment.json --report ./reports/payment-20240520.html

报告里包含：生成时间轴、token消耗热力图、各文件diff预览（用diff2html渲染）、以及一个“可点击的错误堆栈”——当某个文件生成失败时，点击错误行会跳转到/templates里对应的模板行号。这个功能让新人排查问题速度提升3倍，因为他们不再需要在终端日志里手动grep。

4. 实战排错：从unable to connect to anthropic services到稳定生成的完整链路

搜索热词里高频出现的unable to connect to anthropic services、failed to connect to api.anthropic.com，表面看是网络问题，但在我经手的37个相关故障中，只有4个真是网络不通。其余33个，根源都在本地环境与Anthropic服务的协议握手环节。下面还原一次典型排错全过程，展示如何用模板自带的诊断能力定位真因。

4.1 故障现象：本地开发机上100%失败，CI环境却正常

一位前端同学在Windows 10上执行npx @myorg/claude-code generate --config user-profile.json，始终报错：

Error: unable to connect to anthropic services failed to connect to api.anthropic.com

但同样的命令在GitHub Actions里100%成功。第一反应是“Windows防火墙拦截”，但ping api.anthropic.com能通，curl -v https://api.anthropic.com也返回200。问题显然不在基础网络层。

4.2 第一步：启用模板内置诊断模式

所有claude-code-templates衍生的CLI都支持--debug参数。加上后，输出变成：

DEBUG: Using config from user-profile.json DEBUG: Resolved ANTHROPIC_API_KEY length: 32 chars (masked) DEBUG: Building HTTP client with endpoint: https://api.anthropic.com/v1/messages DEBUG: Sending request with 423 input tokens... ERROR: fetch failed: TypeError: fetch failed at Object.processResponse (node:internal/deps/undici/undici:11471:34)

注意TypeError: fetch failed——这是Node.js底层的错误，不是Anthropic返回的HTTP错误。说明请求根本没发出去，卡在了fetch调用环节。

4.3 第二步：检查Node.js版本与fetch兼容性

fetch是Node.js 18+原生支持的，但Windows上常有旧版Node残留。运行：

node -v # 输出 v16.14.2

果然！fetch在Node 16里不存在，httpClient.ts里globalThis.fetch是undefined，导致fetch(url, options)直接抛TypeError。这就是为什么CI里正常（CI用Node 20），而本地失败。

解决方案不是升级Node（可能影响其他项目），而是在httpClient.ts里加优雅降级：

// 兼容 Node 16+ const fetchImpl = globalThis.fetch || (await import('node-fetch')).default; export async function sendMessage(...) { const response = await fetchImpl(url, options); // ... }

但更根本的解决，是在CLI的preinstall里加Node版本检查：

"scripts": { "preinstall": "node -e \"if (parseInt(process.version.slice(1).split('.')[0]) < 18) throw new Error('Node.js >= 18 required')\"" }

这样，用户npm install时就会看到明确提示，而不是等到运行时才报错。

4.4 第三步：当fetch正常，却仍连不上——检查TLS证书链

升级Node到18后，错误变成：

ERROR: fetch failed: TypeError: Client network socket disconnected before secure TLS connection was established

这是典型的TLS握手失败。在Windows上，常见原因是系统根证书过期。运行：

# PowerShell [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12 -bor [System.Net.SecurityProtocolType]::Tls13

但这只是临时修复。永久方案是让fetch使用系统证书：

import https from 'https'; import { Agent } from 'https'; const httpsAgent = new Agent({ ca: require('tls').rootCertificates, // 使用系统根证书 }); const response = await fetch(url, { agent: httpsAgent, // ... });

claude-code-templates的/lib/httpClient.ts里已内置此逻辑，但需要用户显式启用--use-system-ca参数。我们在文档里强调：“Windows用户首次运行必加此参数”。

4.5 第四步：429 Too Many Requests——不是配额用完，而是IP被限流

某天凌晨，所有生成任务突然失败，错误是：

ERROR: Anthropic API returned 429: Too Many Requests

但查看Anthropic控制台，配额剩余92%。这时要看响应头：

curl -I -H "x-api-key: $KEY" https://api.anthropic.com/v1/messages # 输出： # x-ratelimit-limit: 5000 # x-ratelimit-remaining: 0 # x-ratelimit-reset: 1716220800

x-ratelimit-remaining: 0说明不是账户级配额，而是IP级限流。我们集群有20台机器共用一个出口IP，每台每分钟发50次请求，合计1000次/分钟，超过了Anthropic对单IP的500次/分钟限制。

解决方案有二：

1. 短期：在/config/modelConfig.ts里加maxConcurrentRequests: 10，把并发数从默认50降到10，使总请求数<200/分钟。
2. 长期：在/adapters/proxy-adapter.ts里集成公司API网关，网关做IP轮询（Round Robin），把请求分散到10个不同出口IP。

我们选了方案2，因为网关还能统一加X-Request-ID头，方便全链路追踪。上线后，429错误归零。

4.6 第五步：500 Internal Server Error——Claude服务端的“温柔拒绝”

最棘手的错误是：

ERROR: Anthropic API returned 500: Internal Server Error

这不是你的错，而是Claude服务端在过载时返回的通用错误。它不告诉你具体原因，但claude-code-templates的/lib/retryStrategy.ts里有特殊处理：

export const anthropicRetryStrategy = { maxRetries: 3, retryDelay: (attempt) => Math.pow(2, attempt) * 1000, // 指数退避 shouldRetry: (error, response) => { // 500且响应体含"overloaded"，立即重试（不等退避） if (response?.status === 500 && response.body?.includes('overloaded')) { return true; } // 其他5xx，按指数退避重试 return response?.status >= 500; } };

这个策略让500 overloaded错误的恢复时间从平均30秒降到2秒以内——因为服务端过载通常是瞬时的，立刻重试成功率很高。我们在generate.js里加了--retry-on-overload开关，默认开启。

提示：所有排错步骤都应记录在/docs/troubleshooting.md里，并附上curl复现命令。比如对TLS问题，文档里写：

curl -v --cacert /path/to/system-certs.pem https://api.anthropic.com

这样，当新同学遇到同样问题，不用问人，直接复制命令就能验证。

5. 模板演进：从单模型支持到多模型协同的架构升级

claude-code-templates不是静态快照，而是一个持续演进的架构。我们最近一次重大升级，是把“只支持Claude”扩展为“Claude + Qwen + 自研小模型”的混合调度。这次升级不是简单加个if (model === 'qwen')，而是重构了整个模型抽象层。

5.1 模型适配器模式：统一接口，隔离差异

核心变化在/lib/adapters/目录。现在有anthropicAdapter.ts、qwenAdapter.ts、localLlamaAdapter.ts三个文件，它们都实现同一个接口：

export interface ModelAdapter { generate( prompt: string, options: ModelOptions ): Promise<ModelResponse>; getCostEstimate( inputTokens: number, outputTokens: number ): number; }

generate()方法隐藏了所有模型特异性：

• Anthropic Adapter用/v1/messages端点，system字段放系统提示，messages数组放用户消息。
• Qwen Adapter用/v1/chat/completions端点，messages数组里role: "system"放系统提示，role: "user"放用户消息。
• Local Llama Adapter用/completion端点，把system prompt和user prompt拼成单字符串。

这样，/scripts/generate.js里只需：

const adapter = createAdapter(config.model); // 根据config.model返回对应Adapter const response = await adapter.generate(prompt, options);

业务代码完全不感知底层模型切换。上周我们把支付服务的生成模型从Claude切到Qwen（因Qwen对中文金融术语理解更好），只改了一行配置：model: "qwen-max"，其余代码零改动。

5.2 混合调度策略：按场景智能路由

光有适配器还不够，得有调度器。我们在/lib/router.ts里实现了ModelRouter：

export class ModelRouter { route(input: string, context: GenerationContext): ModelSpec { // 规则1：含中文且长度<500字，走Qwen if (/[\u4e00-\u9fa5]/.test(input) && input.length < 500) { return { model: 'qwen-max', priority: 1 }; } // 规则2：需生成TypeScript且含Zod，走Claude（因其TS生态更好） if (context.language === 'typescript' && context.requireZod) { return { model: 'claude-3-sonnet', priority: 2 }; } // 规则3：简单CRUD描述，走本地Llama（快且免费） if (input.toLowerCase().includes('create') || input.toLowerCase().includes('update')) { return { model: 'llama-3-8b', priority: 3 }; } return { model: 'claude-3-haiku', priority: 4 }; } }

GenerationContext来自/config/promptConfig.ts，它把用户输入的原始字符串，解析成结构化上下文。比如输入"为订单表生成TypeScript接口，要求带Zod校验"，context就是`