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

package/skills/rabetbase/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rabetbase
-version: 2.5.3-beta.2
+version: 2.5.3-beta.4
 description: "Use for Lovrabet development work through the rabetbase CLI: create or bind projects (including creating an AppCode project in the current folder), pull Dataset/API facts and maintain SDK clients, or manage datasets, Instant API access policies, database connections, pages, SQL, Backend Functions, menus, notifications, knowledge bases and kb search, Agent Context Rules, roles, files, OCR, deployment metadata, platform issues, and 钉钉沙箱账号绑定. Trigger when the user mentions rabetbase, Lovrabet development, AppCode, Dataset, Instant API allow/deny/route policy, project creation, api pull/codegen, dblink, page, SQL, BFF, menu, notification, knowledge base, kb search, Agent Context Rules, RULES.md, DATABASE.md, rule list/get/set, role, file/OCR, or related development workflows."
 metadata:
   requires:
@@ -19,7 +19,7 @@ metadata:
 ## 前置条件
 
 1. **连接配置与认证分离**：首次使用先执行 `rabetbase config init`。交互模式选择当前已开放国家/地区；非交互模式显式传 `--region`，未传时使用默认节点。企业独立部署优先导入 `lovrabet-routing/v1` 清单，也兼容旧扁平 Domain 文件和对应 `--*-domain` flags。`config init` 默认重建当前项目节点/Domain 配置，显式 `--global` 时写全局；保留 Cookie、AccessKey、format、locale 和应用绑定，但不登录、不绑定项目，随后再执行 `rabetbase auth login`
-2. **AppCode**：确保 `.rabetbase.json` 中设置了 `apps`（单应用自动选中；多应用再配 `defaultApp`），或兼容读取的顶层 `appcode`，或通过 `--appcode <code>` / `--app <name>` 传入。旧 `.lovrabet.json` 不会自动读取
+2. **AppCode**：确保 `.rabetbase.json` 中设置了 `apps`（单应用自动选中；多应用再配 `defaultApp`），或兼容读取的顶层 `appcode`，或通过 `--appcode <code>` / `--app <name>` 传入。`.lovrabet.json` 属于 Lovrabet 运行态 CLI；Rabetbase 不读取也不修改它，两份配置可在同一项目共存
 3. **配置文件**：`rabetbase config init` 默认写当前项目 `.rabetbase.json`，显式 `--global` 时写 `~/.rabetbase.json`；默认节点不落冗余 `region`。官方节点模式清理显式和遗留 Domain，独立部署模式清理旧 `region`/Domain 后写入路由配置。完整字段说明见 [`.rabetbase.json` 配置参考](references/rabetbase-config.md)。当前目录应用绑定使用下方 `workspace init`
 4. **工作目录应用绑定**：当前目录要固定使用某个应用时，使用 `rabetbase workspace init --appcode <code>` 或 `rabetbase workspace use --app <name>`（选型见「app vs workspace 职责边界」）
 5. **多应用场景**：一个项目有多个应用时，先 `rabetbase workspace add <name> --appcode … [--region cn|id]` 登记各应用；profile 的 `region` 高于顶层国家/地区回退值。再用 `--app <name>` 临时切换，或 `workspace use --app <name>` 修改当前工作目录默认应用
@@ -45,14 +45,15 @@ metadata:
    - 表单审批流或独立工作流定义 → 先读 [`approval-flow-development-workflow.md`](guides/approval-flow-development-workflow.md)，先确定 `flowType`，再使用 `flow validate/create/update/publish`
    - Instant API 标准数据记录操作 → SDK filter/getOne/create/batchCreate/update/delete；批量更新使用 `update({ id: [...] })`，不存在 `batchUpdate()`
    - 简单聚合且数据集是 DB_TABLE → SDK aggregate；聚合列用 `aggregate[].column`，不要用旧别名 `field`
-   - 复杂 JOIN / 数据库函数且数据集是 DB_TABLE → Custom SQL
+   - 同库 DB_TABLE 的复杂 JOIN / 数据库函数 → 评估 Custom SQL；跨库查询 → 按 [跨库 BFF 指南](guides/cross-database-bff.md)分别读取并拼接
    - 图表、统计卡片或数据大屏 → 自定义页面 + ECharts；数据层根据查询复杂度选择 Dataset 或 Custom SQL
    - 当前用户、角色、数据范围、外部系统、跨表事务或复杂业务编排 → Backend Function；Backend Function HOOK 可挂 DB_TABLE 或 METADATA，具体 operation 以后端返回为准
 2. **先拿元数据，再写代码**
    - 至少先查 `rabetbase dataset detail --code xxx --format compress`（或 `json`）获取表结构
    - 跨表场景还需查目标表的结构
    - 写入前用 `data.fields[]` 确认真实字段、必填字段、枚举选项；枚举/选择字段写入 `options[].value`，不是展示 `label`
-   - 需要了解数据集关联关系时用 `rabetbase dataset relations --format compress`（或 `json`）；需要审计关系事实错误和人工复核项时用 `rabetbase dataset relation-audit --format compress`
+   - 默认关联关系指同库关联关系；同库／跨库按平台数据库连接区分，执行时核对真实连接信息。同库关系用 `rabetbase dataset relations --format compress`（或 `json`）查询，用 `rabetbase dataset relation-audit --format compress` 审计关系事实错误和人工复核项
+   - 需要管理不同数据库连接之间的 DB_TABLE 关联时，先读 [跨库关系](references/rabetbase-dataset-cross-relations.md)，使用 `dataset cross-relation-list/create/update/delete`；源数据集＋字段定位，更新/删除必须唯一匹配，写前 dry-run，写后以跨库 list 回读为准
    - 需要从文本需求创建新的 `METADATA` 数据集时，先读 [`dataset generate-start/status`](references/rabetbase-dataset-generate.md)，执行 preview 写出 design 文件，审阅后用 `generate-start --apply --design-file` 提交任务，再用 `generate-status` 查询到成功
    - **管理物理库连接 / 测连 / 同步表结构分析**时用 `rabetbase db …`（先 [`db list`](references/rabetbase-db-list.md)，trace/plan id 见 [`database-connection-workflow.md`](guides/database-connection-workflow.md)）
    - 研发资源保存后的增量同步由服务端自动处理；仅在管理员明确要求首次初始化、历史回填或故障恢复时读 [`deployment sync-all`](references/rabetbase-deployment-sync-all.md)，在停止编辑的安静窗口执行；提交成功后按 jobId 查询状态，提交结果未知时用 `sync-jobs` 恢复任务事实
