企业官网建设流程全解析

第7节 Agent Teams官方机制对比：Claude Code/Codex的现成方案

一句话总结：两大官方多智能体机制的配置与玩法——.claude/agents/、.codex/agents/TOML、agent teams交接；什么时候该用官方机制vs自己写。

本文导航

• 一、为什么要看官方机制
• 二、Claude Code Agent Teams：Markdown定义智能体
• 三、Codex Agent Teams：TOML定义智能体
• 四、用Python解析与审计官方agent定义
• 五、官方机制 vs 自己写
• 六、实战：搭一套maker/checker/tester三件套
• 七、官方机制的局限清单
• 小结

一、为什么要看官方机制

前六节我们从零造了一遍编排系统：spawn、worktree、Supervisor、五种模式、编排税。自己造的好处是每个齿轮都摸过，坏处也很明显——每个齿轮都得自己维护。

Claude Code和Codex这两家官方CLI都内置了多智能体机制：定义几个agent文件，主对话里一句"让maker去写、checker去审"，框架替你完成spawn、上下文隔离、结果交接。本节把两家的机制拆开看，最后回答"什么时候用官方、什么时候自己写"。

先给一张全景对照：

注意最后一行：官方机制的日志是"框架级"的，你很难往里塞本课程要求的全字段记录（key尾6位、输入输出长度、起止耗时）。这是后面选型判断的重要砝码。

二、Claude Code Agent Teams：Markdown定义智能体

目录结构

.claude/ agents/ maker.md # 写代码 checker.md # 审查 tester.md # 测试

agent定义

<!-- .claude/agents/maker.md --> --- name: maker description: 写代码的工人 tools: [read_file, write_file, run_command] isolation: worktree --- 你是Python开发者，负责实现功能代码。 完成后输出结构化笔记。

文件分两段：frontmatter（两个---之间）是机器读的配置——名字、描述、工具白名单、隔离方式；正文是人写的系统提示词，spawn时原样成为子智能体的system prompt。

这个设计直接对应我们第2节的理论：tools就是allowed_tools白名单，isolation: worktree就是第3节的隔离机制，正文就是SubAgentConfig.system_prompt。官方机制没有发明新理论，它把前几节的模式做成了配置文件。理解了这一点，看任何框架的多智能体功能都不陌生。

三个角色各司其职：maker拿写权限，checker只读（tools: [read_file, grep_search]），tester只跑命令。审查者无写权限——第2节白名单三理由里的安全条款，官方机制的默认实践。

使用时在主对话里点名委派：让maker实现登录接口，让checker审它的diff。框架会为每个被点名的agent创建独立上下文（worktree隔离下还有独立目录），执行完把结构化结果交回主对话。主对话天然就是Supervisor——你不需要写decompose/dispatch代码，只要会派活。

但"主对话即Supervisor"有边界，两条要心里有数。其一，主对话的上下文同样会膨胀：一晚上的委派记录、agent返回、你的追问全堆在同一个会话里，第1节的注意力挤压会在对话层复发——长任务记得开新会话（相当于给Supervisor做了一次Compaction）。其二，对话式派活的确定性低于代码：让checker审一下这种自然语言指令，框架对"审什么、按什么标准、不通过怎么办"的理解存在漂移，同样的指令两天的执行路径可能不同。要确定性就得把委派指令写成可复用的模板（每类任务一段固定措辞），这实际上是在对话层重建配置文件——绕了一圈，你就理解为什么大型编排最终还是会沉淀回代码。

三、Codex Agent Teams：TOML定义智能体

TOML配置

# .codex/agents/worker.toml [agent] name = "worker" description = "工人智能体" model = "gpt-4o" [agent.tools] allowed = ["read_file", "write_file", "run_command"] [agent.isolation] type = "worktree"

Codex的思路相同，载体换成TOML。一个显著差异：Codex允许在agent级指定model——你可以让maker用强模型、checker用便宜模型、tester干脆用本地小模型。这个"模型分层"能力在成本控制上很实用（回顾第1节：子智能体吃掉90%的token，在它们身上做模型分级，省钱效果是9倍杠杆）。

Claude Code的Markdown定义和Codex的TOML定义，表达能力其实半斤八两。选哪家主要看你主力工具链在哪边，而不是配置格式本身。两家的worktree隔离选项都源自同一个认知：并行修改必须文件系统级隔离（第3节的结论在这里得到了官方背书）。

对照表收一下配置项映射：

四、用Python解析与审计官方agent定义

官方机制好用，但有个真实痛点：团队里agent文件越加越多，谁也说不清现在有几个agent、各自什么权限。我写了个解析器把.claude/agents/下的定义全部读出来，喂给pydantic校验——顺便演示"官方配置+自研工具"的混合玩法。

