命令行界面设计：参数解析、输出格式化、退出码与可组合性（综合报告） 未开始

题记与说明

本报告由同日（2026-11-05）完成的两份章节稿综合而成：纵轴章节《命令行界面设计——纵轴发展史》（output/reports/parts/2026-11-05-命令行界面设计-参数解析-输出格式化-退出码-可组合性-vertical.md）与横轴章节《命令行界面设计——横向对比报告》（同目录 -horizontal.md）。综合工作做了三件事：合并两章重复的事实与来源、消除两章间的表述分歧（校准记录见 §3.5）、在两条轴线交叉处产出单章无法得到的洞察。所有版本号与维护状态均为检索时点 2026-11-05 的快照；关键事实均附来源链接，凡未能检索验证、出自模型既有知识的断言均单独标注（见文末说明）。

最终稿修订说明（已按独立审读意见逐条修订，正文结构与未被质疑的内容未改动）：① 统一退出码表述，消除"只有 0 被标准锁死"与 §1.4 shell 保留值（126/127/>128）的自相矛盾（TL;DR、§2.5、§3.1）；② §1.7 中 sysexits 的"收缩到邮件领域"改为与 §2.2/§2.5/§3.6 一致的限定表述；③ 删去无出处的"128–165"上限，改为"128 以上（bash 的 128+N 约定）"；④ 为 CLI Agent Spec 与 AOI-CLI 补充规范原文出处并核对原文（§2.2）；⑤ 为 1971 Thompson shell、1983 GNU、1991 Linux、2001 POSIX 合并四处史实补来源链接；⑥ §2.1 竞品地图补齐 jq 与 MCP 两行；⑦ 修正 click 维护状态、选型矩阵退出码栏与 PowerShell 快照时点三处费解表述；⑧ §2.4 点破 JSONL 事件流与"被管道不自动切 JSON"的共存关系，§3.6 检查清单补"何时引入更多分类码"、风险提示补"观望判定信号"。

TL;DR

CLI 设计的四个议题——参数解析、输出格式化、退出码、可组合性——六十年只围绕一个张力展开：程序要同时伺服人与机器。参数解析从手写 argv 经 getopt、GNU 长选项、POSIX 准则走到声明式框架，2024 年 getopt_long 入 POSIX 正典；输出端确立「stdout 是数据、stderr 是话语」，TTY 检测＋NO_COLOR＋--json 构成人机双轨；退出码除 shell 保留值（126/127/128+N）外仅 0 被标准定义，是四要素中最欠标准化的一环；可组合性以文本管道为基线，与 PowerShell、Nushell 的结构化路线并存不替。2024 年起 AI Agent 成为 CLI 的第二用户：非交互、--json、--dry-run、可预测退出码从加分项变为硬指标，agent 规范以「机器模式叠加」的方式与 clig.dev 共存而非取而代之。给开发者的收敛建议：用成熟解析库、守住流分流、退出码 0/1/2 并文档化、在文本管道内打结构化补丁。

0. 课题界定

命令行界面（CLI）设计是一门围绕"程序如何被调用、如何说话、如何被机器判读"的工程学问，核心议题有四（纵轴章节 §0）：

• 参数解析：选项、操作数、子命令如何被声明与识别（-v / --verbose / -- / 子命令风格）；
• 输出格式化：stdout 与 stderr 的分工、人类可读与机器可读的平衡（彩色、表格、--json）；
• 退出码：进程结束时留给调用方的语义信号（0 成功、非 0 失败、126/127/128+n）；
• 可组合性：程序能否通过管道、重定向、退出码与脚本彼此咬合。

由于本课题不是单一产品而是一套界面设计约定，横轴章节把"同类与替代方案"拆成三个层次：规范层（POSIX Utility Conventions、GNU Coding Standards、12 Factor CLI Apps、clig.dev，以及 2025 年以来面向 AI Agent 的 CLI Agent Spec 与 AOI-CLI——这一层彼此互为竞品，争夺"开发者以谁为准"）；工具层（POSIX getopt/shell getopts、GNU getopt_long、Python 的 argparse/docopt/click/typer、Go 的 cobra+pflag、Rust 的 clap、Node 的 commander.js 等解析实现）；范式层（Unix 文本管道 vs PowerShell 对象管道 vs Nushell 结构化管道 vs jq 式 JSON 后处理，以及把"调用别的软件"整体替换掉的 MCP）。四个议题在三个层次上各有不同的竞品集合。

这四个议题共同构成 Unix 哲学"单一职责、文本流组合"在现代的落点，也是 POSIX 与后续现代 CLI 规范（Heroku 风格指南、12 Factor CLI Apps、clig.dev）反复规定的对象。

1. 纵轴：发展脉络（1964–2026）

1.1 阶段一（1964–1979）：诞生期——管道、组合哲学与流分离

CLI 的"可组合性"基因早于 Unix 本身。1964 年，贝尔实验室的 Douglas McIlroy 在一份内部备忘录中提出：程序应当像园浇水管一样彼此插接、可互换组合。这份备忘录被视为管道思想的起源（toroid.org 存档的备忘录影印件、Wikipedia: Pipeline (Unix))）。1971 年 Ken Thompson 发布第一版 Unix shell（Wikipedia: Thompson shell：随 1971 年 Unix 第一版引入、为首个 Unix shell），确立了"命令 + 空白分隔的参数"这一基本调用语法。1973 年 1 月，Thompson 在"一个狂热的夜晚"实现了 pipe() 系统调用、shell 管道语法与一批配套工具，并于同年 2 月随 Version 3 Unix 手册发布；由此 grep | sort | wc 式的组合成为日常（Unix Heritage Wiki: pipes）。McIlroy 后来在 1978 年 Bell System Technical Journal 的前言中把这一哲学总结为名言："让每个程序的输出成为另一个尚不存在的程序的输入……不要在输出中掺杂无关信息"（转引见 Wikipedia: Unix philosophy）。

