@josephyan/qingflow-cli 1.1.4 → 1.1.6

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/match-rules.md

@@ -0,0 +1,114 @@
+# Builder Match Rules
+
+Use this reference for builder-side field matching rules in custom buttons and associated view/report filters.
+
+This is not the same thing as `record_access` analysis filters or normal view `filters`.
+
+## Where These Rules Apply
+
+- `app_custom_buttons_apply.upsert_buttons[].trigger_add_data_config.field_mappings`
+- `app_custom_buttons_apply.patch_buttons[].set.trigger_add_data_config.field_mappings`
+- `app_associated_resources_apply.upsert_resources[].match_mappings`
+- `app_associated_resources_apply.patch_resources[].set.match_mappings`
+
+Prefer semantic mappings. Do not handwrite raw `que_relation` or `match_rules` unless you are preserving an existing backend config.
+
+## System Fields
+
+System fields can participate in mappings:
+
+- `数据ID`, `row_record_id`, `apply_id`, `_id` -> `field_id=-17`
+  This is the current record's real apply/record ID.
+- `编号`, `数据编号`, `record_number` -> `field_id=0`
+  This is the frontend-visible record number. It may be custom formatted and is not the same as `数据ID`.
+
+Explicit selectors such as `{"field_id": -17}` and `{"field_id": 0}` are allowed and remove ambiguity.
+
+## Custom Buttons
+
+Use `field_mappings` for dynamic values copied from the current source record:
+
+```json
+{
+  "target_app_key": "WORKLOG_APP",
+  "field_mappings": [
+    {"source_field": "数据ID", "target_field": "关联员工"},
+    {"source_field": "员工名称", "target_field": "员工姓名"}
+  ],
+  "default_values": {
+    "状态": "待提交"
+  }
+}
+```
+
+Use `default_values` only for static constants. Do not use `default_values` as the preferred way to pass the current record.
+
+For an existing button, put the same semantic config under `patch_buttons[].set`:
+
+```json
+{
+  "button_id": 3858041,
+  "set": {
+    "trigger_add_data_config": {
+      "target_app_key": "WORKLOG_APP",
+      "field_mappings": [
+        {"source_field": "数据ID", "target_field": "关联员工"}
+      ],
+      "default_values": {
+        "状态": "待提交"
+      }
+    }
+  }
+}
+```
+
+## Associated Resources
+
+Use `match_mappings` for associated view/report filters:
+
+```json
+{
+  "graph_type": "view",
+  "target_app_key": "WORKLOG_APP",
+  "view_key": "WORKLOG_VIEW",
+  "match_mappings": [
+    {"target_field": "关联员工", "source_field": "数据ID"},
+    {"target_field": "状态", "value": "待提交"}
+  ]
+}
+```
+
+Dynamic conditions use `source_field`; static conditions use `value`.
+
+For an existing associated resource, put the same filter mapping under `patch_resources[].set`:
+
+```json
+{
+  "associated_item_id": 3497587,
+  "set": {
+    "match_mappings": [
+      {"target_field": "关联员工", "source_field": "数据ID"}
+    ]
+  }
+}
+```
+
+## Type Compatibility
+
+- Relation fields: match another relation field with the same target app, or match `数据ID(-17)` when the target relation points to the current source app.
+- Record ID `数据ID(-17)`: can match relation fields that point to the current source app, or ID-compatible text/number fields.
+- Record number `编号(0)`: can match text, long text, number, amount, or another record-number field.
+- Member fields: only match member fields.
+- Department fields: only match department fields.
+- Option fields: single select, multi select, and boolean can match option-family fields or static option values.
+- Date fields: date and datetime can match each other.
+- Text fields: text, long text, phone, and email can match each other.
+- Number fields: number and amount can match each other.
+- Attachment, subtable, code block, Q-Linker, and address fields are not default match fields.
+
+## Error Interpretation
+
+- Field not found: re-read `app_get` or `app_get_fields` and retry with an exact title or `field_id`.
+- Type mismatch: choose a compatible source/target pair from the matrix above.
+- Reference source mismatch: the target relation field points to a different app; choose a relation field that points back to the current source app, or match a non-relation field.
+- Mixed raw and semantic modes: use either semantic `field_mappings/match_mappings` or raw `que_relation/match_rules`, never both in the same item.

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/public-surface-sync.md

