cli-design-framework

CLI 设计框架

概述

使用以分类为先的框架来设计和审查 CLI。

将此框架视为决策系统，而不是通用风格指南。不要假设每个 CLI 都应转向 Agent 优先、机器协议优先或原始载荷优先。

适用场景

在以下情况下使用此技能：

• 设计新的 CLI，但不确定合适的命令形式
• 审查现有 CLI，发现其帮助信息、输出或命令树不匹配
• 判断 CLI 的主要类型是 Capability、Runtime、Environment / Workspace、Workflow、Package / Build 还是 Meta
• 判断面向人的界面和机器可读界面应作为主要界面还是次要界面
• 判断会话语义是否合理，还是过度设计

以下情况下不要使用此技能：

• CLI 分类已经确定，你只需要了解实现机制
• 问题仅涉及解析器库、仓库布局或具体的标志拼写
• 任务纯粹是表面文案润色，不涉及设计决策

快速路径

• 对于快速请求，给出精简评估：用途、分类、简短理由、主要设计影响，以及仅列出可能改变结论的未决问题。
• 只有在用户明确要求，或存在足以采用更长形式的歧义或风险时，才使用完整蓝图或完整审查模板。

核心规则

先分类，再设计，最后审查。

始终按以下顺序进行：

1. 用一句话说明 CLI 的用途。
2. 对主要角色／控制界面进行分类。
3. 对主要用户类型进行分类。
4. 对主要交互形式进行分类。
5. 对有状态性进行分类。
6. 对风险特征进行分类。
7. 明确指出次要界面。
8. 推导设计影响。

使用此框架时，请从以下文件开始：

• references/taxonomy.md，了解分类体系。
• references/output-templates.md，了解所需的输出格式。

仅在需要时查阅以下文件：

• references/classification-examples.md：当类别不明确时，参考分类示例。
• examples/design-blueprint-example.md 和 examples/review-example.md：需要具体的最终形式示例时查阅。
• examples/anti-patterns.md：当设计看起来不妥，但尚未明确分类错误时查阅。

运行模式

使用以下两种模式之一：

1. 设计模式 —— 创建或完善 CLI 设计方向。
2. 审查模式 —— 根据此框架评估现有 CLI。

---

设计模式

目标

明确 CLI 的设计目标，然后制定约束实现的蓝图。

工作流

1. 推断已有的信息。

   • 从用户的请求中提取所有强信号。
   • 尽可能推断可能的角色、用户类型、交互形式、状态性、风险概况和次要界面。
   • 不要询问已被强烈暗示的信息。

2. 只询问最关键的未解决问题。

   • 询问能够实质性改变分类或蓝图的最少问题。
   • 优先询问分类问题，而非实现细节。
   • 优先顺序：用途 → 控制界面 → 主要用户 → 交互形式 → 状态性 → 副作用 → 次要界面。
   • 如果现有信息已经足够，不要提问。直接给出蓝图。

3. 明确分类 CLI。

   • 说明推断或确认的以下信息：
     • 主要角色／控制界面类型
     • 主要用户类型
     • 主要交互形式
     • 状态性
     • 风险概况
     • 次要界面
   • 推断不确定时说明置信度。
   • 明确区分主要和次要，不要混为一谈。

4. 在提出命令之前，先说明设计立场。

   • 用一段简短文字说明 CLI 的优化目标。
   • 说明 CLI 不试图成为什么。
   • 不要从分类直接跳到命令树。

5. 产出设计蓝图。

   • 使用 references/output-templates.md 中的结构。
   • 用户需要蓝图时，或歧义／风险值得采用完整模板时，使用完整模板。
   • 对于快速请求，精简为：用途、分类、分类依据、设计立场、关键设计影响，以及仅有的关键未解决问题。
   • 将分类与设计影响直接关联。
   • 蓝图要具体，避免泛泛而谈。

