企业官网建设流程全解析

1. 项目收尾时最容易踩的坑：模型调用散落各处

走到第十七章，你的 Agent 项目大概率已经能跑通完整链路了：用户输入进来，Planner 拆任务，Memory 加载历史，RAG 检索知识，MCP 调工具，LLM 出结果，前端流式渲染。功能都在，但打开代码仓库一看，问题也全暴露出来了。

我见过太多类似的项目，包括我自己早期写的版本，收尾阶段最典型的症状就是：模型调用的 Key 和 Base URL 散落在至少五六个文件里。planner.ts里写死一个 OpenAI 的 Key，rag/embedding.ts里又配了一个别的服务商的地址，tools/summarize.ts里为了省钱换了个便宜模型，结果 Key 又是另一套。等到要换供应商、要统计成本、要做多租户隔离的时候，你会发现根本无从下手——改一个地方漏三个地方，测试环境能跑生产环境报 401，这种问题排查起来极其消耗精力。

这一章不引入新功能，我们做的是收束。把前十六章散落的模型调用、工具编排、状态管理，收敛成一张能讲清楚、能维护、能交接的架构。核心动作有三个：统一模型接入层、固化目录结构、跑一次端到端回归验证。其中统一模型接入层，我用 TaoToken 来做收口，原因是它把多家模型的调用协议统一成了 OpenAI 兼容格式，一个 Key 就能覆盖对话、推理、代码等不同模型，省掉了为每个供应商单独维护配置的麻烦。

先说清楚这一章适合谁：如果你已经跟着前十六章把 Agent 主体搭起来了，现在处于"能跑但不敢改"的状态，那这一章就是给你写的。如果你还没开始，也可以先看架构部分，理解一个生产级 Agent 项目最终应该长什么样。

收束的价值不在于代码变少，而在于变更成本变低。当模型调用只有一个入口，换模型、加模型、限流、计费、审计，全都只改一处。这是从"能跑的 Demo"到"能维护的项目"之间最关键的一步。

2. TaoToken 统一 Key 接入：把模型调用收敛到一个入口

在讲具体配置之前，先解释为什么要在收尾阶段做这件事。前十六章里，我们为了快速验证，往往是"哪个模型好用就接哪个"，Planner 用 A 家的，RAG 的 embedding 用 B 家的，工具里的摘要用 C 家的。这种写法在开发期没问题，但到了收尾阶段，它会变成架构里最大的技术债。

TaoToken 在这里扮演的角色是模型接入网关。它提供 OpenAI 兼容的 API 协议，也就是说你原来用openaiSDK 写的调用代码，只需要改baseURL和apiKey两个参数，就能切换到 TaoToken 的入口，然后通过model字段指定你要用哪个模型。对于 Agent 项目来说，这意味着 Planner、RAG、工具调用可以共用同一套客户端初始化逻辑，只是传入不同的 model ID。

具体怎么做？核心是抽出一个lib/llm/client.ts，所有模型调用都从这里拿客户端。下面是我实测下来比较稳的写法，用 TypeScript：

// lib/llm/client.ts import OpenAI from "openai"; const TAOTOKEN_BASE_URL = process.env.TAOTOKEN_BASE_URL ?? "https://taotoken.net/api"; const TAOTOKEN_API_KEY = process.env.TAOTOKEN_API_KEY; if (!TAOTOKEN_API_KEY) { throw new Error("TAOTOKEN_API_KEY is not set"); } // 单例客户端，全项目共用 export const llmClient = new OpenAI({ baseURL: TAOTOKEN_BASE_URL, apiKey: TAOTOKEN_API_KEY, }); // 模型路由表：把业务语义映射到具体 model ID export const MODEL_ROUTES = { planner: process.env.MODEL_PLANNER ?? "gpt-4o-mini", reasoning: process.env.MODEL_REASONING ?? "gpt-4o", embedding: process.env.MODEL_EMBEDDING ?? "text-embedding-3-small", summarize: process.env.MODEL_SUMMARIZE ?? "gpt-4o-mini", } as const; export type ModelRole = keyof typeof MODEL_ROUTES;

这段代码的关键设计有两个。第一，客户端是单例，全项目只初始化一次，避免每个模块各自 new 一个导致配置分散。第二，MODEL_ROUTES把"业务角色"和"具体模型"解耦了——Planner 用哪个模型是配置决定的，不是代码写死的。以后想把 Planner 从 mini 换成更强的模型，只改环境变量，不动业务代码。

