@clickzetta/cz-cli-darwin-arm64 0.3.75 → 0.3.78

package/bin/skills/clickzetta-dynamic-table/SKILL.md

@@ -1,168 +1,230 @@
 ---
 name: clickzetta-dynamic-table
 description: |
-  ClickZetta Dynamic Table（动态表）使用指南，覆盖动态表的创建、修改、增量计算配置和性能优化。
-  包含 DT 声明策略（静态分区 DT vs 动态分区 DT）、SQL 支持矩阵、增量配置参考、刷新历史查询、
-  ALTER 操作指南，以及维度表 JOIN、性能优化、非分区表风险等最佳实践。
-  当用户说"Dynamic Table"、"动态表"、"自动刷新"、"增量刷新"、"物化视图"、
-  "REFRESH interval"、"CREATE DYNAMIC TABLE"、
-  "数据管道自动化"、"增量计算"、"自动物化"、"定时刷新"、
-  "依赖刷新"、"SESSION_CONFIGS"、"静态分区DT"、"动态分区DT"、
-  "状态表"、"state table"、"MERGE INTO"、"Table Stream"时触发。
-  Keywords: dynamic table, incremental refresh, REFRESH interval, materialized, auto-refresh pipeline, SESSION_CONFIGS, partitioned DT, state table, MERGE INTO
+  ClickZetta Dynamic Table（动态表）使用指南与路由中心。
+
+  【触发场景】
+  - 通用咨询：动态表介绍、使用方式、最佳实践、性能优化、增量配置
+  - 创建指导：DT 声明策略、SQL 支持矩阵、刷新历史查询
+  - 修改操作：检测到后自动委托给 dynamic-table-alter 子技能
+  - SQL 转换：检测到后自动委托给 sql-to-dt 子技能
+
+  【触发关键词】
+  "动态表怎么用"、"DT 介绍"、"动态表最佳实践"、"动态表性能优化"、
+  "增量计算配置"、"维度表 JOIN"、"动态表刷新历史"、"静态分区 DT"、
+  "动态分区 DT"、"状态表管理"、"非分区表风险"、"创建动态表"、
+  "动态表调度"、"REFRESH INTERVAL"、"动态表告警"
+
+  【不触发场景】
+  修改操作（"修改动态表"、"加列"、"改间隔"等）→ 使用 dynamic-table-alter
+  SQL转换（"转换DT"、"INSERT OVERWRITE转DT"等）→ 使用 sql-to-dt
 ---
 
-# Dynamic Table 使用指南 — 目录索引
+# Dynamic Table 使用指南 — 路由与索引
 
-## 前置检查：确认可用的 GP 型 VCluster
+本技能是 ClickZetta 动态表的**知识中心和路由器**，根据用户意图提供参考文档或自动委托到专门的操作型子技能。
 
-**创建动态表前必须先确认 VCluster 存在且运行正常。** 动态表的 `vcluster` 参数必须填写实际存在的 GP 型集群名称，写死 `default` 可能导致刷新失败。
+---
 
-```sql
--- 查看所有 VCluster 及其状态
-SHOW VCLUSTERS;
--- 关注列：name, type, status
--- type = GENERAL（GP 型，推荐用于动态表）
--- status = RUNNING（正常）或 STOPPED（已停止，需先启动）
-```
+## 使用场景分类
 
-根据查询结果：
-- 找到 `type = GENERAL` 且 `status = RUNNING` 的集群名称，用于 `vcluster <name>`
-- 如果目标集群 `status = STOPPED`，先执行：`ALTER VCLUSTER <name> RESUME;`
-- 如果没有 GP 型集群，需先创建：参考 `clickzetta-vcluster-manager` skill
+### 1. 通用咨询与学习（本技能处理）
 
-> ⚠️ 不要用 `type = ANALYSIS`（AP 型）的集群创建动态表，AP 型不支持小文件合并，长期运行会导致查询性能下降。
+**适用场景：**
+- 需要查询最佳实践和性能优化建议
+- 寻找特定配置项的说明文档
+- 学习如何创建动态表
 
-## 快速入门
+**触发关键词：**
+- "动态表怎么用"、"DT 介绍"、"Dynamic Table 是什么"
+- "动态表最佳实践"、"DT 性能优化"、"动态表性能调优"
+- "增量计算配置"、"刷新策略"、"状态表管理"
+- "维度表 JOIN 怎么配置"、"非分区表风险"
+- "动态表刷新历史怎么查"、"REFRESH HISTORY"
+- "静态分区 DT"、"动态分区 DT"、"DT 声明策略"
+- "动态表支持哪些 SQL"、"动态表 SQL 限制"
+- "创建动态表"、"新建动态表"、"CREATE DYNAMIC TABLE"
 
