产品功能：数据连接与预定义查询

工作区管理员配置数据连接（MySQL / PostgreSQL / SQLite）后，成员可在消息里让工作智能体查业务数据（只读查询为主），并在授权范围内执行受控变更（增删改，可配置审批）。本页说明预定义查询是否必须、表预览行数限制、与工作区技能里写表定义的关系，以及怎样配才又快又准。

来源 help/product-features/data-integration.md

表述：工作区管理员配置 数据连接（MySQL / PostgreSQL / SQLite）后，成员可在消息里让工作智能体 查业务数据（只读查询为主），并在授权范围内执行 受控变更（增删改，可配置审批）。本页说明 预定义查询是否必须、表预览行数限制、与 工作区技能 里写表定义的关系，以及怎样配才 又快又准。

入口：工作区协作 → 助手能力包 → 数据连接（整页管理，与知识文档目录相同）。

子页	用途
数据连接	连接库、允许表、预定义查询、行与字段策略
数据资源	把表与查询打包，供授权引用
谁可以使用	成员能访问哪些数据资源、读/增/改/删权限
变更定义	受控 insert / update / delete 及是否需审批
变更审批	待审批列表与历史记录（管理员）

开通前提（须同时满足）：

平台：运维在 mindlink.json 打开 data_source_tool.enabled（见服务端配置）。
工作区：管理员在 助手能力包 中开通 数据连接（未开通或已到期时，对话里无法查库）。
成员：在 谁可以使用 中授权对应 数据资源（读；变更还须增/改/删权限）。

按样例图做统计图 / 报表时

工作区已开通 数据集成，且成员有权查库时：

数字：以数据连接查询结果为准（助手调用预定义查询等）。
附图：一般只当版式、配色、引线位置的参考，不要把图上的人数、占比抄进正式报表。
例外：你明确说「按这张截图数字化 / 从图里抄数」，或当前没有可用连接时，才可按画面数字出图。

口径不清楚时（例如是否含外包、按哪一级部门汇总），助手应 先问清一轮，确认后连续出图或报表，避免反复确认。

在对话里添加数据连接（工作区管理员）

已开通 数据集成 且平台开启数据连接后，工作区管理员 可在 帮助智能体（右下角浮动窗口或「消息」页）或 工作智能体 对话中，直接说明或粘贴连接信息，系统会：

解析连接参数（MySQL/PostgreSQL：主机、端口、库名、用户名、密码；SQLite：数据库文件路径）
测试连接
保存到本工作区的数据连接
可选 生成查询技能，便于后续在消息里问数

示例（把占位换成真实值即可发送）：

请根据以下内容帮我添加新的数据连接：
数据库：
host: 183.234.85.86
port: 3306
username: root
password: ****
dbname: caretop

SQLite 示例：

请添加 SQLite 数据连接，文件路径：D:/code/mindlink/examples/hr-multi-tenant/server/data/hrms.db

须 先选好顶部工作区；支持 MySQL/MariaDB、PostgreSQL 与 SQLite。连接失败时会提示核对信息；也可到 工作区协作 → 助手能力包 → 数据连接 手动填写。

在对话里管理已有数据连接（工作区管理员）

除 新建连接 外，管理员还可在 帮助智能体（推荐右下角浮动窗口，人还在设置页）或 工作智能体 中用自然语言 查看、修改、删除 数据集成配置。例如：

你说	系统会做
「当前有几个数据连接」「已设置的数据连接」	列出本工作区全部连接及预定义查询、数据资源数量
「查看 xxx 连接详情」	展示该连接的允许表、预定义查询、数据资源、变更定义、行与字段策略
「给 xxx 生成行与字段策略：员工只能看自己」	按说明生成并保存谁能看哪些记录、哪些列
「在 xxx 连接加一条按日期查订单的预定义查询」	追加或更新预定义查询（仅 SELECT）
「删除 xxx 连接上的 query_id 查询」	从连接配置中移除指定预定义查询
「在 xxx 下新建数据资源 HR，包含表 a,b」	创建或更新数据资源
「给成员张三开通 HR 数据资源的读权限」	在谁可以使用中设置读/增/改/删授权
「列出 xxx 连接的变更定义」	展示受控 insert/update/delete 定义

信息不足时会追问（如未指明连接名、成员或查询 id）；与数据集成无关的问题仍走普通对话。添加新连接请直接粘贴 host、库名、账号与密码。

能做什么

成员在对话中，智能体可通过受控工具访问已授权的数据连接，常见动作包括：

