rabetbase（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 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 配置参考
4. 多应用场景：一个项目有多个应用时，先 rabetbase app add <name> --appcode … 配置各应用，再用 --app <name> 或 rabetbase app use <name> 切换
5. 平台发现：当你不知道当前登录账号能访问哪些应用时，先 rabetbase app remote；它查询平台目录，不修改本地配置
6. 本地配置视图：当你要确认当前项目或全局已经登记了哪些应用、默认应用是谁时，用 rabetbase app list。rabetbase app 本身只显示帮助，不等价于 app list
7. 本地 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 工作。sql save 已废弃，不再作为推荐路径。 - BFF：.rabetbase/bff/<appCode>/...（由 bff create 创建或 bff pull 同步；与 bff status / bff push 扫描范围一致）。详见 guides/sql-creation-workflow.md、guides/bff-creation-workflow.md。

1. 可选：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 中「可选：lovrabet CLI 查数」。

Skill Freshness

• 本地 repo 与 CLI 契约优先 — 若已安装的全局 skill 描述与当前仓库 skills/rabetbase/、rabetbase --help、rabetbase schema 不一致，以当前仓库内容和 CLI 实际输出为准。
• 发现 skill 过期时应主动刷新 — 若不一致已经影响当前任务判断，且用户没有禁止网络/环境变更，应主动执行 rabetbase skill install；等价的显式非交互命令是 npx skills add lovrabet/rabetbase -g -y。
• 刷新后必须重新读取 — 刷新完成后，重新打开当前 SKILL.md 与所需 reference，再继续执行任务，避免沿用旧记忆。
• 刷新失败也不能回退到旧结论 — 若安装失败，明确告诉用户“本地全局 skill 可能过期”，并继续以仓库内 skills/rabetbase/ 和 rabetbase schema 作为 source of truth。

Agent 快速执行顺序

1. 判断需求类型

- Instant API 标准数据记录操作 → SDK filter/getOne/create/update/delete - 简单聚合 → SDK aggregate - 复杂 JOIN / 数据库函数 → 自定义 SQL - 外部系统调用 / 跨表事务 / 复杂业务编排 → BFF

1. 先拿元数据，再写代码

- 至少先查 rabetbase dataset detail --code xxx --format compress（或 json）获取表结构 - 跨表场景还需查目标表的结构 - 需要了解数据模型关系时用 rabetbase dataset links --format compress（或 json） - 管理物理库连接 / 测连 / 同步表结构分析时用 rabetbase db …（先 db list，trace/plan id 见 database-connection-workflow.md） - 输出很大且只需子集时，在 compress/json 上加 --jq '.data…' 缩小结果 - （可选） 若环境已安装 lovrabet ≥ 2.0，可用 lovrabet data filter / data getOne 对数据集做与 SDK 同语义的终端查数；不要假设用户已安装或版本够新，见 guides/data-api-guidelines.md

1. 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 save 已废弃；用户若提到它，直接引导迁移到 sql create / sql push

1. BFF 工作流严格分步

- 查现有 → 确认字段 → 查公共函数 → 本地创建(bff create) → 检查状态(bff status) → 先预览(--dry-run) → 再拉取/推送/删除 - 推送完成只代表研发态脚本已同步；若用户要确认运行态效果，显式交接到运行态验证（如可用的 lovrabet bff exec），不要把运行态 smoke 伪装成 rabetbase 已完成

1. 智能列表页（Smart List Page，page）工作流

- 工作流判断先看 guides/page-development-workflow.md - page 命令职责分离：page generate-start 负责提交或复用任务，page generate-status 负责查询任务状态，page standard-page-status 负责查询智能列表页事实 - 数据集字段变更后同步已有智能列表页：page sync - 本地 schema 开发：page pull → IDE 编辑 → page push - 需要理解 formal schema 组件语义时，再按需阅读 knowledge/page-schema/ 下的 PageSchema 组件资料；不要把它与 rabetbase page 命令 reference 混淆