-```sql
--- 1. 创建 Dynamic Table（自动调度刷新）
-CREATE DYNAMIC TABLE IF NOT EXISTS silver.orders_daily
-REFRESH INTERVAL 60 MINUTE vcluster default
-AS
-SELECT DATE(created_at) AS order_date, region, SUM(amount) AS total_amount
-FROM bronze.raw_orders
-GROUP BY 1, 2;
+**处理方式：** 提供相关参考文档的内容和指引。
 
--- 2. 查看状态与刷新历史
-DESC DYNAMIC TABLE silver.orders_daily;
-SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'orders_daily' LIMIT 10;
+---
 
--- 3. 手动触发刷新
-REFRESH DYNAMIC TABLE silver.orders_daily;
+### 2. 修改现有动态表（自动委托给 dynamic-table-alter 子技能）
 
--- 4. 列出所有 Dynamic Table
-SHOW TABLES IN silver WHERE is_dynamic;
--- 返回列：schema_name, table_name, is_view, is_materialized_view, is_external, is_dynamic
--- ⚠️ 列名是 table_name（不是 name），过滤用 WHERE table_name = 'xxx'
+**适用场景：**
+- 需要修改已存在的动态表结构或属性
+- 暂停/恢复动态表刷新
+- 添加/删除列、修改刷新间隔、修改查询定义
 
--- 5. 查看指定表是否为动态表
-SHOW TABLES IN silver WHERE table_name = 'orders_daily';
-```
+**触发关键词：**
+- "修改动态表"、"动态表加列"、"动态表删列"
+- "改刷新间隔"、"修改 REFRESH_INTERVAL"
+- "暂停动态表"、"恢复动态表"、"SUSPEND"、"RESUME"
+- "重命名列"、"修改列注释"、"修改表注释"
+- "ALTER DYNAMIC TABLE"、"CREATE OR REPLACE DYNAMIC TABLE"
+- "修改 DT 查询定义"、"修改 AS SELECT"
 
-### 调度方式
+**处理方式：**
+> ⚠️ 检测到修改操作意图，应立即加载 dynamic-table-alter 子技能。
+> 该子技能提供完整的 10 种修改操作工作流：
+> - 5种直接 ALTER：suspend、resume、set_comment、rename_column、set_column_comment
+> - 5种 CREATE OR REPLACE：add_column、drop_column、alter_column、set_refresh_interval、set_select
 
-| 方式 | 语法 | 适用场景 |
-|---|---|---|
-| 自动调度 | `REFRESH INTERVAL 10 MINUTE vcluster <name>` | 系统按间隔自动刷新（推荐） |
-| 指定开始时间 | `REFRESH START WITH TIMESTAMP '2025-01-01 00:00:00' INTERVAL 1 HOUR vcluster <name>` | 从指定时间开始调度 |
-| 手动触发 | `REFRESH DYNAMIC TABLE my_dt;` | 外部调度器触发，适合静态分区 DT |
+---
 
-INTERVAL 支持的单位：`SECOND`、`MINUTE`、`HOUR`、`DAY`，最小值为 1 分钟。
+### 3. SQL 转换为动态表（自动委托给 sql-to-dt 子技能）
+
+**适用场景：**
+- 将 Hive/Spark 等任意批处理系统的 CREATE TABLE + INSERT OVERWRITE 转换为 DT
+- 批量迁移传统 ETL 到动态表
+- 自动生成 refresh、backfill 等配套文件
+
+**触发关键词：**
+- "转换 DT"、"sql to dt"、"convert to dynamic table"
+- "INSERT OVERWRITE 转 DT"、"DDL 转换"
+- "Hive SQL 转 ClickZetta"、"Spark SQL 转动态表"
+- "批量转换 ETL"、"迁移到动态表"
+- "创建动态表"、"新建动态表"、"CREATE DYNAMIC TABLE"
+
+**处理方式：**
+> ⚠️ 检测到 SQL 转换意图，应立即加载 sql-to-dt 子技能。
+> 如果用户说"创建动态表"但未提供 DDL 和 INSERT OVERWRITE，应主动提示：
+> "请提供原始的 CREATE TABLE DDL 和 INSERT OVERWRITE 语句，我可以全自动生成对应的 Dynamic Table DDL 及配套的 refresh、backfill 文件。"
+> 该子技能提供 6 步自动转换工作流：
+> 1. 预处理输入（移除 ALTER、ANALYZE、注释）
+> 2. 占位符替换（转换为 SESSION_CONFIGS）
+> 3. 自引用检测
+> 4. 核心转换（合并 DDL + INSERT 为 CREATE OR REPLACE）
+> 5. 列校验
+> 6. 生成配套文件（refresh、prev_refresh、backfill）
 
