@qingflow-tech/qingflow-cli 1.1.33 → 1.1.35

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.33
+npm install @qingflow-tech/qingflow-cli@1.1.35
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.33 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.35 qingflow
 ```
 
 Environment:

package/docs/local-agent-install.md

@@ -84,6 +84,7 @@ npm run pack:npm
 
 ```bash
 dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
+dist/npm/qingflow-cli-<version>.tgz
 dist/npm/qingflow-tech-qingflow-app-user-mcp-<version>.tgz
 dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
 ```
@@ -91,11 +92,20 @@ dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
 然后在目标机器安装：
 
 ```bash
+npx -y -p /absolute/path/to/dist/npm/qingflow-cli-<version>.tgz qingflow-cli install --package /absolute/path/to/dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
 npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
 npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-user-mcp-<version>.tgz
 npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
 ```
 
+线上官网入口对应：
+
+```bash
+npx qingflow-cli@latest install
+```
+
+安装器只安装真实 CLI 包 `@qingflow-tech/qingflow-cli`。它会先检查 Node.js、npm 和 Python 3.11+；如果 `npm install -g` 因本机全局目录权限失败，安装器会自动 fallback 到用户目录（macOS/Linux 为 `~/.local`，Windows 为当前用户 AppData npm 目录），但不会修改 shell 配置文件；PATH 缺失时会打印需要执行的 shell / PowerShell 命令。排障可加 `--verbose`；如需禁止 fallback 可加 `--no-fallback`。
+
 安装时会自动：
 
 1. 创建 `.npm-python/`

package/npm/lib/runtime.mjs

@@ -4,6 +4,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 const WINDOWS = process.platform === "win32";
+const MIN_PYTHON_VERSION = [3, 11, 0];
 
 const PKG_BY_BIN = {
   qingflow: "qingflow-cli",
@@ -26,11 +27,41 @@ function runChecked(command, args, options = {}) {
   }
 }
 
-function commandWorks(command, args) {
+function commandResult(command, args) {
   const result = spawnSync(command, args, {
-    stdio: "ignore",
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
   });
-  return result.status === 0;
+  return {
+    status: result.status ?? 1,
+    error: result.error,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  };
+}
+
+function parseVersion(text) {
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(text);
+  if (!match) {
+    return null;
+  }
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+function versionAtLeast(current, minimum) {
+  for (let index = 0; index < minimum.length; index += 1) {
+    if ((current[index] ?? 0) > minimum[index]) {
+      return true;
+    }
+    if ((current[index] ?? 0) < minimum[index]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function formatVersion(version) {
+  return version.join(".");
 }
 
 export function getPackageRoot(metaUrl) {
@@ -449,6 +480,40 @@ export function inspectPythonEnv(packageRoot, commandName = "qingflow-mcp") {
   };
 }
 
+function getRuntimeProbeModule(commandName) {
+  if (commandName === "qingflow") {
+    return "qingflow_mcp.cli.main";
+  }
+  if (commandName === "qingflow-app-user-mcp") {
+    return "qingflow_mcp.server_app_user";
+  }
+  if (commandName === "qingflow-app-builder-mcp") {
+    return "qingflow_mcp.server_app_builder";
+  }
+  return "qingflow_mcp";
+}
+
+function probePythonRuntime(packageRoot, commandName) {
+  const python = getVenvPython(packageRoot);
+  if (!fs.existsSync(python)) {
+    return { ok: false, details: `missing Python executable: ${python}` };
+  }
+  const moduleName = getRuntimeProbeModule(commandName);
+  const result = spawnSync(python, ["-c", `import ${moduleName}`], {
+    cwd: packageRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.error) {
+    return { ok: false, details: result.error.message };
+  }
+  if (result.status !== 0) {
+    const details = [result.stderr, result.stdout].filter((value) => typeof value === "string" && value.trim()).join("\n");
+    return { ok: false, details: details || `import ${moduleName} failed` };
+  }
+  return { ok: true, details: "" };
+}
+
 function formatRuntimeProblem(runtime, commandName, { allowRuntimeBootstrap = false } = {}) {
   const problemLines = [];
   for (const problem of runtime.problems) {
@@ -511,30 +576,38 @@ function findOfflineProjectWheel(findLinksDir) {
 export function findPython() {
   const preferred = process.env.QINGFLOW_MCP_PYTHON?.trim();
   const candidates = preferred
-    ? [{ command: preferred, args: [], label: preferred }]
+    ? [{ command: preferred, checkArgs: ["-V"], runArgs: [], label: preferred }]
     : WINDOWS
       ? [
-          { command: "py", args: ["-3", "-V"], label: "py -3" },
-          { command: "python", args: ["-V"], label: "python" },
-          { command: "python3", args: ["-V"], label: "python3" },
+          { command: "py", checkArgs: ["-3", "-V"], runArgs: ["-3"], label: "py -3" },
+          { command: "python", checkArgs: ["-V"], runArgs: [], label: "python" },
+          { command: "python3", checkArgs: ["-V"], runArgs: [], label: "python3" },
         ]
       : [
-          { command: "python3", args: ["-V"], label: "python3" },
-          { command: "python", args: ["-V"], label: "python" },
+          { command: "python3", checkArgs: ["-V"], runArgs: [], label: "python3" },
+          { command: "python", checkArgs: ["-V"], runArgs: [], label: "python" },
         ];
 
+  const rejected = [];
   for (const candidate of candidates) {
-    if (commandWorks(candidate.command, candidate.args)) {
-      if (candidate.command === "py") {
-        return { command: "py", args: ["-3"], label: candidate.label };
-      }
-      return { command: candidate.command, args: [], label: candidate.label };
+    const result = commandResult(candidate.command, candidate.checkArgs);
+    if (result.status !== 0) {
+      continue;
+    }
+    const version = parseVersion(`${result.stdout}\n${result.stderr}`);
+    if (!version) {
+      rejected.push(`${candidate.label}: version could not be parsed`);
+      continue;
     }
+    if (!versionAtLeast(version, MIN_PYTHON_VERSION)) {
+      rejected.push(`${candidate.label}: ${formatVersion(version)}`);
+      continue;
+    }
+    return { command: candidate.command, args: candidate.runArgs, label: `${candidate.label} (${formatVersion(version)})` };
   }
 
-  throw new Error(
-    "Python 3.11+ was not found. Set QINGFLOW_MCP_PYTHON to a Python 3 executable before running npm install."
-  );
+  const rejectedText = rejected.length ? ` Detected but rejected: ${rejected.join(", ")}.` : "";
+  throw new Error(`Python ${formatVersion(MIN_PYTHON_VERSION)}+ was not found.${rejectedText} Set QINGFLOW_MCP_PYTHON to a Python 3.11+ executable before running npm install.`);
 }
 
 export function ensurePythonEnv(packageRoot, { force = false, commandName = "qingflow-mcp" } = {}) {
@@ -544,7 +617,11 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
   const { packageVersion, serverCommand, stampPath, venvDir, stampVersion } = runtime;
 
   if (!force && fs.existsSync(serverCommand) && fs.existsSync(stampPath) && stampVersion && stampVersion === packageVersion) {
-    return serverCommand;
+    const probe = probePythonRuntime(packageRoot, commandName);
+    if (probe.ok) {
+      return serverCommand;
+    }
+    fs.rmSync(venvDir, { recursive: true, force: true });
   }
 
   if (force && fs.existsSync(venvDir)) {
@@ -571,6 +648,11 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
   }
   runChecked(pip, pipArgs, { cwd: packageRoot });
 
+  const probe = probePythonRuntime(packageRoot, commandName);
+  if (!probe.ok) {
+    throw new Error(`Bootstrap finished but Python runtime import probe failed:\n${probe.details}`);
+  }
+
   fs.writeFileSync(
     stampPath,
     JSON.stringify(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-cli",
-  "version": "1.1.33",
+  "version": "1.1.35",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.1.33"
+version = "1.1.35"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-cli/SKILL.md

@@ -9,7 +9,7 @@ description: |
 
 # Qingflow CLI 使用技能
 
-> **Skill 版本**：`qingflow-skills-2026.07.01.03`（入口文档版本；CLI 包版本用 `qingflow --version`；需要定位版本漂移时用 `qingflow --json version` 读取 `version/package/command_path/executable_path/package_root/skill_version`）。
+> **Skill 版本**：`qingflow-skills-2026.07.01.04`（入口文档版本；CLI 包版本用 `qingflow --version`；需要定位版本漂移时用 `qingflow --json version` 读取 `version/package/command_path/executable_path/package_root/skill_version`）。
 
 **硬约束（必读）**：正文各节与文末「命令速查」中的命令**只作子命令形态索引**，不覆盖 JSON 结构、`--*-file` 键名、枚举全集、执行顺序与排障细节。凡工作**偏复杂**（多步串联、大块 payload、导入全链、**Builder 搭建向**（应用/schema/流程/布局/视图/门户/报表/按钮/关联资源的配置与发布、系统列与字段 `type`）、契约型 `apply`、按 schema 组织写入 payload、任务下钻与 `task action` 等），或你判断当前任务与「关联文件」里某篇所描述的内容**需求一致、场景相同或大体同类**，都应**先 Read 对应 `reference/...` 文档**，再结合 `qingflow … --help` 与 **[EXPLORATION_REPORT](./reference/core/QINGFLOW_CLI_EXPLORATION_REPORT.md)**。**禁止**仅凭索引、习惯或类比去补参数、臆造字段名或推断服务端行为。**CLI 自动化场景只通过 `qingflow` 命令工作**；相关说明已按主题合并为本文档下的 `reference/` 子目录。**最终统计结论、分析报告、趋势/排名/比例/分布**统一走 **[record/analysis](./reference/record/analysis/README.md)** 的 `qingflow record access -> Python/pandas`。
 
@@ -36,13 +36,13 @@ description: |
 | [reference/builder/60-charts.md](./reference/builder/60-charts.md) | **报表 / QingBI**：指标卡、图表、语义聚合、筛选、排序、更新 |
 | [reference/builder/70-portal.md](./reference/builder/70-portal.md) | **门户**：标准工作台、业务入口、指标、图表、视图组件、发布 |
 | [reference/builder/80-buttons-associated-resources.md](./reference/builder/80-buttons-associated-resources.md) | **关联资源 / 非主链路按钮维护**：关联视图/报表、`match_mappings`、上下文传参；按钮配置看视图文档 `action_buttons` |
-| [reference/builder/90-workflow.md](./reference/builder/90-workflow.md) | **流程**：流程预设、`patch_nodes`、角色/成员、流程回读 |
+| [reference/builder/90-workflow.md](./reference/builder/90-workflow.md) | **流程**：WorkflowSpec、`patch_nodes`、角色/成员、流程回读 |
 | [reference/builder/99-publish-verify.md](./reference/builder/99-publish-verify.md) | **发布与回读**：`publish verify`、partial/readback 处理、最终汇报口径 |
 | [reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md) | **新建记录**：`record schema insert -> record insert --items-file`；成员/部门/关联优先自然语言输入；细节见 [record/insert](./reference/record/insert/README.md) |
 | [reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md) | **更新记录**：主链路是 `record get` → 智能体按 `fields[]` 组 key/value → **`record update`**；`record schema update` 仅用于失败后诊断可写字段/路径                                                                                                                                 |
 | [reference/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md) | **删除记录**：`record list/get` 精确定位 → `record delete --app-key --record-id --view-id system:*`；批量用 `--record-ids-file` |
 | [reference/record/analysis/README.md](./reference/record/analysis/README.md) | **数据分析**：最终统计结论、分析报告、趋势/排名/比例/分布统一走 `record access -> Python/pandas` |
-| [reference/builder/reference/app-delivery-sop.md](./reference/builder/reference/app-delivery-sop.md) | **底层交付参考**：历史完整 SOP、权限、旧 fallback、系统列和工具细节；不是主入口 |
+| [reference/builder/reference/app-delivery-sop.md](./reference/builder/reference/app-delivery-sop.md) | **底层交付参考**：历史完整 SOP、权限、系统列和工具细节；不是主入口 |
 | [reference/builder/reference/workspace-icons.md](./reference/builder/reference/workspace-icons.md) | **图标参考**：`builder icon catalog`；新建应用包、应用、门户必须显式选择非 `template` 的 `icon + color` |
 | [reference/builder/reference/match-rules.md](./reference/builder/reference/match-rules.md) | **统一筛选 / 条件写法**：`filters`、`visible_when`、QingBI 图表筛选、工作流条件、`match_mappings`、`field_mappings` 的 `operator/value` 规则 |
 | [reference/builder/workflow/README.md](./reference/builder/workflow/README.md) | **工作流搭建**：已有应用的流程建模、节点配置、`builder flow apply` 与 `patch_nodes` |
@@ -70,10 +70,10 @@ description: |
 > 仅qingflow命令执行后发现不可用再安装，不需要进行校验动作
 
 ```bash
