@josephyan/qingflow-app-builder-mcp 1.0.9 → 1.1.1

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 token in Claude Desktop config; pass it through `auth_use_token` inside the chat

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

@@ -0,0 +1,61 @@
+# 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
+- use `auth_use_token` 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,31 @@
+# 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. Run `auth_use_token`
+4. Run `workspace_list`
+5. Run `workspace_select`
+6. 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
+- 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,96 @@
+---
+name: qingflow-workflow-builder
+description: |
+  在已有的轻流应用中，根据业务建模使用 qingflow CLI 声明式搭建工作流。
+  适用场景：应用已存在、字段已就绪，需要创建或更新审批/填写/网关/自动化/抄送流程。
+  不适用场景：应用不存在或字段缺失——应先完成应用搭建（schema apply）再使用本 Skill。
+---
+
+# 轻流工作流搭建 Skill
+
+## 快速索引
+
+| 主题 | 文件 |
+|------|------|
+| 依赖命令、能力边界 | [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)

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

@@ -0,0 +1,57 @@
+# 流程模式速查
+
+在构建 spec 前，先判断当前流程属于哪种模式，避免用错节点类型或边结构。
+
+## 线性流程
+
+最简单的流程模式：节点首尾相连，无分支、无条件。
+
+```
+n1 → n2 → n3 → n4
+```
+
+- 边不带 `condition`，按顺序流转即可
+- 无需 gateway 节点
+- 适用于：简单的提交→审批→结束
+
+## 分支流程
+
+轻流的分支采用**并行分支**模型——通过 `gateway` 节点（`mode: parallel`）分发，所有出边指向的分支**都会进入**，通过每条边上的条件（`condition.autoJudges`）控制分支内的节点逻辑是否执行。
+
+```
+                ┌──[条件A成立]→ n3 → n4
+n1 → n2 → g1 ──┤
+                └──[条件B成立]→ n5
+```
+
+**关键点**：
+- 分支起点必须是 `gateway`（`mode: parallel`），终点必须是 `gateway`（`mode: join`）
+- 每条分支边都需要配置 `condition`，其中至少一条为 `kind: rules` 带 `autoJudges`
+- 没有条件的边使用 `kind: default` 作为兜底
+- 所有分支并行进入，条件只决定分支内逻辑是否执行，不存在"条件匹配就跳过其他分支"的互斥语义
+
+## 循环/回退
+
+**轻流工作流引擎不支持循环结构**。不要通过 gateway 或其他方式构建回到前序节点的环。
+
+如需回退到前序节点重新处理，应使用审批节点的回退开关：
+
+```json
+{
+  "type": "approval",
+  "attrs": {
+    "revert": true,
+    "revertScope": "all"
+  }
+}
+```
+
+- `revert: true` 开启驳回/回退能力
+- `revertScope` 控制回退范围：`all` 可回退到任意前序节点
+- 这是引擎原生支持的回退机制，无需在 spec 中构建回退边
+
+---
+
+← 上一步：[02-update-mode.md](02-update-mode.md)
+← 返回主流程：[../SKILL.md](../SKILL.md)
+→ 下一步：[04-stage1-business-modeling.md](04-stage1-business-modeling.md)

package/skills/qingflow-workflow-builder/references/04-stage1-business-modeling.md