环境变量文件.env.local这样写：

# .env.local TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_API_KEY=sk-你的key MODEL_PLANNER=gpt-4o-mini MODEL_REASONING=gpt-4o MODEL_EMBEDDING=text-embedding-3-small MODEL_SUMMARIZE=gpt-4o-mini

注意TAOTOKEN_BASE_URL我用了https://taotoken.net/api，这是 API 入口，不要和官网首页混用。Key 的获取在控制台的 API Keys 页面，创建后复制一次就存进环境变量，不要提交到 git。

注意：.env.local必须加进.gitignore。我见过有人把 Key 提交到公开仓库，几分钟内就被扫走刷额度，这个坑一定要避开。

有了统一客户端，原来散落各处的调用就可以逐个替换。比如 Planner 里原来是：

// 改造前：写死的配置 const client = new OpenAI({ apiKey: process.env.OPENAI_KEY }); const res = await client.chat.completions.create({ model: "gpt-4o-mini", messages: [...], });

改造后：

// 改造后：走统一入口 import { llmClient, MODEL_ROUTES } from "@/lib/llm/client"; const res = await llmClient.chat.completions.create({ model: MODEL_ROUTES.planner, messages: [...], });

RAG 的 embedding 调用同理，只是换成MODEL_ROUTES.embedding。工具里的摘要调用换成MODEL_ROUTES.summarize。全部替换完之后，全项目搜索new OpenAI应该只剩下lib/llm/client.ts一处，这就是收束完成的标志。

这一步做完，你的 Agent 项目在模型接入层面就从"散装"变成了"集中管理"。接下来我们看目录结构怎么配合这个设计。

3. 可复制的目录结构与配置片段

统一了客户端之后，目录结构也要跟着收敛。前十六章里，很多人的项目是"按开发顺序"堆出来的：chapter1/、chapter2/这种，或者所有文件平铺在src/下。收尾阶段必须重构成"按职责分层"，否则新人接手根本找不到东西在哪。

下面是我建议的最终目录结构，你可以直接对照调整：

agent-project/ ├── app/ # Next.js App Router │ ├── api/ │ │ ├── chat/route.ts # 流式对话入口 │ │ └── tools/route.ts # 工具调用回调 │ └── (dashboard)/ │ └── page.tsx ├── lib/ │ ├── llm/ │ │ ├── client.ts # 统一模型客户端（上一节） │ │ └── routes.ts # 模型路由表 │ ├── agent/ │ │ ├── planner.ts # 任务规划 │ │ ├── executor.ts # 执行器 │ │ └── manager.ts # 多 Agent 调度 │ ├── memory/ │ │ ├── short-term.ts # 会话内记忆 │ │ └── long-term.ts # 持久化记忆 │ ├── rag/ │ │ ├── retriever.ts # 向量检索 │ │ └── injector.ts # 上下文安全注入 │ ├── tools/ │ │ ├── mcp-client.ts # MCP 统一入口 │ │ └── registry.ts # 工具注册表 │ └── observability/ │ ├── logger.ts │ └── tracer.ts ├── config/ │ ├── models.toml # 模型与预算配置 │ └── tools.toml # 工具权限配置 ├── db/ │ ├── schema.sql │ └── migrations/ ├── .env.local └── package.json

这个结构的分层逻辑是：app/只负责 HTTP 入口和渲染，lib/放所有业务能力，config/放可调参数，db/放数据层。每一层职责单一，跨层调用只能从上往下，不能反向依赖。

重点说config/models.toml，这是把模型配置从代码里彻底剥离出来的关键：

# config/models.toml [defaults] base_url = "https://taotoken.net/api" timeout_ms = 60000 max_retries = 2 [roles.planner] model = "gpt-4o-mini" temperature = 0.2 max_tokens = 2048 [roles.reasoning] model = "gpt-4o" temperature = 0.7 max_tokens = 4096 [roles.embedding] model = "text-embedding-3-small" batch_size = 64 [roles.summarize] model = "gpt-4o-mini" temperature = 0.3 max_tokens = 512 [budget] daily_token_limit = 2000000 per_request_limit = 32000

