@lovrabet/rabetbase-cli 2.4.7 → 2.5.0-beta.2

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

@@ -1,24 +1,24 @@
 # api pull
 
-拉取当前 App 下所有数据集（Dataset）的元信息，生成 TypeScript API 客户端代码到 `src/api/` 目录。
+拉取当前 App 下所有数据集（Dataset）的元信息，刷新 `src/api/sdk-config.ts`，并在 `api.ts` / `client.ts` **缺失时**写入 Cookie-first 脚手架。
 
-生成的代码包含每个 Dataset 的 Model 类，可直接用于 SDK 查询，无需手动调用 HTTP 接口。
+已有 TypeScript **不会被覆盖**。Agent 必须用返回的 `data.models` 按 [`sdk-client-generation.md`](../guides/sdk-client-generation.md) 更新 `api.ts` / `client.ts`。人类若要重新得到脚手架，删除对应文件后再跑本命令。
 
 ## 命令
 
 ```bash
-# 拉取并生成 API 代码（默认 ./src/api/）
-rabetbase api pull
+# 拉取事实并刷新 sdk-config.ts（默认 ./src/api/）
+rabetbase api pull --format compress
 
 # 指定输出目录
-rabetbase api pull --output ./src/generated/api/
+rabetbase api pull --output ./src/generated/api/ --format compress
 
 # 多应用：默认只解析「项目级」apps；与全局合并配置一起拉取时加 --global
-rabetbase api pull --global
+rabetbase api pull --global --format compress
 
 # 多应用模式：指定某个应用
-rabetbase api pull --app order
-rabetbase api pull --appcode app-order-001
+rabetbase api pull --app order --format compress
+rabetbase api pull --appcode app-order-001 --format compress
 ```
 
 ## 参数
@@ -26,9 +26,10 @@ rabetbase api pull --appcode app-order-001
 | 参数 | 说明 |
 |------|------|
 | `--output <dir>` | 输出目录，默认 `./src/api/` |
-| `--global` | 多应用时从「全局+项目」合并配置解析 `apps`（默认仅项目级 `apps`）。若项目配置了 `inherit: false`，见下节 |
+| `--global` | 多应用时显式从「全局+项目」双层解析 `apps`；默认仅项目级 `apps` |
 | `--app <name>` | 多应用模式下，指定应用名称 |
 | `--appcode <code>` | 直接指定 appcode，跳过配置查找 |
+| `--format compress\|json` | 结构化信封。Agent 应读 `data.models`，不要刮 stderr |
 
 ## 多应用过滤
 
@@ -37,31 +38,43 @@ rabetbase api pull --appcode app-order-001
 - **加 `--app <name>`**：仅拉取指定应用
 - **加 `--appcode <code>`**：反查到对应 app profile，使用其 cookie/env/apiDir
 
-## 与 `inherit` 的关系
+## 配置作用域
 
-项目 `.rabetbase.json` 的 `inherit` 字段控制配置合并行为：
+- 默认只从项目文件解析 `apps`，同时可从全局白名单继承 cookie/accessKey 等标量配置。
+- `--global` 显式从全局和项目双层读取 apps；项目同名项覆盖全局同名项。
+- `inherit` 不是受支持的配置项。
 
-- **省略**（默认）：项目主导，仅从全局白名单继承 cookie/accessKey/locale/format/riskLevel/pageSize，不继承 apps/defaultApp/appcode。`--global` 仍可看到全局 apps（多应用列表从双层直接取）。
-- **`true`**：全量合并全局+项目（旧行为，需显式开启）。
-- **`false`**：完全隔离，不继承任何全局字段。
+## CLI 实际写入
 
-此时：
+| 文件 | 行为 |
+|------|------|
+| `sdk-config.ts` | **每次刷新**。只含 `region` / `runtimeDomain`，不含凭证 |
+| `<prefix>-api.ts` | 文件缺失时写入脚手架（含当前 `models`）；已存在则跳过 |
+| `<prefix>-client.ts` | 文件缺失时写入 Cookie-first `createClient`；已存在则跳过 |
 
-- **`api pull` 使用的 cookie、apiDir、appcode 等**均来自**项目文件**（默认行为下 cookie/accessKey 仍可从全局白名单继承）。
-- **`--global` 多应用列表**始终从全局+项目双层取 apps，不受 inherit 限制。
+默认 `prefix` 为空（单应用），多应用非 default 应用使用应用名作为 prefix。
 
-## 输出文件
+`project create` 在拷贝空 demo 脚手架后会覆盖写入一次 TypeScript，以便带上真实 models。日常 `api pull` 遇到已有 `api.ts` / `client.ts` 时跳过，只刷新 `sdk-config.ts` 并返回 `data.models`。
 
-| 文件 | 说明 |
-|------|------|
-| `<prefix>-api.ts` | 数据模型定义（datasetCode → Model 映射） |
-| `<prefix>-client.ts` | SDK 客户端初始化代码 |
+## 输出（单应用 `data`）
 
