@josephyan/qingflow-app-user-mcp 1.0.8 → 1.1.1

package/skills/qingflow-record-analysis/references/pandas-recipes.md

@@ -0,0 +1,172 @@
+# Pandas Recipes
+
+Use Python to read returned CSV shards. Never paste raw CSV into the model context.
+
+## Load All Shards
+
+```python
+import pandas as pd
+
+files = [
+    "/absolute/path/records-0001.csv",
+    # include every record_access.files[].local_path
+]
+
+frames = [pd.read_csv(path, dtype=str, keep_default_na=False) for path in files]
+df = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame()
+
+# Columns are readable and field-id anchored, e.g. 项目状态__field_343283094.
+fields = []  # optionally paste record_access.fields here if you need field-id metadata
+field_by_id = {int(item["field_id"]): item for item in fields if "field_id" in item}
+title_by_col = {item["column_name"]: item["title"] for item in fields if item.get("column_name")}
+```
+
+## Field Quality Profile
+
+Run this before choosing final grouping dimensions.
+
+```python
+def field_quality(frame: pd.DataFrame, *, date_col: str | None = None) -> pd.DataFrame:
+    rows = []
+    for col in frame.columns:
+        blank = frame[col].astype(str).eq("")
+        item = {
+            "column": col,
+            "row_count": len(frame),
+            "blank_count": int(blank.sum()),
+            "blank_rate": float(blank.mean()) if len(frame) else 0.0,
+            "distinct_count": int(frame[col].replace("", pd.NA).nunique(dropna=True)),
+        }
+        rows.append(item)
+    quality = pd.DataFrame(rows).sort_values(["blank_rate", "distinct_count"], ascending=[False, False])
+    if date_col and date_col in frame.columns:
+        tmp = frame.copy()
+        tmp["_period"] = pd.to_datetime(tmp[date_col], errors="coerce").dt.to_period("M").astype(str)
+        period_quality = []
+        for col in frame.columns:
+            if col == date_col:
+                continue
+            by_period = tmp.groupby("_period")[col].apply(lambda s: float(s.astype(str).eq("").mean()))
+            period_quality.append({"column": col, "max_period_blank_rate": float(by_period.max()) if len(by_period) else 0.0})
+        quality = quality.merge(pd.DataFrame(period_quality), on="column", how="left")
+    return quality
+```
+
+Quality gates:
+
+- `blank_rate > 0.4`: do not use as the primary conclusion dimension.
+- `max_period_blank_rate > 0.8`: do not use for period comparison.
+- Very high `distinct_count` fields are usually identifiers or descriptions, not grouping dimensions.
+- High-missing dimensions may still be reported as `已填写样本观察`.
+
+## Column Selection
+
+Prefer exact readable CSV columns. Use suffix matching only when you need to address a field id programmatically.
+
+```python
+def col_by_field_id(frame, field_id: int) -> str:
+    suffix = f"__field_{field_id}"
+    matches = [col for col in frame.columns if col.endswith(suffix)]
+    if not matches:
+        raise KeyError(f"field_id not in CSV: {field_id}")
+    return matches[0]
+```
+
+## Count Distribution
+
+```python
+col = "项目状态__field_18"
+quality = field_quality(df)
+blank_rate = quality.loc[quality["column"].eq(col), "blank_rate"].iloc[0]
+if blank_rate > 0.4:
+    print(f"Use only as filled-sample observation: {col} blank_rate={blank_rate:.1%}")
+dist = (
+    df[col]
+    .replace("", pd.NA)
+    .fillna("未填写")
+    .value_counts(dropna=False)
+    .rename_axis("group")
+    .reset_index(name="count")
+)
+dist["share"] = dist["count"] / dist["count"].sum()
+```
+
+## Numeric Aggregation
+
+```python
+group_col = "项目状态__field_18"
+amount_col = "金额__field_25"
+tmp = df.copy()
+tmp[amount_col] = (
+    tmp[amount_col]
+    .str.replace(",", "", regex=False)
+    .str.replace("￥", "", regex=False)
+    .pipe(pd.to_numeric, errors="coerce")
+)
+summary = (
+    tmp.groupby(group_col, dropna=False)[amount_col]
+    .agg(count="count", total="sum", avg="mean")
+    .reset_index()
+    .sort_values("total", ascending=False)
+)
+```
+
+## Date Trend
+
+```python
+date_col = "申请时间__field_2"
+tmp = df.copy()
+tmp[date_col] = pd.to_datetime(tmp[date_col], errors="coerce")
+tmp = tmp.dropna(subset=[date_col])
+tmp["month"] = tmp[date_col].dt.to_period("M").astype(str)
+trend = tmp.groupby("month").size().reset_index(name="count")
+```
+
+## Year-Over-Year Month Comparison
+
+```python
+date_col = "申请时间__field_2"
+tmp = df.copy()
+tmp[date_col] = pd.to_datetime(tmp[date_col], errors="coerce")
+tmp = tmp.dropna(subset=[date_col])
+tmp["year"] = tmp[date_col].dt.year
+tmp["month"] = tmp[date_col].dt.month
+monthly = tmp.groupby(["year", "month"]).size().reset_index(name="count")
+```
+
+## Ratio
+
+```python
+numerator = len(df[df["项目状态__field_18"].eq("已成交")])
+denominator = len(df)
+ratio = numerator / denominator if denominator else None
+```
+
+Always report numerator and denominator.
+
+## Multi-Select Cells
+
+If values are serialized with delimiters, inspect samples first. For simple comma-separated values:
+
+```python
+col = "标签__field_30"
+exploded = (
+    df.assign(_value=df[col].str.split(","))
+    .explode("_value")
+)
+exploded["_value"] = exploded["_value"].str.strip()
+multi_dist = exploded["_value"].value_counts().reset_index(name="count")
+```
+
+## Business Mapping
+
+```python
+mapping = {
+    "烈焰组": "北斗部门",
+    "飓风组": "北斗部门",
+}
+department_col = "部门__field_40"
+df["department_normalized"] = df[department_col].replace(mapping)
+```
+
+State the mapping in the final answer.

