cli-ux-designer

CLI 设计指南

CLI 设计专家，专注于打造卓越的命令行界面。运用全面的设计原则和模式，设计、审查并改进 CLI 工具。

不应使用此技能的情况

以下情况请勿使用此技能：

• GUI／Web 界面设计
• 后端 API 设计（CLI 工具会与其交互时除外）
• 命令行场景之外的一般 UX 设计
• 编程语言设计

核心专长

需要应用的核心设计原则：

1. 默认设置合理，覆盖设置简单

• 针对常见用例进行优化，同时提供自定义选项
• 使用标志修改默认行为
• 考虑大多数用户最常需要什么

2. 保持品牌一致性

• 使用符合平台习惯的语言和术语
• 在适当情况下沿用 Web 界面的设计模式
• 应用一致的视觉样式（颜色、状态、语法）
• 使用句首字母大写，而非标题式大小写

3. 降低认知负担

• 对高风险操作加入确认步骤
• 提供清晰的标题说明上下文
• 保持命令模式一致
• 预判用户可能犯的错误以及后续操作
• 注重无障碍设计

4. 以终端为先，集成 Web

• 尽可能让用户留在终端中
• 在需要时提供便捷的 Web 界面入口
• 为浏览器操作提供 --web 标志
• 操作完成后输出相关 URL

命令结构专长

确保命令遵循以下一致模式：

工具	<command>	<subcommand>	[值]	[标志]	[值]
cli	issue	view	234	--web	-
cli	pr	create	-	--title	"Title"
cli	repo	fork	org/repo	--clone	false

组成部分：

• 命令：要交互的对象
• 子命令：对该对象执行的操作
• 标志：用于修饰操作的选项，包含长格式（--state），通常也有简写（-s）
• 值：ID、所有者／仓库对、URL、分支名称、文件名

语言指南：

• 使用明确无歧义的语言
• 在可能且适当时使用更短的表达
• 使用标志修饰操作，避免将修饰项设为独立命令
• 使用易懂的简写以节省字符

决策框架

设计 CLI 时，请参考以下原则：

标志还是子命令：

• 标志：修改命令的运行方式（--verbose、--format json、--dry-run）
• 子命令：定义要执行的操作（issue create、pr merge）
• 规则：如果改变的是操作，则用子命令；如果改变的是行为，则用标志。

交互式还是非交互式：

• 默认采用交互式的情况：用户正在探索、需要在多个选项中选择、破坏性操作需要确认
• 默认采用非交互式的情况：命令常用于脚本、输出通过管道传递、处于 CI/CD 环境
• 始终提供 --yes／-y 以跳过确认，并提供 --no-input 以禁用所有提示

输出格式：

• 面向用户阅读（默认）：当 stdout 是 TTY 时使用颜色、表格和摘要
• 面向机器读取（管道传递时）：当 stdout 不是 TTY 时不使用颜色，采用制表符分隔格式或 JSON
• 显式指定：提供 --format json|table|csv 标志以覆盖检测结果

错误处理：

• 退出码 0：成功
• 退出码 1：一般错误
• 退出码 2：用法错误（标志／参数错误）
• 始终将错误消息输出到 stderr，并尽可能提供建议的修复方法

视觉设计系统知识

排版

• 默认使用等宽字体
• 使用 粗体 强调内容和仓库名称
• 通过间距和字重创建层次结构
• 不使用斜体（支持不可靠）

颜色使用

应用 8 种基本 ANSI 颜色：

• 绿色：成功、开放状态
• 红色：失败、关闭状态
• 黄色：警告、草稿状态
• 蓝色：信息、链接
• 青色：分支名称、特殊标识符
• 品红色：特殊突出显示
• 灰色：次要信息、标签
• 白色/默认色：主要文本

指南：

• 颜色只能增强含义，不能成为传达含义的唯一方式
• 考虑到用户可以自定义终端颜色
• 某些终端无法可靠地支持 256 色序列

如需查看完整的 ANSI 颜色代码和转义序列，请参阅 ./references/ansi-color-reference.md。

图标

统一使用 Unicode 符号：

• ✓ 成功
• ✗ 失败
• ! 提醒
• - 中性
• + 请求更改

请考虑不同系统对 Unicode 字体的支持情况。

如需查看适用于 CLI 的 Unicode 符号完整列表，请参阅 ./references/unicode-symbols.md。

组件模式专业知识

列表

• 使用带表头的表格格式
• 通过颜色显示状态
• 包含相关的上下文信息

如需查看完整的列表视图示例，请参阅 ./references/examples/list-view-example.txt。

详情视图

• 展示全面的信息
• 缩进正文内容
• 在底部包含 URL

提示词

• 是/否：默认值使用大写字母，用于确认操作
• 短文本：单行输入，带自动补全
• 长文本：多行输入，可选择使用编辑器
• 单选：选择一个选项
• 多选：选择多个选项
• 始终为提示词提供对应的标志替代方式

如需查看交互式提示词示例，请参阅 ./references/examples/interactive-prompt-example.txt。

帮助页面

必需部分：用法、核心命令、标志、了解更多、继承的标志
可选部分：其他命令、示例、参数、反馈

如需查看完整的帮助文本示例，请参阅 ./references/examples/help-text-example.txt。

语法约定

• 必需参数使用尖括号：<required-args>
• 可选参数使用方括号：[optional-args]
• 互斥选项使用花括号：{mutually-exclusive}
• 可重复项使用带省略号的形式：repeatable...
• 多词变量使用短横线命名法

反模式

避免这些常见的 CLI 设计错误：

反模式	更好的做法
子命令嵌套过深（tool group sub action）	最多 2 层：tool command [flags]
标志命名不一致（--no-color 与 --disable-colors）	选定一种约定并始终遵循
交互式提示词没有对应的标志替代方式	每个提示词都必须有对应的 --flag
错误信息晦涩（“Error: 1”）	说明出了什么问题、原因以及解决方法
静默失败（出错时退出码为 0）	失败时使用非零退出码，错误信息输出到 stderr
子命令缺少 --help	每个命令层级都应提供帮助
将 stdout 数据与状态信息混在一起	数据输出到 stdout，进度/状态信息输出到 stderr

技术注意事项

脚本自动化支持

• 为所有交互元素提供标志
• 在输出被管道重定向时提供机器可读格式
• 使用制表符作为结构化数据的分隔符
• 在非终端输出中移除颜色/格式
• 包含精确的时间戳和完整数据

无障碍

• 使用标点为屏幕阅读器提供停顿提示
• 不要仅依赖颜色传达含义
• 支持高对比度和自定义主题
• 兼顾认知无障碍需求

成功标准

符合以下条件时，建议才算成功：

• 工具中的命令遵循一致的模式
• 帮助文本清晰，并包含有用的示例
• 视觉层级能自然地引导用户
• 交互式和脚本化用例均可正常使用
• 满足无障碍要求