-默认 `prefix` 为空（单应用），多应用非 default 应用使用应用名作为 prefix。
+| 字段 | 说明 |
+|------|------|
+| `appCode` | 当前应用 |
+| `configName` | `"default"` 或具名应用名（不含 TS 引号） |
+| `isDefaultConfig` | 默认应用为 `true` |
+| `models[]` | `datasetCode` / `tableName` / `name` / `alias` |
+| `sdkRouting` | `{ region?: "id", runtimeDomain?: string }` |
+| `files.api` / `files.client` / `files.sdkConfig` | `{ path, action }`：`created` / `overwritten` / `preserved` / `refreshed` |
+| `needsAgentMerge` | 任一 TypeScript 被 `preserved` 时为 `true` |
+| `apiFilePath` / `clientFilePath` / `sdkConfigPath` | 与 `files.*.path` 相同 |
+| `modelCount` / `datasetCount` | 模型数量 |
+
+多应用时 `data` 为 `{ apps, succeeded, failed }`。
 
 ## 生成标识符
 
-`api pull` 遵循 [`best-practices.md`](../guides/best-practices.md) 的动态标识符原则，确保生成的 TypeScript 标识符合法且稳定。数字开头的 App Namespace 使用 `APP` 领域前缀，运行时 AppCode 保持不变；该前缀不适用于其他代码生成场景。
+脚手架路径遵循 [`best-practices.md`](../guides/best-practices.md) 的动态标识符原则。数字开头的 App Namespace 使用 `APP` 领域前缀，运行时 AppCode 保持不变。
 
 ## 前置条件
 
@@ -71,12 +84,14 @@ rabetbase api pull --appcode app-order-001
 ## 示例
 
 ```bash
-# 单应用：生成到 ./src/api/
-rabetbase api pull
+# 单应用：刷新 sdk-config.ts；缺失则写 api.ts/client.ts
+rabetbase api pull --format compress
 
-# 多应用 order：生成到 ./src/api/ 并使用 order- 前缀
-rabetbase api pull --app order
+# 多应用 order
+rabetbase api pull --app order --format compress
 
 # 独立输出目录
-rabetbase api pull --output ./src/generated/api/
+rabetbase api pull --output ./src/generated/api/ --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`（或同目录下首个匹配的旧名）与**项目**当前目录下的配置文件。
+默认列出**本地配置视图**，与 CLI 运行时一致：合并全局 `~/.rabetbase.json` 与从当前目录向父目录解析到的项目 `.rabetbase.json`。旧 `.lovrabet.json` / `.lovrabetrc` 不会自动参与配置发现。
 加 `--remote` 时改为查询**平台目录视图**：当前登录账号在平台上可访问的应用，不读取或修改本地 app 配置。
 
 - **不加 flag**：合并视图（global + project）。
@@ -38,7 +38,7 @@ rabetbase app list --remote
 | 字段 | 说明 |
 |------|------|
 | `items` | 应用条目数组 |
-| `meta` | **合并视图**：`globalPath`、`projectPath`、`defaultApp`（无命名默认时为**有效 appcode**）、`defaultAppSource`（`project` \| `global` \| `null`）。**`--global` / `--project`**：`scope`、`configPath` |
+| `meta` | **合并视图**：`globalPath`、`projectPath`、`defaultApp`（唯一 app 时为其 alias）、`defaultAppSource`（显式配置来源；隐式单应用为 `null`）。**`--global` / `--project`**：`scope`、`configPath` |
 
 每个 `items[]` 元素除 `name`、`appcode`、`env` 等外，另有：
 

package/skills/rabetbase/references/rabetbase-auth-login.md

@@ -25,12 +25,14 @@ rabetbase auth login --help
 
 ## 行为
 
-1. 检查本机是否已有有效 session。
-2. 无有效 session 时启动本地 OAuth 回调服务。
+1. 使用 `rabetbase config init` 已配置的节点与 Domain。
+2. 检查本机是否已有有效 session，无有效 session 时启动本地 OAuth 回调服务。
 3. 交互式模式会自动打开浏览器；非交互 `--yes` 模式只打印登录 URL。
 4. 用户授权成功后，CLI 保存 cookie 并输出登录成功。
 5. 10 分钟内未完成授权时，登录服务退出，需要重新执行命令。
 
