rabetbase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rabetbase CLI

前置条件： 使用任何 API 命令前，需完成认证和配置（见下方）。 执行前必做： 执行任何命令前，必须先阅读对应命令的 reference 文档，再调用命令。 命名约定： 统一使用
rabetbase <service> <command> [flags]
格式。 输出格式： AI Agent 必须使用
--format json
获取结构化输出。

Prerequisites: Before using any API command, you need to complete authentication and configuration (see below). Mandatory before execution: Before executing any command, you must first read the reference documentation for the corresponding command before invoking it. Naming convention: Uniformly use the
rabetbase <service> <command> [flags]
format. Output format: AI Agent must use
--format json
to get structured output.

前置条件

Prerequisites

认证：
```
rabetbase auth
```
通过浏览器完成 OAuth 登录
AppCode：确保
```
.rabetbase.json
```
中设置了
```
appcode
```
（单应用）或
```
apps
```
（多应用），或通过
```
--appcode <code>
```
/
```
--app <name>
```
传入（旧名
```
.lovrabet.json
```
仍可读）
配置文件：
```
rabetbase project init
```
初始化
```
.rabetbase.json
```
（旧名仍兼容读取）
多应用场景：一个项目有多个应用时，先
```
rabetbase app add
```
配置各应用，再用
```
--app <name>
```
或
```
rabetbase app use <name>
```
切换

Authentication: Complete OAuth login via browser with
```
rabetbase auth
```
AppCode: Ensure
```
appcode
```
(single app) or
```
apps
```
(multiple apps) is set in
```
.rabetbase.json
```
, or pass it via
```
--appcode <code>
```
/
```
--app <name>
```
(the old name
```
.lovrabet.json
```
is still readable)
Configuration file: Initialize
```
.rabetbase.json
```
with
```
rabetbase project init
```
(old name is still compatible for reading)
Multi-app scenario: When a project has multiple apps, first configure each app with
```
rabetbase app add
```
, then switch with
```
--app <name>
```
or
```
rabetbase app use <name>
```

Agent 快速执行顺序

Agent Quick Execution Sequence

判断需求类型
- 标准数据 CRUD → SDK filter/getOne/create/update/delete
- 简单聚合 → SDK aggregate
- 复杂 JOIN / 数据库函数 → 自定义 SQL
- 外部系统调用 / 跨表事务 / 复杂业务编排 → BFF
先拿元数据，再写代码
- 至少先查
```
rabetbase dataset detail --code xxx --format json
```
  获取表结构
- 跨表场景还需查目标表的结构
- 需要了解数据模型关系时用
```
rabetbase dataset links --format json
```
SQL 工作流严格分步
- 查现有 → 确认字段 → 编写 → 校验(
```
sql validate
```
  ) → 保存(
```
sql save
```
  ) → 测试(
```
sql exec
```
  )
BFF 工作流严格分步
- 查现有 → 确认字段 → 查公共函数 → 编写 → 预览(
```
--dry-run
```
  ) → 保存(
```
bff save --yes
```
  )

Determine requirement type
- Standard data CRUD → SDK filter/getOne/create/update/delete
- Simple aggregation → SDK aggregate
- Complex JOIN / database functions → Custom SQL
- External system call / cross-table transaction / complex business orchestration → BFF
Get metadata first, then write code
- At least query
```
rabetbase dataset detail --code xxx --format json
```
  first to get table structure
- For cross-table scenarios, you also need to query the structure of the target table
- Use
```
rabetbase dataset links --format json
```
  when you need to understand data model relationships
SQL workflow strictly in steps
- Check existing → Confirm fields → Write → Validate(
```
sql validate
```
  ) → Save(
```
sql save
```
  ) → Test(
```
sql exec
```
  )
BFF workflow strictly in steps
- Check existing → Confirm fields → Check public functions → Write → Preview(
```
--dry-run
```
  ) → Save(
```
bff save --yes
```
  )

Agent 禁止行为

Agent Prohibited Behaviors

不要猜字段名 — 必须从
```
dataset detail
```
返回值获取真实字段名、类型、枚举值
不要跳过 validate — SQL 保存前必须通过
```
sql validate
```
或
```
sql save --dry-run
```
校验
不要手动拼 API URL — 所有操作通过 CLI 命令完成，不要直接调 HTTP 接口
不要臆测 sqlCode / id — 从
```
sql list
```
或
```
bff list
```
获取真实标识
不要含糊处理保存失败 —
```
sql save
```
/
```
bff save
```
返回
```
blocked
```
时必须明确告知用户
不要在不确认表结构时就写 SQL — 先
```
dataset detail
```
，后写 SQL
不要循环单条查询 — 用 SDK
```
filter + $in
```
批量查询，不要 N+1
不要把 MCP 工具名当 CLI 命令 — 使用
```
rabetbase sql list
```
，不是
```
list_sql_queries
```

