@qingflow-tech/qingflow-cli 1.1.2 → 1.1.34

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

@@ -0,0 +1,229 @@
+# Builder 统一筛选 / 条件写法
+
+本文适用于 Builder 侧所有给智能体公开的筛选和条件入口：
+
+- 视图固定筛选：`builder views apply` 的 `filters`
+- 视图动作按钮显示条件：`action_buttons[].visible_when`
+- QingBI 图表筛选：`builder charts apply` 或 `portal apply sections[].chart.filters`
+- 关联视图 / 关联报表匹配：`builder associated-resource apply` 的 `match_mappings`
+- 新增下游记录传参：`field_mappings` / `default_values`
+
+它不是 `record_access` 分析筛选 DSL。数据分析仍走 `record access` 的 `where` 规则。
+流程条件属于 WorkflowSpec 路径：先读 `builder flow schema` / `builder flow get`，再按读回结构修改；不要把 raw workflow `autoJudges/judgeType` 混入视图、报表、关联资源的公共筛选 DSL。
+
+公开写法按场景选择，智能体不要混用。**operator 语义完全一致，区别只在字段名键**：
+
+- **固定筛选**：`field_name + operator + value/values`
+- **关联资源上下文匹配**：`target_field + operator + source_field/value`
+- **新增数据传参**：`source_field + target_field`；静态默认值写 `default_values`
+
+不要直接写 `judgeType`、`judgeValues`、`matchRules`、`beforeAggregationFilterMatrix`。CLI 会按目标协议自动编译，并在读回时还原为业务语义。
+
+最短判断：
+
+| 你想表达 | 写法 | 示例 |
+| --- | --- | --- |
+| 当前视图/图表只显示某类数据 | `filters` | `{"field_name":"状态","operator":"eq","value":"进行中"}` |
+| 关联报表/关联视图只显示“当前记录相关”的数据 | `match_mappings` + `source_field` | `{"target_field":"关联客户","operator":"eq","source_field":"数据ID"}` |
+| 关联报表/关联视图再加一个固定条件 | `match_mappings` + `value/values` | `{"target_field":"状态","operator":"eq","value":"有效"}` |
+| 从当前记录创建下游记录并带值 | `field_mappings` | `{"source_field":"数据ID","target_field":"关联工单"}` |
+
+---
+
+## 1. `operator` / `value` 统一规则
+
+| `operator` | 含义 | `value/values` |
+| --- | --- | --- |
+| `eq` | 等于 | 单值用 `value` |
+| `neq` | 不等于 | 单值用 `value` |
+| `in` | 任一匹配 | 多值用 `values` |
+| `contains` | 包含 / 模糊包含 | 单值用 `value` |
+| `gte` | 大于等于 | 单值用 `value` |
+| `lte` | 小于等于 | 单值用 `value` |
+| `is_empty` | 为空 | 不写 `value/values` |
+| `not_empty` | 不为空 | 不写 `value/values` |
+
+`operator` 省略时按 `eq` 处理，但主示例必须显式写 `operator`。`value` 是单值主写法；`values` 是多值主写法。CLI 兼容 `value` 传数组、`values` 传单个标量，但不要把兼容形态当主示例。
+
+兼容别名：`equal`、`equals`、`=`、`==`、`!=`、`not_equal`、`any_of`、`one_of`、`include`、`like`、`empty`、`is null`、`not empty`、`not null`。主示例只写上表 canonical operator。
+
+### 1.1 不同字段类型的值写法
+
+默认优先写业务可读值，但要区分字段类型。选项字段（单选/多选/是否）在视图筛选、QingBI 筛选、关联资源静态筛选中均支持选项文本或 option id，CLI 会按目标协议自动转成 id 或文本。成员、部门、关联记录这类实体字段在固定筛选里优先写唯一 id 或 `{id,value}`；只有新增数据默认值、record 写入、候选解析类路径才先写名称，解析失败后再按候选改成 id。
+
+| 字段类型 | 推荐值写法 | 示例 |
+| --- | --- | --- |
+| 文本 / 长文本 / 手机 / 邮箱 | 字符串；模糊匹配用 `contains` | `{"field_name":"客户名称","operator":"contains","value":"上海"}` |
+| 数字 / 金额 | JSON 数字；范围用 `gte` / `lte` | `{"field_name":"金额","operator":"gte","value":10000}` |
+| 日期 / 日期时间 | 字符串；优先 `YYYY-MM-DD` 或 `YYYY-MM-DD HH:mm:ss` | `{"field_name":"计划日期","operator":"lte","value":"2026-06-30"}` |
+| 单选 | 选项文本或 option id；优先写文本；对象可写 `{id,value}` / `{optId,optValue}` | `{"field_name":"状态","operator":"eq","value":"进行中"}` 或 `{"field_name":"状态","operator":"eq","value":"160712876"}` |
+| 多选 | 多值用 `values`；每一项可写选项文本、option id 或选项对象 | `{"field_name":"标签","operator":"in","values":["重点","续约"]}` |
+| 布尔 / 是否 | 按字段实际选项文本写，通常是 `是` / `否` | `{"field_name":"是否逾期","operator":"eq","value":"是"}` |
+| 成员 / 部门 | 固定筛选写唯一 id 或 `{id,value}`；候选解析类写入路径可先写名称 | `{"field_name":"负责人","operator":"eq","value":{"id":123,"value":"沈嘉慧"}}` |
+| 关联记录 / relation | 固定筛选写目标记录真实 `record_id/apply_id`；当前记录跨应用匹配用 `source_field:"数据ID"` | `{"field_name":"关联客户","operator":"eq","value":"535734615263924225"}` |
+| 引用 / 数据填充字段 | 按读回展示类型写值；若本质来自选项字段，仍优先写展示文本 | `{"field_name":"客户等级","operator":"eq","value":"A"}` |
+
+字段值选择原则：
+
+- 选项字段：优先写选项文本，例如 `"正常"`；如果文本不唯一或来自读回，也可写 option id，例如 `"160712876"`。
+- 成员/部门：固定筛选优先写 id 或 `{id,value}`；record 写入、默认值等候选解析路径可先写名称，若返回 `needs_confirmation` 再按候选改成 id。
+- 关联/relation：固定筛选写目标记录真实 `record_id/apply_id`；跨应用当前记录匹配写 `source_field:"数据ID"`，不要写前端编号。
+- 引用/数据填充字段：按前端展示的业务值写；如果引用来源是选项字段，仍优先写选项文本。
+- 读回口径：`builder view/chart/associated-resource get` 优先返回业务文本和 canonical `operator`，不把后端数字 `judgeType`、option id、`matchRules` 作为智能体主输出。raw `config` 只用于诊断。
+
+空值判断示例：
+
+```json
+{"field_name": "完工日期", "operator": "is_empty"}
+```
+
+读回示例：
+
+```json
+{"field_name":"使用状态","operator":"eq","value":"正常"}
+{"target_field":"状态","operator":"in","values":["有效","待提交"]}
+```
+
+---
+
+## 2. 当前记录上下文匹配
+
+优先使用语义化映射，不手写后端 raw `que_relation` / `match_rules`。
+
+心智模型：**同一个 operator，同一套 value 规则；只是当前记录匹配要把 `field_name` 改成 `target_field`，并用 `source_field` 表示当前记录字段。**
+
+- 固定筛选当前资源自己的数据：`field_name + operator + value/values`
+- 用当前记录过滤另一个资源：`target_field + operator + source_field`
+- 给另一个资源加静态筛选：`target_field + operator + value/values`
+- 从当前记录创建下游记录时传值：`source_field + target_field`，不写 `operator`
+
+`operator` 和 `value/values` 的含义与 §1 完全一致。`operator` 省略时默认为 `eq`，但为了可读性，主配置仍推荐显式写出。
+不要把跨应用“当前记录匹配”写成 `filters`：`filters` 只筛当前视图/报表自己的数据；`match_mappings` 才表示“拿当前记录的某个字段去匹配另一个资源”。
+
+### 2.1 新增数据按钮
+
+```json
+[
+  {
+    "client_key": "add_worklog",
+    "button_text": "快捷添加工时",
+    "trigger_action": "addData",
+    "trigger_add_data_config": {
+      "target_app_key": "WORKLOG_APP",
+      "field_mappings": [
+        {"source_field": "数据ID", "target_field": "关联员工"},
+        {"source_field": "员工名称", "target_field": "员工姓名"}
+      ],
+      "default_values": {
+        "状态": "待提交"
+      }
+    }
+  }
+]
+```
+
+`field_mappings` 表示从当前记录动态带值，不需要 `operator`；`default_values` 只表示静态默认值。
+
+### 2.2 关联视图 / 报表
+
+跨应用关联必须显式传 `target_app_key`。若关联的是当前应用自己的视图或报表，可以省略 `target_app_key`，CLI 会默认使用命令里的 `--app-key`。
+
+```json
+[
+  {
+    "client_key": "employee_worklogs",
+    "graph_type": "view",
+    "target_app_key": "WORKLOG_APP",
+    "view_key": "WORKLOG_VIEW",
+    "match_mappings": [
+      {"target_field": "关联员工", "source_field": "数据ID"},
+      {"target_field": "状态", "value": "待提交"}
+    ]
+  }
+]
+```
+
+动态条件用 `source_field`；静态条件用 `value/values`。如果一个条件写了 `source_field`，就不要再写 `value/values`。
+
+`field_name` / `field` 可作为 `target_field` 别名；静态单值写 `value`，多值写 `values`，空值类 operator 不写值。
+
+跨应用 relation 最常见写法是把当前记录的数据 ID 匹配到目标应用的引用字段：
+
+```json
+{"target_field": "关联客户", "operator": "eq", "source_field": "数据ID"}
+```
+
+这里 `target_field` 是被关联资源所在应用里的字段，`source_field` 是当前详情页这条记录里的字段。不要把它写成视图/报表 `filters`，也不要手写 `matchRules`。
+
+如果 `target_field` 是目标应用中的引用 / relation 字段，最稳妥的当前记录匹配值是 `source_field: "数据ID"`，因为它表示当前记录真实 `record_id/apply_id`。不要用前端可见 `编号` 代替，除非目标字段本身就是文本/编号字段。
+
+示例：
+
+```json
+{"target_field": "客户ID", "operator": "eq", "source_field": "数据ID"}
+{"target_field": "状态", "operator": "eq", "value": "有效"}
+{"target_field": "状态", "operator": "in", "values": ["有效", "待提交"]}
+{"target_field": "归档说明", "operator": "is_empty"}
+```
+
+---
+
+## 3. 系统字段
+
+系统字段可以参与匹配：
+
+| 写法 | field_id | 含义 |
+| --- | --- | --- |
+| `数据ID` / `row_record_id` / `apply_id` / `_id` | `-17` | 当前记录真实 record/apply ID |
+| `编号` / `数据编号` / `record_number` | `0` | 前端可见数据编号，可能是自定义编号 |
+
+也可以显式写：
+
+```json
+{"source_field": {"field_id": -17}, "target_field": "关联员工"}
+```
+
+注意：`数据ID` 和 `编号` 不是同一个东西。要把当前记录填入目标引用字段时，用 `数据ID`。
+
+---
+
+## 4. 类型兼容规则
+
+| 目标 / 源字段类型 | 可匹配对象 |
+| --- | --- |
+| 引用字段 | 同目标应用的引用字段，或当前源应用记录的 `数据ID(-17)` |
+| `数据ID(-17)` | 指向当前源应用的目标引用字段；也可匹配 ID 兼容的文本/数字字段 |
+| `编号(0)` | 文本、长文本、数字、金额、编号类字段 |
+| 成员字段 | 成员字段 |
+| 部门字段 | 部门字段 |
+| 单选 / 多选 / 布尔 | 选项类字段或静态选项值 |
+| 日期 / 日期时间 | 日期类字段互通 |
+| 文本 / 长文本 / 电话 / 邮箱 | 文本类字段互通 |
+| 数字 / 金额 | 数值类字段互通 |
+
+附件、子表、代码块、Q-Linker、地址字段默认不作为匹配字段。
+
+---
+
+## 5. 常见错误处理
+
+| 错误场景 | 下一步 |
+| --- | --- |
+| 字段不存在 | 重新 `builder app get --app-key APP_KEY fields` / `builder app get --app-key APP_KEY`，用准确字段标题或 `field_id` |
+| 类型不兼容 | 按上表换兼容的源字段 / 目标字段 |
+| 引用来源不一致 | 目标引用字段指向了别的应用；换成指向当前源应用的引用字段 |
+| 同时传 semantic 与 raw | 同一项里只能二选一：`field_mappings/match_mappings` 或 raw `que_relation/match_rules` |
+
+---
+
+## 6. 关联资源 ID 口径
+
+`associated_item_id` 是应用级关联资源池里的 `form_asos_chart.id`，最终口径来自：
+
+```bash
+qingflow --json builder app get --app-key APP_KEY
+```
+
+或同等 `app_get.associated_resources[].associated_item_id`。
+
+它不是 `chart_id`、`chart_key`、`view_key`。但新版 `builder associated-resource apply` 在部分入口可接受 `chart_id` / `chart_key` / `view_key` 作为 selector，并自动解析成后端需要的 `associated_item_id`；写 view config 或排障时仍以读回的 `associated_item_id` 为准。

