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

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

@@ -1,8 +1,8 @@
 # api pull
 
-拉取当前 App 下所有数据集（Dataset）的元信息，刷新对应 SDK 路由配置，并在 `api.ts` / `client.ts` **缺失时**写入 Cookie-first 脚手架。默认应用使用 `src/api/sdk-config.ts`，非默认应用使用 `<name>-sdk-config.ts`。项目公开 Domain 路由由 [`project domain-routing-sync`](rabetbase-project-domain-routing-sync.md) 独立维护。
+拉取当前 App 下所有数据集（Dataset）的元信息并刷新 SDK 模型事实。单应用与显式配置同一 `apiGroup` 的多部署项目使用稳定的 `api.ts` / `client.ts`，CLI 将模型写入 `models.generated.ts`，由 `model-runtime.ts` 按最终 Runtime Domain 选择 profile。项目公开 Domain 路由由 [`project domain-routing-sync`](rabetbase-project-domain-routing-sync.md) 独立维护。
 
-已有 TypeScript 默认**不会被覆盖**。Agent 必须用返回的 `data.models` 按 [`sdk-client-generation.md`](../guides/sdk-client-generation.md) 更新 `api.ts` / `client.ts`。人类明确要放弃本地定制并重新生成完整脚手架时，可使用 `--force --yes`。
+`apiGroup` 只作为归并键，不进入文件名。第二套业务使用独立 `apiDir`，目录内仍是无前缀入口。同一目录中多个未配置 `apiGroup` 的历史 profile 继续使用 `[name-]api.ts` / `[name-]client.ts`。`api pull` 只刷新模型事实；已有应用的稳定入口迁移由 [`project upgrade`](rabetbase-project-upgrade.md) 负责。Agent 按 [`sdk-client-generation.md`](../guides/sdk-client-generation.md) 检查输出。
 
 ## 命令
 
@@ -13,8 +13,8 @@ rabetbase api pull --format compress
 # 指定输出目录
 rabetbase api pull --output ./src/generated/api/ --format compress
 
-# 放弃本地定制，按最新 Dataset 事实整体重建 TypeScript
-rabetbase api pull --force --yes --format compress
+# 确认远端清单确实为空，允许清空当前 profile
+rabetbase api pull --app oa-id --force --yes --format compress
 
 # 多应用：默认只解析「项目级」apps；与全局合并配置一起拉取时加 --global
 rabetbase api pull --global --format compress
@@ -22,6 +22,9 @@ rabetbase api pull --global --format compress
 # 多应用模式：指定某个应用
 rabetbase api pull --app order --format compress
 rabetbase api pull --appcode app-order-001 --format compress