-> ⚠️ **VCluster 类型**：始终使用 GP 型集群（`vcluster default`），不要用 AP 型（`default_ap`）。AP 型集群不支持小文件合并，长期运行会导致查询性能下降。
+---
 
-### ⚠️ 刷新周期的时间基准
+## 知识库目录
 
-**`REFRESH INTERVAL N DAY/HOUR` 以动态表的创建时间（或上次刷新时间）为基准计算下次触发时间，不是从零点或整点开始对齐。**
+### dt-creator/ — 创建动态表参考资料
 
-例如：动态表在 23:17 创建，设置 `REFRESH INTERVAL 1 DAY`，则后续每次刷新约在 23:17 触发，而不是次日 00:00 或业务期望的 03:00。`START WITH TIMESTAMP` 仅影响首次刷新时间，不改变后续周期的基准。
+**包含内容：**
+- **dt-declaration-strategy.md** — 静态分区 DT vs 动态分区 DT 的声明策略与选择
+  - 静态分区 DT：使用 SESSION_CONFIGS() 传递分区参数，每个分区独立刷新
+  - 动态分区 DT：不传递分区参数，一次性处理所有增量数据
+  - 决策树：根据数据模式选择合适的分区策略
 
-**如需控制刷新时间窗口，有三种方案：**
+- **sql-limitations.md** — 增量计算支持的 SQL 模式（JOIN、聚合、窗口函数等的支持情况，以及 VIEW/外部表不支持增量的限制）
 
-1. **在目标时间点附近创建动态表**（最简单）
-2. **创建后立即执行 `REFRESH` 重置基准**（推荐，见下方最佳实践）
-3. **改用短间隔**（如 `4 HOUR`）减少偏差，业务容忍度允许时可接受
+- **incremental-config-reference.md** — 增量刷新配置项完整参考
+  - 刷新策略：强制全量、尝试增量并回退
+  - 源表特征声明：维度表、仅追加表
+  - 全量回退触发条件：基于表变更或变更量
+  - 状态表管理：启用/禁用、生命周期、重建、schema 指定
+  - DT 定义变更：CREATE OR REPLACE 的兼容性检查
+  - Backfill：历史分区数据修正
+  - 分区表写入行为：覆盖 vs 追加模式
 
-### 创建动态表的最佳实践：创建后立即执行首次刷新
+- **refresh-history-guide.md** — 刷新历史查询的 3 种方式
+  - SHOW DYNAMIC TABLE REFRESH HISTORY：作业级信息，含 refresh_mode（INCREMENTAL/FULL/NO_DATA）
+  - DESC HISTORY：版本级历史，含行数、字节数、操作类型
+  - information_schema.materialized_view_refresh_history：批量分析、监控、CRU 统计
 
-```sql
--- ✅ 推荐写法：创建后立即 REFRESH，重置刷新基准时间，实现"开箱即用"
-CREATE DYNAMIC TABLE IF NOT EXISTS dws.user_order_daily
-REFRESH INTERVAL 1 DAY vcluster default
-AS
-SELECT user_id, DATE(created_at) AS dt, COUNT(*) AS order_cnt
-FROM dwd.fact_orders
-GROUP BY 1, 2;
+**适用问题：**
+- "静态分区 DT 和动态分区 DT 有什么区别？ "
+- "动态表支持哪些 SQL 语法？"
+- "增量计算的配置项有哪些？"
+- "怎么查看动态表的刷新历史？"
+- "什么时候会触发全量刷新？"
 
-REFRESH DYNAMIC TABLE dws.user_order_daily;
--- 立即触发首次计算，同时将刷新基准时间重置为当前时刻
-```
+---
 
-### 手动刷新命令
+### dynamic-table-alter/ — 修改动态表操作指南
 
-```sql
--- ✅ 推荐：手动触发刷新
-REFRESH DYNAMIC TABLE schema.table_name;
+**包含内容：**
+- 完整的动态表修改工作流（10 种操作）
+- 5 种直接 ALTER 操作：suspend、resume、set_comment、rename_column、set_column_comment
+- 5 种 CREATE OR REPLACE 操作：add_column、drop_column、alter_column、set_refresh_interval、set_select
+- 平台特有语法和限制说明（CHANGE COLUMN、RENAME COLUMN、DML 限制等）
+- 详细示例和故障排除
 
--- ⚠️ 不推荐：ALTER DYNAMIC TABLE ... REFRESH 语法不标准，建议使用上面的 REFRESH 命令
--- ALTER DYNAMIC TABLE schema.table_name REFRESH;
-```
+> ⚠️ 此目录对应独立的 **dynamic-table-alter 子技能**。当用户有明确的修改操作意图时，应直接加载该子技能而非本指南。
 