+`auth login` 只负责认证，不接受 region 或 Domain 参数。节点调整统一使用 `config init/set/delete`。
+
 ## 常见错误
 
 ```text

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

@@ -39,7 +39,9 @@ rabetbase bff push --type HOOK --name beforeFilter --format json
 
 `bff push` 负责同步脚本，不等价于业务逻辑验证。推送前按 [`backend-function.md`](../guides/backend-function.md) 自检，尤其确认：
 
-- 数据集模型键使用 `"dataset_" + 32 位数据集 code`
+- `DB_TABLE` 数据集优先通过 `context.client.models.byTable("<物理表名>")` 访问；同名表跨 dblink 时传入已确认的 `{ dblinkId }`
+- `METADATA` 数据集使用 `"dataset_" + 数据集 code`；`DB_TABLE` 使用该形式时属于兼容路径
+- Backend Function 的 Custom SQL 默认使用 `context.client.sql.byName("<唯一 SQL 名>").execute({ params })`；名称不存在或重名时先处理 `SQL_NAME_NOT_FOUND` / `SQL_NAME_AMBIGUOUS`
 - 写入字段、必填字段、枚举 `options[].value` 来自当前 `dataset detail`
 - `filter()` 结果从 `.tableData` 读取
 - `create()` 返回新记录 ID，不访问 `created.id`

package/skills/rabetbase/references/rabetbase-codegen-sql.md

@@ -25,8 +25,10 @@ rabetbase codegen sql --sqlcode 2305f915-dd48cd4c > ./src/api/getUserList.ts
 
 ## 提示
 
-- `--target bff` 生成的代码使用 `context.client.sql.execute()`，注意 Backend Function 中 SQL 返回直接是数组
+- `--target bff` 生成的代码使用 `context.client.sql.byName(sqlName).execute({ params })`；生成时仍以 `--sqlcode` 定位 SQL 元数据，但产物不硬编码 `sqlCode`。Backend Function 中 SQL 返回直接是数组
 - `--target sdk` 生成的代码使用 `client.sql.execute()`，返回 `{ execSuccess, execResult }`
+- `sqlName` 在当前应用内必须唯一；未找到或重名时，运行时返回 `SQL_NAME_NOT_FOUND` 或 `SQL_NAME_AMBIGUOUS`，不会任选一个 SQL
+- `--target bff` 产物默认使用语义 SQL 名，`sql.execute({ sqlCode, params })` 是 Backend Function 的兼容调用方式；前端 SDK 产物使用 `sqlCode`
 
 ## 参考
 

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

@@ -6,7 +6,7 @@
 
 它**不是**平台应用目录。若要查看当前登录账号在平台上能访问哪些应用，应使用 `rabetbase app list --remote`，而不是直接查看 `.rabetbase.json`。
 
-兼容旧名：`.lovrabet.json`、`.lovrabetrc`（按优先级 `.rabetbase.json` > `.lovrabet.json` > `.lovrabetrc`，首个存在的生效）。
+只自动读取 `.rabetbase.json`，不会把 `.lovrabet.json` 或 `.lovrabetrc` 当作 Rabetbase 配置。旧文件需要迁移时，显式执行 `rabetbase project upgrade`。
 
 ## 初始化
 
@@ -14,15 +14,14 @@
 rabetbase workspace init --appcode <code>
 ```
 
-绑定当前目录到某个应用并写入 `.rabetbase.json`，采用 canonical 的 `apps + defaultApp` 结构；旧的顶层 `appcode` 仍兼容读取。首次安装后的全局引导用 `rabetbase init`。
+绑定当前目录到某个应用并写入 `.rabetbase.json`，采用 canonical 的 `apps` 结构；单应用自动选中且省略 `defaultApp`，旧的顶层 `appcode` 仍兼容读取。首次安装后的全局引导用 `rabetbase config init`。
 
 ## canonical 主模型
 