-npm install -g @qingflow-tech/qingflow-cli@latest
+npx qingflow-cli@latest install
 ```
 
-环境：Node.js v16+、npm、可达轻流 API。
+安装器会安装真实 CLI 包 `@qingflow-tech/qingflow-cli@latest`；会预检 Node.js、npm、Python 3.11+；若全局 npm 目录权限不足，会 fallback 到用户目录（macOS/Linux 为 `~/.local`，Windows 为用户 AppData npm 目录）并提示 PATH 配置，不会自动改 shell 文件。排障可加 `--verbose`。环境：Node.js v16+、npm、Python 3.11+、可达 npm registry / 轻流 API。
 
 ---
 

package/skills/qingflow-cli/reference/builder/90-workflow.md

@@ -11,7 +11,7 @@ Not responsible for: guessing raw backend fields without first reading `builder
 ## Main chain
 
 ```text
-contract -> app get fields -> builder flow schema -> builder flow get -> member/role lookup -> build WorkflowSpec or patch_nodes -> flow apply --spec-file/--patch-nodes-file -> builder flow get readback
+contract -> app get fields -> builder flow schema -> builder flow get -> member/role lookup -> build WorkflowSpec -> flow apply --spec-file -> builder flow get readback
 ```
 
 ## Demo/reference files
