跳到主要内容

命令参考

这里列出了所有 lovrabet 支持的命令,每个命令都有详细的使用说明和示例。

Windows 用户建议:为了最佳体验,推荐在 Git Bash 中执行所有命令。CMD/PowerShell 中的基础功能可用,但未经充分测试。

基础命令

lovrabet --help - 查看帮助

在你忘记某个命令用法时,这个命令特别有用:

# 查看所有可用命令
lovrabet --help

# 查看特定命令的帮助
lovrabet create --help
lovrabet api --help

认证相关

lovrabet auth - 登录认证

第一次使用 CLI 时必须执行的命令。

lovrabet auth

执行步骤

  1. 运行命令后按回车键
  2. CLI 会启动本地安全服务器
  3. 自动打开浏览器跳转到登录页
  4. 在浏览器中完成登录
  5. 登录成功后返回终端,按 q 退出

登录信息存放位置~/.lovrabet/cookie

项目管理

lovrabet create - 创建项目

用于创建新的 Lovrabet 项目。

# 交互式创建,CLI 会问你项目名称和其他配置
lovrabet create

# 直接指定项目名称
lovrabet create my-awesome-project

创建过程中会做什么?

  • ✅ 创建项目目录和基础文件结构
  • ✅ 从模板复制初始代码
  • ✅ 自动安装 npm 依赖包
  • ✅ 配置 Prettier 代码格式化
  • ✅ 创建 .lovrabetrc 项目配置文件

小提示:如果你不确定项目名称,就直接运行 lovrabet create,CLI 会引导你一步一步配置。

lovrabet add page - 添加页面

在项目中快速添加新页面。

lovrabet add page

交互式配置

  1. 选择页面模板

    • blank - 空白页面,适合从零开始写
    • hello-world - 包含示例内容的页面,适合学习参考
  2. 输入路由路径

    • 单级路由:aboutcontact
    • 多级路由:user/profileadmin/settingsshop/product/detail

生成的文件位置

  • 路径 aboutsrc/pages/about/
  • 路径 user/profilesrc/pages/user/profile/

路径命名规则

  • 长度:1-100 个字符
  • 不能以 / 开头或结尾
  • 不能包含连续的 //
  • 每个路径段只能包含:字母、数字、-_

开发相关

lovrabet start - 启动开发服务器

在项目根目录运行,启动本地开发服务器。

lovrabet start

