@lovrabet/rabetbase-cli 2.5.3-beta.1 → 2.5.3-beta.2

package/skills/rabetbase/knowledge/approval-flow/config-json-schema.md

@@ -0,0 +1,290 @@
+# Rabetbase FlowConfig 契约
+
+本文件描述 `rabetbase flow validate/create/update/detail --output` 使用的可移植本地清单。服务端生成的 id、编码、状态和部署信息不属于本地文件。
+
+## 外层结构
+
+```json
+{
+  "flowName": "采购审批",
+  "flowDesc": "采购申请的主管审批",
+  "flowType": "INDEPENDENT_FLOW",
+  "flowJson": {
+    "pageMode": "CUSTOM_PAGE",
+    "startPageId": 10001,
+    "nodes": [],
+    "edges": []
+  }
+}
+```
+
+必填字段：
+
+- `flowName`：非空流程名称。
+- `flowType`：`FORM_FLOW` 或 `INDEPENDENT_FLOW`，不得根据节点或数据集绑定推断。
+- `flowJson.nodes`：非空节点数组。
+- `flowJson.edges`：非空连线数组。
+
+可选字段：`flowDesc`、`datasetCode`、`pageId`。
+
+`flowType` 是产品语义分类，不由节点形状推断：
+
+- `FORM_FLOW`：表单审批流，可以配置 `datasetCode`、`pageId`；人工节点只允许 `taskMode: "APPROVAL"`，禁止 `HANDLE`。
+- `INDEPENDENT_FLOW`：独立工作流，不能配置外层 `datasetCode` 或外层 `pageId`；可以同时使用 `APPROVAL` 和 `HANDLE`。
+
+独立工作流中出现审批节点不会把它变成表单审批流。需要填写、补充材料、执行或确认等人工办理步骤时使用 `INDEPENDENT_FLOW + HANDLE`。
+
+`flowJson.pageMode` 只适用于 `INDEPENDENT_FLOW`：
+
+- `CUSTOM_PAGE`：业务自定义页面，缺省时按此值处理。
+- `PLATFORM_FORM`：服务端的平台表单页面语义；当前 Skill 和 CLI 不支持生成或提交。
+
+`FORM_FLOW` 不得配置 `pageMode`。自定义页面 SDK/OpenAPI 只返回 `INDEPENDENT_FLOW + CUSTOM_PAGE`。
+
+`INDEPENDENT_FLOW + CUSTOM_PAGE` 可选配置正整数 `flowJson.startPageId`，并在 `APPROVAL` 人工节点上可选配置正整数 `pageId`。二者只用于页面跳转，不参与流程执行或业务判断；缺失时调用方自行选择页面。其他流程类型、`PLATFORM_FORM` 或非人工节点不得配置这两个导航字段。
+
+本地 FlowConfig 必须显式填写 `flowType`。CLI 不再利用服务端的历史默认值推断为 `FORM_FLOW`，避免表单审批流和独立工作流混用。
+
+Skill 根据业务逻辑直接生成完整 `nodes + edges` 拓扑，不读取或填写 SmartCode `templateName`。
+
+`appCode` 来自当前 CLI 工作区，远程定义 `id` 来自 `--id`。二者都不落本地文件。
+
+## 规范化
+
+`normalizeFlowConfig` 不修改调用方对象，并对下列旧字段产生 warning 后从规范结果移除：
+
+- 外层：`id`、`appCode`、`templateName`
+- `flowJson`：`flowKey`、`flowCode`、`flowName`、`bindDatasetCode`、`datasetCode`、`appCode`、`pageId`、`templateName`
+- 任意层级值为空的 `metadata`
+
+`flowJson.schemaVersion` 按 SmartCode 规则单独处理：空值或默认值 `approval.simple-flow.v1` 会警告并移除；其他值保留在规范结果中，并由本地校验明确返回 `Unsupported schemaVersion`。这样不会把未知或未来版本静默降级为 v1。
+
+`flow validate --write-normalized` 只写规范结果。校验器从外层元数据创建独立内存副本，临时注入编译上下文；这些值不会污染文件。
+
+## 页面模式
+
+使用 `INDEPENDENT_FLOW + CUSTOM_PAGE` 时：
+
+- 采购申请等业务数据由自定义页面直接读写业务数据集，并按业务状态展示不同页面和操作。
+- 流程只保存路由、办理人、脚本、通知等执行配置；页面通过 SDK 发起或办理任务，成功后自行更新业务状态。
+- 禁止 `flowJson.formSchema`、`flowJson.formDefinitions`、`flowJson.formPermissions`、节点 `form`、节点 `formPermission` 和 `cc.readSources`。
+- `validate/create/update/detail --output` 遇到上述字段会明确报错，不会静默删除或导出丢字段的文件。普通 `detail` 仍可只读查看远端原始定义。
+
+`INDEPENDENT_FLOW + PLATFORM_FORM` 使用平台表单能力，不属于自定义页面 SDK 的返回范围。当前 CLI 只识别该服务端语义用于明确报错，`validate/create/update/detail --output` 均拒绝生成或提交此模式；Skill 必须返回 `NEEDS_DSL_EXTENSION`。普通 `detail` 仍可只读查看远端原始定义。
+
+## 通用节点
+
+```json
+{
+  "id": "managerApprove",
+  "type": "APPROVAL",
+  "name": "主管审批",
+  "position": { "x": 300, "y": 180 }
+}
+```
+
+- 支持 `START`、`END`、`APPROVAL`、`CONDITION`、`SCRIPT`、`NOTIFICATION`。
+- 每个节点都必须有非空 `name`。
+- 每个节点都必须显式提供有限且大于等于 0 的 `position.x/y`。
+- 节点 ID 和边 ID 使用 `[A-Za-z_][A-Za-z0-9_]*`。
+- 节点和边共用一个 BPMN ID 命名空间，任何元素都不能重名。
+
+## 图结构
+
+- 必须且只能有一个 `START`，至少有一个 `END`。
+- `START` 无入边，`END` 无出边；其他节点必须同时满足必要的入边/出边要求。
+- 所有节点必须从 `START` 可达，并且每个可达节点都必须存在一条通往某个 `END` 的路径。
+- 支持自环、回退连线和多节点有向环；环路必须保留能够到达 `END` 的退出路径，不能形成无出口闭环。
+- 相同 `source + target + conditionType` 只能出现一次，即使边 ID 或 expression 不同。
+
+## APPROVAL
+
+```json
+{
+  "id": "managerApprove",
+  "type": "APPROVAL",
+  "name": "主管审批",
+  "pageId": 10002,
+  "position": { "x": 300, "y": 180 },
+  "taskMode": "APPROVAL",
+  "approvalMode": "SINGLE",
+  "sequential": false,
+  "assignee": {
+    "strategy": "FIXED",
+    "userIds": ["82"]
+  },
+  "transferCandidates": {
+    "strategy": "FIXED",
+    "userIds": ["15023", "16001"]
+  }
+}
+```
+
+- `taskMode` 支持 `APPROVAL`、`HANDLE`；省略时按 `APPROVAL`。`FORM_FLOW` 只能使用 `APPROVAL`，`HANDLE` 仅允许出现在 `INDEPENDENT_FLOW`。
+- `pageId` 可省略；仅 `INDEPENDENT_FLOW + CUSTOM_PAGE` 的 `APPROVAL` 人工节点可配置，用于待办、已办和任务详情跳转，不影响节点执行。
+- `approvalMode` 支持 `SINGLE`、`ALL`、`ANY`；省略时按 `SINGLE`。`sequential` 控制多办理人是否顺序执行，默认 `false`。
+- `FIXED` 需要非空有效 `userIds`；`SINGLE + FIXED` 只能有一个不同用户。
+- `ROLE` 需要正整数 `roleId`。
+- `transferCandidates` 可省略；存在时只支持 `FIXED`，且 `userIds` 必须非空，每项为非空字符串或正整数。
+- `taskMode: "APPROVAL"` 必须且只能有一条 `APPROVED` 出边和一条 `REJECTED` 出边，两条边都不能是默认边。
+- `taskMode: "HANDLE"` 必须且只能有一条 `ALWAYS` 出边，不能配置 `defaultFlow` 或 `expression`；办理完成后直接沿该边继续。
+- 只要流程包含决策型 `APPROVAL` 任务，就必须同时存在 `result: "APPROVED"` 和 `result: "REJECTED"` 的 END 节点。只有 `HANDLE` 的流程不要求这两个结果节点。
+
+### HANDLE 后续路由
+
+- `HANDLE` 自身不选择业务分支。自定义页面可在办理请求中的 `variables` 更新业务变量，或通过 `formPatch` 增量更新 `formData`；任务完成后，下游节点读取更新后的值。
+- 路由变量已准备好时使用 `HANDLE → CONDITION`，由 CONDITION 的表达式和默认边决定后续路径。
+- 需要 Backend Function 先计算、校验或归一化路由变量时使用 `HANDLE → SCRIPT → CONDITION`；不需要计算时可省略 SCRIPT。
+- 不允许给 HANDLE 配置多条出边，也不允许通过 `targetNodeId` 让调用方直接选择目标节点。办理节点存在多个业务结果不应判定为 `NEEDS_DSL_EXTENSION`，因为分支职责属于下游 CONDITION。
+
+### 审批超时
+
+`APPROVAL.timeout.enabled=true` 时必须配置正整数 `duration.value` 和 `SECONDS/MINUTES/HOURS/DAYS` 单位：
+
+- `AUTO_APPROVE`、`AUTO_REJECT` 必须中断当前任务，`interrupting` 省略时默认 `true`。
+- `EXECUTE_BFF` 必须配置 `scriptName`，不能中断当前任务，`interrupting` 省略时默认 `false`；可用 `resultVariable` 保存结果。
+- `HANDLE` 超时只支持 `EXECUTE_BFF`。
+
+## CONDITION
+
+```json
+[
+  {
+    "id": "edge_amount_finance",
+    "source": "amountCheck",
+    "target": "financeApprove",
+    "conditionType": "EXPRESSION",
+    "expression": "${formData.amount > 10000}"
+  },
+  {
+    "id": "edge_amount_default",
+    "source": "amountCheck",
+    "target": "approvedEnd",
+    "conditionType": "ALWAYS",
+    "defaultFlow": true
+  }
+]
+```
+
+- CONDITION 至少有两条出边。
+- 必须且只能有一条 `defaultFlow: true`。
+- 默认边必须使用 `ALWAYS`，且不能定义 `expression`。
+- 其余边必须使用 `EXPRESSION`，且必须有非空 `expression`。
+
+表达式直接读取顶层流程变量；例如发起或办理请求中的 `variables.amount` 在表达式中写作 `${amount > 10000}`，`formData` 字段写作 `${formData.amount > 10000}`。生成表达式前先按开发工作流建立变量契约，不猜测变量名或类型。
+
+## SCRIPT
+
+```json
+{
+  "id": "checkPrice",
+  "type": "SCRIPT",
+  "name": "价格校验",
+  "position": { "x": 520, "y": 180 },
+  "scriptName": "checkProductPrice",
+  "resultVariable": "priceCheckResult",
+  "async": {
+    "enabled": true,
+    "retryCount": 3,
+    "retryInterval": { "value": 30, "unit": "SECONDS" }
+  }
+}
+```
+
+- `scriptName` 必填。
+- `resultVariable` 可省略；Runtime 省略时写入默认变量 `scriptResult`。存在时必须符合变量命名规则并在流程内唯一；多个 SCRIPT 或 `EXECUTE_BFF` 超时动作必须显式配置不同的结果变量，避免默认值互相覆盖。
+- 禁止 `formData`、`approved` 和 `approval_sys_` 前缀。
+- 表达式引用某个 `resultVariable` 时，产生该变量的 SCRIPT 必须位于引用边 source 的所有上游路径；SCRIPT 自己的出边可以读取刚写入的结果。
+- `async.enabled=true` 时使用 Flowable 异步 Job；`retryCount` 默认 3、范围 1～10，`retryInterval` 默认 30 秒，也支持 `MINUTES/HOURS/DAYS`。
+- SCRIPT 接收当前流程变量作为顶层 `params`，并额外收到 `params.approvalContext`；因此业务变量 `amount`、表单字段 `formData.amount` 分别通过 `params.amount`、`params.formData.amount` 读取，不使用 `params.variables` 包装。
+
+## 节点默认抄送
+
+APPROVAL 和 END 节点可配置 `cc.recipientUserIds`。APPROVAL 在整个节点办理结束后创建默认只读抄送记录（会签/或签不会按每个办理人重复抄送），END 在到达结果节点后创建。用户 ID 必须是 1～100 个不重复的非空字符串；`visible` 可限制可见表单字段。抄送详情的 `businessVariables` 从流程当前 variables 中读取，并过滤 `approval_sys_*`、`formData` 和 `approved`；当前页面模式不支持 `cc.readSources`。
+
+## NOTIFICATION
+
+```json
+{
+  "id": "notifyApproved",
+  "type": "NOTIFICATION",
+  "name": "发送审批结果通知",
+  "position": { "x": 740, "y": 180 },
+  "config": {
+    "version": "v1",
+    "configCode": "approval_email",
+    "failurePolicy": "CONTINUE",
+    "template": {
+      "title": "审批结果通知",
+      "summary": "${event.initiatorUsername} 发起的申请已经${event.approvalResultName}",
+      "facts": [
+        {
+          "label": "申请金额",
+          "value": "${variables.formData.amount}"
+        }
+      ],
+      "detailMarkdown": "**审批节点：** ${context.nodeName}",
+      "actions": [
+        {
+          "text": "审批详情页",
+          "url": "${context.detailUrl}"
+        }
+      ]
+    },
+    "recipients": [
+      {
+        "type": "USER",
+        "role": "TO",
+        "value": "${event.initiatorUserId}"
+      }
+    ]
+  }
+}
+```
+
+配置规则：
+
+- `version` 可省略或留空，默认 `v1`；当前只支持 `v1`。
+- `configCode` 必须是从 `notification config-list` 选出的固定非空值，不能使用占位符、渠道名、URL、dataset code 或凭据。
+- `failurePolicy` 支持 `CONTINUE`、`FAIL`，默认 `CONTINUE`。
+- `template` 必填；不要输出 `theme` 或 `templateType`。
+- `template.title`、`template.summary` 必须是非空字符串。
+- `template.detailMarkdown` 可选，存在时必须是字符串。
+- `template.facts` 可选，最多 8 项；每项需要非空 `label`、`value`。
+- `template.actions` 可选，最多 2 项；每项需要非空 `text`、`url`。
+- `actions[].url` 必须使用 `http://`、`https://`，或完整受支持占位符，例如 `${context.detailUrl}`。
+
+占位符只允许以下命名空间，且根名称区分大小写：
+
+```text
+${event.xxx}
+${context.xxx}
+${variables.xxx}
+```
+
+不要使用 `{appCode}`、`${appCode}` 或其他未声明根命名空间。模板标题、摘要、facts、detailMarkdown、actions 和收件人 value 都执行该检查。
+
+收件人规则：
+
+- `recipients` 可省略或为空，此时使用渠道配置的默认目标。
+- 显式项的 `type` 支持 `USER`、`ROLE`、`EMAIL`。
+- `value` 必须是非空固定值或受支持占位符。
+- `role` 可选，支持 `TO`、`CC`、`BCC`，默认 `TO`。
+- 非空显式列表至少包含一个 `TO`。
+- `CC`、`BCC` 只对 EMAIL 渠道有效。
+- 显式收件人只用于 EMAIL 或飞书 APP 机器人；钉钉、企业微信、通用 Webhook 和飞书 Webhook 使用渠道默认目标。
+- 飞书显式收件人应使用 `TO`，并符合渠道配置的 `receiveIdType`。
+
+本地 validator 可确定并检查 version、模板必填字段、数量上限、action URL、占位符语法和 recipients 结构。`configCode` 是否存在、渠道是否支持显式收件人、模板变量解析后的真实值仍以服务端为准。
+
+## 本地校验边界
+
+当前本地校验统一由 `rabetbase flow validate` 调用内置 TS validator，覆盖本文明确列出的本地结构、规范化、节点配置、NOTIFICATION 可确定规则和图拓扑规则。Skill 不维护额外的校验脚本。
+
+本地校验不能确认：
+
+- userId、roleId、datasetCode、pageId、scriptName、configCode 是否在目标环境真实存在。
+- `configCode` 对应的当前通知渠道是否支持指定模板或显式收件人。
+- 服务端保存、编译、部署和 Runtime 执行是否成功。
+
+这些结果必须分别通过资源发现命令、服务端 flow 命令响应和 Runtime 验证确认。

