聊一个我自己折腾了一段时间的项目，名字叫CLI-Anything。简单说，它就是一个跑在终端里的“全能命令行助手”——你给它一句自然语言指令，它负责拆解需求、调用对应工具、执行完再汇总结果给你。听起来像 AI 编程助手的终端版，但它的定位更野：不只想帮写代码，而是想接管你在终端里的一切操作。

这东西适合谁？三种人最需要：一是天天泡在终端里的开发者和运维，二是想把手动操作流程固化成自动化脚本但不想写复杂代码的人，三是纯粹对“用自然语言驱动电脑”这件事感兴趣的技术爱好者。我自己属于第一种，用了大概两个月，中间踩了不少坑，今天把完整的设计思路、实现方案和实操技巧都摊开讲清楚。

核心玩法就一条：自然语言进，命令结果出。后面的内容会涉及 CLI 工具架构、AI 意图解析、工具注册机制、上下文管理和错误自动恢复，每个模块我都会给出可以直接复制的方案。

1. 先拆核心：CLI-Anything 到底想解决什么问题

1.1 终端操作的常态痛点

我们平时用命令行，等于在跟一堆完全不讲道理的工具打交道。git有它自己的参数体系，docker有一套，awk、jq、ffmpeg又各玩各的。一个功能的完整操作链路往往横跨三四个工具，比如“把服务器上的 Nginx 日志里最近一小时 5xx 状态码的请求 IP 统计出来”——这句人话要翻译成命令，至少涉及ssh、grep、awk、sort、uniq五条管道，中间任何一步参数写错，输出就是一团乱码。

CLI-Anything 想干的事，就是把“人话”和“命令”之间的翻译工作自动化。它内部维护了一套工具注册表，每个工具都有声明好的功能描述、参数结构和输出格式。收到自然语言请求后，底层模型负责把请求映射到工具调用链路上，然后逐条执行并把结果反馈回来。整个过程用户不需要知道jq的过滤语法，也不需要记ffmpeg那一长串编码参数。

1.2 与现有方案的本质区别

市面上并不缺终端 AI 工具，OpenAI 的 Codex CLI、各种 shell 的 AI 插件都在做类似的事。但我在实际对比后，发现它们普遍存在两个问题。

第一个问题是“过度聚焦代码”。很多工具的核心场景是“帮我写一段 Python 脚本”或“解释这行命令什么意思”，对于“批量重命名文件并生成日志”“监控某个端口并在异常时自动重启服务”这类日常运维诉求，支持力度明显不够。CLI-Anything 的出发点不是写代码，是操作电脑——一切能在命令行完成的事，都是它的领地。

第二个问题是“单轮交互”。大多数工具的对话是打一次响一次，上一轮跑出来的结果不会自动沉淀下来供下一轮参考。CLI-Anything 在设计时特意做了一套会话上下文机制，每轮执行结果、产生的临时文件路径、重要的环境状态都会被记录到上下文中。你可以说“刚才那批文件里，把大小超过 10MB 的挑出来再压缩成 tar.gz”，它会顺着前一轮的结果继续操作，而不是让你重新描述一遍文件在哪里。

1.3 核心能力边界

在动手实现之前，先明确它到底能管多远。我按“值不值得自动化”和“模型能不能可靠理解”两个维度筛了一遍，最终圈定三个核心能力域：

这三类场景的共同点是：操作模式相对固定，但参数千变万化。正好适合模型来做参数映射和命令组装。

2. 为什么我选了“本地模型为主、云端模型为辅”的架构

2.1 工具调用的核心：结构化协议

CLI-Anything 的第一步设计，是给每个可调用的工具定义一个结构化声明。这个声明包含工具名称、一句话功能描述、参数列表（每个参数的类型、必填性、说明）、返回值结构。模型看到这份声明后，就知道在什么场景下该调用什么工具、参数该填什么值。

实际我用的声明格式长这样，用 JSON 描述，简单直接：

