CLI-Anything：为AI Agent打造通用命令行工具层

1. 为什么“CLI-Anything”值得单独拿出来聊

命令行工具这几年经历了一轮很明显的“回潮”。早些年大家觉得 GUI 才是效率的终点，终端只是运维和极客的玩具；但这几年做 AI Agent、做自动化流水线、做本地开发环境的人越来越多，反而发现一个尴尬的现实：几乎所有真正能跑起来的 Agent 能力，最后都要落到一个命令行入口上。模型再聪明，它也得有个地方去调用工具、执行脚本、读写文件、拉起子进程。这个“地方”，十有八九就是 CLI。

“CLI-Anything”这个标题，我理解的核心不是某一个具体软件，而是一种思路：把任意能力封装成 CLI，让 Agent 能统一调用。它背后牵扯的是 CLI 设计、Agent 工具调用协议、CLI-Hub 这类分发中心、以及 Codex CLI、Claude CLI、各类 agent 框架之间的协作方式。热搜词里反复出现 codex cli 安装、agent 开发、agent 框架、多 agent 协作、agent 记忆，这些其实都指向同一个问题——怎么让命令行成为 Agent 的通用手脚。

这篇文章适合三类人看：第一类是刚开始接触 agent 开发、被各种 CLI 安装和配置绕晕的新手；第二类是已经在写 agent、但工具调用层做得一团乱、想找一套统一封装思路的开发者；第三类是想把现有脚本、内部系统、数据处理流程“Agent 化”的工程同学。我会从设计思路讲到具体落地，把 CLI 封装、Agent 接入、CLI-Hub 分发、常见报错排查这几块拆开讲透，尽量做到你看完就能照着搭一套自己的东西。

先说清楚一个基本判断：CLI 是 Agent 时代最被低估的接口形态。原因很简单，它天然具备三个特性——文本输入输出、可组合、可进程隔离。这三点恰好是 Agent 调用工具时最需要的。GUI 要靠截图和坐标点击，API 要处理鉴权和结构化 schema，而 CLI 只要拼字符串、读 stdout，对模型来说理解成本最低。所以“CLI-Anything”这个方向，本质上是在给 Agent 造一套通用工具层。

2. CLI-Anything 的整体设计与思路拆解

2.1 核心命题：把“任意能力”抽象成统一命令行契约

“CLI-Anything”最关键的一个设计决策，是统一契约。什么叫统一契约？就是不管你这个 CLI 背后是查数据库、调模型、画图、跑测试还是操作文件，对 Agent 暴露出来的形态必须是一致的：一个可执行命令名、一组参数、一个标准输出、一个退出码。Agent 不需要知道你内部是 Python 还是 Go 写的，也不需要知道你连的是 MySQL 还是本地文件，它只需要知道“我执行这条命令，拿到结果，判断成功失败”。

这个思路的价值在于解耦。Agent 的编排逻辑和具体工具实现彻底分开。今天你用某个脚本查数据，明天换成另一个服务，只要 CLI 契约不变，Agent 那侧一行代码都不用改。我见过太多项目把工具调用写死在 Agent 代码里，结果换一个数据源就要重构一遍，这就是没有抽象层的代价。

具体到契约设计，我一般会固定这么几个约定：命令名用短横线小写（比如>text-stats/ bin/ text-stats # 入口 wrapper src/ main.py # 实际逻辑 schema.json # 参数 schema requirements.txt

第二步，写schema.json：

{ "name": "text-stats", "description": "统计文本的字数、词数、句子数", "params": [ {"name": "input", "type": "string", "required": true, "desc": "待统计的文本内容"}, {"name": "format", "type": "string", "required": false, "default": "json", "desc": "输出格式，json 或 text"} ] }

第三步，写main.py，核心是参数解析、逻辑处理、输出格式化三段：

import sys, json, argparse def main(): parser = argparse.ArgumentParser() parser.add_argument("--input", required=True) parser.add_argument("--format", default="json") args = parser.parse_args() text = args.input result = { "chars": len(text), "words": len(text.split()), "sentences": text.count(".") + text.count("!") + text.count("?") } if args.format == "json": print(json.dumps(result, ensure_ascii=False)) else: print(f"chars={result['chars']} words={result['words']} sentences={result['sentences']}") if __name__ == "__main__": try: main() except Exception as e: print(json.dumps({"error": str(e), "code": 1}), file=sys.stderr) sys.exit(1)

第四步，写 wrapperbin/text-stats：

#!/bin/bash DIR="$(cd "$(dirname "$0")/.." && pwd)" export TMPDIR="${TMPDIR:-/tmp}" exec python3 "$DIR/src/main.py" "$@"

这套结构跑起来之后，Agent 侧只要执行text-stats --input "hello world"就能拿到{"chars": 11, "words": 2, "sentences": 0}。契约完整，解析简单。

4.2 把 CLI 注册进 CLI-Hub

有了 CLI，下一步是让它被 Agent 发现。CLI-Hub 的核心是一个清单文件，我一般叫hub.json，放在固定路径下：

{ "tools": [ { "name": "text-stats", "path": "/opt/cli/text-stats/bin/text-stats", "schema": "/opt/cli/text-stats/schema.json", "tags": ["text", "analysis"] } ] }