package/skills/qingflow-cli/reference/builder/reference/workspace-icons.md

@@ -0,0 +1,89 @@
+# Builder 工作区图标规则
+
+用于应用包、应用、门户的新建与改名改图标场景。
+
+## 默认链路
+
+1. 先读取候选目录：
+
+```bash
+qingflow --json builder icon catalog
+```
+
+2. 新建应用包、应用、门户时，显式填写 `icon` 和 `color`。
+
+3. 不要使用 `template`；这是通用图标，新建资源会被 CLI 阻断。
+
+## 关键规则
+
+- CLI 不会根据业务名称自动猜图标。
+- 智能体必须自己选择业务贴合的图标和颜色；主写法只有 `icon + color`，例如 `"icon": "table", "color": "blue"`。
+- CLI/MCP 继续兼容 `icon_name + icon_color`、`icon_config` 或 `icon: {name, color}`，但这些只用于历史载荷和读回适配，不作为新提示词示例。
+- 创建应用包、应用、门户时缺少 `icon` 或 `color` 会失败。
+- 同批多应用创建时，每个新应用应使用不同 `icon`。
+- 编辑已有资源时，不传 `icon/color` 会保留现状；显式传入时仍会校验合法性。
+- 读取结果里的 `icon_config` 是给 UI/agent 展示用的解构结果，包含 `icon_name`、`icon_color`、`icon_text`、`raw`。
+
+## 示例选择
+
+这些只是候选思路，不是 CLI 默认映射：
+
+| 场景 | 可选 icon |
+|---|---|
+| 员工 / 花名册 | `business-personalcard`、`user-group` |
+| 任务 / 待办 | `clipboard-check`、`action-work` |
+| 工时 / 时间 | `clock`、`action-hourglass-full` |
+| 商机 / 增长 | `business-graph`、`business-trend-up` |
+| 订单 / 交付 | `delivery-box-1`、`shopping-bag` |
+| 回款 / 收款 | `money-receipt-2-1`、`money-wallet-1` |
+| 门户 / 数据大屏 | `view-grid`、`chart-square-bar` |
+
+常见安全选择：
+
+| 场景 | 推荐 icon | 推荐颜色 |
+|---|---|---|
+| 应用包 / 门户 | `view-grid`、`chart-square-bar` | `blue`、`indigo`、`qing-purple` |
+| 表单 / 台账 | `table`、`database`、`document` | `blue`、`azure` |
+| 流程 / 任务 / 审批 | `clipboard-check`、`clipboard-list`、`action-work` | `emerald`、`green` |
+| 时间 / 计划 | `clock`、`calendar` | `orange`、`yellow` |
+| 设备 / 资产 | `server`、`comp-devices`、`cog`、`wrench-f` | `azure`、`indigo` |
+| 风险 / 异常 | `exclamation-circle`、`shield-exclamation`、`bug-f` | `red`、`orange` |
+| 财务 / 收付款 | `currency-yen`、`money-wallet-1`、`money-receipt-2-1` | `orange`、`qing-orange` |
+| 人员 / 组织 | `user`、`user-group`、`business-personalcard` | `emerald`、`blue` |
+
+不要写不存在的泛化图标名，例如 `warning`、`approval`、`asset`。需要警告类图标时用 `exclamation-circle` 或 `shield-exclamation`；需要审批类图标时用 `clipboard-check`。
+
+## 当前 catalog 快照
+
+以下清单来自当前 CLI 的 `builder icon catalog`。如果本机 CLI 返回的 catalog 与这里不同，以命令返回为准。
+
+颜色：
+
+`qing-orange`, `yellow`, `green`, `emerald`, `blue`, `azure`, `indigo`, `qing-purple`, `purple`, `pink`, `red`, `orange`
+
+图标：
+
+- `user`, `user-group`, `user-remove`, `user-add`, `user-circle`, `base-camera`, `view-grid`, `inbox`
+- `inbox-in`, `share`, `sitemap`, `airplane`, `template`, `music-note`, `movie-play`, `clock`
+- `document`, `document-search`, `clipboard-check`, `document-download`, `document-text`, `clipboard-copy`, `presentation-chart-bar`, `chart-square-bar`
+- `database`, `server`, `calendar`, `mail`, `annotation`, `chat`, `bell`, `key`
+- `shopping-bag`, `download`, `eye`, `eye-off`, `emoji-happy`, `emoji-sad`, `sun`, `moon`
+- `cloud`, `lightning-bolt`, `fire`, `star`, `sparkles`, `heart`, `cake`, `gift`
+- `light-bulb`, `exclamation`, `cog`, `thumb-up`, `thumb-down`, `cloud-download`, `cloud-upload`, `printer`
+- `phone-incoming`, `phone-missed-call`, `terminal`, `search-circle`, `x-circle`, `check-circle`, `exclamation-circle`, `question-mark-circle`
+- `information-circle`, `academic-cap`, `briefcase`, `home`, `phone`, `photograph`, `puzzle`, `color-swatch`
+- `lock-open`, `lock-closed`, `shield-check`, `shield-exclamation`, `currency-dollar`, `currency-yen`, `globe`, `at-symbol`
+- `slack`, `microphone`, `speakerphone`, `trash`, `book-open`, `truck`, `filter`, `essetional-filter-search`
+- `essetional-filter-tick`, `table`, `calculator`, `location-radar`, `essetional-weight`, `school-award`, `comp-cloud-connection`, `comp-cloud-remove`
+- `comp-cpu-charge`, `comp-cpu-setting`, `comp-cpu`, `comp-devices`, `comp-driver-2`, `comp-driver-refresh`, `location-global`, `location-location`
+- `location-map`, `location-gps`, `essetional-ranking`, `chart-bar`, `business-graph`, `business-status-up`, `business-trend-down`, `business-trend-up`
+- `business-presention-chart`, `business-favorite-chart`, `business-health`, `receipt-refund`, `receipt-tax`, `money-receipt-2-1`, `money-transaction-minus`, `action-hourglass-full`
+- `action-work`, `bug-f`, `essetional-pet`, `files-folder`, `badge-check`, `money-wallet-1`, `money-ticket`, `money-money`
+- `money-tag`, `money-wallet-2`, `business-personalcard`, `car-airplane`, `car-bus`, `car-car`, `car-driving`, `car-gas-station`
+- `car-smart-car`, `car-ship`, `location-map-1`, `location-route-square`, `cone`, `design-brush-4`, `paint-roll`, `wrench-f`
+- `essetional-reserve`, `essetional-broom`, `design-brush-2`, `essetional-judge`, `design-bucket`, `palette`, `comp-electricity`, `vial`
+- `beaker`, `leaf-f`, `cursor-click`, `solid-search-alt-2`, `md-library`, `building-3`, `office-building`, `building-hospital`
+- `school`, `store`, `video-camera-vintage-f`, `comp-monitor`, `delivery-truck`, `delivery-box-1`, `delivery-box-add`, `delivery-box-remove`
+- `settings-setting-3`, `document-duplicate`, `essetional-flag-2`, `flag`, `icon-currency-dollar`, `clipboard-list`, `save-as`, `wifi`
+- `status-online`, `scissors`, `globe-alt`, `ban`, `finger-print`, `qrcode`, `paper-clip`, `translate`
+- `cube-transparent`, `variable`, `switch-vertical`, `sports-baseball`, `sports-basketball`, `sports-soccer`, `sports-football`, `sports-volleyball`

