lovrabet

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lovrabet 开发工作流（路由指南）

Lovrabet Development Workflow (Routing Guide)

Lovrabet 中文名为云兔，也常写作 yuntoo。本文档是路由指南，告诉你什么场景用什么工具/文档。

详细 SDK 用法与参数示例优先读取

./guides/*.md

；如需最新公开文档，再使用 Context7 查询，不要把 rules 文件当作完整 SDK 手册。

Lovrabet is known as Yuntoo in Chinese, often written as yuntoo. This document is a Routing Guide that tells you which tool/document to use in which scenario.

For detailed SDK usage and parameter examples, prioritize reading

./guides/*.md

; if you need the latest public documentation, use Context7 for queries instead of treating the rules file as a complete SDK manual.

强制读取规则（不可跳过）

Mandatory Reading Rules (Cannot Be Skipped)

以下情况必须先调用 Read 工具读取对应文件，禁止依赖记忆直接回答或执行：

触发条件	必须读取的文件
创建 / 修改 / 保存 SQL	`./guides/02-mcp-sql-workflow.md`
涉及 SQL 本地落盘、目录规范	`./guides/07-sql-creation-workflow.md`
创建 / 修改 / 保存 BFF 脚本	`./guides/08-bff-creation-workflow.md`
涉及 BFF 本地落盘、目录规范	`./guides/05-backend-function.md`
遇到冲突提示 / blocked / confirmationRequired	`./guides/09-conflict-detection.md`
使用 TypeScript SDK / filter / sql.execute	`./guides/01-typescript-sdk.md`
数据接口设计、多表关联、性能优化	`./guides/06-data-api-guidelines.md`
报错、行为异常、无法确定原因	`./guides/04-troubleshooting.md`

执行顺序：读完对应 guide → 再调用 MCP 工具 → 再回答用户。

In the following cases, you must first use the Read tool to read the corresponding file. It is prohibited to answer or execute directly relying on memory:

Trigger Condition	File to Be Read
Create / Modify / Save SQL	`./guides/02-mcp-sql-workflow.md`
Involves SQL local storage, directory specifications	`./guides/07-sql-creation-workflow.md`
Create / Modify / Save BFF Script	`./guides/08-bff-creation-workflow.md`
Involves BFF local storage, directory specifications	`./guides/05-backend-function.md`
Encounters conflict prompts / blocked / confirmationRequired	`./guides/09-conflict-detection.md`
Use TypeScript SDK / filter / sql.execute	`./guides/01-typescript-sdk.md`
Data interface design, multi-table association, performance optimization	`./guides/06-data-api-guidelines.md`
Error reporting, abnormal behavior, unable to determine the cause	`./guides/04-troubleshooting.md`

Execution Sequence: Read the corresponding guide → Call MCP tool → Answer the user.

本地稿目录（自定义 SQL / BFF）

Local Draft Directory (Custom SQL / BFF)

SQL：在项目 src/custom_sql/
下按业务功能维护
```
.sql
```
文件，保存后再将内容用于 MCP 验证与保存；细则见
```
02-mcp-sql-workflow.md
```
、
```
07-sql-creation-workflow.md
```
。
BFF：在项目 src/backend-function/
下按
```
05-backend-function.md
```
存放（ENDPOINT 在
```
endpoint/
```
，HOOK 在表名子目录）；保存后再同步到平台；细则见
```
05-backend-function.md
```
、
```
08-bff-creation-workflow.md
```
。
上述业务目录建议纳入 Git。

SQL: Maintain
```
.sql
```
files under the project src/custom_sql/
directory by business function. After saving, use the content for MCP verification and storage; see
```
02-mcp-sql-workflow.md
```
and
```
07-sql-creation-workflow.md
```
for details.
BFF: Store under the project src/backend-function/
directory according to
```
05-backend-function.md
```
(ENDPOINT in
```
endpoint/
```
, HOOK in table name subdirectories); synchronize to the platform after saving; see
```
05-backend-function.md
```
and
```
08-bff-creation-workflow.md
```
for details.
It is recommended to include the above business directories in Git.

前置条件检测

Precondition Detection

检测 MCP 是否可用（必需）

Detect if MCP is Available (Required)

检测方式：尝试调用任何 Lovrabet 相关的 MCP 工具
- 查找工具名包含 "lovrabet" 或 "dataset" 的 MCP 工具
- 常见工具：get_auth_status、list_datasets、get_dataset_detail
- ✅ 找到 → MCP 可用，继续
- ❌ 未找到 → 提示用户：lovrabet mcp install

注意：MCP 服务器名字可能是自定义的，不一定叫

lovrabet-dataset

Detection method: Try to call any Lovrabet-related MCP tool
- Look for MCP tools with tool names containing "lovrabet" or "dataset"
- Common tools: get_auth_status, list_datasets, get_dataset_detail
- ✅ Found → MCP is available, continue
- ❌ Not found → Prompt user: lovrabet mcp install

Note: The MCP server name may be customized and not necessarily called

lovrabet-dataset

工具路由规则

Tool Routing Rules

查询和分析 → 用 MCP Tools

Query and Analysis → Use MCP Tools

场景	使用的 MCP Tool
列出所有数据集	`list_datasets`
搜索数据集	`search_datasets`
获取数据集详情	`get_dataset_detail`
执行已保存的 SQL	`execute_custom_sql`
列出 SQL 查询	`list_sql_queries`
列出 BFF 脚本	`list_bff_scripts`
获取 BFF 详情	`get_bff_script_info`
生成 SDK 代码	`generate_sdk_code`
生成 SQL 代码	`generate_sql_code`

规则：直接调用 MCP 工具，不要生成脚本

Scenario	MCP Tool to Use
List all datasets	`list_datasets`
Search datasets	`search_datasets`
Get dataset details	`get_dataset_detail`
Execute saved SQL	`execute_custom_sql`
List SQL queries	`list_sql_queries`
List BFF scripts	`list_bff_scripts`
Get BFF details	`get_bff_script_info`
Generate SDK code	`generate_sdk_code`
Generate SQL code	`generate_sql_code`

Rule: Call MCP tools directly, do not generate scripts

验证和保存 → 用 MCP Tools（含冲突检测）

Verification and Saving → Use MCP Tools (Including Conflict Detection)

场景	使用的 MCP Tool	说明
验证 SQL 语法	`validate_sql_content`	静态语法 + 可选 schema 验证
保存 SQL	`save_or_update_custom_sql`	通过 toolbox，自动冲突检测
保存 BFF	`save_or_update_bff_script`	通过 toolbox，自动冲突检测

冲突处理：保存工具返回

blocked: true

（例如他人为最后提交者）时，告知用户在平台上手动处理，不要自动重试同一保存。

confirmationRequired

nextAction

等字段以工具返回为准；细节见

09-conflict-detection.md

。

BFF 写入类 MCP：若看不到

list_bff_scripts

save_or_update_bff_script

，请在数据集 MCP 的启动参数中加入

--enable-bff-save

，旧名

--dangerously-bff-save

仍可用；详见

08-bff-creation-workflow.md

中的“平台同步与协作速查”。

Scenario	MCP Tool to Use	Description
Validate SQL syntax	`validate_sql_content`	Static syntax + optional schema validation
Save SQL	`save_or_update_custom_sql`	Via toolbox, automatic conflict detection
Save BFF	`save_or_update_bff_script`	Via toolbox, automatic conflict detection

Conflict Handling: When the save tool returns

blocked: true

(e.g., another user is the last submitter), inform the user to handle it manually on the platform. Do not automatically retry the same save. Fields like

confirmationRequired

nextAction

shall be subject to the tool's return; see

09-conflict-detection.md

for details.

BFF Write MCP: If

list_bff_scripts

save_or_update_bff_script

are not visible, add

--enable-bff-save

to the dataset MCP startup parameters; the old name

--dangerously-bff-save

is still available; see "Platform Synchronization and Collaboration Quick Reference" in

08-bff-creation-workflow.md

for details.

快速决策树

Quick Decision Tree

用户请求
    │
    ├─ 查询数据？
    │   └─ 用 MCP: execute_custom_sql / generate_sql_code
    │
    ├─ 创建/修改 SQL？
    │   ├─ 0. 读取 ./guides/02-mcp-sql-workflow.md（必须）
    │   ├─ 1. 用 MCP: get_dataset_detail（了解结构）
    │   ├─ 2. 生成 SQL 代码
    │   ├─ 3. 用 MCP: validate_sql_content（验证）
    │   ├─ 4. 用 MCP: save_or_update_custom_sql（保存，含冲突检测）
    │   └─ 5. 用 MCP: execute_custom_sql（测试）
    │
    ├─ 创建/修改 BFF？
    │   ├─ 0. 读取 ./guides/08-bff-creation-workflow.md（必须）
    │   ├─ 1. 生成 BFF 代码
    │   └─ 2. 用 MCP: save_or_update_bff_script（保存，含冲突检测）
    │
    ├─ 生成 SDK 代码？
    │   └─ 用 MCP: generate_sdk_code
    │
    └─ 不确定？
        └─ 读取 `./guides/04-troubleshooting.md`

User Request
    │
    ├─ Query data?
    │   └─ Use MCP: execute_custom_sql / generate_sql_code
    │
    ├─ Create/modify SQL?
    │   ├─ 0. Read ./guides/02-mcp-sql-workflow.md (Required)
    │   ├─ 1. Use MCP: get_dataset_detail (Understand structure)
    │   ├─ 2. Generate SQL code
    │   ├─ 3. Use MCP: validate_sql_content (Validate)
    │   ├─ 4. Use MCP: save_or_update_custom_sql (Save, including conflict detection)
    │   └─ 5. Use MCP: execute_custom_sql (Test)
    │
    ├─ Create/modify BFF?
    │   ├─ 0. Read ./guides/08-bff-creation-workflow.md (Required)
    │   ├─ 1. Generate BFF code
    │   └─ 2. Use MCP: save_or_update_bff_script (Save, including conflict detection)
    │
    ├─ Generate SDK code?
    │   └─ Use MCP: generate_sdk_code
    │
    └─ Unsure?
        └─ Read `./guides/04-troubleshooting.md`

全部 Guides 索引

Complete Guides Index

推荐通过
npx skills add lovrabet/lovrabet-skill
安装后，guide 与本文档同目录下的
./guides/
。若团队改用 Lovrabet CLI 从公司 CDN 安装，实际路径以 CLI 落盘位置为准（见项目内 README）。

用户需求	参考的 Guide 文档
使用 TypeScript SDK	`./guides/01-typescript-sdk.md`
创建自定义 SQL（MCP 模式）	`./guides/02-mcp-sql-workflow.md`
React 前端开发	`./guides/03-frontend-development.md`
故障排查	`./guides/04-troubleshooting.md`
创建 BFF 脚本	`./guides/05-backend-function.md`
数据接口规范	`./guides/06-data-api-guidelines.md`
SQL 创建工作流	`./guides/07-sql-creation-workflow.md`
BFF 创建、同步与协作	`./guides/08-bff-creation-workflow.md`
冲突检测和处理	`./guides/09-conflict-detection.md`
团队协作最佳实践	`./guides/10-best-practices.md`

It is recommended to install via
npx skills add lovrabet/lovrabet-skill
, after which the guides are in the
./guides/
directory at the same level as this document. If the team switches to using Lovrabet CLI to install from the company CDN, the actual path shall be subject to the CLI storage location (see the project's README).

User Requirement	Reference Guide Document
Use TypeScript SDK	`./guides/01-typescript-sdk.md`
Create custom SQL (MCP mode)	`./guides/02-mcp-sql-workflow.md`
React frontend development	`./guides/03-frontend-development.md`
Troubleshooting	`./guides/04-troubleshooting.md`
Create BFF scripts	`./guides/05-backend-function.md`
Data interface specifications	`./guides/06-data-api-guidelines.md`
SQL creation workflow	`./guides/07-sql-creation-workflow.md`
BFF creation, synchronization and collaboration	`./guides/08-bff-creation-workflow.md`
Conflict detection and handling	`./guides/09-conflict-detection.md`
Team collaboration best practices	`./guides/10-best-practices.md`

配置文件位置

Configuration File Location

Guides 目录：
```
./guides/
```

Guides Directory:
```
./guides/
```