package/skills/qingflow-record-analysis/references/report-format.md

@@ -0,0 +1,76 @@
+# Report Format
+
+Use this for user-facing analysis reports.
+
+## Short Answer
+
+```text
+结论：
+- ...
+
+关键数据：
+- 指标 A：...
+- 指标 B：...
+
+口径与范围：
+- 应用 / 视图：...
+- 时间范围：...
+- 字段：...
+- 字段质量：...
+- 业务映射：...
+- 数据完整性：...
+
+限制：
+- ...
+```
+
+## Detailed Report
+
+```text
+1. 分析范围
+   - app / view
+   - time range
+   - filters
+   - rows analyzed
+
+2. 核心结论
+   - concrete numbers first
+   - no vague adjectives without numbers
+
+3. 分项数据
+   - distribution / trend / ranking tables
+   - percentages with numerator and denominator
+
+4. 解释与建议
+   - separate facts from hypotheses
+
+5. 口径与可信度
+   - fields used
+   - field-quality gates and downgraded dimensions
+   - mapping rules
+   - completeness
+   - partial or unverified scope warnings
+```
+
+## Wording Rules
+
+- Use `全量可信结论` only when the accessed scope is complete and safe.
+- Use `初步观察` for partial or unverified data.
+- Do not say `全部`, `所有`, `整体`, or `完整` when `safe_for_final_conclusion=false`.
+- For ratios, always show `numerator / denominator`.
+- For comparisons, show both periods' absolute values and the delta.
+
+## Comparison Template
+
+```text
+今年5月 vs 去年5月：
+- 记录数：今年 X，去年 Y，变化 +Z（+P%）
+- 金额：今年 X，去年 Y，变化 +Z（+P%）
+- 结构变化：...
+
+口径：
+- 时间字段：...
+- 部门字段：...
+- 部门映射：...
+- 数据完整性：...
+```

package/skills/qingflow-record-insert/SKILL.md

@@ -9,7 +9,9 @@ metadata:
 
 ## Default Path
 
-`record_insert_schema_get -> (optional candidate lookup / confirmation) -> record_insert`
+`record_insert_schema_get -> record_insert(items) -> optional record_get/readback`
+
+Default to batch-shaped insert. A single new record is `items` with one row.
 
 ## Core Tools
 
