@clickzetta/cz-cli-darwin-x64 0.3.10 → 0.3.13

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

@@ -1,6 +1,6 @@
 ---
-name: cz-cli
-description: "Route ALL ClickZetta Lakehouse operations to cz-cli: SQL, Studio tasks, tables, pipelines, profiles. Never for general programming or non-ClickZetta work."
+name: cz-cli-v2
+description: Route ALL ClickZetta Lakehouse operations to cz-cli: SQL, Studio tasks, tables, pipelines, profiles. Use when user mentions ClickZetta, Lakehouse, cz-cli, or needs profile/connection configuration.
 ---
 
 # cz-cli — ClickZetta Lakehouse Subagent
@@ -47,6 +47,71 @@ cz-cli agent run "<request>" --profile uat_test --format a2a --dangerously-skip-
 
 Available profiles: read `~/.clickzetta/profiles.toml` or run `cz-cli profile list`.
 
+## Adding a new profile
+
+**Trigger conditions:** User says "configure new environment", "add profile", "can't connect", mentions an unknown profile name, or provides connection credentials.
+
+### Step 1 — Collect information (guided Q&A)
+
+If all required fields are already provided, skip directly to Step 2.
+
+Otherwise, ask for missing ones. Accept all at once or prompt one by one.
+
+**Required fields:**
+
+| Field | Question to ask | Example |
+|-------|----------------|---------|
+| `service` | Which cloud region? (see table below, or provide the service endpoint directly) | `cn-shanghai-alicloud.api.clickzetta.com` |
+| `instance` | What is the instance name? | `billingsh` |
+| `workspace` | What is the workspace name? | `meter_n_bill` |
+| `username` | What is the username? | `billing_admin` |
+| `password` | What is the password? | — |
+| `name` | What should this profile be named? (suggested format below) | `billingsh` |
+
+**Common service endpoints (offer as options):**
+
+| Region | service | Suggested profile prefix |
+|--------|---------|--------------------------|
+| Alibaba Cloud East China 2 (Shanghai) | `cn-shanghai-alicloud.api.clickzetta.com` | `cn-shanghai` |
+| Tencent Cloud East China (Shanghai) | `ap-shanghai-tencentcloud.api.clickzetta.com` | `ap-shanghai` |
+| Tencent Cloud North China (Beijing) | `ap-beijing-tencentcloud.api.clickzetta.com` | `ap-beijing` |
+| Tencent Cloud South China (Guangzhou) | `ap-guangzhou-tencentcloud.api.clickzetta.com` | `ap-guangzhou` |
+| AWS China (Beijing) | `cn-north-1-aws.api.clickzetta.com` | `cn-north-1` |
+
+**Inference rules (reduce unnecessary questions):**
+- If the user describes a cloud region in natural language (e.g. "Alibaba Cloud Shanghai", "Tencent Cloud Beijing", "阿里云上海", "腾讯云北京"), look up the service endpoint from the table above — do NOT ask the user to provide it again.
+- If the user hasn't provided a profile name, suggest `<prefix>-<instance>` using the prefix from the table (e.g. `cn-shanghai-billingsh`). Confirm with the user or proceed if they don't object.
+
+### Step 2 — Create profile
+
+Run `cz-cli profile create` with all collected fields:
+
+```bash
+cz-cli profile create <name> \
+  --username <username> \
+  --password <password> \
+  --instance <instance> \
+  --workspace <workspace> \
+  --service <service> \
+  --schema public \
+  --vcluster default
+```
+
+### Step 3 — Verify connection
+
+After creating, run:
+
+```bash
+cz-cli status --profile <name>
+```
+
+A successful response looks like:
+```json
+{"data": {"connected": true, "workspace": "...", "time_ms": ...}}
+```
+
+If it fails, report the error and ask the user to double-check credentials or service endpoint.
+
 ## Error handling
 
 All errors in non-TTY mode output JSON to stdout:
@@ -55,4 +120,4 @@ All errors in non-TTY mode output JSON to stdout:
 {"ok": false, "error": "NO_PROFILE", "next_steps": ["cz-cli setup --credential <base64>"]}
 ```
 
-On `NO_PROFILE` error: guide user to run `cz-cli setup --credential <base64>`. See `references/profile-setup.md`.
+On `NO_PROFILE` error: check if a profile can be configured via username/password (see "Adding a new profile" above). If the user has a base64 credential instead, guide them to run `cz-cli setup --credential <base64>`. See `references/profile-setup.md`.

package/bin/skills/cz-cli/references/profile-setup.md

@@ -79,6 +79,38 @@ For `openai-compatible` (third-party relays), add `--base-url <url>`.
  "supported_providers": ["anthropic", "openai", "openai-compatible", "bedrock", "google", "azure"]}
 ```
 
+## Alternative: username/password profile (no credential required)
+
+If the user has an existing instance account (username + password) but no base64 credential, use `cz-cli profile create` directly:
+
+```bash
+cz-cli profile create <name> \
+  --username <username> \
+  --password <password> \
+  --instance <instance_name> \
+  --workspace <workspace_name> \
+  --service <service_host> \
+  --schema public \
+  --vcluster default
+```
+
+**Common service endpoints:**
+
+| 云区域 | service |
+|--------|---------|
+| 阿里云 华东2（上海） | `cn-shanghai-alicloud.api.clickzetta.com` |
+| 腾讯云 华东（上海） | `ap-shanghai-tencentcloud.api.clickzetta.com` |
+| 腾讯云 华北（北京） | `ap-beijing-tencentcloud.api.clickzetta.com` |
+| 腾讯云 华南（广州） | `ap-guangzhou-tencentcloud.api.clickzetta.com` |
+| AWS 中国（北京） | `cn-north-1-aws.api.clickzetta.com` |
+
+After creating, verify with:
+```bash
+cz-cli status --profile <name>
+```
+
+Note: `profile discover` / `list-workspaces` / `render-command` require a Studio page URL (`https://<instance>.accounts.clickzetta.com`) and are not usable when only a service endpoint + credentials are available.
+
 ## Step-by-step: no credential available
 
 If the user doesn't have a base64 credential, guide them to:

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

@@ -34,7 +34,8 @@ 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 save-config <task>                Save task schedule config
+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 online <task>                     Publish a task
 cz-cli task offline <task>                    Take task offline (irreversible)

package/bin/skills/dt-creator/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: dt-creator
+description: |
+  创建 Dynamic Table 的参考资料索引。涵盖静态分区 DT 与动态分区 DT 的声明策略、
+  增量计算支持的 SQL 模式、增量刷新配置项说明、以及刷新历史的查询方式。
+---
+
+# DT Creator — 参考资料索引
+
+## references/
+
+- **dt-declaration-strategy.md** — DT 声明策略（静态分区 DT vs 动态分区 DT 的创建语法与选择）
+- **sql-limitations.md** — SQL 支持矩阵（JOIN、聚合、窗口函数、非确定性函数等的支持情况）
+- **incremental-config-reference.md** — 增量计算配置参考（刷新策略、源表特征声明、状态表管理等）
+- **refresh-history-guide.md** — 增量刷新历史查询（SHOW REFRESH HISTORY / DESC HISTORY / information_schema）

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

