17.5 实验五：实现一个简化版多 Agent 编排系统

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-18

---

前四个实验让我们掌握了 AI 编程助手的核心组件：LLM 对话、Tool Use、MCP 扩展、Plugin 机制。但真正强大的 AI 编程助手不是一个单独的 Agent 在工作——而是多个 Agent 协作。

在第 15 章，我们深入剖析了 oh-my-opencode 的多 Agent 体系：Sisyphus 作为主编排者、Oracle 提供技术咨询、Explore 负责代码搜索、Prometheus 规划复杂任务……这种分工协作的模式极大地提升了 AI 的任务完成能力。

本节我们将从零构建一个简化版多 Agent 编排系统，模仿 oh-my-opencode 的核心架构，体验 Agent 编排的设计精髓。

17.5.1 目标

构建一个包含以下组件的多 Agent 系统：

1. Commander Agent（主编排者）：接收用户任务，决定是自己处理还是委托给子 Agent

2. Researcher Agent（研究员）：专门负责代码搜索和信息收集

3. Coder Agent（编码者）：专门负责代码编写和修改

4. Task 工具：实现 Agent 间的任务委托机制

5. 会话管理：维护每个 Agent 独立的上下文

衍生解释——什么是多 Agent 编排（Multi-Agent Orchestration）？

多 Agent 编排是指在一个系统中运行多个具有不同能力和"人格"的 AI Agent，通过某种协调机制让它们分工合作完成复杂任务。

这与单 Agent 的关键区别在于：

• 专业化分工：每个 Agent 有不同的 System Prompt、工具集和行为约束，就像团队中的不同角色

• 成本优化：简单任务交给轻量 Agent（便宜的模型），复杂任务交给强力 Agent（昂贵的模型）

• 并行处理：多个子 Agent 可以同时工作，提升效率

• 上下文隔离：每个 Agent 有独立的对话上下文，避免相互干扰

oh-my-opencode 的做法类似一个"虚拟技术团队"：Sisyphus 是技术负责人，根据任务性质分配给不同的专家。

17.5.2 架构设计

在开始编码前，让我们设计系统的整体架构：

┌─────────────────────────────────────────────┐
│                   用户输入                    │
└──────────────────────┬──────────────────────┘
                       ▼
┌─────────────────────────────────────────────┐
│            Commander Agent（主编排者）         │
│                                              │
│  System Prompt: 任务分类 + 委托决策           │
│  工具: task, read, edit, bash                │
│                                              │
│  决策逻辑:                                   │
│  ┌─────────────────────────────────┐        │
│  │ 简单问题 → 直接回答              │        │
│  │ 需要搜索 → 委托给 Researcher     │        │
│  │ 需要编码 → 委托给 Coder          │        │
│  │ 复杂任务 → 先 Researcher 再 Coder│        │
│  └─────────────────────────────────┘        │
└──────┬──────────────────────┬───────────────┘
       │                      │
       ▼                      ▼
┌──────────────┐    ┌──────────────┐
│  Researcher  │    │    Coder     │
│   Agent      │    │    Agent     │
│              │    │              │
│ 工具: read,  │    │ 工具: read,  │
│ glob, grep   │    │ edit, write, │
│              │    │ bash         │
└──────────────┘    └──────────────┘

与 oh-my-opencode 的对应关系

我们的系统	oh-my-opencode	角色
Commander	Sisyphus	主编排者，负责任务分类和委托
Researcher	Explore	代码搜索专家
Coder	Hephaestus	代码编写工匠
task 工具	delegate-task / task	Agent 间任务委托

17.5.3 实现步骤

步骤一：项目初始化与基础结构

mkdir multi-agent-orchestrator
cd multi-agent-orchestrator
bun init -y
bun add ai @ai-sdk/openai zod

创建目录结构：

