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

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-doctor.md

@@ -22,9 +22,9 @@ rabetbase doctor check
 | Built-in Skill | 目标路径、包版本、Skill 版本、内容状态；不一致时给出 `rabetbase cli-skill install` 修复命令 |
 | Config Files | 全局和项目级配置文件路径 |
 | Config JSON | 分别检测全局/项目配置文件是否为**合法 JSON**；非法时标红并给出解析错误（常见于尾随逗号、注释等，会导致该侧配置在合并时被忽略） |
-| Country/Region Configuration | 检查项目与全局 `region`；显式未知值会标明来源，并给出对应作用域的 `config delete region` 修复命令 |
+| Country/Region Configuration | 检查项目、全局和各 app profile 的 `region`；显式未知值会标明来源与修复位置 |
 | Merged Config | 合并后的所有配置项（appCode / env / cookie / apiDir 等） |
-| Apps | 多应用模式下的应用列表及各自配置 |
+| Apps | 多应用模式下的应用列表及各自显式或继承的 `region` |
 | API Endpoints | 最终生效的 region 与域名（user / api / runtime / skill / kb / app）；KB 管理与 search 共用 SmartCode Java origin |
 | Auth | 登录状态及 cookie 有效性 |
 

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 或本地校验结果描述为已发布。

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

@@ -0,0 +1,83 @@
+# 流程定义资源发现
+
+FlowConfig 中的真实标识必须来自 CLI 查询，不得由 Agent 猜测。
+
+## 映射
+
+| FlowConfig 字段 | 发现命令 | 选中值 |
+|---|---|---|
+| 外层 `datasetCode` | `dataset list`、`dataset detail` | Dataset `code` |
+| 外层 `pageId` | `menu list` | 与目标页面对应的 `pageId` |
+| `flowJson.startPageId` | `page custom-list`、`page custom-detail` | 自定义页面 `pageId` |
+| `APPROVAL.pageId` | `page custom-list`、`page custom-detail` | 自定义页面 `pageId` |
+| `APPROVAL.assignee.userIds` | `flow runtime-user-search` | 运行态 `users[].userId` |
+| `APPROVAL.assignee.roleId` | `flow runtime-role-list` | 运行态角色 `id` |
+| 角色成员核对 | `flow runtime-role-user-list` | 运行态只读成员清单 |
+| `transferCandidates.userIds` | `flow runtime-user-search` | 运行态 `users[].userId` |
+| `APPROVAL.cc.recipientUserIds` / `END.cc.recipientUserIds` | `flow runtime-user-search` | 运行态 `users[].userId` |
+| `SCRIPT.scriptName` | `bff list --type ENDPOINT` | Endpoint `functionName` |
+| `APPROVAL.timeout.scriptName` | `bff list --type ENDPOINT` | Endpoint `functionName` |
+| `NOTIFICATION.config.configCode` | `notification config-list --all` | `configs[].configCode` |
+| `NOTIFICATION.config.recipients[].value`（固定 USER） | `flow runtime-user-search` | 运行态 `users[].userId` |
+| `NOTIFICATION.config.recipients[].value`（固定 ROLE） | `flow runtime-role-list` | 运行态角色 `id` |
+
+`startPageId` 和节点 `pageId` 只选择自定义页面事实，不使用菜单名称、URL 或编辑器地址代替数值 `pageId`。占位符形式的通知收件人来自运行态变量，不需要资源查询；固定 EMAIL 收件人由用户明确提供，不推断邮箱地址。
+
+## 搜索运行态应用用户
+
+```bash
+rabetbase flow runtime-user-search --keyword <text> [--page <n>] [--page-size <n>] --format compress
+```
+
+- 只查询当前运行态应用已关联的用户，对 userId、nickname、username、displayName、email 做不区分大小写的包含匹配。
+- 输出 `scope: "runtime"`、安全字段 `userId`、`username`、`nickname`、`displayName`、`email`、`status` 和分页信息。
+- 不输出手机号、访问密钥或无关身份字段。
+- 多个候选时必须由用户确认；不要默认取第一项。
+
+不要用 `role`、`app members-list` 或 `tenant members-list` 的人员结果填写审批 FlowConfig。
+
+## 查询运行态角色
+
+```bash
+rabetbase flow runtime-role-list [--keyword <role-name>] [--page <n>] [--page-size <n>] --format compress
+```
+
+- 查询当前应用运行态 `env=RUNTIME` 角色，`--keyword` 由服务端按角色名模糊过滤。
+- 输出 `scope: "runtime"`、角色 `id/name/type`、备注和人数/权限数安全摘要，不输出权限矩阵。
+- `APPROVAL.assignee.roleId` 只能使用这里返回的运行态角色 ID；不要使用 `role list/detail` 的配置端角色 ID。
+
+## 查看运行态角色成员
+
+```bash
+rabetbase flow runtime-role-user-list --role <role-id-or-name> [--page <n>] [--page-size <n>] --format compress
+```
+
+- 在当前应用运行态角色成员分组中按 ID 或精确名称解析角色。
+- 角色名称不唯一时要求改用角色 ID。
+- 输出 `scope: "runtime"`；只读，不修改成员关系。
+
+## 查询通知配置
+
+```bash
+rabetbase notification config-list --all --format compress
+rabetbase notification config-list --type EMAIL --format compress
+```
+
+- `--all` 查询 `EMAIL`、`FEISHU`、`DINGTALK`、`WECOM`、`WEBHOOK` 的安全摘要。
+- `--all` 与 `--type` 互斥；未指定时继续默认查询 `EMAIL`。
+- 只使用同一条记录的 `configCode`，不要用渠道名、URL、dataset code 或凭据代替。
+
+## 查询脚本
+
+```bash
+rabetbase bff list --type ENDPOINT --name <keyword> --format compress
+```
+
+只把确认后的 Endpoint `functionName` 写入 `SCRIPT.scriptName` 或 `APPROVAL.timeout.scriptName`。COMMON、HOOK 或展示名称不能替代 Endpoint 函数名。
+
+## 确认规则
+
+- 无候选：返回 `NEEDS_USER_CONFIRMATION` 并请求更精确关键词。
+- 多候选：展示稳定 ID、名称和必要上下文，请用户选择。
+- 唯一候选：可以推荐，但身份、角色、脚本和通知配置仍需用户确认。
+- 当前 DSL 无法表达需求：返回 `NEEDS_DSL_EXTENSION`，不要伪造配置。