# src/ai_loop_course/agent_loader.py"""解析 .claude/agents/*.md 的agent定义：frontmatter + 正文系统提示词 工程规范：pydantic校验、logging双输出（按月分割保留12个月） """importloggingfromlogging.handlersimportTimedRotatingFileHandlerfrompathlibimportPathimportyaml# uv add pyyamlfrompydanticimportBaseModel,field_validator logger=logging.getLogger("agent_loader")logger.setLevel(logging.INFO)_fmt=logging.Formatter("%(asctime)s %(levelname)s %(message)s","%Y-%m-%d %H:%M:%S")forhin(logging.StreamHandler(),TimedRotatingFileHandler("logs/agent_loader.log",when="MIDNIGHT",interval=31,backupCount=12,encoding="utf-8")):h.setFormatter(_fmt)logger.addHandler(h)classAgentDef(BaseModel):"""一个官方agent定义的解析结果（字段不全直接校验失败暴露问题）"""name:strdescription:str=""tools:list[str]=[]isolation:str="none"system_prompt:str=""@field_validator("name")@classmethoddefname_lower(cls,v:str)->str:ifnotv.isidentifier():raiseValueError(f"agent名不合法：{v}（须为合法标识符）")returnv.lower()defparse_agent_md(path:Path)->AgentDef:"""解析单个agent定义：frontmatter用yaml读，正文整体作为system_prompt"""text=path.read_text(encoding="utf-8")parts=text.split("---",2)# ['', frontmatter, 正文]meta=yaml.safe_load(parts[1])or{}returnAgentDef(name=meta.get("name",path.stem),description=meta.get("description",""),tools=meta.get("tools",[]),isolation=meta.get("isolation","none"),system_prompt=parts[2].strip())defload_team(agents_dir:str|Path=".claude/agents")->list[AgentDef]:"""加载目录下全部agent定义，解析失败的单个跳过并告警"""team=[]formdinsorted(Path(agents_dir).glob("*.md")):try:team.append(parse_agent_md(md))logger.info("[load] %s 工具=%s 隔离=%s",md.name,team[-1].tools,team[-1].isolation)exceptExceptionasexc:logger.warning("[skip] %s 解析失败：%s",md.name,exc)returnteamif__name__=="__main__":forainload_team():print(f"{a.name:10s}tools={a.tools}isolation={a.isolation}"f"prompt={len(a.system_prompt)}字")

真实控制台输出

2026-03-20 11:15:33 INFO [load] checker.md 工具=['read_file', 'grep_search'] 隔离=none 2026-03-20 11:15:33 INFO [load] maker.md 工具=['read_file', 'write_file', 'run_command'] 隔离=worktree 2026-03-20 11:15:33 INFO [load] tester.md 工具=['read_file', 'run_command'] 隔离=none checker tools=['read_file', 'grep_search'] isolation=none prompt=42字 maker tools=['read_file', 'write_file', 'run_command'] isolation=worktree prompt=33字 tester tools=['read_file', 'run_command'] isolation=none prompt=40字

解析器里有三个设计点。split("---", 2)限定切两刀，正文里再出现---（比如agent提示词里教它写frontmatter）也不会切坏；field_validator校验agent名是合法标识符，防止配置里混进带空格的名字在后续代码里炸；单个文件解析失败只告警跳过，不让一个坏文件瘫痪整个团队的加载——团队配置的解析要按"尽力而为"设计，和第2节解析模型输出同一个哲学。

这个解析器还有个进阶玩法：把官方配置桥接进自研编排。AgentDef和第2节的SubAgentConfig字段几乎一一对应，写一个转换函数就能让官方定义的团队跑在自研Supervisor上：

defto_subagent_config(a:"AgentDef",max_steps:int=10)->"SubAgentConfig":"""官方agent定义 → 自研SubAgentConfig：字段直译，桥接两个世界"""returnSubAgentConfig(name=a.name,system_prompt=a.system_promptora.description,allowed_tools=a.tools,max_steps=max_steps,)

五行的桥接函数，价值在于配置资产不锁死：团队在官方CLI里打磨好的maker/checker提示词，一行转换就能进你的自研系统跑（享受全字段日志和可编程编排），反过来也一样。配置用官方格式写（门槛低、可复用），执行引擎按需选——这是我最终沉淀下来的混合姿势。

顺带一提，Codex的TOML用标准库tomllib读（Python 3.11+内置），五分钟就能写个姊妹版加载器，字段映射表在上一节给过了。两个加载器共用AgentDef模型，.claude和.codex的团队配置就能在同一个审计脚本里混跑。