会发生什么?

  • 启动 Vite 开发服务器(通常是 http://localhost:5173
  • 支持热更新(Hot Module Replacement)
  • 自动打开浏览器
  • SDK 版本检查 v1.2.0+:自动检测项目中的 @lovrabet/sdk 版本,低于 1.2.0 时显示升级提示

原理: 这个命令实际上就是运行 vite,但 CLI 会自动处理路径和环境变量。

SDK 版本兼容性 (v1.2.0+)

CLI v1.2.0+ 会在启动时检查 SDK 版本。如果检测到 @lovrabet/sdk < 1.2.0,会显示黄色警告提示升级,以确保能使用最新的模型别名等功能。

lovrabet build - 构建生产代码

将你的项目打包成生产环境用的代码。

lovrabet build

输出结果

  • dist/ 目录生成优化后的静态文件
  • JavaScript 和 CSS 文件会被压缩和混淆
  • 图片和其他资源会被优化

何时使用: 需要上线部署或本地测试生产环境时。

lovrabet preview - 预览构建结果

本地预览打包后的项目效果。

# 简单预览
lovrabet preview

# 实时构建和预览
lovrabet preview --watch

使用场景

  • 简单预览: 在构建完成后预览效果
  • 实时预览: 修改代码后自动重新构建并更新预览

区别: preview 展示的是生产环境效果,start 展示的是开发环境效果。

配置管理

lovrabet init - 初始化配置文件 v1.1.12+

为现有项目快速初始化 Lovrabet 配置文件。

# 交互式初始化
lovrabet init

# 直接指定 appcode
lovrabet init --appcode my-app-code

使用场景

当你有一个已存在的前端项目,想要为它添加 Lovrabet 支持时使用。不需要重新创建项目,只需初始化配置即可。

会发生什么?

  1. 在项目根目录创建 .lovrabetrc 配置文件
  2. 配置中包含应用代码(appcode)
  3. 自动继承全局配置(如有)
  4. 记录创建时间和 CLI 版本信息

交互式输入

如果不指定 --appcode 参数,CLI 会引导你输入:

  • 支持实时格式验证(只允许字母、数字、-_
  • 输入错误时会即时提示
  • 自动检测并防止覆盖现有配置文件

可用参数

参数说明示例必需
--appcode应用代码--appcode my-app否(不指定则交互输入)

示例

# 为现有 React 项目添加 Lovrabet 支持
cd existing-react-project
lovrabet init --appcode my-app
lovrabet api pull
lovrabet start

注意事项

  • ⚠️ 如果当前目录已存在 .lovrabetrc 文件,命令会失败并提示
  • ✅ 可以在项目的任何子目录执行,配置文件会创建在项目根目录

lovrabet config - 项目配置管理

管理项目级别和全局级别的配置信息。

# 设置配置项
lovrabet config set <键名> <>

# 查看特定配置项
lovrabet config get <键名>

# 查看所有配置项
lovrabet config list

常用配置项

键名说明示例
app应用代码,用于 API 生成my-app-code
apiUrlAPI 基础地址https://api.example.com

配置层级

  • 项目内执行:配置保存到项目根目录的 .lovrabetrc 文件
  • 项目外执行:配置保存到用户主目录的 ~/.lovrabetrc 文件
  • 优先级:CLI 参数 > 项目配置 > 全局配置 > 默认值

示例

# 设置应用代码
lovrabet config set app my-project

# 查看应用代码
lovrabet config get app

# 查看所有配置
lovrabet config list

菜单管理

lovrabet menu sync - 同步菜单 v1.1.15+

智能同步本地页面与 Lovrabet 平台菜单。

# 在项目目录中执行
lovrabet menu sync

会发生什么?

  1. 自动扫描本地 src/pages 目录下的所有页面
  2. 获取 Lovrabet 平台已有的菜单列表
  3. 在终端以表格形式展示对比结果
  4. 引导你为缺失的菜单配置 JS 和 CSS CDN 链接
  5. 批量创建所有缺失的菜单

对比表格示例:

  地址            本地    Lovrabet平台
home ✓ ✓
user/profile ✓ ✗
shop/products ✓ ✗
  • ✓ 绿色:已存在
  • ✗ 红色:不存在(需要创建)

使用场景:

# 场景 1:开发完成新页面后同步
lovrabet add page
lovrabet menu sync

# 场景 2:批量创建多个页面的菜单
lovrabet menu sync

# 场景 3:定期检查本地与平台一致性
lovrabet menu sync

前置条件:

  • 已登录(lovrabet auth
  • 已配置应用代码(lovrabet config set app <code>)或使用 --appcode 参数
  • src/pages 目录下有页面文件
详细教程

完整的使用指南和最佳实践,请查看 菜单同步文档

API 集成

lovrabet api pull - 生成 API 代码

从后端自动拉取 API 定义并生成前端调用代码。

# 使用项目配置中的 app 代码
lovrabet api pull

# 传入特定的 app 代码(v1.1.7+)
lovrabet api pull --appcode my-app-code

# 指定输出目录(v1.1.7+)
lovrabet api pull --output ./lib/api

# 组合使用参数
lovrabet api pull --appcode my-app-code --output ./lib/api
版本说明

从 v1.1.7 开始:

  • 不再支持位置参数方式(如 lovrabet api pull my-app-code
  • 使用 --appcode 参数指定应用代码
  • 新增 --output 参数自定义输出目录
v1.2.0 配置格式升级

从 v1.2.0 开始,生成的配置使用数组格式,以 datasetCode 为核心标识:

// v1.2.0+ 生成的 api.ts
export const LOVRABET_MODELS_CONFIG = {
appCode: 'my-app',
models: [
{
datasetCode: '8d2dcbae08b54bdd84c00be558ed48df',
tableName: 'users',
alias: 'users', // 可选:模型别名(语法糖)
name: '用户管理', // 可选:UI 显示名称
},
],
} as const;

访问方式

  • 标准方式(推荐):client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter() - 全局唯一,AI 友好
  • 别名方式(语法糖):client.models.users.filter() - 方便人类阅读,功能完全相同

可用参数

参数说明示例版本
--appcode指定应用代码--appcode my-appv1.1.7+
--output指定输出目录--output ./lib/apiv1.1.7+

执行步骤

  1. CLI 问你想用什么名称保存 API 文件(默认 api
  2. 从后端拉取 API 配置和数据结构
  3. 生成 TypeScript 类型定义和客户端代码
  4. 自动格式化代码

生成的文件

  • src/api/<name>.ts - API 接口定义和数据类型
  • src/api/client.ts - 封装好的客户端实例

前置条件

  • 已登录(lovrabet auth
  • 已配置应用代码(lovrabet config set app <code>)或使用 --appcode 参数

lovrabet api doc - 生成 API 文档 v1.1.10+

自动生成 API 使用文档(Markdown 格式),方便团队查阅和共享。

# 生成所有数据集的文档
lovrabet api doc

# 只生成指定数据集的文档(v1.1.12+)
lovrabet api doc --datasetcode dataset_abc123

# 生成多个数据集的文档(v1.1.12+)
lovrabet api doc --datasetcode ds_001,ds_002,ds_003

# 指定输出目录
lovrabet api doc --output ./api-docs

# 组合使用参数
lovrabet api doc --appcode my-app --datasetcode ds_001 --output ./docs

会生成什么?

每个数据集会生成一个独立的 Markdown 文件(默认在 ./docs 目录),包含:

  • 📚 数据集基本信息和字段定义
  • 📊 API 接口说明(查询、创建、更新、删除)
  • 💡 完整的请求和响应示例
  • 🔧 使用注意事项和限制说明

可用参数

参数说明示例版本
--appcode指定应用代码--appcode my-appv1.1.10+
--output指定输出目录--output ./api-docsv1.1.10+
--datasetcode指定数据集代码(多个用逗号分隔)--datasetcode ds_001,ds_002v1.1.12+
--env指定环境(可选)--env <env>v1.1.10+

智能验证 v1.1.12+

使用 --datasetcode 参数时:

  • ✅ 自动检查指定的数据集代码是否存在
  • ⚠️ 显示不存在的数据集代码警告
  • 📊 显示匹配的数据集数量统计

使用场景

# 场景 1:团队协作 - 生成文档并提交到 Git
lovrabet api doc
git add docs/
git commit -m "docs: 更新 API 文档"

# 场景 2:选择性生成 - 只更新特定数据集的文档
lovrabet api doc --datasetcode users,orders

# 场景 3:多应用管理 - 为不同应用生成独立文档
lovrabet api doc --appcode user-app --output ./docs/user-api
lovrabet api doc --appcode admin-app --output ./docs/admin-api

前置条件

  • 已登录(lovrabet auth
  • 已配置应用代码(lovrabet config set app <code>)或使用 --appcode 参数

工具命令

lovrabet logs - 日志管理

查看和管理 CLI 操作日志。

# 查看日志
lovrabet logs

# 清空日志
lovrabet logs --clear

日志包含内容

  • 执行的命令和参数
  • 命令执行时间和耗时
  • 错误信息和堆栈信息
  • CLI 版本和环境信息

日志文件位置:项目根目录的 .lovrabet.log(JSONL 格式)

何时查看日志: 当命令执行失败或遇到问题时,日志能帮你定位问题所在。

AI 集成

lovrabet mcp install - 配置 MCP 服务器 v1.2.5+

配置 Model Context Protocol (MCP) 服务器,让 AI IDE 能够访问 Lovrabet 数据集。

# 交互式选择 IDE
lovrabet mcp install

# 直接配置 Cursor
lovrabet mcp install --cursor

# 直接配置 Claude Code
lovrabet mcp install --claude

# 显示其他 IDE 配置指引
lovrabet mcp install --other

支持的平台:

平台配置方式
Cursor自动写入 .cursor/mcp.json
Claude Code输出命令供手动执行
其他显示配置 JSON 模板

会发生什么?

  1. CLI 读取 .lovrabetrc 配置获取 appcode
  2. 对于 Cursor:创建 .cursor/mcp.json 文件并写入配置
  3. 对于 Claude Code:生成配置命令供你手动执行
  4. 同时复制 IDE 规则文件

前置条件:

  • 已配置 appcode(运行过 lovrabet init
  • 已登录(运行过 lovrabet auth

配置示例 (Cursor):

{
"mcpServers": {
"lovrabet-dataset": {
"command": "npx",
"args": ["-y", "@lovrabet/dataset-mcp-server"],
"env": {
"LOVRABET_APP_CODE": "your-app-code",
"LOVRABET_ENV": "online"
}
}
}
}
详细教程

完整的使用指南和故障排查,请查看 MCP 配置文档

lovrabet skill install - 安装skill v1.2.5+

为 AI IDE 安装 Lovrabet 开发规范和指南,帮助 AI 正确使用 SDK 和 CLI。

# 交互式选择 IDE
lovrabet skill install

# 直接安装指定 IDE
lovrabet skill install --cursor

# 安装多个 IDE
lovrabet skill install --cursor claude

# 安装所有 IDE
lovrabet skill install --all

支持的平台:

平台安装内容
Cursor.cursorrules + .cursor/commands/
Windsurf.windsurf/workflows/
Claude Code.claude/skills/ + agents.md
Codex.codex/skills/
OpenCode.opencode/skills/
Qoder.qoder/rules/ + .qoder/skills/
CodeBuddy.codebuddy/skills/
Trae.trae/skills/
通用.agent/skills/

skill内容包括:

技能说明
Filter 查询构建规范10 种常见错误对照
MCP SQL 创建工作流5 步强制流程
AntD UI 开发规范避免 "AI 味道"
API 集成指南lovrabet api pull 流程
菜单管理指南menu sync/update 流程
Backend Function 脚本编写规范权限过滤、数据脱敏

安装后的文件结构:

your-project/
├── .cursorrules # Cursor 通用规则
├── .cursor/
│ ├── mcp.json # MCP 配置(如果配置了 MCP)
│ └── commands/ # Cursor 命令
├── .lovrabet/
│ ├── skill-manifest.json # skill清单
│ └── skill/
│ └── .shared/
│ └── guides/ # 共享开发指南
│ ├── 01-filter-query/guide.md
│ ├── 02-mcp-sql-workflow/guide.md
│ ├── 03-antd-style/guide.md
│ ├── 05-api-integration/guide.md
│ ├── 06-menu-management/guide.md
│ └── 07-backend-function/guide.md
└── agents.md # Claude Code 规则
详细教程

完整的使用指南和技能内容说明,请查看 skill安装文档


常用组合命令

下面是一些常用的命令组合,适合不同场景使用:

第一次使用 CLI(创建新项目)

lovrabet auth                    # 登录
lovrabet create my-project # 创建项目
cd my-project # 进入项目
lovrabet config set app my-app # 配置应用
lovrabet api pull # 生成 API
lovrabet start # 开始开发

为现有项目添加 Lovrabet 支持 v1.1.12+

lovrabet auth                         # 登录(如果还没登录)
cd existing-project # 进入现有项目
lovrabet init --appcode my-app # 初始化配置
lovrabet api pull # 生成 API 代码
lovrabet api doc # 生成 API 文档
lovrabet menu sync # 同步菜单到平台(v1.1.15+)
lovrabet start # 开始开发

日常开发流程

lovrabet start                  # 启动开发服务
lovrabet add page # 添加新页面
lovrabet menu sync # 同步菜单到平台(v1.1.15+)
lovrabet api pull # 更新 API
lovrabet build # 打包测试
lovrabet preview # 预览效果

API 文档更新流程 v1.1.10+

lovrabet api doc                      # 生成所有文档
# 或者
lovrabet api doc --datasetcode ds_001 # 只更新指定数据集文档
git add docs/
git commit -m "docs: 更新 API 文档"

问题排查

lovrabet logs                   # 查看日志
lovrabet config list # 检查配置
lovrabet --help # 查看帮助

AI 辅助开发配置 v1.2.5+

# 配置 MCP 服务器(让 AI 能访问数据集)
lovrabet mcp install --cursor # 配置 Cursor MCP
lovrabet mcp install --claude # 配置 Claude Code MCP

# 安装skill(让 AI 了解开发规范)
lovrabet skill install --cursor # 安装 Cursor skill
lovrabet skill install --all # 安装所有 IDE skill

# 完整 AI 配置(MCP + skill)
lovrabet mcp install --cursor && lovrabet skill install --cursor

常见问题 FAQ

Q1: lovrabet initlovrabet create 有什么区别?

这是两个使用场景完全不同的命令:

lovrabet create - 创建全新项目

适用场景:从零开始创建一个新的 Lovrabet 项目

lovrabet create my-new-project
cd my-new-project

会做什么:

  • ✅ 创建新的项目目录
  • ✅ 生成完整的项目结构(src、public、配置文件等)
  • ✅ 从模板复制所有初始代码
  • ✅ 自动安装依赖包(npm install)
  • ✅ 创建 .lovrabetrc 配置文件
  • ✅ 配置 Prettier 等工具

lovrabet init - 为现有项目添加配置 v1.1.12+

适用场景:你已经有一个前端项目,想要为它添加 Lovrabet 支持

cd existing-react-project
lovrabet init --appcode my-app

会做什么:

  • ✅ 只创建 .lovrabetrc 配置文件
  • ❌ 不创建项目目录
  • ❌ 不生成项目结构
  • ❌ 不安装依赖包

对比表格

特性createinit
使用时机开始新项目已有项目想接入 Lovrabet
创建项目目录✅ 是❌ 否
生成项目结构✅ 是❌ 否
安装依赖✅ 是❌ 否
创建配置文件✅ 是✅ 是
适用场景空白起步现有 React/Vue 项目

实际例子

# 场景 1:开始新项目 - 使用 create
lovrabet create my-shop-project
cd my-shop-project
lovrabet start

# 场景 2:已有项目 - 使用 init
cd my-existing-react-app
lovrabet init --appcode shop-app
lovrabet api pull
lovrabet start

Q2: 我的登录状态过期了怎么办?

症状:运行 lovrabet api pull 或其他需要登录的命令时,提示"登录鉴权失败"或 401 错误。

解决方法

# 1. 退出登录(可选)
lovrabet logout

# 2. 重新登录
lovrabet auth

# 3. 重新执行之前失败的命令
lovrabet api pull

如何检查登录状态

目前没有直接命令检查登录状态,但你可以尝试运行一个需要登录的命令(如 lovrabet api pull),如果提示需要登录,就说明状态已过期。

登录有效期

登录状态由后端管理,通常会保持较长时间。如果长时间未使用 CLI,可能需要重新登录。

Q3: lovrabet api pulllovrabet api doc 有什么区别?

这两个命令都和 API 相关,但作用完全不同:

lovrabet api pull - 生成 API 调用代码

lovrabet api pull --appcode my-app

作用:

  • 生成前端调用 API 的代码文件(TypeScript)
  • 生成文件位置:src/api/
  • 用途:在你的项目代码中直接导入和使用

输出示例:

// src/api/api.ts
import { lovrabetClient } from '@/api/client';
const users = await lovrabetClient.getUsers();

lovrabet api doc - 生成 API 文档 v1.1.10+

lovrabet api doc

作用:

  • 生成 API 使用文档(Markdown 格式)
  • 生成文件位置:docs/
  • 用途:供团队成员阅读、理解 API,或提交到 Git 仓库

输出示例:

# 用户数据集 API 文档

## 数据字段
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | number | 用户ID |
| name | string | 用户名 |
...

何时使用

  • api pull:开发时,需要调用 API
  • api doc:写文档时,或需要让团队了解 API 细节

Q4: 为什么生成的 API 文件名不是我想要的?

原因:CLI 会在生成时询问你想用什么名称,默认是 api

解决方法

  1. 生成时自定义名称
lovrabet api pull
# CLI 会问:请输入 API 文件名称(默认: api)
# 你可以输入:myapi
# 最终生成:src/api/myapi.ts
  1. 生成后手动重命名
# 生成后直接重命名文件
mv src/api/api.ts src/api/myapi.ts
# 并更新代码中的 import 路径
  1. 使用 --output 自定义目录
lovrabet api pull --output ./src/services
# 这样 API 文件会生成到 src/services/ 目录

Q5: 如何更新已生成的 API 代码?

当后端 API 有变更时,需要重新生成 API 代码。

步骤

# 1. 备份现有文件(可选,建议先提交 Git)
git add .
git commit -m "backup: API 代码更新前备份"

# 2. 重新拉取 API
lovrabet api pull

# 3. CLI 会问是否覆盖,选择 Yes

# 4. 检查变更
git diff src/api/

# 5. 如果有问题,可以回退
git checkout src/api/

注意事项

  • ⚠️ 重新生成会覆盖现有文件,所以先备份或提交 Git
  • ✅ 建议使用 Git 管理代码,方便对比变更
  • 📝 API 变更后,相关调用代码可能也需要修改

Q6: 我只想为部分数据集生成文档,怎么办?

使用 --datasetcode 参数指定要生成文档的数据集 v1.1.12+

# 只生成 users 数据集的文档
lovrabet api doc --datasetcode users

# 生成多个数据集的文档(用逗号分隔)
lovrabet api doc --datasetcode users,orders,products

如何获取数据集代码

  1. 运行 lovrabet api pull,CLI 会显示所有数据集
  2. 或者查看 lovrabet.config.js 配置文件
  3. 或者先运行 lovrabet api doc 生成所有文档,从文件名看出数据集代码

智能验证

如果你指定的数据集代码不存在,CLI 会显示警告:

! 以下数据集代码不存在: invalid_dataset
* 从 50 个数据集中筛选出 2 个匹配的数据集

Q7: Windows 用户遇到命令执行失败怎么办?

推荐方案:使用 Git Bash 执行所有 CLI 命令

为什么

  • CLI 在 Git Bash 中经过充分测试
  • CMD/PowerShell 可能存在兼容性问题
  • Git Bash 提供更好的终端体验

如何安装 Git Bash

  1. 下载并安装 Git for Windows
  2. 安装时选择包含 Git Bash
  3. 安装完成后,右键任意文件夹 → "Git Bash Here"
  4. 在 Git Bash 中执行 CLI 命令

常见问题

如果在 CMD 中遇到问题:

# 问题:命令不识别或路径错误
# 解决:切换到 Git Bash

# 问题:npm install 失败
# 解决:检查 Node.js 版本 >= 20
node --version

Q8: 如何查看 CLI 版本和更新?

查看当前版本

lovrabet --version
# 或
npm list -g @lovrabet/cli

更新到最新版本

# 使用 npm
npm update -g @lovrabet/cli

# 使用 bun(推荐)
bun update -g @lovrabet/cli

# 强制重新安装
npm install -g @lovrabet/cli --force

查看更新日志