coco
4.6 KiB
title, source, author, published, created, description, tags
| title | source | author | published | created | description | tags | ||
|---|---|---|---|---|---|---|---|---|
| Thread by @shao__meng | https://x.com/shao__meng/status/2037475968793915494 |
|
2026-03-27 | 2026-03-28 |
|
meng shao @shao__meng 2026-03-26
面向 AI Agent 优化的 CLI 七项设计原则
- 为什么需要 Agent-Friendly CLI？
背景痛点：
· 现有 CLI 设计资源（如 Command Line Interface Guidelines）完全以人类为中心
· 人类可以阅读提示、做出判断、解析格式化表格，但Agent在后台运行时无法处理交互式提示
· 彩色输出浪费 token，无界响应消耗上下文窗口
· 当 Agent 或 Skill 产生后台子 Agent 时，交互式 CLI 会中断——无法将提示传回给用户，导致 Claude Code 和 Codex 等工具直接退出
CLI vs MCP 的权衡：
· MCP 需要加载工具定义（可能消耗数万 token），适合需要用户认证和结构化治理的场景
· CLI 是"文本进、文本出"，天然可组合，LLM 已从训练数据中了解常见 CLI 工具，无 Schema 开销
· 对于开发者日常构建和使用的工具，设计良好的 CLI 更快、更便宜、更可靠
- 七项核心原则详解
1. 默认非交互式
核心： Agent 可能自动化的任何命令都应无需提示即可运行。
关键实现：
· 检测 TTY vs 非 TTY，当 stdin 非交互式时抑制提示
· 支持 --no-input 或 --non-interactive 标志
· 提供 --yes/--force 绕过确认
· 通过 flags、文件或 stdin 接受结构化输入
严重性： 命令挂起等待输入 = Blocker；部分提示可绕过但行为不一致 = Friction；完整flag覆盖+全局非交互模式 = Optimization
2. 结构化、可解析的输出
核心： 返回数据的命令应提供稳定的机器可读表示。
关键实现：
· 数据承载命令支持 --json
· 退出码：0 成功，非 0 失败
· 结果数据写入 stdout，诊断信息写入 stderr
· 非 TTY 时抑制颜色、旋转器和装饰性输出
3. 快速失败并提供可操作的错误
核心： 命令失败时，错误信息应教会 Agent 如何在下次尝试时成功。
优秀错误四要素： 指出具体问题、展示正确调用形式、建议有效值、包含示例
4. 安全重试和显式变更边界
核心： Agent 会重试、恢复和重放命令。变更命令应尽可能安全，危险变更应显式。
关键实现：
· 重复命令不创建重复工作（幂等性或清晰检测）
· 危险操作使用显式破坏性标志（如 --confirm）
· 提供 --dry-run 预览后果
· 返回足够状态信息供 Agent 验证
5. 渐进式帮助发现
核心： Agent 不会预先阅读完整文档，而是通过探测逐步发现。
Agent 探索模式： 顶层 help → 子命令 help → 示例
子命令 help 四要素：
· 单行用途说明
· 具体调用模式
· 必需参数或标志
· 最重要的修饰符或安全标志
关键洞察： Anthropic 研究表明，具体示例能显著提升 Agent 使用工具的效果
6. 可组合和可预测的结构
核心： Agent 通过链式命令解决任务，受益于接受 stdin、产生干净 stdout、使用可预测命名和子命令模式的 CLI。
关键实现：
· 通过 flags、文件或 stdin 接受输入
· 文件路径支持-作为 stdin/stdout 别名
· 相关资源保持命令结构一致
· 多字段模糊操作使用 flags，保留位置参数用于熟悉的惯例场景
一致性陷阱： 如果 posts list 支持 --json 但 posts stats 不支持，或 --limit vs --max-results 混用，Agent 必须学习例外而非应用模式
7. 有界、高信号响应
核心： Agent 为每行额外输出支付真实成本。大输出有时必要，但 CLI 应默认提供狭窄、相关的响应。
关键洞察： 人类可以滚动 500 行输出并视觉定位所需，Agent 必须消耗全部 500 行到上下文窗口，为每个 token 付费，然后判断哪些行重要
关键实现：
·提供简洁vs详细响应模式制
· 提供简洁vs详细响应模式
· 截断时解释如何缩小或分页
· 返回摘要和标识符，而非原始详情
- 实践工具
作者基于这些原则开发了 CLI Agent Readiness Reviewer（Compound Engineering 插件的一部分），能够：
· 自动评估 CLI 源代码是否符合七项原则
· 框架感知（Click、argparse、Cobra、clap 等）
· 按命令类型区分重要性
· 生成每项发现的测试断言，支持 CI 集成
2026-03-26