package/skills/rabetbase/references/rabetbase-bff-create.md

@@ -29,7 +29,7 @@ rabetbase bff create --type HOOK --name beforeFilter --alias appUser --operation
 |------|------|
 | ENDPOINT | `.rabetbase/bff/<appCode>/ENDPOINT/<name>.js` |
 | COMMON | `.rabetbase/bff/<appCode>/COMMON/<name>.js` |
-| HOOK | `.rabetbase/bff/<appCode>/HOOK/<alias-or-datasetCode>/<operationType>/<functionNode>/<name>.js` |
+| HOOK 草稿 | `.rabetbase/bff/<appCode>/HOOK/<alias-or-datasetCode>/<operationType>/<functionNode>/<name>.js` |
 
 Backend Function 源码**仅**应在此目录树内创建与长期维护（与 `bff status` / `bff push` 扫描一致）；不要在本仓库其他路径手写 Backend Function 再尝试推送。
 

package/skills/rabetbase/references/rabetbase-bff-logs.md

@@ -0,0 +1,47 @@
+# bff logs
+
+查询当前 App 的 Backend Function 运行日志，用于开发调试。命令只读，不执行或修改脚本。
+
+## 命令
+
+```bash
+rabetbase bff logs --format compress
+rabetbase bff logs --since 10 --level ERROR --keyword timeout --format compress
+rabetbase bff logs --start-time 1788433200000 --end-time 1788435000000 --limit 500 --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--app <name>` | string | 否 | — | 多应用模式下指定应用名称 |
+| `--appcode <code>` | string | 否 | — | 直接指定 App Code |
+| `--since <minutes>` | number | 否 | `30` | 从结束时间向前查询的分钟数；不能与 `--start-time` 同时使用 |
+| `--start-time <ms>` | number | 否 | — | 查询开始时间，Unix 毫秒时间戳 |
+| `--end-time <ms>` | number | 否 | 当前时间 | 查询结束时间，Unix 毫秒时间戳 |
+| `--level <level>` | string | 否 | — | `DEBUG` / `INFO` / `WARN` / `ERROR` |
+| `--keyword <text>` | string | 否 | — | 对服务端格式化后的整行日志做关键字过滤 |
+| `--limit <count>` | number | 否 | `200` | 最大返回条数，范围 `1-1000` |
+
+## 时间范围
+
+- 未传时间参数时查询最近 30 分钟。
+- `--end-time` 可与 `--since` 配合，查询以指定结束时间为基准的时间窗。
+- 需要精确范围时传 `--start-time`，可同时传 `--end-time`；未传结束时间时使用当前时间。
+- `--since` 与 `--start-time` 互斥，时间戳必须为正整数，开始时间不得晚于结束时间。
+
+## 输出
+
+结构化输出的 `data` 包含：
+
+- `query`：最终发送的 `appCode`、`startTime`、`endTime`、可选过滤条件和 `limit`
+- `count`：本次返回的日志行数
+- `logs`：服务端已格式化的原始日志字符串数组
+
+无结果时先确认 App Code、运行环境和时间范围，再逐步移除 `level` 或 `keyword`。不要把查询不到日志解释为脚本一定未执行。
+
+## 参考
+
+- [backend-function.md](../guides/backend-function.md)
+- [bff detail](rabetbase-bff-detail.md)
+- [bff status](rabetbase-bff-status.md)