multi-agent-orchestrator/
├── src/
│   ├── index.ts          # 入口文件
│   ├── agents/           # Agent 定义
│   │   ├── commander.ts
│   │   ├── researcher.ts
│   │   └── coder.ts
│   ├── tools/            # 工具实现
│   │   ├── file-tools.ts
│   │   ├── search-tools.ts
│   │   └── task-tool.ts
│   ├── session/          # 会话管理
│   │   └── manager.ts
│   └── types.ts          # 类型定义
├── package.json
└── tsconfig.json

步骤二：定义核心类型

创建 src/types.ts：

import type { CoreMessage, CoreTool } from "ai"

// Agent 定义
export interface AgentDefinition {
  name: string
  description: string
  systemPrompt: string
  tools: Record<string, CoreTool>
  model: string // 模型 ID
  maxSteps: number // 最大工具调用轮次
}

// 会话记录
export interface Session {
  id: string
  agentName: string
  messages: CoreMessage[]
  parentSessionId?: string // 关联父会话
  status: "active" | "completed" | "error"
  result?: string // 任务结果
}

// 任务委托请求
export interface TaskRequest {
  targetAgent: string
  description: string
  context?: string // 可选的上下文信息
  parentSessionId: string
}

这些类型对应了第 4 章分析的 OpenCode 数据模型：AgentDefinition 对应 Agent.Info，Session 对应 Session.Info，TaskRequest 对应 task 工具的参数。

步骤三：实现会话管理器

创建 src/session/manager.ts——管理多个 Agent 的独立会话：

import type { Session } from "../types"
import { randomUUID } from "crypto"

export class SessionManager {
  private sessions = new Map<string, Session>()

  // 创建新会话
  create(agentName: string, parentSessionId?: string): Session {
    const session: Session = {
      id: `ses_${randomUUID().slice(0, 8)}`,
      agentName,
      messages: [],
      parentSessionId,
      status: "active",
    }
    this.sessions.set(session.id, session)
    return session
  }

  // 获取会话
  get(sessionId: string): Session | undefined {
    return this.sessions.get(sessionId)
  }

  // 获取指定会话的所有子会话
  getChildren(parentSessionId: string): Session[] {
    return [...this.sessions.values()].filter(
      (s) => s.parentSessionId === parentSessionId
    )
  }

  // 完成会话
  complete(sessionId: string, result: string) {
    const session = this.sessions.get(sessionId)
    if (session) {
      session.status = "completed"
      session.result = result
    }
  }

  // 列出所有会话
  list(): Session[] {
    return [...this.sessions.values()]
  }
}

这个设计模仿了 OpenCode 中 Session 的核心概念（第 4.1 节）：

• parentSessionId：实现父子会话关联。当 Commander 委托任务给 Researcher 时，Researcher 的会话会记录 Commander 的会话 ID，形成层级关系。

• 独立的 messages 数组：每个 Agent 有自己的上下文，互不干扰。

• status 状态机：active → completed/error，对应 OpenCode 的 SessionStatus。

步骤四：定义 Agent

创建 src/agents/researcher.ts——研究员 Agent：

import type { AgentDefinition } from "../types"
import { createSearchTools } from "../tools/search-tools"

export function createResearcher(workDir: string): AgentDefinition {
  return {
    name: "researcher",
    description: "代码库搜索专家，擅长快速定位文件和代码片段",
    model: "gpt-4o-mini", // 使用便宜的模型，因为搜索任务相对简单
    maxSteps: 10,
    systemPrompt: `你是一个代码库搜索专家（Researcher）。你的职责是：

1. 高效地搜索和定位代码文件
2. 阅读并理解代码内容
3. 整理搜索结果，用结构化的方式汇报

## 行为规范

- 只使用 read、glob、grep 工具，不要修改任何文件
- 搜索结果要包含文件路径和关键代码片段
- 如果找不到相关内容，明确说明而不是猜测
- 回复要简洁、结构化，方便调用者使用

## 输出格式

搜索完成后，按以下格式汇报：
- 找到的文件列表及各自的用途
- 关键代码片段（标注行号）
- 你的分析和建议`,
    tools: createSearchTools(workDir),
  }
}

创建 src/agents/coder.ts——编码者 Agent：

