企业官网建设流程全解析

1. 为什么单Agent写不动真实项目，5角色团队才跑得通

CrewAI 是一个用「角色 + 任务 + 团队」三层抽象来编排多 Agent 协作的 Python 框架，它能让产品经理、架构师、开发、审查、测试五个 Agent 像真实小组一样接力干活。这篇面向已经会写 Python、但被单 Agent 上下文爆炸和任务串行卡住的同学，交付一份可直接复制的config.toml与settings.json骨架，把五个角色的模型调用统一收敛到 TaoToken 一个 Key 上，最后跑一次端到端协作验证。

单 Agent 做「开发一个记账 API」这种需求时，问题很具体：它要在同一个上下文里同时记住需求、表结构、接口签名、测试断言，窗口一满就开始丢前面的约束，改到第三轮连字段名都对不上。多 Agent 的价值不是「更聪明」，而是把一份长上下文切成五份短上下文，每个角色只背自己那一段，交接靠结构化产物而不是靠记忆。

我试过把五个角色塞进一个 prompt 里让它自己扮演，前两轮还行，到代码审查环节它就开始「自己夸自己」，因为审查者和开发者共享同一段思维链，根本挑不出毛病。拆成独立 Agent 后，审查者拿到的是开发者产出的文件内容，没有「我刚写的」这种心理包袱，挑错率明显上升。

CrewAI 的核心就三个概念：Agent 扮演角色、Task 描述具体工作、Crew 把人和活组织起来。它的Process.sequential让任务按依赖顺序执行，前一个 Task 的输出自动成为后一个的context，这就是「接力」的机制。下面所有配置都围绕这个机制展开。

2. 前置准备：TaoToken 统一 Key 与项目骨架

多 Agent 最烦的是每个角色配一个模型供应商，Key 散落在五处，换模型要改五个文件。TaoToken 提供统一 API 通道，一个 Key 就能调用不同模型，正好适配「架构师用推理强的、开发用代码强的、审查用长上下文强的」这种分工。

先去控制台创建 Key，地址是 https://taotoken.net/api-keys ，登录后新建一个 Key 复制出来。接入文档在 https://taotoken.net/doc ，里面有各语言 SDK 的 base_url 写法，Python 侧统一用 OpenAI 兼容协议即可。

项目初始化用 uv，比 pip 快很多：

uv init crew-dev-team cd crew-dev-team uv add crewai crewai-tools openai python-dotenv tomli

目录结构建议这样，配置和代码分离，方便你把 Key 换成环境变量：

crew-dev-team/ ├── config/ │ ├── config.toml │ └── settings.json ├── src/ │ ├── agents.py │ ├── tasks.py │ └── crew.py ├── .env └── pyproject.toml

.env里只放一行，别把 Key 写进代码：

TAOTOKEN_API_KEY=sk-你的Key TAOTOKEN_BASE_URL=https://taotoken.net/api

注意：base_url 结尾不要带/v1，OpenAI SDK 会自己拼/chat/completions，多写一层会 404。这是接入时最常见的坑。

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

CrewAI 本身不强制读配置文件，但五个 Agent 的模型参数散在代码里很难维护。我用config.toml存角色定义，settings.json存模型路由，代码只负责组装。

先看config/config.toml，每个角色一段，model_key指向 settings.json 里的模型别名：

[llm] provider = "openai-compatible" base_url_env = "TAOTOKEN_BASE_URL" api_key_env = "TAOTOKEN_API_KEY" timeout = 120 max_retries = 3 [agents.product_manager] role = "产品经理" model_key = "reasoning" allow_delegation = false max_iter = 8 [agents.tech_lead] role = "技术架构师" model_key = "reasoning" allow_delegation = true max_iter = 10 [agents.developer] role = "开发工程师" model_key = "coding" allow_delegation = false max_iter = 15 [agents.code_reviewer] role = "代码审查员" model_key = "long_context" allow_delegation = false max_iter = 8 [agents.qa_engineer] role = "测试工程师" model_key = "coding" allow_delegation = false max_iter = 12

再看config/settings.json，把模型别名映射到 TaoToken 上的具体模型名。这里的关键是「别名」这一层，将来换模型只改这个文件：