@@ -0,0 +1,75 @@
+# Qingflow Core Public Surface Sync
+
+Use this file as the maintenance baseline for the core Qingflow skills.
+It is not a user-facing product spec. It exists to prevent skill drift.
+
+## Current Public Defaults
+
+### User data
+
+- Read range first with `app_get`, then `record_browse_schema_get(view_id=...)`
+- Treat `record_browse_schema_get.fields` as the selected Qingflow table view header schema; `record_access.fields` and `record_list` field selectors must stay aligned with it.
+- Standard flows:
+  - analyze: `app_get -> record_browse_schema_get -> record_access -> Python`
+  - browse detail: `app_get -> record_browse_schema_get -> record_list / record_get`
+  - explicit export/download/Excel: `app_get -> choose view_id -> view_get -> record_export_*` or `record_export_direct`; export tools require explicit `view_id`
+  - insert: `record_insert_schema_get -> record_insert(items)`
+  - update: `record_get -> record_update`; use `record_update_schema_get` only for failure diagnosis or ambiguous writable-field routing
+
+### Tasks
+
+- Discovery stays on `task_list`
+- `task_list --query` uses backend search first and only applies local fallback when backend returns zero rows
+- Public actions are:
+  - `approve`
+  - `reject`
+  - `rollback`
+  - `transfer`
+  - `urge`
+  - `save_only`
+- `reject` requires `payload.audit_feedback`
+- `save_only` requires non-empty `fields`
+- `TASK_RUNTIME_CONSUMED_AFTER_ACTION` is a normal post-success warning when the current node runtime is consumed and `46001` appears on re-read
+
+### Builder
+
+- Official package entry: `package_get`, `package_apply`
+- Official builder writes:
+  - `app_schema_apply`
+  - `app_layout_apply`
+  - `app_flow_apply`
+  - `app_views_apply`
+  - `app_custom_buttons_apply`
+  - `app_associated_resources_apply`
+  - `app_charts_apply`
+  - `portal_apply`
+  - `app_publish_verify`
+- `portal_apply` edit mode may omit `sections` for base-info-only updates
+- `app_charts_apply.visibility` is a public capability and should be treated as a base-only visibility update
+- Existing object parameter replacement should use `patch_views`, `patch_buttons`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
+- `app_get.editability` uses:
+  - `can_edit_app_base`
+  - `can_edit_form`
+  - `can_edit_flow`
+  - `can_edit_views`
+  - `can_edit_charts`
+
+## Known High-Drift Areas
+
+- Task actions, especially `save_only`, reject payload requirements, and `46001` post-action interpretation
+- Package public tools: do not regress to `package_create` / `package_attach_app` as the public default story
+- App editability: do not let `can_edit_form` imply app base-info writes
+- Portal and chart visibility: keep the public story on `portal_apply` / `app_charts_apply`, not low-level internal writes
+- Analysis path: standard path stays `record_access -> Python`
+
+## Release Checklist For Skill Maintenance
+
+After each beta that changes public behavior, re-check:
+
+1. `public_surface.py`
+2. `README.md`
+3. `server_app_builder.py` and `server.py` top-level guidance
+4. CLI help for `task`, `builder package`, `builder portal`, `builder charts`
+5. Whether new warnings or verification fields need to be explained in skills
+
+If a tool behavior changed but the public surface did not, prefer updating the relevant skill section instead of expanding this file.

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/single-app-development-guide.md

