rabetbase

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 config init。交互模式选择 Mainland China (cn) 或 Indonesia (id)；非交互模式显式传 --region cn|id，未传时默认 cn。企业独立部署使用 --domain-config <file> 或六个 --*-domain flags。config init 固定重建全局节点/Domain 配置，保留 Cookie、AccessKey、format、locale 和应用绑定，但不登录、不绑定项目；随后再执行 rabetbase auth login
2. AppCode：确保 .rabetbase.json 中设置了 apps（单应用自动选中；多应用再配 defaultApp），或兼容读取的顶层 appcode，或通过 --appcode <code> / --app <name> 传入。旧 .lovrabet.json 不会自动读取
3. 配置文件：rabetbase config init 固定写全局 ~/.rabetbase.json，不接受项目作用域；默认 cn 不落冗余 region。官方节点模式清理显式和遗留 Domain，独立部署模式清理旧 region/Domain 后写入所提供的覆盖值。完整字段说明见 .rabetbase.json 配置参考。当前目录应用绑定使用下方 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 / Backend Function 目录：新建或长期维护的源文件应落在 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 工作。
   • Backend Function：.rabetbase/bff/<appCode>/...（由 bff create 创建或 bff pull 同步；与 bff status / bff push 扫描范围一致）。详见 guides/sql-creation-workflow.md、guides/bff-creation-workflow.md。
10. 运行态查数显式交接 — rabetbase 只负责 Dataset 结构与研发发布。不需要真实行数据时，lovrabet CLI 可以不装。一旦要验证真实业务行数据，必须交接给 lovrabet data filter/getOne；不可用时报告阻断并提示安装 lovrabet Skill 与 CLI。不要调用已移除的 rabetbase data filter/getOne，也不要由本 Skill 静默安装或修复运行态 CLI。rabetbase sql exec 只验证已发布 SQL，不是行数据查询的通用替代。详见 guides/data-api-guidelines.md。

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 → Custom SQL
   • 图表、统计卡片或数据大屏 → 自定义页面 + ECharts；数据层根据查询复杂度选择 Dataset 或 Custom SQL
   • 当前用户、角色、数据范围、外部系统、跨表事务或复杂业务编排 → Backend Function；Backend Function HOOK 可挂 DB_TABLE 或 METADATA，具体 operation 以后端返回为准
2. 先拿元数据，再写代码
   • 至少先查 rabetbase dataset detail --code xxx --format compress（或 json）获取表结构
   • 跨表场景还需查目标表的结构
   • 写入前用 data.fields[] 确认真实字段、必填字段、枚举选项；枚举/选择字段写入 options[].value，不是展示 label
   • 需要了解数据集关联关系时用 rabetbase dataset relations --format compress（或 json）；需要审计关系事实错误和人工复核项时用 rabetbase dataset relation-audit --format compress
   • 需要从文本需求创建新的 METADATA 数据集时，先读 dataset generate-start/status，执行 preview 写出 design 文件，审阅后用 generate-start --apply --design-file 提交任务，再用 generate-status 查询到成功
   • 管理物理库连接 / 测连 / 同步表结构分析时用 rabetbase db …（先 db list，trace/plan id 见 database-connection-workflow.md）
   • DBAgent 增量分析默认先执行一次异步差异刷新：调用 db diff-refresh-start，保存 traceId，并用 db diff-refresh-status 查询同一任务到终态；成功后按原始意图执行 db diff --all（差异表）或 db tables（全部表）。无论 tableCount 大小都执行刷新；只有用户明确表示“不需要分析”“不刷新”或“只看现有结果”时才跳过异步刷新，并说明结果可能不是最新事实
   • 需要查看全部表（含无差异表）或主动重新分析既有表时，用 db tables；它固定聚合全表分页。db diff --all 只聚合全部差异分页
   • DB 增量分析先对完整 toAnalyzeTables 执行 db analyze-batch-plan；它生成的是本地批次方案，不是服务端 planId，也不会创建任务。再严格按批次顺序启动；每批独立保存 planId（即 analyze-start 返回值），当前批次到达已知终态前不得启动下一批
   • 全部批次结束后再次执行异步差异刷新并重新获取完整差异；仍未收敛时，按 database-connection-workflow.md 对剩余 toAnalyzeTables 逐表串行重试且每表只恢复一次。仅当用户明确要求跳过分析/刷新时直接读取现有差异。状态查询失败继续使用原 planId，不得重复启动任务
   • 输出很大且只需子集时，在 compress/json 上加 --jq '.data…' 缩小结果
   • 需要真实业务行数据时必须交接给 lovrabet data filter/getOne；lovrabet 不可用时报告阻断并提示安装 Skill 与 CLI，不要静默安装或修复，也不要用 rabetbase sql exec 当行数据替代，见 guides/data-api-guidelines.md
   • 需要 src/api/api.ts / client.ts 时：先 rabetbase api pull --format compress 取 data.models、data.files、data.needsAgentMerge，再按 sdk-client-generation.md 更新 TypeScript。api pull 不会覆盖已有 api.ts/client.ts