这一时期还埋下了另外两个议题的种子。其一是流分离：1970 年代中后期，stderr 从 stdout 中分离出来成为独立的标准流，使"数据"与"报错"得以分开处理（此为一般性共识，精确版本节点未检索验证）。其二是退出码：shell 的 $? 参数把子进程的结束状态暴露给脚本，1979 年 Version 7 Unix 携带的 Bourne shell 使 0 = 成功 的约定广泛传播（模型既有知识，未单独检索验证）。在输出端，1976 年 ECMA-48 与 1979 年 ANSI X3.64 定义的控制序列（含颜色）为日后终端彩色输出提供了底层协议（Wikipedia: ANSI escape code）。

驱动因素：小型机内存与 CPU 极其有限，逼出"每个程序只做一件事、用文本流拼接"；多用户分时系统让交互式 shell 取代批处理作业卡。

1.2 阶段二（1980–1985）：早期工程化——getopt 与 sysexits

随着 Unix 工具数量膨胀，各程序"手写 argv 循环"的错误处理开始失控。1980 年 5 月 16 日的 System III 手册页显示，getopt(1) 已作为解析命令行选项的标准工具出现；AT&T 在 1985 年 UNIFORUM 会议（达拉斯）上将其源码对外公开发布，随后演化为 C 库函数 getopt(3)（System III getopt(1) 手册页影印件、Wikipedia: Getopt）；1986 年，SVR3 的 Bourne shell 又引入内建的 getopts（Wikipedia: Getopts）。"选项解析"第一次从每个程序的家务事，变成了一项可复用的基础设施。

同一时期，退出码体系开始分化。sendmail（Eric Allman）为了在邮件投递代理与守护进程之间传递更细粒度的失败原因，形成了一组 64–78 的扩展退出码；这套编码后来固化为 BSD 的 <sysexits.h>（EX_USAGE=64、EX_NOINPUT=66、EX_TEMPFAIL=75 等）。一个常被搞错的细节：sysexits(3) 手册页自己承认该文件"出现在 4.3BSD 之后的某个版本"，而非常被引用的"4.3BSD 首见"（Mac OS X sysexits(3) 手册页、staticdata.dev exit-codes 数据集）。

驱动因素：Unix 的 BSD / System V 两大支系分裂，同一工具的行为差异催生了对统一约定的需求；邮件系统等"无人值守"的服务程序需要比 0/1 更丰富的机器可判读状态。

1.3 阶段三（1983–1991）：GNU 与长选项——--help、--version 与路线之争

1983 年 Richard Stallman 发起 GNU 计划（1983 年 9 月 27 日 Usenet 公告，FSF: About GNU），给 CLI 带来一次至今仍在生效的范式升级：长选项。GNU 软件普遍支持 --help、--version 以及形如 --verbose 的自描述长选项，并把这套约定写进 GNU Coding Standards（Command-Line Interfaces 节）；配套的 getopt_long 在 GNU/glibc 生态中普及（确切入库年份未检索验证），长选项随 Linux 的崛起（1991 年 Linus 发布内核——8 月 25 日宣告、9 月 17 日发布 0.01，Wikipedia: Linux kernel，GNU 用户态工具随之铺开）成为事实标准。

1986 年，Rob Pike 与 Brian Kernighan 发表《Program Design in the UNIX Environment》（即著名的 "cat -v considered harmful"），批评 GNU/MIT 式给 cat 塞入 -v 等选项的做法违背"单一职责"——这是 CLI 设计史上第一次高调的"克制 vs 膨胀"路线之争（全文存档；事件年份为模型既有知识）。

驱动因素：GNU 工具要在各 Unix 上保持一致体验，自描述的长选项降低学习成本；Linux 诞生后 GNU 工具链借助发行版获得空前的分发规模。

1.4 阶段四（1992–2017）：POSIX 时代——语法准则与退出码的法定化

1992 年 IEEE Std 1003.2-1992（POSIX.2，Shell and Utilities）发布，与 X/Open Curses and Utilities Issue 4 在相应技术上等同（The Open Group: Commands and Utilities Issue 4）。它把散落在各工具间的习惯固化成 Utility Syntax Guidelines（12 条）：命令名 2–9 字符、选项用单字母并前置 -、无参选项可分组、-- 终止选项解析、- 代表 stdin/stdout 等（POSIX.1-2017 XBD 第 12 章）；其中最关键的 Guideline 12 要求"选项相对于操作数的顺序不应影响工具功能"。2001 年起 POSIX.1 与 POSIX.2 合并为统一的基础规范（POSIX.1-2001 / SUSv3，Linux man-pages standards(7)：对 POSIX.1、POSIX.2 与 SUS 的 2001 年修订与合并），第 12 章"Utility Conventions"沿用至今。

退出码同样被"法定化"：POSIX shell 规定命令找不到退出码为 127、找到但不可执行为 126、因信号终止则大于 128；标准措辞谨慎地只要求"大于 128"，128+信号号 是 glibc/bash 等实现的可移植实践（POSIX.1-2024 XCU 2.8.2 Exit Status）。