package/skills/rabetbase/references/rabetbase-flow-runtime-boundary.md

@@ -0,0 +1,25 @@
+# 流程定义设计态与运行态边界
+
+`rabetbase flow` 管理 SmartCode 中的表单审批流与独立工作流定义；运行态待办和任务办理不属于本仓 CLI。
+
+## rabetbase 负责
+
+- 查询、导出和校验 FlowConfig。
+- 创建或更新设计态流程定义。
+- 发布流程定义。
+- 通过 dataset、menu、BFF、notification 命令发现设计资源；通过 `flow runtime-user-search/runtime-role-list/runtime-role-user-list` 只读发现审批所需的运行态人员和角色。
+
+## Runtime CLI 负责
+
+- 查询当前用户待办和任务详情。
+- 审批、拒绝和转交已有运行态任务。
+- 验证流程实例、业务状态和任务权限。
+
+`rabetbase` 只调用已核实的运行态人员/角色只读接口来生成 FlowConfig，不查询或办理任务。需要办理待办时，显式交接到 Runtime CLI 仓库及其公开 Skill。
+
+## 完成口径
+
+- `flow validate` 成功只表示本地结构和已实现的拓扑规则通过。
+- `flow create/update` 成功只表示服务端保存了设计态定义。
+- `flow publish` 是同步服务端操作；只有成功响应才表示发布完成，dry-run 不表示发布成功。
+- Runtime 最终行为仍需在 Runtime 环境中验证，不能用设计态查询代替。

package/skills/rabetbase/references/rabetbase-instant-api-policy.md

@@ -12,29 +12,114 @@
 
 `init`、`pull`、`validate` 和 `publish` 只使用该路径，不提供 `--file`。目标应用来自当前工作区、`--app <name>` 或 `--appcode <code>`。策略不存入 `.rabetbase.json` 或运行态 app-config。
 
-`version` 固定为字符串 `"1"`，表示 JSON 结构版本。`revision` 是服务端发布历史版本，首次发布为 1，后续发布和回滚递增；两者含义不同。
+`version` 是 JSON 结构版本：`"1"` 保持精确匹配兼容，`"2"` 支持通配选择和排除项；新版 CLI 的 `init` 默认创建版本 2。`revision` 是服务端发布历史版本，首次发布为 1，后续发布和回滚递增；两者含义不同。
 
 ## 配置结构
 