import type { AgentDefinition } from "../types"
import { createFileTools } from "../tools/file-tools"

export function createCoder(workDir: string): AgentDefinition {
  return {
    name: "coder",
    description: "代码编写工匠，擅长实现功能和修复 Bug",
    model: "gpt-4o", // 使用更强的模型，因为编码需要更高的推理能力
    maxSteps: 20,
    systemPrompt: `你是一个代码编写工匠（Coder）。你的职责是：

1. 根据任务描述编写或修改代码
2. 确保代码质量——遵循项目的现有风格和最佳实践
3. 完成后简要说明所做的更改

## 行为规范

- 修改文件前先阅读现有内容
- 使用 edit 工具做精确替换，而非 write 重写整个文件
- 不要引入不必要的依赖
- 代码风格要与项目保持一致
- 完成后报告修改了哪些文件、每个文件的变更摘要

## 安全规则

- 不要执行危险命令（rm -rf、git push --force 等）
- 不要修改 .env 或包含密钥的文件
- 如果任务不清楚，宁可不做也不要猜测性地修改代码`,
    tools: createFileTools(workDir),
  }
}

创建 src/agents/commander.ts——主编排者 Agent：

import type { AgentDefinition } from "../types"
import { createFileTools } from "../tools/file-tools"
import { createSearchTools } from "../tools/search-tools"
import { createTaskTool } from "../tools/task-tool"
import type { SessionManager } from "../session/manager"

export function createCommander(
  workDir: string,
  sessionManager: SessionManager,
  executeAgent: (agentName: string, task: string, parentSessionId: string) => Promise<string>
): AgentDefinition {
  return {
    name: "commander",
    description: "主编排者，负责理解用户意图并分配任务",
    model: "gpt-4o",
    maxSteps: 30,
    systemPrompt: `你是 Commander——一个 AI 编程团队的技术负责人。你的团队有以下成员：

## 团队成员

| Agent | 擅长 | 成本 | 何时使用 |
|-------|------|------|---------|
| researcher | 代码搜索、文件定位 | 低 | 需要查找代码、理解项目结构时 |
| coder | 代码编写、Bug 修复 | 高 | 需要实际编写或修改代码时 |

## 决策流程

1. **分析用户意图**：理解用户想要什么
2. **判断复杂度**：
   - 简单问题（如解释概念）→ 直接回答，不委托
   - 需要搜索代码 → 委托给 researcher
   - 需要编写代码 → 委托给 coder
   - 复杂任务 → 先让 researcher 搜索，再让 coder 编写
3. **委托任务**：使用 task 工具委托给合适的 Agent
4. **整合结果**：汇总各 Agent 的结果，给用户完整的答复

## 委托协议

使用 task 工具时，description 要包含：
- TASK：具体任务描述
- CONTEXT：必要的背景信息
- EXPECTED_OUTCOME：期望的输出格式

## 重要原则

- 成本意识：简单搜索用 researcher（便宜），不要用 coder
- 不要同时委托多个相互依赖的任务——等前一个完成再委托下一个
- 如果子 Agent 失败了，尝试换一种方式重新委托或自己处理
- 始终给用户清晰的最终答复，不要只转发子 Agent 的原始输出`,
    tools: {
      ...createFileTools(workDir),
      ...createSearchTools(workDir),
      ...createTaskTool(sessionManager, executeAgent),
    },
  }
}

注意 Commander 的 System Prompt 设计——它模仿了 oh-my-opencode 中 Sisyphus 的核心理念（第 15.3.3 节）：

1. 意图分类：分析任务复杂度，类似 Sisyphus 的 Trivial/Explicit/Exploratory/Open-ended 分类

2. 委托协议：结构化的任务描述格式，类似 Sisyphus 的 6 段委托结构

3. 成本意识：区分哪些任务用便宜的 Agent，哪些用昂贵的 Agent

4. 错误恢复：子 Agent 失败时的兜底策略

步骤五：实现工具集

创建 src/tools/search-tools.ts：