+
+# 一个 AppCode 对应多个 profile 时必须按名称选择
+rabetbase api pull --app oa-id --format compress
 ```
 
 ## 参数
@@ -30,9 +33,9 @@ rabetbase api pull --appcode app-order-001 --format compress
 |------|------|
 | `--output <dir>` | 输出目录，默认 `./src/api/` |
 | `--global` | 多应用时显式从「全局+项目」双层解析 `apps`；默认仅项目级 `apps` |
-| `--force` | 整体替换已有 `api.ts` / `client.ts`；必须同时传 `--yes`，本地定制会丢失 |
+| `--force` | 注册表模式允许空结果替换当前 profile；历史前缀模式允许替换对应生成文件；必须同时传 `--yes` |
 | `--app <name>` | 多应用模式下，指定应用名称 |
-| `--appcode <code>` | 直接指定 appcode，跳过配置查找 |
+| `--appcode <code>` | 指定唯一 AppCode；匹配多个 profile 时必须改用 `--app` |
 | `--format compress\|json` | 结构化信封。Agent 应读 `data.models`，不要刮 stderr |
 
 ## 多应用过滤
@@ -40,7 +43,7 @@ rabetbase api pull --appcode app-order-001 --format compress
 多应用模式下：
 - **不加 `--app` / `--appcode`**：遍历已配置应用（默认仅 **项目** `.rabetbase.json` 中的 `apps`；若需包含全局里合并进来的应用，加 **`--global`**）
 - **加 `--app <name>`**：仅拉取指定应用
-- **加 `--appcode <code>`**：反查到对应 app profile 时，使用其 `region`、cookie 和 apiDir；没有匹配 profile 时使用顶层国家/地区回退
+- **加 `--appcode <code>`**：唯一匹配时使用该 profile 的 `region`、cookie 和 apiDir；同一 AppCode 匹配多个 profile 时拒绝猜测，改用 `--app <name>`
 - 每个应用请求前都会切换到其有效 `region`，不会沿用上一个应用的官方服务地址
 
 ## 配置作用域
@@ -53,13 +56,17 @@ rabetbase api pull --appcode app-order-001 --format compress
 
 | 文件 | 行为 |
 |------|------|
-| `sdk-config.ts` / `<prefix>-sdk-config.ts` | **每次刷新**。默认应用无前缀，非默认应用使用应用名前缀；只含必要的最终 `runtimeDomain`，不含凭证 |
-| `<prefix>-api.ts` | 文件缺失时写入脚手架（含当前 `models`）；已存在时默认跳过，`--force` 时整体替换 |
-| `<prefix>-client.ts` | 文件缺失时写入 Cookie-first `createClient`；已存在时默认跳过，`--force` 时整体替换 |
+| `models.generated.ts` | 注册表模式下**每次刷新当前 profile**并保留其他 profile；公共代码写 `datasetCode`，差异或部分可用代码写 `datasetCodes[profile]`，不含凭证 |
+| `model-runtime.ts` | 由 `project create` / `project upgrade` 维护；`api pull` 不改写 |
+| `api.ts` / `client.ts` | 由 `project create` / `project upgrade` 维护稳定结构；注册表模式的 `api pull` 不创建、不覆盖 |
+| `sdk-config.ts` / `<prefix>-sdk-config.ts` | 每次刷新，只含必要的最终 Runtime Domain，不含凭证；旧式多应用继续使用前缀文件 |
+| `<prefix>-api.ts` / `<prefix>-client.ts` | 同目录未显式分组的历史多应用结构；默认保留，仍可被命令侧别名解析读取 |
+
+注册表模式不使用国家/地区文件名前缀。业务代码始终 import `api.ts` / `client.ts`；页面加载时优先读取平台注入的 Runtime Domain，本地构建使用 `rabetbase.domain-routing.json`，据此物化该 profile 的 SDK `models` 数组。
 
-默认 `prefix` 为空（单应用或默认应用），多应用非 default 应用使用应用名作为 prefix；生成的 `<prefix>-client.ts` 导入同前缀 SDK 路由文件。
+同一 `apiGroup` + 同一规范化 `apiDir` 才进入同一注册表，组内 AppCode 可以相同或不同。相同 `apiGroup` 分散到不同目录、同一目录出现不同组、或显式分组与未分组混用都会在请求前报错。多个未分组 profile 共用目录时继续使用旧式具名入口；要共享模型必须显式配置同一个 `apiGroup`。
 
-`project create` 在拷贝空 demo 脚手架后会覆盖写入一次 TypeScript，以便带上真实 models。首次拉取失败时，恢复提示会要求执行 `rabetbase api pull --force --yes`，避免占位脚手架被继续保留。日常 `api pull` 遇到已有 `api.ts` / `client.ts` 时跳过，只刷新 `sdk-config.ts` 并返回 Dataset 事实。
+`project create` 直接生成注册表结构。旧项目先执行 `project upgrade --dry-run`，确认后执行 `project upgrade --yes`；标准旧脚手架会备份后迁移，业务定制入口会保留并生成候选文件。随后运行普通 pull 刷新事实。只拉取一个 profile 时会保留同组其他 profile 的模型代码。注册表已有非空 profile 而远端返回空清单时，普通 pull 会拒绝清空；仅在确认远端确实为空时使用 `--force --yes`。
 
 ## 输出（单应用 `data`）
 
@@ -70,9 +77,13 @@ rabetbase api pull --appcode app-order-001 --format compress
 | `isDefaultConfig` | 默认应用为 `true` |
 | `models[]` | `datasetCode` / `tableName` / `name` / `alias` |
 | `sdkRouting` | `{ runtimeDomain?: string }` |
-| `files.api` / `files.client` / `files.sdkConfig` | `{ path, action }`：`created` / `overwritten` / `preserved` / `refreshed` |
-| `needsAgentMerge` | 任一 TypeScript 被 `preserved` 时为 `true`；这是本地检查提示，不表示文件一定存在差异 |
-| `apiFilePath` / `clientFilePath` / `sdkConfigPath` | 与 `files.*.path` 相同 |
+| `files.api` / `files.client` / `files.sdkConfig` | `{ path, action }`：`created` / `overwritten` / `preserved` / `refreshed` / `missing` |
+| `files.modelRegistry` / `files.modelRuntime` | 注册表模式下的生成文件及动作 |
+| `needsAgentMerge` | 旧式 TypeScript 被保留且尚未使用注册表时为 `true` |
+| `needsProjectUpgrade` | 注册表事实已刷新，但稳定源码入口缺失或仍为旧结构时为 `true` |
+| `modelProfile` | 已刷新的 profile 名称；旧式输出可省略 |
+| `apiFilePath` / `clientFilePath` / `sdkConfigPath` | 稳定入口与 SDK 路由路径 |
+| `modelRegistryPath` / `modelRuntimePath` | 注册表模式下的模型事实与选择器路径 |
 | `modelCount` / `datasetCount` | 模型数量 |
 
 项目使用 `apps` 清单解析时，`data` 为 `{ apps, succeeded, failed }`，每个 `data.apps[]` 元素都使用上表结构。因此 Dataset 事实从直接单应用结果的 `data.models` 读取，或从项目应用清单结果的 `data.apps[].models` 读取；以实际信封为准。
@@ -83,13 +94,13 @@ rabetbase api pull --appcode app-order-001 --format compress
 
 ## 前置条件
 
-- 已完成 `rabetbase auth` 登录
+- 已完成 `rabetbase auth login`；不同官方节点的登录态不通用时，先对目标 profile 执行 `rabetbase auth login --app <name>`
 - 已配置 appcode（单应用或多应用）
 
 ## 示例
 
 ```bash
