企业官网建设流程全解析

1. Cloud Agent 的 Web 交互层为什么先卡在“事件怎么到浏览器”

Cloud Agent 是什么？简单说，它把原本跑在终端里的 Agent 循环搬到了浏览器里：你在网页上发一句话，服务端跑 LLM 推理、调工具、读文件，再把每一步状态实时推回页面。能做什么？让多个用户同时开多个会话，刷新页面不丢消息，点“停止”能立刻中断。适合谁？正在把 CLI 版 Agent 改造成 Web 服务的开发者，尤其是已经跑通query()和 Tool 体系、准备补上交互层与持久化这一段的人。

我踩过的第一个坑不是模型调用，而是“事件怎么到浏览器”。终端里 Claude Code 用 Ink + React 直接消费 AsyncGenerator，事件根本不经过网络；到了 Web，服务端和浏览器之间必须有一条流式协议。可选的就两条路：WebSocket 和 SSE。

WebSocket 双向、能力强，但 Cloud Agent 的交互本质是单向的：服务端持续推流，客户端只在两个时刻发信号——初始请求和点“停止”。为这点双向能力引入 WebSocket 的心跳、重连、连接状态管理，性价比不高。SSE 更轻，浏览器原生支持断线重连语义，Hono 这类框架内置支持，不需要额外依赖。所以主通道选 SSE。

但浏览器原生的EventSource有个硬伤：不支持自定义请求头，加不了 JWT。认证链路不能妥协，于是改用fetch+ReadableStream手动解析 SSE 字节流。多写几十行解析代码，换来完整的鉴权能力，这笔账划算。

线缆格式很直接，服务端按 SSE 规范输出：

event: text data: {"content":"正在读取配置文件..."} event: tool_result data: {"tool_use_id":"toolu_01","content":"...","is_error":false}

事件类型覆盖对话全部状态，常见的有text（LLM 文本增量）、content_block_start（开始输出 tool_use）、content_block_delta（工具参数流式增量）、content_block_stop（参数接收完毕）、tool_result（工具执行完成）、usage（token 统计）、done（循环正常结束）、error（异常）、user（中断插入的消息）、user_question（AskUserQuestion 触发）。一轮query()的典型时序是：text若干 →content_block_start→content_block_delta多次 →content_block_stop→tool_result→usage→done，中间可能穿插多轮工具调用。

这里有个命名上的小插曲。最初沿用了 V1 里偏消息类型的名字，后来翻 Claude Code 源码发现它的事件名更简洁（text、tool_use、tool_result），就统一过去了。命名统一之后，前端 switch 分支和后端 yield 点能一一对应，排障时省了很多“这个名字到底对应哪个阶段”的来回确认。

多用户多会话的状态隔离是第二个坎。一个用户可能同时开着好几个 Session，各自跑各自的 Agent 循环。Zustand store 按sessionId分区，每个会话的消息、SSE 连接状态、工具执行状态都存在独立分区里。用户从会话 A 切到 B 时，A 的 SSE 流在后台继续跑到结束，不会因为切走被强行终止；B 的消息从独立分区加载，不会和 A 串数据。

这个设计踩过一个真实的坑：切换会话时 SSE 事件串到了另一个会话里。排查发现是 store 没有严格按sessionId隔离——收到 SSE 事件后直接往“当前会话”的数组里 push，没检查事件的sessionId和当前显示的sessionId是否一致。修完之后加了分区边界检查，tool_use的 running 状态也按sessionId独立追踪。这个 bug 的教训是：流式事件天然带异步性，任何“当前”这种隐式上下文都不可靠，必须显式带上归属 ID。

2. 用 TaoToken 统一 Key 管理模型调用凭证

交互层跑通之后，下一个问题是模型调用凭证怎么管。Cloud Agent 里模型调用点不止一处：主对话循环、工具结果摘要、AskUserQuestion 的追问生成，未来还可能接不同的模型做不同任务。如果每个调用点各自读环境变量、各自拼 Base URL，配置会散得到处都是，换一个 Key 要改五六个地方。

TaoToken 在这里的角色是统一 Key 与 API 通道管理：把模型调用的凭证收敛到一个入口，Agent 代码只认一个 Base URL 和一个 Key，具体走哪个模型由配置决定。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api （不加 UTM）。

