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

package/skills/rabetbase/guides/sdk-client-generation.md

@@ -1,8 +1,18 @@
-# SDK 客户端代码生成（api.ts / client.ts）
+# SDK 客户端代码生成（稳定入口与模型注册表）
 
-> 目标：根据 `rabetbase api pull` 返回的数据集事实，生成或更新浏览器子应用的 `src/api/api.ts` 与 `src/api/client.ts`，并保留项目已有的自定义写法。
+> 目标：根据 `rabetbase api pull` 返回的数据集事实，维护浏览器子应用的稳定 SDK 入口，并让同一套业务 API 的不同部署使用各自正确的 `datasetCode`。
 >
-> CLI 默认不覆盖 TypeScript。`api pull` 只保证：刷新 `data.files.sdkConfig.path` 指向的应用级 SDK 路由文件、返回 `data.models`，并在文件缺失时写入 Cookie-first 脚手架。已有文件由本指南更新；只有用户明确要求放弃本地定制并完整重建时，才使用 `--force --yes`。
+> 单应用或显式配置同一 `apiGroup` 的 profile 使用注册表模式：`project create` / `project upgrade` 维护稳定源码结构，`api pull` 只刷新 `models.generated.ts` 中的模型事实。`apiGroup` 只负责归并，不进入文件名或运行时对象。
+
+## 重要运行边界：一次运行只选择一个 profile
+
+注册表模式解决的是：**同一份业务代码分别部署到不同节点，并由当前 Runtime Domain 选择唯一 profile**。它不提供跨节点数据访问，也不把多个 profile 合并成一个可同时查询的浏览器 client。
+
+- 业务代码始终通过稳定 alias 调用 `lovrabetClient.models.<alias>`；不要读取注册表后自行挑选其他 profile 的 `datasetCode`，也不要把该代码硬编码进业务模块。
+- 当前 profile 只物化自己的模型。仅其他 profile 存在的 alias 不会注册到当前 client；误用时应保留 SDK 的 `MODEL_NOT_FOUND`，不得回退默认 profile 或借用其他节点的代码。
+- 节点独有功能可先检查 `LOVRABET_PROFILE_NAME` 再决定是否调用；共享功能不需要分支，同一 alias 会自动绑定当前 profile 的代码。
+- 浏览器 Cookie 与 Runtime Domain 都属于当前节点。不要为了“一次查询两端”在浏览器中创建两个 profile client、跨 Domain 转发认证信息或绕过 Domain 选择器。
+- 真正需要跨节点读取、比对或聚合时，使用具备明确认证和授权边界的可信服务端或 Backend Function 编排；CLI 侧排查则分别用 `--app <profile>` 查询，不把两个 profile 当成一个运行实例。
 
 ## 何时执行
 
@@ -10,7 +20,7 @@
 
 - 刚执行 `rabetbase api pull` 或 `rabetbase project create`（带 appCode）
 - 平台增删了 Dataset，本地 `models` 过期
-- `api.ts` / `client.ts` 缺失、空 `models: []`、或 `LOVRABET_APP_CODE` 仍是 `NOT-SET`
+- `api.ts` / `client.ts` 缺失、注册表为空、或生成 profile 的 AppCode 仍是 `NOT-SET`
 - 用户要求修复 SDK 客户端初始化
 
 不要凭空编造 `datasetCode`。不要把本指南里的浏览器 Cookie 客户端写成服务端 `accessKey` 客户端。