3. SQL 工作流严格分步
   • 推荐路径：查现有(sql list/detail) 或新建(sql create) → 拉/落本地(sql pull / sql create) → 编辑同步目录文件 → 可选校验(sql validate) → 检查状态(sql status) → 先预览(sql push --dry-run / sql delete --dry-run) → 再 sql push / sql delete → sql detail / sql exec 验证
   • 先使用 sql list/detail 查找可复用的 Custom SQL；没有满足需求的资源时，按照 sql-creation-workflow.md 与 sql-mybatis.md 创建、校验、发布并验证
   • 页面执行已发布的 Custom SQL 时使用 sqlCode + params；Backend Function 默认使用 context.client.sql.byName(sqlName).execute({ params })，sql.execute({ sqlCode, params }) 仅作兼容路径
4. Backend Function 工作流严格分步
   • 查现有 → 确认字段或通知配置 → 查公共函数 → 本地创建(bff create) → 检查状态(bff status) → 先预览(--dry-run) → 再拉取/推送/删除
   • 创建会发送消息通知的 Backend Function 时，先读取 backend-function.md 的“消息通知扩展”契约，再执行 rabetbase notification config-list --type EMAIL 获取当前应用的 configCode；不得猜测渠道、收件人或把密钥写进脚本
   • 推送完成只代表脚本配置已同步到平台；若用户要确认最终运行效果，显式交接到运行验证（如可用的 lovrabet bff exec），不要把运行验证伪装成 rabetbase 已完成
5. 页面体系选择
   • 数据列表页（Data List Page）是数据集驱动的结构化页面组，用于数据查看、维护和模型验证，不等同于最终业务工作台
   • 自定义页面（Custom Page）是完整代码文件驱动的独立页面，用于工作台、看板、门户和复杂业务交互；当前 React JSX 只是渲染实现，不是页面产品类型
   • 图表、统计卡片和数据大屏使用自定义页面与白名单内的 ECharts
   • 页面体系不明确时，先向用户确认；不要为同一目标同时创建数据列表页与自定义页面
6. 数据列表页（Data List Page，page）工作流
   • 工作流判断先看 guides/page-development-workflow.md
   • page 命令职责分离：page generate-start 负责提交或复用任务，page generate-status 负责查询任务状态，page data-list-status 负责查询数据列表页事实
   • 数据集字段变更后同步已有数据列表页：page sync
   • 页面关系绑定审计：先读 rabetbase-page-relation-binding.md，再执行 page relation-audit
   • 遇到“关联数据带不出 / 数据列表页没有生成关联关系 / 页面关联绑定异常”类问题，固定顺序是：dataset relations 只读确认关系事实 → dataset relation-audit 审计关系事实风险 → page data-list-status 判断页面是否存在 → page relation-audit 审计页面绑定；若关系事实本身不对，先按 dataset relation-create/update/delete 做 --dry-run 方案并等用户确认；已有页面再 page sync --dry-run，无页面走 page generate-start --dry-run
   • page sync 只负责同步已有数据列表页，不是数据集关系修复命令，也不能承诺自动修复所有 wrong_code / wrong_label / missing
   • 本地 schema 开发：page pull → IDE 编辑 → page push
   • 恢复已删除页面：先读 page restore，CLI 产品类型只使用 DATA_LIST|CUSTOM；默认按 ID 自动识别，存在跨类型同 ID 时显式传 --page-type
   • 需要理解 formal schema 组件语义时，再按需阅读 knowledge/page-schema/ 下的 PageSchema 组件资料；不要把它与 rabetbase page 命令 reference 混淆
7. 自定义页面工作流
   • 自定义页面与数据列表页是两类独立页面能力，不混用两类页面的命令
   • 创建、修改或发布前，必须先阅读 custom-page-workflow.md，再按其中的编排读取对应原子命令 reference
   • 编写 JSX、CSS 或词包前，必须阅读 generation-standards.md；选择 UI 组件时阅读 components.md