-# 单应用：刷新 sdk-config.ts；缺失则写 api.ts/client.ts
+# 单应用：刷新模型事实
 rabetbase api pull --format compress
 
 # 多应用 order
@@ -98,8 +109,8 @@ rabetbase api pull --app order --format compress
 # 独立输出目录
 rabetbase api pull --output ./src/generated/api/ --format compress
 
-# 仅在明确放弃本地 TypeScript 定制时整体重建
-rabetbase api pull --force --yes --format compress
+# 仅在确认目标 profile 的远端 Dataset 清单确实为空时
+rabetbase api pull --app oa-id --force --yes --format compress
 ```
 
 更新已有 TypeScript：见 [`sdk-client-generation.md`](../guides/sdk-client-generation.md)。

package/skills/rabetbase/references/rabetbase-app-list.md

@@ -2,7 +2,7 @@
 
 列出应用。
 
-默认列出**本地配置视图**，与 CLI 运行时一致：合并全局 `~/.rabetbase.json` 与从当前目录向父目录解析到的项目 `.rabetbase.json`。旧 `.lovrabet.json` / `.lovrabetrc` 不会自动参与配置发现。
+默认列出**本地配置视图**，与 CLI 运行时一致：合并全局 `~/.rabetbase.json` 与从当前目录向父目录解析到的项目 `.rabetbase.json`。Lovrabet 运行态配置 `.lovrabet.json` 以及 `.lovrabetrc` 不参与 Rabetbase 配置发现，也不会被修改。
 加 `--remote` 时改为查询**平台目录视图**：当前登录账号在平台上可访问的应用，不读取或修改本地 app 配置。
 
 - **不加 flag**：合并视图（global + project）。

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

@@ -6,7 +6,7 @@
 
 它**不是**平台应用目录。若要查看当前登录账号在平台上能访问哪些应用，应使用 `rabetbase app list --remote`，而不是直接查看 `.rabetbase.json`。
 
-只自动读取 `.rabetbase.json`，不会把 `.lovrabet.json` 或 `.lovrabetrc` 当作 Rabetbase 配置。旧文件需要迁移时，显式执行 `rabetbase project upgrade`。
+只自动读取 `.rabetbase.json`，不会把 `.lovrabet.json` 或 `.lovrabetrc` 当作 Rabetbase 配置。`.lovrabet.json` 属于 Lovrabet 运行态 CLI，可与 `.rabetbase.json` 在同一项目共存；Rabetbase 命令不会迁移、改写或删除它。
 
 ## 初始化
 
@@ -147,6 +147,7 @@ rabetbase workspace remove product --yes
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `appcode` | string | **必填**。该应用的 appcode |
+| `apiGroup` | string | 可选显式归并键。同一套业务 API 的多个部署使用相同值并共用一个 `apiDir`；普通单应用不配置 |
 | `region` | string | 覆盖顶层国家/地区；当前可写 `cn`、`id`。显式 `cn` 会保留，以便覆盖顶层 `id` |
 | `env` | string | 历史兼容字段；默认连接不落盘 |
 | `apiDir` | string | 覆盖顶层 `apiDir` |

package/skills/rabetbase/references/rabetbase-dataset-cross-relations.md

@@ -0,0 +1,60 @@
+# 跨库数据集关系
+
+使用 `dataset cross-relation-list/create/update/delete` 管理同一应用内、不同数据库连接的 DB_TABLE 逻辑关联。普通关系命令见 [数据集关系](rabetbase-dataset-relation-mutations.md)。跨库关系事实使用本页的 list 查询，不能用普通 `dataset relations` 或 `dataset detail` 的关系列表替代回读。
+
+## 定位和查询
+
+四个命令均支持 `--appcode` 覆盖当前应用、`--format json|compress`。参数使用真实 Dataset Code 和字段名，先用 `dataset detail` 确认端点字段。
+
+```sh
+rabetbase dataset cross-relation-list --from-datasetcode <source-code> --format json
+rabetbase dataset cross-relation-list --from-dblink-id <source-connection-id> --format json
+rabetbase dataset cross-relation-list --from-datasetcode <source-code> --from-column customer_id --format json
+```
+
+列表必须提供 `--from-datasetcode` 或 `--from-dblink-id`，可同时提供，但必须属于同一连接。提供数据集时自动解析源连接；只提供连接时列出该连接的所有出向跨库关系。`--from-column` 可进一步过滤源字段。
+
+列表输出 `data.appCode`、`data.selector`、`data.total`、`data.relations`。每条包含 `relationId`、`from/to.source`、`datasetCode`、`datasetName`、`dblinkId`、`table`、`field`；目标展示字段为 `to.labelField`，关系属性为 `relation.cardinality`、`relation.relationType`。缺失的 Dataset Code 或名称保留 null，不能根据同名表猜测。Relation ID 是返回事实，不是这些命令的输入参数。
+
+## 创建
+
+```sh
+rabetbase dataset cross-relation-create \
+  --from-datasetcode <source-code> --from-column customer_id \
+  --to-datasetcode <target-code> --to-column id \
+  --to-label-column name --cardinality MANY_TO_ONE --dry-run
+```
+
+两端数据集与字段必填。`--to-label-column` 可选，省略时默认目标关联字段；`--cardinality` 可选，省略时不设置。合法基数：`ONE_TO_ONE`、`ONE_TO_MANY`、`MANY_TO_ONE`、`MANY_TO_MANY`。
+
+完全相同的端点不可重复创建。同一源字段可以关联不同目标；需要在创建前理解下述更新、删除的唯一匹配要求。
+
+## 更新
+
+```sh
+rabetbase dataset cross-relation-update \
+  --from-datasetcode <source-code> --from-column customer_id \
+  --to-datasetcode <new-target-code> --to-column id \
+  --to-label-column name --dry-run
+```
+
+源数据集和源字段定位原关系，目标数据集和目标字段必填并表示更新后的目标。可选 `--from-dblink-id` 校验源连接归属。展示字段和基数省略时保留原值；更换目标数据集时应显式给出有效的 `--to-label-column`。无实际字段变化时返回错误，不当作更新成功。
+
+## 删除
+
+```sh
+rabetbase dataset cross-relation-delete \
+  --from-datasetcode <source-code> --from-column customer_id --dry-run
+```
+
+源数据集和源字段必填；可选 `--from-dblink-id`。删除属于高风险写入：先审阅预演，再按用户授权执行，非交互执行使用 `--yes`，且当前配置必须允许 high-risk-write；`--yes` 不会提高风险上限。
+
+更新和删除都要求源字段恰好匹配一条跨库关系。匹配多条时失败，结构化错误的 `data.candidates` 给出候选事实；不要选择第一条、循环删改，也不要追加 `--relation-id` 重试。先向用户说明该源字段当前无法由这组命令逐条维护。`--relation-id`、`--biz-relation-type` 和 `main_sub` 不属于本组命令。
+
+## 预演与确认
+
+所有写命令支持 `--dry-run`，只读取当前关系；输出 `operation`、`selector`、`before`、预计 `after`、`dryRun`、`backend`、`warnings` 和请求 body。预演不是实际写入，也不是并发锁。审阅后在用户授权范围内移除 `--dry-run` 执行。
+
+正式写入后通过跨库列表回读：创建核对完整端点和属性；更新核对原 Relation ID、更新后的端点和属性；删除核对原 ID 已消失。仅在 `verification.status=matched` 时报告写入已验证。
+
+网络中断会返回结果未确认；写入被接受但回读失败时返回 `verification.status=unconfirmed`。此时先运行 `cross-relation-list` 查询，不要自动重新创建、更新或删除。跨库关系管理完成不代表跨库 JOIN、页面绑定或跨库事务已经验证。

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

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 环境中验证，不能用设计态查询代替。