企业官网建设流程全解析

1. 主会话被上下文撑爆时，Subagents 到底解决了什么

Subagents 是 Claude Code、Cline 这类编码 Agent 里的一个机制：它允许主 Agent 把一件专门的事派发给一个独立运行的子 Agent，子 Agent 从空白上下文起步，干完活只把结论带回来。它适合谁？适合那些主会话已经聊了几十轮、读了几十个文件、上下文快满、再塞一个安全审查就要开始丢信息的项目。它不适合谁？不适合只想让 AI 顺手改一行 CSS 的场景，那种情况留在主会话里更省事。

我先把最容易误解的一点说清楚：Subagent 不是"多了一个更聪明的 AI"。它和主会话用的是同一套底层模型能力，区别在于它被关进了一个隔离的执行沙箱——独立上下文窗口、独立系统提示词、独立工具白名单、可独立指定的模型。这四个隔离维度里，上下文隔离是最关键的。

为什么关键？因为主会话的上下文窗口是有限资源。你让主会话直接审查一次涉及 40 个文件的认证模块重构，读取的文件内容大概会吃掉 80K tokens，而最终有用的结论可能只有 3K tokens。那 80K 的中间产物会一直占着窗口，后续实现阶段可用的空间被硬生生压掉一大块。Subagent 的做法是：这 80K 在子 Agent 内部产生、在子 Agent 内部销毁，主会话只收到那 3K 的结构化结论。净效果是主会话省下约 80K 的上下文空间。

这就是"独立上下文"的真实价值——不是保密，是隔离噪音。安全审查过程中读过的四十个文件，不需要留在主会话里继续占地方。

但这里有个前提：你得让主 Agent 和 Subagent 都能稳定地调用模型。多上下文协作意味着同一时间可能有主会话 + 两三个 Subagent 在发请求，如果每个都走不同的 Key、不同的通道，排查问题时会非常痛苦。所以这篇我用 TaoToken 统一 Key 和 API 通道，把 Cline MCP 和 CC Switch 都接到同一个入口上，再演示一次任务分发与结果回收，让你能确认多上下文协作是不是真的按预期生效。

下面从接入配置开始，一步步来。

2. 用 TaoToken 统一 Key 接入 Cline MCP 与 CC Switch

多上下文协作的第一个坑不是 Subagent 本身，而是"每个工具一套凭证"。主会话在 Claude Code 里跑，Subagent 可能通过 Cline 的 MCP 触发，CC Switch 又在中间切来切去——如果每处都填不同的 Base URL 和 Key，一旦某个 Subagent 报 401，你根本分不清是 Key 错了、通道错了还是模型 ID 写错了。

TaoToken 在这里的作用是提供一个统一的 API 入口，让主 Agent 和所有 Subagent 走同一条通道、同一个 Key。这样排障时变量只有一个：是不是这个 Key 或这个模型 ID 的问题。

先拿 Key。打开控制台，在 API Keys 页面创建一个新 Key，复制出来。注意这个 Key 只在创建时完整显示一次，先存到安全的地方。

拿到 Key 之后，统一入口是：

• Base URL：https://taotoken.net/api
• API Key：你刚创建的那串
• Model ID：按你实际要用的模型填，比如claude-sonnet-4-5这类

这三个东西就是后面所有配置的"三件套"，Cline、CC Switch、Claude Code 全都填这一组，不要各填各的。

2.1 Cline MCP 的配置片段

Cline 的 MCP 配置通常放在项目或用户目录下的 MCP 设置文件里。如果你用的是 JSON 格式的 MCP 配置，结构大致是这样：

{ "mcpServers": { "taotoken-bridge": { "command": "npx", "args": ["-y", "@your-mcp-server-package"], "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoToken密钥", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } } } }

这里的关键是env里的三个变量：Base URL 指向 TaoToken 的 API 入口，Key 用你创建的那串，Model 填你要用的模型 ID。Cline 通过 MCP 启动子进程时，这些环境变量会传进去，子进程里的模型调用就走统一通道了。

如果你用的是 TOML 格式的配置（部分 MCP 客户端支持），等价写法是：

[mcp_servers.taotoken-bridge] command = "npx" args = ["-y", "@your-mcp-server-package"] [mcp_servers.taotoken-bridge.env] ANTHROPIC_BASE_URL = "https://taotoken.net/api" ANTHROPIC_API_KEY = "sk-你的TaoToken密钥" ANTHROPIC_MODEL = "claude-sonnet-4-5"

两种格式选你客户端支持的那种，内容一致。

2.2 CC Switch 的配置

