@dazitech/cli 3.0.0

package/dist/docs/flow/node-code-guide.md

@@ -0,0 +1,399 @@
+# 节点代码编写指南
+
+**文档 ID**: `flow/node-code-guide`  
+**适用**: `项目/flow_*/流程/<名>/节点/<节点名>/code.*`  
+**前置**: [数据流程项目开发指南](./flow-project-guide.md)、[流程变量系统指南](./variables-guide.md)、**[Flow 文档索引 §流程节点组件](./flows-guide.md#流程节点组件)**（全部可用节点）
+
+---
+
+## 1. 哪些节点有代码文件
+
+> 完整 **14 种** 可用 `data.type`（含无代码节点）见 [flows-guide §流程节点组件](./flows-guide.md#流程节点组件)。
+
+| 业务类型 `data.type` | 本地文件 | 平台存储 |
+|---------------------|----------|----------|
+| `sql-query` | `code.sql` | `flow_nodes.code_body` |
+| `database-source` | `code.sql` | 同上 |
+| `dataspace-source` | `code.sql` | 同上 |
+| `python-script` | `code.py` | 同上 |
+| `excel-python` | `code.py` | 同上 |
+| `condition` | `code.py` | 同上 |
+| `data-quality-check` | `code.py`（键 `dqPythonCode`） | 同上 |
+
+纯配置节点（如 `database-sink`、`dataspace-sink`、`excel-import`、`delay`、`file-source` 等）**无** `code.*`，只在 `flow.json` 的 `data` 里配置；完整列表见 [flows-guide](./flows-guide.md#流程节点组件)。
+
+**编辑入口**
+
+- 资源管理器：右键 `节点/<名>/` → **打开节点代码**
+- 设计器：选中节点 → **打开代码文件**
+- 直接打开 `code.sql` / `code.py`
+
+**提交入口**
+
+- 右键 `code.*` → **提交节点** → `flow node push --node <node_uuid>`
+- 或 **提交流程**（批量提交所有脏代码节点）
+
+---
+
+## 2. 修改代码的标准流程
+
+```powershell
+# 1. 进入流程目录（dazi-work 根下）
+cd "项目\flow_xxx\流程\MyFlow"
+
+# 2. 编辑 节点/SQL查询/code.sql 等
+
+# 3. 查看是否有本地改动
+.\scripts\dazi.ps1 flow project status
+
+# 4. 单节点测试（会先 GET debug-run，再 POST 单节点运行）
+.\scripts\dazi.ps1 flow run node-exec --node <node_uuid> --dir .
+
+# 5. 提交代码到平台
+.\scripts\dazi.ps1 flow node push --node <node_uuid> --dir .
+```
+
+`node_uuid` 在 `flow.meta.json` → `nodes.<uuid>`，或设计器属性面板、 `node.info.json` 中查看。  
+**单节点运行 API 使用语义 `nodeId`（画布 `id` 字段）**，CLI 的 `node-exec` 会用 meta 自动翻译。
+
+测试失败时阅读 **`_run/<节点名>.last-error.md`**（含错误分类与修复指引），确认后再交给 AI。
+
+---
+
+## 3. `sql-query` / `database-source` / `dataspace-source`（SQL）
+
+**文件**: `code.sql`  
+**画布配置**（`flow.json` → 节点 `data`）：
+
+| 类型 | 关键字段 |
+|------|----------|
+| `database-source` | `connectionId`、`output_variable_name` |
+| `dataspace-source` | `spaceId`、`output_variable_name` |
+| `sql-query` | `output_variable_name`（消费上游表变量） |
+
+> **变量用法**：`sql-query` 在 SQL 里把 **上游 `output_variable_name`** 当作 **表名**；`database-source` / `dataspace-source` 只 **产出** 变量、不消费 Run 内变量。详见 [流程变量系统指南 §6.1–6.2](./variables-guide.md#61-sql-queryduckdb-内存-sql)。
+
+**约定**
+
+- SQL 写在 **`code.sql`**，不要塞进 `flow.json` 的 `data.sql`（pull 后会剥离到文件）。
+- `connectionId` 为 **`ads_connections` 的字符串 id**，用 `dazi-flow source list` 核对。
+- `spaceId` 为 **`ads_dataspaces` 的 id**，用 `dazi-flow dataspace list` 核对。
+- 执行结果以 **`output_variable_name`** 为名写入调试 Run（表变量）。
+
+**模板（database-source：外部库 → 表变量）**
+
+```sql
+-- output_variable_name = dim_product
+SELECT product_id, product_name, category
+FROM dim_product
+WHERE is_active = 1
+LIMIT 50000;
+```
+
+**模板（dataspace-source：数据空间 DuckDB/ClickHouse → 表变量）**
+
+```sql
+-- spaceId 在 flow.json；SQL 针对空间内已注册表
+-- output_variable_name = sales_raw
+SELECT *
+FROM sales_fact
+WHERE dt >= '2025-01-01'
+LIMIT 100000;
+```
+
+**模板（sql-query：消费上游表变量 → 新表变量）**
+
+```sql
+-- 上游 output_variable_name = excel_raw
+-- 本节点 output_variable_name = sales_agg
+SELECT
+  产品类别,
+  SUM(销售金额) AS 合计金额
+FROM excel_raw
+GROUP BY 产品类别;
+```
+
+**多表 JOIN（变量名即表名）**
+
+```sql
+-- 上游已产出 orders、customers
+SELECT o.order_id, c.customer_name, o.amount
+FROM orders o
+JOIN customers c ON o.customer_id = c.customer_id;
+```
+
+**测试**: 右键 → 测试运行节点；成功后用设计器 📊 或 `flow variable pull --name <output_variable_name>` 查看结果。
+
+---
+
+## 4. `python-script`（表 → 表）
+
+**文件**: `code.py`  
+**画布**: 配置 **`output_variable_name`**（主输出表变量名）。
+
+> **变量用法**：单节点测试用 **`get_variable('上游 output_variable_name')`**；整图跑时入边 **`df`** 可能有值。完整说明与多表示例见 [流程变量系统指南 §6.3](./variables-guide.md#63-python-script最常用)。
+
+**运行时注入**
+
+| 符号 | 说明 |
+|------|------|
+| `pd` | pandas |
+| `df` | 来自入边 Parquet（整图跑时通常非空） |
+| `get_variable("名")` | 从调试 Run 读上游表（**单节点测试时优先用这个**） |
+| `set_table_output(name, df)` | 多表输出 |
+| `result_df` | 主输出 DataFrame（与 `output_variable_name` 对应） |
+| `output.print(...)` | 运行日志（**勿用裸 `print`**） |
+
+**单节点测试要点**
+
+整图运行时 `df` 可能有值；**单节点调试**时常无入边 Parquet，`df` 为空，应：
+
+```python
+# -*- coding: utf-8 -*-
+# 上游 sql-query 的 output_variable_name = sales_agg
+# 本节点 output_variable_name = py_result
+import pandas as pd
+
+output.print("[python-script] 开始")
+
+df = get_variable("sales_agg")  # 变量名须与上游画布配置完全一致
+output.print(f"输入 shape={df.shape}, columns={list(df.columns)}")
+
+result_df = df.groupby("产品类别", as_index=False)["合计金额"].sum()
+output.print(f"输出 shape={result_df.shape}")
+```
+
+**多表 + 入边回退**
+
+```python
+import pandas as pd
+
+if df is None or df.empty:
+    df = get_variable("sales_agg")
+ref = get_variable("dim_product")
+result_df = df.merge(ref, on="product_id", how="left")
+set_table_output("merged_preview", result_df.head(100))  # 可选附加表
+```
+
+**日志规范**（与平台约定一致）
+
+- 开始 / 输入信息 / 关键变换 / 输出结果 / 结束 均用 `output.print`
+- `except` 里先 `output.print` 再 `raise`
+
+---
+
+## 5. `excel-python`（Excel 开发 · **默认首选**）
+
+> **选型**：文件上传管理中的 **`.xlsx` / `.xls`**（有 `managed_file_id`）**优先本节点**，**禁止**用 `file-source`（不解析 Excel）。仅极简单单 Sheet 零代码时才考虑 `excel-import`。
+
+**文件**: `code.py`  
+**画布**（`flow.json` → 节点 `data`，**不是写在 code.py 里**）:
+
+| 字段 | 说明 |
+|------|------|
+| **`managed_file_id`** | 平台「文件上传管理」登记的 **UUID**（见 `资源/files/<名>_<id8>/文件信息.json` → `file_id`） |
+| **`output_variable_name`** | 主输出表变量名；**必须与** `set_table_output` 第一个参数 **完全一致** |
+
+### 分工（AI 必守）
+
+| 谁配置 | 配什么 | 禁止 |
+|--------|--------|------|
+| **`flow.json` / 设计器** | `managed_file_id` = UUID | 不要用文件名、相对路径、data upload 的 `id` |
+| **`code.py`** | 用 **`excel_source_path`** 读 Excel | 不要 `open("xxx.xlsx")`、`pd.read_excel("D:/...")`、不要猜路径 |
+
+引擎根据 `managed_file_id` 查库得到物理路径，执行前注入：
+
+| 变量 | 说明 |
+|------|------|
+| **`excel_source_path`** | 服务端 Excel **绝对路径**（代码里唯一正确的读文件方式） |
+| **`excel_original_filename`** | 登记显示名（仅用于 `output.print` 日志） |
+| `pd` | pandas |
+| `set_table_output(name, df)` | 产出表变量（**必须**调用，主表名 = `output_variable_name`） |
+| `output.print(...)` | 运行日志 |
+
+**获取 `managed_file_id`**
+
+1. 侧栏 **数据资源 → 文件上传管理** → 拉取到 `资源/files/.../文件信息.json`
+2. 或 CLI：`.\scripts\dazi.ps1 flow managed-files list` / `managed-files pull --file-id <uuid>`
+
+**`flow.json` 示例（画布配置）**
+
+```json
+{
+  "id": "n-excel-1",
+  "type": "custom",
+  "data": {
+    "label": "Excel解析",
+    "type": "excel-python",
+    "managed_file_id": "51853ede-9e6b-4a3a-aa7a-060cbead0862",
+    "output_variable_name": "成本统计报表"
+  }
+}
+```
+
+> `managed_file_id` 是 **UUID 字符串**，与 `Excel成本报表08.xlsx` 等文件名 **无关**；文件名只出现在注释/`excel_original_filename` 日志中。
+
+---
+
+### 示例 A：单 Sheet、复杂表头（推荐模板）
+
+对应真实流程「成本报表数据08」：表头不在第 1 行时用 `header=None` + `skiprows` + `names`。
+
+```python
+# -*- coding: utf-8 -*-
+# 画布：managed_file_id = <UUID>（见 flow.json，勿在代码里写文件名）
+# 画布：output_variable_name = 成本统计报表
+import pandas as pd
+
+OUTPUT_VAR = "成本统计报表"  # 必须与 output_variable_name 一致
+DATA_START_ROW = 4           # 0-based，Excel 第 5 行起为数据
+
+COLUMN_NAMES = [
+    "基本信息_组织", "基本信息_年度", "基本信息_月度", "基本信息_项目",
+    "成本项_管理费", "成本项_间接成本", "成本项_税金",
+    # ... 按实际列继续
+]
+
+output.print("[excel-python] 开始")
+output.print(f"source={excel_original_filename or excel_source_path}")
+
+# ✅ 正确：读引擎注入的路径
+raw = pd.read_excel(
+    excel_source_path,
+    sheet_name="Sheet1",
+    header=None,
+    skiprows=DATA_START_ROW,
+    usecols="A:P",
+    names=COLUMN_NAMES,
+)
+table = raw.dropna(how="all")
+
+output.print(f"{OUTPUT_VAR} shape={table.shape}")
+set_table_output(OUTPUT_VAR, table)  # 主输出，名称必须与 output_variable_name 一致
+output.print("[excel-python] 完成")
+```
+
+---
+
+### 示例 B：多 Sheet 产出多张表变量
+
+对应 VS-flow0：一个 Excel 解析出 `销售表`、`产品表`、`规格表`。
+
+```python
+# -*- coding: utf-8 -*-
+# 画布：managed_file_id = <UUID>
+# 画布：output_variable_name = 销售表（主输出，须 set_table_output 同名）
+import pandas as pd
+
+SHEETS = {
+    "销售表": {"sheet_name": "销售表", "header": 0, "usecols": "A:H"},
+    "产品表": {"sheet_name": "产品表", "header": 1, "usecols": "A:C"},
+    "规格表": {"sheet_name": "规格表", "header": 1, "usecols": "A:C"},
+}
+
+output.print("[excel-python] 开始")
+output.print(f"source={excel_original_filename or excel_source_path}")
+
+for var_name, kwargs in SHEETS.items():
+    raw = pd.read_excel(excel_source_path, **kwargs)  # ✅ 只用 excel_source_path
+    table = raw.dropna(how="all")
+    output.print(f"{var_name} shape={table.shape}")
+    set_table_output(var_name, table)
+
+output.print("[excel-python] 完成")
+```
+
+下游 `sql-query` 可直接 `FROM 销售表 JOIN 产品表 ...`。
+
+---
+
+### 反例（AI 禁止）
+
+```python
+# ❌ 错误：臆造本地/相对路径
+pd.read_excel("Excel成本报表08.xlsx")
+pd.read_excel("./uploads/xxx.xlsx")
+pd.read_excel(r"D:\src2025\...\成本报表.xlsx")
+
+# ❌ 错误：在 code.py 里写 managed_file_id 或 open 文件
+open(managed_file_id)
+
+# ❌ 错误：主输出未 set_table_output，或名称与 output_variable_name 不一致
+result_df = pd.read_excel(excel_source_path)
+# 缺少 set_table_output("与画布同名", result_df)
+```
+
+---
+
+### 提交与测试
+
+1. 改 **`managed_file_id` / `output_variable_name`** → `project push --canvas`
+2. 改 **`code.py`** → `node push` → `node-exec` 或整流程 `flow-exec`
+3. 多表时单节点测试可能只有主表；全表变量用 **`flow-exec --type debug`** 后 `variable sync`
+
+详见 [flow-project-guide §6.1 文件上传管理](./flow-project-guide.md#61-文件上传管理excel-等流程数据源)、[流程开发最佳实践 §6.1](./流程开发最佳实践-VS-flow0案例.md#61-excel-多表解析节选)。
+
+---
+
+## 6. `condition`（条件分支）
+
+**文件**: `code.py`  
+逻辑脚本决定分支；使用 `output.print` 记录判断依据。测试方式同 `python-script`。
+
+---
+
+## 7. `data-quality-check`（数据质量）
+
+**文件**: `code.py`（平台键 `dqPythonCode`）
+
+**注入**
+
+| 符号 | 说明 |
+|------|------|
+| `df` | 入边 Parquet；单节点时可能为空 |
+| `get_variable("名")` | 调试 Run 中的附加表 |
+| `quality_config` | 与画布 `qualityConfig` 对齐 |
+| `set_scalar_output(name, value)` | 综合分等标量 |
+| `result_df` | 质检报告表 |
+
+**推荐**：`df.empty` 时用 `get_variable` 补主表（变量名与 `attached_variables` / 上游输出一致）。
+
+规则从 `quality_config["rules"]` 读取，避免魔法数。端到端质检案例见 [流程开发最佳实践（VS-flow0 案例）](./流程开发最佳实践-VS-flow0案例.md)。
+
+---
+
+## 8. 画布配置 vs 代码分工
+
+| 改什么 | 改哪里 | 怎么提交 |
+|--------|--------|----------|
+| SQL / Python 正文 | `code.sql` / `code.py` | `node push` |
+| 连线、坐标、节点增删 | `flow.json`（设计器） | `project push --canvas` |
+| connectionId、表名、output_variable_name | 设计器属性 → `flow.json` | `project push --canvas` |
+
+**不要**在 `flow.json` 里硬塞大段 `pythonCode`/`sql`：pull 会剥离到 `code.*`，push 代码走 `flow-nodes` 接口。
+
+---
+
+## 9. 查看输出变量
+
+变量模型、`debug_run_id`、本地 **`变量/<名>.json`** 详见 **[流程变量系统指南](./variables-guide.md)**。
+
+```powershell
+# 拉取单个变量（schema + 前 10 行）到 变量/<name>.json
+.\scripts\dazi.ps1 flow variable pull --name sales_df --dir .
+
+# 同步全部调试变量
+.\scripts\dazi.ps1 flow variable sync --dir .
+```
+
+设计器：选中节点 → 属性 **`output_variable_name`** → 点击 **📊**。
+
+---
+
+## 10. AI 协作建议
+
+1. 让 AI 阅读 **`code.*`** + **`flow.json` 中该节点 `data`** + 失败时的 **`_run/*.last-error.md`**
+2. **Agent 模式**（用户委托改流程）：AI 应主动执行「改 → `node-exec`/`flow-exec` → 读 `last-error.md` → 再改 → 再跑」循环（默认最多 3 轮），详见流程目录 **`快速启动_<流程名>.md` §AI 自主运行与改错闭环** 或提示词 **`flow/run-fix-loop`**
+3. **对话模式**（用户仅粘贴错误）：用户确认后再改代码 → 测试 → `node push`
+4. 需要查上游表结构时，先 **运行上游** 或 **`variable pull`**，把 `变量/<名>.json` 交给 AI
+5. MCP：`dazi-flow mcp serve`（工具含 `flow_run_node`、`flow_node_get_code`、`flow_node_set_code` 等，写操作需 `--allow-write`）

package/dist/docs/flow/plan-guide.md

@@ -0,0 +1,59 @@
+# Flow 执行计划
+
+**文档 ID**: `flow/plan-guide`
+
+## 编译计划
+
+```bash
+dazi-flow plan compile <flow-id>
+
+# 带输入参数
+dazi-flow plan compile <flow-id> --input '{"date": "2026-01-01"}'
+```
+
+计划保存到 `flows/<flow-id>/plans/plan.json`。
+
+## 应用计划
+
+```bash
+# 验证（dry-run）
+dazi-flow plan apply <flow-id> --dry-run
+
+# 执行应用
+dazi-flow plan apply <flow-id>
+```
+
+## 导出 Markdown 文档
+
+```bash
+# 摘要文档
+dazi-flow plan markdown <flow-id> --type summary
+
+# 详细文档
+dazi-flow plan markdown <flow-id> --type detail
+
+# 流程图（Mermaid）
+dazi-flow plan markdown <flow-id> --type diagram
+```
+
+## 生成 LLM 引导文档
+
+生成供 Cursor/LLM 理解 Flow 结构的文档：
+
+```bash
+dazi-flow plan llm-guide <flow-id>
+```
+
+保存到 `flows/<flow-id>/plans/llm-guide.md`，内容包括：
+- Flow 目的说明
+- 节点功能描述
+- 数据流向
+- 关键配置项
+
+## 生成数据库脚手架
+
+根据 Flow 的数据模型生成建表 DDL：
+
+```bash
+dazi-flow plan scaffold-database <flow-id> --dialect clickhouse
+```

package/dist/docs/flow/run-guide.md

@@ -0,0 +1,98 @@
+# Flow 运行与测试
+
+**文档 ID**: `flow/run-guide`
+
+**命令前缀**（`dazi-work` 根）：`.\scripts\dazi.ps1 flow …`  
+**流程项目**：在 `项目/flow_*/流程/<名>/` 下执行，或使用 `--dir <流程目录>`。
+
+---
+
+## 1. 流程项目：单节点测试（最常用）
+
+```powershell
+cd "项目\flow_xxx\流程\MyFlow"
+
+# 按 node_uuid 测试（CLI 内部翻译为语义 nodeId）
+.\scripts\dazi.ps1 flow run node-exec --node <node_uuid> --dir .
+```
+
+**行为**
+
+1. `GET /flows/{id}/debug-run` — 确保 `ads_flows.debug_run_id` 已绑定调试 Run  
+2. `POST /flows/{id}/nodes/{nodeId}/run` — 执行单节点  
+3. 成功时同步该节点 `output_variable_name` 到 **`变量/<名>.json`**  
+4. 失败时写入 **`_run/<节点名>.last-error.md`**（扩展会自动打开）
+
+扩展：右键 **节点/** 或 **code.*** → **测试运行节点**。
+
+---
+
+## 2. 流程项目：整流程运行
+
+```powershell
+.\scripts\dazi.ps1 flow run flow-exec --dir . --type debug
+# preview：清空调试变量后全新运行
+.\scripts\dazi.ps1 flow run flow-exec --dir . --type preview
+```
+
+成功后 **`flow variable sync`** 同步全部变量到 `变量/` 目录。
+
+扩展：右键 **flow.json** / 流程目录 → **运行整流程**。
+
+---
+
+## 3. 查看运行期变量
+
+变量存储在 **`flow_runs` + `flow_run_variables`**，通过 **`flows.debug_run_id`** 关联。  
+**变量模型、代码节点读写方式**见 [流程变量系统指南](./variables-guide.md)。
+
+```powershell
+# 拉取单个变量（schema + 前 10 行）→ 变量/<name>.json
+.\scripts\dazi.ps1 flow variable pull --name sales_df --dir .
+
+# 同步全部调试 Run 变量
+.\scripts\dazi.ps1 flow variable sync --dir .
+```
+
+设计器：节点 **`output_variable_name`** 旁 **📊** 按钮。
+
+扩展：右键 **`变量/`** → 同步；右键 **`变量/*.json`** → 刷新。
+
+---
+
+## 4. 平台级 Run API（脚本 / 自动化）
+
+```powershell
+# 启动 Run
+.\scripts\dazi.ps1 flow run start <flow-id> --input '{}'
+
+# 列表
+.\scripts\dazi.ps1 flow run list <flow-id> --limit 10
+
+# 调试信息（最近 Run）
+.\scripts\dazi.ps1 flow run debug <flow-id>
+
+# 变量列表（需 --flow）
+.\scripts\dazi.ps1 flow run variables-list <runId> --flow <flow-id>
+```
+
+流程项目日常开发优先用 **§1–§3** 的 `node-exec` / `flow-exec` / `variable pull`。
+
+---
+
+## 5. 失败分析
+
+```powershell
+# 拉取 failure-bundle 落盘
+.\scripts\dazi.ps1 flow run failure --run <runId> --dir .
+```
+
+流程项目测试失败时，优先看 **`_run/*.last-error.md`**（含错误分类：缺上游变量、配置缺失、代码错误等）。
+
+---
+
+## 6. 相关文档
+
+- [流程变量系统指南](./variables-guide.md) — 变量模型与代码示例  
+- [数据流程项目开发指南](./flow-project-guide.md) — debug_run_id、开发循环  
+- [节点代码编写指南](./node-code-guide.md) — 单节点脚本约定  

package/dist/docs/flow/source-guide.md

@@ -0,0 +1,44 @@
+# 数据源管理
+
+**文档 ID**: `flow/source-guide`
+
+## 列出数据源
+
+```bash
+dazi-flow source list
+dazi-flow source list --space <space-id>
+```
+
+## 查看数据源中的表
+
+```bash
+dazi-flow source tables <source-id>
+
+# 过滤 schema
+dazi-flow source tables <source-id> --schema public
+```
+
+## 查看表结构
+
+```bash
+dazi-flow source table-structure <source-id> <table-name>
+```
+
+输出示例：
+```
+表: public.orders
+列名                             类型                 可空   说明
+────────────────────────────────────────────────────────────────
+  id                             bigint               false  主键
+  user_id                        bigint               false  用户ID
+  amount                         decimal(10,2)        false  金额
+  created_at                     timestamp            false  创建时间
+```
+
+## 保存表结构到工作区
+
+```bash
+dazi-flow source table-workspace <source-id> <table-name> --flow <flow-id>
+```
+
+表结构保存到 `flows/<flow-id>/data/<table-name>.schema.json`，可供 Cursor 读取作为上下文。