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

package/bin/skills/clickzetta-dynamic-table/sql-to-dt/references/sql2dt-workflow.md

@@ -0,0 +1,109 @@
+# SQL → Dynamic Table 完整转换工作流
+
+当用户给你一组 CREATE TABLE DDL 和 INSERT OVERWRITE SQL，要求转换为 Dynamic Table 时，按以下步骤顺序执行。
+
+每一步的详细规则在对应的 skill 文件中，你需要同时引用它们。
+
+## 工作流步骤
+
+### Step 1: 预处理输入
+
+从 INSERT OVERWRITE 文件中移除：
+- 所有 `ALTER TABLE` 语句
+- `ANALYZE TABLE` 语句
+- SQL 注释（`--` 和 `/* */`）
+
+保留：CREATE TABLE、INSERT OVERWRITE、WITH、SET、CREATE TEMPORARY FUNCTION。
+
+### Step 2: 占位符替换
+
+按 #[[file:sql2dt-placeholder-rules.md]] 中的规则：
+1. 统一占位符格式（`{{ }}` → `${ }`）
+2. 替换所有占位符为 `SESSION_CONFIGS()` 调用
+3. 处理 nodash 变量、日期运算、macros 函数
+4. 根据引号上下文决定处理方式（去引号 / CONCAT / 直接替换）
+
+### Step 3: 自引用检测
+
+按 #[[file:sql2dt-self-reference-rules.md]] 中的规则：
+1. 检查 INSERT OVERWRITE 目标表是否出现在 FROM/JOIN 中
+2. 如果是自引用表，标记并在后续步骤中添加注释、使用显式 schema
+
+### Step 4: 核心转换
+
+按 #[[file:sql2dt-conversion-rules.md]] 中的规则：
+1. 解析 CREATE TABLE DDL（提取列、分区、属性等）
+2. 解析 INSERT OVERWRITE（提取查询、分区类型）
+3. 组装 `CREATE OR REPLACE DYNAMIC TABLE ... AS SELECT ...`
+4. 注入静态分区值到 SELECT（智能引号处理）
+5. 合并表属性模板（默认 `data_lifecycle=15`）
+6. 处理 UNION ALL（每个分支独立注入）
+7. 日期函数后处理：将所有 `DATE_SUB/DATE_ADD` 统一转为 `sub_days`
+
+### Step 5: 列校验
+
+按 #[[file:sql2dt-column-validation-rules.md]] 中的规则：
+1. 计算 schema 列数和 SELECT 列数
+2. 验证两者相等
+3. 检查重复别名和缺失分区列
+4. UNION ALL 分支列数一致性检查
+
+### Step 6: 生成配套文件
+
+按 #[[file:sql2dt-refresh-rules.md]] 中的规则：
+1. 从 DDL 中提取所有 SESSION_CONFIGS 变量
+2. 生成当前周期 refresh 语句
+3. 生成上一周期 prev_refresh 语句
+4. 生成回填 backfill 语句
+
+### Step 7: 转换后改进建议
+
+DDL 生成完成后，对转换结果做以下检查，并主动向用户提出改进建议：
+
+**检查 1：非分区表 + 持续写入风险**
+
+按 #[[file:../best-practices/non-partitioned-merge-into-warning.md]] 中的判断逻辑：
+- 生成的 DT 是非分区表（无 `PARTITIONED BY` 也无 `SESSION_CONFIGS()`）
+- 且 SQL 中包含 `ROW_NUMBER() OVER (PARTITION BY ... ORDER BY ... DESC) WHERE rn = 1` 去重模式
+
+→ 满足条件时，使用该文档中的告警话术模板向用户发出风险提示，并建议改用 MERGE INTO + Table Stream 方案。
+
+**检查 2：SQL 性能优化机会**
+
+按 #[[file:../best-practices/performance-optimization.md]] 中的规则，扫描生成的 DT SQL：
+- 存在 `LEFT/RIGHT/FULL OUTER JOIN` → 提示如果业务允许，改用 INNER JOIN 可提升增量效率
+- 存在无 `PARTITION BY` 的窗口函数 → 提示添加 PARTITION BY，否则每次增量都全量重算
+- `GROUP BY` 使用了复杂表达式（如 `DATE_TRUNC`、`SUBSTR`）→ 提示考虑在上游预计算或拆分为多级 DT
+
+**检查 3：JOIN 中是否有维度表**
+
+按 #[[file:../best-practices/dimension-table-join-guide.md]] 中的推荐场景：
+- SQL 中存在 JOIN → 询问用户右侧表是否为低频变更的维度表（码表、字典表、配置表等）
+- 如果是 → 建议在 TBLPROPERTIES 中添加 `mv_const_tables` 配置，并说明其行为和数据一致性权衡
+
+## 输出清单
+
+对每个表，最终输出：
+
+| 文件 | 内容 | 条件 |
+|------|------|------|
+| `表名.sql` | Dynamic Table DDL | 始终生成 |
+| `表名_refresh.sql` | 当前周期 REFRESH 语句 | 始终生成 |
+| `表名_prev_refresh.sql` | 上一周期 REFRESH 语句 | 仅有分区变量时 |
+| `表名_backfill.sql` | 回填语句 | 仅有分区变量时 |
+
+## 快速判断路径
+
+```
+输入 DDL + INSERT OVERWRITE
+  │
+  ├─ 有占位符？ → Step 2 占位符替换
+  │
+  ├─ 自引用？ → Step 3 特殊处理
+  │
+  ├─ 有静态分区？ → Step 4 注入分区值到 SELECT
+  │
+  ├─ 有 UNION ALL？ → Step 4 每个分支独立注入
+  │
+  └─ 生成 DDL → Step 5 校验 → Step 6 生成配套文件 → Step 7 改进建议
+```

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

