open-multi-agent-orchestration

Open Multi-Agent Orchestration 是一个面向 TypeScript 开发者的技能，主题是使用 open-multi-agent 框架构建生产级多智能体 AI 团队。该框架让具有不同角色、模型和工具的智能体围绕复杂目标协作，并处理任务依赖解析（DAG 调度）、并行执行、共享内存以及智能体间通信，全部在同一进程内完成，没有子进程开销。

安装与环境变量

npm install @jackchen_me/open-multi-agent
# 或
pnpm add @jackchen_me/open-multi-agent

设置环境变量：

export ANTHROPIC_API_KEY=your_key_here
export OPENAI_API_KEY=your_key_here   # 可选，仅在使用 OpenAI 模型时需要

核心概念

OpenMultiAgent：顶层编排器，所有操作的入口点。
Team：一组具名智能体，共享消息总线、任务队列以及可选的共享内存。
AgentConfig：定义智能体的名称、模型、供应商、系统提示以及允许使用的工具。
Task：一个工作单元，包含标题、描述、负责人以及可选的 dependsOn 依赖列表。
LLMAdapter：可插拔接口，内置 Anthropic 与 OpenAI 适配器。
ToolRegistry：可用工具的注册表；内置工具加上通过 defineTool() 定义的自定义工具。

使用方式

单智能体快速开始：创建 OpenMultiAgent 实例并调用 runAgent()，传入 AgentConfig 与任务提示，返回结果中的 output 即输出。

多智能体团队：为每个角色定义 AgentConfig（如 architect、developer、reviewer），通过 createTeam() 创建团队并开启 sharedMemory，再用 runTeam() 运行团队任务，结果包含 success 与 totalTokenUsage.output_tokens 等字段。可在 OpenMultiAgent 选项中传入 onProgress 回调以接收进度事件。

任务流水线（显式 DAG 控制）：使用 runTasks() 可精确控制任务顺序、分配与并行度。每个任务可带 dependsOn 列表；没有未解决依赖的任务会自动并行执行。框架会级联处理失败——某任务失败时，依赖它的任务会被跳过。

多模型团队：在 AgentConfig 中用 provider 指定 'anthropic' 或 'openai'，即可在同一团队中混用 Claude 与 GPT 等模型，共享内存共同协作。

自定义工具：使用 defineTool() 配合 Zod schema 定义工具的名称、描述、inputSchema 与 execute 函数；再通过 ToolRegistry 注册（registerBuiltInTools() 注册内置工具，registry.register() 注册自定义工具），并配合 ToolExecutor 与 Agent 使用。

流式输出：Agent 提供 stream() 方法，可异步迭代事件，对 event.type === 'text' 的事件写出文本。

进度监控：通过 onProgress 回调监听 task:start、task:complete、task:failed、agent:thinking、agent:tool_use 等事件类型。

内置工具

bash：选项 command、timeout、cwd；返回 stdout 与 stderr。
file_read：选项 path、offset、limit；读取大文件时可用 offset/limit。
file_write：选项 path、content；会自动创建父目录。
file_edit：选项 path、old_string、new_string；精确字符串匹配替换。
grep：选项 pattern、path、flags；有 ripgrep 时使用 ripgrep，否则回退到 Node.js。

AgentConfig 选项

interface AgentConfig {
  name: string                    // 团队内唯一
  model: string                   // 例如 'claude-sonnet-4-6'、'gpt-5.4'
  provider?: 'anthropic' | 'openai'  // 省略时根据模型名推断
  systemPrompt?: string           // 智能体的角色与指令
  tools?: string[]                // 智能体可使用的工具名称
  maxTurns?: number               // 最大对话轮数（默认：不限制）
}

自定义 LLM 适配器

实现 LLMAdapter 的 chat() 与 stream() 两个方法即可接入任意 LLM 供应商。资料给出了 Ollama 适配器示例，通过 fetch 调用 http://localhost:11434/api/chat。

常见模式

研究 → 写作 → 评审流水线：在 content-team 中配置 researcher、writer、editor 三个智能体，开启 sharedMemory，并用 runTasks() 定义“Research topic”“Write article”“Edit article”三个任务，每个任务依赖前一个，从而形成顺序流水线。

扇出后合并：让多个 dev 智能体并行构建各自模块，再由 architect 智能体在依赖这三个模块的任务中完成集成。

故障排查

ANTHROPIC_API_KEY not found：确保运行脚本的 shell 中已导出该环境变量，或在导入框架前用 dotenv 之类的加载器读取 .env。
任务未并行运行：检查任务之间是否存在循环 dependsOn 链；只有所有依赖都已解决的任务才会进入待并行执行状态。
智能体超出 token 限制：在 AgentConfig 上设置 maxTurns 限制对话长度；大文件操作使用带 offset/limit 的 file_read，而不要整文件读取。
Tool not found 错误：确保 AgentConfig.tools[] 中的工具名与 ToolRegistry 中注册的名称完全一致；内置工具通过 registerBuiltInTools(registry) 注册。
OpenAI 适配器未初始化：任何智能体使用 provider: 'openai' 时必须设置 OPENAI_API_KEY；适配器采用延迟初始化，但首次使用若缺少该 key 会抛错。
defineTool 类型错误：确保 zod 作为直接依赖安装（npm install zod）——框架使用 Zod 做 schema 校验，但不重新导出它。

适用场景与限制

该框架适用于需要多角色协作、任务存在先后依赖或并行分支的复杂 AI 工作流，例如多模型混用的软件开发流水线、内容研究写作评审流程、模块化并行构建后集成等。框架本身为 TypeScript，需 Node.js 环境，且依赖相应 LLM 的 API key；资料未提供框架的开源许可、定价、版本号与性能基准等信息，暂未提供。