@clickzetta/cz-cli-darwin-x64 0.3.39 → 0.3.41

package/bin/skills/clickzetta-bi-connect/eval_cases.jsonl

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"怎么把 Superset 连接到 ClickZetta？","expected_skill":"clickzetta-bi-connect","expected_output_contains":["SQLAlchemy","clickzetta://"]}
+{"case_id":"002","type":"should_call","user_input":"Tableau 怎么连接 ClickZetta Lakehouse？","expected_skill":"clickzetta-bi-connect","expected_output_contains":["JDBC",".taco"]}
+{"case_id":"003","type":"should_call","user_input":"DBeaver 连接 ClickZetta 的 JDBC URL 怎么写？","expected_skill":"clickzetta-bi-connect","expected_output_contains":["jdbc:clickzetta://","ClickZettaDriver"]}
+{"case_id":"004","type":"should_call","user_input":"Metabase 怎么连接 ClickZetta？需要装什么驱动？","expected_skill":"clickzetta-bi-connect","expected_output_contains":["Metabase",".jar"]}
+{"case_id":"005","type":"should_call","user_input":"帆软 FineBI 怎么连接 ClickZetta？","expected_skill":"clickzetta-bi-connect","expected_output_contains":["JDBC","MySQL 协议"]}

package/bin/skills/clickzetta-bi-connect/references/bi-tools.md

