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

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-kafka-ingest-pipeline/SKILL.md

@@ -39,29 +39,18 @@ description: |
 - Kafka 集群网络可达（确认 bootstrap 地址和端口）
 - 已知 Kafka Topic 名称和消息格式
 - 认证信息（如需要）：SASL 用户名/密码
-- **执行环境（满足其一即可，优先使用 cz-cli）**：
-  - **cz-cli 路径**：已安装 cz-cli（`pip install cz-cli`），并完成 `cz-cli configure` 配置
-  - **MCP 路径**：clickzetta-mcp-server 工具可用（`LH_execute_query`、`LH_show_object_list` 等）
+- **执行环境**：已安装并配置 cz-cli
 
-## 环境探测（执行前必读）
+## 执行环境
 
-在开始任何操作前，先判断当前执行环境：
+所有 SQL 通过 `cz-cli sql` 执行：
 
-**第一步：检测 cz-cli 是否可用**
 ```bash
-cz-cli --version
+cz-cli --version   # 确认 cz-cli 可用
+cz-cli sql "SELECT 1" --sync   # 验证连接
 ```
-- 若命令存在 → **走 cz-cli 路径**（见本文档末尾"cz-cli 替代路径"章节）
-- 若命令不存在 → 继续检测 MCP
 
-**第二步：检测 MCP 是否可用（仅在 cz-cli 不可用时）**
-
-尝试调用 `LH_execute_query` 工具执行一条简单 SQL（如 `SELECT 1`）。
-- 若工具存在于 tool list → **走 MCP 路径**（本文档默认路径）
-- 若工具不存在 → 停止执行，提示用户：
-  > "当前环境既无 cz-cli 也无 MCP 工具，请安装其中之一后重试。
-  > cz-cli 安装：`pip install cz-cli`，然后运行 `cz-cli configure`
-  > MCP 安装：参考 clickzetta-mcp-server 配置文档"
+需要 cz-cli，请参考官方文档安装并完成配置后重试。
 
 ## ⚠️ 关键注意事项
 
