抢先体验仅限邀请,SDK 尚未发布。申请邀请
跳到正文
文档

供 agent 和脚本使用

CLI 何时输出 JSON、JSON 的格式、退出码,以及一段让编程 agent 排查错误的提示词。

命令行工具既为人设计,也同样为程序设计。在编程 agent 中、在 CI 中或在管道中运行时,它只输出 JSON:没有颜色,没有加载动画, 也不会提问。这样,编程 agent 就能像你在控制台中一样方便地搜索事件、查看错误,以及跟着某个用户把一个会话从头看到尾。

JSON 还是表格

每次运行只判断一次,顺序如下:

  1. --human 输出表格,即使输出到管道。--json 输出 JSON,即使在终端中。两者不能同时使用。
  2. 否则,当 stdout 不是终端时(lyrelog errors | jq、> file.json),或者设置了下列某个变量时,输出 JSON。
  3. 否则,在终端中输出表格。

agent 常常在伪终端中运行命令,所以只检查是否为终端是不够的。下列变量都会被识别:

变量由谁设置
LYRELOG_AGENT你自己:设为任意值,就能在任何地方强制使用 agent 模式
AI_AGENT跨工具的约定:Claude Code 会设置它,Vercel 的 @vercel/detect-agent 会读取它
AGENTAmp(AGENT=amp)、Goose(AGENT=goose);也可以是 1 或 true。其他值会被忽略:这个名字太常见了
CLAUDECODE、CLAUDE_CODE_ENTRYPOINTClaude Code,在它运行的每个 shell 中
CURSOR_AGENT,或 CURSOR_EXTENSION_HOST_ROLE=agent-execCursor 的 agent(CLI 和编辑器)
CODEX_SANDBOX、CODEX_SANDBOX_NETWORK_DISABLED、CODEX_CI、CODEX_THREAD_IDOpenAI Codex CLI
GEMINI_CLIGemini CLI 的 shell 工具
OPENCODE=1、OPENCODE_CLIENTopencode
AMP_CURRENT_THREAD_IDAmp
AUGMENT_AGENT、ANTIGRAVITY_AGENTAugment、Antigravity
CIGitHub Actions、GitLab CI、CircleCI、Buildkite 以及大多数其他 CI。CI=false 或 CI=0 不算。

有些变量是特意不纳入的。CURSOR_TRACE_ID 和 REPL_ID 会出现在每个 Cursor 终端和 Replit shell 中,包括人使用的终端。 aider 运行命令时不带终端,所以管道检查本来就能识别它。

颜色只出现在终端中的表格里。NO_COLOR(任意值)、TERM=dumb 和 --no-color 可以关闭颜色。agent 或 CI 永远不会被提问, 即使使用了 --human。

JSON 约定

  • stdout 只输出数据。 列表是由服务器原始对象组成的 JSON 数组,字段名与控制台 API 完全一致。单个结果则是一个对象。

  • 在终端中(使用 --json 时)会缩进,其他情况下输出为一行。

  • --follow 每行输出一个 JSON 对象(NDJSON),每个事件一个,直到被停止。

  • 当列表被截断时(因为 --limit 或分页),stderr 会输出一行,说明如何获取其余部分。把 next 作为参数传给同一条命令:

    {"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVh..."}
    {"more":true,"next":"--page 1"}
  • 失败时会向 stderr 输出一行,并以某个退出码退出:

    {"error":"This needs a recent sign-in","hint":"Run lyrelog login again, then retry within 10 minutes.","code":"reauth_required","status":403}

    error 和 hint 是给人看的。code 是稳定的,供程序使用。status 是 HTTP 状态码(服务器有响应时)。 retry_after 以秒为单位(服务器要求等待时)。

  • 无法撤销的操作需要 --yes:吊销密钥、删除某个用户的数据、把某人移出组织、删除已保存的视图。没有人能回答提问, 所以不加 --yes 时,命令会以退出码 2 停止。

lyrelog events --level error --since 7d -n 1
[{"event_id":"adea33e4-26eb-422e-b904-96649c0e7830","ts":1795167007485,"level":"error","category":"sync","message":"cloud_save_failed","user_id":"pl-fe0958c6","install_id":"76f5a7d0-81b0-4c36-8908-eefd6c936abf","session_id":"51e19a18-ca3e-4428-a10b-baeadc7eaaf8","app_id":"com.example.tilefall","app_version":"1.6.3","app_build":"202609301304","os_name":"iOS","os_version":"27.2.0","device_model":"iPhone18,2","locale":"fr_FR","country":"FR","environment":"production","platform":"ios","received_at":1795167047509,"verified_by":"","attrs":{"reason":"schema_mismatch","record":"progress","status":422}}]

