@dazitech/cli 3.0.0 → 3.0.2

package/dist/docs/flow/local-files-spec.md

@@ -0,0 +1,194 @@
+# 流程本地文件规范与示例
+
+**文档 ID**: `flow/local-files-spec`  
+**适用**: `项目/flow_*/流程/<名>/` 目录、AI Agent、流程设计器  
+**关联**: [AI 工作手册](./ai-workflow-playbook.md)、[数据流程项目开发指南](./flow-project-guide.md)
+
+---
+
+## 1. 三个文件的职责
+
+| 文件 | 谁维护 | 存什么 | 禁止 |
+|------|--------|--------|------|
+| **`flow.json`** | 你 / 设计器 / `node new` + 编辑 | 画布：节点 `data`（配置）、`edges`、坐标；**不含**代码正文 | 手搓 `node_uuid`；嵌入大段 SQL/Python |
+| **`flow.meta.json`** | **仅** `pull` / `node new` / `repair-meta` | `flowId`、uuid→`节点/` 映射、`codeHash`、画布指纹 | 手改后不同步 |
+| **`节点/<名>/node.info.json`** | CLI 自动生成（只读） | uuid、类型、label、配置快照 | 当真理源编辑 |
+
+**代码正文**只在 `节点/<名>/code.py` 或 `code.sql`。
+
+设计器 **「打开代码」** 读取 `flow.meta.json` 的 `dir` + `codeFile`，**不会**扫描 `节点/` 猜文件。  
+→ meta 缺条目 = 图上有节点但打不开代码（见 §6）。
+
+---
+
+## 2. 标准目录树
+
+```text
+流程/<流程名>/
+├── flow.json                 # 画布真理源（轻量，无 pythonCode/sql 正文）
+├── flow.meta.json            # 工程索引（CLI 维护）
+├── 快速启动_<流程名>.md      # pull 后生成（含一致性检查）
+├── 节点/
+│   └── Excel成本报表解析/
+│       ├── code.py           # 代码真理源
+│       └── node.info.json    # 只读派生
+├── 变量/                     # 调试 Run 派生（只读）
+└── _run/                     # 测试/运行错误（*.last-error.md）
+```
+
+---
+
+## 3. 标准示例（start → excel-python → end）
+
+### 3.1 `flow.json`（片段）
+
+```json
+{
+  "nodes": [
+    {
+      "id": "start-node",
+      "type": "custom",
+      "position": { "x": 50, "y": 250 },
+      "data": { "label": "开始", "type": "start" },
+      "deletable": false,
+      "node_uuid": "aa1ba01e-bc96-41ab-b9e4-4b42e77aaae5"
+    },
+    {
+      "id": "n-excel01",
+      "type": "custom",
+      "position": { "x": 310, "y": 250 },
+      "data": {
+        "label": "Excel成本报表解析",
+        "type": "excel-python",
+        "managed_file_id": "51853ede-9e6b-4a3a-aa7a-060cbead0862",
+        "output_variable_name": "成本统计报表"
+      },
+      "node_uuid": "d96222ce-aaa9-4050-b782-830c2f2de9eb"
+    },
+    {
+      "id": "end-node",
+      "type": "custom",
+      "position": { "x": 850, "y": 250 },
+      "data": { "label": "结束", "type": "end" },
+      "deletable": false,
+      "node_uuid": "47c53b38-6005-4d7f-9f89-7ea56dab6b38"
+    }
+  ],
+  "edges": [
+    {
+      "id": "e1",
+      "source": "start-node",
+      "sourceHandle": "r",
+      "target": "n-excel01",
+      "targetHandle": "l"
+    },
+    {
+      "id": "e2",
+      "source": "n-excel01",
+      "sourceHandle": "r",
+      "target": "end-node",
+      "targetHandle": "l"
+    }
+  ]
+}
+```
+
+要点：`type` 恒为 `custom`，业务类型在 `data.type`；`node_uuid` 必须来自平台（`pull` / `node new`）。
+
+### 3.2 `flow.meta.json`（片段）
+
+```json
+{
+  "flowId": "119",
+  "flowName": "vs-test-03",
+  "nodes": {
+    "aa1ba01e-bc96-41ab-b9e4-4b42e77aaae5": {
+      "nodeId": "start-node",
+      "nodeType": "start"
+    },
+    "d96222ce-aaa9-4050-b782-830c2f2de9eb": {
+      "nodeId": "n-excel01",
+      "nodeType": "excel-python",
+      "dir": "节点/Excel成本报表解析",
+      "codeFile": "code.py",
+      "codeLanguage": "python",
+      "codeHash": "abc123..."
+    },
+    "47c53b38-6005-4d7f-9f89-7ea56dab6b38": {
+      "nodeId": "end-node",
+      "nodeType": "end"
+    }
+  },
+  "lastPulledAt": "2026-06-03T08:37:53.126Z",
+  "graphFingerprint": "sha1:..."
+}
+```
+
+**每个代码节点**在 `nodes` 中必须有 `dir` + `codeFile`。
+
+### 3.3 `node.info.json`（片段，只读）
+
+```json
+{
+  "_readonly": "此文件由 dazi-flow 生成，仅供查看；编辑代码请改 code.py，配置改 flow.json",
+  "node_uuid": "d96222ce-aaa9-4050-b782-830c2f2de9eb",
+  "nodeId": "n-excel01",
+  "nodeType": "excel-python",
+  "label": "Excel成本报表解析",
+  "codeFile": "code.py",
+  "codeLanguage": "python",
+  "data": {
+    "label": "Excel成本报表解析",
+    "type": "excel-python",
+    "managed_file_id": "51853ede-9e6b-4a3a-aa7a-060cbead0862",
+    "output_variable_name": "成本统计报表"
+  }
+}
+```
+
+---
+
+## 4. 错误示例（勿模仿）
+
+| 现象 | 原因 |
+|------|------|
+| `flow.json` 有 3 节点，`meta.nodes` 只有 2 条 | 手改画布未 `node new` / 未 `repair-meta` |
+| 有 `节点/xxx/code.py` 但设计器打不开代码 | meta 无该 uuid 的 `dir` |
+| 多次 `project push` 平台仍无 `managed_file_id` | 用了 `push` 但未加 **`--canvas`** |
+| `node push` 无效果 | meta 无索引 → 命令 skipped |
+
+---
+
+## 5. 变更类型 → 命令
+
+| 改了什么 | 命令 |
+|----------|------|
+| `managed_file_id`、`output_variable_name`、连线、增删节点 | `dazi flow project push --dir . --canvas` |
+| `code.py` / `code.sql` | `dazi flow node push --node <uuid> --dir .` |
+| **新增代码节点** | `dazi flow node new --type <type> --dir . --label "<名>"` → 改 `flow.json` 配置 → `push --canvas` → 写 code → `node push` |
+| 目录不一致 | `dazi flow project repair-meta --dir .` → `doctor` |
+
+`project push`（**无** `--canvas`）**不会**上传 `flow.json` 配置变更。
+
+---
+
+## 6. 设计器「找不到代码」
+
+1. 执行 `dazi flow project doctor --dir .`
+2. 若 meta 缺条目：`dazi flow project repair-meta --dir .`
+3. 再在设计器点击「打开代码」
+4. **勿**在本地画布多于平台时盲目 `pull`（会覆盖 `flow.json`）
+
+---
+
+## 7. 内置示例目录
+
+扩展内置：`examples/flow/minimal-excel-python/`（`dazi docs sync` 后位于 `资源/examples/flow/`）。
+
+---
+
+## 8. 相关文档
+
+- [流程 AI 工作手册](./ai-workflow-playbook.md)
+- [一致性检查表](../guides/flow-consistency-checklist.md)
+- [节点代码编写指南](./node-code-guide.md)

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

