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

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

@@ -1,5 +1,5 @@
-{"case_id":"001","type":"should_call","user_input":"怎么把 MySQL 整库实时同步到 Lakehouse？","expected_skill":"clickzetta-cdc-sync-pipeline","expected_output_contains":["整库镜像","Binlog","CDC"]}
-{"case_id":"002","type":"should_call","user_input":"分库分表的数据怎么合并同步到 Lakehouse 一张表？","expected_skill":"clickzetta-cdc-sync-pipeline","expected_output_contains":["多表合并","分库分表"]}
-{"case_id":"003","type":"should_call","user_input":"CDC 同步任务 Binlog 位点过期了怎么办？","expected_skill":"clickzetta-cdc-sync-pipeline","expected_output_contains":["Binlog"]}
-{"case_id":"004","type":"should_call","user_input":"多表实时同步怎么配置告警？支持飞书通知吗？","expected_skill":"clickzetta-cdc-sync-pipeline","expected_output_contains":["告警","webhook"]}
-{"case_id":"005","type":"should_call","user_input":"PostgreSQL 整库 CDC 同步需要源端做什么准备？","expected_skill":"clickzetta-cdc-sync-pipeline","expected_output_contains":["WAL","PostgreSQL"]}
+{"case_id":"001","type":"should_call","user_input":"How do I sync an entire MySQL database to Lakehouse in real time?","expected_skill":"clickzetta-cdc-sync-pipeline","expected_output_contains":["full database mirror","Binlog","CDC"]}
+{"case_id":"002","type":"should_call","user_input":"How do I merge sharded tables into a single Lakehouse table during sync?","expected_skill":"clickzetta-cdc-sync-pipeline","expected_output_contains":["sharded table merge","merge"]}
+{"case_id":"003","type":"should_call","user_input":"The CDC sync task has a Binlog position expired error, what should I do?","expected_skill":"clickzetta-cdc-sync-pipeline","expected_output_contains":["Binlog"]}
+{"case_id":"004","type":"should_call","user_input":"How do I configure alerts for multi-table real-time sync? Does it support Feishu notifications?","expected_skill":"clickzetta-cdc-sync-pipeline","expected_output_contains":["alert","webhook"]}
+{"case_id":"005","type":"should_call","user_input":"What source database preparation is needed for PostgreSQL full database CDC sync?","expected_skill":"clickzetta-cdc-sync-pipeline","expected_output_contains":["WAL","PostgreSQL"]}

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

@@ -1,237 +1,98 @@
 ---
 name: clickzetta-data-ingest-pipeline
 description: |
-  ClickZetta Lakehouse 数据导入总览与路由。根据用户的数据源类型、实时性要求、数据量等条件，
-  推荐最合适的数据导入方式，并引导到对应的专项 Skill 或直接执行简单导入操作。
-  当用户说"导入数据到 Lakehouse"、"数据入仓"、"数据入湖"、"怎么把数据导进来"、
-  "数据采集"、"数据加载"、"ingest data"、"load data"、"数据导入方案选择"时触发。
-  Keywords: data ingestion, import, routing, pipeline selection, data source
+  Router skill: selects the best data ingestion method for ClickZetta Lakehouse based on
+  data source, latency, sync scope, and continuity requirements. Routes to specialized skills:
+  Kafka Pipe, OSS/S3/COS Pipe, Studio batch sync, Studio real-time sync, Studio CDC,
+  file/URL import, or SDK ingestion.
+  Trigger: user wants to get external data INTO Lakehouse but hasn't chosen a method, OR
+  asks which ingestion approach fits their scenario.
+  Covers: Kafka, MySQL, PostgreSQL, SQL Server, TiDB, OSS, S3, COS, local files, URLs,
+  Java SDK, Python/ZettaPark. Does NOT cover: querying data, pipeline monitoring/diagnosis,
+  Dynamic Table tuning, internal table transformations, or data export.
+  Keywords: data ingestion, import, sync, ETL, migrate, load data, ingest, pipeline selection
 ---
 
-# Lakehouse 数据导入总览与路由
+# Lakehouse Data Ingestion Router
 
-根据用户的数据源、实时性需求、数据规模等条件，推荐最合适的数据导入方式，
-并路由到对应的专项 Pipeline Skill 或直接执行简单导入操作。
+Routes users to the correct ingestion skill based on data source, latency requirements, sync scope, and whether continuous sync is needed. Scoped to **external data → Lakehouse** only.
 
-## 适用场景
+## Applicable Scenarios
 