@@ -62,13 +63,14 @@ metadata:
    - 全部批次结束后再次执行异步差异刷新并重新获取完整差异；仍未收敛时，按 [`database-connection-workflow.md`](guides/database-connection-workflow.md) 对剩余 `toAnalyzeTables` 逐表串行重试且每表只恢复一次。仅当用户明确要求跳过分析/刷新时直接读取现有差异。状态查询失败继续使用原 `planId`，不得重复启动任务
    - 输出很大且只需子集时，在 `compress`/`json` 上加 `--jq '.data…'` 缩小结果
    - 需要真实业务行数据时必须交接给 `lovrabet data filter/getOne`；`lovrabet` 不可用时报告阻断并提示安装 Skill 与 CLI，不要静默安装或修复，也不要用 `rabetbase sql exec` 当行数据替代，见 [`guides/data-api-guidelines.md`](guides/data-api-guidelines.md)
-   - 需要 `src/api/api.ts` / `client.ts` 时：先 `rabetbase api pull --format compress` 取 `data.models`、`data.files`、`data.needsAgentMerge`，再按 [`sdk-client-generation.md`](guides/sdk-client-generation.md) 更新 TypeScript。`api pull` 默认**不会覆盖已有** `api.ts`/`client.ts`；只有用户明确要求放弃本地定制并完整重建时才使用 `--force --yes`
+   - 需要 `src/api/api.ts` / `client.ts` 时：已有项目先执行 `rabetbase project upgrade --dry-run`，确认计划后执行 `rabetbase project upgrade --yes`；再运行 `rabetbase api pull --format compress` 刷新模型事实。按 [`sdk-client-generation.md`](guides/sdk-client-generation.md) 检查 `data.files`、`data.needsProjectUpgrade` 与模型注册表；注册表源码迁移仅使用 `project upgrade`
    - 需要按 Dataset + API 配置 Instant API 的 `allow`、`deny` 或 `route` 时，先读取 [`rabetbase-instant-api-policy.md`](references/rabetbase-instant-api-policy.md)。先执行 `api pull` 更新模型事实，从生成的 `models[].datasetCode` 取得精确选择器；**不得**把 SDK `alias` 当作 `datasetCode`。精确 Dataset 选择器在 v1/v2 都可写 `{ datasetCode: "<real-dataset-code>" }` 或 `{ tableName: "<real-table-name>" }`；两者同时写时必须指向同一 Dataset，已有 code 时优先只写 `datasetCode`。再用 `dataset detail --code <datasetCode>` 确认目标操作存在，只编辑固定 `policy.json`。仅版本 2 可以使用通配：全部 Dataset 固定写作 `datasets: [{"datasetCode":"*"}]`，全部 API 固定写作 `apis: ["*"]`；每种通配都必须是其数组的唯一元素，`tableName: "*"` 不支持，也不得与 Dataset 通配混用。需要从通配规则中豁免组合时，用 `excludes: [{ datasets: [{ datasetCode: "<real-dataset-code>" }], apis: ["<api>"] }]`，豁免项会回退到其他非重叠规则或 `defaults.instantApi`。版本 1 禁止 `*` 与 `excludes`。随后依次执行 `validate`、`publish --dry-run`，经人工确认后再正式发布。认证不可用时报告阻断，不得猜测或复用过期的 Dataset 信息
 3. **SQL 工作流严格分步**
    - 推荐路径：查现有(`sql list/detail`) 或新建(`sql create`) → 拉/落本地(`sql pull` / `sql create`) → 编辑同步目录文件 → 可选校验(`sql validate`) → 检查状态(`sql status`) → 先预览(`sql push --dry-run` / `sql delete --dry-run`) → 再 `sql push` / `sql delete` → `sql detail` / `sql exec` 验证
    - 先使用 `sql list/detail` 查找可复用的 Custom SQL；没有满足需求的资源时，按照 [`sql-creation-workflow.md`](guides/sql-creation-workflow.md) 与 [`sql-mybatis.md`](guides/sql-mybatis.md) 创建、校验、发布并验证
    - 页面执行已发布的 Custom SQL 时使用 `sqlCode` + `params`；Backend Function 默认使用 `context.client.sql.byName(sqlName).execute({ params })`，`sql.execute({ sqlCode, params })` 仅作兼容路径
 4. **Backend Function 工作流严格分步**
+   - 跨数据库连接的业务查询、关联筛选或聚合，先读 [跨库 BFF 查询与拼接](guides/cross-database-bff.md)，确认完整键、执行顺序、各端授权和结果完整性
    - 查现有 → 确认字段或通知配置 → 查公共函数 → 本地创建(`bff create`) → 检查状态(`bff status`) → 先预览(`--dry-run`) → 再拉取/推送/删除；运行行为异常时用 `bff logs` 按时间、级别和关键字查询日志
    - `bff pull` / `bff push` 返回 `data.conflicts` 时，逐项报告 `lockKey` 和 `code`，并只在审阅后执行该项 `nextAction`；不得把同步冲突说成失败、自动使用 `--force`，或盲目重试整批脚本
    - 创建会发送消息通知的 Backend Function 时，先读取 [`backend-function.md`](guides/backend-function.md) 的“消息通知扩展”契约，再执行 [`rabetbase notification config-list --type EMAIL`](references/rabetbase-notification-config-list.md) 获取当前应用的 `configCode`；不得猜测渠道、收件人或把密钥写进脚本
