lark-cli 源码解读：阅读地图

这一组笔记不再按“功能介绍”线性展开，而是按源码的责任边界阅读 larksuite/cli：先看入口，再看三层命令，再看 Agent Skills、身份、输出、安全和工程化质量门禁。

两级分类

一级	二级	读什么
`lark-cli 源码解读`	`01 阅读地图`	README、CHANGELOG、目录结构、安装与仓库导航
`lark-cli 源码解读`	`02 命令系统`	root command、Shortcuts、生成式 API Commands、Raw API 与 schema
`lark-cli 源码解读`	`03 Agent 与身份`	Skills、`lark-shared`、auth、profile、`--as`、strict mode
`lark-cli 源码解读`	`04 输出与安全`	输出 envelope、错误契约、dry-run、`--yes`、内容安全
`lark-cli 源码解读`	`05 工程化`	event、plugin、quality gate、测试与贡献路径

这个分法和源码目录基本对齐：cmd/ 是命令入口，shortcuts/ 是高层任务，cmd/service + internal/registry + internal/apicatalog 是平台 API 命令生成链路，skills/ 是 Agent 手册，errs/ 与 internal/output 是机器可解析契约。

核心结论

lark-cli 的关键不是“把飞书 API 包成命令行”，而是把同一套开放平台能力拆成三种粒度：

Shortcuts：面向人和 Agent 的高频任务，例如 lark-cli calendar +agenda。
API Commands：从 OAPI 元数据生成的类型化命令，例如 lark-cli calendar calendars list。
Raw API：直接按 HTTP method + path 调用任意端点，例如 lark-cli api GET /open-apis/calendar/v4/calendars。

三层之外，源码还做了两件很“Agent-Native”的事：一是把参数、scope、风险等级和输出 schema 暴露给模型；二是把错误、权限缺失、确认门禁、内容安全警告都做成稳定 JSON 契约，而不是只给人看的 stderr 文案。

建议阅读顺序

flowchart TD
  A[README / CHANGELOG] --> B[cmd/build.go]
  B --> C[cmd/root.go]
  C --> D[shortcuts/*]
  C --> E[cmd/service + internal/registry]
  C --> F[cmd/api]
  E --> G[cmd/schema + internal/schema]
  D --> H[skills/lark-*]
  E --> I[internal/output + errs]
  I --> J[security / qualitygate / events]

如果只想快速理解设计，读完前 6 篇就够；如果要贡献代码，后 6 篇更重要。

下一篇：安装与仓库地图。