企业官网建设流程全解析

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 管理集中在一处。

你需要准备的三件套：

获取 API Key 的路径：访问官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册后在控制台创建密钥。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，API Keys 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。

这里有个容易踩的坑：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_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 试一下，能正常出结果就说明这个 Model ID 可用。

对于 Sub-Agent 编排，我建议主 Agent 用能力最强的模型（比如 Sonnet 4），Sub-Agent 按职责选：coder 用强模型，reviewer 可以用稍弱的模型降低成本，researcher 用中等模型即可。TaoToken 的好处是这些模型切换只改 Model ID，Base URL 和 Key 不变。

如果你打算长期跑编码类 Agent 任务，可以考虑 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 ，遇到配置问题先查这里。

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_iterations=10): 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( input=plan.input, session_id=get_session(subagent.name), timeout=plan.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_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 单独测一下 Model ID 能不能正常出结果，排除接入层问题。如果对话页面正常但 Claude Code 里报错，那问题在工具配置，不在模型接入。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

Sub-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_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 确认 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 里配 TaoToken，Base URL 填https://taotoken.net/api，Provider 选 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_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 ，大部分报错都有对应说明。需要单独验证某个 Model ID 时，用模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 快速测一下，能排除掉接入层的问题。

Sub-Agent 编排不是终点，它是 Loop Engineering 的起点。当多个 Sub-Agent 学会在自己的干净上下文里各司其职，主 Agent 学会调度和整合，长程任务才真正从"理论上可行"变成"工程上可靠"。