操作类CLI

操作类 CLI

定位:执行业务动作、产生副作用——建文档、发消息、下单、回填、同步。和查询类一样走 API,但因为会改变状态,必须有 dry-run / 确认 / 审计 / 写后验证这一整套护栏。对应风险等级 R1–R3。

📎 案例参考:飞书 CLI create_doc / add_blocks / insert_image · Stripe customers create/delete · 实战 C 报告发布到企微/飞书。规范基线见 设计指南/CLI设计/CLI设计规范。

---

何时用

• ✅ 写入 / 提交 / 发送 / 删除 / 撤销 / 回填 / 同步
• ✅ 把垂直 Skill 的产物「送到用户真实办公场景」(报告 → 企微文档 → 邮件)
• ⚠️ 任何有外部副作用的动作,默认都当写操作对待

命令形态:业务对象 + 业务动词

命令树第一层是业务对象,不是 API URL(飞书 CLI 范式 + 官方 lark-mcp 的 preset 思路):

# 飞书 CLI(业务动作,不是 POST /open-apis/docx/v1/...)
feishu create_doc <title> [folder]
feishu add_blocks <doc_id> <json>
feishu insert_image <doc_id> <path>

# Stripe(resource-action)
stripe customers create --email x@y.com

lark-mcp 用 preset(preset.doc.default / preset.im.default …)按场景只暴露最小必要命令集,而非把全部 OpenAPI 一股脑给模型——操作类尤其要这样收敛动作空间。

业务 SOP:把动作编成流程

操作类的 Skill 价值在于「什么业务步骤、用哪个命令、每步要干成什么」。例:把销售报告发布到飞书——

1 feishu whoami                       确认是「用户身份」,否则建出来别人看不到
2 feishu create_doc "5月销售达成" <folder>   拿 doc_id / doc_url
3 feishu add_blocks <doc_id> 报告正文   局部追加,不整篇覆盖
4 feishu insert_image <doc_id> chart.png 配图,图文并茂

关键设计点:写操作必须可控

护栏	做法
dry-run / plan	先输出「将要做什么 + requires_confirmation」,不实际写
确认	R2/R3 必须等用户 --yes;无 --yes 拒绝执行
写后验证 readback	写完 verify/readback,返回 evidence(order_id、audit_id、readback_ok)
审计 audit	高风险动作留 audit-log,Agent 能追踪自己做了什么
幂等	重复执行不产生脏数据(尤其异步任务)
认证统一	token 类型(tenant/user access token)由 CLI 统一处理,模型只 whoami/doctor

安全分级(R0–R3)

等级	类型	策略
R0	纯读	→ 其实属 设计指南/CLI设计/查询类CLI
R1	低风险写(建草稿/加 block)	明确意图即可
R2	状态变更	默认 dry-run,需确认
R3	财务/删除/撤销/外部发送	必须 dry-run + 人工确认 + audit + readback

与 AUI 的关系

操作类天然要「先问后做」:涉及敏感金额/外发时,明确「需你确认后再同步」——把决策权交还用户。详见 设计指南/AUI设计。

案例:用户问题 → CLI

操作类的转换特征:问话里有”发/建/改/删/同步/下单”等动词,会改变状态——风险越高,护栏越重(R1 直接做 → R3 必须 dry-run + --yes)。

▸ R1 建草稿「把这份报告整理成一篇飞书文档」

feishu create_doc "5月销售达成" <folder>     # 拿 doc_id
feishu add_blocks <doc_id> <报告正文 json>    # 局部追加

建草稿无外发、可撤,R1 明确意图即可直接做。

▸ R2 状态变更「把核对好的房价同步回台账」

ledger update --project 深圳湾一号 --keyword 3-1801 --price 1280 --dry-run
# 预演确认无误后:
ledger update ... --yes        # 写后自动 readback,返回 {readback_ok, audit_id}

改既有数据默认 --dry-run,等用户确认;写完必须 readback 防假完成。

▸ R3 外发「把这条催款通知发到客户群」

feishu send --chat 客户群 --text "<通知内容>" --dry-run   # 先看将要发给谁、发什么
feishu send ... --yes                                    # 无 --yes 一律拒绝执行

外发不可撤,属 R3:必须 dry-run 预演 + 人工确认 + audit。

▸ R3 删除「把刚建错的那个文档删了」

feishu doc delete --doc-id <id> --dry-run    # 列出将删除的对象
feishu doc delete --doc-id <id> --yes        # 留 audit-log

删除/撤销是最高风险;没 --yes 的 R3 命令必须拒绝。

▸ 下单「给 1801 这套下个认购单」

epr-sales trade order-create --fanghao 3-1801 --type 认购 --dry-run
epr-sales trade order-create ... --yes       # 幂等守卫,重复执行不产生脏单

财务类动作走 R3 全套护栏;异步/可重试的尤其要幂等,免得 AI 一着急下两单。

坏味道

• 写操作没有 dry-run,模型一句话就把单下了 / 把文档删了
• 成功不返回 readback evidence → 假完成(说「已发送」其实没发)
• 异步任务无幂等守卫 → 模型说「拉结果」却误触发新建(实战中的真实坑)
• token 刷新逻辑散在每个命令里 → 模型自己处理认证,稳定性差

一句话

操作类 CLI 的设计中心是**「让 AI 安全地改世界」**:能力封进命令、风险分级、写前预演、写后验证。真实失败模式与治理见 评测与改进/失败分析与治理。