然后在lib/llm/routes.ts里读取这个配置：

// lib/llm/routes.ts import fs from "node:fs"; import path from "node:path"; import TOML from "@iarna/toml"; const configPath = path.join(process.cwd(), "config/models.toml"); const raw = fs.readFileSync(configPath, "utf-8"); const config = TOML.parse(raw) as any; export const modelConfig = config; export const baseUrl = config.defaults.base_url;

这样做的收益是：模型参数、预算上限、超时重试策略全部集中在 TOML 里，运维改配置不用碰代码，代码 review 时也不会因为调了个 temperature 就产生 diff 噪音。

如果你用的是 Claude Code 这类工具做辅助开发，可以在项目根目录放一个.claude/settings.json，把模型入口也统一指向同一个 Base URL：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的key" }, "model": "claude-sonnet-4-20250514" }

这里三件套要写全：Base URL 是https://taotoken.net/api，Key 是你的 TaoToken Key，Model ID 按你实际要用的填。Cline 的 MCP 配置也是同样的逻辑，在cline_mcp_settings.json里把 provider 的 baseURL 指向统一入口即可。

目录和配置收敛完之后，你的项目就从"能跑"进化到了"能讲清楚"。下一步是验证这套收束没有破坏原有功能。

4. 端到端回归验证：一次请求跑通全链路

重构最怕的是"改完不知道有没有改坏"。所以收尾阶段必须做一次端到端回归验证，用一个真实请求把"感知-规划-执行-记忆"整条链路跑一遍，确认每个环节都正常。

我建议写一个独立的验证脚本scripts/e2e-check.ts，不依赖前端，直接调后端逻辑：

// scripts/e2e-check.ts import { llmClient, MODEL_ROUTES } from "../lib/llm/client"; import { planTask } from "../lib/agent/planner"; import { retrieveContext } from "../lib/rag/retriever"; import { callTool } from "../lib/tools/mcp-client"; async function e2eCheck() { const userInput = "帮我查一下北京今天的天气，然后总结成一句话"; console.log("[1/5] 用户输入:", userInput); // 步骤1：RAG 检索 const context = await retrieveContext(userInput); console.log("[2/5] RAG 检索到片段数:", context.length); // 步骤2：Planner 规划 const plan = await planTask(userInput, context); console.log("[3/5] 规划结果:", JSON.stringify(plan, null, 2)); // 步骤3：工具调用 const toolResult = await callTool("weather", { city: "北京" }); console.log("[4/5] 工具返回:", toolResult); // 步骤4：LLM 推理 const res = await llmClient.chat.completions.create({ model: MODEL_ROUTES.reasoning, messages: [ { role: "system", content: "你是助手，基于工具结果回答。" }, { role: "user", content: `${userInput}\n工具结果：${JSON.stringify(toolResult)}` }, ], }); console.log("[5/5] 最终响应:", res.choices[0].message.content); } e2eCheck().catch((err) => { console.error("E2E 验证失败:", err); process.exit(1); });

用tsx scripts/e2e-check.ts跑起来，正常输出应该类似：

[1/5] 用户输入: 帮我查一下北京今天的天气，然后总结成一句话 [2/5] RAG 检索到片段数: 3 [3/5] 规划结果: { "steps": ["call_weather", "summarize"] } [4/5] 工具返回: { "city": "北京", "temp": "18°C", "condition": "晴" } [5/5] 最终响应: 北京今天晴，气温 18°C，适合外出。

五个步骤全部有输出，说明链路是通的。如果某一步卡住或者报错，就定位到对应模块排查。

除了脚本验证，还要做一次"配置切换验证"：把MODEL_ROUTES.reasoning从gpt-4o改成gpt-4o-mini，重跑脚本，确认输出仍然正常。这一步验证的是"模型可替换性"——如果改个 model ID 就报错，说明你的收束没做干净，还有地方写死了模型名。

再做一个"Key 失效验证"：临时把TAOTOKEN_API_KEY改成一个错误值，重跑脚本，确认报错信息清晰（应该是 401 认证失败），而不是一堆看不懂的堆栈。这一步验证的是错误处理是否到位。

提示：回归验证脚本建议加进 CI，每次合并前自动跑一遍。Agent 项目涉及外部 API，最容易在重构时悄悄改坏某个调用，有自动化验证能省很多事。