-- 用户想把数据导入 ClickZetta Lakehouse，但不确定用哪种方式
-- 用户描述了数据源（Kafka、MySQL、OSS、文件等），需要推荐导入方案
-- 用户需要了解各种导入方式的适用场景和差异
-- 关键词：数据导入、数据入仓、数据入湖、数据采集、数据加载、pipeline 选择
+- User wants to import data into ClickZetta Lakehouse but is unsure which method to use
+- User describes a data source and needs an ingestion recommendation
+- User asks about differences between ingestion methods
 
-## 前置依赖
+## Decision Matrix
 
-- ClickZetta Lakehouse 账户，具备创建工作空间、Schema、表、PIPE、任务等权限
-- **执行环境**：已安装并配置 cz-cli
+### Step 1: Collect Requirements
 
-## 执行环境
+1. **Data source type**: Kafka / Object storage (OSS/S3/COS) / Relational DB (MySQL/PostgreSQL/SQL Server/TiDB) / Local file / URL / Java SDK / Python
+2. **Latency**: Real-time (seconds) / Near real-time (minutes) / Batch (hours/days)
+3. **Sync scope**: Single table / Multiple tables / Entire database
+4. **Continuity**: One-time import / Continuous incremental sync
+5. **CDC needed**: Yes / No
 
-所有操作通过 `cz-cli` 执行：
+### Step 2: Route
 
-```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 脚本上传 |
+| Data Source | Latency | Scope | Route To |
+|-------------|---------|-------|----------|
+| Kafka | Real-time/Near real-time | Single topic (SQL Pipe) | `clickzetta-kafka-ingest-pipeline` |
+| Kafka | Real-time | Single topic (Studio task) | `clickzetta-realtime-sync-pipeline` |
+| OSS/S3/COS | Near real-time | Files arriving continuously | `clickzetta-oss-ingest-pipeline` |
+| OSS/S3/COS | One-time batch | Bulk files from bucket | `clickzetta-oss-ingest-pipeline` (batch mode) |
+| Local file / URL | One-time | Single/multiple files | `clickzetta-file-import-pipeline` |
+| MySQL/PG/SQL Server/TiDB | Real-time CDC | Single table | `clickzetta-realtime-sync-pipeline` |
+| MySQL/PG/SQL Server/TiDB | Real-time CDC | Multiple tables / Entire DB | `clickzetta-cdc-sync-pipeline` |
+| MySQL/PG/SQL Server | Offline batch | Single table | `clickzetta-batch-sync-pipeline` |
+| MySQL/PG/SQL Server | Offline batch | Multiple tables / Entire DB | `clickzetta-batch-sync-pipeline` |
+| Java application | Real-time/Batch | Programmatic write | `clickzetta-java-sdk` |
+| Python/ZettaPark | Batch | DataFrame write | `clickzetta-zettapark` / `clickzetta-app-python-sdk` |
+| Small data (manual) | One-time | Few rows | Direct SQL INSERT (see below) |
 
-## 示例
+### How to Choose Between Similar Options
 
-### 示例 1：用户不确定导入方式
+| Scenario | Option A | Option B | Differentiator |
+|----------|----------|----------|----------------|
+| Kafka → Lakehouse | `clickzetta-kafka-ingest-pipeline` | `clickzetta-realtime-sync-pipeline` | Pipe: SQL-native, flexible transforms, no Studio. Studio task: UI-based JSONPath config. |
+| OSS one-time import | `clickzetta-oss-ingest-pipeline` (batch) | `clickzetta-file-import-pipeline` | OSS skill: creates Connection + External Volume. File skill: uses existing/User Volume. |
+| Single-table CDC | `clickzetta-realtime-sync-pipeline` | `clickzetta-cdc-sync-pipeline` | Realtime-sync: simpler for single table. CDC: more operational depth, alerting, repair. |
+| Batch single vs multi | Same skill | Same skill | `clickzetta-batch-sync-pipeline` handles both; multi-table also supports sharded-table merge. |
 
-用户说："我有一个 MySQL 数据库，想把里面的订单表实时同步到 Lakehouse"
+### Key Constraints
 
-路由逻辑：
-1. 数据源：MySQL（关系型数据库）
-2. 实时性：实时
-3. 同步范围：单表
-4. 需要 CDC：是（实时同步意味着需要捕获变更）
-→ 推荐：Studio 实时同步
-→ 路由到 `clickzetta-realtime-sync-pipeline` Skill
+| Skill | Constraints |
+|-------|-------------|
+| `clickzetta-kafka-ingest-pipeline` | PLAINTEXT/SASL_PLAINTEXT only (no SSL/mTLS); GP VCluster |
+| `clickzetta-realtime-sync-pipeline` | Sync VCluster required; Studio datasource config; no test mode before deployment |
+| `clickzetta-cdc-sync-pipeline` | Source tables must have PKs; Studio datasource (not SQL Connection); Sync VCluster |
+| `clickzetta-batch-sync-pipeline` | Studio datasource; Sync VCluster; field mapping configured in Studio UI |
+| `clickzetta-oss-ingest-pipeline` | Dedicated Volume per Pipe (no sharing); same cloud provider as Lakehouse instance |
 
-### 示例 2：多种数据源混合场景
+## Direct Execution for Simple Scenarios
 
-用户说："我们有 Kafka 的用户行为日志，还有 MySQL 的业务数据，都要导入 Lakehouse"
+For trivial imports that don't need a specialized skill:
 
-路由逻辑：
-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 替代路径：
+```bash
+# SQL INSERT (small data volume)
+cz-cli sql "INSERT INTO schema_name.table_name (col1, col2, col3) VALUES ('val1', 'val2', 'val3')" --sync
 