8. Legacy modernization / Application Blueprint 工作流
   • 当用户要把无人交接老项目、外包接手项目或遗留系统翻新到 Lovrabet 体系时，先阅读 guides/legacy-application-blueprint-workflow.md
   • 主产物是 .rabetbase/blueprint/<appCode>/application-blueprint.md，不是直接生成或推送 SQL/Backend Function
   • 必须把老代码 Logic Graph 与 dbagent 已生成的 Dataset / Relations 绑定，再判断 Instant API、Custom SQL、Backend Function、Hook、COMMON 或 Java Service 落点

应用决议指引

1. 已明确 appcode

   • 用户直接给了 app-xxxx
   • 或当前命令已经显式传了 --appcode
   • 直接执行目标命令，不需要先查 rabetbase app list --remote

2. 已明确本地应用名

   • 当前项目 .rabetbase.json 已有唯一 app，或多 app 已配置 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 与 task status。该流程的完成口径不是“任务已提交”，而是异步重新分组任务到达明确终态：

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 取 id 与 latestAnalysisTraceId（如有）。
• 只读常用：db detail、db test、db tables、db diff。db tables 固定聚合全部表及分析状态；db diff 只读差异结果，--all 只聚合全部差异分页。
• 差异刷新：db diff-refresh-start/status。CLI 发起 DBAgent 增量分析时，无论 tableCount 多少或是否缺失，默认先刷新再读取差异；只有用户明确要求跳过分析/刷新时才直接读取现有结果。刷新与 schema analyze-* 是两类任务，不得混用。
• 分析任务：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 获取未收敛表；只有用户明确要求跳过分析/刷新时才直接读取。随后逐表串行执行 analyze-start --tables <单表>，每表只恢复一次；累计原因计数只作可能不完整的参考展示。Agent 可语义理解原始 errorMsg 辅助解释和建议，但两者都不驱动任务状态、重提任务或收敛判断。
• ER 图引导：db analyze-status 终态成功后，检查并转述 data.links.erPage；若没有 data.links，补 --appcode 或进入已配置 app 的项目上下文后重查。
• 写入：db create / db update 默认先测试未保存配置，只有显式 --skip-connection-test 才跳过；db delete 必须先 dry-run，执行前重新检查 DB_TABLE Dataset 依赖，有依赖即阻止且无 force。三者都支持 --dry-run。
• 横切流程与 trace/plan：database-connection-workflow.md。单命令细则见 references/rabetbase-db-*.md（与仓库 src/commands/db/ 一一对应）。

开发角色与协作者（role）

rabetbase role 只管理开发角色与开发协作者关系，输出明确包含 scope: "dev"。业务人员角色、用户组成员以及页面、菜单、数据集权限属于 lovrabet。若 lovrabet 当前 Help/Schema 尚未提供对应命令，应明确告知能力暂不可用，不得改用 rabetbase 代替，也不得跨端双写。

• 角色类型：ADMIN / DEV / OWNER（内置）与已有 CUSTOM；update / delete 仅 CUSTOM。当前不提供 role create。
• 只读人员目录：租户全员查询用 tenant members-list；应用成员及角色归属查询用 app members-list。只查看事实时不要调用 role user-add/user-remove。
• 加人/移人：先 role user-resolve 拿 userId，再 role user-add/user-remove（high-risk-write，只改目标开发角色；OWNER 直接拒绝）。
• 查看/改/删已有组：role list/detail/update/delete。
• 铁律：写前先读取当前角色/成员事实 → --dry-run 看 data.before/after → 高风险写显式 --yes；不要用 rabetbase 修改运行态权限。

配置作用域原则（--global）

• 普通写操作默认当前项目（workspace add、config set、project create 等），除非用户显式传 --global；config init 是首次连接配置入口，固定写全局配置。
• 不要在用户未要求时给命令加 --global** — 默认行为已是「项目优先」；只有用户明确要改全局配置或不在项目内且意图写全局时才使用。
• config set：在没有项目配置文件（当前目录未解析到 .rabetbase.json）且未传 --global 时，CLI 拒绝执行并提示使用 --global 或先 rabetbase workspace init --appcode <code>，不会静默写入全局。
• project create 生成的新项目 .rabetbase.json 只继承少量全局偏好（如 cookie / locale / format / riskLevel 等），不会把全局 apps / defaultApp 带入新项目文件；同时生成浏览器安全的 src/api/sdk-config.ts：默认中国大陆节点不写路由，ID 写 region: "id"，非默认企业 Runtime 写 runtimeDomain 且优先于 region，不下发认证配置。模板的 Vite 本地开发和 preview 地址也按项目 region 选择对应的 HTTPS 域名与证书：ID 使用 https://dev.lovrabet.id，中国大陆使用 https://dev.lovrabet.com。
• api pull / api list：默认仅针对项目 apps；需要合并全局已登记应用时加 --global（见各命令 reference）。
• app list：默认展示合并后的全量；--global 仅全局、--project 仅项目（见 rabetbase app list）。

