453 lines
20 KiB
Markdown
453 lines
20 KiB
Markdown
# MySQL 智能问数设计
|
||
|
||
> 日期：2026-05-15
|
||
> 状态：Draft v2
|
||
> Owner：与 lixin 共识
|
||
> 范围：MySQL 只读数据源配置、Agent Tool、跨表 JOIN、问数 Prompt Skill
|
||
|
||
## 0. v2 架构修订
|
||
|
||
v2 根据系统架构 review 收紧了安全边界：
|
||
|
||
- `mysql_query` MVP 只允许 `SELECT`，不再允许自由 `SHOW`、`DESCRIBE`、`EXPLAIN`。
|
||
- schema、索引、外键和少量样例通过受控工具读取，不通过自由 SQL 读取。
|
||
- 增加表级白名单、表级黑名单和列级脱敏配置。
|
||
- 增加 JOIN 成本保护：查询超时、最大 JOIN 表数、禁止无条件 JOIN、结果行数硬上限。
|
||
- 增加连接池生命周期设计。
|
||
- 增加查询审计表。
|
||
- 明确新增公共 `SecretCryptoService`，不复用当前 SkillSecretService 的明文写入行为。
|
||
- 区分后台安全投影和 Agent 工具投影，`mysql_list_sources` 不向 Agent 暴露 host、username、passwordEncrypted。
|
||
- 对显式 `LIMIT` 做硬上限校验，禁止用超大 LIMIT 绕过结果限制。
|
||
- MVP 对 `maskedColumns` 采取保守策略：自由 SQL 直接引用脱敏列时拒绝执行，避免 alias 绕过。
|
||
|
||
## 1. 背景与目标
|
||
|
||
Neta 当前已经有完整的 Agent Tool 治理、Skill Runtime 和 Agent 配置体系。智能问数能力需要同时满足两类需求：
|
||
|
||
- 平台能力：配置 MySQL 连接、加密保存密码、控制哪些 Agent 可用、执行只读 SQL、限制超时和返回行数。
|
||
- 问数流程：让 Agent 先理解 schema，必要时澄清业务口径，再生成 SQL，最后解释结果、口径和限制。
|
||
|
||
因此本功能采用“Tool 做执行能力，Skill 做问数方法论”的组合方案。MySQL 连接和 SQL 执行进入 NetaClaw Tool 系统；问数策略进入一个 prompt skill，供需要问数的 Agent 绑定。
|
||
|
||
## 2. 非目标
|
||
|
||
第一版不实现以下能力：
|
||
|
||
- 不支持 PostgreSQL、SQLite、SQL Server、Oracle 等其他数据库。
|
||
- 不执行 INSERT、UPDATE、DELETE、CREATE、ALTER、DROP、TRUNCATE、CALL、事务语句或存储过程。
|
||
- 不做可视化 BI 图表、不新增复杂 dashboard。
|
||
- 不做自然语言到 SQL 专用模型微调。
|
||
- 不自动优化复杂 SQL，只提供 schema、样例和执行反馈，让 Agent 在只读约束内生成 SQL。
|
||
- 不跨多个数据源做 JOIN；跨表 JOIN 仅限同一个 MySQL 数据源和当前连接可访问的库。
|
||
- 第一版不允许用户通过 `mysql_query` 自由执行 `SHOW`、`DESCRIBE`、`EXPLAIN`；这些元信息由 `mysql_schema` 等受控工具提供。
|
||
|
||
## 3. 用户体验
|
||
|
||
管理员在后台新增 MySQL 数据源，填写名称、连接地址、端口、数据库名、账号和密码。密码只保存加密值，不在接口回显明文。
|
||
|
||
管理员在 Agent 配置中启用 `mysql` toolset，并按需绑定 `data-analyst-mysql` skill。用户在对话中问“上个月各门店销售额是多少”“按客户和订单表统计复购率”这类问题时，Agent 会先读取 schema，必要时读取表样例，再执行只读 SQL。回答中需要包含：
|
||
|
||
- 结论。
|
||
- 使用的 SQL。
|
||
- 关联口径，尤其是跨表 JOIN 的关联字段。
|
||
- 结果限制，例如采样、LIMIT、字段缺失或关联字段为推断关系。
|
||
|
||
## 4. 架构
|
||
|
||
整体架构沿用 NetaClaw 当前工具链路：
|
||
|
||
```text
|
||
netaclaw_data_source + netaclaw_data_source_query_audit
|
||
-> SecretCryptoService + DataSourceService 授权过滤
|
||
-> MysqlPoolManager + MysqlQueryService / MysqlIntrospectionService
|
||
-> mysql_list_sources / mysql_schema / mysql_table_sample / mysql_query
|
||
-> Tool Catalog + Tool Governance + Tool Resolver
|
||
-> Agent Runtime
|
||
-> data-analyst-mysql Skill 约束问数流程
|
||
```
|
||
|
||
新增能力分为四层：
|
||
|
||
1. 数据源配置层：保存 MySQL 连接和 Agent 授权。
|
||
2. MySQL 执行层：封装连接池、schema 查询、样例读取和只读 SQL 执行。
|
||
3. Tool 层：向 Agent 暴露稳定工具接口，并接入 catalog、resolver、runtime policy。
|
||
4. Skill 层：定义问数流程、JOIN 推理规则和回答格式。
|
||
|
||
## 5. 数据模型
|
||
|
||
新增实体 `NetaClawDataSourceEntity`，表名 `netaclaw_data_source`。
|
||
|
||
字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `name` | varchar(100), unique | 数据源唯一名，工具调用使用 |
|
||
| `label` | varchar(200) | 展示名 |
|
||
| `type` | varchar(20) | 固定为 `mysql` |
|
||
| `host` | varchar(255) | MySQL host |
|
||
| `port` | int | 默认 3306 |
|
||
| `database` | varchar(128) | 默认库名 |
|
||
| `username` | varchar(255) | 连接用户名 |
|
||
| `passwordEncrypted` | text | AES-256-GCM 加密密码 |
|
||
| `readonly` | int | 1 表示只读，MVP 固定为 1 |
|
||
| `status` | int | 0 禁用，1 启用 |
|
||
| `allowedAgentIds` | json | 为空表示不授权任何 Agent；数组内 Agent 可用 |
|
||
| `extra` | json | SSL、connectTimeout、queryTimeout、maxRows、allowedTables、blockedTables、maskedColumns、maxJoinTables 等扩展 |
|
||
|
||
`extra` 权限字段：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `allowedTables` | 可访问表白名单，空数组表示默认不开放任何业务表 |
|
||
| `blockedTables` | 表黑名单，优先级高于白名单 |
|
||
| `maskedColumns` | 需要脱敏的列，格式为 `{ "table.column": "hash|partial|redact" }` |
|
||
| `schemaVisibility` | `allowed-only` 或 `all-names-only`，MVP 默认 `allowed-only` |
|
||
| `queryTimeoutMs` | 单次 SQL 超时，默认 10000，硬上限 30000 |
|
||
| `maxRows` | 默认 200，硬上限 1000 |
|
||
| `maxJoinTables` | 默认 4，硬上限 6 |
|
||
| `poolConnectionLimit` | 默认 3，硬上限 10 |
|
||
|
||
密码必须用新增公共 `SecretCryptoService` 加密保存。当前 `SkillSecretService.encrypt()` 新写入路径是 JSON 明文，不能作为数据源密码的加密实现直接复用。
|
||
|
||
服务端必须区分两种投影：
|
||
|
||
- 管理端安全投影：可返回 `host`、`port`、`database`、`username`、`hasPassword`、授权与权限配置，但不返回 `passwordEncrypted` 或明文密码。
|
||
- Agent 工具投影：`mysql_list_sources` 只返回 `name`、`label`、`database`、`status`，不返回 `host`、`username`、`passwordEncrypted`、权限细节或连接串。
|
||
|
||
新增实体 `NetaClawDataSourceQueryAuditEntity`，表名 `netaclaw_data_source_query_audit`。
|
||
|
||
字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `dataSourceId` | int | 数据源 ID |
|
||
| `agentId` | int | 调用 Agent |
|
||
| `userId` | int | 当前用户，可为空 |
|
||
| `toolCallId` | varchar(100) | 工具调用 ID |
|
||
| `sqlHash` | varchar(64) | SQL SHA-256 |
|
||
| `sqlPreview` | text | 截断后的 SQL 摘要，不含结果集 |
|
||
| `status` | varchar(20) | success / rejected / failed |
|
||
| `rejectReason` | varchar(100) | 被 guard 拒绝原因 |
|
||
| `elapsedMs` | int | 耗时 |
|
||
| `rowCount` | int | 返回行数 |
|
||
| `errorCode` | varchar(50) | MySQL errno / SQLSTATE，可为空 |
|
||
|
||
## 6. 后端服务
|
||
|
||
新增 `SecretCryptoService`：
|
||
|
||
- `encryptJson(value: Record<string, string>): string`
|
||
- `decryptJson(ciphertext: string): Record<string, string>`
|
||
- `encryptText(value: string): string`
|
||
- `decryptText(ciphertext: string): string`
|
||
- 使用 AES-256-GCM，密钥来自 `NETA_SECRET_KEY`，开发环境可回退到 `APP_SECRET`。
|
||
- 密文必须带版本化 envelope，例如 base64(JSON.stringify({ v: 1, alg: 'aes-256-gcm', iv, tag, ct }))，便于后续密钥轮换、格式识别和 Skill secret 迁移。
|
||
- 新数据源密码只允许写入加密格式；Skill secret 的现有兼容逻辑可后续迁移到该公共服务。
|
||
|
||
新增 `DataSourceService`：
|
||
|
||
- `listForAgent(agentId: number): Promise<AgentDataSourceSummary[]>`
|
||
- `listAdminSafe(): Promise<AdminSafeDataSource[]>`
|
||
- `getAuthorizedSource(name: string, agentId: number): Promise<NetaClawDataSourceEntity>`
|
||
- `saveConfig(input): Promise<AdminSafeDataSource>`
|
||
- `testConnection(input): Promise<{ ok: boolean; error?: string }>`
|
||
- 应用 `allowedAgentIds`、`allowedTables`、`blockedTables`、`maskedColumns` 和 `schemaVisibility`。
|
||
- 编辑已有数据源并测试连接时，如果没有传新密码，必须从数据库读取旧 `passwordEncrypted`，不能依赖接口回显密文。
|
||
|
||
新增 `MysqlPoolManager`：
|
||
|
||
- `getPool(source): Promise<Pool>`
|
||
- 按 `dataSource.id` 缓存连接池。
|
||
- 默认 `connectionLimit=3`，由 `extra.poolConnectionLimit` 覆盖但不得超过 10。
|
||
- 保存、禁用或删除数据源时关闭对应 pool。
|
||
- 连接失败时不泄漏 host、username、password，只返回脱敏错误。
|
||
|
||
新增 `MysqlIntrospectionService`：
|
||
|
||
- `listSchema(source, options): Promise<MysqlSchemaResult>`
|
||
- 读取 `information_schema.columns`、`statistics`、`key_column_usage`。
|
||
- 只返回授权表。字段输出要应用 `maskedColumns` 标记，让 Agent 知道该列敏感；MVP 中查询或样例请求直接引用该列时由后端拒绝，后续具备可靠列血缘解析后再支持脱敏展示。
|
||
|
||
新增 `MysqlQueryService`：
|
||
|
||
- `executeReadOnly(source, sql, options): Promise<MysqlQueryResult>`
|
||
- 使用 `mysql2/promise`。
|
||
- 每次查询设置超时、最大行数和结果截断。
|
||
- `SELECT` 查询若没有 `LIMIT`，外层包裹为 `SELECT * FROM (<sql>) AS neta_limited_query LIMIT ?`。
|
||
- 显式 `LIMIT` 必须小于等于 `maxRows`；超过上限直接拒绝或重写为安全上限，不能先拉取大结果再在 Node 中 `slice`。
|
||
- 执行前调用 SQL guard、授权表检查和 JOIN 成本检查。
|
||
- 自由 SQL 引用 `maskedColumns` 时，MVP 直接拒绝执行，避免 `SELECT email AS e` 绕过脱敏；后续只有在引入 SQL parser 并能追踪 source column 到 output alias 后，才允许查询脱敏列并在返回前脱敏。
|
||
- 执行错误必须通过 `sanitizeMysqlError(err)` 脱敏，只返回 `code`、`sqlState`、`errno` 和固定短文案，不返回原始 `err.message`。
|
||
- 执行后写 query audit，不记录结果集。
|
||
|
||
## 7. Tool 设计
|
||
|
||
新增 toolset：`mysql`。
|
||
|
||
### mysql_list_sources
|
||
|
||
输入：
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
输出：
|
||
|
||
```json
|
||
{
|
||
"sources": [
|
||
{
|
||
"name": "sales_prod",
|
||
"label": "销售生产库",
|
||
"database": "sales",
|
||
"status": 1
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
只返回当前 Agent 授权的数据源摘要，不返回 host、username、passwordEncrypted、明文密码、连接串或表/列权限细节。
|
||
|
||
### mysql_schema
|
||
|
||
输入：
|
||
|
||
```json
|
||
{
|
||
"source": "sales_prod",
|
||
"tables": ["orders", "customers"]
|
||
}
|
||
```
|
||
|
||
`tables` 可选。为空时返回表摘要和字段摘要；指定时返回详细字段、索引和外键。
|
||
|
||
输出包含：
|
||
|
||
- `tables[].name`
|
||
- `tables[].comment`
|
||
- `tables[].columns[]`
|
||
- `tables[].primaryKey[]`
|
||
- `tables[].indexes[]`
|
||
- `tables[].foreignKeys[]`
|
||
|
||
### mysql_table_sample
|
||
|
||
输入：
|
||
|
||
```json
|
||
{
|
||
"source": "sales_prod",
|
||
"table": "orders",
|
||
"columns": ["id", "customer_id", "created_at"],
|
||
"limit": 5
|
||
}
|
||
```
|
||
|
||
用于辅助 Agent 判断字段含义和 JOIN key。`limit` 最大 20。表名和列名只能来自 introspection 结果，后端需要做 identifier 校验和反引号转义。
|
||
|
||
`mysql_table_sample` 不能通过拼接自由 SQL 绕过权限。后端必须先校验：
|
||
|
||
- `table` 在 `allowedTables` 内且不在 `blockedTables` 内。
|
||
- `columns` 均来自 `mysql_schema` 可见字段。
|
||
- 如果请求列命中 `maskedColumns`，MVP 返回拒绝错误；后续可加入专门脱敏样例能力。
|
||
|
||
### mysql_query
|
||
|
||
输入：
|
||
|
||
```json
|
||
{
|
||
"source": "sales_prod",
|
||
"sql": "SELECT c.name, COUNT(*) AS order_count FROM customers c JOIN orders o ON o.customer_id = c.id GROUP BY c.name ORDER BY order_count DESC LIMIT 20"
|
||
}
|
||
```
|
||
|
||
允许：
|
||
|
||
- `SELECT`
|
||
- 单数据源内的跨表 JOIN
|
||
|
||
禁止：
|
||
|
||
- 多语句。
|
||
- SQL 注释，包括 `--`、`#`、`/* ... */` 和 MySQL 版本注释。
|
||
- DML、DDL、DCL、事务和存储过程。
|
||
- `SELECT ... INTO OUTFILE`、`LOAD_FILE`、`SLEEP`、`BENCHMARK`。
|
||
- `SHOW`、`DESCRIBE`、`DESC`、`EXPLAIN` 自由 SQL。
|
||
- `UNION`、CTE、用户变量和临时表。
|
||
- 无限制返回大结果集。
|
||
|
||
输出：
|
||
|
||
```json
|
||
{
|
||
"columns": ["name", "order_count"],
|
||
"rows": [
|
||
{ "name": "A 客户", "order_count": 12 }
|
||
],
|
||
"rowCount": 1,
|
||
"truncated": false,
|
||
"elapsedMs": 38,
|
||
"sql": "SELECT ..."
|
||
}
|
||
```
|
||
|
||
## 8. SQL 安全策略
|
||
|
||
安全校验采用保守白名单规则。不要把 Skill prompt 当作安全边界，所有强制规则必须在 Tool/Service 层实现。
|
||
|
||
- 第一版优先采用 SQL parser 或词法 token guard；如果没有稳定 parser，就采用更严格的拒绝策略。
|
||
- 只允许单条 `SELECT`。
|
||
- 拒绝 SQL 注释，避免版本注释和注释夹带绕过。
|
||
- 拒绝包含分号的多语句。
|
||
- 拒绝非白名单开头语句。
|
||
- 拒绝 `UNION`、CTE、`INTO`、用户变量、临时表、危险函数和文件访问能力。
|
||
- 查询涉及的表必须全部落在 `allowedTables` 内，并且不在 `blockedTables` 内。
|
||
- SQL guard 必须逐个检查 `JOIN` 片段：每个显式 `JOIN` 在下一个 `JOIN`、`WHERE`、`GROUP BY`、`ORDER BY`、`LIMIT` 或语句结束前都必须出现 `ON` 或 `USING`。
|
||
- 自由 SQL 引用 `maskedColumns` 时直接拒绝，避免 alias 绕过。
|
||
- `SELECT` 必须限制行数；无 LIMIT 时后端包裹追加限制。
|
||
- 显式 LIMIT 必须不超过 `maxRows`。
|
||
- 查询超时默认 10 秒。
|
||
- 最大返回行数默认 200，硬上限 1000。
|
||
- 默认最大 JOIN 表数 4，硬上限 6。
|
||
- 拒绝无 `ON` / `USING` 的显式 JOIN，避免笛卡尔积。
|
||
- 错误信息只返回 SQLSTATE、errno/code 和固定短文案，不返回原始连接错误、连接密码、host、username 或完整连接串。
|
||
- 每次查询无论成功、失败或被拒绝，都写入审计记录。
|
||
|
||
这层只保证工具层安全，不负责判断业务 SQL 是否“正确”。业务口径由 Skill 和 Agent 交互处理。
|
||
|
||
## 9. 跨表 JOIN 策略
|
||
|
||
跨表 JOIN 是 MVP 能力。Agent 可生成多表 `JOIN`、`LEFT JOIN` 和聚合查询，但必须遵循 Skill 约束：
|
||
|
||
- 先调用 `mysql_schema` 获取相关表字段、索引和外键。
|
||
- 有外键时优先使用外键关系。
|
||
- 无外键时，可根据字段名、字段类型、索引和样例值推断关联字段。
|
||
- 推断关联必须在回答中标明，例如“orders.customer_id 与 customers.id 为字段名和样例推断关联”。
|
||
- 对不确定的关联关系或业务口径，必须先向用户澄清。
|
||
- JOIN 查询仍受 `mysql_query` 的只读、超时、LIMIT 和最大行数限制。
|
||
- JOIN 查询不得超过 `maxJoinTables`。
|
||
- `JOIN` 必须带 `ON` 或 `USING`，不允许隐式逗号连接。
|
||
- 每个 `JOIN` 都必须有自己的 `ON` 或 `USING` 条件，不能只检查整条 SQL 是否出现过一次 `ON`。
|
||
- 如果查询因超时或成本限制失败，Agent 应缩小时间范围、减少表数量、添加过滤条件或向用户澄清。
|
||
|
||
## 10. Skill 设计
|
||
|
||
新增 prompt skill：`packages/backend/skills/data-analyst-mysql/SKILL.md`。
|
||
|
||
Frontmatter：
|
||
|
||
```yaml
|
||
---
|
||
name: data-analyst-mysql
|
||
description: 使用 MySQL 工具进行只读智能问数，支持 schema 分析、跨表 JOIN、口径澄清和 SQL 结果解释。
|
||
version: 1.0.0
|
||
metadata:
|
||
skillType: llm
|
||
tags: [mysql, data-analysis, question-answering]
|
||
conditions:
|
||
requires_tools: ["mysql_list_sources", "mysql_schema", "mysql_query"]
|
||
---
|
||
```
|
||
|
||
Skill 指令要求：
|
||
|
||
- 先确认可用数据源。
|
||
- 先读取相关 schema，再写 SQL。
|
||
- 需要 JOIN 时先找外键、索引和样例值。
|
||
- 跨表 JOIN 不确定时先解释拟采用的关联字段，必要时澄清。
|
||
- 不确定业务口径时使用 `clarify`。
|
||
- 只执行只读 SQL。
|
||
- 回答必须包含结论、SQL、口径说明和限制。
|
||
- 不暴露连接地址、账号、密码。
|
||
- 不承诺“全量统计”除非 SQL 口径和过滤范围明确。
|
||
|
||
## 11. Tool Resolver 和 Runtime Policy
|
||
|
||
`tools/catalog.ts` 新增 `TOOLSET_MYSQL = 'mysql'`，并集中 import MySQL tool 文件。
|
||
|
||
MySQL 工具注册：
|
||
|
||
- `visibility: 'tool'`
|
||
- `capability: 'text'`
|
||
- `isCore: false`
|
||
- `canDisable: true`
|
||
|
||
主 Agent 可直接执行 MySQL 工具。子 Agent 默认不在 worker 本地执行 MySQL 工具，runtime policy 应将这类工具路由为 `main-process-proxy` 或 `disabled`。推荐第一版走 `main-process-proxy`，避免子进程持有数据库密钥。
|
||
|
||
## 12. 管理接口
|
||
|
||
新增 admin controller：`controller/admin/data_source.ts`。
|
||
|
||
接口：
|
||
|
||
- `GET /admin/netaclaw/data-source/list`
|
||
- `POST /admin/netaclaw/data-source/save`
|
||
- `POST /admin/netaclaw/data-source/test`
|
||
- `POST /admin/netaclaw/data-source/delete`
|
||
|
||
保存接口接受明文密码，但只用于加密保存。若编辑时密码为空，则保留原密码。
|
||
|
||
Agent 编辑页后续可接入授权配置，但 MVP 后端先支持 `allowedAgentIds` 字段和接口。
|
||
|
||
## 13. 测试策略
|
||
|
||
测试采用 TDD。
|
||
|
||
优先新增单元测试：
|
||
|
||
- `mysql_sql_guard.test.ts`：验证只读 SQL 白名单、危险关键字、多语句、`SELECT INTO OUTFILE`、`SLEEP` 拒绝。
|
||
- `mysql_sql_guard.test.ts` 还要验证 `SHOW`、`DESCRIBE`、`EXPLAIN`、注释、`UNION`、CTE、用户变量、无条件 JOIN、部分 JOIN 缺少 ON/USING、显式 LIMIT 超过 maxRows、查询脱敏列、超过最大 JOIN 表数被拒绝。
|
||
- `mysql_schema_mapper.test.ts`：验证 information_schema 行映射为表、字段、索引和外键结构。
|
||
- `mysql_query_service.test.ts`：用 mock mysql pool 验证 LIMIT 包裹、超时参数、结果截断和错误脱敏。
|
||
- `mysql_query_service.test.ts` 还要验证表级授权、脱敏列拒绝、审计写入、pool 复用和 `mysql_table_sample` identifier 白名单。
|
||
- `secret_crypto.test.ts`：验证数据源密码使用 AES-GCM 加密，密文不包含明文密码。
|
||
- `data_source_projection.test.ts`：验证管理端投影不返回密码，Agent 投影不返回 host/username/passwordEncrypted。
|
||
- `tool_resolver.test.ts`：验证 `mysql` toolset 可以被 Agent 启用，并在子 Agent runtime profile 中不走 worker-local。
|
||
- `entity_exports.test.ts`：验证新增 entity 导出。
|
||
|
||
不在单元测试里连接真实 MySQL。真实连接测试通过 admin `test` 接口和后续手工环境验证完成。
|
||
|
||
## 14. 分阶段交付
|
||
|
||
### Phase 1：后端最小闭环
|
||
|
||
- 新增数据源 entity、公共 secret crypto service、data source service。
|
||
- 新增 query audit entity。
|
||
- 新增公共 `SecretCryptoService`。
|
||
- 新增 `MysqlPoolManager`。
|
||
- 新增 MySQL SQL guard、schema mapper、query service。
|
||
- 新增四个工具：`mysql_list_sources`、`mysql_schema`、`mysql_table_sample`、`mysql_query`。
|
||
- 接入 catalog、resolver、runtime policy。
|
||
- 新增 `data-analyst-mysql` prompt skill。
|
||
- 补充单元测试。
|
||
|
||
### Phase 2：管理端配置
|
||
|
||
- 新增数据源管理接口。
|
||
- 前端工具管理或 Agent 编辑页接入数据源授权。
|
||
- 支持测试连接和编辑密码。
|
||
|
||
### Phase 3：问数体验增强
|
||
|
||
- 根据真实问数记录优化 Skill。
|
||
- 增加 query result 前端结构化渲染。
|
||
- 增加审计日志查询页和慢查询提示。
|
||
|
||
## 15. 验收标准
|
||
|
||
- 管理员可以配置一个 MySQL 数据源并授权给指定 Agent。
|
||
- 数据源密码以 AES-GCM 密文保存，接口不回显密文或明文。
|
||
- 启用 `mysql` toolset 的 Agent 能列出授权数据源。
|
||
- Agent 只能读取授权表的 schema、字段、索引和外键。
|
||
- Agent 能读取授权表的少量样例。
|
||
- Agent 能执行只读 SELECT 查询。
|
||
- Agent 能执行同一数据源、授权表范围内的跨表 JOIN 查询。
|
||
- `SHOW`、`DESCRIBE`、`EXPLAIN`、多语句、注释、写入语句、无条件 JOIN 和超出 JOIN 表数限制的 SQL 被拒绝。
|
||
- 查询或样例请求命中 `maskedColumns` 时，MVP 后端拒绝执行，避免 alias 绕过；后续如引入 SQL parser 再实现安全脱敏返回。
|
||
- 每次查询写入审计记录。
|
||
- 危险 SQL 被拒绝，错误原因可读且不泄漏连接秘密。
|
||
- Agent 绑定 `data-analyst-mysql` skill 后，回答包含结论、SQL、口径和限制。
|
||
- 单元测试覆盖 SQL guard、schema mapper、query service、secret crypto、pool manager、tool resolver 和 entity 导出。
|