For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /features/ai-assistant.md.
  • 简体中文
  • 数据库 AI 助手实战指南(4.0 核心特性)

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

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

    登录工作台后点击右下角悬浮触发器即可唤出受控数据库 AI 助手面板(适配桌面悬浮抽屉与移动端全屏 Sheet)
    登录工作台后点击右下角悬浮触发器即可唤出受控数据库 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)与详情页跳转链接。
    修改 SQL 或切换流程后必须重新预审

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


    能力三:结合真实表结构的慢 SQL 分析与优化(sql_optimize)

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

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

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

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