Don't guess field names — Must get real field names, types, enumeration values from the return value of
```
dataset detail
```
Don't skip validate — SQL must be validated via
```
sql validate
```
or
```
sql save --dry-run
```
before saving
Don't manually splice API URLs — All operations are done via CLI commands, don't call HTTP interfaces directly
Don't guess sqlCode / id — Get real identifiers from
```
sql list
```
or
```
bff list
```
Don't handle save failures vaguely — Must explicitly inform the user when
```
sql save
```
/
```
bff save
```
returns
```
blocked
```
Don't write SQL without confirming the table structure — Run
```
dataset detail
```
first, then write SQL
Don't loop single queries — Use SDK
```
filter + $in
```
for batch queries, avoid N+1
Don't use MCP tool names as CLI commands — Use
```
rabetbase sql list
```
, not
```
list_sql_queries
```

接口选型优先级

Interface Selection Priority

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

标准 SDK 接口（filter/getOne/create 等）— 能用就不写 SQL
Aggregate 聚合接口 — 简单分组汇总
自定义 SQL — 复杂 JOIN、数据库函数、跨表统计
BFF — 外部系统调用、跨表事务、复杂业务编排

When encountering new requirements, select the implementation method according to priority:

Standard SDK interface (filter/getOne/create, etc.) — Use it if available instead of writing SQL
Aggregate interface — For simple grouping and aggregation
Custom SQL — For complex JOIN, database functions, cross-table statistics
BFF — For external system calls, cross-table transactions, complex business orchestration

SDK 核心规则

SDK Core Rules

初始化

Initialization

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

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 查询（最常用）

Filter Query (most commonly used)

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

typescript

const result = await client.models.users.filter({
  where: { status: { $eq: "active" } },
  select: ["id", "name"],
  orderBy: [{ createTime: "desc" }],
  currentPage: 1,
  pageSize: 20,
});

Parameter name mandatory constraints:

select

(not fields),

orderBy

(not sort),

currentPage

pageSize

(not page/limit)

Where conditions mandatory use operators:

$eq

$ne

$gte

$lte

$gt

$lt

$in

$contain

$startWith

$endWith

SQL 调用

SQL Call

typescript

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

typescript

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

BFF 调用

BFF Call

typescript

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

typescript

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

前端 vs BFF 关键差异

Key Differences between Frontend and BFF

	前端 SDK	BFF (context.client)
SQL 返回值	`{ execSuccess, execResult }`	直接返回数组 `T[]`
单条查询	`getOne(id)`	`getOne(id)`
调 BFF	`client.bff.execute({ scriptName, params })`	—

	Frontend SDK	BFF (context.client)
SQL return value	`{ execSuccess, execResult }`	Directly return array `T[]`
Single query	`getOne(id)`	`getOne(id)`
Call BFF	`client.bff.execute({ scriptName, params })`	—

意图 → 命令索引

Intent → Command Index

意图	推荐命令	备注
查找数据集	`rabetbase dataset list --name "xxx"`	服务端模糊匹配；也可 `--code` 精确查
查看表结构和字段	`rabetbase dataset detail --code xxx`	含字段定义和操作列表
查看 Dataset 操作定义	`rabetbase dataset operations --code xxx`	获取 filter/getOne/create 等参数定义
查看数据模型关系	`rabetbase dataset links`	跨表 JOIN 关系图
查看现有 SQL	`rabetbase sql list --name "xxx"`	分页，按名称过滤
查看 SQL 详情	`rabetbase sql detail --sqlcode xxx`	含完整 SQL 内容和参数定义
校验 SQL 内容	`rabetbase sql validate --file xxx`	类型检测、危险语句检查、参数提取
保存/更新 SQL	`rabetbase sql save --file xxx`	内置校验，不可跳过
执行 SQL 查询	`rabetbase sql exec --sqlcode xxx`	支持 `--params` JSON 参数
查看现有 BFF	`rabetbase bff list`	按类型和名称过滤
查看 BFF 详情	`rabetbase bff detail --id n`	含完整脚本内容
保存/更新 BFF	`rabetbase bff save --file xxx`	high-risk-write，需 `--yes` 确认
生成 SDK 代码	`rabetbase codegen sdk --code xxx`	按操作生成 TypeScript
生成 SQL 调用代码	`rabetbase codegen sql --sqlcode xxx`	sdk/bff 两种 target
列出已配置应用	`rabetbase app list`	多应用模式
切换默认应用	`rabetbase app use <name>`	持久修改 defaultApp
添加应用	`rabetbase app add <name> --appcode <code>`	首个自动设为 default
移除应用	`rabetbase app remove <name>`	移除后自动切换 default
临时切换应用执行	任何命令加 `--app <name>`	不修改配置文件

