@clickzetta/cz-cli-darwin-x64 0.3.95 → 0.3.96

package/bin/skills/clickzetta-pipeline-review/SKILL.md

@@ -1,377 +1,292 @@
 ---
 name: clickzetta-pipeline-review
 description: |
-  对 ClickZetta Lakehouse 数据管道进行全面 Review 与诊断。从任意入口（任务名/schema/表名/
-  业务域关键词）出发，自主发现管道涉及的全部对象（Studio 任务、Lakehouse 表、管道对象、
-  运行记录），识别调度依赖缺失、DDL 幂等问题、分层跳层、DT 反模式等常见问题，
-  给出优先级排序的修复建议并执行。
-  当用户说"Review 管道"、"检查数据管道"、"管道诊断"、"管道有问题"、"任务跑失败了"、
-  "数据不对"、"管道 Review"、"pipeline review"、"检查 ETL"、"管道健康检查"、
-  "数据链路检查"、"管道全貌"、"管道梳理"时触发。
+  Comprehensive review and diagnosis of ClickZetta Lakehouse data pipelines. Starting from any entry point
+  (task name / schema / table name / business domain keyword), autonomously discovers all pipeline objects
+  (Studio tasks, Lakehouse tables, pipeline objects, run records), identifies missing scheduling dependencies,
+  DDL idempotency issues, layer skipping, Dynamic Table anti-patterns, and other common problems.
+  Delivers prioritized fix recommendations and executes them.
+
+  Trigger when the user says: "review pipeline", "check data pipeline", "pipeline diagnosis",
+  "pipeline has issues", "task failed", "data is wrong", "pipeline review", "check ETL",
+  "pipeline health check", "data lineage check", "pipeline overview", "pipeline audit",
+  "task dependency check", "DT refresh failing", "data inconsistency", "pipeline not working".
   Keywords: pipeline review, diagnosis, task dependency, data lineage, DT health, pipeline discovery
 ---
 
-# ClickZetta 数据管道 Review 指南
+# ClickZetta Data Pipeline Review Guide
 
-## 向导：收集必要信息
+## Wizard: Collect Required Information
 
-收到 Review 请求后，**不要立即开始探索**。先通过向导收集必要信息，再启动五阶段流程。
+On receiving a review request, **do not start exploring immediately**. Collect required information first, then launch the five-phase process.
 
-### 第 0 步：信息收集（必须完成，不得跳过）
+Ask two questions: (1) Review scope — full review (discover all issues, complete report), targeted diagnosis (specific issue type: task dependencies / DT refresh failures / data inconsistency), or quick health check (P0 issues only, conclusion in 5 minutes)? (2) Execution permission — read-write (can execute fixes, recommended) or read-only (report only, no fixes)?
 
-优先使用交互式问答工具（如 `question`）收集以下信息并弹出选项菜单；若无此类工具，则用文字一次性列出所有问题：
+Pipeline entry point (domain / task name / schema / table name) and known symptoms can be inferred from context or asked after.
 
-```
-question({
-  questions: [
-    {
-      question: "Review 范围？",
-      options: [
-        { label: "全量 Review", description: "发现所有问题，给出完整报告" },
-        { label: "专项诊断", description: "只看某类问题，如任务依赖、DT 刷新失败、数据不一致" },
-        { label: "快速健康检查", description: "只看 P0 问题，5 分钟内出结论" }
-      ]
-    },
-    {
-      question: "执行权限？",
-      options: [
-        { label: "可读写", description: "可以执行修复操作（推荐）" },
-        { label: "只读", description: "只能查，输出报告不执行修复" }
-      ]
-    }
-  ]
-})
-```
-
-管道入口（业务域/任务名/schema/表名）和已知症状可在用户回答后追问，或从上下文推断。
-
-### 根据回答调整策略
-
-| Review 范围 | 执行权限 | 策略 |
+| Review scope | Permission | Strategy |
 |---|---|---|
