第 10 章 · 多 Agent 协作——一个不够就来一群

// src/agents/types.ts
 
/** 子 Agent 配置 */
interface SubAgentConfig {
  /** 子 Agent 名称，用于日志和结果追踪 */
  name: string
  /** System prompt，定义角色和行为边界 */
  role: string
  /** 允许使用的工具子集（工具名列表） */
  tools: string[]
  /** 可以用不同模型（便宜的任务用便宜的模型） */
  model?: string
  /** 最大对话轮次，防止子 Agent 跑飞 */
  maxTurns?: number
}

/** 子 Agent 执行结果 */
interface SubAgentResult {
  name: string
  success: boolean
  output: string        // 最终输出文本
  turns: number         // 消耗的对话轮次
  durationMs: number    // 执行耗时
  error?: string        // 失败时的错误信息
}

/** 工具条目：定义 + 执行函数 */
interface ToolEntry {
  definition: OpenAI.ChatCompletionTool
  execute: (params: Record<string, unknown>) => Promise<string>
}
 
/** 全局工具注册表 */
type ToolRegistry = Map<string, ToolEntry>

// src/agents/spawner.ts
 
import OpenAI from "openai"
import type { SubAgentConfig, SubAgentResult, ToolRegistry } from "./types.js"
 
const DEFAULT_MODEL = "gpt-4o-mini"
const DEFAULT_MAX_TURNS = 15
 
export class AgentSpawner {
  private openai: OpenAI
  private toolRegistry: ToolRegistry
 
  constructor(openai: OpenAI, toolRegistry: ToolRegistry) {
    this.openai = openai
    this.toolRegistry = toolRegistry
  }
 
  async spawn(config: SubAgentConfig, task: string): Promise<SubAgentResult> {
    const startTime = Date.now()
    const model = config.model ?? DEFAULT_MODEL
    const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS
 
    // 1. 从全局工具表中过滤出子 Agent 允许用的工具
    const allowedTools: OpenAI.ChatCompletionTool[] = []
    const executors = new Map<
      string,
      (params: Record<string, unknown>) => Promise<string>
    >()
 
    for (const toolName of config.tools) {
      const entry = this.toolRegistry.get(toolName)
      if (entry) {
        allowedTools.push(entry.definition)
        executors.set(toolName, entry.execute)
      }
    }
 
    // 2. 独立的消息历史 —— 上下文隔离的关键
    const messages: OpenAI.ChatCompletionMessageParam[] = [
      { role: "system", content: config.role },
      { role: "user", content: task },
    ]
 
    console.log(
      `\n[${config.name}] Started (model=${model}, tools=${config.tools.join(",")})`
    )
 
    // 3. 独立的 agent loop
    let turns = 0
    try {
      while (turns < maxTurns) {
        turns++
 
        const response = await this.openai.chat.completions.create({
          model,
          messages,
          tools: allowedTools.length > 0 ? allowedTools : undefined,
        })
 
        const msg = response.choices[0].message
        messages.push(msg)
 
        // 没有工具调用 → 子 Agent 完成
        if (!msg.tool_calls || msg.tool_calls.length === 0) {
          console.log(`[${config.name}] Completed in ${turns} turns`)
          return {
            name: config.name,
            success: true,
            output: msg.content ?? "",
            turns,
            durationMs: Date.now() - startTime,
          }
        }
 
        // 执行工具调用
        for (const call of msg.tool_calls) {
          const toolName = call.function.name
          const params = JSON.parse(call.function.arguments)
 
          // 安全检查：只执行允许的工具
          const executor = executors.get(toolName)
          if (!executor) {
            messages.push({
              role: "tool",
              tool_call_id: call.id,
              content: `Error: tool "${toolName}" is not allowed for this agent.`,
            })
            continue
          }
 
          const result = await executor(params)
          messages.push({
            role: "tool",
            tool_call_id: call.id,
            content: result,
          })
        }
      }
 
      // 超过最大轮次
      return {
        name: config.name,
        success: false,
        output: "Reached maximum turns without completing.",
        turns,
        durationMs: Date.now() - startTime,
        error: `Exceeded ${maxTurns} turns`,
      }
    } catch (err) {
      return {
        name: config.name,
        success: false,
        output: "",
        turns,
        durationMs: Date.now() - startTime,
        error: err instanceof Error ? err.message : String(err),
      }
    }
  }
}