@@ -18,95 +28,134 @@
 ## 工作流
 
 ```
+rabetbase project upgrade --dry-run
+  → 审阅 apiArchitecture.groups[].files[]
+rabetbase project upgrade --yes
+  → 标准旧脚手架自动备份迁移；业务定制生成候选入口
 rabetbase api pull --format compress
   → 单应用读 data；项目应用清单逐项读 data.apps[]
-  → 读取每项的 models / configName / isDefaultConfig / files / needsAgentMerge
-  → 读已有 api.ts、client.ts 与 files.sdkConfig.path（含 {prefix}-api.ts / {prefix}-client.ts / {prefix}-sdk-config.ts）
-  → 按事实更新 models，保留本地 extras
-  → 不要改已经正确的 createClient({ apiConfigName, ...LOVRABET_SDK_CONFIG })
+  → 读取每项的 models / modelProfile / files / needsProjectUpgrade
+  → 注册表模式检查 models.generated.ts / model-runtime.ts / api.ts / client.ts
+  → 验证最终 Runtime Domain 能选中目标 profile
 ```
 
-1. 执行 `rabetbase api pull --format compress`（需要人类可读缩进时用 `--format json`）。
-   - 不要自动添加 `--force`。
-   - 只有用户明确要求丢弃本地 `api.ts` / `client.ts` 定制并完整重建时，才执行 `rabetbase api pull --force --yes --format compress`；此时根据返回的 `files.*.action` 回查是否为 `overwritten`。
-2. 直接单应用结果使用 `data.models`；项目应用清单结果逐项使用 `data.apps[].models`。不要手写或猜测 `datasetCode`。也可用 `rabetbase api list --format compress` 核对目录，但写文件以 pull 返回的 models 为准。
-3. 先读现有文件再写：
-   - 默认单应用：`src/api/api.ts`、`src/api/client.ts`、`src/api/sdk-config.ts`
-   - 多应用非 default：`{name}-api.ts` / `{name}-client.ts` / `{name}-sdk-config.ts`（以 `data.files.*.path` 为准）
-4. SDK 路由文件由 CLI 维护（`data.files.sdkConfig.action === "refreshed"`），不要往里面写 `cookie` / `accessKey` / `token`。若保留的旧 `{name}-client.ts` 仍导入共享 `./sdk-config`，只把该 import 改为 `./{name}-sdk-config`，其余本地定制保持不变。
-5. 看 `data.needsAgentMerge` 和 `data.files.*.action`，**不要**用已删除的 `wroteScaffold`：
-   - `needsAgentMerge === false` 且 `api`/`client` 均为 `created` 或 `overwritten`：脚手架已按当前 `models` 写好，只需检查项目 extras。
-   - `needsAgentMerge === true`：至少有一个 TypeScript 文件被 **preserved**。先比较本地配置与返回事实，只在有差异时合并；即使 `client` 刚 `created`，也不能据此跳过对已保留 `api.ts` 的检查。
-6. 默认应用：`data.isDefaultConfig === true`，`data.configName === "default"`，代码里用 `CONFIG_NAMES.DEFAULT`。
-7. 具名应用：`data.isDefaultConfig === false`，`data.configName` 是不含引号的名字（如 `order`），`registerModels(..., "order")` 与 `apiConfigName: "order"`。不要把 `configName` 再包一层引号。
+1. 已有项目先执行 `rabetbase project upgrade --dry-run`。标准旧脚手架可直接正式升级；`manual-merge` 表示原入口含业务定制，正式升级只会写候选文件，不会覆盖原文件。
+2. 执行 `rabetbase project upgrade --yes` 后审阅 `apiArchitecture.manualMergeRequired`。候选文件在 `.rabetbase/project-upgrade/api-model-registry-v2/candidates/`；完成合并前不要删除原入口。
+3. 执行 `rabetbase api pull --format compress`（需要人类可读缩进时用 `--format json`），刷新远端 Dataset 事实。不要自动添加 `--force`；它在注册表模式只用于明确接受空结果。
+4. 直接单应用结果使用 `data.models`；项目应用清单结果逐项使用 `data.apps[].models`。不要手写或猜测 `datasetCode`。
+5. `data.modelProfile` 存在时检查 `data.files.modelRegistry`：同一平台 `alias` 只有一条模型，`tableName` 必须在各 profile 间一致。所有当前 profile 都存在且代码相同时使用 `datasetCode`；代码不同或仅部分 profile 存在时使用 `datasetCodes[modelProfile]`，缺失 profile 不写空字符串。
+6. `model-runtime.ts` 由项目创建/升级维护，`models.generated.ts` 由 pull 刷新；都不要写入凭据或应用业务函数。若 `data.needsProjectUpgrade === true`，回到第 1 步，不要手工覆盖入口。
+7. 一个 AppCode 对应多个 profile 时，所有拉取与别名写操作都用 `--app <profile>`；不要使用有歧义的 `--appcode`。AppCode 相同不会自动归并，只有显式相同的 `apiGroup` 才表示共享业务 API。
 
 ## 权威结构
 
 浏览器子应用的权威形态与 `templates/projects/sub-app-react-demo/src/api/` 一致。脚手架模板是 `templates/generate-api/*.tpl`，生成结果应对齐 demo，而不是另造一套。
 
