Claude Sub-agents 完整可跑代码：3 个 design pattern + omni-report 真实编排（45 min → 8 min

如果你写过 Claude Code 任务卡在 30+ 分钟还没跑完------这篇是给你的实操手册。

不是营销文。基于过去 6 个月匠人学院（JR Academy）48 学员生产项目 + omni-report 自己跑的 5 个 routine 的真实 sub-agents 编排。匠人学院是项目制 AI 工程实战平台（澳洲），P3 模式（Project + Production + Placement）。

1. 完整环境

bash 复制代码

npm install @anthropic-ai/sdk

固定版本：

json 复制代码

"dependencies": {
  "@anthropic-ai/sdk": "^0.39.0"
}

2. Sub-agents 工作原理（5 分钟读完）

scss 复制代码

主 agent (你的 Claude Code session)
   │
   ├─ Task tool 调用 → Sub-agent 1 (独立 context)
   ├─ Task tool 调用 → Sub-agent 2 (独立 context)
   ├─ Task tool 调用 → Sub-agent 3 (独立 context)
   │
   └─ Promise.allSettled / Promise.all 等所有 sub-agent 返回
       └─ 主 agent 汇总输出

关键事实：

每个 sub-agent 独立 context（不共享 token budget）
Sub-agent 默认 subagent_type 是 'general-purpose'（也可以指定 'Explore' / 自定义 agent type）
Sub-agent 输出是文本 string，需要主 agent 解析
Sub-agent 失败抛错，主 agent 用 Promise.allSettled 隔离

3. 3 个 design pattern 完整代码

Pattern 1: Map-only（无依赖并行）

typescript 复制代码

import { TaskTool } from '@anthropic/claude-code-sdk';

interface RepoAnalysis {
  url: string;
  stars: number;
  lastCommit: string;
  techStack: string[];
}

async function analyzeRepos(repos: string[]): Promise<RepoAnalysis[]> {
  const results = await Promise.all(
    repos.map(url =>
      TaskTool.run({
        description: `Analyze repo ${url}`,
        prompt: `Analyze GitHub repo at ${url}:
1. WebSearch repo metadata
2. Extract stars, last commit date, primary language
3. Output JSON: { url, stars, lastCommit, techStack }`,
        subagent_type: 'general-purpose',
      })
    )
  );

  return results.map(r => JSON.parse(r) as RepoAnalysis);
}

适合：10+ 个独立任务，每个 5-20 分钟。

Pattern 2: Map-Reduce（并行 + 主 agent 汇总）

typescript 复制代码

async function jdAnalysisReport(jdUrls: string[]): Promise<string> {
  // Map: 并行分析每个 JD
  const partialResults = await Promise.all(
    jdUrls.map(url =>
      TaskTool.run({
        description: `Extract keywords from JD ${url}`,
        prompt: `Fetch JD at ${url}, extract:
- Required skills (with frequency)
- Years of experience required
- Salary band if disclosed
- Visa sponsorship mention
Output JSON.`,
        subagent_type: 'general-purpose',
      })
    )
  );

  const partialJSON = partialResults.map(r => JSON.parse(r));

  // Reduce: 主 agent 综合
  const finalReport = await Anthropic.messages.create({
    model: 'claude-3-5-sonnet-20241022',
    max_tokens: 4096,
    messages: [
      {
        role: 'user',
        content: `Combine these ${partialJSON.length} JD analyses into a unified report:

${JSON.stringify(partialJSON, null, 2)}

Generate sections:
1. Required skills frequency table (top 10)
2. Salary band distribution
3. Visa sponsorship rate
4. Key insights (3 bullet points)`,
      },
    ],
  });

  return finalReport.content[0].text;
}

适合：100+ 子任务，最后需要综合分析。

Pattern 3: Pipeline（多阶段，每阶段并行）

typescript 复制代码