Intent	Recommended Command	Remarks
Find datasets	`rabetbase dataset list --name "xxx"`	Server-side fuzzy matching; you can also use `--code` for exact query
View table structure and fields	`rabetbase dataset detail --code xxx`	Includes field definitions and operation list
View Dataset operation definitions	`rabetbase dataset operations --code xxx`	Get parameter definitions for filter/getOne/create, etc.
View data model relationships	`rabetbase dataset links`	Cross-table JOIN relationship diagram
View existing SQL	`rabetbase sql list --name "xxx"`	Pagination, filter by name
View SQL details	`rabetbase sql detail --sqlcode xxx`	Includes complete SQL content and parameter definitions
Validate SQL content	`rabetbase sql validate --file xxx`	Type detection, dangerous statement check, parameter extraction
Save/update SQL	`rabetbase sql save --file xxx`	Built-in validation, cannot be skipped
Execute SQL query	`rabetbase sql exec --sqlcode xxx`	Supports `--params` JSON parameters
View existing BFF	`rabetbase bff list`	Filter by type and name
View BFF details	`rabetbase bff detail --id n`	Includes complete script content
Save/update BFF	`rabetbase bff save --file xxx`	high-risk-write, requires `--yes` confirmation
Generate SDK code	`rabetbase codegen sdk --code xxx`	Generate TypeScript by operation
Generate SQL call code	`rabetbase codegen sql --sqlcode xxx`	Two targets: sdk/bff
List configured apps	`rabetbase app list`	Multi-app mode
Switch default app	`rabetbase app use <name>`	Persistently modify defaultApp
Add app	`rabetbase app add <name> --appcode <code>`	The first one is automatically set as default
Remove app	`rabetbase app remove <name>`	Automatically switch default after removal
Temporarily switch app for execution	Add `--app <name>` to any command	Does not modify configuration file

命令分组

Command Groups

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

命令分组	说明
app commands	`list` / `use` / `add` / `remove`
dataset commands	`list` / `detail` / `operations` / `links`
sql commands	`list` / `detail` / `validate` / `save` / `exec`
bff commands	`list` / `detail` / `save`
codegen commands	`sdk` / `sql`

Mandatory before execution: After locating the command from the table below, be sure to read the reference documentation for the corresponding command first before invoking it.

Command Group	Description
app commands	`list` / `use` / `add` / `remove`
dataset commands	`list` / `detail` / `operations` / `links`
sql commands	`list` / `detail` / `validate` / `save` / `exec`
bff commands	`list` / `detail` / `save`
codegen commands	`sdk` / `sql`

风险控制

Risk Control

所有声明式命令有 risk level：

级别	含义	使用方式
`read`	只读查询，随时可执行	直接执行
`write`	修改数据，如 `sql save`	先 `--dry-run` 预览，再正式执行
`high-risk-write`	影响运行时行为，如 `bff save`	必须 `--yes` 确认或交互确认；CI 模式强制 `--yes`

sql save

内置 SQL 校验（与

sql validate

共用核心），DELETE / DDL 语句被自动阻止。

配置

riskLevel

可限制允许执行的最高风险等级（

.rabetbase.json

或

RABETBASE_RISK_LEVEL

；旧名

.lovrabet.json

仍可读）。

All declarative commands have a risk level:

Level	Meaning	Usage
`read`	Read-only query, can be executed at any time	Execute directly
`write`	Modify data, e.g. `sql save`	Preview with `--dry-run` first, then execute formally
`high-risk-write`	Affect runtime behavior, e.g. `bff save`	Must confirm with `--yes` or interactive confirmation; `--yes` is mandatory in CI mode

sql save

has built-in SQL validation (shares core with

sql validate

), DELETE / DDL statements are automatically blocked.

Configuring

riskLevel

can limit the highest risk level allowed for execution (

.rabetbase.json

RABETBASE_RISK_LEVEL

; old name

.lovrabet.json

is still readable).

输出格式

Output Format