-当前推荐、也是所有新写入默认采用的结构，是 **`apps + defaultApp`**：
+当前推荐、也是单应用新写入默认采用的结构，是只有一个 profile 的 **`apps`**：
 
 ```json
 {
-  "defaultApp": "main",
   "apps": {
     "main": {
       "appcode": "app-xxxxxxxx",
@@ -47,6 +46,16 @@ CLI 对旧版顶层 `appcode` 仍兼容读取，但它已经不是推荐主模
 
 ### 完整字段
 
+下面分别展示字段形态；官方 `region` 模式与企业显式 Domain 模式不要混写。官方印尼节点只需：
+
+```json
+{
+  "region": "id"
+}
+```
+
+企业独立部署才显式提供 Domain：
+
 ```json
 {
   "appcode": "app-xxx",
@@ -61,13 +70,16 @@ CLI 对旧版顶层 `appcode` 仍兼容读取，但它已经不是推荐主模
   "template_base_url": "https://custom-cdn.example.com/dist",
   "apiDomain": "https://custom-api.example.com",
   "userDomain": "https://custom-user.example.com",
-  "runtimeDomain": "https://custom-runtime.example.com"
+  "runtimeDomain": "https://custom-runtime.example.com",
+  "skillDomain": "https://custom-skills.example.com",
+  "kbDomain": "https://custom-kb.example.com",
+  "appDomain": "https://custom-app.example.com"
 }
 ```
 
 ## 多应用模式
 
-一个项目对接多个 Lovrabet 应用时，使用 `apps` + `defaultApp`：
+一个项目对接多个 Lovrabet 应用时，才使用 `apps` + `defaultApp`：
 
 ```json
 {
@@ -87,7 +99,7 @@ CLI 对旧版顶层 `appcode` 仍兼容读取，但它已经不是推荐主模
 }
 ```
 
-每个 app profile 可单独覆盖普通顶层字段。`riskLevel` 是安全例外：默认值为 `write`，全局、项目与 profile 决定基础上限并取最严格值；环境变量只能继续收紧，不能提权。CLI 运行时根据 `--app <name>` 或 `defaultApp` 选择激活的 profile。权限不足时只能提醒用户手动编辑配置；Agent 和自动化脚本不得自行修改 `riskLevel` 或尝试提权。
+每个 app profile 可单独覆盖普通顶层字段。唯一 app 自动激活；两个及以上 app 必须通过 `--app <name>` 临时选择，或用 `defaultApp` 持久选择，CLI 不按 JSON key 顺序猜测。`riskLevel` 是安全例外：默认值为 `write`，全局、项目与 profile 决定基础上限并取最严格值；环境变量只能继续收紧，不能提权。权限不足时只能提醒用户手动编辑配置；Agent 和自动化脚本不得自行修改 `riskLevel` 或尝试提权。
 
 管理命令（声明式 flags，非位置参数）：
 
@@ -105,22 +117,25 @@ rabetbase workspace remove product --yes
 
 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `appcode` | string | — | 顶层单应用兼容字段。新写入优先使用 `apps + defaultApp`。兼容旧名 `app` |
+| `appcode` | string | — | 顶层单应用兼容字段。新写入优先使用 `apps`。兼容旧名 `app` |
 | `env` | string | `"production"` | 环境。可选值：`production`、`daily`（配置文件若仍为旧值 `online`，加载时会规范为 `production`） |
-| `locale` | string | `"en-US"` | 语言设置 |
+| `locale` | string | `"en-US"` | 应用本地化设置（不是 CLI 语言；目前命令尚未消费） |
 | `cookie` | string | — | 内联 session cookie。设置后优先于 `~/.lovrabet/cookie` 文件 |
 | `accessKey` | string | — | Access Key 认证（预留，未来替代 cookie） |
 | `format` | string | — | 默认输出格式。可选值：`json`、`pretty`、`compress`。不设则命令默认 `compress` |
 | `pageSize` | number | — | 默认分页大小，用于 `sql list` 等分页命令 |
 | `riskLevel` | string | `"write"` | 允许执行的最高风险等级。可选值：`read`、`write`、`high-risk-write`。兼容旧名 `maxRisk` |
-| `inherit` | boolean | 省略 | 配置继承模式。**省略**（默认）：项目主导，仅从全局白名单继承 cookie/accessKey/locale/format/riskLevel/pageSize，不继承 apps/defaultApp/appcode。**`true`**：全量合并全局+项目（旧行为，需显式开启）。**`false`**：普通字段完全隔离；全局 `riskLevel` 仍作为不可绕过的上限 |
 | `apiDir` | string | `"./src/api"` | `api pull` 生成代码的输出目录 |
+| `region` | string | `"cn"`（省略） | 当前开放的官方节点快捷配置：`cn`、`id` |
 | `template_base_url` | string | 平台默认 CDN | 模板 CDN 基础 URL，一般无需修改 |
-| `defaultApp` | string | — | 多应用模式下的默认应用名称 |
+| `defaultApp` | string | — | 多应用模式下的默认应用名称；单应用省略 |
 | `apps` | object | — | 多应用配置。key 为应用名，value 为 AppProfile（见下方） |
-| `apiDomain` | string | 平台默认 | 自定义 API 域名（独立部署场景）。覆盖后所有 API 请求使用此域名 |
+| `apiDomain` | string | 节点默认 | 普通研发平台 API 域名 |
 | `userDomain` | string | 平台默认 | 自定义用户域名 |
 | `runtimeDomain` | string | 平台默认 | 自定义运行时域名 |
+| `skillDomain` | string | 节点默认 | SkillHub HTTPS origin 覆盖 |
+| `kbDomain` | string | 跟随 `apiDomain` / 节点 API 默认值 | 企业知识库 HTTPS origin 覆盖；显式配置时优先，`runtimeDomain` 不参与回退 |
+| `appDomain` | string | 节点默认 | 工作台、页面编辑器和发布页面域名 |
 
 ### AppProfile 字段（`apps.*` 内的每个应用）
 
@@ -134,7 +149,7 @@ rabetbase workspace remove product --yes
 | `format` | string | 覆盖顶层 `format` |
 | `pageSize` | number | 覆盖顶层 `pageSize` |
 | `riskLevel` | string | 只能继续收紧顶层 `riskLevel`，不能提权 |
-| `locale` | string | 覆盖顶层 `locale` |
+| `locale` | string | 覆盖顶层 `locale`（应用本地化；目前命令尚未消费） |
 
 ## 优先级
 
@@ -174,16 +189,19 @@ CLI flag (--appcode, --env, --format, --app ...)
 
 | 作用域 | 查找目录 | 文件名优先级 |
 |--------|---------|------------|
-| 项目级 | `process.cwd()` | `.rabetbase.json` > `.lovrabet.json` > `.lovrabetrc` |
-| 全局级 | `~`（用户 HOME） | 同上 |
+| 项目级 | 从 `process.cwd()` 向父目录查找 | 仅 `.rabetbase.json` |
+| 全局级 | `~`（用户 HOME） | 仅 `.rabetbase.json` |
 
-合并策略由项目级 `inherit` 字段控制（三态）：
+配置合并使用固定模型，`inherit` 不是受支持的配置项：
 
-- **省略 `inherit`（默认，项目主导）**：项目级配置自给自足；仅从全局白名单继承 `cookie`、`accessKey`、`locale`、`format`、`riskLevel`、`pageSize`，**不继承** `apps` / `defaultApp` / `appcode` / `env` 等业务字段。普通字段由项目级显式值覆盖；`riskLevel` 始终取全局与项目顶层的更严格值。
-- **`inherit: true`（显式全量合并）**：标量字段项目级覆盖全局级；`apps` 深度合并（项目同名覆盖全局同名，其余保留）；`defaultApp` 仅当项目级显式声明时才覆盖全局级。等价于历史默认行为，需要跨项目共享全局 `apps` 时显式开启。
-- **`inherit: false`（普通字段完全隔离）**：业务与偏好字段只使用项目级值；安全例外是全局 `riskLevel` 仍参与最严格上限计算，项目不能借此提权。
+- 项目显式值覆盖全局显式值。
+- 项目存在时，仅从全局白名单继承 `cookie`、`accessKey`、`locale`、`format`、`riskLevel`、`pageSize`、`region` 和六个 Domain（`userDomain` / `apiDomain` / `runtimeDomain` / `skillDomain` / `kbDomain` / `appDomain`）；不继承 `apps` / `defaultApp` / `appcode` / `env`。
+- `apps` / `defaultApp` 始终项目隔离，避免研发写操作落到全局应用。
+- `region` 是 Domain fallback profile；显式 Domain 按普通 key 继承和覆盖，不会被 `region` 清除或屏蔽。
+- `riskLevel` 始终取全局与项目顶层的更严格值，项目不能借配置覆盖提权。
+- 旧配置中的 `inherit` 会被忽略，可用 `rabetbase config delete inherit` 清理。
 
-> **为什么默认改成项目主导**：避免 `~/.lovrabet.json` 中的 `defaultApp` / `apps` 在用户进入空白目录或新项目时被无声继承（曾导致 menu asset-update 误改其他应用资源）。`api list` / `api pull` / `app list` 仍可通过 `--global` 显式查看合并视图。
+> **为什么固定为项目主导**：避免全局 `.rabetbase.json` 中的 `defaultApp` / `apps` 在用户进入项目后被无声继承（曾导致写操作误选应用）。`api list` / `api pull` 仍可通过 `--global` 显式读取双层 apps。
 
 ## 示例
 
@@ -242,26 +260,36 @@ rabetbase dataset list --app product
 
 ```bash
 # 写入项目级配置（默认；须在能解析到项目 .rabetbase.json 的目录下执行）
