Notion(@NotionHQ)
如何为人类与代理设计 CLI？—— Notion CLI 的 4 条原则
7.5Score
TL;DR · AI 摘要
Notion CLI (ntn) 的 4 条设计原则为 AI 时代 CLI 设计提供了可复用的工程范式：渐进式披露、可操作错误信息、stdout/stderr 分离、交互/非交互双模式。
核心要点
- 渐进式披露：默认隐藏复杂选项，通过 -v/-vv 层级展开，平衡人类可读性与机器解析性
- 可操作错误信息：错误输出需包含具体修复命令或文档链接，而非仅状态码
- stdout/stderr 严格分离：结构化数据走 stdout，日志/错误走 stderr，确保管道与代理解析可靠
结构提纲
按章节快速跳转。
Notion CLI 需要同时服务人类开发者和 AI 代理，这要求界面设计在可用性与机器可解析性之间取得平衡。
通过默认简洁输出与多级详细模式（-v/-vv），CLI 既满足人类快速扫读，又为代理提供完整上下文。
错误输出必须包含具体修复步骤或文档链接，使人类和代理都能自主解决问题而非猜测。
结构化数据输出至 stdout，日志与错误输出至 stderr，确保管道传输和程序解析的可靠性。
通过检测 TTY 状态自动切换模式，同一命令可在交互式提示与纯 JSON 输出间自适应。
思维导图
用一张图看清主题之间的关系。
查看大纲文本（无障碍 / 无 JS 友好）
- ntn CLI Design Principles
- Progressive Disclosure
- Default: minimal output
- -v/-vv: verbose levels
- Actionable Errors
- Specific fix commands
- Documentation links
- Output Separation
- stdout: structured data
- stderr: logs/errors
- Dual Modes
- TTY detection
- Interactive ↔ JSON
金句 / Highlights
值得收藏与分享的关键句。
渐进式披露：默认隐藏复杂性，通过 -v/-vv 标志层级展开
可操作错误信息：告诉用户具体下一步做什么，而非仅告知出错
数据与消息分离：stdout 输出结构化数据，stderr 输出日志和错误
交互与非交互双模式：检测 TTY 在人类提示与 JSON 输出间自动切换
#CLI#AI Agent#Notion#开发者体验#API 设计
打开原文