-| 全量 Review | 可读写 | 走完五阶段，发现问题后询问是否执行修复 |
-| 全量 Review | 只读 | 走完五阶段，输出问题报告，不执行修复 |
-| 专项诊断 | 任意 | 只执行对应阶段的检查项，跳过无关步骤 |
-| 快速健康检查 | 任意 | 只检查 P0 问题（依赖缺失、DT 持续失败），5 分钟内出结论 |
+| Full review | Read-write | Run all five phases, ask before executing fixes |
+| Full review | Read-only | Run all five phases, output report, no fixes |
+| Targeted diagnosis | Either | Run only the relevant phase checks |
+| Quick health check | Either | Check P0 issues only (missing deps, DT failures), conclude in 5 min |
 
-**如果用户已经在请求中提供了足够信息（如"帮我 Review shenyu_gateway 管道，全量 Review，可以修复"），直接进入第一阶段，不再重复询问。**
+**If the user has already provided sufficient information (e.g. "review the shenyu_gateway pipeline, full review, can fix"), proceed directly to Phase 1.**
 
 ---
 
-## 工作模式：五阶段 Review 流程
-
-收集到必要信息后，按以下五阶段执行：
+## Five-Phase Review Process
 
 ```
-发现 → 分析 → 识别问题 → 执行修复 → 验证
+Discover → Analyze → Identify Issues → Execute Fixes → Verify
 ```
 
 ---
 
-## 第一阶段：发现（管道全貌探索）
-
-### 入口识别
+## Phase 1: Discover (Pipeline Overview)
 
-用户可能从任意层给出入口，从入口向上下游展开：
+### Entry Point Recognition
 
-| 用户给出的入口 | 展开方向 |
+| User provides | Expand direction |
 |---|---|
-| 业务域关键词（如"shenyu_gateway"） | 同时搜索 Studio 任务和 Lakehouse schema |
-| Studio 任务名/目录 | 读任务脚本 → 找涉及的表 → 找上下游任务 |
-| Lakehouse 表名/schema | 找写入该表的任务 → 找读取该表的 DT/任务 |
-| 管道对象（Pipe/DT/Stream） | 找源表和目标表 → 找关联任务 |
-| 错误信息/运行 ID | 先定位任务 → 再展开全貌 |
+| Business domain keyword (e.g. "shenyu_gateway") | Search Studio tasks and Lakehouse schemas simultaneously |
+| Studio task name / directory | Read task scripts → find involved tables → find upstream/downstream tasks |
+| Lakehouse table name / schema | Find tasks writing to this table → find DTs/tasks reading from it |
+| Pipeline object (Pipe/DT/Stream) | Find source and target tables → find associated tasks |
+| Error message / run ID | Locate task first → then expand overview |
 
-### 探索四层
+### Explore Four Layers
 
-**无论入口是什么，都要探索以下四层，缺一不可：**
-
-**层 1 — Studio 任务层**
+**Layer 1 — Studio task layer**
 ```bash
-# 按业务域关键词找任务目录
 cz-cli task list-folders
-
-# 列出目录下所有任务
 cz-cli task list --folder <folder>
-
-# 读每个任务的脚本和配置（重点看：task_type、cron_express、task_dependencies、edit_state）
-cz-cli task content <task_id>
+cz-cli task content <task_id>   # focus on: task_type, cron_express, task_dependencies, edit_state
 ```
 
-**层 2 — Lakehouse 对象层**
+**Layer 2 — Lakehouse object layer**
 ```sql
--- 找相关 schema
 SHOW SCHEMAS;
-
--- 列出各层表
-SHOW TABLES IN <ods_schema>;
-SHOW TABLES IN <dwd_schema>;
-SHOW TABLES IN <dws_schema>;
-SHOW TABLES IN <ads_schema>;
-
--- 找 Dynamic Table
+SHOW TABLES IN <schema>;
 SHOW TABLES IN <schema> WHERE is_dynamic;
-
--- 找 Pipe
 SHOW PIPES;
-
--- 找 Table Stream
 SHOW TABLE STREAMS;
 ```
 