package/skills/rabetbase/references/rabetbase-bff-pull.md

@@ -25,17 +25,21 @@ rabetbase bff pull --type HOOK --force --format json
 返回：
 - `pulled`
 - `skipped`
+- `conflicts`
 - `failed`
 
-`--dry-run` 时返回预览对象，包含远端脚本、目标 `filePath` 和预期状态（如 `would_pull` / `conflict`）。
+`--dry-run` 时返回预览对象，包含远端脚本、目标 `filePath`、`alias`、`datasetCode`、Hook operation/node 和预期状态（如 `would_pull` / `conflict`）。有已跟踪的旧 HOOK 目录需要迁移时，还会返回 `hookDirectoryMigrations`。
 
 远端脚本列表会自动聚合服务端全部分页；不会只同步第一页。
 
 ## 提示
 
-- 默认会保护本地未同步改动，冲突时进入 `skipped: local unsynced changes`
+- 默认会保护本地未同步改动，冲突时进入 `conflicts`，包含受审阅约束的 `nextAction`
+- `conflicts[].code=BFF_LOCAL_UNSYNCED` 表示本地脚本自上次 pull 后已修改；先审阅，再在本地版本应成为事实来源时执行 `nextAction.command` 精确推送更新远端。不要把它报告为失败或用 `--force` 覆盖内容
 - `--dry-run` 不会改本地文件，也不会写 lock