CC Switch 是用来在多个 Claude Code 配置之间切换的工具。它的配置文件一般是一个 JSON，里面存多套 profile。你要做的是新增一个指向 TaoToken 的 profile：

{ "profiles": { "taotoken": { "name": "TaoToken 统一通道", "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的TaoToken密钥", "model": "claude-sonnet-4-5" } }, "active": "taotoken" }

把active设成taotoken，之后 Claude Code 启动时读到的就是这套配置。这样主会话和通过 CC Switch 拉起的 Subagent 环境用的是同一个 Base URL 和 Key，通道统一了。

2.3 Claude Code 侧的 settings 片段

Claude Code 本身也支持通过 settings 指定模型通道。在项目的.claude/settings.json里可以这样写：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoToken密钥", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } }

注意路径：项目级是.claude/settings.json，用户级是~/.claude/settings.json。项目级优先。如果你希望所有项目都走 TaoToken，就写用户级；如果只想某个项目走，写项目级。

三处配置填的是同一组三件套（Base URL + Key + Model ID），这是后面能顺利排障的基础。配置完先别急着跑 Subagent，下一节先验证单条请求通不通。

3. 可复制配置：把三件套落到 settings 与 agent 定义里

上一节给了通道配置，这一节把 Subagent 本身的定义也补全，因为 Subagent 能不能按预期工作，一半取决于通道，一半取决于 agent 定义文件。

Subagent 的定义文件通常放在.claude/agents/目录下，一个角色一个.md文件。文件头部是 YAML frontmatter，声明 name、description、tools，下面是角色指令。这里最容易出问题的是tools字段——它决定了这个 Subagent 物理上能干什么。

先看一个只读安全审查 Subagent 的完整定义：

--- name: security-reviewer description: > 审查代码变更中的安全漏洞。 在认证、权限、数据处理的改动后使用。 tools: Read, Grep, Glob --- ## 角色 你是安全审计员。你的任务是发现代码中的安全风险，不是修复它们。 ## 检查范围 - 认证绕过：session 校验缺失、token 验证跳过 - 注入攻击：SQL 拼接、命令注入、XSS 模板拼接 - 敏感数据暴露：日志中的密钥、API 响应中的内部 ID、硬编码凭据 - 不安全默认值：缺失的权限校验、宽松的 CORS、未设过期时间的 token ## 输出格式 对每个发现，输出： 1. 严重级别（critical / high / medium / low） 2. 文件路径和行号 3. 问题描述（一行） 4. 影响范围（一句话） 5. 修复建议（具体到操作） ## 禁止事项 - 不要修改任何文件 - 不要输出完整的修复代码，只输出建议 - 不要对没有文件证据的风险做推测性判断

这个定义里tools: Read, Grep, Glob是硬约束。三个工具全是只读的：Read 读文件、Grep 搜内容、Glob 按文件名找文件。没有 Edit、Write、Bash，所以这个 Subagent 物理上无法改文件——哪怕它的提示词写错了、被诱导了，也改不了。这就是"工具白名单是行为约束的最底层防线"的意思。

再看一个需要执行测试的 Subagent，它必须多一个 Bash：

--- name: test-runner description: > 运行测试并分析失败原因。 在实现完成后验证，或 CI 失败后定位问题。 tools: Read, Grep, Glob, Bash --- ## 角色 你是测试工程师。运行测试、归纳失败、定位根因。 ## 工作流程 1. 先读 CLAUDE.md 获取项目测试命令 2. 运行测试，等待结果 3. 对每个失败用例： a. 读失败的测试文件和对应源文件 b. 分析是断言错误、环境问题还是代码 bug c. 定位最小可复现路径 4. 归纳失败模式（同类失败合并，不要逐条罗列） ## Bash 使用限制 - 只允许运行测试相关命令（test, jest, vitest, pytest 等） - 不允许运行安装、构建、部署命令 - 不允许修改任何文件

注意这里 Bash 是给了的，但角色指令里明确约束了使用范围。这是"给权限但约束范围"——测试分析的核心价值就是实际跑测试、读输出，只读代码文件替代不了真实执行结果。但 Bash 权限高，所以必须靠指令约束住。

两个定义有个共同结构：角色定义 → 检查范围 → 输出格式 → 约束。这个结构不是模板洁癖，是有效性的最低要求。没有明确检查范围的角色会输出泛泛建议，把代码风格、性能、可读性全评论一遍，淹没真正的安全问题；没有输出格式的角色会返回大段自然语言，主会话没法解析；没有约束的角色会越界。

把通道配置（上一节）和 agent 定义（这一节）都放好之后，目录结构大概是这样：

