@clickzetta/cz-cli-darwin-x64 0.3.92 → 0.3.94

package/bin/skills/clickzetta-ai-function/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: clickzetta-ai-function
+description: |
+  Use ClickZetta built-in AI functions: AI_COMPLETE (call LLMs) and AI_EMBEDDING (text vectors).
+  Covers CREATE API CONNECTION (TYPE ai_function), AI_COMPLETE, AI_EMBEDDING.
+  Keywords: AI_COMPLETE, AI_EMBEDDING, LLM, text embedding, semantic search, built-in AI function
+---
+
+# ClickZetta Built-in AI Functions
+
+ClickZetta provides two built-in AI functions that let you call LLMs and generate text embeddings directly from SQL — no cloud function deployment required. You only need an API Connection.
+
+See [references/ai-function-ddl.md](references/ai-function-ddl.md) for the full syntax reference.
+
+---
+
+## Quick Start
+
+```sql
+-- 1. Create an AI API Connection
+CREATE API CONNECTION conn_bailian
+    TYPE ai_function
+    BASE_URL = 'https://dashscope.aliyuncs.com/api/v1'
+    API_KEY = '<your-api-key>';
+
+-- 2. Call AI_COMPLETE to summarize text
+SELECT id,
+       AI_COMPLETE('conn_bailian:qwen3-plus', 'Summarize in one sentence: ' || content) AS summary
+FROM articles
+LIMIT 10;
+
+-- 3. Call AI_EMBEDDING to generate vectors
+SELECT id,
+       AI_EMBEDDING('conn_bailian:text-embedding-v3', content) AS vec
+FROM documents
+LIMIT 10;
+```
+
+---
+
+## Create an AI API Connection
+
+```sql
+CREATE API CONNECTION conn_bailian
+    TYPE ai_function
+    BASE_URL = 'https://dashscope.aliyuncs.com/api/v1'
+    API_KEY = '<key>';
+```
+
+| Parameter | Description |
+|---|---|
+| TYPE | Must be `ai_function` |
+| BASE_URL | Provider API base URL |
+| API_KEY | API key for the provider |
+
+---
+
+## AI_COMPLETE — Call an LLM
+
+```sql
+-- Text summarization
+SELECT id,
+       AI_COMPLETE('conn_bailian:qwen3-plus', 'Summarize in one sentence: ' || content) AS summary
+FROM articles;
+
+-- Sentiment analysis
+SELECT id, review,
+       AI_COMPLETE('conn_bailian:qwen3-plus',
+           'Classify the sentiment of the following review (positive/negative/neutral), return one word only: ' || review) AS sentiment
+FROM user_reviews;
+
+-- Text classification
+SELECT id, description,
+       AI_COMPLETE('conn_bailian:qwen3-plus',
+           'Classify this product description into one category (Electronics/Clothing/Food): ' || description) AS category
+FROM products;
+
+-- Via a platform Endpoint (pre-configured by admin, no API key needed)
+SELECT AI_COMPLETE('my_llm_endpoint:qwen3-plus', prompt_col) AS result
+FROM my_table;
+```
+
+---
+
+## AI_EMBEDDING — Text Embedding
+
+```sql
+-- Batch generate embeddings
+SELECT id, content,
+       AI_EMBEDDING('conn_bailian:text-embedding-v3', content) AS vec
+FROM documents;
+
+-- Semantic search (combined with a vector index)
+SELECT id, content,
+       cosine_distance(vec, AI_EMBEDDING('conn_bailian:text-embedding-v3', 'user query text')) AS dist
+FROM doc_embeddings
+ORDER BY dist
+LIMIT 10;
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Cause | Solution |
+|---|---|---|
+| AI_COMPLETE / AI_EMBEDDING error | Invalid API key or insufficient balance | Check the API_KEY in the API Connection |
+| Slow response | LLM API latency | Expected for large batches; consider filtering rows first |
+| Empty or unexpected output | Prompt not specific enough | Refine the prompt with clearer instructions |

package/bin/skills/clickzetta-ai-function/eval_cases.jsonl

@@ -0,0 +1,4 @@
+{"case_id":"001","type":"should_call","user_input":"How do I use AI_COMPLETE to summarize text in SQL?","expected_skill":"clickzetta-ai-function","expected_output_contains":["AI_COMPLETE","connection"]}
+{"case_id":"002","type":"should_call","user_input":"How do I generate text embeddings with AI_EMBEDDING?","expected_skill":"clickzetta-ai-function","expected_output_contains":["AI_EMBEDDING","connection"]}
+{"case_id":"003","type":"should_call","user_input":"How do I create an AI API Connection for Bailian?","expected_skill":"clickzetta-ai-function","expected_output_contains":["API CONNECTION","ai_function"]}
+{"case_id":"004","type":"should_call","user_input":"How do I do semantic search using vector embeddings in ClickZetta?","expected_skill":"clickzetta-ai-function","expected_output_contains":["AI_EMBEDDING","cosine_distance"]}

package/bin/skills/clickzetta-ai-function/references/ai-function-ddl.md

@@ -0,0 +1,106 @@
+# AI Function DDL Reference
+
+## Concepts
+
+ClickZetta provides two built-in AI functions that call external LLM APIs directly from SQL:
+
+| Function | Purpose |
+|---|---|
+| `AI_COMPLETE(source, prompt)` | Call an LLM to generate text (summarization, classification, Q&A, etc.) |
+| `AI_EMBEDDING(source, text)` | Generate a vector embedding for a text string |
+
+Both functions require an **API Connection** of `TYPE ai_function`, or a platform **Endpoint** pre-configured by an admin.
+
+---
+
+## CREATE API CONNECTION (AI Function)
+
+```sql
+CREATE API CONNECTION conn_bailian
+    TYPE ai_function
+    BASE_URL = 'https://dashscope.aliyuncs.com/api/v1'
+    API_KEY = '<key>';
+```
+
+| Parameter | Description |
+|---|---|
+| TYPE | `ai_function` — distinguishes from cloud function connections |
+| BASE_URL | Provider API base URL |
+| API_KEY | API key for authentication |
+
+---
+
+## AI_COMPLETE
+
+```sql
+AI_COMPLETE('<connection-name>:<model-name>', prompt)
+```
+
+| Argument | Description |
+|---|---|
+| `source` | `'<connection-name>:<model-name>'` — connection name and model name joined by `:` |
+| `prompt` | A string expression — the prompt sent to the LLM |
+
+Returns: `STRING` — the LLM's text response.
+
+### Examples
+
+```sql
+-- Summarization
+SELECT AI_COMPLETE('conn_bailian:qwen3-plus', 'Summarize in one sentence: ' || content) AS summary
+FROM articles;
+
+-- Sentiment analysis
+SELECT AI_COMPLETE('conn_bailian:qwen3-plus',
+    'Classify sentiment (positive/negative/neutral), one word only: ' || review) AS sentiment
+FROM user_reviews;
+
+-- Via platform Endpoint (pre-configured by admin)
+SELECT AI_COMPLETE('my_llm_endpoint:qwen3-plus', prompt_col) AS result
+FROM my_table;
+```
+
+---
+
+## AI_EMBEDDING
+
+```sql
+AI_EMBEDDING('<connection-name>:<model-name>', text)
+```
+
+| Argument | Description |
+|---|---|
+| `source` | `'<connection-name>:<model-name>'` — connection name and model name joined by `:` |
+| `text` | A string expression — the text to embed |
+
+Returns: `ARRAY<FLOAT>` — the embedding vector.
+
+### Examples
+
+```sql
+-- Generate embeddings
+SELECT id, AI_EMBEDDING('conn_bailian:text-embedding-v3', content) AS vec
+FROM documents;
+
+-- Semantic search
+SELECT id, content,
+       cosine_distance(vec, AI_EMBEDDING('conn_bailian:text-embedding-v3', 'query text')) AS dist
+FROM doc_embeddings
+ORDER BY dist
+LIMIT 10;
+```
+
+---
+
+## Source Format
+
+The first argument is always `'<connection-name>:<model-name>'`:
+
+| Part | Description |
+|---|---|
+| `<connection-name>` | Name of the API Connection created with `CREATE API CONNECTION` (or a platform Endpoint name) |
+| `<model-name>` | Model identifier supported by the provider, e.g. `qwen3-plus`, `text-embedding-v3` |
+
+Examples:
+- `'conn_bailian:qwen3-plus'` — use connection `conn_bailian` with model `qwen3-plus`
+- `'conn_bailian:text-embedding-v3'` — use connection `conn_bailian` with embedding model `text-embedding-v3`

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

@@ -1,179 +1,180 @@
 ---
 name: clickzetta-batch-sync-pipeline
 description: |
-  创建和管理 ClickZetta Lakehouse 离线同步（批量同步）任务，支持单表离线同步和多表离线同步两种模式。
-  单表模式适合简单的源→目标表同步；多表模式支持整库镜像、多表镜像、多表合并三种同步方式。
-  当用户说"离线同步"、"批量同步"、"batch sync"、"数据库同步到 Lakehouse"、"整库迁移"、
-  "多表同步"、"定期同步"、"周期性数据同步"、"分库分表合并"、"离线数据迁移"时触发。
-  包含单表/多表离线同步任务创建、数据源配置、字段映射、同步规则、调度部署、任务运维等
-  ClickZetta Studio 特有逻辑。
-  Keywords: batch sync, offline sync, full load, mirror, multi-table sync
+  Create and manage ClickZetta Lakehouse batch sync tasks, supporting both single-table and multi-table modes.
+  Single-table mode is suitable for simple source-to-target table sync; multi-table mode supports full database mirror,
+  multi-table mirror, and sharded table merge.
+  Triggered when the user says "batch sync", "offline sync", "sync database to Lakehouse", "full database migration",
+  "multi-table sync", "periodic sync", "scheduled data sync", "sharded table merge", "offline data migration".
+  Covers single-table/multi-table batch sync task creation, data source configuration, column mapping,
+  sync rules, scheduling, deployment, and task operations — all ClickZetta Studio specific logic.
+  Keywords: batch sync, offline sync, full load, mirror, multi-table sync, scheduled sync
 ---
 
-# 离线同步（批量同步）Pipeline 工作流
+# Batch Sync Pipeline Workflow
 
-## 向导：收集必要信息
+## Wizard: Collect Required Information
 
-开始创建同步任务前，优先使用交互式问答工具（如 `question`）收集以下信息并弹出选项菜单；若无此类工具，则用文字一次性列出所有问题：
+Before creating a sync task, use an interactive question tool (e.g., `question`) to collect the following information via option menus. If no such tool is available, list all questions in text at once:
 
 ```
 question({
   questions: [
     {
-      question: "数据源类型和名称是什么？",
+      question: "What is the data source type and name?",
       options: [
-        { label: "MySQL", description: "如 aliyun_mysql、rds_mysql" },
-        { label: "PostgreSQL", description: "如 pg_prod、aurora_pg" },
-        { label: "SQL Server", description: "如 sqlserver_prod" },
-        { label: "OSS/S3/COS 对象存储", description: "如 oss_bucket、s3_data" }
+        { label: "MySQL", description: "e.g., aliyun_mysql, rds_mysql" },
+        { label: "PostgreSQL", description: "e.g., pg_prod, aurora_pg" },
+        { label: "SQL Server", description: "e.g., sqlserver_prod" },
+        { label: "OSS/S3/COS Object Storage", description: "e.g., oss_bucket, s3_data" }
       ]
     },
     {
-      question: "同步范围是什么？",
+      question: "What is the sync scope?",
       options: [
-        { label: "单表同步", description: "指定一张源表同步到目标表" },
-        { label: "多表镜像", description: "整库或指定多张表批量同步" },
-        { label: "分库分表合并", description: "多张源表合并到一张目标表" }
+        { label: "Single-table sync", description: "Sync one source table to one target table" },
+        { label: "Multi-table mirror", description: "Sync entire database or multiple selected tables" },
+        { label: "Sharded table merge", description: "Merge multiple source tables into one target table" }
       ]
     },
     {
-      question: "写入模式？",
+      question: "Write mode?",
       options: [
-        { label: "全量覆盖（OVERWRITE）", description: "每次全量覆盖目标表，推荐" },
-        { label: "增量追加（APPEND）", description: "追加新数据，不删除历史" }
+        { label: "Full overwrite (OVERWRITE)", description: "Overwrite target table each run, recommended" },
+        { label: "Incremental append (APPEND)", description: "Append new data without deleting history" }
       ]
     }
   ]
 })
 ```
 
-收集到信息后，还需确认：目标 schema（如 `ods`）、调度时间（如每天 02:00）。这两项可以在用户回答后直接询问，或从上下文推断。
+After collecting the above, also confirm: target schema (e.g., `ods`) and schedule time (e.g., daily at 02:00). These can be asked after the user responds, or inferred from context.
 
-**如果用户已经提供了足够信息，直接进入工作流，不再弹出菜单。**
+**If the user has already provided sufficient information, proceed directly to the workflow without showing the menu.**
 
 ---
 
-## 前置依赖
+## Prerequisites
 
-- ClickZetta Lakehouse Studio 账户，具备创建同步任务、目标表的权限
-- 源端数据源已在 Studio 中配置（具备 SELECT 权限）
-- 目标端 Lakehouse 数据源可用（具备 CREATE、INSERT 权限）
-- 已安装 cz-cli 并完成 profile 配置（`cz-cli profile status` 验证连接）
+- ClickZetta Lakehouse Studio account with permissions to create sync tasks and target tables
+- Source data source already configured in Studio (with SELECT permission)
+- Target Lakehouse data source available (with CREATE and INSERT permissions)
+- cz-cli installed and profile configured (verify with `cz-cli profile status`)
 
 ---
 
-## 适用场景
+## Applicable Scenarios
 
-- 将外部数据库（MySQL / PostgreSQL / SQL Server 等）的数据定期同步到 Lakehouse
-- 单表离线同步：简单的源表 → 目标表周期性同步
-- 多表离线同步：整库迁移、多表批量同步、分库分表合并
-- 数据时效性要求不高，按天/小时等周期批量更新
+- Periodically sync data from external databases (MySQL / PostgreSQL / SQL Server, etc.) to Lakehouse
+- Single-table batch sync: simple source table → target table periodic sync
+- Multi-table batch sync: full database migration, multi-table batch sync, sharded table merge
+- Low data freshness requirements — batch updates on daily/hourly schedules
 
 ---
 
-## 模式选择
+## Mode Selection
 
-| 维度 | 单表离线同步 | 多表离线同步 |
-|------|------------|------------|
-| 任务类型 ID | `1`（DI/INTEGRATION） | `291`（MULTI_DI） |
-| 同步粒度 | 单张源表 → 单张目标表 | 整库 / 多表 → 多张目标表 |
-| 适用场景 | 简单同步、精细控制单表 | 整库迁移、批量同步、分库分表合并 |
-| Schema Evolution | 不支持 | 支持（新增字段自动适配） |
-| 自动建表 | 需手动创建或快速创建 | 目标表不存在时自动创建 |
-| 写入模式 | 由数据源决定 | overwrite / upsert 可选 |
+| Dimension | Single-table Batch Sync | Multi-table Batch Sync |
+|-----------|------------------------|----------------------|
+| Task Type ID | `1` (DI/INTEGRATION) | `291` (MULTI_DI) |
+| Sync Granularity | One source table → one target table | Full database / multiple tables → multiple target tables |
+| Use Case | Simple sync, fine-grained single-table control | Full database migration, batch sync, sharded table merge |
+| Schema Evolution | Not supported | Supported (new columns auto-adapted) |
+| Auto Table Creation | Manual or quick-create required | Auto-creates target table if not exists |
+| Write Mode | Determined by data source | overwrite / upsert selectable |
 
-> **重要**：这两种任务类型均为 UI_ONLY 类型，脚本内容必须在 Studio Web UI 中配置。
-> cz-cli 负责任务创建、调度配置、发布和运维；数据源选择、字段映射等内容配置在 Studio UI 完成。
+> **Important**: Both task types are UI_ONLY types — task content must be configured in the Studio Web UI.
+> cz-cli handles task creation, scheduling, deployment, and operations; data source selection and column mapping are configured in Studio UI.
 
 ---
 
-## 工作流
+## Workflow
 
-> **重要**：离线同步任务的**内容配置**（来源表选择、字段映射、同步规则等）必须在 Studio Web UI 中完成。
-> cz-cli 负责任务创建、调度配置、发布和运维；数据源选择、字段映射等内容配置在 Studio UI 完成。
+> **Important**: Batch sync task **content configuration** (source table selection, column mapping, sync rules, etc.) must be completed in the Studio Web UI.
+> cz-cli handles task creation, scheduling, deployment, and operations; data source selection and column mapping are configured in Studio UI.
 
-### 步骤 1：用 cz-cli 创建任务
+### Step 1: Create Task with cz-cli
 
 ```bash
