@lovrabet/rabetbase-cli 2.3.16-beta.7 → 2.4.1

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

@@ -0,0 +1,65 @@
+# bff push
+
+把本地 BFF 脚本上传到远端。
+
+> **风险等级：high-risk-write** — 必须显式 `--yes`。
+
+## 命令
+
+```bash
+rabetbase bff push --yes --format json
+rabetbase bff push --yes --type ENDPOINT --name getUserList --format json
+rabetbase bff push --type ENDPOINT --name getUserList --dry-run --format json
+rabetbase bff push --yes --type HOOK --name beforeFilter --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--type <type>` | string | 否 | — | 仅推指定类型：`COMMON` / `ENDPOINT` / `HOOK` |
+| `--name <name>` | string | 否 | — | 仅推指定函数名；传时必须搭配 `--type` |
+| `--force` | boolean | 否 | — | 忽略 hash 保护强制推送 |
+| `--dry-run` | boolean | 否 | — | 仅预览将要推送的本地脚本 |
+| `--yes` | boolean | 是 | — | 跳过高风险确认 |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
+
+## 输出
+
+返回：
+- `uploaded`
+- `skipped`
+- `failed`
+
+常见 `skipped` 原因：
+- `unchanged`
+
+`--dry-run` 时返回预览对象，包含本地 `filePath`、目标模式（`create` / `update`）和预期状态（如 `unchanged` / `would_push`）。
+
+## 推送前检查
+
+`bff push` 负责同步脚本，不等价于业务逻辑验证。推送前按 [`backend-function.md`](../guides/backend-function.md) 自检，尤其确认：
+
+- 数据集模型键使用 `"dataset_" + 32 位数据集 code`
+- 写入字段、必填字段、枚举 `options[].value` 来自当前 `dataset detail`
+- `filter()` 结果从 `.tableData` 读取
+- `create()` 返回新记录 ID，不访问 `created.id`
+- BFF 中没有使用前端 SDK 初始化能力，如 `createClient`、`registerModels`
+- 通知型 BFF 只使用已确认的 `configCode` / `audiences` / `message`，没有渠道地址、密钥、旧 MANUAL 参数或 `${...}` 模板表达式
+
+## 提示
+
+- 推送前先跑 `bff status`
+- `--dry-run` 不会上传远端，也不会改 lock
+- 精确推单个函数时用 `--type + --name`
+- HOOK 推送依赖数据集 alias / datasetCode 和 operationType/functionNode
+- HOOK 可挂载 `DB_TABLE` 或 `METADATA` 数据集；METADATA 不支持 SQL / aggregate 路径，脚本中使用平台返回的标准数据操作
+- 推送成功只代表脚本配置已同步到平台；如需确认最终运行效果，使用运行验证（例如 `lovrabet bff exec --name <functionName> --params '<json>' --format compress`）
+- 管理态已同步但运行态仍旧版本时，按传播延迟 / 缓存延迟处理：等待后重试，必要时对目标脚本精确执行 `--force` 推送；仍不生效时记录平台运行态缓存风险
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [bff-creation-workflow.md](../guides/bff-creation-workflow.md)
+- [backend-function.md](../guides/backend-function.md)
+- [conflict-detection.md](../guides/conflict-detection.md)

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

