Agent Orchestrator（智能体编排器） 是做什么的？
概述
元技能，用于编排生态系统中所有智能体。自动扫描技能、按能力匹配、协调多技能工作流并管理注册表。
何时使用此技能
- 需要此领域的专业协助时
不要使用此技能的情况
- 任务与智能体编排器无关
- 有更简单、更具体的工具可以处理请求
- 用户需要通用协助，无需领域专业知识
工作原理
元技能，充当整个技能生态系统的中央决策与协调层。自动扫描、识别相关智能体，并编排多个技能来处理复杂任务。
原则：零人工干预
- 始终扫描，在处理任何请求之前
- 新技能通过在任意子文件夹中创建
SKILL.md实现自动检测并包含 - 移除的技能会自动从注册表中排除
- 无需手动命令注册新技能
强制工作流（每次请求）
在处理用户的任何请求之前，请执行以下步骤。 脚本会自动使用相对路径，可从任何目录运行。
步骤1：自动发现（扫描）
python agent-orchestrator/scripts/scan_registry.py
通过 MD5 哈希缓存实现超快速扫描（<100ms）。仅重新处理已更改的文件。 返回包含所有已找到技能摘要的 JSON。
步骤2：技能匹配
python agent-orchestrator/scripts/match_skills.py "<用户请求>"
返回按相关性排序的技能 JSON。解释结果：
| 结果 | 操作 |
|---|---|
matched: 0 | 无相关技能。正常操作，不使用技能。 |
matched: 1 | 一个相关技能。加载其 SKILL.md 并遵循。 |
matched: 2+ | 多个技能。执行步骤3（编排）。 |
步骤3：编排（如果匹配数 >= 2）
python agent-orchestrator/scripts/orchestrate.py --skills skill1,skill2 --query "<请求>"
返回包含模式、步骤顺序以及技能间数据流的执行计划。
快速步骤（捷径）
对于简单查询，步骤1+2可以按顺序组合：
python agent-orchestrator/scripts/scan_registry.py && python agent-orchestrator/scripts/match_skills.py "<请求>"
技能注册表
注册表位于：
agent-orchestrator/data/registry.json
搜索位置
扫描器在以下位置查找 SKILL.md：
.claude/skills/*/（在 Claude Code 中注册的技能）*/（顶层独立技能）*/*（子文件夹中的技能，深度最多3层）
每个技能的元数据
注册表中的每条记录包含：
| 字段 | 描述 |
|---|---|
| name | 技能名称（来自 YAML 前置元数据） |
| description | 完整描述（包括触发条件） |
| location | 目录的绝对路径 |
| skill_md | SKILL.md 的绝对路径 |
| registered | 是否在 .claude/skills/ 中（true/false） |
| capabilities | 能力标签（自动提取 + 显式指定） |
| triggers | 从描述中提取的激活关键词 |
| language | 主要语言（python/nodejs/bash/none） |
| status | active / incomplete / missing |
注册表命令
## 快速扫描（使用哈希缓存）
python agent-orchestrator/scripts/scan_registry.py
## 详细状态表
python agent-orchestrator/scripts/scan_registry.py --status
## 完全重新扫描（忽略缓存）
python agent-orchestrator/scripts/scan_registry.py --force
匹配算法
对于每个请求，匹配器根据以下标准对技能进行评分：
| 标准 | 分数 | 示例 |
|---|---|---|
| 查询中包含技能名称 | +15 | "使用 web-scraper" -> web-scraper |
| 精确关键词触发词 | +10 | "scrape" -> web-scraper |
| 能力类别 | +5 | data-extraction -> web-scraper |
| 词语重叠 | +1 | 查询中的词语出现在描述中 |
| 项目提升 | +20 | 技能已分配给活动项目 |
最低阈值：5分。低于此分数的技能将被忽略。
带项目的匹配
python agent-orchestrator/scripts/match_skills.py --project my-project "query here"
分配给项目的技能会自动获得 +20 的提升。
编排模式
当多个技能相关时，编排器会分类模式：
1. 顺序流水线
技能形成一条链，一个的输出作为下一个的输入。
适用情况： "生产者"技能（数据提取、政府数据）与"消费者"技能（消息、社交媒体）混合。
示例： web-scraper 收集价格 -> whatsapp-cloud-api 发送警报
user_query -> web-scraper -> whatsapp-cloud-api -> result
2. 并行执行
技能独立处理请求的不同方面。
适用情况： 所有技能角色相同（全是生产者或全是消费者）。
示例： instagram 发布帖子 + whatsapp 发送通知（都接收相同内容）
user_query -> [instagram, whatsapp-cloud-api] -> aggregated_result
3. 主从模式
一个主要技能主导；其他技能提供支持数据。
适用情况： 一个技能的分数远高于其他技能（>= 2x）。
示例： whatsapp-cloud-api 发送消息（主要）+ web-scraper 提供数据（支持）
user_query -> whatsapp-cloud-api (primary) + web-scraper (support) -> result
详情请参阅 References/Orchestration-Patterns.md
项目管理
将技能分配给项目可实现相关性提升和持久上下文。
项目文件
agent-orchestrator/data/projects.json
操作
创建项目： 向 projects.json 添加条目：
{
"name": "项目名称",
"created_at": "2026-02-25T12:00:00",
"skills": ["web-scraper", "whatsapp-cloud-api"],
"description": "项目描述"
}
向项目添加技能： 更新项目的 skills 数组。
从项目移除技能： 从 skills 数组中移除。
查询项目技能： 读取 projects.json 并列出已分配的技能。
添加新技能
要向生态系统添加新技能：
- 在
skills root:下的任何位置创建一个文件夹 - 创建带有 YAML 前置元数据的
SKILL.md：
---
name: 我的新技能
description: "带有激活关键词的描述..."
---
## 技能文档
- 完成！ 自动发现会在下次请求时自动检测到。
（可选）为了 Claude Code 的原生发现：
4. 将 SKILL.md 复制到 .claude/skills/<名称>/SKILL.md
显式能力标签（可选）
在前置元数据中添加，以实现更精确的匹配：
capabilities: [data-extraction, web-automation]
查看所有技能的状态
python agent-orchestrator/scripts/scan_registry.py --status
状态解释
| 状态 | 含义 |
|---|---|
| active | SKILL.md 包含 name 和 description |
| incomplete | SKILL.md 存在但缺少 name 或 description |
| missing | 目录存在但没有 SKILL.md |
当前生态系统中的技能
| 技能 | 能力 | 状态 |
|---|---|---|
| web-scraper | data-extraction, web-automation | active |
| junta-leiloeiros | government-data, data-extraction | active |
| whatsapp-cloud-api | messaging, api-integration | active |
| social-media, api-integration | partial |
此表格通过 scan_registry.py --status 自动更新。
最佳实践
- 提供有关项目和要求的具体上下文
- 在将任何建议应用于生产代码之前进行审查
- 与其他互补技能结合使用，实现全面分析
常见陷阱
- 将此技能用于其领域专业知识之外的任务
- 未理解具体上下文就应用建议
- 未提供足够的项目上下文以进行准确分析
相关技能
multi-advisor- 用于增强分析的互补技能task-intelligence- 用于增强分析的互补技能
限制
- 仅在任务明确符合上述范围时使用此技能
- 不要将输出视为特定环境验证、测试或专家审查的替代品
- 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清