import { z } from "zod"
import type { CoreTool } from "ai"
import * as fs from "fs"
import * as path from "path"
import { execSync } from "child_process"

export function createSearchTools(workDir: string): Record<string, CoreTool> {
  return {
    read: {
      description: "读取文件内容。返回带行号的文件内容。",
      parameters: z.object({
        file_path: z.string().describe("要读取的文件路径"),
        offset: z.number().optional().describe("起始行号（从 1 开始）"),
        limit: z.number().optional().describe("读取的行数限制"),
      }),
      execute: async (args) => {
        try {
          const fullPath = path.resolve(workDir, args.file_path)
          const content = fs.readFileSync(fullPath, "utf-8")
          const lines = content.split("\n")

          const start = (args.offset || 1) - 1
          const end = args.limit ? start + args.limit : lines.length
          const selectedLines = lines.slice(start, end)

          return selectedLines
            .map((line, i) => `${start + i + 1}\t${line}`)
            .join("\n")
        } catch (error) {
          return `Error: ${error instanceof Error ? error.message : String(error)}`
        }
      },
    },

    glob: {
      description: "使用 glob 模式搜索文件。返回匹配的文件路径列表。",
      parameters: z.object({
        pattern: z.string().describe("glob 模式，如 '**/*.ts' 或 'src/**/*.tsx'"),
      }),
      execute: async (args) => {
        try {
          const glob = new Bun.Glob(args.pattern)
          const matches: string[] = []
          for await (const file of glob.scan({ cwd: workDir })) {
            if (!file.includes("node_modules") && !file.includes(".git")) {
              matches.push(file)
            }
          }
          return matches.length > 0
            ? matches.join("\n")
            : "没有找到匹配的文件"
        } catch (error) {
          return `Error: ${error instanceof Error ? error.message : String(error)}`
        }
      },
    },

    grep: {
      description: "在文件内容中搜索正则表达式。返回匹配的文件和行。",
      parameters: z.object({
        pattern: z.string().describe("正则表达式模式"),
        include: z.string().optional().describe("文件模式过滤，如 '*.ts'"),
      }),
      execute: async (args) => {
        try {
          const includeArg = args.include ? `--include='${args.include}'` : ""
          const result = execSync(
            `grep -rn ${includeArg} '${args.pattern}' . 2>/dev/null | head -50`,
            { cwd: workDir, encoding: "utf-8", timeout: 10000 }
          )
          return result || "没有找到匹配内容"
        } catch {
          return "没有找到匹配内容"
        }
      },
    },
  }
}

创建 src/tools/file-tools.ts：

import { z } from "zod"
import type { CoreTool } from "ai"
import * as fs from "fs"
import * as path from "path"
import { execSync } from "child_process"