+### 先取得真实 Dataset 选择器
+
+策略匹配的是平台 Dataset，不是前端 SDK 的变量名。编辑前按下面顺序取得当前应用的事实：
+
+```bash
+# 更新当前应用的本地模型事实；多应用项目显式选择目标
+rabetbase api pull --appcode <appCode> --yes --format compress
+
+# 对将被规则覆盖的 Dataset 确认真实 code、字段和支持的操作
+rabetbase dataset detail --appcode <appCode> --code <datasetCode> --format compress
+```
+
+`api pull` 生成的模型条目包含 `datasetCode`、可选 `tableName` 和 SDK `alias`。规则中优先只写这个 `datasetCode`；**不能**写 `alias`。例如模型中的 `alias: "brand"` 只是 SDK 调用名，不是策略选择器。只有无法取得 code 的兼容场景才使用 `tableName`；若两者同时填写，服务端要求它们解析为同一个 Dataset。
+
+认证不可用、`api pull` 失败或模型文件明显过期时，停止配置并先恢复认证；不要根据业务名称、SDK alias 或旧截图猜测 `datasetCode`。
+
+### Dataset 选择器规则
+
+| 场景 | 合法写法 | 约束 |
+| --- | --- | --- |
+| v1/v2 的精确 Dataset | `{ "datasetCode": "<real-dataset-code>" }` | 首选；code 来自当前应用的 `api pull` 或 `dataset detail` |
+| v1/v2 的精确物理表 | `{ "tableName": "<real-table-name>" }` | 可用作兼容选择器；不能填 SDK alias |
+| v1/v2 双字段精确选择 | `{ "datasetCode": "…", "tableName": "…" }` | 两值必须解析为同一个 Dataset；已知 code 时不要冗余填写 tableName |
+| 仅 v2 的全部 Dataset | `{ "datasetCode": "*" }` | `datasets` 的唯一元素；不能附带 `tableName`，也不能与精确选择器混用 |
+
+`{ "tableName": "*" }` 在任何版本都不支持。版本 1 只接受上面的精确选择器，不能使用 Dataset/API 通配或 `excludes`。
+
+### 顶层字段
+
+| 字段 | 必填 | 取值 / 约束 | 作用 |
+| --- | --- | --- | --- |
+| `version` | 是 | `"1"` 或 `"2"`；新文件使用 `"2"` | JSON 结构版本，不是服务端发布 revision |
+| `appCode` | 是 | 必须等于当前命令解析出的应用 | 防止跨应用误发布 |
+| `defaults.instantApi` | 是 | `"allow"` 或 `"deny"` | 没有任何规则命中时的最终动作；不能是 `"route"` |
+| `rules` | 否 | 规则数组；缺省或空数组表示全部使用默认动作 | 对特定 Dataset + API 组合覆盖默认动作 |
+
+### 规则字段
+
+| 字段 | 必填 | 取值 / 约束 |
+| --- | --- | --- |
+| `name` | 是 | 稳定、可读的规则标识，方便审阅和版本回溯 |
+| `description` | 否 | 说明规则的业务目的和影响范围 |
+| `datasets` | 是 | 非空数组；每项优先仅 `{ "datasetCode": "<real-dataset-code>" }` |
+| `apis` | 是 | 非空数组，每项是独立 API 名；不能把多个 API 拼为一个逗号字符串 |
+| `action` | 是 | `"allow"`、`"deny"` 或 `"route"` |
+| `backendFunction` | 条件必填 | 仅 `action: "route"` 时填写；必须是同一应用的普通 `ENDPOINT`，不能是 Personal Backend Function |
+| `excludes` | 仅 v2 可用 | 从本规则的 Dataset × API 匹配集合中扣除的数组；每项都要有 `datasets` 和 `apis`，且不得超出父规则范围 |
+
+支持的 API 名称为：`getSelectOptions`、`getList`、`excelExport`、`filter`、`aggregate`、`getOne`、`getOneOrigin`、`create`、`batchCreate`、`update`、`delete`。
+
+规则数组**没有优先级**。服务端会先按每条规则的 Dataset × API 组合（扣除 `excludes` 后）计算覆盖范围；仍有重叠就校验失败，而不是“后一条覆盖前一条”。未被任何规则覆盖的组合回退到 `defaults.instantApi`。
+
+### 精确匹配示例
+
+下面的 `<real-dataset-code>` 必须替换为刚由 `api pull` 得到的 code，不能替换成 alias 或展示名称：
+
+```json
+{
+  "version": "2",
+  "appCode": "app-example",
+  "defaults": { "instantApi": "allow" },
+  "rules": [
+    {
+      "name": "deny-sensitive-export",
+      "description": "禁止敏感数据集通过 Instant API 导出",
+      "datasets": [{ "datasetCode": "<real-dataset-code>" }],
+      "apis": ["excelExport"],
+      "action": "deny"
+    }
+  ]
+}
+```
+
+这是默认放行下的最小收紧方式：仅该 Dataset 的 `excelExport` 被禁止，其他组合继续由默认动作处理。
+
+### 版本 2 通配与排除示例
+
 ```json
 {
-  "version": "1",
+  "version": "2",
   "appCode": "app-example",
   "defaults": {
     "instantApi": "allow"
   },
   "rules": [
     {
-      "name": "route-student-filter",
-      "description": "学生筛选交给业务 Backend Function",
-      "datasets": [
+      "name": "route-all-except-student-create",
+      "description": "除学生新增外，全部数据集操作交给统一 Backend Function",
+      "datasets": [{"datasetCode": "*"}],
+      "apis": ["*"],
+      "excludes": [
         {
-          "datasetCode": "student23"
+          "datasets": [{"datasetCode": "student23"}],
+          "apis": ["create"]
         }
       ],
-      "apis": ["filter"],
       "action": "route",
-      "backendFunction": "filterStudents"
+      "backendFunction": "unifiedGateway"
+    },
+    {
+      "name": "allow-student-create",
+      "datasets": [{"datasetCode": "student23"}],
+      "apis": ["create"],
+      "action": "allow"
     }
   ]
 }
@@ -43,8 +128,13 @@
 - `defaults.instantApi` 只允许 `allow` 或 `deny`，不能是 `route`。
 - `rules[].action` 允许 `allow`、`deny`、`route`。
 - `route` 必须填写 `backendFunction`；其他 action 禁止填写。
-- `datasets[]` 至少填写 `datasetCode` 或 `tableName`；建议优先使用稳定的 `datasetCode`。两者同时填写时必须指向同一 Dataset。
-- 同一个 `datasetCode + api` 只能命中一条规则；重复覆盖会校验失败。
+- `datasets[]` 至少填写 `datasetCode` 或 `tableName`；已知 code 时只填写稳定的 `datasetCode`。两者同时填写时必须指向同一 Dataset。
+- 版本 1 只支持精确匹配，不允许 `*` 或 `excludes`。
+- 版本 2 的全部数据集写为 `datasets: [{"datasetCode":"*"}]`。通配项必须是数组唯一元素且不能包含 `tableName`；不支持 `tableName: "*"`。
+- 版本 2 的全部 API 写为 `apis: ["*"]`，`"*"` 必须是数组唯一元素。
+- `excludes[]` 每项包含 `datasets` 和 `apis`，表示从父规则中扣除两者笛卡尔积；排除范围不能超出父规则。
+- 被排除的组合可以由后续其他规则处理；没有其他规则时执行 `defaults.instantApi`。
+- 排除后仍重复的 `datasetCode + api` 会校验失败，规则数组顺序不表示优先级。
 - `apis` 的每个元素是一个独立值。`["filter,create"]` 或包含中文逗号的 `["filter，create"]` 都不是两个 API。
 - 支持的 API：`getSelectOptions`、`getList`、`excelExport`、`filter`、`aggregate`、`getOne`、`getOneOrigin`、`create`、`batchCreate`、`update`、`delete`。
 
@@ -70,7 +160,7 @@ rabetbase instant-api-policy publish --expected-revision 0 --change-summary "ini
 rabetbase instant-api-policy publish --expected-revision 0 --change-summary "initial policy" --yes --format compress
 ```
 
