企业官网建设流程全解析

1. 从空目录到 Todo Demo：我为什么要用三个 Agent 跑一遍

Claude Code 的 Agent Teams 是实验特性，简单说就是让一个主会话里同时跑多个带角色的 Agent，各自有独立上下文，能互相发消息、派任务、等结果。它适合谁？适合已经会用 Claude Code 单 Agent 写代码、想观察多角色协作边界的人。我这次的目标很具体：一个空目录，三个 Agent，分别负责 FastAPI 后端、React 前端、联调验证，共用一条 TaoToken 统一 Key 通道，把 Todo Demo 从零跑到端到端可用。

为什么强调统一 Key？因为三个 Agent 并行时，每个 Teammate 都是独立的模型调用实例，如果各自配一套 Key，额度、限流、日志会散成三份，排查问题时根本对不上账。我试过把 Key 分散配置，结果 QA Agent 跑到一半报 429，前端 Agent 却还在正常请求，定位花了十几分钟。统一走 TaoToken 的 API 通道后，所有 Agent 的请求都从同一个入口出，出问题只看一处日志就行。

这篇笔记给的是可跟做的骨架：settings.json 和 config.toml 怎么填、三个 Agent 的分工提示词模板长什么样、Todo Demo 端到端跑通要做哪些验证动作、以及我踩过的坑。不追求业务复杂度，只看协作流程能不能串起来。

2. TaoToken 前置：统一 Key 与 API 通道怎么接

TaoToken 在这里的角色是统一模型调用入口。你不需要给每个 Agent 单独申请 Key，而是拿一个 Key，通过它的 API 地址让 Claude Code 的所有模型请求都走这条通道。官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api ，注意 API 地址不加 UTM 参数。

先拿 Key。进入控制台创建 API Key，页面在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，Key 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。创建后复制那串 sk- 开头的字符串，后面配置要用。

这里有个容易混的点：Claude Code 读的是环境变量，不是你在某个配置文件里写死就行。所以统一 Key 的落地方式是——把 Key 写进环境变量，让主会话和所有 Teammate 继承同一份。下面两节分别给 settings.json 和 config.toml 的骨架，你按自己系统选一种。

注意：Key 只放环境变量或本地配置文件，不要提交到 git，也不要在提示词里明文粘贴。

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

3.1 settings.json 配置骨架

Claude Code 的用户级配置在~/.claude/settings.json。这个文件负责开启 Agent Teams 实验开关，并把模型请求指向 TaoToken 通道。下面是我实际用的骨架，把sk-你的Key换成你自己的：