@@ -176,7 +178,8 @@ metadata:
 - **不要**在用户未要求时给命令加 `--global`** — 默认行为已是「项目优先」；只有用户明确要改全局配置或不在项目内且意图写全局时才使用。
 - **`config set`**：在**没有**项目配置文件（当前目录未解析到 `.rabetbase.json`）且**未**传 `--global` 时，CLI **拒绝执行**并提示使用 `--global` 或先 `rabetbase workspace init --appcode <code>`，**不会**静默写入全局。
 - **`project create`** 生成的新项目 `.rabetbase.json` **只继承**少量全局偏好（如 `cookie` / `locale` / `format` / `riskLevel` 等），**不会**把全局 `apps` / `defaultApp` 带入新项目文件；同时生成浏览器安全的 `src/api/sdk-config.ts` 与 `rabetbase.domain-routing.json`。每个官方节点直接声明自己的第三方库 CDN 与 Lovrabet 自有资源 Domain；项目文件始终包含解析后的完整地址，企业独立部署从共用清单读取显式 CDN。两个生成文件都不下发认证配置；`rabetbase run start|dev|build|preview` 会在执行脚本前刷新公开 Domain 快照，也可用 `project domain-routing-sync` 立即显式刷新；`api pull` 只刷新 SDK/API 文件。
-- **`api pull` / `api list`**：默认仅针对**项目** `apps`；需要合并全局已登记应用时加 `--global`。多应用遍历会在每个请求前应用该 profile 的有效 `region`；`api pull` 为非默认应用生成独立 `<name>-sdk-config.ts`（见各命令 reference）。
+- **`api pull` / `api list`**：默认仅针对**项目** `apps`；需要合并全局已登记应用时加 `--global`。多应用遍历会在每个请求前应用该 profile 的有效 `region`。一个 AppCode 匹配多个 profile 时必须用 `--app <profile>` 消除歧义；只有显式相同 `apiGroup` 且使用同一 `apiDir` 的 profile 才共享生成注册表（见各命令 reference）。
+- **多 profile SDK 的运行边界**：共享注册表只解决“同一份业务代码分别运行在不同节点，并按当前 Runtime Domain 选择唯一 profile”；它不是跨节点网关，也不允许浏览器 client 在一次运行中同时读取多个节点。业务代码只使用 alias，不硬编码或跨 profile 取 `datasetCode`。确需跨节点聚合时，交给可信服务端或 Backend Function 编排；完整约束见 [`sdk-client-generation.md`](guides/sdk-client-generation.md) 与 [`typescript-sdk.md`](guides/typescript-sdk.md)。
 - **`app list`**：默认展示**合并**后的全量；`--global` 仅全局、`--project` 仅项目（见 [`rabetbase app list`](references/rabetbase-app-list.md)）。
 
 ## app vs workspace 职责边界
@@ -224,6 +227,7 @@ metadata:
 - **不要跳过 Dataset rename 最终线上回查** — 连续重命名后必须按 code 重新查询线上名称，不能只相信本地 plan 或 dry-run
 - **不要把 MCP 工具名当 CLI 命令** — 使用 `rabetbase sql list`，不是 `list_sql_queries`
 - **不要擅自加 `--global`** — 见上文「配置作用域原则」；默认写项目、读合并；仅在用户明确要求或文档说明的场景使用 `--global`。
+- **不要迁移或删除 Lovrabet 运行态配置** — `.lovrabet.json`、`.lovrabet/` 与 Lovrabet Skill 不属于 Rabetbase 项目升级范围；即使它们与 `.rabetbase.json` 同时存在也必须保留
 - **不要为 Instant API Policy 传任意文件路径或写入 app-config** — 策略只使用 `.rabetbase/instant-api-policy/<appCode>/policy.json` 与独立策略接口；发布和回滚前必须校验并预览。
 
 ## 接口选型优先级
@@ -232,7 +236,7 @@ metadata:
 
 1. **标准 SDK 接口**（filter/getOne/create 等）— 能用就不写 SQL
 2. **aggregate 聚合接口** — DB_TABLE 的简单分组汇总；METADATA 不默认支持 aggregate；聚合定义使用 `column` 指定列，`field` 仅作为历史兼容别名
-3. **自定义 SQL** — DB_TABLE 的复杂 JOIN、数据库函数、跨表统计；METADATA 不支持 SQL 路径
+3. **自定义 SQL** — 同库 DB_TABLE 的复杂 JOIN、数据库函数、跨表统计；跨库查询由 Backend Function 分别读取并拼接，METADATA 不支持 SQL 路径
 4. **Backend Function** — 外部系统调用、跨表事务、复杂业务编排
 
 ## SDK 核心规则
