# AI 助手 > 配置云端、兼容 API 或本地 CLI 模型，在 Schema 上下文中生成 SQL、分析数据并执行受控 Agent 工作流。 Source: https://dbxio.com/cn/docs/ai-assistant Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/ai-assistant. AI 助手把当前会话绑定的连接、数据库和 Schema，与编辑器 SQL、错误、结果预览和用户点名的对象组合成上下文，用于生成 SQL、解释查询、优化语句、修复错误和分析数据。每个会话各自持有绑定，使用不同连接的会话互不串用目标。 Ask 模式只生成建议；Agent 模式在用户明确要求真实数据时可以调用查询工具。任何模型输出都可能错误。执行 SQL 前仍应检查目标连接、字段、过滤条件、参数和影响范围。 ## 支持的模型接入方式 ### API 供应商 DBX 内置以下配置预设： * Claude * OpenAI * Gemini * DeepSeek * Qwen * MiniMax * Ollama * OpenAI Compatible * Anthropic Compatible * Custom 兼容或自定义配置可以设置端点、模型、API 风格、认证方式、代理、上下文窗口和额外 HTTP 请求头。API 风格包括 OpenAI 风格 completions、Responses API 和 Anthropic Messages。供应商支持时，DBX 会读取模型列表并过滤掉不适合对话/Agent 的模型。 ### 本地 CLI Agent Desktop 还可以直接调用已安装并登录的： * Claude Code CLI * Codex CLI * Pi Coding Agent 可以配置可执行文件路径和额外环境变量。CLI Agent 运行在 Desktop 所在电脑，并通过 DBX 提供的受限 MCP 工具访问当前数据库。Docker/Web 不会显示这些本机 CLI 供应商，因为服务器不能假设浏览器电脑上安装了对应命令。 ## 添加配置 ### 打开 AI 设置 在编辑器设置中进入 AI，添加一个命名配置。可以为同一供应商保存多套端点或凭据。 ### 选择供应商和模型 使用预设、兼容 API、自定义端点或本地 CLI。模型列表可发现时从供应商或本地 CLI 读取，也可以手动填写。手动填写的模型会保存到当前配置；当兼容供应商未提供模型发现接口或发现失败时，已保存的模型仍可选择。 ### 配置认证和推理参数 API 模式填写 API Key、认证方式、端点、代理和自定义 HTTP 请求头。请求头可用于网关认证或租户路由，例如 `X-GoModel-User-Path: /dbx-assistant`；模型发现、连接测试、对话和 Agent 请求都会携带它们。支持的模型可以选择 effort、reasoning 或 thinking；具体选项来自供应商能力，而不是对所有模型统一显示。 ### 测试并保存 测试会报告成功、延迟、实际模型和认证、限流、超时、模型不存在等错误类别。 API Key、自定义请求头的值、CLI 环境变量和自定义端点可能具有敏感性。不要把设置截图、导出的配置或调试日志发送到不可信位置。 ## Ask 和 Agent | 模式 | 适合任务 | 工具和执行行为 | | ----- | ---------------------------------- | ----------------------------- | | Ask | 生成、解释、优化、修复、转换 SQL，或基于已有上下文给建议 | 不主动执行数据库查询；最终答案应明确区分建议和已验证结果 | | Agent | “查出结果”“对比真实数据”“先看表结构再回答”等需要迭代取证的任务 | 可以列表、读字段、取样和执行只读查询；写入必须经过精确确认 | Agent 只有在原始请求明确要求真实数据/结果时才应执行查询。仅要求“写一条 SQL”时，即使处于 Agent 模式，也应返回 SQL 而不是自动运行。 ## Agent 轮次和重试 * **最大 Agent 轮次**：默认 30，可配置 5–500。它限制模型、工具调用和修复循环的总轮数，防止复杂任务无限运行 * **最大 API 重试次数**：默认 2，可配置 0–10。只用于限流、超时和临时网络错误；Claude Code、Codex 和 Pi CLI 不使用这个 API 重试设置 * 达到轮次上限、用户取消、连接失败或工具策略拒绝时，Agent 会停止并保留已有步骤和错误 提高轮次上限会增加时间、数据库读取次数和模型成本。应先通过明确提示、表提及和缩小任务范围减少无效探索。 ## Schema、表和 SQL 文件上下文 AI 上下文可以包含： * 数据库类型、连接名称、数据库和 Schema * 当前编辑器 SQL、最近错误（编辑器与会话绑定在同一连接和数据库上时才纳入），以及显式发送过来的编辑器选区 * 表、字段、索引、外键和少量样例数据 * 当前结果集的有限预览 * 用户选择的提示模板 * 被提及的保存 SQL 文件内容 在输入框键入 `@` 可以搜索表和保存的 SQL 文件： * `@users`：优先加入 `users` 的元数据 * `@public.orders`：指定 Schema 中的表 * 同时选择多张表或 SQL 文件：把相关上下文一起交给模型 ### 从编辑器发送选区到 AI 在 SQL 编辑器中选中文本后，右键选择 **发送到 AI**（或使用对应快捷键），选区会以可移除的芯片出现在 AI 输入框上方，输入框保持为空并聚焦，由你输入真正的问题。选区按**数据**处理而不是指令：SQL 注释里写的“忽略以上指令”不会被当作命令执行。 会话目标取自选区所在的编辑器标签页： * 与当前会话绑定共用同一个连接、数据库（和 Schema）时，复用当前会话 * 不同时新建一个会话并绑定到该标签页，已有会话的绑定不会被改写 * 该标签页的连接已被删除时会话保持未绑定并给出提示，需要你手动选择连接 单个选区上限 12 000 字符，超出会截断并在芯片上标明“已截断”。查询结果报错处的 **用 AI 修复** 使用同一套规则。 完整 Schema 过大时会截断。表提及比让模型在所有对象中猜测更可靠，也能减少 token 和元数据请求。 ## 全局指令和提示模板 设置中可以维护： * **全局指令**：每次 AI 请求都注入，例如命名规范、时区、软删除字段和生产约束 * **提示模板**：按场景保存可复用规则，例如“只生成 PostgreSQL 兼容 SQL”或“分析必须包含索引建议” 助手中可以同时选择多个模板。DBX 在发送时冻结当前全局指令和模板快照，因此请求开始后修改设置不会改变已经运行的任务。 模板会进入模型上下文，应避免放入密码、令牌或不必要的业务数据。规则冲突时，模型未必能按预期选择优先级，应保持全局指令和模板简短、明确且互不矛盾。 ## Skills（SKILL.md） Desktop 可以把只读的 [`SKILL.md`](https://developers.openai.com/codex/skills) 规则文件作为补充性指令附加到请求中。技能始终从 `~/.agents/skills` 发现；设置 → AI 中还可以额外启用一个自定义目录。两个目录独立校验，同名技能并列保留并标注来源（`默认目录` / `自定义目录`），自定义目录的技能排在前面。 在输入区的 `Skills` 入口（或输入 `/skill`）选择技能，选中项以芯片形式显示在输入框上方，可随时移除。选择的生命周期是一个打开的 AI 面板：切换会话、新建会话都会保留；关闭面板或重启 DBX 即清空。选择不会持久化，DBX 也绝不写入技能文件。 技能正文只在发送时从磁盘读取，并当场校验：文件被删除或不可读、frontmatter 无效、不是 UTF-8、超过单文件 1 MiB 上限、符号链接逃逸出所在目录，都会阻断发送，并在输入框上方显示横幅，标明失败的技能并提供重试、刷新、移除或打开设置等恢复操作。未选择任何技能时，提示词与既有行为逐字节一致。Web 端不提供该功能。 ## 插件工具 使用 API 供应商的 Agent 模式下，助手还可以调用已安装插件提供的工具——例如通过 SSH 执行命令、读取容器日志、查看 Kafka 消费延迟——并与数据库工具结合起来回答同一个问题。 1. 插件工具按插件显式开启：打开「插件中心 → 已安装」选中插件，开启 **内置 AI 工具** 开关后助手才能调用其工具；点击 **查看工具** 可以看到助手能用哪些工具、以及哪些需要确认；关闭开关即可排除某插件（选择会持久保留）。 2. 打开助手要使用的插件连接（例如那台 SSH 服务器）。工具只会作用于已打开的连接。 3. 在 Agent 模式下提问。插件声明为只读的工具会直接执行；其他调用会暂停运行，并展示完整参数，由你选择 **允许本次** 或 **拒绝**。五分钟未响应视为拒绝，点击停止会取消等待中的请求。 绑定插件连接时，输入框显示插件图标，并隐藏数据库和 Schema 选择器。AI 不再加载数据库表结构，Agent 模式仅保留时间工具与已启用的插件工具。关闭插件的内置 AI 工具开关，也会阻止正在进行的会话继续调用该插件。 工具输出会像查询结果一样发送给你配置的 AI 模型；不希望数据发给模型的插件，请关闭其 **内置 AI 工具** 开关。CLI Agent 供应商不会获得插件工具。 ## 写入和生产安全 AI Agent 的执行边界是后端强制的，不只是提示词： 1. 只读工具可以按任务调用 2. 非只读 SQL 必须先作为明确的 SQL 提案展示 3. 用户确认后，授权只绑定到同一连接、同一数据库和完全相同的 SQL 文本 4. 授权只对下一次运行有效，不会变成永久写入权限 5. 生产数据库上的写入和 DDL 不会授权给 AI Agent；模型只能返回 SQL 供用户在 DBX 中人工审阅执行 连接只读保护、生产保护和数据库账号权限仍是上限。即使用户确认，目标变化、SQL 变化、空确认或后端风险分类不通过都会使授权失效。 Redis 连接改用只读命令工具，而不是 SQL。助手可以执行 DBX 判定为只读的命令（`SCAN`、`GET`、`TYPE`、`TTL`、`HGET` 等）并基于结果回答。写命令或被拦截的命令（`SET`、`DEL`、`EXPIRE`、`EVAL`、`KEYS`、`CONFIG` 等）AI Agent 永不执行：它会把命令作为代码块返回，由你在 Redis 控制台中执行，控制台会先要求确认。`SELECT` 同样不可用，逻辑数据库通过工具的 `db` 参数选择。 AI Agent 不会获得“以后都可以写”的授权，也不会绕过 MCP 策略、连接只读保护或数据库权限。更多边界见 [生产环境安全](/cn/docs/production-safety) 。 ## 推理强度和 Thinking 不同供应商使用不同机制：枚举 effort、reasoning level、布尔 thinking、整数预算或自定义文本。DBX 按当前模型能力展示可用选项，并记住每个配置/模型的选择。 * 简单生成或解释可使用供应商默认或较低强度 * 多表推理、复杂优化和错误诊断可提高强度 * 更高强度通常增加延迟和费用，但不保证答案正确 不要把 UI 中的统一标签理解为所有供应商拥有相同推理语义。 ## 对话、历史和导出 * 输入框支持使用 ↑ / ↓ 浏览当前提示历史 * 每个会话按自身的连接、数据库和 Schema 绑定保存，重新打开时恢复该绑定 * 每条最终 AI 分析可以导出为 Markdown，文件包含连接名、时间和最终回答 * Markdown 导出只包含最终分析内容，不会把内部 reasoning 或 Agent 步骤附加到文件中 导出内容仍可能包含表名、SQL、结果片段和业务数据，分享前请审阅和脱敏。 ## 常见任务 ### 生成 SQL > 根据 `@orders` 和 `@customers` 生成最近 30 天客户销售额 Top 10 查询，只返回 SQL，不执行。 明确写出“不执行”可以让意图更清晰。检查时间函数、Schema 限定、JOIN 键、空值和返回行数。 ### 分析真实数据 > 查询 `@orders` 最近 7 天每天的订单数，执行只读查询并解释异常峰值。 这类请求适合 Agent 模式，因为它明确要求真实结果。 ### 修复错误 把失败 SQL、数据库错误和涉及的表一起提供。AI 可以读取字段和方言信息，但版本特有行为、权限、锁和运行计划仍需人工验证。 ## 隐私和故障排查 * 云端供应商会收到发送给模型的提示、Schema 摘要、SQL 和有限结果上下文；以供应商隐私条款为准 * Ollama 和本地 CLI 可以在本机运行，但模型进程和 CLI 插件仍可能有自己的联网或日志行为 * 代理、兼容端点和自定义网关可能记录请求内容 * 测试失败时先检查端点、认证方式、模型名、代理和模型是否支持当前 API 风格 * Agent 反复失败时减少上下文、点名目标表、降低任务范围，并查看具体工具错误，而不是只提高轮次上限 ## 相关功能 ### [生产环境安全](/cn/docs/production-safety) 查看 AI、MCP、只读连接和生产保护的统一边界。 ### [MCP 集成](/cn/docs/mcp) 让外部 AI 编程助手通过 DBX 访问数据库。 ### [SQL 编辑器](/cn/docs/query-editor) 了解 AI 所使用的当前 SQL、结果和元数据上下文。