-| 数据源 | 推荐方式 | 对应 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 替代路径 |
+# COPY INTO from Volume
+cz-cli sql "COPY INTO schema_name.table_name FROM VOLUME volume_name USING CSV OPTIONS('header'='true') FILES('data.csv')" --sync
+```
 
-### 简单场景直接执行（cz-cli 版）
+## Error Handling
 
-对于无需专项 Skill 的简单场景，可直接用 cz-cli agent 完成：
+| Scenario | Resolution |
+|----------|-----------|
+| User cannot identify data source type | Ask where data currently lives (which system/service) |
+| Multiple data sources | Split into separate tasks, route each independently |
+| Cloud environment doesn't support a connection | `cz-cli sql "SHOW CONNECTIONS" --sync` to check available types |
+| TB-scale data volume | Prefer PIPE or Studio sync tasks (support checkpoint resume) |
+| No Sync VCluster available | Studio sync tasks (batch/realtime/CDC) require Sync VCluster — check with `cz-cli sql "SHOW VCLUSTERS" --sync` |
 
-```bash
-# SQL INSERT 导入（小数据量）
-cz-cli agent run "向表 <schema_name>.<table_name> 插入数据：<col1>=<val1>, <col2>=<val2>" \
-  --format a2a --dangerously-skip-permissions
+## Notes
 
-# COPY INTO 快速导入（从 Volume）
-cz-cli agent run "从 Volume <volume_name> 以 CSV 格式（有 header）将数据导入表 <schema_name>.<table_name>" \
-  --format a2a --dangerously-skip-permissions
-```
+- This skill is a routing entry point — it does not execute complex pipeline setup
+- Data warehousing (into managed tables) is the default; data lake loading (into Volume/object storage) is for staging or cross-system sharing
+- Consider user's cloud environment (Alibaba Cloud/Tencent Cloud/AWS) — cross-cloud ingestion is not supported

package/bin/skills/clickzetta-data-science/SKILL.md

@@ -1,50 +1,51 @@
 ---
 name: clickzetta-data-science
 description: |
-  数据科学家使用 ClickZetta Lakehouse 的端到端工作流指南。按工作阶段组织：
-  开发环境准备（Python 3.10+ 检查/搭建）、Jupyter Notebook 配置与使用、
-  项目结构规范（Cookiecutter DS 标准）、数据发现、数据质量评估、
-  数据清洗与整合、数据集构建、EDA 探索分析、
-  特征工程（SQL + ZettaPark）、模型推理上线（BITMAP 用户画像/UDF 批量推理/向量检索）。
-  当用户说"数据科学"、"机器学习"、"特征工程"、"EDA"、"数据探索"、
-  "ZettaPark 机器学习"、"Jupyter 连接 Lakehouse"、"notebook"、"ipynb"、
-  "jupyter kernel"、"%%sql"、"magic command"、"pandas 读取数据"、
-  "数据质量检查"、"数据采样"、"TABLESAMPLE"、"approx_percentile"、
-  "BITMAP 用户画像"、"人群圈选"、"批量推理"、"Python 3.10"、
-  "scikit-learn"、"项目目录结构"、"config.json"、".env"时触发。
+  End-to-end data science workflow guide for ClickZetta Lakehouse. Organized by
+  work stage: environment setup (Python 3.10+ check/install), Jupyter Notebook
+  configuration, project structure (Cookiecutter DS standard), data discovery,
+  data quality assessment, data cleaning and integration, dataset construction,
+  EDA, feature engineering (SQL + ZettaPark), and model inference deployment
+  (BITMAP user profiling / UDF batch inference / vector search).
+  Trigger when user mentions: "data science", "machine learning", "feature engineering",
+  "EDA", "data exploration", "ZettaPark ML", "Jupyter connect Lakehouse", "notebook",
+  "ipynb", "jupyter kernel", "%%sql", "magic command", "pandas read data",
+  "data quality check", "data sampling", "TABLESAMPLE", "approx_percentile",
+  "BITMAP user profile", "audience segmentation", "batch inference", "Python 3.10",
+  "scikit-learn", "project directory structure", "config.json", ".env".
   Keywords: data science, Jupyter, EDA, feature engineering, ML, pandas, notebook
 ---
 
-# ClickZetta Lakehouse 数据科学工作流
+# ClickZetta Lakehouse Data Science Workflow
 
-## 工作流全景
+## Workflow Overview
 
 ```