@@ -0,0 +1,58 @@
+# Single App Development Guide
+
+Use this when the user asks for one app/form, or gives one `app_key`.
+If the user asks for a package, system, or several related modules, use `complete-system-development-guide.md` instead.
+
+## Recommended Completeness
+
+Required:
+
+- target package/app resolved by `package_get`, `app_resolve`, or `app_get`
+- business fields created or updated through `app_schema_apply`
+- exactly one readable top-level `as_data_title: true`
+- no platform system fields in `add_fields`
+- layout places the important fields
+- at least one business view beyond platform default views when the task includes user-facing list work
+
+Strongly recommended:
+
+- saved filters and query panel fields for the main operating views
+- simple charts when the app has status, amount, date, or owner fields worth tracking
+- associated resources or buttons only when they support a concrete workflow
+
+Optional:
+
+- workflow, portal entry, sample data, roles, or visibility changes when requested by the user or clearly needed by the app's job
+
+Workflow preflight:
+
+- If the app will have approval/fill/copy workflow nodes, add one explicit business status `select` field first, such as `状态`, `处理状态`, `审批状态`, `工单状态`, or `流程阶段`.
+- Do not create platform workflow system fields: `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`.
+
+## Standard Path
+
+1. Read current target: `app_resolve` or `app_get`.
+2. Read current fields: `app_get_fields`.
+3. Apply fields with `app_schema_apply`.
+4. Apply layout with `app_layout_apply`.
+5. Apply views with `app_views_apply` when list/table/card/gantt behavior is part of the request.
+6. Apply charts/buttons/associated resources only if they are part of the app's actual workflow.
+7. Use `app_publish_verify` only when explicit live verification is required.
+
+## Field Rules
+
+- Use agent-friendly field types where possible: `text`, `multiline`, `select`, `multi_select`, `number`, `amount`, `date`, `datetime`, `member`, `department`, `attachment`, `relation`.
+- Do not create `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`.
+- Do not create built-in default views such as `全部数据` or `我的数据`; Qingflow provides system views.
+
+## View Query Rules
+
+- `filters` are fixed saved filters; `query_conditions` only configures frontend query-panel fields.
+- Put only query-panel fields in `query_conditions.rows`: text, long text, number, amount, date/datetime, select, member, department, phone, email, or boolean.
+- Do not put relation, attachment, subtable/subfield, address, Q-Linker, or code-block fields in `query_conditions`; use fixed `filters` or associated-resource `match_mappings` instead.
+
+## Stop Conditions
+
+- If the task actually needs multiple business objects, stop and switch to the complete-system guide.
+- If a write returns `partial_success`, `write_executed=true`, or `safe_to_retry=false`, read back before retrying.
+- If the same validation error repeats twice, re-read `qingflow --json builder contract` instead of guessing.

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/solution-playbooks.md

@@ -0,0 +1,52 @@
+# Builder Playbooks
+
+Use these when you need a quick reminder of the standard v2 builder sequences.
+
+## Create a new app in an existing package
+
+1. `package_get`
+2. `app_resolve`
+3. `app_schema_apply`
+5. `app_publish_verify` only if the user asks for explicit live verification
+
+## Update fields on an existing app
+
+1. `app_resolve`
+2. `app_get_fields`
+3. `app_schema_apply`
+
+## Rework layout
+
+1. `app_get_layout`
+2. `app_layout_apply`
+
+Prefer `mode=merge`. Use `mode=replace` only when every field placement is intentional.
+
+## Add or update workflow
+
+1. `app_get_fields`
+2. `app_get_flow`
+3. `role_search` or `member_search`
+4. `role_create` if the business wants a reusable role and no good exact role exists
+5. `app_flow_apply`
+
+If `app_flow_apply` reports `FLOW_DEPENDENCY_MISSING`, fix schema first.
+If it reports `FLOW_ASSIGNEE_REQUIRED`, resolve roles or members first and retry with canonical `assignees.*`.
+
+## Add or update views
+
+1. `app_get_fields`
+2. `app_get_views`
+3. `app_views_apply`
+
+For both workflow and view work, prefer `suggested_next_call` over re-guessing arguments after a validation failure.
+
+## Final readback
+
+Prefer these fields after writes:
+
+- `app_get.tag_ids`
+- `app_get.publish_status`
+- `app_get_layout.unplaced_fields`
+- `app_get_views.views`
+- `app_get_flow.nodes`

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/tool-selection.md