-### 开启增量刷新的前提
+---
 
-源表需开启变更跟踪：
-```sql
-ALTER TABLE bronze.raw_orders SET PROPERTIES ('change_tracking' = 'true');
-```
+### sql-to-dt/ — SQL 转 DT 自动转换
 
-### 增量刷新 vs 全量刷新
-
-通过 `SHOW DYNAMIC TABLE REFRESH HISTORY` 的 `refresh_mode` 字段可查看刷新模式：
-- `INCREMENTAL`：增量刷新（仅处理变更数据，高效）
-- `FULL`：全量刷新（重新计算所有数据）
-- `NO_DATA`：无数据变更，跳过刷新
-
-**触发全量刷新的条件**：
-| 条件 | 说明 |
-|---|---|
-| 源表未开启 `change_tracking` | 系统无法识别增量数据 |
-| 查询含不支持增量的算子 | 如某些复杂 JOIN、子查询 |
-| `CREATE OR REPLACE` 修改了计算逻辑 | 如修改 WHERE、GROUP BY、JOIN key |
-| 手动设置强制全量 | `SET cz.optimizer.incremental.force.full.refresh = true` |
-| 维度表变更 | 被 JOIN 的维度表数据变化时，增量结果可能不一致 |
-
-**确认是否支持增量刷新**：
-```sql
-SET cz.optimizer.explain.can.incrementalize = true;
-EXPLAIN REFRESH DYNAMIC TABLE my_dt;
--- 查看 CanBeIncrementalized 字段：Yes = 支持增量，No = 不支持（会给出原因）
-```
+将 Hive/Spark 等任意批处理系统的 CREATE TABLE DDL + INSERT OVERWRITE 全自动转换为 Dynamic Table DDL 及配套文件（refresh、prev_refresh、backfill）。
+
+详细转换规则参见 sql-to-dt 子技能。
 
 ---
 
-## dt-creator/
-创建 Dynamic Table 的参考资料（声明策略、SQL 支持矩阵、增量配置、刷新历史查询）。
+### best-practices/ — 最佳实践与避坑指南
+
+**包含内容：**
+
+- **performance-optimization.md** — 性能优化策略
+  - 核心原则：变更量占比（< 5% 适合增量）、算子类型（INNER JOIN 快于 OUTER JOIN）、数据局部性
+  - SQL 优化技巧：优先 INNER JOIN、减少 DISTINCT、窗口函数必须有 PARTITION BY、使用分区条件限制数据范围
+  - 管道拆分：将复杂 DT 拆分为多个阶段
+
+- **dimension-table-join-guide.md** — 维度表 JOIN 场景详解
+  - 核心机制：维度表变更被忽略，仅事实表变更触发增量计算
+  - 配置方式：TBLPROPERTIES('mv_const_tables'='dim1,dim2') 或 Session 配置
+  - 推荐场景：码表/字典表、T+1 维度 + 实时事实表、大事实 JOIN 小维度
+  - 不推荐场景：频繁更新的维度且需要实时一致性
+  - 数据修正：维度表变更后必须使用全量刷新
+
+- **non-partitioned-merge-into-warning.md** — 非分区 DT + 连续写入风险告警
+  - 触发条件：DT 是非分区表 + 源表连续写入 + SQL 含 ROW_NUMBER() 去重
+  - 三大风险：存储无限增长、归档引发性能灾难、无法过滤归档删除
+  - 推荐替代方案：MERGE INTO + Table Stream（归档免疫、独立生命周期管理）
+
+- **scheduling-guide.md** — 调度方式选择指南
+  - 两种方式对比：DDL 内置调度（REFRESH INTERVAL）vs Studio Task 调度
+  - 有 Studio 时始终推荐 Studio Task：支持上下游依赖、统一告警、可视化监控
+  - DDL 内置调度的弊端：无告警、无依赖编排、只能手动 SQL 查询刷新状态
+  - Studio Task 配置要点：必须开启自依赖、配置失败/超时告警、按需配置上游依赖
+  - 多级 DT 管道的调度编排方式
+
+**适用问题：**
+- "动态表性能怎么优化？"
+- "维度表 JOIN 怎么配置？"
+- "非分区动态表有什么风险？"
+- "什么时候不应该用动态表？"
+- "动态表调度用 REFRESH INTERVAL 还是 Studio Task？"
+- "动态表刷新失败怎么收到告警？"
+
+---
 
-## dynamic-table-alter/
-修改 Dynamic Table 的结构和属性（suspend/resume、加列删列、改刷新间隔等）。
+## 路由决策树
 
