@josephyan/qingflow-app-builder-mcp 1.1.30 → 1.1.33

package/skills/qingflow-app-builder/scripts/validate_system_build_summary.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+VALID_PORTAL_STATUSES = {"verified", "unverified", "not_created"}
+VALID_APP_VERIFY_STATUSES = {"verified", "unverified", "failed"}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Validate a Qingflow complete-system delivery summary JSON file.")
+    parser.add_argument("summary_file", nargs="?", default="tmp/qingflow_system_build_summary.json")
+    args = parser.parse_args(argv)
+    path = Path(args.summary_file)
+    issues = validate_summary_file(path)
+    if issues:
+        _emit({"status": "failed", "error_code": "SYSTEM_BUILD_SUMMARY_INVALID", "path": str(path), "issues": issues})
+        return 1
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    _emit(
+        {
+            "status": "success",
+            "path": str(path),
+            "summary": {
+                "package_id": payload.get("package_id"),
+                "package_name": payload.get("package_name"),
+                "portal_dash_key": payload.get("portal_dash_key"),
+                "portal_live_status": payload.get("portal_live_status"),
+                "app_count": len(payload.get("apps") or []),
+                "partial_count": len(payload.get("partial_items") or []),
+                "needs_followup_count": len(payload.get("needs_followup") or []),
+            },
+        }
+    )
+    return 0
+
+
+def validate_summary_file(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return [_issue("MISSING_FILE", "$", f"summary file does not exist: {path}")]
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        return [_issue("READ_FAILED", "$", str(exc))]
+    except json.JSONDecodeError as exc:
+        return [_issue("INVALID_JSON", "$", exc.msg)]
+    if not isinstance(payload, dict):
+        return [_issue("INVALID_ROOT", "$", "summary root must be a JSON object")]
+
+    issues: list[dict[str, Any]] = []
+    _require_positive_int(payload, "package_id", issues)
+    _require_nonempty_string(payload, "package_name", issues)
+    _require_bool(payload, "front_end_visible", issues)
+    _require_string_enum(payload, "portal_live_status", VALID_PORTAL_STATUSES, issues)
+    if payload.get("portal_live_status") == "verified":
+        _require_nonempty_string(payload, "portal_dash_key", issues)
+    elif "portal_dash_key" in payload and payload.get("portal_dash_key") is not None and not isinstance(payload.get("portal_dash_key"), str):
+        issues.append(_issue("INVALID_TYPE", "$.portal_dash_key", "portal_dash_key must be a string when present"))
+
+    apps = payload.get("apps")
+    if not isinstance(apps, list) or not apps:
+        issues.append(_issue("INVALID_APPS", "$.apps", "apps must be a non-empty array"))
+    else:
+        for index, app in enumerate(apps):
+            prefix = f"$.apps[{index}]"
+            if not isinstance(app, dict):
+                issues.append(_issue("INVALID_APP_ITEM", prefix, "app item must be an object"))
+                continue
+            _require_nonempty_string(app, "app_key", issues, prefix)
+            _require_nonempty_string(app, "app_name", issues, prefix)
+            for key in ("fields_count", "views_count", "flows_count", "charts_count"):
+                _require_nonnegative_int(app, key, issues, prefix)
+            _require_string_enum(app, "publish_verify_status", VALID_APP_VERIFY_STATUSES, issues, prefix)
+
+    for key in ("warnings", "partial_items", "needs_followup"):
+        if not isinstance(payload.get(key), list):
+            issues.append(_issue("INVALID_TYPE", f"$.{key}", f"{key} must be an array"))
+    return issues
+
+
+def _require_positive_int(payload: dict[str, Any], key: str, issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    value = payload.get(key)
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        issues.append(_issue("INVALID_TYPE", f"{prefix}.{key}", f"{key} must be a positive integer"))
+
+
+def _require_nonnegative_int(payload: dict[str, Any], key: str, issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    value = payload.get(key)
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        issues.append(_issue("INVALID_TYPE", f"{prefix}.{key}", f"{key} must be a non-negative integer"))
+
+
+def _require_nonempty_string(payload: dict[str, Any], key: str, issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        issues.append(_issue("INVALID_TYPE", f"{prefix}.{key}", f"{key} must be a non-empty string"))
+
+
+def _require_bool(payload: dict[str, Any], key: str, issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    if not isinstance(payload.get(key), bool):
+        issues.append(_issue("INVALID_TYPE", f"{prefix}.{key}", f"{key} must be a boolean"))
+
+
+def _require_string_enum(payload: dict[str, Any], key: str, allowed: set[str], issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    value = payload.get(key)
+    if value not in allowed:
+        issues.append(_issue("INVALID_VALUE", f"{prefix}.{key}", f"{key} must be one of {sorted(allowed)}"))
+
+
+def _issue(code: str, path: str, message: str) -> dict[str, Any]:
+    return {"code": code, "path": path, "message": message}
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/qingflow-app-builder-code-integrations/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: qingflow-app-builder-code-integrations
-description: Configure Qingflow code block and Q-Linker fields through the builder surface when the task involves input field insertion, alias parsing, target field binding, or troubleshooting broken code/q-linker form configurations. Use after MCP is connected and authenticated, especially for CRM-style scoring, lookup, and enrichment forms.
+description: Configure Qingflow code block and Q-Linker fields through the builder surface when the task involves input field insertion, alias parsing, target field binding, or troubleshooting broken code/q-linker form configurations. In Wingent Momo runtime, use the injected MCP session and recover auth/workspace only after a tool error.
 metadata:
   short-description: Configure Qingflow code blocks and Q-Linkers safely
 ---
 
 # Qingflow App Builder Code Integrations
 
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 Use this skill when the user wants to build or repair:
 - `code_block` fields
 - `q_linker` fields
@@ -58,7 +60,7 @@ For code block or Q-Linker work, use this order:
 
 1. Resolve the app and read fields:
    - `app_resolve`
-   - `app_read_fields`
+   - `app_get_fields`
 2. Confirm the target field set already exists.
 3. Apply schema updates with `app_schema_apply`.
 4. Read fields again and verify:
@@ -115,7 +117,7 @@ Hard rules:
 
 After each code block or Q-Linker change, verify all of these:
 
-- `app_read_fields` shows the intended field type
+- `app_get_fields` shows the intended field type
 - the high-level config is readable and stable
 - target fields still have valid types
 - insert schema can be opened

package/skills/qingflow-app-builder-code-integrations/references/code-block.md

@@ -59,7 +59,7 @@ Do not bind code block outputs to:
 
 ## Safe Verification
 
-- `app_read_fields`
+- `app_get_fields`
 - `record_insert_schema_get`
 - optional `record_code_block_run`
 

package/skills/qingflow-app-builder-code-integrations/references/q-linker.md

@@ -70,7 +70,7 @@ Avoid:
 
 ## Safe Verification
 
-- `app_read_fields`
+- `app_get_fields`
 - `record_insert_schema_get`
 - `record_insert`
 

package/skills/qingflow-mcp-setup/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow MCP Setup
 
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Overview
 
 This skill sets up the local Qingflow MCP server, connects it to a local AI client, and verifies authentication and workspace selection. Use it for installation, client configuration, token login, and connection troubleshooting.
@@ -73,24 +75,26 @@ cd <repo_root>/qingflow-support/mcp-server
 
 Prefer validating through the client after config is added.
 
-### Step 5: Authenticate and select workspace
+### Step 5: Use injected session first; authenticate only for setup or recovery
+
+For Wingent Momo runtime conversations, the session normally already carries the credential-derived token, workspace, and route context. Do not run `auth_use_credential`, `auth_login`, `workspace_list`, or `workspace_select` before ordinary business tools. Start with the smallest read-only business call that fits the task; if it succeeds, continue.
 
-Recommended order inside the client:
+For a standalone local MCP client that has no injected session, use this setup order:
 
-1. `auth_use_token` or `auth_login`
+1. `auth_use_credential` or `auth_login`
 2. `workspace_list`
 3. `workspace_select`
-4. Only then use business tools
+4. Run a small read-only business tool
 
-If the user already knows the target workspace, prefer `auth_use_token(..., ws_id=<id>)`.
+`auth_use_credential` gets the selected workspace from the credential context. If the user needs a different workspace after authentication, use `workspace_list` and then `workspace_select`.
 After auth, prefer one read-only tool call that returns `request_route` so you can confirm the live `base_url` and `qf_version` before proceeding.
-`auth_use_token` is a tool call, not a custom HTTP header. The runtime injects `token`, `wsId`, and when needed `Cookie: qfVersion=...` after the session is established.
-Do not skip `workspace_select` on production paths. If `/user` does not return a version lane, the session now falls back to the workspace `systemVersion`.
+`auth_use_credential` is a tool call, not a custom HTTP header. It exchanges the createClaw credential for a Qingflow token, `wsId`, and when needed `Cookie: qfVersion=...` after the session is established.
+Do not run `workspace_select` on production paths unless the user explicitly asks to switch workspace or a business tool clearly reports that no workspace is selected. If `/user` does not return a version lane, the session now falls back to the workspace `systemVersion`.
 
 ### Step 6: Troubleshoot in the right layer
 
 - If the client cannot launch the server, check path, execute permission, and `.venv`
-- If tools return `auth required`, re-run `auth_use_token` or `auth_login`
+- If tools return `auth required`, re-run `auth_use_credential` or `auth_login`
 - If tools return `workspace not selected`, call `workspace_list` and `workspace_select`
 - If calls fail after a working session, assume token expiry and re-authenticate
 - If the browser shows data but MCP does not, compare `request_route` against the browser environment and check whether `qf_version` should be `canary`
@@ -98,7 +102,7 @@ Do not skip `workspace_select` on production paths. If `/user` does not return a
 ## Guardrails
 
 - Never write tokens into the skill files
-- Never assume a workspace is selected until `auth_whoami` or `workspace_select` confirms it
+- In Wingent Momo runtime, trust injected workspace context until a business tool proves otherwise; for standalone clients, confirm workspace with `auth_whoami`, `workspace_select`, or a successful read-only business call.
 - When debugging, distinguish server startup issues from Qingflow auth issues
 - When the user mentions production, restate the exact `base_url`, `qf_version`, and workspace before any live validation
 - If setup is complete but the current MCP capability is still unsupported or the user's need still cannot be satisfied, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation

package/skills/qingflow-mcp-setup/references/claude-desktop.md

@@ -31,4 +31,4 @@ Keep separate snippets for `test` and `prod` so switching environments does not
 - Replace `<ABSOLUTE_PATH_TO_REPO>` with the real checkout path on the current machine
 - If the server path changes, update the `command` field
 - The server is local stdio MCP, so no remote URL is required
-- Do not store Qingflow token in Claude Desktop config; pass it through `auth_use_token` inside the chat
+- Do not store Qingflow credentials in Claude Desktop config; pass the createClaw credential through `auth_use_credential` inside the chat, or use `auth_login` when credential exchange is unavailable

package/skills/qingflow-mcp-setup/references/environments.md

@@ -28,7 +28,8 @@ Known values in the current workspace:
 Setup behavior:
 
 - prefer this environment for Claude Desktop or local MCP client onboarding
-- use `auth_use_token` or `auth_login`, then `workspace_list`, then `workspace_select`
+- for Wingent Momo runtime, use the injected session and skip auth/workspace preflight
+- for standalone MCP client setup, use `auth_use_credential` or `auth_login`, then `workspace_list`, then `workspace_select`
 - if the user asks to verify installation, a real read-only smoke path is acceptable
 
 ## Production Environment

package/skills/qingflow-mcp-setup/references/generic-stdio.md

@@ -19,13 +19,14 @@ Keep separate client entries or separate config snippets for `test` and `prod`.
 
 1. Start the client
 2. Confirm the `qingflow` MCP server is visible
-3. Run `auth_use_token`
-4. Run `workspace_list`
-5. Run `workspace_select`
-6. Run a read-only tool such as `app_list`
+3. In Wingent Momo runtime, skip auth/workspace preflight and run a read-only tool such as `app_list`
+4. In a standalone client without injected credentials, run `auth_use_credential` or `auth_login`
+5. Then run `workspace_list`
+6. Then run `workspace_select`
+7. Run a read-only tool such as `app_list`
 
 ## Common failures
 
 - Launch failure: bad `command` path or missing `.venv`
-- Auth failure: invalid or expired token
+- Auth failure: invalid or expired credential/token
 - Business tool failure before setup: workspace not selected

package/skills/qingflow-workflow-builder/SKILL.md

@@ -8,6 +8,8 @@ description: |
 
 # 轻流工作流搭建 Skill
 
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## 快速索引
 
 | 主题 | 文件 |
@@ -17,8 +19,8 @@ description: |
 | 流程模式速查（线性/分支/回退） | [references/03-flow-patterns.md](references/03-flow-patterns.md) |
 | 阶段 1：业务建模与自检 | [references/04-stage1-business-modeling.md](references/04-stage1-business-modeling.md) |
 | 阶段 2：成员/角色搜索 | [references/05-stage2-members-roles.md](references/05-stage2-members-roles.md) |
-| 阶段 3：Schema + 构建 Spec | [references/06-stage3-build-spec.md](references/06-stage3-build-spec.md) |
-| 阶段 4：验证 Spec | [references/07-stage4-validate-spec.md](references/07-stage4-validate-spec.md) |
+| 阶段 3：Schema + 构建流程输入 | [references/06-stage3-build-spec.md](references/06-stage3-build-spec.md) |
+| 阶段 4：验证流程输入 | [references/07-stage4-validate-spec.md](references/07-stage4-validate-spec.md) |
 | 阶段 5：Apply + 验证循环 | [references/08-stage5-apply-verify.md](references/08-stage5-apply-verify.md) |
 | 阶段 6：总结报告与回退 | [references/09-stage6-summary.md](references/09-stage6-summary.md) |
 | 节点配置参考 | [references/10-node-config-reference.md](references/10-node-config-reference.md) |
@@ -56,8 +58,8 @@ description: |
 | 在范围内 | 超出范围 |
 |----------|----------|
 | 基于已有应用搭建工作流 | 从零创建应用 |
-| 声明式 WorkflowSpec 生成与 apply | 操作复杂命令拼接 |
-| 分支条件（gateway + autoJudges）配置 | 后端不支持的高级特性 |
+| WorkflowSpec 生成与 apply；`patch_nodes` 局部修改；public nodes/transitions 仅作简单线性兼容 | 操作复杂命令拼接 |
+| 审批/填写/抄送/自动化/分支条件等 WorkflowSpec 支持的流程 | 不读 schema/spec 就猜 raw 后端字段 |
 | 审批/填写/抄送/自动化节点配置 | 修改字段定义 |
 | 成员/角色搜索用于节点负责人 | 组织架构管理 |
 | 验证 → apply → 校验循环 | 前端 UI 拖拽操作 |
@@ -76,11 +78,11 @@ description: |
 | 阶段 0 | 判断是否为更新模式，确认最小修改原则 | [references/02-update-mode.md](references/02-update-mode.md) |
 | 阶段 1 | 提取业务建模，完成七维度业务自检 | [references/04-stage1-business-modeling.md](references/04-stage1-business-modeling.md) |
 | 阶段 2 | 搜索成员/角色，用于节点负责人配置 | [references/05-stage2-members-roles.md](references/05-stage2-members-roles.md) |
-| 阶段 3 | 获取 Schema、读取现有 Spec、构建新 Spec | [references/06-stage3-build-spec.md](references/06-stage3-build-spec.md) |
-| 阶段 4 | 验证 Spec（JSON Schema + 自定义约束） | [references/07-stage4-validate-spec.md](references/07-stage4-validate-spec.md) |
+| 阶段 3 | 获取 Schema、读取现有流程、构建 WorkflowSpec 或 patch_nodes | [references/06-stage3-build-spec.md](references/06-stage3-build-spec.md) |
+| 阶段 4 | 验证 WorkflowSpec / patch_nodes；简单线性兼容输入由 CLI 校验 | [references/07-stage4-validate-spec.md](references/07-stage4-validate-spec.md) |
 | 阶段 5 | Apply 工作流并验证部署结果 | [references/08-stage5-apply-verify.md](references/08-stage5-apply-verify.md) |
 
-构建 Spec 前，若对流程模式有疑问，先查阅 [references/03-flow-patterns.md](references/03-flow-patterns.md)。
+构建流程输入前，若对流程模式有疑问，先查阅 [references/03-flow-patterns.md](references/03-flow-patterns.md)。
 
 ---
 

package/skills/qingflow-workflow-builder/references/01-overview.md

@@ -20,6 +20,8 @@
 | `qingflow builder flow schema --json` | 获取最新 WorkflowSpecDTO JSON Schema |
 | `qingflow builder flow get --app-key <KEY>` | 读取当前工作流 spec |
 | `qingflow builder flow apply --app-key <KEY> --spec-file <FILE>` | 部署/更新工作流 |
+| `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>` | 获取应用信息（字段列表等） |
@@ -33,8 +35,8 @@
 | 在范围内 | 超出范围 |
 |----------|----------|
 | 基于已有应用搭建工作流 | 从零创建应用 |
-| 声明式 WorkflowSpec 生成与 apply | 操作复杂命令拼接 |
-| 分支条件（gateway + autoJudges）配置 | 后端不支持的高级特性 |
+| WorkflowSpec 生成与 apply；public nodes/transitions 兼容简单线性流程 | 操作复杂命令拼接 |
+| 审批/填写/抄送/分支条件等 WorkflowSpec 支持的流程 | 不读 schema/spec 就猜 raw 后端字段 |
 | 审批/填写/抄送/自动化节点配置 | 修改字段定义 |
 | 成员/角色搜索用于节点负责人 | 组织架构管理 |
 | 验证 → apply → 校验循环 | 前端 UI 拖拽操作 |

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

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

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

@@ -1,4 +1,4 @@
-# 阶段 3：获取 Schema + 构建 Spec
+# 阶段 3：获取 Schema + 构建流程输入
 
 ## 3.1 获取当前工作流 Schema
 
@@ -16,7 +16,7 @@ qingflow --json builder flow get --app-key <APP_KEY> > tmp/current_flow.json
 
 从返回的 `spec` 中提取 `nodes` 和 `edges` 作为修改基础。
 
-**更新模式下**：构建新 spec 后，用 diff 脚本确认变更范围是否符合预期：
+**更新模式下**：如果走 `patch_nodes[]`，直接使用读回的 `spec.nodes[].id` 做局部修改；如果提交完整 `--spec-file`，用 diff 脚本确认变更范围是否符合预期：
 
 ```bash
 python3 scripts/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
@@ -24,9 +24,45 @@ python3 scripts/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
 
 新建场景可跳过此步。
 
-## 3.3 构建 WorkflowSpec
+## 3.3 兼容：构建 public nodes / transitions（仅简单线性）
 
-按照以下结构构建 `spec.json`：
+完整流程主链路是 `WorkflowSpec --spec-file` 或现有流程的 `patch_nodes`。只有明确是简单线性审批/填写/抄送流程时，才继续写两个 public alias 数组文件：
+
+`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`。
+
+WorkflowSpec 示例：
 
 ```json
 {
@@ -116,7 +152,7 @@ python3 scripts/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
 }
 ```
 
-## 节点类型速查
+## WorkflowSpec 节点类型速查
 
 | type | 说明 | 必要 attrs |
 |------|------|-----------|
@@ -129,6 +165,8 @@ python3 scripts/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
 
 ## 边条件体系
 
+本节属于 `--spec-file` WorkflowSpec 路径。不要凭记忆手写 `autoJudges`、`judgeType` 或 raw `fieldId` 条件；先读 `builder flow schema` / `builder flow get`，再按读回结构修改。简单线性兼容链路才使用 `builder flow apply --nodes-file --transitions-file`。
+
 | condition.kind | 含义 | 要求 |
 |---------------|------|------|
 | `rules` | 条件选路 | 必须含 `autoJudges`（OR-of-AND 二维数组） |
@@ -154,9 +192,23 @@ OR-of-AND 二维数组：
 
 **judgeType 常用值**：`equals`, `not_equals`, `equals_any`, `includes`, `greater_than` 等（共21种，详见 schema）。
 
-## 3.4 保存 Spec 到文件
+## 3.5 局部修改 patch_nodes
+
+局部修改现有流程时，先 `builder flow get`，使用读回 `spec.nodes[].id`：
 
-将构建好的完整 Spec 以 JSON 格式保存到文件 `tmp/flow_spec.json`，确保使用 UTF-8 编码、缩进格式化，以便后续验证和 apply 使用。
+```json
+[
+  {"id": "89160906", "set": {"name": "需求评审（局部改）"}}
+]
+```
+
+```bash
+qingflow --json builder flow apply \
+  --app-key <APP_KEY> \
+  --patch-nodes-file tmp/flow_patch_nodes.json \
+  --publish \
+  > tmp/flow_patch_apply.json
+```
 
 ---
 

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

@@ -1,13 +1,22 @@
-# 阶段 4：验证 Spec
+# 阶段 4：验证流程输入
 
-使用本 Skill 自带的验证脚本：
+主链路 `--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 \
   tmp/flow_spec.json --schema tmp/flow_schema.json
 
-# 更新模式（同时校验最小修改原则）
+# WorkflowSpec 更新模式（同时校验最小修改原则）
 python3 scripts/validate_flow_spec.py \
   tmp/flow_spec.json --schema tmp/flow_schema.json --previous tmp/current_flow.json
 ```
@@ -24,7 +33,7 @@ python3 scripts/validate_flow_spec.py \
 
 ## 验证不通过时的处理
 
-根据错误信息修正 spec，重新验证，直到全部通过再进入 apply。
+WorkflowSpec 根据验证脚本错误修正 spec，重新验证，直到全部通过再进入 apply。简单线性兼容输入根据 CLI 错误修正 nodes/transitions。
 
 ---
 

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

@@ -2,11 +2,26 @@
 
 ## 5.1 部署工作流
 
+推荐主链路：
+
 ```bash
-qingflow builder flow apply \
+qingflow --json builder flow apply \
   --app-key <APP_KEY> \
   --spec-file tmp/flow_spec.json \
-  --publish
+  --publish \
+  > tmp/flow_apply.json
+```
+
+简单线性兼容流程仍可用 `--nodes-file + --transitions-file`；不要和 `--spec-file` / `--patch-nodes-file` 混用。
+
+局部修改已存在节点：
+
+```bash
+qingflow --json builder flow apply \
+  --app-key <APP_KEY> \
+  --patch-nodes-file tmp/flow_patch_nodes.json \
+  --publish \
+  > tmp/flow_patch_apply.json
 ```
 
 ### 解读响应
@@ -14,6 +29,7 @@ qingflow builder flow apply \
 - `status: success` → 进入验证
 - `status: failed` → 查看 `error_code` / `message` / `blocking_issues`，修正后重试
 - `missing_input_node_ids` 警告（新建时常见）→ 可忽略，是正常现象
+- 成功写入应读取 `write_executed=true`、`write_succeeded=true`、`safe_to_retry=false`；不要因中间读回 pending 立刻重放。
 
 ## 5.2 验证部署结果
 
@@ -25,7 +41,7 @@ qingflow --json builder flow get --app-key <APP_KEY> > tmp/deployed_flow.json
 
 1. **节点数量与类型**：`nodes` 数量是否一致，每个节点的 `type` 和 `name` 是否正确
 2. **边连通性**：`edges` 数量是否一致，`from`/`to` 关系是否正确
-3. **分支条件**（核心关注点）：每个 gateway 出边是否有正确的 `autoJudges`
+3. **分支条件**（WorkflowSpec 路径）：每个 gateway 出边是否有正确的 `autoJudges`
    - 检查 `condition.kind` 是否为 `rules`
    - 检查 `autoJudges` 中的 `fieldId`、`judgeType`、`values` 是否正确
    - **`autoJudges` 必须是非空二维数组 `[[{...}]]`，空数组或一维数组说明条件未生效**

package/skills/qingflow-workflow-builder/references/11-troubleshooting.md

@@ -1,5 +1,7 @@
 # 常见问题与排障
 
+`autoJudges` 属于 WorkflowSpec 路径。公开主链路是先读 `builder flow schema` / `builder flow get`，再提交 `--spec-file` 或 `--patch-nodes-file`；简单线性兼容链路 `nodes-file + transitions-file` 不要求智能体手写这些字段。
+
 | 问题 | 原因 | 解决 |
 |------|------|------|
 | `autoJudges` apply 后为空 | 使用了一维数组 `[{...}]` 格式 | 改为二维 `[[{...}]]` |

package/src/qingflow_mcp/__main__.py

@@ -1,5 +1,9 @@
-"""Entry point for running qingflow_mcp as a module."""
-from qingflow_mcp.server import main
+"""Entry point for running qingflow_mcp as a module.
+
+Default to the curated user-facing MCP surface. Split package and console
+entrypoints can still start the builder server explicitly.
+"""
+from qingflow_mcp.server_app_user import main
 
 if __name__ == "__main__":
     main()