-### sdk-config.ts / {name}-sdk-config.ts（路由，无凭证）
+### models.generated.ts（CLI 生成事实）
 
 ```typescript
-/**
- * Lovrabet SDK runtime routing.
- * Generated by Rabetbase CLI. Do not add credentials to this file.
- */
-export const LOVRABET_SDK_CONFIG = {} as const;
+/* rabetbase-model-registry:v2 */
+export const LOVRABET_MODEL_REGISTRY = {
+  defaultProfile: "oa-cn",
+  profiles: {
+    "oa-cn": {
+      appCode: "app-xxxxxxxx",
+      runtimeDomain: "https://runtime.lovrabet.com",
+    },
+    "oa-id": {
+      appCode: "app-xxxxxxxx",
+      runtimeDomain: "https://runtime.lovrabet.id",
+    },
+  },
+  models: [
+    {
+      alias: "paymentApplication",
+      tableName: "payment_application",
+      name: "Payment Application",
+      datasetCode: "shared-dataset-code",
+    },
+    {
+      alias: "orders",
+      tableName: "orders",
+      name: "Orders",
+      datasetCodes: {
+        "oa-cn": "cn-dataset-code",
+        "oa-id": "id-dataset-code",
+      },
+    },
+  ],
+} as const;
 ```
 
-默认节点保持空对象；其他官方节点和企业独立部署统一写入最终 `runtimeDomain`。不要手改成认证字段。项目模板所需的完整公开 Domain 与资源策略由独立命令 `rabetbase project domain-routing-sync` 写入项目根目录的 `rabetbase.domain-routing.json`。
+- 以平台稳定 `alias` 作为跨 profile 的模型归并键，`tableName` 作为一致性校验；同 alias 指向不同表或同表出现不同 alias 时停止写入。
+- 默认 profile 提供公共 `alias` / `name`；其他 profile 的同表展示名不同不会制造第二份模型。
+- 所有当前 profile 都存在且 Dataset 代码相同时只写单数 `datasetCode`。
+- 某 profile 独有的表只包含自己的 `datasetCodes` key；运行时不会把它提供给其他 profile。
+- 文件版本由 CLI 专用注释标记识别，不进入应用运行时对象。
+- 此文件由 CLI 原子刷新，不手工编辑。
 
-### api.ts
+### model-runtime.ts（通用选择器）
 