这一阶段，POSIX 语法准则成为几乎所有语言解析库的隐形模板：Perl 的 Getopt::Long、Python 2.3 引入的 optparse，都在复刻"短选项 + 长选项 + --"的模型。2009 年 Python 通过 PEP 389 把第三方库 argparse 收编进标准库（随 Python 2.7/3.2 发布），官方宣布 optparse 进入弃用状态；argparse 首次把子命令（git add 式）与可变参数 nargs 做成标准库能力（PEP 389）。2006 年微软 PowerShell 1.0 发布，管道里流动的不再是文本而是对象——这是对"文本流可组合性"的一次正面替代尝试（Wikipedia: PowerShell；事件年份为模型既有知识）。2003 年 Eric Raymond 的《The Art of UNIX Programming》则把"Rule of Silence""Rule of Separation"等 CLI 设计法则成文化（模型既有知识）。

驱动因素：企业采购要求跨 Unix（AIX/HP-UX/Solaris/…）可移植，标准化的命令行为成为合同级需求；脚本化运维（cron、CI 前身）要求退出码可编程判读。

1.5 阶段五（2011–2019）：现代 CLI 文艺复兴——声明式框架与"体验优先"

2010 年代，云与 DevOps 让 CLI 从"系统管理员的附属品"变成产品的一等门面，专用解析框架大爆发：

• commander.js（TJ Holowaychuk，2011 年首版）：Node.js 生态事实标准的 CLI 框架（github.com/tj/commander.js）；
• docopt（Vladimir Keleshev，2012）：反其道而行——直接把用法字符串（usage string）当作解析器，"文档即测试"（PyPI）；
• jq（Stephen Dolan，2012）："JSON 时代的 sed"，让结构化数据也可以进入管道组合（官方手册）；
• Cobra（Steve Francia，2013 年开始维护，2014 年 12 月经 Gopher Academy 正式介绍）：把"子命令 + 自动 help 生成 + 脚手架"打包，随后被 Docker、Kubernetes（kubectl）、Hugo 乃至 GitHub CLI 采纳，子命令风格由 git 特例升格为云原生时代的通用范式（cobra.dev、github.com/spf13/cobra）；
• Click（Armin Ronacher / Pallets，2014 年 4 月首次发布）：基于装饰器的声明式解析，绑定 Flask 社区；
• clap（Kevin Knapp，Rust，2015）：Rust 生态的解析器旗舰，crates.io 早在 2015 年 8 月即有 1.3.0 版本（crates.io/crates/clap、docs.rs/clap）。

设计规范也在快速成文。Heroku 以自家 CLI 为样板发布 CLI Style Guide，规定 help 结构、输出与错误的处理（devcenter.heroku.com）。2018 年 10 月，Heroku CLI 前负责人 Jeff Dickey 发表 "12 Factor CLI Apps"，把 12-Factor App 方法论移植到 CLI：涵盖设计、配置、退出码（0 成功、1 失败、2 用法错误）、输出、错误、help、版本化等 12 条（jdx.dev 原文；镜像：Medium）。输出端则出现去干扰运动：2017 年提出的 NO_COLOR 约定（no-color.org），配合 TERM=dumb 检测与 --no-color 标志，"颜色必须可被关闭"成为礼貌底线；--json / --output json 也在这一时期成为各大云 CLI（AWS CLI 等）的通用出口。2019 年 8 月 Nushell 诞生，把"表格/结构化数据管道"推向 shell 本体（诞生博客、github.com/nushell/nushell）。

驱动因素：云计算与 CI/CD 把 CLI 嵌入人机与机机两条交互链路；开源框架间的竞争使"自动生成 help、补全、类型校验"成为框架标配，参数解析彻底从手写循环变为声明式工程。

1.6 阶段六（2020–2026）：clig.dev 集大成与智能体时代

2020 年 12 月，由 Aanand Prasad、Ben Firshman（Docker Compose 共同作者）、Carl Tashian、Eva Parish 撰写的 Command Line Interface Guidelines（clig.dev） 上线，被广泛视为 Unix 时代设计原则的"现代更新版"（clig.dev、InfoQ 2020 年 12 月访谈）。它在四个议题维度上都给出了可执行条款（细则展开见 §2.2、§2.4）：

• 参数解析：尽量用成熟的解析库；能用 flag 就不用裸参数；全量提供长选项；遵循 -a/--all、-n/--dry-run、--json 等标准命名；不要把密码放在 flag 里（会泄漏进 ps）；
• 输出格式化：数据进 stdout，日志与错误进 stderr；用 TTY 判断对面是人还是程序；为机器消费提供 --json 与 --plain；在"非 TTY、NO_COLOR 非空、TERM=dumb、--no-color"四种情况下必须关闭颜色；stdout 非 TTY 时禁止动画；
• 退出码：成功返回 0，失败返回非 0，并把非零码映射到最重要的失败模式上；
• 可组合性：引用 McIlroy 1964 年那句"每个程序的输出都会成为另一个未知程序的输入"，支持 - 代表 stdin/stdout，强调"可组合"与"人类优先"并不冲突。

2024 年是规范层面的大年：POSIX Issue 8（IEEE Std 1003.1-2024）于 2024 年 6 月发布，其中一项标志性变化是把 GNU 系的 getopt_long / getopt_long_only 连同 option 结构体与 no_argument / required_argument / optional_argument 常量一并收编进 <getopt.h>——"长选项"这一延宕三十余年的事实标准终于入法（IEEE 1003.1-2024、The Open Group Base Specifications Issue 8、Open Group POSIX.1-2024 FAQ；Issue 8 还新增了 readlink、realpath、timeout 等实用工具，见 HN 讨论）。同年 11 月，Anthropic 发布 Model Context Protocol（MCP），为工具调用提供结构化接口（anthropic.com/news/model-context-protocol）。