-## best-practices/
-Dynamic Table 最佳实践与避坑指南（维度表 JOIN 场景、性能优化、非分区表风险告警）。
+```
+用户提问
+    │
+    ├─ 包含修改操作关键词？
+    │   （"修改动态表"、"加列"、"改间隔"、"暂停"、"ALTER DYNAMIC TABLE"）
+    │   └─ 是 → 立即加载 dynamic-table-alter 子技能
+    │
+    ├─ 包含 SQL 转换关键词？
+    │   （"转换DT"、"sql to dt"、"INSERT OVERWRITE转DT"、"DDL转换"、"创建动态表"）
+    │   └─ 是 → 立即加载 sql-to-dt 子技能
+    │
+    └─ 通用咨询/学习？
+        （"动态表怎么用"、"最佳实践"、"性能优化"、"增量配置"）
+        └─ 是 → 提供本指南的参考文档
+```
 
 ---
 
-## 常见问题排障
-
-| 问题 | 原因 | 解决方案 |
-|---|---|---|
-| 刷新一直是 FULL 模式 | 源表未开启 change_tracking，或查询含不支持增量的算子 | 开启 change_tracking；用 `EXPLAIN REFRESH` 检查 |
-| 刷新延迟超过预期 | VCluster 资源不足，或查询复杂度高 | 升级 VCluster 规格；拆分管道 |
-| `SUSPEND` 后数据不更新 | 已暂停 | 执行 `ALTER DYNAMIC TABLE ... RESUME` |
-| 依赖链中下游不刷新 | 上游 Dynamic Table 刷新失败 | 先修复上游，再手动 `REFRESH` 下游 |
-| 删除报错 | 有下游 Dynamic Table 依赖 | 先删除下游，再删除上游 |
-| 增量结果与全量不一致 | 维度表变更未触发重算 | 执行全量刷新：`SET cz.optimizer.incremental.force.full.refresh = true` |
-| 状态表损坏 | 系统异常 | `SET cz.optimizer.incremental.rebuild.rule.based.state.table = true` |
-| 手动 REFRESH 后历史未显示 | 刷新历史有短暂延迟 | 等待几秒后重新查询 `SHOW DYNAMIC TABLE REFRESH HISTORY` |
-| AP 集群刷新后查询变慢 | AP 集群不支持小文件合并 | 改用 GP 型集群（`CREATE OR REPLACE` 重建） |
-| 刷新时间与预期不符（如期望 03:00 实际 23:00） | REFRESH INTERVAL 以创建时间为基准，不对齐整点 | 在目标时间点附近创建 DT，或创建后立即执行 `REFRESH DYNAMIC TABLE` 重置基准 |
+## 使用建议
+
+1. **首次学习**：从 dt-creator/ 开始，了解 DT 的声明策略和配置项
+2. **迁移场景**：使用 sql-to-dt 子技能批量转换现有 ETL
+3. **日常运维**：使用 dynamic-table-alter 子技能修改 DT 结构
+4. **性能调优**：参考 best-practices/ 中的优化建议和避坑指南
+5. **调度配置**：有 Studio 时始终使用 Studio Task 调度，参考 best-practices/scheduling-guide.md
+
+---
+
+## 相关技能
+
+- **dynamic-table-alter** — 修改动态表的操作型子技能（10 种修改操作）
+- **sql-to-dt** — SQL 转 DT 的转换型子技能（6 步自动转换工作流）

package/bin/skills/clickzetta-dynamic-table/best-practices/dimension-table-join-guide.md

@@ -16,10 +16,7 @@ TBLPROPERTIES('mv_const_tables'='dim_table1,dim_table2')
 AS SELECT ...;
 
 -- 方式2：Session 配置（在 REFRESH 前设置，灵活可动态调整）
--- set CZ_OPTIMIZER_INCREMENTAL_DIMENSION_TABLES=dim_table1:dim_table2
-
--- 查看已设置的 TBLPROPERTIES（使用 SHOW CREATE TABLE，不支持 SHOW TBLPROPERTIES）
-SHOW CREATE TABLE my_dt;
+set CZ_OPTIMIZER_INCREMENTAL_DIMENSION_TABLES=dim_table1:dim_table2
 ```
 
 ## 各 JOIN 类型下的增量行为
@@ -154,21 +151,20 @@ LEFT JOIN t3 ON t1.id = t3.id;
 
 ```sql
 -- 强制全量刷新（推荐）
--- set cz.optimizer.incremental.force.full.refresh=true
+set cz.optimizer.incremental.force.full.refresh=true
 REFRESH DYNAMIC TABLE my_dt;
 -- 刷新完成后记得关闭，否则后续每次都是全量
-SET cz.optimizer.incremental.force.full.refresh = false;
+set cz.optimizer.incremental.force.full.refresh=false
 