@@ -663,10 +652,8 @@ COPY INTO ods.secure_events FROM (
 
 ---
 
-## cz-cli 替代路径
+## cz-cli 执行路径
 
-> 仅在 cz-cli 可用且 MCP 不可用时使用本节。步骤编号与上方 MCP 路径对应。
-> 所有操作通过 `cz-cli agent run` 委托给内置 agent 完成，agent 内置完整的 MCP 工具访问能力。
 
 ### 路径一：READ_KAFKA Pipe（cz-cli 版）
 

package/bin/skills/clickzetta-metadata/SKILL.md

@@ -35,6 +35,27 @@ description: |
 
 # ClickZetta 元数据查询指南
 
+## 执行方式
+
+所有 SQL 通过 `cz-cli sql` 执行，无需 MCP 工具。
+
+**执行示例：**
+
+```bash
+# 执行 SHOW/DESC 查询
+cz-cli sql "SHOW TABLES" --sync -o table
+
+# 执行 information_schema 查询
+cz-cli sql "SELECT * FROM information_schema.tables LIMIT 10" --sync -o table
+
+# 执行 load_history 查询
+cz-cli sql "SELECT * FROM load_history('my_schema.my_table') LIMIT 20" --sync -o table
+```
+
+注意：`--sync` 等待结果返回；`-o table` 输出为表格格式便于阅读。
+
+---
+
 ## 选择查询方式
 
 | 场景 | 推荐方式 | 原因 |
@@ -138,7 +159,7 @@ SHOW VCLUSTERS WHERE state = 'RUNNING';
 
 -- 作业（最近 7 天，最多 10000 条，不支持 ORDER BY）
 SHOW JOBS LIMIT 20;
-SHOW JOBS IN VCLUSTER default_ap LIMIT 20;
+SHOW JOBS IN VCLUSTER default LIMIT 20;
 
 -- 动态表刷新历史（最近 7 天）
 SHOW DYNAMIC TABLE REFRESH HISTORY LIMIT 20;
@@ -169,7 +190,7 @@ SHOW SHARES;
 DESC my_table;
 DESC EXTENDED my_table;          -- 含 last_modified_time/properties/statistics
 DESC SCHEMA my_schema;
-DESC VCLUSTER default_ap;
+DESC VCLUSTER default;
 DESC VOLUME my_volume;
 DESC CONNECTION my_oss_conn;
 DESC FUNCTION my_schema.my_function;  -- 仅支持外部函数

package/bin/skills/clickzetta-monitoring/SKILL.md

@@ -13,6 +13,22 @@ description: |
   Keywords: monitoring, job status, performance, resource usage, SHOW JOBS, slow query
 ---
 
+## 执行方式
+
+所有 SQL 通过 `cz-cli sql` 执行，无需 MCP 工具：
+
+```bash
+# 执行查询
+cz-cli sql "SHOW JOBS LIMIT 20" --sync -o table
+
+# 执行 information_schema 查询
+cz-cli sql "SELECT * FROM information_schema.job_history WHERE pt_date >= CAST(CURRENT_DATE - INTERVAL 1 DAY AS DATE) LIMIT 10" --sync -o table
+```
+
+注意：`--sync` 等待结果返回；`-o table` 输出为表格格式便于阅读。
+
+---
+
 # ClickZetta 作业监控与分析
 
 阅读 [references/show-jobs.md](references/show-jobs.md) 了解 SHOW JOBS 语法。
@@ -27,7 +43,7 @@ description: |
 SHOW JOBS;
 
 -- 查看指定集群的作业
-SHOW JOBS IN VCLUSTER default_ap;
+SHOW JOBS IN VCLUSTER default;
 
 -- 查看执行时间超过2分钟的慢查询
 SHOW JOBS WHERE execution_time > INTERVAL 2 MINUTE;
@@ -36,7 +52,7 @@ SHOW JOBS WHERE execution_time > INTERVAL 2 MINUTE;
 SHOW JOBS WHERE status = 'FAILED';
 
 -- 限制返回数量
-SHOW JOBS IN VCLUSTER default_ap LIMIT 50;
+SHOW JOBS IN VCLUSTER default LIMIT 50;
 ```
 
 ---

package/bin/skills/clickzetta-monitoring/references/show-jobs.md

@@ -24,10 +24,10 @@ SHOW JOBS [IN VCLUSTER vc_name] [LIKE 'pattern'] [WHERE <expr>] [LIMIT num];
 SHOW JOBS;
 
 -- 查看指定集群的作业
-SHOW JOBS IN VCLUSTER default_ap;
+SHOW JOBS IN VCLUSTER default;
 
 -- 查看执行时间超过2分钟的作业
-SHOW JOBS IN VCLUSTER default_ap WHERE execution_time > INTERVAL 2 MINUTE;
+SHOW JOBS IN VCLUSTER default WHERE execution_time > INTERVAL 2 MINUTE;
 
 -- 限制返回100条
 SHOW JOBS LIMIT 100;

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

@@ -26,29 +26,18 @@ description: |
 
 - ClickZetta Lakehouse 账户，具备创建 PIPE、表、存储连接、Volume 等权限
 - 对象存储桶可达（Endpoint、AccessKey 或 Role ARN）
-- **执行环境（满足其一即可，优先使用 cz-cli）**：
-  - **cz-cli 路径**：已安装 cz-cli（`pip install cz-cli`），并完成 `cz-cli configure` 配置
-  - **MCP 路径**：clickzetta-mcp-server 工具可用（`LH_execute_query`、`LH_show_object_list` 等）
+- **执行环境**：已安装并配置 cz-cli
 
-## 环境探测（执行前必读）
+## 执行环境
 
-在开始任何操作前，先判断当前执行环境：
+所有 SQL 通过 `cz-cli sql` 执行：
 
-**第一步：检测 cz-cli 是否可用**
 ```bash
-cz-cli --version
+cz-cli --version   # 确认 cz-cli 可用
+cz-cli sql "SELECT 1" --sync   # 验证连接
 ```
-- 若命令存在 → **走 cz-cli 路径**（见本文档末尾"cz-cli 替代路径"章节）
-- 若命令不存在 → 继续检测 MCP
 
-**第二步：检测 MCP 是否可用（仅在 cz-cli 不可用时）**
-
-尝试调用 `LH_execute_query` 工具执行一条简单 SQL（如 `SELECT 1`）。
-- 若工具存在于 tool list → **走 MCP 路径**（本文档默认路径）
-- 若工具不存在 → 停止执行，提示用户：
-  > "当前环境既无 cz-cli 也无 MCP 工具，请安装其中之一后重试。
-  > cz-cli 安装：`pip install cz-cli`，然后运行 `cz-cli configure`
-  > MCP 安装：参考 clickzetta-mcp-server 配置文档"
+需要 cz-cli，请参考官方文档安装并完成配置后重试。
 
 ## 核心概念
 
@@ -82,7 +71,7 @@ cz-cli --version
 #### 步骤 1：创建存储连接（Storage Connection）
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 -- 密钥方式（LIST_PURGE 模式支持）
 CREATE STORAGE CONNECTION IF NOT EXISTS my_oss_connection
   TYPE OSS
@@ -102,7 +91,7 @@ CREATE STORAGE CONNECTION IF NOT EXISTS my_oss_connection
 #### 步骤 2：创建外部 Volume
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 CREATE EXTERNAL VOLUME IF NOT EXISTS pipe_volume
   LOCATION 'oss://my-bucket/data-path/'
   USING CONNECTION my_oss_connection
@@ -121,7 +110,7 @@ CREATE EXTERNAL VOLUME IF NOT EXISTS pipe_volume
 在创建 PIPE 之前，先用 COPY INTO 验证数据能正常加载：
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 COPY INTO my_schema.target_table
 FROM VOLUME pipe_volume
 USING CSV OPTIONS ('header' = 'true', 'delimiter' = ',') PURGE=true;
@@ -134,7 +123,7 @@ USING CSV OPTIONS ('header' = 'true', 'delimiter' = ',') PURGE=true;
 #### 步骤 4：创建 PIPE（LIST_PURGE 模式）
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 CREATE PIPE IF NOT EXISTS my_oss_pipe
   INGEST_MODE = 'LIST_PURGE'
   VIRTUAL_CLUSTER = 'my_vc'
@@ -168,7 +157,7 @@ USING CSV OPTIONS ('header' = 'true') PURGE=true;
 #### 步骤 5：验证 PIPE 状态
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 DESC PIPE EXTENDED my_oss_pipe;
 ```
 
@@ -190,7 +179,7 @@ DESC PIPE EXTENDED my_oss_pipe;
 #### 步骤 1：创建存储连接（Role ARN 方式）
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 CREATE STORAGE CONNECTION IF NOT EXISTS my_oss_role_connection
   TYPE OSS
   ENDPOINT = 'oss-cn-hangzhou.aliyuncs.com'
@@ -201,7 +190,7 @@ CREATE STORAGE CONNECTION IF NOT EXISTS my_oss_role_connection
 #### 步骤 2：创建外部 Volume
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 CREATE EXTERNAL VOLUME IF NOT EXISTS pipe_event_volume
   LOCATION 'oss://my-bucket/data-path/'
   USING CONNECTION my_oss_role_connection
@@ -212,7 +201,7 @@ CREATE EXTERNAL VOLUME IF NOT EXISTS pipe_event_volume
 #### 步骤 3：创建 PIPE（EVENT_NOTIFICATION 模式）
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 CREATE PIPE IF NOT EXISTS my_oss_event_pipe
   INGEST_MODE = 'EVENT_NOTIFICATION'
   VIRTUAL_CLUSTER = 'my_vc'
@@ -245,7 +234,7 @@ USING CSV;
 #### 步骤 1：创建目标表
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 CREATE TABLE IF NOT EXISTS my_schema.target_table (
   id STRING,
   name STRING,
@@ -257,7 +246,7 @@ CREATE TABLE IF NOT EXISTS my_schema.target_table (
 #### 步骤 2：创建存储连接（access_id/access_key 语法）
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 CREATE STORAGE CONNECTION IF NOT EXISTS my_batch_conn
   TYPE OSS
   ENDPOINT = 'oss-cn-shanghai-internal.aliyuncs.com'
@@ -273,7 +262,7 @@ CREATE STORAGE CONNECTION IF NOT EXISTS my_batch_conn
 #### 步骤 3：创建外部 Volume（启用目录自动刷新）
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 CREATE EXTERNAL VOLUME IF NOT EXISTS my_batch_volume
   LOCATION 'oss://my-bucket/data-path/'
   USING CONNECTION my_batch_conn
@@ -293,7 +282,7 @@ CREATE EXTERNAL VOLUME IF NOT EXISTS my_batch_volume
 #### 步骤 4a：INSERT INTO 从 Volume 导入（支持过滤转换）
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 INSERT INTO my_schema.target_table
 SELECT * FROM VOLUME my_batch_volume (
   id STRING,
@@ -315,7 +304,7 @@ WHERE amount > 0;
 #### 步骤 4b：COPY INTO 从 Volume 导入（简洁语法）
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 COPY INTO my_schema.target_table
 FROM VOLUME my_batch_volume (
   id STRING,
@@ -334,7 +323,7 @@ FROM VOLUME my_batch_volume (
 #### 步骤 5：验证导入结果
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 SELECT COUNT(*) AS total_rows FROM my_schema.target_table;
 SELECT * FROM my_schema.target_table LIMIT 10;
 ```
@@ -346,7 +335,7 @@ SELECT * FROM my_schema.target_table LIMIT 10;
 ### 查看 PIPE 详细状态
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 DESC PIPE EXTENDED my_oss_pipe;
 ```
 
@@ -359,7 +348,7 @@ DESC PIPE EXTENDED my_oss_pipe;
 ### 查看加载历史
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 SELECT * FROM load_history('my_schema.target_table')
 ORDER BY last_load_time DESC
 LIMIT 20;
@@ -372,7 +361,7 @@ LIMIT 20;
 PIPE 执行的作业会自动打上 `query_tag`，格式为：`pipe.<workspace_name>.<schema_name>.<pipe_name>`
 
 ```sql
--- 使用 LH_execute_query 执行
+-- 通过 cz-cli sql "<SQL>" --sync 执行
 -- 在 JOBS 列表中过滤 PIPE 相关作业
 SHOW JOBS WHERE query_tag = 'pipe.my_workspace.my_schema.my_oss_pipe';
 ```
@@ -450,10 +439,7 @@ DROP PIPE IF EXISTS my_oss_pipe;
 
 ---
 
-## cz-cli 替代路径
-
-> 仅在 cz-cli 可用且 MCP 不可用时使用本节。步骤编号与上方 MCP 路径对应。
-> 所有操作通过 `cz-cli agent run` 委托给内置 agent 完成，agent 内置完整的 MCP 工具访问能力。
+## cz-cli 执行路径
 
 ### 模式 A：LIST_PURGE 扫描模式（cz-cli 版）
 

package/bin/skills/cz-cli-inner/SKILL.md

@@ -32,14 +32,14 @@ cz-cli workspace current                      Show current workspace
 
 cz-cli task list                              List Studio tasks
 cz-cli task create <name> --type <TYPE>       Create task (SQL/PYTHON/SHELL/SPARK/FLOW)
-cz-cli task content <task>                    Get task script and config
-cz-cli task save-content <task> --file <f>    Save task script
+cz-cli task content <task>                    Get task script, config and params (draft)
+cz-cli task save-content <task> --file <f>    Save task script; use --params '{"key":"val","dt":"bizdate","yd":"$[yyyy-MM-dd,-1d]"}' to set params (system params like bizdate/sys_plan_day/sys_biz_datetime etc. auto-detected)
 cz-cli task save-config <task>                Save task non-cron config, like retry, dependency
 cz-cli task save-cron <task>                  Save task schedule config
 cz-cli task deps <task>                       Show task dependencies (draft)
 cz-cli task deploy <task>                     Publish/deploy a task (alias: online)
 cz-cli task undeploy <task>                   Undeploy a task, irreversible (alias: offline)
-cz-cli task execute <task>                    Execute ad-hoc
+cz-cli task execute <task>                    Execute ad-hoc; auto-uses saved manual params as defaults (--param KEY=VAL overrides); warns if unresolved ${placeholders} remain (SQL will fail, Python/Shell silently keeps literal string)
 cz-cli task delete <task>                     Delete draft/offline task
 cz-cli task flow dag <task>                   Get flow DAG
 cz-cli task flow create-node <task>           Add node to flow
@@ -58,7 +58,7 @@ cz-cli runs wait <id>                         Poll until complete
 cz-cli runs logs <id>                         Get execution log
 cz-cli runs deps <task>                       Published dependencies
 cz-cli runs stop <id>                         Stop a running instance
-cz-cli runs refill <task>                     Backfill date range
+cz-cli runs refill <task> --from D --to D    Backfill date range. D accepts YYYY-MM-DD (day boundary) or YYYY-MM-DDTHH:MM:SS (exact datetime for hourly/minutely tasks)
 cz-cli runs rerun <id>                        Rerun failed instance
 cz-cli runs stats                             Run statistics summary
 
@@ -100,6 +100,7 @@ cz-cli datasource sample <name_or_id> <catalog> <object>
 6. **State-changing operations** (deploy/undeploy/execute/delete/refill): confirm intent with user first.
 7. **Multi-environment**: use `--profile <name>` to target a specific environment.
 8. **On `NO_PROFILE` error**: guide user to run `cz-cli setup`.
+9. **补数/回填/重跑历史数据 → `runs refill`**: when user says "补数", "回填", "重跑历史", "backfill", "re-run historical data", use `cz-cli runs refill <task> --from YYYY-MM-DD --to YYYY-MM-DD`. This is under `runs`, NOT `task`.
 
 ## Companion Skills
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clickzetta/cz-cli-darwin-x64",
-  "version": "0.3.39",
+  "version": "0.3.40",
   "description": "cz-cli binary for macOS x64 (Intel)",
   "os": ["darwin"],
   "cpu": ["x64"],