跳到主要内容

高级技巧与故障排查

这篇给接入、维护和排障同学看。业务人员如果只是通过 Agent 使用，一般不需要通读这一篇。

当前可用的输出格式​

当前 runtime CLI 只支持三种输出格式：

格式适合什么场景
compressAgent、脚本、CI，默认值
json调试、保存原始结构
pretty终端人工查看

常见用法：

lovrabet app list --format json
lovrabet data filter --code <datasetCode> --format pretty
lovrabet schema --format compress

如果你想在结构化输出上继续筛字段，可以用 --jq：

lovrabet app list --format compress --jq '.data.items[] | {name, appcode}'

--jq 现在怎么工作​

当前版本已经内置 jq sidecar。解析顺序是：

  1. JQ_PATH
  2. CLI 内置 jq
  3. 系统 PATH 上的 jq

大多数情况下，你不需要再单独安装 jq。

日志能帮你看什么​

CLI 会记录命令历史：

lovrabet logs show
lovrabet logs clear

排障时很适合先看这几件事：

  • 最近到底执行了什么命令
  • 成功还是失败
  • 大概耗时多少

从 rabetbase 配置导入​

如果你已经有 .rabetbase.json，当前推荐方式是：

lovrabet app import --file .rabetbase.json

如果旧文件还是 legacy 结构，先执行：

rabetbase project upgrade

然后再导入。

最常见的错误​

报错常见原因先做什么
Authentication required没有可用 AccessKey先 lovrabet auth login
Set accessKey in .lovrabet.json or pass LOVRABET_ACCESS_KEY.配置里没有 AK检查 auth status 或环境变量
Set appcode via --appcode or in .lovrabet.json.当前没有解析出应用显式传 --app / --appcode，或验证 defaultApp 是否匹配本次需求
App "<name>" not found选了一个当前账号不可见的应用先 lovrabet app list
Flag --code validation faileddataset code 格式不对重新从 dataset list 结果里复制
Invalid JSON for --paramsJSON 拼错了先把 JSON 单独格式化再传
risk "write" but riskLevel is "read"权限护栏拦截手动调整配置文件中的 riskLevel
High-risk operation requires --yes非交互模式删数据显式加 --yes

最有效的排查顺序​

建议按这个顺序看：

  1. lovrabet auth status
  2. lovrabet doctor
  3. lovrabet app list
  4. lovrabet logs show
  5. 必要时加 --format json
  6. 写入类问题加 --dry-run

这套顺序比上来就翻代码更有效。

当前配置文件该长什么样​

现在 runtime CLI 的核心配置是顶层用户意图配置，不是旧的本地多应用 profile 模型。

常见形态例如：

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

如果你看到很多旧的 apps 块，不代表一定不能读，但那已经不是推荐写法了。

什么时候该怀疑是 skills 而不是 CLI​

如果命令本身能跑通，但 Agent 给出的结果不对，问题不一定在 CLI，也可能在：

  • skill 里把业务对象理解错了
  • skill 里写死了旧的 SQL / BFF 名称
  • skill 里的默认候选应用或业务流程已经过时

这时要反过来检查：

  • 业务 prompt 是否说清楚了
  • skill 里绑定的流程是否仍然有效
  • 这次是否应该先做数据集发现，而不是直接执行 SQL / BFF