SKILL里如何调用CLI

SKILL 里如何描述调用 CLI

两件事:① 正文怎么写调用——指令清单 + 少样本示例 + 易错点三件套;② CLI 怎么分层——L1 场景封装 / L2 原子指令 / L3 API 兜底,让模型优先用高层、少调用、少猜。 一个默认:非必要不放脚本,默认都走 CLI 模式。

📎 实例:飞书 lark-base 的路由表与 Shortcut > 已注册 API > api 裸调 三档命令;本页是设计指南/Skill设计的子页。配套深规范设计指南/CLI设计/CLI设计规范。

一、怎么写调用:指令清单 + 少样本 + 易错点

SKILL 正文不复制 CLI 的完整参数文档(那是 --help 的事),只写让模型选对路、不踩坑的三样:

① 指令清单 = 路由表

用户目标 → 优先命令 → 何时读哪个 reference。飞书 lark-base 的快速路由表是范本:

用户目标	优先命令	何时读 reference
写记录	`+record-upsert` / `+record-batch-create`	必读 `lark-base-record-upsert.md` 和 `lark-base-cell-value.md`
一次性聚合统计	`+data-query`	入口读 `…-data-query-guide.md`,完整 DSL 再读 `…-data-query.md`
公式字段	`+field-create --json '{"type":"formula",…}'`	必读 `formula-field-guide.md`

模型不必读懂每个 flag,只要在表里对号入座:我要干 X,就用命令 Y,(复杂时)先读 reference Z。

② 少样本示例 = fewshot

把「正确长什么样」内置成永久 Few-shot。单条复杂命令给一个能照抄的范例——飞书 data-query-guide 里「按分类计数」的 fewshot:

# 按状态字段计数(照着改字段名即可)
lark-cli base +data-query --base-token <base_token> \
  --dsl '{"dimensions":[{"field_name":"Status","alias":"status"}],
          "measures":[{"field_name":"Status","aggregation":"count","alias":"count"}],
          "shaper":{"format":"flat"}}'

多步流程的 fewshot 重点不是单条命令,而是步骤间数据怎么传。飞书会议周报工作流是范本——每步的输出喂给下一步:

# Step 2 查会议 → 收集 meeting-id
lark-cli vc +search --start 2026-06-01 --end 2026-06-07 --format json --page-size 30
# Step 3 用上一步的 meeting-id 查纪要 → 拿到 note_doc_token
lark-cli vc +notes --meeting-ids "id1,id2,id3"
# Step 4 用 note_doc_token 批量取文档链接(先 schema 再调,见下)
lark-cli drive metas batch_query \
  --data '{"request_docs":[{"doc_type":"docx","doc_token":"<note_doc_token>"}],"with_url":true}'

注意范例里写清了「meeting-id → note_doc_token → 文档链接」的传递链,以及「单次最多 50 个纪要,超了分批」这类隐含约束——这才是多步 fewshot 的价值。

③ 易错点 = 错误恢复表

把「会踩的坑 → 怎么爬出来」做成确定性映射。飞书 lark-base 的错误恢复表:

错误 / 现象	恢复动作
`1254045` 字段名不存在	重新 `+field-list`,用真实字段名或 ID
`1254104`	批量超 200,分批调用
`91403`	无权限,转 `lark-shared` 流程,不要盲目重试换身份

这三件套对应六大缺陷里的「不知用什么工具」(清单)、「缺样例」(fewshot)、「会踩坑」(易错点)。详见设计指南/Skill设计。

二、三层 CLI 设计:让模型优先用高层、少调用

CLI 给模型的接口要分层,默认引导到最高层,层层向下兜底:

层	是什么	飞书真实命令
L1 · 场景封装	一条指令完成一个业务场景,减少调用	`lark-cli base +data-query --dsl '{…}'`(一条顶聚合全流程)`lark-cli base +record-upsert`(有则更新无则插入)
L2 · 原子指令	`resource.method`,可自由组合	`lark-cli base table.fields list` · `table.records create` · `table.records patch` · `tables create`
L3 · API 封装	裸 OpenAPI,低频兜底	`lark-cli api GET /open-apis/vc/v1/rooms --params '{"page_size":"50"}'`

