命令参考
这里列出了所有 lovrabet 支持的命令,每个命令都有详细的使用说明和示例。
Windows 用户建议:为了最佳体验,推荐在 Git Bash 中执行所有命令。CMD/PowerShell 中的基础功能可用,但未经充分测试。
基础命令
lovrabet --help - 查看帮助
在你忘记某个命令用法时,这个命令特别有用:
# 查看所有可用命令
lovrabet --help
# 查看特定命令的帮助
lovrabet create --help
lovrabet api --help
认证相关
lovrabet auth - 登录认证
第一次使用 CLI 时必须执行的命令。
lovrabet auth
执行步骤:
- 运行命令后按回车键
- CLI 会启动本地安全服务器
- 自动打开浏览器跳转到登录页
- 在浏览器中完成登录
- 登录成功后返回终端,按
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
交互式配置:
-
选择页面模板:
blank- 空白页面,适合从零开始写hello-world- 包含示例内容的页面,适合学习参考
-
输入路由路径:
- 单级路由:
about、contact - 多级路由:
user/profile、admin/settings、shop/product/detail
- 单级路由:
生成的文件位置:
- 路径
about→src/pages/about/ - 路径
user/profile→src/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 会自动处理路径和环境变量。
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 支持时使用。不需要重新创建项目,只需初始化配置即可。
会发生什么?
- 在项目根目录创建
.lovrabetrc配置文件 - 配置中包含应用代码(appcode)
- 自动继承全局配置(如有)
- 记录创建时间和 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 |
apiUrl | API 基础地址 | 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
会发生什么?
- 自动扫描本地
src/pages目录下的所有页面 - 获取 Lovrabet 平台已有的菜单列表
- 在终端以表格形式展示对比结果
- 引导你为缺失的菜单配置 JS 和 CSS CDN 链接
- 批量创建所有缺失的菜单
对比表格示例:
地址 本地 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 开始,生成的配置使用数组格式,以 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-app | v1.1.7+ |
--output | 指定输出目录 | --output ./lib/api | v1.1.7+ |
执行步骤:
- CLI 问你想用什么名称保存 API 文件(默认
api) - 从后端拉取 API 配置和数据结构
- 生成 TypeScript 类型定义和客户端代码
- 自动格式化代码
生成的文件:
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-app | v1.1.10+ |
--output | 指定输出目录 | --output ./api-docs | v1.1.10+ |
--datasetcode | 指定数据集代码(多个用逗号分隔) | --datasetcode ds_001,ds_002 | v1.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 模板 |
会发生什么?
- CLI 读取
.lovrabetrc配置获取 appcode - 对于 Cursor:创建
.cursor/mcp.json文件并写入配置 - 对于 Claude Code:生成配置命令供你手动执行
- 同时复制 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 init 和 lovrabet 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配置文件 - ❌ 不创建项目目录
- ❌ 不生成项目结构
- ❌ 不安装依赖包
对比表格:
| 特性 | create | init |
|---|---|---|
| 使用时机 | 开始新项目 | 已有项目想接入 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 pull 和 lovrabet 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:开发时,需要调用 APIapi doc:写文档时,或需要让团队了解 API 细节
Q4: 为什么生成的 API 文件名不是我想要的?
原因:CLI 会在生成时询问你想用什么名称,默认是 api。
解决方法:
- 生成时自定义名称:
lovrabet api pull
# CLI 会问:请输入 API 文件名称(默认: api)
# 你可以输入:myapi
# 最终生成:src/api/myapi.ts
- 生成后手动重命名:
# 生成后直接重命名文件
mv src/api/api.ts src/api/myapi.ts
# 并更新代码中的 import 路径
- 使用
--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
如何获取数据集代码:
- 运行
lovrabet api pull,CLI 会显示所有数据集 - 或者查看
lovrabet.config.js配置文件 - 或者先运行
lovrabet api doc生成所有文档,从文件名看出数据集代码
智能验证:
如果你指定的数据集代码不存在,CLI 会显示警告:
! 以下数据集代码不存在: invalid_dataset
* 从 50 个数据集中筛选出 2 个匹配的数据集
Q7: Windows 用户遇到命令执行失败怎么办?
推荐方案:使用 Git Bash 执行所有 CLI 命令
为什么:
- CLI 在 Git Bash 中经过充分测试
- CMD/PowerShell 可能存在兼容性问题
- Git Bash 提供更好的终端体验
如何安装 Git Bash:
- 下载并安装 Git for Windows
- 安装时选择包含 Git Bash
- 安装完成后,右键任意文件夹 → "Git Bash Here"
- 在 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
查看更新日志: