Shortcuts：`+` 命令为什么是第一层

Shortcuts 是 lark-cli 的第一层命令，命名上统一带 +，例如：

lark-cli calendar +agenda
lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
lark-cli docs +create --doc-format markdown --content "# Weekly Report"

它们不是 API 的简单别名，而是“面向任务”的封装。

源码位置

shortcuts/ 按业务域拆分：

目录	典型能力
`shortcuts/calendar`	日程、agenda、free/busy、会议室
`shortcuts/im`	发消息、回复、群、媒体上传下载
`shortcuts/doc` / `drive` / `wiki`	文档、云空间、知识库
`shortcuts/base` / `sheets` / `slides`	多维表格、电子表格、幻灯片
`shortcuts/mail`	邮件浏览、发送、草稿、watch
`shortcuts/apps`	Spark/Miaoda 应用、发布、日志、指标、openapi-key
`shortcuts/event`	事件订阅与消费

业务域里通常有大量测试文件，这很重要：shortcut 是给人和 Agent 直接调用的高层接口，任何参数命名、输出形状或安全门禁变化都会影响真实自动化。

Shortcut 的设计目的

和 generated API command 相比，Shortcut 更像“产品接口”：

维度	Shortcut	API Command
输入	人类可记的参数，如 `--chat-id`、`--text`	接近 OAPI 的字段和 body
输出	默认适合任务继续流转	更接近接口响应
风险控制	常内置 dry-run、提示、确认	来自 metadata 的统一机制
适用	高频任务、Agent 首选	精确覆盖平台 API

所以 root help 才会写“Prefer a +shortcut over the raw API resource when one matches the task.” 这条规则对 Agent 尤其重要：少暴露底层字段，就少一次幻觉填参的机会。

阅读一个 Shortcut 的方法

读某个 shortcut 时按这个顺序看：

找 shortcuts/<domain>/shortcuts.go，看它如何注册到 domain command。
找具体 +xxx 文件，看 flags、validation、dry-run、RunE。
看同名 _test.go，确认输出契约和边界条件。
回到对应 skills/lark-<domain>/SKILL.md，看 Agent 文档是否同步描述。

下一篇：生成式 API Commands。