输出与错误契约

lark-cli 能给 Agent 用，关键在输出。人类可以读彩色文本，Agent 和脚本需要稳定 envelope、字段、退出码和错误类型。

输出格式

README 当前使用的是 --format：

--format json
--format pretty
--format table
--format ndjson
--format csv

同时支持 --jq，让命令自己输出被过滤后的 JSON，而不是要求每个调用方都外接 jq。

internal/output 里能看到对应实现：csv.go、table.go、format.go、jq.go、envelope_success.go、errors.go 等。

Success envelope

WriteSuccessEnvelope 会输出类似：

{
  "ok": true,
  "identity": "user",
  "data": {},
  "_notice": {}
}

_notice 可携带 update、skills drift、deprecated command 等非阻塞提醒。这个设计让“主结果”和“运行时提醒”不会混在一起。

Error contract

errs/ERROR_CONTRACT.md 是错误契约的单一说明。错误输出到 stderr，核心结构是：

{
  "ok": false,
  "identity": "user",
  "error": {
    "type": "authorization",
    "subtype": "missing_scope",
    "message": "missing scope",
    "hint": "run lark-cli auth login --scope ..."
  }
}

稳定字段是 error.type、error.subtype、code、retryable 和特定 subtype 扩展字段；message 和 hint 给人和模型阅读，不适合作为程序分支依据。

错误分类

type	场景	exit
`validation`	参数错误	2
`authentication`	未登录或 token 无效	3
`authorization`	缺 scope 或权限	3
`config`	本地配置缺失	3
`network`	DNS、连接、超时	4
`api`	飞书服务端错误	1
`policy`	内容安全或安全挑战	6
`internal`	CLI 内部错误	5
`confirmation`	高风险动作缺 `--yes`	10

这套契约比“报错时打印一段红字”重得多，也正是 Agent 能可靠恢复的基础：缺 scope 就重新登录，参数错就看 param，高风险缺确认就停下来问用户。

下一篇：风险门禁与内容安全。