@@ -0,0 +1,185 @@
+# Dynamic Table 声明策略
+
+DT 有两种创建语法：静态分区 DT 和动态分区 DT（非分区 DT 可视为动态分区的特例）。两者在创建语法、刷新方式、增量行为上有本质区别。
+
+## 核心概念
+
+### 静态分区 DT（Partitioned DT with SESSION_CONFIGS args）
+
+SQL 中通过 `SESSION_CONFIGS()` 引用分区参数，每次 REFRESH 时指定具体的分区值。每个分区独立刷新，可以视为每个分区刷新单元都是一个彼此独立的 DT。
+
+```sql
+CREATE DYNAMIC TABLE order_daily (
+    id BIGINT, amount DECIMAL(12,2), ds STRING
+)
+PARTITIONED BY (ds)
+AS
+SELECT id, amount, SESSION_CONFIGS()['dt.args.ds'] AS ds
+FROM orders
+WHERE ds = SESSION_CONFIGS()['dt.args.ds'];
+
+-- 刷新时指定分区（在 Studio 任务中执行，dt.args.ds 通过任务参数传入）
+REFRESH DYNAMIC TABLE order_daily PARTITION(ds = '2025-01-01');
+```
+
+### 动态分区 DT（Non-partitioned DT / DT without args）
+
+SQL 中不引用 `SESSION_CONFIGS()`，或者虽然有分区但分区值由查询逻辑动态产生。每次 REFRESH 处理所有源表的增量数据。
+
+动态分区 DT 不允许除 REFRESH 以外的任何命令修改数据（INSERT/UPDATE/DELETE/MERGE 均不可用），数据完全由 REFRESH 驱动。
+
+因此以下 ETL 场景不适合使用动态分区 DT：
+- 需要手动修补数据（如发现某几行数据有误，需要直接 UPDATE 修正）
+- 需要按条件删除部分数据（如清理脏数据、删除过期记录）
+- 需要 MERGE INTO 做 upsert（如 CDC 场景中消费 stream 合并到目标表）
+- 需要 INSERT INTO 追加外部数据（如手动导入一批补录数据）
+- 需要按分区独立回填或重刷（动态分区 DT 只能整表全量刷新，无法单独刷某个分区）
+- 下游有其他任务需要往同一张表写入数据（DT 独占写入权）
+
+```sql
+CREATE DYNAMIC TABLE order_summary (
+    category STRING, total_amount DECIMAL(12,2)
+)
+AS
+SELECT category, SUM(amount) AS total_amount
+FROM orders
+GROUP BY category;
+
+-- 刷新时不指定分区
+REFRESH DYNAMIC TABLE order_summary;
+```
+
+## 两者的关键区别
+
+| 维度 | 静态分区 DT | 动态分区 DT |
+|------|-----------|-----------|
+| SQL 中是否有 `SESSION_CONFIGS()` | 有，用于引用分区参数 | 无 |
+| REFRESH 语法 | `REFRESH ... PARTITION(ds='xxx')` | `REFRESH ...`（无 PARTITION） |
+| 增量范围 | 只处理指定分区的增量数据 | 处理所有源表的全部增量数据 |
+| 调度方式 | 外部调度器按分区值逐个触发 | 外部调度器定时触发即可 |
+| 数据生命周期 | 按分区管理，可独立回填/删除 | 整表管理 |
+| 状态表 | 按分区独立维护 | 全局维护 |
+| 适合的数据模式 | T+1 批处理、按时间分区的 ETL | 实时流、全局聚合、无明确分区键 |
+
+## 选择决策树
+
+```
+你的数据有明确的时间/业务分区键吗？
+│
+├─ 是 → 原始 ETL 是按分区 INSERT OVERWRITE 的吗？
+│       │
+│       ├─ 是 → 使用静态分区 DT
+│       │       （保持原有的分区粒度，每个分区独立刷新）
+│       │
+│       └─ 否 → 数据量大吗？需要按分区管理生命周期吗？
+│               │
+│               ├─ 是 → 使用静态分区 DT
+│               │       （即使原来不是分区表，也建议加分区以便管理）
+│               │
+│               └─ 否 → 使用动态分区 DT
+│                       （简单场景，不需要分区管理）
+│
+└─ 否 → 使用动态分区 DT
+        （全局聚合、实时汇总等场景）
+```
+
+## 静态分区 DT 详解
+
+### 适用场景
+
+1. **T+1 批处理 ETL 迁移**
+   - 原始 SQL 是 `INSERT OVERWRITE TABLE t PARTITION(ds='${ds}')` 模式
+   - 每天/每小时按分区刷新一次
+   - 需要支持历史分区回填
+
+2. **滑动窗口计算**
+   - 如：最近 7 天的聚合、环比计算
+   - SQL 中引用 `SESSION_CONFIGS()['dt.args.ds']` 和 `sub_days(...)` 做窗口范围
+
+3. **需要按分区管理数据生命周期**
+   - 通过 `data_lifecycle` 自动清理过期分区
+   - 可以单独回填某个分区而不影响其他分区
+
+4. **自引用 DT（日环比、SCD）**
+   - 当前分区依赖上一个分区的结果
+   - 必须用静态分区，因为需要明确指定"当前分区"和"上一分区"
+
+### 刷新方式
+
+> ⚠️ **重要**：静态分区 DT 的 `dt.args.*` 参数**仅在 Studio 任务中可用**，不能在交互式 SQL 中使用 `SET dt.args.xxx`。
+> 必须通过 Studio 创建调度任务，在任务参数中配置 `dt.args.ds` 等值。
+
+```sql
+-- 在 Studio 任务中，参数通过任务配置传入，REFRESH 语句指定分区值：
+REFRESH DYNAMIC TABLE my_dt PARTITION(ds = '2025-01-15');
+
+-- 多级分区
+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 中可用
+
+## 动态分区 DT 详解
+
+### 适用场景
+
+1. **实时流数据聚合**
+   - 源表持续写入，DT 定时刷新
+   - 不需要按分区管理，每次处理所有新增数据
+
+2. **全局汇总表**
+   - 如：全局 TopN、全局计数、全局去重
+   - 没有明确的分区键
+
+3. **简单的 JOIN + 过滤**
+   - 不涉及分区参数的简单转换
+   - 如：事实表 JOIN 维度表，输出宽表
+
+4. **多源表合并（UNION ALL）**
+   - 多个源表的数据合并到一张表
+   - 不需要按分区管理
+
+### 刷新方式
+
+```sql
+-- 直接刷新，处理所有源表的增量
+REFRESH DYNAMIC TABLE my_dt;
+```
+
+### 注意事项
+
+- 每次刷新处理所有源表的全部增量，如果源表变更量大，刷新可能较慢
+- 状态表全局维护，随着数据量增长可能膨胀
+- 不支持按分区回填，只能全量刷新整表
+- 适合变更量占比小的场景（< 5%）
+
+## 分区粒度选择
+
+当选择静态分区 DT 时，还需要决定分区粒度：
+
+| 数据模式 | 推荐分区粒度 | 说明 |
+|---------|------------|------|
+| 严格有序的时间序列（如日志） | 分钟级 (`dt_min`) | 数据量大、写入频繁 |
+| 大致有序、少量迟到数据 | 小时级 (`dt_hour`) | 平衡粒度和管理复杂度 |
+| T+1 批量导入 | 天级 (`ds`) | 最常见的 ETL 场景 |
+| 按业务周期 | 周/月级 | 报表类场景 |
+| 多级分区 | 天 + 小时 (`ds`, `hour`) | 需要更细粒度的生命周期管理 |
+
+选择原则：
+- 粒度越细，每次刷新处理的数据量越小，增量效率越高
+- 粒度越细，分区数越多，管理和调度越复杂
+- 粒度应与数据写入频率匹配：如果数据每小时写入一次，分区粒度不应细于小时
+
+## 从原始 ETL 判断分区策略
+
+| 原始 ETL 模式 | 推荐 DT 分区策略 |
+|--------------|----------------|
+| `INSERT OVERWRITE TABLE t PARTITION(ds='${ds}')` | 静态分区 DT，天级 |
+| `INSERT OVERWRITE TABLE t PARTITION(ds='${ds}', hour='${hour}')` | 静态分区 DT，天+小时级 |
+| `INSERT OVERWRITE TABLE t PARTITION(ds)` （动态分区写入） | 动态分区 DT 或静态分区 DT（取决于是否需要按分区管理） |
+| `INSERT INTO TABLE t SELECT ...` （无分区） | 动态分区 DT |
+| `INSERT OVERWRITE TABLE t SELECT ...` （全表覆盖） | 动态分区 DT |

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

@@ -0,0 +1,429 @@
+# Dynamic Table 增量计算配置参考
+
+本文档列出 Dynamic Table / Materialized View 增量刷新中可供用户调整的配置项。所有配置均通过 `SET` 语句在 Session 级别生效。
+
+---
+
+## 刷新策略
+
+控制增量刷新与全量刷新之间的切换行为。
+
+### `cz.optimizer.incremental.force.full.refresh`
+
+- 类型：bool，默认值：`false`
+
+强制当次刷新使用全量模式，跳过增量逻辑，对所有源表做全量扫描重算。
+
+**适用场景：**
+- 增量刷新结果出现数据异常（如数据缺失、重复），需要做一次全量修复
+- 维度表发生了重要变更（如修正了映射关系），需要让所有历史数据重新 JOIN 到最新维度
+- DT 的状态表被误删或损坏，增量刷新报错，需要从头重算
+
+**优势：** 全量重算可以保证结果与直接执行 SQL 完全一致，是最可靠的数据修复手段。
+
+**风险：** 全量刷新需要扫描所有源表的全部数据，计算量和耗时远大于增量刷新。对于大数据量的 DT，一次全量刷新可能需要数分钟甚至数小时。
+
+**注意：** 这是一个 Session 级别的一次性开关。刷新完成后必须手动设回 `false`，否则后续每次 REFRESH 都会走全量，浪费计算资源。
+
+```sql
+SET cz.optimizer.incremental.force.full.refresh = true;
+REFRESH DYNAMIC TABLE my_dt;
+SET cz.optimizer.incremental.force.full.refresh = false;
+```
+
+### `cz.optimizer.incremental.try.incremental.refresh.enabled`
+
+- 类型：bool，默认值：`false`
+
+优先尝试增量刷新；若增量计划生成失败（如 SQL 中包含不支持增量的算子），自动回退至全量刷新，而非直接报错。
+
+**适用场景：**
+- 刚将一个复杂 SQL 迁移为 DT，不确定所有算子是否都支持增量计算，希望"能增量就增量，不行就全量"
+- 生产环境中希望保证刷新任务不因增量计划生成失败而中断
+
+**优势：** 提高了 DT 刷新的容错性。即使 SQL 中包含增量引擎暂不支持的模式，刷新任务也不会失败，而是自动降级为全量刷新。
+
+**风险：** 如果增量计划生成持续失败，每次刷新都会静默回退为全量，用户可能不知道自己的 DT 一直在走全量，浪费计算资源。建议配合日志监控，关注是否频繁回退。
+
+```sql
+-- 在 REFRESH 语句前执行
+SET cz.optimizer.incremental.try.incremental.refresh.enabled = true;
+REFRESH DYNAMIC TABLE my_dt;
+```
+
+---
+
+## 源表数据特征声明
+
+通过声明源表的数据特征，引导增量引擎选择更高效的计算策略。
+
+### `cz.optimizer.incremental.dimension.tables`
+
+- 类型：string，默认值：`""`
+
+将指定的源表标记为维度表。标记后，增量引擎不再读取该表的变更数据，每次刷新时直接读取其最新全量数据。只有非维度表（事实表）的变更才会驱动增量计算。
+
+格式为逗号或冒号分隔的表名，支持完整路径 `instanceId.ws.schema.table` 或简短名称。
+
+**这是一个用正确性换性能的权衡。** 标记为维度表后，该表的任何数据变更（INSERT/UPDATE/DELETE）都不会触发增量计算，已输出的结果行不会因维度表变更而更新。作为回报，增量引擎可以获得显著的性能提升：
+- 跳过维度表的变更数据扫描（不需要读取变更日志）
+- 减少状态表数量（JOIN 一侧全是维度表时不需要创建状态表）
+- 简化增量计划（只需要用事实表的变更数据 JOIN 维度表的全量数据，不需要反向计算）
+- 减少增量数据的去重合并操作
+
+**适用场景：**
+- 事实表 LEFT JOIN 码表/字典表（如地区码表、产品分类表），码表极少变更，不需要跟踪其变更
+- 大事实表 JOIN 小维度表，核心诉求是事实表的增量性能，维度表偶尔变更后可以接受短暂不一致
+- 外部表（如 MySQL 外表）不支持 time travel，无法提供变更数据，标记为维度表后可正常增量计算
+- T+1 维度表 + 实时事实表：维度表每天批量更新一次，在两次更新之间可视为不变
+
+**正确性影响：** 维度表变更后，已输出的结果不会自动更新。例如维度表中某行的 `name` 从 `'A'` 改为 `'B'`，已经 JOIN 过该行的历史结果仍然显示 `'A'`。只有新的事实表增量才会 JOIN 到最新的 `'B'`。如果需要订正历史数据，必须手动执行一次全量刷新。
+
+详细的正确性影响分析和各 JOIN 类型下的行为，请参阅《维度表 JOIN 场景详解》文档（dimension-table-join-guide）。
+
+```sql
+-- 推荐：通过 DT 表属性声明（跟随 DT 定义，不需要每次 REFRESH 前设置）
+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;
+
+-- 维度表发生重要变更后，手动全量刷新订正数据
+SET cz.optimizer.incremental.force.full.refresh = true;
+REFRESH DYNAMIC TABLE my_dt;
+SET cz.optimizer.incremental.force.full.refresh = false;
+```
+
+### `cz.optimizer.incremental.append.only.tables`
+
+- 类型：string，默认值：`""`
+
+将指定的源表标记为"预期仅追加"。这是一个优化 hint，告诉优化器该表预期只有 INSERT 操作，优化器据此选择更高效的增量计划（如提前创建针对仅追加场景优化的中间状态）。
+
+**这不影响正确性。** 即使标记为 append-only 的表后续实际发生了 UPDATE 或 DELETE，增量引擎仍然会正常捕获并计算这些变更，结果不会出错。区别在于：当实际发生了 UPDATE/DELETE 时，优化器之前基于"仅追加"假设选择的计划可能不是最优的，性能上可能不如未标记时的计划。
+
+**适用场景：**
+- Kafka 消费落地表、日志表、埋点表等绝大多数时候只有 INSERT 的数据源
+- 源表偶尔可能有少量 UPDATE/DELETE（如数据修正），但主要写入模式是 INSERT
+
+**优势：** 优化器基于"仅追加"假设可以选择更高效的增量计划，减少不必要的中间状态维护开销。对于聚合场景，可以直接累加而不需要维护完整的中间状态。性能提升显著，尤其是在包含 JOIN 和聚合的复杂 SQL 中。
+
+**风险：** 如果该表实际频繁发生 UPDATE/DELETE，优化器基于"仅追加"假设选择的计划可能不是最优的，增量刷新性能可能不如不标记时好。但结果的正确性不受影响。
+
+```sql
+-- 推荐：通过表属性声明（永久生效，不需要每次刷新前设置）
+ALTER TABLE event_log SET PROPERTIES('INCR_APPEND_ONLY_TABLE' = 'true');
+
+-- 或通过 Session 配置（在 REFRESH 语句前执行）
+SET cz.optimizer.incremental.append.only.tables = 'event_log,click_stream';
+REFRESH DYNAMIC TABLE my_dt;
+```
+
+---
+
+## 全量刷新回退策略
+
+当源表变更量过大或特定表发生变更时，自动从增量切换为全量刷新。
+
+### `cz.optimizer.incremental.full.refresh.if.these.tables.change`
+
+- 类型：string，默认值：`""`
+
+逗号分隔的表名列表。当列表中的任意表在本次刷新周期内有数据变更时，自动触发全量刷新。
+
+**适用场景：**
+- DT 的 SQL 中 JOIN 了一张关键维度表（如价格表、汇率表），该表一旦变更，所有历史数据都需要按新值重算
+- 与 `cz.optimizer.incremental.dimension.tables` 的区别：`dimension.tables` 是忽略变更继续增量；本配置是检测到变更后触发全量重算
+
+**优势：** 保证了关键表变更后结果的正确性——一旦检测到变更，自动全量重算，不需要人工干预。
+
+**风险：** 如果指定的表变更频繁（如每小时都有更新），每次刷新都会触发全量，完全失去增量的性能优势。应仅用于变更频率极低但变更影响面大的表。
+
+```sql
+-- 在 REFRESH 语句前执行
+SET cz.optimizer.incremental.full.refresh.if.these.tables.change = 'dim_pricing,dim_exchange_rate';
+REFRESH DYNAMIC TABLE my_dt;
+```
+
+### `cz.optimizer.incremental.full.refresh.if.source.table.changes.significantly`
+
+- 类型：bool，默认值：`false`
+
+启用后，当源表的增量数据量占全量数据量的比例超过阈值时，自动切换为全量刷新。
+
+**适用场景：**
+- 源表偶尔会发生大批量数据导入（如历史数据回灌），此时增量数据量接近甚至超过全量，增量刷新反而比全量更慢
+- 希望系统自动判断"增量划不划算"，不划算时自动切全量
+
+**优势：** 自动在增量和全量之间选择最优策略，避免增量数据量过大时增量刷新反而更慢的问题（增量需要额外的变更数据计算、去重合并、状态表读写等开销）。
+
+**风险：** 阈值判断基于统计信息，可能不完全准确。如果统计信息不精确，可能出现不必要的全量刷新或该切全量时没切的情况。
+
+需配合 `cz.optimizer.incremental.threshold.of.source.table.change.for.full.refresh` 设置阈值。
+
+### `cz.optimizer.incremental.threshold.of.source.table.change.for.full.refresh`
+
+- 类型：double，默认值：`1.0`
+
+触发全量刷新的变更比例阈值。当增量数据量 / 全量数据量超过此值时触发全量刷新。
+
+- `1.0`：增量数据量超过全量时才触发（非常保守）
+- `0.5`：增量超过全量的一半就触发
+- `0.1`：增量超过全量的 10% 就触发（激进，适用于增量计算开销较大的复杂 SQL）
+
+```sql
+-- 在 REFRESH 语句前执行
+SET cz.optimizer.incremental.full.refresh.if.source.table.changes.significantly = true;
+SET cz.optimizer.incremental.threshold.of.source.table.change.for.full.refresh = 0.5;
+REFRESH DYNAMIC TABLE my_dt;
+```
+
+---
+
+## 状态表管理
+
+状态表是增量引擎在刷新过程中自动创建的内部表，用于存储中间计算结果（如聚合的中间状态、JOIN 的历史数据等），以加速后续的增量刷新。
+
+### `cz.optimizer.incremental.enable.state.table`
+
+- 类型：bool，默认值：`true`
+
+状态表总开关。系统默认限制每个 DT 最多创建 5 个状态表，以防止极端场景下状态表过多导致磁盘存储占用过大。当 DT 的 SQL 中包含的有状态计算算子（如聚合、JOIN、窗口函数等）超过 5 个时，若用户未显式开启此配置，系统将**放弃创建所有状态表**，增量刷新退化为每次从源表重新计算中间结果。
+
+如果用户希望为这些算子创建状态表以获得更优的增量刷新性能，需要显式设置此配置为 `true`。**显式开启此配置意味着用户理解并接受以额外的磁盘存储为代价换取更优的增量刷新性能。**
+
+设为 `false` 后，增量引擎不创建也不复用任何状态表，所有中间结果每次都从源表重新计算。
+
+**适用场景：**
+
+设为 `true`（显式开启）：
+- DT 的 SQL 包含大量有状态算子（如多层 JOIN + 聚合 + 窗口函数），默认的 5 个状态表限制不足以覆盖所有算子，希望创建更多状态表以获得最优增量性能
+- 用户已评估存储开销，确认可以接受额外的状态表存储占用
+
+设为 `false`（关闭）：
+- 排查状态表相关的问题（如怀疑状态表数据不一致导致增量结果异常）
+- 源表数据量较小，全量重算的代价可以接受，不需要状态表加速
+- 需要严格控制存储开销，不希望系统自动创建额外的表
+
+**优势：** 显式开启后，系统可以为所有有状态算子创建状态表，最大化增量刷新的性能收益。关闭后则消除了状态表带来的所有存储开销。
+
+**风险：** 显式开启后，状态表数量可能超过默认的 5 个限制，带来额外的磁盘存储占用。关闭后，包含聚合或多表 JOIN 的复杂 DT 每次增量刷新都需要读取源表的全量数据来重算中间结果，性能可能显著下降。
+
+```sql
+-- 显式开启：允许系统为所有有状态算子创建状态表（在 REFRESH 语句前执行）
+SET cz.optimizer.incremental.enable.state.table = true;
+REFRESH DYNAMIC TABLE my_dt;
+
+-- 关闭：不创建也不复用任何状态表
+SET cz.optimizer.incremental.enable.state.table = false;
+REFRESH DYNAMIC TABLE my_dt;
+```
+
+### `cz.optimizer.incremental.state.table.lifecycle`
+
+- 类型：string，默认值：`"3"`
+
+状态表数据保留天数。超过此天数的历史版本数据将被自动清理。
+
+**适用场景：**
+- DT 的刷新间隔较长（如每周一次），默认 3 天会导致状态表在两次刷新之间被清理，下次刷新时无法复用状态表，退化为全量刷新。此时需要增大此值
+- 希望减少状态表的存储占用，可以适当缩短保留期（但不能短于刷新间隔）
+- 状态表内容很大，希望及时回收存储空间，可以显式缩短生命周期（例如设为 1 天），让过期版本尽快被清理
+
+**优势：** 增大保留期可以确保状态表在刷新间隔内不被清理，保证增量刷新能正常复用状态。
+
+**风险：** 保留期越长，状态表占用的存储空间越大。每个版本的状态表都会保留到过期，如果刷新频率高（如每小时一次）且保留期长（如 30 天），状态表的存储量会非常可观。
+
+```sql
+-- 在 REFRESH 语句前执行
+SET cz.optimizer.incremental.state.table.lifecycle = '10';
+REFRESH DYNAMIC TABLE my_dt;
+```
+
+### `cz.optimizer.incremental.rebuild.rule.based.state.table`
+
+- 类型：bool，默认值：`false`
+
+设为 `true` 后，下次刷新时重建所有状态表。重建过程会清除旧的状态表数据，基于当前源表数据重新生成。
+
+**适用场景：**
+- 状态表数据损坏（如因系统异常导致状态表写入不完整），增量刷新结果异常
+- DT 的 SQL 发生了变更（如修改了聚合逻辑），旧的状态表 Schema 与新 SQL 不匹配
+- 增量刷新持续报错，怀疑是状态表问题，希望从头重建
+
+**优势：** 重建后状态表数据与当前源表完全一致，消除了历史累积的数据不一致问题。
+
+**风险：** 重建过程中该次刷新会走全量，耗时较长。重建完成前，增量刷新不可用。
+
+**注意：** 这是一个一次性开关。重建完成后必须设回 `false`，否则每次刷新都会重建状态表，完全失去增量的意义。
+
+```sql
+SET cz.optimizer.incremental.rebuild.rule.based.state.table = true;
+REFRESH DYNAMIC TABLE my_dt;
+SET cz.optimizer.incremental.rebuild.rule.based.state.table = false;
+```
+
+### `cz.optimizer.incremental.state.table.specified.schema`
+
+- 类型：string，默认值：`""`
+
+指定状态表存放的 Schema。默认情况下，状态表与 DT 目标表在同一个 Schema 中。
+
+**适用场景：**
+- 希望将状态表与业务表隔离，便于统一管理和监控状态表的存储占用
+- 多个 DT 共享同一个 Schema 存放状态表，方便批量清理
+
+**优势：** 业务表和状态表分离后，可以独立设置 Schema 级别的权限、配额和生命周期策略，避免状态表干扰业务表的管理。
+
+**风险：** 跨 Schema 访问可能带来轻微的元数据查询开销。此外，如果指定的 Schema 不存在或权限不足，状态表创建会失败。
+
+```sql
+SET cz.optimizer.incremental.state.table.specified.schema = 'incr_state';
+```
+
+---
+
+## DT 定义变更
+
+控制 `CREATE OR REPLACE DYNAMIC TABLE` 时的兼容性检查行为。
+
+### `cz.sql.mv.check.before.replacing.sql`
+
+- 类型：bool，默认值：`true`
+
+控制 `CREATE OR REPLACE DYNAMIC TABLE` 时是否对新旧 SQL 进行兼容性检查。
+
+**开启检查（`true`，默认）：** 系统会比较新旧 SQL 的列结构，判断是否兼容。如果判定为兼容（如仅新增列），系统会保留已有的增量状态，后续继续增量刷新。但兼容性判断并非完美——对于被判定为"兼容"的变更，新增列在历史数据中将填充 NULL，且已有的历史行不会按新 SQL 重新计算，可能导致新旧数据不一致。
+
+**关闭检查（`false`）：** 系统跳过兼容性检查，直接认定新旧 SQL 不兼容，重置增量状态（清除状态表和历史版本信息）。替换后的下一次刷新将执行全量计算，确保所有数据按新 SQL 重新生成。
+
+**适用场景：**
+
+设为 `false`（关闭检查）：
+1. **`CREATE OR REPLACE` 卡住或报错**：某些情况下兼容性检查本身可能耗时较长或因元数据问题报错，导致 `CREATE OR REPLACE` 无法完成。关闭检查可跳过该步骤，让替换操作顺利完成。代价是下次刷新会变成全量。
+2. **SQL 发生了实质性变更，希望从头重算**：如修改了 JOIN 逻辑、聚合方式等核心计算逻辑，需要全量重算以保证数据正确性。关闭检查可确保系统不会错误地判定为"兼容"而保留旧的增量状态。
+
+保持 `true`（开启检查，默认）：
+1. **仅新增列等简单变更**：希望系统自动判断兼容性，兼容时保留增量状态避免全量刷新。适用于对历史数据中新增列为 NULL 可以接受的场景。
+2. **日常迭代中频繁调整 DT 定义**：依赖系统自动判断，减少不必要的全量刷新。
+
+**开启检查的风险：** 兼容性判断可能将实际不完全兼容的变更判定为"兼容"，导致新增列在历史数据中为 NULL，或已有历史行永远不会按新 SQL 更新。
+
+**关闭检查的风险：** 下一次刷新将执行全量计算，对于大数据量的 DT 可能耗时较长。
+
+```sql
+-- 关闭检查，确保替换后全量重算
+SET cz.sql.mv.check.before.replacing.sql = false;
+CREATE OR REPLACE DYNAMIC TABLE my_dt AS SELECT ...;
+SET cz.sql.mv.check.before.replacing.sql = true;
+-- 注意：下次 REFRESH 将执行全量刷新
+```
+
+---
+
+## 历史分区回填（Backfill）
+
+### `cz.optimizer.incremental.backfill.enabled`
+
+- 类型：bool，默认值：`false`
+
+启用回填模式。用于对 DT 的历史分区进行数据回填或修正。开启后，系统会自动执行以下操作：
+- 强制当次刷新使用全量模式（等同于开启 `force.full.refresh`）
+- 跳过增量数据的读取，避免读取大量历史变更日志
+- 对于分区 DT，禁用状态表的创建和匹配（因为回填的分区不需要增量状态）
+- 允许对 DT 执行 DML 操作（如 `INSERT OVERWRITE`）
+
+**适用场景：**
+
+设为 `true`（开启回填）：
+1. **历史分区数据修正**：某个历史分区的数据出现问题，需要用正确的源数据重新生成该分区。
+2. **新建 DT 后补充历史数据**：DT 创建后，需要为已有的历史分区逐个生成数据。
+3. **源表数据回灌后重算**：源表进行了历史数据回灌，需要对受影响的分区重新计算。
+
+**注意：**
+- 回填模式是一次性操作，回填完成后应设回 `false`，否则后续每次刷新都会走全量。
+- 回填模式下不会创建或更新状态表，因此不会影响后续正常增量刷新的状态。
+- 回填通常配合 `INSERT OVERWRITE` 使用，覆盖目标分区的已有数据。
+
+```sql
+-- 在 Studio 任务中，参数通过任务配置传入：
+SET cz.optimizer.incremental.backfill.enabled = true;
+REFRESH DYNAMIC TABLE my_dt PARTITION(ds = '2025-01-01');
+SET cz.optimizer.incremental.backfill.enabled = false;
+
+-- 也可以通过 INSERT OVERWRITE 直接回填
+SET cz.optimizer.incremental.backfill.enabled = true;
+INSERT OVERWRITE TABLE my_dt
+SELECT id, amount, '2025-01-01' AS ds
+FROM source_table
+WHERE ds = '2025-01-01';
+SET cz.optimizer.incremental.backfill.enabled = false;
+```
+
+---
+
+## 全量刷新时分区表的写入行为
+
+### `cz.optimizer.incremental.full.refresh.overwrite.partitioned.table`
+
+- 类型：bool，默认值：`true`
+
+控制分区 DT 在全量刷新时的写入模式。
+
+**背景：** 对于分区表，全量刷新（`force.full.refresh = true` 或系统自动触发的全量刷新）默认采用覆盖写入（OVERWRITE）模式——这是大数据领域的通用行为，即全量重算的结果会覆盖目标表的所有分区。但在某些场景下，DT 的 SQL 只计算部分分区的数据（例如只查询最近 7 天），全量刷新的结果也只包含这部分分区。此时如果使用覆盖写入，会导致历史分区（如 7 天前的数据）被清空。
+
+**开启覆盖（`true`，默认）：** 全量刷新时，目标表的所有分区都会被覆盖。刷新结果中不包含的分区将被清空。这适用于 DT 的 SQL 覆盖了目标表的全部数据范围的场景。
+
+**关闭覆盖（`false`）：** 全量刷新时，只写入本次计算产生的分区数据，不影响目标表中已有的其他分区。历史分区的数据保持不变。
+
+**适用场景：**
+
+设为 `false`（关闭覆盖）：
+1. **DT 的 SQL 只计算部分分区**：例如 SQL 中有 `WHERE ds >= '2025-01-01'` 的过滤条件，只计算最近一段时间的数据。全量刷新时不希望清空更早的历史分区。
+2. **按分区逐步积累数据的 DT**：每次刷新只产生当前分区的数据，历史分区由之前的刷新产生。全量刷新时只需要重算当前分区，不应影响历史分区。
+3. **滑动窗口场景**：DT 的 SQL 基于分区参数计算一个时间窗口内的数据，全量刷新时只重算窗口内的分区。
+
+保持 `true`（开启覆盖，默认）：
+1. **DT 的 SQL 覆盖全部数据**：SQL 没有分区过滤条件，全量刷新的结果包含目标表的所有数据。
+2. **需要全量重建目标表**：希望全量刷新后目标表的数据与直接执行 SQL 的结果完全一致，不保留任何历史残留。
+
+**风险：**
+- 开启覆盖时，如果 DT 的 SQL 只计算部分分区，全量刷新会清空未被计算到的历史分区，导致数据丢失。
+- 关闭覆盖时，如果 DT 的 SQL 覆盖全部数据，全量刷新后目标表中可能残留旧数据（因为旧分区没有被清空），导致数据不一致。
+
+```sql
+-- 关闭覆盖：全量刷新时保留历史分区（在 REFRESH 语句前执行）
+SET cz.optimizer.incremental.full.refresh.overwrite.partitioned.table = false;
+SET cz.optimizer.incremental.force.full.refresh = true;
+REFRESH DYNAMIC TABLE my_dt;
+SET cz.optimizer.incremental.force.full.refresh = false;
+```
+
+---
+
+## 配置速查表
+
+按使用场景快速定位所需配置：
+
+| 场景 | 配置项 | 推荐值 |
+|------|--------|--------|
+| 数据异常，需要全量重算修复 | `cz.optimizer.incremental.force.full.refresh` | `true`（一次性） |
+| 不确定 SQL 是否支持增量 | `cz.optimizer.incremental.try.incremental.refresh.enabled` | `true` |
+| 小表 JOIN 不需要跟踪变更 | `cz.optimizer.incremental.dimension.tables` 或表属性 `mv_const_tables` | 表名列表 |
+| 源表主要是 INSERT，希望优化增量性能 | `cz.optimizer.incremental.append.only.tables` 或表属性 `INCR_APPEND_ONLY_TABLE` | 表名列表 / `true` |
+| 关键表变更时必须全量重算 | `cz.optimizer.incremental.full.refresh.if.these.tables.change` | 表名列表 |
+| 增量数据量过大时自动切全量 | `cz.optimizer.incremental.full.refresh.if.source.table.changes.significantly` + `threshold` | `true` + `0.5` |
+| SQL 算子多，需要更多状态表加速 | `cz.optimizer.incremental.enable.state.table` | `true`（显式开启） |
+| 不需要状态表，或排查状态表问题 | `cz.optimizer.incremental.enable.state.table` | `false` |
+| 状态表数据损坏，需要重建 | `cz.optimizer.incremental.rebuild.rule.based.state.table` | `true`（一次性） |
+| 刷新间隔长，状态表被提前清理 | `cz.optimizer.incremental.state.table.lifecycle` | 增大至覆盖刷新间隔 |
+| 状态表与业务表隔离管理 | `cz.optimizer.incremental.state.table.specified.schema` | Schema 名 |
+| `CREATE OR REPLACE` 卡住或 SQL 实质性变更 | `cz.sql.mv.check.before.replacing.sql` | `false`（一次性） |
+| 历史分区数据回填或修正 | `cz.optimizer.incremental.backfill.enabled` | `true`（一次性） |
+| 全量刷新时保留历史分区数据 | `cz.optimizer.incremental.full.refresh.overwrite.partitioned.table` | `false` |

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

@@ -0,0 +1,268 @@
+# Dynamic Table 增量刷新历史查询指南
+
+查看 DT/MV 的增量刷新历史有三种方式，适用于不同场景。
+
+---
+
+## 方式一：SHOW DYNAMIC TABLE REFRESH HISTORY
+
+查看 DT 的刷新作业级别信息，包括每次刷新的状态、耗时、触发方式、刷新模式等。
+
+### 语法
+
+```sql
+-- 查看指定 DT 的刷新历史（使用 WHERE name = 过滤）
+SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt';
+
+-- 限制返回行数
+SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' LIMIT 10;
+
+-- 组合 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>'` 语法。
+
+### 输出列
+
+| 列名 | 类型 | 说明 |
+|------|------|------|
+| workspace_name | STRING | 所属 Workspace |
+| schema_name | STRING | 所属 Schema |
+| name | STRING | DT/MV 名称 |
+| virtual_cluster | STRING | 执行刷新的虚拟集群 |
+| start_time | TIMESTAMP | 刷新开始时间 |
+| end_time | TIMESTAMP | 刷新结束时间（运行中为 NULL） |
+| duration | INTERVAL | 刷新耗时（运行中显示已经过的时间） |
+| state | STRING | 刷新状态（SUCCEED / FAILED / RUNNING 等） |
+| refresh_trigger | STRING | 触发方式：`SYSTEM_SCHEDULED`（系统调度自动触发）或 `MANUAL`（用户手动 REFRESH） |
+| refresh_mode | STRING | 刷新模式，见下方详细说明 |
+| error_message | STRING | 失败时的错误信息（成功时为 NULL） |
+| source_tables | ARRAY<MAP<STRING,STRING>> | 源表列表，每个元素是一个 MAP，包含 `workspace`、`schema`、`table_name` 三个 key |
+| stats | MAP<STRING,STRING> | 刷新统计，包含 `rows_inserted`（插入行数）和 `rows_deleted`（删除行数） |
+| job_id | STRING | 对应的 Job ID，可用于关联 `information_schema.job_history` 查更多详情 |
+
+### refresh_mode 详解
+
+`refresh_mode` 是判断增量计算是否生效的关键字段：
+
+| 值 | 含义 | 说明 |
+|----|------|------|
+| `INCREMENTAL` | 增量刷新 | 增量引擎成功生成了增量计划，只处理了源表的变更数据 |
+| `FULL` | 全量刷新 | 回退到全量重算。可能原因：首次刷新、维度表变更、增量计划生成失败、用户强制全量等 |
+| `NO_DATA` | 无数据变更 | 源表在上次刷新后没有新的数据变更，本次刷新跳过计算 |
+
+### source_tables 详解
+
+`source_tables` 列返回该次刷新涉及的所有输入表信息，每个元素是一个 MAP：
+
+```
+[
+  {"workspace": "my_ws", "schema": "public", "table_name": "orders"},
+  {"workspace": "my_ws", "schema": "public", "table_name": "dim_product"}
+]
+```
+
+### stats 详解
+
+`stats` 列返回该次刷新对目标表的写入统计：
+
+```
+{"rows_inserted": "1000", "rows_deleted": "50"}
+```
+
+- `rows_inserted`：本次刷新向目标表插入的行数
+- `rows_deleted`：本次刷新从目标表删除的行数（增量模式下，更新操作会产生 delete + insert）
+
+### 典型用法
+
+```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';
+
+-- 查看是否回退到了全量刷新（排查增量是否生效）
+SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' AND refresh_mode = 'FULL';
+
+-- 查看无数据变更的刷新（源表没有新数据时会出现）
+SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' AND refresh_mode = 'NO_DATA';
+
+-- 查看系统自动调度的刷新
+SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' AND refresh_trigger = 'SYSTEM_SCHEDULED';
+```
+
+---
+
+## 方式二：DESC HISTORY
+
+查看表的版本级别历史，包括每个版本的行数、字节数、操作类型等。适用于了解数据变更粒度。
+
+### 语法
+
+```sql
+-- 查看 DT 的版本历史
+DESC HISTORY my_dt;
+
+-- 查看源表的版本历史
+DESC HISTORY source_table;
+
+-- 支持 WHERE 过滤
+DESC HISTORY my_dt WHERE version > 10;
+
+-- 支持 LIMIT
+DESC HISTORY my_dt LIMIT 20;
+```
+
+### 输出列
+
+对于普通表（DESC_TABLE_HISTORY）：
+
+| 列名 | 类型 | 说明 |
+|------|------|------|
+| sequence | BIGINT | 序列号 |
+| version | BIGINT | 版本号 |
+| time | TIMESTAMP | 版本创建时间 |
+| total_rows | BIGINT | 该版本的总行数 |
+| total_bytes | BIGINT | 该版本的总字节数 |
+| user | STRING | 操作用户 |
+| operation | STRING | 操作类型（INSERT / COMPACTION / REFRESH 等） |
+| job_id | STRING | 对应的 Job ID |
+
+对于 DT/MV（DESC_MV_HISTORY），额外包含：
+
+| 列名 | 类型 | 说明 |
+|------|------|------|
+| source_tables | ARRAY<MAP<STRING,STRING>> | 源表及其对应的版本信息 |
+
+DESC HISTORY 对 DT/MV 的 `source_tables` 比 SHOW REFRESH HISTORY 更详细，包含每个源表在该版本对应的快照信息：
+
+```
+[
+  {"table_name": "orders", "workspace": "my_ws", "schema": "public", "version": "123", "sequence": "5", "commit_time": "2025-01-15 10:30:00"},
+  {"table_name": "dim_product", "workspace": "my_ws", "schema": "public", "version": "456", "sequence": "2", "commit_time": "2025-01-15 08:00:00"}
+]
+```
+
+- `version`：源表的 snapshot_id
+- `sequence`：源表的 sequence 号
+- `commit_time`：源表该版本的提交时间
+
+这些信息可以用来追溯某次刷新读取了源表的哪个版本数据。
+
+### 典型用法
+
+```sql
+-- 查看 DT 最近的版本变化，确认 compaction 是否正常执行
+DESC HISTORY my_dt LIMIT 10;
+
+-- 查看源表的版本历史，判断数据写入频率
+DESC HISTORY source_table LIMIT 20;
+
+-- 查看 DT 的 compaction 记录
+DESC HISTORY my_dt WHERE operation = 'COMPACTION';
+```
+
+---
+
+## 方式三：information_schema.materialized_view_refresh_history
+
+从 information_schema 查询刷新历史，适合跨表批量分析、与其他系统集成、或做长期趋势监控。数据按天分区（pt_date），保留天数由系统配置决定。
+
+### 语法
+
+```sql
+-- 查看指定 DT 的刷新历史
+SELECT *
+FROM information_schema.materialized_view_refresh_history
+WHERE materialized_view_name = 'my_dt'
+ORDER BY start_time DESC
+LIMIT 10;
+
+-- 查看某天所有 DT 的刷新情况
+SELECT materialized_view_name, status, start_time, end_time, error_message
+FROM information_schema.materialized_view_refresh_history
+WHERE pt_date = '2025-01-15'
+ORDER BY start_time DESC;
+
+-- 查看失败的刷新
+SELECT materialized_view_name, error_code, error_message, start_time
+FROM information_schema.materialized_view_refresh_history
+WHERE status = 'FAILED' AND pt_date >= '2025-01-01'
+ORDER BY start_time DESC;
+```
+
+### 输出列
+
+| 列名 | 类型 | 说明 |
+|------|------|------|
+| workspace_name | STRING | 所属 Workspace |
+| schema_name | STRING | 所属 Schema |
+| materialized_view_name | STRING | DT/MV 名称 |
+| cru | DOUBLE | 消耗的计算资源单位 |
+| virtual_cluster_name | STRING | 执行刷新的虚拟集群 |
+| status | STRING | 刷新状态 |
+| scheduled_start_time | TIMESTAMP | 计划开始时间 |
+| start_time | TIMESTAMP | 实际开始时间 |
+| end_time | TIMESTAMP | 结束时间 |
+| error_code | STRING | 错误码 |
+| error_message | STRING | 错误信息 |
+| pt_date | STRING | 分区日期 |
+
+### 典型用法
+
+```sql
+-- 统计某个 DT 最近 7 天的刷新成功率
+SELECT
+    pt_date,
+    COUNT(*) AS total,
+    SUM(CASE WHEN status = 'SUCCEED' THEN 1 ELSE 0 END) AS success,
+    SUM(CASE WHEN status = 'FAILED' THEN 1 ELSE 0 END) AS failed
+FROM information_schema.materialized_view_refresh_history
+WHERE materialized_view_name = 'my_dt'
+  AND pt_date >= DATE_FORMAT(DATEADD(DAY, -7, CURRENT_DATE()), '%Y-%m-%d')
+GROUP BY pt_date
+ORDER BY pt_date;
+
+-- 查看消耗 CRU 最多的刷新
+SELECT materialized_view_name, cru, start_time, end_time
+FROM information_schema.materialized_view_refresh_history
+WHERE pt_date >= '2025-01-01'
+ORDER BY cru DESC
+LIMIT 10;
+```
+
+### 与 information_schema.job_history 的区别
+
+`information_schema.job_history` 记录所有类型的 Job（SQL 查询、DML、DDL 等），而 `materialized_view_refresh_history` 专门记录 DT/MV 的刷新历史，字段更有针对性。
+
+如果需要查看刷新 Job 的完整信息（如 job_text、input_bytes 等），可以通过 job_id 关联：
+
+```sql
+-- 通过 SHOW DYNAMIC TABLE REFRESH HISTORY 获取 job_id，再到 job_history 查详情
+SELECT *
+FROM information_schema.job_history
+WHERE job_id = '<从 SHOW REFRESH HISTORY 获取的 job_id>'
+  AND pt_date = '2025-01-15';
+```
+
+---
+
+## 三种方式对比
+
+| 特性 | SHOW REFRESH HISTORY | DESC HISTORY | information_schema |
+|------|---------------------|--------------|-------------------|
+| 粒度 | 刷新作业级别 | 表版本级别 | 刷新作业级别 |
+| 刷新模式（增量/全量/无数据） | ✅ refresh_mode | ❌ | ❌ |
+| 触发方式（调度/手动） | ✅ refresh_trigger | ❌ | ❌ |
+| 写入统计（inserted/deleted） | ✅ stats | ❌ | ❌ |
+| 源表列表 | ✅ 表名级别 | ✅ 含版本/sequence/commit_time | ❌ |
+| 版本号/总行数/总字节数 | ❌ | ✅ version/total_rows/total_bytes | ❌ |
+| CRU 消耗 | ❌ | ❌ | ✅ cru |
+| 跨表批量查询 | ❌（单表） | ❌（单表） | ✅（可批量） |
+| compaction 记录 | ❌ | ✅ | ❌ |
+| 适用场景 | 排查增量是否生效、刷新状态 | 查看数据版本变化、追溯源表版本 | 批量分析/监控/CRU 统计 |