@@ -0,0 +1,170 @@
+# BI 工具连接参考
+
+> 来源：https://www.yunqi.tech/documents/ecosystem-all 等
+
+## 连接方式总览
+
+| 工具 | 连接方式 | 说明 |
+|---|---|---|
+| Apache Superset | SQLAlchemy URL | 需安装 clickzetta-connector |
+| Tableau | JDBC + 插件 | 需下载 .taco 插件 |
+| Metabase | 专用驱动 | 需下载 .jar 驱动 |
+| DBeaver | JDBC | 通用数据库客户端 |
+| DataGrip | JDBC | JetBrains 数据库 IDE |
+| 帆软 FineBI | JDBC | 国产 BI 工具 |
+
+---
+
+## JDBC 连接字符串格式
+
+```
+jdbc:clickzetta://<instance_name>.<region_id>.api.clickzetta.com/<workspace_name>?username=<user>&password=<pwd>&schema=<schema>&virtualCluster=<vc_name>
+```
+
+示例：
+```
+jdbc:clickzetta://f8866243.cn-shanghai-alicloud.api.clickzetta.com/quick_start?username=alice&password=xxxx&schema=public&virtualCluster=default_ap
+```
+
+JDBC 驱动类：`com.clickzetta.client.jdbc.ClickZettaDriver`
+
+JDBC 驱动下载：
+- Maven: `com.clickzetta:clickzetta-java`
+- 直接下载：https://central.sonatype.com/artifact/com.clickzetta/clickzetta-java/versions
+
+---
+
+## SQLAlchemy URL 格式
+
+```
+clickzetta://<username>:<password>@<instance_name>.<region_id>.api.clickzetta.com/<workspace_name>?schema=<schema>&vcluster=<vc_name>
+```
+
+示例：
+```
+clickzetta://alice:xxxx@f8866243.cn-shanghai-alicloud.api.clickzetta.com/quick_start?schema=public&vcluster=default_ap
+```
+
+安装：
+```bash
+pip uninstall -y clickzetta-sqlalchemy clickzetta-connector && pip install clickzetta-connector -U
+```
+
+---
+
+## Apache Superset
+
+### 快速启动（Docker）
+
+```bash
+docker pull clickzetta/superset:2.1.0-1
+docker run -p 8088:8088 clickzetta/superset:2.1.0-1
+# 访问 http://localhost:8088，默认账号 admin/clickzetta
+```
+
+### 本地安装
+
+```bash
+pip uninstall -y clickzetta-sqlalchemy clickzetta-connector
+pip install clickzetta-connector -U
+pip install 'apache-superset>=2.1'
+
+export FLASK_APP=superset
+superset db upgrade
+superset fab create-admin
+superset init
+superset run -p 8088 --with-threads --reload --debugger
+```
+
+### 配置数据库连接
+
+1. Settings → Database Connections → + Database
+2. 选择 **Other** 数据库类型
+3. 填写 SQLAlchemy URI：
+   ```
+   clickzetta://username:password@instance.region.api.clickzetta.com/workspace?vcluster=default_ap
+   ```
+4. 点击 TESTING CONNECTION 验证，通过后 CONNECT
+
+---
+
+## Tableau
+
+### 前提条件
+
+1. 下载 JDBC 驱动 JAR 包
+2. 下载 Tableau 插件：`clickzetta_jdbc-v0.0.1.taco`
+
+### 安装步骤
+
+**放置 JDBC 驱动：**
+- Windows: `C:\Program Files\Tableau\Drivers`
+- macOS: `~/Library/Tableau/Drivers`
+- Linux: `/opt/tableau/tableau_driver/jdbc`
+
+**放置 Tableau 插件（.taco 文件）：**
+- Windows: `C:\Users\[User]\Documents\My Tableau Repository\Connectors`
+- macOS: `/Users/[user]/Documents/My Tableau Repository/Connectors`
+
+**启动 Tableau（禁用签名校验）：**
+```bash
+# macOS
+/Applications/Tableau\ Desktop\ [version].app/Contents/MacOS/Tableau -DDisableVerifyConnectorPluginSignature=true
+
+# Windows
+tableau.exe -DDisableVerifyConnectorPluginSignature=true
+```
+
+**连接：** 左侧导航 → 到服务器 → 更多 → Lakehouse x 云器科技 → 填写服务器/用户名/密码
+
+---
+
+## Metabase
+
+### Docker 部署
+
+```bash
+docker pull metabase/metabase:v0.54.6
+docker run -d -p 3000:3000 --name metabase metabase/metabase:v0.54.6
+
+# 下载并安装云器驱动
+docker cp clickzetta.metabase-driver.jar metabase:/plugins/clickzetta.metabase-driver.jar
+docker restart metabase
+```
+
+驱动下载：`clickzetta.metabase-driver.jar`（联系云器技术支持获取）
+
+### 配置连接
+
+1. 访问 `http://localhost:3000`
+2. Admin Settings → Databases → Add a database
+3. 选择 ClickZetta Lakehouse，填写连接信息
+4. Test connection → Save
+
+---
+
+## DBeaver
+
+### 配置步骤
+
+1. 数据库 → 驱动管理器 → 新建驱动
+2. 填写：
+   - 驱动名称：`Clickzetta`
+   - 类名：`com.clickzetta.client.jdbc.ClickZettaDriver`
+   - URL 模板：`jdbc:clickzetta://{instanceName}.{service}/{workspaceName}?virtualCluster={vc_name}`
+3. 选择库 → 添加 JDBC JAR 包
+4. 新建连接 → 搜索 Clickzetta → 粘贴 JDBC 连接字符串 → 填写用户名密码
+
+---
+
+## 地域代码（region_id）速查
+
+| 云厂商 | 地域 | region_id |
+|---|---|---|
+| 阿里云 | 华东2（上海） | cn-shanghai-alicloud |
+| 腾讯云 | 华东（上海） | ap-shanghai-tencentcloud |
+| 腾讯云 | 华北（北京） | ap-beijing-tencentcloud |
+| 腾讯云 | 华南（广州） | ap-guangzhou-tencentcloud |
+| AWS | 中国（北京） | cn-north-1-aws |
+| 阿里云（新加坡） | 亚太东南1 | ap-southeast-1-alicloud |
+| AWS（新加坡） | 亚太（新加坡） | ap-southeast-1-aws |

package/bin/skills/clickzetta-cdc-sync-pipeline/SKILL.md

