Files

T

qyqy f2ac8a4460 docs: 交付说明按评审意见第二次修订；修同事带入的文档重号

评审意见逐条落地（详见文档新增的 §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 份）。

2026-09-11 19:15:23 +08:00

2.6 KiB

Raw Permalink Blame History

金融 NL2SQL 工具接入说明

1. 工具定位

query_financial_data 是运营和投顾共用的金融只读 NL2SQL 工具。业务 Agent 只负责判断是否调用工具，不直接连库、不读取密钥、不自行写审计。

调用链固定为：

业务 Agent -> BaseAgent.call_tool -> ToolExecutor -> query_financial_data -> 金融只读表

2. 工具声明

业务 Agent 的 AgentDefinition.allowed_tools 需要包含：

allowed_tools=("query_financial_data",)
supported_intents=("financial_query", "general")

发布配置需要按意图开启工具白名单：

{
  "namespace": "agent_tools",
  "config_key": "<agent_type>:financial_query",
  "value_json": {"allowed_tools": ["query_financial_data"]}
}

工具权限码：

financial:nl2sql:read

允许角色：

advisor、operator、admin、super_admin

3. 调用示例

result = await self.call_tool(
    "query_financial_data",
    {"question": request.message, "dry_run": False, "limit": 50},
    intent="financial_query",
    context=context,
)

低置信度或模糊问题会返回：

{"status": "need_confirmation", "message": "请确认查询范围、指标口径和时间条件。"}

Agent 应把 message 原样返回给用户，等待用户补充或确认后再次调用，并传入 confirmation。

4. MVP 范围

当前纳入 NL2SQL 的表：

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 和权限校验摘要。

2.6 KiB Raw Permalink Blame History Unescape Escape