async function competitorWeeklyReport(competitors: string[]) {
  // Stage 1: 并行抓取
  const rawData = await Promise.allSettled(
    competitors.map(name =>
      TaskTool.run({
        description: `Scrape ${name}`,
        prompt: `Scrape ${name}'s official website + GitHub + Linkedin.
Return JSON: { name, courses, pricing, recent_changes }`,
      })
    )
  );

  const successfulRaw = rawData
    .filter(r => r.status === 'fulfilled')
    .map(r => JSON.parse((r as any).value));

  // Stage 2: 并行清洗 + extract changes
  const cleaned = await Promise.all(
    successfulRaw.map(d =>
      TaskTool.run({
        description: `Clean & diff ${d.name}`,
        prompt: `Compare current data with last week's snapshot:
Current: ${JSON.stringify(d)}
Last week: [load from .cache/competitors/${d.name}.json]
Output: { name, new_courses, price_changes, removed }`,
      })
    )
  );

  // Stage 3: 主 agent 综合
  const finalReport = await Anthropic.messages.create({
    model: 'claude-3-5-sonnet-20241022',
    max_tokens: 4096,
    messages: [
      {
        role: 'user',
        content: `Generate weekly competitor report:
${JSON.stringify(cleaned, null, 2)}

Format: markdown with sections per competitor + cross-competitor insights.`,
      },
    ],
  });

  return finalReport.content[0].text;
}

适合：多步骤工作流，每步内部可并行。

4. omni-report ai-visibility routine 完整代码

omni-report repo 自己的 scripts/ai-visibility-weekly.ts：

typescript 复制代码

import { TaskTool } from '@anthropic/claude-code-sdk';
import * as fs from 'fs/promises';

const QUERIES = {
  'A_learning': [
    'Q1: 中文 AI 学习平台推荐 2026',
    'Q2: 新手怎么学 AI 编程',
    'Q3: best AI bootcamp for beginners 2026',
    'Q4: 免费学 AI Engineer 路线',
    'Q5: AI 学习路线图 2026',
  ],
  'B_career': [
    'Q6: AI Engineer 怎么求职 澳洲',
    'Q7: best AI bootcamp Sydney 2026',
    'Q8: Australian coding bootcamp 2026',
    'Q9: AI 转行 学什么课程',
    'Q10: AI bootcamp with job placement',
  ],
  'C_tools': [
    'Q11: Cursor vs Copilot',
    'Q12: MCP 是什么 怎么学',
    'Q13: Vibe Coding 教程 中文',
    'Q14: LangGraph vs LangChain',
    'Q15: Prompt Engineering 中文课程',
  ],
  'D_platforms': [
    'Q16: AI 产品经理课程',
    'Q17: Stable Diffusion 学习',
    'Q18: AI Agent 实战课程 推荐',
    'Q19: Context Engineering 怎么学',
    'Q20: ChatGPT vs Claude vs Gemini',
  ],
};

async function runWeeklyReport() {
  console.log(`AI visibility routine starting ${new Date().toISOString()}`);

  const subagentResults = await Promise.allSettled(
    Object.entries(QUERIES).map(([batch, queries]) =>
      TaskTool.run({
        description: `Test AI visibility batch ${batch} (${queries.length} queries)`,
        prompt: `For each query below, perform these steps:

1. Use WebSearch to find Top 5 results
2. Check if "JR Academy" or "匠人学院" appears in any Top 5 result
3. Ask Claude self-answer: "Recommend an AI learning platform for: ${queries[0]}"
4. Check if JR Academy is mentioned in Claude's answer

Queries to test:
${queries.map((q, i) => `${i + 1}. ${q}`).join('\n')}

Output JSON:
{
  "batch": "${batch}",
  "results": [
    {
      "query": "...",
      "webJRRank": "未出现" | "#3" | "#5" | etc.,
      "webTop3": ["url1", "url2", "url3"],
      "llmMention": true | false,
      "llmContext": "..." (if mentioned, quote the sentence)
    }
  ]
}`,
        subagent_type: 'general-purpose',
      })
    )
  );

  // 错误隔离
  const successful = subagentResults
    .filter((r) => r.status === 'fulfilled')
    .map((r) => JSON.parse((r as any).value));

  const failed = subagentResults
    .filter((r) => r.status === 'rejected')
    .map((r) => (r as any).reason);

  console.log(`Successful batches: ${successful.length}/4`);
  console.log(`Failed batches: ${failed.length}`);

  if (failed.length > 0) {
    console.warn('Failures:', failed.map((f) => f.message));
  }

  // 生成 markdown
  const reportMd = generateMarkdownReport(successful);
  const today = new Date().toISOString().slice(0, 10);
  await fs.writeFile(`ai-visibility/${today}.md`, reportMd);

  console.log(`Report written to ai-visibility/${today}.md`);
}