@@ -15,6 +15,43 @@ description: |
 
 # 多表实时同步 Pipeline 工作流
 
+## 向导：收集必要信息
+
+开始创建 CDC 同步任务前，优先使用交互式问答工具（如 `question`）收集以下信息并弹出选项菜单；若无此类工具，则用文字一次性列出所有问题：
+
+```
+question({
+  questions: [
+    {
+      question: "源端数据库类型？",
+      options: [
+        { label: "MySQL", description: "含 Aurora MySQL、PolarDB MySQL，基于 Binlog" },
+        { label: "PostgreSQL", description: "含 Aurora PG、PolarDB PG，基于 WALs，需 14+" }
+      ]
+    },
+    {
+      question: "同步模式？",
+      options: [
+        { label: "整库镜像", description: "同步整个数据库，自动适配新增表" },
+        { label: "多表镜像", description: "指定同步哪些表" },
+        { label: "多表合并", description: "分库分表合并到一张目标表" }
+      ]
+    },
+    {
+      question: "源端是否已完成准备？",
+      options: [
+        { label: "已准备好", description: "MySQL: Binlog 已开启，账号有 REPLICATION 权限；PG: wal_level=logical" },
+        { label: "不确定，帮我检查", description: "我来帮你验证源端配置" }
+      ]
+    }
+  ]
+})
+```
+
+收集到信息后，还需确认目标 schema（如 `ods`）。
+
+**如果用户已经提供了足够信息，直接进入工作流，不再弹出菜单。**
+
 ## 适用场景
 
 - 将 MySQL / PostgreSQL 数据库整库或多表实时同步到 Lakehouse（CDC 变更捕获）
@@ -59,7 +96,7 @@ description: |
 - 源端数据源已在 Studio 中配置（通过 Studio UI 添加数据源，不是 SQL Storage Connection），且账号具备 CDC 所需权限
 - Sync VCluster 可用（多表实时同步任务 task_type=281 必须使用 Sync VCluster）
 - **执行环境（满足其一即可，优先使用 cz-cli）**：
-  - **cz-cli 路径**：已安装 cz-cli（`pip install cz-cli`），并完成 `cz-cli configure` 配置
+  - **cz-cli 路径**：已安装 cz-cli（`brew install cz-cli 或参考官方文档安装`），并完成 `cz-cli setup` 配置
   - **MCP 路径**：clickzetta-studio-mcp 工具可用（`create_task`、`save_cdc_realtime_task`、`publish_task`、`list_data_sources`、`LH_show_object_list` 等）
 
 ## 环境探测（执行前必读）
@@ -79,7 +116,7 @@ cz-cli --version
 - 若工具存在于 tool list → **走 MCP 路径**（本文档默认路径）
 - 若工具不存在 → 停止执行，提示用户：
   > "当前环境既无 cz-cli 也无 MCP 工具，请安装其中之一后重试。
-  > cz-cli 安装：`pip install cz-cli`，然后运行 `cz-cli configure`
+  > cz-cli 安装：`brew install cz-cli 或参考官方文档安装`，然后运行 `cz-cli setup`
   > MCP 安装：参考 clickzetta-studio-mcp 配置文档"
 
 > ⚠️ **重要区分**：CDC 多表同步使用 **Studio 数据源**（通过 Studio UI 或 API 配置），不是 SQL 的 `CREATE STORAGE CONNECTION`。
@@ -485,7 +522,18 @@ PostgreSQL 权限要求（建议用管理员账号执行）：
 > 仅在 cz-cli 可用且 MCP 不可用时使用本节。步骤编号与上方 MCP 路径对应。
 > 所有操作通过 `cz-cli agent run` 委托给内置 agent 完成，agent 内置完整的 Studio MCP 工具访问能力。
 