-rabetbase config set apiDomain https://custom-api.example.com
-rabetbase config set env daily
+rabetbase config set --key apiDomain --value https://custom-api.example.com
+rabetbase config set --key env --value daily
 
 # 写入全局配置（任意目录）
-rabetbase config set apiDomain https://custom-api.example.com --global
+rabetbase config set --key apiDomain --value https://custom-api.example.com --global
 ```
 
 `config set` **默认写入项目**配置文件（当前工作目录能解析到 `.rabetbase.json` 等）；加 **`--global`** 则写入 **`~/.rabetbase.json`**。
 
-若当前目录**没有**项目配置文件且**未**指定 `--global`，CLI **拒绝执行**并提示使用 `--global` 或先 `rabetbase init`，**不会**静默改全局。
+若当前目录**没有**项目配置文件且**未**指定 `--global`，CLI **拒绝执行**并提示使用 `--global` 或先 `rabetbase workspace init --appcode <code>`，**不会**静默改全局。
 
 ### config get
 
 读取配置项（读取合并后的值）：
 
 ```bash
-rabetbase config get apiDomain
+rabetbase config get --key apiDomain
 # 输出: https://custom-api.example.com
 ```
 
+### config delete
+
+删除当前作用域显式配置的 key；命令幂等，key 已不存在时仍成功返回。默认删除项目层，`--global` 删除全局层。`riskLevel` 受保护，不能通过 CLI 删除。
+
+```bash
+rabetbase config delete apiDomain
+rabetbase config delete apiDomain --global
+rabetbase config delete inherit  # 清理已移除的旧字段
+```
+
 ### config list
 
 以 JSON 格式输出当前合并后的完整配置：
@@ -284,13 +312,30 @@ rabetbase doctor
 
 ## 独立部署场景
 
-如果 Lovrabet 部署在自定义域名下，通过 `apiDomain` / `userDomain` / `runtimeDomain` 覆盖默认域名：
+官方节点使用内置完整映射，默认 `cn` 可省略：
+
+```bash
+rabetbase config set --key region --value id --global
+```
+
+企业独立部署推荐通过连接配置入口一次性初始化：
+
+```bash
+rabetbase config init --domain-config ./lovrabet-domains.json
+```
+
+该文件只接收 `userDomain`、`apiDomain`、`runtimeDomain`、`skillDomain`、`kbDomain`、`appDomain`；值必须是无 path/query/fragment 的 HTTPS origin。完整行为与命令行 flags 见 [`rabetbase config init`](rabetbase-init.md)。
+
+也可以逐项覆盖：
 
 ```bash
 # 写入全局配置（所有项目生效）