-**层 3 — 运行记录层**（配置是"应该怎样"，运行记录是"实际怎样"）
+**Layer 3 — Run record layer** (config = "should be", run records = "actually is")
 ```bash
-# 查每个关键任务的最近运行记录
 cz-cli runs list --task <task_name> --limit 10
-
-# 发现失败时查日志
 cz-cli runs logs <run_id>
-
-# 查运行统计（成功率、平均耗时）
 cz-cli runs stats --task <task_name>
 ```
 
-**层 4 — 管道对象状态层**
+**Layer 4 — Pipeline object status layer**
 ```sql
--- Dynamic Table 刷新历史（每张 DT 都要查）
 SHOW DYNAMIC TABLE REFRESH HISTORY <schema>.<table> LIMIT 10;
-
--- Pipe 状态
 DESC PIPE <pipe_name>;
-
--- Table Stream 积压
 SELECT COUNT(*) FROM <stream_name>;
 ```
 
-### 发现阶段输出
+### Discovery Output
 
-完成四层探索后，向用户呈现管道全貌摘要：
 ```
-管道全貌：
-- Studio 任务：N 个（列出名称、类型、状态、cron）
-- ODS 层：N 张表
-- DWD 层：N 张表
-- DWS/ADS 层：N 张 Dynamic Table
-- 管道对象：Pipe × N，Table Stream × N
-- 运行记录：最近 N 次，成功率 X%
+Pipeline overview:
+- Studio tasks: N (list name, type, status, cron)
+- ODS layer: N tables
+- DWD layer: N tables
+- DWS/ADS layer: N Dynamic Tables
+- Pipeline objects: Pipe × N, Table Stream × N
+- Run records: last N runs, success rate X%
 ```
 
 ---
 
-## 第二阶段：分析（深度读取）
-
-发现阶段只是"找到了什么"，分析阶段要"读懂内容"：
+## Phase 2: Analyze (Deep Read)
 
 ```bash
-# 读每个任务的完整脚本
 cz-cli task content <task_id>
-
-# 重点关注：
-# - task_dependencies：是否配置了上下游依赖
-# - cron_express：调度时间是否合理
-# - edit_state：20=DRAFT，30=PUBLISHED
-# - task_type：SQL任务/同步任务/实时同步
+# Focus on: task_dependencies, cron_express, edit_state (20=DRAFT, 30=PUBLISHED), task_type
 ```
 
-**同步任务运行模式判断（不能只看单一字段）：**
+**Sync task run mode determination (cannot rely on a single field):**
 
-| 字段 | 不能单独判断 | 需要综合判断 |
+| Field | Cannot determine alone | Needs combined judgment |
 |---|---|---|
-| `readMode: BINLOG` | ❌ 不代表 CDC 实时 | 还需看 cron_express、pkWriteMode、运行记录 |
-| `pkWriteMode: OVERWRITE` | 覆盖写 → 离线批量 | 结合 cron 和运行记录确认 |
-| 运行记录只有 1 条手动触发 | → 定时调度可能未生效 | 需确认 cron 是否正常触发 |
+| `readMode: BINLOG` | ❌ Does not mean CDC real-time | Also check cron_express, pkWriteMode, run records |
+| `pkWriteMode: OVERWRITE` | Overwrite write → offline batch | Confirm with cron and run records |
+| Run records show only 1 manual trigger | → Scheduled trigger may not be working | Confirm cron is firing correctly |
 
-**综合判断规则**：
-- `cron_express` 有值 + `pkWriteMode: OVERWRITE` + 运行记录为定时触发 → **离线批量同步**
-- `cron_express` 为空 + 任务持续运行状态 → **实时同步（CDC/Kafka）**
-- 运行记录全是手动触发 → **调度未生效，需排查**
+**Combined judgment rules:**
+- `cron_express` has value + `pkWriteMode: OVERWRITE` + run records show scheduled triggers → **offline batch sync**
+- `cron_express` empty + task in continuous running state → **real-time sync (CDC/Kafka)**
+- All run records are manual triggers → **scheduling not working, investigate**
 
 ---
 
