1. 主对话为什么会被脏活撑爆先说结论Claude Code 的主对话不是被任务多撑爆的是被过程噪声撑爆的。你把代码审查、测试生成、Bug 修复一股脑塞进同一个会话前几轮它还能对答如流到第五轮就开始忘事——把 CamelCase 写回 snake_case修复方案跟自己前面的结论打架。这不是模型失忆是上下文窗口的信噪比失衡了。我拿一个真实重构任务算过账原始代码约 5 万 token搜索过程约 3 万 token中间推理约 2 万 token测试输出日志约 4 万 token。等你想让它做最终决策时留给决策的有效上下文已经被挤到角落。模型每次回答都要重新读一遍这十几万 token 的噪声质量自然断崖式下跌。子智能体Subagent干的事就是把这个过程搬走在独立的子上下文里跑完整个脏活只把结论塞回主对话。主对话保持清爽模型每次决策都基于干净的输入。这篇就聚焦 Claude Code 子智能体的上下文隔离机制演示怎么用 TaoToken 统一 Key/API 通道接入子智能体交付可复制的settings.json与子智能体定义骨架并给出主/子上下文占用对比的验证动作。适合谁看正在用 Claude Code 做 AI 工程、Harness 实践被主对话上下文污染困扰的开发者。读完你能自己搭一套CEO 派活、子智能体干活的协作结构。2. TaoToken 前置统一 Key 与 API 通道子智能体要跑起来绕不开模型调用通道。Claude Code 默认走 Anthropic 官方通道但如果你同时用多个模型、多个项目Key 管理会变成一团乱麻。TaoToken 在这里的角色是统一 Key/API 通道一个 Key 覆盖 Claude 系列模型子智能体定义里指定model: sonnet或model: haiku时请求都从同一条通道出去不用为每个子智能体单独配 Key。先做前置准备。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号进控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。API 基础地址统一用 https://taotoken.net/api 这个不加 UTM。拿到 Key 之后别急着写子智能体先把 Claude Code 的全局配置打通。Claude Code 读取环境变量的优先级是项目级.claude/settings.json 用户级~/.claude/settings.json 系统环境变量。我建议把 Key 放在用户级配置里项目级只放子智能体定义这样多个项目共用一套通道。注意Key 属于敏感凭证不要提交到 Git。项目级settings.json里如果要写 Key务必加进.gitignore或者用环境变量引用。前置这一步做完你手上应该有三样东西一个可用的 API Key、一个确认能通的 API 基础地址、一个装好 Claude Code 的项目目录。接下来进入配置环节。3. 可复制配置settings.json 与子智能体骨架3.1 全局 settings.json 打通通道先配用户级~/.claude/settings.json把模型通道指向 TaoToken{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 }, model: sonnet, permissions: { allow: [ Read, Grep, Glob ] } }这里ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址ANTHROPIC_API_KEY填你创建的 Key。model是主对话默认模型子智能体可以在自己的 frontmatter 里覆盖。permissions.allow是全局白名单子智能体的tools字段只能在这个范围内再收窄不能突破。项目级.claude/settings.json可以只放项目相关的东西比如{ permissions: { allow: [ Read, Grep, Glob, Edit, Write, Bash ] } }项目级允许了Edit、Write、Bash是因为 bug-fixer 和 test-runner 需要写文件和跑命令。但注意全局白名单里没有这些所以最终生效的是两级配置的交集——这是 Claude Code 的权限收敛逻辑子智能体拿不到超出全局的工具。3.2 子智能体定义骨架子智能体就是一个 markdown 文件丢在.claude/agents/目录下。frontmatter 里写清楚身份和权限正文写工作流程和输出格式。先看一个代码审查子智能体的完整骨架--- name: code-reviewer description: 审查代码质量、安全漏洞和性能问题的专家。当用户要求代码审查、安全审计或质量评估时使用。 tools: - Read - Grep - Glob model: sonnet permissionMode: plan --- 你是一个资深的代码审查专家拥有十年以上的工程经验。 ## 审查维度 ### 安全性 - 检查硬编码凭证API Key、密码、Token - 检查 SQL 注入、XSS、CSRF 等注入漏洞 - 检查输入验证的完整性 - 检查敏感数据的处理方式 ### 代码质量 - 函数是否遵循单一职责原则 - 命名是否清晰、一致 - 是否存在重复代码 - 错误处理是否恰当 ### 性能 - 是否有不必要的循环嵌套 - 数据库查询是否存在 N1 问题 - 是否有未关闭的资源 ## 输出格式 ### 审查摘要 [一段话总结整体代码质量] ### 发现的问题 - [严重/主要/次要] 问题描述 at file_path:line_number ### 改进建议 [按优先级排列的具体改进建议]frontmatter 这五件套你得记牢字段作用取值建议name唯一标识主对话靠它派活小写连字符如 code-reviewerdescription路由依据Claude 据此判断何时自动 spawn写清触发场景tools工具白名单最小权限原则只列必需的model指定 haiku/sonnet/opus确定性活用 haikupermissionModeplan 只读、acceptEdits 可改文件按需开permissionMode: plan意味着这个子智能体只能读、不能写适合审查类任务。如果要让它改文件改成acceptEdits。3.3 流水线型子智能体的契约式输出流水线型最容易踩的坑是阶段间格式不固定。上游今天输出根因在 xxx明天输出问题出在 xxx下游根本解析不了。所以上游必须严格按契约输出。看 bug-locator--- name: bug-locator description: 定位 Bug 的根本原因 tools: - Read - Grep - Glob permissionMode: plan --- 你是 Bug 定位专家。你的任务是找到 Bug 的根本原因。 ## 定位流程 1. 理解症状分析错误信息和复现步骤 2. 搜索相关代码通过关键词和文件模式定位可疑区域 3. 追溯调用链从错误点向上追溯到根因 4. 确认根因明确说明是哪行代码导致了问题 ## 输出格式下游阶段依赖此格式请严格遵守 根因文件[file_path:line_number] 问题描述[一句话说明根因] 调用链[从入口到出错点的完整路径] 修复方向[简要的修复思路]下游 bug-fixer 的消费方式也写死--- name: bug-fixer description: 基于定位结果修复 Bug tools: - Read - Grep - Glob - Edit - Write - Bash --- 你是 Bug 修复专家。你将收到 bug-locator 的定位结论基于此进行修复。 ## 修复原则 1. 最小改动只改必须改的代码 2. 不引入新问题修复不能破坏其他功能 3. 保持风格一致遵循项目现有代码风格 4. 添加防御性代码防止同类问题再次发生 ## 输出格式 修改的文件[file_path_1, file_path_2, ...] 每处修改的原因[逐一说明] 潜在副作用[如果有的话] 建议的测试命令[用于验证修复的命令]四行字段、固定顺序、固定标签。bug-fixer 读到根因文件就知道从这行取路径读到修复方向就知道这是上下文提示。这种契约一旦定下来整条流水线就稳了。我自己的规则是上游输出格式一旦修改必须同步改下游解析逻辑跟改 API 一个待遇。3.4 成本优化test-runner 用 haiku跑测试这种不需要复杂推理的活用 haiku 足够省钱又快--- name: test-runner description: 运行项目测试套件并分析测试结果。当用户要求运行测试、检查测试覆盖率或分析测试失败原因时使用。 tools: - Read - Grep - Glob - Bash model: haiku --- 你是一个测试执行专家。你的核心价值是从大量测试输出中提炼关键信息为主对话提供精准的测试摘要。 ## 执行流程 1. 确认项目的测试命令查看 package.json 或 CLAUDE.md 2. 运行测试套件 3. 分析输出区分通过和失败的测试 4. 对失败的测试定位失败原因 ## 输出格式严格遵守 ### 测试摘要 - 总计X 个测试 - 通过X 个 - 失败X 个 - 跳过X 个 ### 失败详情仅列出失败的测试 - test_name: 失败原因一句话at file_path:line_number ### 建议 [如果有明显的失败模式给出修复方向] 注意不要在输出中包含完整的测试日志。只输出上述格式的摘要信息。model: haiku单次成本比 sonnet 低一个数量级跑测试这种确定性高的任务完全够用。子智能体的模型选择是独立的主对话用 sonnet 做决策子智能体用 haiku 干体力活成本结构一下就优化了。4. 验证请求主/子上下文占用对比配置写完得验证子智能体真的在独立上下文里跑。Claude Code 里触发子智能体有两种方式自动路由和显式调用。自动路由靠description字段你说帮我审查这段代码Claude 根据 description 判断该 spawn code-reviewer。显式调用是直接说用 code-reviewer 审查 src/ 目录。验证动作分三步。第一步跑一个代码审查任务观察主对话里出现的内容。如果配置正确主对话里出现的不是Grep 搜索了 30 个文件发现 5 处疑似 SQL 注入逐个分析…而是发现 2 处 SQL 注入高危位于 userController.js:42 和 orderDao.js:118。过程被折叠了只有结论回流。第二步对比 token 占用。我做过一次实测同一个代码审查任务5000 行 ArkTS 代码两种跑法差距非常明显指标主对话直跑子智能体跑主对话过程 token8.6 万0主对话结论 token0.3 万0.3 万子智能体上下文08.4 万主对话有效信噪比3.5%100%后续轮次回答质量明显衰减稳定子智能体那一栏的过程 token 不进主对话主对话里只剩下结论。后续再让它做决策时模型看到的全是有效信息不会被 8.6 万 token 的过程噪声稀释。这就是为什么主对话直跑到第五轮信噪比已经掉到 3.5%模型当然开始忘事。第三步验证模型路由。在子智能体定义里把model改成haiku跑一次测试任务观察响应速度和输出格式是否符合契约。如果输出里带了完整测试日志说明子智能体没遵守只输出摘要的指令回去检查正文里的输出格式约束。提示验证阶段建议先用小任务试跑比如审查单个文件、跑单个测试用例。确认通道通了、子智能体被正确 spawn、输出格式符合契约再上大任务。5. 本篇常见错排查配置过程中最容易踩的几个坑我逐个列出来。子智能体没被触发。最常见的原因是description写得太模糊。Claude 靠 description 做路由判断如果你写代码相关任务它不知道什么时候该用。改成当用户要求代码审查、安全审计或质量评估时使用触发率立刻上来。另一个原因是文件没放对位置必须在.claude/agents/目录下文件名和name字段一致。工具权限报错。子智能体定义里tools列了Bash但全局settings.json的permissions.allow里没有Bash最终生效的是交集子智能体拿不到这个工具。排查方法先看全局白名单再看项目级白名单最后看子智能体tools三级取交集。缺哪级补哪级。API 通道不通。报错通常是 401 或连接超时。先确认ANTHROPIC_BASE_URL是https://taotoken.net/api注意结尾没有多余斜杠。再确认ANTHROPIC_API_KEY是有效的 Key没被撤销。如果还不行去控制台看 Key 的余额和权限范围。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的参数说明。流水线阶段格式对不上。bug-fixer 解析不了 bug-locator 的输出通常是上游没严格遵守契约。检查 bug-locator 的输出是不是四行固定字段有没有多写或少写。契约式输出的关键是固定标签 固定顺序任何自由发挥都会让下游解析失败。主对话还是被污染。如果你发现主对话里还是出现了大量过程日志说明任务没走子智能体而是主对话直跑了。检查触发方式自动路由靠 description如果没触发改用显式调用用 xxx 子智能体做 yyy。另外确认子智能体的permissionMode和tools配置正确配置错误会导致 spawn 失败后回退到主对话执行。模型选择不当。给 test-runner 配了 opus成本飙升还没必要。确定性高的任务用 haiku需要推理的用 sonnet只有极复杂的架构决策才上 opus。子智能体的model字段独立于主对话按任务复杂度分配。6. 把脏活丢出去主对话只留决策子智能体的本质是上下文隔离把过程噪声关在子上下文里只让结论回流主对话。主智能体扮演 CEO派活、收结论、不做执行。三种协作形态覆盖大多数场景——并行型多个专家同时干活流水线型串行处理链团队型多会话自组织协作。我自己的用法是凡是过程噪声大、只需要结论回流的任务一律丢给子智能体。代码审查、测试生成、Bug 定位修复全部走流水线。主对话只留给真正需要多轮交互的决策。上下文干净得像新装系统模型每次回答都在最佳状态。如果你要长期跑编码任务或搭 Agent 工作流建议把模型通道统一到 TaoToken 的 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 一个 Key 覆盖多个子智能体的模型调用省去逐个配 Key 的麻烦。想先验证模型效果可以去模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 试跑几个子智能体任务确认输出格式和响应质量符合预期再落到项目里。配置这件事先跑通一个子智能体再复制成流水线。别一上来就搭五个调试成本会把你劝退。