2025 年以来，编码智能体（Claude Code、Codex CLI、Gemini CLI 等，均为模型既有知识、未逐项检索验证）让"机器调用 CLI"的规模空前放大，这反过来重塑四个议题的优先级：退出码从"提示人类"变为"agent 的控制流信号"；--json 与幂等、非交互从加分项变为 agent 兼容性硬指标。横轴章节还检索到面向 Agent 的 CLI 规范开始成文——CLI Agent Spec 与 AOI-CLI（Machine Mode）（machinemode.io/compare，详见 §2.2、§2.5）。而"人类可读输出优先"的原则并未被推翻——clig.dev 式双轨设计（TTY 时取悦人，管道时取悦机器）成为最稳妥的答案。

驱动因素：LLM 智能体成为 CLI 的新"用户群体"，无 GUI、无交互、依赖退出码与结构化输出；POSIX 组织（Austin Group）持续运维标准，把三十年间工业界自发形成的约定回灌进正式规范。

1.7 四条议题的演化曲线（纵轴小结）

2. 横轴：横向对比（2026-11-05 时点）

2.1 总览：三个层次的竞品地图

2.2 规范层正面对决：POSIX vs GNU vs 12 Factor vs CLIG vs Agent 规范

依据 machinemode.io/compare 与各规范原文。两份 agent 规范的原始出处（2026-11-05 已核对原文，下表相应细节均与原文相符）：CLI Agent Spec v1.16 原文见 cli-agent-spec.github.io（仓库 github.com/cli-agent-spec/cli-agent-spec）；AOI-CLI v1.0-alpha（Machine Mode 标准的 CLI profile）原文见 machinemode.io/spec（组织 github.com/agentoperable）。唯一例外是下表 AOI-CLI 行的合规工具 aoi-probe——该工具仅见于对比页、未出现在规范原文中，其余细节（15 具名码、retryable/side_effects、JSON 信封、--format jsonl、167 条要求、sysexits 兼容、JSONL 事件流、aoi-lint）均已对上原文：

该对比页面的结论值得直接引用：面向人的指南（CLIG、12 Factor）与面向 Agent 的规范不冲突——默认输出遵循前者，机器模式叠加后者。另一处值得强调的共识是流分流：CLIG 与 12 Factor CLI 在"主数据走 stdout、消息与错误走 stderr"上完全一致，且默认不要给 stderr 加 ERR:/WARN: 日志级别标签（verbose 模式除外），来源：clig.dev、12 Factor CLI Apps、galligan 的 Console vs. Logger 摘录。

2.3 参数解析：POSIX/GNU 基线与九个实现

基线：POSIX.1-2017 第 12 章定义 12 条 Utility Syntax Guidelines——短选项以 - 前缀、操作数（operand）与选项区分、-abc 可组合、-o arg 与 -oarg 两种传参方式、-- 终结选项；--name=val 形式的长选项在该章 rationale 中出现（正式条目仅规定以 -- 开头避免冲突）；最关键的 Guideline 12 要求选项与操作数的相对顺序不影响功能。来源：POSIX.1-2017 Chapter 12；最新版标准已推进到 IEEE 1003.1-2024。

GNU 对 POSIX 的"加法"：GNU Coding Standards 在 POSIX 之上做了三件关键加法——必须用 getopt_long 为每个短选项提供等价长选项；长选项命名跨程序统一（"任何 GNU 程序中 verbose 选项必须拼写为 --verbose"）；每个程序必须支持 --version 与 --help，且普通参数只作输入文件、输出文件应走 -o/--output。GNU 的 getopt 还"通常允许选项出现在任意位置"，比 POSIX 更宽松。来源：GNU Coding Standards — Command-Line Interfaces。

解析库对比表（维护状态为检索时点快照）：

逐项判断：

• 能力维度：声明式（docopt、clap derive）把"帮助文本 = 解析规格"做到极致，理论上消灭了帮助与行为漂移；框架式（cobra）强项是子命令树、自动帮助与文档生成——kubectl 团队在 cobra.dev 证词中称其 "game-changer"；程序式（click、commander）灵活但样板多。类型校验上 clap（Rust 类型系统）与 typer（Python 注解）最强，POSIX 原语最弱。
• 成本维度：docopt 学习成本最低但迁移成本最高（生态停更，新 Python 版本兼容性被 issue #519 点名）；clap 的成本是二进制体积（sunshowers.io 明确列出）；argparse 零依赖但样板代码多。
• 生态与成熟度：语言生态已出现"事实标准收敛"——Go 收敛到 cobra、Rust 收敛到 clap、Node 收敛到 commander，Python 则是 argparse（标准库）与 click/typer 双主流并存。clig.dev 的解析建议正是"尽量用解析库"，因为它能顺带处理帮助文本与拼写建议（来源：clig.dev）。
• 分化点：docopt 的衰落说明"声明式理想"输给了"生态维护"——理念被 clap/typer 继承，实现被活跃度淘汰。

2.4 输出格式化：双轨制的细则与三种机器通道