@@ -0,0 +1,63 @@
+# bff save（已退出主工作流）
+
+> `bff save` 不再作为当前 CLI 的主工作流命令使用。
+>
+> Agent 看到旧文档、旧脚本或用户口头提到 `bff save` 时，统一迁移到下面这套流程：
+>
+> - 本地创建：`rabetbase bff create`
+> - 查看状态：`rabetbase bff status`
+> - 预览上传：`rabetbase bff push --dry-run`
+> - 推送远端：`rabetbase bff push --yes`
+> - 拉取远端：`rabetbase bff pull`
+> - 删除脚本：`rabetbase bff delete --yes --target ...`
+
+## 迁移规则
+
+### 旧“新建并保存”
+
+旧思路：
+
+```bash
+rabetbase bff save --file ./scripts/getUserInfo.js --name getUserInfo --format json
+```
+
+迁移为：
+
+```bash
+rabetbase bff create --type ENDPOINT --name getUserInfo --format json
+# 编辑 .rabetbase/bff/<appCode>/ENDPOINT/getUserInfo.js
+rabetbase bff push --dry-run --format json
+rabetbase bff push --yes --format json
+```
+
+### 旧“更新已有脚本”
+
+旧思路：
+
+```bash
+rabetbase bff save --file ./scripts/getUserInfo.js --id 42 --yes --format json
+```
+
+迁移为：
+
+```bash
+rabetbase bff pull --format json
+# 编辑同步目录中的本地文件
+rabetbase bff status --format json
+rabetbase bff push --dry-run --format json
+rabetbase bff push --yes --format json
+```
+
+## Agent 规则
+
+- 不要再基于 `bff save` 设计新流程
+- 如果用户只是沿用旧术语，先解释“推荐路径是 `bff create + bff push`”，然后直接按新流程执行
+- 如果用户贴出历史脚本，优先帮他改造成 `create/push/pull/status/delete`
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [bff-creation-workflow.md](../guides/bff-creation-workflow.md)
+- [conflict-detection.md](../guides/conflict-detection.md)
+- [rabetbase-bff-create.md](./rabetbase-bff-create.md)
+- [rabetbase-bff-push.md](./rabetbase-bff-push.md)

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

@@ -0,0 +1,37 @@
+# bff status
+
+检查本地 BFF 脚本与 `.rabetbase/bff.lock.json` 的同步状态。
+
+## 命令
+
+```bash
+rabetbase bff status --format json
+rabetbase bff status --remote --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--remote` | boolean | 否 | — | 额外检查远端存在但本地不存在的脚本 |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
+
+## 输出字段
+
+- `added`：本地新增、尚未写入 lock 的脚本
+- `modified`：本地有变更、和 lock 中 hash 不一致
+- `unchanged`：本地与 lock 一致
+- `remoteOnly`：仅远端存在（需 `--remote`）
+
+## 提示
+
+- `push` 前先看 `status`
+- `pull` 后再次看 `status`，确认是否回到 `unchanged`
+- `status` 只比较本地文件与 lock/远端同步状态，不检查脚本运行时语义；字段、返回值和 `context.client` 用法仍按 `backend-function.md` 自检
+- 多应用项目建议带 `--app` 或 `--appcode`
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [conflict-detection.md](../guides/conflict-detection.md)
+- [backend-function.md](../guides/backend-function.md)

package/skills/rabetbase/references/rabetbase-cli-skill-install.md

@@ -0,0 +1,42 @@
+# cli-skill install
+
+从当前 npm 包内安装、重装或刷新同版本 Rabetbase CLI Built-in Skill。命令通过 `npx --yes skills@latest` 使用包内本地路径作为安装源，由官方 Skills CLI 识别已安装的 Agent 并选择兼容目录；不会从外部 Skill 内容源下载文件。
+
+## 命令
+
+```bash
+rabetbase cli-skill install
+```
+
+## 参数
+
+无。
+
+## 行为
+
+- 安装源固定为当前 npm 包内的 `skills/rabetbase/`。
+- 安装目录和多 Agent 兼容规则由最新版官方 Skills CLI 管理，Rabetbase 不自行选择或写入某个固定 Agent 目录。
+- 每次安装请求都交给当前最新版 Skills CLI；若安装前后内容均为当前版本，结果标记为 `already current`。
+- 安装前校验 npm 包内 Skill 的版本和整体摘要，安装后复验实际生效内容。
+- 失败会返回稳定错误码和修复命令；不会回退到外部 Skill 内容源，也不自动修改 npm、Git 或网络配置。
+
+业务 Skill 安装属于 `lovrabet skill install`，不要迁移到 `rabetbase`。
+
+## 输出
+
+- 首次安装或替换：输出 Skill 版本和目标路径。
+- 已是当前版本：输出 `is already current`。
+- 失败：输出本地错误码，并提示重新执行 `rabetbase cli-skill install`。
+
+## 提示
+
+- 安装或升级 `@lovrabet/rabetbase-cli` 时，npm `postinstall` 会自动安装包内同版本 Skill。
+- `rabetbase update` 的语义是 CLI 与 Built-in Skill 一体升级。
+- Skill 丢失、被修改或 npm 安装时跳过 scripts 后，可用本命令修复；需要 npm registry 可访问，以获取最新版 `skills` 安装器。
+- 修复后重新读取 `SKILL.md` 与所需 reference，再继续当前任务。
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [update](rabetbase-update.md)
+- [doctor](rabetbase-doctor.md)

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

