unix-cli

UNIX/POSIX 标准 CLI 最佳实践

为遵循 UNIX 约定的命令行工具提供的全面指南，专为 AI Agent 和大模型设计。包含 8 个类别中的 44 条规则，按影响程度排序，从关键项（参数处理、退出码、输出流）到渐进改进项（配置和环境）。

适用场景

在以下情况下参考这些指南：

• 使用任何语言编写新的 CLI 工具
• 解析命令行参数和标志
• 决定哪些内容输出到 stdout，哪些内容输出到 stderr
• 选择合适的退出码
• 处理 SIGINT 和 SIGTERM 等信号

按优先级划分的规则类别

优先级	类别	影响	前缀
1	参数和标志设计	CRITICAL	args-
2	退出码	CRITICAL	exit-
3	输出流	CRITICAL	output-
4	错误处理	HIGH	error-
5	I/O 和组合	HIGH	io-
6	帮助和文档	MEDIUM-HIGH	help-
7	信号和稳健性	MEDIUM	signal-
8	配置和环境	MEDIUM	config-

快速参考

1. 参数和标志设计（CRITICAL）

• args-use-getopt - 使用标准参数解析库
• args-provide-long-options - 为所有短选项提供长选项
• args-support-double-dash - 支持使用双连字符终止选项
• args-require-help-version - 实现 --help 和 --version 选项
• args-prefer-flags-over-positional - 优先使用标志，而非位置参数
• args-use-standard-flag-names - 使用标准标志名称
• args-never-read-secrets-from-flags - 切勿从命令行标志读取机密
• args-support-option-bundling - 支持选项组合

2. 退出码（CRITICAL）

• exit-zero-for-success - 仅在成功时返回零
• exit-use-standard-codes - 使用标准退出码
• exit-signal-codes - 信号终止时使用 128+N
• exit-partial-success - 以一致的方式处理部分成功
• exit-distinguish-error-types - 使用不同的退出码区分错误类型

3. 输出流（CRITICAL）

• output-stdout-for-data - 仅将数据写入 stdout
• output-stderr-for-errors - 将错误和诊断信息写入 stderr
• output-detect-tty - 检测 TTY，以提供面向人的输出
• output-provide-machine-format - 提供机器可读的输出格式
• output-line-based-text - 文本流使用基于行的输出
• output-respect-no-color - 遵循 NO_COLOR 环境变量

4. 错误处理（HIGH）

• error-include-program-name - 在错误消息中包含程序名称
• error-actionable-messages - 让错误消息具有可操作性
• error-use-strerror - 系统错误使用 strerror
• error-avoid-stack-traces - 面向用户的错误中避免显示堆栈跟踪
• error-validate-early - 尽早验证输入并快速失败

5. 输入/输出与组合（高）

• io-support-stdin - 支持从标准输入读取
• io-write-to-stdout - 默认将输出写入标准输出
• io-be-stateless - 设计无状态操作
• io-handle-binary-safely - 安全处理二进制数据
• io-atomic-writes - 使用原子文件写入
• io-handle-multiple-files - 以一致的方式处理多个输入文件

6. 帮助与文档（中高）

• help-show-usage-on-error - 参数错误时显示简要用法
• help-structure-help-output - 以一致的方式组织帮助输出
• help-show-defaults - 在帮助中显示默认值
• help-include-examples - 在帮助中包含实用示例
• help-version-format - 正确格式化版本输出

7. 信号与稳健性（中）

• signal-handle-sigint - 妥善处理 SIGINT
• signal-handle-sigterm - 处理 SIGTERM，以便干净地关闭
• signal-handle-sigpipe - 处理 SIGPIPE，以应对管道断开
• signal-cleanup-on-second-interrupt - 第二次中断时跳过清理

8. 配置与环境（中）

• config-follow-xdg - 遵循 XDG 基本目录规范
• config-precedence-order - 按正确的优先级顺序应用配置
• config-env-naming - 统一环境变量命名
• config-never-store-secrets - 切勿在配置文件或环境中存储密钥
• config-respect-standard-vars - 遵循标准环境变量

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息