-```typescript
-import { registerModels, CONFIG_NAMES, type ModelsConfig } from "@lovrabet/sdk";
+该文件根据平台注入的 Runtime Domain 选择唯一 profile；本地构建读取项目根目录的 `rabetbase.domain-routing.json`。零匹配或多匹配都直接报错，不回退 `defaultProfile`。它只将所选 profile 物化为 SDK 的 `{ appCode, models }`，不会创建多节点 client，不放业务函数，也不硬编码具体 Dataset。
 
-export const LOVRABET_APP_CODE = "app-xxxxxxxx";
-
-export const LOVRABET_MODELS_CONFIG: ModelsConfig = {
-  appCode: LOVRABET_APP_CODE,
-  models: [
-    { datasetCode: "abc123", tableName: "orders", name: "订单", alias: "orders" },
-  ],
-} as const;
+### api.ts
 
+```typescript
+import { registerModels, CONFIG_NAMES } from "@lovrabet/sdk";
+import projectRouting from "../../rabetbase.domain-routing.json";
+import { LOVRABET_MODEL_REGISTRY } from "./models.generated";
+import { resolveActiveModelConfig } from "./model-runtime";
+
+const activeModelConfig = resolveActiveModelConfig(
+  LOVRABET_MODEL_REGISTRY,
+  projectRouting.domains.runtime,
+);
+
+export const LOVRABET_PROFILE_NAME = activeModelConfig.profileName;
+export const LOVRABET_APP_CODE = activeModelConfig.appCode;
+export const LOVRABET_RUNTIME_DOMAIN = activeModelConfig.runtimeDomain;
+export const LOVRABET_MODELS_CONFIG = activeModelConfig.modelsConfig;
 registerModels(LOVRABET_MODELS_CONFIG, CONFIG_NAMES.DEFAULT);
 ```
 
-- 默认应用：`data.isDefaultConfig` 为 true 时用 `CONFIG_NAMES.DEFAULT`。
-- 非默认 / 具名应用：用 `data.configName`（不含引号的字符串，如 `order`）作为 `registerModels` 第二参数和 `apiConfigName`，不要再 import 未使用的 `CONFIG_NAMES`。
-- 数字开头的文件前缀使用 `APP_` 变量前缀（如 `APP_5B732428_APP_CODE`），运行时 `appCode` 保持原值。
-- `registerModels` 是 `@lovrabet/sdk` 的独立命名导出，**不是** `client.registerModels()`。
-- `api.ts` 可以作为稳定入口，从一个或多个项目内相对模块转导出模型配置。例如 `export { APP_MODELS_CONFIG as LOVRABET_MODELS_CONFIG } from "./app-api"`。CLI 会静态读取每个本地 `export … from` 目标中的模型，不执行 TypeScript；HOOK 目录和 `--code` alias 会使用汇总后的模型别名。每个 Dataset 必须只有一个 alias，且一个 alias 不能对应多个 Dataset；冲突时 CLI 会停止而不是猜测绑定目标。
+`api.ts` 只负责连接注册表、路由事实和 SDK 注册。业务层继续从原路径 import，无需感知 profile 数量。
+
+`registerModels` 是 `@lovrabet/sdk` 的独立命名导出，**不是** `client.registerModels()`。
+
+历史未分组项目仍兼容读取具名前缀文件及项目内相对转导出。例如 `api.ts` 可写 `export { APP_MODELS_CONFIG as LOVRABET_MODELS_CONFIG } from "./app-api"`。CLI 会静态读取本地 `export … from` 目标，不执行 TypeScript；HOOK 目录和 `--code` alias 会使用汇总后的模型别名。每个 Dataset 必须只有一个 alias，且一个 alias 不能对应多个 Dataset；冲突时 CLI 会停止而不是猜测绑定目标。旧式前缀路径的默认应用使用 `CONFIG_NAMES.DEFAULT`，具名应用使用 `data.configName`；数字开头的文件前缀继续使用 `APP_` 变量前缀。
 
 ### client.ts（Cookie-first）
 
 ```typescript
 import { createClient, CONFIG_NAMES } from "@lovrabet/sdk";