@@ -21,20 +21,14 @@ Workflow examples depend on live `builder flow schema`, field ids, role ids, and
 ## Recommended write path
 
 - Before applying a workflow, verify the app has an explicit business status select field such as `状态`, `处理状态`, `审批状态`, `工单状态`, `计划状态`, `报工状态`, or `单据状态`. Domain result fields are not enough by themselves: for example, `检验结论` should be paired with `处理状态`.
-- For full workflow replacement, prefer `builder flow get` / `builder flow schema`, then submit a complete WorkflowSpec with `--spec-file`.
-- Use legacy `--nodes-file` + `--transitions-file` only for deliberately simple linear compatibility flows; it is not the main workflow path.
-- Start from a preset when possible: `basic_approval` or `basic_fill_then_approve`.
-- Patch preset node ids instead of adding duplicate nodes:
-  - `basic_approval` -> `approve_1`
-  - `basic_fill_then_approve` -> `fill_1`, `approve_1`
-- Use `patch_nodes[]` for targeted updates to an existing flow. Node ids come from `builder flow get` readback, not from the original public `nodes-file` ids after the backend has assigned workflow node ids.
+- For workflow creation or replacement, always use `builder flow get` / `builder flow schema`, then submit a complete WorkflowSpec with `--spec-file`.
+- Do not use `--nodes-file` + `--transitions-file` in skill-led workflow builds. Even simple linear workflows should be represented as WorkflowSpec.
+- Use `patch_nodes[]` only for targeted maintenance of existing nodes. Node ids come from `builder flow get` readback.
 - Do not mix `patch_nodes` and full `spec` in the same call.
 