@@ -2,7 +2,9 @@
 
 **文档 ID**: `flow/node-code-guide`  
 **适用**: `项目/flow_*/流程/<名>/节点/<节点名>/code.*`  
-**前置**: [数据流程项目开发指南](./flow-project-guide.md)、[流程变量系统指南](./variables-guide.md)、**[Flow 文档索引 §流程节点组件](./flows-guide.md#流程节点组件)**（全部可用节点）
+**前置**: **[流程本地文件规范](./local-files-spec.md)**（必读）、[数据流程项目开发指南](./flow-project-guide.md)、[流程变量系统指南](./variables-guide.md)
+
+> 设计器「打开代码」依赖 `flow.meta.json` 中该节点的 `dir`+`codeFile`。若打不开，先 `dazi flow project doctor` → `repair-meta`。
 
 ---
 
@@ -10,15 +12,15 @@
 
 > 完整 **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`） | 同上 |
+| 业务类型 `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#流程节点组件)。
 
@@ -44,13 +46,13 @@ cd "项目\flow_xxx\流程\MyFlow"
 # 2. 编辑 节点/SQL查询/code.sql 等
 
 # 3. 查看是否有本地改动
-.\scripts\dazi.ps1 flow project status
+dazi flow project status
 
 # 4. 单节点测试（会先 GET debug-run，再 POST 单节点运行）
-.\scripts\dazi.ps1 flow run node-exec --node <node_uuid> --dir .
+dazi flow run node-exec --node <node_uuid> --dir .
 
 # 5. 提交代码到平台
-.\scripts\dazi.ps1 flow node push --node <node_uuid> --dir .
+dazi flow node push --node <node_uuid> --dir .
 ```
 
 `node_uuid` 在 `flow.meta.json` → `nodes.<uuid>`，或设计器属性面板、 `node.info.json` 中查看。  
@@ -65,11 +67,11 @@ cd "项目\flow_xxx\流程\MyFlow"
 **文件**: `code.sql`  
 **画布配置**（`flow.json` → 节点 `data`）：
 
-| 类型 | 关键字段 |
-|------|----------|
-| `database-source` | `connectionId`、`output_variable_name` |
-| `dataspace-source` | `spaceId`、`output_variable_name` |
-| `sql-query` | `output_variable_name`（消费上游表变量） |
+| 类型               | 关键字段                                 |
+| ------------------ | ---------------------------------------- |
+| `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)。
 