-`init --default-action deny` 可以创建默认禁止草稿。`init` 和 `pull` 遇到不同的既有文件时停止；只有 `--force --yes` 可以替换。
+`init --default-action deny` 可以创建版本 2 的默认禁止草稿。`init` 和 `pull` 遇到不同的既有文件时停止；只有 `--force --yes` 可以替换。已有版本 1 文件仍可继续校验和发布。
 
 `validate` 调用服务端完整校验，返回 `configHash` 和 `normalizedConfig`，但不发布、不生成 revision。Dataset、API、规则重叠以及 Backend Function 合法性以该结果为准。
 
@@ -90,3 +180,5 @@ rabetbase instant-api-policy rollback --revision 2 --expected-revision 5 --chang
 回滚不会把 revision 倒退，也不会覆盖历史。例如当前 revision 为 5，恢复 revision 2 后会生成新的 revision 6。
 
 发布和回滚最多提交一次。CLI 随后读取当前策略，要求 configHash 匹配且 revision 推进。响应丢失但回读可以证明结果时返回 verified；证据不足时停止并提示执行 `current`，不得自动重提。Runtime 最迟约 30 秒感知新策略。
+
+数据集通配项按应用当前有效数据集展开；应用新增数据集后，会在 Runtime 策略缓存刷新时自动进入通配规则范围。