package/bin/skills/dt-creator/references/sql-limitations.md

@@ -0,0 +1,80 @@
+# Dynamic Table SQL 限制与支持矩阵
+
+本文档列出 Dynamic Table 增量计算支持和不支持的 SQL 模式。
+
+## JOIN 类型支持
+
+| JOIN 类型 | 增量支持 | 说明 |
+|-----------|---------|------|
+| INNER JOIN | ✅ | 完全支持 |
+| LEFT JOIN (LEFT OUTER) | ✅ | 完全支持 |
+| RIGHT JOIN (RIGHT OUTER) | ✅ | 完全支持 |
+| FULL OUTER JOIN | ✅ | 完全支持 |
+| LEFT SEMI JOIN | ✅ | 完全支持 |
+| LEFT ANTI JOIN | ✅ | 完全支持 |
+
+## 聚合函数支持
+
+### 支持增量计算的聚合函数
+
+- `SUM`, `SUM0`, `COUNT`, `COUNT_IF`, `MIN`, `MAX`, `MIN_BY`, `MAX_BY`
+- `AVG`, `STDDEV_SAMP`, `STDDEV_POP`, `VAR_SAMP`, `VAR_POP`
+- `Percentile`, `Median`, `COUNT_DISTINCT`
+- `BIT_OR`, `BIT_AND`, `BIT_XOR`, `BOOL_OR`, `BOOL_AND`
+- `GROUP_BITMAP` 系列
+- `COLLECT_SET`, `COLLECT_LIST`, `COLLECT_SET_ON_ARRAY`, `COLLECT_LIST_ON_ARRAY`
+- `MAP_AGG`, `WM_CONCAT`
+
+### 结果不稳定的聚合函数（增量结果可能与全量不一致）
+
+- `ANY_VALUE`, `FIRST_VALUE`, `LAST_VALUE`
+- `APPROX_COUNT_DISTINCT`, `APPROX_HISTOGRAM`, `APPROX_TOP_K`, `APPROX_PERCENTILE`
+- `JSON_MERGE_AGG`
+
+## 窗口函数支持
+
+### 支持的窗口函数
+
+- `ROW_NUMBER`, `RANK`, `DENSE_RANK`, `PERCENT_RANK`
+- `FIRST_VALUE`, `LAST_VALUE`, `NTH_VALUE`
+- `COUNT`, `SUM`, `SUM0`, `MIN`, `MAX`, `AVG`
+- `LEAD`, `LAG`, `CUME_DIST`, `NTILE`
+- `COLLECT_LIST`, `COLLECT_SET`, `COLLECT_SET_ON_ARRAY`, `COLLECT_LIST_ON_ARRAY`
+
+## ORDER BY / LIMIT / OFFSET
+
+支持 `ORDER BY`、`LIMIT`、`OFFSET` 语法。
+
+⚠️ 不建议在 DT 中使用全局 `ORDER BY`。全局排序在每次增量刷新时开销非常大，推荐将排序逻辑放在下游查询数据时执行，而非 ETL 建模阶段。
+
+## 非确定性函数
+
+非确定性函数（如 `NOW()`、`CURRENT_TIMESTAMP`、`CURRENT_DATE`、`random()` 等）在不参与计算逻辑时默认支持。具体来说，只要这些函数不出现在以下位置，就可以正常使用：
+- 窗口函数的 `PARTITION BY` key
+- `JOIN` key
+- `GROUP BY` key
+- 其他函数的入参
+
+典型场景：在 SELECT 中直接输出数据处理时间，记录每条数据被 DT 刷新处理的时刻：
+
+```sql
+CREATE DYNAMIC TABLE order_with_process_time AS
+SELECT
+    id,
+    amount,
+    status,
+    CURRENT_TIMESTAMP AS process_time  -- 记录刷新时的处理时间，直接输出到目标表
+FROM orders
+WHERE status = 'completed';
+```
+
+时间函数会在每次 REFRESH 时被常量折叠为当次刷新的时间戳。
+
+## UDF / UDAF / UDTF
+
+自定义函数需要在创建时声明为确定性函数（deterministic），才能在 DT 中使用增量计算。未声明确定性的自定义函数会导致增量计算被禁用。
+
+## 源表类型限制
+
+- **虚拟视图（VIEW）**：不能作为 DT 的输入表，会禁用增量计算
+- **外部表（External Table）**：不支持增量计算

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

