第7节 Agent Teams官方机制对比Claude Code/Codex的现成方案一句话总结两大官方多智能体机制的配置与玩法——.claude/agents/、.codex/agents/TOML、agent teams交接什么时候该用官方机制vs自己写。本文导航一、为什么要看官方机制二、Claude Code Agent TeamsMarkdown定义智能体三、Codex Agent TeamsTOML定义智能体四、用Python解析与审计官方agent定义五、官方机制 vs 自己写六、实战搭一套maker/checker/tester三件套七、官方机制的局限清单小结一、为什么要看官方机制前六节我们从零造了一遍编排系统spawn、worktree、Supervisor、五种模式、编排税。自己造的好处是每个齿轮都摸过坏处也很明显——每个齿轮都得自己维护。Claude Code和Codex这两家官方CLI都内置了多智能体机制定义几个agent文件主对话里一句让maker去写、checker去审框架替你完成spawn、上下文隔离、结果交接。本节把两家的机制拆开看最后回答什么时候用官方、什么时候自己写。先给一张全景对照维度Claude CodeCodex自研本课程前6节定义方式MarkdownfrontmatterTOMLPython类角色声明.claude/agents/*.md.codex/agents/*.tomlSubAgentConfig工具白名单frontmattertools字段[agent.tools].allowedallowed_tools隔离机制worktree选项worktree选项第3节编排器交接方式agent名调用结构化返回agent teams协作StructuredNote定制自由度中中高日志规范框架自带框架自带需自己实现注意最后一行官方机制的日志是框架级的你很难往里塞本课程要求的全字段记录key尾6位、输入输出长度、起止耗时。这是后面选型判断的重要砝码。二、Claude Code Agent TeamsMarkdown定义智能体目录结构.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审一下这种自然语言指令框架对审什么、按什么标准、不通过怎么办的理解存在漂移同样的指令两天的执行路径可能不同。要确定性就得把委派指令写成可复用的模板每类任务一段固定措辞这实际上是在对话层重建配置文件——绕了一圈你就理解为什么大型编排最终还是会沉淀回代码。点名maker点名checker点名tester结构化结果审查意见测试报告主对话Supervisor角色maker.md写权限worktreechecker.md只读权限tester.md命令权限三、Codex Agent TeamsTOML定义智能体TOML配置# .codex/agents/worker.toml [agent] name worker description 工人智能体 model gpt-4o [agent.tools] allowed [read_file, write_file, run_command] [agent.isolation] type worktreeCodex的思路相同载体换成TOML。一个显著差异Codex允许在agent级指定model——你可以让maker用强模型、checker用便宜模型、tester干脆用本地小模型。这个模型分层能力在成本控制上很实用回顾第1节子智能体吃掉90%的token在它们身上做模型分级省钱效果是9倍杠杆。Claude Code的Markdown定义和Codex的TOML定义表达能力其实半斤八两。选哪家主要看你主力工具链在哪边而不是配置格式本身。两家的worktree隔离选项都源自同一个认知并行修改必须文件系统级隔离第3节的结论在这里得到了官方背书。对照表收一下配置项映射概念Claude Code字段Codex字段本课程实现名字name[agent].nameSubAgentConfig.name系统提示Markdown正文—写在prompt段system_prompt工具白名单tools[agent.tools].allowedallowed_tools隔离isolation[agent.isolation].typeWorktreeOrchestrator模型主对话统一agent级可指定client注入四、用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 loggerlogging.getLogger(agent_loader)logger.setLevel(logging.INFO)_fmtlogging.Formatter(%(asctime)s %(levelname)s %(message)s,%Y-%m-%d %H:%M:%S)forhin(logging.StreamHandler(),TimedRotatingFileHandler(logs/agent_loader.log,whenMIDNIGHT,interval31,backupCount12,encodingutf-8)):h.setFormatter(_fmt)logger.addHandler(h)classAgentDef(BaseModel):一个官方agent定义的解析结果字段不全直接校验失败暴露问题name:strdescription:strtools:list[str][]isolation:strnonesystem_prompt:strfield_validator(name)classmethoddefname_lower(cls,v:str)-str:ifnotv.isidentifier():raiseValueError(fagent名不合法{v}须为合法标识符)returnv.lower()defparse_agent_md(path:Path)-AgentDef:解析单个agent定义frontmatter用yaml读正文整体作为system_prompttextpath.read_text(encodingutf-8)partstext.split(---,2)# [, frontmatter, 正文]metayaml.safe_load(parts[1])or{}returnAgentDef(namemeta.get(name,path.stem),descriptionmeta.get(description,),toolsmeta.get(tools,[]),isolationmeta.get(isolation,none),system_promptparts[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}fprompt{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] isolationnone prompt42字 maker tools[read_file, write_file, run_command] isolationworktree prompt33字 tester tools[read_file, run_command] isolationnone prompt40字解析器里有三个设计点。split(---, 2)限定切两刀正文里再出现---比如agent提示词里教它写frontmatter也不会切坏field_validator校验agent名是合法标识符防止配置里混进带空格的名字在后续代码里炸单个文件解析失败只告警跳过不让一个坏文件瘫痪整个团队的加载——团队配置的解析要按尽力而为设计和第2节解析模型输出同一个哲学。这个解析器还有个进阶玩法把官方配置桥接进自研编排。AgentDef和第2节的SubAgentConfig字段几乎一一对应写一个转换函数就能让官方定义的团队跑在自研Supervisor上defto_subagent_config(a:AgentDef,max_steps:int10)-SubAgentConfig:官方agent定义 → 自研SubAgentConfig字段直译桥接两个世界returnSubAgentConfig(namea.name,system_prompta.system_promptora.description,allowed_toolsa.tools,max_stepsmax_steps,)五行的桥接函数价值在于配置资产不锁死团队在官方CLI里打磨好的maker/checker提示词一行转换就能进你的自研系统跑享受全字段日志和可编程编排反过来也一样。配置用官方格式写门槛低、可复用执行引擎按需选——这是我最终沉淀下来的混合姿势。顺带一提Codex的TOML用标准库tomllib读Python 3.11内置五分钟就能写个姊妹版加载器字段映射表在上一节给过了。两个加载器共用AgentDef模型.claude和.codex的团队配置就能在同一个审计脚本里混跑。团队配置审计一个实用脚本加载器只解决读出来再进一步就是审计权限配得对不对角色齐不齐我给团队定义了三条审计规则写成可运行的检查器。# src/ai_loop_course/agent_audit.pyAgent团队配置审计角色齐全性 权限最小化 并行隔离检查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无人把关ifmakerinnamesandcheckernotinnames:findings.append(AuditFinding(levelerror,message有maker无checker产出无人审查))# 规则2checker不允许有写权限审查者篡改现场forainteam:ifa.namecheckerand({write_file}set(a.tools)):findings.append(AuditFinding(levelerror,messagefchecker持有写权限{a.tools}))# 规则3持有write权限的agent建议worktree隔离并行改仓库前提forainteam:ifwrite_fileina.toolsanda.isolation!worktree:findings.append(AuditFinding(levelwarn,messagef{a.name}可写但未启用worktree隔离并行会互踩))ifnotfindings:findings.append(AuditFinding(levelinfo,message团队配置通过全部审计规则))returnfindingsif__name____main__:teamload_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要求复现步骤是为了失败可追溯。系统提示词写的不是能力是边界——能力模型自带边界要你划。运行时的完整流程testercheckermaker主对话testercheckermaker主对话实现需求并输出改动清单改动文件自测结果审查maker的改动approve或request_changes跑测试套件测试报告三绿才合并任一红灯回到maker主对话在这里就是第4节的Supervisor派发、回收、裁决、循环。区别是它用自然语言派活不需要写decompose代码——官方机制的本质是把编排逻辑从代码搬进对话。代价是编排的确定性也降了对话式派活的稳定性不如代码这也是官方vs自研权衡的另一个切面。七、官方机制的局限清单用官方机制两年我攒了一张它会卡住的清单每一条都对应一个自研的理由局限具体表现自研的解法无自定义验证器插槽审查模型审查插不进确定性校验第5章验证器直接挂进循环编排逻辑在对话里派活顺序靠人记复杂拓扑管不住第4节Supervisor代码化日志是框架黑盒拿不到key尾6位/输入输出长度/耗时第2节全字段日志规范无票据库概念跨会话的任务状态会丢第12章票据库重试策略固定失败重派的逻辑不可编程max_retries失败原因注入第一行最要命。官方checker是模型审查但真正可靠的门禁是确定性验证类型检查、lint、测试套件——这些在第5章里是我们验证器体系的地基在官方机制里只能靠maker自己跑命令自己检查自己Maker/Checker分离失效或者你在对话里手动补。所以我的实际用法是混合架构官方机制当执行器自研当验证器和账房。maker产出后外围脚本先跑确定性验证pytestmypyruff红灯直接打回绿灯才进checker的模型审查每次委派和回收都由外围脚本按第2节规范记日志。官方机制负责它擅长的上下文隔离、worktree、结构化交接自研补它缺的验证器、日志、可编程编排。这个混合架构还有个隐性好处可替换性。哪天换CLI工具执行器层换掉配置文件就行验证器和日志层是纯Python资产原样保留。编排系统里最难写的从来不是执行是验证和记账——把这两块握在自己手里其他都是可换零件。小结核心要点Claude Code.claude/agents/下Markdownfrontmatter定义智能体主对话点名委派即spawn主对话天然是SupervisorCodex.codex/agents/下TOML定义agent级可指定模型——在吃掉90%token的子智能体上做模型分级省钱是9倍杠杆官方理论的配置化tools白名单、worktree隔离、结构化交接全是前六节模式的官方背书配置要审计缺checker、checker带写权限、可写无隔离三条规则脚本化挂进CI防配置漂移选型三条线编排是否标准、日志度量要求、团队演进速度——标准低度量需求用官方定制强审计需求自己写。下节预告工具箱满了最后泼盆冷水。下一节第10章第8节《反面教材什么时候不该用多智能体》——成本翻倍、责任稀释、调试地狱三个真实反例以及一张多智能体准入检查清单。如果觉得本文对你有帮助欢迎点赞、收藏、关注三连本系列持续更新中关注不迷路~文章编号第10章第7节 | 总进度74/120 | 预计阅读时间13分钟
第7节 Agent Teams官方机制对比Claude Code/Codex的现成方案一句话总结两大官方多智能体机制的配置与玩法——.claude/agents/、.codex/agents/TOML、agent teams交接什么时候该用官方机制vs自己写。本文导航一、为什么要看官方机制二、Claude Code Agent TeamsMarkdown定义智能体三、Codex Agent TeamsTOML定义智能体四、用Python解析与审计官方agent定义五、官方机制 vs 自己写六、实战搭一套maker/checker/tester三件套七、官方机制的局限清单小结一、为什么要看官方机制前六节我们从零造了一遍编排系统spawn、worktree、Supervisor、五种模式、编排税。自己造的好处是每个齿轮都摸过坏处也很明显——每个齿轮都得自己维护。Claude Code和Codex这两家官方CLI都内置了多智能体机制定义几个agent文件主对话里一句让maker去写、checker去审框架替你完成spawn、上下文隔离、结果交接。本节把两家的机制拆开看最后回答什么时候用官方、什么时候自己写。先给一张全景对照维度Claude CodeCodex自研本课程前6节定义方式MarkdownfrontmatterTOMLPython类角色声明.claude/agents/*.md.codex/agents/*.tomlSubAgentConfig工具白名单frontmattertools字段[agent.tools].allowedallowed_tools隔离机制worktree选项worktree选项第3节编排器交接方式agent名调用结构化返回agent teams协作StructuredNote定制自由度中中高日志规范框架自带框架自带需自己实现注意最后一行官方机制的日志是框架级的你很难往里塞本课程要求的全字段记录key尾6位、输入输出长度、起止耗时。这是后面选型判断的重要砝码。二、Claude Code Agent TeamsMarkdown定义智能体目录结构.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审一下这种自然语言指令框架对审什么、按什么标准、不通过怎么办的理解存在漂移同样的指令两天的执行路径可能不同。要确定性就得把委派指令写成可复用的模板每类任务一段固定措辞这实际上是在对话层重建配置文件——绕了一圈你就理解为什么大型编排最终还是会沉淀回代码。点名maker点名checker点名tester结构化结果审查意见测试报告主对话Supervisor角色maker.md写权限worktreechecker.md只读权限tester.md命令权限三、Codex Agent TeamsTOML定义智能体TOML配置# .codex/agents/worker.toml [agent] name worker description 工人智能体 model gpt-4o [agent.tools] allowed [read_file, write_file, run_command] [agent.isolation] type worktreeCodex的思路相同载体换成TOML。一个显著差异Codex允许在agent级指定model——你可以让maker用强模型、checker用便宜模型、tester干脆用本地小模型。这个模型分层能力在成本控制上很实用回顾第1节子智能体吃掉90%的token在它们身上做模型分级省钱效果是9倍杠杆。Claude Code的Markdown定义和Codex的TOML定义表达能力其实半斤八两。选哪家主要看你主力工具链在哪边而不是配置格式本身。两家的worktree隔离选项都源自同一个认知并行修改必须文件系统级隔离第3节的结论在这里得到了官方背书。对照表收一下配置项映射概念Claude Code字段Codex字段本课程实现名字name[agent].nameSubAgentConfig.name系统提示Markdown正文—写在prompt段system_prompt工具白名单tools[agent.tools].allowedallowed_tools隔离isolation[agent.isolation].typeWorktreeOrchestrator模型主对话统一agent级可指定client注入四、用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 loggerlogging.getLogger(agent_loader)logger.setLevel(logging.INFO)_fmtlogging.Formatter(%(asctime)s %(levelname)s %(message)s,%Y-%m-%d %H:%M:%S)forhin(logging.StreamHandler(),TimedRotatingFileHandler(logs/agent_loader.log,whenMIDNIGHT,interval31,backupCount12,encodingutf-8)):h.setFormatter(_fmt)logger.addHandler(h)classAgentDef(BaseModel):一个官方agent定义的解析结果字段不全直接校验失败暴露问题name:strdescription:strtools:list[str][]isolation:strnonesystem_prompt:strfield_validator(name)classmethoddefname_lower(cls,v:str)-str:ifnotv.isidentifier():raiseValueError(fagent名不合法{v}须为合法标识符)returnv.lower()defparse_agent_md(path:Path)-AgentDef:解析单个agent定义frontmatter用yaml读正文整体作为system_prompttextpath.read_text(encodingutf-8)partstext.split(---,2)# [, frontmatter, 正文]metayaml.safe_load(parts[1])or{}returnAgentDef(namemeta.get(name,path.stem),descriptionmeta.get(description,),toolsmeta.get(tools,[]),isolationmeta.get(isolation,none),system_promptparts[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}fprompt{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] isolationnone prompt42字 maker tools[read_file, write_file, run_command] isolationworktree prompt33字 tester tools[read_file, run_command] isolationnone prompt40字解析器里有三个设计点。split(---, 2)限定切两刀正文里再出现---比如agent提示词里教它写frontmatter也不会切坏field_validator校验agent名是合法标识符防止配置里混进带空格的名字在后续代码里炸单个文件解析失败只告警跳过不让一个坏文件瘫痪整个团队的加载——团队配置的解析要按尽力而为设计和第2节解析模型输出同一个哲学。这个解析器还有个进阶玩法把官方配置桥接进自研编排。AgentDef和第2节的SubAgentConfig字段几乎一一对应写一个转换函数就能让官方定义的团队跑在自研Supervisor上defto_subagent_config(a:AgentDef,max_steps:int10)-SubAgentConfig:官方agent定义 → 自研SubAgentConfig字段直译桥接两个世界returnSubAgentConfig(namea.name,system_prompta.system_promptora.description,allowed_toolsa.tools,max_stepsmax_steps,)五行的桥接函数价值在于配置资产不锁死团队在官方CLI里打磨好的maker/checker提示词一行转换就能进你的自研系统跑享受全字段日志和可编程编排反过来也一样。配置用官方格式写门槛低、可复用执行引擎按需选——这是我最终沉淀下来的混合姿势。顺带一提Codex的TOML用标准库tomllib读Python 3.11内置五分钟就能写个姊妹版加载器字段映射表在上一节给过了。两个加载器共用AgentDef模型.claude和.codex的团队配置就能在同一个审计脚本里混跑。团队配置审计一个实用脚本加载器只解决读出来再进一步就是审计权限配得对不对角色齐不齐我给团队定义了三条审计规则写成可运行的检查器。# src/ai_loop_course/agent_audit.pyAgent团队配置审计角色齐全性 权限最小化 并行隔离检查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无人把关ifmakerinnamesandcheckernotinnames:findings.append(AuditFinding(levelerror,message有maker无checker产出无人审查))# 规则2checker不允许有写权限审查者篡改现场forainteam:ifa.namecheckerand({write_file}set(a.tools)):findings.append(AuditFinding(levelerror,messagefchecker持有写权限{a.tools}))# 规则3持有write权限的agent建议worktree隔离并行改仓库前提forainteam:ifwrite_fileina.toolsanda.isolation!worktree:findings.append(AuditFinding(levelwarn,messagef{a.name}可写但未启用worktree隔离并行会互踩))ifnotfindings:findings.append(AuditFinding(levelinfo,message团队配置通过全部审计规则))returnfindingsif__name____main__:teamload_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要求复现步骤是为了失败可追溯。系统提示词写的不是能力是边界——能力模型自带边界要你划。运行时的完整流程testercheckermaker主对话testercheckermaker主对话实现需求并输出改动清单改动文件自测结果审查maker的改动approve或request_changes跑测试套件测试报告三绿才合并任一红灯回到maker主对话在这里就是第4节的Supervisor派发、回收、裁决、循环。区别是它用自然语言派活不需要写decompose代码——官方机制的本质是把编排逻辑从代码搬进对话。代价是编排的确定性也降了对话式派活的稳定性不如代码这也是官方vs自研权衡的另一个切面。七、官方机制的局限清单用官方机制两年我攒了一张它会卡住的清单每一条都对应一个自研的理由局限具体表现自研的解法无自定义验证器插槽审查模型审查插不进确定性校验第5章验证器直接挂进循环编排逻辑在对话里派活顺序靠人记复杂拓扑管不住第4节Supervisor代码化日志是框架黑盒拿不到key尾6位/输入输出长度/耗时第2节全字段日志规范无票据库概念跨会话的任务状态会丢第12章票据库重试策略固定失败重派的逻辑不可编程max_retries失败原因注入第一行最要命。官方checker是模型审查但真正可靠的门禁是确定性验证类型检查、lint、测试套件——这些在第5章里是我们验证器体系的地基在官方机制里只能靠maker自己跑命令自己检查自己Maker/Checker分离失效或者你在对话里手动补。所以我的实际用法是混合架构官方机制当执行器自研当验证器和账房。maker产出后外围脚本先跑确定性验证pytestmypyruff红灯直接打回绿灯才进checker的模型审查每次委派和回收都由外围脚本按第2节规范记日志。官方机制负责它擅长的上下文隔离、worktree、结构化交接自研补它缺的验证器、日志、可编程编排。这个混合架构还有个隐性好处可替换性。哪天换CLI工具执行器层换掉配置文件就行验证器和日志层是纯Python资产原样保留。编排系统里最难写的从来不是执行是验证和记账——把这两块握在自己手里其他都是可换零件。小结核心要点Claude Code.claude/agents/下Markdownfrontmatter定义智能体主对话点名委派即spawn主对话天然是SupervisorCodex.codex/agents/下TOML定义agent级可指定模型——在吃掉90%token的子智能体上做模型分级省钱是9倍杠杆官方理论的配置化tools白名单、worktree隔离、结构化交接全是前六节模式的官方背书配置要审计缺checker、checker带写权限、可写无隔离三条规则脚本化挂进CI防配置漂移选型三条线编排是否标准、日志度量要求、团队演进速度——标准低度量需求用官方定制强审计需求自己写。下节预告工具箱满了最后泼盆冷水。下一节第10章第8节《反面教材什么时候不该用多智能体》——成本翻倍、责任稀释、调试地狱三个真实反例以及一张多智能体准入检查清单。如果觉得本文对你有帮助欢迎点赞、收藏、关注三连本系列持续更新中关注不迷路~文章编号第10章第7节 | 总进度74/120 | 预计阅读时间13分钟
