docs: 新增agent开发文档和风险评估文档

2026-05-15 06:58:21 +00:00
parent 45abd36430
commit 4f3556a38b
35 changed files with 8257 additions and 0 deletions
--- a/document/development/agent/agent
+++ b/document/development/agent/agent
@@ -0,0 +1,198 @@
+# Capability Registry 能力注册中心
+
+## 1. 为什么需要能力注册中心
+
+双 Agent 架构里会出现很多能力：
+
+- 规则文件。
+- 技能。
+- MCP 服务。
+- 数据库查询。
+- 知识库检索。
+- 定时任务。
+- 报告生成。
+
+如果 Orchestrator 直接在代码里硬编码这些能力，会导致：
+
+- 能力越来越多后难维护。
+- 无法统一权限。
+- 无法统一版本。
+- 无法统一输入输出格式。
+- Hermes 和 User Agent 复用困难。
+
+因此建议建立 Capability Registry。
+
+它的定位是：
+
+```text
+所有可被 Agent 调用的能力目录
+```
+
+## 2. 能力类型
+
+建议第一版支持：
+
+```text
+rule
+skill
+mcp
+task
+database_query
+knowledge_search
+report_generator
+notification
+```
+
+含义：
+
+- `rule`：审查规则，通常是 `.md` 文件或规则配置。
+- `skill`：智能能力，如审批意见生成、风险解释。
+- `mcp`：外部服务连接。
+- `task`：定时或批量任务。
+- `database_query`：受控数据库查询能力。
+- `knowledge_search`：知识库检索能力。
+- `report_generator`：报告生成能力。
+- `notification`：通知能力。
+
+## 3. 能力注册结构
+
+建议结构：
+
+```json
+{
+  "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 匹配能力。
+
+示例：
+
+```json
+{
+  "domain": "reimbursement",
+  "scenario": "invoice_validation",
+  "intent": "explain",
+  "risk_signals": ["duplicate_invoice"],
+  "next_step": "run_rule"
+}
+```
+
+可以匹配：
+
+```text
+重复报销识别规则
+发票验真 MCP
+风险解释技能
+制度知识库检索
+```
+
+## 5. 能力匹配优先级
+
+建议顺序：
+
+```text
+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. 数据表建议
+
+```text
+agent_capabilities
+```
+
+字段：
+
+```text
+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
+
+从：
+
+```text
+if next_step = run_rule then call duplicate_invoice_rule
+```
+
+改为：
+
+```text
+query capabilities where type = rule and scenario = invoice_validation
+```
+
+### Step 3: 加权限过滤
+
+只返回当前用户或任务有权限调用的能力。
+
+### Step 4: 加版本选择
+
+默认使用 active 版本。
+
+历史版本只用于回放和调试。
+
+### Step 5: 加健康状态
+
+MCP、任务、数据库查询能力应有健康状态。
+
+不可用时 Orchestrator 走降级策略。
+
+## 8. 治理要求
+
+- 所有能力必须有 owner。
+- 高风险能力必须有 reviewer。
+- 所有能力必须有输入输出 schema。
+- 所有能力必须有状态。
+- 下线能力不能被 Orchestrator 调用。
+- 能力版本变更必须写入审计。
+