高级使用：配置、缓存与集成排障

这篇面向企业 IT、交付实施、二开开发者和 skill 维护者。业务人员通常不需要理解 .lovrabet.json、app cache、AccessKey 作用域和集成细节。

先说结论

Lovrabet CLI 是面向业务场景的 AI 操作套件。对业务人员来说，主路径应该是“提出业务目标，让 Agent 调用能力完成查询、核对、执行与协作”。配置、缓存和应用决议属于技术维护层，只在接入、二开、排障或企业内部统一部署时需要关注。

当前配置模型可以概括为一句话：

本地配置只保存“我想优先怎么用”，远端 + cache 才保存“系统里真实有什么应用”；defaultApp 是第一个验证候选，不是强制上下文。

适合阅读这篇文档的场景

场景	说明
企业 IT 帮业务团队部署 Agent	需要统一安装 CLI、Skill、AccessKey 和默认候选应用
交付实施排查客户现场问题	需要判断 AK、环境、app cache、dataset 权限是否正常
二开或私有化 Lovrabet 体系	需要知道哪些命名、包名、域名和 Skill 源可以配置
skill 维护者固化业务流程	需要理解 `defaultApp`、`--app`、`--appcode` 的优先级
CI / 自动化任务接入	需要控制 `--format compress`、`--jq`、`--dry-run`、`--yes` 等行为

本地配置保存什么

.lovrabet.json 只保存用户意图配置，例如：

accessKey
env
format
riskLevel
defaultApp
兼容单应用模式的顶层 appcode

它不保存整份平台应用目录，也不代表 Lovrabet 平台里的“项目”。

常见配置形态：

{
  "accessKey": "ak_xxx",
  "env": "production",
  "format": "compress",
  "defaultApp": "crm"
}

配置分哪两层

作用域	文件路径	用途
本地配置	`./.lovrabet.json`	当前目录下的可选用户意图配置
全局配置	`~/.lovrabet.json`	这台机器上的通用默认配置

读取时，本地配置会覆盖全局配置。这里的“本地”只是文件作用域，不是平台项目概念。

写配置时要注意：

日常业务命令优先使用显式 --app / --appcode
不要为了完成一次查询主动改 .lovrabet.json
config set / config delete 属于高级配置维护命令
无本地配置且未传 --global 时，CLI 会拒绝执行，避免静默污染全局配置

应用目录和 cache

当前 AK 可见的应用目录由下面两个命令维护：

lovrabet app list
lovrabet app pull

应用目录会缓存在本地，例如：

~/.lovrabet/cache/<env>/<ak-fingerprint>/my-apps.json

职责边界：

.lovrabet.json 保存“我想优先怎么用”
cache 保存“当前账号实际上能看到哪些应用”
远端平台是应用目录的最终事实来源

常用排查命令：

lovrabet app list
lovrabet app list --local
lovrabet app list --no-cache
lovrabet app pull --env daily

应用决议规则

执行 dataset / data / sql / bff 时，应用来源优先级大致是：

显式 --appcode
显式 --app
已确认的当前应用上下文
defaultApp 默认候选
顶层兼容字段 appcode

defaultApp 只是弱候选。用户本次需求里出现订单、商品、库存、CRM、工单等新业务域时，应先在默认候选下按关键词验证数据集；验证不成立再扩大到应用列表，不要因为配置里存在 defaultApp 就直接认定它正确。

推荐排查流程：

lovrabet app list
lovrabet dataset list --app <appName> --name <业务关键词>
lovrabet dataset detail --code <datasetCode>
lovrabet data filter --code <datasetCode> --params '{"currentPage":1,"pageSize":5}'

认证和权限排查

当前 Lovrabet Runtime CLI 走的是 AccessKey 主路径。

lovrabet auth login
lovrabet auth status
lovrabet auth info --format compress

排查顺序建议：

确认 auth info 能返回当前 AK 对应用户
确认 app list 能看到目标应用
用 dataset list --name <关键词> 验证业务对象是否存在
用 dataset detail 看字段和权限边界
写入类命令先加 --dry-run

集成与二开关注点

如果企业独立部署 Lovrabet 体系，或者要把 Lovrabet CLI 改名、换 npm 包、换 Skill 源，应优先检查运行态 CLI 项目里的产品常量配置。

当前二开相关配置集中在：

src/constant/product.ts
src/constant/distribution.ts

常见可变项包括：

配置类型	示例
CLI 展示名和命令名	`lovrabet` / `Lovrabet CLI`
npm 包名	`@lovrabet/lovrabet-cli`
Skill 安装源	`lovrabet/lovrabet-cli`
域名和控制台链接	官网、文档、用户中心、AccessKey 管理
本地配置文件名	`.lovrabet.json`
cache / log 命名	cache 目录、运行日志文件

二开时优先改常量，不要在命令实现里散落替换字符串。

CI 和 Agent 自动化建议

自动化场景建议：

使用环境变量或显式 flags，减少隐式本地配置依赖
默认输出使用 --format compress
需要取字段时叠加 --jq
普通写入先 --dry-run
高危写入必须显式 --yes

示例：

LOVRABET_ACCESS_KEY=ak_xxx \
lovrabet dataset list --app crm --name 客户 --format compress

lovrabet data update \
  --app crm \
  --code <datasetCode> \
  --params '{"id":123,"status":"processing"}' \
  --dry-run

常见误区

误区	正确理解
应用列表写在 `.lovrabet.json`	应用目录来自远端和 cache
`app use` 会写入整份应用详情	`app use` 只写 `defaultApp`
有 `defaultApp` 就必须用它	`defaultApp` 是默认候选，需要按业务语义验证
业务人员需要理解配置细节	配置细节主要给 IT、交付、二开和 skill 维护者
Agent 可以自由猜 app / 字段	应先用真实 `app list`、`dataset list`、`dataset detail` 验证

一句话总结

业务人员不需要读这篇；他们只需要提出业务目标。技术人员读这篇，是为了把 Lovrabet CLI 配成一个稳定、可排查、可二开、可被 Agent 安全调用的运行态执行入口。

先说结论​

适合阅读这篇文档的场景​

本地配置保存什么​

配置分哪两层​

应用目录和 cache​

应用决议规则​

认证和权限排查​

集成与二开关注点​

CI 和 Agent 自动化建议​

常见误区​

一句话总结​