--- 如果是分区表，也可以只全量刷新指定分区（在 Studio 任务中执行）
-SET cz.optimizer.incremental.force.full.refresh = true;
+-- 如果是分区表，也可以只全量刷新指定分区
+set cz.optimizer.incremental.force.full.refresh=true
+set dt.args.ds=2025-01-01
 REFRESH DYNAMIC TABLE my_dt PARTITION(ds = '2025-01-01');
-SET cz.optimizer.incremental.force.full.refresh = false;
+set cz.optimizer.incremental.force.full.refresh=false
 ```
 
 配置说明：
 - `cz.optimizer.incremental.force.full.refresh`：默认 `false`。设为 `true` 后，下一次 REFRESH 会忽略增量逻辑，对所有源表做全量扫描重算
-- `SET cz.optimizer.*` 配置项在交互式 SQL 中可用
-- `dt.args.*` 参数仅在 Studio 任务中可用，不能在交互式 SQL 中 SET
 - 该配置是 session 级别的，刷新完成后需要手动设回 `false`，否则后续所有 REFRESH 都会走全量
 - backfill 模式（`cz.optimizer.incremental.backfill.enabled=TRUE`）也会自动开启全量刷新
 

package/bin/skills/clickzetta-dynamic-table/best-practices/scheduling-guide.md

@@ -0,0 +1,135 @@
+# Dynamic Table 调度方式选择指南
+
+## 两种调度方式对比
+
+| 方式 | 做法 | 优点 | 缺点 |
+|------|------|------|------|
+| **DDL 内置调度**（REFRESH INTERVAL） | 在 CREATE DYNAMIC TABLE 时写 `REFRESH INTERVAL` 子句，由 Lakehouse 自动触发 | 简单，无需额外配置 | 无告警、无依赖编排、刷新状态只能手动 SQL 查询 |
+| **Studio Task 调度**（推荐） | 在 Studio 创建定时任务，任务内容为 `REFRESH DYNAMIC TABLE` 命令 | 支持上下游依赖、统一告警、可视化监控 | 需要额外创建 Task |
+
+**生产环境推荐使用 Studio Task 调度。** DDL 内置调度适合快速验证和开发测试阶段。
+
+---
+
+## DDL 内置调度
+
+在 CREATE 语句中通过 `REFRESH INTERVAL` 子句定义刷新频率，Lakehouse 自动周期性触发：
+
+```sql
+CREATE DYNAMIC TABLE sales_daily
+REFRESH INTERVAL 1 DAY
+VCLUSTER default
+AS
+SELECT DATE(created_at) AS dt, SUM(amount) AS total
+FROM orders
+GROUP BY 1;
+```
+
+### 弊端
+
+- **无告警**：刷新失败不会主动通知，只能手动执行 SQL 查询状态
+- **无依赖编排**：无法声明"等上游任务完成后再刷新"，只能靠时间间隔错开
+- **监控成本高**：需要定期手动执行以下命令检查刷新是否正常
+
+```sql
+-- 查看刷新历史，确认 state 是否为 SUCCEED
+SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'your_dt_name';
+```
+
+关键字段说明：
+
+| 字段 | 含义 |
+|------|------|
+| `state` | SUCCEED / FAILED / RUNNING / QUEUED |
+| `refresh_mode` | INCREMENTAL / FULL / NO_DATA |
+| `error_message` | 失败时的错误信息 |
+| `duration` | 本次刷新耗时 |
+| `stats` | 增量行数（rows_inserted / rows_deleted） |
+
+---
+
+## Studio Task 调度（生产推荐）
+
+在 Studio 中创建 SQL 任务，任务内容为 REFRESH 命令，通过 Studio 的调度系统管理执行。
+
+### Task 内容
+
+**非分区 DT：**
+
+```sql
+REFRESH DYNAMIC TABLE schema_name.dt_name;
+```
+
+**分区 DT（带参数）：**
+
+```sql
+SET dt.args.ds = '${bizdate}';
+REFRESH DYNAMIC TABLE schema_name.dt_name PARTITION (ds = '${bizdate}');
+```
+
+`${bizdate}` 由 Studio 调度引擎在每次执行时自动替换为业务日期。
+
+### 必须配置自依赖
+
+同一张 DT 禁止并发 REFRESH（会导致写冲突或数据不一致）。Task 必须开启**自依赖**，确保上一个实例完成后才启动下一个实例。
+
+### 上游依赖配置
+
+- 如果 DT 的源表数据需要等上游任务产出后才能刷新 → 配置上游依赖
+- 如果源表数据不要求同步就绪（如实时写入表）→ 可以不配置上游依赖
+
+### 告警配置
+
+Studio Task 支持以下告警规则，生产环境建议全部配置：
+
+- **失败告警**：任务执行失败时通知
+- **超时告警**：刷新耗时超过阈值时通知（用于发现性能回退）
+- **未运行告警**：任务在预期时间内未启动时通知
+
+---
+
+## 多级 DT 管道的调度编排
+
+当存在多张 DT 形成上下游依赖时（如 DT_A → DT_B → DT_C），每张 DT 对应一个 Studio Task，通过任务依赖关系保证执行顺序：
+
+```
+Task_A (REFRESH DT_A)
+    └─ Task_B (REFRESH DT_B，依赖 Task_A)
+        └─ Task_C (REFRESH DT_C，依赖 Task_B)
+```
+
+不同分区的 REFRESH 可以并行执行（分配到不同 Task 实例），同一分区/非分区 DT 禁止并发。
+
+---
+
+## 判断逻辑：向用户推荐调度方式
+
+在帮助用户创建或配置 DT 时，按以下逻辑推荐：
+
+1. **是否有 Studio？**
+   - 有 → 始终推荐 Studio Task 调度，无论是开发还是生产环境
+   - 无 → 使用 DDL 内置调度或第三方调度引擎
+
+2. **是否有上下游依赖？**
+   - 有（如源表由另一个任务产出）→ 必须用 Studio Task，配置上游依赖
+   - 无 → 仍推荐 Studio Task，获得告警能力
+
+3. **用户已经写了 REFRESH INTERVAL 子句？**
+   - 提示：可以去掉 REFRESH INTERVAL 子句，改用 Studio Task 调度，获得告警和依赖管理能力
+   - REFRESH INTERVAL 和 Studio Task 可以共存，但会导致双重触发，建议二选一
+
+---
+
+## 告警话术模板
+
+当用户使用 DDL 内置调度时，使用以下话术提示：
+
+> 💡 **建议**：您当前使用的是 DDL 内置调度（REFRESH INTERVAL），这种方式存在以下局限：
+>
+> 1. **无告警**：刷新失败不会主动通知，需要手动执行 `SHOW DYNAMIC TABLE REFRESH HISTORY` 查看状态
+> 2. **无依赖编排**：无法声明上下游任务依赖关系，只能靠时间间隔错开
+>
+> **推荐**：在 Studio 中创建定时调度任务，任务内容为 `REFRESH DYNAMIC TABLE schema.dt_name`，并配置：
+> - 自依赖（防止并发刷新）
+> - 失败告警 + 超时告警
+> - 上游依赖（如果源表由其他任务产出）

package/bin/skills/clickzetta-dynamic-table/dt-creator/references/dt-declaration-strategy.md

@@ -18,7 +18,8 @@ SELECT id, amount, SESSION_CONFIGS()['dt.args.ds'] AS ds
 FROM orders
 WHERE ds = SESSION_CONFIGS()['dt.args.ds'];
 
--- 刷新时指定分区（在 Studio 任务中执行，dt.args.ds 通过任务参数传入）
+-- 刷新时指定分区
+set dt.args.ds=2025-01-01
 REFRESH DYNAMIC TABLE order_daily PARTITION(ds = '2025-01-01');
 ```
 