-rabetbase config set apiDomain https://your-api.example.com --global
-rabetbase config set userDomain https://your-user.example.com --global
-rabetbase config set runtimeDomain https://your-runtime.example.com --global
+rabetbase config set --key apiDomain --value https://your-api.example.com --global
+rabetbase config set --key userDomain --value https://your-user.example.com --global
+rabetbase config set --key runtimeDomain --value https://your-runtime.example.com --global
+rabetbase config set --key skillDomain --value https://your-skills.example.com --global
+rabetbase config set --key kbDomain --value https://your-kb.example.com --global
+rabetbase config set --key appDomain --value https://your-app.example.com --global
 ```
 
-优先级：配置文件中显式设置 > 环境变量 > 默认平台域名。项目级配置可覆盖全局配置。
+官方模式：`region` 内置完整 Domain 映射，默认 `cn`，配置文件可省略；`id` 只需保存 `"region": "id"`。企业独立部署模式才保存显式 Domain。项目级配置可覆盖全局配置；默认项目合并会继承全局节点配置。

package/skills/rabetbase/references/rabetbase-dataset-business-group-update.md

@@ -18,14 +18,25 @@ rabetbase dataset business-group-update \
 
 确认 dry-run 结果无误后再去掉 `--dry-run` 执行。
 
+清空当前业务场景分组：
+
+```bash
+rabetbase dataset business-group-update \
+  --code 1a90dbff5f094a9a89936fa99b10984c \
+  --business-group ungrouped \
+  --expect-business-group "旧分组" \
+  --dry-run \
+  --format compress
+```
+
 ## 参数
 
 | Flag | 必填 | 说明 |
 | --- | --- | --- |
 | `--appcode <code>` | 否 | 目标应用编码；未配置默认 app 时必填 |
 | `--code <code>` | 是 | Dataset code，32 位 hex UUID |
-| `--business-group <name>` | 是 | 目标业务场景分组；空字符串表示清空 |
-| `--expect-business-group <name>` | 否 | 当前业务场景分组保护；不匹配即中止且不写入 |
+| `--business-group <name>` | 是 | 目标业务场景分组；保留值 `ungrouped` 表示清空 |
+| `--expect-business-group <name>` | 否 | 当前业务场景分组保护；使用 `ungrouped` 表示期望当前未分组；不匹配即中止且不写入 |
 | `--dry-run` | 否 | 只返回 before/after 预览，不执行写入 |
 | `--format <fmt>` | 否 | 输出格式，AI Agent 优先用 `compress` |
 
@@ -33,9 +44,9 @@ rabetbase dataset business-group-update \
 
 - 命令用 `--code` 定位 Dataset。
 - 当前值和写后校验都按 Dataset code 读取业务场景分组；不需要 `dblinkId`、`tableName` 或 `sourceType`。
-- `--business-group` 为空字符串时表示清空业务场景分组。
-- 回读到 `businessGroup` 为空字符串时表示未分组，是合法当前值。
-- `--expect-business-group` 用于保护当前值；不匹配时中止且不写入。
+- `--business-group ungrouped` 表示清空业务场景分组；`ungrouped` 是保留值，不能作为分组名称使用。
+- 平台原始详情可能以空字符串返回 `businessGroup`，也可能省略 `extend.businessGroup`；CLI 会将这两种形态统一归一化为空字符串，表示未分组。
+- `--expect-business-group` 用于保护当前值；当前未分组时传 `ungrouped`，不匹配时中止且不写入。
 - `--dry-run` 只预览 before/after，不执行写入。
 - 正式写入后会校验目标值已生效。
 - 当目标值和当前值一致时，命令返回 `changed=false`，不会执行写入。
@@ -70,7 +81,7 @@ rabetbase dataset business-group-update \
 ## 提示
 
 - 写入前必须先运行 `--dry-run`。
-- `businessGroup` 用于按业务场景组织 Dataset，而不是按数据库、表类型或服务名等技术结构分组。优先按业务场景命名并复用当前应用已有分组；需要跨领域消歧或沿用既有两级分组体系时，可使用 `<业务领域>---<业务场景>`，否则使用 `<业务场景>`。表数量不决定是否拆分层级。建议最多两级，层级不得为空或带首尾空白；空字符串表示清空。CLI 仅描述推荐格式并保持兼容，不额外拒绝历史非标准值。
+- `businessGroup` 用于按业务场景组织 Dataset，而不是按数据库、表类型或服务名等技术结构分组。优先按业务场景命名并复用当前应用已有分组；需要跨领域消歧或沿用既有两级分组体系时，可使用 `<业务领域>---<业务场景>`，否则使用 `<业务场景>`。表数量不决定是否拆分层级。建议最多两级，层级不得为空或带首尾空白；使用保留值 `ungrouped` 清空。CLI 仅描述推荐格式并保持兼容，不额外拒绝历史非标准值。
 - 推荐用 `--expect-business-group` 保护当前值。
 - 不确定 Dataset code 时，先用 `rabetbase dataset list --name <name> --format compress` 定位。
 - 业务场景分组只能使用本命令更新，不要通过 `dataset extend-update` 或 `/smartapi/dataset/update-driven-data` 修改。

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

@@ -97,7 +97,7 @@ rabetbase dataset detail --code <数据集编码> --format json --jq '.data.oper
 ## 提示
 
 - 写 SQL / Backend Function 前先调用此命令确认真实字段名、类型与枚举；关联关系统一看 **`dataset relations`**
-- `--alias` 需要先执行 `rabetbase api pull` 生成 `api.ts`
+- `--alias` 需要本地 `api.ts` 已有对应 alias（`api pull` 取事实后按 [`sdk-client-generation.md`](../guides/sdk-client-generation.md) 更新）
 - 横切数据访问流程、外键与性能：见 [`guides/data-api-guidelines.md`](../guides/data-api-guidelines.md)
 
 ## 参考

package/skills/rabetbase/references/rabetbase-db-analyze.md

@@ -4,7 +4,7 @@
 
 ## 何时用
 
-- **analyze-batch-plan**：增量表清单较多时，先预览确定性安全批次；不创建服务端任务
+- **analyze-batch-plan**：只要增量表清单非空，就先预览确定性安全批次；不因表少而跳过，也不创建服务端任务
 - **analyze-start**：接入新库或表结构大变后，同步到 Lovrabet（一次调用只启动一个任务）
 - **analyze-cancel**：任务卡住或误触，需要停掉当前分析
 - **analyze-status**：轮询任务状态，并读取 CLI 派生的终态、重试和耗时字段
@@ -70,7 +70,7 @@ rabetbase db analyze-status --id 10157 --plan <traceId> --format compress
 
 必须按 `index` 严格串行：每批独立调用一次 `analyze-start`，并保存一个独立 `planId`。当前批次为 `PENDING / RUNNING / RETRYING / CANCELING` 时继续查询同一 planId；`SUCCESS` 才直接进入下一批；`PARTIAL_SUCCESS` 记录失败事实后继续；`FAILED / CANCELLED` 停止整个批次编排；未知状态停止自动推进。
 
-如果 `analyze-start` 没有明确返回 `data.planId`，停止自动推进且不得盲目重试，因为请求结果可能不确定。全部批次结束后按 `db detail.tableCount` 的 200 表阈值决定直接读取或先执行 `db diff-refresh-start/status`，再执行完整 `db diff --all --changed-only`；只对仍在 `data.toAnalyzeTables` 的非删除表逐表串行恢复一次，最后按同一策略再读取一次完整 diff。
+如果 `analyze-start` 没有明确返回 `data.planId`，停止自动推进且不得盲目重试，因为请求结果可能不确定。全部批次结束后默认执行 `db diff-refresh-start/status`，再执行完整 `db diff --all --changed-only`，不根据 `tableCount` 跳过异步刷新；只有用户明确要求不分析、不刷新或只看现有结果时才直接读取。只对仍在 `data.toAnalyzeTables` 的非删除表逐表串行恢复一次，最后按同一策略再读取一次完整 diff。
 
 显式单批 `analyze-start --tables` 的持久化参数超过 1024 UTF-8 bytes 时，CLI 会在调用 API 前返回 validation error 并提示先运行 `db analyze-batch-plan`。960 是规划安全预算；960 至 1024 bytes 的显式单批仍允许启动。未传 `--tables` 的全量分析不受此保护影响。
 
@@ -101,7 +101,7 @@ rabetbase db analyze-status --id 10157 --plan <traceId> --format compress
 | `data.totalElapsedMs` | 从 `firstStartTime` 到 `endTime` 或当前查询时刻的 plan 墙钟耗时；缺少可靠时间戳时为 `null` |
 | `data.hasMultipleAttempts` | `firstStartTime` 与 `startTime` 都有效且不相同时为 `true`，表示服务端开启过后续执行尝试 |
 
-`PENDING / RUNNING / RETRYING / CANCELING` 与未知状态都不是终态。不要根据 `failedTables`、`retryCount` 或错误文案推测状态。`PARTIAL_SUCCESS` 只表示任务已到终态；必须按 200 表阈值刷新或直接复跑 `db diff --all --changed-only` 验证目标差异收敛，才能得出本轮分析完成结论。
+`PENDING / RUNNING / RETRYING / CANCELING` 与未知状态都不是终态。不要根据 `failedTables`、`retryCount` 或错误文案推测状态。`PARTIAL_SUCCESS` 只表示任务已到终态；默认必须异步刷新后复跑 `db diff --all --changed-only` 验证目标差异收敛，只有用户明确要求跳过分析/刷新时才直接读取现有结果，之后才能得出本轮分析完成结论。
 
 `analyze-status` 每次只查询一次。轮询时必须继续使用当前任务的同一 `planId`；查询超时、断网或临时 API 失败不等于分析失败，也不得触发新的 `analyze-start`。当前稳定任务状态中没有独立的 `TIMEOUT` 终态。
 

package/skills/rabetbase/references/rabetbase-db-detail.md

@@ -5,7 +5,7 @@
 ## 何时用
 
 - 已用 `db list` 拿到 `id`，需要比列表更全的字段
-- 读取 `tableCount`，按 200 张表阈值决定是否先刷新差异结果
+- 读取 `tableCount` 作为连接规模事实；不再用它决定是否先刷新差异结果
 - 需要当前 **`latestAnalysisTraceId`** 查询最新分析状态；取消已知任务时仍使用正在跟踪的原 planId
 
 ## 命令
@@ -24,7 +24,7 @@ rabetbase db detail --id 10157 --format compress
 
 ## 参考
 
-输出中的 `tableCount` 是当前连接表数量：不大于 200 时通常直接读取 `db diff`；大于 200 时建议先执行 `db diff-refresh-start/status`。字段缺失时不猜测数量，也不隐式刷新。
+输出中的 `tableCount` 是当前连接表数量，仅用于展示和排期。DBAgent 增量分析默认先执行 `db diff-refresh-start/status`，无论该字段大小或是否缺失；只有用户明确要求跳过分析/刷新时才直接读取现有 `db diff`。
 
 `datasetDependency.hasDependencies` 表示当前连接是否仍有有效 Dataset 依赖，`activeDatasetCount` 是依赖数量；明细见同级 `datasets`。
 

package/skills/rabetbase/references/rabetbase-db-diff-refresh.md

@@ -4,11 +4,11 @@
 
 ## 何时刷新
 
-- `db detail` 返回 `tableCount > 200`，读取差异前建议刷新。
-- 用户明确要求“实时刷新”或“强制刷新”，无论表数量多少都刷新。
-- `tableCount <= 200` 时服务端通常实时计算差异，默认不刷新。
+- DBAgent 增量分析工作流默认刷新，无论 `tableCount` 多少或是否缺失。
+- 用户明确要求“实时刷新”或“强制刷新”时执行刷新。
+- 只有用户明确要求“不需要分析”“不刷新”或“只看现有结果”时才跳过，并说明现有差异可能不是最新事实。
 
-刷新只影响默认 `db diff` 差异视角；`db diff --view all` 本身就是实时全表分页，不需要先刷新差异快照。
+刷新只影响默认 `db diff` 差异视角；`db diff --view all` 本身是实时全表分页，但在 DBAgent 增量分析工作流中仍默认先完成异步差异刷新，以形成一致、可跟踪的分析流程。
 
 ## 命令
 

package/skills/rabetbase/references/rabetbase-db-diff.md

@@ -6,7 +6,7 @@
 
 | 视角           | 命令                 | 服务端语义                                                                                              |
 |---|---|---|
-| 差异表（默认） | `db diff`            | 调用 `getDiffTableByPage`。表数量不大于 200 时服务端通常实时计算；大于 200 时可能读取最近一次差异快照。 |
+| 差异表（默认） | `db diff`            | 调用 `getDiffTableByPage`。服务端可能实时计算或读取最近差异快照；Agent 不根据表数量推断新鲜度。 |
 | 全部表         | `db diff --view all` | 调用实时分页接口，包含 `ALREADY_ANALYZED`，用于查看无差异表或手动选择重新分析。                         |
 
 `--all` 始终表示“聚合当前视角的全部分页”，不表示“全部表”。需要全部表必须显式传 `--view all`。
@@ -36,15 +36,12 @@ rabetbase db diff --id 10157 --view all --all --format compress
 
 ## 刷新决策
 
-先执行 `db detail --id <id>` 读取 `tableCount`：
+- DBAgent 增量分析工作流默认先按 [`db diff-refresh-start/status`](rabetbase-db-diff-refresh.md) 完成一次异步差异刷新，再读取 `db diff`。
+- 不根据 `tableCount` 的大小或缺失状态跳过刷新。
+- 只有用户明确要求“不需要分析”“不刷新”或“只看现有结果”时才直接读取，并说明结果可能不是最新事实。
+- 用户明确要求“实时刷新/强制刷新”时，同样执行默认异步刷新流程。
 
-- `tableCount <= 200`：直接读取 `db diff`；除非用户明确要求，否则不要刷新。
-- `tableCount > 200`：读取前建议按 [`db diff-refresh-start/status`](rabetbase-db-diff-refresh.md) 刷新差异快照。
-- 用户明确要求“实时刷新/强制刷新”：不考虑表数量，执行刷新。
-- 用户明确要求“不刷新/只看现有结果”：直接读取；大库需提示结果可能滞后。
-- `tableCount` 缺失：直接读取并说明新鲜度未知，不要因为未知而隐式发起写任务。
-
-`db diff` 是只读命令，绝不隐式启动刷新任务。
+`db diff` 命令自身仍是只读命令，不会在实现内部隐式启动刷新任务；这里要求的是 Agent 在调用 `db diff` 前显式编排 `db diff-refresh-start/status`。
 
 ## 机器可读摘要
 

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

@@ -24,7 +24,7 @@ rabetbase doctor check
 | Config JSON | 分别检测全局/项目配置文件是否为**合法 JSON**；非法时标红并给出解析错误（常见于尾随逗号、注释等，会导致该侧配置在合并时被忽略） |
 | Merged Config | 合并后的所有配置项（appCode / env / cookie / apiDir 等） |
 | Apps | 多应用模式下的应用列表及各自配置 |
-| API Endpoints | 最终生效的三个域名（apiDomain / userDomain / runtimeDomain） |
+| API Endpoints | 最终生效的 region 与六个域名（user / api / runtime / skill / kb / app） |
 | Auth | 登录状态及 cookie 有效性 |
 
 ## 典型场景