-## 第三阶段：识别问题
+## Phase 3: Identify Issues
 
-### 检查清单（按优先级）
+### Checklist (by priority)
 
-**🔴 P0 — 调度依赖缺失**
+**🔴 P0 — Missing scheduling dependencies**
 
 ```bash
-# 检查每个 ETL/转换任务的依赖配置
 cz-cli task content <task_id>
-# 查看 task_dependencies 字段是否为空数组 []
+# Check if task_dependencies field is empty array []
 ```
 
-- ETL 转换任务的 `task_dependencies` 为空 → **P0，必须修复**
-- 上游同步任务未完成时下游就开始执行 → 读到旧数据或空数据
-- 运行记录时间线混乱（多次手动触发、时间间隔异常）→ 依赖缺失的典型症状
+- ETL transform task `task_dependencies` is empty → **P0, must fix**
+- Downstream starts executing before upstream sync completes → reads stale or empty data
+- Run record timeline is chaotic (multiple manual triggers, abnormal intervals) → typical symptom of missing dependencies
 
-**🔴 P0 — Dynamic Table 刷新持续失败**
+**🔴 P0 — Dynamic Table refresh continuously failing**
 
 ```sql
 SHOW DYNAMIC TABLE REFRESH HISTORY <schema>.<table> LIMIT 10;
--- status 连续出现 FAILED → P0
+-- status shows consecutive FAILED → P0
 ```
 
-**🟡 P1 — DDL 幂等性问题**
+**🟡 P1 — DDL idempotency issue**
 
-Dynamic Table 的 DDL 应统一使用 `CREATE OR REPLACE`，不要用 `DROP + CREATE` 两步：
-- `DROP` 和 `CREATE` 之间存在竞态条件
-- 如果 `CREATE` 失败，表已被删除，数据丢失
+Dynamic Table DDL should use `CREATE OR REPLACE`, not `DROP + CREATE`:
+- Race condition between `DROP` and `CREATE`
+- If `CREATE` fails, table is already deleted — data loss
 
 ```sql
--- ❌ 有竞态风险
+-- ❌ Race condition risk
 DROP DYNAMIC TABLE IF EXISTS schema.table;
 CREATE DYNAMIC TABLE schema.table ...;
 
--- ✅ 原子操作
+-- ✅ Atomic operation
 CREATE OR REPLACE DYNAMIC TABLE schema.table ...;
 ```
 
-> ⚠️ `CREATE OR REPLACE` 有类型变更限制：字段类型变更（如 `TINYINT → BOOLEAN`）会报错。
-> 解决方案：用 `CAST(col AS TINYINT)` 保持类型兼容，或先 `DROP` 再 `CREATE`。
+> ⚠️ `CREATE OR REPLACE` has type change restrictions: field type changes (e.g. `TINYINT → BOOLEAN`) will error. Solution: use `CAST(col AS TINYINT)` to maintain type compatibility, or `DROP` then `CREATE`.
 
-**🟡 P1 — DWS 层跳过 DWD 直接读 ODS**
+**🟡 P1 — DWS layer skipping DWD and reading ODS directly**
 
 ```sql
--- 检查 DWS 层 DT 的 SQL 定义，看 FROM 子句引用的是哪一层
 SHOW CREATE TABLE <dws_schema>.<table>;
+-- Check FROM clause — DWS should read from DWD, not ODS
 ```
 
-- DWS 层应从 DWD 层读取，不应直接读 ODS
-- 跳层问题：重复计算（DWD 已做的 JSON 解析/类型转换在 DWS 又做一遍）、口径不一致、维护成本高
+Skipping layers causes: duplicate computation (JSON parsing/type conversion already done in DWD), inconsistent metrics, higher maintenance cost.
 
