X-Financial/document/development/agent plan/07_capability_registry.md

Capability Registry 能力注册中心

1. 为什么需要能力注册中心

双 Agent 架构里会出现很多能力：

• 规则文件。
• 技能。
• MCP 服务。
• 数据库查询。
• 知识库检索。
• 定时任务。
• 报告生成。

如果 Orchestrator 直接在代码里硬编码这些能力，会导致：

• 能力越来越多后难维护。
• 无法统一权限。
• 无法统一版本。
• 无法统一输入输出格式。
• Hermes 和 User Agent 复用困难。

因此建议建立 Capability Registry。

它的定位是：

所有可被 Agent 调用的能力目录

2. 能力类型

建议第一版支持：

rule
skill
mcp
task
database_query
knowledge_search
report_generator
notification

含义：

• rule：审查规则，通常是 .md 文件或规则配置。
• skill：智能能力，如审批意见生成、风险解释。
• mcp：外部服务连接。
• task：定时或批量任务。
• database_query：受控数据库查询能力。
• knowledge_search：知识库检索能力。
• report_generator：报告生成能力。
• notification：通知能力。

3. 能力注册结构

建议结构：

{
  "id": "cap_rule_duplicate_invoice",
  "code": "duplicate_invoice_rule",
  "name": "重复报销识别规则",
  "capability_type": "rule",
  "domain": "reimbursement",
  "scenarios": ["invoice_validation", "reimbursement_audit"],
  "intents": ["validate", "explain", "monitor"],
  "input_schema": {},
  "output_schema": {},
  "permission_required": ["reimbursement:read", "risk:write"],
  "risk_level": "high",
  "owner": "财务风控组",
  "version": "v1.9",
  "status": "active",
  "requires_confirmation": false,
  "created_at": "",
  "updated_at": ""
}

4. 与语义本体的匹配关系

Orchestrator 根据 ontology_json 匹配能力。

示例：

{
  "domain": "reimbursement",
  "scenario": "invoice_validation",
  "intent": "explain",
  "risk_signals": ["duplicate_invoice"],
  "next_step": "run_rule"
}

可以匹配：

重复报销识别规则
发票验真 MCP
风险解释技能
制度知识库检索

5. 能力匹配优先级

建议顺序：

Step 1: next_step 决定能力大类
Step 2: domain 限定业务域
Step 3: scenario 限定场景
Step 4: risk_signals 匹配具体规则
Step 5: intent 匹配技能
Step 6: permission_required 校验权限
Step 7: status 必须 active
Step 8: version 使用当前上线版本

6. 数据表建议

agent_capabilities

字段：

id
code
name
capability_type
domain
scenario_json
intent_json
input_schema_json
output_schema_json
permission_json
risk_level
owner
current_version
status
requires_confirmation
config_json
created_at
updated_at

7. 开发步骤

Step 1: 先注册静态能力

先把现有规则、技能、MCP、任务写入 Registry。

不需要一开始做复杂 UI。

Step 2: Orchestrator 改为查 Registry

从：

if next_step = run_rule then call duplicate_invoice_rule

改为：

query capabilities where type = rule and scenario = invoice_validation

Step 3: 加权限过滤

只返回当前用户或任务有权限调用的能力。

Step 4: 加版本选择

默认使用 active 版本。

历史版本只用于回放和调试。

Step 5: 加健康状态

MCP、任务、数据库查询能力应有健康状态。

不可用时 Orchestrator 走降级策略。

8. 治理要求

• 所有能力必须有 owner。
• 高风险能力必须有 reviewer。
• 所有能力必须有输入输出 schema。
• 所有能力必须有状态。
• 下线能力不能被 Orchestrator 调用。
• 能力版本变更必须写入审计。