6. 约束后续实现。

   • 以简短的方向说明收尾，说明：
     • 应优化什么
     • 不应优化什么
     • 可接受的模式
     • 类别错误
     • v1 的范围和非目标

必要的设计准则

每份蓝图都必须遵守以下规则：

• 主要与次要界面

  • 明确指出主要界面。
  • 明确指出次要界面。
  • 说明每种界面的用途。
  • 不要在未说明 JSON、事件流、模板、原始负载或 TUI 属于主要还是次要界面的情况下，将它们称为“重要”。

• 以人为主／兼顾可发现性

  • 如果 CLI 以人为主或兼顾人与机器，必须明确说明：
    • 帮助内容的质量
    • 示例
    • 可发现性
    • 适用时的解释／描述界面
  • 不要只讨论命令结构而忽略易学性。

• 结构化机器契约

  • 如果 CLI 提供机器可读界面，必须明确说明：
    • 哪些命令提供该界面
    • 输出格式（--json、--jsonl 等）
    • 字段名称是否稳定
    • 退出码是否重要
    • 是否需要 schema／字段／describe 支持
  • 如果没有说明契约，不要称该界面“便于脚本使用”。

• 风险阶梯

  • 如果 CLI 会修改状态，至少定义：
    • 低风险操作
    • 中风险操作
    • 高风险操作
  • 说明每个级别应有的防护措施。
  • 不要只说“谨慎操作”或“添加确认”。

• 状态模型

  • 如果 CLI 有会话状态、长时间运行，或支持连接／分离，必须明确描述会话标识和生命周期。
  • 如果 CLI 基本无状态，必须明确说明，并避免凭空设计会话语义。

• v1 范围

  • 说明 v1 应包含什么。
  • 说明 v1 应推迟什么。
  • 说明哪些抽象过早。

问题策略

只询问会影响分类或蓝图的问题。

不要一开始就询问实现细节，例如：

• 语言选择
• 解析库
• 仓库布局
• 命名之争
• 具体的标志拼写

只有当这些问题会实质性影响 CLI 的分类或设计后果时，才询问。

---

评审模式

目标

检查 CLI 及其源代码，反向推断其设计意图，然后分两个层面进行评审：

1. 分类契合度 — 它是否按照恰当的 CLI 类型来设计？
2. 执行质量 — 在该类型下，它的实现质量如何？

工作流程

1. 先检查，再提问。

   • 检查帮助输出、子命令帮助、文档、示例、解析器代码、输出代码、错误处理、状态／会话代码、配置界面和测试。
   • 优先依据直接证据，而非推测。

2. 反向推断设计意图。

   • 推断：
     • 表面上的用途
     • 可能的主要角色／控制界面类型
     • 可能的主要用户类型
     • 可能的交互形式
     • 可能的有状态性
     • 可能的风险概况
     • 现有的次要界面

3. 仅确认无法可靠推断的内容。

   • 只有当答案可能实质性地改变分类或评审时，才提出有针对性的确认问题。
   • 不要要求用户重述 CLI 或代码中已经显而易见的事实。

4. 分两个层面进行评审。

   • 将分类契合度与执行质量分开讨论。
   • 除非用户明确希望转向，否则不要批评面向人类的主要 CLI 不够面向 Agent。

5. 形成结构化评审。

   • 使用 references/output-templates.md 中的评审结构。
   • 用户需要正式评审，或类别之间存在重大张力时，使用完整模板。
   • 对于快速请求，精简为：推断出的意图、分类、有证据支持的类别错误、同类执行中的不足，以及优先级最高的改进项。
   • 将类别错误与同类执行中的不足分开讨论。

必须检查的评审要点

在相关情况下，明确检查以下方面：

• 主要与次要界面的清晰度

  • CLI 是否清楚说明主要界面是什么？
  • 次要界面是否是真正的契约，还是仅仅是非正式的附加功能？

