> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 数据库 AI 助手实战指南（4.0 核心特性）

**数据库 AI 助手（Database AI Assistant）** 是 Yearning v4.0 推出的核心增效能力：它以右下角悬浮入口（`dots-02` 图标，亦支持独立页 `/assistant`）常驻工作台，严格聚焦在 **「平台使用咨询」「基于真实元数据的自然语言生成 SQL」「SQL 分析与优化」** 三项数据库任务上。

与通用聊天机器人不同，Yearning AI 助手在架构层面贯彻 **零泄漏单轮内存脱敏、方言 AST 结构化还原、零直接执行 SQL、强制衔接正式 AI 预审与审批门禁** 四条硬边界，让研发既能用自然语言秒出合规 SQL，又不突破生产数据安全红线。


![登录工作台后点击右下角悬浮触发器即可唤出受控数据库 AI 助手面板（适配桌面悬浮抽屉与移动端全屏 Sheet）](/screenshots/dashboard-zh-CN-dark.png)

登录工作台后点击右下角悬浮触发器即可唤出受控数据库 AI 助手面板（适配桌面悬浮抽屉与移动端全屏 Sheet）

## 1. 三大核心能力与真实使用示例

### 能力一：角色感知的平台操作与报错咨询（`platform_help`）

内置知识库与当前 Yearning v4 版本严格同步，并按登录身份自动过滤（普通用户只看工作台业务操作，管理员额外检索 `/admin/*` 后台配置指南）。回答附带步骤清单、来源引用以及**可点击的站内页面直达按钮**。

**直接这么问**：

- _"我提交变更工单报错 `2008` 和 `2001` 是什么原因？怎么解决？"_
- _"如何申请生产库的只读查询权限，顺便开通导出？"_
- _"（管理员）怎么把内网 vLLM 部署的本地模型配置成 `san` 原生轨道？"_

***

### 能力二：自然语言生成 SQL + 两阶段直连变更工单（`sql_generate`）

当你知道目标库表和要写入/查询的业务内容，却不想手工核对几十个列的字段名、类型、非空约束和方言引号时，可直接把业务描述交由助手生成并衔接提单：

**真实操作流程（以「插入一条新仓库记录并提单」为例）**：

1. **打开助手并描述需求**：
   > _"帮我往 `prod-erp` 数据源 `erp` 库的 `warehouses` 表插入一条新记录：华东一号冷链仓，编码 `WH-EC-001`，联系人张明，电话 `13800138000`，地址上海市浦东新区XX路88号。生成 SQL 并帮我准备提单。"_
2. **服务端前置鉴权与受控元数据探测**：
   - 系统先校验你是否拥有 `prod-erp` 的权限：**仅持有只读 Query 授权只能生成 `SELECT`，持有 `change_review` 流程授权才允许生成 DML/DDL**（无权统一返回 `6002`，不泄露数据源或表是否存在）。
   - 鉴权通过后，服务端调用只读 Metadata Tool 自动拉取 `warehouses` 表的列定义、类型、`NOT NULL` 约束、默认值/自增标记与主键/索引。
3. **缺必填列时主动追问（绝不瞎编值）**：
   - 如果 `warehouses` 表存在 `NOT NULL` 且无默认值/非自增的字段（如 `region_code`），而你的描述里没提供，助手会暂停生成草稿并列出缺失字段清单请你补充，绝不自行猜测编造。
4. **单轮内存脱敏 → 模型生成 → 方言 AST 校验与安全还原**：
   - 在公有云 `default` 轨道下，表名、列名和你的业务敏感值（仓库名、姓名、电话、地址）会被全部替换为匿名标识（`table_1`、`column_1`）与类型化占位符（`:val_str_1`、`:val_str_2`）后发往模型；模型返回后由服务端做方言语法解析、授权表列校验与类型安全还原，最终在面板输出带 **`draft_id` + `revision` + `sql_hmac`** 的完整 SQL 草稿卡片。
5. **两阶段确认提单（绝不跳过正式门禁）**：
   - **第 1 步（触发正式 AI 预审）**：在 SQL 卡片上核对目标数据源、Schema 与还原后的完整 SQL，点击 **执行正式 AI 预审**（调用 `POST /api/v4/ai-assistant/sessions/{session_id}/drafts/{draft_id}/precheck` -> `StartEphemeralRun`），完整走一遍平台确定性规则 + AI 预审引擎。
   - **第 2 步（确认提交工单）**：仅当绑定当前草稿版本和 `sql_hmac` 的预审达到 **`ready`** 且零 `Critical` 阻断项时，**确认提交变更工单** 按钮才亮起；点击后以 `Idempotency-Key` 幂等调用 `SubmitOrderV2` 创建正式工单，并返回真实工单号（`display_number`）与详情页跳转链接。

:::warning 修改 SQL 或切换流程后必须重新预审
只要你编辑了草稿 SQL、切换了目标数据源/审批流程或权限发生变化，旧预审绑定立即失效（提交会拦截 `6005 ASSISTANT_DRAFT_REVISION_STALE`），必须重新点击 **执行正式 AI 预审**。
:::

***

### 能力三：结合真实表结构的慢 SQL 分析与优化（`sql_optimize`）

把线上慢 SQL（以及可选手工粘贴的 `EXPLAIN` 执行计划文本）直接贴给助手并指定数据源：