// src/agents/roles.ts
 
import type { SubAgentConfig } from "./types.js"
 
/** Plan Agent：只读不写 */
export function planAgent(task: string): SubAgentConfig {
  return {
    name: "plan-agent",
    role: `You are a planning agent. Your job is to analyze the codebase and produce a migration plan.
 
Rules:
- You can ONLY read files and search code. You CANNOT write or execute anything.
- Output a structured plan: which files need changes, what changes, and in what order.
- Be specific. Don't say "update the routes", say "change app.get() to app.get() with Hono syntax in src/routes/users.ts lines 10-25".
 
Task: ${task}`,
    tools: ["read_file", "grep", "glob", "list_files"],
    model: "gpt-4o-mini",
    maxTurns: 10,
  }
}
 
/** Code Agent：有全部工具权限 */
export function codeAgent(name: string, task: string): SubAgentConfig {
  return {
    name,
    role: `You are a code agent. Your job is to make specific code changes.
 
Rules:
- Follow the plan exactly. Don't improvise.
- After editing, verify the change by reading the file back.
- If something doesn't work, fix it — don't leave broken code.
 
Task: ${task}`,
    tools: ["read_file", "edit_file", "bash", "grep", "glob", "list_files"],
    maxTurns: 20,
  }
}
 
/** Review Agent：只读权限 */
export function reviewAgent(focus: string): SubAgentConfig {
  return {
    name: "review-agent",
    role: `You are a code review agent. Your job is to review recent changes for correctness and consistency.
 
Rules:
- You can ONLY read files and search. You CANNOT modify anything.
- Check for: import consistency, API compatibility, missing error handling, type errors.
- Output a review report with PASS / FAIL and specific issues found.
 
Focus: ${focus}`,
    tools: ["read_file", "grep", "glob"],
    model: "gpt-4o-mini",
    maxTurns: 10,
  }
}

// src/agents/scheduler.ts
 
import type { SubAgentConfig, SubAgentResult } from "./types.js"
import type { AgentSpawner } from "./spawner.js"
 
export interface SchedulerTask {
  config: SubAgentConfig
  task: string
}
 
/** 并行运行多个子 Agent */
export async function runParallel(
  spawner: AgentSpawner,
  tasks: SchedulerTask[],
  options: { timeoutMs?: number } = {}
): Promise<SubAgentResult[]> {
  const timeoutMs = options.timeoutMs ?? 5 * 60 * 1000
 
  console.log(`\n[scheduler] Running ${tasks.length} agents in parallel...`)
  const startTime = Date.now()
 
  const promises = tasks.map(({ config, task }) => {
    return Promise.race([
      spawner.spawn(config, task),
      timeout(timeoutMs, config.name),
    ])
  })
 
  const results = await Promise.all(promises)
 
  const elapsed = Date.now() - startTime
  const succeeded = results.filter((r) => r.success).length
  console.log(
    `\n[scheduler] Done. ${succeeded}/${results.length} succeeded in ${elapsed}ms`
  )
 
  return results
}

function timeout(ms: number, name: string): Promise<SubAgentResult> {
  return new Promise((resolve) =>
    setTimeout(
      () =>
        resolve({
          name,
          success: false,
          output: "",
          turns: 0,
          durationMs: ms,
          error: `Timeout after ${ms}ms`,
        }),
      ms
    )
  )
}

/** 串行运行：前一个完成后才启动下一个 */
export async function runSequential(
  spawner: AgentSpawner,
  tasks: SchedulerTask[]
): Promise<SubAgentResult[]> {
  const results: SubAgentResult[] = []
 
  for (const { config, task } of tasks) {
    const result = await spawner.spawn(config, task)
    results.push(result)
 
    // 如果某个子 Agent 失败了，后续的可能也没意义
    if (!result.success) {
      console.log(`[scheduler] ${config.name} failed, stopping pipeline.`)
      break
    }
  }
 
  return results
}