export function createFileTools(workDir: string): Record<string, CoreTool> {
  // 包含搜索工具的基础功能
  const searchTools = (await import("./search-tools")).createSearchTools(workDir)

  return {
    // 继承 read 工具
    read: searchTools.read,

    edit: {
      description:
        "精确替换文件中的内容。old_string 必须在文件中唯一存在。",
      parameters: z.object({
        file_path: z.string().describe("要编辑的文件路径"),
        old_string: z.string().describe("要替换的原始文本"),
        new_string: z.string().describe("替换后的新文本"),
      }),
      execute: async (args) => {
        try {
          const fullPath = path.resolve(workDir, args.file_path)
          const content = fs.readFileSync(fullPath, "utf-8")

          // 检查 old_string 是否唯一存在
          const count = content.split(args.old_string).length - 1
          if (count === 0) {
            return `Error: old_string 在文件中不存在`
          }
          if (count > 1) {
            return `Error: old_string 在文件中出现了 ${count} 次，必须唯一`
          }

          // 执行替换
          const newContent = content.replace(args.old_string, args.new_string)
          fs.writeFileSync(fullPath, newContent)
          return `已成功编辑 ${args.file_path}`
        } catch (error) {
          return `Error: ${error instanceof Error ? error.message : String(error)}`
        }
      },
    },

    write: {
      description: "将内容写入文件。如果文件已存在会被覆盖。",
      parameters: z.object({
        file_path: z.string().describe("要写入的文件路径"),
        content: z.string().describe("文件内容"),
      }),
      execute: async (args) => {
        try {
          const fullPath = path.resolve(workDir, args.file_path)
          // 确保目录存在
          fs.mkdirSync(path.dirname(fullPath), { recursive: true })
          fs.writeFileSync(fullPath, args.content)
          return `已成功写入 ${args.file_path}`
        } catch (error) {
          return `Error: ${error instanceof Error ? error.message : String(error)}`
        }
      },
    },

    bash: {
      description: "执行 Shell 命令。用于运行测试、安装依赖等操作。",
      parameters: z.object({
        command: z.string().describe("要执行的命令"),
      }),
      execute: async (args) => {
        // 安全检查：禁止危险命令
        const dangerous = ["rm -rf /", "git push --force", ":(){ :|:& };:"]
        if (dangerous.some((d) => args.command.includes(d))) {
          return "Error: 该命令被安全策略禁止"
        }

        try {
          const result = execSync(args.command, {
            cwd: workDir,
            encoding: "utf-8",
            timeout: 30000, // 30 秒超时
          })
          return result.slice(0, 10000) // 截断过长输出
        } catch (error) {
          return `命令执行失败: ${error instanceof Error ? error.message : String(error)}`
        }
      },
    },
  }
}

步骤六：实现 Task 工具（核心）

创建 src/tools/task-tool.ts——这是实现 Agent 编排的关键：

import { z } from "zod"
import type { CoreTool } from "ai"
import type { SessionManager } from "../session/manager"

export function createTaskTool(
  sessionManager: SessionManager,
  executeAgent: (agentName: string, task: string, parentSessionId: string) => Promise<string>
): Record<string, CoreTool> {
  return {
    task: {
      description: `将任务委托给专门的子 Agent 执行。可用的 Agent：
- researcher：代码搜索和信息收集专家（成本低）
- coder：代码编写和修改专家（成本高）

使用时机：当任务需要专业能力时委托，简单问题直接回答不要委托。`,
      parameters: z.object({
        agent: z.enum(["researcher", "coder"]).describe("目标 Agent 名称"),
        description: z.string().describe(
          "详细的任务描述。格式：TASK: 任务 | CONTEXT: 上下文 | EXPECTED_OUTCOME: 期望输出"
        ),
      }),
      execute: async (args) => {
        console.log(`\n📋 Commander 委托任务给 ${args.agent}:`)
        console.log(`   ${args.description.slice(0, 100)}...`)

        try {
          // 获取当前 Commander 的会话 ID
          const commanderSession = [...sessionManager.list()]
            .filter((s) => s.agentName === "commander" && s.status === "active")
            .pop()

          const parentId = commanderSession?.id || "root"

          // 执行子 Agent
          const result = await executeAgent(args.agent, args.description, parentId)

          console.log(`✅ ${args.agent} 完成任务`)
          return `[${args.agent} 的执行结果]\n\n${result}`
        } catch (error) {
          console.log(`❌ ${args.agent} 执行失败`)
          return `[${args.agent} 执行失败] ${error instanceof Error ? error.message : String(error)}`
        }
      },
    },
  }
}

这个 task 工具的设计直接对应了 OpenCode 中 tool/task.ts 的核心思想（第 5.3.5 节）：

• 创建子会话：通过 sessionManager.create() 为子 Agent 创建独立的会话

• Agent 权限过滤：通过 z.enum(["researcher", "coder"]) 限制可委托的目标

• 结果回传：子 Agent 的执行结果作为 task 工具的返回值，回到 Commander 的上下文中

步骤七：实现核心执行引擎

创建 src/index.ts——把所有组件组装在一起：