先说清楚它解决什么、不解决什么。它解决的是“凭证集中管理 + 通道统一”，不替代你的编辑器，也不替代 Agent 引擎本身。你的query()循环、Tool 体系、pathGuard 都还是自己写，TaoToken 只负责模型调用这一层的接入。

接入前需要准备三件套，这三件套在任何客户端里都是同一组：

• Base URL：https://taotoken.net/api
• API Key：在控制台创建，形如sk-...
• Model ID：按你实际要用的模型填，比如claude-sonnet-4-5这类标识

控制台创建 Key 的入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API Keys 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

为什么要在 Cloud Agent 里做这层收敛？因为 Agent 的模型调用有三个特点：频率高（一轮对话可能多次调用）、位置散（主循环、摘要、追问各一处）、需要可观测（token 用量要统计进usage事件）。如果凭证散落，用量统计就没法统一，换模型也要逐个改。收敛到一个配置对象之后，usage事件的input_tokens、output_tokens、cache_*字段能在一个地方汇总，前端展示的 token 统计才准确。

还有一个实际考虑：开发阶段经常要在不同模型之间切换对比效果。如果 Base URL 和 Key 写死在代码里，每次切换都要改代码重启。收敛到配置文件之后，改一行 Model ID 重启即可，主循环代码完全不动。

需要提醒的是，Key 属于敏感凭证，不要提交进 Git 仓库。配置文件里可以放占位符，真实 Key 通过环境变量注入，或者用.gitignore排除本地配置文件。这一点在多人协作的项目里尤其重要，一旦 Key 进了提交历史，清理起来很麻烦。

3. 可复制的 settings.json 与 config.toml 配置骨架

这一节给可直接复制的配置骨架。不同客户端读的配置文件不一样，Claude Code 系读settings.json，Codex 系读config.toml，Cline 走 MCP 配置。三件套（Base URL + Key + Model ID）在每个文件里都要写全。

先看 Claude Code 的settings.json，路径通常在~/.claude/settings.json：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-4-5" }, "permissions": { "allow": [ "Read", "Write", "Bash(git status)", "Bash(npm run test)" ] } }

这里ANTHROPIC_BASE_URL指向 TaoToken 的 API 端点，ANTHROPIC_AUTH_TOKEN填控制台创建的 Key，ANTHROPIC_MODEL填 Model ID。三个字段缺一不可，少任何一个都会在请求阶段报错。

再看 Codex 系的config.toml，路径通常在~/.codex/config.toml：

model = "claude-sonnet-4-5" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" [profiles.default] model = "claude-sonnet-4-5" model_provider = "taotoken"

Codex 的auth.json单独存凭证，路径通常在~/.codex/auth.json：

{ "TAOTOKEN_API_KEY": "sk-你的Key" }

config.toml里用env_key引用auth.json中的键名，这样凭证和配置分离，配置文件可以进版本库，凭证文件单独排除。

Cline 走 MCP 配置，在 Cline 的设置里填三件套：

{ "mcpServers": { "taotoken": { "command": "npx", "args": ["-y", "@taotoken/mcp-server"], "env": { "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_API_KEY": "sk-你的Key", "TAOTOKEN_MODEL": "claude-sonnet-4-5" } } } }

CC Switch 用来在多个配置之间切换，它的配置文件里同样要写全三件套：

{ "providers": [ { "name": "taotoken", "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key", "model": "claude-sonnet-4-5" } ], "active": "taotoken" }

配置写完之后，Cloud Agent 服务端的模型调用层要读同一份配置。我建议在服务端做一个loadModelConfig()，从环境变量或配置文件读三件套，返回一个统一对象：

interface ModelConfig { baseUrl: string; apiKey: string; model: string; } function loadModelConfig(): ModelConfig { const baseUrl = process.env.TAOTOKEN_BASE_URL; const apiKey = process.env.TAOTOKEN_API_KEY; const model = process.env.TAOTOKEN_MODEL; if (!baseUrl || !apiKey || !model) { throw new Error("模型配置缺失：请检查 TAOTOKEN_BASE_URL / TAOTOKEN_API_KEY / TAOTOKEN_MODEL"); } return { baseUrl, apiKey, model }; }

