开放平台有 500 个 API，是不是应该生成 500 个 CLI 命令？
如果答案是“是”，模型会被大量相似命令包围。如果答案是“只做一个万能 invoke”，路径、参数、权限和错误又会全部回到模型手里。
这两个极端，本质上都没有完成产品设计：前者复制 API 数量，后者复制 API 复杂性。
一个好的 Agent CLI，不是开放 API 换层命令壳。它要把底层能力压缩成模型会选择、会填参、会纠错、知道何时停止的执行契约。
命令粒度不按 API 数量算
更合理的原则是：一个稳定业务意图，对应一个可独立治理的执行边界。
基础结构可以使用 <domain> <resource> <verb>。例如“表格—单元格—读取”和“群聊—消息—发送”，资源、动作和风险都不同，应该分开。
是否拆分，重点检查五件事：
- 权限是否不同；
- 读写风险是否不同；
- 失败和重试策略是否不同；
- 是否需要独立保证幂等；
- 输出能否单独验证。
是否合并，则看几个步骤是否总是一起发生，中间结果是否对用户没有价值，拆开后是否只会让模型机械编排。
如果一个命令有十几个互相影响的开关，多种完全不同的执行模式，或者一次失败后无法说明哪些步骤已完成，通常意味着粒度已经失控。
飞书为什么做三层命令体系
飞书 CLI 将能力分成业务 Shortcut、类型化 API 命令和 Raw API。
- Shortcut 面向高频稳定任务，提供更短参数和业务默认值；
- 类型化命令对应明确的开放平台资源和方法；
- Raw API 保留长尾能力的逃生口。
这套设计把易用性与覆盖率分开处理。高频任务不必每次从底层接口重新拼装，长尾需求也不必等待团队逐个封装。
新增 Shortcut 仍应设置产品门槛：它覆盖多少真实任务？减少多少稳定重复的编排？能否定义独立权限、失败和验收结果？答不上来，新增命令可能只是在扩大目录。
Agent CLI 需要四份机器契约
1. 命令契约：该选谁
命令描述不能只罗列功能，还要说明 WHEN 和 NOT。
飞书里的文档、云盘、Wiki、电子表格、多维表格和会议纪要互相相邻。如果不声明边界，模型在组装参数前就会选错工具。
2. Schema 契约：怎样填
复杂 JSON 不能只给一个成功示例。示例无法完整表达必填字段、枚举、互斥关系、条件依赖和深层对象。
飞书 CLI 提供 schema，部分复杂 Shortcut 可以使用 --print-schema 按需读取具体字段结构。模型需要哪一层就加载哪一层，不必把超长说明一次塞进上下文。
3. 错误契约：下一步怎么办
“权限不足”对 Agent 不够。它还要知道缺哪个 scope、是否可以重试、是否需要换身份，以及已经成功的操作会不会重复执行。
结构化错误至少应包含稳定 code、可执行 hint、retriable、非零退出码、trace id 和部分成功范围。
飞书表格批量更新会明确声明：执行按顺序进行，失败前成功的操作不会回滚。修复后只能从失败位置继续，不能整批重放。
这类部分成功语义直接决定 Agent 是恢复任务，还是制造重复写入。
4. 安全契约：什么时候停
飞书 CLI 将命令标为 read、write、high-risk-write。高风险写入先 --dry-run，获得明确同意后再追加 --yes。Lark CLI 工程规范
重点不是参数名称，而是把安全要求做成执行层硬门禁。确认规则如果只写在 Prompt 里，模型漏读或错误重试都可能绕过它。
有帮助和 Schema，为什么还需要 Skill
CLI 负责“能做什么、参数怎么填、结果是什么”。Skill 负责“什么时候用、什么时候不要用、先查什么、遇到什么情况要停”。
用户说“读取这个飞书链接”，可能对应文档、云盘、Wiki、表格、多维表格或会议纪要。这一步还不是参数问题，而是资源类型和业务意图路由。
合理结构是一条渐进披露链：
- Skill 描述用 WHAT / WHEN / NOT 完成领域路由；
SKILL.md放每次都需要的边界和安全规则；- references 按具体任务加载操作细节；
- CLI 帮助和 Schema 提供最终参数结构；
- 执行后根据结构化结果决定下一步。
Skill 不是重复帮助文档，而是在能力变多后治理模型的注意力。
产品评审时检查四件事
- 命令对应稳定业务意图，还是简单复制 API？
- 权限、风险、失败和幂等边界是否清楚？
- 模型能否按需获得精确 Schema，而不是靠示例猜？
- Skill、reference 和 CLI 是否各自承担清晰职责？
CLI 的质量不看命令数量，而看模型能否用最少上下文和最少试错，正确完成任务。