验证通过之后，你的收束工作就基本完成了。但实际跑的时候，大概率会遇到一些报错，下一节专门讲怎么排查。

5. 收尾阶段常见报错排查

重构和统一 Key 的过程中，报错是必然的。下面是我和身边朋友实际踩过的几类，按出现频率排序。

第一类：401 Unauthorized / invalid api key

这是最常见的。原因通常是环境变量没加载、Key 复制时带了空格、或者.env.local没被 Next.js 读到。排查顺序：先在脚本里console.log(process.env.TAOTOKEN_API_KEY?.slice(0, 8))确认 Key 前几位对得上；再确认.env.local在项目根目录而不是src/下；最后确认 Key 没有过期或被删除。如果用的是 TaoToken 的 Key，去控制台的 API Keys 页面核对一下状态。

第二类：local proxy failed / connection refused

这个报错通常出现在你配置了本地代理或者自定义 baseURL 写错的时候。检查TAOTOKEN_BASE_URL是不是写成了https://taotoken.net（少了/api），或者写成了带 UTM 参数的官网地址。正确的 API 入口是https://taotoken.net/api，不带任何查询参数。另外确认你的运行环境能正常访问外网，公司内网有时候会拦截。

第三类：Cannot read properties of undefined (reading 'choices')

这个报错说明 API 返回的结构和你预期的不一样。常见原因是：请求根本没成功（返回的是错误对象），但你直接取了res.choices[0]。正确做法是先判断：

const res = await llmClient.chat.completions.create({...}); if (!res.choices || res.choices.length === 0) { throw new Error(`LLM 返回异常: ${JSON.stringify(res)}`); } const content = res.choices[0].message.content;

还有一种情况是流式响应没处理完就取结果，这个要确认你用的是stream: true还是false，两种模式的返回结构不同。

第四类：OAuth / authentication flow 相关报错

如果你在 Claude Code 或类似工具里配置，可能会遇到 OAuth 相关的提示。这类工具通常支持两种认证：OAuth 登录和 API Key。用 TaoToken 的话走 API Key 模式，在 settings 里把ANTHROPIC_API_KEY设成你的 Key，ANTHROPIC_BASE_URL设成https://taotoken.net/api，不要走 OAuth 流程。如果工具强制走 OAuth，检查一下是不是配置项名字写错了。

第五类：模型不存在 / model not found

这个通常是 model ID 拼错了，或者你用的模型在当前账号下没有权限。排查方法是先用一个最简单的请求测试：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'

如果这个能通，说明 Key 和 Base URL 没问题，问题在代码里的 model ID。如果这个也报 model not found，那就是模型名不对，去文档里核对可用的 model ID 列表。

第六类：超时 / timeout

Agent 项目链路长，一次请求可能串了好几个模型调用，很容易超时。建议在客户端初始化时设置合理的 timeout，并且对非关键路径的调用做异步化。比如记忆写入、日志记录这些不影响主响应的操作，用Promise.allSettled并行处理，不要串行 await。

排查这类问题的通用思路是：先隔离，再定位。用 curl 或独立脚本单独测某一层，确认是配置问题还是代码问题，比在完整链路里瞎猜高效得多。

6. 收束完成后的下一步：把统一入口用起来

走到这里，你的 Agent 项目应该已经完成了三件事：模型调用收敛到lib/llm/client.ts一个入口，目录结构按职责分层，端到端回归验证通过。这就是"架构终章"该有的样子——不是功能最多，而是结构最清晰。

接下来你可以做的，是把这套统一入口真正用起来。比如在 Coding Plan 里配置长期编码任务，让 Agent 在统一 Key 下持续跑；或者在控制台里查看各模型的调用量和成本分布，据此调整models.toml里的路由策略。这些动作都建立在"模型调用只有一个入口"的前提上，如果入口还是散的，统计和优化都无从谈起。

如果你在排查过程中遇到认证或接入问题，可以直接看接入文档，里面有各语言 SDK 的完整示例。需要新建或管理 Key 的话，API Keys 页面是入口。想先验证某个模型的实际效果，模型对话页面可以快速试跑，不用写代码。

架构收束不是终点，而是让后续迭代有据可依的起点。当变更成本降下来，你才敢放心地加功能、换模型、扩规模。这一章做的事，就是把这个基础打牢。