@@ -25,19 +27,20 @@ metadata:
 2. Read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`
 3. Inside every field bucket, read field-level `linkage` first when present; it is the canonical static hint for linked visibility, reference-driven auto fill, or formula-driven fields
 4. Inside `optional_fields`, pay special attention to any field with `may_become_required=true`; these are writable fields that can become required when linked visibility or option-driven rules activate
-5. Build `fields` from the manually-supplied required/optional fields in that schema
+5. Build `items` as `[{"fields": {...}}]`, where each `fields` map uses field titles from the insert schema
 6. Treat `runtime_linked_required_fields` as required-but-not-directly-writable runtime/upstream dependencies, not as fields to hand-fill blindly
 7. For `linkage.kind=logic_visibility`, read `sources` as upstream trigger fields and treat `role=manual_input_after_activation` as "fill this only after the upstream condition is satisfied"
 8. For `linkage.kind=reference_fill`, prefer filling the source field first; treat target fields with `role=auto_fill_preferred` or `auto_fill_only` as reference-driven outputs rather than blind manual inputs
 9. For `linkage.kind=formula_fill`, treat the field as formula/default-auto-fill driven unless the user explicitly asks to override it and the field is still writable
-10. If insert succeeds and readback shape matters, prefer `record_get(..., output_profile="normalized")` or `record_list(..., output_profile="normalized")`
+10. If insert succeeds and single-record detail/readback matters, prefer `record_get`; use `record_list(..., output_profile="normalized")` only for batch row-shaped normalized readback
 11. Keep subtable payloads under the parent field as a row array
-12. Member / department / relation fields may accept natural strings directly
+12. Member / department / relation fields may accept natural strings directly, such as `"张三"`, `"直销部"`, or `"海军军医大学"`; do not pre-query ids by default
 13. If the write returns `status="needs_confirmation"`, stop and surface the candidates
-14. Retry with explicit ids / objects only after the user confirms
+14. Retry failed rows only with explicit ids / objects after the user confirms
 15. Keep `verify_write=true` for production inserts
-16. If post-write readback consistency matters, prefer `record_get(..., output_profile="normalized")` and surface `normalized_ambiguous_fields` instead of pretending same-title columns are unambiguous
+16. If post-write detail context matters, read `record_get.fields[]`, `media_assets.items[].local_path`, `file_assets.items[].local_path`, `file_assets.items[].extraction.text_path`, and `semantic_context`; `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, so prefer local paths over remote URLs and do not expect legacy `data.normalized_record`
 17. Treat nested schema shape as guidance, not a brittle contract; do not hard-code transient implementation details like optional nested `field_id` shape when composing inserts
+18. For `partial_success`, read `created_record_ids`, then repair only the failed `items[].row_number` using `failed_fields`; never retry the whole batch after any row has `write_executed=true`
 
 ## Field Notes
 
@@ -51,11 +54,29 @@ metadata:
 - `linkage.affects_fields` lists downstream field titles that may change when this field changes
 - `linkage.role=auto_fill_only` means "normally do not hand-fill this unless the product explicitly requires it"
 - `requires_upload=true` means upload the file first, then write the returned value
+- `failed_fields[].next_action` tells the next repair step for that row
+
+## CLI Pattern
+
+Use a JSON array file:
+
+```bash
+qingflow record insert --app-key APP_KEY --items-file records.json --json
+```
+
+`records.json`:
+
+```json
+[
+  { "fields": { "客户名称": "测试客户", "负责人": "张三" } }
+]
+```
 
 ## Do Not
 
 - Do not skip `record_insert_schema_get`
 - Do not invent missing required fields
 - Do not flatten subtable leaf fields to the top level
-- Do not silently guess member / department / relation ids
+- Do not pre-query or silently guess member / department / relation ids when a natural string is enough
+- Do not retry a whole batch after `created_record_ids` is non-empty
 - Do not bind logic to a transient nested schema serialization detail when the field title and parent table already identify the legal payload shape

package/skills/qingflow-record-update/SKILL.md

@@ -34,7 +34,9 @@ metadata:
 12. Do not assume any arbitrary combination of writable fields will succeed; one single matched accessible view still has to cover the payload
 13. Do not look for any extra context bucket in update schema; lookup behavior stays inline on the field definitions themselves
 14. When update context feels unstable, trust `record_update_schema_get`'s route-aware matched-view result over guessed `view_id` or remembered UI scope
-15. If readback consistency matters, prefer `record_get(..., output_profile="normalized")` after the write and surface `normalized_ambiguous_fields` instead of hiding same-title conflicts
+15. If single-record detail/readback matters, prefer `record_get` after the write and read top-level `fields[]`, `media_assets.items[].local_path`, `file_assets.items[].local_path`, `file_assets.items[].extraction.text_path`, and `semantic_context`; `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, so prefer local paths over remote URLs; use `record_list(..., output_profile="normalized")` only for batch row-shaped normalized readback
+16. For batch updates, read top-level `mode`, `dry_run`, `total`, `succeeded`, `failed`, `needs_confirmation`, `updated_record_ids`, `write_executed`, `safe_to_retry`, `verification_status`, and `items[].row_number/status/record_id`
+17. If `write_executed=true`, do not blindly retry the whole batch; use `items[]` and `updated_record_ids` to decide whether only failed rows need repair
 
 ## Do Not
 

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)