package/skills/rabetbase/references/rabetbase-notification-config-list.md

@@ -7,6 +7,7 @@
 ```bash
 rabetbase notification config-list --format compress
 rabetbase notification config-list --type EMAIL --format compress
+rabetbase notification config-list --all --format compress
 rabetbase notification config-list --type EMAIL --appcode app-xxxxx --format json
 ```
 
@@ -20,6 +21,8 @@ rabetbase notification config-list --type EMAIL --appcode app-xxxxx --format jso
 
 类型值使用大写。
 
+`--all` 会分别查询 `EMAIL`、`FEISHU`、`DINGTALK`、`WECOM`、`WEBHOOK`，合并为同一份安全摘要。`--all` 与 `--type` 互斥；不传二者时继续保持默认 `EMAIL` 行为。
+
 ## 输出
 
 ```json
@@ -45,6 +48,20 @@ rabetbase notification config-list --type EMAIL --appcode app-xxxxx --format jso
 }
 ```
 
+`--all` 输出使用 `data.channelTypes` 代替单个 `data.channelType`，`configs` 为五种类型结果的合并列表：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "appCode": "app-xxxxx",
+    "channelTypes": ["EMAIL", "FEISHU", "DINGTALK", "WECOM", "WEBHOOK"],
+    "count": 2,
+    "configs": []
+  }
+}
+```
+
 CLI 只输出用于选择配置的安全字段，不输出：
 
 * `channelConfig`

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

@@ -31,7 +31,11 @@ rabetbase page push --id 1020286 --dry-run --format json
 ## 行为说明
 
 - 单页模式：校验本地文件、读取 lock、比对远端版本，再调用更新接口
-- 批量模式：只推送本地 hash 有变更的页面；无基线时会 fail-fast，提示先执行 `page pull`
+- 批量模式：先完成远端版本检查与 `LrSmartJsx` 编译准备，再只推送结果 hash 与 lock 不同的页面；无基线时会 fail-fast，提示先执行 `page pull`
+- 遇到 `LrSmartJsx` 时，以 `props.render.source` 为唯一手工维护内容；源码变化、`render.value` 缺失或远端无编译值时，CLI 调用平台正式编译器生成 `value`
+- CLI 会把 `LrSmartJsx.props._context` 规范为 `{ "type": "JSExpression", "value": "this" }`；`source` 组件仍通过 `props.env` / `props.sdkClient` 消费平台注入能力
+- `--dry-run` 同样执行编译校验，但不会更新页面；任一组件编译失败时整页不提交
+- 不要手写或直接修改 `render.value`；当 `source` 未变化但本地 `value` 与远端不一致时，命令会拒绝推送并提示修改 `source`
 - 推送后会再次拉取远端 canonical schema，并覆盖本地文件和 lock，避免本地保留非 canonical 版本
 
 ## 提示

package/skills/rabetbase/references/rabetbase-workspace.md

@@ -9,7 +9,7 @@
 ## 命令
 
 ```bash
-rabetbase workspace init --appcode <code> [--env daily|production]
+rabetbase workspace init --appcode <code> [--region cn|id]
 rabetbase workspace init --app <name> --appcode <code>
 rabetbase workspace use --app <name>
 rabetbase workspace use --app <name> --appcode <code>
@@ -23,7 +23,8 @@ rabetbase workspace remove <name> [--global]
 |------|------|
 | `--app <name>` | 工作空间里的应用名，如 `crm`、`order` |
 | `--appcode <code>` | 应用 App Code；不知道本地应用名时可直接使用 |