动作	用途
查看可访问的表	了解有哪些业务表
查看表字段	了解列名与类型
表预览	快速看某张表的前若干行样例（未筛选）
预定义查询	按固定业务口径、带条件地取数（如按部门、按日期）
受控变更	按变更定义写入、修改或删除记录（须单独授权；可需审批）

照片与二进制字段：业务库里的员工照片等图片字段（BLOB）会自动保存为可下载附件。对话里可直接看到照片链接；写入 Word/PPT 时可用同一附件编号嵌入。

智能体不能在对话里临时拼任意 SQL；带条件的查询须通过 预定义查询 执行，写入类操作须通过 变更定义。

工作智能体保存预定义查询

仅工作区管理员 可在消息里通过 工作智能体 新增、更新或删除 预定义查询（例如探明表结构后把 SQL 固化下来，便于后续按查询 id 复用）。可说「把这条查询保存为 xxx」「删除 xxx 连接上的某条查询」等，由智能体调用受控工具完成。

普通成员不能改查询配置，只能在已授权范围内查数（表预览、预定义查询执行等）。无管理员身份时，工具会提示「仅工作区管理员可管理预定义查询」。

#### 对话里补充查询（缺匹配时）

用户问 统计、查重、按条件筛选、查证件号 等，而 query.list 没有对应查询时，智能体应走 「建议 → 确认 → 保存 → 执行」，而不是用 表预览 下「有/没有、多少个」的结论：

步骤	说明
1. 提议	说明用途，给出只读 `SELECT`、建议的查询 id、参数含义；SQL 参数用 `?` 占位（`params` 顺序与 `?` 一致），勿用 `@empName` 等形式
2. 等确认	用户明确表示同意（如「可以，加上并查」）后再保存
3. 保存并查	管理员 `query.upsert`，同一会话内立即 `query.run` 给出结果
4. 禁止	未确认前不要写入连接；不要用表预览代替全库统计或按姓名筛选

普通成员 不能保存查询：应给出 SQL 建议，请用户联系 工作区管理员 或在 数据集成 表单中配置。

须同时满足：

条件	说明
工作区已开通数据集成	与查数相同
当前用户为工作区管理员	普通成员无法保存或删除
SQL 仅 SELECT	平台校验，禁止写入类语句
查询 id 唯一、稳定	建议 snake_case，如 `unpaid_employees_by_period`

#### 谁有「管理预定义查询」的资格？

身份	能否在对话里增删改预定义查询
工作区管理员	能
普通成员（含已获数据资源读授权）	不能（仅可查数）
非本工作区成员	不能

读权限与改查询已分离：在 谁可以使用 中勾选读，只表示能在对话里执行已有预定义查询与表预览，不包含 新增或修改查询定义。

#### 三种配置入口（均为管理员）

入口	能做什么
工作智能体对话	在授权范围内增删改预定义查询
帮助智能体自然语言	列出/查看/改连接、批量改查询、管数据资源与成员授权、按已勾选对象生成并写入行与字段策略
数据集成表单	编辑连接分三个标签：连接、预定义查询、行与字段策略（先选表/视图再生成、查看 / 设置 / 测试）

#### 管理员须知（共享配置）

预定义查询保存在 整条数据连接 上，对工作区内 已授权可见该查询的成员 生效。修改或删除某条查询会影响所有依赖该 查询 id 的问数场景，建议在 数据集成 统一维护核心口径，改完后 点保存（必要时 生成技能 同步说明）。

行与字段策略（谁能看哪些记录、哪些列）

把助手 嵌入到已有业务系统（如人力资源）时，查数不能只靠「技能里写一句别越权」——须在 数据连接 上配置 行与字段策略，查数时强制生效。

你要限制的	策略做什么
行（只能看自己 / 下属 / 本租户）	按当前登录身份，把参数强制写成该人的员工编号、下属名单、租户等；模型改不掉
列（不给看薪资、银行卡）	结果里只保留允许的列，或去掉敏感列

在界面里：打开 数据连接 → 编辑已保存的连接 → 行与字段策略。

操作	说明
查看 / 设置	结构预览可折叠阅读，也可切到「编辑源码」。键名以本连接预定义查询和表列为准，身份占位符写在值里（如 `{{host_actor.employee_id}}`）
测试验证	选模拟身份、填对应账号，看会匹配哪条规则、强制什么参数、留下哪些列。可对库试跑。详见下方
先选表/视图再生成	点生成策略打开对话框，连库列出表、视图和函数。勾选后点生成所选，只分析这些对象的真实字段。已有策略的默认隐藏。函数不能设行策略，勾选后仅用于补预定义查询
按策略补预定义查询	已有策略但还缺按人筛选的查询时，按策略里的强制参数自动补 SELECT（不改写未点名的旧查询）