-**🟡 P1 — Dynamic Table 定义中包含 ORDER BY**
+**🟡 P1 — Dynamic Table definition contains ORDER BY**
 
 ```sql
--- 查看 DT 定义
 SHOW CREATE TABLE <schema>.<dt_name>;
--- 如果 AS 子句中有 ORDER BY → 需要移除
+-- If AS clause contains ORDER BY → remove it
 ```
 
-- DT 的 `ORDER BY` 仅在查询时生效，不影响存储顺序
-- 每次刷新额外消耗计算资源做排序，无实际收益
-- 排序逻辑应放在查询端（BI 工具或下游 SQL）
+`ORDER BY` in DT only affects query results, not storage order. It wastes compute on every refresh with no benefit. Sorting logic belongs at the query layer (BI tools or downstream SQL).
 
-**🟢 P2 — DDL 任务保留 Cron 配置**
+**🟢 P2 — DDL task retains Cron configuration**
 
 ```bash
 cz-cli task content <ddl_task_id>
-# edit_state=20（DRAFT）但 cron_express 不为空 → P2
+# edit_state=20 (DRAFT) but cron_express is not empty → P2
 ```
 
-- DRAFT 状态不会实际执行，但保留 Cron 配置容易误导维护者
-- 建议清理，非紧急
+DRAFT state won't actually execute, but retaining Cron config misleads maintainers. Clean up when convenient.
 
-**🟢 P2 — Studio 任务脚本与实际 DT 定义不一致**
+**🟢 P2 — Studio task script inconsistent with actual DT definition**
 
-直接通过 SQL 重建 DT 后，Studio 任务脚本不会自动同步：
+After rebuilding DT directly via SQL, Studio task script does not auto-sync:
 
 ```bash
-# 检查：读 Studio 任务脚本
-cz-cli task content <task_id>
-
-# 对比：读实际 DT 定义（执行以下 SQL）
-# SHOW CREATE TABLE <schema>.<table>
-
-# 如果不一致，同步 Studio 任务脚本
+cz-cli task content <task_id>   # read Studio task script
+# SHOW CREATE TABLE <schema>.<table>  # read actual DT definition
+# If inconsistent, sync Studio task script:
 cz-cli task save-content <task_id> --content "<new_sql>"
 ```
 
 ---
 
-## 第四阶段：执行修复
+## Phase 4: Execute Fixes
 
-### 修复依赖配置
+### Fix dependency configuration
 
 ```bash
-# 为 ETL 任务配置上游依赖
 cz-cli task save-config <task_id> --deps replace \
   --dep-tasks '[{"taskId":<upstream_id>,"taskName":"<upstream_name>"}]'
-
-# 部署生效
 cz-cli task deploy <task_id> -y
 ```
 
-### 修复 DT DDL（统一为 CREATE OR REPLACE）
+### Fix DT DDL (unify to CREATE OR REPLACE)
 
 ```sql
--- 先确认字段类型，避免类型变更报错
+-- Confirm field types first to avoid type change errors
 SHOW CREATE TABLE <schema>.<table>;
 
--- 执行重建（如有类型变更，用 CAST 保持兼容）
+-- Rebuild (use CAST for type compatibility if needed)
 CREATE OR REPLACE DYNAMIC TABLE <schema>.<table>
   REFRESH INTERVAL <n> <unit> vcluster <gp_cluster>
 AS
 SELECT ...
-FROM <dwd_schema>.<table>  -- 确保从 DWD 层读取，不跳层
-...;  -- 移除 ORDER BY
+FROM <dwd_schema>.<table>   -- ensure reading from DWD, not skipping layers
+...;   -- remove ORDER BY
 
--- 立即触发首次刷新
+-- Trigger immediate first refresh
 REFRESH DYNAMIC TABLE <schema>.<table>;
 ```
 
-### 同步 Studio 任务脚本
+### Sync Studio task script
 
 ```bash
-# SQL 重建 DT 后，同步 Studio 任务脚本保持一致
 cz-cli task save-content <task_id> --content "<updated_sql>"
 ```
 
