@dazitech/cli 3.0.0 → 3.0.1

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

@@ -7,15 +7,16 @@
 
 ## 1. 定位与核心约定
 
-| 维度 | 说明 |
-|------|------|
-| CLI 入口 | `.\scripts\dazi.ps1 flow …` → `dazi-flow`（Trae / VS Code / Cursor 交付环境） |
-| 工作区 | `dazi-work` + `项目/flow_<名>/` |
-| 本地流程树 | `流程/<名>/flow.json` + `节点/<名>/code.*` |
-| 画布真理源 | **`flow.json`**（= 平台 `config_json` 镜像，代码已剥离） |
-| 代码真理源 | **`节点/<名>/code.sql|py`** + `node push` |
-| 主交互 | **资源管理器右键** + MVP 流程设计器 |
-| AI | **Cursor 侧读文件** + `dazi-flow mcp` |
+| 维度       | 说明                                                            |
+| ---------- | --------------------------------------------------------------- | ------------------- |
+| CLI 入口   | `dazi flow …` → `dazi-flow`（Trae / VS Code / Cursor 交付环境） |
+| **本地文件** | **[流程本地文件规范](./local-files-spec.md)**（AI 必读） |
+| 工作区     | `dazi-work` + `项目/flow_<名>/`                                 |
+| 本地流程树 | `流程/<名>/flow.json` + `节点/<名>/code.*`                      |
+| 画布真理源 | **`flow.json`**（= 平台 `config_json` 镜像，代码已剥离）        |
+| 代码真理源 | \*\*`节点/<名>/code.sql                                         | py`** + `node push` |
+| 主交互     | **资源管理器右键** + MVP 流程设计器                             |
+| AI         | **Cursor 侧读文件** + `dazi-flow mcp`                           |
 
 API 根路径：**`{serverUrl}/api/data-pipelines/v1`**（搭子数据流程引擎）。
 
@@ -36,7 +37,7 @@ dazi-work/
             └── 客户数据清洗/          ← 一个流程 = 一个目录
                 ├── 快速启动_<流程名>.md   pull 后生成（flowId、常用命令、AI 单文件入口）
                 ├── flow.json          ★ 画布（节点配置 + 边，不含代码正文）
-                ├── flow.meta.json     flowId、uuid 映射、代码指纹
+                ├── flow.meta.json     flowId、uuid 映射、代码指纹（pull / node new / repair-meta 维护，勿手改）
                 ├── 节点/
                 │   └── SQL查询/
                 │       ├── code.sql   ★ 代码唯一真理源
@@ -55,12 +56,12 @@ dazi-work/
 
 ---
 
-## 3. CLI 怎么跑：`dazi.ps1` 与 `dazi-flow`
+## 3. CLI 怎么跑：全局 `dazi` 与 bundled
 
 ### 3.1 调用链（Trae / VS Code / Cursor 交付环境）
 
 ```text
-.\scripts\dazi.ps1 flow <子命令...>
+dazi flow <子命令...>
         │
         ▼  node bundled/clis/dazi.js
         │  （设置 DAZI_BUNDLED_DIR，cwd = dazi-work 根）
@@ -68,33 +69,33 @@ dazi-work/
    forward → node bundled/clis/dazi-flow.js <子命令...>
 ```
 
-- **没有**全局 `dazi-flow` 命令；与本体一致，统一走 **`.\scripts\dazi.ps1`**。
+- **没有**全局 `dazi-flow` 命令；与本体一致，统一走 **`dazi`**。
 - 扩展侧栏/右键菜单与上述 CLI **同源**（同一套 bundled `dazi-flow.js`）。
-- 首次使用：在 **`dazi-work` 根**执行 `.\scripts\doctor-cli.ps1` → `.\scripts\dazi.ps1 auth login`。
+- 首次使用：在 **`dazi-work` 根**执行 `.\scripts\doctor-cli.ps1` → `dazi auth login`。
 
 ### 3.2 命令写法对照
 