-| `--env <env>` | 写入该 app profile 的环境：`daily` / `production` |
+| `--region <region>` | 写入该 app profile 的国家/地区：`cn` / `id` |
+| `--env <env>` | 历史兼容参数；默认内部路由值不会写入 app profile |
 | `--apiDir <dir>` | 写入该 app profile 的 API 目录 |
 | `--defaultFormat <format>` | 写入该 app profile 的默认输出格式 |
 | `--pageSize <n>` | 写入该 app profile 的分页大小 |
@@ -39,6 +40,7 @@ rabetbase workspace remove <name> [--global]
 - `workspace use --app crm`：切换当前目录默认应用；如果 `crm` 只存在于全局配置，会复制非敏感 profile 字段到当前目录。
 - `workspace use --app crm --appcode app-xxx`：直接在当前目录新增或更新 `crm`，并设为默认应用。
 - `workspace add crm --appcode app-xxx`：登记应用 profile（默认写当前项目，`--global` 写全局）。第一个应用不写 `defaultApp`；增加第二个应用时保留原应用为默认。已存在则更新。
+- `region` 省略时继承项目顶层、再继承全局回退；显式传 `--region cn` 或 `--region id` 时只作用于该应用。
 - `workspace remove crm`：移除本地应用 profile。默认按「项目优先、其次全局」定位要删的那一层，`--global` 强制删全局；只剩一个应用时删除冗余的 `defaultApp`，仍有多个应用时才自动切换；若该应用在项目与全局都有定义，只删单侧并在结果里提示另一侧仍存在。
 
 `workspace init` / `workspace use` 不会从全局配置复制 `cookie` / `accessKey` 到项目文件。若当前项目文件里原本已有这些字段，更新应用时会保留它们。

package/skills/rabetbase.manifest.json

@@ -2,10 +2,11 @@
   "schemaVersion": 1,
   "name": "rabetbase",
   "packageName": "@lovrabet/rabetbase-cli",
-  "packageVersion": "2.5.2",
-  "skillVersion": "2.5.2",
+  "packageVersion": "2.5.3-beta.2",
+  "skillVersion": "2.5.3-beta.2",
   "files": [
     "SKILL.md",
+    "guides/approval-flow-development-workflow.md",
     "guides/backend-function.md",
     "guides/best-practices.md",
     "guides/bff-creation-workflow.md",
@@ -22,6 +23,7 @@
     "guides/sql-mybatis.md",
     "guides/troubleshooting.md",
     "guides/typescript-sdk.md",
+    "knowledge/approval-flow/config-json-schema.md",
     "knowledge/components.md",
     "knowledge/custom-page/generation-standards.md",
     "knowledge/custom-page/page-templates.md",
@@ -46,6 +48,7 @@
     "references/rabetbase-bff-delete.md",
     "references/rabetbase-bff-detail.md",
     "references/rabetbase-bff-list.md",
+    "references/rabetbase-bff-logs.md",
     "references/rabetbase-bff-pull.md",
     "references/rabetbase-bff-push.md",
     "references/rabetbase-bff-save.md",
@@ -85,6 +88,9 @@
     "references/rabetbase-deployment-sync-all.md",
     "references/rabetbase-doctor.md",
     "references/rabetbase-file.md",
+    "references/rabetbase-flow-commands.md",
+    "references/rabetbase-flow-resources.md",
+    "references/rabetbase-flow-runtime-boundary.md",
     "references/rabetbase-init.md",
     "references/rabetbase-instant-api-policy.md",
     "references/rabetbase-issue-report.md",
@@ -140,5 +146,5 @@
     "references/rabetbase-user-account.md",
     "references/rabetbase-workspace.md"
   ],
-  "digest": "85bd9afc1c6af3d817dd6a6317e0c1cee9fce3e1df76904165e79d5e6a9e63a1"
+  "digest": "bdb1237d11f707a54a1a189d00c313b8cf7f4ac4f41e9ec7d2aec7e187edbaa9"
 }

package/templates/generate-api/client.ts.tpl

@@ -9,7 +9,7 @@
 
 import { createClient, CONFIG_NAMES } from "@lovrabet/sdk";
 import "./{ApiFileName}"; // 导入配置文件，执行 registerModels() 注册
-import { LOVRABET_SDK_CONFIG } from "./sdk-config";
+import { LOVRABET_SDK_CONFIG } from "./{SdkConfigFileName}";
 
 /**
  * 主要的客户端实例