@qingflow-tech/qingflow-app-builder-mcp 1.0.44 → 1.1.0

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.44
+npm install @qingflow-tech/qingflow-app-builder-mcp@1.1.0
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.44 qingflow-app-builder-mcp
+npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.1.0 qingflow-app-builder-mcp
 ```
 
 Environment:
@@ -24,6 +24,8 @@ Bundled skills:
 
 - `skills/qingflow-app-builder`
 - `skills/qingflow-app-builder-code-integrations`
+- `skills/qingflow-workflow-builder`
+- `skills/qingflow-mcp-setup`
 
 Note:
 

package/npm/bin/qingflow-app-builder-mcp.mjs

@@ -1,7 +1,36 @@
 #!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
-import { getPackageRoot, spawnServer } from "../lib/runtime.mjs";
+const PKG_BY_BIN = {
+  qingflow: "qingflow-cli",
+  "qingflow-app-user-mcp": "qingflow-app-user-mcp",
+  "qingflow-app-builder-mcp": "qingflow-app-builder-mcp",
+};
 
-const packageRoot = getPackageRoot(import.meta.url);
+function resolvePackageModule(metaUrl, ...segments) {
+  const scriptPath = fileURLToPath(metaUrl);
+  const scriptDir = path.dirname(scriptPath);
+  const direct = path.join(scriptDir, ...segments);
+  if (fs.existsSync(direct)) {
+    return pathToFileURL(direct).href;
+  }
+  if (path.basename(scriptDir) === ".bin") {
+    const binName = path.basename(scriptPath);
+    const pkgName = PKG_BY_BIN[binName];
+    if (!pkgName) {
+      throw new Error(`Unknown qingflow command: ${binName}`);
+    }
+    const scope = process.env.QINGFLOW_NPM_SCOPE || "@qingflow-tech";
+    const fromBin = path.join(scriptDir, "..", scope, pkgName, "npm", ...segments);
+    if (fs.existsSync(fromBin)) {
+      return pathToFileURL(fromBin).href;
+    }
+  }
+  throw new Error(`Cannot locate ${segments.join("/")} from ${scriptPath}`);
+}
 
+const { getPackageRoot, spawnServer } = await import(resolvePackageModule(import.meta.url, "lib", "runtime.mjs"));
+const packageRoot = getPackageRoot(import.meta.url);
 spawnServer(packageRoot, process.argv.slice(2), "qingflow-app-builder-mcp", { allowRuntimeBootstrap: false });

package/npm/lib/runtime.mjs

@@ -5,6 +5,12 @@ import { fileURLToPath } from "node:url";
 
 const WINDOWS = process.platform === "win32";
 
+const PKG_BY_BIN = {
+  qingflow: "qingflow-cli",
+  "qingflow-app-user-mcp": "qingflow-app-user-mcp",
+  "qingflow-app-builder-mcp": "qingflow-app-builder-mcp",
+};
+
 function runChecked(command, args, options = {}) {
   const result = spawnSync(command, args, {
     encoding: "utf8",
@@ -28,7 +34,18 @@ function commandWorks(command, args) {
 }
 
 export function getPackageRoot(metaUrl) {
-  return path.resolve(path.dirname(fileURLToPath(metaUrl)), "..", "..");
+  const scriptPath = fileURLToPath(metaUrl);
+  const scriptDir = path.dirname(scriptPath);
+  if (path.basename(scriptDir) === ".bin") {
+    const binName = path.basename(scriptPath);
+    const pkgName = PKG_BY_BIN[binName];
+    if (!pkgName) {
+      throw new Error(`Unknown qingflow command: ${binName}`);
+    }
+    const scope = process.env.QINGFLOW_NPM_SCOPE || "@qingflow-tech";
+    return path.join(scriptDir, "..", scope, pkgName);
+  }
+  return path.resolve(scriptDir, "..", "..");
 }
 
 export function getCodexHome() {
@@ -480,6 +497,17 @@ function getVenvPip(packageRoot) {
     : path.join(getVenvDir(packageRoot), "bin", "pip");
 }
 
+function findOfflineProjectWheel(findLinksDir) {
+  const wheels = fs
+    .readdirSync(findLinksDir)
+    .filter((name) => /^qingflow_mcp-.*\.whl$/i.test(name))
+    .sort();
+  if (wheels.length === 0) {
+    throw new Error(`Offline install expected a qingflow_mcp wheel in ${findLinksDir}`);
+  }
+  return path.join(findLinksDir, wheels[wheels.length - 1]);
+}
+
 export function findPython() {
   const preferred = process.env.QINGFLOW_MCP_PYTHON?.trim();
   const candidates = preferred
@@ -528,7 +556,20 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
   }
 
   const pip = getVenvPip(packageRoot);
-  runChecked(pip, ["install", "--disable-pip-version-check", "."], { cwd: packageRoot });
+  const pipArgs = ["install", "--disable-pip-version-check"];
+  const offlineFindLinks = process.env.QINGFLOW_MCP_PIP_FIND_LINKS?.trim();
+  if (process.env.QINGFLOW_MCP_PIP_NO_INDEX === "1") {
+    pipArgs.push("--no-index");
+  }
+  if (offlineFindLinks) {
+    pipArgs.push("--find-links", offlineFindLinks);
+  }
+  if (process.env.QINGFLOW_MCP_PIP_NO_INDEX === "1" && offlineFindLinks) {
+    pipArgs.push(findOfflineProjectWheel(offlineFindLinks));
+  } else {
+    pipArgs.push(".");
+  }
+  runChecked(pip, pipArgs, { cwd: packageRoot });
 
   fs.writeFileSync(
     stampPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-builder-mcp",
-  "version": "1.0.44",
+  "version": "1.1.0",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

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

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow App Builder Code Integrations
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **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

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

@@ -0,0 +1,115 @@
+---
+name: qingflow-mcp-setup
+description: Install, connect, authenticate, and troubleshoot the Qingflow MCP server in local AI clients such as Claude Desktop or any stdio-compatible MCP client. Use when the user wants to configure the MCP, verify local startup, log in with token/password, select a workspace, or fix connection/authentication issues.
+metadata:
+  short-description: Install and connect the Qingflow MCP locally
+---
+
+# 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.
+
+## Workflow
+
+Follow these steps in order.
+
+`feedback_submit` is also available as a cross-cutting helper when setup or MCP capability gaps still block the user after reasonable troubleshooting. It does not require Qingflow login or workspace selection, and should be called only after explicit user confirmation.
+
+Before configuration or live calls, identify the target environment explicitly as `test` or `prod`, then read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
+
+### Step 1: Verify the local project path
+
+Resolve the repository root first. In this repo, the MCP server should live at:
+
+- `<repo_root>/qingflow-support/mcp-server`
+
+Key entrypoint:
+
+- `<repo_root>/qingflow-support/mcp-server/qingflow-mcp`
+
+If the path differs, stop and update all client config snippets before proceeding.
+If the skill is installed under `$CODEX_HOME/skills` instead of the repo-local `.codex/skills`, set `QINGFLOW_MCP_ROOT=<repo_root>/qingflow-support/mcp-server` before running `scripts/check_local_server.sh`.
+
+### Step 2: Install local dependencies
+
+Run:
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+python3 -m venv .venv
+./.venv/bin/pip install -e '.[dev]'
+```
+
+Use `scripts/check_local_server.sh` to verify the entrypoint and virtualenv. The script will first try `QINGFLOW_MCP_ROOT`, then the current git repo, then a repo-local `.codex/skills` layout.
+
+### Step 3: Configure the local AI client
+
+For any stdio-compatible MCP client, map these values:
+
+- `command`: `<repo_root>/qingflow-support/mcp-server/qingflow-mcp`
+- `args`: `[]`
+- `env.QINGFLOW_MCP_DEFAULT_BASE_URL`: the target backend URL for the active environment
+- `env.QINGFLOW_MCP_DEFAULT_QF_VERSION`: set this when the environment must route to a specific version such as `canary`
+
+Client-specific snippets:
+
+- Claude Desktop: read [references/claude-desktop.md](references/claude-desktop.md)
+- Generic stdio MCP clients: read [references/generic-stdio.md](references/generic-stdio.md)
+
+When both test and production are in play, keep separate config snippets or clearly labeled `env` blocks so the user can switch without ambiguity.
+
+### Step 4: Validate startup
+
+The server is a stdio MCP process. A direct terminal launch may print nothing and wait for a client. That is normal.
+
+Manual startup command:
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+./qingflow-mcp
+```
+
+Prefer validating through the client after config is added.
+
+### 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.
+
+For a standalone local MCP client that has no injected session, use this setup order:
+
+1. `auth_use_credential` or `auth_login`
+2. `workspace_list`
+3. `workspace_select`
+4. Run a small read-only business tool
+
+`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_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_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`
+
+## Guardrails
+
+- Never write tokens into the skill files
+- 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
+
+## Resources
+
+- Environment switching: [references/environments.md](references/environments.md)
+- Claude Desktop config: [references/claude-desktop.md](references/claude-desktop.md)
+- Generic stdio config: [references/generic-stdio.md](references/generic-stdio.md)
+- Local checks: [scripts/check_local_server.sh](scripts/check_local_server.sh)

package/skills/qingflow-mcp-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow MCP Setup"
+  short_description: "Install and connect the Qingflow MCP locally"
+  default_prompt: "Use $qingflow-mcp-setup to install and connect the Qingflow MCP in a local AI client, and to verify the active base_url, qf_version, auth state, and workspace selection."

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

@@ -0,0 +1,34 @@
+# Claude Desktop
+
+Use this when the user wants to install Qingflow MCP in Claude Desktop.
+
+## Config snippet
+
+```json
+{
+  "mcpServers": {
+    "qingflow": {
+      "command": "<ABSOLUTE_PATH_TO_REPO>/qingflow-support/mcp-server/qingflow-mcp",
+      "args": [],
+      "env": {
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "<QINGFLOW_BASE_URL>"
+      }
+    }
+  }
+}
+```
+
+## Environment examples
+
+- `prod` (default): set `QINGFLOW_MCP_DEFAULT_BASE_URL` to `https://qingflow.com/api`
+- `test`: if needed, set `QINGFLOW_MCP_DEFAULT_BASE_URL` to the explicitly provided non-production backend
+
+Keep separate snippets for `test` and `prod` so switching environments does not require editing values in-place under pressure.
+
+## Notes
+
+- After updating the config, restart Claude Desktop
+- 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 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

