agent-orchestrator

Agent Orchestrator

概述

用于编排整个生态系统中所有 Agent 的元技能。自动扫描技能，根据能力进行匹配，协调多技能工作流并管理注册表。

何时使用此技能

• 当用户要求列出本地技能，或为需要多种能力的任务制定协调计划时。
• 当需要明确比较候选项，但不执行其指令也不启动 Agent 时。

不要在以下情况下使用此技能

• 任务与 Agent Orchestrator 无关
• 更简单、更具体的工具可以处理该请求
• 用户需要的是通用协助，不需要领域专业知识

工作原理

作为整个技能生态系统的中央决策与协调层运行的元技能。它会自动扫描、识别相关 Agent，并为复杂任务编排多个技能。

原则：按需发现与可审阅计划

• 仅在用户要求的范围内扫描；此技能不应拦截所有请求
• 新技能会在下次显式扫描时检测到，扫描范围受根目录和深度限制
• 已移除的技能会从注册表中自动排除
• 请显式执行扫描；匹配器不会自动启动扫描

---

按需发现工作流

仅当任务要求使用此工具时，才执行以下步骤。分数是本地启发式指标，并不能证明安全性、兼容性或授权情况。计划不会执行技能；委派、发送消息和发布内容都需要用户授权。 脚本会根据自身安装位置定位文件，但以下命令假设 agent-orchestrator 的父目录是当前目录。从其他位置运行时，请使用脚本的绝对路径。

依赖项

使用 Python 3.10+，并在经过审查的虚拟环境中安装 scripts/requirements.txt；解析器需要 PyYAML。以下命令仅会盘点元数据并生成计划，不会执行技能。

步骤 1：自动发现（扫描）

python agent-orchestrator/scripts/scan_registry.py

使用 SHA-256 哈希缓存，仅重新处理已更改的文件。耗时取决于目录树的大小；不保证在 100ms 内完成。 返回包含所有已发现技能摘要的 JSON。

步骤 2：技能匹配

python agent-orchestrator/scripts/match_skills.py "<solicitacao do usuario>"

返回按相关性排序的技能 JSON。结果解读如下：

结果	操作
matched: 0	没有超过启发式阈值的候选项；这并不能证明不存在相关技能。
matched: 1	一个候选项。选定之前，请检查其范围、文件、依赖项和授权情况。
matched: 2+	多个候选项。仅当任务要求协调时，才提出计划。

步骤 3：编排（若 Matched >= 2）

python agent-orchestrator/scripts/orchestrate.py --skills skill1,skill2 --query "<solicitacao>"

返回执行计划，其中包含模式、步骤顺序以及技能之间的数据流。

快速步骤（快捷方式）

对于简单查询，可以依次合并步骤 1 和 2：

python agent-orchestrator/scripts/scan_registry.py && python agent-orchestrator/scripts/match_skills.py "<solicitacao>"

---

技能注册表

执行之前，请将 AGENT_ORCHESTRATOR_DATA_DIR 设置为技能安装目录之外、经授权的私有目录的绝对路径。注册表、哈希和项目分配信息都会保存在此目录中。请勿使用共享目录或包含符号链接的目录树；重复使用前请检查其内容。

export AGENT_ORCHESTRATOR_DATA_DIR="<diretorio-absoluto-autorizado>"

请先显式执行扫描，再运行匹配器。读取失败、JSON 无效或注册表缺失，并不意味着不存在技能。即使名称相同，不同路径也会分别保留在清单中；如果按名称选择存在歧义，则应停止。扫描器的深度限制会导致清单不完整。

搜索位置

扫描器会在以下位置查找 SKILL.md：

1. .claude/skills/*/（在 Claude Code 中注册的技能）
2. */（顶层独立技能）
3. 深度不超过 3 的子文件夹（部分覆盖）

每项技能的元数据

注册表中的每个条目都包含：

字段	描述
name	技能名称（来自 YAML frontmatter）
description	完整描述（包括触发条件）
location	目录的绝对路径
skill_md	SKILL.md 的绝对路径
registered	是否位于 .claude/skills/ 中（true/false）；不能证明宿主已加载该技能
capabilities	能力标签（自动提取 + 显式指定）
triggers	从 description 中提取的激活关键词
language	主要语言（python/nodejs/bash/none）
status	active / incomplete / missing