@@ -106,22 +107,21 @@ REFRESH DYNAMIC TABLE order_summary;
 
 ### 刷新方式
 
-> ⚠️ **重要**：静态分区 DT 的 `dt.args.*` 参数**仅在 Studio 任务中可用**，不能在交互式 SQL 中使用 `SET dt.args.xxx`。
-> 必须通过 Studio 创建调度任务，在任务参数中配置 `dt.args.ds` 等值。
-
 ```sql
--- 在 Studio 任务中，参数通过任务配置传入，REFRESH 语句指定分区值：
+-- 每次刷新一个分区
+set dt.args.ds=2025-01-15
 REFRESH DYNAMIC TABLE my_dt PARTITION(ds = '2025-01-15');
 
 -- 多级分区
+set dt.args.pt=20250411
+set dt.args.pt_hour=01
 REFRESH DYNAMIC TABLE my_dt PARTITION(pt = '20250411', pt_hour = '01');
 ```
 
 ### 注意事项
 
-- 回填时使用 `SET cz.optimizer.incremental.backfill.enabled = TRUE`（此配置在交互式 SQL 中可用）
-- `dt.args.*` 参数仅在 Studio 任务中可用，不能在交互式 SQL 中 SET
-- `cz.optimizer.*` 配置项在交互式 SQL 中可用
+- 回填时使用 `cz.optimizer.incremental.backfill.enabled=TRUE`，会自动走全量刷新
+- 分区参数通过 `set dt.args.xxx=value` 传入，REFRESH 语句中的 PARTITION 子句指定分区值
 
 ## 动态分区 DT 详解
 