@@ -0,0 +1,62 @@
+# Environment Switching
+
+Use this reference before any setup, authentication, or live validation flow.
+
+## Step 1: Resolve the active environment
+
+Decide explicitly whether the user is targeting:
+
+- `test`: for smoke tests, trial setup, DSL validation, mock data, and integration debugging
+- `prod`: for real business usage in the formal environment
+
+If the user did not specify an environment, default to `prod`.
+
+## Test Environment
+
+Default characteristics:
+
+- preferred for first-time setup and local MCP validation
+- mock or smoke data is acceptable when the user asks for it
+- use read/write verification freely inside the intended test workspace
+
+Known values in the current workspace:
+
+- use an explicitly provided non-production backend
+- common test workspace example: `ws_id=2`
+- `qf_version`: usually unset unless the user explicitly needs a routed version
+
+Setup behavior:
+
+- prefer this environment for Claude Desktop or local MCP client onboarding
+- 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
+
+Production is the default environment when the user does not specify one. If the user explicitly says `test`, switch to the dedicated non-production backend they provide.
+
+Expected behavior:
+
+- default `base_url`: `https://qingflow.com/api`
+- confirm the production `qf_version` explicitly when browser traffic depends on routed versions such as `canary`
+- confirm the exact workspace before any live validation
+- prefer read-only checks first
+- avoid mock data, smoke writes, or destructive tests unless the user explicitly asks for them
+
+Production guardrails:
+
+- do not store credentials in skill files or examples
+- do not assume the same workspace ids as test
+- treat startup verification and auth verification as separate steps
+- when sharing snippets, label them as `prod` and `test` clearly
+- when MCP and browser results diverge, compare `request_route` with the browser route before blaming the query logic
+
+## Reporting Rule
+
+When you give setup instructions, always state:
+
+- active environment
+- selected `base_url`
+- selected `qf_version` when relevant
+- whether the next step is read-only or write-impacting

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