app vs workspace 职责边界

划分轴 = 「这是关于 app 的客观事实，还是关于我当前工作环境的配置？」

• app = 应用的客观事实查询：回答「我有/能访问哪些 app」和「某应用有哪些人员及角色归属」，与在哪写代码无关。只读，不承载增删。
  • app list（本地登记视图）/ app list --remote（平台可访问目录）/ app members-list（应用人员）。
• 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 config init
当前目录还没绑定 app	rabetbase workspace init --appcode <code>（单应用不写 defaultApp）
目录已有配置，只再登记一个 profile	rabetbase workspace add <name> --appcode <code>（从单应用变为多应用时保留原应用为默认；--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 接口
• 不要向产品用户展开研发实现 — 回答角色权限操作时，不输出工程仓库、Controller、数据库表、接口路径、MR 排查或迁移过程；只说明 CLI 命令、角色边界、风险和可验证结果
• 不要臆测 sqlCode / id — 从 sql list 或 bff list 获取真实标识
• 不要臆测 dblink id 或分析 trace/plan id — 从 db list / db detail / db analyze-start 的返回字段获取（见 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. Backend Function — 外部系统调用、跨表事务、复杂业务编排

SDK 核心规则

初始化

import { createClient } from "@lovrabet/sdk";
const client = createClient({
  appCode: "your-app-code",
  authMode: "client-ak", // 传 accessKey 时必须显式声明；缺省 authMode 一律走 cookie 模式，accessKey 会被忽略
  accessKey: process.env.RABETBASE_ACCESS_KEY,
  models: [{ tableName: "users", datasetCode: "abc123", alias: "users" }],
});

认证模式必须显式声明：accessKey（仅 accessKey）用 authMode: "client-ak"；accessKey + secretKey 或 token 的签名场景用 authMode: "openapi"；浏览器 Cookie 环境省略 authMode（默认 cookie）。

filter 查询（最常用）

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 $gt $lt $gte（或别名 $gteq）$lte（或别名 $lteq）$in $contain $startWith $endWith $notNull（$gteq/$lteq 为后端兼容别名，映射同一 SQL，新代码推荐 $gte/$lte）

SQL 调用

页面 SDK 通过已发布 Custom SQL 的 sqlCode + params 执行查询；Backend Function 默认通过当前应用内唯一 sqlName 的 context.client.sql.byName(sqlName).execute({ params }) 执行查询，sql.execute({ sqlCode, params }) 作为兼容调用方式。

const data = await client.sql.execute<MyRow>({
  sqlCode: "xxx",
  params: { key: "val" },
});
if (data.execSuccess && data.execResult) {
  console.log(data.execResult);
}

自定义页面需要图表时，在其 React JSX 实现中使用 ECharts 呈现；只读查询且平台 sqlCode 权限已经满足时可以直接调用上面已发布的 Custom SQL。需要基于当前用户、角色、数据范围或业务规则做额外控制时，页面改调 Backend Function，由 Backend Function 完成校验后再执行该 Custom SQL。执行失败时保留并报告原始错误，根据 SQL 资源状态、参数与权限定位问题。

Backend Function 调用

const result = await client.bff.execute<DashboardData>({
  scriptName: "getUserDashboard",
  params: { userId: "123" },
});

前端 vs Backend Function 关键差异

	前端 SDK	Backend Function (context.client)
SQL 返回值	{ execSuccess, execResult }	直接返回数组 T[]
单条查询	getOne({ id })	getOne({ id })
数据集访问	可通过初始化/生成代码使用 alias	DB_TABLE 默认使用 models.byTable(tableName, { dblinkId? })；METADATA 使用 "dataset_" + 数据集 code，DB_TABLE 也支持该兼容调用方式
filter() 返回	tableData 为列表数据	tableData 为列表数据，不是 list
create() 返回	以 SDK 文档/类型为准	新记录 ID，不是完整对象
SDK 初始化能力	createClient / registerModels	不可用；context.client 由平台注入
调 Backend Function	client.bff.execute({ scriptName, params })	—

意图 → 命令索引