{ "name": "file_find", "description": "在指定目录下按名称模式查找文件，支持通配符", "parameters": [ {"name": "path", "type": "string", "required": true, "description": "起始目录路径"}, {"name": "pattern", "type": "string", "required": true, "description": "文件名匹配模式，如 *.log"}, {"name": "max_depth", "type": "integer", "required": false, "default": 3, "description": "递归深度限制"} ], "output": {"type": "list", "items": {"type": "string", "description": "匹配到的文件绝对路径"}}, "command_template": "find {path} -maxdepth {max_depth} -name \"{pattern}\"" }

关键在command_template这一栏。它预置了命令的固定部分，模型只需要填参数值，不用凭空捏造一个复杂命令。这大大降低了模型“发挥创意”导致命令错误的概率。模型要生成的全部东西，就是一份 JSON 形式的调用参数。

2.2 双通道模型策略

有了声明和模板，接下来就是谁来解析意图的问题。我在实践中试了三条路线：

第一条是纯云端模型。用 GPT 或 Claude 的 API 做意图识别和参数抽取，效果确实好，但有两个硬伤：命令内容明文出网，公司内网环境直接用不了；每次调用都有网络延迟，简单的“列出当前目录最大的三个文件”也要等两秒才能出现结果，交互体验很割裂。

第二条是纯本地小模型。用 Qwen 或 Llama 的 7B 量级本地模型跑推理，隐私和速度问题都解决了，但意图理解能力明显弱一截。复杂一点的指令，比如“找出 bin 目录下最近三天改动过的所有 PHP 文件，按大小排序并输出前十个”，本地小模型经常把参数填错或者漏掉某个条件。

第三条就是最终采用的双通道方案：核心调度用本地模型，复杂指令二级确认时访问云端模型。日常的简单操作全部本地完成，只有本地模型判定“这句话的意图置信度低于阈值”时，才把请求转发给云端模型做兜底解析。实测下来，约 70% 的指令可以在本地直接搞定，剩下 30% 需要二级确认的，准确率也能保持在 95% 以上。

2.3 架构总览

最终形成的结构分四层：

1. 交互层：终端 TUI 界面，接收用户输入，展示执行结果和执行过程；
2. 调度层：意图识别、参数抽取、工具匹配、调用序列编排；
3. 执行层：实际运行命令、捕获输出、处理超时和错误；
4. 上下文层：记录会话历史、文件状态、执行结果摘要，供调度层参考。

层与层之间全部通过 JSON 结构传递数据，方便调试也方便替换组件。比如你不想用本地模型，可以直接把调度层换成 OpenAI API；不想用find工具，重新声明一个fd工具的 JSON 就行。

3. 实操：从零把 CLI-Anything 跑起来

3.1 环境准备与安装

整个项目我用的 Python 3.11，核心依赖只有三个：ollama用于拉起本地模型服务，rich负责终端界面美化，paramiko处理可选的远程 SSH 执行能力。数据库层直接用 SQLite，存储对话历史和执行记录，不需要单独装服务。

基础安装步骤：

# 1. 克隆项目并安装依赖 git clone https://github.com/your-repo/cli-anything.git cd cli-anything pip install -r requirements.txt # 2. 确保本地有 ollama 服务，拉取一个模型 ollama pull qwen2.5:7b # 3. 修改配置文件 config.yaml # 核心配置项： # model_provider: local (可选 cloud) # local_model_name: qwen2.5:7b # cloud_api_key: sk-xxx (留空则纯本地模式) # tool_repo_dir: ./tools

装完后第一件事不是直接对话，而是跑一遍自带的工具扫描命令cli-anything scan-tools，它会遍历tools目录下所有 JSON 声明文件，检查格式合法性、命令模板是否能被解析、参数名是否和模板里的占位符对齐。这一步能提前发现很多低级错误，比如command_template里写了{path}但参数定义里叫{dir}，这种不一致不检查的话，到执行的时候才报错，很难排查。

