发布命令行界面设计指南

背景

命令行界面（CLI）是计算机历史上最持久、最底层的交互方式之一。早在1980年代，用户面对的是 C:\> 或 ~$ 的提示符，必须记住命令、翻阅厚厚的螺旋装订手册，错误信息晦涩难懂，没有 Stack Overflow 可求助，只有 Usenet 社区提供有限的帮助。四十年后的今天，计算机对普通人越来越友好，但这种便利往往以牺牲底层控制权为代价——许多设备甚至取消了命令行入口，这与围墙花园和应用商店的企业利益相悖。大多数人不再知道命令行是什么，更不用说为什么值得花时间学习它。正如计算先驱 Alan Kay 在2017年访谈中所说：“因为人们不了解计算的意义，他们以为 iPhone 就是计算的全部，这种错觉和认为‘吉他英雄’就是真吉他的错觉一样糟糕。”Kay 所说的“真吉他”并不完全指 CLI，但他强调的是一种超越文本文件的编程方式，能够提供CLI的威力。尽管有学者认为我们需要跳出沿用几十年的文本局部最优解，但命令行依然是计算机中最通用的角落：它可以让你拉开帷幕，查看真实运行状况，以GUI无法达到的深度和精细度与机器交互；它几乎在任何笔记本电脑上都可用，适合任何人学习；既可以交互使用，也可以自动化；而且它比其他系统组件变化更慢，这种稳定性本身就具有创造价值。

然而，从编程方式来看，命令行已经发生了巨大变化。过去的命令行以机器为先：本质上是脚本平台之上的一层 REPL（读取-求值-打印循环）。但随着通用解释型语言的蓬勃发展，Shell 脚本的角色日益缩小。今天的命令行以人为先：它是一种基于文本的 UI，可以访问各种工具、系统和平台。过去，编辑器存在于终端内部；现在，终端常常是编辑器的一项功能。Git 式的多工具命令（子命令系统）大量涌现，出现了更高层次的命令（执行完整工作流而非原子功能）。受到传统 UNIX 哲学的启发，同时出于创造一个更愉悦、更易访问的 CLI 环境的愿望，一群有经验的程序员决定重新审视构建命令行程序的最佳实践和设计原则，于是撰写了这份开源指南。

核心内容

这份指南名为《Command Line Interface Guidelines》（命令行界面指南），由 Aanand Prasad（Squarespace 工程师，Docker Compose 联合创建者）、Ben Firshman（Replicate 联合创始人，Docker Compose 联合创建者）、Carl Tashian（Smallstep 越野工程师，Zipcar 首位工程师，Trove 联合创始人）、Eva Parish（Squarespace 技术文档撰写者，O’Reilly 贡献者）共同撰写。设计由 Mark Hurrell 完成，感谢 Andreas Jansson 早期贡献，以及 Andrew Reitz、Ashley Williams、Brendan Falk、Chester Ramey、Dj Walker-Morgan、Jacob Maine、James Coglan、Michael Dwan、Steve Klabnik 等审阅草稿。

引言

该文档涵盖高级设计哲学和具体指南，更侧重指南部分——因为作为实践者，他们的哲学是不过度哲学化。他们相信通过实例学习，提供了大量例子。本指南不涵盖全屏终端程序（如 emacs、vim），这些项目较为小众，很少有机会设计。指南也对编程语言和工具持中立态度。

读者对象：

• 如果你正在创建一个 CLI 程序，并希望了解 UI 设计的原理和具体最佳实践，本指南适合你。
• 如果你是一名专业的“CLI UI设计师”，那太棒了——他们乐意向你学习。
• 如果你希望避免那些违反40年 CLI 设计惯例的明显错误，本指南适合你。
• 如果你希望通过良好的设计和有用的帮助信息让用户感到愉悦，本指南绝对适合你。
• 如果你正在创建一个 GUI 程序，本指南不适合你——但也许你会在阅读中了解到一些 GUI 反模式。
• 如果你正在设计一个沉浸式全屏 CLI 版的《Minecraft》，本指南不适合你（但很期待见到它）。

哲学

以下被认为是优秀 CLI 设计的根本原则：

1. 以人为先的设计（Human-first design）