团队配置审计：一个实用脚本

加载器只解决"读出来"，再进一步就是审计：权限配得对不对？角色齐不齐？我给团队定义了三条审计规则，写成可运行的检查器。

# src/ai_loop_course/agent_audit.py"""Agent团队配置审计：角色齐全性 + 权限最小化 + 并行隔离检查"""frompydanticimportBaseModelfromagent_loaderimportAgentDef,load_teamclassAuditFinding(BaseModel):"""一条审计发现：级别+描述"""level:str# error / warn / infomessage:strdefaudit(team:list[AgentDef])->list[AuditFinding]:"""三条规则：缺角色报错、审查者有写权限报错、并行修改无worktree报错"""findings=[]names={a.nameforainteam}# 规则1：写代码的团队必须有checker（有maker无checker=无人把关）if"maker"innamesand"checker"notinnames:findings.append(AuditFinding(level="error",message="有maker无checker，产出无人审查"))# 规则2：checker不允许有写权限（审查者篡改现场）forainteam:ifa.name=="checker"and({"write_file"}&set(a.tools)):findings.append(AuditFinding(level="error",message=f"checker持有写权限：{a.tools}"))# 规则3：持有write权限的agent建议worktree隔离（并行改仓库前提）forainteam:if"write_file"ina.toolsanda.isolation!="worktree":findings.append(AuditFinding(level="warn",message=f"{a.name}可写但未启用worktree隔离，并行会互踩"))ifnotfindings:findings.append(AuditFinding(level="info",message="团队配置通过全部审计规则"))returnfindingsif__name__=="__main__":team=load_team()forfinaudit(team):print(f"[{f.level.upper():5s}]{f.message}")

真实控制台输出

2026-03-20 11:20:47 INFO [load] checker.md 工具=['read_file', 'grep_search'] 隔离=none 2026-03-20 11:20:47 INFO [load] maker.md 工具=['read_file', 'write_file', 'run_command'] 隔离=worktree 2026-03-20 11:20:47 INFO [load] tester.md 工具=['read_file', 'run_command'] 隔离=none [INFO ] 团队配置通过全部审计规则

三条规则对应前几节的三条军规：规则1是第5章Maker/Checker分离（有产必有害）；规则2是第2节白名单（审查者只读）；规则3是第3节worktree（可写必隔离）。官方机制给了配置的壳，安全语义还得自己审——这是本节最重要的实践结论。CI里挂上这个审计脚本，配置漂移当轮构建就报红。

审计脚本本身也有个使用心得：把它挂进CI的pre-commit阶段而不是构建阶段。构建阶段才跑，配置错误已经进了主分支半天；pre-commit阶段跑，提交本地就被拦下。三个规则的执行成本不到100毫秒，放在越早的环节，拦截的性价比越高——这和第5章“验证器前置”是同一条原则在配置管理上的投影。

五、官方机制 vs 自己写

选型建议：

标准场景（maker/checker/worker）→ 用官方机制 特殊需求（自定义编排/特殊验证）→ 自己写

把这张表翻译成更可操作的判定，我自己的三条分界线：

第一条：编排模式是否标准。你的需求是"主管+若干工人"或"maker/checker"，官方机制开箱即用；要跑第5节的Pipeline带检查点、Review带仲裁权重，官方配置文件表达不了这种流程逻辑，得自己写。

第二条：日志和度量要求多高。官方日志是框架黑盒，你拿不到第2节那种全字段调用记录（key尾6位、输入输出长度、起止耗时、提示词落盘）。要做成本分析、要做无人值守审计（第11章的主题），自研客户端是刚需。折中方案：官方机制跑任务，外围用第4节的日志规范包一层调用追踪。

第三条：团队规模和演进速度。两三个人的团队用官方机制，配置文件进版本库就够了；十几人共用一套编排、要按业务定制验证器和票据库，自研的掌控力优势开始超过维护成本。

还有一条隐藏分界线：换框架的成本。官方机制绑死在对应CLI生态里，.claude/agents/搬到别处就是几个Markdown文件；自研编排是纯Python资产，跟人走。多智能体系统是要长期演进的，资产可迁移性值得在第一天就纳入考量。

落地节奏上我建议分三步走，别一步到位：第一步全用官方机制跑两周，验证任务真的需要多智能体（顺便完成第8节准入清单的第一条"单循环试过"的对照实验）；第二步把日志规范包上去（外围脚本记录每次委派），看清成本和瓶颈的真实分布；第三步只把痛的那一环换成自研（通常是验证器或某个定制工人），其他保持官方。渐进迁移的每一步都有回滚点，推倒重写没有——编排系统的选型失误大多不是方向错，是步子太大。

