qyqy
f2ac8a4460
评审意见逐条落地（详见文档新增的 §0 对照表）： - §1.1/§1.2/§4：确认两台机器连的**不是同一套 MySQL/Milvus**（我方 config_release 总共 4 条、 最高 216；架构师侧 201 + 9 条白名单），据此把"216 已在共享库生效"整体改写为 "**我方环境**已发布，你那台需补发"；补发由架构师做（配置属环境数据，不随代码合并） - §1.3：字段映射已改为运行时探测（见上一提交），文档里的 A/B/C 三选一整体替换为探测方案说明 - §1.4：mypy 那条改写——查清主因是**本机缺 SQLAlchemy 2.0 类型信息**（装 sqlalchemy2-stubs 181→43，卸载回 184），明确"本机数字不可作为质量结论、两边不可比"；我文件里的 8 个真实错误已修 - §2：明确 docs/26 是**重命名**（原 21，因 21 已被风控迁移清单占用），不是新增、不会并存 - §3.1：审计留痕已补（agent_type + governance_rewrite） - §3.3：5 份文档删除**已撤回**（上一提交） - §5/§7：更新验证数字（1218 passed）、两个环境相关失败的证据、memory_sync_outbox 双环境对照表 另修一处**同事那条线带入的重号**：docs/15-金融NL2SQL工具接入说明.md 与既有 docs/15-Agent组员详细开发与使用手册.md 撞号 → 新那份让号到 docs/27 （依据：手册被 docs/16、docs/17、AGENTS.md 三处引用，改名代价更大）。守卫恢复通过（32 份）。
106 lines
2.6 KiB
Markdown
106 lines
2.6 KiB
Markdown
# 金融 NL2SQL 工具接入说明
|
||
|
||
## 1. 工具定位
|
||
|
||
`query_financial_data` 是运营和投顾共用的金融只读 NL2SQL 工具。业务 Agent 只负责判断是否调用工具，不直接连库、不读取密钥、不自行写审计。
|
||
|
||
调用链固定为：
|
||
|
||
```text
|
||
业务 Agent -> BaseAgent.call_tool -> ToolExecutor -> query_financial_data -> 金融只读表
|
||
```
|
||
|
||
## 2. 工具声明
|
||
|
||
业务 Agent 的 `AgentDefinition.allowed_tools` 需要包含：
|
||
|
||
```python
|
||
allowed_tools=("query_financial_data",)
|
||
supported_intents=("financial_query", "general")
|
||
```
|
||
|
||
发布配置需要按意图开启工具白名单：
|
||
|
||
```json
|
||
{
|
||
"namespace": "agent_tools",
|
||
"config_key": "<agent_type>:financial_query",
|
||
"value_json": {"allowed_tools": ["query_financial_data"]}
|
||
}
|
||
```
|
||
|
||
工具权限码：
|
||
|
||
```text
|
||
financial:nl2sql:read
|
||
```
|
||
|
||
允许角色：
|
||
|
||
```text
|
||
advisor、operator、admin、super_admin
|
||
```
|
||
|
||
## 3. 调用示例
|
||
|
||
```python
|
||
result = await self.call_tool(
|
||
"query_financial_data",
|
||
{"question": request.message, "dry_run": False, "limit": 50},
|
||
intent="financial_query",
|
||
context=context,
|
||
)
|
||
```
|
||
|
||
低置信度或模糊问题会返回：
|
||
|
||
```json
|
||
{"status": "need_confirmation", "message": "请确认查询范围、指标口径和时间条件。"}
|
||
```
|
||
|
||
Agent 应把 `message` 原样返回给用户，等待用户补充或确认后再次调用，并传入 `confirmation`。
|
||
|
||
## 4. MVP 范围
|
||
|
||
当前纳入 NL2SQL 的表：
|
||
|
||
```text
|
||
sys_customer_assignment
|
||
fin_customer_profile
|
||
fin_risk_assessment
|
||
fin_product
|
||
fin_fee_rule
|
||
fin_market_price
|
||
fin_nav_history
|
||
fin_holding
|
||
fin_transaction
|
||
fin_sim_order
|
||
fin_sim_account
|
||
fin_cash_ledger
|
||
client_facing_content
|
||
```
|
||
|
||
第一期只支持只读查询；支持跨两个或三个业务域查询；支持历史范围查询。历史时点查询如果依赖当前快照表，例如 `fin_holding`、`fin_sim_account`、`sys_customer_assignment`，会拒绝执行。
|
||
|
||
## 5. 审计与持久化
|
||
|
||
工具输出包含 `audit`，其中有：
|
||
|
||
- `query_plan`：查询计划；
|
||
- `generated_sql`：生成 SQL；
|
||
- `permission_check`：权限校验结果；
|
||
- `execution`：执行状态和返回行数。
|
||
|
||
`ToolExecutor` 会把这些摘要写入 `ToolCallRecord.output_summary`，公共运行持久化会最终写入 `conversation_message.tool_calls`。
|
||
|
||
## 6. 接入验收
|
||
|
||
运营或投顾 Agent 接入时至少验证：
|
||
|
||
- AgentDefinition 声明了 `query_financial_data`；
|
||
- 发布配置按目标意图放行该工具；
|
||
- 调用方角色具备 `financial:nl2sql:read`；
|
||
- 模糊问题会先要求确认；
|
||
- 生成 SQL 只包含 `SELECT`，且表名均在白名单内；
|
||
- `conversation_message.tool_calls` 能看到查询计划、SQL 和权限校验摘要。
|