测试验证

先保存数据连接，再在 行与字段策略 里测。选一条预定义查询（或填表名），勾选「同时对库试跑」后，在账号、表名或任一测试参数框里 按回车 即可试跑（中文输入法选字时的回车不会误触发）。

模拟身份填谁的账号（填业务系统里的登录账号，不是 Cadau 工作区成员）：

模拟身份	填什么	试跑时怎么用
员工自助	该员工的工号或登录账号	按「本人」匹配规则。登录账号会传给查询里的账号类参数；工号类参数按同一值预填
主管	该主管的登录账号	按主管规则匹配。账号记在登录用户编号上，不会当成员工档案编号。若要验证「只能看下属」，再填下属工号（多个用逗号分隔）
管理员	该管理员的登录账号	按管理员规则匹配。同样只记登录用户编号，不预填工号

Cadau 不会去业务系统反查「这个主管有哪些下属」。正式嵌入时，下属名单由业务系统随登录身份带过来；这里测试要自己填下属工号，或在测试参数里改。

多个参数：查询声明了几个参数，测试里就显示几格，可分别填写。账号类参数（如 account、login）会预填上面填的登录账号；主管的工号类参数按「下属工号」预填。某一格留空，则用策略展开的强制参数。

用变量填参数（与策略里的写法相同）。可填库里的真实值，也可整格写成变量，试跑时按当前模拟身份展开：

写成	展开成
`{{host_actor.external_user_id}}` 或 `host_actor.external_user_id`	上面填的登录账号（主管 / 管理员就是这个）
`{{host_actor.employee_id}}` / `{{host_actor.emp_no}}`	员工档案编号 / 工号（仅员工自助会有）
`{{host_actor.managed_employee_ids}}`	下属工号，逗号拼接
`{{host_actor.tenant_external_id}}`	租户编号

两种写法都行：带花括号的 {{host_actor.external_user_id}}，或整格只写 host_actor.external_user_id。句子里偶尔出现这段文字不会被误替换。不认识的变量名会展开成空。结果里的「实查使用参数」显示的是展开后的值。

例如查询有 account、empNo 两格：account 填 {{host_actor.external_user_id}}，empNo 填真实工号或 host_actor.managed_employee_ids。

要不要同时改预定义查询：只藏列（如薪资）不必改。要按人收窄行时，查询 SQL 里须已有对应筛选参数；没有时，生成策略会自动补，也可点 按策略补预定义查询。补上的是新查询（或只改策略里点名的那几条），不会改写其它未点名的旧查询。

须 先保存数据连接 再配策略。嵌入场景建议同时做到：须携带当前登录身份、对不上规则则拒绝访问。

成员授权（谁可以使用）决定「能不能用这条连接」；行与字段策略决定「用的时候能看到哪几行、哪几列」。二者都要配。

表预览与行数限制

表预览 每次从表中取 前 N 行（按数据库默认顺序），不做筛选，适合认字段、看样例，不能替代按条件问数或全表统计。

项	说明
默认行数	200 行（未指定时）
单次上限	500 行（硬上限）
指定行数	智能体可在工具参数里传 `limit`（不超过上限）
平台配置	运维可在 `mindlink.json` → `data_source_tool` 调整 `default_preview_max_rows`、`absolute_preview_max_rows`（见服务端配置）
返回说明	结果中含 `limit_applied`，表示实际使用的行数上限

注意：对话里若看到工具结果被截断提示，可能是 写入对话上下文时的字数限制（与 SQL 行数上限无关）。需要更多行或聚合结果时，应配置 预定义查询，而不是反复加大表预览的 limit。

预定义查询 的 max_rows 未填时，沿用同一套默认/上限；单条查询可在 JSON 里单独设 max_rows（仍不超过平台上限）。

预定义查询是不是必须的？

不是必须的。

只要配好连接、允许访问的表，并为成员授权，智能体就能 看表结构 和 预览表数据。

预定义查询 是为常见「问数」场景准备的 增强项：把常用写法事先配好，对话里按 查询 id 取数，而不是每次从零摸索。

预定义查询 vs 技能里的表定义

二者 不能互相取代，只能 配合使用。

	技能里的表定义	预定义查询
本质	给智能体看的说明文档	可执行的受控查询
能否按条件查数	不能	能
典型用途	表叫什么、字段含义、业务口径说明	「按部门查员工」「按日期查订单」等

