先看结论lark-cli不是简单把飞书 API 包一层命令而是把复杂 SaaS 平台拆成三种 CLI 能力资源 API把平台 OpenAPI 元数据映射成service resource method用于结构化覆盖。Raw API保留HTTP method OpenAPI path的兜底入口用于覆盖长尾接口。Shortcut把高频、易错、多步骤的用户任务封装成service verb用于提高人和 Agent 的成功率。这三层不是互相替代而是分工Shortcut面向用户意图成功率最高 资源 API面向平台对象结构化覆盖 Raw API面向 HTTP OpenAPI长尾兜底从资源和动作说起做平台 CLI 时第一步不是写命令而是先定义两类东西资源平台中可被操作的业务对象例如日历事件、云盘文件、消息、任务、权限成员、知识库节点。动作资源上可发生的操作例如create、get、list、patch、delete、copy、forward、transfer_owner。飞书的资源 API 大体按这个结构展开service 业务域 resource 业务对象 method 对象动作例子calendar.events.create calendar.events.delete calendar.events.instance_view drive.files.list drive.files.copy drive.permission.members.create im.chats.create im.messages.delete im.reactions.create task.tasks.create task.tasks.patch task.subtasks.create这些动作可以粗略归类读get、list、search、batch_query、instance_view写create、patch、update、delete关系add_members、remove_members、transfer_owner执行send、forward、approve、reject、urgent媒体upload、download、export、import观察status、statistics、view_records、quota注意平台对象不一定都能统一成标准 CRUD。比如im.messages.forward是执行动作drive.permission.members.transfer_owner是关系迁移calendar.events.instance_view是视图查询。资源 API资源 API 是从平台 metadata 自动注册出来的结构化命令。形态lark-cliserviceresourcemethod--params{}--data{}真实例子lark-cli task tasks create--data{...}lark-cli drive files list--params{...}lark-cli calendar events instance_view--params{...}代码上lark-cli会遍历 metadata 中的services - resources - methods并注册成命令命令树注册入口service.go:L32-L48resource/method 注册逻辑service.go:L78-L100资源 API 的价值覆盖平台对象能力。参数、scope、risk 可以通过 schema 查询。比 Raw API 更结构化。比 Shortcut 更接近底层平台能力。但资源 API 不一定覆盖所有业务域。比如docs文档域就没有暴露docs documents create这种资源命令。Raw APIRaw API 基本就是通过 CLI 直接发飞书 HTTP OpenAPI。形态lark-cli api GET /open-apis/calendar/v4/calendars lark-cli api POST /open-apis/im/v1/messages--params{...}--data{...}它看起来像curl但不是裸curl。它仍然经过lark-cli的统一运行时自动处理user/bot身份。自动获取和刷新 token。自动拼接飞书 OpenAPI base URL。支持--params、--data、--file、stdin、file。支持--dry-run。支持统一 JSON 输出。支持统一错误、权限 hint、scope 修复建议。所以 Raw API 的本质是HTTP 的表达自由 CLI 的认证、安全、输出、错误协议为什么不只让 Skill 描述接口Skill 可以告诉 Agent “这个接口做什么、参数怎么填”。但 Skill 不能负责 token、身份、权限、输出 envelope、文件上传、dry-run、错误恢复。这些必须由 CLI runtime 承担。因此 Raw API 仍然值得抽象成 CLI它不是为了重新发明 HTTP而是为了让 HTTP 调用进入统一、安全、可恢复的执行协议。ShortcutShortcut 是用户任务级命令不是 API 级命令。形态lark-cliserviceverb[flags]例子lark-cli docs create --api-version v2--contenttitle报告/titlelark-cli docs fetch --api-version v2--docurl--detailwith-ids lark-cli docs update --api-version v2--docurl--commandappend--contentp补充内容/pShortcut 的判断标准用户经常说的是这个任务而不是底层 API。直接调 API 容易错。需要处理格式、权限、默认值、状态锚点。可能是多步骤编排。输出会被后续步骤继续使用。docs create是典型例子。它不是资源命令层的docs documents create而是一个 Shortcut底层直接调用POST /open-apis/docs_ai/v1/documents相关代码docs create调用 create APIdocs_create_v2.go:L48-L74docs fetch调用 fetch APIdocs_fetch_v2.go:L63-L81docs update调用 update APIdocs_update_v2.go:L124-L170为什么文档域主要做 Shortcut文档创建和编辑不是简单 CRUD。它涉及 XML / Markdown、标题、block id、revision、资源块、bot 创建后的用户权限、长文档分段写入。如果只暴露底层 APIAgent 仍然要猜很多业务规则。所以lark-cli把文档能力产品化成docs create/fetch/update。三层关系用户意图Skill 或人类判断Shortcut 意图命令资源 API 命令Raw API 兜底CLI Runtime认证和身份权限和 scopedry-run 和风险确认飞书 OpenAPIJSON envelope结构化错误和 hint使用顺序可以理解为优先 Shortcut任务更明确成功率最高 没有 Shortcut用资源 API结构化调用平台对象 还不够用 Raw API直接访问长尾 OpenAPIlark-cli 的 SKILL 怎么设计lark-cli的 Skill 不是再造一层 API而是把“怎么正确调用 CLI”写成可执行说明。它大体做三件事先做意图路由先判断这是文档、消息、日历还是云盘问题。优先走 Shortcut有高频任务封装时先用create、fetch、update这类成功率更高的命令。必要时下探Shortcut 不够再落到资源 API最后才用 Raw API 兜底。所以lark-cli的 Skill 设计重点不是描述“某个 HTTP 接口怎么调”而是描述这个任务应该选哪个 domain。先查什么 schema 或参考。优先用哪个 Shortcut。什么情况下切到资源 API 或 Raw API。遇到身份、权限、scope 问题时怎么修复。可以把它理解成Skill 负责任务路由和调用策略CLI runtime 负责真正执行。CLI 的公共运行时三层命令最终都应该经过同一个运行时而不是各自处理认证和输出。lark-cli的公共能力包括config配置应用、品牌、profile。auth登录、登出、状态、scope 检查。--as显式选择user或bot身份。schema查看资源 API 的参数、响应、scope、risk。--dry-run只构造请求不执行副作用。risk / --yes高风险操作确认。--format / --jq人和机器都可消费的输出。--file / file / -统一文件和 stdin 输入。JSON envelope统一成功输出。typed error hint统一失败恢复建议。这就是 CLI 的真正价值不只是多了一种调用方式而是提供一个 Agent 可依赖的执行协议。产品转 CLI 的方法1. 抽资源 API先从平台对象出发形成结构化命令platform-cli domain resource method适合自动生成来自 OpenAPI / RPC / IDL / metadata。保持和平台接口一致。用 schema 保证参数可查询。用统一 runtime 处理身份、权限、输出、错误。2. 抽 Shortcut再从真实任务出发形成意图命令platform-cli domain intent适合人工设计高频任务。多参数易错。多步骤编排。需要默认值和业务兜底。需要返回后续可用的状态锚点。例子workflow debug-smoke doc create-report env deploy-current3. 保留 Raw API最后保留兜底入口platform-cli api method path适合长尾能力新接口还没生成资源命令。没有必要设计 Shortcut。Agent 或开发者知道具体 endpoint。仍然需要 CLI runtime 的认证、安全和输出协议。最值得复制的模式Narrow Waist所有命令经过同一套 runtime。Progressive Disclosure常用走 Shortcut不够用走资源 API再不够用走 Raw API。Agent Contract Firststdout、stderr、exit code、JSON envelope、hint、risk 都是协议。Schema Before Action不熟悉的接口先查 schema再执行。Dry-run First副作用操作先预览请求再执行。Stateful Outputs每次操作返回下一步需要的 ID、URL、revision、log_id、rollback token。一句话总结把一个产品转成 CLI不是把按钮翻译成命令而是把平台能力拆成三层资源 API 保证覆盖率 Raw API 保证长尾不断供 Shortcut 保证真实任务的成功率真正的核心是让三层都进入同一个认证、安全、输出和错误恢复协议。