-### 执行原则
+### Execution principles
 
-- **直接 SQL 操作**（重建 DT、修改表结构）→ 执行对应 SQL，执行前向用户确认
-- **Studio 任务配置**（依赖、Cron、脚本）→ 用 `cz-cli task save-*` + `deploy`
-- **两者都改时**：先改 SQL（数据层），再同步 Studio（配置层）
+- **Direct SQL operations** (rebuild DT, modify table structure) → execute SQL, confirm with user first
+- **Studio task config** (dependencies, Cron, script) → use `cz-cli task save-*` + `deploy`
+- **When changing both**: change SQL first (data layer), then sync Studio (config layer)
 
 ---
 
-## 第五阶段：验证
-
-修复完成后，**逐项验证**，不跳过：
+## Phase 5: Verify
 
 ```sql
--- 1. Dynamic Table 刷新状态
+-- 1. Dynamic Table refresh status
 SHOW DYNAMIC TABLE REFRESH HISTORY <schema>.<table> LIMIT 5;
--- 确认最近一次 status = SUCCESS
+-- Confirm latest status = SUCCESS
 
--- 2. 各层行数
+-- 2. Row counts at each layer
 SELECT COUNT(*) FROM <ods_schema>.<table>;
 SELECT COUNT(*) FROM <dwd_schema>.<table>;
 SELECT COUNT(*) FROM <dws_schema>.<table>;
 
--- 3. 关键字段非空率
-SELECT ROUND(COUNT(key_field) * 100.0 / COUNT(*), 2) AS non_null_pct
-FROM <schema>.<table>;
+-- 3. Key field null rate
+SELECT ROUND(COUNT(key_field) * 100.0 / COUNT(*), 2) AS non_null_pct FROM <schema>.<table>;
 ```
 
 ```bash
-# 4. 确认任务依赖已生效
-cz-cli task content <task_id>
-# 查看 task_dependencies 不再为空
+# 4. Confirm task dependencies are in effect
+cz-cli task content <task_id>   # task_dependencies should no longer be empty
 
-# 5. 确认 Studio 任务脚本已同步
-cz-cli task content <task_id>
-# 对比脚本内容与实际 DT 定义一致
+# 5. Confirm Studio task script is synced
+cz-cli task content <task_id>   # script content matches actual DT definition
 ```
 
-向用户输出 Review 结论：
+Output review conclusion:
 ```
-Review 结论：
-- 发现问题：P0 × N，P1 × N，P2 × N
-- 已修复：（列出每项）
-- 未修复/建议：（列出每项及原因）
-- 验证结果：各层行数、DT 刷新状态
+Review conclusion:
+- Issues found: P0 × N, P1 × N, P2 × N
+- Fixed: (list each item)
+- Not fixed / recommendations: (list each item with reason)
+- Verification: row counts at each layer, DT refresh status
 ```
 
 ---
 
-## 常见问题速查
+## Common Issues Quick Reference
 
-| 现象 | 根因 | 排查命令 |
+| Symptom | Root cause | Investigation command |
 |---|---|---|