技能里写「employees 有 dept_name、status」→ 帮助智能体 理解该看哪张表。
用户问「研发部在职员工有哪些」→ 仍需要 预定义查询；仅靠 表预览 只能看到前若干行 未筛选 的样例，无法替代完整业务问法。

保存数据连接后，可使用 「生成技能」，把各预定义查询的用途与参数写入工作区技能，便于智能体 选对查询。若已生成过技能，再次保存 且预定义查询有变更时，系统会 自动同步 技能正文，无需重启后端。

是不是查询越多、越详细越好？

不是。 关键是 覆盖常见问法 且 每条写得清楚，而不是堆很多相似条目。

情况	效果
用户问题能对应某条预定义查询	通常更快、更准：SQL 已校验，少走「查结构 → 试预览 → 再猜」
问题对不上任何预定义查询	可能改用表预览等，速度和准确度都会下降
查询太多、名称相似	智能体可能选错查询，反而答非所问
`name`、`description` 写清楚	更容易选对，比堆 SQL 细节更重要

表预览 适合：「这张表大概长什么样」「有哪些字段叫什么」。 预定义查询 适合：按条件筛选、多表关联、聚合统计、固定业务口径。

工作区有多条数据连接时

默认情况下，对话里智能体会看到你 已授权的全部数据连接，并根据你的问题 自行选择 要查哪一条——连接越多，越可能 选错库 或 选错预定义查询。

建议组合使用（由粗到细）：

做法	作用
数据资源 / 谁可以使用	按角色让成员只能看到相关的表与查询（工作区级授权）
可用数据与技能（某只智能体）	在我的智能体 → 管理 → 概览为专用问数助手指定或优先某几条连接与技能；可勾选仅限以上资源禁止误用其它库
生成技能	保存连接后把各预定义查询的用途、参数写进工作区技能，帮助选对查询
对话里点名	可直接说「用 xxx 连接查…」「走 query_id 那条查询」

典型场景：HR 专用助手只绑定 HR 库与 HR 问数技能；财务助手只绑定财务库——同一工作区、不同智能体、各查各库。

完整说明见技能与智能体 · 可用数据与技能。

实用配置建议

按业务场景配查询 — 每个常见问法一条（如「按部门查在职员工」「近 30 天订单」），不要为每张表机械写一条。
写好名称与说明 — 说明「什么时候用、要什么参数」。
保存后生成技能 — 让智能体知道该用哪条查询；之后改查询须 点保存（「从文档解析」只写入表单，保存后才入库）。
从文档解析 — 在数据连接表单点 「从文档解析」，粘贴业务说明或 Markdown（可含 SQL），AI 会 新增或更新 预定义查询并与已有条目合并。
用「数据资源」收窄范围 — 在 数据集成 → 数据资源 / 谁可以使用 中，让不同角色只看到相关表与查询。
多条连接时为专用智能体配置「可用数据与技能」 — 见上文工作区有多条数据连接时。
简单看样例用表预览；正式问数用预定义查询。

预定义查询 JSON 字段（管理员）

在 数据连接 表单中配置 JSON 数组，主要字段：

字段	说明
`id`	查询标识，智能体调用时使用
`name`	给人看的名称
`description`	可选，建议写清适用场景
`sql`	只能是 SELECT；参数用 `?` 占位（与 `params` 数组顺序一致），勿用 `@param`
`params`	参数名、类型、是否必填、默认值；个数须与 SQL 中 `?` 一致
`max_rows`	该查询最多返回行数；未填时用平台默认（200），且不超过平台上限（500）

界面 「?」帮助、「从文档解析」 与 「智能检查校正」 可辅助从 Markdown/文本生成或校正查询；须已配置 AI 服务。

智能检查校正（数据连接表单）

点 「智能检查校正」 后，系统会逐条检查编辑器中的预定义查询（条目较多时耗时更长，属正常现象）：

阶段	说明
本地规范	自动将 legacy 的 `@param` 改为 `?`（若可识别）
AI 逐条检查	每条单独校正 SELECT、`?` 与 `params`、表名等
进度	显示第 N / 总数、当前查询 id、进度条；全屏编辑预定义查询时进度对话框仍可见
结果	有修改时确认应用才写回编辑器；部分条目失败会保留原内容并在说明中提示

注意：保存连接后才会入库；全屏编辑 与 从文档解析 面板类似，长任务浮层挂到页面最上层，避免被挡住。

SQL 占位符常见错误

写法	结果
`WHERE empName = ?` + 对应 `params`	正确
`WHERE empName = @empName`	错误：保存时会被拒绝；旧数据执行时可能报「参数个数不一致」
SQL 有 2 个 `?` 但 `params` 只声明 1 个	错误：保存校验不通过