这样主循环、摘要、追问三处调用都从loadModelConfig()拿配置，换模型只改环境变量，代码零改动。usage事件的统计也在这个统一层里汇总，前端拿到的 token 数据才一致。

4. 验证请求与 SSE 断线重连的实测动作

配置写完，先做一次最小验证请求，确认三件套能通。用 curl 直接打 API 端点：

curl -X POST https://taotoken.net/api/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: sk-你的Key" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-sonnet-4-5", "max_tokens": 64, "messages": [{"role": "user", "content": "回复 OK 两个字母"}] }'

返回里能看到content数组和usage字段，说明 Base URL、Key、Model ID 三件套都正确。如果这一步就报错，先别往下走，对照第 5 节的报错表排查。

验证通过后，测 SSE 通道。服务端起一个最小 SSE 端点：

import { Hono } from "hono"; import { streamSSE } from "hono/streaming"; const app = new Hono(); app.get("/api/sessions/:id/stream", async (c) => { const sessionId = c.req.param("id"); return streamSSE(c, async (stream) => { let id = 0; while (true) { await stream.writeSSE({ event: "text", data: JSON.stringify({ content: `chunk-${id}` }), id: String(id), }); id++; await stream.sleep(1000); } }); });

前端用fetch+ReadableStream手动解析，因为要带 JWT：

async function connectSSE(sessionId: string, token: string) { const res = await fetch(`/api/sessions/${sessionId}/stream`, { headers: { Authorization: `Bearer ${token}` }, }); const reader = res.body!.getReader(); const decoder = new TextDecoder(); let buffer = ""; while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const parts = buffer.split("\n\n"); buffer = parts.pop()!; for (const part of parts) { const lines = part.split("\n"); let event = "message"; let data = ""; for (const line of lines) { if (line.startsWith("event: ")) event = line.slice(7); if (line.startsWith("data: ")) data = line.slice(6); } handleEvent(event, JSON.parse(data)); } } }

断线重连是 SSE 的关键验证点。服务端每个事件带id字段，浏览器重连时会在请求头带Last-Event-ID。服务端要支持从这个 ID 之后继续推：

app.get("/api/sessions/:id/stream", async (c) => { const lastEventId = c.req.header("Last-Event-ID"); const startFrom = lastEventId ? parseInt(lastEventId) + 1 : 0; return streamSSE(c, async (stream) => { for (let id = startFrom; id < startFrom + 100; id++) { await stream.writeSSE({ event: "text", data: JSON.stringify({ content: `chunk-${id}` }), id: String(id), }); await stream.sleep(200); } }); });

验证动作：打开浏览器 DevTools 的 Network 面板，找到 SSE 请求，手动切到 Offline 再切回 Online，观察是否自动重连并带上Last-Event-ID。如果重连后从断点继续推，说明断线重连链路通了。

持久化写入的验证动作：发一条消息，等 Agent 跑完，检查data/messages/{sessionId}.jsonl文件是否追加了新行。用tail -f实时观察：

tail -f data/messages/sess_abc123.jsonl

每行应该是一个完整的 JSON 对象，包含role、content、timestamp。刷新浏览器页面，消息应该从 JSONL 重新加载出来，不丢。再开一个会话，确认两个会话的 JSONL 文件独立，互不干扰。

SQLite 元数据的验证：用sqlite3直接查：

sqlite3 data/agent.db "SELECT id, name FROM aac_sessions WHERE project_id = 'proj_001';"

能查到会话元信息，说明 SQLite 写入正常。WAL 模式下并发读不阻塞写，多用户场景下这个特性很重要。

5. 本篇常见报错排查：401、local proxy failed、reading choices、OAuth

这一节对照真实报错逐个排查。这些错误在接入阶段出现频率最高，按顺序排查能省很多时间。

401 Unauthorized。最常见的原因是 Key 没填对或没生效。先确认ANTHROPIC_AUTH_TOKEN或TAOTOKEN_API_KEY的值是完整的sk-...，没有多余空格或换行。再确认 Base URL 是https://taotoken.net/api，不是首页地址。如果用的是环境变量注入，确认服务进程重启过，环境变量改动不会热生效。还有一种情况是 Key 被禁用或额度耗尽，去控制台 API Keys 页面确认状态。