package/bin/skills/clickzetta-dynamic-table/dt-creator/references/incremental-config-reference.md

@@ -87,9 +87,6 @@ CREATE DYNAMIC TABLE my_dt
 TBLPROPERTIES('mv_const_tables' = 'dim_product,dim_region')
 AS SELECT ...;
 
--- 查看已设置的 TBLPROPERTIES（⚠️ 不支持 SHOW TBLPROPERTIES 语法）
-SHOW CREATE TABLE my_dt;
-
 -- 或通过 Session 配置（在 REFRESH 语句前执行）
 SET cz.optimizer.incremental.dimension.tables = 'dim_product,dim_region';
 REFRESH DYNAMIC TABLE my_dt;
@@ -352,8 +349,9 @@ SET cz.sql.mv.check.before.replacing.sql = true;
 - 回填通常配合 `INSERT OVERWRITE` 使用，覆盖目标分区的已有数据。
 
 ```sql
--- 在 Studio 任务中，参数通过任务配置传入：
+-- 回填指定历史分区（在 REFRESH 语句前执行）
 SET cz.optimizer.incremental.backfill.enabled = true;
+SET dt.args.ds = '2025-01-01';
 REFRESH DYNAMIC TABLE my_dt PARTITION(ds = '2025-01-01');
 SET cz.optimizer.incremental.backfill.enabled = false;
 

package/bin/skills/clickzetta-dynamic-table/dt-creator/references/refresh-history-guide.md

@@ -11,21 +11,16 @@
 ### 语法
 
 ```sql
--- 查看指定 DT 的刷新历史（使用 WHERE name = 过滤）
+-- 通过 WHERE 过滤（name 列匹配表名）
 SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt';
 
--- 限制返回行数
-SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' LIMIT 10;
-
--- 组合 WHERE + LIMIT + 状态过滤
+-- 组合 WHERE + LIMIT
 SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' AND state = 'SUCCEED' LIMIT 20;
 
 -- MV 也支持同样的语法
 SHOW MATERIALIZED VIEW REFRESH HISTORY WHERE name = 'my_mv' LIMIT 10;
 ```
 
-> ⚠️ 注意：`FOR <table_name>` 语法在当前版本中可能返回空结果，请使用 `WHERE name = '<table_name>'` 语法。
-
 ### 输出列
 
 | 列名 | 类型 | 说明 |
@@ -80,9 +75,6 @@ SHOW MATERIALIZED VIEW REFRESH HISTORY WHERE name = 'my_mv' LIMIT 10;
 ### 典型用法
 
 ```sql
--- 查看最近 5 次刷新是否成功
-SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' LIMIT 5;
-
 -- 查看失败的刷新记录
 SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' AND state = 'FAILED';
 

package/bin/skills/clickzetta-dynamic-table/sql-to-dt/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: sql-to-dt
+description: 将 Hive/Spark 等任意批处理系统的 CREATE TABLE DDL + INSERT OVERWRITE SQL 自动转换为 Dynamic Table DDL 及配套文件（refresh、prev_refresh、backfill）。当用户提供 DDL 和 INSERT OVERWRITE 要求转换为 DT 时触发，或用户说"创建动态表"时主动引导提供输入。Triggers on: "转换DT", "sql to dt", "convert to dynamic table", "INSERT OVERWRITE 转 DT", "DDL 转换", "创建动态表"
+---
+
+# SQL → Dynamic Table 自动转换
+
+将 Hive/Spark 等任意批处理系统的 ETL SQL（CREATE TABLE + INSERT OVERWRITE）转换为 Dynamic Table DDL 及配套运维文件。
+
+## 使用方式
+
+提供以下输入：
+1. CREATE TABLE DDL（表结构定义）
+2. INSERT OVERWRITE SQL（ETL 查询逻辑）
+
+转换工具会自动完成：占位符替换、自引用检测、核心转换、列校验、配套文件生成、转换后改进建议。
+
+详细工作流参见 #[[file:references/sql2dt-workflow.md]]
+
+## references/
+
+- **sql2dt-workflow.md** — 完整转换工作流（6 步：预处理、占位符替换、自引用检测、核心转换、列校验、配套文件生成）
+- **sql2dt-conversion-rules.md** — 核心 DDL 转换规则（解析 DDL、解析 INSERT、组装 DT DDL、静态分区注入）
+- **sql2dt-placeholder-rules.md** — 占位符替换规则（${var} → SESSION_CONFIGS()）
+- **sql2dt-self-reference-rules.md** — 自引用表转换规则
+- **sql2dt-column-validation-rules.md** — 列校验规则（schema 列数 = SELECT 列数）
+- **sql2dt-refresh-rules.md** — Refresh 与调度文件生成规则