1. CLI-Anything 是什么把万物装进终端的核心思路1.1 为什么万物皆可 CLI不是口号而是效率刚需最近一两年我身边的开发者朋友开始频繁讨论 CLI不是因为我们怀旧而是命令行确实解决了一个图形界面始终绕不开的问题可组合、可脚本化、可复现。打开多个 GUI 窗口来回点击和敲一条命令让流程自动跑完两者的效率差距不是一点半点。尤其当你需要同时操作 AI 编程助手、云服务、代码仓库和自动化流水线时GUI 的点击成本会成倍放大。我一直想把所有高频工作流都收敛到终端里这套思路我给它起了个名字CLI-Anything。核心目标就一句话无论底层是哪个服务、哪种 API、哪款外部工具最终都表现为一组统一、好记、能组合的命令。它适合每天要和编辑器、终端、API 打交道的开发者也适合想给团队沉淀一键操作脚本的技术运营。你会发现真正用起来后命令行不再是高手的玩具而是最顺手的操作界面。1.2 CLI-Anything 的三种形态适配器、配置生成器、交互规范我把 CLI-Anything 拆成三个层面这样才不会被Anything这个词吓住。第一个是适配器层。它负责把外部命令、HTTP API、内部函数统一转换成命令入口。比如把调用 Codex CLI变成cli-anything exec把调用 Claude CLI变成cli-anything review把请求通义千问变成cli-anything chat --provider qwen。底层服务怎么换适配层负责把差异吃掉。第二个是配置生成器。所有鉴权信息、模型名、超时、输出格式都收敛到一份 YAML 或 TOML 文件里通过环境变量覆盖。换供应商、换环境时不用改代码只改配置。这样的好处是配置可以进版本库团队协作时每个人拿到的行为是一致的。第三个是交互规范。命令的参数命名、退出码、输出格式要统一。比如所有子命令都支持--json和--quiet成功返回 0失败返回非 0。这套规范确保新加入的命令也能被老脚本直接调用不会出现换了个命令就不能用了的情况。我现在用 Python 的 Typer 库实现因为类型注解能自动生成帮助信息编写子命令的成本很低。但 CLI-Anything 的思想不绑定语言用 Node、Go 甚至纯 bash 都能搭关键是上面三层契约要固定住。1.3 与当前 AI CLI 热潮的结合Codex CLI、Claude CLI最近 Codex CLI 和 Claude CLI 火起来本质上是万物皆 CLI趋势在 AI 领域的爆发。Codex CLI 能把自然语言编码指令变成代码修改、命令执行、测试反馈的闭环Claude CLI 则把长上下文代码理解和文件编辑能力塞进了终端。它们本身就是很好的Anything示范AI 能力被包装成可以反复调用的命令。但实际用起来会发现一个尴尬不同工具安装方式不同、配置方法不同、输出格式也不同。有人想用 Qwen 这类模型做后端还要额外折腾兼容参数。这些碎片化体验正是我用 CLI-Anything 做统一封装的原因。接下来的章节我会从设计到实战一步步拆解如何把这些工具变成你自己命令体系里的普通子命令。2. 核心技术拆解设计一个能封装任何东西的命令行工具2.1 命令解析与参数设计的关键原则命令行工具给人最直接的感受就是命令长什么样。设计第一原则是子命令即操作一个顶级命令对应一套场景。我在自己的工具里用cli-anything作为主命令下面挂chat、exec、agent、review等子命令。这样既保留了扩展空间又让用户记忆成本极低。第二原则参数尽量少选项尽量明确。位置参数只用于真正的主体对象比如要处理的文件路径或要询问的问题其他全部用--model、--provider、--format这类选项承载。每个选项都要有短别名和完整的帮助文本让--help输出本身就是文档。第三原则环境变量是隐藏参数。API Key、Base URL、超时时间等敏感或环境相关配置不要写死在命令行里。解析参数时遵循命令行参数优先其次环境变量最后配置文件的顺序这样在 CI、本地、服务器上都能有一致的表现却互不干扰。下面这段 Typer 示例展示了基本结构import typer from typing import Optional app typer.Typer(namecli-anything, help把任意服务封装成CLI) app.command() def chat( question: str typer.Argument(..., help要提问的内容), provider: str typer.Option(auto, --provider, -p, help使用哪个provider), model: Optional[str] typer.Option(None, --model, -m, help模型名默认取配置), json_output: bool typer.Option(False, --json, help输出JSON格式), ): 发起一次AI对话 ...把主命令、子命令、选项拆清楚后剩下的事情就是让chat、exec这些函数真正干活。我在实际项目中还会在每个子命令里加--quiet、--debug两个通用选项前者只输出关键结果后者打印调试日志能减少很多现场排查的沟通成本。2.2 配置管理一份配置就能切换 Codex、Claude、QwenCLI-Anything 的配置层要解决的核心问题是异构后端统一表达。我维护一份~/.cli-anything/config.yaml按 provider 组织providers: openai: type: openai_api api_key_env: OPENAI_API_KEY base_url: https://api.openai.com/v1 default_model: gpt-4o anthropic: type: anthropic_api api_key_env: ANTHROPIC_API_KEY base_url: https://api.anthropic.com default_model: claude-sonnet-4 qwen: type: openai_compatible api_key_env: DASHSCOPE_API_KEY base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 default_model: qwen-plus三个关键设计点type字段决定适配器。openai_api和anthropic_api走各自的原生协议openai_compatible用于一切兼容 OpenAI Chat Completions 协议的服务像 DashScope 的兼容模式就是这么接入的。base_url是每个 provider 的入口通过它不需要改代码就能把工具从官方端点切换到自建网关。Key 全部通过环境变量名引用配置里只有名字没有密钥值避免配置文件被提交到 Git 时泄密。有了这份配置运行时选择 provider 就变得很自然cli-anything chat 帮我解释这段代码 --provider qwen --model qwen-plus cli-anything chat 帮我重构这个函数 --provider anthropic底层差异被配置层吸收使用体验完全一致。我实际使用中还发现一个细节配置里的timeout也要按 provider 单独设置不同模型服务的响应速度差别很大统一设一个值容易导致某些慢模型频繁超时。2.3 输出处理拦截、解析与再格式化封装外部命令时最常踩的坑是命令能用但输出没法进脚本。有的工具把日志打到 stderr有的在 stdout 里混了进度条还有的人机交互提示在管道模式下会卡住。CLI-Anything 的输出层统一做三件事第一用 subprocess 接管外部命令的 stdout 和 stderr而不是直接把进程交给终端。进程实时产生的内容照常打印方便交互查看同时按行写入内存缓冲区。这样屏幕上看到的是原汁原味下游拿到的是干净内容。第二定义输出协议。每个适配器在--json模式下只输出一份 JSON 文档内容至少包含status、output、error三个字段没有额外说明文字。CI 可以直接用 jq 解析不用写脆弱的正则去捞内容。第三规范退出码。成功返回 0错误返回非 0并按类型细分1 表示参数错误2 表示配置错误3 表示上游 API 失败4 表示超时。排查问题时只扫一眼退出码就能定位方向。核心部分代码如下import subprocess, json def run_external(cmd: list[str]) - dict: proc subprocess.Popen( cmd, stdoutsubprocess.PIPE, stderrsubprocess.PIPE, textTrue, encodingutf-8 ) stdout, stderr proc.communicate() return { status: ok if proc.returncode 0 else error, output: stdout, error: stderr, exit_code: proc.returncode, }这还只是起点。如果要支持流式输出我会把Popen改成逐行读取并把超时控制、键盘中断、重试逻辑都收拢到这一层避免每个适配器重复实现。2.4 扩展机制用 Hook 和插件目录实现AnythingAnything意味着你总会遇到设计时没想到的命令。为了不把自己锁死CLI-Anything 规定了一个简单的插件目录约定~/.cli-anything/plugins/下每个子目录就是一个封装单元里面可以放command.yaml描述命令名、参数、需要执行的模板再加一段可选的前置和后置脚本。command.yaml模板看起来是这样name: daily-review description: 用当前git diff生成代码评审意见 arguments: files: type: string required: false help: 只评审指定文件 hooks: before: hooks/prepare_git_diff.sh after_success: hooks/post_to_console.sh after_error: hooks/handle_error.sh exec: type: external_command command: cli-anything args: [chat, 请评审以下diff, --provider, qwen] input_from: git_diff_content钩子的设计原则是主流程保持简单附加行为都放到 Hook 里。团队里有人想加告警、记日志、发通知不需要改主程序代码只要在插件目录里加脚本。每次运行结束后CLI-Anything 会在~/.cli-anything/runs/留下一份时间戳命名的 JSON 运行记录包含输入参数、退出码、耗时、输出摘要方便事后回溯。这个运行记录目录就是你的黑盒出了问题先看它比猜原因高效太多。3. 实操记录把 Codex CLI 与 Claude CLI 风格统一到 CLI-Anything3.1 安装与初始化先说怎么把环境搭起来。CLI-Anything 本身是个 Python 包安装很简单pip install cli-anything cli-anything initinit会在用户目录生成默认配置和插件目录并输出一段 PATH 配置提示。接下来安装两个典型的外部 CLI。Codex CLI 通常通过 Node 包管理器安装npm install -g openai/codex codex --versionClaude CLI 也是常见的终端型工具安装命令类似npm install -g anthropic-ai/claude-code claude --version装好之后先确认which能找到它们。这一步经常会暴露环境变量问题具体排查我放在下一章。等外部命令能独立运行后再让 CLI-Anything 去调用它们。我习惯在配置里加一个包装外部命令类型的 providerproviders: codex_local: type: external_cli command: [codex] args_template: exec --json {prompt}这段配置的意思是用户执行cli-anything exec --provider codex_local时工具实际拼出codex exec --json ...这条外部命令并交给输出层处理。通过这种设计不需要理解 Codex 内部实现只需要遵守它的参数接口。3.2 用 Qwen 兼容端点给工作流供电很多同学想在本地工作流中接入 Qwen 这类模型而不只用官方 Key。把 Qwen 接入 CLI-Anything 的步骤非常简单因为不少 AI 服务都提供 OpenAI 兼容协议DashScope 的兼容模式也提供了/compatible-mode/v1端点。只要在配置里用type: openai_compatible设置 base_url 和 API Key 环境变量即可。配置好后一条命令即可调用export DASHSCOPE_API_KEY你的key cli-anything chat 写一个冒泡排序的单元测试 --provider qwen --model qwen-plus如果你已经安装了 Claude CLI又希望同一套对话逻辑也走 Qwen需要区分命令入口和模型后端两个概念。我的做法是让claude这个 provider 调用本地 Claude CLI同时让qwen这个 provider 走 OpenAI 兼容接口。在命令层它们都是cli-anything chat的选项切换后端只需一个--provider参数。这比每次手动改环境变量可靠得多。对比一下如果直接使用不同的官方 CLI你需要在多个工具配置文件里分别维护 base_url、key、模型名用 CLI-Anything 后差异被收敛到一份 YAML命令风格完全一致。3.3 统一命令风格与日常使用封装完成后我日常最高频的命令如下场景命令询问代码逻辑cli-anything chat 解释一下src/auth.py的登录流程 --provider qwen用 Codex 本地执行cli-anything exec 修复测试失败并补充断言 --provider codex_local用 Claude 做代码评审cli-anything review --provider claude只看 JSON 输出在任意命令后加--json静默模式任意命令后加--quiet只输出关键结果实际使用中我通常把三个动作串成一条工作流先用cli-anything chat让模型分析规格再用cli-anything exec让 Codex 落地改代码最后用cli-anything review对 diff 做评审。每一步的输出都被输出层标准化下一步能直接当成输入继续传递。这里分享一个细节不要让每个子命令都去实现一遍读 git diff的逻辑。我把读取待评审内容做成了共享 Hook放在~/.cli-anything/hooks/git_diff.sh子命令通过配置引用它。这样做的好处是以后有了新命令想复用同样的输入源只要在 YAML 里把input_from指向同一个 Hook。4. 常见问题与排查技巧实录4.1 二进制找不到unable to locate the codex cli binary or required runtime components这个报错我遇到太多次了。它通常不是 Codex 本身的问题而是 CLI-Anything 启动子进程时找不到codex可执行文件。检查顺序如下第一步直接在终端执行which codex codex --version如果which没有输出说明 Node 全局 bin 目录不在 PATH 里。先确认 npm 全局根目录npm prefix -g然后把该目录下的 bin 路径加入 PATH。以 macOS 或 Linux 为例在.zshrc或.bashrc中追加export PATH$(npm prefix -g)/bin:$PATHWindows 下则检查 npm 全局目录是否已加入系统环境变量 PATH。第二步如果which codex能找到但 CLI-Anything 里仍然报错多半是启动子进程时的环境变量和执行 shell 不一致。排查时可以在command.yaml的hooks.before里加一句env输出对比真实 PATH。第三步确认版本兼容。Codex CLI 升级后偶发运行时组件不匹配此时建议先清缓存再重装npm uninstall -g openai/codex npm cache clean --force npm install -g openai/codexlatest这类问题大概率是环境问题不是代码问题。先确定直接手动执行是否正常就能快速排除故障范围。4.2 Key 与鉴权常见坑配置 API Key 时最常见的坑是把 Key 直接写进 YAML。这样如果配置库被共享或误提交等于把自己的账单公开了。我在 CLI-Anything 里强制要求配置只引用环境变量名启动时若发现变量未设置立即报错并提示用户执行export。另一个常见问题使用 Qwen 兼容端点时很容易漏掉/compatible-mode/v1路径导致一直报 404 或 401。正确写法是base_url: https://dashscope.aliyuncs.com/compatible-mode/v1还有一类问题出在模型名。有的服务要求模型名带版本后缀比如qwen-max-2025-01-25有的只接受短名qwen-plus。配置 default_model 前先查服务商文档。遇到 404 时不要只盯着 URL把请求体里的model字段也打印出来看看。如果你在 CI 里运行建议把 API Key 放到 CI Secrets 中然后通过环境变量注入而不是写入项目文件。CLI-Anything 内部通过os.environ.get()读取天然支持这种用法。4.3 输出乱码与流式中断AI CLI 的流式输出很好看但进入自动化流程后反而容易变成麻烦。最常见的表现有两种中文乱码和长时间无输出。乱码问题通常是编码不一致。外部进程输出编码可能是 ASCII 或系统代码页而程序用 UTF-8 解析。在启动外部命令前我会在 Python 侧设置环境变量PYTHONIOENCODINGutf-8同时给 subprocess 传encodingutf-8。另外在.bashrc中设置export LANGC.UTF-8和export LC_ALLC.UTF-8也能减少很多终端层的乱码。流式中断则要区分是服务异常还是 subprocess 管道被阻塞。我的经验是对于交互式 CLI优先使用非交互模式参数。比如 Codex 的--json模式会一次性输出结果而不是逐步渲染自动化场景更可靠。如果确实需要实时读取则要加超时保护try: stdout, stderr proc.communicate(timeout120) except subprocess.TimeoutExpired: proc.kill() raise RuntimeError(上游命令执行超时)这个 try/except 是很多适配器通用的一段代码。处理超时后记得把退出码设置成 4方便上层脚本识别。4.4 权限与自动化中的坑CLI-Anything 核心能力之一是把手工操作变成自动化脚本。但自动化环境与交互终端差异很大命令不能等待人工确认不能用未导出的 shell 函数路径不能依赖当前目录。在 CI 流水线里我强制使用--json --quiet让prompt从文件或环境变量读取而不是交互输入。例如cli-anything exec $(cat prompt.md) --provider codex_local --json还有一条安全底线不要把可变输入直接拼到 shell 命令里。外部命令的参数列表要用数组传递不要先拼成一个字符串再用shellTrue执行否则用户输入里的分号、引号可能造成命令注入。CLI-Anything 的适配器层始终使用列表形式的命令这一条值得写进每个开发者的编码规范。5. 给进阶玩家的一些设计心得5.1 错误处理与可观测性CLI 做得越多越需要观察自己。我在~/.cli-anything/runs/里保存每次运行的 JSON 记录包含命令名、参数、provider、退出码、耗时、错误摘要。这个目录本身就是一个低成本的审计日志。当用户反馈命令突然不好用了我第一件事不是看代码而是看运行记录里最近几条的退出码和错误摘要。结构化日志帮我把定位时间从十分钟压缩到两分钟。如果是团队使用还可以把每次运行记录同步到内部日志服务方便做失败率告警。这里我建议再存一个raw_stdout字段虽然会增加磁盘占用但在复现问题时能省去很多猜测。5.2 性能与资源占用CLI-Anything 的封装层很薄真正的开销都在上游服务。但有几个细节能让体验好很多对固定内容做本地缓存比如--help生成的帮助文本不要每次现算。并发调用上游 API 时加信号量限制避免一个脚本同时打出几十个请求。对可能长时间运行的命令默认设置超时超时后先把已产出的输出保存下来再抛出错误。这里有个取舍流式交互能提升体感但自动化脚本更看重确定性。我在设计每个适配器时都同时暴露--stream和--json把选择权交给用户。实测中--json在大模型返回长代码时反而比流式更不容易被截断因为它走的是完整响应解析不存在行缓冲问题。5.3 下一步从个人工具到团队平台当 CLI-Anything 证明一个入口包装所有工具可行之后下一个自然动作是让它变成团队共享平台。我在项目里把配置分成两层团队基础配置放远端 Git 仓库个人覆盖配置放本地运行时通过配置合并机制让个人配置只覆盖差异项。这样新成员 clone 下来后执行一次同步就能得到全套工具入口不用逐项对照文档配置。插件市场是另一个可以考虑的方向。如果你已经把自己最喜欢的命令封装成了插件可以发布到内部源团队其他人一条命令就能安装。命名空间建议用scope/name的形式比如mycompany/daily-review避免插件名冲突。切记平台化之前先让工具在个人场景里足够顺手。过早抽象只会增加团队的认知负担等两三个人的使用场景都稳定了再做统一也不迟。在实际封装过程中我发现最有价值的设计不是我能封装多少工具而是每次封装都在让命令行世界的边界变宽一点。Codex CLI、Claude CLI 这些外部工具会持续迭代但只要你牢牢握住参数规范、配置分层、输出协议这三个舵盘任何新工具都能在你的 CLI-Anything 里快速落户。先挑三个自己每天都要做的手工操作动手改造吧改造完你会有种原来还能这么顺手的感觉。