-# 单表离线同步（task_type=1，即 DI/INTEGRATION）
+# Single-table batch sync (task_type=1, i.e., DI/INTEGRATION)
 cz-cli task create "sync_orders_daily" --type DI --folder <folder_name>
 
-# 多表离线同步（task_type=291，即 MULTI_DI）
+# Multi-table batch sync (task_type=291, i.e., MULTI_DI)
 cz-cli task create "sync_ecommerce_db" --type MULTI_DI --folder <folder_name>
 ```
 
-命令返回 `task_id` 和 `studio_url`，在 `studio_url` 中完成数据源配置。
+The command returns `task_id` and `studio_url`. Complete data source configuration at the `studio_url`.
 
-### 步骤 2：在 Studio UI 中配置同步内容
+### Step 2: Configure Sync Content in Studio UI
 
-打开步骤 1 返回的 `studio_url`，在 Studio 中完成：
+Open the `studio_url` returned in Step 1 and complete the following in Studio:
 
-**来源数据配置**
-- 选择源端数据源类型和连接（支持的数据源类型以 Studio UI 中显示为准，可通过 `cz-cli datasource list` 查看已配置的数据源）
-- 单表：指定 schema 和表名
-- 多表：选择整库 / 勾选多表 / 配置合并规则
+**Source Data Configuration**
+- Select source data source type and connection (supported types are shown in Studio UI; use `cz-cli datasource list` to view configured data sources)
+- Single-table: specify schema and table name
+- Multi-table: select full database / check multiple tables / configure merge rules
 
-**目标设置**
-- 选择目标 Lakehouse 数据源和 workspace
-- 配置目标 schema 和表名
-- 多表模式可配置命名规则（支持 `{SOURCE_DATABASE}`、`{SOURCE_TABLE}` 变量）
+**Target Settings**
+- Select target Lakehouse data source and workspace
+- Configure target schema and table name
+- Multi-table mode supports naming rules (with `{SOURCE_DATABASE}`, `{SOURCE_TABLE}` variables)
 
-**同步规则（多表模式）**
-- Schema Evolution：源端新增字段自动适配；删除字段写入 Null
-- 写入模式：非主键表 → overwrite；主键表 → overwrite 或 upsert
+**Sync Rules (Multi-table mode)**
+- Schema Evolution: new columns from source are auto-adapted; deleted columns are written as Null
+- Write Mode: non-primary-key tables → overwrite; primary-key tables → overwrite or upsert
 
-### 步骤 3：在 Studio UI 中调试运行
+### Step 3: Debug Run in Studio UI
 
-点击「运行」按钮进行调试，验证数据源连接和配置是否正确。
+Click the "Run" button to debug and verify data source connectivity and configuration.
 
-### 步骤 4：用 cz-cli 配置调度和发布
+### Step 4: Configure Scheduling and Deploy with cz-cli
 
 ```bash
