Coordinator

Coordinator 模块通过 coordinatorMode.ts 实现多 Agent 协作的核心调度逻辑。它判断当前是否处于协调器模式（isCoordinatorMode），根据会话模式（matchSessionMode）分发不同的系统提示词和用户上下文。模块支持 Scratchpad 门控、Agent 间的上下文隔离，以及主 Agent 与子 Agent 的角色区分。虽然只有一个文件，但它是多 Agent 架构的神经中枢。

职责与设计理念

职责说明

多 Agent 协调器，管理主/子 Agent 的会话模式与系统提示词

设计理念

协调即解耦——Agent 之间不直接通信，通过协调器的模式匹配间接协作。一个文件承载的不是代码量，而是架构决策的密度。

架构决策

为什么 Agent 间不直接通信？

所有 Agent 通信通过 Coordinator 中转

直接通信会形成 N×N 的连接网络，Coordinator 将其简化为 N×1 的星型拓扑。更重要的是，Coordinator 可以在中转时注入安全检查、日志记录和上下文过滤。

⚖️ Coordinator 成为单点瓶颈，但对于当前的 Agent 规模（通常 < 10 个并发），这不是问题。

为什么用模式匹配而不是继承/多态？

三态 matchSessionMode 函数式模式匹配

只有三种模式（coordinator/subAgent/standalone），用 class 继承过度设计。函数式模式匹配让每个调用点都能看到完整的分支逻辑，不需要追踪继承链。

文件清单

文件名 用途
coordinatorMode.ts 协调器核心，模式判断、系统提示词生成、上下文分发

使用场景

用户启用多 Agent 模式

isCoordinatorMode() 返回 true，主 Agent 获得协调器系统提示词

用户配置 → setMainThreadAgentType() → Coordinator 激活

主 Agent 分派子任务

Coordinator 为子 Agent 创建隔离的会话上下文，分配专用系统提示词

Coordinator → regenerateSessionId() → buildSubAgentPrompt() → 子 Agent 启动

依赖关系

  • Assistant — 会话历史管理与远程事件同步，连接本地对话与云端持久化
  • Context — 9 个 React Context Provider，管理 UI 层的全局状态分发
  • Bootstrap — 全局状态容器与会话生命周期管理，维护运行时的单一真相源

关键代码片段

会话模式匹配与分发

function isCoordinatorMode(): boolean {
  return getMainThreadAgentType() !== undefined
}

function matchSessionMode(
  sessionId: SessionId,
  handlers: {
    coordinator: () => T
    subAgent: () => T
    standalone: () => T
  }
): T {
  if (isCoordinatorMode()) return handlers.coordinator()
  if (getParentSessionId()) return handlers.subAgent()
  return handlers.standalone()
}

function getCoordinatorSystemPrompt(): string {
  // 根据模式生成不同的系统提示词
}

三态模式匹配：coordinator（主 Agent）、subAgent（子 Agent）、standalone（独立模式）

Agent 上下文隔离

// 子 Agent 只能看到分配给它的上下文切片
function getSubAgentContext(agentId: string): SubAgentContext {
  return {
    // 继承父会话的项目路径
    projectRoot: getProjectRoot(),
    // 但使用独立的会话 ID
    sessionId: regenerateSessionId({ parentSessionId: getSessionId() }),
    // 系统提示词根据角色定制
    systemPrompt: buildSubAgentPrompt(agentId),
  }
}

子 Agent 继承项目上下文但隔离会话状态，防止 Agent 间的状态污染

技术笔记

security

Agent 上下文隔离

子 Agent 无法访问父 Agent 的完整会话历史，只能看到 Coordinator 显式传递的上下文切片。这防止了敏感信息在 Agent 间泄露。

limitation

Scratchpad 门控

某些高级协调功能（如 Agent 间的 Scratchpad 共享）受特性开关控制，需要特定的订阅等级才能启用。