@@ -0,0 +1,107 @@
+# Tool Selection
+
+Use the smallest v2 builder tool chain that can finish the task.
+
+## Default path
+
+`summary read -> apply -> publish_verify`
+
+Public builder `apply` tools already perform server-side planning, normalization, and dependency checks internally. Do not route normal public builder work through explicit `*_plan` tools.
+
+## Hierarchy first
+
+Before picking tools, decide which layer the request targets:
+
+- `package`: a solution/app bundle like “研发项目管理” or “费控管理系统”
+- `app`: one form/app inside that package
+- `field`: one field inside one app
+- `relation`: a field that links two apps
+
+If the user asks for multiple forms/modules that relate to each other, this is a package-level multi-app task, not a single-app create.
+
+## Resolve
+
+- `package_get`: read one known package by `package_id`
+- `package_apply`: create or update one package; use `create_if_missing=true` only after explicit user intent
+- `member_search`: resolve named people from the directory
+- `role_search`: resolve reusable roles from the directory
+- `role_create`: create a reusable role when the business owner wants role-based routing
+- `app_resolve`: locate an existing app by exactly one selector mode: `app_key`, or `app_name + package_id`
+
+## Summary reads
+
+All `app_get_*` tools accept either `app_key` (single) or `app_keys[]` (batch). Batch returns `{status, apps[], errors[]}` — prefer batch when reading multiple apps in one step.
+
+- `app_get`: overall app config health, publish state, counts, and builder editability
+- `app_get_fields`: field names, types, required flags, section ids
+- `app_get_layout`: sections, rows, unplaced fields
+- `app_get_views`: current view names, types, columns, group-by
+- `app_get_flow`: workflow enabled state, full spec (nodes + transitions)
+- `app_get_charts`: current chart ids, names, types, order
+- `app_get_buttons`: current custom button list (draft state)
+- `app_get_associated_resources`: current associated resource pool (draft state)
+- `app_publish_verify`: publish state and package tag verification — accepts `app_keys[]` for multi-app batch
+- `portal_get`: current portal config detail and component inventory
+
+## Apply tools
+
+These execute normalized patches. Some app apply tools publish by default and still accept `publish=false`; custom button and associated-resource apply publish after at least one write succeeds and do not expose that switch.
+
+- `app_schema_apply`: create app shell or change fields
+- `app_layout_apply`: merge or replace layout; use `apps[]` (each item `{app_key, mode?, sections}`) for multi-app batch
+- `app_flow_apply`: replace full workflow spec; use `patch_nodes[]` (`{id, set, unset}`) to update specific nodes without rewriting the full spec
+- `app_views_apply`: use `patch_views` for existing-view parameter replacement; use `upsert_views` for creation or full target config; remove views by key; new views default associated report/view display to visible with `limit_type="all"`; use `apps[]` for multi-app batch
+- `app_custom_buttons_apply`: use `patch_buttons` for existing-button parameter replacement; use `upsert_buttons` for creation or full target config; configure add-data field mappings/default values; bind buttons to header/detail/list view positions; `placement=list` maps to the backend `INSIDE` row/list button position; merge-mode view configs require `buttons`; use `view_configs[].mode="replace"` or `buttons=[]` to clear a view's custom button bindings. For child-record creation linked to the current source record, map `source_field: "数据ID"` to the target relation field. Use `apps[]` for multi-app batch.
+- `app_associated_resources_apply`: attach existing BI reports/views to the Qingflow app associated-resource pool and per-view display area; it does not create or edit QingBI report bodies/configs. Use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; `view_configs`, remove, and reorder may reference existing resources by internal `associated_item_id` or by `chart_id`/`chart_key`/`view_key`; use `match_mappings` for associated view/report filters; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only to attach an existing BI dataset report. Before `upsert_resources`, read `app_get.associated_resources` and reuse an existing matching `target_app_key + view_key/chart_key`; repeated upsert can create duplicates because `client_key` is only valid inside one apply call. Use `apps[]` for multi-app batch.
+- `app_charts_apply`: create/edit/remove/reorder app-source QingBI report bodies/configs with `dataSourceType=qingflow`; it does not create/edit dataset BI reports and does not attach reports to Qingflow app associated-resource display. Use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; supports `target/table` aliases plus QingBI chart types such as `summary`, `columnar`, `area`, `funnel`, `radar`, `scatter`, `dualaxes`, and `map`; charts are immediate-live and do not publish; use `chart_id` when names are not unique; use `apps[]` for multi-app batch
+- `portal_apply`: create or replace-update portal pages; use `dash_key` for update mode or `package_id + dash_name` for create mode; edit mode may omit `sections` for base-info-only updates; when sections are supplied they still use replace semantics; sections use a 24-column PC grid — all components in the same row (same `y`) must share the same `rows` value and their `cols` must sum to exactly 24; mismatched `rows` causes height misalignment, `cols` under 24 leaves trailing blank space; use `patch_sections[]` (`{chart_ref/view_ref/order, set, unset}`) to update individual sections without replacing all
+
+For object-level updates, the safe partial syntax is `patch_*` with the object's real selector field plus `set` and optional `unset`. `selector` is only a concept, not a literal key. Examples: `patch_views: [{"view_key": "VIEW_KEY", "set": {...}}]`, `patch_buttons: [{"button_id": 1001, "set": {...}}]`, `patch_resources: [{"associated_item_id": 123, "set": {...}}]`, `patch_charts: [{"chart_id": 456, "set": {...}}]`, `patch_nodes: [{"id": "approve_1", "set": {...}}]`, `patch_sections: [{"chart_ref": {"chart_key": "ck_001"}, "set": {"title": "新标题"}}]`. The tool reads the current backend config, merges the patch, then submits the full backend payload internally. Do not send a partial `upsert_*` and expect missing required fields to be preserved.
+
+## Explicit post-apply tools
+
+- `app_publish_verify`: explicit final publish verification when the user asks for live confirmation
+
+## Decision shortcuts
+
+- Create one app inside an existing package:
+  `package_get -> app_resolve -> app_schema_apply`
+- Create a brand new package, then create one app in it:
+  `package_apply(create_if_missing=true) -> app_schema_apply`
+- Create a brand new multi-app system/package:
+  `package_apply(create_if_missing=true) -> app_schema_apply(apps[])`
+- Update fields on an existing app:
+  `app_resolve -> app_get_fields -> app_schema_apply`
+- Tidy layout:
+  `app_get_fields -> app_get_layout -> qingflow --json builder contract (if shape is unclear) -> app_layout_apply`
+- Add workflow:
+  `qingflow --json builder contract -> app_get_fields -> app_get_flow -> role_search/member_search -> app_flow_apply -> app_get_flow`
+- Update specific flow nodes:
+  `app_get_flow -> app_flow_apply.patch_nodes[]`
+- Add views:
+  `qingflow --json builder contract -> app_get_fields -> app_get_views -> app_views_apply.patch_views/upsert_views -> app_get_views`
+- Add QingBI charts:
+  `qingflow --json builder contract -> app_get_fields -> app_get_charts -> app_charts_apply.patch_charts/upsert_charts -> app_get_charts`
+- Show an existing QingBI chart inside a Qingflow app/view:
+  `app_get -> app_associated_resources_apply.upsert_resources/patch_resources + view_configs -> app_get`
+- Create or update a portal:
+  `qingflow --json builder contract -> portal_get -> portal_apply -> portal_get`
+- Update portal section(s) without replacing all:
+  `portal_get -> portal_apply.patch_sections[]`
+
+## Avoid
+
+- Do not handcraft raw Qingflow schema payloads
+- Do not rely on internal `solution_*` tools in public builder flows
+- Do not create a new package without first asking the user to confirm package creation
+- Do not regress to `package_create` or `package_attach_app` as the public default story
+- Do not treat a package/system name as `app_name` when the user clearly wants multiple apps inside it
+- Do not compress multiple business objects into one app with several text fields
+- Do not skip summary reads before flow or view work
+- Do not emit `column_names`; always use `columns`
+- Do not model layout shape with `fields`, `field_ids`, or top-level `columns`; custom layout sections should be `title + rows`
+- Do not reuse internal flow keys such as `role_entries` or `editable_que_ids` in public builder calls
+- Do not pass natural-language preset guesses such as `default_approval`; map them to canonical preset values first
+- Do not omit assignees on approval/fill/copy nodes
+- Do not patch preset flows with brand new approval/fill node ids unless you are intentionally replacing the skeleton; reuse preset ids like `approve_1` and `fill_1`
+- Do not guess role ids, member ids, or editable field ids; resolve names first

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/update-flow.md