• 可发现性

  • 帮助输出是否支持其声称的用户类型？
  • 示例、选项说明和命令结构是否与 CLI 的核心定位一致？

• 结构化输出契约

  • JSON／JSONL／字段选择／退出代码界面是否明确且稳定？
  • 是否会拒绝未知字段，还是默默容忍？
  • 机器界面是否足以支撑文档中的主张？

• 风险模型

  • 是否有意义地区分低、中、高风险操作？
  • 确认／试运行／预览／审计等防护措施是否与风险概况一致？

• 状态模型

  • 是否正确处理有状态性？
  • attach／detach／resume／session／history 等概念的使用是否有充分依据？

• v1 的边界控制

  • CLI 是否保持连贯的 v1 范围？
  • 是否引入了过早的抽象，或缺少必要的契约？

评审规则

• 不要用面向 Agent 优先的标准评判每个 CLI。
• 除非分类有此要求，否则不要强求原始载荷、完整的模式内省能力或机器优先输出。
• 将现代 CLI 视为多界面系统：一个主要角色、一种主要交互形式，以及可选的次要界面。
• 优先进行有力推断，然后有针对性地确认。
• 批评机器支持时，明确指出问题属于：
  • 主要／次要界面不清晰；
  • 机器契约薄弱；或
  • 真正的类别不匹配。

---

处理混合型 CLI

有些 CLI 确实在子命令层面横跨多个角色。

混合型 CLI 的规则：

1. 先在产品层面进行分类——这个 CLI 的核心定位是什么？
2. 如果子命令明显分属不同角色，请明确说明这种划分。
3. 指明主要角色（定义 CLI 身份和设计约束的角色）。
4. 将次要角色指明为具有各自局部约束的次要界面。
5. 如果某个 CLI 的子命令确实服务于不同角色，不要强行将其归为单一角色。

示例：Docker

• 产品层面的主要角色：运行时（其核心定位是容器执行）。
• docker run、docker exec、docker attach → 运行时交互。
• docker image ls、docker volume inspect → 类似能力的资源界面（次要）。
• docker compose up → 工作流／编排（次要）。

关于不断演进的 CLI 的指导：

• 如果 CLI 正从一种类型迁移到另一种类型，请说明其当前核心定位和预期方向。
• 不要只根据未来目标进行分类；应依据当前证据分类，并说明演进趋势。

---

常见失败模式

注意避免以下错误：

• 将每个 CLI 都视为能力型 CLI。
• 将每个 CLI 都视为运行时型 CLI。
• 将 TUI 或 REPL 当作角色，而不是交互形式。
• 忽略有状态性。
• 忽略风险概况。
• 忽略以人为主要用户的 CLI 的帮助信息／可发现性。
• 将自动化适用性视为顶层身份，而不是设计结果。
• 强行让以人为主要用户的工具采用仅面向 Agent 的模式。
• 不定义契约，就称某个 JSON 界面“强”。
• 忽略混合模式 CLI 中的次要界面。
• 未说明设计立场，就直接从分类跳到命令树。
• 未标明 v1 的边界和非目标。
• 对于子命令确实服务于不同控制界面的混合型 CLI，强行将其归为单一角色。
• 对于只有持久化配置／锁文件副作用、但没有真正会话的 CLI，过度设计其有状态性。
• 根据 CLI 对未来的期望，而不是当前证据进行分类。

输出标准

最终输出应：

• 明确说明分类
• 在存在分歧或歧义时，明确说明分类依据
• 明确说明证据、置信度和假设
• 明确说明设计后果
• 明确区分主要界面与次要界面
• 在相关时，明确说明可发现性和机器契约
• 在存在修改操作时，明确说明风险阶梯
• 根据用户要求的深度调整内容
• 简洁但信息密集
• 以诊断为主，而非泛泛而谈

避免使用“改善用户体验”或“让它更适合 Agent”等含糊建议，除非这些建议与具体分类和明确的设计后果相关联。