{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1", "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-4-5" }, "teammateMode": "auto" }

几个参数说明。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS置 1 才会启用多 Agent 能力，不设的话你只能跑单 Agent。ANTHROPIC_BASE_URL指向 TaoToken 的 API 基址，注意结尾不要多加斜杠。ANTHROPIC_API_KEY就是刚才拿到的统一 Key。teammateMode设 auto，Claude Code 会根据终端环境自己决定用分屏还是进程内模式。

如果你不想改全局配置，也可以在项目目录下建.claude/settings.json，只对当前项目生效。我建议实验阶段用项目级，避免污染其他项目。

3.2 config.toml 配置骨架

有些环境走的是 config.toml 形式，比如你在用支持 TOML 配置的客户端或包装层。骨架如下：

[env] CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1" ANTHROPIC_BASE_URL = "https://taotoken.net/api" ANTHROPIC_API_KEY = "sk-你的Key" ANTHROPIC_MODEL = "claude-sonnet-4-5" [agent_teams] teammate_mode = "auto" max_teammates = 3

max_teammates限制同时活跃的 Teammate 数量，这次实验就是 3 个。设太大 Token 消耗会失控，后面排错章节会讲。

3.3 验证配置是否生效

配完先别急着开团队，跑一条最小请求确认通道通。用 curl 直接打 TaoToken 的 API：

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

返回里能看到content字段带文本，就说明 Key 和通道都正常。如果返回 401，检查 Key 有没有复制全；返回 404，检查 base URL 是不是写成了带/v1的完整路径导致重复。

4. 三个 Agent 的分工提示词模板

配置通了，接下来是团队组建。Agent Teams 的关键在于提示词要把角色边界写死，否则三个 Agent 会互相抢活。下面是我用的分工模板，你可以直接改。

4.1 Team Lead 总指令

在空目录启动 Claude Code 后，第一段输入总指令，核心是把 API 契约先定下来：

项目：Todo List 应用 技术栈：后端 Python 3.11 + FastAPI + SQLite；前端 React 18 + Vite + TailwindCSS；测试 pytest + httpx + Playwright API 契约（唯一真实数据源）： Base URL: http://localhost:8000/api/v1 GET /todos 获取全部，返回 [{id, title, completed, created_at}] POST /todos 创建，请求 {"title": "..."}，返回 201 PUT /todos/{id} 更新，请求 {"title":"...", "completed":true} DELETE /todos/{id} 删除，返回 {"message":"deleted"} 状态码：200 成功、201 创建、404 未找到、422 校验失败 字段：id int, title str, completed bool, created_at ISO8601 请先输出 API_CONTRACT.md，再启动三个 Teammate： @backend-dev 实现 FastAPI 后端，交付可运行服务 uvicorn main:app --reload @frontend-dev 实现 React 前端，proxy 指向 8000 端口 @qa-engineer 先写测试框架，开发完成后执行联调验证

这段指令管用的原因有三个。契约写在提示词里，三个 Agent 不用猜接口。交付物具体到运行命令，Agent 知道什么算做完。QA 被当成独立角色，不是"顺便测测"。

4.2 后端 Agent 提示词

你是 Backend Dev。严格按 API_CONTRACT.md 实现，不擅自扩展接口。 任务：用 FastAPI 搭 main.py / models.py / schemas.py / database.py， SQLAlchemy + SQLite 定义 Todo 模型，实现完整 CRUD，加 Pydantic 校验和 CORS。 交付：可独立运行的后端，命令 uvicorn main:app --reload。 完成后用 SendMessage 通知 Team Lead。

4.3 前端 Agent 提示词

你是 Frontend Dev。只读 API_CONTRACT.md，发现歧义发消息问 Team Lead，不要猜。 任务：Vite + React + TailwindCSS 初始化，实现列表展示、添加输入框、 完成切换、删除按钮，封装 API 调用层，配置 proxy 到 8000 端口。 交付：可独立运行的前端，npm run dev 能起。

4.4 QA Agent 提示词

你是 QA Engineer，最苛刻的质量守门人，宁可误报不可漏报。 阶段 1：开发开始前先写集成测试和契约测试框架。 阶段 2：后端完成后执行代码审查、单元测试、集成测试、契约测试。 阶段 3：前端完成后执行构建验证和 E2E 测试。 遇到数字或文字对不上时先停下来确认，不要猜着干。

角色定义越鲜明，协作越顺。反面例子是三个角色都叫"开发者"，你会看到它们互相抢活、重复实现。

5. 端到端验证：Todo Demo 跑通要做哪些动作

三个 Agent 跑起来后，验证不能只看"它说完成了"。下面是我实际执行的验证动作，按顺序做。

5.1 后端独立验证

后端 Agent 报告完成后，先单独验证后端能不能起：

cd backend pip install -r requirements.txt uvicorn main:app --reload

另开一个终端打接口：

curl -s -X POST http://localhost:8000/api/v1/todos \ -H "content-type: application/json" \ -d '{"title":"写实验笔记"}'

返回 201 且带id、created_at字段，说明创建通了。再打 GET 确认列表里有这条：

curl -s http://localhost:8000/api/v1/todos

5.2 前端独立验证

cd frontend npm install npm run dev

浏览器打开 Vite 给的地址，添加一条 Todo，看列表是否出现。如果请求报 CORS，检查后端 CORS 配置有没有放行前端端口。

5.3 端到端联调验证

前后端都起来后，走一遍完整用户路径：打开页面 → 添加 Todo → 勾选完成 → 删除 → 列表恢复为空。这一步 QA Agent 会用 Playwright 自动跑，你也可以手动过一遍。

5.4 验证结果对照

我这次跑下来，后端 7 个文件、前端 12 个文件，自动化测试 72 项全过，覆盖率 99%。数字只说明这个 Demo 跑通了，不代表能外推到真实业务。

6. 本篇常见错排查

6.1 Agent 起不来或只有一个在跑

先查版本。Agent Teams 需要 Claude Code v2.1.32+，用claude --version确认。再查环境变量有没有生效，echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS应该输出 1。如果 settings.json 改了但没生效，重启会话。

6.2 请求报 401 或 403

大概率是 Key 问题。检查ANTHROPIC_API_KEY有没有复制全，前后有没有多余空格。如果 Key 是对的还报错，去控制台看额度是否用完，页面在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。

6.3 请求报 404

检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/v1。基址只到/api，客户端会自己拼/v1/messages，你多写一层就重复了。

6.4 三个 Agent 互相抢活

这是提示词没写清角色边界。回到第 4 节，把每个 Agent 的职责和交付物写具体。特别是 QA，要明确它是独立角色，不是开发的附属。

6.5 Token 消耗过快

每个 Teammate 是独立实例，3 个 Agent 并行消耗是单人的数倍。省钱关键是委派模式：Team Lead 只管协调不写代码。如果 Team Lead 也下场写代码，上下文会变重，消耗翻倍。另外max_teammates别设太大，线性任务别硬拆。

6.6 端口冲突

后端 8000、前端 5173 是默认端口。如果被占用，后端换uvicorn main:app --port 8001，前端在 vite.config.js 改 server.port，同时更新 proxy 目标。

6.7 数据库脏状态导致复现失败

实验收尾要关进程、删数据库。SQLite 有三件套：.db、.db-wal、.db-shm，只删.db下次可能读到残留 WAL。清理命令：

rm -f todo.db todo.db-wal todo.db-shm

7. 收尾与下一步

实验跑完，Team Lead 给三个 Agent 发 shutdown_request，然后清理 Team 资源。这一步别省，否则下次复现会被脏状态干扰。

如果你想把这条链路用得更顺，几个入口按需取：验证模型对话效果走 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite ；长期编码或 Agent 场景看 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ；接入细节和报错对照查文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ；Claude Code 相关配置参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude-code-anthropic&utm_campaign=rewrite 。

最后留一句实操建议：先写契约再开工，角色任务具体到交付物，给 QA 独立地位，遇到冲突先停。这四条比任何配置都值钱。