-import "./api";
+import { LOVRABET_RUNTIME_DOMAIN } from "./api";
 import { LOVRABET_SDK_CONFIG } from "./sdk-config";
 
 export const lovrabetClient = createClient({
   apiConfigName: CONFIG_NAMES.DEFAULT,
   ...LOVRABET_SDK_CONFIG,
+  runtimeDomain: LOVRABET_RUNTIME_DOMAIN,
 });
 ```
 
-- 必须 `import "./api"`（或 `./{prefix}-api`）以执行 `registerModels`。
 - 浏览器子应用默认登录态 Cookie：省略 `authMode`，**不要**在此文件写入 `accessKey` / `token`。
-- 已有 `createClient({ apiConfigName, ...LOVRABET_SDK_CONFIG })` 且与 `data.isDefaultConfig` / `data.configName` 一致时，不要改参数形态。
-- 非生产环境脚手架可能带 `env: "daily"`；已有客户端已能工作则不要为了对称去改。
+- `runtimeDomain` 放在 spread 之后，确保运行时选中的 profile 是最终路由事实。
+
+### sdk-config.ts（路由，无凭证）
+
+该文件仍由 CLI 刷新并保持浏览器安全。注册表模式的最终 Runtime Domain 来自 `api.ts`，项目的完整公开 Domain 与资源策略由 `rabetbase project domain-routing-sync` 写入 `rabetbase.domain-routing.json`。
+
+## apiGroup、目录隔离与旧式兼容
 
-## 合并规则
+CLI 仍能读取已有 `[name-]api.ts` 中的 `models`，页面与 BFF 的 `--alias` 不会立即失效。迁移时：
 
-以 `data.models` 为 Dataset 清单的唯一事实来源：
+- 先执行 `project upgrade --dry-run`，审阅标准生成文件与业务定制文件的分类。
+- 有本地定制时，将业务 helper 移到独立业务模块；不要放进 `models.generated.ts` 或 `model-runtime.ts`。
+- 正式执行 `project upgrade --yes`；标准旧入口先备份再替换，定制入口只生成候选文件。
+- 执行 `api pull --format compress` 刷新远端事实；业务 import 继续指向 `src/api/api.ts` / `client.ts`。
+- 旧的 `[name-]api.ts` / `[name-]client.ts` 可在确认无引用后再删除；CLI 不自动删除用户文件。
 
-- **新增**：pull 有、本地没有的 `datasetCode`，追加到 `models`
-- **删除**：本地有、pull 没有的 `datasetCode`，从 `models` 移除
-- **更新**：同一 `datasetCode` 的 `tableName` / `name` 以 pull 为准
-- **别名**：本地已有且仍对应同一 `datasetCode` 的 `alias` 保留；新建项使用 pull 给出的 `alias`
-- **保留 extras**：额外的 `registerModels(...)`、额外 client 导出、项目自定义注释（非 Generated 头）不要删
-- **多应用**：继续使用 CLI 的 `{name}-api.ts` / `{name}-client.ts` 命名，不要把多个 app 的 models 揉进同一个 `api.ts`
+`apiGroup` 是显式 join key：同组 profile 的 AppCode 可以相同或不同，但必须使用同一规范化 `apiDir`；同一 `apiDir` 也只能承载一个显式组。`./src/api`、`src/api`、`src/api/` 会视为同一目录。第二套业务使用独立目录，例如 `src/api/finance`，目录内仍是无前缀的 `api.ts` / `client.ts`。同一目录下多个未配置 `apiGroup` 的历史 profile 继续使用 `[name-]api.ts` / `[name-]client.ts`，不会被静默归并。
 
 ## 认证（不要写进浏览器 client.ts）
 
@@ -138,13 +187,15 @@ export const lovrabetClient = createClient({
 | 字段 | 含义 |
 |------|------|
 | `appCode` | 当前应用 |
-| `configName` | `"default"` 或具名应用名（不含 TS 引号） |
-| `isDefaultConfig` | 默认应用为 `true` |
+| `modelProfile` | 本次刷新的 profile；旧式输出可省略 |
 | `models[]` | `datasetCode` / `tableName` / `name` / `alias` |
 | `sdkRouting` | `{ runtimeDomain?: string }` |
-| `files.api` / `files.client` / `files.sdkConfig` | `{ path, action }`；`action` 为 `created` / `overwritten` / `preserved` / `refreshed` |
-| `needsAgentMerge` | 任一 TypeScript 被 `preserved` 时为 `true`，必须合并 `models` |
-| `apiFilePath` / `clientFilePath` / `sdkConfigPath` | 与 `files.*.path` 相同，兼容路径字段 |
+| `files.api` / `files.client` / `files.sdkConfig` | 稳定入口与 SDK 路由的路径及动作 |
+| `files.modelRegistry` / `files.modelRuntime` | 注册表模式的模型事实与通用选择器路径及动作 |
+| `needsAgentMerge` | 兼容字段；旧式或自定义入口尚未接入注册表时为 `true` |
+| `needsProjectUpgrade` | 注册表事实已刷新，但稳定源码入口缺失或仍为旧结构时为 `true` |
+| `apiFilePath` / `clientFilePath` / `sdkConfigPath` | 稳定入口与 SDK 路由路径 |
+| `modelRegistryPath` / `modelRuntimePath` | 注册表模式下的生成文件路径 |
 | `modelCount` / `datasetCount` | 模型数量 |
 
 多应用时 `data.apps[]` 为上述对象的数组。

package/skills/rabetbase/guides/typescript-sdk.md

@@ -18,6 +18,15 @@
 
 生成或更新项目里的 `src/api/api.ts` / `client.ts` 时，先 `rabetbase api pull --format compress`，再遵守 [`sdk-client-generation.md`](sdk-client-generation.md)。浏览器子应用的默认 client 是 Cookie + `...LOVRABET_SDK_CONFIG`，不要把下面的服务端 `accessKey` 示例写进 `src/api/client.ts`。
 
+## 多 profile 的调用边界
+
+CLI 生成的多 profile 注册表用于**同一份代码在不同节点分别运行**：当前 Runtime Domain 必须且只能选中一个 profile，随后业务代码通过同一 alias 使用该 profile 的 `datasetCode`。它不表示一个浏览器实例能同时查询多个节点。
+
+- 不在业务代码中读取 `datasetCodes`、指定另一个 profile，或硬编码任一节点的 DatasetCode。
+- 当前 profile 没有某 alias 时，让 SDK 抛出 `MODEL_NOT_FOUND`；节点独有功能可先检查生成入口导出的 `LOVRABET_PROFILE_NAME`，不得回退默认 profile。
+- 不在浏览器中创建多个跨 Domain client 或转发 Cookie、AccessKey、token。确需跨节点聚合时，由可信服务端或 Backend Function 按明确授权编排。
+- 只需分别验证节点数据时，使用对应项目 profile 和运行态工具逐端验证，不把它实现成业务前端的跨节点调用。
+
 ## 初始化规则
 
 必须使用 `createClient` 命名导出，禁止使用 `new LovrabetClient()`：

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-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-project-create.md

@@ -51,8 +51,8 @@ rabetbase project create my-project --appcode <code>
 **关键边界：**
 
 - 当前目录非空时不得覆盖、移动或删除已有内容，应报告冲突。
-- `needsAgentMerge` 只表示已有 TypeScript 被保留，是检查提示，不代表必须改写文件；仅在模型事实存在差异时合并。
-- `--force --yes` 只用于首次脚手架拉取明确失败，或用户明确要求放弃本地定制的场景。
+- `needsProjectUpgrade` 表示模型事实已刷新，但已有项目尚未安装稳定源码入口；新建项目模板正常不会出现该状态。
+- `--force --yes` 在注册表模式只用于确认远端空清单，不用于源码迁移。
 - 此意图只授权本地工程创建与平台事实读取，不授权修改线上业务数据或平台资源。
 
 `api pull` 的单应用/项目应用清单输出结构见 [`rabetbase-api-pull.md`](rabetbase-api-pull.md)，TypeScript 合并规则见 [`sdk-client-generation.md`](../guides/sdk-client-generation.md)。Agent 可根据实际输出选择检查、修复和验证方式。
@@ -70,7 +70,7 @@ rabetbase project create my-project --appcode <code>
 - 交互与非交互模式使用同一创建流程，都会安装依赖、格式化代码并写入项目配置
 - 项目模板从 CDN 下载并校验 SHA-256；CDN 不可用、模板不兼容或校验失败时命令停止，修复后重试
 - 新项目中的 `.rabetbase.json` **只继承**全局中的少量偏好及 `region` / Domain 路由配置，**不会**把全局的 `apps` / `defaultApp` 复制进新项目
-- `src/api/sdk-config.ts` 与 `rabetbase.domain-routing.json` 只生成浏览器可公开的最终路由，不会写入 `cookie`、`accessKey` 等认证配置；`rabetbase run start|dev|build|preview` 会在执行脚本前刷新公开 Domain 快照，也可用 [`project domain-routing-sync`](rabetbase-project-domain-routing-sync.md) 立即显式刷新。`api.ts` / `client.ts` 仅在缺失时由 CLI 写脚手架，已有文件按 [`sdk-client-generation.md`](../guides/sdk-client-generation.md) 更新；若项目创建时首次拉取失败，按 CLI 提示执行 `rabetbase api pull --force --yes` 完成占位脚手架初始化
+- `src/api/sdk-config.ts` 与 `rabetbase.domain-routing.json` 只生成浏览器可公开的最终路由，不会写入 `cookie`、`accessKey` 等认证配置；`rabetbase run start|dev|build|preview` 会在执行脚本前刷新公开 Domain 快照，也可用 [`project domain-routing-sync`](rabetbase-project-domain-routing-sync.md) 立即显式刷新。新项目模板已经包含稳定 `api.ts` / `client.ts`；若首次拉取失败，修复登录或连接后执行普通 `rabetbase api pull --format compress` 刷新占位注册表
 
 | 当前有效路由 | `src/api/sdk-config.ts` |
 |--------------|-------------------------|

package/skills/rabetbase/references/rabetbase-project-upgrade.md

@@ -1,6 +1,8 @@
 # project upgrade
 
-从 lovrabet-cli 迁移到 rabetbase-cli。
+升级已有项目的 SDK 依赖与应用源码结构。新项目继续使用 `project create`；Dataset 事实刷新继续使用 `api pull`。
+
+`.lovrabet.json`、`.lovrabet/` 与 Lovrabet Skill 属于 Lovrabet 运行态 CLI，可与 Rabetbase 项目配置和源码共存。该命令不会读取、迁移、改写或删除这些运行态资产。
 
 ## 命令
 
@@ -8,6 +10,9 @@
 # 交互模式（先分析 → 展示报告 → 确认 → 执行）
 rabetbase project upgrade
 
+# 只查看完整迁移计划，不写文件
+rabetbase project upgrade --dry-run
+
 # 自动模式（跳过确认）
 rabetbase project upgrade --yes
 ```
