技能与应用导入导出：预定义查询如何跟着走
把技能或应用拷到另一个工作区时，预定义查询怎么跟着走、怎么补齐。
来源 docs/技术博客/技能应用导入导出与预定义查询.md
表述：本文面向 工作区管理员，说明把技能或应用拷到另一个工作区时，预定义查询会怎样处理、导入时如何一键补齐，以及目标库表结构不一致时要注意什么。日常成员只需会用技能/应用；不必了解 zip 里的文件名。实现对照见文末。
日期：2026-07-19 状态：已实现 关联帮助：工作区应用 · 数据连接与预定义查询 · 怎么写好工作区技能 机制说明：工作区应用
结论（先看这个）
| 问题 | 答案 |
|---|---|
| 导出技能/应用会带走数据库账号吗？ | 不会 |
| 会带走预定义查询的 SQL 吗？ | 会尽量带走（写入包内依赖清单，不含连接密钥） |
| 导入时缺查询会怎样？ | 技能/应用仍可导入；取数会失败，除非补齐查询 |
| 管理员能一键补齐吗？ | 能：导入时可选择写入本工作区某条数据连接 |
| 目标库表名不同怎么办？ | 先写入，再用「智能检查校正」或实测改 SQL |
一句话：界面与逻辑走技能/应用包；怎么查数走数据连接上的预定义查询；迁移时把「查询定义」作为依赖一并带上，导入时可选合并。
1. 为什么以前会「迁过去不能用」
技能和应用 不存业务库连接，只按 查询 id 去调工作区里的数据连接，例如：
- 技能正文写「调用预定义查询
staff_by_dept」 - 员工画像
pipeline写死employee_by_name - 报表应用脚本里
platform.query_run("dept_rank_emp", …)
导出包原先主要带走：
- 技能：说明文档、脚本、参考材料
- 应用：界面描述与逻辑（不含已登记的业务数据）
预定义查询 挂在「数据集成 → 数据连接」上，不在包里。目标工作区若没有同名查询（或没有对应数据连接），导入本身往往成功，但一查数就报「未找到查询定义」，或对话里临场猜别的 id、用表预览冒充正式结果。
2. 现在的做法：依赖清单跟着包走
2.1 导出时自动收集
导出技能包或应用包时，系统会：
- 扫描包内材料中用到的查询 id（流水线、脚本、正文说明等）
- 到 当前工作区 的数据连接里解析出对应定义（名称、说明、SQL、参数）
- 写入包内依赖文件（不含主机、账号、密码）
若源工作区本身也没有这些查询的完整定义，包里就带不齐 SQL——迁移前请先在源侧把常用查询配置好再导出。
2.2 导入时缺口检查 + 可选写入
导入预览会对照目标工作区，给出大致状态：
| 状态 | 含义 |
|---|---|
| 已就绪 | 某条数据连接上已有同名且内容一致的查询 |
| 缺失 | 包里有定义，目标还没有 |
| 冲突 | 同名存在，但 SQL/参数与包内不同 |
确认导入后，若有缺失（或冲突），工作区管理员 会被询问：
- 是否写入本工作区的某条 数据连接
- 同名冲突时：保留已有，或用包内定义覆盖
也可以选「仅导入，不写入」——技能/应用照常落地，之后再到「数据集成」手工补查询。
非管理员可以导入包，但不能把查询写入数据连接；界面会提示请管理员处理。
3. 操作步骤（管理员）
3.1 从源工作区导出
| 类型 | 怎么做 |
|---|---|
| 应用 | 打开应用 → 导出应用包 → 得到 zip |
| 技能 | 技能中心打开技能 → 导出（标准或完整均可；依赖查询两种模式都会尽量附带） |
导出后仍 不包含 原工作区已登记的业务表数据，也不包含数据库连接密钥。
3.2 在目标工作区准备数据连接
写入预定义查询之前，目标工作区需要：
- 已开通 数据集成，并配置好可用的 MySQL（等）数据连接
- 库里有业务表（或至少允许后续改 SQL 对齐）
- 导入操作者具备 工作区管理员 身份（若要一键写入查询）
3.3 导入并写入缺失查询
- 导入技能包或应用包，按提示处理「标识符已存在」（覆盖 / 复制）
- 若提示有预定义查询依赖：选择要写入的数据连接，确认「写入并继续导入」
- 到 数据集成 → 该数据连接 核对查询列表
- 用真实业务场景跑一遍（对话 @ 技能，或点应用按钮）
3.4 同名冲突怎么选
| 选择 | 适用 |
|---|---|
| 保留已有（默认） | 目标侧查询已调通，不想被源环境覆盖 |
| 覆盖同名 | 要以源包口径为准，统一 SQL 与参数名 |
4. 目标库与源库不一致时
依赖清单解决的是「有没有同名查询」，不能保证 SQL 在目标库一定能跑通。常见差异：
- 表名、列名不同（如
empIdvsemp_id） - 允许表范围更窄，写入时校验不通过
- 参数名与脚本/技能里写的不一致
建议：
- 先完成导入并写入缺失查询
- 对关键连接执行 智能检查校正（见 预定义查询智能检查校正机制解析）
- 用固定样例参数对各查询 id 做一次执行验证
- 员工画像类固定流水线，还可对照 员工画像 Pipeline 与数据连接对齐指南
5. 和「生成技能 / 对话写入查询」的关系
| 场景 | 做法 |
|---|---|
| 本工作区新配连接 | 数据连接保存后可 生成技能；或对话里管理员写入查询 |
| 跨工作区拷技能/应用 | 用本文的 导出依赖 + 导入合并 |
| 画像 pipeline 缺规范 id | 仍可用对话一键写入模板查询（见画像对齐指南） |
三者互补：日常配置靠表单/对话；整包迁移靠导入导出依赖合并。
6. 成员侧会看到什么
- 导入成功、查询已写入：与原先一样使用技能或应用即可
- 只导入了包、没写查询：点报表/画像等取数动作可能失败；对话里可能提示未找到查询——请管理员补齐
- 没有数据连接：无法写入查询；需先配连接再导入一次（或手工粘贴查询定义）
7. 检查清单（迁移前）
- [ ] 源工作区：技能/应用依赖的查询已在数据连接中配置并可执行
- [ ] 导出得到 zip（应用或技能）
- [ ] 目标工作区：数据连接已通，表结构大致可用
- [ ] 管理员执行导入，并对缺失项选择写入
- [ ] 冲突项已按口径选择保留或覆盖
- [ ] 抽样验证对话取数或应用按钮
- [ ] 表结构有差异时已做智能检查或手工改 SQL
实现对照（给开发 / 排障）
| 能力 | 位置 |
|---|---|
| 收集查询 id、打包/解析依赖 | backend/internal/querydepbundle/ |
| 应用导出注入 / 导入合并 | backend/internal/api/handlers/workspace_apps_import.go |
| 技能导出注入 / 导入合并 | backend/internal/api/handlers/skills_import.go |
| 合并进数据连接 | store.MergeImportQueryDefs（skip / replace） |
| 包内依赖文件 | references/query-defs.json（格式 mindlink-query-deps） |
| 导入表单字段 | merge_query_defs、data_source_slug、on_query_conflict |
| Web 确认流程 | client/web/src/importQueryDeps.ts；应用/技能导入页调用 |
预览响应中的 query_deps 含就绪/缺失/冲突计数与推荐连接；合并失败时应用/技能仍可能已导入，响应可带 query_deps_merge_error 便于提示。