-## Legacy public node types
+## Input modes
 
-Legacy `--nodes-file` supports only `start`, `approve`, `fill`, `copy`, `webhook`, and `end`.
-
-Branching or richer routing should use the WorkflowSpec `--spec-file` path after reading the schema.
+All workflow creation and replacement uses WorkflowSpec through `--spec-file`. Existing-node maintenance can use `--patch-nodes-file` after readback. This is the only skill-led workflow write path for linear, branching, Q-Robot, approval, filling, and cc flows.
 
 ## Detailed workflow docs
 

package/skills/qingflow-cli/reference/builder/README.md

@@ -52,7 +52,7 @@ Rules:
 | [60-charts.md](./60-charts.md) | Standalone QingBI chart maintenance; portal dashboards normally use section `chart` for missing reports |
 | [70-portal.md](./70-portal.md) | Portal apply/delete, standard workbench layout, component config, section `chart` |
 | [80-buttons-associated-resources.md](./80-buttons-associated-resources.md) | Associated views/reports and context mappings; standalone button maintenance only when the user explicitly asks to maintain existing button bodies outside view design |
-| [90-workflow.md](./90-workflow.md) | Flow presets, patch_nodes, workflow verification |
+| [90-workflow.md](./90-workflow.md) | WorkflowSpec, patch_nodes, workflow verification |
 | [99-publish-verify.md](./99-publish-verify.md) | Publish verification, partial success, readback-before-retry |
 
 ## Example files

package/skills/qingflow-cli/reference/builder/reference/app-delivery-sop.md

@@ -306,14 +306,11 @@ qingflow builder layout apply \
 ```bash
 qingflow builder flow apply \
   --app-key "<APP_KEY>" \
-  --mode replace \
   [--publish | --no-publish] \
-  --nodes-file tmp/nodes.json \
-  --transitions-file tmp/transitions.json
+  --spec-file tmp/flow_spec.json
 ```
 
-- **`mode`**：CLI 当前仅 **`replace`**。
-- **限制**（契约 **execution_notes**）：公开面 **有意仅支持线性流程**；**分支 / 条件节点不可用**（后端前端组合不稳定）。
+- 公开智能体链路只使用 WorkflowSpec `--spec-file` 或已有节点 `--patch-nodes-file`。
 
 ---
 
