@dazitech/cli 3.0.2 → 3.0.4

package/dist/clis/dazi-onto.js

@@ -3061,11 +3061,27 @@ var AuthError = class extends DaziError {
   }
 };
 var NetworkError = class extends DaziError {
-  constructor(message, status) {
+  constructor(message, status, request) {
     super(message, "ERR_NETWORK", 3);
     this.status = status;
+    this.request = request;
     this.name = "NetworkError";
   }
+  /** 多行人类可读详情，写入 stderr / OutputChannel */
+  formatDetailLines() {
+    const lines = [`\u9519\u8BEF: ${this.message}`];
+    const r = this.request;
+    if (!r)
+      return lines;
+    if (r.label)
+      lines.push(`\u6B65\u9AA4: ${r.label}`);
+    lines.push(`\u8BF7\u6C42: ${r.method} ${r.path}`);
+    lines.push(`\u5B8C\u6574 URL: ${r.url}`);
+    lines.push(`HTTP \u72B6\u6001: ${r.status}`);
+    if (r.responseSnippet)
+      lines.push(`\u54CD\u5E94\u6458\u8981: ${r.responseSnippet}`);
+    return lines;
+  }
 };
 
 // cli/shared/src/auth.js
@@ -3084,30 +3100,74 @@ function loadAuth() {
 }
 
 // cli/shared/src/httpClient.js
+var SNIPPET_MAX = 280;
+function truncateSnippet(text) {
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  if (oneLine.length <= SNIPPET_MAX)
+    return oneLine;
+  return `${oneLine.slice(0, SNIPPET_MAX)}\u2026`;
+}
+function buildHttpErrorMessage(ctx, detail) {
+  const parts = [
+    ctx.label ? `${ctx.label}\u5931\u8D25` : "HTTP \u8BF7\u6C42\u5931\u8D25",
+    `[${ctx.status} ${ctx.method} ${ctx.path}]`,
+    detail
+  ].filter(Boolean);
+  return parts.join(" \u2014 ");
+}
 async function apiRequest(path7, opts = {}) {
   const auth = opts.token || opts.serverUrl ? { token: opts.token ?? "", serverUrl: opts.serverUrl ?? "" } : loadAuth();
-  const url = `${auth.serverUrl.replace(/\/$/, "")}${path7}`;
+  const method = (opts.method ?? "GET").toUpperCase();
+  const serverBase = auth.serverUrl.replace(/\/$/, "");
+  const url = `${serverBase}${path7}`;
   const headers = {
     "Content-Type": "application/json",
     Authorization: `Bearer ${auth.token}`,
     ...opts.headers
   };
   const res = await fetch(url, {
-    method: opts.method ?? "GET",
+    method,
     headers,
     body: opts.body != null ? JSON.stringify(opts.body) : void 0
   });
   if (!res.ok) {
-    let msg = `HTTP ${res.status} ${res.statusText}`;
-    try {
-      const j = await res.json();
-      if (j.message)
-        msg = j.message;
-    } catch {
+    let detail = `HTTP ${res.status} ${res.statusText}`;
+    let responseSnippet;
+    const rawText = await res.text();
+    if (rawText) {
+      responseSnippet = truncateSnippet(rawText);
+      try {
+        const j = JSON.parse(rawText);
+        if (typeof j.detail === "string" && j.detail.trim()) {
+          detail = j.detail;
+        } else if (Array.isArray(j.detail) && j.detail.length) {
+          detail = j.detail.map((d) => d.msg ?? JSON.stringify(d)).join("; ");
+        } else if (j.message) {
+          detail = j.message;
+        }
+      } catch {
+        if (rawText.trim() && detail.startsWith("HTTP ")) {
+          detail = `\u975E JSON \u54CD\u5E94\uFF08\u53EF\u80FD\u662F\u7F51\u5173/\u524D\u7AEF 404\uFF09`;
+        }
+      }
     }
-    throw new NetworkError(msg, res.status);
+    const ctx = {
+      method,
+      path: path7,
+      url,
+      status: res.status,
+      label: opts.label,
+      responseSnippet
+    };
+    throw new NetworkError(buildHttpErrorMessage(ctx, detail), res.status, ctx);
+  }
+  if (res.status === 204 || res.headers.get("content-length") === "0") {
+    return void 0;
   }
-  return res.json();
+  const text = await res.text();
+  if (!text.trim())
+    return void 0;
+  return JSON.parse(text);
 }
 
 // cli/shared/src/output.js
@@ -3121,7 +3181,12 @@ function fail(code, message) {
   printJsonSummary({ ok: false, error: { code, message } });
 }
 function handleError(err) {
-  if (err instanceof Error) {
+  if (err instanceof NetworkError) {
+    for (const line of err.formatDetailLines()) {
+      console.error(line);
+    }
+    fail(err.code, err.message);
+  } else if (err instanceof Error) {
     const code = err.code ?? "ERR_UNKNOWN";
     console.error(`\u9519\u8BEF: ${err.message}`);
     fail(code, err.message);
@@ -3913,7 +3978,7 @@ function makeMcpCommand() {
               result: {
                 protocolVersion: "2024-11-05",
                 capabilities: { tools: {} },
-                serverInfo: { name: "dazi-onto", version: "3.0.2" }
+                serverInfo: { name: "dazi-onto", version: "3.0.4" }
               }
             };
             process.stdout.write(JSON.stringify(response) + "\n");
@@ -3936,7 +4001,7 @@ function makeMcpCommand() {
 
 // cli/dazi-onto/src/index.ts
 var program2 = new Command();
-program2.name("dazi-onto").description("\u642D\u5B50 Onto CLI \u2014 \u672C\u4F53\uFF08Ontology\uFF09\u7BA1\u7406").version("3.0.2", "-v, --version");
+program2.name("dazi-onto").description("\u642D\u5B50 Onto CLI \u2014 \u672C\u4F53\uFF08Ontology\uFF09\u7BA1\u7406").version("3.0.4", "-v, --version");
 program2.addCommand(makeSpaceCommand());
 program2.addCommand(makeFunctionCommand());
 program2.addCommand(makeActionCommand());

package/dist/clis/dazi.js

@@ -3659,11 +3659,27 @@ var AuthError = class extends DaziError {
   }
 };
 var NetworkError = class extends DaziError {
-  constructor(message, status) {
+  constructor(message, status, request) {
     super(message, "ERR_NETWORK", 3);
     this.status = status;
+    this.request = request;
     this.name = "NetworkError";
   }
+  /** 多行人类可读详情，写入 stderr / OutputChannel */
+  formatDetailLines() {
+    const lines = [`\u9519\u8BEF: ${this.message}`];
+    const r = this.request;
+    if (!r)
+      return lines;
+    if (r.label)
+      lines.push(`\u6B65\u9AA4: ${r.label}`);
+    lines.push(`\u8BF7\u6C42: ${r.method} ${r.path}`);
+    lines.push(`\u5B8C\u6574 URL: ${r.url}`);
+    lines.push(`HTTP \u72B6\u6001: ${r.status}`);
+    if (r.responseSnippet)
+      lines.push(`\u54CD\u5E94\u6458\u8981: ${r.responseSnippet}`);
+    return lines;
+  }
 };
 
 // cli/shared/src/auth.js
@@ -3700,30 +3716,74 @@ function tryLoadAuth() {
 }
 
 // cli/shared/src/httpClient.js
+var SNIPPET_MAX = 280;
+function truncateSnippet(text2) {
+  const oneLine = text2.replace(/\s+/g, " ").trim();
+  if (oneLine.length <= SNIPPET_MAX)
+    return oneLine;
+  return `${oneLine.slice(0, SNIPPET_MAX)}\u2026`;
+}
+function buildHttpErrorMessage(ctx, detail) {
+  const parts = [
+    ctx.label ? `${ctx.label}\u5931\u8D25` : "HTTP \u8BF7\u6C42\u5931\u8D25",
+    `[${ctx.status} ${ctx.method} ${ctx.path}]`,
+    detail
+  ].filter(Boolean);
+  return parts.join(" \u2014 ");
+}
 async function apiRequest(path13, opts = {}) {
   const auth = opts.token || opts.serverUrl ? { token: opts.token ?? "", serverUrl: opts.serverUrl ?? "" } : loadAuth();
-  const url = `${auth.serverUrl.replace(/\/$/, "")}${path13}`;
+  const method = (opts.method ?? "GET").toUpperCase();
+  const serverBase = auth.serverUrl.replace(/\/$/, "");
+  const url = `${serverBase}${path13}`;
   const headers = {
     "Content-Type": "application/json",
     Authorization: `Bearer ${auth.token}`,
     ...opts.headers
   };
   const res = await fetch(url, {
-    method: opts.method ?? "GET",
+    method,
     headers,
     body: opts.body != null ? JSON.stringify(opts.body) : void 0
   });
   if (!res.ok) {
-    let msg = `HTTP ${res.status} ${res.statusText}`;
-    try {
-      const j = await res.json();
-      if (j.message)
-        msg = j.message;
-    } catch {
+    let detail = `HTTP ${res.status} ${res.statusText}`;
+    let responseSnippet;
+    const rawText = await res.text();
+    if (rawText) {
+      responseSnippet = truncateSnippet(rawText);
+      try {
+        const j = JSON.parse(rawText);
+        if (typeof j.detail === "string" && j.detail.trim()) {
+          detail = j.detail;
+        } else if (Array.isArray(j.detail) && j.detail.length) {
+          detail = j.detail.map((d) => d.msg ?? JSON.stringify(d)).join("; ");
+        } else if (j.message) {
+          detail = j.message;
+        }
+      } catch {
+        if (rawText.trim() && detail.startsWith("HTTP ")) {
+          detail = `\u975E JSON \u54CD\u5E94\uFF08\u53EF\u80FD\u662F\u7F51\u5173/\u524D\u7AEF 404\uFF09`;
+        }
+      }
     }
-    throw new NetworkError(msg, res.status);
+    const ctx = {
+      method,
+      path: path13,
+      url,
+      status: res.status,
+      label: opts.label,
+      responseSnippet
+    };
+    throw new NetworkError(buildHttpErrorMessage(ctx, detail), res.status, ctx);
+  }
+  if (res.status === 204 || res.headers.get("content-length") === "0") {
+    return void 0;
   }
-  return res.json();
+  const text2 = await res.text();
+  if (!text2.trim())
+    return void 0;
+  return JSON.parse(text2);
 }
 
 // cli/shared/src/output.js
@@ -3737,7 +3797,12 @@ function fail(code, message) {
   printJsonSummary({ ok: false, error: { code, message } });
 }
 function handleError(err2) {
-  if (err2 instanceof Error) {
+  if (err2 instanceof NetworkError) {
+    for (const line of err2.formatDetailLines()) {
+      console.error(line);
+    }
+    fail(err2.code, err2.message);
+  } else if (err2 instanceof Error) {
     const code = err2.code ?? "ERR_UNKNOWN";
     console.error(`\u9519\u8BEF: ${err2.message}`);
     fail(code, err2.message);
@@ -3959,7 +4024,7 @@ function makeEnvCommand() {
   return new Command("env").description("\u663E\u793A\u73AF\u5883\u4FE1\u606F").action(() => {
     const auth = tryLoadAuth();
     const env = {
-      version: "3.0.2",
+      version: "3.0.4",
       node: process.version,
       platform: `${import_os5.default.type()} ${import_os5.default.arch()}`,
       serverUrl: getServerUrl(),
@@ -5629,7 +5694,7 @@ function dispatch(msg) {
         result: {
           protocolVersion: "2024-11-05",
           capabilities: { tools: {} },
-          serverInfo: { name: "dazi", version: "3.0.2" }
+          serverInfo: { name: "dazi", version: "3.0.4" }
         }
       };
     case "initialized":
@@ -5752,7 +5817,7 @@ function forwardToCli(cliName, extraArgs) {
   process.exit(result.status ?? 1);
 }
 var program2 = new Command();
-program2.name("dazi").description("\u642D\u5B50 v3 \u2014 Onto / Flow / App \u7EDF\u4E00 CLI").version("3.0.2", "-v, --version");
+program2.name("dazi").description("\u642D\u5B50 v3 \u2014 Onto / Flow / App \u7EDF\u4E00 CLI").version("3.0.4", "-v, --version");
 program2.addCommand(makeAuthCommand());
 program2.addCommand(makeDoctorCommand());
 program2.addCommand(makeEnvCommand());

package/dist/docs/flow/ai-workflow-playbook.md

@@ -1,7 +1,7 @@
 # 流程项目 AI 工作手册
 
 **文档 ID**: `flow/ai-workflow-playbook`  
-**适用**: Cursor / Trae / 任何 Agent 修改 `项目/flow_*/流程/<名>/`
+**适用**: Cursor / Trae / 任何 Agent 修改 `项目/<业务名>/流程/flows/<流程名>/`
 
 > 完整文件规范见 [流程本地文件规范](./local-files-spec.md)。
 
@@ -34,20 +34,21 @@
 ## 3. 标准流程（改现有 excel-python）
 
 ```powershell
-cd "项目\flow_xxx\流程\<流程名>"
+# 推荐绝对路径（禁止在 dazi-work 根 --dir .）
+$flowDir = "D:\path\to\dazi-work\项目\<业务名>\流程\flows\<流程名>"
 
-dazi flow project doctor --dir .
+dazi flow project doctor --dir $flowDir
 # 若不一致：
-dazi flow project repair-meta --dir .
+dazi flow project repair-meta --dir $flowDir
 
 # 改 flow.json 配置后：
-dazi flow project push --dir . --canvas
+dazi flow project push --dir $flowDir --canvas
 
 # 改 code.py 后：
-dazi flow node push --node <node_uuid> --dir .
+dazi flow node push --node <node_uuid> --dir $flowDir
 
-dazi flow run node-exec --node <node_uuid> --dir .
-dazi flow run flow-exec --dir . --type debug
+dazi flow run node-exec --node <node_uuid> --dir $flowDir
+dazi flow run flow-exec --dir $flowDir --type debug
 ```
 
 确认终端出现 **`✅ 画布已全量推送`**。

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

@@ -1,7 +1,7 @@
 # 数据流程项目开发指南
 
 **文档 ID**: `flow/flow-project-guide`  
-**适用**: `dazi-vscode` v3.1+、`dazi-work` 工作区、`项目/flow_*` 流程项目
+**适用**: `dazi-vscode` v3.0.4+、`dazi-work` 工作区、业务项目 `项目/<业务名>/`
 
 ---
 
@@ -11,8 +11,8 @@
 | ---------- | --------------------------------------------------------------- | ------------------- |
 | CLI 入口   | `dazi flow …` → `dazi-flow`（Trae / VS Code / Cursor 交付环境） |
 | **本地文件** | **[流程本地文件规范](./local-files-spec.md)**（AI 必读） |
-| 工作区     | `dazi-work` + `项目/flow_<名>/`                                 |
-| 本地流程树 | `流程/<名>/flow.json` + `节点/<名>/code.*`                      |
+| 工作区     | `dazi-work` + `项目/<业务名>/`（含 `本体/`、`流程/`、`应用/`）   |
+| 本地流程树 | `流程/flows/<流程名>/flow.json` + `节点/<名>/code.*`            |
 | 画布真理源 | **`flow.json`**（= 平台 `config_json` 镜像，代码已剥离）        |
 | 代码真理源 | \*\*`节点/<名>/code.sql                                         | py`** + `node push` |
 | 主交互     | **资源管理器右键** + MVP 流程设计器                             |
@@ -29,24 +29,28 @@ dazi-work/
 ├── scripts/
 │   └── dazi.ps1              ← 终端/Trae 中运行搭子 CLI 的入口
 └── 项目/
-    └── flow_数据集成01/
-        ├── README.md                  项目元信息
-        ├── 快速启动.md                项目级入门
-        ├── 规划/
+    └── 财务分析02/            ← 业务项目名（无 flow_/onto_/app_ 前缀）
+        ├── README.md
+        ├── 本体/ontos/…
+        ├── 应用/apps/…
         └── 流程/
-            └── 客户数据清洗/          ← 一个流程 = 一个目录
-                ├── 快速启动_<流程名>.md   pull 后生成（flowId、常用命令、AI 单文件入口）
-                ├── flow.json          ★ 画布（节点配置 + 边，不含代码正文）
-                ├── flow.meta.json     flowId、uuid 映射、代码指纹（pull / node new / repair-meta 维护，勿手改）
-                ├── 节点/
-                │   └── SQL查询/
-                │       ├── code.sql   ★ 代码唯一真理源
-                │       └── node.info.json
-                ├── 变量/              调试 Run 变量只读派生（schema + 预览）
-                │   └── sales_df.json
-                └── _run/              测试/运行产物（*.last-error.md 等）
+            ├── README.md              流程工作区说明
+            ├── 规划/
+            └── flows/                 各流程实例容器
+                └── 客户数据清洗/      ← 一个流程 = 一个目录
+                    ├── 快速启动_<流程名>.md   pull 后生成（flowId、绝对路径命令、AI 入口）
+                    ├── flow.json          ★ 画布（节点配置 + 边，不含代码正文）
+                    ├── flow.meta.json     flowId、uuid 映射、代码指纹（勿手改）
+                    ├── 节点/
+                    │   └── SQL查询/
+                    │       ├── code.sql   ★ 代码唯一真理源
+                    │       └── node.info.json
+                    ├── 变量/              调试 Run 变量只读派生
+                    └── _run/              测试/运行产物（*.last-error.md 等）
 ```
 
+> **禁止**在 `dazi-work` **工作区根**对流程命令使用 `--dir .`（可能误读根目录残留的 `flow.meta.json`，导致 flowId 与目标流程不一致）。`--dir` 必须指向含 `flow.json` 的 `flows/<流程名>/` 目录，**推荐绝对路径**。
+
 **关键约定**
 
 - 节点 `type` 在画布上恒为 `"custom"`，**业务类型在 `data.type`**（如 `sql-query`、`python-script`）。
@@ -82,23 +86,30 @@ dazi flow <子命令...>
 | `dazi-flow run node-exec …` | `dazi flow run node-exec …` |
 | `dazi-flow variable pull …` | `dazi flow variable pull …` |
 
-**工作目录技巧**：多数命令支持 `--dir <流程目录>`。也可 **`cd` 到流程目录**后省略 `--dir`（cwd 即 `流程/<名>/`）。
+**`--dir` 约定**（Trae / Agent 必读）：
+
+| 方式 | 说明 |
+|------|------|
+| **推荐：绝对路径** | `--dir "D:\path\to\dazi-work\项目\<业务名>\流程\flows\<流程名>"`，不依赖终端 `cd` |
+| 可选：`cd` + `--dir .` | 仅当已确认终端位于目标 `flows/<流程名>/` 时 |
+| **禁止** | 在 `dazi-work` 根执行 `project status/push/pull --dir .` |
+
+CLI 会校验目录含 `flow.json`；从 `节点/` 子路径执行时可向上解析到流程目录。
 
 ```powershell
-# 在 dazi-work 根
+# 鉴权（可在 dazi-work 根）
 cd D:\path\to\dazi-work
 dazi auth whoami
 
-# 拉取平台流程到本地（首次）
-dazi flow project pull --flow 98 --dir "项目\flow_流程项目01\流程\MyFlow0529"
+# 拉取平台流程（推荐绝对路径 --dir）
+dazi flow project pull --flow 98 --dir "D:\path\to\dazi-work\项目\财务分析02\流程\flows\MyFlow0529"
 
-# 进入流程目录后，后续命令可省略 --dir
-cd "项目\flow_流程项目01\流程\MyFlow0529"
-dazi flow project status
-dazi flow node push --node <node_uuid>
+# 状态自检：输出 flowId / 流程名须与 快速启动_*.md 一致
+dazi flow project status --dir "D:\path\to\dazi-work\项目\财务分析02\流程\flows\MyFlow0529"
+dazi flow node push --node <node_uuid> --dir "D:\path\to\dazi-work\项目\财务分析02\流程\flows\MyFlow0529"
 ```
 
-**常用子命令速查**（拉取 / 提交 / 测试 / 变量等）见 [Flow 文档索引 · 流程项目常用命令](./flows-guide.md#流程项目flow_-常用命令)。Plan、数据源等专题见 [执行计划](./plan-guide.md)、[数据源管理](./source-guide.md)。
+**常用子命令速查**见 [Flow 文档索引 · 流程项目常用命令](./flows-guide.md#流程项目业务项目常用命令)。Plan、数据源等见 [执行计划](./plan-guide.md)、[数据源管理](./source-guide.md)。
 
 ---
 
@@ -106,7 +117,7 @@ dazi flow node push --node <node_uuid>
 
 ```text
 1. 新建或拉取
-   扩展：项目/flow_* → 新建流程 / 拉取平台流程
+   扩展：右键 `流程/flows/` → 新建流程 / 拉取平台流程
    CLI： flow project pull --flow <id> --dir <流程目录>
 
 2. 改代码
@@ -163,7 +174,7 @@ dazi flow node push --node <node_uuid>
 | `节点/<名>/code.*`          | 提交、测试、拉取                                       |
 | `变量/`                     | 同步变量到本地                                         |
 | `变量/<名>.json`            | 刷新变量、查看变量信息                                 |
-| `项目/flow_*`               | 新建流程、拉取平台流程                                 |
+| `流程/flows/`（容器目录）   | 新建流程、拉取平台流程                                 |
 | **数据资源 → 文件上传管理** | 浏览平台登记文件、**拉取到本地资源**、复制 AI 附加说明 |
 
 设计器工具栏：**保存 / 校验 / 运行 / 提交 / 拉取**。
@@ -508,3 +519,4 @@ VS Code **打开流程设计器**（右键 `flow.json`）时：
 | 变量查看失败         | 先 **测试节点** 或 **运行流程**；确认 `flow.meta.json` 有 `flowId`                  |
 | 节点测试报缺上游变量 | 先运行上游节点，或 **运行整流程（debug）** 再测当前节点                             |
 | 代码改了平台没更新   | `node push` 或 `project push`；看 `project status` 是否脏                           |
+| flowId 与文档不一致  | 在 dazi-work 根或错误目录执行 `--dir .`；改用 `flows/<名>/` 绝对路径                 |

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

@@ -23,34 +23,41 @@
 
 ## 终端命令前缀
 
-在 **`dazi-work` 根目录**（Trae、VS Code、Cursor 交付环境）：
+命令前缀（Trae、VS Code、Cursor 交付环境）：
 
 ```powershell
 dazi flow <子命令...>
 ```
 
-等价于开发时的 `dazi-flow <子命令...>`。示例：
+等价于开发时的 `dazi-flow <子命令...>`。
+
+> **流程子命令的 `--dir`** 须指向 `项目/<业务名>/流程/flows/<流程名>/`（含 `flow.json`），**推荐绝对路径**。**禁止**在 `dazi-work` 工作区根使用 `--dir .`。
+
+示例：
 
 ```powershell
 dazi flow flows list
-dazi flow project pull --flow 98 --dir "项目\flow_xxx\流程\MyFlow"
+dazi flow project pull --flow 98 --dir "D:\path\to\dazi-work\项目\财务分析02\流程\flows\MyFlow"
+dazi flow project status --dir "D:\path\to\dazi-work\项目\财务分析02\流程\flows\MyFlow"
 ```
 
 ---
 
-## 流程项目（`项目/flow_*`）常用命令
-
-| 任务               | 命令                                                |
-| ------------------ | --------------------------------------------------- |
-| 拉取平台流程到本地 | `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 <流程目录>` |
-| 整流程运行         | `flow run flow-exec --dir <流程目录> --type debug`  |
-| 拉取变量           | `flow variable pull --name <名> --dir <流程目录>`   |
+## 流程项目（业务项目）常用命令
+
+| 任务               | 命令                                                                 |
+| ------------------ | -------------------------------------------------------------------- |
+| 拉取平台流程到本地 | `flow project pull --flow <id> --dir <flows/<名>/绝对路径>`          |
+| 提交代码 + 画布    | `flow project push --dir <flows/<名>/绝对路径> --canvas`             |
+| 目录一致性检查     | `flow project doctor --dir <flows/<名>/绝对路径>`                    |
+| 修复 meta 索引     | `flow project repair-meta --dir <flows/<名>/绝对路径>`               |
+| 查看本地改动       | `flow project status --dir <flows/<名>/绝对路径>`                    |
+| 提交单个节点代码   | `flow node push --node <uuid> --dir <flows/<名>/绝对路径>`           |
+| 单节点测试         | `flow run node-exec --node <uuid> --dir <flows/<名>/绝对路径>`       |
+| 整流程运行         | `flow run flow-exec --dir <flows/<名>/绝对路径> --type debug`        |
+| 拉取变量           | `flow variable pull --name <名> --dir <flows/<名>/绝对路径>`         |
+
+`<flows/<名>/绝对路径>` = `…/项目/<业务名>/流程/flows/<流程名>`。执行 `status` 后核对输出的 **flowId / 流程名** 与 `快速启动_*.md` 一致。
 
 扩展侧栏/资源管理器右键与上表 **同源**，见 [flow-project-guide](./flow-project-guide.md#6-资源管理器菜单主交互)。
 

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

@@ -1,7 +1,7 @@
 # 流程本地文件规范与示例
 
 **文档 ID**: `flow/local-files-spec`  
-**适用**: `项目/flow_*/流程/<名>/` 目录、AI Agent、流程设计器  
+**适用**: `项目/<业务名>/流程/flows/<流程名>/` 目录、AI Agent、流程设计器  
 **关联**: [AI 工作手册](./ai-workflow-playbook.md)、[数据流程项目开发指南](./flow-project-guide.md)
 
 ---
@@ -24,10 +24,10 @@
 ## 2. 标准目录树
 
 ```text
-流程/<流程名>/
+项目/<业务名>/流程/flows/<流程名>/
 ├── flow.json                 # 画布真理源（轻量，无 pythonCode/sql 正文）
 ├── flow.meta.json            # 工程索引（CLI 维护）
-├── 快速启动_<流程名>.md      # pull 后生成（含一致性检查）
+├── 快速启动_<流程名>.md      # pull 后生成（含绝对路径命令、一致性检查）
 ├── 节点/
 │   └── Excel成本报表解析/
 │       ├── code.py           # 代码真理源

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

@@ -1,7 +1,7 @@
 # 节点代码编写指南
 
 **文档 ID**: `flow/node-code-guide`  
-**适用**: `项目/flow_*/流程/<名>/节点/<节点名>/code.*`  
+**适用**: `项目/<业务名>/流程/flows/<流程名>/节点/<节点名>/code.*`  
 **前置**: **[流程本地文件规范](./local-files-spec.md)**（必读）、[数据流程项目开发指南](./flow-project-guide.md)、[流程变量系统指南](./variables-guide.md)
 
 > 设计器「打开代码」依赖 `flow.meta.json` 中该节点的 `dir`+`codeFile`。若打不开，先 `dazi flow project doctor` → `repair-meta`。
@@ -40,19 +40,19 @@
 ## 2. 修改代码的标准流程
 
 ```powershell
-# 1. 进入流程目录（dazi-work 根下）
-cd "项目\flow_xxx\流程\MyFlow"
+# 1. 确定流程目录（推荐绝对路径）
+$flowDir = "D:\path\to\dazi-work\项目\<业务名>\流程\flows\MyFlow"
 
 # 2. 编辑 节点/SQL查询/code.sql 等
 
 # 3. 查看是否有本地改动
-dazi flow project status
+dazi flow project status --dir $flowDir
 
-# 4. 单节点测试（会先 GET debug-run，再 POST 单节点运行）
-dazi flow run node-exec --node <node_uuid> --dir .
+# 4. 单节点测试
+dazi flow run node-exec --node <node_uuid> --dir $flowDir
 
 # 5. 提交代码到平台
-dazi flow node push --node <node_uuid> --dir .
+dazi flow node push --node <node_uuid> --dir $flowDir
 ```
 
 `node_uuid` 在 `flow.meta.json` → `nodes.<uuid>`，或设计器属性面板、 `node.info.json` 中查看。  

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

@@ -3,17 +3,17 @@
 **文档 ID**: `flow/run-guide`
 
 **命令前缀**（`dazi-work` 根）：`dazi flow …`  
-**流程项目**：在 `项目/flow_*/流程/<名>/` 下执行，或使用 `--dir <流程目录>`。
+**流程项目**：`--dir` 指向 `项目/<业务名>/流程/flows/<流程名>/`（**推荐绝对路径**；禁止在 `dazi-work` 根 `--dir .`）。
 
 ---
 
 ## 1. 流程项目：单节点测试（最常用）
 
 ```powershell
-cd "项目\flow_xxx\流程\MyFlow"
+$flowDir = "D:\path\to\dazi-work\项目\<业务名>\流程\flows\MyFlow"
 
 # 按 node_uuid 测试（CLI 内部翻译为语义 nodeId）
-dazi flow run node-exec --node <node_uuid> --dir .
+dazi flow run node-exec --node <node_uuid> --dir $flowDir
 ```
 
 **行为**

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

@@ -84,16 +84,16 @@ GET /flows/{id}/debug-run  →  绑定 ads_flows.debug_run_id
 ```
 
 ```powershell
-cd "项目\flow_xxx\流程\MyFlow"
+$flowDir = "D:\path\to\dazi-work\项目\<业务名>\流程\flows\MyFlow"
 
 # 先运行产出变量的上游节点，或整流程 debug
-dazi flow run node-exec --node <上游uuid> --dir .
+dazi flow run node-exec --node <上游uuid> --dir $flowDir
 
 # 拉取单个变量（列信息 + 前 10 行）
-dazi flow variable pull --name sales_clean --dir .
+dazi flow variable pull --name sales_clean --dir $flowDir
 
 # 同步调试 Run 中全部变量
-dazi flow variable sync --dir .
+dazi flow variable sync --dir $flowDir
 ```
 
 - 设计器：选中节点 → **`output_variable_name`** 旁 **📊**

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

@@ -49,7 +49,7 @@ dazi onto function list --space <space-id>
 | ---------------------------------------------------------------- | ----------------------------------------------------------------------- |
 | `dazi auth whoami`                                               | 原 `dazi auth whoami`                                                   |
 | `dazi onto script publish ...`                                   | 原 `dazi onto script publish ...`（**勿用** `dazi-onto`）               |
-| `dazi flow project pull --flow 98 --dir 项目\flow_x\流程\MyFlow` | 流程项目拉取                                                            |
+| `dazi flow project pull --flow 98 --dir …\项目\<业务名>\流程\flows\MyFlow` | 流程项目拉取（`--dir` 推荐绝对路径）                                    |
 | `dazi flow run node-exec --node <uuid> --dir <流程目录>`         | 单节点测试                                                              |
 | `pnpm run dazi-app -- upload ...`                                | 原 `dazi-app upload ...`（须在**应用项目根**，含 `sdk/`、`templates/`） |
 
@@ -65,7 +65,8 @@ dazi onto function list --space <space-id>
 因此文档里的 `dazi-flow project pull …` 在 Trae / VS Code 交付环境中应写为：
 
 ```powershell
-dazi flow project pull --flow 98 --dir "项目\flow_xxx\流程\MyFlow"
+# --dir 须指向 flows/<流程名>/（含 flow.json）；禁止在 dazi-work 根 --dir .
+dazi flow project pull --flow 98 --dir "D:\path\to\dazi-work\项目\财务分析02\流程\flows\MyFlow"
 ```
 
 流程项目开发详见 [flow/flow-project-guide](../flow/flow-project-guide.md)。