1. 为什么“CLI-Anything”值得单独拿出来聊命令行工具这几年经历了一轮很明显的回潮。图形界面把门槛降到了最低但真正做工程、做自动化、做批量处理的人兜兜转转还是会回到终端里。原因不复杂CLI 天然可组合、可脚本化、可远程执行、可版本管理而且它的输出是纯文本能被管道、重定向、grep、awk 这些几十年前就打磨好的工具直接消费。你写一个 GUI 工具想让它被另一个程序调用得先设计 API、写 SDK、处理鉴权你写一个 CLI 工具别人一行your-tool --json | jq就能接上。但“CLI-Anything”这个标题有意思的地方不在于它又是一个命令行工具而在于它把 CLI 和 Agent 这两个词绑在了一起。最近围绕codex cli、claude cli、pi agent、agent 框架、agent 记忆、多 agent 协作的讨论密度非常高说明大家已经不满足于“让模型在对话框里回答问题”而是想让模型真正去操作环境、执行任务、拿到结果、根据结果决定下一步。CLI 恰好是这个闭环里最自然的执行层它稳定、可观测、可回放而且几乎每个开发环境里都已经有了。所以我把 CLI-Anything 理解成一个方向而不是一个具体产品把任意能力封装成 CLI再让 Agent 通过调用 CLI 来完成原本需要人手动敲命令才能完成的事情。它解决的核心问题是“Agent 怎么安全、可控、可复现地操作真实世界”适合正在做 Agent 开发、想给自己的工具加一层智能调度、或者单纯想把日常重复操作自动化的开发者。哪怕你只是刚装完codex cli、还在研究agent 开发学习路线这篇文章里的思路也能直接拿去用。2. 整体设计思路为什么是 CLI 而不是别的2.1 CLI 作为 Agent 执行层的天然优势先想清楚一个问题Agent 要干活它需要一个“手”。这只手可以是浏览器自动化、可以是直接调 API、可以是操作数据库也可以是执行 shell 命令。这几种方式里CLI 的性价比是最高的原因有这么几条。第一接口稳定。一个 CLI 工具一旦定下来参数和输出格式它就是一个契约。Agent 不需要理解工具内部怎么实现只要按契约调用就行。这比让模型去点网页按钮可靠得多网页改个 DOM 结构自动化脚本就废了CLI 的参数一般不会随便变。第二可观测。Agent 执行了什么命令、返回了什么、退出码是多少全都能记录下来。出了问题你能回放整条链路这在调试 Agent 行为时是救命的。相比之下模型内部在想什么你很难完全看清但至少它对外部世界的每一次操作都是白纸黑字。第三可组合。一个 CLI 的输出可以喂给另一个 CLIAgent 可以把多个小工具串成一条流水线。这正好对应agent 框架与编排里说的编排能力——不是让一个巨大的 Agent 干所有事而是让一堆职责单一的工具被灵活调度。第四权限边界清晰。你可以精确控制 Agent 能调用哪些命令、带哪些参数、在哪个目录下执行。这比给它一个万能 shell 要安全得多也是agent 安全讨论里绕不开的一环。提示把能力封装成 CLI 时务必让每个工具只做一件事并且输出结构化格式推荐 JSON。Agent 解析结构化输出比解析自然语言稳定一个数量级。2.2 Agent 调用 CLI 的三种典型模式在实际项目里Agent 和 CLI 的结合大致有三种模式复杂度依次上升你可以按需选择。模式一单次调用。Agent 根据用户意图选一个 CLI 命令执行拿到结果后直接返回。比如用户说“帮我看看这个目录下最大的十个文件”Agent 就调用一个封装好的list-large-files命令。这种模式最简单适合入门也是理解cli 什么这个问题最直观的场景。模式二多轮循环。Agent 执行一个命令看结果决定下一步执行什么直到任务完成。这就是经典的 ReAct 循环。比如部署一个服务先检查环境再拉代码再构建构建失败就去看日志根据日志决定改配置还是重试。这种模式对 Agent 的规划能力要求更高也是agent 架构里最核心的部分。模式三多 Agent 协作。不同 Agent 负责不同阶段通过共享的 CLI 工具集和状态来协同。一个负责规划一个负责执行一个负责校验。这就是多 agent 协作讨论的范畴复杂度最高但在大型任务里收益也最明显。我个人的建议是从模式一开始把单次调用打磨到极致再考虑往上走。很多团队一上来就搞多 Agent 编排结果连单个工具的输出格式都没定清楚最后调试成本高到无法维护。2.3 方案选型自研封装还是复用现成 CLI这里有个很现实的取舍。你手头可能已经有一堆现成的 CLI 工具比如 git、docker、kubectl、各种云厂商的命令行客户端。要不要重新封装一遍我的经验是分情况。对于成熟稳定的工具直接复用不要封装。git 就是 git你没必要再包一层my-git那样只会增加维护负担。Agent 完全可以直接调用 git你只需要在提示词或工具描述里告诉它这个命令怎么用、有哪些限制。对于你自己业务里的操作值得封装。比如“给某个用户开通某个权限”这种操作背后可能涉及好几个系统调用直接让 Agent 拼命令既容易出错又不安全。这时候封装成一个语义清晰的 CLI参数校验、权限检查、日志记录都在工具内部做好Agent 只管调用边界就干净了。判断标准很简单如果这个操作需要三步以上、涉及多个系统、或者有安全敏感性就封装如果它本身就是一条标准命令就直接用。3. 核心细节解析把 CLI 做成 Agent 能用的样子3.1 输出格式为什么 JSON 是默认答案Agent 要解析 CLI 的输出纯文本对人类友好对程序不友好。你让模型去正则匹配一段自然语言输出成功率会随着输出格式的微小变化而剧烈波动。所以只要这个 CLI 是给 Agent 用的默认输出 JSON人类可读的格式作为可选项。一个合格的 JSON 输出应该包含几个要素状态、数据、错误信息、以及必要的元数据。我一般会定成这样的结构{ ok: true, data: { }, error: null, meta: { command: list-large-files, duration_ms: 128, timestamp: 2025-01-01T00:00:00Z } }ok字段让 Agent 一眼判断成败不用去猜退出码的含义。error字段在失败时给出结构化原因Agent 可以据此决定重试还是放弃。meta里的耗时和命令名在排查问题和做性能分析时特别有用。注意错误信息不要只给一个错误码要给一句人类能看懂、模型也能理解的话。比如不要只返回E403而是返回permission denied: user lacks write access to /data。模型看到后者才知道下一步该去申请权限还是换个目录。3.2 参数设计让 Agent 不容易用错Agent 调用 CLI 时最容易出问题的地方就是参数。人类看--help能理解模型看一长串选项容易懵。所以参数设计要遵循几个原则。必填参数少而明确。一个命令最好只有一到两个必填参数其余都有合理默认值。参数越多模型填错的概率越高。用长选项别用短选项。--output-format json比-o json对模型友好得多因为语义清晰。短选项省的那几个字符不值得用可读性去换。枚举值要显式列出。如果某个参数只能取几个值在帮助信息里明确写出来别让模型去猜。比如--mode只能是fast、safe、dry-run三个之一就写清楚。危险操作要有显式确认参数。删除、覆盖、发布这类操作加一个--confirm或者--dry-run默认开启。Agent 在不确定的时候可以先跑 dry-run 看结果确认无误再真正执行。这是agent 安全里非常实用的一招。3.3 退出码Agent 判断成败的第一信号退出码是 CLI 和调用方之间最古老的契约。0 表示成功非 0 表示失败这个约定 Agent 必须遵守你的工具也必须严格遵守。但光有 0 和非 0 还不够。我建议把常见的失败类型映射到不同的退出码这样 Agent 不用解析输出就能做初步判断。比如退出码含义Agent 建议动作0成功继续下一步1通用错误查看 error 字段2参数错误修正参数后重试3权限不足申请权限或换路径4资源不存在检查输入或先创建5超时重试或延长超时6外部依赖失败检查依赖服务状态这张表不是标准是我自己在项目里总结出来的一套约定。有了它Agent 的决策逻辑可以写得很清晰退出码 2 就重新组织参数退出码 5 就重试退出码 3 就上报给人。比让模型去读一大段错误文本再判断要可靠。3.4 幂等性让重试变得安全Agent 执行任务时重试是常态。网络抖动、服务临时不可用、超时都会触发重试。如果命令不幂等重试就可能造成重复操作——重复创建资源、重复发送消息、重复扣款。所以给 Agent 用的 CLI尽量设计成幂等的。创建类操作可以用“存在即返回”的语义而不是“存在就报错”。更新类操作天然幂等。删除类操作删一个不存在的东西返回成功比返回失败更合理因为最终状态是一致的。如果实在做不到幂等就加一个幂等键参数让调用方传入一个唯一标识工具内部记录已处理过的键重复请求直接返回上次结果。这个模式在支付、订单类系统里很常见搬到 CLI 上一样管用。4. 实操过程从零搭一个 Agent 可调用的 CLI4.1 环境准备与工具链选择先明确技术栈。写 CLI 用什么语言取决于你的团队和部署环境。Node.js 生态里commander、yargs很成熟Python 里click、typer写起来很舒服Go 编译出来是单二进制分发最省心。如果你已经在用codex cli或者claude cli这类工具那大概率是 Node 环境用 JS/TS 写 CLI 最顺手。我这边以 Node.js 为例因为它的生态和 Agent 工具链结合最紧密。先初始化项目mkdir cli-anything-demo cd cli-anything-demo npm init -y npm install commander chalkcommander负责参数解析chalk负责终端着色人类可读模式下用。如果你要输出 JSON其实不需要额外库JSON.stringify就够了。目录结构建议这样组织cli-anything-demo/ bin/ cli.js # 入口负责注册命令 commands/ list-files.js # 每个命令一个文件 deploy.js lib/ output.js # 统一输出格式 errors.js # 错误码定义 package.json每个命令独立成文件好处是职责清晰加新命令不影响老命令测试也好写。4.2 统一输出层的实现输出层是整个 CLI 的地基所有命令都走它才能保证格式一致。我写一个lib/output.jsfunction success(data, meta {}) { return { ok: true, data, error: null, meta: { timestamp: new Date().toISOString(), ...meta, }, }; } function failure(code, message, meta {}) { return { ok: false, data: null, error: { code, message }, meta: { timestamp: new Date().toISOString(), ...meta, }, }; } function print(result, exitCode) { process.stdout.write(JSON.stringify(result, null, 2) \n); process.exit(exitCode); } module.exports { success, failure, print };这个层看起来简单但它是所有命令行为一致的保证。任何命令不管内部多复杂对外都只吐这一种结构。Agent 侧只需要写一套解析逻辑就能处理所有命令的返回。实操心得process.exit会立即终止进程如果还有异步操作没完成可能丢数据。稳妥的做法是先确保所有输出写完再退出。在 Node 里可以用process.exitCode code然后让进程自然结束避免截断输出。4.3 一个完整命令的实现list-files拿一个实际命令来演示。假设我们要做一个“列出目录下大文件”的命令Agent 可以用它来排查磁盘占用。const fs require(fs); const path require(path); const { success, failure, print } require(../lib/output); function listFiles(dir, options) { const start Date.now(); const limit parseInt(options.limit, 10) || 10; const minSize parseInt(options.minSize, 10) || 0; if (!fs.existsSync(dir)) { print(failure(NOT_FOUND, directory not found: ${dir}), 4); return; } const entries fs.readdirSync(dir, { withFileTypes: true }); const files []; for (const entry of entries) { if (!entry.isFile()) continue; const fullPath path.join(dir, entry.name); const stat fs.statSync(fullPath); if (stat.size minSize) { files.push({ name: entry.name, size: stat.size, path: fullPath }); } } files.sort((a, b) b.size - a.size); const result files.slice(0, limit); print( success(result, { command: list-files, duration_ms: Date.now() - start, total_matched: files.length, returned: result.length, }), 0 ); } module.exports { listFiles };这个命令有几个设计点值得说。limit和min-size都有默认值Agent 不传也能跑。目录不存在时返回退出码 4对应“资源不存在”Agent 一看就知道该检查路径。meta里带了total_matched和returnedAgent 能知道是不是被截断了需不需要调整 limit 再查一次。4.4 入口注册与帮助信息bin/cli.js负责把命令挂上去#!/usr/bin/env node const { program } require(commander); const { listFiles } require(../commands/list-files); program .name(cli-anything) .description(Agent-friendly CLI toolkit) .version(1.0.0); program .command(list-files) .description(List files in a directory sorted by size) .argument(dir, directory to scan) .option(--limit n, max number of files to return, 10) .option(--min-size bytes, minimum file size in bytes, 0) .action((dir, options) listFiles(dir, options)); program.parse();帮助信息是给模型看的文档。description要写清楚这个命令干什么参数说明要写清楚每个选项的含义和默认值。模型在决定调用哪个命令时读的就是这些文字。写得越清楚它选错的概率越低。4.5 让 Agent 真正调用起来CLI 写好了怎么让 Agent 用核心是把这个命令的“说明书”喂给模型。说明书包含三部分命令名、参数说明、返回结构示例。你可以把它写成一个工具描述塞进 Agent 的 system prompt 或者工具注册表里。一个简化的工具描述长这样{ name: list_files, description: List files in a directory sorted by size descending. Use this when you need to find large files or check disk usage., parameters: { type: object, properties: { dir: { type: string, description: absolute path to the directory }, limit: { type: integer, description: max results, default 10 }, min_size: { type: integer, description: minimum size in bytes, default 0 } }, required: [dir] } }Agent 拿到这个描述就能在需要的时候生成对应的命令调用。执行层收到调用后拼出cli-anything list-files /data --limit 20执行把 JSON 结果返回给模型。模型看到ok: true和data数组就能继续推理。这套流程跑通之后你会发现加新能力变得非常简单写一个新命令加一条工具描述Agent 就多了一项技能。这就是 CLI-Anything 这个思路的威力——能力扩展变成了写 CLI而不是改 Agent 本身。5. 常见问题与排查技巧实录5.1 Agent 调用失败的高频原因实际跑起来之后问题基本集中在这几类。我整理成一张速查表方便对照排查。现象可能原因排查方向命令找不到PATH 未包含 CLI 目录用绝对路径调用或检查环境变量参数解析失败模型生成了不存在的选项检查工具描述是否准确加参数校验输出解析失败命令混入了非 JSON 日志确保 stdout 只有 JSON日志走 stderr权限错误执行用户权限不足检查文件权限和运行身份超时命令执行时间过长加超时参数或拆分成异步任务结果被截断输出量超过限制分页返回或让 Agent 用 limit 参数其中“输出混入非 JSON”是最隐蔽的一类。很多库默认会往 stdout 打日志结果 JSON 里混了一行INFO: starting...Agent 解析直接失败。解决办法很简单所有日志走 stderrstdout 只留给结构化输出。这是 Unix 的老规矩但在 Agent 场景下尤其重要。5.2 关于unable to locate the codex cli binary这类报错的思路很多人在装codex cli或者类似工具时会遇到“找不到二进制或运行时组件”的报错。这类问题的本质是调用方知道命令名但系统 PATH 里找不到对应的可执行文件。排查顺序是这样的先确认工具是否真的装上了用which或where查一下再确认安装路径是否在 PATH 里最后确认运行环境的架构是否匹配比如在 ARM 机器上装了 x86 的包就会报不兼容。这个思路对所有 CLI 工具都通用。Agent 调用 CLI 失败时第一步永远是确认“这个命令在当前环境下能不能被找到”。环境问题占了失败原因的一大半而且往往和 Agent 本身无关。5.3 独家避坑给 Agent 的 CLI 要“防呆”人类用 CLI看帮助能理解模型用 CLI很多时候是“照着描述猜”。所以给 Agent 用的 CLI 要比给人用的更防呆。默认值要安全。删除类命令默认 dry-run真要删必须显式加--confirm。这样模型即使判断失误也不会造成不可逆的破坏。错误信息要可操作。不要只说“参数错误”要说“参数 limit 必须是正整数收到的是 abc”。模型看到后者才知道怎么改。输出要自解释。字段名用完整的英文单词别用缩写。duration_ms比dur好total_matched比tm好。模型对完整单词的理解准确率明显更高。限制单次输出规模。一个命令返回十万条记录既浪费 token 又容易让模型迷失。默认返回前 N 条并在 meta 里告诉模型总数让它自己决定要不要翻页。5.4 调试 Agent 调用链的实用手法Agent 调用 CLI 出问题时最有效的调试方式是把整条链路记录下来。我会在 CLI 入口加一层日志记录每次调用的命令、参数、耗时、退出码和输出摘要写到文件里。出问题时翻这个日志比在模型对话里找线索快得多。另一个技巧是用 dry-run 模式复现。让 Agent 在 dry-run 下跑一遍看它打算执行什么命令确认无误再放开真实执行。这在调试复杂任务时特别有用能提前发现模型理解偏差。提示日志里不要记录敏感数据。参数里如果有密钥、token记录前先脱敏。这是基本的安全习惯别等出事才想起来。6. 从单命令到多 Agent 协作的演进路径6.1 什么时候该引入多 Agent单 Agent 加一堆 CLI 工具能解决大部分问题。但任务复杂到一定程度单 Agent 会力不从心上下文太长、职责太杂、容易顾此失彼。这时候可以考虑拆成多 Agent。判断信号有几个任务步骤超过十步、需要不同领域的专业知识、需要并行处理、或者单个 Agent 的提示词已经长到难以维护。出现这些信号就该考虑多 agent 协作了。但我要泼一盆冷水多 Agent 不是免费的。Agent 之间的通信、状态同步、冲突处理都是额外的复杂度。很多任务用单 Agent 加好的工具设计就能解决硬拆成多 Agent 反而更难调试。我的建议是能单就单实在不行再拆。6.2 共享 CLI 工具集作为协作基础多 Agent 协作时CLI 工具集可以成为它们共同的“手”。不同 Agent 负责不同阶段但调用的是同一套工具状态通过文件系统或数据库共享。这样每个 Agent 的职责清晰工具的行为一致整体可控。比如一个部署任务规划 Agent 负责拆解步骤执行 Agent 负责调用部署 CLI校验 Agent 负责调用检查 CLI 验证结果。三个 Agent 各司其职通过共享的工具集和状态协同。这种架构比让一个 Agent 从头干到尾要清晰得多也更容易定位问题出在哪个环节。6.3 记忆与状态的落地方式Agent 记忆是绕不开的话题。agent 记忆框架以及选型讨论很多但落到 CLI 场景其实可以很简单用文件系统做记忆。每个任务一个目录中间结果写成文件Agent 需要时读回来。这比搞一套复杂的向量数据库要简单可靠得多而且完全可观测——你随时能打开文件看 Agent 到底记住了什么。对于大多数工程任务文件系统加结构化 JSON 就够用了。真到了需要语义检索的规模再考虑上专门的记忆框架也不迟。7. 我在这套东西上踩过的坑最后分享几个实际踩过的坑都是文档里不会写、但真会让人卡半天的。第一个坑是过度依赖模型的参数生成能力。早期我让模型自由生成命令参数结果它经常编出不存在的选项。后来改成在工具描述里把参数枚举清楚并且 CLI 侧做严格校验非法参数直接返回退出码 2 和明确的错误信息模型看到后基本都能自我纠正。别指望模型记住所有参数要把约束写进工具本身。第二个坑是忽略了输出编码。有一次命令返回的中文在 Agent 侧变成了乱码排查半天发现是编码没统一。现在我的 CLI 一律用 UTF-8 输出并且在文档里明确写出来。这种小问题不解决会让整个链路莫名其妙地失败。第三个坑是没有给命令加超时。有个命令在特定情况下会卡住Agent 就一直等整个任务挂死。后来所有命令都加了超时参数超时返回退出码 5Agent 看到就重试或上报。任何可能阻塞的操作都要有超时这是铁律。第四个坑是日志和输出混在一起。前面提过但值得再强调一次。stdout 只放结构化结果stderr 放日志这个约定能省掉无数解析问题。这套 CLI-Anything 的思路本质上是用工程手段给 Agent 装上一双可靠的手。工具写得好Agent 就稳工具写得糙再强的模型也救不回来。把每个 CLI 当成一个对 Agent 友好的 API 来设计剩下的编排和协作才有意义。