-# 配置调度（具体参数见 --help）
+# Configure schedule (see --help for parameters)
 cz-cli task save-cron <task_name> --help
 
-# 发布任务
+# Deploy task
 cz-cli task deploy <task_name> -y
 ```
 
-> 离线同步任务（task_type=1 和 291）必须使用 Sync VCluster，不能使用通用型或分析型 VCluster。
+> Batch sync tasks (task_type=1 and 291) must use a Sync VCluster — general-purpose or analytics VClusters are not supported.
 
-### 步骤 5：验证与监控
+### Step 5: Verify and Monitor
 
 ```bash
-cz-cli runs list --task <task_name>      # 查看运行记录
-cz-cli runs detail <run_id>              # 查看运行详情
-cz-cli attempts log <run_id>             # 查看执行日志
-cz-cli runs refill <task_name> --help    # 补数据（--help 查看参数）
+cz-cli runs list --task <task_name>      # View run history
+cz-cli runs detail <run_id>              # View run details
+cz-cli attempts log <run_id>             # View execution logs
+cz-cli runs refill <task_name> --help    # Backfill data (--help for parameters)
 ```
 
 ---
 
-## 任务运维操作
+## Task Operations
 
-| 操作 | cz-cli 命令 | 说明 |
-|------|------------|------|
-| 下线 | `cz-cli task undeploy <task> -y` | 停止任务并从调度系统移除（不可逆） |
-| 补数据 | `cz-cli runs refill <task> --from D --to D -y` | 对历史周期进行数据补录 |
-| 查看依赖 | `cz-cli runs deps <task>` | 查看已发布的上下游依赖 |
-| 查看运行 | `cz-cli runs list --task <task>` | 查看运行实例列表 |
+| Operation | cz-cli Command | Description |
+|-----------|---------------|-------------|
+| Undeploy | `cz-cli task undeploy <task> -y` | Stop task and remove from scheduler (irreversible) |
+| Backfill | `cz-cli runs refill <task> --from D --to D -y` | Backfill data for historical periods |
+| View Dependencies | `cz-cli runs deps <task>` | View published upstream/downstream dependencies |
+| View Runs | `cz-cli runs list --task <task>` | View run instance list |
 
-多表离线同步任务在 Studio「任务运维」→「周期任务」中管理，可查看：
-- 任务实例 Tab：每张表的读取/写入行数和同步速率
-- 同步对象 Tab：所有源表和目标表的映射关系
+Multi-table batch sync tasks are managed in Studio under "Task Operations" → "Scheduled Tasks", where you can view:
+- Task Instance Tab: read/write row counts and sync rate per table
+- Sync Objects Tab: mapping of all source tables to target tables
 
 ---
 
-## 交付验收 Checklist
+## Delivery Acceptance Checklist
 
-同步任务发布运行后，**必须逐项验证**：
+After the sync task is deployed and running, **verify each item**:
 
 ```sql