-| 文档/扩展内部 | 在 `dazi-work` 根目录终端 |
-|---------------|---------------------------|
-| `dazi-flow project pull …` | `.\scripts\dazi.ps1 flow project pull …` |
-| `dazi-flow node push …` | `.\scripts\dazi.ps1 flow node push …` |
-| `dazi-flow run node-exec …` | `.\scripts\dazi.ps1 flow run node-exec …` |
-| `dazi-flow variable pull …` | `.\scripts\dazi.ps1 flow variable pull …` |
+| 文档/扩展内部               | 在 `dazi-work` 根目录终端   |
+| --------------------------- | --------------------------- |
+| `dazi-flow project pull …`  | `dazi flow project pull …`  |
+| `dazi-flow node push …`     | `dazi flow node push …`     |
+| `dazi-flow run node-exec …` | `dazi flow run node-exec …` |
+| `dazi-flow variable pull …` | `dazi flow variable pull …` |
 
 **工作目录技巧**：多数命令支持 `--dir <流程目录>`。也可 **`cd` 到流程目录**后省略 `--dir`（cwd 即 `流程/<名>/`）。
 
 ```powershell
 # 在 dazi-work 根
 cd D:\path\to\dazi-work
-.\scripts\dazi.ps1 auth whoami
+dazi auth whoami
 
 # 拉取平台流程到本地（首次）
-.\scripts\dazi.ps1 flow project pull --flow 98 --dir "项目\flow_流程项目01\流程\MyFlow0529"
+dazi flow project pull --flow 98 --dir "项目\flow_流程项目01\流程\MyFlow0529"
 
 # 进入流程目录后，后续命令可省略 --dir
 cd "项目\flow_流程项目01\流程\MyFlow0529"
-.\scripts\dazi.ps1 flow project status
-.\scripts\dazi.ps1 flow node push --node <node_uuid>
+dazi flow project status
+dazi flow node push --node <node_uuid>
 ```
 
 **常用子命令速查**（拉取 / 提交 / 测试 / 变量等）见 [Flow 文档索引 · 流程项目常用命令](./flows-guide.md#流程项目flow_-常用命令)。Plan、数据源等专题见 [执行计划](./plan-guide.md)、[数据源管理](./source-guide.md)。
@@ -138,27 +139,31 @@ cd "项目\flow_流程项目01\流程\MyFlow0529"
 
 ## 5. 同步策略（pull / push）
 
-| 操作 | API / 行为 |
-|------|------------|
-| **pull** | `GET /flows/{id}/snapshot` 一次拿全 → 拆成 `flow.json` + `节点/*/code.*` + `flow.meta.json` |
-| **push 代码** | 仅脏节点：`PATCH /flows/{id}/flow-nodes/{uuid}`（乐观锁 `expected_version`） |
-| **push 画布** | `PUT /flows/{id}` body `{ data: 完整 document }`（`--canvas`） |
-| **status** | 本地 `code.*` 的 sha1 与 meta 中 `codeHash` 比对 |
+| 操作          | API / 行为                                                                                  |
+| ------------- | ------------------------------------------------------------------------------------------- |
+| **pull**      | `GET /flows/{id}/snapshot` 一次拿全 → 拆成 `flow.json` + `节点/*/code.*` + `flow.meta.json` |
+| **push 代码** | 仅脏节点：`PATCH /flows/{id}/flow-nodes/{uuid}`（乐观锁 `expected_version`）                |
+| **push 画布** | `PUT /flows/{id}` body `{ data: 完整 document }`（`--canvas`）                              |
+| **status**    | 本地 `code.*` 的 sha1 与 meta 中 `codeHash` 比对                                            |
+| **doctor**    | 检查 `flow.json` / `flow.meta.json` / `节点/` 一致性                                        |
+| **repair-meta** | 按 `flow.json` 与 `节点/` 重建 meta 索引；并刷新 `快速启动_*.md`                          |
 
-冲突时：先 **拉取** 或 **`node push --force`**（慎用覆盖）。
+冲突时：先 **拉取** 或 **`node push --force`**（慎用覆盖）。**本地节点多于平台时勿 pull**，应先 `push --canvas`。
+
+`pull` 前若 doctor 报错会打印警告；拉取后若平台节点少于本地会提示可能已覆盖手改画布。
 
 ---
 
 ## 6. 资源管理器菜单（主交互）
 
-| 右键对象 | 常用命令 |
-|----------|----------|
-| `flow.json` / 流程目录 | 打开设计器、拉取、**提交**、状态、运行整流程 |
-| `节点/<名>/` | 打开代码、拉取/提交节点、**测试运行** |
-| `节点/<名>/code.*` | 提交、测试、拉取 |
-| `变量/` | 同步变量到本地 |
-| `变量/<名>.json` | 刷新变量、查看变量信息 |
-| `项目/flow_*` | 新建流程、拉取平台流程 |
+| 右键对象                    | 常用命令                                               |
+| --------------------------- | ------------------------------------------------------ |
+| `flow.json` / 流程目录      | 打开设计器、拉取、**提交**、状态、**doctor**、**修复 meta**、运行整流程 |
+| `节点/<名>/`                | 打开代码、拉取/提交节点、**测试运行**                  |
+| `节点/<名>/code.*`          | 提交、测试、拉取                                       |
+| `变量/`                     | 同步变量到本地                                         |
+| `变量/<名>.json`            | 刷新变量、查看变量信息                                 |
+| `项目/flow_*`               | 新建流程、拉取平台流程                                 |
 | **数据资源 → 文件上传管理** | 浏览平台登记文件、**拉取到本地资源**、复制 AI 附加说明 |
 
 设计器工具栏：**保存 / 校验 / 运行 / 提交 / 拉取**。
@@ -187,9 +192,9 @@ dazi-work/资源/files/<显示名>_<fileId前8位>/
 CLI 等价命令：
 
 ```powershell
-.\scripts\dazi.ps1 flow managed-files list
-.\scripts\dazi.ps1 flow managed-files dirs --path excel
-.\scripts\dazi.ps1 flow managed-files pull --file-id <uuid> --relative-dir excel
+dazi flow managed-files list
+dazi flow managed-files dirs --path excel
+dazi flow managed-files pull --file-id <uuid> --relative-dir excel
 ```
 
 ---
@@ -202,15 +207,15 @@ Web 端 `@xyflow/react` 与 VS Code MVP 设计器共用同一套 **`flow.json`
 
 ### 6.2.1 节点尺寸与布局
 
-| 项 | 规范值 | 说明 |
-|----|--------|------|
-| 最小宽度 | **200px** | 对齐 Web `CustomNode` 的 `min-w-[200px]` |
-| 典型高度 | **约 88px** | header（约 36px）+ body（约 52px）；内容多时会增高 |
-| 边框 / 圆角 | 2px / 8px | 与系统设计器一致 |
-| 锚点直径 | **12px** | 对应 Tailwind `w-3 h-3` |
-| 横向间距 | **≥ 260px** | 相邻节点 `position.x` 差值，避免 200px 宽节点重叠 |
-| 纵向间距 | **≥ 140px** | 相邻节点 `position.y` 差值 |
-| 首节点参考坐标 | `x: 80, y: 80` | 从左上网格起点排布 |
+| 项             | 规范值         | 说明                                               |
+| -------------- | -------------- | -------------------------------------------------- |
+| 最小宽度       | **200px**      | 对齐 Web `CustomNode` 的 `min-w-[200px]`           |
+| 典型高度       | **约 88px**    | header（约 36px）+ body（约 52px）；内容多时会增高 |
+| 边框 / 圆角    | 2px / 8px      | 与系统设计器一致                                   |
+| 锚点直径       | **12px**       | 对应 Tailwind `w-3 h-3`                            |
+| 横向间距       | **≥ 260px**    | 相邻节点 `position.x` 差值，避免 200px 宽节点重叠  |
+| 纵向间距       | **≥ 140px**    | 相邻节点 `position.y` 差值                         |
+| 首节点参考坐标 | `x: 80, y: 80` | 从左上网格起点排布                                 |
 
 **结构**：每个节点为 **header（标题）+ body（状态摘要）** 双层；`position` 为节点**左上角**在画布上的像素坐标。
 
@@ -227,13 +232,13 @@ Web 端 `@xyflow/react` 与 VS Code MVP 设计器共用同一套 **`flow.json`
 
 锚点 ID 写入边的 **`sourceHandle`**（输出端）与 **`targetHandle`**（输入端）。**必须显式填写**，不要省略后依赖推断。
 
-| 锚点 ID | 节点上的位置 | 角色 | 用于 |
-|---------|--------------|------|------|
-| `l` | 左侧中点 | **输入**（target） | 常规入边（最常见） |
-| `t` | 顶部中点 | **输入**（target） | 自下方节点连入 |
-| `r` | 右侧中点 | **输出**（source） | 常规出边（最常见） |
-| `b` | 底部中点 | **输出**（source） | 连到下方节点 |
-| `true` | 右侧 **30%** 高度 | **输出**（source） | **仅** `condition` 节点 True 分支 |
+| 锚点 ID | 节点上的位置      | 角色               | 用于                               |
+| ------- | ----------------- | ------------------ | ---------------------------------- |
+| `l`     | 左侧中点          | **输入**（target） | 常规入边（最常见）                 |
+| `t`     | 顶部中点          | **输入**（target） | 自下方节点连入                     |
+| `r`     | 右侧中点          | **输出**（source） | 常规出边（最常见）                 |
+| `b`     | 底部中点          | **输出**（source） | 连到下方节点                       |
+| `true`  | 右侧 **30%** 高度 | **输出**（source） | **仅** `condition` 节点 True 分支  |
 | `false` | 右侧 **70%** 高度 | **输出**（source） | **仅** `condition` 节点 False 分支 |
 
 **合法组合**
@@ -246,14 +251,14 @@ Web 端 `@xyflow/react` 与 VS Code MVP 设计器共用同一套 **`flow.json`
 
 **常用拓扑与锚点配对**
 
-| 场景 | sourceHandle | targetHandle |
-|------|--------------|--------------|
-| 左 → 右（主流水线） | `r` | `l` |
-| 上 → 下 | `b` | `t` |
-| 右 → 下 | `r` | `t` |
-| 下 → 左 | `b` | `l` |
-| 条件 True 分支 | `true` | `l` 或 `t` |
-| 条件 False 分支 | `false` | `l` 或 `t` |
+| 场景                | sourceHandle | targetHandle |
+| ------------------- | ------------ | ------------ |
+| 左 → 右（主流水线） | `r`          | `l`          |
+| 上 → 下             | `b`          | `t`          |
+| 右 → 下             | `r`          | `t`          |
+| 下 → 左             | `b`          | `l`          |
+| 条件 True 分支      | `true`       | `l` 或 `t`   |
+| 条件 False 分支     | `false`      | `l` 或 `t`   |
 
 **边 `id` 命名**（与 React Flow 一致，便于 diff）：
 
@@ -265,12 +270,12 @@ xy-edge__{source节点id}{sourceHandle}-{target节点id}{targetHandle}
 
 ### 6.2.3 各类节点锚点一览
 
-| `data.type` | 输入 `l`/`t` | 输出 `r`/`b` | 输出 `true`/`false` | 备注 |
-|-------------|:------------:|:------------:|:-------------------:|------|
-| `start` | — | `r`, `b` | — | 无入边；语义 id 常为 `start-node` |
-| `end` | `l`, `t` | — | — | 无出边；语义 id 常为 `end-node` |
-| `condition` | `l`, `t` | — | **`true`, `false`** | **不用** `r`/`b` |
-| 其他业务节点 | `l`, `t` | `r`, `b` | — | 如 `sql-query`、`python-script` 等 |
+| `data.type`  | 输入 `l`/`t` | 输出 `r`/`b` | 输出 `true`/`false` | 备注                               |
+| ------------ | :----------: | :----------: | :-----------------: | ---------------------------------- |
+| `start`      |      —       |   `r`, `b`   |          —          | 无入边；语义 id 常为 `start-node`  |
+| `end`        |   `l`, `t`   |      —       |          —          | 无出边；语义 id 常为 `end-node`    |
+| `condition`  |   `l`, `t`   |      —       | **`true`, `false`** | **不用** `r`/`b`                   |
+| 其他业务节点 |   `l`, `t`   |   `r`, `b`   |          —          | 如 `sql-query`、`python-script` 等 |
 
 画布上节点 **`type` 恒为 `"custom"`**，业务类型在 **`data.type`**。
 
@@ -483,23 +488,23 @@ VS Code **打开流程设计器**（右键 `flow.json`）时：
 
 ## 8. 相关文档
 
-| 文档 | 内容 |
-|------|------|
-| [流程变量系统指南](./variables-guide.md) | 变量模型、`output_variable_name`、各节点读写变量与代码示例 |
-| [节点代码编写指南](./node-code-guide.md) | `python-script`、`sql-query` 等单节点代码约定 |
-| [Flow 运行与测试](./run-guide.md) | `node-exec`、`flow-exec`、变量命令 |
-| [CLI 调用约定](../guides/cli-invocation.md) | `dazi.ps1`、Trae 扩展路径、doctor |
-| [CLI 命令速查](../guides/cli-reference.md) | 完整命令表 |
-| [Flow 管理入门](./flows-guide.md) | 文档索引、**AI 创建流程速查**、平台级 Flow 操作 |
+| 文档                                        | 内容                                                       |
+| ------------------------------------------- | ---------------------------------------------------------- |
+| [流程变量系统指南](./variables-guide.md)    | 变量模型、`output_variable_name`、各节点读写变量与代码示例 |
+| [节点代码编写指南](./node-code-guide.md)    | `python-script`、`sql-query` 等单节点代码约定              |
+| [Flow 运行与测试](./run-guide.md)           | `node-exec`、`flow-exec`、变量命令                         |
+| [CLI 调用约定](../guides/cli-invocation.md) | `dazi.ps1`、Trae 扩展路径、doctor                          |
+| [CLI 命令速查](../guides/cli-reference.md)  | 完整命令表                                                 |
+| [Flow 管理入门](./flows-guide.md)           | 文档索引、**AI 创建流程速查**、平台级 Flow 操作            |
 
 ---
 
 ## 9. 常见问题
 
-| 现象 | 处理 |
-|------|------|
-| `dazi-flow` 找不到 | 使用 `.\scripts\dazi.ps1 flow …`，运行 `doctor-cli.ps1` |
-| 提交 HTTP 405 | 画布提交须 `PUT /flows/{id}`，用 `project push --canvas`，勿对 `apply-patch` 发 PUT |
-| 变量查看失败 | 先 **测试节点** 或 **运行流程**；确认 `flow.meta.json` 有 `flowId` |
-| 节点测试报缺上游变量 | 先运行上游节点，或 **运行整流程（debug）** 再测当前节点 |
-| 代码改了平台没更新 | `node push` 或 `project push`；看 `project status` 是否脏 |
+| 现象                 | 处理                                                                                |
+| -------------------- | ----------------------------------------------------------------------------------- |
+| `dazi-flow` 找不到   | 使用 `dazi flow …`，运行 `doctor-cli.ps1`                                           |
+| 提交 HTTP 405        | 画布提交须 `PUT /flows/{id}`，用 `project push --canvas`，勿对 `apply-patch` 发 PUT |
+| 变量查看失败         | 先 **测试节点** 或 **运行流程**；确认 `flow.meta.json` 有 `flowId`                  |
+| 节点测试报缺上游变量 | 先运行上游节点，或 **运行整流程（debug）** 再测当前节点                             |
+| 代码改了平台没更新   | `node push` 或 `project push`；看 `project status` 是否脏                           |

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

@@ -9,13 +9,15 @@
 
 ## 推荐阅读顺序
 
-1. [数据流程项目开发指南](./flow-project-guide.md) — 目录结构、`dazi.ps1 flow`、菜单、pull/push 循环
+0. **[流程本地文件规范](./local-files-spec.md)** — **AI 必读**：`flow.json` / `flow.meta.json` / `node.info.json` 职责与标准示例  
+0.1 [流程 AI 工作手册](./ai-workflow-playbook.md) — 一分钟决策树与禁止清单  
+1. [数据流程项目开发指南](./flow-project-guide.md) — 目录结构、`dazi flow`、菜单、pull/push 循环
 2. **[画布节点与连线规范](./flow-project-guide.md#62-画布节点与连线规范ai-创建--编辑-flowjson-必读)** — **AI 创建流程必读**：节点尺寸 200px、锚点 `l/t/r/b/true/false`、条件分支
 3. [流程开发最佳实践（VS-flow0 案例）](./流程开发最佳实践-VS-flow0案例.md) — **端到端案例**：Excel → 质检 → SQL → 落库、五阶段开发法、检查表
 4. [流程变量系统指南](./variables-guide.md) — 变量模型、`output_variable_name`、代码节点如何用变量
 5. [节点代码编写指南](./node-code-guide.md) — `python-script`、`sql-query` 等单节点代码
 6. [Flow 运行与测试](./run-guide.md) — 单节点/整流程运行、变量
-7. [CLI 调用约定](../guides/cli-invocation.md) — `.\scripts\dazi.ps1` 在 Trae/VS Code 中的用法
+7. [CLI 调用约定](../guides/cli-invocation.md) — `dazi` 在 Trae/VS Code 中的用法
 
 ---
 
@@ -24,14 +26,14 @@
 在 **`dazi-work` 根目录**（Trae、VS Code、Cursor 交付环境）：
 
 ```powershell
-.\scripts\dazi.ps1 flow <子命令...>
+dazi flow <子命令...>
 ```
 
 等价于开发时的 `dazi-flow <子命令...>`。示例：
 
 ```powershell
-.\scripts\dazi.ps1 flow flows list
-.\scripts\dazi.ps1 flow project pull --flow 98 --dir "项目\flow_xxx\流程\MyFlow"
+dazi flow flows list
+dazi flow project pull --flow 98 --dir "项目\flow_xxx\流程\MyFlow"
 ```
 
 ---
@@ -42,6 +44,8 @@
 | ------------------ | --------------------------------------------------- |
 | 拉取平台流程到本地 | `flow project pull --flow <id> --dir <流程目录>`    |
 | 提交代码 + 画布    | `flow project push --dir <流程目录> --canvas`       |
+| 目录一致性检查     | `flow project doctor --dir <流程目录>`              |
+| 修复 meta 索引     | `flow project repair-meta --dir <流程目录>`         |
 | 查看本地改动       | `flow project status --dir <流程目录>`              |
 | 提交单个节点代码   | `flow node push --node <uuid> --dir <流程目录>`     |
 | 单节点测试         | `flow run node-exec --node <uuid> --dir <流程目录>` |
@@ -87,46 +91,46 @@
 新建节点（在流程目录）：
 
 ```powershell
-.\scripts\dazi.ps1 flow node new --type <data.type> --dir . --label "<显示名>"
+dazi flow node new --type <data.type> --dir . --label "<显示名>"
 ```
 
 ### 总览
 
-| 分组 | `data.type` | 名称 | 代码文件 | 典型用途 |
-|------|-------------|------|----------|----------|
-| 流程控制 | `condition` | 条件判断 | `code.py` | 布尔分支，出边 `true`/`false` |
-| 流程控制 | `delay` | 延时等待 | — | 暂停 N 秒 |
-| 数据处理 | `file-source` | 文件输入 | — | 托管/上传文件 → 表变量 |
-| 数据处理 | `excel-import` | Excel 导入 | — | 单 Sheet 简单导入 |
-| 数据处理 | `excel-python` | Excel 开发 | `code.py` | 多 Sheet、复杂表头 |
-| 数据处理 | `sql-query` | SQL 查询 | `code.sql` | DuckDB 内存 SQL，上游变量作表名 |
-| 数据处理 | `python-script` | Python 脚本 | `code.py` | pandas 转换（最常用） |
-| 数据处理 | `database-source` | 数据库读取 | `code.sql` | 外部库只读（`connectionId`） |
-| 数据处理 | `database-sink` | 数据库写入 | — | 表变量 → 外部库表 |
-| 数据处理 | `dataspace-source` | 数据空间读取 | `code.sql` | 空间只读（`spaceId`） |
-| 数据处理 | `dataspace-sink` | 数据空间写入 | — | 表变量 → 空间表 |
-| 数据处理 | `data-quality-check` | 数据质量检查 | `code.py` | 规则或自定义质检脚本 |
-| 数据处理 | `folder-resource-import` | 文件夹资源导入 | — | 文件夹批量导入 |
-| 数据处理 | `folder-resource-register` | 资源注册 | — | 注册到连接/目录 |
+| 分组     | `data.type`                | 名称           | 代码文件   | 典型用途                        |
+| -------- | -------------------------- | -------------- | ---------- | ------------------------------- |
+| 流程控制 | `condition`                | 条件判断       | `code.py`  | 布尔分支，出边 `true`/`false`   |
+| 流程控制 | `delay`                    | 延时等待       | —          | 暂停 N 秒                       |
+| 数据处理 | `file-source`              | 文件输入       | —          | 托管/上传文件 → 表变量          |
+| 数据处理 | `excel-import`             | Excel 导入     | —          | 单 Sheet 简单导入               |
+| 数据处理 | `excel-python`             | Excel 开发     | `code.py`  | 多 Sheet、复杂表头              |
+| 数据处理 | `sql-query`                | SQL 查询       | `code.sql` | DuckDB 内存 SQL，上游变量作表名 |
+| 数据处理 | `python-script`            | Python 脚本    | `code.py`  | pandas 转换（最常用）           |
+| 数据处理 | `database-source`          | 数据库读取     | `code.sql` | 外部库只读（`connectionId`）    |
+| 数据处理 | `database-sink`            | 数据库写入     | —          | 表变量 → 外部库表               |
+| 数据处理 | `dataspace-source`         | 数据空间读取   | `code.sql` | 空间只读（`spaceId`）           |
+| 数据处理 | `dataspace-sink`           | 数据空间写入   | —          | 表变量 → 空间表                 |
+| 数据处理 | `data-quality-check`       | 数据质量检查   | `code.py`  | 规则或自定义质检脚本            |
+| 数据处理 | `folder-resource-import`   | 文件夹资源导入 | —          | 文件夹批量导入                  |
+| 数据处理 | `folder-resource-register` | 资源注册       | —          | 注册到连接/目录                 |
 
 ### 流程控制
 
 #### `condition` — 条件判断
 
-| 项 | 说明 |
-|----|------|
-| 代码 | `节点/<名>/code.py`（布尔表达式，运行时 eval） |
-| 入边 | 至少一条；上游表注入为 **`df`** |
-| 出边 | **`sourceHandle: "true"`** / **`"false"`**（禁止用 `r`/`b`） |
-| 变量 | 不产生新表，仅路由 |
+| 项   | 说明                                                                       |
+| ---- | -------------------------------------------------------------------------- |
+| 代码 | `节点/<名>/code.py`（布尔表达式，运行时 eval）                             |
+| 入边 | 至少一条；上游表注入为 **`df`**                                            |
+| 出边 | **`sourceHandle: "true"`** / **`"false"`**（禁止用 `r`/`b`）               |
+| 变量 | 不产生新表，仅路由                                                         |
 | 详见 | [flow-project-guide §6.2.4](./flow-project-guide.md#624-条件节点condition) |
 
 #### `delay` — 延时等待
 
-| 项 | 说明 |
-|----|------|
+| 项   | 说明                                 |
+| ---- | ------------------------------------ |
 | 配置 | `data.delaySeconds` 或 `delay`（秒） |
-| 变量 | 无 |
+| 变量 | 无                                   |
 
 ### 数据输入 / 读取
 
@@ -134,11 +138,11 @@
 
 数据源来自 **文件上传管理**（有 `file_id` / `managed_file_id`）且文件为 **`.xlsx` / `.xls`** 时：
 
-| 优先级 | 节点 | 说明 |
-|:------:|------|------|
+|    优先级     | 节点               | 说明                                                                                          |
+| :-----------: | ------------------ | --------------------------------------------------------------------------------------------- |
 | **1（默认）** | **`excel-python`** | **优先使用**。可控制 Sheet、表头行、列范围、多表 `set_table_output`；画布配 `managed_file_id` |
-| 2 | `excel-import` | 仅当 **单 Sheet、第 1 行即标准表头、无需任何解析逻辑** 时 |
-| **禁止** | `file-source` | **不要**用 file-source 读 Excel——它只做原始文件透传，**不会**解析为表变量 |
+|       2       | `excel-import`     | 仅当 **单 Sheet、第 1 行即标准表头、无需任何解析逻辑** 时                                     |
+|   **禁止**    | `file-source`      | **不要**用 file-source 读 Excel——它只做原始文件透传，**不会**解析为表变量                     |
 
 ```text
 有 managed_file_id + Excel  →  excel-python（默认）
@@ -150,114 +154,114 @@ CSV / Parquet / 非 Excel     →  file-source 或其他专用节点
 
 #### `file-source` — 文件输入
 
-| 项 | 说明 |
-|----|------|
-| 何时用 | **非 Excel** 的原始文件透传（CSV、Parquet 等已登记文件） |
+| 项         | 说明                                                     |
+| ---------- | -------------------------------------------------------- |
+| 何时用     | **非 Excel** 的原始文件透传（CSV、Parquet 等已登记文件） |
 | **勿用于** | **`.xlsx` / `.xls`** → 改用 **`excel-python`**（见上表） |
-| 配置 | `file_id` / `managed_file_id`、`output_variable_name` |
-| 产出 | 原始文件路径对应的表变量（**不解析 Excel**） |
+| 配置       | `file_id` / `managed_file_id`、`output_variable_name`    |
+| 产出       | 原始文件路径对应的表变量（**不解析 Excel**）             |
 
 #### `excel-import` — Excel 导入（简单）
 
-| 项 | 说明 |
-|----|------|
-| 何时用 | **单 Sheet、第 1 行标准表头、零自定义逻辑** 的极少数场景 |
+| 项       | 说明                                                                         |
+| -------- | ---------------------------------------------------------------------------- |
+| 何时用   | **单 Sheet、第 1 行标准表头、零自定义逻辑** 的极少数场景                     |
 | 默认建议 | 有 `managed_file_id` 的 Excel **优先 `excel-python`**，便于后续改 Sheet/表头 |
-| 配置 | `file_id` / `source_excel_id`、`sheetName`（可选）、`output_variable_name` |
-| 产出 | 表变量（如 `excel_raw`） |
+| 配置     | `file_id` / `source_excel_id`、`sheetName`（可选）、`output_variable_name`   |
+| 产出     | 表变量（如 `excel_raw`）                                                     |
 
 #### `excel-python` — Excel 开发（Excel 默认首选）
 
-| 项 | 说明 |
-|----|------|
-| 何时用 | **凡 `.xlsx`/`.xls` 且已有 `managed_file_id` 时优先本节点**；多 Sheet、非标准表头、需清洗/拆表 |
-| 画布配置 | **`managed_file_id`**（UUID，来自文件上传管理 / `文件信息.json` 的 `file_id`） |
-| 代码 | `code.py` 内 **只读 `excel_source_path`**（引擎注入），**禁止**写文件名或本地路径 |
-| 产出 | **`set_table_output(变量名, df)`**；主表名 **= `output_variable_name`** |
-| 详见 | [node-code-guide §5 excel-python](./node-code-guide.md#5-excel-pythonexcel-开发)（含完整示例与反例） |
+| 项       | 说明                                                                                                 |
+| -------- | ---------------------------------------------------------------------------------------------------- |
+| 何时用   | **凡 `.xlsx`/`.xls` 且已有 `managed_file_id` 时优先本节点**；多 Sheet、非标准表头、需清洗/拆表       |
+| 画布配置 | **`managed_file_id`**（UUID，来自文件上传管理 / `文件信息.json` 的 `file_id`）                       |
+| 代码     | `code.py` 内 **只读 `excel_source_path`**（引擎注入），**禁止**写文件名或本地路径                    |
+| 产出     | **`set_table_output(变量名, df)`**；主表名 **= `output_variable_name`**                              |
+| 详见     | [node-code-guide §5 excel-python](./node-code-guide.md#5-excel-pythonexcel-开发)（含完整示例与反例） |
 
 #### `database-source` — 数据库读取
 
-| 项 | 说明 |
-|----|------|
-| 代码 | `code.sql`（SELECT，直连外部库） |
-| 配置 | **`connectionId`**（`ads_connections.id`）、`output_variable_name` |
-| 消费 | **不**消费 Run 内变量 |
+| 项   | 说明                                                                                                         |
+| ---- | ------------------------------------------------------------------------------------------------------------ |
+| 代码 | `code.sql`（SELECT，直连外部库）                                                                             |
+| 配置 | **`connectionId`**（`ads_connections.id`）、`output_variable_name`                                           |
+| 消费 | **不**消费 Run 内变量                                                                                        |
 | 详见 | [source-guide](./source-guide.md)、[variables-guide §6.2](./variables-guide.md#62-database-source外部库只读) |
 
 #### `dataspace-source` — 数据空间读取
 
-| 项 | 说明 |
-|----|------|
-| 代码 | `code.sql` |
-| 配置 | **`spaceId`**、`output_variable_name`、`limit`（可选） |
-| 消费 | **不**消费 Run 内变量 |
+| 项   | 说明                                                                           |
+| ---- | ------------------------------------------------------------------------------ |
+| 代码 | `code.sql`                                                                     |
+| 配置 | **`spaceId`**、`output_variable_name`、`limit`（可选）                         |
+| 消费 | **不**消费 Run 内变量                                                          |
 | 详见 | [variables-guide §6.2b](./variables-guide.md#62b-dataspace-source数据空间只读) |
 
 ### 数据加工
 
 #### `sql-query` — SQL 查询
 
-| 项 | 说明 |
-|----|------|
-| 代码 | `code.sql` |
-| 消费 | 上游 **`output_variable_name` 作 SQL 表名**（`FROM 上游变量名`） |
-| 产出 | `output_variable_name` |
-| 注意 | 单节点测试前须先跑上游；SQL 末尾勿加分号 |
+| 项   | 说明                                                                     |
+| ---- | ------------------------------------------------------------------------ |
+| 代码 | `code.sql`                                                               |
+| 消费 | 上游 **`output_variable_name` 作 SQL 表名**（`FROM 上游变量名`）         |
+| 产出 | `output_variable_name`                                                   |
+| 注意 | 单节点测试前须先跑上游；SQL 末尾勿加分号                                 |
 | 详见 | [variables-guide §6.1](./variables-guide.md#61-sql-queryduckdb-内存-sql) |
 
 #### `python-script` — Python 脚本
 
-| 项 | 说明 |
-|----|------|
-| 代码 | `code.py` |
-| 消费 | **`get_variable("上游变量名")`**（单节点测试首选）或入边 `df` |
-| 产出 | **`result_df`** → `output_variable_name` |
+| 项   | 说明                                                                                                         |
+| ---- | ------------------------------------------------------------------------------------------------------------ |
+| 代码 | `code.py`                                                                                                    |
+| 消费 | **`get_variable("上游变量名")`**（单节点测试首选）或入边 `df`                                                |
+| 产出 | **`result_df`** → `output_variable_name`                                                                     |
 | 详见 | [variables-guide §6.3](./variables-guide.md#63-python-script最常用)、[node-code-guide](./node-code-guide.md) |
 
 #### `data-quality-check` — 数据质量检查
 
-| 项 | 说明 |
-|----|------|
+| 项   | 说明                                                 |
+| ---- | ---------------------------------------------------- |
 | 代码 | `code.py`（平台键 `dqPythonCode`；非空时优先于规则） |
-| 配置 | `qualityConfig`、`output_variable_name` |
-| 消费 | 上游表 / `get_variable` |
-| 典型 | 与 **`condition`** 组合做合格/不合格分支 |
+| 配置 | `qualityConfig`、`output_variable_name`              |
+| 消费 | 上游表 / `get_variable`                              |
+| 典型 | 与 **`condition`** 组合做合格/不合格分支             |
 
 ### 数据输出 / 写入
 
 #### `database-sink` — 数据库写入
 
-| 项 | 说明 |
-|----|------|
-| 代码 | 无 |
-| 配置 | **`connectionId`**、**`tableName`**、**`input_variable_name`**、`mode` |
-| 消费 | 指定变量或入边 Parquet |
+| 项   | 说明                                                                    |
+| ---- | ----------------------------------------------------------------------- |
+| 代码 | 无                                                                      |
+| 配置 | **`connectionId`**、**`tableName`**、**`input_variable_name`**、`mode`  |
+| 消费 | 指定变量或入边 Parquet                                                  |
 | 详见 | [variables-guide §6.6](./variables-guide.md#66-database-sink无代码文件) |
 
 #### `dataspace-sink` — 数据空间写入
 
-| 项 | 说明 |
-|----|------|
-| 代码 | 无 |
+| 项   | 说明                                                                      |
+| ---- | ------------------------------------------------------------------------- |
+| 代码 | 无                                                                        |
 | 配置 | **`spaceId`**、**`tableName`**、**`input_variable_name`**、`syncMetadata` |
-| 消费 | 同 database-sink |
+| 消费 | 同 database-sink                                                          |
 
 ### 资源与文件夹
 
 #### `folder-resource-import` — 文件夹资源导入
 
-| 项 | 说明 |
-|----|------|
+| 项   | 说明                                                         |
+| ---- | ------------------------------------------------------------ |
 | 配置 | `folderId`、`resourceId`、`pageSize`、`output_variable_name` |
-| 产出 | 表变量 |
+| 产出 | 表变量                                                       |
 
 #### `folder-resource-register` — 资源注册
 
-| 项 | 说明 |
-|----|------|
+| 项   | 说明                                  |
+| ---- | ------------------------------------- |
 | 配置 | `connectionName`、`targetFolderId` 等 |
-| 用途 | 将导入结果注册到连接/资源目录 |
+| 用途 | 将导入结果注册到连接/资源目录         |
 
 ### 选型速查（AI 常用）
 
@@ -294,7 +298,7 @@ pandas 清洗/聚合   → python-script
 | ------------------------------------------ | ------------------------------------------- |
 | [流程变量系统指南](./variables-guide.md)   | 变量产生/消费、`get_variable`、SQL 表名约定 |
 | [Flow 运行与测试](./run-guide.md)          | Run、debug、变量、流程项目测试              |
-| [Flow 快照管理](./snapshot-guide.md)       | 平台级 `flows/<id>/snapshot.json` 分离快照  |
+| [数据流程项目开发指南 §5 pull/push](./flow-project-guide.md#5-同步策略pull--push) | 平台快照拉取与本地拆分  |
 | [数据源管理](./source-guide.md)            | connectionId、表结构                        |
 | [Flow 执行计划](./plan-guide.md)           | FlowPlan / markdown 规划                    |
 | [CLI 命令速查](../guides/cli-reference.md) | 完整命令表                                  |