-环境准备 → Jupyter 配置 → 项目结构 → 数据发现 → 数据质量评估 → 数据清洗整合
-                                                                        ↓
-                                      模型推理上线 ← 特征工程 ← EDA ← 数据集构建
+Environment Setup → Jupyter Config → Project Structure → Data Discovery → Data Quality → Data Cleaning
+                                                                                               ↓
+                                           Model Inference ← Feature Engineering ← EDA ← Dataset Build
 ```
 
 ---
 
-## 硬性前提条件
+## Hard Prerequisite
 
-**Python 3.10+**（ZettaPark 硬性要求）。用户环境是 3.9 或更低时，先给升级方案再继续：
+**Python 3.10+** (required by ZettaPark). If the user's environment is 3.9 or lower, provide an upgrade path before continuing:
 
 ```bash
 brew install pyenv && pyenv install 3.12.9 && pyenv local 3.12.9
 python -m venv .venv && source .venv/bin/activate
 ```
 
-详细搭建步骤见 [references/setup.md](references/setup.md)。
+See [references/setup.md](references/setup.md) for detailed setup steps.
 
 ---
 
-## 项目结构
+## Project Structure
 
 ```
 my-ds-project/
-├── notebooks/          # 00-env-check.ipynb 必须是第一个
+├── notebooks/          # 00-env-check.ipynb must be first
 │   ├── 00-env-check.ipynb
 │   ├── 01-data-discovery.ipynb
 │   ├── 02-data-quality.ipynb
@@ -52,74 +53,74 @@ my-ds-project/
 │   ├── 04-feature-engineering.ipynb
 │   └── 05-modeling.ipynb
 ├── src/
-│   ├── config.py       # 连接配置，见 references/setup.md
+│   ├── config.py       # connection config, see references/setup.md
 │   ├── data/
 │   └── features/
 ├── sql/
-├── data/               # 全部加入 .gitignore
-├── models/             # 全部加入 .gitignore
-├── .env                # 绝不入 git
-└── .env.example        # 入 git
+├── data/               # all in .gitignore
+├── models/             # all in .gitignore
+├── .env                # never commit to git
+└── .env.example        # commit to git
 ```
 
-环境变量命名规范：`CLICKZETTA_SERVICE` / `CLICKZETTA_INSTANCE` / `CLICKZETTA_WORKSPACE` / `CLICKZETTA_USERNAME` / `CLICKZETTA_PASSWORD` / `CLICKZETTA_VCLUSTER` / `CLICKZETTA_SCHEMA`。
+Environment variable naming: `CLICKZETTA_SERVICE` / `CLICKZETTA_INSTANCE` / `CLICKZETTA_WORKSPACE` / `CLICKZETTA_USERNAME` / `CLICKZETTA_PASSWORD` / `CLICKZETTA_VCLUSTER` / `CLICKZETTA_SCHEMA`.
 
 ---
 
-## 数据写入规则（禁止事项）
+## Data Write Rules
 
-| 方式 | 结论 |
+| Method | Verdict |
 |------|------|
-| `session.create_dataframe(df).write.save_as_table()` | ✅ 推荐 |
-| `cursor` 批量 INSERT（每批 500 行） | ✅ Python 3.9 / ZettaPark 不可用时的 fallback |
-| `df.to_sql(conn, ...)` | ❌ 禁止，报 `'list' object has no attribute 'keys'` |
-| SQLAlchemy `clickzetta://...` | ❌ 禁止，dialect 不可靠 |
+| `session.create_dataframe(df).write.save_as_table()` | ✅ Recommended |
+| `cursor` batch INSERT (500 rows per batch) | ✅ Fallback when Python 3.9 / ZettaPark unavailable |
+| `df.to_sql(conn, ...)` | ❌ Forbidden — raises `'list' object has no attribute 'keys'` |
+| SQLAlchemy `clickzetta://...` | ❌ Forbidden — dialect is unreliable |
 
