跨库迁移的难点往往不在数据复制本身，而在周边环节：源库能否连通、目标引擎是否匹配、DDL 会影响哪些对象、任务失败后如何续跑。为了应对这些问题，用户不得不在控制台、接口文档和脚本之间反复切换。

kwdb-data-migration 将这套流程整合为一个面向 KaiwuDB（KWDB）的 AI Agent Skill。用户只需用自然语言描述迁移需求，Agent 会自动收集参数并调用 KDTS （KaiwuDB Data Transformer）的 REST API，依次完成配置校验、建表预览、任务提交与状态查询。

它解决的是哪类迁移

该 Skill 专注于将异构数据源迁入 KaiwuDB，支持的源端包括 MySQL、Oracle、PostgreSQL、SQL Server、ClickHouse、InfluxDB 1.x/2.x、OpenTSDB、TDengine 2.x/3.x、MongoDB、FTP/SFTP、HDFS，以及 KaiwuDB 自身。各类源端的能力存在差异：例如 SQL Server 仅支持元数据读取，ClickHouse 以数据迁移为主；表格类和文件类源端则通常需要用户补充表结构或字段映射。

目标端固定为 KaiwuDB，且需明确指定 RELATIONAL 或 TIMESERIES 引擎。Skill 会在任务创建前主动拦截不兼容的组合——例如 InfluxDB、OpenTSDB、TDengine等时序源只能迁入 TIMESERIES 引擎，MongoDB、FTP 和 HDFS 同样面向时序目标。这类限制提前暴露，避免迁移执行到中途才发现方向有误。

一次迁移如何推进

一次完整的迁移按状态机逐步推进：收集参数 → 验证配置 → 测试两端连接 → 读取元数据 → 预览 DDL → 等待确认 → 执行 DDL → 生成并提交迁移任务 → 持续监控结果。

Agent 首先会要求用户提供 KDTS 地址、源库与目标库的连接信息、迁移模式及范围。Skill 支持全量迁移、仅 Schema、仅数据和分批迁移四种模式。当涉及大量表而生成多个脚本时，建议按批提交——默认每批 10 个脚本，以避免一次性提交过多任务导致客户端读取超时。

运行前的连接测试是必经步骤。Skill 要求先通过 ConfigValidator.validate_source_config() 检查源端能力，再分别测试源端和目标端的连通性。需要注意 KDTS 的一种特殊响应：部分校验失败时会返回 code=0，而失败信息实际位于 data 字段；随附的 API 客户端会将其规整为 code=2001，因此调用方不应绕过封装、仅凭原始状态码判断结果。

把破坏性操作放在确认门之后

迁移过程涉及建表、覆盖同名目标表以及终止运行中的任务等操作。该 Skill 为两类高风险操作设置了明确的确认门。

• 执行 DDL 前，先展示生成的 DDL 语句、将创建的对象清单及潜在覆盖风险，取得用户明确同意后再执行。

• 终止迁移前，先展示任务当前状态与进度，并要求用户输入 YES 确认。终止操作可能留下部分写入的数据，且任务无法自动恢复。

此外，Skill 会在迁移开始前提醒用户备份源端和目标端数据。由于数据操作不支持自动回滚，最终验证仍需由用户比对源端与目标端的行数来确认一致性。

时序迁移需要额外关注什么

迁入 TIMESERIES 引擎时，表结构并非关系表的简单映射。Skill 要求用户指定时间列、普通 TAG 和 PRIMARY TAG，并校验相关约束：PRIMARY TAG 最多 4 个、必须来自 TAG 列表且不可为 NULL，首列须满足 TIMESTAMPTZ NOT NULL。若源数据在主标签列中存在空值，迁移可能在运行时失败——此时需要回填数据、调整标签选择，或将该列降级为普通 TAG。

部分源端不具备元数据读取能力。此时 Skill 不会猜测表结构，而是要求用户提供源端的 CREATE TABLE DDL 或列定义，再由 Agent 构造元数据并生成目标 DDL。FTP 和 HDFS 本身没有表结构，目标表需在迁移前预先创建。对于时序目标，构建数据迁移任务时同样应提供显式表映射，不能依赖自动发现。

适合怎样使用

你可以从一句具体的需求开始，例如"把 MySQL 的 sales 库迁到 KaiwuDB 的关系引擎"，随后按提示逐步补充地址、账号、数据库名和迁移范围。请注意不要将密码写入代码或版本库；在对话中提供连接信息前，也应确认当前环境具备恰当的凭据管理机制。

该 Skill 的核心设计理念是将迁移细节在恰当的时机逐步处理：先校验兼容性与连接，再交由用户审阅 DDL，然后提交任务并持续跟踪状态。对于首次迁移，建议先执行 Schema-only 模式并核对生成的 DDL，确认无误后再执行数据迁移，以便更精准地定位问题。