@@ -135,14 +137,14 @@ JOIN customers c ON o.customer_id = c.customer_id;
 
 **运行时注入**
 
-| 符号 | 说明 |
-|------|------|
-| `pd` | pandas |
-| `df` | 来自入边 Parquet（整图跑时通常非空） |
-| `get_variable("名")` | 从调试 Run 读上游表（**单节点测试时优先用这个**） |
-| `set_table_output(name, df)` | 多表输出 |
-| `result_df` | 主输出 DataFrame（与 `output_variable_name` 对应） |
-| `output.print(...)` | 运行日志（**勿用裸 `print`**） |
+| 符号                         | 说明                                               |
+| ---------------------------- | -------------------------------------------------- |
+| `pd`                         | pandas                                             |
+| `df`                         | 来自入边 Parquet（整图跑时通常非空）               |
+| `get_variable("名")`         | 从调试 Run 读上游表（**单节点测试时优先用这个**）  |
+| `set_table_output(name, df)` | 多表输出                                           |
+| `result_df`                  | 主输出 DataFrame（与 `output_variable_name` 对应） |
+| `output.print(...)`          | 运行日志（**勿用裸 `print`**）                     |
 
 **单节点测试要点**
 
@@ -189,32 +191,32 @@ set_table_output("merged_preview", result_df.head(100))  # 可选附加表
 **文件**: `code.py`  
 **画布**（`flow.json` → 节点 `data`，**不是写在 code.py 里**）:
 
-| 字段 | 说明 |
-|------|------|
-| **`managed_file_id`** | 平台「文件上传管理」登记的 **UUID**（见 `资源/files/<名>_<id8>/文件信息.json` → `file_id`） |
-| **`output_variable_name`** | 主输出表变量名；**必须与** `set_table_output` 第一个参数 **完全一致** |
+| 字段                       | 说明                                                                                        |
+| -------------------------- | ------------------------------------------------------------------------------------------- |
+| **`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:/...")`、不要猜路径 |
+| 谁配置                   | 配什么                              | 禁止                                                           |
+| ------------------------ | ----------------------------------- | -------------------------------------------------------------- |
+| **`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(...)` | 运行日志 |
+| 变量                          | 说明                                                        |
+| ----------------------------- | ----------------------------------------------------------- |
+| **`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>`
+2. 或 CLI：`dazi flow managed-files list` / `managed-files pull --file-id <uuid>`
 
 **`flow.json` 示例（画布配置）**
 
@@ -348,13 +350,13 @@ result_df = pd.read_excel(excel_source_path)
 
 **注入**
 
-| 符号 | 说明 |
-|------|------|
-| `df` | 入边 Parquet；单节点时可能为空 |
-| `get_variable("名")` | 调试 Run 中的附加表 |
-| `quality_config` | 与画布 `qualityConfig` 对齐 |
-| `set_scalar_output(name, value)` | 综合分等标量 |
-| `result_df` | 质检报告表 |
+| 符号                             | 说明                           |
+| -------------------------------- | ------------------------------ |
+| `df`                             | 入边 Parquet；单节点时可能为空 |
+| `get_variable("名")`             | 调试 Run 中的附加表            |
+| `quality_config`                 | 与画布 `qualityConfig` 对齐    |
+| `set_scalar_output(name, value)` | 综合分等标量                   |
+| `result_df`                      | 质检报告表                     |
 
 **推荐**：`df.empty` 时用 `get_variable` 补主表（变量名与 `attached_variables` / 上游输出一致）。
 
@@ -364,10 +366,10 @@ result_df = pd.read_excel(excel_source_path)
 
 ## 8. 画布配置 vs 代码分工
 