-代码模板见 [references/write-and-infer.md](references/write-and-infer.md)。
+See [references/write-and-infer.md](references/write-and-infer.md) for code templates.
 
 ---
 
-## 数据查看规则
+## Data Viewing Rules
 
-- 快速查看用 `.show()`，不需要 pandas 时不要 `.to_pandas()`
-- 大表操作默认加 `TABLESAMPLE ROW(10)` 采样，避免 OOM
+- Use `.show()` for quick inspection; avoid `.to_pandas()` when pandas is not needed
+- Always add `TABLESAMPLE ROW(10)` when working with large tables to prevent OOM
 
 ---
 
-## 数据验证规则
+## Data Validation Rules
 
-导入数据后，**立即用已知基准值验证统计结果**，再进行后续分析。
+After loading data, **immediately validate statistics against known baseline values** before proceeding with analysis.
 
-常见陷阱：运动员/用户级别的原始数据，团体项目每个参与者各有一条记录，直接 SUM 会重复计算。正确做法：先 `SELECT DISTINCT event, medal, ...` 去重，再聚合。
+Common pitfall: raw athlete/user-level data where each participant in a team event has one row — a direct `SUM` will double-count. Correct approach: `SELECT DISTINCT event, medal, ...` to deduplicate first, then aggregate.
 
 ---
 
-## ClickZetta SQL 不支持的语法
+## Unsupported ClickZetta SQL Syntax
 
-| 不支持 | 替代方案 |
+| Not Supported | Alternative |
 |--------|---------|
-| `CREATE OR REPLACE TABLE` | `CREATE TABLE IF NOT EXISTS`（普通表不支持 OR REPLACE） |
-| `ARRAY_AGG(col IGNORE NULLS)` | `MAX(col)` 或 `COALESCE()` |
-| `QUALIFY` 子句 | 子查询 + `WHERE rn = 1` |
-| `UNION` / `INTERSECT` / `EXCEPT` | JOIN + 应用层合并 |
-| `BEGIN; COMMIT; ROLLBACK;` | 用 MERGE 实现原子操作 |
+| `CREATE OR REPLACE TABLE` | `CREATE TABLE IF NOT EXISTS` (regular tables don't support OR REPLACE) |
+| `ARRAY_AGG(col IGNORE NULLS)` | `MAX(col)` or `COALESCE()` |
+| `QUALIFY` clause | Subquery + `WHERE rn = 1` |
+| `UNION` / `INTERSECT` / `EXCEPT` | JOIN + application-layer merge |
+| `BEGIN; COMMIT; ROLLBACK;` | Use MERGE for atomic operations |
 | `NOW()` | `CURRENT_TIMESTAMP()` |
 
-遇到其他语法报错，加载 `clickzetta-sql-syntax-guide` skill。
+For other syntax errors, load the `clickzetta-sql-migration` skill to see Snowflake/Databricks/Spark vs. ClickZetta syntax differences.
 
 ---
 
-## Schema 上下文
+## Schema Context
 
-Python 代码中 SQL 语句始终使用完整表名 `schema.table`，不依赖当前 schema 上下文。
+Always use fully qualified table names (`schema.table`) in SQL within Python code — do not rely on the current schema context.
 
 ---
 
-## 参考文档
+## References
 
-- [环境搭建与项目配置](references/setup.md) — 环境搭建、config.py 模板、Jupyter 配置
-- [数据发现/质量/清洗/EDA 示例](references/data-patterns.md)
-- [数据写入/特征工程/模型推理示例](references/write-and-infer.md)
+- [Environment Setup & Project Config](references/setup.md) — environment setup, config.py template, Jupyter configuration
+- [Data Discovery / Quality / Cleaning / EDA Examples](references/data-patterns.md)
+- [Data Write / Feature Engineering / Model Inference Examples](references/write-and-infer.md)
 - [ZettaPark API](references/zettapark-api.md)
-- [统计分析函数](references/stats-functions.md)
-- [BITMAP 用户画像](references/bitmap-profile.md)
+- [Statistical Analysis Functions](references/stats-functions.md)
+- [BITMAP User Profiling](references/bitmap-profile.md)