Wayne的技术博客
·
面向 AI / Agent 友好的 CLI 开发建议
💡
原文中文，约13800字，阅读约需33分钟。
📝
内容提要
本文讨论了面向AI和Agent友好的命令行界面（CLI）设计原则，强调CLI应作为Agent的文本API，具备稳定的输出格式、结构化的JSON响应和明确的退出码。设计应确保stdout仅输出机器可读数据，stderr用于日志和提示，同时支持流式输出和分页，以降低Agent的推理负担。CLI的未来在于其可组合性和对Agent的友好性，需遵循规范以提升可用性和效率。
🎯
关键要点
- CLI 应作为 Agent 的文本 API，具备稳定的输出格式和结构化的 JSON 响应。
- stdout 应仅输出机器可读数据，stderr 用于日志和提示，确保输出格式的稳定性。
- 所有返回结果的命令都应支持 --json，且 JSON 结构应稳定、完整、版本化。
- 长任务应支持 NDJSON 格式，允许 Agent 实时读取进度信息。
- 退出码应分层设计，提供明确的状态反馈，便于 Agent 决策。
- 帮助信息应清晰，便于 Agent 快速建立模型，包含输入/输出契约和示例。
- CLI 设计应遵循安全分级，确保危险操作需要明确确认。
- CLI 应具备可组合性，成为 Agent 基础设施，而非仅仅是人类操作界面。
❓
延伸问答
如何设计一个面向AI的命令行界面（CLI）?
设计应确保CLI作为Agent的文本API，具备稳定的输出格式和结构化的JSON响应，同时支持流式输出和明确的退出码。
CLI的输出格式应该如何处理?
stdout应仅输出机器可读数据，stderr用于日志和提示，确保输出格式的稳定性。
为什么CLI需要支持--json选项?
所有返回结果的命令都应支持--json，以确保输出结构稳定、完整、版本化，便于Agent解析。
CLI的退出码应该如何设计?
退出码应分层设计，提供明确的状态反馈，便于Agent决策，避免所有错误都返回相同的码。
如何确保CLI的安全性?
CLI设计应遵循安全分级，确保危险操作需要明确确认，并对不同操作进行权限分级。
CLI如何支持长任务的输出?
长任务应支持NDJSON格式，允许Agent实时读取进度信息，避免一次性输出造成的信息丢失。
➡️
