安装与登录
这篇主要给 接入同学、技能维护者、交付工程师 看。业务人员通常不需要自己执行这些步骤。
当前内容按
lovrabet-runtime-cli v2.1.x与@lovrabet/cli-framework v1.0.3校对。最新版本已内置 jq sidecar，--jq一般不需要额外安装系统 jq。
什么时候需要看这篇
下面这些情况建议先看：
- 你要在某台机器上第一次把
lovrabet跑起来 - 你要给 Agent 客户端准备运行环境
- 你要安装或更新 Lovrabet skills
- 你要登录 AccessKey，并确认当前账号可见应用
如果你只是业务侧使用 Agent，可以先跳过，直接看业务场景文档。
推荐方式：通过 AI Agent 自动安装
如果你已经在使用 Claude Code、Codex、Cursor、Trae、Windsurf 等 AI Coding 工具，可以直接把下面的提示词复制给 AI 助手，它会根据指南完成 CLI 安装、Skill 安装和 AccessKey 登录，你只需要在需要粘贴 AccessKey 时配合完成。
提示词（直接复制给 AI 助手）：
帮我安装 Lovrabet CLI：https://www.lovrabet.com/agent-install-guides/lovrabet-cli.md
支持的 AI Agent 工具：Claude Code、Codex、Cursor、Trae、Windsurf、GitHub Copilot
💡 如果你不使用 AI Agent 工具，或者想手动控制每一步，请继续看下面的手动安装步骤。
手动安装：1. 安装 CLI
Node.js >= 20
npm install -g @lovrabet/lovrabet-cli@latest --force
验证安装：
lovrabet --version
2. 安装 Skills
推荐直接使用 CLI 内置命令安装或更新 Lovrabet Skill：
lovrabet skill install
它会调用官方 skills 工具完成全局安装。也可以直接执行等价命令：
npx skills add lovrabet/lovrabet-cli -g -y
Skills 的作用不是给业务人员多一个命令，而是让 Agent 知道：
- 哪类业务问题该走哪套流程
- 哪些 SQL / BFF 可以调
- 哪些操作只能只读，哪些操作允许写入
3. 登录 AccessKey
Lovrabet Runtime CLI 现在使用 AccessKey 作为认证方式。
# 交互式登录
lovrabet auth login
# 非交互式登录
lovrabet auth login --access-key ak_xxxxxxxxxxxxxxxx
登录后建议马上确认：
lovrabet auth status
lovrabet auth info --format compress
AccessKey 获取入口：
工作台 → 头像 → AccessKey 管理
如果怀疑泄露，直接在后台重新生成。
4. 确认应用与默认候选
登录后，下一步通常是确认当前账号能看到哪些应用。Lovrabet Runtime CLI 不要求先创建“项目”或初始化本地工程；多数命令可以直接通过 --app / --appcode 指定目标应用。
# 查看当前账号可见应用
lovrabet app list
# 只读本地 cache
lovrabet app list --local
# 强制打远端并刷新 cache
lovrabet app list --no-cache
# 可选：设置默认候选应用
lovrabet app use crm
这里要注意两件事：
app list/app pull维护的是本地 cache.lovrabet.json只是可选的本地用户意图配置，比如defaultApp、appcode、env、accessKey
当前版本不会再把整份应用目录写进 .lovrabet.json。
5. Agent 选应用时的优先级
对接入同学来说，理解这一点很重要。
Agent 或脚本真正执行时，应用来源大致按下面顺序决策：
- 显式传入的
--appcode - 显式传入的
--app - 已确认的当前应用上下文
- 配置里的
defaultApp默认候选 - 顶层兼容字段
appcode
注意：defaultApp 只是默认候选，不是强上下文。用户需求明显指向订单、商品、库存、CRM 等业务域且未指定 app 时，先在默认候选下按关键词验证数据集；验证不成立再扩大到应用列表。
常见用法：
# 直接指定 appcode
lovrabet data filter --appcode app-xxxxxxxx --code <datasetCode> --params '{"pageSize":10}'
# 临时指定应用名
lovrabet dataset list --app crm --name 客户
# 设置默认候选应用
lovrabet app use crm
lovrabet dataset list --name 客户
6. 建议做一次就绪检查
安装和登录完成后，建议跑一遍下面这组命令：
lovrabet auth status
lovrabet auth info --format compress
lovrabet doctor
lovrabet app list
如果你已经知道一个数据集关键词，还可以再试一次：
lovrabet dataset list --name 客户
这一步的意义不是“业务人员马上开始敲命令”，而是确认：
- CLI 已正确安装
- AccessKey 可用
- 当前环境、默认候选应用和应用目录可用
- Agent 后续能稳定调用
7. 常用全局参数
| 参数 | 说明 |
|---|---|
--appcode | 直接指定 appcode |
--app | 临时指定应用名 |
--env | 指定环境：production / development / daily |
--format | 输出格式：json / pretty / compress，默认 compress |
--jq | 用 jq 过滤 JSON 输出 |
--dry-run | 预览操作，不真正执行 |
--yes | 跳过高危确认 |
--non-interactive | 强制非交互模式 |
--global | 使用或写入全局配置；日常业务命令通常不需要 |
8. 配置文件现在长什么样
常见情况通常只有两种：
单应用直连
{
"accessKey": "ak_xxx",
"env": "production",
"appcode": "app-xxxxxxxx"
}
使用默认候选应用名
{
"accessKey": "ak_xxx",
"env": "production",
"defaultApp": "crm"
}
当前版本的设计重点是：
- 顶层配置保持简单
- 应用目录来自远端 + cache
- 本地只保存“我想优先尝试哪个应用、用哪个环境、用哪把 AK”
9. 给业务侧的一句建议
如果你是在给业务团队接入 Agent，真正需要他们知道的通常只有两件事：
- 问题要用业务语言说清楚
- 写入类需求要明确说“先预览”
至于命令、appcode、dataset code、sqlcode、function name，应该尽量由 Agent 和 skills 在后台处理。