1. 1900 文件 Monorepo 里，单 Agent 为什么一定会卡住
一个 1930 个 TypeScript 文件、Lerna 三子包（Web + Dashboard + H5）的前端仓库，组件树深度经常超过 8 层。这种体量下，你让一个 Agent 串行干活，最先崩掉的不是模型能力，而是上下文窗口和等待时间。
我拿一个真实需求做过对照：新增「合规审查」模块，要动四个地方——web 子包建页面组件、dashboard 子包加管理后台、shared 包补公共类型、API 层写单测。串行模式下，Agent 做完第一步再做第二步，每一步都要重新读一遍相关文件、重新建立对仓库结构的理解。总耗时基本等于所有任务耗时之和，而且越到后面越慢，因为上下文里堆的东西越来越多。
这里的关键矛盾是：Monorepo 的物理结构是共享的，但任务逻辑是独立的。三个子包各自有自己的tsconfig.json、自己的构建产物、自己的依赖树，可它们又共享同一个.git、同一个node_modules（hoist 之后）、同一套 shared 类型。单 Agent 串行时，它没法同时「站在 web 视角」和「站在 dashboard 视角」思考，只能来回切换，切换成本极高。
多 Agent 并行的价值就在这：让 Agent A 专注 web 子包，Agent B 专注 dashboard，Agent C 专注 shared 类型定义，三个同时跑。实测下来，上面那个场景并行比串行快 60% 左右。但前提是——你得先解决隔离问题，否则三个 Agent 同时改 shared 包，合并冲突能让你怀疑人生。
这篇就按「worktree 隔离 → 任务边界划分 → 类型校验流水线」的顺序，把可复制的脚本和配置交给你。适合已经在用 Claude Code、手里有中大型 TypeScript Monorepo、想从单 Agent 升级到多 Agent 并行的同学。如果你还在单文件小项目阶段，这篇的收益不明显，可以先收藏。
2. 前置准备：TaoToken 接入与 Claude Code 环境打通
多 Agent 并行对底层模型调用的稳定性要求比单 Agent 高得多——三个 Agent 同时发请求，任何一个超时或鉴权失败，整个并行批次都会拖慢。所以第一步是把接入层做扎实。
TaoToken 在这里的角色是统一的模型调用入口，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。你需要先在控制台拿到 API Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。
拿到 Key 之后，Claude Code 的接入方式有两种，我推荐用环境变量，因为多 Agent 并行时每个 worktree 会起独立进程，环境变量最不容易串。
# 写入 shell 配置，全局生效 export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的Key" export ANTHROPIC_MODEL="claude-sonnet-4-5"如果你用的是 Claude Code 的 settings 文件方式，路径在~/.claude/settings.json，内容长这样：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } }注意 Base URL 后面不要带/v1，Claude Code 会自己拼路径。Model ID 要和你实际开通的模型一致，写错了会直接 404。
如果你同时用 Cline 或 CC Switch 管理多个配置，那三件套必须写全：Base URL 填https://taotoken.net/api，Key 填控制台生成的，Model ID 填具体模型名。缺任何一个都会在启动时报鉴权或模型不存在。
验证接入是否通，最直接的方式是跑一次模型对话，地址 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite ，发一句「你好」看有没有正常返回。返回正常说明 Key 和端点都没问题，再进 Claude Code 里跑。
Claude Code 本身的安装和初始化这里不展开，假设你已经能正常claude启动。接下来要确认的是 git 版本——worktree 需要 git 2.5 以上，建议 2.20+，因为老版本 worktree 在子模块和 sparse-checkout 上有坑。
git --version # 期望输出：git version 2.34.1 或更高还有一个容易被忽略的点：Monorepo 里如果用了 pnpm workspace 或 yarn workspace，每个 worktree 是独立目录，node_modules不会自动共享。你有两个选择——要么在每个 worktree 里重新pnpm install（慢但干净），要么用 pnpm 的全局 store 做硬链接（快，推荐）。下面脚本里我会用后者。
3. 可复制配置：worktree 初始化脚本与 Agent 分工模板
这一节是全文的核心，直接给你能跑的脚本和配置。
3.1 worktree 初始化脚本
在仓库根目录建一个scripts/agent-worktree.sh：
#!/usr/bin/env bash set -euo pipefail # 用法: ./scripts/agent-worktree.sh <agent-name> <base-branch> AGENT_NAME="${1:?agent name required}" BASE_BRANCH="${2:-main}" REPO_ROOT="$(git rev-parse --show-toplevel)" WORKTREE_DIR="${REPO_ROOT}/.worktrees/${AGENT_NAME}" BRANCH_NAME="agent/${AGENT_NAME}" # 1. 清理同名残留 if [ -d "${WORKTREE_DIR}" ]; then echo "[worktree] 清理已存在的 ${WORKTREE_DIR}" git worktree remove --force "${WORKTREE_DIR}" || true fi # 2. 基于最新 base 分支创建 worktree git fetch origin "${BASE_BRANCH}" --quiet git worktree add -b "${BRANCH_NAME}" "${WORKTREE_DIR}" "origin/${BASE_BRANCH}" # 3. 用 pnpm 全局 store 做硬链接安装，避免重复下载 cd "${WORKTREE_DIR}" if [ -f "pnpm-lock.yaml" ]; then pnpm install --frozen-lockfile --prefer-offline elif [ -f "yarn.lock" ]; then yarn install --frozen-lockfile --prefer-offline else npm ci --prefer-offline fi echo "[worktree] ${AGENT_NAME} 就绪 -> ${WORKTREE_DIR}" echo "[worktree] 分支: ${BRANCH_NAME}"给它执行权限：
chmod +x scripts/agent-worktree.sh这个脚本做了三件事：清理残留、基于 origin/main 建独立分支、用离线优先的方式装依赖。--prefer-offline配合 pnpm 的全局 store，第二个 worktree 的安装时间通常只有第一次的 1/5。
3.2 Agent 分工配置模板
在仓库根目录建agents/fleet.json，定义每个 Agent 的作用域和任务：
{ "fleet": [ { "name": "web-compliance", "scope": ["packages/web/src/modules/compliance/**"], "prompt": "在 packages/web/src/modules/compliance 下创建合规审查页面组件，复用 shared 包已有类型，不要修改 shared 包", "model": "claude-sonnet-4-5", "budget": 80000 }, { "name": "dashboard-compliance", "scope": ["packages/dashboard/src/pages/compliance/**"], "prompt": "在 packages/dashboard/src/pages/compliance 下创建合规审查管理页，只读 shared 类型，不写入", "model": "claude-sonnet-4-5", "budget": 80000 }, { "name": "shared-types", "scope": ["packages/shared/src/types/compliance.ts"], "prompt": "在 packages/shared/src/types/compliance.ts 中定义合规审查相关类型，导出 interface 和 enum", "model": "claude-sonnet-4-5", "budget": 40000 } ] }关键在scope字段——它限定了每个 Agent 只能改哪些文件。这是避免合并冲突的第一道防线。注意 shared-types 这个 Agent 的 scope 精确到单个文件，因为类型定义是共享资源，多个 Agent 同时改必然冲突。
3.3 并行调度脚本
建scripts/run-fleet.sh：
#!/usr/bin/env bash set -euo pipefail FLEET_FILE="agents/fleet.json" REPO_ROOT="$(git rev-parse --show-toplevel)" # 读取 fleet 配置，逐个起 worktree 并启动 Agent AGENT_COUNT=$(node -e "console.log(require('./${FLEET_FILE}').fleet.length)") for i in $(seq 0 $((AGENT_COUNT - 1))); do NAME=$(node -e "console.log(require('./${FLEET_FILE}').fleet[${i}].name)") PROMPT=$(node -e "console.log(require('./${FLEET_FILE}').fleet[${i}].prompt)") SCOPE=$(node -e "console.log(require('./${FLEET_FILE}').fleet[${i}].scope.join(','))") echo "[fleet] 启动 Agent: ${NAME}" "${REPO_ROOT}/scripts/agent-worktree.sh" "${NAME}" main # 在对应 worktree 里启动 Claude Code，后台运行 ( cd "${REPO_ROOT}/.worktrees/${NAME}" claude --print "${PROMPT}" \ --allowed-paths "${SCOPE}" \ > "${REPO_ROOT}/.worktrees/${NAME}/agent.log" 2>&1 ) & done wait echo "[fleet] 所有 Agent 执行完毕"--allowed-paths是 Claude Code 的路径白名单参数，配合 fleet.json 里的 scope 使用，双保险。&让每个 Agent 后台跑，wait等全部结束。
跑起来：
./scripts/run-fleet.sh三个 Agent 会同时在各自的 worktree 里工作，互不干扰。日志分别落在.worktrees/<name>/agent.log。
4. 验证请求与成功结果：tsc 校验与冲突检测
Agent 跑完之后，不能直接合并。必须先做类型校验和冲突检测。
4.1 并行 tsc 校验
在每个 worktree 里跑一次tsc --noEmit，确认类型没崩：
#!/usr/bin/env bash # scripts/verify-fleet.sh set -euo pipefail REPO_ROOT="$(git rev-parse --show-toplevel)" FAILED=0 for dir in "${REPO_ROOT}"/.worktrees/*/; do NAME=$(basename "${dir}") echo "[verify] 校验 ${NAME} ..." if (cd "${dir}" && npx tsc --noEmit -p tsconfig.json); then echo "[verify] ${NAME} 类型校验通过" else echo "[verify] ${NAME} 类型校验失败" FAILED=1 fi done exit ${FAILED}跑：
./scripts/verify-fleet.sh期望输出是每个 Agent 都打印「类型校验通过」。如果有失败，去对应 worktree 里单独跑npx tsc --noEmit看具体报错行。
4.2 冲突检测
合并前先做一次 dry-run 合并检测：
#!/usr/bin/env bash # scripts/check-conflicts.sh set -euo pipefail REPO_ROOT="$(git rev-parse --show-toplevel)" cd "${REPO_ROOT}" git checkout main git pull origin main --quiet for branch in $(git branch --list 'agent/*' --format='%(refname:short)'); do echo "[conflict] 检测 ${branch} ..." if git merge-tree "$(git merge-base main "${branch}")" main "${branch}" | grep -q '<<<<<<<'; then echo "[conflict] ${branch} 存在冲突，需人工处理" else echo "[conflict] ${branch} 可干净合并" fi donegit merge-tree是纯内存操作，不会真的改工作区，适合做预检。输出里出现<<<<<<<就说明有冲突。
4.3 成功结果长什么样
三个 Agent 跑完、校验通过、无冲突之后，你会看到：
[verify] web-compliance 类型校验通过 [verify] dashboard-compliance 类型校验通过 [verify] shared-types 类型校验通过 [conflict] agent/web-compliance 可干净合并 [conflict] agent/dashboard-compliance 可干净合并 [conflict] agent/shared-types 可干净合并这时候按顺序合并：先合 shared-types（因为其他两个依赖它），再合 web 和 dashboard。
git checkout main git merge agent/shared-types --no-ff -m "feat: 合规审查类型定义" git merge agent/web-compliance --no-ff -m "feat: 合规审查页面" git merge agent/dashboard-compliance --no-ff -m "feat: 合规审查管理页"合并完再跑一次全量tsc --noEmit和单测，确认整体没崩。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
多 Agent 并行时，报错会比单 Agent 更集中地暴露接入层问题。下面几个是我踩过的。
401 Unauthorized：最常见。原因通常是ANTHROPIC_API_KEY没设、设错、或者 worktree 里环境变量没继承。检查方式：
echo $ANTHROPIC_API_KEY # 应该输出 sk- 开头的字符串如果 worktree 里跑 Agent 报 401，但主目录正常，多半是 shell 配置没被 worktree 的子 shell 加载。解决办法是在run-fleet.sh里显式 export，或者把配置写进~/.claude/settings.json而不是 shell rc。
local proxy failed：这个报错说明 Claude Code 尝试走本地代理但连不上。检查ANTHROPIC_BASE_URL是不是写成了http://localhost:xxxx之类的本地地址。正确值应该是https://taotoken.net/api。另外检查有没有残留的HTTP_PROXY/HTTPS_PROXY环境变量指向失效地址：
env | grep -i proxy # 如果有输出且地址不可用，unset 掉 unset HTTP_PROXY HTTPS_PROXYreading choices 相关报错：通常出现在模型返回格式不符合预期时，比如 Agent 的 schema 定义太宽泛，模型返回了无法解析的结构。回到 fleet.json，把 prompt 里的输出格式要求写死，比如「只返回 JSON，不要 markdown 代码块」。如果用了--print模式，确保 prompt 里明确要求结构化输出。
OAuth 相关报错：Claude Code 某些版本会尝试 OAuth 流程，如果你用的是 API Key 模式，需要在 settings 里关掉 OAuth。检查~/.claude/settings.json里有没有"forceLoginMethod": "oauth"之类的字段，有的话删掉或改成"apiKey"。另外确认没有同时设置CLAUDE_CODE_OAUTH_TOKEN和ANTHROPIC_API_KEY，两者冲突会导致鉴权混乱。
worktree 创建失败：报fatal: '<path>' already exists或is a main working tree。前者是残留目录没清干净，手动rm -rf .worktrees/<name>再跑；后者是你把 worktree 建到了主仓库目录上，检查脚本里的WORKTREE_DIR路径。
pnpm install 在 worktree 里极慢：说明没走全局 store。确认pnpm config get store-dir有输出，且--prefer-offline生效。如果还是慢，检查是不是每个 worktree 都在重新下载，可以在脚本里加--offline强制走缓存。
tsc 校验报 shared 类型找不到：因为 shared 包的构建产物（dist/）没生成。在 shared 包目录先跑一次pnpm build，或者把 tsconfig 的 paths 指向源码而非 dist。Monorepo 里推荐后者，用 project references 做增量编译。
6. 从 2 个 Agent 起步，把并行当成加速器而不是银弹
多 Agent 并行的收益和任务独立性严格成正比。我实测的数据：新模块开发（3 个子包）从 45 分钟降到 18 分钟，提升 60%；大规模代码审查（50 个文件）从 35 分钟降到 12 分钟，提升 66%；但 Bug 猎杀这种范围未知的任务，从 20 分钟只降到 15 分钟，提升 25%；而简单搜索一个函数定义，单 Agent 10 秒，多 Agent 反而 25 秒——负优化。
原因很简单：Agent 的启动成本包括 worktree 创建、依赖安装、上下文加载，加起来 200-500ms 起步，复杂仓库里更高。为「搜一个函数」起 Agent，纯属浪费。
所以我的建议是：从 2 个 Agent 的简单并行开始，选两个作用域完全不重叠的任务，跑通 worktree 隔离和 tsc 校验的完整流程，再逐步加到 3 个、5 个。每次加 Agent 之前，先问自己一句：这个任务的文件集合和现有 Agent 有没有重叠？有重叠就先拆任务，别硬上。
Token 预算也要控制。一次 5 Agent 并行的 Code Review，Token 消耗轻松破 200K。在 fleet.json 里给每个 Agent 设budget字段，跑之前算一下总量，别让并行变成烧钱。
最后，合并顺序有讲究：先合被依赖的（shared 类型），再合依赖方（web、dashboard）。合并前必跑tsc --noEmit和冲突预检，这两步能挡掉 90% 的集成问题。worktree 隔离解决的是「同时改」的问题，类型校验解决的是「改完能不能用」的问题，两者缺一不可。
如果你在跑的过程中遇到接入层的报错，先去 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 确认 Key 状态，再看 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 的接入文档核对参数。长期跑编码 Agent 的话，Coding Plan 在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，比按量计费更适合高频并行场景。