应用决议指引

1. 已明确 appcode

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

1. 已明确本地应用名

- 当前项目 .rabetbase.json 已有 apps + defaultApp - 或用户给了 --app <name> - 先用 rabetbase app list 验证本地配置，再执行目标命令

1. 只知道业务名称，不知道能访问哪个应用

- 先 rabetbase app remote --format compress - 从平台目录里确认当前登录账号可访问的应用 - 再决定是否需要 rabetbase app add / rabetbase app use，或临时传 --appcode

1. 不要混淆两种视图

- rabetbase app list：本地配置视图，回答“当前项目/全局登记了哪些应用” - rabetbase app remote：平台目录视图，回答“当前登录账号能访问哪些应用”

1. 当两边不一致时

- 平台上有，本地没有：说明还没登记到本地配置，可用 rabetbase app add - 本地有，平台上查不到：说明当前账号可能无权限，或本地配置已过时，应先核对权限与 appcode

数据库连接（db）

与 dataset（数据集模型） 的分工：**db * 管平台登记的 物理库连接（dblink）、测连、schema 分析任务、物理表清单与差异；表字段、枚举、模型关系仍以 dataset detail / dataset links** 为准。

• 入口：先 db list 取 id 与 latestAnalysisTraceId（如有）。
• 只读常用：db detail、db test、db tables、db diff（--table 为表名子串过滤，分页用 --page / --pagesize）。
• 分析任务：db analyze-start / analyze-cancel / analyze-status（plan/trace 来源见下）。
• ER 图引导：db analyze-status 终态成功后，检查并转述 data.links.erPage；若没有 data.links，补 --appcode 或进入已配置 app 的项目上下文后重查。
• 写入：db create / db update / db delete（高危删连需确认）；create/update 支持 --dry-run 预览。db create 成功后返回连接信息与数据库连接页链接。
• 横切流程与 trace/plan：database-connection-workflow.md。单命令细则见 references/rabetbase-db-*.md（与仓库 src/commands/db/ 一一对应）。

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

• 写操作默认当前项目（init、app 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）。

Agent 禁止行为

• 不要猜字段名 — 必须从 dataset detail 返回值获取真实字段名、类型、枚举值
• 不要跳过 validate 与 dry-run — 修改已有 SQL 并准备 sql push 前，必须先跑 sql validate；执行高风险同步前至少确认过 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）
• 不要把废弃命令当主路径 — sql save 仅用于返回迁移提示；bff save 已退出主工作流。除了解释兼容/迁移，不要再基于它们设计步骤
• 不要含糊处理失败 — sql create / sql push / sql delete / bff push / bff delete 返回失败时，必须明确告知用户是哪条资源失败、为什么失败
• 不要在不确认表结构时就写 SQL — 先 dataset detail，后写 SQL
• 不要循环单条查询 — 用 SDK filter + $in 批量查询，不要 N+1
• 不要把 MCP 工具名当 CLI 命令 — 使用 rabetbase sql list，不是 list_sql_queries
• 不要擅自加 --global — 见上文「配置作用域原则」；默认写项目、读合并；仅在用户明确要求或文档说明的场景使用 --global。

接口选型优先级

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

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

SDK 核心规则

初始化

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

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 调用

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

BFF 调用

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

前端 vs BFF 关键差异

意图 → 命令索引

命令分组

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

风险控制

所有声明式命令有 risk level：

sql validate 仍是 SQL 内容校验入口；sql save 已废弃，不再作为推荐写入路径。

配置 riskLevel 可限制允许执行的最高风险等级（详见 配置参考）。

输出格式

声明式命令统一走 标准信封：ok、command、risk、可选 data（失败时可有 error 等，以实际输出为准）。

--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。

常见错误速查

冲突处理

凡是出现 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 提供详细说明、示例与边界情况：