@@ -0,0 +1,35 @@
+# codegen sdk
+
+根据 Dataset 操作定义生成 TypeScript SDK 调用代码。
+
+## 命令
+
+```bash
+rabetbase codegen sdk --alias order --operation filter --format json
+rabetbase codegen sdk --code 097b7361b76c42bcb12b923fa5a08861 --operation create --format json
+rabetbase codegen sdk --alias productSku --operation getOne --skip-imports > ./src/api/getSku.ts
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--code <code>` | string | 与 alias 二选一 | — | Dataset code（32 位 hex UUID） |
+| `--alias <name>` | string | 与 code 二选一 | — | `api.ts` 中定义的别名 |
+| `--operation <name>` | string | 是 | — | 操作名（`filter` `getOne` `create` `update` `delete`） |
+| `--skip-imports` | boolean | 否 | — | 不包含 import 语句 |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
+
+## 输出
+
+生成的 TypeScript 代码直接打印到 stdout，可重定向到文件。
+
+## 提示
+
+- 生成前先用 `dataset operations --operation <name>` 确认操作存在
+- `--skip-imports` 适合追加到已有文件
+- 生成代码包含完整类型标注和注释
+
+## 参考
+
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,33 @@
+# codegen sql
+
+根据已保存的 SQL 查询生成 TypeScript 调用代码。
+
+## 命令
+
+```bash
+rabetbase codegen sql --sqlcode 2305f915-dd48cd4c --format json
+rabetbase codegen sql --sqlcode 2305f915-dd48cd4c --target bff --format json
+rabetbase codegen sql --sqlcode 2305f915-dd48cd4c > ./src/api/getUserList.ts
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--sqlcode <code>` | string | 是 | — | SQL code 标识符（格式：`xxxxxxxx-xxxxxxxx`） |
+| `--target <target>` | string | 否 | `sdk` | 生成目标：`sdk`（SDK 调用） / `bff`（BFF 脚本内调用） |
+| `--no-imports` | boolean | 否 | — | 不包含 import 语句 |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
+
+## 输出
+
+生成的 TypeScript 代码直接打印到 stdout。`--target sdk` 生成前端 SDK 调用代码，`--target bff` 生成 BFF 脚本内调用代码。
+
+## 提示
+
+- `--target bff` 生成的代码使用 `context.client.sql.execute()`，注意 BFF 中 SQL 返回直接是数组
+- `--target sdk` 生成的代码使用 `client.sql.execute()`，返回 `{ execSuccess, execResult }`
+
+## 参考
+
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,296 @@
+# `.rabetbase.json` 配置参考
+
+项目级配置文件，放在项目根目录。CLI 启动时自动读取，全局配置（`~/.rabetbase.json`）作为 fallback。
+
+这份文件描述的是**本地配置模型**：默认应用、应用名到 `appcode`/`env`/`apiDir` 的映射，以及输出格式、风险等级、认证信息等本地偏好。
+
+它**不是**平台应用目录。若要查看当前登录账号在平台上能访问哪些应用，应使用 `rabetbase app list --remote`，而不是直接查看 `.rabetbase.json`。
+
+兼容旧名：`.lovrabet.json`、`.lovrabetrc`（按优先级 `.rabetbase.json` > `.lovrabet.json` > `.lovrabetrc`，首个存在的生效）。
+
+## 初始化
+
+```bash
+rabetbase workspace init --appcode <code>
+```
+
+绑定当前目录到某个应用并写入 `.rabetbase.json`，采用 canonical 的 `apps + defaultApp` 结构；旧的顶层 `appcode` 仍兼容读取。首次安装后的全局引导用 `rabetbase init`。
+
+## canonical 主模型
+
+当前推荐、也是所有新写入默认采用的结构，是 **`apps + defaultApp`**：
+
+```json
+{
+  "defaultApp": "main",
+  "apps": {
+    "main": {
+      "appcode": "app-xxxxxxxx",
+      "env": "daily"
+    }
+  }
+}
+```
+
+CLI 对旧版顶层 `appcode` 仍兼容读取，但它已经不是推荐主模型。
+
+## 兼容读取的单应用模式
+
+兼容读取的最简配置只需 `appcode` 和 `env`：
+
+```json
+{
+  "appcode": "app-xxxxxxxx",
+  "env": "daily"
+}
+```
+
+### 完整字段
+
+```json
+{
+  "appcode": "app-xxx",
+  "env": "production",
+  "locale": "en-US",
+  "cookie": "session-cookie-value",
+  "accessKey": "ak-xxx",
+  "format": "json",
+  "pageSize": 20,
+  "riskLevel": "high-risk-write",
+  "apiDir": "./src/api",
+  "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"
+}
+```
+
+## 多应用模式
+
+一个项目对接多个 Lovrabet 应用时，使用 `apps` + `defaultApp`：
+
+```json
+{
+  "defaultApp": "order",
+  "apps": {
+    "order": {
+      "appcode": "app-yyyyyyyy",
+      "env": "daily",
+      "riskLevel": "write"
+    },
+    "product": {
+      "appcode": "app-zzzzzzzz",
+      "env": "production",
+      "apiDir": "./src/api/product"
+    }
+  }
+}
+```
+
+每个 app profile 可单独覆盖普通顶层字段。`riskLevel` 是安全例外：默认值为 `high-risk-write`，全局、项目、profile 与环境变量都作为 ceiling，最终取最严格值。CLI 运行时根据 `--app <name>` 或 `defaultApp` 选择激活的 profile。
+
+管理命令（声明式 flags，非位置参数）：
+
+```bash
+rabetbase workspace add order --appcode app-order-001 --env daily
+rabetbase workspace add product --appcode app-product-002
+rabetbase workspace use --app order
+rabetbase app list
+rabetbase workspace remove product --yes
+```
+
+## 字段说明
+
+### 顶层字段
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `appcode` | string | — | 顶层单应用兼容字段。新写入优先使用 `apps + defaultApp`。兼容旧名 `app` |
+| `env` | string | `"production"` | 环境。可选值：`production`、`daily`（配置文件若仍为旧值 `online`，加载时会规范为 `production`） |
+| `locale` | string | `"en-US"` | 语言设置 |
+| `cookie` | string | — | 内联 session cookie。设置后优先于 `~/.lovrabet/cookie` 文件 |
+| `accessKey` | string | — | Access Key 认证（预留，未来替代 cookie） |
+| `format` | string | — | 默认输出格式。可选值：`json`、`pretty`、`compress`。不设则命令默认 `compress` |
+| `pageSize` | number | — | 默认分页大小，用于 `sql list` 等分页命令 |
+| `riskLevel` | string | `"high-risk-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` 生成代码的输出目录 |
+| `template_base_url` | string | 平台默认 CDN | 模板 CDN 基础 URL，一般无需修改 |
+| `defaultApp` | string | — | 多应用模式下的默认应用名称 |
+| `apps` | object | — | 多应用配置。key 为应用名，value 为 AppProfile（见下方） |
+| `apiDomain` | string | 平台默认 | 自定义 API 域名（独立部署场景）。覆盖后所有 API 请求使用此域名 |
+| `userDomain` | string | 平台默认 | 自定义用户域名 |
+| `runtimeDomain` | string | 平台默认 | 自定义运行时域名 |
+
+### AppProfile 字段（`apps.*` 内的每个应用）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `appcode` | string | **必填**。该应用的 appcode |
+| `env` | string | 覆盖顶层 `env` |
+| `apiDir` | string | 覆盖顶层 `apiDir` |
+| `cookie` | string | 覆盖顶层 `cookie` |
+| `accessKey` | string | 覆盖顶层 `accessKey` |
+| `format` | string | 覆盖顶层 `format` |
+| `pageSize` | number | 覆盖顶层 `pageSize` |
+| `riskLevel` | string | 只能继续收紧顶层 `riskLevel`，不能提权 |
+| `locale` | string | 覆盖顶层 `locale` |
+
+## 优先级
+
+每个配置项的解析优先级从高到低（`appcode` 不从环境变量自动解析，必须来自 `--appcode` 或配置文件）：
+
+```
+CLI flag (--appcode, --env, --format, --app ...)
+  ↓
+当前项目 app profile / 顶层字段
+  ↓
+环境变量 (RABETBASE_ENV, RABETBASE_FORMAT ...)
+  ↓
+全局级 ~/.rabetbase.json app profile / 顶层字段
+  ↓
+内置默认值
+```
+
+业务落点类字段以当前项目为主。`appcode` 不允许从 shell 残留环境变量自动推断；CI 或一次性脚本如需使用环境变量，必须显式传 `--appcode "$RABETBASE_APPCODE"`。对需要 App Code 的业务命令，如果检测到 `RABETBASE_APPCODE` / `LOVRABET_APPCODE` 已设置但未显式传 `--appcode`，且当前解析结果为空或与环境变量不同，CLI 会直接拒绝执行，避免误操作其他应用。`RABETBASE_APP`、`RABETBASE_ENV` 仍只作为无项目配置时的显式选择 / 环境 fallback。
+
+## 环境变量
+
+所有环境变量以 `RABETBASE_` 为前缀，兼容旧前缀 `LOVRABET_`。
+
+| 环境变量 | 对应配置项 | 说明 |
+|----------|-----------|------|
+| `RABETBASE_APPCODE` | — | 仅作为 shell 变量供脚本显式传给 `--appcode`；业务命令检测到冲突时会拒绝执行 |
+| `RABETBASE_ENV` | `env` | 无项目 env 时的环境 fallback |
+| `RABETBASE_COOKIE` | `cookie` | Session cookie |
+| `RABETBASE_ACCESS_KEY` | `accessKey` | Access Key |
+| `RABETBASE_FORMAT` | `format` | 输出格式 |
+| `RABETBASE_PAGE_SIZE` | `pageSize` | 分页大小 |
+| `RABETBASE_RISK_LEVEL` | `riskLevel` | 临时风险上限，只能收紧，不能提权 |
+| `RABETBASE_VERBOSE` | — | 全局 verbose 开关（`1` 或 `true` 启用），仅环境变量，不支持配置文件 |
+| `RABETBASE_APP` | — | 无项目显式选择时的临时应用名 fallback（显式切换优先用 `--app`） |
+
+## 配置文件查找规则
+
+| 作用域 | 查找目录 | 文件名优先级 |
+|--------|---------|------------|
+| 项目级 | `process.cwd()` | `.rabetbase.json` > `.lovrabet.json` > `.lovrabetrc` |
+| 全局级 | `~`（用户 HOME） | 同上 |
+
+合并策略由项目级 `inherit` 字段控制（三态）：
+
+- **省略 `inherit`（默认，项目主导）**：项目级配置自给自足；仅从全局白名单继承 `cookie`、`accessKey`、`locale`、`format`、`riskLevel`、`pageSize`，**不继承** `apps` / `defaultApp` / `appcode` / `env` 等业务字段。普通字段由项目级显式值覆盖；`riskLevel` 始终取全局与项目顶层的更严格值。
+- **`inherit: true`（显式全量合并）**：标量字段项目级覆盖全局级；`apps` 深度合并（项目同名覆盖全局同名，其余保留）；`defaultApp` 仅当项目级显式声明时才覆盖全局级。等价于历史默认行为，需要跨项目共享全局 `apps` 时显式开启。
+- **`inherit: false`（普通字段完全隔离）**：业务与偏好字段只使用项目级值；安全例外是全局 `riskLevel` 仍参与最严格上限计算，项目不能借此提权。
+
+> **为什么默认改成项目主导**：避免 `~/.lovrabet.json` 中的 `defaultApp` / `apps` 在用户进入空白目录或新项目时被无声继承（曾导致 menu asset-update 误改其他应用资源）。`api list` / `api pull` / `app list` 仍可通过 `--global` 显式查看合并视图。
+
+## 示例
+
+### 最小化（CI 环境用环境变量）
+
+```json
+{}
+```
+
+```bash
+export RABETBASE_APPCODE=app-xxx
+export RABETBASE_ENV=daily
+rabetbase dataset list --appcode "$RABETBASE_APPCODE"
+```
+
+### 开发环境单应用
+
+```json
+{
+  "appcode": "app-xxxxxxxx",
+  "env": "daily",
+  "riskLevel": "high-risk-write"
+}
+```
+
+### 多应用 + 限制风险
+
+```json
+{
+  "riskLevel": "write",
+  "defaultApp": "order",
+  "apps": {
+    "order": {
+      "appcode": "app-order-001",
+      "env": "daily"
+    },
+    "product": {
+      "appcode": "app-product-002",
+      "env": "production",
+      "riskLevel": "read"
+    }
+  }
+}
+```
+
+```bash
+rabetbase sql list --app order
+rabetbase dataset list --app product
+```
+
+## config 命令
+
+### config set
+
+写入配置项：
+
+```bash
+# 写入项目级配置（默认；须在能解析到项目 .rabetbase.json 的目录下执行）
+rabetbase config set apiDomain https://custom-api.example.com
+rabetbase config set env daily
+
+# 写入全局配置（任意目录）
+rabetbase config set apiDomain https://custom-api.example.com --global
+```
+
+`config set` **默认写入项目**配置文件（当前工作目录能解析到 `.rabetbase.json` 等）；加 **`--global`** 则写入 **`~/.rabetbase.json`**。
+
+若当前目录**没有**项目配置文件且**未**指定 `--global`，CLI **拒绝执行**并提示使用 `--global` 或先 `rabetbase init`，**不会**静默改全局。
+
+### config get
+
+读取配置项（读取合并后的值）：
+
+```bash
+rabetbase config get apiDomain
+# 输出: https://custom-api.example.com
+```
+
+### config list
+
+以 JSON 格式输出当前合并后的完整配置：
+
+```bash
+rabetbase config list
+```
+
+## 诊断命令
+
+遇到配置问题时，用 `rabetbase doctor` 快速定位问题：
+
+```bash
+rabetbase doctor
+```
+
+输出包括：CLI 版本、配置文件路径、**各侧配置文件 JSON 语法是否合法**（非法则该侧内容在合并时会被忽略）、合并后的所有配置项（appCode / env / cookie / apiDomain 等）、API 域名、认证状态。
+
+多应用列表与来源说明见 [`rabetbase app list`](rabetbase-app-list.md)（`items` / `meta` / `definedIn`）。
+
+## 独立部署场景
+
+如果 Lovrabet 部署在自定义域名下，通过 `apiDomain` / `userDomain` / `runtimeDomain` 覆盖默认域名：
+
+```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
+```
+
+优先级：配置文件中显式设置 > 环境变量 > 默认平台域名。项目级配置可覆盖全局配置。

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