@@ -0,0 +1,32 @@
+# Generic Stdio MCP Clients
+
+Use this for any local AI client that supports MCP over stdio.
+
+## Required mapping
+
+- `command`: `<ABSOLUTE_PATH_TO_REPO>/qingflow-support/mcp-server/qingflow-mcp`
+- `args`: `[]`
+- `env.QINGFLOW_MCP_DEFAULT_BASE_URL`: backend base URL for the active environment
+
+Environment examples:
+
+- `prod` (default): `https://qingflow.com/api`
+- `test`: use the explicitly provided non-production backend
+
+Keep separate client entries or separate config snippets for `test` and `prod`.
+
+## Validation sequence
+
+1. Start the client
+2. Confirm the `qingflow` MCP server is visible
+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 credential/token
+- Business tool failure before setup: workspace not selected

package/skills/qingflow-mcp-setup/scripts/check_local_server.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="${QINGFLOW_MCP_ROOT:-}"
+
+if [[ -z "$ROOT" ]]; then
+  if git_root="$(git rev-parse --show-toplevel 2>/dev/null)" && [[ -d "$git_root/qingflow-support/mcp-server" ]]; then
+    ROOT="$git_root/qingflow-support/mcp-server"
+  elif [[ -d "$PWD/qingflow-support/mcp-server" ]]; then
+    ROOT="$PWD/qingflow-support/mcp-server"
+  else
+    repo_root="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+    if [[ -d "$repo_root/qingflow-support/mcp-server" ]]; then
+      ROOT="$repo_root/qingflow-support/mcp-server"
+    fi
+  fi
+fi
+
+if [[ -z "$ROOT" ]]; then
+  echo "Unable to locate qingflow-support/mcp-server. Set QINGFLOW_MCP_ROOT to the repo copy of the MCP server." >&2
+  exit 1
+fi
+
+ENTRY="$ROOT/qingflow-mcp"
+PY="$ROOT/.venv/bin/python"
+
+echo "ROOT=$ROOT"
+test -d "$ROOT"
+echo "OK root exists"
+
+test -x "$ENTRY"
+echo "OK entrypoint exists and is executable"
+
+test -x "$PY"
+echo "OK virtualenv python exists"
+
+PYTHONPATH="$ROOT/src" "$PY" -c "import qingflow_mcp.server; print('OK import qingflow_mcp.server')"

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

