Raw API 与 Schema：兜底层和自省层

Raw API 与 Schema：兜底层和自省层

第三层不是 raw 子命令，而是 api：

lark-cli api GET /open-apis/calendar/v4/calendars
lark-cli api POST /open-apis/im/v1/messages \
  --params '{"receive_id_type":"chat_id"}' \
  --data '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"Hello\"}"}'

README 把它称为 Raw API Calls，源码里入口是 cmd/api/api.go。

api 做了什么

cmd/api 的职责很清楚：

  • 接收 HTTP method + path；
  • 把完整 URL 或裸路径归一化为 /open-apis/...；
  • 解析 --params、--data、--file；
  • 支持 --page-all、--page-size、--page-limit、--page-delay；
  • 支持 --format json|ndjson|table|csv 和 --jq；
  • 支持 --dry-run 预览请求；
  • 支持 --as 选择身份。

它是逃生口，不是首选。源码的 Long help 明确提醒：如果 typed domain command 覆盖你的任务，优先用 typed command，因为 typed command 有参数校验、风险等级、--yes 门禁和使用指导。

Schema 自省

cmd/schema 和 internal/schema 把 metadata 渲染成 Agent 可读的 envelope。internal/schema/assembler.go 会输出：

区域内容
inputSchema.paramspath/query 参数，附带对应 CLI flag
inputSchema.datarequest body 字段
inputSchema.file文件上传字段，标记 binary
outputSchemaresponse body 字段
_metarequired scopes、access tokens、risk、doc URL、affordance

高风险写入还会在 schema 里出现 yes 字段，对应 --yes 确认门禁。也就是说，Agent 不需要猜“这个命令危险不危险”，schema 本身会告诉它。

常用读法

lark-cli schema
lark-cli schema calendar.events.instance_view
lark-cli schema im.messages.delete

写自动化时，schema 比 README 更接近真实执行面；调底层端点时，api 比 curl 更接近 CLI 的身份、输出、安全和分页机制。

下一篇：Agent Skills 体系。