{ "models": { "reasoning": { "name": "gpt-5.5", "temperature": 0.3, "max_tokens": 4096 }, "coding": { "name": "claude-4-sonnet", "temperature": 0.1, "max_tokens": 8192 }, "long_context": { "name": "claude-4-sonnet", "temperature": 0.2, "max_tokens": 8192 } }, "crew": { "process": "sequential", "verbose": true, "memory": false } }

参数对照说明一下，方便你按预算调：

读取配置的代码很短，用 tomli 和 json 各读一次，然后拼成 CrewAI 需要的 LLM 对象：

import json import os import tomli from openai import OpenAI def load_config(): with open("config/config.toml", "rb") as f: cfg = tomli.load(f) with open("config/settings.json", "r", encoding="utf-8") as f: settings = json.load(f) return cfg, settings def build_llm(model_key, cfg, settings): m = settings["models"][model_key] return { "model": m["name"], "base_url": os.environ["TAOTOKEN_BASE_URL"], "api_key": os.environ["TAOTOKEN_API_KEY"], "temperature": m["temperature"], "max_tokens": m["max_tokens"], }

CrewAI 的LLM类接受base_url和api_key参数，把上面这个 dict 展开传进去就行。这样五个角色共用同一个 Key，模型差异只体现在model字段上。

4. 五角色定义与任务链组装

角色定义的重点是backstory要写「行为约束」，不是写「人设」。比如审查员要明确「每个问题必须给出修改建议」，否则它会只报问题不给方案，下游测试 Agent 拿不到可执行输入。

src/agents.py里五个角色这样写，注意llm从配置构建：

from crewai import Agent from config_loader import load_config, build_llm cfg, settings = load_config() def make_agent(key): a = cfg["agents"][key] return Agent( role=a["role"], goal=GOALS[key], backstory=BACKSTORIES[key], llm=build_llm(a["model_key"], cfg, settings), allow_delegation=a["allow_delegation"], max_iter=a["max_iter"], verbose=True, ) GOALS = { "product_manager": "把模糊需求转成含验收标准的 PRD", "tech_lead": "输出含数据模型和接口签名的技术方案", "developer": "按方案写出可运行、带类型注解的代码", "code_reviewer": "逐条列出问题并给出修改建议", "qa_engineer": "编写覆盖边界和异常的测试并报告结果", } BACKSTORIES = { "product_manager": "你关注用户价值，每条需求都有可验证的验收标准。", "tech_lead": "你精通 FastAPI 与 SQLAlchemy，方案必须落到具体表字段。", "developer": "你先写测试再写实现，代码必须有类型注解和文档字符串。", "code_reviewer": "你只报有依据的问题，每条附具体修改代码。", "qa_engineer": "你专测边界值和异常路径，测试必须能实际运行。", } product_manager = make_agent("product_manager") tech_lead = make_agent("tech_lead") developer = make_agent("developer") code_reviewer = make_agent("code_reviewer") qa_engineer = make_agent("qa_engineer")

任务链的关键是context字段，它声明「我这个任务依赖谁的输出」。CrewAI 会把被依赖任务的产出拼进当前任务的 prompt，这就是接力：

from crewai import Task def create_tasks(project_desc): t1 = Task( description=f"分析需求并输出 PRD：\n{project_desc}\n" "PRD 必须含功能列表、优先级、验收标准。", expected_output="Markdown 格式 PRD", agent=product_manager, ) t2 = Task( description="根据 PRD 设计技术方案：数据模型、API 签名、目录结构。", expected_output="Markdown 格式技术设计文档", agent=tech_lead, context=[t1], ) t3 = Task( description="按技术方案实现代码，每个文件给出完整内容。", expected_output="文件路径与完整代码的列表", agent=developer, context=[t2], ) t4 = Task( description="审查代码，逐条列出问题并给出修改后的代码片段。", expected_output="审查报告，含问题清单与修改建议", agent=code_reviewer, context=[t3], ) t5 = Task( description="为代码编写单元测试与边界测试，并说明如何运行。", expected_output="测试文件内容与运行命令", agent=qa_engineer, context=[t3, t4], ) return [t1, t2, t3, t4, t5]