@@ -17,27 +22,33 @@ rabetbase project upgrade --yes
 | Flag | 类型 | 必填 | 默认 | 说明 |
 |------|------|------|------|------|
 | `--yes` | boolean | 否 | `false` | 跳过确认提示，直接执行 |
+| `--dry-run` | boolean | 否 | `false` | 只输出依赖和源码升级计划 |
 
 ## 执行流程
 
-两阶段模式：先分析 → 展示报告 → 确认 → 执行 6 步：
+两阶段模式：先分析 → 展示报告 → 确认 → 执行 2 步：
 
 | 步骤 | 操作 | 说明 |
 |------|------|------|
-| 1 | 配置文件迁移 | 旧配置（`.lovrabet.json` 等）→ `.rabetbase.json`，旧文件备份为 `.bak` |
-| 2 | 删除 `.lovrabet/` | 移除旧的工作目录 |
-| 3 | 删除旧 IDE skill 文件 | 移除 `.cursor/rules/lovrabet_rules.mdc`、`.claude/skills/lovrabet` 等 |
-| 4 | 清理 MCP 配置 | 从 `.cursor/mcp.json` 移除引用 `@lovrabet/dataset-mcp-server` 的条目 |
-| 5 | 移除旧 skill | 清理旧的 Lovrabet Skill 安装记录 |
-| 6 | 安装新 skill | `npx skills add lovrabet/rabetbase -g -y` |
+| 1 | 升级 SDK 依赖 | 将已有 `@lovrabet/sdk` 依赖更新到当前维护版本 |
+| 2 | 升级应用源码 | 迁移稳定 API 入口、模型注册表、运行时选择器和项目 Domain 路由 |
+
+## 源码迁移安全规则
+
+- 先执行 `rabetbase project upgrade --dry-run`；确认 `apiArchitecture.groups[].files[]` 的动作后再正式执行。
+- 缺失文件直接创建；可识别的旧 CLI 生成文件先备份到 `.rabetbase/project-upgrade/api-model-registry-v2/backups/` 再替换。
+- 发现业务定制的 `api.ts` / `client.ts` 时不覆盖原文件，在 `candidates/` 下写入候选文件，并返回 `manualMergeRequired: true`。
+- 旧 `api.ts` 中可识别的 Dataset 事实迁入 `models.generated.ts`，迁移后再运行 `rabetbase api pull --format compress` 刷新远端事实。
+- 多个未配置 `apiGroup` 且共用同一 `apiDir` 的历史 profile 保留 `[name-]api.ts` / `[name-]client.ts`，不会被静默归并。
+- 命令可重复执行；已是最新稳定入口时不重复改写。
 
 ## 分析报告
 
 执行前会扫描并展示：
