1. 项目概述Agency-Orchestrator 是什么Agency-Orchestrator简称 AO是一个基于 Node.js 开发的开源多智能体协作框架它能让用户通过自然语言指令自动调度多个专业 AI 角色协同完成复杂任务。与传统的单 AI 对话模式不同AO 内置了 216 个细分领域的专家角色涵盖技术、产品、运营、财务等方向当用户提出需求时系统会自动匹配相关专家组成虚拟团队按照预设的工作流并行执行任务最终输出结构化解决方案。这个工具最核心的价值在于零配置启动支持 7 种免 API Key 的运行方式如 Claude Code、Gemini CLI 等已有相关服务的用户安装即可使用智能任务分解自动将模糊需求拆解为可执行步骤构建有向无环图DAG实现步骤间依赖管理和并行执行中文场景优化角色库包含 50 针对中国市场的本地化角色如小红书运营、抖音内容策划等可视化交互提供网页版 Studio 和桌面客户端支持拖拽式工作流编辑和实时执行监控2. 核心架构解析2.1 技术栈组成AO 的技术实现主要包含以下关键组件编排引擎基于 TypeScript 开发的 DAG 调度核心负责解析 YAML 工作流、管理步骤状态、处理错误重试等角色库系统216 个中文角色agency-agents-zh和 184 个英文角色agency-agents每个角色包含# 示例产品经理角色定义 name: 产品经理 system_prompt: 你是有5年经验的互联网产品专家擅长需求分析、PRD撰写和跨部门协调。 你的输出必须包含用户故事地图、核心功能列表、数据埋点方案。 constraints: - 拒绝讨论与产品规划无关的话题 - 所有建议必须给出实施优先级连接器体系支持 10 类大模型接入方式包括CLI 模式Claude Code/Gemini CLI 等已安装的客户端API 模式DeepSeek/OpenAI 等本地模型Ollama2.2 工作流执行原理典型的工作流执行过程分为四个阶段需求解析通过自然语言处理NLP识别用户意图的关键要素角色匹配使用向量相似度算法从角色库中筛选相关专家DAG 生成根据任务依赖关系自动构建执行流程图并行执行引擎管理各步骤的状态流转典型流程如下用户输入 → 解析需求 → 匹配角色 → 生成DAG → 并行执行 → 结果汇总 ↑____________错误处理/重试___________↓3. 安装与配置指南3.1 环境准备最低系统要求Node.js v22.13 或更高版本npm 9.x磁盘空间 500MB含角色库推荐通过 nvm 管理 Node 版本# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 安装 Node.js nvm install 22 nvm use 223.2 安装方式对比方式命令适用场景注意事项CLInpm i -g agency-orchestrator开发者/自动化场景需手动配置环境变量桌面端官网下载安装包非技术用户自带 Node 运行时Dockerdocker pull jnmetacode/ao生产环境部署需挂载数据卷持久化提示Windows 用户建议使用桌面端避免 PATH 配置问题Mac/Linux 开发者推荐 CLI 方式3.3 模型接入配置以常用的 DeepSeek 为例获取 API Key 后设置环境变量export DEEPSEEK_API_KEYsk-your-key-here验证连接ao run workflows/dev/pr-review.yaml --provider deepseek免 Key 方案推荐配置# 使用已安装的 Claude Code npm install -g anthropic-ai/claude-code ao compose 需求分析 --provider claude-code4. 核心功能实战4.1 智能编排Compose最核心的功能是通过自然语言自动生成工作流ao compose 作为创业者我需要一个AI教育项目的商业计划书 --run系统会自动匹配「市场分析师」「产品经理」「财务规划师」等角色生成包含 6 个步骤的 YAML 工作流并行执行并输出 Markdown 格式的方案典型输出结构ao-output/商业计划书-2026-03-25/ ├── summary.md # 整合报告 ├── steps/ │ ├── 1-市场分析.md │ ├── 2-产品设计.md │ └── 3-财务模型.md └── metadata.json # 执行元数据4.2 团队协作模式对于固定场景可以保存角色阵容复用# 保存技术评审团队 ao team save workflows/dev/tech-review.yaml --name tech-team # 用同一组专家处理新需求 ao run --team tech-team 请评审我们的微服务架构设计4.3 可视化编辑启动网页版 Studioao web主要功能界面角色面板按领域筛选专家查看角色详情画布编辑器拖拽方式构建工作流支持节点依赖连线条件分支设置循环控制配置执行监控实时显示各步骤状态和 Token 消耗5. 高级技巧与优化5.1 性能调优当处理复杂工作流时建议调整并发数默认 2concurrency: 4 # 根据模型配额调整设置步骤级模型覆盖steps: - id: coding role: engineering/backend-engineer llm: provider: claude-code # 关键步骤使用更强模型5.2 错误处理机制系统内置三种容错策略指数退避重试网络错误时自动延迟重试备用模型切换主模型失败时自动尝试备用供应商人工干预节点在 YAML 中配置审批步骤- id: approval type: approval prompt: 请确认财务模型是否合理5.3 提示词工程通过技能(Skill)注入方法论steps: - id: review role: engineering/security-engineer skills: [owasp-top10] # 应用OWASP检查清单 task: 审计这段代码的安全风险查看内置技能ao skills list6. 典型应用场景6.1 技术团队场景需求推荐工作流预期产出PR 代码审查workflows/dev/pr-review.yaml安全/性能/可维护性三维度报告技术方案评审workflows/dev/tech-design.yaml架构图风险评估实施建议事故复盘workflows/ops/postmortem.yaml时间线/根因/改进措施6.2 业务场景# 小红书内容运营 ao run workflows/marketing/xiaohongshu.yaml \ -i product智能咖啡机 \ -i budget5000 # 商业计划书生成 ao compose 10万元启动AI编程教育项目 --run7. 常见问题排查7.1 安装问题症状Error: Node.js version mismatch解决方案nvm install 22 nvm use 22 npm rebuild症状桌面端启动失败排查步骤检查日志文件~/Library/Logs/agency-orchestrator/main.log(Mac)重置配置删除~/Library/Application Support/agency-orchestrator7.2 执行异常症状步骤卡在Running状态调试方法# 查看详细日志 AO_LOG_LEVELdebug ao run workflow.yaml # 跳过失败步骤 ao run --resume last --from next_step症状输出质量不稳定优化建议为关键步骤添加验收标准- id: analysis acceptance: 必须包含3个以上数据来源使用更稳定的模型组合8. 生态整合8.1 与开发工具链集成在 VS Code 中配置{ tasks: { type: shell, command: ao run workflows/pr-review.yaml -i code${file} } }8.2 CI/CD 流水线示例GitHub Actions 配置片段- name: Run AI Review run: | ao run workflows/dev/pr-review.yaml \ -i code$(git diff --cached) \ --output reports/ env: DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_KEY }}9. 安全与合规项目设计中的关键安全措施数据本地化所有执行记录默认存储在用户本地密钥管理API Key 只存在于内存不写入持久化存储内容过滤通过 shellward 中间件进行注入检测企业级部署建议# 使用隔离环境 docker run -it --rm \ -v ./ao-data:/data \ -e AO_HOME/data \ jnmetacode/ao