无争议的底座是流分流（见 §2.2）。在此基础上必须厘清一个容易混淆的点：TTY 检测管的是"颜色与花哨格式"，不管"自动切 JSON"。Prisma CLI 的输出规范文档指出一个事实——没有任何主流 CLI（gh/aws/kubectl）会在"被管道时"自动切换成 JSON；人类面向的部署输出应走 stderr，--json 才是 stdout 上的机器通道（来源：Prisma CLI Output Conventions；"CLI 的第二个用户是 Agent"的论述见 jedarden.com）。

机器可读输出的三种实现路径：

CLIG 的双轨细则：人类可读优先，靠 TTY 检测猜测读者是谁；输出要保证 | grep 行为符合直觉；花式格式会破坏按行解析时提供 --plain（每行一条记录）；传 --json 时输出格式化 JSON 以接入 jq；禁色条件四条——非 TTY、NO_COLOR 非空、TERM=dumb、--no-color。来源：clig.dev。NO_COLOR 本身是 2017 年发起的非正式标准，精确触发条件是"该环境变量存在且非空串时（无论取值），阻止添加 ANSI 颜色"，来源：no-color.org。

2025 年后的新竞品维度：为 Agent 输出：

• AOI-CLI（Machine Mode）：每次运行输出 JSONL 事件流——aoi:meta 开头、类型化事件居中、aoi:summary 收尾；适合长任务可观测。来源：AOI-CLI v1.0-alpha 规范原文（对比表见 machinemode.io/compare）。
• CLI Agent Spec：每条命令输出单个 JSON 信封 {ok, data, error, warnings, meta}，流式为可选项（--format jsonl，REQ-O-004）；对已输出单份 JSON 的工具改造成本最低。来源：CLI Agent Spec v1.16 规范原文。
• 反调：HN 讨论中有人主张小数据量下自然语言纯文本对 LLM 反而优于 JSON，表格格式会干扰模型。来源：HN #48052333、Rethinking CLI interfaces for AI。

小结：输出格式的竞品格局已从"文本 vs JSON"二元，演化为"人类双轨（TTY 检测 + --plain）+ 机器单轨（--json）+ agent 三轨（信封或事件流）"的三层结构。

需要点破一个看似冲突之处：agent 的 JSONL 事件流属于显式机器通道（由 --format jsonl/--stream 这类旗标开启，见上文 CLI Agent Spec 的 REQ-O-004），与上文"被管道时不自动切 JSON"（Prisma 归纳的 gh/aws/kubectl 现状）并不矛盾——前者是调用方显式要求，后者只是禁止按 TTY 状态隐式切换输出格式。因此 TTY 双轨与 agent 流式输出可以共存于同一工具：TTY 上取悦人、被管道时输出纯文本、被 agent 以显式旗标调用时输出 JSON 信封或事件流。

2.5 退出码：四要素中标准化程度最低的一环

调和说明：表中"仅 0 被标准严格定义"说的是工具自身的退出语义——这是标准对工具作者的唯一定义；而 126/127/>128 是 POSIX shell（XCU 2.8.2）对命令查找失败与信号终止的规定（见 §1.4），属于 shell 层保留值，不是工具自定义的空间。两句话并不矛盾；本文 TL;DR 与 §3.1 统一采用"除 shell 保留值外仅 0 被标准定义"的措辞。

逐项判断：

• 成熟度：POSIX 只把 0 锁死；sysexits 从 BSD 邮件工具时代（sendmail）沿用至今，是"分类错误码"的唯一定型先例；126/127/128+N 是 shell 的强约定，脚本作者无法逾越。
• 成本：CLIG 明确选择"不扩编数字"——因为它观察到数字分类在实践中难维护；agent 规范则反其道而行，认为机器（Agent）消费退出码时数字分类+标志位才有用。这是人类用户与机器用户在同一维度上的直接分歧。
• 适用场景：普通工具遵循"0/1/2 + 文档化"即可；面向 Agent 的工具可考虑 sysexits 或直接采纳 CLI Agent Spec 的 15 码体系；AOI-CLI 把 130（SIGINT）、141（SIGPIPE）这类进程级信号保留在退出码层、不进 payload 的设计，对管道工具更友好。

2.6 可组合性：文本管道、对象管道、结构化管道与 MCP

逐项判断：

• 能力：文本管道的组合性来自"最小公共接口"（一行文本），代价是每个衔接点都要一次脆弱解析——这正是 PowerShell 与 Nushell 立项的动机；Nushell 官方博客明确定位为"经典 Unix 管道哲学 + PowerShell 的结构化数据 + 函数式编程"的合体（Nushell 博客、Atomic Object）。
• 成本：PowerShell 最重（完整 .NET 运行时），Nushell 是 Rust 单二进制但语法自成一家；jq 学习曲线陡但生态回报高。
• 生态：PowerShell 在 Windows/企业自动化中扎根；Nushell 未到 1.0，仍属"早期采用者"工具。
• 对本课题的启示：本课题的"可组合性"设计原则（stdout 纯数据、--json、每行一记录的 --plain）本质上是在不改变管道范式的前提下为文本管道打结构化补丁；PowerShell/Nushell 则是推翻范式重做。两条路线并存且互不兼容——这是横向对比中最大的"范式分化"。
• MCP 的位置：MCP 与 CLI 的关系需要分范围表述（详见 §3.5 校准 3）：在"机器如何调用工具"这一狭窄通道上是替代竞争，在整体工程版图上互补共存。

2.7 横轴小结：三条收敛、两条分化

收敛：

