docs: 增加风控Agent工具白名单与意图配置

2026-09-11 15:06:06 +08:00
parent 6911dd98a7
commit 2ebe438ba5
4 changed files with 206 additions and 0 deletions
@@ -0,0 +1,119 @@
+# Agent 工具白名单与意图配置
+
+## 文档功能
+
+本文档用于向主项目方交付奶龙风控智能助手的工具白名单和意图配置，说明实际生效值、配置表位置、工具权限和一致性要求。
+
+## Agent 基础声明
+
+| 项目 | 值 |
+|---|---|
+| `agent_type` | `risk` |
+| 展示名称 | 奶龙风控智能助手 |
+| 允许角色 | `risk_operator`、`admin` |
+| 允许入口 | `api` |
+| 运行权限 | `agent:run` |
+| 工具权限 | `risk:alert:read` |
+
+## 工具白名单
+
+当前 active 发布：
+
+```text
+release_no=risk-agent-local-v1
+namespace=agent_tools
+schema_version=1
+```
+
+| 配置键 | 允许工具 |
+|---|---|
+| `risk:risk_overview` | `get_risk_overview` |
+| `risk:risk_search` | `search_risk_alerts` |
+| `risk:risk_evidence` | `get_alert_evidence` |
+| `risk:general` | 无 |
+
+JSON 文件：
+
+- `config/risk_agent_tools.json`
+
+## 意图配置
+
+| 意图 | 名称 | 示例 | 允许工具 |
+|---|---|---|---|
+| `risk_overview` | 风险概览 | 查看当前风险概览；当前有多少高风险预警 | `get_risk_overview` |
+| `risk_search` | 风险查询 | 查询高风险预警；查看命中 RW-007 的预警 | `search_risk_alerts` |
+| `risk_evidence` | 预警证据 | 查询预警编号 ALERT-001 的证据；查看这条预警的证据链 | `get_alert_evidence` |
+| `general` | 通用风控查询 | 你能做什么；说明你的功能边界 | 无 |
+
+统一参数：
+
+```text
+confidence_threshold=0.6500
+max_clarification_rounds=2
+transfer_on_failure=true
+priority=100
+version=1
+status=active
+```
+
+JSON 文件：
+
+- `config/risk_agent_intents.json`
+
+## 配置表映射
+
+### 工具白名单
+
+写入 `platform_config_item`：
+
+- `release_id`：当前 active 配置发布。
+- `namespace`：`agent_tools`。
+- `config_key`：`risk:<intent_code>`。
+- `value_json`：`{"allowed_tools":[...]}`。
+
+### 意图
+
+写入 `agent_intent_config`：
+
+- `agent_type=risk`
+- `intent_code`
+- `intent_name`
+- `description`
+- `examples`
+- `classifier_instruction`
+- `confidence_threshold`
+- `max_clarification_rounds`
+- `transfer_on_failure`
+- `allowed_tools`
+- `priority`
+- `version`
+- `status`
+
+## 一致性要求
+
+- `platform_config_item` 的工具白名单是实际执行边界。
+- `agent_intent_config.allowed_tools` 必须与工具白名单保持一致。
+- 工具名称必须同时存在于代码的 `AgentDefinition.allowed_tools` 和工具注册表中。
+- 不得只配置意图而遗漏工具白名单。
+- 不得把写操作、处置操作或修改交易数据的工具放入白名单。
+
+## 工具权限
+
+三个工具均为只读工具：
+
+| 工具 | 角色 | 权限 |
+|---|---|---|
+| `get_risk_overview` | `risk_operator/admin` | `risk:alert:read` |
+| `search_risk_alerts` | `risk_operator/admin` | `risk:alert:read` |
+| `get_alert_evidence` | `risk_operator/admin` | `risk:alert:read` |
+
+## 主项目接入检查
+
+- 创建或复用 active `config_release`。
+- 导入 4 条 `agent_tools` 配置。
+- 导入 4 条 risk 意图配置。
+- 确认配置已审核并激活。
+- 确认 `risk_operator` 拥有 `agent:run` 和 `risk:alert:read`。
+- 确认 `risk` Agent 已注册到 `AgentFactory`。
+- 发起一次风险概览和一次预警搜索验证工具调用。
+
@@ -40,6 +40,7 @@
 | 17 | 前端合并提示词与验收约束 | 指导后续模型识别风控功能并合并前端 |
 | 18 | 当前项目完成进度 | 汇总当前完成度、验证结果和剩余任务 |
 | 19 | 风控模块配置项清单 | 单独说明风控专用和公共依赖配置 |
+| 20 | Agent工具白名单与意图配置 | 交付主项目方的工具和意图配置 |

 ## 推荐阅读顺序

@@ -51,3 +52,4 @@
 6. 17：主项目前端合并时直接提供给模型。
 7. 18：项目汇报、进度同步和下一阶段安排。
 8. 19：合并部署和联调时核对环境变量。
+9. 20：主项目方导入 Agent 工具白名单和意图配置。