示例：

{
  "id": "staff_by_name",
  "name": "按姓名查员工",
  "sql": "SELECT empId, empName FROM eaemp WHERE empName = ?",
  "params": [{ "name": "empName", "type": "string", "required": true }],
  "max_rows": 100
}

受控数据变更（可选）

除只读查数外，管理员可在 变更定义 中配置 insert / update / delete，并在 谁可以使用 里为成员勾选 增 / 改 / 删 权限（读权限单独控制）。

概念	说明
变更定义	绑定数据连接与表，指定可操作字段、主键/条件字段
审批模式	`none` 直接执行；`required` 提交后须指定人员或管理员在变更审批中通过
对话中	智能体通过受控工具提交变更（不能临时拼 SQL）

典型流程：成员在消息中说明要登记/修改的数据 → 智能体调用对应 变更 id → 若需审批则进入待办，审批通过后写入数据库。

变更与只读查询一样受 数据资源 与 谁可以使用 约束；无权限时智能体应说明并停下。

谁可以配置与使用

角色	能做什么
平台运维	在服务端打开数据连接总开关、配置预览行数上限等
工作区管理员	配置连接、预定义查询、变更定义、数据资源、成员授权、变更审批；在帮助智能体中自然语言管理数据集成
普通成员	在已授权范围内，通过对话查数（表预览、执行预定义查询、受控变更等）；不能增删改预定义查询

工作区管理员默认可访问全部数据连接；普通成员仅能在 「谁可以使用」 中已勾选的范围里查数。

常见问题

可以不配预定义查询，只靠技能里的表说明吗？ 可以应对「看样例、认结构」类问题；涉及筛选、统计或固定口径时，仍建议配预定义查询。

技能里写了完整 SELECT，智能体会直接执行吗？ 不会。技能是说明文档；执行须走受控工具（表预览或预定义查询）。

配了很多查询，对话一定更快吗？ 不一定。覆盖到位、说明清楚更有帮助；过多相似查询可能拖慢选型或导致选错。

表预览为什么只有几百行？ 这是平台为保护数据库与对话性能设的上限（默认 200、最多 500，可配置）。要看全量或做统计，请配 预定义查询；不能用表预览的前若干行回答「有没有重名」「一共多少个」。

智能检查校正失败或很慢？ 条目多时会逐条调用 AI，请等待进度条走完。若超时，可稍后重试或先拆成较少条目再查。须已配置 AI 服务；SQL 勿用 @param，改用 ? 与 params。

对话里智能体用表预览说「没有重名」靠谱吗？ 不靠谱。表预览是无筛选的前 N 行样例，不能代表全库。应配 预定义查询（如按姓名分组统计），或走上文 「建议 → 确认 → 保存 → 执行」 流程。

导出技能或应用后，另一边没有预定义查询怎么办？ 导出包会尽量附带用到的预定义查询定义（不含数据库账号）。导入时若目标工作区缺少同名查询，工作区管理员 可选择写入某条数据连接；也可先导入再在「数据集成」手动补齐。目标库表结构不同时，写入后请用「智能检查校正」或实测 query.run 核对。

改完预定义查询要重启后端吗？ 不需要。在数据连接表单 点「保存」 后，下一条消息起 query.run 即用最新 SQL。若曾点过 「生成技能」，保存时技能正文也会自动更新；未生成技能时，智能体仍可通过工具列表看到最新查询 id，只是说明文档可能较简。

改了查询但智能体还用旧的？ 常见原因：① 只改了表单 没点保存；② 新查询 id 未加入成员的 数据资源 授权；③ 对话里智能体仍引用旧上下文——发一条新消息或新开对话再试。

有多条连接，智能体总查错库怎么办？ 先用 谁可以使用 收窄成员可见范围；再为专用助手在 概览 → 可用数据与技能 指定连接（必要时勾选 仅限以上资源）；并 生成技能 写清该用哪条预定义查询。

任意成员都能在对话里改预定义查询吗？ 不能。仅工作区管理员 可在对话或 数据集成 表单中增删改预定义查询。普通成员即使有数据资源读权限，也只能执行已有查询，不能改配置。

有读权限就能改查询吗？ 不能。读权限仅用于查数；改查询定义须管理员身份。若成员在对话里提出「保存这条查询」，智能体应说明须由管理员操作，或引导到 数据集成 / 帮助智能体。

普通成员能在网页表单里改预定义查询 JSON 吗？ 不能。数据集成 表单仅 工作区管理员 可保存。