@@ -0,0 +1,84 @@
+# dataset business-group-update
+
+安全更新业务场景分组（`businessGroup`）。
+
+本命令用于修改业务场景分组。它不同于 `dataset extend-update`：`extend-update` 当前可写 key 白名单为空，且不支持修改 `businessGroup`。
+
+## 命令
+
+```bash
+rabetbase dataset business-group-update \
+  --appcode app-64e32817 \
+  --code 1a90dbff5f094a9a89936fa99b10984c \
+  --business-group "数据智能---AI任务与平台配置" \
+  --expect-business-group "旧分组" \
+  --dry-run \
+  --format compress
+```
+
+确认 dry-run 结果无误后再去掉 `--dry-run` 执行。
+
+## 参数
+
+| Flag | 必填 | 说明 |
+| --- | --- | --- |
+| `--appcode <code>` | 否 | 目标应用编码；未配置默认 app 时必填 |
+| `--code <code>` | 是 | Dataset code，32 位 hex UUID |
+| `--business-group <name>` | 是 | 目标业务场景分组；空字符串表示清空 |
+| `--expect-business-group <name>` | 否 | 当前业务场景分组保护；不匹配即中止且不写入 |
+| `--dry-run` | 否 | 只返回 before/after 预览，不执行写入 |
+| `--format <fmt>` | 否 | 输出格式，AI Agent 优先用 `compress` |
+
+## 行为
+
+- 命令用 `--code` 定位 Dataset。
+- 当前值和写后校验都按 Dataset code 读取业务场景分组；不需要 `dblinkId`、`tableName` 或 `sourceType`。
+- `--business-group` 为空字符串时表示清空业务场景分组。
+- 回读到 `businessGroup` 为空字符串时表示未分组，是合法当前值。
+- `--expect-business-group` 用于保护当前值；不匹配时中止且不写入。
+- `--dry-run` 只预览 before/after，不执行写入。
+- 正式写入后会校验目标值已生效。
+- 当目标值和当前值一致时，命令返回 `changed=false`，不会执行写入。
+
+## 输出
+
+返回结构包含：
+
+```json
+{
+  "operation": "update",
+  "appCode": "app-64e32817",
+  "selector": {
+    "code": "1a90dbff5f094a9a89936fa99b10984c"
+  },
+  "dataset": {
+    "code": "1a90dbff5f094a9a89936fa99b10984c",
+    "name": "保单条款"
+  },
+  "before": {
+    "businessGroup": "旧分组"
+  },
+  "after": {
+    "businessGroup": "数据智能---AI任务与平台配置"
+  },
+  "changed": true,
+  "dryRun": true,
+  "submitted": false
+}
+```
+
+## 提示
+
+- 写入前必须先运行 `--dry-run`。
+- `businessGroup` 用于按业务场景组织 Dataset，而不是按数据库、表类型或服务名等技术结构分组。优先按业务场景命名并复用当前应用已有分组；需要跨领域消歧或沿用既有两级分组体系时，可使用 `<业务领域>---<业务场景>`，否则使用 `<业务场景>`。表数量不决定是否拆分层级。建议最多两级，层级不得为空或带首尾空白；空字符串表示清空。CLI 仅描述推荐格式并保持兼容，不额外拒绝历史非标准值。
+- 推荐用 `--expect-business-group` 保护当前值。
+- 不确定 Dataset code 时，先用 `rabetbase dataset list --name <name> --format compress` 定位。
+- 业务场景分组只能使用本命令更新，不要通过 `dataset extend-update` 或 `/smartapi/dataset/update-driven-data` 修改。
+- `dataset extend-update` 当前可写 key 白名单为空；未来如开放其他 Dataset 顶层 `extend` 字段，以 `dataset extend-update` reference 为准。
+
+## 参考
+
+- [dataset detail](rabetbase-dataset-detail.md)
+- [dataset list](rabetbase-dataset-list.md)
+- [dataset extend-update](rabetbase-dataset-extend-update.md)
+- [SKILL.md](../SKILL.md)