@@ -0,0 +1,98 @@
+---
+name: qingflow-workflow-builder
+description: |
+  在已有的轻流应用中，根据业务建模使用 qingflow CLI 声明式搭建工作流。
+  适用场景：应用已存在、字段已就绪，需要创建或更新审批/填写/网关/自动化/抄送流程。
+  不适用场景：应用不存在或字段缺失——应先完成应用搭建（schema apply）再使用本 Skill。
+---
+
+# 轻流工作流搭建 Skill
+
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
+## 快速索引
+
+| 主题 | 文件 |
+|------|------|
+| 依赖命令、能力边界 | [references/01-overview.md](references/01-overview.md) |
+| 更新模式与最小修改原则 | [references/02-update-mode.md](references/02-update-mode.md) |
+| 流程模式速查（线性/分支/回退） | [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) |
+| 阶段 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) |
+| 常见问题与排障 | [references/11-troubleshooting.md](references/11-troubleshooting.md) |
+
+---
+
+## 一、思考（Thought）：何时启用与前置条件
+
+### 触发条件
+
+当用户要求**在轻流应用中搭建工作流**时启用本 Skill，典型触发语：
+
+- "帮我搭建审批流程"
+- "在这个应用里创建工作流"
+- "按照这张流程图实现工作流"
+- "配置流程分支条件"
+- "给这个应用加一个审批节点"
+
+### 前提检查（进入行动前必须完成）
+
+在开始任何搭建操作前，按顺序确认以下条件：
+
+1. **应用存在性**：`qingflow --json app get --app-key <APP_KEY>` 成功返回
+2. **字段就绪**：`qingflow --json builder app get --app-key <APP_KEY> fields` 返回字段列表，确认业务建模所需字段（如单选框、成员、部门字段）均已存在
+3. **未启用已有流程**（新建场景）：`qingflow --json builder app get --app-key <APP_KEY> flow` 查看 `enabled` 状态，若已有流程则为**更新模式**
+
+**不满足时的处理**：
+- 应用不存在 → 先完成应用搭建和字段配置，再继续工作流搭建
+- 字段缺失 → 先补充缺失的字段定义，再继续工作流搭建
+- 应用已启用流程 → 进入更新模式（读取现有 spec 再修改）
+
+### 能力边界
+
+| 在范围内 | 超出范围 |
+|----------|----------|
+| 基于已有应用搭建工作流 | 从零创建应用 |
+| 声明式 WorkflowSpec 生成与 apply | 操作复杂命令拼接 |
+| 分支条件（gateway + autoJudges）配置 | 后端不支持的高级特性 |
+| 审批/填写/抄送/自动化节点配置 | 修改字段定义 |
+| 成员/角色搜索用于节点负责人 | 组织架构管理 |
+| 验证 → apply → 校验循环 | 前端 UI 拖拽操作 |
+
+完整命令与依赖说明见 [references/01-overview.md](references/01-overview.md)。
+本 Skill 中的 `scripts/...` 路径均以 `qingflow-workflow-builder/` 技能根目录为基准；执行脚本时先解析为该技能目录下的实际文件。
+
+---
+
+## 二、行动（Action）：核心 SOP
+
+按顺序执行以下阶段，每个阶段详见对应 reference 文件：
+
+| 阶段 | 任务 | 参考文件 |
+|------|------|----------|
+| 阶段 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) |
+| 阶段 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)。
+
+---
+
+## 三、反思（Reflection）：验证与总结
+
+| 阶段 | 任务 | 参考文件 |
+|------|------|----------|
+| 阶段 6 | 输出结构化搭建报告，回顾业务完整性 | [references/09-stage6-summary.md](references/09-stage6-summary.md) |
+
+搭建失败时的回退策略、节点配置细节、常见问题排障分别见：
+- [references/09-stage6-summary.md](references/09-stage6-summary.md)
+- [references/10-node-config-reference.md](references/10-node-config-reference.md)
+- [references/11-troubleshooting.md](references/11-troubleshooting.md)