1. 语法收敛到 POSIX+GNU。无论 cobra 的 pflag、click 还是 clap，实现的都是"POSIX 短选项 + GNU 长选项"的并集；GNU 的 --help/--version 强制已被 CLIG 吸收为通用约定。
2. --json 成为机器可读的事实标准，但实现粒度三派不同：gh 的字段白名单、kubectl 的格式+查询分离、AWS 的多级格式菜单。
3. stdout/stderr 分流零争议，所有规范（POSIX 时代到 agent 规范）完全一致。

分化：

1. 管道数据模型三派并存：文本字节流（Unix）、内存对象（PowerShell）、类型化结构流（Nushell）互不兼容，且没有一派胜出——CLI 设计者只能"在文本管道内打结构化补丁"。
2. 退出码是四要素中最欠标准化的一环，而 agent 规范正在此维度反向加码（15 具名码、retryable 标志），2025 年后新出现的 envelope（JSON 信封）vs stream（JSONL 事件流）之争尚未收敛。

最大外部冲击：AI Agent 成为 CLI 的"第二用户"，把 1970 年代为人类设计的四要素逐一推向双轨制——这是本课题在 2026-11-05 时点上最重要的横向格局变化。

3. 交叉洞察：两轴结合说明了什么

3.1 四要素停在不同的标准化台阶上

纵轴揭示了一条规律：每个议题都走过"个人习惯 → 公共基础设施（getopt、管道）→ 正式标准（POSIX）→ 框架与指南"四级台阶。把横轴的 2026 年快照对上去，会发现四要素恰好停在不同的台阶上：参数解析站在"框架+标准"双台阶上，收敛基本完成（2024 年 getopt_long 入法是收官动作）；输出格式化停在"指南+事实标准"台阶，双轨成形但信封/事件流未定；退出码仍停在"习惯+shell 强约定"台阶，除 shell 保留值外仅 0 被标准定义；可组合性则停在"范式分歧"，三条管道路线并存。

台阶高低与"读者是谁"强相关：读者越单一，标准化越彻底——解析器的读者最终是程序自己，所以最快收敛；退出码同时被 shell、人类、agent 三方读取，语义最难统一。这解释了为什么四要素的标准化程度呈阶梯状分布，而不是齐头并进。

3.2 收敛的都是语法，分化的都是语义

把横轴"三条收敛、两条分化"再抽象一层：收敛的三条（POSIX+GNU 语法并集、--json 事实标准、流分流）都是形式层；分化的两条（管道数据模型、退出码语义）都是含义层。形式收敛因为有网络效应——一次学习处处可用，框架也乐于复用同一套心智模型；语义分化因为它绑定具体场景——shell 的 126/127 是 shell 的场景，sysexits 是邮件的场景，15 具名码是 agent 重试的场景。

给设计者的推论：不要指望"退出码大战"会出现一个赢家。正确姿势是遵守共同底线（0/非 0、避开 126/127 及 128 以上的 shell 保留区间——POSIX 只要求"大于 128"，bash 按 128+N 映射致命信号，见 §1.4 与 §2.5），再在文档里定义自己的语义——CLIG"不规定数字、映射最重要失败模式"的克制正是因为看到了这一点。

3.3 六十年三次"人机再平衡"

纵轴的三段式与横轴的规范对决互为印证，合起来是三次"人机再平衡"：

1. 第一次（1964–1992）：为机器立约。POSIX 用语法准则与退出码把接口交给机器判读，人靠记忆适应机器。
2. 第二次（1983–2020）：为人补偿。GNU 的长选项与 --help、clig.dev 的颜色与人类可读输出，让机器（解析器、TTY 检测）反过来适应人。
3. 第三次（2024 起）：为机器第二次立约。Agent 规范要求非交互、--json、稳定 schema、可重试退出码——但这次用的是"叠加"而非"推翻"：machinemode 对比页的结论是默认输出遵循 CLIG、机器模式叠加 agent 规范。

每一次再平衡都留下沉淀：长选项、--help/--version、NO_COLOR、--json。AI 没有推翻任何一层，这正是 clig.dev 双轨设计（TTY 时取悦人、管道时取悦机器）被证明稳健的原因——它天生就是为"两种读者"设计的。

3.4 两场"克制 vs 膨胀"之争的重演

1986 年的 "cat -v considered harmful" 与 2025 年的"JSON vs 自然语言"之辩（HN #48052333、Rethinking CLI interfaces for AI）是同一辩论的两次重演：接口该为调用方塞多少信息。第一次的结论——克制、单一职责——由 clig.dev 继承成文；第二次还没有结论：小数据量下自然语言对 LLM 可能优于 JSON，表格反而干扰模型。

这提示 agent 时代的输出设计不要押注单一格式：横轴 §2.4 的小结——人类双轨（TTY 检测 + --plain）+ 机器单轨（--json）+ 可选 agent 三轨（信封或事件流）的三层结构——是当前风险最小的落点。

3.5 两轴分歧的校准记录

综合过程中发现并消除了两章之间的五处不一致，处置如下：