项目根/ ├── .claude/ │ ├── settings.json # 通道三件套 │ └── agents/ │ ├── security-reviewer.md │ └── test-runner.md

到这里配置就齐了。下一节验证它到底通不通。

4. 验证请求：一次任务分发与结果回收

配置写完不代表生效，必须实测。这一节做一次完整的任务分发与结果回收，确认多上下文协作按预期工作。

4.1 先验证单条请求通不通

在跑 Subagent 之前，先用一条最简单的请求确认通道没问题。用 curl 直接打 TaoToken 的 API：

curl https://taotoken.net/api/v1/messages \ -H "x-api-key: sk-你的TaoToken密钥" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-4-5", "max_tokens": 64, "messages": [ {"role": "user", "content": "只回复两个字：通了"} ] }'

如果返回里能看到正常的content字段和文本，说明 Base URL、Key、Model ID 三件套都对。如果这里就报错，先别往下走，去第 5 节对照报错排查。

4.2 触发一次 Subagent 分发

单条通了之后，在 Claude Code 主会话里触发 Subagent。假设你刚改完一个认证模块，想让 security-reviewer 审一遍。在主会话里输入类似这样的指令：

用 security-reviewer 审查 src/auth/ 下的改动

主会话会根据 security-reviewer 的description字段判断该不该路由到这个 Subagent，然后派发任务。这时候会发生几件事：

第一，主会话把任务打包成一条消息发给 Subagent。第二，Subagent 从空白上下文启动，加载自己的角色指令（security-reviewer.md 的内容），只读任务相关的文件。第三，Subagent 用tools里声明的 Read、Grep、Glob 干活，读文件、搜模式、找文件。第四，干完后按"输出格式"返回一条结构化消息。第五，主会话收到这条消息，继续后续工作。

4.3 确认上下文隔离真的生效

怎么确认 Subagent 是独立上下文？看两个信号。

信号一：Subagent 不会引用主会话里聊过的内容。如果你在主会话里刚讨论过某个函数名，但没写进任务描述，Subagent 不应该知道这个函数名。它只能看到任务描述和它自己读的文件。如果它"莫名其妙"知道主会话里的细节，说明隔离没生效。

信号二：主会话不会自动获得 Subagent 的中间产物。Subagent 读了 40 个文件，主会话的上下文里不应该出现这 40 个文件的内容，只应该出现 Subagent 返回的那条结论。你可以在主会话里问"你刚才读了哪些文件"，如果它列不出来（因为它没读，是 Subagent 读的），说明隔离生效了。

4.4 结果回收

Subagent 返回的结构化报告大概长这样：

## 任务结果 ### 摘要 在 src/auth/ 发现 2 个高危、1 个中危问题，集中在 session 校验和 token 过期处理。 ### 详细发现 | # | 类型 | 严重级别 | 文件 | 描述 | |---|------|---------|------|------| | 1 | 认证绕过 | high | src/auth/session.ts:42 | session 校验在异常分支被跳过 | | 2 | 敏感数据暴露 | high | src/auth/token.ts:88 | 日志打印了完整 token | | 3 | 不安全默认值 | medium | src/auth/config.ts:15 | token 未设过期时间 | ### 建议 1. session.ts:42 的异常分支补上校验，或直接抛错 2. token.ts:88 改为只打印 token 前 8 位 3. config.ts:15 补上默认过期时间 ### 未确认项 - src/auth/legacy/ 下的旧代码未纳入本次审查范围

主会话收到后，按这个流程处理：先看摘要是否回答了原始问题；如果有 critical/high，优先处理；如果建议可直接执行，按建议改；如果未确认项影响决策，追加调查或人工确认。注意最后一条——不要把 Subagent 的建议当真理，要结合当前上下文判断优先级。

到这里，一次完整的"分发 → 隔离执行 → 结果回收"就跑通了。如果你在第 4.1 或 4.2 卡住了，下一节对照报错。

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

多上下文协作的报错大多集中在通道和权限两块。下面按真实报错逐个对照。

5.1 401 Unauthorized

最常见。报错长这样：

API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}

原因通常是三个之一：Key 复制时带了空格或换行；Key 已经失效或被删；配置里填的字段名不对（比如把x-api-key写成了Authorization）。

排查顺序：先确认 Key 没有多余空白，重新从控制台复制一次；再确认这个 Key 在控制台里还是启用状态；最后确认配置里的字段名和客户端要求的一致。Cline 和 Claude Code 一般用ANTHROPIC_API_KEY环境变量，curl 直接测时用x-api-key头，别混。