package/skills/qingflow-workflow-builder/manifest.yaml

@@ -0,0 +1,8 @@
+identity: qingflow_workflow_builder
+type: skill
+description: 在轻流应用中搭建工作流。从业务建模提取流程结构（含业务完整性自检：规模分级、组织层级、异常路径、状态闭环、角色分离），映射为声明式 WorkflowSpec，通过 qingflow CLI 的 schema/get/apply 三步部署工作流，并验证分支条件与自动化节点配置一致性。
+tags:
+  - qingflow
+  - workflow
+  - builder
+  - flow

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

@@ -0,0 +1,45 @@
+# 轻流工作流搭建：概览与依赖
+
+## 关联文件
+
+| 文件 | 说明 |
+|------|------|
+| `manifest.yaml` | 技能清单 |
+| `SKILL.md` | 主流程入口 |
+| `scripts/validate_flow_spec.py` | 工作流 Spec 验证脚本，基于 JSON Schema + 自定义约束 |
+| `scripts/diff_flow_spec.py` | 新旧 Spec 差异分析脚本，辅助更新模式下最小修改原则判断 |
+
+---
+
+## 依赖声明
+
+本 Skill 关键依赖 **qingflow CLI**（已安装于 PATH，详见 `qingflow_cli` Skill）。以下 qingflow 命令为核心操作：
+
+| 命令 | 用途 |
+|------|------|
+| `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 builder member search --query <关键词>` | 搜索成员 |
+| `qingflow builder role search --keyword <关键词>` | 搜索角色 |
+| `qingflow --json app get --app-key <KEY>` | 获取应用信息（字段列表等） |
+| `qingflow --json builder app get --app-key <KEY> fields` | 获取应用可搭建字段详情 |
+| `qingflow --json builder app get --app-key <KEY> flow` | 获取流程摘要（是否启用等） |
+
+---
+
+## 能力边界
+
+| 在范围内 | 超出范围 |
+|----------|----------|
+| 基于已有应用搭建工作流 | 从零创建应用 |
+| 声明式 WorkflowSpec 生成与 apply | 操作复杂命令拼接 |
+| 分支条件（gateway + autoJudges）配置 | 后端不支持的高级特性 |
+| 审批/填写/抄送/自动化节点配置 | 修改字段定义 |
+| 成员/角色搜索用于节点负责人 | 组织架构管理 |
+| 验证 → apply → 校验循环 | 前端 UI 拖拽操作 |
+
+---
+
+← 返回主流程：[../SKILL.md](../SKILL.md)
+→ 下一步：[02-update-mode.md](02-update-mode.md)