export function summarizeResults(results: SubAgentResult[]): string {
  const lines: string[] = ["## Sub-Agent Results\n"]
 
  for (const r of results) {
    const status = r.success ? "OK" : "FAILED"
    lines.push(`### ${r.name} [${status}] (${r.turns} turns, ${r.durationMs}ms)`)
    if (r.error) lines.push(`Error: ${r.error}`)
    lines.push(r.output)
    lines.push("")
  }
 
  return lines.join("\n")
}

// src/ling.ts 中的 agent 工具定义
 
function buildAgentTool(
  spawner: AgentSpawner
): OpenAI.ChatCompletionTool {
  return {
    type: "function",
    function: {
      name: "agent",
      description: `Launch a sub-agent to handle a task independently.
The sub-agent has its own context and tools.
Available roles: plan (read-only analysis), code (full tools), review (read-only review).`,
      parameters: {
        type: "object",
        properties: {
          role: {
            type: "string",
            enum: ["plan", "code", "review"],
            description: "The role of the sub-agent",
          },
          name: {
            type: "string",
            description: "A short name for this sub-agent",
          },
          task: {
            type: "string",
            description: "The specific task for the sub-agent",
          },
        },
        required: ["role", "task"],
      },
    },
  }
}

async function executeAgentTool(
  spawner: AgentSpawner,
  params: Record<string, unknown>
): Promise<string> {
  const role = params.role as string
  const task = params.task as string
  const name = (params.name as string) || `${role}-agent`
 
  let config
  switch (role) {
    case "plan":
      config = planAgent(task)
      break
    case "code":
      config = codeAgent(name, task)
      break
    case "review":
      config = reviewAgent(task)
      break
    default:
      return `Unknown role: ${role}`
  }
 
  config.name = name
 
  const result = await spawner.spawn(config, task)
  return result.success
    ? result.output
    : `[${result.name}] Failed: ${result.error}\n${result.output}`
}

// 主循环中的工具执行
for (const call of msg.tool_calls) {
  const toolName = call.function.name
  const params = JSON.parse(call.function.arguments)
 
  let result: string
 
  if (toolName === "agent") {
    // 特殊处理：启动子 Agent
    result = await executeAgentTool(spawner, params)
  } else {
    // 普通内置工具
    const entry = toolRegistry.get(toolName)
    result = entry
      ? await entry.execute(params)
      : `Unknown tool: ${toolName}`
  }
 
  messages.push({
    role: "tool",
    tool_call_id: call.id,
    content: result,
  })
}

import {
  AgentSpawner,
  planAgent, codeAgent, reviewAgent,
  runParallel, runSequential, summarizeResults,
} from "./agents/index.js"
import type { SchedulerTask } from "./agents/index.js"
 
// 假设 toolRegistry 和 openai 已经初始化
const spawner = new AgentSpawner(openai, toolRegistry)
 
// 第一步：Plan Agent 分析
const plan = await spawner.spawn(
  planAgent("Analyze this Express app and create a migration plan to Hono"),
  "Analyze the project structure, list all Express-specific APIs used, and output a file-by-file migration plan."
)
 
console.log("=== Migration Plan ===")
console.log(plan.output)
// 输出类似：
// 1. src/routes/users.ts — app.get/post → Hono.get/post, req.query → c.req.query()
// 2. src/routes/posts.ts — app.get/post/put/delete → Hono equivalents
// 3. src/middleware/auth.ts — (req, res, next) → Hono middleware pattern
// ...共 8 个文件
 