@@ -398,7 +395,7 @@ qingflow builder flow apply \
 ### 7.2 布局 / 流程中的「系统行为」
 
 - **布局**：仅摆放 **`app_get_fields`** 里出现的 **`name`**；不要把上表系统列名放进 **`rows`** 除非读回确认存在对应可摆放控件。
-- **流程**：**`app_flow_apply` 的 `permissions.editable_fields`** 等须引用 **真实业务字段名**（读 `fields`）。流程需要状态时，创建业务字段 `状态` / `处理状态` 等，不创建平台字段 `当前流程状态`。
+- **流程**：WorkflowSpec 中的字段权限、条件和自动化映射须引用 **真实业务字段名 / 字段 id**（先读 `fields` 与 `builder flow schema`）。流程需要状态时，创建业务字段 `状态` / `处理状态` 等，不创建平台字段 `当前流程状态`。
 
 ---
 

package/skills/qingflow-cli/reference/builder/workflow/01-overview.md

@@ -6,14 +6,14 @@
 |------|------|
 | `manifest.yaml` | 技能清单 |
 | `SKILL.md` | 主流程入口 |
-| `scripts/validate_flow_spec.py` | 工作流 Spec 验证脚本，基于 JSON Schema + 自定义约束 |
-| `scripts/diff_flow_spec.py` | 新旧 Spec 差异分析脚本，辅助更新模式下最小修改原则判断 |
+| `scripts/workflow/validate_flow_spec.py` | 工作流 Spec 验证脚本，基于 JSON Schema + 自定义约束 |
+| `scripts/workflow/diff_flow_spec.py` | 新旧 Spec 差异分析脚本，辅助更新模式下最小修改原则判断 |
 
 ---
 
 ## 依赖声明
 
-本 Skill 关键依赖 **qingflow CLI**（已安装于 PATH，详见 `qingflow_cli` Skill）。以下 qingflow 命令为核心操作：
+本 Skill 关键依赖 **qingflow CLI**（已安装于 PATH，详见主入口 `qingflow-cli` Skill）。以下 qingflow 命令为核心操作：
 
 | 命令 | 用途 |
 |------|------|
@@ -21,7 +21,6 @@
 | `qingflow builder flow get --app-key <KEY>` | 读取当前工作流 spec |
 | `qingflow --json builder flow apply --app-key <KEY> --spec-file <FILE>` | 主链路：部署/更新 WorkflowSpec |
 | `qingflow --json builder flow apply --app-key <KEY> --patch-nodes-file <PATCH>` | 局部修改现有节点 |
-| `qingflow --json builder flow apply --app-key <KEY> --nodes-file <NODES> --transitions-file <TRANSITIONS>` | 兼容链路：简单线性 public 工作流 |
 | `qingflow builder member search --query <关键词>` | 搜索成员 |
 | `qingflow builder role search --keyword <关键词>` | 搜索角色 |
 | `qingflow --json app get --app-key <KEY>` | 获取应用信息（字段列表等） |
@@ -35,7 +34,7 @@
 | 在范围内 | 超出范围 |
 |----------|----------|
 | 基于已有应用搭建工作流 | 从零创建应用 |
-| WorkflowSpec 生成与 apply；public nodes/transitions 兼容简单线性流程 | 操作复杂命令拼接 |
+| WorkflowSpec 生成与 apply；`patch_nodes` 仅用于已有节点局部维护 | 操作复杂命令拼接 |
 | 审批/填写/抄送/分支条件等 WorkflowSpec 支持的流程 | 不读 schema/spec 就猜 raw 后端字段 |
 | 审批/填写/抄送/自动化节点配置 | 修改字段定义 |
 | 成员/角色搜索用于节点负责人 | 组织架构管理 |
@@ -43,5 +42,7 @@
 
 ---
 
+无论线性、分支、Q-Robot、审批、填写还是抄送流程，新建和替换都使用 WorkflowSpec `--spec-file`；已有节点的小修改才使用 `--patch-nodes-file`。不要在技能主链路使用 `--nodes-file` + `--transitions-file`。
+
 ← 返回主流程：[../SKILL.md](../../../SKILL.md)
 → 下一步：[02-update-mode.md](02-update-mode.md)

package/skills/qingflow-cli/reference/builder/workflow/03-flow-patterns.md

@@ -16,7 +16,7 @@ n1 → n2 → n3 → n4
 
 ## 分支流程
 
