1. 长程任务为什么必须拆 Sub-Agent从 Harness Engineering 到 Loop Engineering先说结论单 Agent 做长程任务卡点从来不是模型不够聪明而是上下文窗口这个物理边界。我试过让一个 200K 窗口的模型一口气调研 5 个框架、对比架构、写 5000 字报告、再给选型建议——跑到第三步前面调研的细节已经被 auto-compact 压成几句话报告里开始出现某框架支持 X这种模糊表述实际上它已经忘了具体是哪个框架。这就是 Harness Engineering 阶段的核心矛盾你给单 Agent 配了工具、配了记忆、配了检索本质上还是在给它扩容装备但装备再多它还是一个人在一间屋子里干活。房间就这么大资料堆到天花板注意力必然衰减。Loop Engineering 的思路不一样。它不追求让单个 Agent 更强而是把长程任务拆成多个循环每个循环里有一个专职 Sub-Agent 在自己的干净上下文里完成一段工作主 Agent 负责调度和整合。任务分解、角色分工、循环调度这三件事构成了 Loop Engineering 的骨架。具体到工程上一个长程任务通常包含四类上下文消耗调研资料原文一次 web 搜索 10-30K token、代码文件内容多文件重构 50-150K、中间推理过程thinking block 占用大量窗口、历史对话越滚越大。单 Agent 要把这四类全塞进一个窗口必然触顶。Sub-Agent 的价值就是把它们分到不同窗口researcher 消化搜索原文只返回摘要coder 只拿需求描述和文件路径reviewer 只拿 diff 和规范。适合谁用这套东西如果你在做的是一次问答单文件修改这类短任务单 Agent 加工具调用就够了上 Sub-Agent 是过度设计。但如果你面对的是多源调研 综合报告跨模块重构 审查长文档生成 校对这类需要多步骤、多技能栈、上下文消耗大的任务Sub-Agent 协作与编排就是绕不过去的工程路径。下面我会从可复制的配置模板讲起一路讲到 Loop 调度伪代码、验证步骤和失败回退。所有配置都基于 Claude Code 的 Sub-Agent 机制你可以直接抄。2. TaoToken 前置准备Base URL、API Key 与 Model ID 三件套在写 Sub-Agent 配置之前得先把模型接入这层搞定。Sub-Agent 编排对模型调用的稳定性要求比单 Agent 高——因为一次任务里可能有主 Agent、coder、reviewer 多个角色轮流调用任何一个环节的鉴权或路由出问题整条链路就断了。TaoToken 在这里扮演的是统一接入层你拿到一个 Base URL 和一个 API Key就能在 Claude Code、Cline、Codex 这些工具里调用多个模型不用为每个工具单独配一套鉴权。对 Sub-Agent 场景来说这意味着主 Agent 和各个 Sub-Agent 可以共享同一套接入配置provider 管理集中在一处。你需要准备的三件套配置项值说明Base URLhttps://taotoken.net/api所有请求的根地址不加 UTMAPI Key在控制台创建形如sk-...注意保密Model ID如claude-sonnet-4-20250514按你实际要用的模型填获取 API Key 的路径访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建密钥。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。这里有个容易踩的坑Base URL 末尾不要带斜杠也不要自己拼/v1。很多工具比如 Claude Code会自动在 Base URL 后面追加路径你手动加了/v1就变成/v1/v1/messages直接 404。正确的写法就是https://taotoken.net/api让工具自己处理路径拼接。另一个坑是 Model ID 的写法。不同工具对模型名的要求不一样Claude Code 里通常用claude-sonnet-4-20250514这种带日期的完整 ID而有些工具接受claude-sonnet-4这种简写。如果你不确定先去模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 试一下能正常出结果就说明这个 Model ID 可用。对于 Sub-Agent 编排我建议主 Agent 用能力最强的模型比如 Sonnet 4Sub-Agent 按职责选coder 用强模型reviewer 可以用稍弱的模型降低成本researcher 用中等模型即可。TaoToken 的好处是这些模型切换只改 Model IDBase URL 和 Key 不变。如果你打算长期跑编码类 Agent 任务可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它针对高频编码调用做了额度优化。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到配置问题先查这里。3. 可复制的 Sub-Agent 编排配置settings.json 与 agent 定义这一节给你可以直接抄的配置。Claude Code 的 Sub-Agent 通过两个地方定义一是全局的settings.json配置模型接入二是.claude/agents/目录下的 agent 定义文件配置每个 Sub-Agent 的职责、工具、系统提示。先看settings.json。这个文件通常放在~/.claude/settings.json或项目根目录的.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Write, Edit, Bash(git:*), Bash(npm:*) ] } }注意ANTHROPIC_BASE_URL就是https://taotoken.net/api不要加/v1。ANTHROPIC_API_KEY填你在控制台创建的密钥。ANTHROPIC_MODEL是主 Agent 用的模型。接下来定义 Sub-Agent。在项目根目录建.claude/agents/文件夹里面每个.md文件就是一个 Sub-Agent。先写code-reviewer.md--- name: code-reviewer description: 代码审查专家。当需要审查代码 diff、检查潜在 bug、安全漏洞、规范问题时调用。输入是代码 diff 或文件路径输出是结构化审查意见。 tools: Read, Grep, Glob model: claude-sonnet-4-20250514 --- 你是一个有 10 年经验的资深代码审查员。你的唯一职责是审查代码并给出结构化反馈。 你不做这些事 - 不修改代码本身 - 不给模糊建议如可以更简洁 - 不在没有具体理由的情况下批准 你要做这些事 - 彻底阅读相关代码 - 对照常见陷阱检查null 处理、错误路径、安全风险 - 给出带文件路径和行号的行级评论 - 给出最终结论approve / request_changes / reject 输出格式必须是 JSON { verdict: approve|request_changes|reject, comments: [ {file: 路径, line: 行号, issue: 问题描述, severity: high|medium|low} ], summary: 一句话总结 }再写web-researcher.md--- name: web-researcher description: 网页调研专家。当需要搜索多个来源、整理调研报告、对比多个方案时调用。输入是调研问题输出是结构化调研报告。 tools: WebSearch, WebFetch, Read model: claude-sonnet-4-20250514 --- 你是一个专业的调研员。你的职责是针对给定的调研问题进行多轮搜索输出结构化调研报告。 工作流程 1. 把调研问题拆成 3-5 个搜索关键词 2. 对每个关键词执行搜索读取前 3 条结果的原文 3. 交叉验证信息标注来源 4. 输出 markdown 格式报告包含核心发现、对比表格、引用来源列表 输出要求 - 每个结论必须标注来源 URL - 不确定的信息标注待验证 - 报告控制在 1500 字以内避免冗长这两个文件放好后Claude Code 启动时会自动加载。主 Agent 在推理时会根据description字段判断何时调用哪个 Sub-Agent。这里的关键是description要写得具体——它是主 Agent 的路由依据写得太泛比如处理代码相关任务会导致路由错乱。如果你用的是 Cline 或 CC Switch 这类工具配置思路类似但字段名可能不同。CC Switch 里通常是在config.json里配baseUrl、apiKey、model三件套Sub-Agent 的定义方式看具体版本。Codex 的话配置在~/.codex/auth.json和~/.codex/config.toml# ~/.codex/config.toml model claude-sonnet-4-20250514 model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY// ~/.codex/auth.json { TAOTOKEN_API_KEY: sk-你的密钥 }三件套Base URL Key Model ID在哪个工具里都是这个结构记住这个模式换工具只是改字段名。4. Loop 调度伪代码与验证请求从任务分解到结果整合配置好了接下来是 Loop Engineering 的核心——调度逻辑。Sub-Agent 不是注册完就自动协作的你需要一个主循环来驱动分解任务、分派 Sub-Agent、收集结果、判断是否继续循环。先给 Loop 调度的伪代码def loop_engineering(task, max_iterations10): context {task: task, history: [], artifacts: {}} for i in range(max_iterations): # 1. 主 Agent 规划当前该做什么 plan main_agent.plan(context) if plan.action done: return context[artifacts][final] # 2. 根据 plan 决定调用哪个 Sub-Agent if plan.action delegate: subagent select_subagent(plan.role) result subagent.run( inputplan.input, session_idget_session(subagent.name), timeoutplan.deadline ) # 3. 失败处理 if result.status failed: if plan.retry_count 2: plan.retry_count 1 continue else: context[artifacts][plan.output_key] None context[history].append({error: result.error}) else: context[artifacts][plan.output_key] result.output # 4. 并行分支如果 plan 里有多个独立子任务 elif plan.action parallel: results parallel_run([ (select_subagent(t.role), t.input, t.deadline) for t in plan.tasks ]) for t, r in zip(plan.tasks, results): context[artifacts][t.output_key] r.output if r.ok else None # 5. 记录历史进入下一轮 context[history].append({iteration: i, plan: plan}) return context[artifacts].get(final, 任务未在限定轮次内完成)这个伪代码里有几个关键设计点。第一max_iterations是硬性上限防止死循环。第二每个 Sub-Agent 调用都带timeout超时即失败不无限等待。第三失败有重试上限retry_count 2超过就降级为None让主 Agent 基于已有信息继续。第四并行分支用parallel_run一次性发起等所有结果回来再继续。现在验证这套东西能不能跑通。最直接的验证方式是发一个需要 Sub-Agent 协作的请求然后看调用链。在 Claude Code 里输入请帮我审查 src/utils/format.ts 这个文件找出潜在问题。如果配置正确你会看到主 Agent 先读文件然后调用 code-reviewer Sub-Agent最后整合审查意见输出。验证成功的标志是输出里有结构化的 JSON 审查结果包含verdict和comments字段。如果你想验证并行编排发一个多源调研请求调研 React、Vue、Svelte 三个框架在 2025 年的状态管理方案给出对比。主 Agent 应该会并行调用多个 web-researcher或者一个 researcher 分三轮最后整合成对比报告。验证点是报告里每个框架的信息都有来源标注且三个框架的信息量大致均衡——如果某个框架明显信息少说明那个 Sub-Agent 可能失败了。验证请求时建议打开 Claude Code 的 verbose 模式claude --verbose能看到每次 Sub-Agent 调用的输入输出摘要。如果看不到 Sub-Agent 调用说明description没匹配上主 Agent 自己把活干了。对于模型层面的验证你可以先用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 单独测一下 Model ID 能不能正常出结果排除接入层问题。如果对话页面正常但 Claude Code 里报错那问题在工具配置不在模型接入。5. 常见报错排查401、local proxy failed、reading choices、OAuthSub-Agent 编排链路长出错的地方也多。这一节按真实报错逐个排查。401 Unauthorized。这是最常见的接入层错误。原因通常是 API Key 填错、Key 已失效、或者 Base URL 拼错导致请求打到了错误的端点。排查步骤先确认settings.json里的ANTHROPIC_API_KEY是完整的sk-...格式没有多余空格再确认ANTHROPIC_BASE_URL是https://taotoken.net/api没有多余的/v1或末尾斜杠最后去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 Key 状态正常。如果三个都对还报 401可能是环境变量被系统里其他配置覆盖了用echo $ANTHROPIC_API_KEY检查实际生效的值。local proxy failed。这个报错通常出现在工具尝试走本地代理但代理没启动时。Claude Code 和 Cline 都支持配置代理如果你没配代理检查settings.json里有没有残留的HTTP_PROXY或HTTPS_PROXY环境变量。有的话删掉让请求直连https://taotoken.net/api。另外检查系统 hosts 文件有没有把taotoken.net指向 localhost 的条目。reading choices 报错。这个错误信息通常来自 OpenAI 兼容格式的响应解析失败。原因是某些工具默认按 OpenAI 的choices字段解析响应但实际返回的是 Anthropic 格式content字段。解决办法是确认工具的 API 格式设置Claude Code 用 Anthropic 格式Cline 里要选 Anthropic 而不是 OpenAI Compatible。如果你在 Cline 里配 TaoTokenBase URL 填https://taotoken.net/apiProvider 选 Anthropic。OAuth 相关报错。如果你在 Claude Code 里同时配了 OAuth 登录和 API Key可能出现签名冲突。典型表现是 Sub-Agent 跨调用时报 thinking block signature invalid。原因是不同 OAuth 账号的 thinking block 签名不兼容。解决办法是给每个 Sub-Agent 持久化provider_id让它 sticky 到同一个 provider。在 Claude Code 里这通常意味着不要混用 OAuth 和 API Key统一用 API Key 接入。Sub-Agent 不被调用。配置都对了但主 Agent 就是不用 Sub-Agent。排查检查.claude/agents/目录下的文件是否被正确加载启动时会有日志检查description字段是否足够具体检查任务是否真的需要 Sub-Agent简单任务主 Agent 自己就干了。如果description写的是处理代码任务改成审查代码 diff检查 bug 和安全漏洞输出结构化审查意见路由命中率会高很多。Sub-Agent 超时。长任务里 Sub-Agent 超时是常态。排查先看 Sub-Agent 的timeout设置是否合理默认可能只有 30 秒调研类任务需要 120 秒以上再看 Sub-Agent 的工具集是否过宽导致它做了太多事最后看是不是模型响应慢可以换个更快的 Model ID 试试。并行任务部分失败。并行编排里一个 Sub-Agent 失败不应该拖垮全部。排查确认主 Agent 的整合逻辑是否处理了None结果确认失败标记是否传递到了最终输出用户应该看到某部分调研失败而不是静默缺失确认重试逻辑是否生效。排查时有个通用技巧把max_iterations临时调到 1让主 Agent 只跑一轮看它第一轮做了什么决策。这样能把问题定位到具体的规划或委派环节而不是在长循环里迷失。6. 从配置到生产Sub-Agent 编排的落地建议配置能跑通只是第一步真正上生产还要考虑几件事。第一Sub-Agent 数量控制在 3-7 个。我见过有人一上来建 20 个 Sub-Agent结果主 Agent 路由错误率飙升维护成本爆炸。经验阈值是3-7 个为佳10 个为限。超过 10 个考虑用层级编排Sub-Agent 下面再挂 Sub-Agent而不是平铺。第二每个 Sub-Agent 都要能独立测试。给每个 Sub-Agent 写 golden case固定输入期望输出。回归时跑一遍能快速定位是哪个 Sub-Agent 退化了。没有独立测试的 Sub-Agent出问题时你只能猜。第三可观测性是底线。每次 Sub-Agent 调用都要记录trace_id、agent_id、输入摘要、输出摘要、耗时、token 消耗、状态。没有这些多 Agent 系统就是黑盒里的黑盒。Claude Code 的 verbose 模式能看一部分但生产环境建议自己接一层日志。第四失败要部分成功加明确标记。长程任务里全部回滚代价太大——10 个并行任务里 1 个失败重跑全部 10 个不现实。正确做法是已完成的保留失败的标记出来让用户决定是否重试。主 Agent 的整合逻辑要能处理None结果不能因为一个 Sub-Agent 失败就整个崩掉。第五provider_id 要持久化。这是 HappyClaw 在生产环境踩坑后总结的Sub-Agent 跨调用必须 sticky 到同一个 provider否则 thinking block 签名失效Sub-Agent 退化成新 session上下文丢失。在 Claude Code 里这意味着统一用 API Key 接入不要混用 OAuth。第六编排复杂度匹配任务复杂度。简单任务用单 Agent 加工具调用就够了别上 Sub-Agent。判断标准如果单 Agent 一轮推理能搞定就不拆如果上下文消耗超过窗口 50%或者有明确的并行机会才拆。过度编排是反模式代码量激增可维护性暴跌。最后长期跑编码类 Agent 任务的话Coding Plan 的额度优化能省不少成本地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入过程中遇到配置问题先查文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 大部分报错都有对应说明。需要单独验证某个 Model ID 时用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 快速测一下能排除掉接入层的问题。Sub-Agent 编排不是终点它是 Loop Engineering 的起点。当多个 Sub-Agent 学会在自己的干净上下文里各司其职主 Agent 学会调度和整合长程任务才真正从理论上可行变成工程上可靠。