// 第二步：3 个 Code Agent 并行改代码
const codeTasks: SchedulerTask[] = [
  {
    config: codeAgent("route-migrator", "Migrate Express routes to Hono syntax"),
    task: `Migrate these files from Express to Hono:
- src/routes/users.ts
- src/routes/posts.ts
- src/routes/auth.ts
Change app.get/post/put/delete to Hono equivalents. Update req/res to use Hono's Context (c).`,
  },
  {
    config: codeAgent("middleware-migrator", "Migrate Express middleware to Hono"),
    task: `Migrate middleware files:
- src/middleware/auth.ts
- src/middleware/cors.ts
- src/middleware/logger.ts
Convert (req, res, next) pattern to Hono's middleware pattern using c and next.`,
  },
  {
    config: codeAgent("config-migrator", "Migrate Express config to Hono"),
    task: `Migrate configuration:
- src/app.ts — replace express() with new Hono(), update middleware registration
- src/server.ts — replace app.listen() with Hono's serve()
Update package.json: remove express, add hono.`,
  },
]
 
const codeResults = await runParallel(spawner, codeTasks)
 
// 第三步：Review Agent 检查一致性
const review = await spawner.spawn(
  reviewAgent("Check the Express-to-Hono migration for consistency"),
  `Review all migrated files. Check:
1. No remaining Express imports (express, Router, Request, Response)
2. All routes use Hono's Context pattern
3. Middleware signatures are correct
4. app.ts correctly initializes Hono`
)
 
console.log("=== Review ===")
console.log(review.output)
 
// 汇总
console.log(summarizeResults([plan, ...codeResults, review]))

[plan-agent] Started (model=gpt-4o-mini, tools=read_file,grep,glob,list_files)
[plan-agent] read_file({"file_path":"src/app.ts"})
[plan-agent] grep({"pattern":"require.*express","path":"src"})
[plan-agent] Completed in 5 turns

[scheduler] Running 3 agents in parallel...
[route-migrator] Started (model=gpt-4o-mini, tools=read_file,edit_file,bash,grep,glob,list_files)
[middleware-migrator] Started (model=gpt-4o-mini, tools=read_file,edit_file,bash,grep,glob,list_files)
[config-migrator] Started (model=gpt-4o-mini, tools=read_file,edit_file,bash,grep,glob,list_files)
[config-migrator] Completed in 8 turns
[middleware-migrator] Completed in 6 turns
[route-migrator] Completed in 12 turns

[scheduler] Done. 3/3 succeeded in 34200ms

[review-agent] Started (model=gpt-4o-mini, tools=read_file,grep,glob)
[review-agent] Completed in 4 turns

# 为每个子 Agent 创建独立的工作目录
git worktree add /tmp/ling-route-migrator -b agent/route-migrator
git worktree add /tmp/ling-middleware-migrator -b agent/middleware-migrator
git worktree add /tmp/ling-config-migrator -b agent/config-migrator

import { execSync } from "node:child_process"
 
/** 创建 worktree 并返回路径 */
function createWorktree(agentName: string): string {
  const dir = `/tmp/ling-${agentName}`
  const branch = `agent/${agentName}`
  execSync(`git worktree add ${dir} -b ${branch}`, { stdio: "pipe" })
  return dir
}
 
/** 清理 worktree */
function removeWorktree(dir: string) {
  execSync(`git worktree remove ${dir} --force`, { stdio: "pipe" })
}
 
/** 合并子 Agent 的修改 */
function mergeWorktree(branch: string) {
  execSync(`git merge ${branch} --no-edit`, { stdio: "pipe" })
  execSync(`git branch -d ${branch}`, { stdio: "pipe" })
}

// Claude Code 的 Agent 定义（简化）
interface AgentDefinition {
  description: string       // 给父 Agent 看的描述
  tools: string[]           // 允许的工具
  disallowedTools?: string[] // 明确禁止的工具
  prompt: string            // system prompt
  model?: string
  maxTurns?: number
}

父 Agent → agent 工具 (id: "tool_123")
  └─ 子 Agent → read_file (parent: "tool_123")
  └─ 子 Agent → edit_file (parent: "tool_123")
  └─ 子 Agent → read_file (parent: "tool_123")