注册表命令

## Scan Rapido (Usa Cache De Hashes)

python agent-orchestrator/scripts/scan_registry.py

## Tabela De Status Detalhada

python agent-orchestrator/scripts/scan_registry.py --status

## Re-Scan Completo (Ignora Cache)

python agent-orchestrator/scripts/scan_registry.py --force

---

匹配算法

对于每个请求，匹配器会按以下标准为技能评分：

标准	分数	示例
查询中出现技能名称	+15	"use web-scraper" -> web-scraper
精确匹配触发关键词	+10	"scrape" -> web-scraper
能力类别	+5	data-extraction -> web-scraper
词语重叠	+1	查询中的词语出现在 description 中
项目加权	+20	分配给当前项目的技能

最低阈值：5 分。低于此分数的技能将被忽略。

项目匹配

python agent-orchestrator/scripts/match_skills.py --project meu-projeto "query aqui"

分配给项目的技能会自动获得 +20 加权分。

---

编排模式

当多个技能都相关时，编排器会对模式进行分类：

1. 顺序流水线

技能组成一条链，前一个技能的输出会作为下一个技能的输入。

适用情况： 混合使用“生产型”技能（data-extraction、government-data）和“消费型”技能（messaging、social-media）。

示例： 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. 主技能 + 辅助技能

一个主要技能负责主导，其他技能提供支持数据。

适用情况： 一个技能的得分远高于其他技能（>= 2 倍）。

示例： whatsapp-cloud-api 发送消息（主技能）+ web-scraper 提供数据（辅助技能）

user_query -> whatsapp-cloud-api (primary) + web-scraper (support) -> result

详见 orchestration-patterns.md

---

项目管理

将技能分配给项目，可提升相关性并提供持久化上下文。

项目文件

$AGENT_ORCHESTRATOR_DATA_DIR/projects.json

操作

创建项目： 在 projects.json 的 projects 数组中添加条目：

{"projects": [{
  "name": "nome-do-projeto",
  "created_at": "2026-02-25T12:00:00",
  "skills": ["web-scraper", "whatsapp-cloud-api"],
  "description": "Descricao do projeto"
}]}

向项目添加技能： 更新项目的 skills 数组。

从项目中移除技能： 从 skills 数组中移除。

查询项目技能： 读取 projects.json 并列出分配的技能。

---

添加新技能

要向生态系统添加新技能：

1. 在 skills root: 下任意位置创建一个文件夹
2. 创建包含 YAML frontmatter 的 SKILL.md：

---
name: minha-nova-skill
description: "Descricao com keywords de ativacao..."
---

## Documentacao Da Skill

3. 显式运行扫描以更新部分清单。

可选：如需 Claude Code 原生发现功能： 4. 将 SKILL.md 复制到 .claude/skills/<nome>/SKILL.md

显式能力标签（可选）

在 frontmatter 中添加以下内容，以实现更精确的匹配：

capabilities: [data-extraction, web-automation]

---

查看所有技能的状态

python agent-orchestrator/scripts/scan_registry.py --status

状态说明

状态	含义
active	存在 name + description；不代表已审核、安全或具备运行完整性
incomplete	存在 SKILL.md，但缺少 name 或 description
missing	目录存在，但没有 SKILL.md

---

当前生态系统中的 Skills

Skill	能力	状态
web-scraper	data-extraction, web-automation	active
junta-leiloeiros	government-data, data-extraction	active
whatsapp-cloud-api	messaging, api-integration	active
instagram	social-media, api-integration	partial

生态系统原始数据示例表；扫描器会输出当前清单，但不会修改此表。名称并不保证已安装在 AAS 中。

最佳实践

• 提供清晰、具体的项目背景和需求
• 在将任何建议应用于生产代码之前，先进行审核
• 与其他互补技能结合使用，以进行全面分析

常见陷阱

• 将此技能用于超出其专业领域的任务
• 未了解自身具体情况就应用建议
• 未提供足够的项目背景，导致分析不准确

相关技能

• multi-advisor - 用于增强分析的互补技能
• task-intelligence - 用于增强分析的互补技能

局限性

• 仅当任务明确符合上述范围时才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审核的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。