-- `HOOK` 落盘目录依赖 alias / datasetCode 解析
+- HOOK 一级目录优先使用 `api.ts` 模型中的 alias；没有 alias 时使用 Dataset code
+- 挂载关系中有明确 Dataset code、但当前 SDK 模型没有 alias 时，仍按原始 Dataset code 下载，不阻断其他脚本；push 更新已有脚本时仍须回读确认脚本身份、版本与挂载关系
+- pull 会将 lock 跟踪的旧表名或过期 alias 目录迁到当前 SDK alias；当前没有 alias 时迁到 Dataset code。若目标目录已存在、旧目录已被另一 Dataset alias 复用且含未跟踪脚本，或本地文件系统无法安全迁移，命令会停止且不覆盖本地脚本
 - 拉取后建议立刻跑一次 `bff status`
 
 ## 参考

package/skills/rabetbase/references/rabetbase-bff-push.md

@@ -28,12 +28,15 @@ rabetbase bff push --type HOOK --name beforeFilter --format json
 返回：
 - `uploaded`
 - `skipped`
+- `conflicts`
 - `failed`
 
 常见 `skipped` 原因：
 - `unchanged`
 
-`--dry-run` 时返回预览对象，包含本地 `filePath`、目标模式（`create` / `update`）和预期状态（如 `unchanged` / `would_push`）。
+`--dry-run` 时返回预览对象，包含本地 `filePath`、`alias`、`datasetCode`、Hook operation/node、warning、目标模式（`create` / `update`）和预期状态（如 `unchanged` / `would_push`）。
+
+`conflicts[].code=BFF_REMOTE_VERSION_CHANGED` 或 `BFF_REMOTE_VERSION_MISSING` 表示本地 lock 不能安全更新远端脚本。保留本地脚本，先执行 `nextAction.command` 的 `bff detail` 取得远端源码，审阅并合并后再重试；只在明确放弃本地修改时才考虑 `--force`。这类同步分歧不进入 `failed`，其 `nextAction` 仅供审阅后执行。
 
 ## 推送前检查
 
