| name | agent-router |
| description | 任务到 Agent 的智能路由器，根据任务类型、文件路径自动选择最合适的 Agent。
使用场景：subagent-driver 需要为任务选择 Agent、不确定应该使用哪个 Agent
|
| argument-hint | [task-description] |
| disable-model-invocation | false |
| user-invocable | false |
| context | fork |
| agent | general-purpose |
| allowed-tools | Read, Glob, Grep, Bash |
Agent Router (智能路由器)
版本: 1.2.2 | 类型: 路由器 (Agent 选择)
更新: 2026-07-12 - 摘要表残余漂移对齐 #101 (architecture→backend-architect 0.85 / api-doc·llm·rag 0.95 / React Native·Flutter 0.95 [后两行 recon 新发现]) + 表级 canonical banner (ROUTING_RULES=SOT, 根治双写漂移); 前版 1.2.1 基线层语义补明 #99
快速开始
我应该使用这个 Skill 吗？
使用场景:
- 为任务自动选择合适的 Agent
- 不确定应该使用哪个专业 Agent
- 需要智能 Agent 匹配
不使用场景:
- 已明确知道使用哪个 Agent → 直接调用
- 简单通用任务 → 使用 general-purpose
核心功能
| 功能 | 说明 |
|---|
| 智能路由 | 根据任务特征自动匹配 Agent |
| 置信度评分 | 对每个匹配结果评分 (0-1) |
| 项目级 capability 路由 | 扫描 .aria/agents/ 项目级 Agent, 按 capabilities 匹配进入 auto/recommend (v1.2.0, ROUTING_RULES §CAP) |
| 多模式支持 | 自动 / 推荐 / 手动三种模式 |
| 用户覆盖 | 允许用户显式指定 Agent |
| Fallback | 无匹配时使用 general-purpose |
路由模式
自动模式 (auto)
行为: 两段式裁决 (v1.2.0, 详见 §执行流程 step 5 + ROUTING_RULES §CAP-4):
Stage 1 基线裁决 (FP/TT/技术栈/关键词, 既有规则含 threshold 与 <0.1 近分降级)
Stage 2 项目级 CAP 挑战 (仅当存在项目级 CAP 候选):
R-a 决定性直派 (specialist 全命中) / R-b 有序四分支数值裁决
条件: 用户未显式指定 Agent
示例:
任务: "实现用户登录 API" (无项目级候选)
路由结果: backend-architect (confidence: 0.95, decision_path: baseline)
动作: 直接使用 backend-architect
推荐模式 (recommend) - 默认
行为: 展示 Top-3 Agent 供用户选择
触发: confidence < threshold 或有多个候选
条件: 用户未显式指定 Agent
示例:
任务: "优化数据库查询"
路由结果:
[1] backend-architect (0.85) - 后端架构优化
[2] qa-engineer (0.60) - 性能分析
[3] general-purpose (0.50) - 通用任务兜底
动作: 询问用户选择
手动模式 (manual)
行为: 使用用户显式指定的 Agent
触发: 用户在任务中指定
优先级: 最高 (覆盖自动和推荐)
示例:
任务: "用 backend-architect 实现用户认证"
路由结果: backend-architect (手动指定)
动作: 直接使用 backend-architect
路由规则
本节为插件级基线四类规则 (文件路径/任务类型/技术栈/关键词) 摘要。项目级 capability 匹配 (§CAP: required_caps 推断 / 评分公式 / 两段式决策 / 同名得分归属 / recommend 混排) 见 ROUTING_RULES.md §CAP。
Canonical banner (v1.2.2, #101): 本节摘要表的目标 Agent 与置信度以
ROUTING_RULES.md 为 canonical SOT, 摘要仅便于扫读;
与 canonical 冲突时一律以 canonical 为准。改路由规则只改 ROUTING_RULES,
摘要表随之对齐 (摘要表历史上已两次漂移: #99 frontend 行 / #101 六行, 皆双写所致)。
文件路径匹配
| 路径模式 | 目标 Agent | 置信度 |
|---|
backend/**/* | backend-architect | 0.90 |
api/**/* | backend-architect | 0.95 |
database/**/* | backend-architect | 0.90 |
mobile/**/* | mobile-developer | 0.95 |
*.dart | mobile-developer | 0.90 |
frontend/**/* | frontend-developer (注) | 0.85 |
docs/**/* | knowledge-manager | 0.85 |
ai/**/* | ai-engineer | 0.90 |
注 (v1.2.1, #99): frontend/**/* 行此前写 general-purpose 0.70, 与 canonical
ROUTING_RULES FP-022 (frontend-developer 0.85) 冲突, 现对齐。frontend-developer
非插件内置 Agent (不在 §Agent 能力矩阵) — 胜出时按 §错误处理「Agent 不存在」回退
general-purpose, 除非项目级 .aria/agents/frontend-developer.md 提供该 Agent
(详见 ROUTING_RULES FP-022~025 注 1)。
任务类型匹配
| 任务类型 | 目标 Agent | 置信度 |
|---|
architecture | backend-architect | 0.85 |
code-review | qa-engineer | 0.95 |
ui-design | ui-ux-designer | 0.90 |
legal | legal-advisor | 0.95 |
api-doc | api-documenter | 0.95 |
llm / rag | ai-engineer | 0.95 |
tech-lead / planning | tech-lead | 0.85 |
技术栈匹配
| 技术关键词 | 目标 Agent | 置信度 |
|---|
React Native | mobile-developer | 0.95 |
Flutter | mobile-developer | 0.95 |
REST / GraphQL | backend-architect | 0.85 |
vector / embedding | ai-engineer | 0.90 |
OpenAPI / Swagger | api-documenter | 0.90 |
输入参数
| 参数 | 必需 | 说明 | 默认值 |
|---|
task | ✅ | 任务描述 | - |
task_type | ❌ | 任务类型。未传时自动推断: 以 TT 表「触发关键词」为唯一依据, task 文本词边界逐字命中 (非语义联想), 见 ROUTING_RULES §任务类型规则推断程序 (v1.2.1, #99) | 自动推断 |
files | ❌ | 相关文件列表 | [] |
mode | ❌ | 路由模式 | recommend |
threshold | ❌ | 自动模式阈值; 比较取 >= (恰等合格, 见 ROUTING_RULES §threshold 比较语义, v1.2.1 #99) | 0.9 |
user_agent | ❌ | 用户指定的 Agent | null |
required_caps | ❌ | 显式任务需求标签 (taxonomy tag list, v1.2.0)。传入 → 跳过 L1/L2 推断直接采用 (归一失败值剔除+WARN), 见 ROUTING_RULES §CAP-1 | null (推断) |
输出格式
自动模式 (直接匹配)
status: "auto_match"
agent: "backend-architect"
confidence: 0.95
reason: "任务涉及 API 设计，路径匹配 backend/**/*"
model: "sonnet"
agent_source: "plugin"
decision_path: "baseline"
required_caps_trace:
explicit: false
l1: [api-design]
l2: []
negated: []
off_taxonomy_tags: []
warnings: []
推荐模式 (多候选)
status: "recommend"
candidates:
- rank: 1
agent: "backend-architect"
confidence: 0.85
reason: "后端架构相关任务"
model: "sonnet"
- rank: 2
agent: "qa-engineer"
confidence: 0.60
reason: "可能涉及性能分析"
model: "sonnet"
- rank: 3
agent: "general-purpose"
confidence: 0.50
reason: "通用任务兜底"
model: "sonnet"
user_select_required: true
手动模式 (用户指定)
status: "manual"
agent: "mobile-developer"
confidence: 1.0
reason: "用户显式指定"
source: "user_override"
无匹配 (Fallback)
status: "fallback"
agent: "general-purpose"
confidence: 0.0
reason: "无明确匹配规则"
fallback: true
执行流程
路由流程:
1. 解析输入:
├── 读取 task 描述
├── 读取 task_type (如有)
├── 读取 files 列表
└── 检查 user_agent (手动指定)
2. 手动模式检查:
├── if user_agent 存在:
│ └── 返回手动模式结果
└── else: 继续
3. 规则匹配:
├── 3a 文件路径匹配 (FP)
├── 3b 任务类型匹配 (TT)
├── 3c 技术栈匹配
├── 3d 关键词匹配
└── 3e 项目级 capability 匹配 (v1.2.0 新增, 主链默认步, 受配置门控):
├── 门控 (最先判定, 命中即整步不执行 — 含同名检测/吸收在内的一切 3e 逻辑):
│ agent_router.plugin_only == true 或 scan_project_agents == false
│ → 跳过 3e, 退化纯基线 (输出 shape 完全等同 v1.1.x, 不含 3e 新字段)
├── 扫描 .aria/agents/*.md (缓存与失效语义见 §项目级 Agent 发现「缓存」)
├── frontmatter 健壮性: capabilities 缺失/非 list/YAML parse 失败 → skip 该
│ agent 不阻断; 空 list → 合法 (零命中)
├── 同名保护复合 (得分归属见 ROUTING_RULES §CAP-6): 池构建期先按名去重 —
│ 项目级替换插件级候选 + 输出警告; 幸存者吸收插件级按名命中的全部
│ FP/TT/技术栈/关键词 confidence; agent_source 恒 = project
├── 读 capabilities, 经 capabilities-taxonomy.yaml 归一 (ROUTING_RULES §CAP-2)
└── 按 ROUTING_RULES §CAP-3 评分产出项目级候选 (match_rate > 0 才产出,
零命中不入池; 候选携带 match_rate/|matched|/|required_caps|/precision/
off_taxonomy_tags)
4. 置信度聚合:
├── 合并所有匹配结果 (基线候选 + 项目级 CAP 候选进同一候选池)
├── 侧别语义: B12 吸收候选凭吸收分归基线侧; 其 CAP 分录仅用于 recommend
│ 排序与 trace, 不参与 Stage 2 auto 挑战者遴选 (ROUTING_RULES §CAP-6)
├── 去重并排序
└── 选择 Top-N
5. 模式决策:
├── if mode == auto: 两段式 (ROUTING_RULES §CAP-4):
│ ├── Stage 1 基线裁决: 基线侧候选 (含吸收分候选) 按既有规则得出
│ │ baseline 决策 + baseline_top — 基线侧候选间差值 < 0.1 严格降级
│ │ 与 threshold 检查照旧 (无项目级候选时行为与 v1.1.x 一致)
│ └── Stage 2 项目级 CAP 挑战 (仅当存在纯 CAP 项目级候选):
│ R-a 决定性直派 → R-b 有序分支 (0)-(4), 含基线池空分支 → 采纳/直派/降级
│ (auto 内部任何降级产出的 recommend 输出, 同样按 §CAP-7 混排)
│
├── if mode == recommend:
│ └── 返回 Top-3 推荐 (项目级候选按 §CAP-7 规则混排进入)
│
└── if mode == manual:
└── 既有逻辑不变 (user_agent 显式指定时于 step 2 前置返回;
未指定时等待指定 — 两形态均不经 3e 评分)
6. 返回结果
与 subagent-driver 集成
subagent-driver 调用流程:
1. 接收任务列表
2. for each task:
a. 调用 agent-router
├── task: 任务描述
├── files: 相关文件
└── mode: recommend (配置)
b. 获取路由结果
├── auto: 直接使用
├── recommend: 询问用户
├── manual: 使用用户指定
└── v1.2.0: 结果含 agent_source (plugin|project) — 项目级 Agent 胜出时
subagent-driver 可据此填充 handoff-contract 预留字段 agent_source
c. 启动 Fresh Subagent
└── 使用选定 Agent
3. 执行任务
4. 任务间审查
5. 4 选项完成
配置
项目级配置 (.claude/agent-router-config.json) — legacy
Legacy 标注 (v1.2.0): 本块为 v1.0.0 era 遗留配置面。step 3e 门控与缓存的 3 个 key (scan_project_agents / plugin_only / cache_ttl_seconds) 的 SOT 为 .aria/config.json 的 agent_router 块 (见下方「项目级 Agent 发现 → 配置」); 既有 confidence_threshold / max_candidates / default_mode 等仍居本 legacy 块, 迁移不在 v1.2.0 范围。
{
"enabled": true,
"default_mode": "recommend",
"confidence_threshold": 0.9,
"max_candidates": 3,
"fallback_agent": "general-purpose"
}
任务级覆盖
tasks:
- id: TASK-001
description: "实现用户认证"
agent: backend-architect
files:
- backend/api/auth.js
Agent 能力矩阵
下表为插件级基线 Agent (静态)。项目级 Agent (.aria/agents/*.md) 为动态发现, 不在此表 — 其能力由各自 frontmatter capabilities 标签声明, 经 ROUTING_RULES §CAP 匹配参与路由。
| Agent | 擅长任务 | 模型 | 颜色 |
|---|
| general-purpose | 通用任务、复杂搜索 | sonnet | gray |
| knowledge-manager | 文档架构、AI-DDD | sonnet | blue |
| tech-lead | 架构决策、任务规划 | opus | red |
| qa-engineer | 代码审查、质量保证 | sonnet | yellow |
| context-manager | 上下文管理、多任务协调 | opus | cyan |
| ai-engineer | LLM 应用、RAG 系统 | opus | yellow |
| backend-architect | API 设计、微服务 | sonnet | green |
| mobile-developer | React Native、Flutter | sonnet | pink |
| api-documenter | OpenAPI、SDK 生成 | haiku | orange |
| legal-advisor | 法律文档、合规 | haiku | purple |
| ui-ux-designer | 界面设计、用户体验 | sonnet | purple |
使用示例
示例 1: 自动匹配
输入:
task: "实现用户登录 REST API"
files: ["backend/api/auth.js"]
mode: auto
输出:
status: auto_match
agent: backend-architect
confidence: 0.95
reason: "文件路径匹配 backend/**/*，包含 API 关键词"
示例 2: 推荐模式
输入:
task: "优化用户注册流程性能"
files: ["backend/api/register.js", "database/schema.sql"]
mode: recommend
输出:
status: recommend
candidates:
- rank: 1
agent: backend-architect
confidence: 0.75
reason: "后端相关文件和性能优化"
- rank: 2
agent: qa-engineer
confidence: 0.65
reason: "性能分析和优化"
- rank: 3
agent: general-purpose
confidence: 0.50
reason: "通用任务兜底"
示例 3: 手动指定
输入:
task: "用 tech-lead 规划系统重构"
user_agent: tech-lead
输出:
status: manual
agent: tech-lead
confidence: 1.0
source: user_override
示例 4: 项目级 Agent R-a 决定性直派 (v1.2.0)
前提: .aria/agents/database-specialist.md 存在
(capabilities: [orm-migration, query-optimization, database-schema])
输入:
task: "给 extraction_job.status 的 CHECK 约束加值, 写 Alembic migration, 同步模型"
files: ["backend/models/extraction_job.py"]
mode: auto
required_caps: [orm-migration, database-schema]
输出:
status: auto_match
agent: database-specialist
confidence: 1.0
agent_source: project
decision_path: R-a
reason: "项目级 specialist 全命中 required_caps (R-a 决定性直派)"
required_caps_trace: {explicit: true, l1: [], l2: [], negated: []}
off_taxonomy_tags: []
warnings: []
错误处理
| 错误 | 原因 | 解决方案 |
|---|
| 无匹配规则 | 任务特征不符合任何规则 | 使用 general-purpose |
| Agent 不存在 | 指定的 Agent 无效 | 警告并回退到 general-purpose |
| 多高置信度 | 多个 Agent 置信度都 >= threshold | 降级到推荐模式 |
| 3e 扫描失败 (目录不可读) | 权限/IO 异常 | skip 3e 退化纯基线, WARN 不阻断 |
| 项目级 frontmatter 损坏 | capabilities 缺失/非 list/parse 失败 | skip 该 agent 不阻断; 空 list = 合法零命中 |
| 缓存写入失败 | 权限/磁盘/目录缺失 | mkdir -p 或 WARN + 直读 frontmatter, 不阻断 (§缓存) |
| required_caps 传参含无效值 | off-taxonomy/拼写错 | 剔除该值 + WARN, 余下继续 (§CAP-1) |
项目级 Agent 发现 (v1.2.0 主链接线; 机制引入于 v1.1.0)
机制
项目级 Agent 发现是 §执行流程 step 3e 的主链默认步 (v1.2.0 起, 见上方执行流程; v1.1.0-v1.53.0 期间本段曾为文末孤儿描述, auto 路径从未真正执行 — #153 发现 B, 已修复): 扫描 .aria/agents/ 目录, 项目级 Agent 经 capability 匹配 (ROUTING_RULES §CAP) 进入候选池并参与两段式 auto 裁决。
路由决策流程 (接线版):
1. 加载插件级 Agent 列表 (aria/agents/*.md)
2. step 3e: 扫描项目级 Agent 目录 (.aria/agents/*.md, 受配置门控)
3. 合并: 项目级 CAP 候选与基线候选进同一候选池 (同名保护复合见 §CAP-6)
4. 执行路由匹配: FP/TT/技术栈/关键词 (基线) + capabilities (项目级, §CAP)
5. step 5 两段式裁决 → 输出 (含 agent_source / decision_path 等字段, 见 §输出格式)
注意 (D4 rationale, 保留): 这是 Skill 层的运行时行为,不是 Plugin 层的静态注册。Claude Code Plugin 不会自动加载 .aria/agents/ 中的 Agent,但 agent-router Skill 在执行时会读取它们的 description 和 capabilities。
缓存 (v1.2.0 per-file 语义)
- 缓存文件
.aria/cache/project-agents.json, schema:
last_full_scan (int epoch seconds UTC, TTL 判定基准) + files: [{path, mtime[纳秒精度, 文件系统支持时], size}, ...]
- 主判: 每次 3e 对
.aria/agents/*.md 做 stat 集合比对, 任何差异 (增/删/改) → 重建缓存 + 更新 last_full_scan
cache_ttl_seconds (配置, 默认 0): >0 = 即使 stat 集合一致, now − last_full_scan 超 TTL 也强制重建 (对 stat 粒度漏检的时间兜底); 0 = 仅 stat 比对- 已知残余窗口 (诚实标注): 同秒 (纳秒不可用时) + 字节数不变的原地编辑可能漏检 — 兜底 1: cache_ttl_seconds; 兜底 2: 强制刷新 (删除缓存文件)
- 写入健壮性:
.aria/cache/ 不存在 → mkdir -p; 写入失败 → WARN + 本次直读 frontmatter 不用缓存, 不阻断路由; tmp + rename 原子写; 旧 schema 缓存 (无 last_full_scan) → 视为失效直接重建
同名保护
如果项目级 Agent 与插件级 Agent 同名:
- 输出警告:
⚠️ 项目级 Agent '<name>' 覆盖了插件级路由
- 项目级优先 (用户显式创建的应优先)
- 回退: 用户可在配置中设置
plugin_only: true 忽略项目级 Agent
配置
{
"agent_router": {
"scan_project_agents": true,
"plugin_only": false,
"cache_ttl_seconds": 0
}
}
相关文档
最后更新: 2026-07-12
Skill版本: 1.2.2 (摘要表残余漂移对齐 #101: 6 行对齐 canonical + 表级 canonical banner; 前版 1.2.1 基线层 5 处语义补明 #99)