import { streamText } from "ai"
import { openai } from "@ai-sdk/openai"
import { createInterface } from "readline"
import { SessionManager } from "./session/manager"
import { createCommander } from "./agents/commander"
import { createResearcher } from "./agents/researcher"
import { createCoder } from "./agents/coder"
import type { AgentDefinition, Session } from "./types"
import type { CoreMessage } from "ai"

// ===== 全局状态 =====
const sessionManager = new SessionManager()
const workDir = process.cwd()

// ===== Agent 执行引擎 =====
async function executeAgent(
  agentName: string,
  task: string,
  parentSessionId: string
): Promise<string> {
  // 查找 Agent 定义
  const agent = agents[agentName]
  if (!agent) {
    throw new Error(`未知的 Agent: ${agentName}`)
  }

  // 创建子会话
  const session = sessionManager.create(agentName, parentSessionId)
  console.log(`\n🔄 [${agentName}] 开始执行 (session: ${session.id})`)

  // 初始化消息
  session.messages = [
    { role: "user", content: task },
  ]

  // Agentic Loop：持续调用 LLM 直到没有工具调用
  let steps = 0
  let finalText = ""

  while (steps < agent.maxSteps) {
    steps++

    const result = await streamText({
      model: openai(agent.model),
      system: agent.systemPrompt,
      messages: session.messages,
      tools: agent.tools,
      maxSteps: 1, // 每次只执行一步，我们手动控制循环
    })

    // 收集完整响应
    let text = ""
    const toolCalls: any[] = []
    const toolResults: any[] = []

    for await (const part of result.fullStream) {
      if (part.type === "text-delta") {
        text += part.textDelta
      }
      if (part.type === "tool-call") {
        toolCalls.push(part)
      }
      if (part.type === "tool-result") {
        toolResults.push(part)
      }
    }

    // 更新会话消息
    if (text) {
      session.messages.push({ role: "assistant", content: text })
      finalText = text
    }

    // 如果没有工具调用，Agent 完成了任务
    if (toolCalls.length === 0) {
      break
    }

    // 将工具调用和结果添加到消息历史
    session.messages.push({
      role: "assistant",
      content: toolCalls.map((tc) => ({
        type: "tool-call" as const,
        toolCallId: tc.toolCallId,
        toolName: tc.toolName,
        args: tc.args,
      })),
    })

    session.messages.push({
      role: "tool",
      content: toolResults.map((tr) => ({
        type: "tool-result" as const,
        toolCallId: tr.toolCallId,
        toolName: tr.toolName,
        result: tr.result,
      })),
    })

    console.log(
      `   [${agentName}] 步骤 ${steps}: 调用了 ${toolCalls.map((t) => t.toolName).join(", ")}`
    )
  }

  // 完成会话
  sessionManager.complete(session.id, finalText)
  console.log(`✅ [${agentName}] 完成 (${steps} 步)`)
  return finalText
}

// ===== Agent 注册表 =====
const agents: Record<string, AgentDefinition> = {}

function registerAgents() {
  const researcher = createResearcher(workDir)
  const coder = createCoder(workDir)
  const commander = createCommander(workDir, sessionManager, executeAgent)

  agents[researcher.name] = researcher
  agents[coder.name] = coder
  agents[commander.name] = commander
}