-### 模式一：整库镜像同步（cz-cli 版）
+### 快速路径：直接创建任务 + Studio UI 配置
+
+```bash
+# 创建 CDC 多表实时同步任务（task_type=281，即 MULTI_REALTIME）
+cz-cli task create "cdc_<database>" --type MULTI_REALTIME --folder <folder_name>
+# 返回 task_id 和 studio_url，在 studio_url 中完成数据源选择、表映射等配置
+
+# 配置完成后发布（CDC 任务无需调度，提交即持续运行）
+cz-cli task deploy "cdc_<database>" -y
+```
+
+### 模式一：整库镜像同步（cz-cli agent 版）
 
 ```bash
 # 步骤 1-9 合并：让 agent 完成完整的 CDC 整库同步任务创建
@@ -515,7 +563,7 @@ cz-cli agent run "提交 CDC 任务 cdc_<database>，使其开始持续运行" \
 
 ---
 
-### 模式二：多表镜像同步（cz-cli 版）
+### 模式二：多表镜像同步（cz-cli agent 版）
 
 ```bash
 # 创建多表镜像 CDC 任务（指定具体表）
@@ -525,7 +573,7 @@ cz-cli agent run "创建 CDC 多表实时同步任务（task_type=281），pipel
 
 ---
 
-### 模式三：多表合并同步（cz-cli 版）
+### 模式三：多表合并同步（cz-cli agent 版）
 
 ```bash
 # 创建多表合并 CDC 任务（多源表合并到单目标表）
@@ -538,11 +586,48 @@ cz-cli agent run "创建 CDC 多表实时同步任务（task_type=281），pipel
 ### 运维监控（cz-cli 版）
 
 ```bash
-# 查看任务状态
-cz-cli agent run "查看 CDC 任务 <task_name> 的运行状态和详细信息" \
-  --format a2a --dangerously-skip-permissions
+# 查看最近运行记录
+cz-cli runs list --task <task_name>
 
