API Commands：从 metadata 生成命令树

第二层命令是 API Commands。它们不是手写完 200+ 个文件，而是由 cmd/service 从 API metadata 动态注册出来。

生成链路

flowchart LR
  R[internal/registry] --> C[internal/apicatalog]
  C --> S[cmd/service]
  S --> Cobra[Cobra command tree]
  Cobra --> U[lark-cli calendar events instance_view]
  C --> Schema[cmd/schema]

internal/registry 有两个入口：

EmbeddedCatalog()：使用嵌入 metadata，适合 schema、golden tests、lint；
RuntimeCatalog()：使用 embedded + remote overlay，适合运行时命令注册和 scope 发现。

cmd/service.RegisterServiceCommandsFromCatalog 先按 service 建一级命令，再按 resource path 建子命令，最后给 method 加一个可执行 Cobra command。

Method command spec

cmd/service/service.go 里有一个关键结构：methodCommandSpec。它把一个 API method 需要的事实收拢到一起：

字段	用途
`schemaPath`	`calendar.events.instance_view` 这类 schema 查询路径
`servicePath`	HTTP base path
`risk`	read / write / high-risk-write
`identities`	支持 user、bot 还是两者都支持
`params`	path/query 参数，生成 typed flags
`fileFields`	文件上传字段，映射到 `--file`
`acceptsBody` / `declaresBody`	是否允许/声明 request body
`paginates`	是否有 `page_token`，决定分页参数是否有意义

这就是命令能自动拥有 --params、--data、--file、--page-all、--dry-run、--as、--format 等公共能力的原因。

为什么这层适合源码阅读

Shortcuts 告诉你产品设计，API Commands 告诉你平台覆盖方式。读这一层可以看到 lark-cli 的核心取舍：不手写所有 OAPI，但也不把 metadata 生硬暴露给用户；它在生成命令时插入了风险、身份、分页、文件、输出和帮助文案。

下一篇：Raw API 与 Schema 自省。