Wayne的技术博客
·
面向 AI / Agent 友好的 CLI 开发建议
内容提要
本文讨论了面向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 基础设施，而非仅仅是人类操作界面。
延伸解读
CLI 设计的转变
随着 AI 和 Agent 的兴起，CLI 的角色正在从传统的人机交互界面转变为面向机器的文本 API。这一转变要求开发者在设计时考虑机器的解析能力和稳定性，以便 Agent 能够高效地集成和使用 CLI 工具。
输出格式的重要性
在设计 CLI 时，确保 stdout 只输出机器可读的数据，而 stderr 用于日志和提示是至关重要的。这种分离不仅提高了数据的可解析性，还减少了 Agent 在处理输出时的推理负担，避免了因格式不稳定而导致的错误。
流式输出的优势
对于长时间运行的任务，采用 NDJSON 格式进行流式输出可以让 Agent 实时获取进度信息。这种设计不仅提升了 Agent 的决策能力，也使得人类用户能够更好地跟踪任务进展，增强了 CLI 的实用性。
安全性与可用性的平衡
在 CLI 设计中，安全性与可用性之间的平衡至关重要。通过对命令进行分级（如 read、write、dangerous），并要求在执行危险操作时进行明确确认，可以有效降低误操作的风险，同时确保 Agent 在执行任务时的安全性。
延伸问答
如何设计一个面向AI的命令行界面（CLI）?
设计应确保CLI作为Agent的文本API，具备稳定的输出格式和结构化的JSON响应，同时支持流式输出和明确的退出码。
CLI的输出格式应该如何处理?
stdout应仅输出机器可读数据，stderr用于日志和提示，确保输出格式的稳定性。
为什么CLI需要支持--json选项?
所有返回结果的命令都应支持--json，以确保输出结构稳定、完整、版本化，便于Agent解析。
CLI的退出码应该如何设计?
退出码应分层设计，提供明确的状态反馈，便于Agent决策，避免所有错误都返回相同的码。
如何确保CLI的安全性?
CLI设计应遵循安全分级，确保危险操作需要明确确认，并对不同操作进行权限分级。
CLI如何支持长任务的输出?
长任务应支持NDJSON格式，允许Agent实时读取进度信息，避免一次性输出造成的信息丢失。