-| ETL 任务读到旧数据 | 依赖缺失，上游未完成就开始执行 | `cz-cli task content` 查 task_dependencies |
-| 运行记录时间线混乱 | 依赖缺失，多次手动触发 | `cz-cli runs list` 看触发方式 |
-| DT 刷新报"表已存在" | DROP+CREATE 竞态，或 CREATE OR REPLACE 类型冲突 | `SHOW CREATE TABLE` 确认字段类型 |
-| DT 刷新时间与预期不符 | REFRESH INTERVAL 以创建时间为基准，不对齐整点 | 创建后立即执行 `REFRESH DYNAMIC TABLE` |
-| Studio 脚本与实际 DT 不一致 | 直接 SQL 重建后未同步 Studio | `cz-cli task save-content` 同步 |
-| 同步任务判断为 CDC 但实为离线 | 只看 readMode 字段，未综合判断 | 结合 cron、pkWriteMode、运行记录综合判断 |
-| DWS 数据与 DWD 口径不一致 | DWS 跳层读 ODS，重复计算 | `SHOW CREATE TABLE` 检查 FROM 子句 |
+| ETL task reads stale data | Missing dependency, upstream not complete before downstream starts | `cz-cli task content` → check task_dependencies |
+| Run record timeline chaotic | Missing dependency, multiple manual triggers | `cz-cli runs list` → check trigger type |
+| DT refresh reports "table already exists" | DROP+CREATE race condition, or CREATE OR REPLACE type conflict | `SHOW CREATE TABLE` → confirm field types |
+| DT refresh time doesn't align with expectations | REFRESH INTERVAL based on creation time, not clock-aligned | Run `REFRESH DYNAMIC TABLE` immediately after creation |
+| Studio script inconsistent with actual DT | Rebuilt via SQL without syncing Studio | `cz-cli task save-content` to sync |
+| Sync task judged as CDC but actually offline | Only checked readMode field, not combined judgment | Combine cron, pkWriteMode, run records |
+| DWS data inconsistent with DWD metrics | DWS skipping DWD and reading ODS, duplicate computation | `SHOW CREATE TABLE` → check FROM clause |

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

@@ -19,28 +19,7 @@ description: |
 
 Before creating a real-time 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: "Data source type?",
-      options: [
-        { label: "Kafka", description: "Kafka Topic real-time ingestion, supports JSON message parsing" },
-        { label: "MySQL / Aurora MySQL", description: "Single-table CDC real-time sync" },
-        { label: "PostgreSQL / Aurora PG", description: "Single-table CDC real-time sync" },
-        { label: "SQL Server", description: "Single-table CDC real-time sync" }
-      ]
-    },
-    {
-      question: "Sync granularity?",
-      options: [
-        { label: "Single table/topic", description: "Supported by this skill, fine-grained configuration" },
-        { label: "Full database/multi-table", description: "Use clickzetta-cdc-sync-pipeline instead" }
-      ]
-    }
-  ]
-})
-```
+Ask the user two questions: (1) What is the data source type — Kafka (topic real-time ingestion, supports JSON message parsing), MySQL/Aurora MySQL (single-table CDC), PostgreSQL/Aurora PG (single-table CDC), or SQL Server (single-table CDC)? (2) What is the sync granularity — single table/topic (supported by this skill, fine-grained configuration) or full database/multi-table (use clickzetta-cdc-sync-pipeline instead)?
 
 **If the user has already provided sufficient information, proceed directly to the workflow without showing the menu.**
 

package/bin/skills/clickzetta-spark-flink-connector/SKILL.md

@@ -1,39 +1,40 @@
 ---
 name: clickzetta-spark-flink-connector
 description: |
-  使用 Spark Connector 或 Flink Write Connector 将数据写入 ClickZetta Lakehouse。
-  覆盖 Spark DataFrame 读写配置（Maven 依赖、连接参数、read/write 代码）、
-  Flink Table API 写入（CDC 模式 igs-dynamic-table、仅追加模式 igs-dynamic-table-append-only）、
-  checkpoint 配置、buffer/flush 调优，以及主键表限制等关键约束。
-  当用户说"Spark Connector"、"Flink Connector"、"Spark 写入 Lakehouse"、
-  "Flink 写入 Lakehouse"、"spark-clickzetta"、"igs-flink-connector"、
-  "Spark DataFrame 写入"、"Flink CDC 写入"、"Flink sink"、
-  "spark.read.format clickzetta"时触发。
+  Write data to ClickZetta Lakehouse using the Spark Connector or Flink Write Connector.
+  Covers Spark DataFrame read/write configuration (Maven dependencies, connection
+  parameters, read/write code), Flink Table API writes (CDC mode igs-dynamic-table,
+  append-only mode igs-dynamic-table-append-only), checkpoint configuration,
+  buffer/flush tuning, and key constraints such as primary-key table limitations.
+  Trigger when the user says "Spark Connector", "Flink Connector", "Spark writes to Lakehouse",
+  "Flink writes to Lakehouse", "spark-clickzetta", "igs-flink-connector",
+  "Spark DataFrame write", "Flink CDC write", "Flink sink",
+  or "spark.read.format clickzetta".
   Keywords: Spark, Flink, DataFrame, connector, read, write, CDC, igs-dynamic-table
 ---
 
 # ClickZetta Spark & Flink Connector
 
-阅读 [references/spark.md](references/spark.md) 了解 Spark Connector，[references/flink.md](references/flink.md) 了解 Flink Write Connector。
+Read [references/spark.md](references/spark.md) for the Spark Connector and [references/flink.md](references/flink.md) for the Flink Write Connector.
 
 ---
 
-## 关键约束（必读）
+## Key Constraints (Required Reading)
 
-| 约束 | Spark Connector | Flink Connector |
+| Constraint | Spark Connector | Flink Connector |
 |---|---|---|
-| 主键表写入 | ❌ 不支持 | ✅ 支持（igs-dynamic-table 模式） |
-| 部分字段写入 | ❌ 必须写全部字段 | ✅ 支持 |
-| CDC（UPDATE/DELETE） | ❌ 仅 append | ✅ igs-dynamic-table 模式支持 |
-| Spark 版本 | 3.4.0+ | — |
-| Flink 版本 | — | 1.15.2+ |
+| Primary-key table writes | Not supported | Supported in `igs-dynamic-table` mode |
+| Partial-column writes | Not supported; all columns must be written | Supported |
+| CDC (UPDATE/DELETE) | Not supported; append only | Supported in `igs-dynamic-table` mode |
+| Spark version | 3.4.0+ | N/A |
+| Flink version | N/A | 1.14, 1.15, 1.17, 1.18 |
 
 ---
 
-## Spark Connector 快速示例
+## Spark Connector Quick Example
 
 ```scala