@@ -0,0 +1,131 @@
+# 阶段 1：提取业务建模
+
+从用户上下文（对话文本、上传的流程图图片、需求描述等）中提取业务建模。
+
+## 若上下文包含流程图图片
+
+1. 优先使用当前客户端已暴露的图片理解能力读取流程图；不要假定某个跨插件工具名一定存在
+2. 如果当前环境没有图片理解能力，要求用户补充流程文字说明或节点/分支清单
+3. 从图片理解结果或用户补充中提取：节点名称、节点类型、流转顺序、分支条件（字段→选项→目标）
+
+## 建模输出格式
+
+保存到 `tmp/业务建模_<应用名>.md`：
+
+```markdown
+# 业务建模：<流程名称>
+
+## 应用信息
+- APP_KEY: <xxx>
+- 应用名称: <xxx>
+
+## 节点清单
+| id | 名称 | 类型 | 审批人/处理人 | 说明 |
+|----|------|------|--------------|------|
+| n1 | 员工提交申请 | applicant | — | 工作流入门 |
+| n2 | 部门经理审批 | approval | 部门经理 | 或签 |
+| ... | ... | ... | ... | ... |
+
+## 流转路径
+n1 → n2 → [分支:字段=选项]
+  ├─ 选项A → n3
+  └─ 选项B → n4
+...
+
+## 分支条件明细
+| 分支来源 | 条件字段 | 判断符 | 选项值 | 目标节点 |
+|----------|---------|--------|--------|----------|
+| 服务类型 | 服务类型(单选) | equals | 客诉 | 质量部负责人接单 |
+| ... | ... | ... | ... | ... |
+```
+
+**无法提取时**：明确告知用户缺少哪些信息（节点、角色、条件等），要求补充，**禁止臆测**。
+
+---
+
+## 业务完整性自检（建模完成后必须逐项确认）
+
+> ⚠️ **用户指令优先**：如果用户给出了明确的流程设计指令，以用户指令为准，本自检仅作为补充建议。与用户指令冲突的项标记为「用户已明确」并跳过。
+>
+> 当用户未给出明确指令时，本自检从以下七个维度引导思考。回答「否」的项需在建模文件中说明理由。**禁止为了通过自检而添加无业务意义的节点。**
+
+### 一、审批强度与风险匹配
+- 审批层数是否与业务风险匹配？
+- 低风险场景是否走了简化路径？
+- 是否存在冗余审批节点？
+
+### 二、角色策略与审批人指派
+- 审批人是否基于角色而非个人？
+- 不同审批层级是否代表不同能力或权限？
+- 关键节点是否需要多人会签？审批人缺席时是否有替代方案？
+
+### 三、执行顺序与效率
+- 互不依赖的审批是否并行？
+- 是否存在可合并的冗余环节？
+- 串行审批链是否过长？
+
+### 四、条件路由与分支设计
+- 是否需要根据业务数据动态路由？
+- 分支条件是否覆盖所有可能？是否有默认兜底？
+
+### 五、异常处理与纠错机制
+- 审批不通过时是否可以修正重提？
+- 驳回后回到哪个节点？
+- 是否考虑了审批超时？
+- 异常升级是否有终态？
+
+### 六、信息透明与闭环
+- 关键决策节点完成后是否需要抄送？
+- 流程结束后提交人是否能明确知道结果？
+- 是否需要自动化节点更新状态字段？
+
+### 七、流程嵌入与业务衔接
+- 审批通过后是否有后续业务动作？
+- 是否有前置校验需求？
+
+---
+
+## 自检结果格式
+
+追加到建模文件末尾：
+
+```markdown
+## 业务完整性自检
+
+| 维度 | 检查项 | 结果 | 说明 |
+|------|--------|:----:|------|
+| 一、审批强度 | 审批层数是否与风险匹配？ | ✅/❌ | |
+| 一、审批强度 | 低风险是否简化路径？ | ✅/❌ | |
+| 一、审批强度 | 是否存在冗余审批节点？ | ✅/❌ | |
+| 二、角色策略 | 审批人是否基于角色？ | ✅/❌ | |
+| 二、角色策略 | 不同层级是否代表不同能力？ | ✅/❌ | |
+| 二、角色策略 | 是否考虑缺席替代方案？ | ✅/❌ | |
+| 三、执行效率 | 独立审批是否并行化？ | ✅/❌ | |
+| 三、执行效率 | 串行链是否过长？ | ✅/❌ | |
+| 三、执行效率 | 是否存在可合并环节？ | ✅/❌ | |
+| 四、条件路由 | 是否需要动态路由？ | ✅/❌ | |
+| 四、条件路由 | 分支条件是否全覆盖？ | ✅/❌ | |
+| 四、条件路由 | 是否有默认兜底？ | ✅/❌ | |
+| 五、异常处理 | 驳回后是否可修正重提？ | ✅/❌ | |
+| 五、异常处理 | 是否考虑审批超时？ | ✅/❌ | |
+| 五、异常处理 | 异常升级是否有终态？ | ✅/❌ | |
+| 六、信息透明 | 关键节点是否抄送？ | ✅/❌ | |
+| 六、信息透明 | 提交人能否明确结果？ | ✅/❌ | |
+| 六、信息透明 | 状态字段是否自动更新？ | ✅/❌ | |
+| 七、业务衔接 | 是否有前置校验？ | ✅/❌ | |
+| 七、业务衔接 | 审批后是否有后续动作？ | ✅/❌ | |
+```
+
+## 自检不通过时的处理
+
+- 某个维度确实需要但设计中遗漏了 → 回到建模环节补充
+- 某个维度在业务上确实不需要 → 在「说明」列记录理由后放行
+- 与用户明确指令冲突 → 标记「用户已明确」，以用户指令为准
+
+**无法提取时**：明确告知用户缺少哪些信息，要求补充，**禁止臆测**。
+
+---
+
+← 上一步：[03-flow-patterns.md](03-flow-patterns.md)
+← 返回主流程：[../SKILL.md](../SKILL.md)
+→ 下一步：[05-stage2-members-roles.md](05-stage2-members-roles.md)

package/skills/qingflow-workflow-builder/references/05-stage2-members-roles.md

@@ -0,0 +1,29 @@
+# 阶段 2：获取成员/角色信息
+
+在配置节点负责人（`responsible`）前，需要搜索可用成员与角色：
+
+```bash
+# 搜索成员
+qingflow --json builder member search --query "<姓名/关键词>" --page-size 20
+# 搜索角色
+qingflow --json builder role search --keyword "<角色名>" --page-size 20
+```
+
+## 注意事项
+
+- `responsible` 是 **MemberRefDTO 数组**，不是单值对象
+- `type` 字段可取：
+  - `user`（指定人）
+  - `role`（角色）
+  - `dept`（部门）
+  - `applicant` / `leader` / `formEmail` / `formMember` / `formDept` / `nodeLeader`
+- 指定人时使用 `uid` 传入成员 UID（整数）
+- 角色时使用 `roleId` 传入角色 ID（整数）
+- 部门时使用 `deptId` 传入部门 ID（整数），可选 `havingSubDept`
+- 避免硬编码 UID/角色 ID/部门 ID，始终从搜索结果中提取
+
+---
+
+← 上一步：[04-stage1-business-modeling.md](04-stage1-business-modeling.md)
+← 返回主流程：[../SKILL.md](../SKILL.md)
+→ 下一步：[06-stage3-build-spec.md](06-stage3-build-spec.md)