@@ -53,7 +56,12 @@ rabetbase bff push --type HOOK --name beforeFilter --format json
 - 推送前先跑 `bff status`
 - `--dry-run` 不会上传远端，也不会改 lock
 - 精确推单个函数时用 `--type + --name`
-- HOOK 推送依赖数据集 alias / datasetCode 和 operationType/functionNode
+- HOOK 优先从 SDK alias 目录解析 Dataset；没有 alias 时 Dataset code 目录保持可读
+- 正式上传仍使用平台真实 Dataset ID，目录名不会替代远端 Dataset 身份
+- 已有 HOOK 的 Dataset 元数据缺失时，CLI 回读脚本 ID、应用、名称、类型、版本及唯一挂载关系；全部与本地 lock 匹配才允许按脚本 ID 更新且不重绑，返回 `EXISTING_HOOK_BINDING_PRESERVED` warning；新建 HOOK 不走此路径
+- 无法解析或查不到目标 Dataset 的 HOOK 单独进入 `failed`，其余可确认目标的脚本继续上传；部分失败时命令返回 `ok: false`，必须检查 `uploaded` 与 `failed`，不要整批盲目重试
+- 预演中无法确认目标的脚本显示 `status: failed` 与 `error`，不会上传或更改 lock
+- alias 与 Dataset code 命名空间碰撞、Dataset 映射漂移或同一 Dataset 出现多个本地目录会在首次远端写入前阻断
 - HOOK 可挂载 `DB_TABLE` 或 `METADATA` 数据集；METADATA 不支持 SQL / aggregate 路径，脚本中使用平台返回的标准数据操作
 - 推送成功只代表脚本配置已同步到平台；如需确认最终运行效果，使用运行验证（例如 `lovrabet bff exec --name <functionName> --params '<json>' --format compress`）
 - 管理态已同步但运行态仍旧版本时，按传播延迟 / 缓存延迟处理：等待后重试，必要时对目标脚本精确执行 `--force` 推送；仍不生效时记录平台运行态缓存风险