1. NO_COLOR 的触发条件：纵轴写"无论值为何"，横轴写"存在且非空串"。采用 no-color.org 原文的精确定义：环境变量存在且非空字符串时（无论取值）必须禁色（no-color.org）。本报告全文按此表述。
2. POSIX Utility Syntax Guidelines 条数：纵轴小节标题作"14 条语法准则"，横轴与 POSIX.1-2017 第 12 章原文均为 12 条。采纳 12 条，纵轴标题系笔误。
3. MCP 与 CLI 的关系：横轴范式表称"替代而非叠加"，纵轴称"互补而非替代"。校准为分范围表述：在"机器如何调用工具"这一狭窄通道上，MCP 与 CLI 争夺同一类调用、构成替代竞争；在整体工程版图上互补共存——MCP 管工具发现与类型化调用，CLI 管执行与人类交互，且 xpander 的分析指出 CLI 在 token 效率上仍占优。两种说法各自在限定范围内成立，不存在绝对对错；本报告统一采用限定表述。
4. Utility Conventions 的年代：横轴总览表记"1988 起（随 POSIX）"，纵轴以 IEEE Std 1003.2-1992 为成文节点。本报告统一以 1992 年 POSIX.2-1992 为"法定化节点"表述，1980 年代仅指 POSIX 系列标准开始酝酿的时期。
5. 12 Factor CLI 的退出码 0/1/2：纵轴把 0/1/2 明确归到 12 Factor CLI Apps 名下（其原文如此），横轴退出码表未收录该体系。两者并不矛盾：12 Factor 是"建议的简化约定"，CLIG 是"不规定数字的指南"，本报告两处均保留并注明出处。

3.6 对用户的判断与建议

选型矩阵（检索时点 2026-11-05）：

Agent 友好设计的共性建议（非交互、结构化输出、--dry-run、可预测退出码）来源：Speakeasy、linkly.ai。

九条检查清单：

1. 参数解析用成熟解析库，不手写 argv 循环（clig.dev；库顺带解决帮助文本与拼写建议）；
2. 全量提供长选项，命名随大流（--verbose、--all、--dry-run、--json），--help/--version 不可缺席（GNU Coding Standards、CLIG）；
3. 数据进 stdout，日志与错误进 stderr；stderr 默认不加日志级别标签（12 Factor CLI）；
4. 颜色与动画按四条件禁用：非 TTY、NO_COLOR 非空、TERM=dumb、--no-color；不要在被管道时自动切 JSON——机器通道永远是显式 --json（Prisma 输出规范）；
5. 机器输出提供字段级白名单或 --plain，避免输出过肥与破坏按行解析（gh 的做法）；
6. 退出码守住底线：0 成功、非 0 失败、用法错误 2、避开 126/127 及 128 以上的 shell 保留区（bash 的 128+N 约定），语义写进文档（POSIX、12 Factor CLI、CLIG）。何时才在 0/1/2 之上引入更多分类码：仅当工具主要被程序化调用、且调用方确有失败分类需求（如需要区分"可重试/不可重试"）时——此时才引入 sysexits 或 agent 规范的具名码并写进文档；人用为主的工具停在 0/1/2 即可。12 Factor 的 0/1/2、CLIG 的"不规定数字"与 sysexits/15 具名码三套建议并不冲突：它们面向的调用方不同（人、通用脚本、机器编排）；
7. 面向 agent 补齐：非交互（不依赖 TTY 提问）、幂等、--dry-run、稳定 schema、可预测退出码（Speakeasy）；
8. 密码与敏感信息不进 flag（会泄漏进 ps），走环境变量或配置（clig.dev）；
9. 不押注单一管道范式：文本管道仍是通用语，结构化输出是增值方言；PowerShell/Nushell 路线按团队生态选，不必整体迁移（§2.6）。

三条风险提示：

• 生态风险重于理念风险：docopt 的"文档即规格"理念被 clap/typer 继承，但实现因弃养被淘汰（Python 版停于 2014、仓库 2018 年后无更新，issue #519）——选库先看维护状态再看范式；
• 能力有价：clap 的类型校验与 derive 人体工学以二进制体积为代价（sunshowers.io）；PowerShell 的零解析以完整 .NET 运行时为代价；Nushell 未到 1.0（检索时最新 0.116.1），生产关键路径慎用；
• agent 规范尚在春秋：CLI Agent Spec（JSON 信封）与 AOI-CLI（JSONL 事件流）的 envelope vs stream 之争未收敛，合规套件（167 条要求、aoi-lint）各自绑定阵营；2026 年时点建议以 --json + 文档化退出码为最大公约数，观望后再叠加。观望的判定信号：两份 agent 规范（CLI Agent Spec / AOI-CLI）任一发布 1.0、或获得头部 CLI（gh/kubectl 级别的项目）采用——届时再按其阵营叠加信封或事件流。

4. 参考来源

以下为两章参考来源合并去重后的清单，按主题分组；正文中均已就地引用。

发展史与管道起源

• https://toroid.org/unix-pipe-implementation
• https://wiki.tuhs.org/doku.php?id=features:pipes
• https://en.wikipedia.org/wiki/Pipeline_(Unix)
• https://en.wikipedia.org/wiki/Unix_philosophy
• https://harmful.cat-v.org/cat-v/
• https://en.wikipedia.org/wiki/ANSI_escape_code
• Thompson shell（1971，首个 Unix shell）：https://en.wikipedia.org/wiki/Thompson_shell
• Linux kernel（1991）：https://en.wikipedia.org/wiki/Linux_kernel

标准与规范