Agent 启动时读这个文件，把每个工具的 schema 转成自己的工具描述。转换逻辑很简单：遍历 params，拼成一段自然语言描述，比如“text-stats：统计文本的字数、词数、句子数。参数 input（必填，字符串）：待统计的文本内容；参数 format（可选，字符串，默认 json）：输出格式”。

这段描述直接塞进 Agent 的 system prompt 或者工具列表里，模型就能知道有这个工具、怎么调。新增工具只需要往hub.json里加一条，Agent 重启后自动生效，不用改代码。

4.3 Agent 侧的工具调用编排

Agent 侧我一般用一个统一的run_cli函数来执行所有 CLI：

import subprocess, json def run_cli(tool_name, params, timeout=30): tool = load_tool(tool_name) cmd = [tool["path"]] for k, v in params.items(): cmd.extend([f"--{k}", str(v)]) try: proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout) except subprocess.TimeoutExpired: return {"ok": False, "error": "timeout", "code": -1} if proc.returncode != 0: return {"ok": False, "error": proc.stderr.strip(), "code": proc.returncode} try: return {"ok": True, "data": json.loads(proc.stdout)} except json.JSONDecodeError: return {"ok": True, "data": proc.stdout.strip()}

这个函数做了几件事：拼命令、执行、超时保护、退出码判断、输出解析。Agent 拿到{"ok": True, "data": ...}就知道成功了，拿到{"ok": False, ...}就走错误处理。这套封装让 Agent 的编排逻辑非常干净，不用关心每个 CLI 的细节。

编排层再往上，就是多 agent 协作了。一个 Agent 负责规划，调用text-stats分析文本；另一个 Agent 负责决策，根据分析结果决定下一步。它们共享同一个 CLI-Hub，各自调用自己需要的工具。这就是热搜词里“多 agent 协作”和“agent 框架”的落地形态。

4.4 参数计算与超时策略的实际取舍

超时时间怎么定？我一般按工具类型分档：纯计算类 10s，网络请求类 30s，模型调用类 120s。这个分档不是拍脑袋，是根据实际 P99 耗时定的。纯计算类超过 10s 基本就是死循环了，早点杀掉；模型调用类本身就可能跑一分钟，给太短反而误杀。

重试策略也要配合退出码。退出码 2（参数错误）不重试，直接让 Agent 改参数；退出码 1（通用错误）重试一次；退出码 3（依赖缺失）不重试，报告环境问题。这套策略实测下来能避免大量无效重试，节省时间和 token。

注意：超时杀掉进程后，一定要清理子进程。有些 CLI 会 fork 子进程，主进程被杀子进程还在跑，时间长了会堆积。用subprocess的进程组或者killpg处理。

5. 常见问题与排查技巧实录

5.1 安装类问题：找不到二进制或运行时

热搜词里那个unable to locate the codex cli binary or required runtime components是最高频的问题。这类报错本质是PATH 或者运行时缺失。排查顺序我一般这么走：

Windows 上那个node_modules\@opencode\cli\bin\opencode.exe 与你运行的 windows 版本不兼容就是典型的架构不匹配。解决办法是确认你的系统架构，下载对应版本，或者用源码方式安装。Mac 上用 Claude CLI 配 Qwen key 这类场景，问题往往出在环境变量没传进去，wrapper 里要显式 export。

5.2 执行类问题：Agent 执行中途终止

agent execution terminated due to error这个报错信息很泛，得看上下文。我的排查经验是分三层：第一层看 CLI 本身能不能独立跑通，脱离 Agent 手动执行一次；第二层看 Agent 传的参数对不对，把实际命令打印出来；第三层看是不是超时或者内存问题。

大部分情况下问题出在第二层——Agent 拼的参数格式不对。比如日期格式、路径带空格、特殊字符没转义。解决办法是在run_cli里加参数校验，拼命令前先按 schema 检查类型和格式，不合法就直接返回错误，不要让错误命令真的执行。

5.3 输出类问题：解析失败或结果异常

输出解析失败通常有三个原因：输出混入了日志、输出被截断、编码问题。日志问题靠 stdout/stderr 分离解决；截断问题靠--limit控制；编码问题统一用 UTF-8，wrapper 里设PYTHONIOENCODING=utf-8。

还有一种隐蔽情况是输出顺序问题。有些 CLI 是异步打印，结果和日志交错，解析时就会乱。解决办法是让 CLI 把结果写到临时文件，最后一次性输出，或者用明确的标记符包裹结果，比如===RESULT===和===END===，解析时只取标记之间的内容。

5.4 环境类问题：跨平台与依赖冲突

跨平台是 CLI 的老大难。我的经验是能用脚本就不用二进制，脚本跨平台成本低。必须用二进制时，按平台分目录存放，wrapper 里根据uname选择对应版本。

依赖冲突的根治办法是环境隔离。每个 CLI 独立 venv 或者独立容器，绝不共享。我见过两个工具因为依赖同一个库的不同版本，互相覆盖导致轮流挂掉，排查了半天才发现。隔离之后这类问题彻底消失。

提示：wrapper 里加一行版本检查，比如python3 -c "import sys; assert sys.version_info >= (3,9)"，环境不对直接报错，比跑到一半失败好排查得多。

6. 从单 CLI 到 Agent 工具生态的扩展思路

6.1 工具分类与命名空间

工具多了之后要分类。我一般按领域分命名空间，比如text-*、img-*、>