package/skills/rabetbase/references/rabetbase-dataset-generate.md

@@ -1,6 +1,6 @@
 # dataset generate-start / generate-status
 
-从自然语言需求生成可审阅的数据集 design 快照，再基于快照提交异步创建任务，最后查询任务状态拿到新 Dataset。
+从自然语言需求生成可审阅的单数据集或多数据集批次 design 快照，再基于快照提交异步创建任务，最后查询任务状态拿到完整结果。
 
 推荐顺序：
 
@@ -10,7 +10,36 @@
 
 ## 适用范围
 
-当前能力面向服务端支持的 `METADATA` 数据集生成链路。design 文件结构由服务端返回并由 CLI 原样提交，调用方不需要手写或选择内部 DO 版本。
+当前能力面向服务端支持的 `METADATA` 数据集生成链路。单数据集保持原协议；批次使用 `kind=dataset-batch`、`schemaVersion=1`，一次创建 1–20 个数据集及其 lookup 关系。
+
+## Batch：一次生成多个关联数据集
+
+```bash
+rabetbase dataset generate-start \
+  --batch \
+  --description "创建客户和订单数据集，订单通过 customer_id 关联客户 id" \
+  --design-output .rabetbase/dataset-designs/customer-orders.json \
+  --format compress
+```
+
+批次 Preview 不需要且不接受 `--name`。审阅文件时确认：`localKey` 唯一且为小写标识；每项 `design.relations` 为空；所有关系只出现在顶层 `relations`；`unresolvedRelations` 仅是待确认提示，不会落库。
+
+```bash
+rabetbase dataset generate-start \
+  --apply \
+  --design-file .rabetbase/dataset-designs/customer-orders.json \
+  --format compress
+```
+
+Apply 会按 `kind` 自动识别批次。`--batch` 可以显式要求输入必须是批次文件。首次提交默认生成 `dataset-batch-...` 恢复 ID；明确恢复或重试同一批时可传 `--client-operation-id <原ID>`。提交超时、响应损坏或未确认批次模式时，错误 `dataset_batch_submit_outcome_unknown` 会保留原 `clientOperationId`；只运行 `data.query.command` 或文本提示中的 status 查询，不要再次 POST。
+
+批次 start 响应必须确认 `mode=batch`。Status 只有同时满足以下条件才返回 `generated_datasets_created`：
+
+1. `expectedLocalKeys` 与 `createdDatasets[].localKey` 精确一致，每项都有真实 code。
+2. `expectedRelations` 与 `createdRelations` 按来源数据集、来源字段、目标数据集、目标字段、relationType、cardinality 六元组精确一致；字段名比较忽略大小写。
+3. 集合中不存在缺失、重复或多余项，真实关系携带的数据集 code 与创建结果一致。
+
+否则返回 `unknown_reconcile_failed`。批次输出使用复数 `createdDatasets` / `createdRelations`，不输出单数 `createdDataset`。
 
 ## Preview：生成 design 快照
 