• POSIX.1-2017 第 12 章 Utility Conventions：https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
• POSIX.1-2024 XCU 2.8.2 Exit Status：https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html
• X/Open Commands and Utilities Issue 4：https://pubs.opengroup.org/onlinepubs/9695969399/toc.pdf
• IEEE 1003.1-2024（Issue 8）：https://standards.ieee.org/ieee/1003.1/7700
• The Open Group Base Specifications Issue 8：https://pubs.opengroup.org/onlinepubs/9799919799
• Open Group POSIX.1-2024 FAQ：https://www.opengroup.org/austin/papers/posix_faq.html
• GNU Coding Standards — Command-Line Interfaces：https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html
• Command Line Interface Guidelines：https://clig.dev ；InfoQ 访谈：https://www.infoq.com/news/2020/12/cli-guidelines-qa
• Heroku CLI Style Guide：https://devcenter.heroku.com/articles/cli-style-guide
• 12 Factor CLI Apps：https://jdx.dev/posts/2018-10-08-12-factor-cli-apps ；https://jdxcode.medium.com/12-factor-cli-apps-dd3c227a0e46
• NO_COLOR：https://no-color.org
• POSIX.1-2001/SUSv3 合并沿革（Linux man-pages standards(7)）：https://man7.org/linux/man-pages/man7/standards.7.html
• GNU 计划与 1983 年公告（FSF: About GNU）：https://www.gnu.org/gnu/gnu.en.html
• CLI standards for AI agents, compared：https://www.machinemode.io/compare
• CLI Agent Spec v1.16 原文：https://cli-agent-spec.github.io ；仓库：https://github.com/cli-agent-spec/cli-agent-spec
• AOI-CLI v1.0-alpha（Machine Mode）原文：https://www.machinemode.io/spec ；组织：https://github.com/agentoperable

解析库与工具

• System III getopt(1) 手册页：https://www.typewritten.org/Manual/Bell/UNIX/SystemIII/man1/getopt.html
• https://en.wikipedia.org/wiki/Getopt ；https://en.wikipedia.org/wiki/Getopts
• PEP 389：https://peps.python.org/pep-0389
• commander.js：https://github.com/tj/commander.js
• docopt：https://pypi.org/project/docopt/ ；弃养状态：https://github.com/docopt/docopt/issues/519 ；https://pypi.org/project/types-docopt
• Cobra：https://cobra.dev ；https://github.com/spf13/cobra ；https://pkg.go.dev/github.com/spf13/cobra
• Click：https://click.palletsprojects.com/en/stable/why
• clap：https://crates.io/crates/clap ；https://docs.rs/clap ；选型代价：https://rust-cli-recommendations.sunshowers.io/cli-parser.html
• jq：https://jqlang.github.io/jq/

退出码

• sysexits.h(3head)：https://man7.org/linux/man-pages/man3/sysexits.h.3head.html ；OpenBSD 源码：https://github.com/openbsd/src/blob/master/include/sysexits.h ；Mac OS X 手册页：https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/sysexits.3.html
• 退出码汇编：https://staticdata.dev/datasets/exit-codes ；https://www.ditig.com/linux-exit-status-codes
• 126/127/128+N 约定：https://unix.stackexchange.com/questions/504663/what-is-linux-exit-status-and-list-of-all-status ；https://brandur.org/exit-status

输出与机器可读格式

• GitHub CLI：https://cli.github.com/manual/gh_help_formatting ；https://github.blog/engineering/principles/scripting-with-github-cli
• kubectl：https://kubernetes.io/docs/concepts/overview/kubectl
• AWS CLI：https://docs.aws.amazon.com/cli/v1/userguide/cli-usage-output.html ；https://aws.amazon.com/blogs/developer/announcing-new-output-formats-in-aws-cli-v2
• Prisma CLI 输出规范：https://github.com/prisma/prisma-cli/blob/main/docs/product/output-conventions.md
• https://jedarden.com/notes/cli-design-for-humans-and-agents
• galligan 摘录：https://gist.github.com/galligan/8caddedbdbd830c9731de03eb177e4fd

可组合性与 shell 范式

• Nushell：https://www.nushell.sh/blog/2019-08-23-introducing-nushell.html ；https://spin.atomicobject.com/nushell-treats-everything-as-data ；https://github.com/nushell/nushell
• PowerShell：https://github.com/PowerShell/PowerShell ；https://en.wikipedia.org/wiki/PowerShell ；https://stackshare.io/stackups/nu-shell-vs-powershell
• 文本管道解析脆弱性讨论：https://unix.stackexchange.com/questions/399/unix-equivalent-of-powershell
• CircleCI CLI（内置 --jq）：https://circleci.com/docs/guides/toolkit/circleci-cli

AI Agent 与 CLI

• Model Context Protocol：https://www.anthropic.com/news/model-context-protocol
• MCP vs CLI：https://xpander.ai/resources/mcp-vs-cli-for-ai-agents
• Agent-friendly CLI：https://www.speakeasy.com/blog/engineering-agent-friendly-cli ；https://linkly.ai/blog/cli-best-interface-for-ai-agents
• 反调与讨论：https://www.notcheckmark.com/2025/07/rethinking-cli-interfaces-for-ai ；https://news.ycombinator.com/item?id=48052333
• POSIX Issue 8 讨论：https://news.ycombinator.com/item?id=40679809

未单独检索验证、出自模型既有知识的断言（承自纵轴章节的原始标注，综合时保留）：stderr 与 stdout 分离的精确版本节点；Bourne shell 0=成功 约定的传播；"cat -v considered harmful" 事件年份（1986）；PowerShell 1.0 发布年份（2006）；《The Art of UNIX Programming》出版年份（2003）；getopt_long 入库的确切年份；Claude Code、Codex CLI、Gemini CLI 等编码智能体的具体名录。其余事实均以上列来源为准，版本号与维护状态为 2026-11-05 检索快照。