@@ -0,0 +1,7 @@
+# Legacy Redirect: Update Flow
+
+This historical playbook is no longer a main entry point.
+
+For current workflow creation, patching, and verification, read [../../90-workflow.md](../../90-workflow.md).
+
+Reason: update behavior belongs inside the resource document. Route by target resource first, not by the generic word "update".

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/update-layout.md

@@ -0,0 +1,7 @@
+# Legacy Redirect: Update Layout
+
+This historical playbook is no longer a main entry point.
+
+For current form layout creation and update work, read [../../40-layout.md](../../40-layout.md).
+
+Reason: update behavior belongs inside the resource document. Route by target resource first, not by the generic word "update".

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/update-schema.md

@@ -0,0 +1,7 @@
+# Legacy Redirect: Update Schema
+
+This historical playbook is no longer a main entry point.
+
+For current field creation and update work, read [../../30-schema-fields.md](../../30-schema-fields.md).
+
+Reason: update behavior belongs inside the resource document. Route by target resource first, not by the generic word "update".

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/update-views.md

@@ -0,0 +1,7 @@
+# Legacy Redirect: Update Views
+
+This historical playbook is no longer a main entry point.
+
+For current view creation, filtering, query panels, and patching, read [../../50-views.md](../../50-views.md).
+
+Reason: update behavior belongs inside the resource document. Route by target resource first, not by the generic word "update".

package/skills/qingflow-cli/reference/builder/workflow/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-cli/reference/builder/workflow/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-cli/reference/builder/workflow/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)