stderr 上则输出:

{"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVhMzNlNC0yNmViLTQyMmUtYjkwNC05NjY0OWMwZTc4MzA"}

时间均为 Unix 毫秒时间戳。更多示例:

lyrelog errors | jq -c '.[0] | {name, area, count, players, versions, sample_event}'
lyrelog events values message --level error --since 7d | jq -c '.[0:2]'
lyrelog events -f --level error | jq -r '.message'
lyrelog keys create --type server --name tilefall-api | jq -r .secret
{"name":"cloud_save_failed","area":"sync","count":823,"players":124,"versions":["1.6.3"],"sample_event":"adea33e4-26eb-422e-b904-96649c0e7830"}
[{"value":"cloud_save_failed","count":823,"players":124},{"value":"daily_upload_failed","count":178,"players":124}]

字段名沿用 API 的命名,所以无论项目怎么称呼用户,用户数的字段都是 players。

退出码

退出码是稳定的:脚本和 agent 可以据此分支处理。

退出码code含义
0成功
1error其他失败(服务器、文件)
2usage命令、参数或取值有误;或者需要 --yes
3not_signed_in未登录,或会话已结束:运行 lyrelog login
4reauth_required该操作需要最近 10 分钟内的登录:运行 lyrelog login,然后重试
5forbidden已登录,但没有权限(所有者才能执行的操作)
5browser_only只能在控制台中进行:删除账户或项目、更改登录方式。错误信息会指明对应的页面。访问令牌试图创建或更改令牌时也是这个退出码
6not_found没有这样的项目、事件、密钥或用户(或者不属于你)
7refused服务器拒绝了这个请求(例如 400 或 409)
8rate_limited请求过多,或服务器繁忙:等待 retry_after
9network无法连接服务器
130interruptedCtrl-C

用 Ctrl-C 停止 --follow 属于正常结束,退出码为 0。

登录

agent 无法自己登录。lyrelog login 拒绝在 agent 或 CI 中运行:

{"error":"An agent (claude-code) can't sign in by itself: signing in needs a person","hint":"Ask a person to run `lyrelog login` in a terminal on this computer; the CLI then uses that sign-in. In CI, set LYRELOG_TOKEN to an access token from your account page: https://docs.lyrelog.com/cli/login#scripts-and-ci","code":"not_signed_in"}

由人在那台电脑的终端里运行一次 lyrelog login,之后那里的每个 agent 都会使用这个登录,直到它结束(参见登录)。 agent 以那个人的身份操作,拥有那个人的项目和角色。创建服务器密钥、只读密钥或管理密钥,还要求那个人在最近 10 分钟内登录过。

在 CI 中,或者对于身边没有人的 agent,请使用访问令牌:由人在运行 lyrelog login 之后立即用 lyrelog tokens create 创建一个, 或者在账户页面中创建,并把它设为 LYRELOG_TOKEN(参见脚本和 CI)。

排查错误的提示词

先在应用代码仓库的终端中运行 lyrelog login 和 lyrelog use <project>,然后把下面这段提示词粘贴到该仓库中的 Claude Code、Cursor 或其他编程 agent 中。把 cloud_save_failed 换成你的错误名称。

Investigate the error "cloud_save_failed" in our app with the Lyrelog CLI (lyrelog),
which is installed and signed in. It writes JSON when you run it. Run `lyrelog --help` and
the commands' --help first; don't guess flags. Read only: don't create, change, revoke or
delete anything.

1. `lyrelog errors --since 7d` and find this error: how many times, how many people, which
   versions, when it started, and its sample_event and sample_session.
2. `lyrelog events get <sample_event>`: read its attributes and payload.
3. `lyrelog events --session <sample_session> --oldest-first`: what happened before it in
   that session.
4. Compare: `lyrelog events values version --message cloud_save_failed --since 7d`,
   and the same with device, then `lyrelog insights rate --hits cloud_save_failed
   --of "<the events that attempt it>" --by version`.
5. Look at one or two more people it reached (`lyrelog person <user_id>`), to check the
   pattern holds.
6. Find the code that logs this event in this repository, explain the most likely cause from
   what the events show, and propose a fix. Say what's proven by the events and what's a
   guess.

If a command fails with code reauth_required or not_signed_in, stop and tell me: I'll sign in
again. Don't paste customers' event content anywhere outside this conversation.

agent 也可以读取这些文档的 Markdown 版本:参见与 AI agent 一起使用。