-// 写入
+// Write
 df.write.format("clickzetta")
   .option("endpoint", "your_instance.cn-shanghai-alicloud.api.clickzetta.com")
   .option("username", sys.env("CZ_USERNAME"))
@@ -45,7 +46,7 @@ df.write.format("clickzetta")
   .mode("append")
   .save()
 
-// 读取
+// Read
 val df = spark.read.format("clickzetta")
   .option("endpoint", "your_instance.cn-shanghai-alicloud.api.clickzetta.com")
   .option("username", sys.env("CZ_USERNAME"))
@@ -59,10 +60,10 @@ val df = spark.read.format("clickzetta")
 
 ---
 
-## Flink Connector 快速示例
+## Flink Connector Quick Example
 
 ```sql
--- CDC 模式（支持 INSERT/UPDATE/DELETE，目标表需有主键）
+-- CDC mode (supports INSERT/UPDATE/DELETE; the target table must have a primary key)
 CREATE TABLE lakehouse_sink (
     order_id   INT,
     status     STRING,
@@ -82,11 +83,11 @@ INSERT INTO lakehouse_sink SELECT order_id, status, amount FROM source_table;
 
 ---
 
-## 选择指南
+## Selection Guide
 
-| 场景 | 推荐方案 |
+| Scenario | Recommended option |
 |---|---|
-| Spark ETL 批量写入（无主键表） | Spark Connector |
-| Flink 实时流写入（无主键表） | Flink igs-dynamic-table-append-only |
-| Flink CDC 同步（有主键表，含 UPDATE/DELETE） | Flink igs-dynamic-table |
-| 高频实时写入（Java 应用） | Java SDK RealtimeStream |
+| Spark ETL batch writes to a non-primary-key table | Spark Connector |
+| Flink real-time stream writes to a non-primary-key table | Flink `igs-dynamic-table-append-only` |
+| Flink CDC synchronization to a primary-key table, including UPDATE/DELETE | Flink `igs-dynamic-table` |
+| High-frequency real-time writes from a Java application | Java SDK RealtimeStream |