开源 AI CLI 设计：命令行工具要先稳定，再智能

AI 工具很适合做成 CLI：开发者可以在终端里生成提交说明、解释报错、整理日志、检查代码片段。但很多 AI CLI 一上来就追求“全能助手”，结果命令复杂、输出不稳定、配置分散，最后变成一个很难自动化的聊天入口。命令行工具的第一原则不是聪明，而是可预测。

开源 AI CLI 的设计目标，是把模型能力封装成稳定、可组合、可脚本化的开发者工具。

一、先定义最小命令集

flowchart TD
  A[CLI Entry] --> B[Subcommand]
  B --> C[Input Adapter]
  C --> D[LLM Call]
  D --> E[Output Formatter]
  E --> F[Stdout Or File]

一个可维护的 CLI 不应该只有 ask 一个入口。可以先拆成少数稳定命令，例如 explain、commit、summarize、review。每个命令只解决一个开发场景，输入输出格式固定，后续才能被 shell、CI 或编辑器插件调用。

命令越少，越要把语义做清楚。review 是检查 diff，还是检查整个目录；summarize 是总结文件，还是总结日志；commit 是否允许读取未暂存内容。这些边界如果不明确，用户会把 CLI 当聊天机器人使用，工具就失去了可自动化的价值。

二、配置要分层

provider: openai
model: "gpt-4.1-mini"
temperature: 0.2
commands:
  commit:
    max_tokens: 300
  review:
    max_tokens: 1200

配置可以分为全局配置、项目配置和命令参数三层。全局配置放供应商、默认模型和密钥引用；项目配置放仓库约定；命令参数用于本次执行覆盖。层级清楚之后，用户知道一个行为为什么发生，也知道应该改哪里。

不要把密钥写进项目配置。开源工具默认会被放进仓库，密钥应该来自环境变量或本地凭据存储。配置文件里可以写 OPENAI_API_KEY 这样的引用名，但不要保存真实值。CLI 做得越方便，越要谨慎处理安全边界。

三、输出必须适合管道

ai-cli summarize ./logs/error.log --format json | jq '.root_cause'

开发者喜欢 CLI，是因为它能接进已有流程。纯自然语言输出适合阅读，但不适合脚本。一个 AI CLI 至少要支持 text、json、markdown 三种输出模式。默认可以友好，但机器可读模式必须严格。

结构化输出要做校验。模型返回 JSON 不代表 JSON 一定合法，也不代表字段完整。CLI 应该在输出前解析结果，失败时返回非零退出码，并把错误写到 stderr。这样调用方才能可靠地判断命令成功还是失败。

四、智能能力要可降级

type CliResult =
  | { ok: true; output: string; tokens: number }
  | { ok: false; code: "MODEL_ERROR" | "INVALID_OUTPUT" | "CONFIG_ERROR"; message: string };

AI 服务可能超时、限流、返回格式错误。CLI 不能因为一次模型失败就输出半截内容。更稳的做法是定义明确错误码，必要时提供 --no-ai 或 --fallback-template。比如生成提交说明失败时，可以退回到基于文件列表的模板，而不是让整个发布流程中断。

开源工具还要把日志分级。普通用户只看简洁错误，调试模式再显示请求耗时、模型名、重试次数和响应摘要。不要默认把完整 Prompt 和输入内容打印出来，里面可能包含私有代码或业务日志。

五、总结

开源 AI CLI 要先稳定，再智能。最小命令集、分层配置、结构化输出、错误码和降级策略，是命令行工具能被长期使用的基础。

模型可以让 CLI 更聪明，但 CLI 的价值仍然来自可预测性。能放进脚本、CI 和日常开发流程里的 AI 工具，才是真正有生命力的工具。