意图	推荐命令	备注
初始化连接配置	rabetbase config init	选择官方节点或导入独立部署 Domain
创建新项目	rabetbase project create	支持 --name + --appcode 非交互
从 lovrabet-cli 迁移	rabetbase project upgrade	6 步自动迁移，--yes 跳过确认
老项目翻新蓝图 / Legacy Application Blueprint	guides/legacy-application-blueprint-workflow.md	先输出 .rabetbase/blueprint/<appCode>/application-blueprint.md，把老代码逻辑与 Dataset / Relations 绑定后再生成迁移 Backlog
运行 package.json 脚本	rabetbase run <script>	write；先审阅脚本命令体，嵌入式工具暂不开放
安装 / 重装 / 刷新 CLI Built-in Skill	rabetbase cli-skill install	由最新版官方 Skills CLI 从当前 npm 包内本地源重装同版本 Skill；发现本地 skill 过期时优先执行
退出登录	rabetbase auth logout	删除本地认证 cookie
绑定当前用户的钉钉沙箱账号	rabetbase user-account dingding-sandbox-bind	write；先 --dry-run 核对 ID，正式执行不要求 --yes；不需要 appCode
诊断配置问题	rabetbase doctor	Built-in Skill 一致性、合并配置、各侧 JSON 语法、域名、认证状态
上报平台问题	rabetbase issue report	由 Skill 组织完整客观事实，禁止代替平台侧做根因判断或方案设计
上传应用文件	rabetbase file upload	返回可持久保存的 filePath
获取文件访问链接	rabetbase file query-url	默认短效；Markdown/HTML URL-only 内容显式加 --long-term
提取票证类业务材料的文字与结构化字段	rabetbase ocr recognize	发票、票据、证照等；不用于通用图片理解
导出命令契约（flags/risk 等）	rabetbase schema	与 --help 同源；无需登录；大结果用 --format compress
更新 CLI 版本	rabetbase update	自动检测最新版本，CLI 与 Built-in Skill 一体升级
初始化/切换当前工作目录应用	rabetbase workspace	写当前目录 .rabetbase.json；不从全局复制 cookie/accessKey
修改配置文件	rabetbase config set <key> <value>	默认写项目；无项目配置且未 --global 会拒绝；--global 写 ~/.rabetbase.json
列出配置	rabetbase config list	查看当前生效的配置
管理运行态 app-config	rabetbase app-config list/get/set/delete	运行态 app-config 管理面；默认不输出明文 value；set 为 write，delete 保持 high-risk-write
管理和检索当前研发应用的企业知识库	rabetbase kb list/detail/search/create/update/delete	管理仅 company scope；search 仅 COMPANY/PUBLIC；create/update 为 write，delete 保持 high-risk-write
查询或管理应用级通知配置	rabetbase notification config-list / rabetbase notification config-create / rabetbase notification config-update / rabetbase notification config-delete	list 获取 Backend Function 所需 configCode；写入只接收单一敏感 JSON 源，先 dry-run；update/delete 必须 --yes
查看线上菜单事实 / 菜单异常审计	rabetbase menu list	返回 DFS 事实、children/page、URL、最近更新人/时间和 snapshotHash；异常治理先读 menu-anomaly-manual-cleanup
批量显示或隐藏菜单	rabetbase menu visibility-update	用精确 ID/path 选择目标；先 dry-run，使用 --expect-visible / --expected-count 防漂移，正式执行必须 --yes
创建外部网站链接菜单	rabetbase menu external-link-create	write；显式选择 embedded 或 new-window，仅接受 HTTPS；建议先 dry-run，正式执行不要求 --yes
原地更新既有外链 URL	rabetbase menu external-link-update	write；精确单 ID、URL-only；必须带旧 URL 与父级断言，先 dry-run，再复用参数正式执行
修改任意类型菜单名称	rabetbase menu rename	精确单 ID、label-only；使用 --expect-label 防漂移，先 dry-run 并检查 before/after
同步本地微前端路由到平台	rabetbase menu sync	扫描 src/pages 创建缺失的 procode 菜单；不上传构建产物；正式执行前先 --dry-run
修改微前端菜单资源 URL	rabetbase menu asset-update	write；用 ID/path 精确选目标或显式 --all，默认 patch 且保留加载模式，先 dry-run 再复用参数正式执行
查看/管理开发角色	rabetbase role list/detail/update/delete	角色类型为 ADMIN/DEV/OWNER/CUSTOM；仅 CUSTOM 可改/删；当前不提供 create；输出 scope: dev
解析昵称/用户名到 userId	rabetbase role user-resolve	基于租户成员目录；重名时列出候选 ID，再把选中的 ID 传给 role user-add/user-remove --user <id>
查询租户人员列表	rabetbase tenant members-list --tenant-code <code>	先校验当前账号所属租户，再返回全量人员；不分页、不输出邮箱/手机号/头像
查询应用人员及角色列表	rabetbase app members-list --appcode <code>	按 userId 去重并聚合 roles[]；同时保留 ACTIVE/PENDING 角色归属
把开发协作者加入/移出角色	rabetbase role user-add / user-remove	只改目标开发角色；OWNER 直接拒绝；high-risk-write，先 --dry-run
按 ID 删除菜单或目录树	rabetbase menu delete	精确删除空 folder/非 folder 叶子；非空 folder 显式 --recursive，计划按叶子优先批量提交并回读
创建空菜单分组	rabetbase menu group-create	group 持久化为 type=folder，保留平台生成的非空 path；先 dry-run 并检查创建位置与排序
修改菜单分组排序	rabetbase menu group-update	目标必须为 folder；修改任意菜单类型的名称统一使用 menu rename；先 dry-run 并检查 before/after
移动已有叶子菜单	rabetbase menu move	使用精确源 ID、目标父级 ID 和当前父级断言；逐项 dry-run 并检查写后回读
异步新建根分组	rabetbase menu regroup-start	write；只接收精确非 folder 叶子 ID；返回 taskId，非幂等请求不自动重提
查询通用异步任务	rabetbase task status	按 taskId + appCode 查询 PENDING / PROCESSING / SUCCESS / FAILED；只读，不重启业务操作
查找数据集	rabetbase dataset list --name "xxx"	默认返回支持的 DB_TABLE 和 METADATA 数据集；查指定来源用 --source DB_TABLE / --source METADATA；也可 --code 精确查
查看表结构和字段	rabetbase dataset detail --code xxx	含字段定义和操作列表
废弃数据集	rabetbase dataset delete	high-risk-write；默认非级联，显式 --cascade --confirm 才删除关联页；必须先 --dry-run，批量推荐 --expected-count
恢复已删除数据集	rabetbase dataset restore	high-risk-write；按唯一回收站日志只恢复 Dataset，页面用 page restore 明确恢复；必须先 --dry-run
修改 Dataset 展示名	rabetbase dataset rename	只更新 Dataset 展示名；必须先 --dry-run，用 --expect-name 防漂移；连续重命名先读对应章节
从文本生成新 METADATA 数据集	rabetbase dataset generate-start / generate-status	三步：preview；审阅后提交；随后执行 data.query.command，优先按同一个 taskId 查询。PENDING/PROCESSING 非终态，未知或响应丢失不得自动重提；只在返回 createdDataset.code 后使用 Dataset
安全更新 Dataset 原始字段对象	rabetbase dataset field-update	使用 --code 定位 Dataset，只允许 patch 已知可变业务配置字段；必须先 --dry-run，用 --expect-json 防漂移
Dataset 顶层 extend 更新命令	rabetbase dataset extend-update	当前无可写字段；不得用于 businessGroup。业务场景分组只能使用 rabetbase dataset business-group-update
发现已有业务分组	rabetbase dataset business-groups	read；按 --dbid 汇总 DB_TABLE Dataset，不含 METADATA；空字符串桶表示未分组
更新业务场景分组	rabetbase dataset business-group-update	唯一入口；使用 --code 定位 Dataset；必须先 --dry-run，推荐用 --expect-business-group 防漂移
查看 Dataset 操作定义	rabetbase dataset operations --code xxx	获取 filter/getOne/create 等参数定义
查看数据集关联关系	rabetbase dataset relations	标准只读入口，输出 datasetCode + field 关系事实；支持 DB_TABLE -> DB_TABLE、DB_TABLE -> METADATA、METADATA -> METADATA
审计数据集关联关系	rabetbase dataset relation-audit	只读审计关系事实结构错误、风险和人工复核项
管理单条数据集关联关系	rabetbase dataset relation-create/update/delete	单条关系写入；写入前用 relations 确认 datasetCode + field 关系事实，DB_TABLE 写入所需表名来自显式参数或物理表事实
首次生成数据列表页	rabetbase page generate-start --datasetcode <code>	提交或复用服务端异步任务
创建自定义页面	rabetbase page create --page-pattern BLANK --name "客户看板"	当前只发布 BLANK 模式；创建 JSX/CSS/词包及菜单；先 dry-run
查询自定义页面	rabetbase page custom-list	返回页面 ID、页面名称、pageUrl（查看最新保存内容）和 editPageUrl（打开编辑器）
查看自定义页面详情	rabetbase page custom-detail --id <pageId>	查询页面详情，codeContent 包含可修改后整体提交的完整页面文件
更新自定义页面	rabetbase page custom-update --id <pageId> --page-content <json>	保存完整页面文件并创建新版本；先 dry-run
发布自定义页面	rabetbase page custom-publish --id <pageId>	write；发布当前保存内容，先 dry-run 并审阅预览
查询数据列表页生成任务状态	rabetbase page generate-status --datasetcode <code> --operation-id <id>	查询 job 状态，支持 operationId / clientOperationId
查询数据列表页生成任务状态	rabetbase page generate-status --datasetcode <code> --task-id <id>	查询 job 状态；taskId 首选，operationId/clientOperationId 兼容。成功后仍读取数据列表页事实，未知状态不得自动重提
查询数据列表页事实快照	rabetbase page data-list-status --datasetcode <code>	查询数据列表页四件套、残留页与菜单事实
审计数据列表页关系绑定	rabetbase page relation-audit --datasetcode <code>	只读检查数据列表页 options 绑定是否匹配 dataset relations
同步已有数据列表页	rabetbase page sync --datasetcode <code>	数据集字段变更后同步到关联数据列表页
拉取数据列表页 schema 到本地	rabetbase page pull --id <pageId>	写入 .rabetbase/page/<appCode>/，进入本地编辑工作流
推送本地数据列表页 schema	rabetbase page push --id <pageId>	推送后自动回拉 canonical schema 覆盖本地
恢复已删除页面	rabetbase page restore --id <pageId>	支持 `DATA_LIST
数据库连接（dblink）/ 测连 / 结构分析	rabetbase db list 起	id、trace/plan id 与“终态 + 复跑 diff”完成口径见 database-connection-workflow.md；各子命令见 references/rabetbase-db-*.md
生成 / 更新 API 客户端代码	rabetbase api pull → sdk-client-generation.md	api pull 拉 Dataset 事实并刷新 sdk-config.ts；已有 api.ts/client.ts 按 guide 合并更新
查看生成的 API 模型	rabetbase api list	列出已生成的数据模型
查看现有 SQL	rabetbase sql list --name "xxx"	分页，按名称过滤；默认查当前决议到的单个应用
查看 SQL 详情	rabetbase sql detail --sqlcode xxx	含完整 SQL 内容和参数定义
新建本地同步 SQL	rabetbase sql create --name xxx --db-id 10001 --mode sql	先在远端创建，再落本地文件与 sql.lock.json
查看本地同步状态	rabetbase sql status	检查 added / modified / missing / unchanged / remoteOnly
拉取远端 SQL 到本地	rabetbase sql pull	写入 `.rabetbase/sql//<dbName
推送本地 SQL 到远端	rabetbase sql push --sqlcode xxx	write；以 sql.lock.json 为基准上传同步目录中的本地文件
删除 SQL	rabetbase sql delete --sqlcode xxx --yes	删除远端并将本地文件移入 .rabetbase/sql-trash/
校验 SQL 内容	rabetbase sql validate --file xxx	类型检测、危险语句检查、参数提取
执行 SQL 查询	rabetbase sql exec --sqlcode xxx	支持 --params JSON 参数
查看现有 Backend Function	rabetbase bff list	按类型和名称过滤，支持 --app 限定应用
查看 Backend Function 详情	rabetbase bff detail --id n	含完整脚本内容
创建本地 Backend Function	rabetbase bff create --type ENDPOINT --name xxx	在 .rabetbase/bff/<appCode>/... 下创建脚手架
查看 Backend Function 本地状态	rabetbase bff status	检查 added / modified / unchanged / remoteOnly
拉取远端 Backend Function	rabetbase bff pull	从远端同步到本地
推送本地 Backend Function	rabetbase bff push	write；建议先 dry-run，正式执行不要求 --yes
删除 Backend Function	rabetbase bff delete --yes --target xxx	high-risk-write，删远端并清理本地
生成 SDK 代码	rabetbase codegen sdk --code xxx	按操作生成 TypeScript
生成 SQL 调用代码	rabetbase codegen sql --sqlcode xxx	sdk/bff 两种 target
列出已配置应用	rabetbase app list	默认合并视图；--global / --project 限定单层；items[].named、meta 见 reference
发现平台可访问应用	rabetbase app list --remote	查询当前登录账号在平台上的应用目录，不修改本地配置
查询应用人员及角色归属	rabetbase app members-list --appcode <code>	全量只读；按 userId 去重，角色归属聚合到 roles[]
查询租户人员	rabetbase tenant members-list --tenant-code <code>	全量只读；租户必须属于当前账号
查看 app 服务帮助	rabetbase app	只显示 app 子命令帮助，不等价于 app list
绑定当前目录到应用	rabetbase workspace init --appcode <code>	首次绑定；单应用自动选中且不写 defaultApp；与 config init（全局引导）不同
切换当前工作目录默认应用	rabetbase workspace use --app <name>	持久修改当前目录 defaultApp
登记应用	rabetbase workspace add <name> --appcode <code>	单应用不写 default；增加第二个应用时保留原应用为默认；--global 写全局
移除应用	rabetbase workspace remove <name>	只移除本地 profile，移除后自动切换 default
临时切换应用执行	任何命令加 --app <name> 或 --appcode <code>	不修改配置文件
查看配置文件格式	.rabetbase.json 配置参考	完整字段、优先级、环境变量