-分支流程属于 WorkflowSpec 主路径，不是简单线性兼容 `builder flow apply --nodes-file --transitions-file` 的能力范围。需要分支时先读 `builder flow schema` / `builder flow get`，再用 `--spec-file` 提交完整 WorkflowSpec。
+分支流程属于 WorkflowSpec 主路径。需要分支时先读 `builder flow schema` / `builder flow get`，再用 `--spec-file` 提交完整 WorkflowSpec。
 
 轻流的分支采用**并行分支**模型——通过 `gateway` 节点（`mode: parallel`）分发，所有出边指向的分支**都会进入**，通过每条边上的条件（`condition.autoJudges`）控制分支内的节点逻辑是否执行。
 

package/skills/qingflow-cli/reference/builder/workflow/06-stage3-build-spec.md

@@ -19,48 +19,16 @@ qingflow --json builder flow get --app-key <APP_KEY> > tmp/current_flow.json
 **更新模式下**：如果走 `patch_nodes[]`，直接使用读回的 `spec.nodes[].id` 做局部修改；如果提交完整 `--spec-file`，用 diff 脚本确认变更范围是否符合预期：
 
 ```bash
-python3 scripts/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
+python3 scripts/workflow/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
 ```
 
 新建场景可跳过此步。
 
-## 3.3 兼容：构建 public nodes / transitions（仅简单线性）
+## 3.3 主路径：构建 WorkflowSpec
 
-完整流程主链路是 `WorkflowSpec --spec-file` 或现有流程的 `patch_nodes`。只有明确是简单线性审批/填写/抄送流程时，才继续写两个 public alias 数组文件：
+`--spec-file` 用于已经从 `builder flow schema` / `builder flow get` 读回并理解的 WorkflowSpec。节点结构、节点 id、负责人、字段权限和边条件都以 schema/readback 为准。
 
-`tmp/flow_nodes.json`
-
-```json
-[
-  {"id": "start", "type": "start", "name": "提交申请"},
-  {"id": "approve_1", "type": "approve", "name": "部门经理审批", "role_names": ["部门经理"]},
-  {"id": "end", "type": "end", "name": "结束"}
-]
-```
-
-`tmp/flow_transitions.json`
-
-```json
-[
-  {"from": "start", "to": "approve_1"},
-  {"from": "approve_1", "to": "end"}
-]
-```
-
-提交时使用：
-
-```bash
-qingflow --json builder flow apply \
-  --app-key <APP_KEY> \
-  --nodes-file tmp/flow_nodes.json \
-  --transitions-file tmp/flow_transitions.json \
-  --publish \
-  > tmp/flow_apply.json
-```
-
-## 3.4 主路径：构建 WorkflowSpec
-
-`--spec-file` 用于已经从 `builder flow schema` / `builder flow get` 读回并理解的 WorkflowSpec。不要把 `start` / `approve` / `fill` / `end` 这类 legacy public node alias 放进 `--spec-file`。
+所有需要继续向下路由的节点都显式写 `sync: true`。Q-Robot 也在 WorkflowSpec 中表达为 `type: "automation"`，由 `attrs.subType` 选择具体能力。
 
 WorkflowSpec 示例：
 
@@ -71,12 +39,14 @@ WorkflowSpec 示例：
       "id": "n1",
       "type": "applicant",
       "name": "员工提交申请",
+      "sync": true,
       "attrs": {}
     },
     {
       "id": "n2",
       "type": "approval",
       "name": "部门经理审批",
+      "sync": true,
       "attrs": {
         "responsible": [
           {"type": "role", "roleId": 123}
@@ -92,17 +62,39 @@ WorkflowSpec 示例：
       "id": "g1",
       "type": "gateway",
       "name": "服务类型判断",
+      "sync": true,
       "attrs": {"mode": "parallel"}
     },
     {
       "id": "n3",
       "type": "filling",
       "name": "补充信息",
+      "sync": true,
       "attrs": {
         "responsible": [
           {"type": "user", "uid": 456}
         ]
       }
+    },
+    {
+      "id": "n4",
+      "type": "approval",
+      "name": "技术服务审批",
+      "sync": true,
+      "attrs": {
+        "responsible": [
+          {"type": "role", "roleId": 456}
+        ],
+        "approveType": "or_signed",
+        "auditUserType": "role"
+      }
+    },
+    {
+      "id": "g2",
+      "type": "gateway",
+      "name": "分支汇合",
+      "sync": true,
+      "attrs": {"mode": "join"}
     }
   ],
   "edges": {
@@ -146,7 +138,9 @@ WorkflowSpec 示例：
             ]
           ]
         }
-      }
+      },
+      {"from": "n3", "to": "g2"},
+      {"from": "n4", "to": "g2"}
     ]
   }
 }
@@ -165,7 +159,7 @@ WorkflowSpec 示例：
 
 ## 边条件体系
 
