Rabetbase

Rabetbase CLI

前置条件： 使用任何 API 命令前，需完成认证和配置（见下方）。 资料使用： 先从意图索引定位能力，只读取当前任务直接相关的 reference。写操作、覆盖/恢复、复杂输出解析或命令契约不明确时，执行前读取对应 reference；简单只读操作可依据已确认的 CLI schema 直接完成。 命名约定： 统一使用 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。交互模式选择当前已开放国家/地区；非交互模式显式传 --region，未传时使用默认节点。企业独立部署优先导入 lovrabet-routing/v1 清单，也兼容旧扁平 Domain 文件和对应 --*-domain flags。config init 默认重建当前项目节点/Domain 配置，显式 --global 时写全局；保留 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，显式 --global 时写 ~/.rabetbase.json；默认节点不落冗余 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。
   • Instant API Policy：.rabetbase/instant-api-policy/<appCode>/policy.json。instant-api-policy init/pull/validate/publish 只读取或写入这一固定文件，不接受任意 --file。
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）
   • 研发资源保存后的增量同步由服务端自动处理；仅在管理员明确要求首次初始化、历史回填或故障恢复时读 deployment sync-all，在停止编辑的安静窗口执行；提交成功后按 jobId 查询状态，提交结果未知时用 sync-jobs 恢复任务事实
   • 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；只有用户明确要求放弃本地定制并完整重建时才使用 --force --yes
   • 需要按 Dataset + API 配置 Instant API 的 allow、deny 或 route 时，先读取 rabetbase-instant-api-policy.md，只编辑固定 policy.json，随后依次执行 validate、publish --dry-run，经人工确认后再正式发布
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）

• 写操作默认当前项目（包括 config init、workspace add、config set、project create 等），除非用户显式传 --global。
• 不要在用户未要求时给命令加 --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 与 rabetbase.domain-routing.json。每个官方节点直接声明自己的第三方库 CDN 与 Lovrabet 自有资源 Domain；项目文件始终包含解析后的完整地址，企业独立部署从共用清单读取显式 CDN。两个生成文件都不下发认证配置；rabetbase run start|dev|build|preview 会在执行脚本前刷新公开 Domain 快照，也可用 project domain-routing-sync 立即显式刷新；api pull 只刷新 SDK/API 文件。
• 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。

三入口选型（不要混用）：

入口判断：

• 「看有哪些 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 接口
• 不要把 sync-all 当成日常发布或精确镜像 — 它只用于管理员首次初始化、历史回填或故障恢复，按源端现存记录 UPSERT，不删除目标端额外记录；在停止编辑的安静窗口执行，提交结果不确定时先用 deployment sync-jobs 恢复任务事实，不自动重提
• 不要向产品用户展开研发实现 — 回答角色权限操作时，不输出工程仓库、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。
• 不要为 Instant API Policy 传任意文件路径或写入 app-config — 策略只使用 .rabetbase/instant-api-policy/<appCode>/policy.json 与独立策略接口；发布和回滚前必须校验并预览。

接口选型优先级

遇到新需求时按优先级选择实现方式：

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" },
});

Personal Backend Function 调用

前端或 Node 服务通过 client.personal.bff.execute({ scriptId, params }) 调用 Personal Backend Function。认证方式、兼容性检查、undefined 处理和返回值约定见 typescript-sdk.md。

前端 vs Backend Function 关键差异

意图 → 命令索引

命令分组

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

…(truncated)