--- 1. 行数比对：目标表行数与源端一致
+-- 1. Row count comparison: target table row count matches source
 SELECT COUNT(*) FROM <ods_schema>.<table>;
--- 与源端 MySQL/PG 执行 SELECT COUNT(*) FROM <table> 对比
+-- Compare with source MySQL/PG: SELECT COUNT(*) FROM <table>
 
--- 2. 关键字段非空率
+-- 2. Key field non-null rate
 SELECT
   COUNT(*) AS total,
   COUNT(key_field) AS non_null,
@@ -181,47 +182,46 @@ SELECT
 FROM <ods_schema>.<table>;
 ```
 
-**验收标准：**
-- [ ] 目标表行数与源端一致
-- [ ] 关键字段非空率符合预期
-- [ ] 同步任务最近运行状态为 SUCCESS
-- [ ] 字段类型映射正确（重点检查 BIT/ENUM/TEXT 等异构类型）
-- [ ] 调度 Cron 配置正确，下次执行时间符合预期
+**Acceptance Criteria:**
+- [ ] Target table row count matches source
+- [ ] Key field non-null rate meets expectations
+- [ ] Latest task run status is SUCCESS
+- [ ] Column type mapping is correct (pay attention to BIT/ENUM/TEXT and other heterogeneous types)
+- [ ] Cron schedule is configured correctly; next execution time is as expected
 
 ---
 
-## 故障排除
+## Troubleshooting
 
-| 问题 | 排查方向 |
-|------|---------|
-| 任务创建失败 | 确认账号有创建任务权限；检查文件夹 ID 是否存在 |
-| 源端连接失败 | 检查数据源配置中的连接信息、网络可达性、账号权限 |
-| 字段映射失败 | 检查源表和目标表的字段类型兼容性 |
-| 同步速度慢 | 调整并发数（最大 10）和同步速率；检查源端数据库负载 |
-| Schema Evolution 失败 | 不支持修改主键字段；字段类型仅支持同类型扩展（int8→int16→int32→int64） |
-| 多表同步部分表失败 | 在实例详情的「同步对象」Tab 查看各表状态；可对失败表单独重跑 |
-| upsert 模式数据不一致 | 确认目标表有正确的主键定义；检查源端数据是否有主键冲突 |
-| VCluster 类型错误 | 离线同步必须使用 Sync VCluster，通过 `SHOW VCLUSTERS` 确认类型 |
+| Issue | Investigation |
+|-------|--------------|
+| Task creation failed | Verify account has task creation permissions; check if folder ID exists |
+| Source connection failed | Check data source connection info, network reachability, account permissions |
+| Column mapping failed | Check column type compatibility between source and target tables |
+| Slow sync speed | Adjust concurrency (max 10) and sync rate; check source database load |
+| Schema Evolution failed | Primary key column changes not supported; type changes only support same-type widening (int8→int16→int32→int64) |
+| Partial table failure in multi-table sync | Check per-table status in instance detail "Sync Objects" tab; failed tables can be re-run individually |
+| Data inconsistency in upsert mode | Verify target table has correct primary key definition; check for primary key conflicts in source data |
+| Wrong VCluster type | Batch sync must use Sync VCluster — verify type with `SHOW VCLUSTERS` |
 
 ---
 
-## 注意事项
+## Notes
 
-**权限要求**
-- 源端：数据源配置的账号需具备 SELECT 权限
-- 目标端：任务负责人需具备 CREATE 和 INSERT 权限
+**Permission Requirements**
+- Source: the account configured in the data source must have SELECT permission
+- Target: the task owner must have CREATE and INSERT permissions
 
-**性能考虑**
-- 合理配置并发度，避免对源端数据库造成过大压力
-- 首次执行需初始化所有同步对象，可能耗时较长
-- 选择源端数据库压力较小的时间窗口执行调度
+**Performance Considerations**
+- Configure concurrency appropriately to avoid excessive load on the source database
+- First execution initializes all sync objects and may take longer
+- Schedule execution during low-load windows on the source database
 
-**Schema Evolution 限制（多表离线同步）**
-- 不支持修改主键字段（Lakehouse 主键表限制）
-- 字段类型修改仅支持同类型扩展（int8 → int16 → int32 → int64）
-- 不支持跨类型转换（如 int → double）
-
-**支持的数据源**
-- 来源端：关系型数据库（MySQL、PostgreSQL、SQL Server 等）及其云变体（Aurora、PolarDB 等），具体支持列表以 Studio UI 中显示为准，可通过 `cz-cli datasource list` 查看已配置的数据源
-- 目标端：Lakehouse
+**Schema Evolution Limitations (Multi-table Batch Sync)**
+- Primary key column changes are not supported (Lakehouse primary key table limitation)
+- Column type changes only support same-type widening (int8 → int16 → int32 → int64)
+- Cross-type conversions are not supported (e.g., int → double)
 
+**Supported Data Sources**
+- Source: relational databases (MySQL, PostgreSQL, SQL Server, etc.) and their cloud variants (Aurora, PolarDB, etc.). The specific supported list is shown in Studio UI; use `cz-cli datasource list` to view configured data sources
+- Target: Lakehouse

package/bin/skills/clickzetta-batch-sync-pipeline/eval_cases.jsonl

@@ -1,5 +1,5 @@
-{"case_id":"001","type":"should_call","user_input":"怎么创建离线同步任务把 MySQL 表定期同步到 Lakehouse？","expected_skill":"clickzetta-batch-sync-pipeline","expected_output_contains":["离线同步","Cron","调度"]}
-{"case_id":"002","type":"should_call","user_input":"多表离线同步支持自动建表吗？","expected_skill":"clickzetta-batch-sync-pipeline","expected_output_contains":["自动创建","多表"]}
-{"case_id":"003","type":"should_call","user_input":"离线同步的单表模式和多表模式怎么选？","expected_skill":"clickzetta-batch-sync-pipeline","expected_output_contains":["单表","多表","task_type"]}
-{"case_id":"004","type":"should_call","user_input":"批量同步支持 Schema Evolution 吗？新增字段会自动适配吗？","expected_skill":"clickzetta-batch-sync-pipeline","expected_output_contains":["Schema Evolution","多表"]}
-{"case_id":"005","type":"should_call","user_input":"怎么配置离线同步任务的调度周期？用 Cron 表达式吗？","expected_skill":"clickzetta-batch-sync-pipeline","expected_output_contains":["Cron","调度"]}
+{"case_id":"001","type":"should_call","user_input":"How do I create a batch sync task to periodically sync a MySQL table to Lakehouse?","expected_skill":"clickzetta-batch-sync-pipeline","expected_output_contains":["batch sync","Cron","schedule"]}
+{"case_id":"002","type":"should_call","user_input":"Does multi-table batch sync support auto table creation?","expected_skill":"clickzetta-batch-sync-pipeline","expected_output_contains":["auto-create","multi-table"]}
+{"case_id":"003","type":"should_call","user_input":"How do I choose between single-table and multi-table batch sync modes?","expected_skill":"clickzetta-batch-sync-pipeline","expected_output_contains":["single-table","multi-table","task_type"]}
+{"case_id":"004","type":"should_call","user_input":"Does batch sync support Schema Evolution? Will new columns be auto-adapted?","expected_skill":"clickzetta-batch-sync-pipeline","expected_output_contains":["Schema Evolution","multi-table"]}
+{"case_id":"005","type":"should_call","user_input":"How do I configure the schedule for a batch sync task? Does it use Cron expressions?","expected_skill":"clickzetta-batch-sync-pipeline","expected_output_contains":["Cron","schedule"]}