cli-help-layers

CLI Help Layers：帮助信息分层设计指南

为 AI-First CLI 的命令行交互与文档体系提供设计指引。核心读者：人类开发者 + LLM/Agent。

三条设计理念

1. 渐进式披露：usage → help → man，信息密度逐层递增，agent 多数场景只需前两层
2. 示例即规范：借鉴 tldr，每层文档以可执行示例为锚点
3. 结构化优先：固定分隔符与格式约定，便于 LLM 零样本抽取

四层信息架构

触发方式	层级	覆盖率	内容
命令不带参数	@USAGE	80%	BRIEF + SYNTAX + 3-5 EXAMPLES
-h / --help	@HELP	95%	OPTIONS 表 + ENUMS + COMMON ERRORS
子命令 --help	@HELP sub	98%	特有选项 + INHERITED OPTIONS + TEMPLATE
--man	@MAN	100%	SCHEMA + EXIT CODES + ALL ERRORS + CAVEATS

结构化标记

@USAGE <path>  / @HELP <path>  / @MAN <path>   → 层级标识
BRIEF: / SYNTAX: / OPTIONS: / ENUMS: / EXAMPLES: / ERRORS:  → 区块标签
# [RECOMMENDED] / [TEMPLATE] / [PIPELINE] / [ADVANCED]      → 示例标签

Agent 定位正则：^@(USAGE|HELP|MAN)\s+(.+)$，区块：^([A-Z ]+):$

层间发现性 (Discoverability)

每层输出的最后一行必须包含指向下一层的提示，形成引导链：

当前层	尾部提示文案
@USAGE (无参数输出)	Run '<cmd> --help' for all options and error codes.
@HELP (-h/--help 输出)	Run '<cmd> --man' for full schema, exit codes, and caveats.
@MAN (--man 输出)	无（已是最完整层）

设计要点：

• 提示使用 dim/grey 样式（终端 \033[2m）或尾注格式，避免干扰主要内容
• Agent 据此判断是否需要请求更详细信息，而非盲目升级到 man 层
• 如果 CLI 不支持 --man，可替换为 See docs at <url> 或 man <cmd>

工作流

设计或审查 CLI 帮助文档时：

1. 确定命令结构 → 参考 references/architecture.md（命名规则、名词-动词组织）
2. 编写 Usage → 参考 references/usage-spec.md（模板 + 示例挑选原则）
3. 编写 Help → 参考 references/help-spec.md（OPTIONS 表 + 枚举 + Sub-command Help）
4. 编写 Man → 参考 references/man-spec.md（SCHEMA + EXIT CODES + 完整错误码）
5. 设计错误信息 → 参考 references/error-design.md（错误码编码 + 各层嵌入策略）
6. Agent 友好性优化 → 参考 references/agent-friendly.md（文案风格 + 标记系统 + 披露流程）
7. 对照检查 → 参考 references/checklist.md（五维度 checklist）
8. 参考完整示例 → 参考 references/example-feishu-doc.md（feishu doc 命令族三层完整实践）
9. 常见问题 → 参考 references/faq.md（设计理念来源、标记选择等）

适用范围

Do not use this skill for:

• CLI 工具的实际代码实现（只管文档设计）
• 非命令行的 API 文档设计
• 已有 CLI 工具的运行与调试