@dazitech/cli 3.0.0

package/dist/docs/flow//346/265/201/347/250/213/345/274/200/345/217/221/346/234/200/344/275/263/345/256/236/350/267/265-VS-flow0/346/241/210/344/276/213.md

@@ -0,0 +1,344 @@
+# 流程开发最佳实践（VS-flow0 案例）
+
+**文档 ID**: `flow/流程开发最佳实践-VS-flow0案例`
+
+> 最佳实践系列文档。以 **VS-flow0**（flowId `103`）为完整案例，总结从 Excel 解析 → 质检分支 → SQL 关联 → 数据库落库的端到端实践。  
+> 本文侧重**模式与决策**；目录结构、pull/push、画布规范见 [数据流程项目开发指南](./flow-project-guide.md)。  
+> 系列索引见 [Flow 文档索引 · 最佳实践系列](./flows-guide.md#最佳实践系列)。
+
+---
+
+## 一、VS-flow0 案例总结
+
+### 1.1 业务目标
+
+| 项          | 说明                                                                          |
+| ----------- | ----------------------------------------------------------------------------- |
+| 输入        | `Demo销售表_最简.xlsx`（销售表 / 产品表 / 规格表）                            |
+| 处理        | 多 Sheet 解析 → 数据质量检查 → 条件分支 → DuckDB JOIN 宽表                    |
+| 输出        | ClickHouse `space__xsh_01.temp_sales001`（销售表临时数据 001，96 行 × 12 列） |
+| 平台 flowId | `103`（示例；你的项目以 `flow.meta.json` 为准）                               |
+
+### 1.2 流程拓扑
+
+```text
+开始
+  ↓
+Excel 多表解析          → 产出：销售表、产品表、规格表
+  ↓
+数据质量检查            → 产出：V_DQ_REPORT、V_DQ_SCORE、quality_passed
+  ↓
+质检是否通过（condition）
+  ├─ True  → SQL 表间关联  → 产出：销售明细宽表
+  │            ↓
+  │         写入销售临时表（database-sink）→ temp_sales001
+  │            ↓
+  └─ False → 结束（跳过 SQL 与入库）
+            ↓
+          结束
+```
+
+### 1.3 节点与变量一览
+
+| 序号 | 节点           | 类型                 | 主要配置                                                 | 产出变量                                      |
+| ---- | -------------- | -------------------- | -------------------------------------------------------- | --------------------------------------------- |
+| 1    | Excel 多表解析 | `excel-python`       | `managed_file_id`、主输出 `销售表`                       | `销售表`、`产品表`、`规格表`                  |
+| 2    | 数据质量检查   | `data-quality-check` | `attached_variables`、7 条 rules、`fail_on_error: false` | `V_DQ_REPORT`、`V_DQ_SCORE`、`quality_passed` |
+| 3    | 质检是否通过   | `condition`          | 单行表达式 `eval`                                        | （无，仅分支）                                |
+| 4    | SQL 表间关联   | `sql-query`          | `attached_variables` 三表                                | `销售明细宽表`                                |
+| 5    | 写入销售临时表 | `database-sink`      | `connectionId`、`tableName`、`input_variable_name`       | （写入外部库）                                |
+
+### 1.4 关键设计决策
+
+**（1）一个 excel-python + 一个 sql-query，而非多个 excel-import**
+
+- 三张 Sheet 表头行不一致（销售表 header=0，维表 header=1），用 **单节点 Python** 统一 `read_excel` 参数更可控。
+- 多表 JOIN 放在 **DuckDB sql-query**，变量名即表名，SQL 可读性高、易调试。
+
+**（2）质检与分支分离**
+
+- `data-quality-check` 设置 **`fail_on_error: false`**：始终产出报告，不中断流程。
+- 下游 **`condition`** 读入边 `df`（即 `V_DQ_REPORT`），按「通过」列决定 True/False。
+- 好处：失败路径可观测（报告仍在 Run 中），成功路径才执行重计算与入库。
+
+**（3）条件节点必须是单行表达式**
+
+```python
+bool(df is not None and not df.empty and df["通过"].all())
+```
+
+多行 Python + `output.print` 会在 `eval` 时报 `Condition Error: invalid syntax`。
+
+**（4）database-sink 显式绑定变量**
+
+- 配置 `input_variable_name: 销售明细宽表`，不依赖隐式入边推断。
+- `connectionId` 使用 `ads_connections` 字符串 id（如 `clickhouse__space_xsh_01`），与 `资源/datasources/<连接名>/` 文档一致。
+
+### 1.5 运行验证
+
+整流程 `flow run flow-exec --type debug` 通过后，各节点耗时量级参考：Excel ~700ms、质检 ~600ms、SQL ~50ms、入库 ~620ms（以实际环境为准）。
+
+---
+
+## 二、推荐开发阶段（五步法）
+
+### 阶段 0：规划（动手写代码前）
+
+1. **画拓扑**：明确数据源、中间变量名、终态（表变量 / 标量 / 外部库表）。
+2. **变量命名表**：全流程唯一、见名知意；中文名可用，但团队内保持一致。
+3. **引用资源**：
+   - Excel 表结构 → `资源/files/`（侧栏「文件上传管理」拉取）；
+   - 目标库 → `资源/datasources/<连接名>/`（侧栏「数据连接」→ **拉取连接信息**）；
+   - 数据空间表清单 → `资源/dataspaces/<空间名>/`（侧栏「数据空间」→ **拉取空间信息**）。
+4. **节点选型**：见下文「节点选型速查」。
+
+### 阶段 1：接入与解析
+
+- Excel 多 Sheet、表头不统一 → **`excel-python`** + `set_table_output`。
+- **凡有 `managed_file_id` 的 Excel（`.xlsx`/`.xls`）默认用 `excel-python`**，**勿用 `file-source`**（不解析 Excel）。
+- 单 Sheet、第 1 行标准表头、零自定义逻辑 → 才考虑 **`excel-import`**。
+- 解析后立即 **`flow variable pull`** 核对列名、行数、类型。
+
+### 阶段 2：质量与分支
+
+- 规则集中在 **`flow.json` → qualityConfig.rules**（行数、非空、外键）。
+- 需要「失败仍跑完、再决定是否继续」→ **`fail_on_error: false` + condition**。
+- 条件逻辑简单 → **`condition`**；复杂判定 → 先用 **`python-script`** 写清再提炼为单行。
+
+### 阶段 3：转换与关联
+
+- 内存多表 JOIN / 聚合 → **`sql-query`**（`FROM 上游变量名`）。
+- 复杂行级逻辑 → **`python-script`**（`get_variable` + `result_df`）。
+- SQL 节点配置 **`attached_variables`**，便于单测时注册未连线的维表。
+
+### 阶段 4：落库与收尾
+
+- 写外部库 → **`database-sink`**（`connectionId` + `tableName` + `input_variable_name`）。
+- 更新 `资源/datasources/` 下表说明（侧栏连接下各表「下载表信息」）。
+- 整流程 **debug run** 通过后，再考虑 preview / 生产调度。
+
+---
+
+## 三、节点选型速查
+
+| 场景                  | 推荐节点             | 避免                              |
+| --------------------- | -------------------- | --------------------------------- |
+| Excel + managed_file_id | **`excel-python`**   | **`file-source`**（不解析 xlsx）  |
+| 多 Sheet、不同 header | `excel-python`       | 多个 `excel-import` 重复配置      |
+| 极简单 Sheet、零代码   | `excel-import`       | 不必要的 Python                   |
+| 行数/非空/外键        | `data-quality-check` | 在 Python 里散落 if/raise         |
+| 通过/不通过两路       | `condition`          | 在 SQL 里写 impossible WHERE      |
+| 多表 JOIN 宽表        | `sql-query`          | 全用 pandas merge（大表时难维护） |
+| 写 ClickHouse / PG 等 | `database-sink`      | 在 Python 里手写 JDBC/HTTP        |
+| 写数据空间表          | `dataspace-sink`     | 先落外部库再回灌空间              |
+| 读外部库              | `database-source`    | 与 sql-query 混用职责             |
+| 读数据空间            | `dataspace-source`   | 误填 `connectionId`               |
+
+---
+
+## 四、变量约定（必守）
+
+### 4.1 命名
+
+- 全流程 **`output_variable_name` 不重名**。
+- 事实表 / 维表 / 宽表 / 报告表语义分离，例如：`销售表` → `销售明细宽表`、`V_DQ_REPORT`。
+- 标量用简短名：`quality_passed`、`V_DQ_SCORE`。
+
+### 4.2 读写方式
+
+| 场景              | 做法                                                                            |
+| ----------------- | ------------------------------------------------------------------------------- |
+| SQL 消费上游表    | `FROM 销售表` / `JOIN 产品表`（变量名即表名）                                   |
+| Python 单节点测试 | `get_variable("销售表")`（勿假设 `df` 一定有值）                                |
+| Python 整图运行   | 入边 `df` 可用；多表时其余 `get_variable`                                       |
+| excel-python 多表 | 每张表 **`set_table_output(变量名, df)`**，主表名与 `output_variable_name` 一致 |
+| database-sink     | **`input_variable_name`** 指向要写入的表变量                                    |
+
+### 4.3 调试顺序
+
+```text
+自上游向下单节点测试 → 或一次 flow-exec --type debug → variable pull/sync 核对
+```
+
+改 **`output_variable_name` / 画布** → `project push --canvas`  
+改 **`code.py` / `code.sql`** → `node push` 或 `project push`
+
+---
+
+## 五、画布与 flow.json 规范
+
+1. 节点 **`type: "custom"`**，业务类型在 **`data.type`**。
+2. 连线必须写 **`sourceHandle` / `targetHandle`**（`l` `t` `r` `b`；条件用 `true` / `false`）。
+3. 相邻节点间距：横向 ≥ 260px，纵向 ≥ 140px。
+4. 代码只放在 **`节点/<名>/code.*`**，不要内嵌进 `flow.json`。
+5. 新增节点流程：**改 flow.json → `push --canvas` → `pull` 同步 uuid → 再 push 代码**（纯配置节点无 code 则省略最后一步）。
+
+详见 [flow-project-guide §6.2](./flow-project-guide.md#62-画布节点与连线规范ai-创建--编辑-flowjson-必读)。
+
+---
+
+## 六、VS-flow0 代码片段参考
+
+### 6.1 Excel 多表解析（节选）
+
+```python
+SHEETS = {
+    "销售表": {"sheet_name": "销售表", "header": 0, "usecols": "A:H"},
+    "产品表": {"sheet_name": "产品表", "header": 1, "usecols": "A:C"},
+    "规格表": {"sheet_name": "规格表", "header": 1, "usecols": "A:C"},
+}
+for var_name, kwargs in SHEETS.items():
+    raw = pd.read_excel(excel_source_path, **kwargs)
+    table = _normalize_sales(raw) if var_name == "销售表" else _normalize_dim(raw)
+    set_table_output(var_name, table)
+```
+
+### 6.2 SQL 三表 JOIN（节选）
+
+```sql
+SELECT
+    s.ID AS 销售ID,
+    s.地区,
+    s.产品 AS 产品ID,
+    p.名称 AS 产品名称,
+    ...
+FROM 销售表 s
+LEFT JOIN 产品表 p ON CAST(s.产品 AS VARCHAR) = CAST(p.ID AS VARCHAR)
+LEFT JOIN 规格表 g ON CAST(s.规格 AS VARCHAR) = CAST(g.ID AS VARCHAR)
+```
+
+维表 ID 为字符串、事实表编码混用时，**JOIN 前 CAST** 避免 silent mismatch。
+
+### 6.3 database-sink 配置
+
+```json
+{
+  "type": "database-sink",
+  "data": {
+    "connectionId": "clickhouse__space_xsh_01",
+    "tableName": "temp_sales001",
+    "display_name": "销售表临时数据001",
+    "input_variable_name": "销售明细宽表"
+  }
+}
+```
+
+### 6.4 dataspace-source / dataspace-sink 配置（新增）
+
+```json
+{
+  "type": "dataspace-source",
+  "data": {
+    "spaceId": "space__0519",
+    "output_variable_name": "空间销售明细"
+  }
+}
+```
+
+`节点/<dataspace-source名>/code.sql` 示例：
+
+```sql
+SELECT *
+FROM sales_fact
+WHERE dt >= '2025-01-01'
+LIMIT 100000
+```
+
+```json
+{
+  "type": "dataspace-sink",
+  "data": {
+    "spaceId": "space__0519",
+    "tableName": "temp_sales001",
+    "mode": "append",
+    "syncMetadata": true,
+    "input_variable_name": "空间销售明细"
+  }
+}
+```
+
+要点：
+
+- `dataspace-source` / `dataspace-sink` 一律使用 **`spaceId`**，不是 `connectionId`。
+- `dataspace-source` 的 SQL 放在 `code.sql`，与 `database-source` 一致。
+- `dataspace-sink` 支持 `mode=append|replace`，默认建议 `append`。
+- `syncMetadata=true` 时，写入后会触发空间元数据同步（建议保留默认）。
+
+---
+
+## 七、常用命令清单
+
+在 **工作区根目录**（如 `dazi-work`）执行，`<流程目录>` 替换为你的流程项目路径：
+
+```powershell
+cd "<流程目录>"
+
+# 同步平台
+.\scripts\dazi.ps1 flow project pull --flow <flowId> --dir .
+.\scripts\dazi.ps1 flow project push --dir . --canvas
+
+# 测试
+.\scripts\dazi.ps1 flow run node-exec --node <node_uuid> --dir .
+.\scripts\dazi.ps1 flow run flow-exec --dir . --type debug
+
+# 变量
+.\scripts\dazi.ps1 flow variable pull --name 销售明细宽表 --dir .
+.\scripts\dazi.ps1 flow variable sync --dir .
+
+# 数据源
+.\scripts\dazi.ps1 flow source list
+
+# 数据空间
+.\scripts\dazi.ps1 flow dataspace list
+.\scripts\dazi.ps1 flow dataspace tables <spaceId>
+```
+
+命令前缀与 Trae/VS Code 约定见 [CLI 调用约定](../guides/cli-invocation.md)。
+
+---
+
+## 八、常见问题与对策
+
+| 现象                            | 原因                     | 对策                                  |
+| ------------------------------- | ------------------------ | ------------------------------------- |
+| SQL 单测找不到表                | 上游变量未写入 debug Run | 先跑 Excel 节点或整流程 debug         |
+| excel-python 单测只有主表       | 多表需整图或先跑 Excel   | 用 `flow-exec` 或按序 node-exec       |
+| Condition Error: invalid syntax | 条件脚本非单行表达式     | 改为单行 `bool(...)`                  |
+| 质检失败流程中断                | `fail_on_error: true`    | 改为 `false` + 下游 condition         |
+| 画布 push 失败                  | 未关联 flowId            | 先 `project pull --flow <id>`         |
+| sink 写库失败                   | connectionId / 表名错误  | 对照 `资源/datasources/<连接名>/*.md` |
+| dataspace-sink 写入失败         | spaceId / tableName 错误 | 先 `flow dataspace list` / `flow dataspace tables` |
+| 变量列为空                      | 单测时只用了 `df`        | Python 改用 `get_variable`            |
+| AI 不知道 connectionId          | 未拉取连接文档           | 侧栏数据连接 → **拉取连接信息**       |
+| AI 不知道 spaceId               | 未拉取空间文档           | 侧栏数据空间 → **拉取空间信息**       |
+
+---
+
+## 九、新流程启动检查表
+
+复制到新项目 `流程/<FlowName>/README.md` 或规划文档中使用：
+
+- [ ] 已创建/拉取流程目录，`flow.meta.json` 含 `flowId`
+- [ ] 拓扑图与变量命名表已评审
+- [ ] 数据源文档已 @ 引用（Excel / connectionId / 空间表清单）
+- [ ] 每个产出表节点配置了 `output_variable_name`
+- [ ] SQL / Python 中变量名与画布完全一致
+- [ ] 条件节点为单行表达式；出边使用 `true`/`false`
+- [ ] 需要入库时配置了 `database-sink` 三要素
+- [ ] 读写数据空间时使用 `dataspace-source` / `dataspace-sink` + `spaceId`
+- [ ] 自上游单测或整流程 debug 通过
+- [ ] `变量/*.json` 已核对 schema 与样例行
+- [ ] 项目 README / 快速启动已更新拓扑与命令
+
+---
+
+## 十、相关文档
+
+| 文档                                                          | 用途                          |
+| ------------------------------------------------------------- | ----------------------------- |
+| [Flow 文档索引 · 最佳实践系列](./flows-guide.md#最佳实践系列) | 系列目录                      |
+| [数据流程项目开发指南](./flow-project-guide.md)               | 目录结构、pull/push、画布规范 |
+| [流程变量系统指南](./variables-guide.md)                      | 变量模型与各节点读写          |
+| [节点代码编写指南](./node-code-guide.md)                      | code.py / code.sql 模板       |
+| [Flow 运行与测试](./run-guide.md)                             | Run、debug、错误文件          |
+| [数据源管理](./source-guide.md)                               | connectionId、表结构          |

package/dist/docs/guides/cli-invocation.md

@@ -0,0 +1,93 @@
+# CLI 调用约定（生产交付）
+
+**文档 ID**: `guides/cli-invocation`  
+**适用**: 开发人员仅持有 **`dazi-work/`** + **`dazi-vscode.vsix`**，**无** monorepo 源码
+
+## 原则
+
+v3 **不会**把 `dazi` / `dazi-onto` / `dazi-app` 安装到系统 PATH。  
+终端中请使用 **`dazi-work` 包装脚本** 或 **扩展内置 bundled CLI**。
+
+## 命令前缀
+
+| 场景 | 工作目录 | 命令形式 |
+|------|----------|----------|
+| 本体 / 流程 / 鉴权 / 数据 / 文档 | **`dazi-work` 根** | `.\scripts\dazi.ps1 <子命令...>` |
+| DRAP 应用 | **`dazi-work/项目/app_<名称>/`**（应用项目根） | `pnpm run dazi-app -- <子命令...>` |
+| 环境自检 | **`dazi-work` 根** | `.\scripts\doctor-cli.ps1` |
+
+CMD 用户：`scripts\dazi.cmd`、`scripts\doctor-cli.cmd`（转发到同名 `.ps1`）。
+
+## 首次安装后（推荐顺序）
+
+```powershell
+# 1) 安装扩展
+code --install-extension dazi-vscode-3.x.x.vsix
+
+# 2) 打开 dazi-work 为 VS Code 工作区根
+
+# 3) 自检 CLI（无需源码、无需 pnpm run bundle:clis）
+cd D:\path\to\dazi-work
+.\scripts\doctor-cli.ps1
+
+# 4) 登录
+.\scripts\dazi.ps1 auth login
+# 或
+.\scripts\dazi.ps1 auth set-token --token "<jwt>"
+
+# 5) 验证
+.\scripts\dazi.ps1 auth whoami
+.\scripts\dazi.ps1 onto function list --space <space-id>
+```
+
+## 文档中的写法对照
+
+内置帮助文档里的可运行示例统一采用 **`.\scripts\dazi.ps1`**，等价关系如下：
+
+| 文档示例 | 含义 |
+|----------|------|
+| `.\scripts\dazi.ps1 auth whoami` | 原 `dazi auth whoami` |
+| `.\scripts\dazi.ps1 onto script publish ...` | 原 `dazi onto script publish ...`（**勿用** `dazi-onto`） |
+| `.\scripts\dazi.ps1 flow project pull --flow 98 --dir 项目\flow_x\流程\MyFlow` | 流程项目拉取 |
+| `.\scripts\dazi.ps1 flow run node-exec --node <uuid> --dir <流程目录>` | 单节点测试 |
+| `pnpm run dazi-app -- upload ...` | 原 `dazi-app upload ...`（须在**应用项目根**，含 `sdk/`、`templates/`） |
+
+扩展侧栏、命令面板触发的操作与上述 CLI **同源**（bundled `clis/*.js`）。
+
+### 流程子命令（`flow` → `dazi-flow`）
+
+`.\scripts\dazi.ps1 flow …` **不会**执行独立的 `dazi-flow.exe`，而是：
+
+1. `dazi.ps1` 设置 `DAZI_BUNDLED_DIR`，在 **dazi-work 根**执行 `node bundled/clis/dazi.js`
+2. `dazi.js` 将 `flow` 后所有参数 **转发**给 `node bundled/clis/dazi-flow.js`
+
+因此文档里的 `dazi-flow project pull …` 在 Trae / VS Code 交付环境中应写为：
+
+```powershell
+.\scripts\dazi.ps1 flow project pull --flow 98 --dir "项目\flow_xxx\流程\MyFlow"
+```
+
+流程项目开发详见 [flow/flow-project-guide](../flow/flow-project-guide.md)。
+
+## CLI 解析来源（doctor-cli 会检查）
+
+1. 环境变量 `DAZI_BUNDLED_DIR`
+2. `dazi-work/tools/dazi-clis/`（可选离线包）
+3. 已安装扩展（路径因 IDE 而异）  
+   - Trae：`%USERPROFILE%\.trae\extensions\dazitech.dazi-vscode-*\bundled\clis`  
+   - Cursor / VS Code：`.cursor\extensions` 或 `.vscode\extensions`  
+   - 也可：`%VSCODE_EXTENSIONS%`、`dazi-work\tools\dazi-clis`（`sync-clis-from-extension.ps1`）
+
+## 常见错误
+
+| 现象 | 原因 | 处理 |
+|------|------|------|
+| `dazi-onto` 找不到 | v3 无此全局命令 | 改用 `.\scripts\dazi.ps1 onto ...` |
+| `dazi` 找不到 | 未装 vsix / 未用包装脚本 | `doctor-cli.ps1` → 安装 vsix |
+| `dazi-app` 找不到 | 未在应用项目根或未 pnpm install | `cd 项目/app_<名> && pnpm install` |
+
+## 相关文档
+
+- [CLI 命令参考](./cli-reference.md)
+- [故障排查](./troubleshooting.md)
+- 工作区脚本说明：`dazi-work/scripts/README.md`（交付包内）

package/dist/docs/guides/cli-reference.md

@@ -0,0 +1,98 @@
+# CLI 命令速查
+
+**文档 ID**: `guides/cli-reference`
+
+> **生产环境**：在 `dazi-work` 根目录，所有 `dazi` / `dazi onto` / `dazi flow` 命令写作  
+> **`.\scripts\dazi.ps1 <子命令>`**；DRAP 在**应用项目根**（`项目/app_<名称>/`，含 `sdk/`）用 **`pnpm run dazi-app -- <子命令>`**。  
+> 详见 [CLI 调用约定](./cli-invocation.md)。首次安装后运行 **`.\scripts\doctor-cli.ps1`**。
+
+## 主 CLI（`.\scripts\dazi.ps1`）
+
+| 命令                                    | 说明                                    |
+| --------------------------------------- | --------------------------------------- |
+| `.\scripts\dazi.ps1 auth login`         | 用户名密码登录                          |
+| `.\scripts\dazi.ps1 auth set-token`     | 绑定 JWT Token                          |
+| `.\scripts\dazi.ps1 auth whoami`        | 显示当前账号                            |
+| `.\scripts\dazi.ps1 auth migrate`       | 迁移旧版认证                            |
+| `.\scripts\dazi.ps1 doctor`             | 环境诊断                                |
+| `.\scripts\dazi.ps1 env`                | 显示环境信息                            |
+| `.\scripts\dazi.ps1 docs list`          | 列出文档                                |
+| `.\scripts\dazi.ps1 docs open <id>`     | 打开文档                                |
+| `.\scripts\dazi.ps1 docs sync`          | 同步内置文档到 `资源/docs/`             |
+| `.\scripts\dazi.ps1 prompt list`        | 列出提示词                              |
+| `.\scripts\dazi.ps1 prompt show <id>`   | 显示提示词                              |
+| `.\scripts\dazi.ps1 prompt sync`        | 同步内置提示词到 `资源/prompts/`        |
+| `.\scripts\dazi.ps1 examples list`      | 列出示例脚本                            |
+| `.\scripts\dazi.ps1 examples open <id>` | 显示示例内容                            |
+| `.\scripts\dazi.ps1 examples sync`      | 同步内置示例到 `资源/examples/`         |
+| `.\scripts\dazi.ps1 migrate workspace`  | 迁移工作区                              |
+| `.\scripts\dazi.ps1 migrate config`     | 迁移旧配置                              |
+| `.\scripts\dazi.ps1 onto <args>`        | 本体 CLI（**勿用** `dazi-onto`）        |
+| `.\scripts\dazi.ps1 flow <args>`        | 流程 CLI                                |
+| `.\scripts\dazi.ps1 app <args>`         | 应用 CLI（亦可在应用项目根用 `pnpm run dazi-app`） |
+
+## 本体（`.\scripts\dazi.ps1 onto ...`）
+
+| 命令                                                                     | 说明             |
+| ------------------------------------------------------------------------ | ---------------- |
+| `.\scripts\dazi.ps1 onto space list`                                     | 空间列表         |
+| `.\scripts\dazi.ps1 onto space snapshot`                                 | 拉取空间快照     |
+| `.\scripts\dazi.ps1 onto space init`                                     | 初始化空间工作区 |
+| `.\scripts\dazi.ps1 onto function list`                                  | 函数定义列表     |
+| `.\scripts\dazi.ps1 onto function run`                                   | 执行函数         |
+| `.\scripts\dazi.ps1 onto function publish`                               | 发布函数         |
+| `.\scripts\dazi.ps1 onto function update-code`                           | 更新函数代码     |
+| `.\scripts\dazi.ps1 onto action list/update-code/delete`                 | 动作管理         |
+| `.\scripts\dazi.ps1 onto rule list/run-seed/delete`                      | 规则管理         |
+| `.\scripts\dazi.ps1 onto script sync/publish/publish-preview/run/dedupe` | 脚本管理         |
+| `.\scripts\dazi.ps1 onto mcp serve`                                      | 启动本体 MCP     |
+
+## 流程（`.\scripts\dazi.ps1 flow ...`）
+
+> **流程项目日常开发**见 [flow/flow-project-guide](../flow/flow-project-guide.md)。  
+> 下列 `flow` 子命令均写作 `.\scripts\dazi.ps1 flow <...>`。
+
+### 流程项目（`项目/flow_*/流程/<名>/`）
+
+| 命令 | 说明 |
+|------|------|
+| `flow project pull --flow <id> --dir <流程目录>` | 拉取 snapshot 并拆分为 flow.json + 节点代码 |
+| `flow project push --dir <dir> [--canvas]` | 提交脏代码节点；`--canvas` 含画布 |
+| `flow project status --dir <dir>` | 本地代码改动 |
+| `flow node push --node <uuid> --dir <dir>` | 提交单节点代码 |
+| `flow node pull --node <uuid> --dir <dir>` | 拉取单节点代码 |
+| `flow run node-exec --node <uuid> --dir <dir>` | 单节点测试 |
+| `flow run flow-exec --dir <dir> --type debug` | 整流程运行 |
+| `flow variable pull --name <名> --dir <dir>` | 拉取变量到 `变量/<名>.json` |
+| `flow variable sync --dir <dir>` | 同步全部调试变量 |
+
+### 平台级 / 旧式
+
+| 命令 | 说明 |
+|------|------|
+| `flow flows list` | Flow 列表 |
+| `flow flows get <id>` | Flow 详情 |
+| `flow flows create` | 新建 Flow |
+| `flow snapshot pull --flow <id>` | 拉取快照到 `flows/<id>/` |
+| `flow snapshot push-graph` | 推送图快照 |
+| `flow run start <id>` / `run debug <id>` | 启动 / 调试 Run |
+| `flow run variables-list` | 查看变量 |
+| `flow source list/tables/table-structure` | 数据源 |
+| `flow plan compile/apply/markdown` | 执行计划 |
+| `flow file list/upload/pull` | 文件管理 |
+| `flow mcp serve` | Flow MCP |
+
+## 应用（`项目/app_<名称>/` 应用项目根）
+
+在 `dazi-work/项目/app_<名称>/` 下（须含 `sdk/`、`templates/`）：
+
+| 命令                                                                 | 说明             |
+| -------------------------------------------------------------------- | ---------------- |
+| `pnpm run dazi-app -- init ...`                                      | 初始化应用       |
+| `pnpm run dazi-app -- build`                                         | 构建应用         |
+| `pnpm run dazi-app -- upload --space <id>`                           | 上传应用         |
+| `pnpm run dazi-app -- release list`                                  | 发布管理         |
+| `pnpm run dazi-app -- asset list`                                    | drap-assets 列表 |
+| `pnpm run dazi-app -- manifest validate --cwd apps/<app> --scan-src` | 校验 manifest    |
+
+等价写法（仍在 `dazi-work` 根）：`.\scripts\dazi.ps1 app <子命令>`。

package/dist/docs/guides/mcp-setup.md

@@ -0,0 +1,89 @@
+# MCP 配置指南
+
+**文档 ID**: `guides/mcp-setup`
+
+## 在 Cursor 中配置搭子 MCP
+
+在项目根目录创建 `.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "dazi": {
+      "command": "node",
+      "args": ["<dazi-vscode>/bundled/clis/dazi.js", "mcp", "stdio"],
+      "env": {
+        "DAZI_BUNDLED_DIR": "<dazi-vscode>/bundled/clis"
+      }
+    }
+  }
+}
+```
+
+生产交付（`dazi-work`）可将 `command` 改为包装脚本，或设置 `DAZI_BUNDLED_DIR` 指向 `tools/dazi-clis` / 扩展内 `bundled/clis`（见 [CLI 调用约定](./cli-invocation.md)）。
+
+## 聚合 MCP 工具总览（`mcp stdio`）
+
+运行 `.\scripts\dazi.ps1 mcp tools` 查看完整列表，共 **28 个工具**：
+
+### 📖 文档与提示词（4 个）
+
+| 工具 | 说明 |
+|------|------|
+| `list_docs` | 列出文档目录（可按分类过滤） |
+| `get_doc` | 获取文档完整内容 |
+| `list_prompts` | 列出提示词目录 |
+| `get_prompt` | 获取提示词完整内容 |
+
+### 🧠 本体 onto（8 个）
+
+| 工具 | 说明 |
+|------|------|
+| `onto_list_spaces` | 列出所有本体空间 |
+| `onto_list_functions` | 列出空间函数定义 |
+| `onto_get_function` | 查看函数详情 |
+| `onto_run_function` | 执行函数 |
+| `onto_list_actions` | 列出动作定义 |
+| `onto_list_rules` | 列出规则 |
+| `onto_list_scripts` | 列出脚本 |
+| `onto_space_snapshot` | 拉取空间快照 |
+
+### 🔄 流程 flow（9 个）
+
+| 工具 | 说明 |
+|------|------|
+| `flow_list_flows` | 列出 Flow |
+| `flow_get_flow` | 查看 Flow 详情 |
+| `flow_list_runs` | 列出运行记录 |
+| `flow_start_run` | 启动 Flow |
+| `flow_debug_run` | 调试最近 Run |
+| `flow_list_sources` | 列出数据源 |
+| `flow_source_tables` | 列出数据源中的表 |
+| `flow_table_structure` | 查看表列结构 |
+| `flow_snapshot_pull` | 拉取快照 |
+| `flow_plan_llm_guide` | 生成 LLM 引导文档 |
+
+### 🗂 数据 data（4 个）
+
+| 工具 | 说明 |
+|------|------|
+| `data_list_spaces` | 列出数据空间 |
+| `data_list_tables` | 列出数据表 |
+| `data_table_schema` | 查看表字段结构 |
+| `data_table_sample` | 采样数据（前 N 行）|
+
+## Cursor 使用示例
+
+```
+给我 onto/function-guide 文档
+→ get_doc({"id": "onto/function-guide"})
+
+列出 space-001 的所有函数
+→ onto_list_functions({"space_id": "space-001"})
+
+调试最近一次 Flow 运行失败原因
+→ flow_debug_run({"flow_id": "flow-abc123"})
+
+查看 orders 表的字段结构
+→ flow_table_structure({"source_id": "ch-main", "table_name": "orders"})
+```

package/dist/docs/guides/migrate-v2-v3.md

@@ -0,0 +1,54 @@
+# 从 v2 迁移到 v3
+
+**文档 ID**: `guides/migrate-v2-v3`
+
+## 快速迁移（3 步）
+
+### 第 1 步：预览变更
+
+```bash
+.\scripts\dazi.ps1 migrate workspace --dry-run
+```
+
+输出示例：
+```
+[计划]
+  重命名: ontology/ → onto/
+  重命名: runtime-apps/ → apps/
+  创建: flows/
+  创建: data/
+  创建: docs/
+  创建: prompts/
+  创建: .dazi/
+```
+
+### 第 2 步：执行迁移
+
+```bash
+.\scripts\dazi.ps1 migrate workspace
+```
+
+迁移前会自动备份到 `.dazi/backup/<timestamp>/`。
+
+### 第 3 步：迁移认证
+
+```bash
+.\scripts\dazi.ps1 auth migrate --dry-run  # 预览
+.\scripts\dazi.ps1 auth migrate            # 执行（从 ~/.dazi-app/auth.json 迁移）
+```
+
+## 配置迁移
+
+旧版 `daziAgent.*` / `daziApp.*` 配置会在首次激活时自动提示迁移，也可手动执行：
+
+```bash
+.\scripts\dazi.ps1 migrate config
+```
+
+## 回退
+
+如果迁移出现问题，备份在 `.dazi/backup/<timestamp>/`，恢复方式：
+
+```bash
+cp -r .dazi/backup/<timestamp>/ontology ./ontology
+```