@@ -73,6 +102,21 @@ rabetbase dataset generate-status --client-operation-id dataset-generate-xxx --f
 
 `--task-id`、`--operation-id` 与 `--client-operation-id` 必须且只能传一个。taskId 是首选恢复标识；CLI 会把它映射为后端 Dataset status 的 `operationId` query，服务端接口本身没有原生 taskId query。只有 status 输出 `status=generated_dataset_created` 且包含非空 `createdDataset.code` 时，后续才可执行 `dataset detail`、`page generate-start` 或 `api pull`。
 
+## 生成耗时与失败阶段
+
+Preview、Start、Status 的 `data.metrics` 透传服务端实际提供的指标，`data.failedStage` 表示服务端报告的失败阶段。旧响应或没有可用指标时返回 `null`，不代表耗时为零。指标与 design 分离，不能把指标写回设计快照或用于重新创建任务。
+
+可选指标包括：`schemaVersion`、`attemptId`、`attempt`、`datasetCount`、`fieldCount`、`previewDurationMs`、`queueWaitMs`、`executionDurationMs`、`resultReadDurationMs`、`stageDurationsMs`、`modelCallCount`、`retryCount`。耗时单位为毫秒；只使用返回中存在的测量值，不补造缺失阶段。重复 Status 查询不会累计服务端执行时间，`resultReadDurationMs` 仅表示本次结果读取。阶段可能嵌套，不能把阶段耗时相加当作端到端耗时。
+
+采集基线时：
+
+1. 固定输入、模型、环境、数据集数和字段数，分别记录简单结构、复杂枚举、已有数据集引用样例；保留每次原始输出和任务 ID。
+2. 预热后每个样例至少重复 10 次，分开记录 preview、排队、执行、结果读取及客户端观察到的完成耗时；排除人工审阅 design 的时间。10 次仅供初步比较，不足以稳定估计 P95。
+3. 优化前后保持相同条件，比较中位耗时和长尾，同时回读完整字段、枚举、主键及关联，不能以漏保存换速度。
+4. 失败、超时或响应丢失时恢复原任务，不重提；缺指标样本应标注不可用，不能当作零耗时样本。
+
+以上步骤只适用于有授权的测试环境。批次指标仍与 design 分离；指标出现只说明可观测性可用，不能独自证明性能已改善或批次结果完整。
+
 ## dry-run
 
 三条路径都支持 `--dry-run`：
@@ -184,6 +228,8 @@ Status 成功后的 `data` 包含：
 - 不要把 start 输出视为已创建 Dataset；必须用 `generate-status` 查询到 `generated_dataset_created`。
 - `PENDING` / `PROCESSING` 都不是完成；始终继续查询同一个 taskId。
 - 超时、未知状态或 start 响应丢失时只做状态恢复，不得自动重提生成请求。
+- 批次响应丢失时保留并复用原 `clientOperationId`；同一 design 自动生成新 ID 会成为另一批操作。
+- 批次成功后逐项使用 `createdDatasets[].code`，并核对 `createdRelations`；不要读取单数 `createdDataset`。
 - 成功后用 `rabetbase dataset detail --code <createdDataset.code> --format compress` 确认结构。
 - 如需生成数据列表页，再执行 `rabetbase page generate-start --datasetcode <createdDataset.code> --format compress`。
 - 真实业务行数据验证交接到 `lovrabet data filter|getOne`。
@@ -196,6 +242,10 @@ Status 成功后的 `data` 包含：
 | Preview 传了 `--design-file` | 去掉 `--design-file`，或改用 `--apply` |
 | Start 缺 `--design-file` | 指向已审阅的 design JSON 文件 |
 | Start 同时传了 `--name` / `--description` / `--design-output` | 删除这些 preview 参数 |
+| Batch Preview 传了 `--name` | 删除 `--name`；批次由 description 描述整体需求 |
+| `--batch --apply` 读取单设计 | 使用 `kind=dataset-batch`、`schemaVersion=1` 的批次文件 |
+| Batch Start 响应未确认 `mode=batch` | 停止，不要自动重提；用原 `clientOperationId` 查询状态 |
+| Batch SUCCESS 缺少完整 expected/created 集合 | 按 `unknown_reconcile_failed` 处理，继续恢复查询或人工核验 |
 | Status 缺任务标识 | 首选传 `--task-id`；旧响应才回退 `--operation-id` 或 `--client-operation-id` |
 | design 文件不是 JSON object | 修正为 JSON object 后重试 |
 

package/skills/rabetbase/references/rabetbase-flow-commands.md