优先级:L1 > L2 > L3(飞书原话:「优先级:Shortcut > 已注册 API > api 裸调」)。

⚠️ 此处 L1/L2/L3 指 CLI 命令的三档,和设计指南/Skill设计里三级加载的 L1/L2/L3(metadata / SKILL.md / references)是两套独立编号,别混。

L1 减少对 L2 的调用——+record-upsert 一条,顶过去「先 search 找记录 → 判断有无 → create 或 update」三四步原子调用。场景越高频,越该封成 L1,把多步编排藏进 CLI,模型只说「做什么」:

# L1:一条搞定「有则更新、无则新增」
lark-cli base +record-upsert --base-token <t> --table-id <tid> --json '{…}'
# 等价的 L2 编排(模型要自己判断分支,多 2-3 次调用、还容易错)
lark-cli base table.records list  --table-id <tid>   # 找有没有
lark-cli base table.records patch --table-id <tid> … # 或 create

L2 留给自由组合:没有现成场景动词时,模型用原子指令自己拼(注意飞书要求完整点分路径 table.records create,不能省成 records create)。

L3 兜底,且 schema 先查:CLI 没注册的低频 API 才用裸调;调用前必须先 schema 查参数,绝不猜字段:

lark-cli schema drive.metas.batch_query      # ① 先查参数结构
lark-cli drive metas batch_query --data '{…}' # ② 再按结构调用

飞书还配了 lark-openapi-explorer,在 CLI 完全没覆盖时从官方文档逐层挖接口、路径、参数和 scope。

这与设计指南/CLI设计的「好 CLI 是业务动作接口,不是 API wrapper」是同一件事:L1 就是业务动作接口,L3 才是 wrapper。设计 CLI 时,把高频场景尽量上提到 L1,模型调得少、错得少。

三、脚本还是 CLI?默认 CLI,SKILL 不放裸脚本

主张:非必要情况下,默认都走 CLI 模式,SKILL 里不放让模型按路径直接执行的脚本。

四条理由:

理由	说明
避免环境/目录/权限问题	裸脚本依赖 Python 版本、工作目录、依赖包、可执行权限——换台机器就崩。CLI 装好在 PATH 里,`mycli foo` 到处能跑
精简调用指令	模型说 `mycli query --entity X` 比「先 cd 到某目录,再 `python scripts/q.py --config ./cfg.yaml …`」短得多(实测脚本模式 ~200 字符 vs CLI 模式 ~100 字符)
提高调用效率	命令面向「指令」不面向「文件」,模型不用先知道脚本在哪、参数怎么排
控制幻觉	路径、参数顺序、配置文件位置都是模型容易瞎编的地方;CLI 把这些收敛成稳定子命令 + `--help`,可猜空间小

那脚本就不用了吗? 用,但作为 CLI 的实现,藏在命令背后,不作为 SKILL 暴露给模型的入口。即:

✅ SKILL 告诉模型:mycli build-report --month 5(背后是不是调 report.py 模型不关心)
❌ SKILL 告诉模型:python scripts/report.py --month 5 --tpl ./assets/t.docx

这正是设计指南/CLI设计的「物理隔离强于文档约定」「脚本是唯一入口(但入口是 CLI 命令,不是裸路径)」。把易错的执行细节钉死在 CLI 里,SKILL 只保留指令。

例外(可以在 SKILL 里直接给脚本的少数情况):纯本地、无外部依赖、一次性的确定性变换,且尚未值得封成 CLI 的早期阶段——但一旦复用,就该上提成命令。

自检清单

正文是不是只写了指令清单 + 少样本 + 易错点,没复制完整 flag 文档?
路由表有没有点名「何时读哪份 reference」?
高频多步场景有没有上提到 L1 场景封装,减少模型的调用与编排?
L3 裸 API 调用前是否强制 schema 先查,不让模型猜字段?
SKILL 暴露给模型的是 CLI 指令,而不是 python scripts/x.py 裸路径?

配套:Skill 怎么切 → 设计指南/Skill设计/Skill切分;reference 怎么切 → 设计指南/Skill设计/reference切分;飞书全景 → 设计指南/Skill设计/飞书Skill设计实践;CLI 深规范 → 设计指南/CLI设计/CLI设计规范。

← 返回设计指南/Skill设计