3.2 配置语言与工具声明

CLI-Anything 的工具声明直接放在tools目录下，以.json文件形式存在，想添加工具能力就丢一个 JSON 进去，不需要改任何代码。以我常用的日志分析工具为例，完整声明如下：

{ "name": "log_analyze", "description": "分析日志文件中的错误模式和出现频率", "parameters": [ {"name": "file", "type": "string", "required": true, "description": "日志文件路径"}, {"name": "level", "type": "string", "required": false, "description": "日志级别，可选 error/warn/info"}, {"name": "time_range", "type": "string", "required": false, "description": "时间范围，如 last_1h、today、yesterday"} ], "command_template": "grep \"{level}\" {file} | awk '{print $1, $2, $NF}' | sort | uniq -c | sort -rn | head -20", "output_parser": "table", "timeout_seconds": 10 }

注意command_template里的$NF和双引号，在 JSON 字符串里必须转义，这是新手最容易踩的坑。我早期写过一个模板，awk '{print $1}'里的单引号没转义，导致 JSON 解析直接失败，整个工具目录加载不出来。

声明文件的output_parser字段也值得展开说。它决定了执行完命令后展示成什么格式。目前支持三种：

• raw：原样输出文本；
• table：按列进行对齐展示，适合多维数据；
• json：把输出按 JSON 解析并格式化高亮。

模型在生成工具调用时，会带上期望的输出格式，这样后端执行完能自动切换渲染方式。我建议每个工具都尽量声明table或json，原始文本输出在终端里一片糊，真正用起来眼睛受不了。

3.3 核心流程的代码骨架

调度层的核心逻辑其实不复杂，去掉界面和异常处理，整个主循环可以浓缩成一段伪代码：

def handle_user_input(user_text, session_context): # 1. 加载工具声明列表 tools = load_tool_repo("tools/") tool_schemas = [t.schema for t in tools] # 2. 调用本地模型，让模型输出工具调用和参数 response = local_model.chat( messages=[ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": user_text}, ], tools=tool_schemas, tool_choice="auto", ) # 3. 如果模型没有调用工具，直接回复文本 if not response.tool_calls: return response.content # 4. 逐个执行工具调用 results = [] for call in response.tool_calls: tool = get_tool(call.name) if tool is None: results.append({"error": f"tool not found: {call.name}"}) continue # 关键：把模型填的参数和模板占位符做严格校验 validated_args = validate_args(tool.parameters, call.arguments) command = render_template(tool.command_template, validated_args) # 5. 执行命令，捕获输出、退出码、运行时间 exec_result = run_shell(command, timeout=tool.timeout_seconds) results.append(exec_result) # 6. 汇总结果写入上下文，再回复用户 session_context.append({"user": user_text, "results": results}) return summarize_results(results)

这里要特别强调第 4 步的validate_args。不能让模型说什么就是什么，必须对照工具声明的参数类型和必填性做校验：max_depth给了字符串就转成整数，time_range出现枚举范围之外的值就直接拒绝，并让模型重新生成。我见过不少情况是模型把level=ERROR写成了level=2，然后grep用了个荒谬的模式去匹配，浪费一次执行机会。

3.4 会话上下文如何保持

上下文是 CLI-Anything 比普通 shell 插件强的地方，也是实现细节最多的模块。它保存三类历史信息：

• 自然语言对话历史：最近 20 轮的用户请求和助手回复；
• 命令执行摘要：每条执行过的命令、退出码、输出第一行摘要；
• 轻量状态变量：上次操作涉及的文件路径、目录、进程 ID 等。

这三类信息会在下一轮请求时作为额外上下文交付给模型。具体做法是把状态变量转成一段伪 Python 代码注入 system prompt，让模型知道“当前工作目录是 /home/user/projects/web，刚才操作的日志文件路径是 /var/log/nginx/access.log”。