@@ -0,0 +1,86 @@
+# rabetbase flow commands
+
+设计态流程定义命令，覆盖表单审批流与独立工作流。除 `validate` 外均需要认证和当前应用；`appCode` 由 CLI 工作区上下文注入。
+
+## validate
+
+```bash
+rabetbase flow validate --file <path> [--write-normalized] --format compress
+```
+
+- 纯本地命令，不要求登录或 App Code。
+- 返回 `data.valid`、`errors`、`warnings` 和 `normalized`。
+- `--write-normalized` 仅在配置有效时原子写回规范结果。
+- 校验时注入的临时 `flowKey`、`flowName` 和数据集绑定只存在于内存。
+- 空值或默认 `approval.simple-flow.v1` 会从 `flowJson.schemaVersion` 规范化移除；其他版本保留并报 `Unsupported schemaVersion`。
+
+Skill 直接执行本机的 `rabetbase flow validate` 命令，不维护额外的校验脚本或第二套规则。
+
+## list
+
+```bash
+rabetbase flow list \
+  [--flow-code <code>] \
+  [--flow-name <name>] \
+  [--flow-status <draft|published>] \
+  [--dataset-code <code>] \
+  [--flow-type <type>] \
+  [--page <n>] [--page-size <n>] \
+  --format compress
+```
+
+调用 `POST /smartapi/flow/page`。输出 `data.flows` 和分页信息，保留后续 detail/update/publish 所需的服务端 `id`。
+
+## detail
+
+```bash
+rabetbase flow detail --id <flow-id> --format compress
+rabetbase flow detail --id <flow-id> --output .rabetbase/flows/purchase.json
+rabetbase flow detail --id <flow-id> --output <path> --force
+```
+
+调用 `POST /smartapi/flow/detail`。控制台结果保留服务端定义；`--output` 会重新投影、校验并规范化为可移植 FlowConfig。包含当前不支持的自定义表单字段时只读 detail 仍成功，但 `--output` 明确失败，避免生成丢配置文件。目标已存在时必须显式 `--force`，写入使用原子替换。
+
+## create
+
+```bash
+rabetbase flow create --file <path> --dry-run --format compress
+rabetbase flow create --file <path> --format compress
+```
+
+调用 `POST /smartapi/flow/create`。提交前强制 normalize + validate。请求体只包含外层可写字段、当前工作区 `appCode` 和最小 `flowJson`；文件中的遗留 `id`、`appCode`、状态和部署字段不会提交。
+
+`flowType` 必填，支持 `FORM_FLOW`、`INDEPENDENT_FLOW`。`FORM_FLOW` 是表单审批流，禁止 `taskMode: HANDLE`；`INDEPENDENT_FLOW` 是工作流，可以同时包含 `APPROVAL` 和 `HANDLE`，且不能同时配置外层 `datasetCode` 或 `pageId`。`flowJson.pageMode` 只用于独立工作流，当前 CLI 只允许 `CUSTOM_PAGE`，缺省也按 `CUSTOM_PAGE`；`PLATFORM_FORM` 返回不支持错误。`INDEPENDENT_FLOW + CUSTOM_PAGE` 可选配置 `flowJson.startPageId` 和人工节点 `pageId`，两者仅用于导航。
+
+Skill 直接提交完整 `nodes + edges` 拓扑，不读取或发送 `templateName`。旧本地文件中的该字段会在规范化时移除并产生 warning。
+
+当前公开 Skill 创建独立工作流时使用 `INDEPENDENT_FLOW + 业务自定义页面`；表单审批流仍使用 `FORM_FLOW` 及其外层数据集/页面绑定。CLI 不解析 `formSchema/formDefinitions/formPermissions` 或节点 `form/formPermission`，这些字段会在 validate/create/update 中报错。
+
+## update
+
+```bash
+rabetbase flow update --id <flow-id> --file <path> --dry-run --format compress
+rabetbase flow update --id <flow-id> --file <path> --format compress
+```
+
+调用 `POST /smartapi/flow/update`。目标 id 只取自 `--id`，不信任文件内字段。服务端对已发布流程的修改限制原样作为远程错误返回。
+
+## publish
+
+```bash
+rabetbase flow publish --id <flow-id> --dry-run --format compress
+rabetbase flow publish --id <flow-id> --yes --format compress
+```
+
+调用 `POST /smartapi/flow/publish`，风险为 `high-risk-write`。`--dry-run` 不发请求；正式执行必须确认或显式 `--yes`。SmartCode 同步返回发布结果，成功响应即为该命令的完成口径。
+
+## 风险与完成口径
+
+| 命令 | 风险 | 完成口径 |
+|---|---|---|
+| `validate` | `read` | 本地 `data.valid=true` |
+| `list` / `detail` | `read` | 服务端查询成功；detail 写文件时还需本地原子写入成功 |
+| `create` / `update` | `write` | 服务端返回创建或更新后的定义 |
+| `publish` | `high-risk-write` | 服务端返回发布成功 |
+
+本地 `READY` 不等于远程成功。服务端拒绝 create、update 或 publish 时返回 `REMOTE_VALIDATION_FAILED`，不得把 dry-run 或本地校验结果描述为已发布。