1. 服务端自动解析 SQL 涉及的库表，拉取授权范围内的真实列类型、索引顺序与约束，统一脱敏后送入模型。
2. 助手输出优化后的改写 SQL（经方言 AST 校验还原）、改动理由、风险提示与待验证项。
3. **严守诚实边界**：
   - 助手**绝不会**对生产库自动跑 `EXPLAIN` 或 `SELECT`，也绝不编造「耗时下降 80%」这类未经实测的数据。
   - 如果改写可能改变 `NULL` 行为、去重结果或过滤边界，助手会显式标出 **语义差异警示**，绝不冒充等价优化。

***

## 2. 零泄漏隐私链路与双轨协同原理

```text
用户输入（含真实表名、业务敏感文本、SQL）
        │
        ▼
[1] 服务端权限校验 + 受控只读元数据读取（绝不读业务表行数据）
        │
        ├── default 轨道（公有云模型）
        │     ├─► RunMapper：库/表/列 -> schema_1 / table_1 / column_1
        │     ├─► TurnValueMapper：业务字面值 -> :val_str_1 / :val_int_1
        │     └─► AssertNoLeak 断言（仅驻留单次 HTTP 请求内存，请求结束立即销毁）
        │
        └── san 轨道（内网自部署 vLLM / Ollama）
              └─► Raw-SQL 本地原生精简契约（>256 字符字面值截断，严禁回退泄露给公有云）
        │
        ▼
[2] 方言 Lexer/AST 解析 + 对象越权校验 + 占位符类型核对 + IdentifierQuoter 结构化还原
    （严禁全局字符串替换拼装 SQL；发现未知占位符或越权表列直接 Fail-Closed 报错 6004）
        │
        ▼
[3] AES-256-GCM 加密持久化会话与不可变草稿快照（draft_id + revision + sql_hmac）
```

## 3. 会话持久化、自动压缩与配额管理

| 特性            | 精确规则与配额                                                                                                              |
| :------------ | :------------------------------------------------------------------------------------------------------------------- |
| **加密落库与保留期**  | 所有历史消息、SQL 草稿与压缩摘要均以 **AES-256-GCM** 加密保存（刷新浏览器可续聊），默认保留 **30 天**                                                    |
| **单用户会话上限**   | 最多 **50 个活跃会话**（超限返回 `1012`；删除旧会话立即释放额度并物理擦除对应密文消息与草稿）                                                               |
| **单会话消息上限**   | 最多 **100 轮消息**；也可随时输入 `/clear` 或新建会话开启干净上下文                                                                          |
| **超预算自动脱敏压缩** | 当长对话接近模型 Token 上限时，服务端自动把较早轮次通过**脱敏调用**压缩为结构化摘要（`ai_assistant_context_summaries`，仅含目标、决定与草稿引用，不含业务明文值），界面仍保留完整历史供你翻看 |
| **流式中止**      | 输出期间点击 **停止（Stop）** 立即中止生成（同一会话流式输出未结束前重复发送返回 `6007`）                                                                |

## 4. 严禁边界与 `60xx` 错误码速查

为了守住生产数据库安全底线，AI 助手在代码层强制执行以下 5 条不可绕过禁令：

1. **不陪聊**：拒绝数据库与 Yearning 之外的通用闲聊、写诗、通用编程或运维脚本请求（`6001`）。
2. **不执行**：绝不在目标库上执行任何 `SELECT`、`EXPLAIN`、DML 或 DDL。
3. **不看行数据**：不采样、不读取、不返回任何业务表行数据。
4. **不生成高危破坏语句**：禁止生成 `TRUNCATE`、`DROP DATABASE`、`DROP SCHEMA`、`GRANT`/`REVOKE` 与存储过程/触发器。
5. **不绕门禁**：草稿绝不等同于预审通过，提单必须重新鉴权并走通正式 `StartEphemeralRun` + `SubmitOrderV2`。

| 错误码    | 含义                                  | 排查与解决                                                              |
| :----- | :---------------------------------- | :----------------------------------------------------------------- |
| `6001` | `ASSISTANT_OUT_OF_SCOPE`            | 问题超出数据库/Yearning 范畴，或请求了 `TRUNCATE`/`DROP DATABASE` 等禁止语句          |
| `6002` | `ASSISTANT_DATASOURCE_FORBIDDEN`    | 对目标数据源无权访问，或仅持只读查询授权却要求生成 DML/DDL（需管理员在权限组授予对应 `change_review` 流程） |
| `6003` | `ASSISTANT_ANONYMIZATION_FAILED`    | 输入文本疑似包含原始密码、API Key（如 `sk-`）或完整 DSN 连接串，移除敏感凭据后重试                 |
| `6004` | `ASSISTANT_SQL_RESTORATION_INVALID` | 模型输出未通过方言 AST 校验、引用了未授权对象或存在未绑定占位符，点击重试或补充明确表名                     |
| `6005` | `ASSISTANT_DRAFT_REVISION_STALE`    | 草稿 SQL 被修改或尚未跑完正式预审，在草稿卡片点击 **执行正式 AI 预审**                         |
| `6006` | `ASSISTANT_CONTEXT_BUDGET_EXCEEDED` | 单轮粘贴的 SQL 或执行计划超出上下文 Token 预算，精简输入或新建会话                            |
| `6007` | `ASSISTANT_STREAM_IN_PROGRESS`      | 当前会话正在流式回复，等待结束或点击 **停止** 后再发下一条                                   |