5.2 local proxy failed

报错类似：

Error: local proxy failed to connect

这个通常出现在你本地配了某种转发但转发进程没起来，或者端口被占。如果你没有主动配本地转发，检查一下配置里是不是残留了指向localhost或127.0.0.1的 Base URL。统一走 TaoToken 的话，Base URL 应该是https://taotoken.net/api，不是本地地址。把配置里所有本地地址清掉，重试。

5.3 reading choices 相关报错

报错类似：

Error reading choices: unexpected end of JSON input

这类报错一般是响应体不是预期的 JSON 结构，常见于 Base URL 填错——比如把/api漏了，或者多填了一段路径，导致请求打到了非 API 端点，返回了 HTML 或空响应。确认 Base URL 精确等于https://taotoken.net/api，不要自己加/v1之类的后缀（具体路径由客户端拼接）。

5.4 OAuth 相关报错

报错类似：

OAuth token expired / invalid_grant

如果你之前用 OAuth 方式登录过某个客户端，它可能缓存了旧的 OAuth 凭证，和你新配的 API Key 冲突。解决办法是清掉客户端的凭证缓存，强制它用配置里的 API Key。Claude Code 的话，检查~/.claude/下有没有残留的凭证文件；CC Switch 的话，确认 active profile 指向的是你新配的 taotoken profile，而不是旧的 OAuth profile。

5.5 Subagent 越界改文件

这个不是通道报错，但很常见。现象是：你配了一个只读审查 Subagent，结果它把文件改了。根因几乎总是tools字段没写或写漏了。如果 agent 定义里没有tools字段，Subagent 会继承主会话的全部工具权限，包括 Edit、Write、Bash。角色指令里写"不要修改文件"是建议，工具权限才是约束。修复方法：在 frontmatter 里显式写tools: Read, Grep, Glob，把写操作工具排除掉。

5.6 并行 Subagent 触发 429

现象是主会话或某个 Subagent 突然报 429 限流。原因是并行跑的 Subagent 太多，请求速率叠加超过了限制。假设限制是 60 请求/分钟，主会话占 20，三个 Subagent 各占 15、10、12，加起来 57，接近上限，稍微波动就超。管理策略：串行调度（一个完成再起下一个）、有限并行（最多 2-3 个）、优先级队列（高优先级先跑）、结果缓存（相似任务复用结果）。常规场景控制在 2-3 个并行比较稳。

排障时如果确认是通道问题，去 API Keys 页面重新生成 Key；如果是配置格式问题，对照接入文档核对字段名。这两个入口能覆盖绝大多数通道类报错。

6. 把统一 Key 用在长期编码与 Agent 编排上

跑通一次 Subagent 不难，难的是把它变成日常编码流程的一部分。这里给几条实测下来比较有用的经验。

第一，角色要窄。一个只查认证漏洞的安全审查员，比一个"什么都查"的安全专家有效得多。任务越模糊，Subagent 越容易输出泛泛建议。判断标准不是"这个任务够不够复杂"，而是"隔离上下文和限制工具能不能让结果更可控"。如果答案是否定的，留在主会话更稳妥。

第二，工具白名单宁少勿多。只读角色就只给 Read、Grep、Glob，需要执行测试才加 Bash，并且用指令约束 Bash 的范围。不要因为"可能用得上"就放开权限，权限一旦放开，LLM 倾向于使用它能用的工具。

第三，输出格式必须结构化。Subagent 返回自然语言段落，主会话很难解析。用表格、固定字段、明确的严重级别，让主会话能直接提取可执行信息。

第四，控制并行数量。2-3 个并行是常规上限，再多就要考虑速率限制和 token 预算。每个 Subagent 的执行都消耗 token，三个并行各 30K 就是 90K，这笔消耗从账户预算里扣，不从主会话上下文里扣，但一样要算成本。

第五，通道统一。主会话、Subagent、CC Switch 切换的环境，全走同一个 TaoToken Key 和 Base URL。这样出问题时变量只有一个，排障时间能省一大半。长期跑编码任务和 Agent 编排的话，用 Coding Plan 会比按量更可控，尤其是你经常并行跑多个 Subagent 的场景。

如果你还在验证阶段，想先确认模型行为符不符合预期，可以先用模型对话快速试几条请求，确认通道和模型 ID 都对，再往 Subagent 编排上投入。

最后一条经验：第一次用新 Subagent 时，一定检查它有没有遵守工具限制和输出格式。不要假设配置生效了。我见过太多次"配了只读但实际能写"的情况，都是因为tools字段漏写。验证一次，比事后收拾烂摊子便宜得多。