命令分组

执行前必做： 从下表定位到命令后，务必先阅读对应命令的 reference 文档，再调用命令。

命令分组	说明
快速开始	init
项目	create / upgrade
工作区	workspace init / workspace use / workspace add / workspace remove
运行脚本	run
身份验证	auth login / auth logout
用户账号	dingding-sandbox-bind
自我更新	update
Schema	schema / schema export
诊断	doctor
平台问题	report
文件	upload / query-url
配置	config set/get/list/delete
运行时应用配置管理	app-config list/get/set/delete
公司知识库	kb list/detail/search/create/update/delete
菜单	list / external-link-create / external-link-update / rename / sync / asset-update / delete / group-create / group-update / move / regroup-start
异步任务	task status
通知配置	notification config-list / notification config-create / notification config-update / notification config-delete
角色	list / detail / update / delete / user-resolve / user-add / user-remove
租户成员	tenant members-list（当前账号所属租户的全量人员目录）
应用命令	list（只读应用事实；平台目录用 list --remote）/ members-list（应用人员及角色归属）。登记/移除应用改用 workspace add / workspace remove
数据集命令	list / detail / delete / restore / generate-start/status / rename / field-update / extend-update / business-group-update / operations / relations / relation-audit / relation-create/update/delete
数据列表页命令	generate-start / generate-status / data-list-status / relation-audit / sync / pull / push
自定义页面命令	create / custom-list / custom-detail / custom-update / custom-publish
数据库连接（db）	list / detail / create / update / delete / test / analyze / tables / diff / diff-refresh-start/status
API 命令	pull / list
SQL 命令	list / detail / create / status / pull / push / delete / validate / save（已弃用） / exec
BFF 命令	list / detail / create / status / pull / push / delete
文件 / OCR 命令	file upload/query-url / ocr recognize
代码生成命令	sdk / sql
CLI 内置技能	install