传统 UNIX 命令假设它们主要被其他程序调用。它们在编程语言中更像是函数，而非图形应用。如今，许多 CLI 程序主要（甚至完全）由人类使用，但它们的交互设计仍带有过去的包袱。是时候抛弃一些包袱了：如果一个命令主要被人类使用，它就应该首先为人类设计。

2. 可组合的简单部件（Simple parts that work together）

原始 UNIX 哲学的核心信条：小而简单的程序，具有清晰的接口，可以组合成更大的系统。与其往单个程序里塞入越来越多功能，不如让程序足够模块化，以便根据需要重新组合。在过去，管道和 Shell 脚本在程序组合中至关重要；随着通用解释型语言的兴起，它们的作用有所减弱，但并未消失。大规模自动化（CI/CD、编排、配置管理）蓬勃发展，使得程序的可组合性一如既往地重要。幸运的是，UNIX 环境中长期建立的惯例（标准输入/输出/错误、信号、退出码等）仍然帮助我们确保不同程序能很好地拼接在一起。纯文本的、基于行的文本易于在命令间管道传递。JSON 作为较新的发明，在需要时提供了更多结构，并允许命令行工具更轻松地与 Web 集成。无论构建什么软件，你都可以确信人们会以你未曾预料的方式使用它。你的软件将成为更大系统的一部分——你唯一的选择是它是否成为一个行为良好的部分。最重要的是，为可组合性设计并不需要与“以人为先”的设计相冲突。这份文档中的许多建议正是关于如何兼得两者。

3. 程序间的一致性（Consistency across programs）

终端的惯例已经深植于用户的指尖。用户通过学习命令行语法、标志、环境变量等付出了前期成本，但长期来看收益巨大——只要程序保持一致。如果每个程序都发明自己的命令风格、标志命名规则或输出格式，用户的学习成本将居高不下。因此，遵循已有的惯例至关重要。（原文在此处截断，但核心思想已经明确。）

关键要点

• 以人为先：传统 UNIX 服务于机器，现代 CLI 应优先考虑人类用户体验，包括清晰的错误信息、友好的帮助文档和合理的交互设计。
• 模块化与可组合：继承 UNIX 哲学，让程序小而专、接口干净，通过标准输入/输出/错误、退出码、信号等机制实现可组合性，适应自动化场景。
• 跨程序一致性：遵循现有 CLI 惯例（如标志命名、子命令结构、环境变量），降低用户学习成本，使肌肉记忆生效。
• 兼顾人机与机机交互：设计既能被人类友好使用，又能被脚本和管道高效消费——例如同时输出人类可读的文本和结构化数据（如 JSON）。
• 文本为基础，善用管道：保持纯文本、基于行的输出，易于管道传递；必要时提供 JSON 等结构化格式以增强集成能力。
• 拥抱变化但保持稳定：命令行环境变化较慢，这种稳定性具有创造价值；但同时要适应现代解释型语言和复杂工作流，如 git 风格的多工具命令。
• 学习实例，不过度哲学化：指南提供具体例子而非空泛理论，强调实践驱动。
• 面向 CLI 创建者：适合所有需要设计 CLI 程序的开发者，尤其是那些希望避免常见错误、提升用户满意度的开发者。

意义与影响

这份指南的出现具有重要意义。在 GUI 和触控界面日益主导的今天，命令行依然在开发运维、数据工程、系统管理、自动化等领域扮演着不可替代的角色。然而，CLI 的设计长期以来缺乏系统性的、与时俱进的指导。传统 UNIX 哲学诞生于1970年代，许多惯例（如短标志、不友好的错误信息）在面向人类使用时显得过时。该指南由 Docker Compose 等知名工具的创造者撰写，结合了现代编程实践和用户体验设计，为 CLI 程序开发者提供了一份权威参考。

它不仅重申了 UNIX 的经典原则（可组合、模块化），更将其与“以人为先”的理念融合，解决了过去 CLI 设计偏重机器、忽视人类的矛盾。这份指南鼓励开发者遵循一致性、提供友好的帮助、支持结构化输出，从而降低 CLI 工具的学习门槛，提高开发者效率和自动化质量。此外，开源发布、社区讨论（Discord）的模式也促进了 CLI 设计的最佳实践传播。

长远来看，这份指南可能促使新一代 CLI 工具更加生态友好、更加规范，推动命令行界面在新时代的复兴。