@@ -87,6 +87,10 @@ cz-cli agent run "<request>" --format a2a --dangerously-skip-permissions
 
 Do NOT use direct cz-cli subcommands when an active LLM is available. Always delegate the full request to `cz-cli agent run`.
 
+The output includes a `session_id`. Use it to inspect the run:
+- `cz-cli agent session status <session_id>` — current state (`busy`/`retry` with `progress`, `idle` with `result`, or `error`)
+- `cz-cli agent export <session_id>` — full conversation (messages, tool calls, reasoning, text). Wait until `status` is `idle` before exporting; otherwise the conversation may still be in progress.
+
 **Step 3 — ONLY if no active LLM (kind: "none" or empty list), fall back to direct commands:**
 
 Decompose the request into concrete `cz-cli` subcommands (`sql`, `schema`, `table`, `task`, `runs`, `job`, `datasource`, `profile`, etc.), execute them, and synthesize the result.
@@ -101,6 +105,127 @@ cz-cli agent run "<request>" --format a2a --dangerously-skip-permissions --sessi
 
 Reuse `session_id` for follow-ups on the same topic. Omit `--session` to start fresh.
 
+## Async mode (non-TTY / long-running tasks)
+
+When running in non-TTY environments (e.g. as a subagent from Claude Code) or for long-running tasks, use async mode to avoid blocking:
+
+### Submit asynchronously
+
+```bash
+cz-cli agent run "<request>" --async --format a2a --dangerously-skip-permissions
+```
+
+Returns immediately with a session ID:
+```json
+{"session_id": "01JXF3K...", "status": "running", "message": "Session submitted asynchronously"}
+```
+
+Note: In non-TTY with `--format a2a` or `--format json`, async mode activates automatically (no `--async` flag needed).
+
+### Poll status
+
+```bash
+cz-cli agent session status <session_id>
+```
+
+While running:
+```json
+{"session_id": "01JXF3K...", "status": "busy", "progress": "$ cz-cli table list -o table"}
+```
+
+Other progress examples you may see during polling:
+- `"💭 Thinking..."` — LLM is reasoning
+- `"✏ Generating response..."` — LLM is writing the reply
+- `"✱ Grep \"error\" · 3 matches"` — running a search tool
+- `"↻ Retry (attempt 2)"` — retrying a failed LLM call (paired with a `retry` field describing the reason)
+
+When complete:
+```json
+{"session_id": "01JXF3K...", "status": "idle", "result": "Here are the results:\n..."}
+```
+
+The `result` field is the final text reply. For full conversation details (thinking, tool calls, intermediate text), use `cz-cli agent export <session_id>`.
+
+If the session does not exist:
+```json
+{"session_id": "ses_invalid", "error": "Session not found"}
+```
+(exits with code 1)
+
+### Retrieve full conversation (thinking + tool calls + text)
+
+```bash
+cz-cli agent export <session_id>
+```
+
+Returns complete session with all message parts:
+```json
+{
+  "info": { "id": "...", "title": "...", "time": {...} },
+  "messages": [
+    {
+      "info": { "role": "user" },
+      "parts": [{ "type": "text", "text": "original prompt" }]
+    },
+    {
+      "info": { "role": "assistant" },
+      "parts": [
+        { "type": "reasoning", "text": "thinking content..." },
+        { "type": "tool", "tool": "bash", "state": { "status": "completed", "input": {...}, "output": "..." } },
+        { "type": "text", "text": "final answer..." }
+      ]
+    }
+  ]
+}
+```
+
+Part types in export:
+- `reasoning` — LLM thinking/reasoning blocks
+- `tool` — tool calls with full input/output (bash, read, write, edit, glob, grep, etc.)
+- `text` — final text response
+- `step-start` / `step-finish` — step boundaries
+- `patch` — code diffs
+- `subtask` — delegated sub-tasks
+
+### Async workflow pattern
+
+```bash
+# 1. Submit
+SESSION=$(cz-cli agent run "complex analysis" --async --format a2a --dangerously-skip-permissions | jq -r '.session_id')
+
+# 2. Poll until done, printing progress along the way
+while true; do
+  STATUS=$(cz-cli agent session status $SESSION)
+  STATE=$(echo "$STATUS" | jq -r '.status')
+  if [ "$STATE" = "idle" ]; then
+    echo "$STATUS" | jq -r '.result'
+    break
+  fi
+  echo "$STATUS" | jq -r '.progress // empty'
+  sleep 5
+done
+
+# Need full conversation (thinking + tool calls)?
+cz-cli agent export $SESSION
+```
+
+### With session continuity (async)
+
+```bash
+# First turn
+SESSION=$(cz-cli agent run "describe sales table" --async --format a2a --dangerously-skip-permissions | jq -r '.session_id')
+# ... wait for completion ...
+
+# Follow-up turn on same session
+cz-cli agent run "now show row counts" --async --format a2a --dangerously-skip-permissions --session $SESSION
+```
+
+### Important notes for async mode
+
+- **Permissions:** Always use `--dangerously-skip-permissions` — async mode cannot handle interactive permission prompts
+- **Server requirement:** An agent runtime server must be running (or will be started automatically)
+- **Error handling:** If session is already busy, returns `{"error": "session busy"}`
+
 ## Multi-environment (profiles)
 
 When the user specifies an environment or profile (e.g. "use uat_test", "on the test instance"):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clickzetta/cz-cli-darwin-arm64",
-  "version": "0.3.75",
+  "version": "0.3.76",
   "description": "cz-cli binary for macOS ARM64 (Apple Silicon)",
   "os": [
     "darwin"