在 AI 工具内运行 agency-orchestrator…

用户提供 .yaml 工作流或要求多角色协作，且已安装 agency-agents-zh 时，可在 Claude Code/OpenClaw/Cursor 当前会话中直接编排执行。

适用场景

解决思路

1. 用 Read 工具读取用户指定的 YAML 文件，提取 name、agents_dir、inputs、steps 字段。
2. 忽略 YAML 中的 llm、concurrency、timeout、retry 配置；Skill 模式使用当前会话的 LLM，这些字段仅用于 CLI 模式。
3. 用 Bash test -d 按以下顺序检查并定位角色目录，使用第一个存在的：1）当前工作目录下的 {agents_dir}/，如 ./agency-agents-zh/；2）../{agents_dir}/；3）相对于 YAML 文件所在目录的 {agents_dir}/；4）node_modules/agency-agents-zh/。
4. 如果全部找不到角色目录，停止执行并提示用户安装：git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git 或 npm install agency-agents-zh。
5. 对每个 required: true 的输入，检查用户消息中是否已提供值。
6. 未提供的必填输入立即向用户询问，不要猜测或用空值。
7. 有 default 的可选输入使用默认值；无 default 的可选输入设为空字符串。
8. 根据 depends_on 进行拓扑排序，将步骤分成多个层级：无 depends_on 的步骤归入第 1 层；depends_on 全部在第 N 层或之前的步骤归入第 N+1 层；同一层内步骤互不依赖，可并行。
9. 在回复中展示执行计划，格式为：执行计划（共 N 步）：第 1 层: [step_id] — 角色名；第 2 层: [step_a, step_b] — 并行；第 3 层: [step_id] — 角色名。
10. 对每一层执行前，用 Read 工具读取该层所有步骤的角色 .md 文件：{角色目录}/{role}.md。
11. 从角色 .md 文件中提取：frontmatter 中的 name 字段作为角色名；第二个 --- 之后的全部 markdown 内容作为角色 system prompt。
12. 渲染 task 模板：将 task 中的 {{变量名}} 替换为来自 inputs 的用户输入值，或来自前序步骤 output 的结果文本。
13. 单步骤层直接在主会话中扮演该角色执行，格式为：### Step N/Total: step_id（角色名），然后以该角色身份完成 task，使用角色的专业知识和沟通风格。
14. 多步骤层并行时，使用 Agent 工具为每个步骤启动子代理；每个子代理的 prompt 必须包含：角色文件的完整文本内容（不是路径，因为子代理可能无法读文件）、渲染后的 task 文本、指令：以上是你的角色定义，请以该角色身份完成以下任务，直接输出结果。
15. 如果 step 有 output 字段，将该步骤的输出文本存入变量上下文，供后续步骤的 {{变量}} 使用。
16. 用 Write 工具将结果保存到 .ao-output/{工作流名称}-{YYYY-MM-DD}/，目录包含：steps/ 下每步输出 1-{step_id}.md、2-{step_id}.md 等；summary.md 保存最后一步的完整输出作为最终成果；metadata.json 保存基本元数据。
17. metadata.json 格式为：包含 name、date、success、steps 数组；steps 数组中每项包含 id、role、status。
18. 执行完毕后向用户展示：最终成果（summary.md 的内容）、文件保存位置、执行了几个步骤。
19. 遵守硬性规则：每个步骤都必须真正扮演对应角色，使用该角色的专业知识和沟通风格，不能泛泛回答。
20. 遵守硬性规则：角色切换必须明确，每步开始时标注角色名。
21. 遵守硬性规则：不要跳过步骤或合并步骤，严格按 DAG 层级顺序执行。
22. 遵守硬性规则：如果角色文件找不到，告知用户并建议安装 agency-agents-zh。
23. 遵守硬性规则：不要在没有读取角色 .md 文件的情况下执行步骤，必须先 Read 再执行。
24. 没有 YAML 文件时启用快捷模式：如果用户没有指定 YAML 文件，但描述了需要多角色协作的任务，则根据用户描述自动生成 YAML 工作流定义。
25. 生成 YAML 工作流定义后，展示给用户确认。
26. 用户确认后，按上述完整流程执行。
27. 故障处理：角色文件不存在时，提示用户运行 ao init 或 npm install agency-agents-zh。
28. 故障处理：模板变量未定义时，检查上下文；如果是必填输入则向用户询问。
29. 故障处理：步骤执行失败时，标记该步骤为失败，跳过所有依赖它的下游步骤，继续执行其他独立步骤。

适用边界 · 注意事项

• 未安装 agency-agents-zh 且无法安装时，缺少角色定义目录，无法按角色执行。
• 需要 llm、concurrency、timeout、retry 等 CLI 专属配置控制时，Skill 模式会忽略这些字段，应改用 CLI 模式。
• 当前 AI 工具不支持 Read/Write/Bash/Agent 工具，或无法在主会话与子代理中切换角色时，无法完整执行该流程。