src/crew.py把 Agent 和 Task 组装起来，Process.sequential保证按 t1 到 t5 顺序执行：

from crewai import Crew, Process from agents import product_manager, tech_lead, developer, code_reviewer, qa_engineer from tasks import create_tasks def run_crew(project_desc): crew = Crew( agents=[product_manager, tech_lead, developer, code_reviewer, qa_engineer], tasks=create_tasks(project_desc), process=Process.sequential, verbose=True, ) return crew.kickoff() if __name__ == "__main__": desc = """ 开发一个个人记账 API： - 用户注册登录（JWT） - 记录收支（金额、类别、日期、备注） - 按月统计报表 技术栈：FastAPI + SQLAlchemy + SQLite """ result = run_crew(desc) print(result)

5. 验证请求：一次端到端协作跑通

跑之前先单独验证 TaoToken 通道是通的，避免把网络问题误判成 CrewAI 配置问题。用一段最小请求测：

import os from openai import OpenAI client = OpenAI( api_key=os.environ["TAOTOKEN_API_KEY"], base_url=os.environ["TAOTOKEN_BASE_URL"], ) resp = client.chat.completions.create( model="gpt-5.5", messages=[{"role": "user", "content": "只回复两个字：通了"}], ) print(resp.choices[0].message.content)

看到「通了」两个字，说明 Key 和 base_url 都对。这一步失败的话，先查 Key 是否复制完整、base_url 是否多写了/v1。

然后跑完整团队：

uv run python src/crew.py

成功时终端会依次打印五个 Agent 的执行日志，最后输出一份合并结果。判断是否真的跑通，看三个信号：产品经理的 PRD 里有没有「验收标准」小节；开发者的输出里有没有出现具体文件路径如app/models.py；测试工程师有没有给出pytest运行命令。三个都有，说明任务链的 context 传递是有效的。

如果只想快速验证模型通道而不跑全流程，可以直接用模型对话页面发一条消息，地址是 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ，比本地起项目快。

6. 本篇常见报错排查

报错一：openai.AuthenticationError: Incorrect API key九成是.env没被加载。CrewAI 不会自动读.env，要在crew.py顶部加from dotenv import load_dotenv; load_dotenv()。另一个可能是 Key 前后有空格，复制时带上了换行。

报错二：Connection error或请求超时先确认TAOTOKEN_BASE_URL是https://taotoken.net/api，不带路径后缀。如果公司网络有出口限制，换网络环境再试。timeout 在 config.toml 里设了 120 秒，长任务可以调到 180。

报错三：ValidationError: llm field requiredCrewAI 的Agent不接受字符串模型名，必须传LLM对象或兼容的 dict。检查build_llm返回的 dict 是否包含model、base_url、api_key三个键，缺一个就会报这个。

报错四：任务输出为空或截断max_tokens设太小。代码类任务建议 8192，如果模型本身上限低于这个值，会被服务端截断。把 settings.json 里对应别名的max_tokens调低到模型实际支持的值。

报错五：审查员和开发者互相「打架」，任务卡住allow_delegation开太多。只有架构师需要转派，其他角色设 false。另外max_iter别设太大，开发 15 次循环还没产出就该人工介入，否则会一直烧 token。

报错六：ModuleNotFoundError: No module named 'tomli'Python 3.11 以下需要装 tomli，3.11 以上可以用内置tomllib。统一用 tomli 兼容性最好，uv add tomli即可。

7. 长期跑团队：把 Key 和模型路由管起来

五个角色跑一次消耗的 token 是单 Agent 的五倍以上，长期用必须把成本管住。我的做法是给每个角色设独立的max_tokens上限，产品经理和审查员用 4096 就够，只有开发和测试需要 8192。模型路由上，推理密集的架构设计用强推理模型，代码生成用代码专精模型，审查用长上下文模型，通过 settings.json 的别名层切换，不动业务代码。

如果你打算把这套团队接进 CI 或做成常驻服务，建议用 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 。

最后留一个实操建议：第一次跑别用完整记账项目，先用「写一个字符串反转函数」这种小需求验证五个角色的交接是否顺畅，确认 context 传递没问题，再换真实项目。这样出问题时能快速定位是配置问题还是任务描述问题。