实际效果举个例子。我先说“看看项目根目录下有哪些 .py 文件”，执行完成后上下文里就有last_searched_path=/home/user/projects/web和一批文件列表。紧接着说“把其中文件名带 test 的删掉”，模型会基于上一轮提到的路径列表去做匹配，而不是重新全盘搜索一遍。没有上下文的话，第二句话基本就是耳旁风，模型只能瞎猜文件在哪。

4. 模块级设计：工具注册表、执行沙箱与错误恢复

4.1 工具注册表的加载与热更新

工具注册表不是一次性加载完就完事的。我开始做的时候，每次增删工具 JSON 都要重启进程，特别烦躁。后来改成了文件监听 + 哈希比对的机制：启动时扫描一次目录，之后每隔 5 秒对比每个文件的 MD5，变化了就重新加载整个注册表并通知调度层刷新。

热更新的好处不只是开发方便。实际运维时，你可以在不改主程序的情况下，给某个工具声明里加一条更安全的命令模板，或者调整timeout_seconds的值，改动即刻生效，会话都不用断。这对需要长时间驻留的终端工具来说非常重要。

注册表加载时还会做一项静态检查：命令模板里的占位符是否都能在参数列表中找到对应项。找不到的会直接拒绝加载，并把错误信息输出到日志。这一步拦住了一大半手滑写错的模板。

4.2 执行沙箱与权限控制

命令执行不能是裸奔的。CLI-Anything 默认情况下不会直接拿当前用户的所有权限去跑模型生成的命令，我给它加了三层保护：

第一层是工具白名单。没有在注册表里声明的命令一律不执行，模型没有资格直接拼任意 shell 字符串然后扔给os.system。要扩展能力，先写 JSON 声明，人工确认过模板没有恶意风险，才会被纳入可执行范围。

第二层是参数合法性校验。除了类型必填之外，每个参数可以声明一个allowed_pattern正则。比如文件路径参数强制要求只能匹配[\w./\-]，杜绝;|&&这类注入符号。模型再鬼也没有用，模板里根本没有执行任意 shell 语法的位置。

第三层是工作目录隔离。所有工具命令默认在一个指定的临时工作目录里执行，切到别的目录需要显式使用cd_workspace工具并经确认。这层能有效避免命令在用户完全没预期的目录里乱改文件。

当初加这套沙箱，是因为我遇到过一个真实事故：模型在解析“把日志文件归档”这句指令时，不知道从哪里理解的路径，生成的命令直接把整个家目录下的文件用mv挪走了，幸好我当时开了目录隔离并且提前做了确认，不然后果很严重。

4.3 错误识别与自动重试策略

模型生成的命令出错率再低，也不可能为零。CLI-Anything 的错误处理逻辑不是简单把 stderr 抛给用户，而是做了一层错误语义解析，然后决定下一步动作。

我实现了一个错误分类器，针对常见的命令失败场景，规则如下：

这层处理的价值在于，把“命令报错”这件事从单纯的展示层面提升到了反馈闭环。模型收到错误信息后，会基于错误类型重新调整参数或换一个工具，整个过程用户看到的就是“第一次没找到文件，自动换了个路径，成功执行了”。而不需要自己盯着报错信息猜半天。

5. 踩坑实录：试运行两个月后的真实问题排查

5.1 本地模型意图理解的“小聪明”陷阱

本地 7B 模型和 GPT 级别的模型比，最大的差异不是知识量，而是对齐程度。GPT 在生成工参时非常稳，基本不会多填字段；Qwen 7B 这个量级的，则经常做一些不必要的“聪明”操作。

我遇到的最典型的一个：用户说“统计一下错误日志里的行数”，正确做法是工具调用log_analyze传file=/var/log/nginx/error.log。但本地模型某次直接生成了wc -l /var/log/nginx/error.log这种自由发挥，绕过注册表，企图直接执行它自己构造的命令。这正是我前面说“模板占位符 + 参数校验”这套沙箱要拦的重点。