-# 查看运行记录
-cz-cli agent run "查看 CDC 任务 <task_name> 的最近运行记录" \
-  --format a2a --dangerously-skip-permissions
+# 查看运行详情
+cz-cli runs detail <run_id>
+
+# 查看执行日志
+cz-cli attempts log <run_id>
+
+# 下线任务（停止持续运行）
+cz-cli task undeploy <task_name> -y
 ```
+
+---
+
+## 交付验收 Checklist
+
+CDC 同步任务发布运行后，**必须逐项验证**：
+
+```sql
+-- 1. 行数比对：全量阶段完成后，ODS 层行数与源端一致
+SELECT COUNT(*) FROM <ods_schema>.<table>;
+
+-- 2. 增量验证：写入一条测试数据到源端，确认 Lakehouse 侧同步到位
+-- 在源端 MySQL 执行 INSERT，等待 10~30 秒后在 Lakehouse 查询
+
+-- 3. 关键字段非空率
+SELECT
+  COUNT(*) AS total,
+  COUNT(key_field) AS non_null,
+  ROUND(COUNT(key_field) * 100.0 / COUNT(*), 2) AS non_null_pct
+FROM <ods_schema>.<table>;
+
+-- 4. 检查 _op 字段分布（CDC 接入时）
+SELECT _op, COUNT(*) FROM <ods_schema>.<table> GROUP BY _op;
+-- 正常应有 I（INSERT）记录，UPDATE/DELETE 场景下有 U/D
+```
+
+**验收标准：**
+- [ ] 全量阶段完成，ODS 层行数与源端一致
+- [ ] 增量写入测试数据，Lakehouse 侧 30 秒内同步到位
+- [ ] 关键字段非空率符合预期
+- [ ] _op 字段分布合理（无异常大量 D 记录）
+- [ ] 任务状态为持续运行（RUNNING），无频繁重启
+- [ ] 字段类型映射正确（重点检查 BIT/ENUM/TEXT 等异构类型）

package/bin/skills/clickzetta-data-ingest-pipeline/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: clickzetta-data-ingest-pipeline
+description: |
+  ClickZetta Lakehouse 数据导入总览与路由。根据用户的数据源类型、实时性要求、数据量等条件，
+  推荐最合适的数据导入方式，并引导到对应的专项 Skill 或直接执行简单导入操作。
+  当用户说"导入数据到 Lakehouse"、"数据入仓"、"数据入湖"、"怎么把数据导进来"、
+  "数据采集"、"数据加载"、"ingest data"、"load data"、"数据导入方案选择"时触发。
+  Keywords: data ingestion, import, routing, pipeline selection, data source
+---
+
+# Lakehouse 数据导入总览与路由
+
+根据用户的数据源、实时性需求、数据规模等条件，推荐最合适的数据导入方式，
+并路由到对应的专项 Pipeline Skill 或直接执行简单导入操作。
+
+## 适用场景
+
+- 用户想把数据导入 ClickZetta Lakehouse，但不确定用哪种方式
+- 用户描述了数据源（Kafka、MySQL、OSS、文件等），需要推荐导入方案
+- 用户需要了解各种导入方式的适用场景和差异
+- 关键词：数据导入、数据入仓、数据入湖、数据采集、数据加载、pipeline 选择
+
+## 前置依赖
+
+- ClickZetta Lakehouse 账户，具备创建工作空间、Schema、表、PIPE、任务等权限
+- **执行环境**：已安装并配置 cz-cli
+
+## 执行环境
+
+所有操作通过 `cz-cli` 执行：
+
+```bash
+cz-cli --version
+```
+
+需要 cz-cli，请参考官方文档安装并完成配置后重试。
+
+## 数据导入方式决策树
+
+### 步骤 1：确认数据源类型和需求
+
+向用户收集以下信息：
+
+1. **数据源类型**：Kafka / 对象存储(OSS/S3/COS) / 关系型数据库(MySQL/PostgreSQL/SQL Server) / 本地文件 / URL/Web 文件 / Java SDK / ZettaPark
+2. **实时性要求**：实时（秒级延迟）/ 准实时（分钟级）/ 离线批量（小时/天级）
+3. **同步范围**：单表 / 多表 / 整库
+4. **是否需要持续同步**：一次性导入 / 持续增量同步
+5. **是否需要 CDC（变更数据捕获）**：是 / 否
+
+### 步骤 2：根据决策矩阵推荐方案
+
+| 数据源 | 实时性 | 同步范围 | 推荐方式 | 对应 Skill |
+|--------|--------|---------|---------|-----------|
+| Kafka | 实时/准实时 | 单 topic | Kafka PIPE 持续导入（SQL） | `clickzetta-kafka-ingest-pipeline` |
+| Kafka | 实时 | 多 topic | Studio 实时同步 | `clickzetta-realtime-sync-pipeline` |
+| 对象存储 (OSS/S3/COS) | 准实时/批量 | 文件持续到达 | PIPE 持续导入 | `clickzetta-oss-ingest-pipeline` |
+| 对象存储 | 一次性 | 批量文件 | COPY INTO 命令 | `clickzetta-file-import-pipeline`（COPY INTO 部分） |
+| MySQL/PostgreSQL/SQL Server | 实时 CDC | 单表 | Studio 实时同步 | `clickzetta-realtime-sync-pipeline` |
+| MySQL/PostgreSQL/SQL Server | 实时 CDC | 多表/整库 | Studio 多表实时同步 | `clickzetta-cdc-sync-pipeline` |
+| MySQL/PostgreSQL/SQL Server | 离线批量 | 单表 | Studio 离线同步 | `clickzetta-batch-sync-pipeline` |
+| MySQL/PostgreSQL/SQL Server | 离线批量 | 多表 | Studio 多表离线同步 | `clickzetta-batch-sync-pipeline` |
+| 本地文件 / URL | 一次性 | 单文件/多文件 | URL 下载 + COPY INTO | `clickzetta-file-import-pipeline` |
+| 流式增量计算 | 准实时 | 表变更驱动 | Dynamic Table + Stream | `clickzetta-incremental-compute-pipeline` |
+| Java 应用 | 实时/批量 | 程序写入 | Java SDK | （见下方 SDK 导入指引） |
+| Python/ZettaPark | 批量 | DataFrame | ZettaPark save_as_table | （见下方 SDK 导入指引） |
+
+### 步骤 3：路由到专项 Skill 或直接执行
+
+根据推荐方案，执行以下路由逻辑：
+
+**有对应专项 Skill 的场景** → 告知用户推荐方案，引导使用对应 Skill：
+- `clickzetta-kafka-ingest-pipeline`：Kafka PIPE 管道搭建
+- `clickzetta-oss-ingest-pipeline`：对象存储 PIPE 管道搭建
+- `clickzetta-batch-sync-pipeline`：Studio 离线同步任务
+- `clickzetta-realtime-sync-pipeline`：Studio 实时同步任务
+- `clickzetta-cdc-sync-pipeline`：Studio 多表实时同步（CDC）
+- `clickzetta-incremental-compute-pipeline`：Dynamic Table + Stream 增量计算管道
+- `clickzetta-file-import-pipeline`：URL/文件下载导入
+- `clickzetta-table-stream-pipeline`：Table Stream 变更数据捕获
+
+**无专项 Skill 的简单场景** → 直接执行：
+
+#### SQL INSERT 导入（小数据量）
+```sql
+INSERT INTO schema_name.table_name (col1, col2, col3)
+VALUES ('val1', 'val2', 'val3');
+```
+
+#### COPY INTO 快速导入（从 Volume）
+```sql
+-- 1. 确认 Volume 中有文件
+SHOW VOLUME DIRECTORY volume_name;
+
+-- 2. 执行 COPY INTO
+COPY INTO schema_name.table_name
+FROM VOLUME volume_name
+USING CSV
+OPTIONS('header' = 'true');
+```
+
+#### Java SDK 导入指引
+提供 Java SDK 的关键配置信息：
+- Maven 依赖坐标
+- 连接配置（endpoint、workspace、schema、vcluster）
+- 批量写入 API：`BulkloadWriter`
+- 实时写入 API：`RealtimeWriter`
+- 建议用户参考官方文档：`comprehensive_guide_to_ingesting_javasdk_buckload_realtime`
+
+#### ZettaPark (Python) 导入指引
+- `INSERT` 方式：`session.sql("INSERT INTO ...")`
+- `save_as_table` 方式：`df.write.save_as_table("table_name")`
+- 建议用户参考官方文档：`comprehensive_guide_to_ingesting_zettapark_save_as_table`
+
+## 异构数据源类型映射（ODS 层建表必读）
+
+从关系型数据库（MySQL/PostgreSQL 等）同步数据时，ODS 层建表的字段类型选择直接影响同步成功率。
+
+**核心原则：ODS 层使用宽泛类型，DWD 层再做精确转换。**
+
+### MySQL → Lakehouse 类型映射
+
+| MySQL 类型 | ❌ ODS 层不要用 | ✅ ODS 层用 | DWD 层转换 |
+|---|---|---|---|
+| `BIT(1)` | `BOOLEAN` | `TINYINT` | `CAST(col AS BOOLEAN)` |
+| `TINYINT(1)` | `BOOLEAN` | `TINYINT` | `CAST(col AS BOOLEAN)` |
+| `DATETIME` | `DATETIME` | `TIMESTAMP` | 直接用 |
+| `ENUM('a','b')` | `ENUM` | `STRING` | 直接用 |
+| `TEXT` / `LONGTEXT` / `MEDIUMTEXT` | `TEXT` | `STRING` | 直接用 |
+| `DECIMAL(p,s)` | `FLOAT` / `DOUBLE` | `DECIMAL(p,s)` | 直接用 |
+| `JSON` | `JSON` | `STRING` | `parse_json(col)['field']` |
+| `SET('a','b')` | `SET` | `STRING` | 直接用 |
+
+> ⚠️ **最常见踩坑**：`BIT(1)` 映射为 `BOOLEAN` 会导致同步任务失败。ODS 层改为 `TINYINT`，同步成功后在 DWD 层用 `CAST(col AS BOOLEAN)` 转换。
+
+### PostgreSQL → Lakehouse 类型映射
+
+| PostgreSQL 类型 | ❌ ODS 层不要用 | ✅ ODS 层用 |
+|---|---|---|
+| `BOOLEAN` | `BOOLEAN` | `TINYINT` |
+| `SERIAL` / `BIGSERIAL` | `SERIAL` | `BIGINT` |
+| `JSONB` / `JSON` | `JSON` | `STRING` |
+| `ARRAY` | `ARRAY` | `STRING`（JSON 序列化） |
+| `UUID` | `UUID` | `STRING` |
+| `NUMERIC(p,s)` | `FLOAT` | `DECIMAL(p,s)` |
+
+## 数据入仓 vs 数据入湖| 维度 | 数据入仓 | 数据入湖 |
+|------|---------|---------|
+| 目标 | Lakehouse 托管表 | 用户 Volume（对象存储） |
+| 格式 | 自动转为内部列式格式 | 保持原始文件格式 |
+| 查询性能 | 高（列式存储 + 索引） | 较低（需扫描原始文件） |
+| 适用场景 | 分析查询、BI 报表、数据仓库 | 数据暂存、原始数据归档、跨系统共享 |
+| 常用方式 | Studio 同步、PIPE、COPY INTO、SDK | PUT 文件、Python 脚本上传 |
+
+## 示例
+
+### 示例 1：用户不确定导入方式
+
+用户说："我有一个 MySQL 数据库，想把里面的订单表实时同步到 Lakehouse"
+
+路由逻辑：
+1. 数据源：MySQL（关系型数据库）
+2. 实时性：实时
+3. 同步范围：单表
+4. 需要 CDC：是（实时同步意味着需要捕获变更）
+→ 推荐：Studio 实时同步
+→ 路由到 `clickzetta-realtime-sync-pipeline` Skill
+
+### 示例 2：多种数据源混合场景
+
+用户说："我们有 Kafka 的用户行为日志，还有 MySQL 的业务数据，都要导入 Lakehouse"
+
+路由逻辑：
+1. Kafka 用户行为日志 → `clickzetta-kafka-ingest-pipeline`（PIPE 持续导入）
+2. MySQL 业务数据 → 确认实时性需求：
+   - 实时 → `clickzetta-realtime-sync-pipeline` 或 `clickzetta-cdc-sync-pipeline`
+   - 离线 → `clickzetta-batch-sync-pipeline`
+→ 分别引导到对应 Skill
+
+### 示例 3：简单的一次性文件导入
+
+用户说："我有一个 CSV 文件要导入"
+
+路由逻辑：
+1. 数据源：本地文件
+2. 一次性导入
+→ 路由到 `clickzetta-file-import-pipeline` Skill（支持文件上传 + COPY INTO）
+
+## 错误处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 用户无法确定数据源类型 | 询问数据当前存储位置（哪个系统/服务），帮助判断 |
+| 用户需求跨多种导入方式 | 拆分为多个独立的导入任务，分别路由到对应 Skill |
+| 推荐的 Skill 尚未创建 | 提供该导入方式的基本步骤和关键 SQL/API，引导用户参考官方文档 |
+| 用户的云环境不支持某种连接 | 执行 `cz-cli sql "SHOW CONNECTIONS" --sync` 检查可用连接类型，推荐替代方案 |
+| 数据量极大（TB 级） | 建议分批导入，优先使用 PIPE 或 Studio 同步任务（支持断点续传） |
+
+## 注意事项
+
+- 本 Skill 是路由入口，不直接执行复杂的 pipeline 搭建，而是引导到专项 Skill
+- 对于简单场景（SQL INSERT、单次 COPY INTO），可以直接在本 Skill 中完成
+- 推荐方案时需考虑用户的云环境（阿里云/腾讯云/AWS），不同环境支持的连接类型可能不同
+- 执行 `cz-cli sql "SHOW VCLUSTERS" --sync` 确认可用的虚拟集群，同步任务需要 SYNC 类型的 VCluster
+- 数据入仓是最常见的场景，数据入湖主要用于原始数据暂存或跨系统共享
+
+---
+
+## cz-cli 替代路径
+
+> 仅在 cz-cli 可用且 MCP 不可用时使用本节。
+> 本 Skill 是路由入口，cz-cli 路径的核心逻辑在各专项 Skill 的"cz-cli 替代路径"章节中。
+
+### 路由说明
+
+当 MCP 不可用时，各专项 Skill 均已提供 cz-cli 替代路径：
+
+| 数据源 | 推荐方式 | 对应 Skill 的 cz-cli 路径 |
+|--------|---------|--------------------------|
+| Kafka | PIPE 持续导入 | `clickzetta-kafka-ingest-pipeline` → cz-cli 替代路径 |
+| 对象存储 (OSS/S3/COS) | PIPE 持续导入 | `clickzetta-oss-ingest-pipeline` → cz-cli 替代路径 |
+| MySQL/PostgreSQL/SQL Server（实时单表） | Studio 实时同步 | `clickzetta-realtime-sync-pipeline` → cz-cli 替代路径 |
+| MySQL/PostgreSQL/SQL Server（实时多表/整库） | Studio 多表实时同步 | `clickzetta-cdc-sync-pipeline` → cz-cli 替代路径 |
+| MySQL/PostgreSQL/SQL Server（离线批量） | Studio 离线同步 | `clickzetta-batch-sync-pipeline` → cz-cli 替代路径 |
+
+### 简单场景直接执行（cz-cli 版）
+
+对于无需专项 Skill 的简单场景，可直接用 cz-cli agent 完成：
+
+```bash
+# SQL INSERT 导入（小数据量）
+cz-cli agent run "向表 <schema_name>.<table_name> 插入数据：<col1>=<val1>, <col2>=<val2>" \
+  --format a2a --dangerously-skip-permissions
+
+# COPY INTO 快速导入（从 Volume）
+cz-cli agent run "从 Volume <volume_name> 以 CSV 格式（有 header）将数据导入表 <schema_name>.<table_name>" \
+  --format a2a --dangerously-skip-permissions
+```

package/bin/skills/clickzetta-data-ingest-pipeline/eval_cases.jsonl

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"我想把数据导入 Lakehouse，但不确定用哪种方式","expected_skill":"clickzetta-data-ingest-pipeline","expected_output_contains":["数据源","实时","批量"]}
+{"case_id":"002","type":"should_call","user_input":"数据入仓有哪些方案？怎么选择？","expected_skill":"clickzetta-data-ingest-pipeline","expected_output_contains":["Kafka","对象存储","MySQL"]}
+{"case_id":"003","type":"should_call","user_input":"我有 MySQL 和 Kafka 两个数据源要导入 Lakehouse，分别用什么方式？","expected_skill":"clickzetta-data-ingest-pipeline","expected_output_contains":["CDC"]}
+{"case_id":"004","type":"should_call","user_input":"数据导入方案怎么选？实时和离线有什么区别？","expected_skill":"clickzetta-data-ingest-pipeline","expected_output_contains":["实时","离线","延迟"]}
+{"case_id":"005","type":"should_call","user_input":"ingest data into ClickZetta Lakehouse, what options do I have?","expected_skill":"clickzetta-data-ingest-pipeline","expected_output_contains":["Kafka","OSS","SDK"]}