风险控制

所有声明式命令有 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 可限制允许执行的最高风险等级，默认值为 write（详见 配置参考）。权限不足时，Agent 只能提醒用户手动编辑 .rabetbase.json；禁止 Agent 或自动化脚本自行修改 riskLevel、写入环境变量或以其他方式尝试提权。

输出格式

声明式命令统一走 标准信封：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 与仓库 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。

前端页面规则

• 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
生成 / 更新 api.ts 与 client.ts	api pull 之后、模型过期、脚手架缺失、或用户要求修复 SDK 客户端	sdk-client-generation.md
SQL MyBatis 与动态 SQL	写自定义 SQL、<if>/<foreach>、参数绑定	sql-mybatis.md
前端页面开发约束	React 页、表单、列表、与数据集绑定	frontend-development.md
故障诊断	CLI/登录/数据集/保存失败排障	troubleshooting.md
Backend Function 脚本规范	HOOK/ENDPOINT/COMMON、context.client、消息通知扩展、目录与注释模板	backend-function.md
数据接口访问	先 detail 再编码、外键/枚举、禁止 N+1、批量与关联查询；验证真实行数据时交接 lovrabet data（lovrabet CLI ≥ 2.0）	data-api-guidelines.md
SQL 创建工作流	list/detail → pull/create → edit → validate → status → push/delete → exec 全链路	sql-creation-workflow.md
Backend Function 创建工作流	new → status → dry-run → pull/push	bff-creation-workflow.md
冲突检测与保存	blocked、未保存时的用户沟通、响应结构	conflict-detection.md
质量与最佳实践	审查 SQL/Backend Function、命名、高危边界、描述字段	best-practices.md
数据库连接与分析	接入/改连/测连、traceId 来源、db analyze-* 与 dataset 分工；子命令速查见上文 「数据库连接（db）」	database-connection-workflow.md
菜单异常审计与安全修复	重复 path、根级菜单重名、空 folder 删除计划和平台处理后回查	menu-anomaly-manual-cleanup.md