// ===== 主交互循环 =====
async function main() {
  registerAgents()
  const commanderSession = sessionManager.create("commander")

  console.log("🤖 多 Agent 编排系统已启动")
  console.log("   Commander（主编排者）已就绪")
  console.log("   可用的子 Agent：researcher, coder")
  console.log("   输入 /sessions 查看会话状态")
  console.log("   输入 /quit 退出\n")

  const rl = createInterface({
    input: process.stdin,
    output: process.stdout,
  })

  const prompt = () => {
    rl.question("你> ", async (input) => {
      const trimmed = input.trim()

      if (!trimmed) {
        prompt()
        return
      }

      // 内置命令
      if (trimmed === "/quit") {
        console.log("再见！")
        rl.close()
        return
      }

      if (trimmed === "/sessions") {
        const sessions = sessionManager.list()
        console.log("\n📊 会话列表:")
        for (const s of sessions) {
          console.log(
            `   ${s.id} | ${s.agentName} | ${s.status} | 消息数: ${s.messages.length} | 父: ${s.parentSessionId || "无"}`
          )
        }
        console.log()
        prompt()
        return
      }

      // 发送给 Commander Agent
      try {
        commanderSession.messages.push({ role: "user", content: trimmed })

        const commander = agents["commander"]
        let steps = 0
        let lastText = ""

        // Commander 的 Agentic Loop
        while (steps < commander.maxSteps) {
          steps++

          const result = await streamText({
            model: openai(commander.model),
            system: commander.systemPrompt,
            messages: commanderSession.messages,
            tools: commander.tools,
            maxSteps: 1,
          })

          let text = ""
          const toolCalls: any[] = []
          const toolResults: any[] = []

          // 流式输出 Commander 的文本响应
          for await (const part of result.fullStream) {
            if (part.type === "text-delta") {
              process.stdout.write(part.textDelta)
              text += part.textDelta
            }
            if (part.type === "tool-call") {
              toolCalls.push(part)
            }
            if (part.type === "tool-result") {
              toolResults.push(part)
            }
          }

          if (text) {
            commanderSession.messages.push({
              role: "assistant",
              content: text,
            })
            lastText = text
          }

          if (toolCalls.length === 0) break

          // 添加工具调用历史
          commanderSession.messages.push({
            role: "assistant",
            content: toolCalls.map((tc) => ({
              type: "tool-call" as const,
              toolCallId: tc.toolCallId,
              toolName: tc.toolName,
              args: tc.args,
            })),
          })

          commanderSession.messages.push({
            role: "tool",
            content: toolResults.map((tr) => ({
              type: "tool-result" as const,
              toolCallId: tr.toolCallId,
              toolName: tr.toolName,
              result: tr.result,
            })),
          })
        }

        console.log("\n")
      } catch (error) {
        console.error(
          "❌ 错误:",
          error instanceof Error ? error.message : String(error)
        )
      }

      prompt()
    })
  }

  prompt()
}

main().catch(console.error)

步骤八：运行与测试

# 设置 API Key
export OPENAI_API_KEY="your-key-here"

# 运行
bun run src/index.ts

测试场景：

你> 帮我看看这个项目的目录结构和主要文件

🔄 [researcher] 开始执行 (session: ses_a1b2c3)
   [researcher] 步骤 1: 调用了 glob
   [researcher] 步骤 2: 调用了 read
✅ [researcher] 完成 (3 步)

Commander: 根据 Researcher 的分析，这个项目的结构如下...

你> 在 src/utils/ 下创建一个 format-date.ts 文件，实现日期格式化函数

🔄 [coder] 开始执行 (session: ses_d4e5f6)
   [coder] 步骤 1: 调用了 write
✅ [coder] 完成 (1 步)

Commander: Coder 已经创建了 src/utils/format-date.ts...

你> /sessions
📊 会话列表:
   ses_main01 | commander | active | 消息数: 8 | 父: 无
   ses_a1b2c3 | researcher | completed | 消息数: 6 | 父: ses_main01
   ses_d4e5f6 | coder | completed | 消息数: 4 | 父: ses_main01

17.5.4 进阶：添加并行任务执行

oh-my-opencode 的后台 Agent 系统（第 15.6.1 节）支持并行执行多个子 Agent。让我们为系统添加这个能力：

// src/tools/task-tool.ts 中增加 parallel_tasks 工具

