CLI设计规范

CLI 设计规范

定位:设计指南/CLI设计 概览的深度规范。CI = Command Interface——给 Agent/Skill 调用的一套指令系统(可落地为 CLI,也可被 MCP/脚本封装)。核心不是「命令行形式」,而是「为 AI 执行业务任务而设计的稳定、短、可验证、可组合的指令层」。

📎 来源:好 Skill 与 AI 原生 CLI/CI 指令系统设计指南。

---

稳定架构:四层不要混

业务 API / 数据 / 系统能力
        ↓
AI 原生 Command Interface / CLI     ← 把不稳定部分收敛掉
        ↓
Skill:告诉 Agent 何时、如何、安全地调用这些命令
        ↓
Agent:理解任务、选择流程、调用命令、验证结果

不要问「这个 API 怎么包成命令」,要问「AI 在这个业务里需要哪些稳定动作?拆成什么颗粒度?每个动作如何输入/输出/验证/恢复?」

五层模型

L0 API / SDK 层        认证/请求/分页/限流/错误码/原始字段 —— 不直接给 Agent
L1 Resource 层         围绕资源的 CRUD(record get/search/create/...)—— 调试/精细控制
L2 Workflow 层         围绕业务任务的组合动作(report generate / audit run)—— ★ Agent 主入口
L3 Safety & Ops 层     doctor / validate / plan / dry-run / verify / audit-log
L4 Skill Guidance 层   Skill 告诉 Agent 何时用哪个命令、先 doctor、写操作先 dry-run

L2 内部通常是:validate input → query context → calculate → write/submit → readback → output evidence。

命令颗粒度:三类 + 7 问

三类:原子资源命令(crm customer get)· 业务动作命令(epr-sales trade order-create)· 任务工作流命令(cost-audit audit run)。

设计每个命令前问 7 个问题——2/3/4/5/6 多个为「是」就该做成高层业务命令,而不是让 Agent 自己拼 API:

1. Agent 会频繁需要吗? 2. 有明确业务语义吗? 3. 参数多到容易错吗? 4. 需要多步 API 组合吗? 5. 有安全风险吗? 6. 需要写后验证吗? 7. 该被复用为 Skill 标准步骤吗?

输出协议:给模型用,必须机器友好

• stdout 只放 JSON(--output json 默认);进度/警告/调试走 stderr。不要把进度条、emoji 混进 stdout。
• 错误必须结构化:{ok:false, error_code, message, hint, details} —— 纯文本 invalid input 对 Agent 没用。
• 成功必须带 evidence:{ok:true, data, evidence:{readback_ok, readback_command, audit_id}} —— 没 evidence 就容易假完成。

基础命令集(给 Skill 用的 CLI 最低配)

xxx doctor   --output json     检查 CLI/版本/配置/token/依赖/网络/读写权限
xxx help [domain [command]]    人/Agent 速查
xxx schema <command> -o json   让 Agent 不用猜参数(required/flags/examples/risk)
xxx validate --file in.json    只校验不写
xxx <cmd> --dry-run            预演:输出将要做什么 + requires_confirmation
xxx <cmd> --yes               真正执行
xxx verify --id <id>          写后验证
xxx audit list/show           Agent 能追踪自己做了什么

安全分级(高风险必须有护栏)

等级	类型	策略
R0	纯读	可直接执行
R1	低风险写	明确用户意图即可
R2	状态变更	默认 dry-run,需确认
R3	财务/删除/撤销/外部发送	必须 dry-run + 人工确认 + audit + readback

没有 --yes 的 R3 命令必须拒绝执行。高风险动作不允许 Agent 静默执行。

命名原则

• 用业务动词:trade order-create / audit run / report generate,不是 api post / invoke AddOrderAsync。
• 命令要短:把复杂性封进命令内部,而不是堆在命令行(对照 设计指南/CLI设计 的 200 字符 vs 100 字符)。
• 参数业务化:--project-id / --scenario control-price,不是 --guid1 / --type 3 / --payload。
• 命令树第一层是业务对象,不是 API URL / 服务名 / URL 前缀。

从 API 到 AI 原生 CLI 的迁移(6 步)

1 识别产品对象(先建对象模型,不是先看 API)
2 识别 Agent 任务(查询/分析/报告/审核/写入/同步/回填/通知)
3 设计命令层级(domain object action)
4 区分只读 / 低风险写 / 高风险写(写操作:dry-run→confirm→audit→readback)
5 把复杂多步 API 封装进 Workflow command(别让模型自己拼 schema→查数→拼 DSL→跑查询)
6 Skill 只写调用策略(先 schema describe,再 dsl generate,再 query …)

参考飞书 CLI 的「保留底层 + 优先高层工作流」双层设计,以及官方 lark-mcp 的 preset(按任务暴露最小必要命令集,而非把全部 OpenAPI 一股脑给模型)。

与业务本体的关系

数据问答/分析/审核类场景,CLI/CI 还应结合本体(设计指南/本体设计):TBox(schema/概念层)对应 biz schema describe / dsl generate;ABox(实例/数据层)对应 biz data query / drilldown / evidence。Agent 不拼 SQL,而是调审核/查询动作。

评估清单 & 坏味道

好 CLI/CI:有 doctor / help / schema;stdout 纯 JSON;错误带 error_code+hint;写操作有 dry-run;写后有 verify;高风险有 audit;按场景 preset;examples 可复制。

坏味道:没有 --output json;stdout 混日志;错误不可解析;没 doctor/schema;参数全是 API 字段名;命令名是 URL/服务名;写操作没 dry-run;成功后没 readback;所有命令都是 API wrapper。

参考与延伸

• 概览与实测收益 → 设计指南/CLI设计
• Skill 该怎么配合写 → 设计指南/Skill设计
• 真实 CLI 化案例(4 方评测)→ 实践分享/控制价审核CLI化实战