排查这类问题的思路是：打开调试模式，打印模型生成的完整 response 结构。你很快会发现，小模型在 tool calling 的arguments里偶尔会出现未被声明的字段，或者把boolean值写成字符串。最好的应对不是提高模型温度或者换更大的模型，而是在 system prompt 里写死一句“你只能调用提供的工具，禁止直接构造 shell 命令”，反复强化之后错误率能降一半以上。

5.2 上下文爆炸与策略裁剪

对话超过一定轮数后，上下文管理开始出现问题。最直接的现象是：模型开始“忘记”早期的工具执行结果，或者回答速度明显变慢。这是因为每一轮我都把执行结果的完整输出塞进上下文，攒了 20 轮之后，光历史文本就有几万字，7B 模型的输入窗口根本吃不下。

解决思路分两步。

第一步是摘要压缩。每次工具执行完毕后，不是把原始 stdout 全部存进会话历史，而是生成一条摘要。数字类结果只保留最大值、最小值、总条数，文件类结果只保留文件名和绝对路径，长文本截断为前 200 字。原始输出另存到 SQLite，需要看细节时再翻出来。

第二步是滑动窗口。上下文里最多保留最近 10 轮对话，超过的部分逐出。逐出不是直接扔掉，而是把其中涉及的关键路径、进程号、临时文件位置提取到“长期状态变量”里继续保留。这样模型永远能看到最近的操作全景，同时不会被大量历史输出淹没。

5.3 命令模板的“跨平台”幻觉

很多工具命令在 macOS 和 Linux 上的表现完全不同。find -maxdepth在 macOS 上需要改成-d，awk在不同 BSD 版本上的行为也有差异。CLI-Anything 的模板系统里有platform字段，可以在声明中指定该模板适用于哪些平台。

我一开始没做这个区分，结果同一套工具声明在 macOS 上跑得好，到 Linux 服务器上直接报语法错误。现在的做法是：每个工具的声明里可以有多个command_template_variants，按平台名索引。调度层在渲染模板前先查一下当前系统平台，选对应的变体；没有匹配的就直接提示该工具在当前平台不可用，而不是硬跑然后报错。

5.4 超时设置的“三秒定则”

最后分享一个耗时踩出来的经验：超时时间别用拍脑袋的值。我给每个工具加了一个timeout_seconds字段，并总结了一套定则。

常规文件查找类工具，3 秒够了；日志分析类工具，看文件大小，小于 10MB 给 5 秒，更大的建议先走head截断再分析；涉及网络下载或镜像构建的命令，至少给 30 秒。超时太短会导致长任务莫名其妙被腰斩，超时太长又会让用户感觉整个工具卡死了。我的做法是先设一个保守时间，跑几个真实场景记录真实耗时，然后按“真实耗时的 1.5 倍”来定值。

6. 写在最后：这个方向还能怎么延伸

CLI-Anything 后续我计划加两个方向的能力。一是多步任务编排，现在已经有了单步工具调用的能力，但像“每周日凌晨三点清理 /tmp 下三天前的临时文件并把结果发到邮件”这种带条件分支的定时任务，还需要一套真正的工作流引擎支持。二是跨主机的远程执行，借助paramiko把工具执行能力延伸到远程服务器，实现“本地说一句话，远程自动完成部署和检查”。

最后说说我个人用下来的体会。做这个项目最大的收获不是代码量，而是理解了一个道理：CLI 工具的传统使用方式是“人能做什么，命令就做什么”；而配上 AI 解析层之后，边界变成了“人能描述什么，命令就能做什么”。描述比记忆简单太多，这件事本身就值得做。如果你也是每天一堆重复命令在手敲，建议从这个思路出发，先挑两三个最常用的工具写成 JSON 声明，跑通一次完整的自然语言调用链路，你会发现终端突然变得比以前懂事很多。