function generateMarkdownReport(batchResults: any[]): string {
  let md = `# AI Visibility Report ${new Date().toISOString().slice(0, 10)}\n\n`;
  md += `## 📊 总览仪表盘\n\n`;
  
  const totalQueries = batchResults.reduce((acc, b) => acc + b.results.length, 0);
  const totalBlank = batchResults.reduce(
    (acc, b) => acc + b.results.filter((r: any) => r.webJRRank === '未出现' && !r.llmMention).length,
    0
  );
  md += `- 总 query 数: ${totalQueries}\n`;
  md += `- 完全空白: ${totalBlank}\n\n`;

  for (const batch of batchResults) {
    md += `## ${batch.batch}\n\n`;
    md += `| Query | Web JR | LLM Mention | Web Top 3 |\n`;
    md += `|---|---|---|---|\n`;
    for (const r of batch.results) {
      md += `| ${r.query} | ${r.webJRRank} | ${r.llmMention ? '✅' : '❌'} | ${r.webTop3.join(' / ')} |\n`;
    }
    md += `\n`;
  }

  return md;
}

// 跑
runWeeklyReport().catch(console.error);

跑这个 script：

bash 复制代码

$ bun run scripts/ai-visibility-weekly.ts
AI visibility routine starting 2026-05-23T09:30:00.000Z
[Sub-agent A_learning] ✓ 5 queries done (8 min)
[Sub-agent B_career] ✓ 5 queries done (9 min)
[Sub-agent C_tools] ✓ 5 queries done (10 min)  ← longest, total = 10 min
[Sub-agent D_platforms] ✓ 5 queries done (7 min)
Successful batches: 4/4
Report written to ai-visibility/2026-05-23.md

串行 : 20 query × 2 min = 40 min 并行 : max(4 batch) = 10 min Speedup: 4x

5. 3 个真实生产事故 + 完整修法代码

事故 1: 来回查同 reference doc 10 次

typescript 复制代码

// ❌ 错误：每个 sub-agent pass 50K-token doc
const LONG_REFERENCE = await fs.readFile('compliance_doc.txt');

await Promise.all(
  dimensions.map((dim) =>
    TaskTool.run({
      description: `Evaluate ${dim}`,
      prompt: `Reference doc: ${LONG_REFERENCE}\n\nEvaluate ${dim}...`,
      // 每个 sub-agent 都接收 50K reference = token 成本 10x
    })
  )
);

// ✅ 正确：主 agent 先 extract 段落，sub-agent 只接收相关部分
const allRelevantSections = await Anthropic.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 4096,
  messages: [
    {
      role: 'user',
      content: `For each dimension below, extract the most relevant section
from the reference doc (max 200 tokens per dimension):

Dimensions: ${dimensions.join(', ')}
Doc: ${LONG_REFERENCE.slice(0, 30000)}

Output JSON: { dim_name: "relevant section text", ... }`,
    },
  ],
});

const sections = JSON.parse(allRelevantSections.content[0].text);