踩坑提示：别把官方机制当黑盒用。我最惨的一次是checker的agent定义里忘了配tools，框架默认继承了全量工具——审查Agent直接改了被审代码，diff里混着"顺手修复"。官方机制的默认值是宽松的，显式声明白名单、跑一遍审计脚本，再交给团队。

六、实战：搭一套maker/checker/tester三件套

光看单文件不过瘾，把一套完整的团队配置搭出来跑一遍。目标：给一个功能需求走完"实现→审查→测试"三道工序。

三个agent定义如下（Claude Code格式，Codex同理翻译成TOML）：

<!-- .claude/agents/maker.md --> --- name: maker description: 功能实现工人 tools: [read_file, write_file, run_command] isolation: worktree --- 你是Python开发者。规则： 1. 只实现任务描述内的功能，不顺手重构无关代码 2. 每个函数带类型标注和docstring 3. 完成后输出：改动文件清单+每个文件的一句话说明+自测结果

<!-- .claude/agents/checker.md --> --- name: checker description: 代码审查员 tools: [read_file, grep_search] isolation: none --- 你是代码审查员。只审查不修改。输出： 1. 按严重度分级的问题清单（blocker/warning/note） 2. 每个问题给出文件与行号定位 3. 结论：approve 或 request_changes+理由

<!-- .claude/agents/tester.md --> --- name: tester description: 测试执行员 tools: [read_file, run_command] isolation: none --- 你是测试工程师。职责： 1. 运行完整测试套件，收集通过率与失败详情 2. 对新增功能补充边界用例 3. 输出：测试报告+失败用例的复现步骤

三个提示词各有讲究。maker的规则1堵"顺手重构"（Agent最常见的越权），checker的"只审查不修改"配只读工具双保险，tester要求"复现步骤"是为了失败可追溯。系统提示词写的不是能力是边界——能力模型自带，边界要你划。

运行时的完整流程：

主对话在这里就是第4节的Supervisor：派发、回收、裁决、循环。区别是它用自然语言派活，不需要写decompose代码——官方机制的本质是把编排逻辑从代码搬进对话。代价是编排的确定性也降了（对话式派活的稳定性不如代码），这也是"官方vs自研"权衡的另一个切面。

七、官方机制的局限清单

用官方机制两年，我攒了一张"它会卡住"的清单，每一条都对应一个自研的理由：

第一行最要命。官方checker是"模型审查"，但真正可靠的门禁是确定性验证：类型检查、lint、测试套件——这些在第5章里是我们验证器体系的地基，在官方机制里只能靠maker自己跑命令（自己检查自己，Maker/Checker分离失效）或者你在对话里手动补。

所以我的实际用法是混合架构：官方机制当执行器，自研当验证器和账房。maker产出后，外围脚本先跑确定性验证（pytest+mypy+ruff），红灯直接打回，绿灯才进checker的模型审查；每次委派和回收都由外围脚本按第2节规范记日志。官方机制负责它擅长的（上下文隔离、worktree、结构化交接），自研补它缺的（验证器、日志、可编程编排）。

这个混合架构还有个隐性好处：可替换性。哪天换CLI工具，执行器层换掉配置文件就行，验证器和日志层是纯Python资产原样保留。编排系统里最难写的从来不是执行，是验证和记账——把这两块握在自己手里，其他都是可换零件。

小结

核心要点：

1. Claude Code：.claude/agents/下Markdown+frontmatter定义智能体，主对话点名委派即spawn，主对话天然是Supervisor；
2. Codex：.codex/agents/下TOML定义，agent级可指定模型——在吃掉90%token的子智能体上做模型分级，省钱是9倍杠杆；
3. 官方=理论的配置化：tools白名单、worktree隔离、结构化交接，全是前六节模式的官方背书；
4. 配置要审计：缺checker、checker带写权限、可写无隔离三条规则脚本化，挂进CI防配置漂移；
5. 选型三条线：编排是否标准、日志度量要求、团队演进速度——标准+低度量需求用官方，定制+强审计需求自己写。

下节预告

工具箱满了，最后泼盆冷水。下一节：第10章第8节《反面教材：什么时候不该用多智能体》——成本翻倍、责任稀释、调试地狱三个真实反例，以及一张多智能体准入检查清单。

如果觉得本文对你有帮助，欢迎点赞、收藏、关注三连！
本系列持续更新中，关注不迷路~

文章编号：第10章第7节 | 总进度：74/120 | 预计阅读时间：13分钟