@@ -316,7 +320,7 @@ const result = await client.bff.execute<DashboardData>({
 | 初始化连接配置 | [`rabetbase config init`](references/rabetbase-init.md) | 选择官方节点或导入独立部署 Domain |
 | 创建新项目 | [`rabetbase project create`](references/rabetbase-project-create.md) | 支持新目录或当前空目录创建；完成口径与安全边界见 reference |
 | 刷新项目公开 Domain 路由 | [`rabetbase project domain-routing-sync`](references/rabetbase-project-domain-routing-sync.md) | 根据当前有效配置原子生成项目级 `rabetbase.domain-routing.json`；与前端页面路由无关 |
-| 从 lovrabet-cli 迁移 | [`rabetbase project upgrade`](references/rabetbase-project-upgrade.md) | 6 步自动迁移，`--yes` 跳过确认 |
+| 升级已有项目依赖与源码架构 | [`rabetbase project upgrade`](references/rabetbase-project-upgrade.md) | 先 `--dry-run`，标准旧脚手架自动备份迁移，业务定制写候选文件；不修改 Lovrabet 运行态配置 |
 | 老项目翻新蓝图 / Legacy Application Blueprint | [`guides/legacy-application-blueprint-workflow.md`](guides/legacy-application-blueprint-workflow.md) | 先输出 `.rabetbase/blueprint/<appCode>/application-blueprint.md`，把老代码逻辑与 Dataset / Relations 绑定后再生成迁移 Backlog |
 | 运行 package.json 脚本 | [`rabetbase run <script>`](references/rabetbase-run.md) | `write`；先审阅脚本命令体，嵌入式工具暂不开放 |
 | 安装 / 重装 / 刷新 CLI Built-in Skill | [`rabetbase cli-skill install`](references/rabetbase-cli-skill-install.md) | 由最新版官方 Skills CLI 从当前 npm 包内本地源重装同版本 Skill；发现本地 skill 过期时优先执行 |
@@ -373,6 +377,7 @@ const result = await client.bff.execute<DashboardData>({
 | 查看数据集关联关系 | [`rabetbase dataset relations`](references/rabetbase-dataset-relations.md) | 标准只读入口，输出 `datasetCode + field` 关系事实；支持 `DB_TABLE -> DB_TABLE`、`DB_TABLE -> METADATA`、`METADATA -> METADATA` |
 | 审计数据集关联关系 | [`rabetbase dataset relation-audit`](references/rabetbase-dataset-relation-audit.md) | 只读审计关系事实结构错误、风险和人工复核项 |
 | 管理单条数据集关联关系 | [`rabetbase dataset relation-create/update/delete`](references/rabetbase-dataset-relation-mutations.md) | 单条关系写入；写入前用 `relations` 确认 `datasetCode + field` 关系事实，DB_TABLE 写入所需表名来自显式参数或物理表事实 |
+| 管理跨库数据集关联 | [`dataset cross-relation-list/create/update/delete`](references/rabetbase-dataset-cross-relations.md) | 不同连接的 DB_TABLE 逻辑关系；源端定位，更新/删除要求唯一匹配 |
 | 首次生成数据列表页 | [`rabetbase page generate-start --datasetcode <code>`](references/rabetbase-page-generate-start.md) | 提交或复用服务端异步任务 |
 | 创建自定义页面 | [`rabetbase page create --page-pattern BLANK --name "客户看板"`](references/rabetbase-page-create.md) | 综合操作页面优先使用 `ONEPAGE`，业务数据可视化使用 `DASHBOARD`，基础页面使用 `BLANK`；模板详情见 [`page-templates.md`](knowledge/custom-page/page-templates.md)，也可通过 `--page-dir` 创建完整页面；先 dry-run |
 | 查询自定义页面 | [`rabetbase page custom-list`](references/rabetbase-page-custom-list.md) | 返回页面 ID、页面名称、`pageUrl`（查看最新保存内容）和 `editPageUrl`（打开编辑器） |
@@ -389,7 +394,7 @@ const result = await client.bff.execute<DashboardData>({
 | 恢复已删除页面 | [`rabetbase page restore --id <pageId>`](references/rabetbase-page-restore.md) | 支持 `DATA_LIST|CUSTOM` 自动识别；跨类型同 ID 时显式传 `--page-type` |
 | 数据库连接（dblink）/ 测连 / 结构分析 | [`rabetbase db list`](references/rabetbase-db-list.md) 起 | **`id`**、**trace/plan id** 与“终态 + 复跑 diff”完成口径见 [database-connection-workflow.md](guides/database-connection-workflow.md)；各子命令见 `references/rabetbase-db-*.md` |
 | 独立部署应用范围补偿同步 | [`rabetbase deployment sync-all`](references/rabetbase-deployment-sync-all.md) | 管理员首次初始化、历史回填或故障恢复时使用；`write`，只提交 appCode；在停止编辑的安静窗口执行，保存 jobId 后查询状态，结果未知时用 `sync-jobs` 恢复任务事实，不自动重提；不是精确镜像 |
-| 生成 / 更新 API 客户端代码 | [`rabetbase api pull`](references/rabetbase-api-pull.md) → [`sdk-client-generation.md`](guides/sdk-client-generation.md) | `api pull` 拉 Dataset 事实并刷新匹配应用的 SDK 路由文件；已有 `api.ts`/`client.ts` 按 guide 合并更新 |
+| 升级 API 客户端源码结构并刷新模型 | [`rabetbase project upgrade`](references/rabetbase-project-upgrade.md) → [`rabetbase api pull`](references/rabetbase-api-pull.md) → [`sdk-client-generation.md`](guides/sdk-client-generation.md) | `project upgrade` 迁移稳定入口，`api pull` 只刷新 Dataset 模型事实 |
 | 查看生成的 API 模型 | [`rabetbase api list`](references/rabetbase-api-list.md) | 列出已生成的数据模型 |
 | 查看现有 SQL | [`rabetbase sql list --name "xxx"`](references/rabetbase-sql-list.md) | 分页，按名称过滤；默认查当前决议到的单个应用 |
 | 查看 SQL 详情 | [`rabetbase sql detail --sqlcode xxx`](references/rabetbase-sql-detail.md) | 含完整 SQL 内容和参数定义 |
@@ -457,7 +462,7 @@ const result = await client.bff.execute<DashboardData>({
 | Database Connections (`db`) | [`list`](references/rabetbase-db-list.md) / [`detail`](references/rabetbase-db-detail.md) / [`create`](references/rabetbase-db-create.md) / [`update`](references/rabetbase-db-update.md) / [`delete`](references/rabetbase-db-delete.md) / [`test`](references/rabetbase-db-test.md) / [`analyze`](references/rabetbase-db-analyze.md) / [`tables`](references/rabetbase-db-tables.md) / [`diff`](references/rabetbase-db-diff.md) / [`diff-refresh-start/status`](references/rabetbase-db-diff-refresh.md) |
 | Deployment | [`sync-all` / `sync-status` / `sync-jobs`](references/rabetbase-deployment-sync-all.md)（管理员初始化、回填与恢复） |
 | api commands | [`pull`](references/rabetbase-api-pull.md) / [`list`](references/rabetbase-api-list.md) |
-| sql commands | [`list`](references/rabetbase-sql-list.md) / [`detail`](references/rabetbase-sql-detail.md) / [`create`](references/rabetbase-sql-create.md) / [`status`](references/rabetbase-sql-status.md) / [`pull`](references/rabetbase-sql-pull.md) / [`push`](references/rabetbase-sql-push.md) / [`delete`](references/rabetbase-sql-delete.md) / [`validate`](references/rabetbase-sql-validate.md) / [`save`（deprecated）](references/rabetbase-sql-save.md) / [`exec`](references/rabetbase-sql-exec.md) |
+| sql commands | [`list`](references/rabetbase-sql-list.md) / [`detail`](references/rabetbase-sql-detail.md) / [`create`](references/rabetbase-sql-create.md) / [`status`](references/rabetbase-sql-status.md) / [`pull`](references/rabetbase-sql-pull.md) / [`push`](references/rabetbase-sql-push.md) / [`delete`](references/rabetbase-sql-delete.md) / [`validate`](references/rabetbase-sql-validate.md) / [`exec`](references/rabetbase-sql-exec.md) |
 | bff commands | [`list`](references/rabetbase-bff-list.md) / [`detail`](references/rabetbase-bff-detail.md) / [`logs`](references/rabetbase-bff-logs.md) / [`create`](references/rabetbase-bff-create.md) / [`status`](references/rabetbase-bff-status.md) / [`pull`](references/rabetbase-bff-pull.md) / [`push`](references/rabetbase-bff-push.md) / [`delete`](references/rabetbase-bff-delete.md) |
 | file / ocr commands | [`file upload/query-url`](references/rabetbase-file.md) / [`ocr recognize`](references/rabetbase-ocr.md) |
 | codegen commands | [`sdk`](references/rabetbase-codegen-sdk.md) / [`sql`](references/rabetbase-codegen-sql.md) |
@@ -535,6 +540,7 @@ const result = await client.bff.execute<DashboardData>({
 | 数据接口访问           | 先 detail 再编码、外键/枚举、禁止 N+1、批量与关联查询；验证真实行数据时交接 `lovrabet data`（**`lovrabet` CLI ≥ 2.0**） | [`data-api-guidelines.md`](guides/data-api-guidelines.md)                   |
 | SQL 创建工作流         | list/detail → pull/create → edit → validate → status → push/delete → exec 全链路                                      | [`sql-creation-workflow.md`](guides/sql-creation-workflow.md)               |
 | Backend Function 创建工作流         | new → status → dry-run → pull/push                                                                                    | [`bff-creation-workflow.md`](guides/bff-creation-workflow.md)               |
+| 跨库 BFF 查询与拼接 | 完整键、分库批量读取、分页筛选排序、授权与一致性边界 | [`cross-database-bff.md`](guides/cross-database-bff.md) |
 | 冲突检测与保存         | `blocked`、未保存时的用户沟通、响应结构                                                                               | [`conflict-detection.md`](guides/conflict-detection.md)                     |
 | 质量与最佳实践         | 审查 SQL/Backend Function、命名、高危边界、描述字段                                                                                | [`best-practices.md`](guides/best-practices.md)                             |
 | 数据库连接与分析       | 接入/改连/测连、`traceId` 来源、`db analyze-*` 与 dataset 分工；子命令速查见上文 **「数据库连接（db）」**             | [`database-connection-workflow.md`](guides/database-connection-workflow.md) |

package/skills/rabetbase/guides/backend-function.md

@@ -830,6 +830,8 @@ rabetbase notification config-list --type EMAIL --format compress
 
 ## 事务规则
 
+事务原子性只适用于已核验的运行时事务范围。跨连接模型操作或外部 API 不因位于同一个回调就成为原子操作；分库读取也不能假定共享一致性快照。涉及这些场景时，按 [跨库 BFF 查询与拼接](cross-database-bff.md)确认授权、一致性与写入边界。
+
 事务使用方式：
 
 ```javascript
@@ -860,6 +862,8 @@ await context.client.db.transaction(async (tx) => {
 
 编写 Backend Function 前，必须阅读 `data-api-guidelines.md` 中的性能优化部分。
 
+跨库关联须先区分展示补充与参与筛选、排序、统计的关联，执行顺序见 [跨库 BFF 查询与拼接](cross-database-bff.md)。批量调用仍需处理分页完整性和重复匹配；不能用单次 `$in` 或当前页拼接代替完整结果。
+
 重点避免：
 
 * 循环查询单条
@@ -868,7 +872,7 @@ await context.client.db.transaction(async (tx) => {
 
 性能要求：
 
-* 单次脚本数据库调用尽量控制在 `50` 次以内
+* 按接口限制与业务预算设定调用次数、读取量和超时上限；超限时明确报告，不能截断并冒充完整结果
 * 可批量查询时，用 `filter + $in`
 * 同一数据集批量新增优先使用 `batchCreate()`；相同字段值的批量更新优先使用 `update({ id: [...] })`
 * 只有 Instant API 无法表达的复杂写入才考虑已有且契约可信的 Custom SQL

package/skills/rabetbase/guides/bff-creation-workflow.md

@@ -41,7 +41,9 @@ rabetbase dataset detail --code <数据集编码> --format compress \
 写入前必须确认：
 * 业务必填字段：`data.fields[].required === true`，平台自动维护字段除外
 * 枚举/选择字段：写入 `options[].value`，不要写展示用 `label`
-* 外键字段：从 `data.relations[]` 或 `dataset relations` 确认真实关系
+* 外键字段：同库关系从 `data.relations[]` 或 `dataset relations` 确认；跨库关系使用 `dataset cross-relation-list`，不能用同库关系列表代替
+
+涉及跨连接读取或拼接时，先读 [跨库 BFF 查询与拼接](cross-database-bff.md)，确认完整键、基数、目标字段用途、各端授权和读取预算。业务关系说明与平台登记事实分别核对；冲突时报告差异，不能自动采用平台关系。复合键不能拆成独立的单字段 Relation。
 
 ### 3. 查平台（按需）
 * 新建 → 跳过

package/skills/rabetbase/guides/cross-database-bff.md

@@ -0,0 +1,70 @@
+# 跨库 Backend Function 查询与拼接
+
+用于编写或审查跨数据库连接的 BFF 查询：分别读取各数据源，在可信 BFF 中按完整关联键拼接，再输出业务结果。单表优先使用 InstantAPI；同一连接内的关联或聚合可使用已确认支持的关联查询或 Custom SQL。跨库 Relation 描述逻辑关联，不赋予自动 JOIN、访问授权或分布式事务能力。
+
+本文同库／跨库按平台数据库连接区分；不同 dblink 不因库名或表名相同而视为同库。默认关联关系指同库关联关系。
+
+## 先确认事实和业务合同
+
+1. 用 `rabetbase dataset detail --code <datasetCode> --format compress` 核对两端字段、类型、物理表和连接；模型访问方式遵循 [Backend Function](backend-function.md)，同名表必须消歧。连接身份以当前应用的真实 dblink 为准，不靠库名或表名推断。
+2. 用 [跨库关系命令](../references/rabetbase-dataset-cross-relations.md)的 `cross-relation-list` 查询平台已登记关系。业务文档中的关系说明不代表已经登记；平台配置也不能代替业务正确性确认。两者冲突时报告端点差异，由业务确认后再维护关系，不能自动照搬或修正。
+3. 在业务项目明确：完整关联键及顺序、基数、允许缺失与否、目标字段用途（展示、筛选、排序、统计）、各端访问范围、返回字段，以及读取预算和失败处理。具体映射留在业务项目，详细元数据按需查询；不在通用 Skill 中保存项目关系清单或元数据快照。
+
+依据按需查找：先读已有接口文档和当前元数据，确认调用能力与硬限制；再读项目业务合同和现有配置，确定关联语义、授权及读取预算。已有事实充分时直接采用，不重复要求用户确认。依据冲突或缺少影响正确性、授权、完整性的必要信息时，说明具体缺口后确认；不自行发明权限字段、运行时上限或项目级配置。
+
+当前 `cross-relation-create/update/delete` 每端只接收一个字段。复合键必须作为有序字段组整体理解，不能拆成多条单字段 Relation，也不能用逗号拼接字段来冒充复合关系支持。BFF 可依据已确认的业务合同实现完整键匹配，但不得宣称该复合关系已由这些命令登记。
+
+## 根据查询语义选择执行顺序
+
+| 外表的用途 | 执行方式 | 结果要求 |
+|---|---|---|
+| 仅补充展示字段 | 先对已授权主表筛选、稳定排序、计数和分页，再批量读取当前页所需外表数据 | 保留主记录、主表顺序和总数；一对多用约定的集合承载，不能展开后仍沿用原分页含义 |
+| 参与筛选 | 先分析完整筛选表达式；能够等价转成目标键条件时，在预算内完整取得所需键集合，再保留原布尔逻辑筛选、计数和分页主表 | 主表 total 对应最终筛选结果；不能等价表达时报告能力边界 |
+| 参与排序或统计 | 先确认能够覆盖完整相关结果集的执行方案 | 当前页拼接后的排序或统计不能冒充全局结果；预算不足时请求调整范围或由权威查询服务承接 |
+
+正向匹配可在确认等价后使用引用键 `IN` 条件。否定、无关联、空引用，以及主表条件与外表条件混合的 `OR` 必须分别保留语义，不能统一改成正向 `IN`。例如“主记录紧急 OR 目标启用”转换后仍须保留主记录紧急分支；“没有关联目标”不能用任意目标字段筛选的补集代替。授权过滤始终限制整个结果集，不能被业务 `OR` 绕过。
+
+不同连接分别读取，不用跨库 SQL JOIN、跨库子查询或视图绕过执行边界，也不把整个外库拉进 BFF。关系存在和 `sql validate` 通过都不能证明跨连接查询可执行。各库支持的过滤、投影、聚合可在所属库内完成；没有可验证的完整方案时停止，不能返回貌似完整的部分结果。
+
+## 完整键、批量读取与拼接
+
+以下步骤描述为已选定主记录补充展示字段的流程。参与筛选、排序或统计时先按上表确定读取顺序，再复用完整键与批量处理规则；不能把主表先分页当作所有跨库查询的前置步骤。
+
+1. 从已授权主记录提取有效引用键。空值定义遵循字段合同，不用真值过滤误删合法的 `0`；复合键任一必需部分缺失时按缺失关系处理。
+2. 保留 ID 精度及类型语义，不把大整数 ID 转成 `Number`。只有两端合同明确同一标识的不同编码方式时才做无损归一化；不擅自忽略大小写、前导零或空白。
+3. 对完整键去重并按字段值比较。复合键保留字段顺序和类型，使用嵌套 `Map` 或明确的无损键编码，避免分隔符拼接碰撞；不能直接用新建数组作为 `Map` 查询键，因为数组按对象身份而非内容比较。例如期望 `(A, 7)`、`(B, 9)` 时，`region IN (A,B) AND external_id IN (7,9)` 会额外选中 `(A,9)`、`(B,7)`；应使用配对条件，或按第一个键分组后查询对应第二键集合，最终仍按完整键匹配。更多字段同样逐一配对，不省略剩余字段；示例字段不替代真实字段合同。
+4. 键集合为空时跳过外表查询。非空时按目标接口的参数、分页和数量限制分批查询，投影只包含拼接和已授权输出所需字段。分批大小、最大页数、总读取量、并发和超时依据接口合同及业务预算确定，不复制其他项目的固定数值。
+5. 每批都按该接口的分页合同读取完整结果，再建立映射。已知仍有后续结果却只拿到一页、完成前达到预算上限、页码不推进或查询失败时，默认返回错误，不推断剩余键均不存在。分批循环用于有界读取，不退回逐条记录的 N+1 调用。
+6. 按已确认基数组装。1:1 或 N:1 的同一完整目标键出现多条记录时，报告重复匹配，不能用 `Map.set`、`Object.fromEntries` 或“取第一条”静默覆盖。一对多或多对多按合同保留集合，输出顺序须明确。
+
+区分以下结果，不用 `catch(() => [])` 将错误伪装为空数据：
+
+默认接口成功表示所需数据已完整读取。只有已有接口合同明确支持部分结果时，才使用其既定状态与字段输出；不能临时新增 `partial` 字段就返回成功，也不能把未完成计算的 `total`、排序或统计描述为准确结果。
+
+| 情况 | 处理 |
+|---|---|
+| 完整查询成功，允许缺失的展示关系未匹配 | 保留主记录；单目标返回 `null`，多目标集合按业务合同返回 |
+| 必需关系缺失或唯一关系重复匹配 | 按业务合同返回错误；不猜测替代记录 |
+| 权限不足或查询失败 | 返回错误，不能解释为“目标不存在” |
+| 分页结果不完整 | 默认返回错误；已有部分结果合同按上文处理，不能推断未读结果 |
+
+## 授权与数据所有权
+
+- BFF 从可信身份或已核验的服务端访问上下文确定权限。客户端提供的业务筛选值不能扩大授权范围；子记录需要沿已确认的父关系核验归属。
+- 每个数据源分别落实访问控制。不能把主库的租户字段、门店字段、软删除字段或状态枚举机械套到目标表；关联键本身不是访问凭证，已取得的目标 ID 也不等于有权读取它。
+- 核对 BFF 内部模型、SQL 或外部 API 的实际调用通道，不假设它必然经过 Dataset HTTP Hook。缺少授权合同则停止；复用公共授权函数前确认其输入、可信上下文和覆盖范围。
+- 查询投影和返回值使用已授权字段白名单，敏感字段不得通过拼接结果、错误、日志或参数回显泄漏。保留业务字段的精度和空值语义，不为展示默认补零或改变标识符类型。
+- 读写通道由数据所有权和接口合同决定。某个项目的外库只读、指定 OpenAPI 写入规则不能推广为所有外库的统一策略；确认关系或具备读取能力均不构成写入授权。
+
+## 一致性与写入边界
+
+分库读取不共享已证明的一致性快照。数据可能在两次读取之间变化；拼接结果不能作为库存、结算等关键写入的最终依据，关键校验应由权威写入服务在其一致性边界内完成。
+
+`context.client.db.transaction` 的原子性仅按已核验的运行时事务范围理解，不能通过把调用放进同一个回调就承诺跨连接或外部 API 原子性。涉及多系统写入时先明确操作顺序、幂等、部分成功与补偿合同；状态未知时先核对，不盲目重试或自动补偿。事务 API 用法见 [Backend Function 事务规则](backend-function.md#事务规则)。
+
+## 交付检查
+
+- 两端连接、完整键、基数、权限、投影和读取预算都有明确依据；历史关系和同名字段没有被自动当成有效关系。
+- 覆盖空键、复合键交叉组合与按值查找、重复匹配、允许/必需关系缺失、多页结果、读取中断及预算不足。
+- 展示补充保留主表分页含义；关联筛选包含正向、否定、无关联和混合 OR 的反例，全局排序和统计不会用当前页结果替代完整结果。
+- 用不同身份验证各端数据范围和字段输出；需要真实业务行数据或 BFF 执行验证时，按 [BFF 工作流](bff-creation-workflow.md)显式交接运行态验证。关系配置回读和 `bff push` 成功不能替代该验证。

package/skills/rabetbase/guides/data-api-guidelines.md

@@ -14,7 +14,7 @@
 | **分析主外键关系** | 理解表间关联，正确处理下拉框数据 |
 | **使用真实接口** | 不使用 mock 数据，直接调用数据集接口 |
 | **避免循环访问** | 批量查询替代循环单个查询 |
-| **性能优先** | 单次接口调用次数 < 50 次 |
+| **有界读取** | 按接口限制与业务预算设定调用和读取上限；超限不能截断结果并冒充完整数据 |
 
 ---
 
@@ -31,7 +31,7 @@
 
 **CLI 信封、`data.*` 键位、平台 `get-driven-data` 与 CLI 归一化对照**：单一权威见 [`references/rabetbase-dataset-detail.md`](../references/rabetbase-dataset-detail.md)。
 
-**不要复制示例字段名。** 本指南里的表名、字段名、枚举值只用于说明形态；真实代码必须从当前项目的 `rabetbase dataset detail` 输出中取 `data.fields[]`、`data.relations[]` 和 `data.dbtable`。
+**不要复制示例字段名。** 本指南里的表名、字段名、枚举值只用于说明形态；真实代码的字段与连接事实来自当前项目的 `rabetbase dataset detail` 输出。同库关系读取 `data.relations[]`，跨库登记事实单独使用 `dataset cross-relation-list` 核对。
 
 ---
 
@@ -56,7 +56,10 @@
 | 聚合列名 | `aggregate[].column` | SDK aggregate 定义使用 `column`，不要写旧别名 `field` |
 | 必填字段 | `data.fields[].required` | `true` 表示创建/写入时需处理，平台自动维护字段除外 |
 | 枚举/选择值 | `data.fields[].options[].value` | 写入持久化 `value`，不要写展示用的 `label` |
-| 外键关系 | `data.relations[]` / `dataset relations` | 只有确认存在关系后才写关联查询或校验 |
+| 同库关系 | `data.relations[]` / `dataset relations` | 确认端点、基数和查询能力，不按同名字段推断关系 |
+| 跨库登记关系 | `dataset cross-relation-list` | 与业务合同分别核对，不用同库关系列表替代 |
+
+复合键 BFF 可依据已确认的业务合同和两端字段事实实现，不要求先拆成单字段 Relation；平台登记关系不等于执行能力。完整键、查询顺序和授权边界见 [跨库 BFF 查询与拼接](cross-database-bff.md)。
 
 常用投影：
 
@@ -271,7 +274,7 @@ const result = await models[TABLES.primary].filter({
 
 ### 场景识别
 
-代码中出现**循环内调用接口**时，必须优化：
+代码中出现**按主记录逐条调用接口的 N+1 查询**时，必须优化；按接口合同执行的有界分批和分页循环属于批量读取：
 
 ```tsx
 // ❌ 性能灾难：N 次接口调用
@@ -283,22 +286,22 @@ for (const row of rows) {
 ### 优化方案选择
 
 ```
-循环访问接口（N 次调用）
+循环逐条访问接口（N 次调用）
+    │
+    ├─ 不同数据库连接 → BFF 分库批量读取，按完整键拼接
     │
-    ├─ 关联类型是 1:1 或 N:1？
-    │   │
-    │   ├─ 是 → 使用 filter 多表关联查询（推荐）
-    │   │        一次查询，自动 JOIN
-    │   │
-    │   └─ 否 → 使用批量查询（$in）
-    │        一次查询，手动映射
+    └─ 同一连接
+        ├─ 1:1/N:1 且已确认支持关联查询 → filter 多表关联查询
+        └─ 其他场景 → 有界批量查询，或已确认支持的库内 Custom SQL
 ```
 
+先核对数据源及查询能力，再选择方案；基数或平台存在 Relation 不能单独证明可自动 JOIN。跨库场景必须阅读 [跨库 BFF 查询与拼接](cross-database-bff.md)，分别处理展示补充、关联筛选、全局排序和统计。
+
 ### 方案 1：多表关联查询（推荐）
 
 <span style={{fontSize: '0.9em', color: '#888'}}>v1.2.0+</span>
 
-**适用于**：1:1 或 N:1 关联（主记录→关联记录、成员→组织等）
+**适用于**：同一数据库连接内、已确认支持关联查询的 1:1 或 N:1 关系（主记录→关联记录、成员→组织等）。以下示例不能用于推断跨连接 JOIN 能力。
 
 ```tsx
 // ✅ 一次查询，自动 JOIN
@@ -319,28 +322,27 @@ const result = await client.models.primary.filter({
 
 ### 方案 2：批量查询
 
-**适用于**：复杂场景或不支持多表关联时
+**适用于**：不支持多表关联或需要分开读取时；跨库拼接在可信 BFF 中完成。
 
-```tsx
-// ✅ 一次查询，$in 批量获取
-const relatedIds = [...new Set(rows.map(row => row.related_id))];
-const relatedRows = await client.models.related.filter({
-  where: { id: { $in: relatedIds } },
-  select: ['id', 'name']
-});
-const relatedMap = Object.fromEntries(
-  relatedRows.tableData?.map(row => [row.id, row.name]) || []
-);
-rows.forEach(row => row.relatedName = relatedMap[row.related_id]);
-```
+以下步骤用于向已选定主记录补充展示字段。外表参与筛选、排序或统计时，先按 [跨库 BFF 查询与拼接](cross-database-bff.md)确定完整查询顺序，不能先取主表当前页后套用本流程。
+
+1. 从已授权主记录提取有效完整键并去重；空键集合跳过查询，合法的 `0` 不用真值过滤排除。
+2. 单字段键可用 `$in` 批量过滤；复合键保留字段配对，不能用两个独立 `$in` 替代联合条件。
+3. 按目标接口限制分批并读取所有匹配页，只取拼接和输出必需的已授权字段。批量查询不保证一次调用返回完整数据；结果不完整或请求失败时默认返回错误。部分结果只按已有接口合同输出，规则见 [跨库 BFF 查询与拼接](cross-database-bff.md)。
+4. 完整结果按完整键和基数组装；单目标关系出现重复键时报告冲突，一对多按合同收集为集合，不能静默覆盖。
+5. 只有完整查询成功才判断未匹配；允许缺失的单目标展示关系保留主记录并返回 `null`，必需关系缺失按业务合同失败。
+
+具体执行顺序、复合键示例与失败语义见 [跨库 BFF 查询与拼接](cross-database-bff.md)。
 
 ### 性能对比
 
-| 方案 | 调用次数 | 耗时 |
-|------|---------|------|
-| 循环单条（100 条） | 100 次 | ~10 秒 |
-| 多表关联 | 1 次 | ~0.1 秒 |
-| 批量查询 | 1 次 | ~0.1 秒 |
+| 方案 | 调用量取决于 | 使用前提 |
+|------|-------------|----------|
+| 循环单条 | 主记录数量 | 容易产生 N+1，应优先批量化 |
+| 库内关联 | 接口分页与查询计划 | 同连接且查询能力已确认 |
+| 批量查询 | 去重键数量、批次和匹配结果页数 | 完整读取并在预算内组装 |
+
+调用次数不能直接换算为固定耗时；按真实查询计划、数据量和接口限制验证。
 
 ---
 
@@ -381,7 +383,7 @@ await context.client.sql.execute({
 - [ ] **外键字段已识别**：下拉框数据来自关联数据集接口
 - [ ] **枚举字段已处理**：展示使用 `options[].label`，写入使用 `options[].value`
 - [ ] **未使用 mock 数据**：所有下拉框数据来自真实接口
-- [ ] **无循环访问**：优先使用多表关联查询，或使用批量查询
+- [ ] **避免 N+1**：同连接且能力已确认时使用多表关联；跨连接交由 BFF 有界批量读取
 - [ ] **字段名正确**：使用 `data.fields[].name`（列名），区分大小写，与数据集定义一致
 - [ ] **系统字段已识别**：结合 `data.dbtable` 与 `backend-function.md`，创建/更新时间等按平台约定不传
 - [ ] **关联表使用表名**：多表关联时使用 `tableName.fieldName` 格式
@@ -394,7 +396,7 @@ await context.client.sql.execute({
 - [ ] **枚举字段写入正确**：写入 `options[].value`，不是展示 `label`
 - [ ] **外键校验已处理**：创建/更新前校验外键有效性
 - [ ] **系统字段未设置**：主键自增、系统时间等按平台约定不手工传入，详见 `backend-function.md`
-- [ ] **无循环访问**：使用 filter + $in 批量查询
+- [ ] **批量读取完整**：按完整键去重、分批和分页；查询失败、不完整或唯一关系重复匹配均明确报告
 - [ ] **批量操作已优化**：大量数据操作使用自定义 SQL
 
 ### SQL 开发