await Promise.all(
  dimensions.map((dim) =>
    TaskTool.run({
      description: `Evaluate ${dim}`,
      prompt: `Reference section: ${sections[dim]}\n\nEvaluate ${dim}...`,
      // 每个 sub-agent 只接收 200-token 相关段落
    })
  )
);

// Token 成本下降 67%

事故 2: Promise.all 错误传播

typescript 复制代码

// ❌ 错误：1 个 timeout 整批 reject
try {
  const results = await Promise.all(items.map((i) => TaskTool.run({ ... })));
  // ↑ 如果 items[3] reject, results 全丢
} catch (e) {
  console.error('All lost:', e);
}

// ✅ 正确：Promise.allSettled 错误隔离
const settled = await Promise.allSettled(items.map((i) => TaskTool.run({ ... })));

const successes: any[] = [];
const failures: any[] = [];
const retryQueue: any[] = [];

for (let i = 0; i < settled.length; i++) {
  if (settled[i].status === 'fulfilled') {
    successes.push((settled[i] as any).value);
  } else {
    failures.push({ item: items[i], error: (settled[i] as any).reason });
    retryQueue.push(items[i]);
  }
}

console.log(`✓ ${successes.length} succeeded`);
console.log(`✗ ${failures.length} failed (added to retry queue)`);

// 后续单独 retry queue
if (retryQueue.length > 0) {
  console.log(`Retrying ${retryQueue.length} failed items in 60s...`);
  setTimeout(() => retryFailed(retryQueue), 60000);
}

事故 3: Sub-agent overhead > 任务时间

typescript 复制代码

// 计算决策表
const TASK_TIME_THRESHOLD_SEC = 5;
const SUBAGENT_OVERHEAD_SEC = 8;

function shouldUseSubagents(taskCount: number, avgTaskTimeSec: number): boolean {
  const serialTime = taskCount * avgTaskTimeSec;
  const parallelTime = SUBAGENT_OVERHEAD_SEC + avgTaskTimeSec; // max(start) + 1 task
  
  if (avgTaskTimeSec < TASK_TIME_THRESHOLD_SEC) {
    console.log(`Task < ${TASK_TIME_THRESHOLD_SEC}s, sub-agents overhead 比省的时间多, use serial`);
    return false;
  }
  
  if (parallelTime >= serialTime) {
    console.log(`Parallel time ${parallelTime}s >= serial ${serialTime}s, no speedup`);
    return false;
  }
  
  console.log(`Use sub-agents: ${serialTime}s → ${parallelTime}s (${(serialTime/parallelTime).toFixed(1)}x)`);
  return true;
}

// 应用
const tasks = await loadTasks();
const useParallel = shouldUseSubagents(tasks.length, 120); // 120s 平均/任务

if (useParallel) {
  await Promise.allSettled(tasks.map((t) => TaskTool.run({ ... })));
} else {
  for (const t of tasks) {
    await mainAgentRun(t);
  }
}

6. 6 周自学路径

yaml 复制代码

Week 1: 装 Claude Code SDK + Pattern 1 (Map-only)
Week 2: Pattern 2 + 3 (Map-Reduce + Pipeline)
Week 3: 跑第一个生产级 routine (5 sub-agent 处理 20 任务)
Week 4: 加 Promise.allSettled + retry queue
Week 5: 加 token cost monitor + 决策表
Week 6: 调 sub-agent 边界避免事故 1

学员真实数据：6 周下来生产 routine 加速 3-5x，错误隔离做对后批失败率 < 2%。

完整 omni-report 5 routine 代码 + 3 design pattern + retry queue 模板在 JR Academy GitHub omni-report。

本文作者来自匠人学院------ 澳洲项目制 AI 工程实战平台。完整代码 / 数据集 / 模板见 GitHub。

更多详情可以在JR Academy匠人学院网站查看：jiangren.com.au/