local proxy failed。这个报错通常出现在客户端配置了本地代理但代理没起来。检查settings.json或config.toml里有没有残留的HTTP_PROXY、HTTPS_PROXY配置。如果有，删掉或确认代理进程在跑。Cloud Agent 服务端如果部署在容器里，容器内的代理环境变量也要检查。这个报错和模型配置无关，纯粹是网络层的问题。

reading choices 相关报错。这类报错通常出现在响应解析阶段，提示读取choices字段失败。原因是请求打到了 OpenAI 兼容格式的端点，但客户端按 Anthropic 格式解析，或者反过来。确认你的客户端和端点格式匹配：TaoToken 的/api端点同时支持两种格式，但请求头要对应。Anthropic 格式用x-api-key+anthropic-version，OpenAI 格式用Authorization: Bearer。混用会导致响应结构对不上，解析choices或content时报错。

OAuth 相关报错。如果客户端走 OAuth 流程而不是 API Key，报错通常提示 token 过期或 scope 不足。Cloud Agent 场景建议直接用 API Key，不走 OAuth，链路更短、排障更简单。如果确实需要 OAuth，确认回调地址配置正确，token 刷新逻辑有兜底。

SSE 事件串会话。这个不是报错，是静默 bug，但危害大。现象是切换会话后消息出现在错误的会话里。排查方法：在handleEvent里打印事件的sessionId和当前 store 的activeSessionId，看是否一致。修复方式是在 push 之前加边界检查：

function handleEvent(event: string, data: any) { const eventSessionId = data.sessionId; const activeId = useStore.getState().activeSessionId; if (eventSessionId !== activeId) { // 事件属于后台会话，写入对应分区，不写当前显示分区 useStore.getState().appendToSession(eventSessionId, event, data); return; } useStore.getState().appendToActive(event, data); }

JSONL 写入乱序。多轮工具调用并发写同一个 JSONL 文件时，可能出现行交错。原因是多个appendFile调用没有串行化。修复方式是用一个写队列，按sessionId串行追加：

const writeQueues = new Map<string, Promise<void>>(); function appendMessage(sessionId: string, msg: object) { const prev = writeQueues.get(sessionId) ?? Promise.resolve(); const next = prev.then(() => fs.appendFile(`data/messages/${sessionId}.jsonl`, JSON.stringify(msg) + "\n") ); writeQueues.set(sessionId, next); return next; }

SQLite database is locked。WAL 模式下并发写仍可能锁。确认开启了 WAL：PRAGMA journal_mode=WAL;。写入用事务批量提交，减少锁持有时间。如果还是频繁锁，检查是不是有长事务没提交。

排障时如果拿不准是配置问题还是代码问题，先用 curl 打一次 API 端点，把变量收敛到最小。curl 通了说明三件套没问题，问题在客户端代码；curl 不通说明配置或 Key 有问题。这个二分法能快速定位。

6. 把交互与落库链路一次跑通的收尾动作

到这里，SSE 通道、多会话隔离、中断处理、三层持久化都串起来了。最后给一个一次跑通的检查清单，按顺序执行：

第一步，确认三件套配置正确。settings.json或config.toml里 Base URL 是https://taotoken.net/api，Key 完整，Model ID 有效。用 curl 验证一次请求能返回。

第二步，起服务端，确认 SSE 端点可访问。浏览器直接打开 SSE 端点 URL，应该能看到事件流持续输出。

第三步，前端连上 SSE，发一条消息，观察事件时序是否符合预期：text→content_block_start→content_block_delta→content_block_stop→tool_result→usage→done。

第四步，检查data/messages/{sessionId}.jsonl是否追加了新行，刷新页面消息是否还在。

第五步，开第二个会话，确认两个会话的 SSE 流和 JSONL 文件独立，切换会话不串数据。

第六步，点“停止”，确认前端立即反馈，后端生成 synthetic tool_result，下一轮对话状态自洽。

如果这六步都过，交互与落库链路就通了。后续要扩展的方向：集群化时按第 1 节分析的四个方案选型，当前单实例用 sticky session 亲和最务实；模型调用层如果要接多个模型，在loadModelConfig()里加路由逻辑，主循环代码不用动。

需要长期跑编码任务或 Agent 工作流的，可以看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。想先在网页里验证模型效果的，用模型对话：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。接入过程中遇到配置或报错问题，先查接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，再去 API Keys 页面确认凭证状态：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。