-本节属于 `--spec-file` WorkflowSpec 路径。不要凭记忆手写 `autoJudges`、`judgeType` 或 raw `fieldId` 条件；先读 `builder flow schema` / `builder flow get`，再按读回结构修改。简单线性兼容链路才使用 `builder flow apply --nodes-file --transitions-file`。
+本节属于 `--spec-file` WorkflowSpec 路径。不要凭记忆手写 `autoJudges`、`judgeType` 或 raw `fieldId` 条件；先读 `builder flow schema` / `builder flow get`，再按读回结构修改。
 
 | condition.kind | 含义 | 要求 |
 |---------------|------|------|
@@ -192,7 +186,7 @@ OR-of-AND 二维数组：
 
 **judgeType 常用值**：`equals`, `not_equals`, `equals_any`, `includes`, `greater_than` 等（共21种，详见 schema）。
 
-## 3.5 局部修改 patch_nodes
+## 3.4 局部修改 patch_nodes
 
 局部修改现有流程时，先 `builder flow get`，使用读回 `spec.nodes[].id`：
 

package/skills/qingflow-cli/reference/builder/workflow/07-stage4-validate-spec.md

@@ -2,22 +2,15 @@
 
 主链路 `--spec-file` 使用本 Skill 自带的 WorkflowSpec 验证脚本；局部修改 `patch_nodes[]` 至少检查节点 id 来自 `builder flow get` 读回，且 `set/unset` 只包含要改的字段。
 
-简单线性兼容输入 `--nodes-file + --transitions-file` 由 CLI 模型校验 public node type、边引用和角色/成员解析。提交前至少检查：
-
-- `nodes[].id` 唯一；
-- `transitions[].from/to` 都能在 nodes 中找到；
-- 节点类型只用 `start`、`approve`、`fill`、`copy`、`webhook`、`end`；
-- 审批/填写节点有明确 `member_names`、`member_ids`、`role_names` 或 `role_ids`。
-
 WorkflowSpec 验证命令：
 
 ```bash
 # WorkflowSpec 新建模式
-python3 scripts/validate_flow_spec.py \
+python3 scripts/workflow/validate_flow_spec.py \
   tmp/flow_spec.json --schema tmp/flow_schema.json
 
 # WorkflowSpec 更新模式（同时校验最小修改原则）
-python3 scripts/validate_flow_spec.py \
+python3 scripts/workflow/validate_flow_spec.py \
   tmp/flow_spec.json --schema tmp/flow_schema.json --previous tmp/current_flow.json
 ```
 
@@ -30,10 +23,11 @@ python3 scripts/validate_flow_spec.py \
 5. 审批/填写/抄送节点必要字段检查
 6. 自动化节点配置检查
 7. 孤立节点检查
+8. 入口节点和需要继续路由的节点显式 `sync: true`
 
 ## 验证不通过时的处理
 
-WorkflowSpec 根据验证脚本错误修正 spec，重新验证，直到全部通过再进入 apply。简单线性兼容输入根据 CLI 错误修正 nodes/transitions。
+WorkflowSpec 根据验证脚本错误修正 spec，重新验证，直到全部通过再进入 apply。
 
 ---
 

package/skills/qingflow-cli/reference/builder/workflow/08-stage5-apply-verify.md

@@ -12,8 +12,6 @@ qingflow --json builder flow apply \
   > tmp/flow_apply.json
 ```
 
-简单线性兼容流程仍可用 `--nodes-file + --transitions-file`；不要和 `--spec-file` / `--patch-nodes-file` 混用。
-
 局部修改已存在节点：
 
 ```bash
@@ -41,6 +39,7 @@ qingflow --json builder flow get --app-key <APP_KEY> > tmp/deployed_flow.json
 
 1. **节点数量与类型**：`nodes` 数量是否一致，每个节点的 `type` 和 `name` 是否正确
 2. **边连通性**：`edges` 数量是否一致，`from`/`to` 关系是否正确
+   - 必须确认 `applicant` 入口节点存在出边，不能只停留在“提交申请”
 3. **分支条件**（WorkflowSpec 路径）：每个 gateway 出边是否有正确的 `autoJudges`
    - 检查 `condition.kind` 是否为 `rules`
    - 检查 `autoJudges` 中的 `fieldId`、`judgeType`、`values` 是否正确
@@ -53,7 +52,7 @@ qingflow --json builder flow get --app-key <APP_KEY> > tmp/deployed_flow.json
 
 若验证发现不一致：
 1. 分析差异原因（条件格式错误、节点缺失、边遗漏等）
