coco
152 lines
4.6 KiB
Markdown
152 lines
4.6 KiB
Markdown
---
|
||
title: "Thread by @shao__meng"
|
||
source: "https://x.com/shao__meng/status/2037475968793915494"
|
||
author:
|
||
- "[[@shao__meng]]"
|
||
published: 2026-03-27
|
||
created: 2026-03-28
|
||
description:
|
||
tags:
|
||
- "clippings"
|
||
---
|
||
**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
|
||
>
|
||
>   |