@@ -0,0 +1,190 @@
+---
+name: dynamic-table-alter
+description: |
+  修改 ClickZetta 动态表（Dynamic Table）的结构和属性。支持直接 ALTER 操作（suspend、resume、
+  rename_column、set_comment、set_column_comment、set/unset properties）以及 CREATE OR REPLACE
+  重建操作（修改调度周期、计算集群、加列、减列、改列类型、改 SQL 定义）。当用户说"修改动态表"、
+  "动态表加列"、"改刷新间隔"、"暂停动态表"时触发。
+---
+
+# 动态表修改工作流
+
+## 指令
+
+### 步骤 1：确认动态表存在并获取当前定义
+使用 `read_query` 执行 `SHOW CREATE TABLE schema_name.table_name` 获取动态表当前定义。
+如果不确定是否为动态表，先用 `SHOW TABLES WHERE is_dynamic` 查看列表。
+
+### 步骤 2：判断操作类型并选择执行方式
+
+ClickZetta 动态表的修改操作分为两类：
+
+**A. 直接 ALTER 操作**（6种，可直接执行）：
+
+1. **suspend** — 暂停调度任务：
+```sql
+ALTER DYNAMIC TABLE dt_name SUSPEND;
+```
+
+2. **resume** — 启动调度任务：
+```sql
+ALTER DYNAMIC TABLE dt_name RESUME;
+```
+
+3. **set_comment** — 修改表注释：
+```sql
+ALTER DYNAMIC TABLE dt_name SET COMMENT 'comment';
+```
+
+4. **rename_column** — 修改列名：
+```sql
+ALTER DYNAMIC TABLE dt_name RENAME COLUMN old_name TO new_name;
+```
+
+5. **set_column_comment** — 修改列注释（注意用 CHANGE COLUMN）：
+```sql
+ALTER DYNAMIC TABLE dt_name CHANGE COLUMN column_name COMMENT 'comment';
+```
+
+6. **set/unset properties** — 修改表属性（目前为保留参数）：
+```sql
+-- 设置属性
+ALTER DYNAMIC TABLE dt_name SET PROPERTIES('key' = 'value');
+-- 删除属性
+ALTER DYNAMIC TABLE dt_name UNSET PROPERTIES('key');
+```
+
+**B. CREATE OR REPLACE 操作**（6种，需要重建动态表）：
+
+> ⚠️ **以下操作不支持 ALTER 语法**。`ALTER DYNAMIC TABLE ... SET REFRESH INTERVAL` 等语法不存在，会报语法错误。必须使用 `CREATE OR REPLACE DYNAMIC TABLE` 重建。
+
+这些操作涉及 SQL 查询逻辑变化，无法通过 ALTER 直接完成：
+
+7. **修改调度周期** — ❌ 不支持 `ALTER ... SET REFRESH INTERVAL`
+8. **修改计算集群** — ❌ 不支持 `ALTER ... SET VCLUSTER`
+9. **增加列**
+10. **减列**
+11. **修改列类型**
+12. **修改 SQL 定义**
+
+### 步骤 3：执行 CREATE OR REPLACE 重建（仅 B 类操作）
+
+1. 用 `read_query` 执行 `SHOW CREATE TABLE schema_name.table_name` 获取原始 DDL
+   > ⚠️ `SHOW CREATE TABLE` 不支持 LIMIT/WHERE 子句，直接执行即可
+2. 解析出：列定义、REFRESH 子句、AS SELECT 子句、COMMENT 等
+3. 根据操作修改对应部分
+4. 用 `write_query` 执行重建 SQL
+
+**关于全量刷新的触发**：
+- 简单的删除列 / 添加列（添加的列只是从源表 SELECT 透传，不参与 JOIN key、GROUP key 等计算）→ **增量刷新**
+- 涉及计算逻辑变化（修改 WHERE 条件、修改聚合逻辑、新增列参与计算等）→ **全量刷新**
+- 兼容类型变更（如 INT → BIGINT）→ **增量刷新**
+
+### 步骤 4：验证修改结果
+使用 `DESC TABLE dt_name` 确认修改生效。
+
+---
+
+## 示例
+
+### 示例 1：修改调度周期
+
+```sql
+-- 原表
+CREATE DYNAMIC TABLE dt_name
+REFRESH INTERVAL 10 MINUTE vcluster DEFAULT
+AS SELECT * FROM student02;
+
+-- 修改后（改为 20 分钟）
+CREATE OR REPLACE DYNAMIC TABLE dt_name
+REFRESH INTERVAL 20 MINUTE vcluster DEFAULT
+AS SELECT * FROM student02;
+```
+
+### 示例 2：修改计算集群
+
+```sql
+-- 原表
+CREATE DYNAMIC TABLE dt_name
+REFRESH INTERVAL 10 MINUTE vcluster DEFAULT
+AS SELECT * FROM student02;
+
+-- 修改后（改为 alter_vc 集群）
+CREATE OR REPLACE DYNAMIC TABLE dt_name
+REFRESH INTERVAL 10 MINUTE vcluster alter_vc
+AS SELECT * FROM student02;
+```
+
+### 示例 3：增加列
+
+```sql
+-- 原表
+CREATE DYNAMIC TABLE change_table (i, j)
+AS SELECT * FROM dy_base_a;
+
+-- 添加一列 col（涉及计算逻辑，下次刷新会全量刷新）
+CREATE OR REPLACE DYNAMIC TABLE change_table (i, j, col)
+AS SELECT i, j, j * 1 FROM dy_base_a;
+
+REFRESH DYNAMIC TABLE change_table;
+```
+
+### 示例 4：减列
+
+```sql
+-- 原表有 i, j 两列
+CREATE DYNAMIC TABLE change_table (i, j)
+AS SELECT * FROM dy_base_a;
+
+-- 减列（简单透传，增量刷新）
+CREATE OR REPLACE DYNAMIC TABLE change_table (i)
+AS SELECT i FROM dy_base_a;
+```
+
+### 示例 5：修改 SQL 定义
+
+```sql
+-- 修改 WHERE 过滤条件（全量刷新）
+CREATE OR REPLACE DYNAMIC TABLE change_table (i, j)
+AS SELECT * FROM dy_base_a WHERE i > 3;
+
+REFRESH DYNAMIC TABLE change_table;
+```
+
+### 示例 6：修改列类型
+
+```sql
+-- INT → BIGINT（兼容类型，增量刷新）
+CREATE OR REPLACE DYNAMIC TABLE change_table (i, j)
+AS SELECT CAST(i AS BIGINT), j FROM dy_base_a;
+
+REFRESH DYNAMIC TABLE change_table;
+```
+
+---
+
+## 平台特有知识
+
+- **CHANGE COLUMN 语法**：设置列注释用 `CHANGE COLUMN col COMMENT 'xxx'`，不是 `ALTER COLUMN`
+- **RENAME COLUMN 语法**：`RENAME COLUMN old TO new`
+- **DML 限制**：动态表默认不支持 UPDATE/DELETE/MERGE（因隐藏列 MV__KEY），如需 DML 须先执行 `SET cz.sql.dt.allow.dml = true;`
+- **REFRESH 格式**：`REFRESH INTERVAL <N> MINUTE vcluster <name>`，支持 SECOND/MINUTE/HOUR/DAY
+- **CREATE OR REPLACE 风险**：涉及计算逻辑变化时会触发全量刷新，大表可能耗时较长
+- **schema 前缀**：所有 ALTER/CREATE 语句中表名应包含 schema 前缀
+- **列定义可省略类型**：`CREATE DYNAMIC TABLE dt (i, j) AS SELECT ...` 类型由 SELECT 推断
+- **DROP 语法**：必须用 `DROP DYNAMIC TABLE dt_name`，不能用 `DROP TABLE dt_name`（会报错）
+- **UNDROP 语法**：必须用 `UNDROP TABLE dt_name`，不能用 `UNDROP DYNAMIC TABLE dt_name`
+- **DESC 语法**：动态表用 `DESC TABLE dt_name`，不要写 `DESC DYNAMIC TABLE dt_name EXTENDED`（EXTENDED 不支持）
+
+## 故障排除
+
+| 错误 | 原因 | 解决方案 |
+|---|---|---|
+| ALTER 报 "Syntax error at or near 'REFRESH'" | `ALTER ... SET REFRESH INTERVAL` 语法不存在 | 使用 `CREATE OR REPLACE DYNAMIC TABLE ... REFRESH INTERVAL ...` 重建 |
+| ALTER 报 "unsupported operation" | 尝试对动态表执行 B 类操作的 ALTER 语法 | 使用 CREATE OR REPLACE 重建 |
+| `DROP TABLE dt_name` 报错 | 动态表必须用 `DROP DYNAMIC TABLE` | 改为 `DROP DYNAMIC TABLE dt_name` |
+| `UNDROP DYNAMIC TABLE` 报错 | UNDROP 不支持 DYNAMIC TABLE 关键字 | 改为 `UNDROP TABLE dt_name` |
+| `DESC DYNAMIC TABLE ... EXTENDED` 报错 | 不支持 EXTENDED 参数 | 改为 `DESC TABLE dt_name`（不加 EXTENDED） |
+| UPDATE/DELETE 报 "MV__KEY" 相关错误 | 动态表有隐藏列 MV__KEY，默认禁止 DML | 先执行 `SET cz.sql.dt.allow.dml = true;` |
+| CREATE OR REPLACE 后数据为空 | AS SELECT 子句引用的源表或列不正确 | 先用 `read_query` 验证 SELECT 子句 |
+| CREATE OR REPLACE 后全量刷新 | 新增列参与了计算逻辑（JOIN key、GROUP key 等） | 预期行为，等待全量刷新完成 |

package/package.json

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