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

package/skills/rabetbase/SKILL.md

@@ -0,0 +1,493 @@
+---
+name: rabetbase
+version: 2.4.1
+description: "Lovrabet 开发工作流 CLI — 通过 rabetbase 命令管理数据集、数据库连接（dblink）、智能列表页（Smart List Page）、React 自定义页面（JSX 页面）、SQL 查询、BFF 脚本、通知配置、菜单事实读取与同步、应用文件、OCR 识别、代码生成，以及平台问题上报。触发词：数据集、数据表、dataset relation-audit、dataset delete、dataset restore、废弃数据集、恢复数据集、dataset rename、dataset field-update、dataset extend-update、dataset business-group-update、businessGroup、字段对象更新、doType、options、智能列表页、Smart List Page、React 自定义页面、JSX 页面、page react-create、page react-list、page react-detail、page react-update、page react-publish、page generate-start、page generate-status、page relation-audit、page sync、page pull、page push、page restore、恢复已删除页面、dblink、数据库连接、schema 分析、db list、db detail、db test、db tables、db diff、db diff --table、db analyze-batch-plan、db analyze-start、analyze-cancel、analyze-status、traceId、自定义 SQL、sql.execute、bff.execute、BF 消息通知、BFF 消息通知、Backend Function 消息通知、notification config-list、EMAIL configCode、通知配置、notification.send、get_dataset_detail、validate_sql_content、save_or_update_custom_sql、@lovrabet/sdk、lovrabet 开发、rabetbase、filter、codegen、init、appcode、app list、app members-list、tenant members-list、应用人员列表、租户人员列表、workspace、workspace init、workspace use、workspace add、workspace remove、多应用、默认应用、menu list、menu external-link-create、menu external-link-update、menu rename、菜单改名、外链菜单创建、外链 URL 更新、菜单异常审计、菜单手动删除清单、menu sync、menu asset-update、菜单资源更新、menu move、菜单移动、角色、用户组、权限、role、permit、role list、role create、role user-add、role user-remove、user-resolve、销售组、加入开发者、page-set、page-get、row-roles、SELF、ALL、行级权限、role-menus-set、role-apis-set、菜单权限、API 权限、DEV、CUSTOM、project create、project upgrade、schema、jq、compress、file upload、file query-url、ocr recognize、文件上传、OCR 识别、发票识别、图片识别、长期链接、issue report、平台问题、platform issue、问题上报、user-account dingding-sandbox-bind、钉钉沙箱账号绑定。"
+metadata:
+  requires:
+    bins: ["rabetbase"]
+    node: ">=20"
+  cliHelp: "rabetbase --help"
+---
+
+# Rabetbase CLI
+
+> **前置条件：** 使用任何 API 命令前，需完成认证和配置（见下方）。
+> **执行前必做：** 执行任何命令前，必须先阅读对应命令的 reference 文档，再调用命令。
+> **命名约定：** 统一使用 `rabetbase <service> <command> [flags]` 格式。
+> **输出格式：** AI Agent 需要结构化输出时，**优先 `--format compress`**（与 `json` 相同信封，单行紧凑、省 token）；需要人类可读缩进时用 **`--format json`**。可在 **`json` / `compress`** 上叠加 **`--jq '<expr>'`**（对最终打印的整条 JSON 做 jq；二进制查找顺序为 **`JQ_PATH` → CLI 内置 sidecar jq → `PATH` 上的 jq**，通常无需单独安装系统 jq）。不确定当前 CLI 有哪些子命令或 flags 时，先跑 **`rabetbase schema`**（与 `--help` 同源的机器可读契约，无需登录）。
+
+## 前置条件
+
+1. **认证**：`rabetbase auth login` 通过浏览器完成 OAuth 登录；非交互 Agent 使用 `rabetbase auth login --yes`，把终端打印的授权链接发给用户打开，链接有效期 10 分钟
+2. **AppCode**：确保 `.rabetbase.json` 中设置了 `apps + defaultApp`（推荐）或兼容读取的顶层 `appcode`，或通过 `--appcode <code>` / `--app <name>` 传入（旧名 `.lovrabet.json` 仍可读）
+3. **配置文件**：`rabetbase init` 做**首次安装后的全局引导**（可写 `.rabetbase.json`；旧名仍兼容读取）。完整字段说明见 [`.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 …` 登记各应用，再用 `--app <name>` 临时切换，或 `workspace use --app <name>` 修改当前工作目录默认应用
+6. **平台发现**：当你不知道当前登录账号能访问哪些应用时，先 `rabetbase app list --remote`；它查询平台目录，不修改本地配置
+7. **本地配置视图**：当你要确认当前项目或全局已经登记了哪些应用、默认应用是谁时，用 `rabetbase app list`。`rabetbase app` 本身只显示帮助，不等价于 `app list`
+8. **人员目录查询**：查询某租户的人员用 `rabetbase tenant members-list --tenant-code <code>`；查询某应用的人员及其角色归属用 `rabetbase app members-list --appcode <code>`。两者均为只读全量查询，不提供分页、模糊搜索或写入能力。
+9. **本地 SQL / BFF 目录**：新建或长期维护的源文件应落在 CLI 与 `bff status` / `sql pull` 一致的路径，避免写在 `src/`、`queries/` 等随意目录后再迁移。
+   - **SQL**：项目根 **`.rabetbase/sql/<appCode>/<dbName|db-<id>>/<sqlCode>_<sqlName>.sql|xml`**；草稿或人工兜底可放 `.draft.sql`。`sql create` / `sql pull` / `sql push` / `sql status` 默认围绕这套目录与 `.rabetbase/sql.lock.json` 工作。
+   - **BFF**：**`.rabetbase/bff/<appCode>/...`**（由 `bff create` 创建或 `bff pull` 同步；与 `bff status` / `bff push` 扫描范围一致）。详见 [`guides/sql-creation-workflow.md`](guides/sql-creation-workflow.md)、[`guides/bff-creation-workflow.md`](guides/bff-creation-workflow.md)。
+10. **可选：`lovrabet` CLI 查数** — 若本机已安装 **`@lovrabet/lovrabet-cli`**（命令 **`lovrabet`**）且 **版本 ≥ 2.0**（`lovrabet --version`），可用 **`lovrabet data filter` / `lovrabet data getOne`** 按 SDK 语义在终端查看真实行数据与 JSON，便于调试；**非人人安装**，未安装或版本低于 2.0 时仅用 `rabetbase` 即可。详见 [`guides/data-api-guidelines.md`](guides/data-api-guidelines.md) 中「可选：`lovrabet` CLI 查数」。
+
+## Skill Freshness
+
+- **本地 repo 与 CLI 契约优先** — 若已安装的全局 skill 描述与当前仓库 `skills/rabetbase/`、`rabetbase --help`、`rabetbase schema` 不一致，以**当前仓库内容和 CLI 实际输出**为准。
+- **发现 skill 过期时应主动刷新** — CLI 安装和升级会自动安装同版本 Skill；若不一致已经影响当前任务判断，应执行 `rabetbase cli-skill install`，由最新版官方 Skills CLI 从当前 npm 包内本地源重装。
+- **刷新后必须重新读取** — 刷新完成后，重新打开当前 `SKILL.md` 与所需 reference，再继续执行任务，避免沿用旧记忆。
+- **刷新失败也不能回退到旧结论** — 若安装失败，明确告诉用户“本地全局 skill 可能过期”，并继续以仓库内 `skills/rabetbase/` 和 `rabetbase schema` 作为 source of truth。
+
+## Agent 快速执行顺序
+
+1. **判断需求类型**
+   - Instant API 标准数据记录操作 → SDK filter/getOne/create/batchCreate/update/delete；批量更新使用 `update({ id: [...] })`，不存在 `batchUpdate()`
+   - 简单聚合且数据集是 DB_TABLE → SDK aggregate；聚合列用 `aggregate[].column`，不要用旧别名 `field`
+   - 复杂 JOIN / 数据库函数且数据集是 DB_TABLE → 自定义 SQL
+   - 外部系统调用 / 跨表事务 / 复杂业务编排 → BFF；BFF 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`
+   - 需要从文本需求创建新的 `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)）
+   - DB 增量分析先对完整 `toAnalyzeTables` 执行 `db analyze-batch-plan`；它生成的是本地批次方案，不是服务端 `planId`，也不会创建任务。再严格按批次顺序启动；每批独立保存 `planId`（即 `analyze-start` 返回值），当前批次到达已知终态前不得启动下一批
+   - 全部批次结束后复跑完整 `db diff --all --changed-only`；仍未收敛时，按 [`database-connection-workflow.md`](guides/database-connection-workflow.md) 对剩余 `toAnalyzeTables` 逐表串行重试且每表只恢复一次。状态查询失败继续使用原 `planId`，不得重复启动任务
+   - 输出很大且只需子集时，在 `compress`/`json` 上加 `--jq '.data…'` 缩小结果
+   - **（可选）** 若环境已安装 **`lovrabet` ≥ 2.0**，可用 `lovrabet data filter` / `data getOne` 对数据集做与 SDK 同语义的终端查数；**不要**假设用户已安装或版本够新，见 [`guides/data-api-guidelines.md`](guides/data-api-guidelines.md)
+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` 验证
+4. **BFF 工作流严格分步**
+   - 查现有 → 确认字段或通知配置 → 查公共函数 → 本地创建(`bff create`) → 检查状态(`bff status`) → 先预览(`--dry-run`) → 再拉取/推送/删除
+   - 创建会发送消息通知的 BFF 时，先读取 [`backend-function.md`](guides/backend-function.md) 的“消息通知扩展”契约，再执行 [`rabetbase notification config-list --type EMAIL`](references/rabetbase-notification-config-list.md) 获取当前应用的 `configCode`；不得猜测渠道、收件人或把密钥写进脚本
+   - 推送完成只代表脚本配置已同步到平台；若用户要确认最终运行效果，显式交接到运行验证（如可用的 `lovrabet bff exec`），不要把运行验证伪装成 `rabetbase` 已完成
+5. **页面体系选择**
+   - 智能标准页面（Smart List Page）是内置的基础表单、表格展示和常规数据操作页面，常规数据管理需求优先使用它
+   - 仅当标准页面无法满足个性化布局、可视化、复杂交互或自定义页面结构时，才使用 React 自定义 JSX 页面
+   - 页面体系不明确时，先向用户确认；不要为同一目标同时创建标准页面与 React 页面
+6. **智能列表页（Smart List Page，page）工作流**
+   - 工作流判断先看 [`guides/page-development-workflow.md`](guides/page-development-workflow.md)
+   - `page` 命令职责分离：[`page generate-start`](references/rabetbase-page-generate-start.md) 负责提交或复用任务，[`page generate-status`](references/rabetbase-page-generate-status.md) 负责查询任务状态，[`page standard-page-status`](references/rabetbase-standard-page-status.md) 负责查询智能列表页事实
+   - 数据集字段变更后同步已有智能列表页：[`page sync`](references/rabetbase-page-sync.md)
+   - 页面关系绑定审计：先读 [`rabetbase-page-relation-binding.md`](references/rabetbase-page-relation-binding.md)，再执行 [`page relation-audit`](references/rabetbase-page-relation-binding.md)
+   - 遇到“关联数据带不出 / 标准页面没有生成关联关系 / 页面关联绑定异常”类问题，固定顺序是：`dataset relations` 只读确认关系事实 → `dataset relation-audit` 审计关系事实风险 → `page standard-page-status` 判断页面是否存在 → `page relation-audit` 审计页面绑定；若关系事实本身不对，先按 [`dataset relation-create/update/delete`](references/rabetbase-dataset-relation-mutations.md) 做 `--dry-run` 方案并等用户确认；已有页面再 `page sync --dry-run`，无页面走 `page generate-start --dry-run`
+   - `page sync` 只负责同步已有智能列表页，不是数据集关系修复命令，也不能承诺自动修复所有 `wrong_code` / `wrong_label` / `missing`
+   - 本地 schema 开发：[`page pull`](references/rabetbase-page-pull.md) → IDE 编辑 → [`page push`](references/rabetbase-page-push.md)
+   - 恢复已删除 STANDARD/JSX 页面：先读 [`page restore`](references/rabetbase-page-restore.md)，默认按 ID 自动识别类型；存在跨类型同 ID 时显式传 `--page-type`
+   - 需要理解 formal schema 组件语义时，再按需阅读 `knowledge/page-schema/` 下的 PageSchema 组件资料；不要把它与 `rabetbase page` 命令 reference 混淆
+7. **React 自定义页面工作流**
+   - React 自定义页面与智能列表页是两类独立页面能力，不混用两类页面的命令
+   - 创建、修改或发布前，必须先阅读 [`react-custom-page-workflow.md`](guides/react-custom-page-workflow.md)，再按其中的编排读取对应原子命令 reference
+   - 编写 JSX、CSS 或词包前，必须阅读 [`generation-standards.md`](knowledge/react-page/generation-standards.md)；选择 UI 组件时阅读 [`components.md`](knowledge/react-page/components.md)
+8. **Legacy modernization / Application Blueprint 工作流**
+   - 当用户要把无人交接老项目、外包接手项目或遗留系统翻新到 Lovrabet 体系时，先阅读 [`guides/legacy-application-blueprint-workflow.md`](guides/legacy-application-blueprint-workflow.md)
+   - 主产物是 `.rabetbase/blueprint/<appCode>/application-blueprint.md`，不是直接生成或推送 SQL/BFF
+   - 必须把老代码 Logic Graph 与 dbagent 已生成的 Dataset / Relations 绑定，再判断 Instant API、Custom SQL、BFF、Hook、COMMON 或 Java Service 落点
+
+## 应用决议指引
+
+1. **已明确 appcode**
+   - 用户直接给了 `app-xxxx`
+   - 或当前命令已经显式传了 `--appcode`
+   - 直接执行目标命令，不需要先查 `rabetbase app list --remote`
+
+2. **已明确本地应用名**
+   - 当前项目 `.rabetbase.json` 已有 `apps + defaultApp`
+   - 或用户给了 `--app <name>`
+   - 先用 `rabetbase app list` 验证本地配置，再执行目标命令
+
+3. **只知道业务名称，不知道能访问哪个应用**
+   - 先 `rabetbase app list --remote --format compress`
+   - 从平台目录里确认当前登录账号可访问的应用
+   - 再决定是否需要 `rabetbase workspace add` / `rabetbase workspace use`，或临时传 `--appcode`
+
+4. **不要混淆两种视图**
+   - `rabetbase app list`：本地配置视图，回答“当前项目/全局登记了哪些应用”
+   - `rabetbase app list --remote`：平台目录视图，回答“当前登录账号能访问哪些应用”
+
+5. **当两边不一致时**
+   - 平台上有，本地没有：说明还没登记到本地配置，可用 `rabetbase workspace add`
+   - 本地有，平台上查不到：说明当前账号可能无权限，或本地配置已过时，应先核对权限与 appcode
+
+## 菜单异步重新分组（`menu regroup-start`）
+
+执行前先阅读 [`menu regroup-start`](references/rabetbase-menu-regroup-start.md) 与 [`task status`](references/rabetbase-task-status.md)。该流程的完成口径不是“任务已提交”，而是异步重新分组任务到达明确终态：
+
+1. 先用 `menu list` 取得精确的非 folder 叶子菜单 ID，再执行 `menu regroup-start --dry-run`。
+2. 正式执行只提交一次并保存 `data.task.taskId`。首次回读时，`data.verification.groupingApplied` 可能是 `true` 或 `"unconfirmed"`；未回读确认不代表任务提交失败。
+3. 若 `data.task.status` 为 `PENDING / PROCESSING`，执行返回的 `data.query.command`；后续仍为非终态时继续查询同一个 taskId，不得再次提交 `regroup-start`。
+4. 保留初始响应的 `data.verification.lookupCommand`。无论初始响应已是 `SUCCESS`，还是后续 `task status` 到达 `SUCCESS`，都必须用该命令回读最终菜单事实；回读仍未确认时只重试只读查询，不得重提 `regroup-start`。
+5. `FAILED` 时报告 `errorMessage` 且不自动重提；未知状态（`knownStatus=false`）进入人工复核，不推断成功或失败。
+
+## 数据库连接（`db`）
+
+与 **`dataset`（数据集模型）** 的分工：**`db *`** 管平台登记的 **物理库连接（dblink）**、**测连**、**schema 分析任务**、**物理表清单与差异**；表字段、枚举以 **`dataset detail`** 为准，数据集关联关系优先以 **`dataset relations`** 为准，关系事实风险用 **`dataset relation-audit`**。
+
+- **入口**：先 [`db list`](references/rabetbase-db-list.md) 取 `id` 与 `latestAnalysisTraceId`（如有）。
+- **只读常用**：[`db detail`](references/rabetbase-db-detail.md)、[`db test`](references/rabetbase-db-test.md)、[`db tables`](references/rabetbase-db-tables.md)、[`db diff`](references/rabetbase-db-diff.md)（`--table` 为表名**子串**过滤，分页用 `--page` / `--pagesize`）。
+- **分析任务**：`db analyze-batch-plan` / `analyze-start` / `analyze-cancel` / `analyze-status`（服务端 plan/trace 来源见下）。
+- **状态诊断边界**：`analyze-status` 的 `requestedAnalysis` 只还原原始提交范围；`hasMultipleAttempts=true` 只表示观察到多个执行尝试。不得据此推断尝试间连续性、实际执行范围或自动重启。
+- **增量分批**：先用本地只读的 `db analyze-batch-plan --id <id> --tables <清单>` 得到确定性批次及 `planningEstimate`；这里生成的是本地批次方案，不是服务端 `planId`，不会创建或预留任务。再逐批调用一次 `analyze-start`，读取真实 `planId` 与当前任务的 `serverEstimate`；每批独立保存其返回的 `planId`，同一 dblink 严格串行。两类估算都不得驱动超时、取消、重试、自动重启或状态判断，`PENDING / RUNNING / RETRYING / CANCELING` 均不得推进下一批。
+- **取消已有任务**：只使用正在跟踪的原 `planId` 执行 `analyze-cancel --plan <原 planId>`；取消分支不得调用 `analyze-start`，也不得用可能变化的 `latestAnalysisTraceId` 替换已知目标。
+- **失败恢复**：全部批次结束后以完整 `db diff --all --changed-only` 获取未收敛表，逐表串行执行 `analyze-start --tables <单表>`，每表只恢复一次；累计原因计数只作可能不完整的参考展示。Agent 可语义理解原始 `errorMsg` 辅助解释和建议，但两者都不驱动任务状态、重提任务或收敛判断。
+- **ER 图引导**：`db analyze-status` 终态成功后，检查并转述 `data.links.erPage`；若没有 `data.links`，补 `--appcode` 或进入已配置 app 的项目上下文后重查。
+- **写入**：[`db create`](references/rabetbase-db-create.md) / [`db update`](references/rabetbase-db-update.md) / [`db delete`](references/rabetbase-db-delete.md)（高危删连需确认）；`create`/`update` 支持 **`--dry-run`** 预览。`db create` 成功后返回连接信息与数据库连接页链接。
+- **横切流程与 trace/plan**：[`database-connection-workflow.md`](guides/database-connection-workflow.md)。**单命令细则**见 `references/rabetbase-db-*.md`（与仓库 `src/commands/db/` 一一对应）。
+
+## 用户组与权限（`role` / `permit`）
+
+先分清两个层面再动手：**成员归属**（谁在组里，用 `role user-*`）与**能力授权**（组能看什么/做什么，用 `permit *`）。「某人不能看财务」通常是收紧其所在 `CUSTOM` 组的能力，而不是把人移出组；内置 `DEV`/`ADMIN` 的权限矩阵不可改。
+
+- **横切工作流与决策树**（问题 → 命令、`role-menus-set` vs `page-set --menu-roles` 的区别、5 个剧本）先读 [`guides/role-permit-workflow.md`](guides/role-permit-workflow.md)。
+- **角色类型**：`ADMIN`/`DEV`/`USER`（内置）与 `CUSTOM`（用户创建）；`update`/`delete` 仅 `CUSTOM`。
+- **只读人员目录**：租户全员查询用 [`tenant members-list`](references/rabetbase-tenant-members-list.md)；应用成员及角色归属查询用 [`app members-list`](references/rabetbase-app-members-list.md)。只查看事实时不要调用 `role user-add`/`user-remove`。
+- **加人/移人**：先 [`role user-resolve`](references/rabetbase-role-user-resolve.md) 拿 userId，再 [`role user-add`/`user-remove`](references/rabetbase-role-user-add.md)（`high-risk-write`，内部 read-merge-write，只改目标组）。
+- **建/改/删组**：[`role list/detail/create/update/delete`](references/rabetbase-role-list.md)。
+- **收紧菜单/接口（按组）**：[`role-menus-set`](references/rabetbase-permit-role-menus-set.md) / [`role-apis-set`](references/rabetbase-permit-role-apis-set.md)，必须显式 `--menus`/`--datasets`。
+- **单页权限（含行级只看自己）**：[`page-get`/`page-set`](references/rabetbase-permit-page-set.md)；行级 `SELF` 只用于 `--row-roles`。
+- **铁律**：写前先 `page-get`/`role-menus` 拿真实标识 → `--dry-run` 看 `data.before/after` → `--yes`；行级/接口收紧的运行态效果交给 `lovrabet data filter` 验证。
+
+## 配置作用域原则（`--global`）
+
+- **写操作默认当前项目**（`init`、`workspace add`、`config set`、`project create` 等），除非用户**显式**传 `--global`。
+- **不要**在用户未要求时给命令加 `--global`** — 默认行为已是「项目优先」；只有用户明确要改全局配置或不在项目内且意图写全局时才使用。
+- **`config set`**：在**没有**项目配置文件（当前目录未解析到 `.rabetbase.json`）且**未**传 `--global` 时，CLI **拒绝执行**并提示使用 `--global` 或先 `rabetbase init`，**不会**静默写入全局。
+- **`project create`** 生成的新项目 `.rabetbase.json` **只继承**少量全局偏好（如 `cookie` / `locale` / `format` / `riskLevel` 等），**不会**把全局 `apps` / `defaultApp` 带入新项目文件。
+- **`api pull` / `api list`**：默认仅针对**项目** `apps`；需要合并全局已登记应用时加 `--global`（见各命令 reference）。
+- **`app list`**：默认展示**合并**后的全量；`--global` 仅全局、`--project` 仅项目（见 [`rabetbase app list`](references/rabetbase-app-list.md)）。
+
+## app vs workspace 职责边界
+
+划分轴 = **「这是关于 app 的客观事实，还是关于我当前工作环境的配置？」**
+
+- **`app` = 应用的客观事实查询**：回答「我有/能访问哪些 app」和「某应用有哪些人员及角色归属」，与在哪写代码无关。**只读**，不承载增删。
+  - `app list`（本地登记视图）/ `app list --remote`（平台可访问目录）/ [`app members-list`](references/rabetbase-app-members-list.md)（应用人员）。
+- **`workspace` = 配置当前工作环境用哪些 app**：一切「改我的配置」的写操作都在这里。
+  - `workspace init`（首次绑定当前目录）/ `workspace use --app <name>`（切换当前目录默认应用）。
+  - `workspace add <name> --appcode <code>`（登记应用 profile）/ `workspace remove <name>`（移除本地 profile）。
+  - 默认写当前项目 `.rabetbase.json`；`--global` 写全局（全局视作一个大工作空间）。`init`/`use` 不从全局复制 cookie/accessKey。
+
+**三入口选型（不要混用）**：
+
+| 场景 | 命令 |
+|------|------|
+| 首次安装后的全局引导 | `rabetbase init` |
+| 当前目录还没绑定默认 app | `rabetbase workspace init --appcode <code>`（**始终**写 `defaultApp`） |
+| 目录已有配置，只再登记一个 profile | `rabetbase workspace add <name> --appcode <code>`（仅当尚无 default 时才顺带设默认；`--global` 写全局） |
+| 切换当前目录默认应用 | `rabetbase workspace use --app <name>` |
+
+**入口判断**：
+- 「看有哪些 app / 平台上能访问哪些」→ `app list`（`--remote` 查平台）。
+- 「看某应用有哪些人员及其角色」→ `app members-list --appcode <code>`。
+- 「看某租户有哪些人员」→ `tenant members-list --tenant-code <code>`。
+- 「登记/删除应用 profile」→ `workspace add` / `workspace remove`（要动全局清单时加 `--global`）。
+- 「让当前目录用某应用 / 切换默认应用」→ `workspace init` / `workspace use`。
+
+## Agent 禁止行为
+
+- **不要猜字段名** — 必须从 `dataset detail` 返回值获取真实字段名、类型、枚举值
+- **不要跳过 validate 与 dry-run** — 修改已有 SQL 并准备 `sql push` 前，必须先跑 `sql validate`；创建 SQL 或执行高风险同步前至少确认过 `sql create --dry-run`、`sql push --dry-run` 或 `sql delete --dry-run` 的预览
+- **不要手动拼 API URL** — 所有操作通过 CLI 命令完成，不要直接调 HTTP 接口
+- **不要臆测 sqlCode / id** — 从 `sql list` 或 `bff list` 获取真实标识
+- **不要臆测 dblink id 或分析 trace/plan id** — 从 `db list` / `db detail` / `db analyze-start` 的返回字段获取（见 [database-connection-workflow.md](guides/database-connection-workflow.md)）
+- **只使用可见命令** — 以本 skill、`rabetbase schema`、`rabetbase --help` 中出现的命令为准；不要凭训练记忆调用未出现的旧别名
+- **不要含糊处理失败** — `sql create` / `sql push` / `sql delete` / `bff push` / `bff delete` 返回失败时，必须明确告知用户是哪条资源失败、为什么失败
+- **不要在不确认表结构时就写 SQL** — 先 `dataset detail`，后写 SQL、Backend Function、页面……
+- **不要把案例字段当通用规则** — 任何 Demo、历史项目、示例里的字段名、枚举值、表名都不能照搬；必须以当前 `dataset detail` 为准
+- **不要循环单条查询** — 用 SDK `filter + $in` 批量查询，不要 N+1
+- **不要依赖 CLI 输出文本片段判断写入结果** — 对 `dataset rename --dry-run` / 正式执行，只读取结构化 envelope 的 `data.*` 稳定字段
+- **不要跳过 Dataset rename 最终线上回查** — 连续重命名后必须按 code 重新查询线上名称，不能只相信本地 plan 或 dry-run
+- **不要把 MCP 工具名当 CLI 命令** — 使用 `rabetbase sql list`，不是 `list_sql_queries`
+- **不要擅自加 `--global`** — 见上文「配置作用域原则」；默认写项目、读合并；仅在用户明确要求或文档说明的场景使用 `--global`。
+
+## 接口选型优先级
+
+遇到新需求时按优先级选择实现方式：
+
+1. **标准 SDK 接口**（filter/getOne/create 等）— 能用就不写 SQL
+2. **aggregate 聚合接口** — DB_TABLE 的简单分组汇总；METADATA 不默认支持 aggregate；聚合定义使用 `column` 指定列，`field` 仅作为历史兼容别名
+3. **自定义 SQL** — DB_TABLE 的复杂 JOIN、数据库函数、跨表统计；METADATA 不支持 SQL 路径
+4. **BFF** — 外部系统调用、跨表事务、复杂业务编排
+
+## SDK 核心规则
+
+### 初始化
+
+```typescript
+import { createClient } from "@lovrabet/sdk";
+const client = createClient({
+  appCode: "your-app-code",
+  accessKey: process.env.RABETBASE_ACCESS_KEY,
+  models: [{ tableName: "users", datasetCode: "abc123", alias: "users" }],
+});
+```
+
+### filter 查询（最常用）
+
+```typescript
+const result = await client.models.users.filter({
+  where: { status: { $eq: "active" } },
+  select: ["id", "name"],
+  orderBy: [{ createTime: "desc" }],
+  currentPage: 1,
+  pageSize: 20,
+});
+```
+
+参数名强制约束：`select`（非 fields）、`orderBy`（非 sort）、`currentPage`/`pageSize`（非 page/limit）
+
+where 条件强制使用操作符：`$eq` `$ne` `$gte` `$lte` `$gt` `$lt` `$in` `$contain` `$startWith` `$endWith`
+
+### SQL 调用
+
+```typescript
+const data = await client.sql.execute<MyRow>({
+  sqlCode: "xxx",
+  params: { key: "val" },
+});
+if (data.execSuccess && data.execResult) {
+  console.log(data.execResult);
+}
+```
+
+### BFF 调用
+
+```typescript
+const result = await client.bff.execute<DashboardData>({
+  scriptName: "getUserDashboard",
+  params: { userId: "123" },
+});
+```
+
+### 前端 vs BFF 关键差异
+
+|                 | 前端 SDK                                     | BFF (context.client)                 |
+| --------------- | -------------------------------------------- | ------------------------------------ |
+| SQL 返回值      | `{ execSuccess, execResult }`                | 直接返回数组 `T[]`                   |
+| 单条查询        | `getOne({ id })`                             | `getOne({ id })`                     |
+| 模型键          | 可通过初始化/生成代码使用 alias              | 使用 `"dataset_" + 32 位数据集 code` |
+| `filter()` 返回 | `tableData` 为列表数据                       | `tableData` 为列表数据，不是 `list`  |
+| `create()` 返回 | 以 SDK 文档/类型为准                         | 新记录 ID，不是完整对象              |
+| SDK 初始化能力  | `createClient` / `registerModels`            | 不可用；`context.client` 由平台注入  |
+| 调 BFF          | `client.bff.execute({ scriptName, params })` | —                                    |
+
+## 意图 → 命令索引
+
+| 意图 | 推荐命令 | 备注 |
+|------|---------|------|
+| 初始化项目 | [`rabetbase init`](references/rabetbase-init.md) | 智能检测旧配置，支持 `--appcode` 非交互；**不加 `--global`** |
+| 创建新项目 | [`rabetbase project create`](references/rabetbase-project-create.md) | 支持 `--name` + `--appcode` 非交互 |
+| 从 lovrabet-cli 迁移 | [`rabetbase project upgrade`](references/rabetbase-project-upgrade.md) | 6 步自动迁移，`--yes` 跳过确认 |
+| 老项目翻新蓝图 / 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) | `high-risk-write`；先审阅脚本命令体，独立 CLI 需人工提升风险上限并确认，嵌入式工具暂不开放 |
+| 安装 / 重装 / 刷新 CLI Built-in Skill | [`rabetbase cli-skill install`](references/rabetbase-cli-skill-install.md) | 由最新版官方 Skills CLI 从当前 npm 包内本地源重装同版本 Skill；发现本地 skill 过期时优先执行 |
+| 退出登录 | [`rabetbase auth logout`](references/rabetbase-auth-logout.md) | 删除本地认证 cookie |
+| 绑定当前用户的钉钉沙箱账号 | [`rabetbase user-account dingding-sandbox-bind`](references/rabetbase-user-account.md) | 先 `--dry-run` 核对 ID，正式执行显式加 `--yes`；不需要 appCode |
+| 诊断配置问题 | [`rabetbase doctor`](references/rabetbase-doctor.md) | Built-in Skill 一致性、合并配置、各侧 JSON 语法、域名、认证状态 |
+| 上报平台问题 | [`rabetbase issue report`](references/rabetbase-issue-report.md) | 由 Skill 组织完整客观事实，禁止代替平台侧做根因判断或方案设计 |
+| 上传应用文件 | [`rabetbase file upload`](references/rabetbase-file.md) | 返回可持久保存的 `filePath` |
+| 获取文件访问链接 | [`rabetbase file query-url`](references/rabetbase-file.md) | 默认短效；Markdown/HTML URL-only 内容显式加 `--long-term` |
+| 识别图片、PDF 或发票文字 | [`rabetbase ocr recognize`](references/rabetbase-ocr.md) | 支持 URL 或本地文件；本地文件自动串联上传、短效 URL 与 OCR |
+| 导出命令契约（flags/risk 等） | [`rabetbase schema`](references/rabetbase-schema.md) | 与 `--help` 同源；**无需登录**；大结果用 `--format compress` |
+| 更新 CLI 版本 | [`rabetbase update`](references/rabetbase-update.md) | 自动检测最新版本，CLI 与 Built-in Skill 一体升级 |
+| 初始化/切换当前工作目录应用 | [`rabetbase workspace`](references/rabetbase-workspace.md) | 写当前目录 `.rabetbase.json`；不从全局复制 cookie/accessKey |
+| 修改配置文件 | [`rabetbase config set <key> <value>`](references/rabetbase-config.md) | 默认写项目；无项目配置且未 `--global` 会拒绝；`--global` 写 `~/.rabetbase.json` |
+| 列出配置 | [`rabetbase config list`](references/rabetbase-config.md) | 查看当前生效的配置 |
+| 管理运行态 app-config | [`rabetbase app-config list/get/set/delete`](references/rabetbase-app-config.md) | 运行态 app-config 管理面；默认不输出明文 value，`set/delete` 先 `--dry-run` |
+| 管理当前研发应用的企业知识库 | [`rabetbase kb list/detail/create/update/delete`](references/rabetbase-kb.md) | 标准解析 `--app/--appcode`；仅 company scope；写操作先 dry-run，再显式 `--yes` |
+| 获取 BFF 通知配置 `configCode` | [`rabetbase notification config-list`](references/rabetbase-notification-config-list.md) | 默认查询 EMAIL 应用级通知配置；不输出渠道地址、配置内容或凭据 |
+| 查看线上菜单事实 / 菜单异常审计 | [`rabetbase menu list`](references/rabetbase-menu-list.md) | 返回 DFS 事实、children/page、URL、最近更新人/时间和 snapshotHash；异常治理先读 [`menu-anomaly-manual-cleanup`](guides/menu-anomaly-manual-cleanup.md) |
+| 创建外部网站链接菜单 | [`rabetbase menu external-link-create`](references/rabetbase-menu-external-link-create.md) | `write`；显式选择 `embedded` 或 `new-window`，仅接受 HTTPS；建议先 dry-run，正式执行不要求 `--yes` |
+| 原地更新既有外链 URL | [`rabetbase menu external-link-update`](references/rabetbase-menu-external-link-update.md) | 精确单 ID、URL-only；必须带旧 URL 与父级断言，先 dry-run，再复用参数加 `--yes` |
+| 修改任意类型菜单名称 | [`rabetbase menu rename`](references/rabetbase-menu-rename.md) | 精确单 ID、label-only；使用 `--expect-label` 防漂移，先 dry-run 并检查 before/after |
+| 同步本地微前端路由到平台 | [`rabetbase menu sync`](references/rabetbase-menu-sync.md) | 扫描 `src/pages` 创建缺失的 `procode` 菜单；不上传构建产物；正式执行前先 `--dry-run` |
+| 修改微前端菜单资源 URL | [`rabetbase menu asset-update`](references/rabetbase-menu-asset-update.md) | 高频高风险写入；用 ID/path 精确选目标或显式 `--all`，默认 patch 且保留加载模式，先 dry-run 再复用参数加 `--yes` |
+| 用户组与权限总览（先读工作流/决策树） | [`guides/role-permit-workflow.md`](guides/role-permit-workflow.md) | 先分清「成员归属」vs「能力授权」，再定位到具体命令；含 `role-menus-set` 与 `page-set` 的区别与 5 个剧本 |
+| 查看/创建/管理角色（用户组） | [`rabetbase role list/detail/create/update/delete`](references/rabetbase-role-list.md) | 仅 CUSTOM 可改/删；DEV/ADMIN 拒绝；写操作先 `--dry-run` 再 `--yes` |
+| 解析昵称/用户名到 userId | [`rabetbase role user-resolve`](references/rabetbase-role-user-resolve.md) | 基于租户成员目录；重名报错要求 `--user <id>` 消歧 |
+| 查询租户人员列表 | [`rabetbase tenant members-list --tenant-code <code>`](references/rabetbase-tenant-members-list.md) | 先校验当前账号所属租户，再返回全量人员；不分页、不输出邮箱/手机号/头像 |
+| 查询应用人员及角色列表 | [`rabetbase app members-list --appcode <code>`](references/rabetbase-app-members-list.md) | 按 userId 去重并聚合 `roles[]`；同时保留 ACTIVE/PENDING 角色归属 |
+| 把员工加入/移出角色 | [`rabetbase role user-add / user-remove`](references/rabetbase-role-user-add.md) | 内部全量 read-merge-write，只改目标角色；`high-risk-write`，先 `--dry-run` |
+| 配置页面权限 / 行级只看自己 | [`rabetbase permit page-get / page-set`](references/rabetbase-permit-page-set.md) | 行级 SELF 用 `page-set --row-roles SELF`；只改传入槽位，其余原样回写 |
+| 收紧角色菜单/接口访问（如销售组不看财务） | [`rabetbase permit role-menus-set / role-apis-set`](references/rabetbase-permit-role-menus-set.md) | 先 `dataset list`/`menu list` 定位，再显式 `--menus`/`--datasets`；一期不自动 suggest |
+| 按 ID 删除菜单或目录树 | [`rabetbase menu delete`](references/rabetbase-menu-delete.md) | 精确删除空 folder/非 folder 叶子；非空 folder 显式 `--recursive`，计划按叶子优先批量提交并回读 |
+| 创建空菜单分组 | [`rabetbase menu group-create`](references/rabetbase-menu-group-create.md) | group 持久化为 `type=folder`，保留平台生成的非空 path；先 dry-run 并检查创建位置与排序 |
+| 修改菜单分组排序 | [`rabetbase menu group-update`](references/rabetbase-menu-group-update.md) | 目标必须为 folder；修改任意菜单类型的名称统一使用 `menu rename`；先 dry-run 并检查 before/after |
+| 移动已有叶子菜单 | [`rabetbase menu move`](references/rabetbase-menu-move.md) | 使用精确源 ID、目标父级 ID 和当前父级断言；逐项 dry-run 并检查写后回读 |
+| 异步新建根分组 | [`rabetbase menu regroup-start`](references/rabetbase-menu-regroup-start.md) | 只接收精确非 folder 叶子 ID；返回 taskId，非幂等请求不自动重提 |
+| 查询通用异步任务 | [`rabetbase task status`](references/rabetbase-task-status.md) | 按 taskId + appCode 查询 `PENDING / PROCESSING / SUCCESS / FAILED`；只读，不重启业务操作 |
+| 查找数据集 | [`rabetbase dataset list --name "xxx"`](references/rabetbase-dataset-list.md) | 默认返回全部 DO V2 数据集；查指定来源用 `--source DB_TABLE` / `--source METADATA`；也可 `--code` 精确查 |
+| 查看表结构和字段 | [`rabetbase dataset detail --code xxx`](references/rabetbase-dataset-detail.md) | 含字段定义和操作列表 |
+| 废弃数据集 | [`rabetbase dataset delete`](references/rabetbase-dataset-delete.md) | high-risk-write；只从未删除数据集中定位，必须先 `--dry-run`，正式执行加 `--confirm --yes`，批量废弃推荐 `--expected-count` |
+| 恢复已删除数据集 | [`rabetbase dataset restore`](references/rabetbase-dataset-restore.md) | high-risk-write；只从已删除数据集中定位，必须先 `--dry-run`，正式执行加 `--confirm --yes`，批量恢复推荐 `--expected-count` |
+| 修改 Dataset 展示名 | [`rabetbase dataset rename`](references/rabetbase-dataset-rename.md) | 只更新 Dataset 展示名；必须先 `--dry-run`，用 `--expect-name` 防漂移；连续重命名先读对应章节 |
+| 从文本生成新 METADATA 数据集 | [`rabetbase dataset generate-start`](references/rabetbase-dataset-generate.md) / [`generate-status`](references/rabetbase-dataset-generate.md) | 三步：preview；审阅后提交；随后执行 `data.query.command`，优先按同一个 taskId 查询。`PENDING/PROCESSING` 非终态，未知或响应丢失不得自动重提；只在返回 `createdDataset.code` 后使用 Dataset |
+| 安全更新 Dataset 原始字段对象 | [`rabetbase dataset field-update`](references/rabetbase-dataset-field-update.md) | 使用 `--code` 定位 Dataset，只允许 patch 已知可变业务配置字段；必须先 `--dry-run`，用 `--expect-json` 防漂移 |
+| Dataset 顶层 extend 更新命令 | [`rabetbase dataset extend-update`](references/rabetbase-dataset-extend-update.md) | 当前无可写字段；不得用于 `businessGroup`。业务场景分组只能使用 `rabetbase dataset business-group-update` |
+| 更新业务场景分组 | [`rabetbase dataset business-group-update`](references/rabetbase-dataset-business-group-update.md) | 唯一入口；使用 `--code` 定位 Dataset；必须先 `--dry-run`，推荐用 `--expect-business-group` 防漂移 |
+| 查看 Dataset 操作定义 | [`rabetbase dataset operations --code xxx`](references/rabetbase-dataset-operations.md) | 获取 filter/getOne/create 等参数定义 |
+| 查看数据集关联关系 | [`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 写入所需表名来自显式参数或物理表事实 |
+| 首次生成智能列表页 | [`rabetbase page generate-start --datasetcode <code>`](references/rabetbase-page-generate-start.md) | 提交或复用服务端异步任务 |
+| 创建 React 自定义页面 | [`rabetbase page react-create --name "客户看板"`](references/rabetbase-page-react-create.md) | 创建初始 JSX/CSS/词包及菜单；先 dry-run |
+| 查询 React 自定义页面 | [`rabetbase page react-list`](references/rabetbase-page-react-list.md) | 返回页面 ID、页面名称、`pageUrl`（查看最新保存内容）和 `editPageUrl`（打开编辑器） |
+| 查看 React 自定义页面详情 | [`rabetbase page react-detail --id <pageId>`](references/rabetbase-page-react-detail.md) | 查询页面详情，`codeContent` 包含可修改后整体提交的完整页面文件 |
+| 更新 React 自定义页面 | [`rabetbase page react-update --id <pageId> --page-content <json>`](references/rabetbase-page-react-update.md) | 保存完整页面文件并创建新版本；先 dry-run |
+| 发布 React 自定义页面 | [`rabetbase page react-publish --id <pageId>`](references/rabetbase-page-react-publish.md) | 发布当前保存内容；先 dry-run 并明确确认 |
+| 查询智能列表页生成任务状态 | [`rabetbase page generate-status --datasetcode <code> --operation-id <id>`](references/rabetbase-page-generate-status.md) | 查询 job 状态，支持 `operationId` / `clientOperationId` |
+| 查询智能列表页生成任务状态 | [`rabetbase page generate-status --datasetcode <code> --task-id <id>`](references/rabetbase-page-generate-status.md) | 查询 job 状态；taskId 首选，operationId/clientOperationId 兼容。成功后仍读取标准页事实，未知状态不得自动重提 |
+| 查询智能列表页事实快照 | [`rabetbase page standard-page-status --datasetcode <code>`](references/rabetbase-standard-page-status.md) | 查询智能列表页四件套、残留页与菜单事实 |
+| 审计智能列表页关系绑定 | [`rabetbase page relation-audit --datasetcode <code>`](references/rabetbase-page-relation-binding.md) | 只读检查智能列表页 options 绑定是否匹配 `dataset relations` |
+| 同步已有智能列表页 | [`rabetbase page sync --datasetcode <code>`](references/rabetbase-page-sync.md) | 数据集字段变更后同步到关联智能列表页 |
+| 拉取智能列表页 schema 到本地 | [`rabetbase page pull --id <pageId>`](references/rabetbase-page-pull.md) | 写入 `.rabetbase/page/<appCode>/`，进入本地编辑工作流 |
+| 推送本地智能列表页 schema | [`rabetbase page push --id <pageId>`](references/rabetbase-page-push.md) | 推送后自动回拉 canonical schema 覆盖本地 |
+| 恢复已删除页面 | [`rabetbase page restore --id <pageId>`](references/rabetbase-page-restore.md) | 支持 STANDARD/JSX 自动识别；跨类型同 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` |
+| 生成 API 客户端代码 | [`rabetbase api pull`](references/rabetbase-api-pull.md) | 拉取数据集并生成 `src/api/` TypeScript 代码 |
+| 查看生成的 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 内容和参数定义 |
+| 新建本地同步 SQL | [`rabetbase sql create --name xxx --db-id 10001 --mode sql`](references/rabetbase-sql-create.md) | 先在远端创建，再落本地文件与 `sql.lock.json` |
+| 查看本地同步状态 | [`rabetbase sql status`](references/rabetbase-sql-status.md) | 检查 `added / modified / missing / unchanged / remoteOnly` |
+| 拉取远端 SQL 到本地 | [`rabetbase sql pull`](references/rabetbase-sql-pull.md) | 写入 `.rabetbase/sql/<appCode>/<dbName|db-<id>>/`，含 `@lovrabet` 头注释 |
+| 推送本地 SQL 到远端 | [`rabetbase sql push --sqlcode xxx --yes`](references/rabetbase-sql-push.md) | 以 `sql.lock.json` 为基准上传同步目录中的本地文件 |
+| 删除 SQL | [`rabetbase sql delete --sqlcode xxx --yes`](references/rabetbase-sql-delete.md) | 删除远端并将本地文件移入 `.rabetbase/sql-trash/` |
+| 校验 SQL 内容 | [`rabetbase sql validate --file xxx`](references/rabetbase-sql-validate.md) | 类型检测、危险语句检查、参数提取 |
+| 执行 SQL 查询 | [`rabetbase sql exec --sqlcode xxx`](references/rabetbase-sql-exec.md) | 支持 `--params` JSON 参数 |
+| 查看现有 BFF | [`rabetbase bff list`](references/rabetbase-bff-list.md) | 按类型和名称过滤，支持 `--app` 限定应用 |
+| 查看 BFF 详情 | [`rabetbase bff detail --id n`](references/rabetbase-bff-detail.md) | 含完整脚本内容 |
+| 创建本地 BFF | [`rabetbase bff create --type ENDPOINT --name xxx`](references/rabetbase-bff-create.md) | 在 `.rabetbase/bff/<appCode>/...` 下创建脚手架 |
+| 查看 BFF 本地状态 | [`rabetbase bff status`](references/rabetbase-bff-status.md) | 检查 added / modified / unchanged / remoteOnly |
+| 拉取远端 BFF | [`rabetbase bff pull`](references/rabetbase-bff-pull.md) | 从远端同步到本地 |
+| 推送本地 BFF | [`rabetbase bff push --yes`](references/rabetbase-bff-push.md) | high-risk-write，需 `--yes` |
+| 删除 BFF | [`rabetbase bff delete --yes --target xxx`](references/rabetbase-bff-delete.md) | high-risk-write，删远端并清理本地 |
+| 生成 SDK 代码 | [`rabetbase codegen sdk --code xxx`](references/rabetbase-codegen-sdk.md) | 按操作生成 TypeScript |
+| 生成 SQL 调用代码 | [`rabetbase codegen sql --sqlcode xxx`](references/rabetbase-codegen-sql.md) | sdk/bff 两种 target |
+| 列出已配置应用 | [`rabetbase app list`](references/rabetbase-app-list.md) | 默认合并视图；`--global` / `--project` 限定单层；`items[].named`、`meta` 见 reference |
+| 发现平台可访问应用 | `rabetbase app list --remote` | 查询当前登录账号在平台上的应用目录，不修改本地配置 |
+| 查询应用人员及角色归属 | [`rabetbase app members-list --appcode <code>`](references/rabetbase-app-members-list.md) | 全量只读；按 userId 去重，角色归属聚合到 `roles[]` |
+| 查询租户人员 | [`rabetbase tenant members-list --tenant-code <code>`](references/rabetbase-tenant-members-list.md) | 全量只读；租户必须属于当前账号 |
+| 查看 app 服务帮助 | `rabetbase app` | 只显示 `app` 子命令帮助，不等价于 `app list` |
+| 绑定当前目录到应用 | [`rabetbase workspace init --appcode <code>`](references/rabetbase-workspace.md) | 首次绑定；**始终**写 `defaultApp`；与 `rabetbase init`（全局引导）不同 |
+| 切换当前工作目录默认应用 | [`rabetbase workspace use --app <name>`](references/rabetbase-workspace.md) | 持久修改当前目录 defaultApp |
+| 登记应用 | [`rabetbase workspace add <name> --appcode <code>`](references/rabetbase-workspace.md) | 仅当尚无 default 时顺带设默认；`--global` 写全局 |
+| 移除应用 | [`rabetbase workspace remove <name>`](references/rabetbase-workspace.md) | 只移除本地 profile，移除后自动切换 default |
+| 临时切换应用执行 | 任何命令加 `--app <name>` 或 `--appcode <code>` | 不修改配置文件 |
+| 查看配置文件格式 | [`.rabetbase.json` 配置参考](references/rabetbase-config.md) | 完整字段、优先级、环境变量 |
+
+## 命令分组
+
+> **执行前必做：** 从下表定位到命令后，务必先阅读对应命令的 reference 文档，再调用命令。
+
+| 命令分组 | 说明 |
+|----------|------|
+| Quick Start | [`init`](references/rabetbase-init.md) |
+| Project | [`create`](references/rabetbase-project-create.md) / [`upgrade`](references/rabetbase-project-upgrade.md) |
+| Workspace | [`workspace init` / `workspace use` / `workspace add` / `workspace remove`](references/rabetbase-workspace.md) |
+| Run Scripts | [`run`](references/rabetbase-run.md) |
+| Authentication | [`auth login`](references/rabetbase-auth-login.md) / [`auth logout`](references/rabetbase-auth-logout.md) |
+| User Accounts | [`dingding-sandbox-bind`](references/rabetbase-user-account.md) |
+| Self Update | [`update`](references/rabetbase-update.md) |
+| Schema | [`schema` / `schema export`](references/rabetbase-schema.md) |
+| Diagnostics | [`doctor`](references/rabetbase-doctor.md) |
+| Platform Issue | [`report`](references/rabetbase-issue-report.md) |
+| File | [`upload` / `query-url`](references/rabetbase-file.md) |
+| Configuration | [`config set`](references/rabetbase-config.md) / [`config get`](references/rabetbase-config.md) / [`config list`](references/rabetbase-config.md) |
+| Runtime App Config Management | [`app-config list/get/set/delete`](references/rabetbase-app-config.md) |
+| Company Knowledge Base | [`kb list/detail/create/update/delete`](references/rabetbase-kb.md) |
+| Menu | [`list`](references/rabetbase-menu-list.md) / [`external-link-create`](references/rabetbase-menu-external-link-create.md) / [`external-link-update`](references/rabetbase-menu-external-link-update.md) / [`rename`](references/rabetbase-menu-rename.md) / [`sync`](references/rabetbase-menu-sync.md) / [`asset-update`](references/rabetbase-menu-asset-update.md) / [`delete`](references/rabetbase-menu-delete.md) / [`group-create`](references/rabetbase-menu-group-create.md) / [`group-update`](references/rabetbase-menu-group-update.md) / [`move`](references/rabetbase-menu-move.md) / [`regroup-start`](references/rabetbase-menu-regroup-start.md) |
+| Async Tasks | [`task status`](references/rabetbase-task-status.md) |
+| Notification Configuration | [`notification config-list`](references/rabetbase-notification-config-list.md) |
+| Roles | [`list`](references/rabetbase-role-list.md) / `detail` / `create` / `update` / `delete` / [`user-resolve`](references/rabetbase-role-user-resolve.md) / [`user-add` / `user-remove`](references/rabetbase-role-user-add.md) |
+| Permissions | [`page-get` / `page-set`](references/rabetbase-permit-page-set.md) / `role-menus` / [`role-menus-set`](references/rabetbase-permit-role-menus-set.md) / [`role-apis-set`](references/rabetbase-permit-role-apis-set.md) |
+| Tenant Members | [`tenant members-list`](references/rabetbase-tenant-members-list.md)（当前账号所属租户的全量人员目录） |
+| app commands | [`list`](references/rabetbase-app-list.md)（只读应用事实；平台目录用 `list --remote`）/ [`members-list`](references/rabetbase-app-members-list.md)（应用人员及角色归属）。登记/移除应用改用 `workspace add` / `workspace remove` |
+| dataset commands | [`list`](references/rabetbase-dataset-list.md) / [`detail`](references/rabetbase-dataset-detail.md) / [`delete`](references/rabetbase-dataset-delete.md) / [`restore`](references/rabetbase-dataset-restore.md) / [`generate-start/status`](references/rabetbase-dataset-generate.md) / [`rename`](references/rabetbase-dataset-rename.md) / [`field-update`](references/rabetbase-dataset-field-update.md) / [`extend-update`](references/rabetbase-dataset-extend-update.md) / [`business-group-update`](references/rabetbase-dataset-business-group-update.md) / [`operations`](references/rabetbase-dataset-operations.md) / [`relations`](references/rabetbase-dataset-relations.md) / [`relation-audit`](references/rabetbase-dataset-relation-audit.md) / [`relation-create/update/delete`](references/rabetbase-dataset-relation-mutations.md) |
+| Smart List Page commands | [`generate-start`](references/rabetbase-page-generate-start.md) / [`generate-status`](references/rabetbase-page-generate-status.md) / [`standard-page-status`](references/rabetbase-standard-page-status.md) / [`relation-audit`](references/rabetbase-page-relation-binding.md) / [`sync`](references/rabetbase-page-sync.md) / [`pull`](references/rabetbase-page-pull.md) / [`push`](references/rabetbase-page-push.md) |
+| React custom page commands | [`react-create`](references/rabetbase-page-react-create.md) / [`react-list`](references/rabetbase-page-react-list.md) / [`react-detail`](references/rabetbase-page-react-detail.md) / [`react-update`](references/rabetbase-page-react-update.md) / [`react-publish`](references/rabetbase-page-react-publish.md) |
+| 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) |
+| 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) |
+| bff commands | [`list`](references/rabetbase-bff-list.md) / [`detail`](references/rabetbase-bff-detail.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) |
+| CLI Built-in Skill | [`install`](references/rabetbase-cli-skill-install.md) |
+
+## 风险控制
+
+所有声明式命令有 **risk level**：
+
+| 级别              | 含义                                                                                                    | 使用方式                                         |
+| ----------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `read`            | 不创建、更新或删除业务数据；允许远端读取后生成可重建本地文件或维护本机 CLI                              | 可直接执行                                       |
+| `write`           | 创建或修改可控范围的数据与本地配置                                                                      | 命令支持 dry-run 时先检查预览                    |
+| `high-risk-write` | 覆盖、删除或明显影响线上运行行为                                                                        | 按命令 reference 完成 dry-run、计划或显式确认    |
+
+具体命令的 risk、flags 与确认要求以 `rabetbase schema` 为唯一事实来源；reference 只描述稳定执行输入、输出与安全前置。
+
+`sql validate` 是 SQL 内容校验入口；SQL 写入统一通过 `sql create` 或编辑同步文件后执行 `sql push`。
+
+配置 `riskLevel` 可限制允许执行的最高风险等级（详见 [配置参考](references/rabetbase-config.md)）。
+
+## 输出格式
+
+声明式命令统一走 **标准信封**：`ok`、`command`、`risk`、可选 `data`（失败时可有 `error` 等，以实际输出为准）。
+
+| 格式                    | 用途                                   | 说明                                                           |
+| ----------------------- | -------------------------------------- | -------------------------------------------------------------- |
+| **`--format compress`** | **AI / 脚本优先**                      | 与 `json` **语义相同**，**单行紧凑**、无缩进换行，显著省 token |
+| `--format json`         | 程序解析、调试                         | 同上信封，**缩进**，便于人工阅读                               |
+| `--format pretty`       | 人类阅读（未指定 format 时的常见默认） | 非 JSON 的彩色文本                                             |
+| `--format table`        | 列表数据                               | 表格                                                           |
+
+**`--jq '<expr>'`**（全局）：仅配合 **`json` 或 `compress`**；对**最终打印的整段 JSON**执行 jq（表达式作用在信封上，例如取 `data` 内字段用 `.data.xxx`）。**jq 可执行文件**按 **`JQ_PATH` → CLI 内置 sidecar jq → `PATH` 上的 jq** 的顺序解析。若显式设置了 **`JQ_PATH`**，它必须指向一个真实可执行文件；否则命令会直接报错，不会静默回退。
+
+**不确定子命令、flags、risk、是否要 appcode**：执行 **`rabetbase schema`**（即 `schema export`，**无需认证**），输出与 `rabetbase --help` 同源的机器可读元数据；详见 [`references/rabetbase-schema.md`](references/rabetbase-schema.md) 与仓库 **`docs/user-guide/12-schema命令.md`**。
+
+## 常见错误速查
+
+| 错误类型           | 含义                                                       | 解决方案                                                   |
+| ------------------ | ---------------------------------------------------------- | ---------------------------------------------------------- |
+| `auth_required`    | 未登录                                                     | 执行 `rabetbase auth`                                      |
+| `config_missing`   | 未配置 appcode                                             | `rabetbase workspace init --appcode <code>` 或传 `--appcode` |
+| `flag_missing`     | 缺少必填参数                                               | 检查 reference 文档确认必填 flags                          |
+| `validation_error` | 输入校验失败（含 SQL 类型阻止）                            | 检查 SQL 内容或参数格式                                    |
+| `api_error`        | 后端 API 错误                                              | 检查 appcode、网络、权限                                   |
+| `cancelled`        | 用户取消高风险操作                                         | 用 `--yes` 跳过确认，或修改 riskLevel                      |
+| `blocked`          | 平台冲突检测或资源状态冲突（常见于旧保存链路或平台侧限制） | 明确说明未完成远端写入，引导用户去平台处理或改走同步工作流 |
+
+## 冲突处理
+
+凡是出现 `blocked: true`、`action: "blocked"`、或其他明确表示**远端未写入成功**的返回：都必须直接说明“平台未保存/未同步成功”，必要时引导用户去平台处理或回到 `create + 本地编辑 + push` 工作流；**禁止重试绕过、禁止粉饰为已保存**。完整分支表、响应 JSON 样例与沟通要求见 [`guides/conflict-detection.md`](guides/conflict-detection.md)。
+
+## 前端页面规则
+
+- CLI 生成的页面顶部注释必须保留，追加说明用 `@modified`
+- 页面组件设置 `displayName`
+- 写页面前必须 `dataset detail` 确认字段和关系
+- 禁止 emoji、AI 味文案、感叹号、花哨颜色；文案简洁专业
+- 图标用 `@ant-design/icons`，颜色用 AntD token
+
+## 深入指南
+
+**文档分层**：`references/` 按 **单条 CLI 命令**（执行前先读对应页）；`guides/` 按 **横切主题**（工作流、数据访问、前后端规范）。二者配合 SKILL 正文渐进披露。
+
+以下 guide 提供详细说明、示例与边界情况：
+
+| 主题                   | Use when                                                                                                              | Guide                                                                       |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| SDK 完整参数与返回值   | 初始化 client、filter/create、sql.execute、bff.execute、错误处理                                                      | [`typescript-sdk.md`](guides/typescript-sdk.md)                             |
+| SQL MyBatis 与动态 SQL | 写自定义 SQL、`<if>`/`<foreach>`、参数绑定                                                                            | [`sql-mybatis.md`](guides/sql-mybatis.md)                                   |
+| 前端页面开发约束       | React 页、表单、列表、与数据集绑定                                                                                    | [`frontend-development.md`](guides/frontend-development.md)                 |
+| 故障诊断               | CLI/登录/数据集/保存失败排障                                                                                          | [`troubleshooting.md`](guides/troubleshooting.md)                           |
+| BFF 脚本规范           | HOOK/ENDPOINT/COMMON、`context.client`、消息通知扩展、目录与注释模板                                                   | [`backend-function.md`](guides/backend-function.md)                         |
+| 数据接口访问           | 先 detail 再编码、外键/枚举、禁止 N+1、批量与关联查询；可选 `lovrabet data` 查数（**`lovrabet` CLI ≥ 2.0** 且已安装） | [`data-api-guidelines.md`](guides/data-api-guidelines.md)                   |
+| SQL 创建工作流         | list/detail → pull/new → edit → validate → status → push/delete → exec 全链路                                         | [`sql-creation-workflow.md`](guides/sql-creation-workflow.md)               |
+| BFF 创建工作流         | new → status → dry-run → pull/push                                                                                    | [`bff-creation-workflow.md`](guides/bff-creation-workflow.md)               |
+| 冲突检测与保存         | `blocked`、未保存时的用户沟通、响应结构                                                                               | [`conflict-detection.md`](guides/conflict-detection.md)                     |
+| 质量与最佳实践         | 审查 SQL/BFF、命名、高危边界、描述字段                                                                                | [`best-practices.md`](guides/best-practices.md)                             |
+| 数据库连接与分析       | 接入/改连/测连、`traceId` 来源、`db analyze-*` 与 dataset 分工；子命令速查见上文 **「数据库连接（db）」**             | [`database-connection-workflow.md`](guides/database-connection-workflow.md) |
+| 菜单异常审计与安全修复 | 重复 path、根级菜单重名、空 folder 删除计划和平台处理后回查                                                          | [`menu-anomaly-manual-cleanup.md`](guides/menu-anomaly-manual-cleanup.md)   |
+| 用户组与权限配置       | 建组/加人、按组收紧菜单与接口、单页权限与行级只看自己；先分清成员归属 vs 能力授权                                       | [`role-permit-workflow.md`](guides/role-permit-workflow.md)                 |