-| 改什么 | 改哪里 | 怎么提交 |
-|--------|--------|----------|
-| SQL / Python 正文 | `code.sql` / `code.py` | `node push` |
-| 连线、坐标、节点增删 | `flow.json`（设计器） | `project push --canvas` |
+| 改什么                                   | 改哪里                   | 怎么提交                |
+| ---------------------------------------- | ------------------------ | ----------------------- |
+| 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` 接口。
@@ -380,10 +382,10 @@ result_df = pd.read_excel(excel_source_path)
 
 ```powershell
 # 拉取单个变量（schema + 前 10 行）到 变量/<name>.json
-.\scripts\dazi.ps1 flow variable pull --name sales_df --dir .
+dazi flow variable pull --name sales_df --dir .
 
 # 同步全部调试变量
-.\scripts\dazi.ps1 flow variable sync --dir .
+dazi flow variable sync --dir .
 ```
 
 设计器：选中节点 → 属性 **`output_variable_name`** → 点击 **📊**。

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

@@ -2,7 +2,7 @@
 
 **文档 ID**: `flow/run-guide`
 
-**命令前缀**（`dazi-work` 根）：`.\scripts\dazi.ps1 flow …`  
+**命令前缀**（`dazi-work` 根）：`dazi flow …`  
 **流程项目**：在 `项目/flow_*/流程/<名>/` 下执行，或使用 `--dir <流程目录>`。
 
 ---
@@ -13,26 +13,26 @@
 cd "项目\flow_xxx\流程\MyFlow"
 
 # 按 node_uuid 测试（CLI 内部翻译为语义 nodeId）
-.\scripts\dazi.ps1 flow run node-exec --node <node_uuid> --dir .
+dazi 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`**  
+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.*** → **测试运行节点**。
+扩展：右键 **节点/** 或 **code.\*** → **测试运行节点**。
 
 ---
 
 ## 2. 流程项目：整流程运行
 
 ```powershell
-.\scripts\dazi.ps1 flow run flow-exec --dir . --type debug
+dazi flow run flow-exec --dir . --type debug
 # preview：清空调试变量后全新运行
-.\scripts\dazi.ps1 flow run flow-exec --dir . --type preview
+dazi flow run flow-exec --dir . --type preview
 ```
 
 成功后 **`flow variable sync`** 同步全部变量到 `变量/` 目录。
@@ -48,10 +48,10 @@ cd "项目\flow_xxx\流程\MyFlow"
 
 ```powershell
 # 拉取单个变量（schema + 前 10 行）→ 变量/<name>.json
-.\scripts\dazi.ps1 flow variable pull --name sales_df --dir .
+dazi flow variable pull --name sales_df --dir .
 
 # 同步全部调试 Run 变量
-.\scripts\dazi.ps1 flow variable sync --dir .
+dazi flow variable sync --dir .
 ```
 
 设计器：节点 **`output_variable_name`** 旁 **📊** 按钮。
@@ -64,16 +64,16 @@ cd "项目\flow_xxx\流程\MyFlow"
 
 ```powershell
 # 启动 Run
-.\scripts\dazi.ps1 flow run start <flow-id> --input '{}'
+dazi flow run start <flow-id> --input '{}'
 
 # 列表
-.\scripts\dazi.ps1 flow run list <flow-id> --limit 10
+dazi flow run list <flow-id> --limit 10
 
 # 调试信息（最近 Run）
-.\scripts\dazi.ps1 flow run debug <flow-id>
+dazi flow run debug <flow-id>
 
 # 变量列表（需 --flow）
-.\scripts\dazi.ps1 flow run variables-list <runId> --flow <flow-id>
+dazi flow run variables-list <runId> --flow <flow-id>
 ```
 
 流程项目日常开发优先用 **§1–§3** 的 `node-exec` / `flow-exec` / `variable pull`。
@@ -84,7 +84,7 @@ cd "项目\flow_xxx\流程\MyFlow"
 
 ```powershell
 # 拉取 failure-bundle 落盘
-.\scripts\dazi.ps1 flow run failure --run <runId> --dir .
+dazi flow run failure --run <runId> --dir .
 ```
 
 流程项目测试失败时，优先看 **`_run/*.last-error.md`**（含错误分类：缺上游变量、配置缺失、代码错误等）。
@@ -93,6 +93,6 @@ cd "项目\flow_xxx\流程\MyFlow"
 
 ## 6. 相关文档
 
-- [流程变量系统指南](./variables-guide.md) — 变量模型与代码示例  
-- [数据流程项目开发指南](./flow-project-guide.md) — debug_run_id、开发循环  
-- [节点代码编写指南](./node-code-guide.md) — 单节点脚本约定  
+- [流程变量系统指南](./variables-guide.md) — 变量模型与代码示例
+- [数据流程项目开发指南](./flow-project-guide.md) — debug_run_id、开发循环
+- [节点代码编写指南](./node-code-guide.md) — 单节点脚本约定