package/skills/qingflow-workflow-builder/references/02-update-mode.md

@@ -0,0 +1,53 @@
+# 更新模式与最小修改原则
+
+当应用已有工作流时，进入**更新模式**。核心原则是**最小修改**——只改动必要的部分，保持其他结构不变。
+
+## 为什么要保持节点 ID 稳定
+
+后端可能存储了 spec 中不支持的运行时配置（如审批策略、超时规则、高级权限等），这些配置与节点 ID 绑定。一旦修改节点 ID，后端会将其视为「删除旧节点 + 创建新节点」，导致不支持的配置全部丢失。
+
+**因此：修改已有节点时，只改 attrs/name，绝不改 id。**
+
+## 最小修改原则速查
+
+| 操作 | ✅ 正确做法 | ❌ 错误做法 |
+|------|-----------|-----------|
+| 添加节点 | 使用新 ID，追加到 nodes 末尾 | 重排已有节点 ID |
+| 删除节点 | 删除对应 node 和关联边 | 不删关联边导致孤立边 |
+| 修改节点配置 | 同一 ID 下只改 attrs/name | 改 ID 导致节点重建 |
+| 添加边 | 追加到 edges 数组 | 修改已有边的 from/to |
+| 修改条件 | 同一条边内改 condition | 删除边再新建 |
+| 调整流转 | 修改边的 from/to | 改节点 ID 来适配 |
+
+## 使用 diff 脚本辅助判断
+
+在构建新 spec 后、apply 前，使用 diff 脚本对比新旧 spec：
+
+```bash
+python3 scripts/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
+```
+
+输出会显示删除的节点/边、新增的节点/边、修改的节点/边，并自动评估是否符合最小修改原则。
+
+验证脚本也支持在更新模式下进行最小修改原则校验：
+
+```bash
+python3 scripts/validate_flow_spec.py \
+  tmp/flow_spec.json \
+  --schema tmp/flow_schema.json \
+  --previous tmp/current_flow.json
+```
+
+## 更新模式 SOP 调整
+
+在更新模式下，阶段 3.2 变为**必须执行**（读取现有 spec），阶段 5.2 的对比验证增加最小修改原则检查：
+
+- 节点 ID 不应无故变更
+- 删除的节点/边应为业务需要，而非误删
+- 修改范围应仅限于业务建模中变更的部分
+
+---
+
+← 上一步：[01-overview.md](01-overview.md)
+← 返回主流程：[../SKILL.md](../SKILL.md)
+→ 下一步：[03-flow-patterns.md](03-flow-patterns.md)