package/skills/qingflow-cli/reference/builder/workflow/01-overview.md

@@ -0,0 +1,48 @@
+# 轻流工作流搭建：概览与依赖
+
+## 关联文件
+
+| 文件 | 说明 |
+|------|------|
+| `manifest.yaml` | 技能清单 |
+| `SKILL.md` | 主流程入口 |
+| `scripts/workflow/validate_flow_spec.py` | 工作流 Spec 验证脚本，基于 JSON Schema + 自定义约束 |
+| `scripts/workflow/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 --json builder flow apply --app-key <KEY> --spec-file <FILE>` | 主链路：部署/更新 WorkflowSpec |
+| `qingflow --json builder flow apply --app-key <KEY> --patch-nodes-file <PATCH>` | 局部修改现有节点 |
+| `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；`patch_nodes` 仅用于已有节点局部维护 | 操作复杂命令拼接 |
+| 审批/填写/抄送/分支条件等 WorkflowSpec 支持的流程 | 不读 schema/spec 就猜 raw 后端字段 |
+| 审批/填写/抄送/自动化节点配置 | 修改字段定义 |
+| 成员/角色搜索用于节点负责人 | 组织架构管理 |
+| 验证 → apply → 校验循环 | 前端 UI 拖拽操作 |
+
+---
+
+无论线性、分支、Q-Robot、审批、填写还是抄送流程，新建和替换都使用 WorkflowSpec `--spec-file`；已有节点的小修改才使用 `--patch-nodes-file`。不要在技能主链路使用 `--nodes-file` + `--transitions-file`。
+
+← 返回主流程：[../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,63 @@
+# 更新模式与最小修改原则
+
+当应用已有工作流时，进入**更新模式**。核心原则是**最小修改**——只改动必要的部分，保持其他结构不变。
+
+## 为什么要保持节点 ID 稳定
+
+后端可能存储了 spec 中不支持的运行时配置（如审批策略、超时规则、高级权限等），这些配置与节点 ID 绑定。一旦修改节点 ID，后端会将其视为「删除旧节点 + 创建新节点」，导致不支持的配置全部丢失。
+
+**因此：修改已有节点时，只改 attrs/name，绝不改 id。**
+
+## 最小修改原则速查
+
+| 操作 | ✅ 正确做法 | ❌ 错误做法 |
+|------|-----------|-----------|
+| 添加节点 | 使用新 ID，追加到 nodes 末尾 | 重排已有节点 ID |
+| 删除节点 | 删除对应 node 和关联边 | 不删关联边导致孤立边 |
+| 修改节点配置 | 同一 ID 下只改 attrs/name | 改 ID 导致节点重建 |
+| 添加边 | 追加到 edges 数组 | 修改已有边的 from/to |
+| 修改条件 | 同一条边内改 condition | 删除边再新建 |
+| 调整流转 | 修改边的 from/to | 改节点 ID 来适配 |
+
+## 使用 patch_nodes 优先
+
+如果只是改节点名称、负责人、局部 attrs，优先使用 `patch_nodes[]`，节点 id 从 `builder flow get` 的 `spec.nodes[]` 读取：
+
+```json
+[
+  {"id": "89160906", "set": {"name": "需求评审（局部改）"}}
+]
+```
+
+## WorkflowSpec 更新时使用 diff 脚本辅助判断
+
+需要提交完整 `--spec-file` 时，在 apply 前使用 diff 脚本对比新旧 spec：
+
+```bash
+python3 scripts/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
+```
+
+输出会显示删除的节点/边、新增的节点/边、修改的节点/边，并自动评估是否符合最小修改原则。
+
+验证脚本也支持在 WorkflowSpec 更新模式下进行最小修改原则校验：
+
+```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,59 @@
+# 流程模式速查
+
+在构建 spec 前，先判断当前流程属于哪种模式，避免用错节点类型或边结构。
+
+## 线性流程
+
+最简单的流程模式：节点首尾相连，无分支、无条件。
+
+```
+n1 → n2 → n3 → n4
+```
+
+- 边不带 `condition`，按顺序流转即可
+- 无需 gateway 节点
+- 适用于：简单的提交→审批→结束
+
+## 分支流程
+
+分支流程属于 WorkflowSpec 主路径。需要分支时先读 `builder flow schema` / `builder flow get`，再用 `--spec-file` 提交完整 WorkflowSpec。
+
+轻流的分支采用**并行分支**模型——通过 `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-cli/reference/builder/workflow/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-cli/reference/builder/workflow/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)