parallel_tasks: {
  description: "并行执行多个子 Agent 任务。所有任务同时启动，等待全部完成后返回结果。",
  parameters: z.object({
    tasks: z.array(z.object({
      agent: z.enum(["researcher", "coder"]),
      description: z.string(),
    })).describe("要并行执行的任务列表"),
  }),
  execute: async (args) => {
    console.log(`\n🔀 并行执行 ${args.tasks.length} 个任务...`)

    const commanderSession = [...sessionManager.list()]
      .filter((s) => s.agentName === "commander" && s.status === "active")
      .pop()
    const parentId = commanderSession?.id || "root"

    // 并行执行所有任务
    const results = await Promise.allSettled(
      args.tasks.map((task, i) =>
        executeAgent(task.agent, task.description, parentId)
          .then((result) => ({ index: i, agent: task.agent, result }))
      )
    )

    // 整理结果
    const output = results.map((r, i) => {
      if (r.status === "fulfilled") {
        return `### 任务 ${i + 1} (${r.value.agent}) — 成功\n${r.value.result}`
      } else {
        return `### 任务 ${i + 1} (${args.tasks[i].agent}) — 失败\n${r.reason}`
      }
    })

    return output.join("\n\n---\n\n")
  },
},

使用 Promise.allSettled 而非 Promise.all，这样即使某个子 Agent 失败，其他任务也能正常完成——这正是 oh-my-opencode 的防御式编程理念。

17.5.5 进阶：Doom Loop 检测

回顾第 4.4.2 节分析的 Doom Loop 检测机制——当 Agent 反复调用同一个工具得到相同结果时，说明它陷入了死循环。让我们添加这个保护：

// 在 executeAgent 函数中添加 Doom Loop 检测

const DOOM_LOOP_THRESHOLD = 3
const recentToolCalls: string[] = []

// 在每次工具调用后检查
const callSignature = `${toolCall.toolName}:${JSON.stringify(toolCall.args)}`
recentToolCalls.push(callSignature)

// 检查最近的调用是否重复
if (recentToolCalls.length >= DOOM_LOOP_THRESHOLD) {
  const recent = recentToolCalls.slice(-DOOM_LOOP_THRESHOLD)
  const allSame = recent.every((c) => c === recent[0])

  if (allSame) {
    console.log(`⚠️ [${agentName}] 检测到 Doom Loop，强制结束`)
    session.messages.push({
      role: "user",
      content:
        "你似乎在重复相同的操作。请停下来，总结你目前了解的信息，" +
        "直接用文字回复。不要再调用工具。",
    })
    // 不 break，让 Agent 有机会响应
  }
}

17.5.6 知识点总结

通过这个实验，我们实现了一个包含以下核心机制的多 Agent 系统：

知识点	对应章节	实现方式
Agent 定义与 Prompt 工程	第 6 章 Agent 系统	AgentDefinition + 精心设计的 System Prompt
会话管理与上下文隔离	第 4 章 Session 系统	SessionManager + 父子会话关联
Task 工具与任务委托	第 5.3.5 节 task 工具	task 工具 + executeAgent()
Agentic Loop	第 4.4 节 SessionProcessor	while 循环 + 工具调用检测
Doom Loop 检测	第 4.4.2 节	重复调用签名检查
并行执行	第 15.6.1 节后台 Agent	Promise.allSettled()
防御式编程	第 15.5 节 Hook 系统	错误恢复、超时保护、安全检查

从这个实验到生产级产品的差距：

我们的简化版系统虽然展示了核心概念，但与 OpenCode + oh-my-opencode 的生产级实现相比，还缺少：

1. 持久化存储：我们的会话存在内存中，退出即丢失。OpenCode 使用文件存储（第 10 章）

2. 流式 UI：我们只有简单的 console.log。OpenCode 有完整的 TUI（第 12 章）

3. 权限系统：我们的安全检查是硬编码的。OpenCode 有完整的权限评估引擎（第 9 章）

4. Snapshot 回滚：我们没有文件变更快照。OpenCode 可以撤销所有修改（第 10.1 节）

5. 上下文压缩：我们没有 Compaction。长对话会超出 Token 限制（第 4.5 节）

6. 53 个 Hook：oh-my-opencode 的 Hook 系统提供了极其精细的行为控制

但核心思想是一样的：通过 Agent 分工 + 工具系统 + 会话管理，构建一个能够自主完成复杂编程任务的 AI 系统。理解了这些核心概念，你就具备了从零构建类似系统的基础。