-2. 主路径修正 `tmp/flow_spec.json` 或 `tmp/flow_patch_nodes.json`；只有简单线性兼容输入才修正 `tmp/flow_nodes.json` / `tmp/flow_transitions.json`
+2. 主路径修正 `tmp/flow_spec.json` 或 `tmp/flow_patch_nodes.json`
 3. 重新验证 → apply → 对比
 4. **最多循环 3 次**；若 3 次后仍有不可修复的差异，告知用户并列出：
    - 已成功配置的部分

package/skills/qingflow-cli/reference/builder/workflow/11-troubleshooting.md

@@ -1,12 +1,13 @@
 # 常见问题与排障
 
-`autoJudges` 属于 WorkflowSpec 路径。公开主链路是先读 `builder flow schema` / `builder flow get`，再提交 `--spec-file` 或 `--patch-nodes-file`；简单线性兼容链路 `nodes-file + transitions-file` 不要求智能体手写这些字段。
+`autoJudges` 属于 WorkflowSpec 路径。公开主链路是先读 `builder flow schema` / `builder flow get`，再提交 `--spec-file` 或 `--patch-nodes-file`。
 
 | 问题 | 原因 | 解决 |
 |------|------|------|
 | `autoJudges` apply 后为空 | 使用了一维数组 `[{...}]` 格式 | 改为二维 `[[{...}]]` |
 | 条件分支不生效 | `autoJudges` 中的 `values` 与表单选项 label 不一致 | 核对字段选项文本，确保完全一致 |
 | apply 返回 `missing_input_node_ids` | 新建 flow 首次 apply 的正常提示 | 可忽略，再次 get 验证即可 |
+| 录入数据后只留下“提交申请”日志，不进入下一节点 | WorkflowSpec 入口节点没有出边，或入口/路由节点缺少 `sync: true` | `builder flow get` 读回 spec，确认 applicant 出边和节点 `sync`，修正后用 `--spec-file` 发布 |
 | 回退边（gateway → 前序节点）不生效 | 引擎不支持通过 gateway 实现回退 | 改用审批节点 `revert: true` |
 | 审批节点无审批人 | `responsible` 中的 UID/角色 ID 无效或缺失 | 使用 `builder member search` / `role search` 确认 |
 | `fieldType` 不匹配 | 单选用了 `text` 而非 `single_select` | 确认字段实际类型后更正 |

package/skills/qingflow-cli/reference/builder/workflow/README.md

@@ -48,7 +48,7 @@
 | 在范围内 | 超出范围 |
 |----------|----------|
 | 基于已有应用搭建工作流 | 从零创建应用 |
-| WorkflowSpec 生成与 apply；`patch_nodes` 局部修改；public nodes/transitions 仅作简单线性兼容 | 操作复杂命令拼接 |
+| WorkflowSpec 生成与 apply；`patch_nodes` 仅用于已有节点局部维护 | 操作复杂命令拼接 |
 | 审批/填写/抄送/自动化/分支条件等 WorkflowSpec 支持的流程 | 不读 schema/spec 就猜 raw 后端字段 |
 | 审批/填写/抄送/自动化节点配置 | 修改字段定义 |
 | 成员/角色搜索用于节点负责人 | 组织架构管理 |
@@ -68,8 +68,8 @@
 | 阶段 0 | 判断是否为更新模式，确认最小修改原则 | [02-update-mode.md](./02-update-mode.md) |
 | 阶段 1 | 提取业务建模，完成七维度业务自检 | [04-stage1-business-modeling.md](./04-stage1-business-modeling.md) |
 | 阶段 2 | 搜索成员/角色，用于节点负责人配置 | [05-stage2-members-roles.md](./05-stage2-members-roles.md) |
-| 阶段 3 | 获取 Schema、读取现有流程、构建 WorkflowSpec 或 patch_nodes | [06-stage3-build-spec.md](./06-stage3-build-spec.md) |
-| 阶段 4 | 验证 WorkflowSpec / patch_nodes；简单线性兼容输入由 CLI 校验 | [07-stage4-validate-spec.md](./07-stage4-validate-spec.md) |
+| 阶段 3 | 获取 Schema、读取现有流程、构建 WorkflowSpec；已有节点小改才用 patch_nodes | [06-stage3-build-spec.md](./06-stage3-build-spec.md) |
+| 阶段 4 | 验证 WorkflowSpec / patch_nodes | [07-stage4-validate-spec.md](./07-stage4-validate-spec.md) |
 | 阶段 5 | Apply 工作流并验证部署结果 | [08-stage5-apply-verify.md](./08-stage5-apply-verify.md) |
 
 构建流程输入前，若对流程模式有疑问，先查阅 [03-flow-patterns.md](./03-flow-patterns.md)。