-- 旧配置文件路径和待迁移字段
-- 旧文件/目录列表
-- MCP 配置中待清理的条目
-- 是否需要 skill 替换
+- `@lovrabet/sdk` 是否需要更新
+- 每个 API 目录的 profile、文件动作、备份或候选文件路径
+
+不会把 `.lovrabet.json`、`.lovrabet/`、Lovrabet Skill 或 Lovrabet 的 IDE 配置列为待清理项。
 
 ## 输出
 
@@ -49,7 +60,7 @@ rabetbase project upgrade --yes
 ## 触发方式
 
 - 手动执行：`rabetbase project upgrade`
-- 显式执行：`rabetbase project upgrade` 检测并迁移旧配置
+- 已有应用需要采用当前源码架构：先 `rabetbase project upgrade --dry-run`，再正式升级
 
 ## 参考
 

package/skills/rabetbase.manifest.json

@@ -2,8 +2,8 @@
   "schemaVersion": 1,
   "name": "rabetbase",
   "packageName": "@lovrabet/rabetbase-cli",
-  "packageVersion": "2.5.3-beta.2",
-  "skillVersion": "2.5.3-beta.2",
+  "packageVersion": "2.5.3-beta.3",
+  "skillVersion": "2.5.3-beta.3",
   "files": [
     "SKILL.md",
     "guides/approval-flow-development-workflow.md",
@@ -61,6 +61,7 @@
     "references/rabetbase-database-template.md",
     "references/rabetbase-dataset-business-group-update.md",
     "references/rabetbase-dataset-business-groups.md",
+    "references/rabetbase-dataset-cross-relations.md",
     "references/rabetbase-dataset-delete.md",
     "references/rabetbase-dataset-detail.md",
     "references/rabetbase-dataset-extend-update.md",
@@ -146,5 +147,5 @@
     "references/rabetbase-user-account.md",
     "references/rabetbase-workspace.md"
   ],
-  "digest": "bdb1237d11f707a54a1a189d00c313b8cf7f4ac4f41e9ec7d2aec7e187edbaa9"
+  "digest": "fb687c0d57936cfcba5e4f4d395e8695309e549ce848c5834befbade117e83e8"
 }