格式	用途	示例
`--format json`	AI Agent / 程序解析	`{ "ok": true, "command": "...", "risk": "read", "data": {...} }`
`--format pretty`	人类阅读（默认）	彩色文本输出
`--format table`	列表数据展示	表格输出

Format	Purpose	Example
`--format json`	AI Agent / program parsing	`{ "ok": true, "command": "...", "risk": "read", "data": {...} }`
`--format pretty`	Human reading (default)	Colored text output
`--format table`	List data display	Table output

常见错误速查

Common Error Quick Check

错误类型	含义	解决方案
`auth_required`	未登录	执行 `rabetbase auth`
`config_missing`	未配置 appcode	`rabetbase project init` 或传 `--appcode`
`flag_missing`	缺少必填参数	检查 reference 文档确认必填 flags
`validation_error`	输入校验失败（含 SQL 类型阻止）	检查 SQL 内容或参数格式
`api_error`	后端 API 错误	检查 appcode、网络、权限
`cancelled`	用户取消高风险操作	用 `--yes` 跳过确认，或修改 riskLevel
`blocked` (sql save/bff save)	平台冲突检测	告知用户手动在平台操作，写本地草稿

Error Type	Meaning	Solution
`auth_required`	Not logged in	Execute `rabetbase auth`
`config_missing`	appcode not configured	Run `rabetbase project init` or pass `--appcode`
`flag_missing`	Missing required parameters	Check reference documentation to confirm required flags
`validation_error`	Input validation failed (including SQL type blocking)	Check SQL content or parameter format
`api_error`	Backend API error	Check appcode, network, permissions
`cancelled`	User cancelled high-risk operation	Use `--yes` to skip confirmation, or modify riskLevel
`blocked` (sql save/bff save)	Platform conflict detection	Inform user to operate manually on the platform, write local draft

冲突处理

Conflict Handling

sql save

bff save

blocked: true

时：

告知用户手动在平台操作
将内容写入本地草稿文件（
```
.draft.sql
```
/
```
.draft.js
```
）
禁止重试、禁止绕过
未保存成功时必须明确告知用户，禁止含糊带过

When

sql save

bff save

returns

blocked: true

Inform the user to operate manually on the platform
Write the content to a local draft file (
```
.draft.sql
```
/
```
.draft.js
```
)
Prohibit retrying, prohibit bypassing
Must explicitly inform the user when saving is not successful, prohibit vague handling

前端页面规则

Frontend Page Rules

CLI 生成的页面顶部注释必须保留，追加说明用
```
@modified
```
页面组件设置
```
displayName
```
写页面前必须
```
dataset detail
```
确认字段和关系
禁止 emoji、AI 味文案、感叹号、花哨颜色；文案简洁专业
图标用
```
@ant-design/icons
```
，颜色用 AntD token

The top comment of the page generated by CLI must be retained, use
```
@modified
```
for additional notes
Set
```
displayName
```
for page components
Must run
```
dataset detail
```
to confirm fields and relationships before writing pages
Prohibit emojis, AI-style copy, exclamation marks, fancy colors; copy should be concise and professional
Use
```
@ant-design/icons
```
for icons, use AntD token for colors

深入指南

In-depth Guides

以下 guide 文件提供各主题的详细说明、完整示例和边界情况：

主题	Guide
SDK 完整参数与返回值	`typescript-sdk.md`
SQL MyBatis 语法与动态 SQL	`sql-mybatis.md`
前端页面开发约束	`frontend-development.md`
故障诊断手册	`troubleshooting.md`
BFF 脚本编写规范	`backend-function.md`
数据接口访问规范	`data-api-guidelines.md`
SQL 创建工作流细则	`sql-creation-workflow.md`
BFF 创建工作流细则	`bff-creation-workflow.md`
冲突检测与处理	`conflict-detection.md`
开发质量与最佳实践	`best-practices.md`

The following guide files provide detailed descriptions, complete examples and boundary cases for each topic:

Topic	Guide
SDK full parameters and return values	`typescript-sdk.md`
SQL MyBatis syntax and dynamic SQL	`sql-mybatis.md`
Frontend page development constraints	`frontend-development.md`
Troubleshooting manual	`troubleshooting.md`
BFF script writing specifications	`backend-function.md`
Data interface access specifications	`data-api-guidelines.md`
SQL creation workflow details	`sql-creation-workflow.md`
BFF creation workflow details	`bff-creation-workflow.md`
Conflict detection and handling	`conflict-detection.md`
Development quality and best practices	`best-practices.md`