1. 为什么非要 CLI——大模型时代的工具调用困境先说我观察到的现象身边的开发者和非开发者都在用 AI Agent 处理杂事但几乎所有人都会撞上同一堵墙——AI 能“看懂”你的需求却“伸不出手”去操作软件。大多数桌面软件、老牌工具、行业专用程序只提供了图形界面别说开放 API连个像样的自动化接口都没有。而另一边大语言模型天然擅长的是文本生成、语义理解它没法直接挪动鼠标去点按钮也没法读懂屏幕上的像素内容。这个矛盾让我意识到真正缺的不是更强的模型而是一层让 Agent 与现有软件对话的桥。也正是出于这个想法我开始折腾 CLI-Anything一个把“所有软件”都变成 AI Agent 可原生调用的工具的方案。这里说的“原生调用”不是让它截屏后“看”界面来操作而是给每个软件配一套结构化的命令行访问入口再让大模型把自然语言请求翻译成标准命令。这样 Agent 就能像调用函数一样指挥任何一个程序。其实这条路有一个反直觉的结论GUI 反而是障碍CLI 才是答案。下面我详细讲讲我的思路、架构和一个能跑的极简实现最后再把我踩过的坑一次性列出来。这篇东西适合三种人想把本地工具接入 AI 工作流的爱折腾型选手、正在做 Agent 产品但卡在“工具接入”环节的开发者以及单纯好奇“LLM 到底怎么控制电脑”的读者。1.1 从 GUI 到 CLI 的一次认知升级先别急着把“图形界面”踩到地上它对人当然是友好的。问题出在 AI 这边。一个能熟练操作 Photoshop 的人靠的是多年积累的视觉经验和手眼协调但让大模型通过视觉定位按钮、猜测菜单层级、处理弹窗阻断每一步都是巨坑。不信你可以做个实验让一个 Agent 通过屏幕截图去操作某个绘图软件让它“把画布背景改成浅灰色”。模型需要先找到背景设置入口再识别颜色选择器期间任何弹窗、鼠标悬停变化、界面缩放都会导致定位失败。哪怕每一步都做对速度也慢得让人崩溃。反过来如果这个软件有一个命令行版本或者有人给它包了一层命令行适配器事情就变成了toolname set-bg --color e5e5e5一行命令确定、可控、可以重复执行。我们再让大模型负责“翻译意图 填参数”它只需要根据工具描述生成正确命令。这个思路的底层逻辑是语言模型最擅长的是处理文本和结构化数据CLI 恰好就是结构化的文本协议。不要求模型具备视觉能力不依赖 UI 坐标只要描述清楚“有什么工具、每个工具能干什么、参数是什么”模型就能稳定输出调用。我在实际测试中发现同一批任务走“读屏 模拟鼠标”的准确率经常在 70% 上下波动而走“自然语言转命令”的准确率可以稳定到 95% 以上。差距不是模型聪明与否而是问题形态根本不匹配。1.2 为什么说 CLI 是 Agent 时代的“标准插头”把电脑比作一个装满家电的房间AI Agent 是遥控器而各个软件就是电视、空调、音响。如果每个家电都有自己的遥控协议遥控器就得内置无数套规则任何一种新电器出来都要升级。但如果所有电器都统一用某种标准插头事情就简单了。CLI 就是那个事实上的标准插头。几乎所有正经软件哪怕只有 GUI底层也多半存在命令行入口或脚本化能力。即便是纯 GUI 程序也可以通过辅助工具包一层“命令行外壳”。而且 CLI 有一个天然优势它是长文本的、可拼接的、可编程的。这意味着 Agent 不仅可以执行单条命令还能把多条命令组合成流水线甚至根据前一步输出决定下一步动作。这在 GUI 场景里几乎不可能做到。所以我的结论是与其费劲教模型“看界面”不如花力气把软件的“操作面”重构成 CLI。这就像一个翻译官把人类自然语言翻译成软件能理解的执行动作。CLI-Anything 正是这个翻译官的系统化实现。2. 整体架构与设计思路把“调用”变成“协议”很多人第一次听到“让 AI 调用软件”第一反应是“直接让大模型生成 shell 命令不就行了”我在初期也这么干过让模型自由发挥写命令然后丢给终端执行。结果显而易见模型会编造不存在的参数、用错命令语法、甚至在一个危险操作上给我“自信满满”地执行。后来我彻底否定了这种“裸奔”方案转向协议化封装——不是让模型自由写命令而是给每个工具定义一套结构严谨的调用协议模型只负责在协议框架内填参数。整个系统分四层工具注册层、意图解析层、命令执行层、结果回传层。先说整体架构长什么样。我用一个简单的进程内调度器把四层串起来每个被接入的软件都声明成一个“工具”声明内容包括工具 ID、一句话描述、参数定义、调用示例、安全约束。Agent 收到用户需求后先从工具清单里找到匹配项再按参数定义生成结构化调用最后执行并返回结果。示意图不值得画文字很好理解注册表决定“有什么可用”调度器决定“怎么调用”执行器决定“能否安全落地”。2.1 工具注册给 Agent 一份“能力清单”工具注册是整个系统的地基。每个工具的声明必须精确到“参数名、类型、可选值、默认值”不能留模糊空间。我用 YAML 来写这份清单因为它的可读性最好既能给人看也能快速转成 JSON 喂给大模型。举个例子我接入过一个老旧的图像批处理软件它没有 API但提供了一个命令行 exe。我给它的注册描述长这样id: image_resizer description: 批量调整图片尺寸支持常见图像格式输出到指定目录 parameters: - name: input_dir type: string required: true description: 存放原始图片的文件夹路径 - name: width type: integer required: true description: 目标宽度像素值必须大于 0 - name: height type: integer required: true description: 目标高度像素值必须大于 0 - name: keep_ratio type: boolean default: false description: 是否保持原始宽高比为 true 时忽略 height examples: - 把 /tmp/pics 里的图缩到 800 宽保持比例 call: image_resizer --input /tmp/pics --width 800 --keep-ratio true这份清单最关键的地方在description和examples两处。description决定模型能不能正确找到这个工具examples则像给模型做了一次示范让它知道“这类说法应该翻译成那种调用”。我后来还发现示例的数量和质量比参数描述的详细程度更能影响调用准确率所以每个工具至少配三到五个典型示例覆盖“简单请求、带细枝末节的请求、容易混淆的写法”。另外每个工具都要显式声明安全约束比如执行目录白名单、禁止删除操作、超时上限。这部分不是给模型看的是给执行器做硬校验用的。模型可能给出合法但危险的参数执行器必须拦截。2.2 意图解析与参数绑定最关键的“翻译”环节有了工具清单接下来就是让大模型把用户的话翻译成结构化调用。这一步很容易做歪我反复调出来的稳定做法是不要求模型直接输出 shell 命令而是先输出一段 JSON。JSON 里包含工具 ID 和参数表再由调度器转换成实际命令。为什么绕一道因为 JSON 是结构化数据方便校验也方便在出问题时定位是“模型填错参数”还是“命令执行失败”。比如用户说“帮我把桌面上的照片都缩小一半”模型应该输出{ tool: image_resizer, parameters: { input_dir: /home/user/Desktop, width: null, height: null, keep_ratio: true, scale: 0.5 } }模型在翻译时可能会漏掉某个参数或者把“一半”直接误解为固定的 500 像素。为了减少这类问题我在提示词里做了三个约束第一用户没说具体数值时必须标出来不能自作主张补默认值第二参数类型必须严格匹配声明比如整数参数不能填字符串第三任何不确定的映射都要输出到ambiguous_fields字段由下游再向用户确认。这套机制跑下来误填参数的比例明显下降。不过“翻译”环节还有一个隐蔽的坑模型会根据工具描述里的相似词“幻觉”出不存在的参数。例如工具明明只支持width和height模型却因为用户提到“质量”而输出一个quality参数。解决的办法有两个一个是在提示词里强调“只能使用参数定义列表里的字段”另一个是在校验器中增加“未知字段拒绝”的硬规则。2.3 执行安全边界这条底线不能松命令执行层是整套系统里最需要敬畏的部分。直接让模型生成的命令在系统里跑等于把钥匙交给一个喝了三杯咖啡的实习生他可能很努力但偶尔会闯祸。我踩过一次深刻的教训某次测试时模型把用户说的“清理临时文件”翻译成了删除一整个目录差点把缓存里的其他东西清理掉。安全设计从三个层面同时进行。第一层是参数白名单每个工具声明允许的路径前缀、允许的文件类型、禁止触达的目录。第二层是命令模板不是把 JSON 里的值直接拼进 shell 命令而是通过子进程的参数数组传递避免任何可能被解释为 shell 语法的内容混进来。第三层是权限降级执行器尽量以当前用户运行绝不使用 sudo对危险操作单独二次确认。我强烈建议在执行层前加一道“预演模式”。所谓预演就是把命令跑一遍但不真正改文件只输出将要执行的动作和影响范围。等 Agent 确认无误后再执行正式版本。这个机制在接入真实工作环境时几乎是必需品因为模型偶尔会误解用户的意图预演能给流程留一个纠错机会。3. 核心实现手写一个极简 CLI-Anything 代理纸上谈兵到此为止下面直接上代码。我用来做演示的载体是一个 Python 脚本依赖很轻模型调用接口用普通的 OpenAI 兼容接口命令执行用 Python 标准的subprocess模块。为了不让代码篇幅超出控制我把演示聚焦在三件事上定义一个工具、让模型输出结构化调用、安全执行这个调用。3.1 定义第一个被封装的实际工具我先选了一个轻度工具来演示一个图片尺寸查询程序。大家可以类比理解成“任意一个仅有命令行入口的软件”。它的原始调用方式是这样的img-info /path/to/image.png输出是纯文本格式的尺寸信息。接入 CLI-Anything 后我们把它声明为工具注册到一个简单字典里TOOLS { image_info: { description: 获取图片的基础信息包括宽高、格式、大小, parameters: { type: object, properties: { path: {type: string, description: 图片文件的绝对路径} }, required: [path] }, command: [img-info], # 实际执行的命令列表 } }这里的command是执行器唯一允许拼接的内容。模型输出的参数会被塞到command后面但不会以字符串拼接的方式进入 shell这正是后面要讲的安全细节。3.2 让模型输出规范化调用有了工具清单接下来写调度函数。它的职责是把用户自然语言请求、可用工具描述、输出格式要求一并交给模型拿到 JSON 后做校验。为了让输出稳定我采用 JSON 模式约束。def parse_intent(user_input): system_prompt 你是工具调度器。根据用户请求从下列工具中选择一个并生成调用参数。 工具列表 {tool_descriptions} 输出格式必须严格为 JSON {{tool: 工具id, parameters: {{...}}, ambiguous_fields: [不确定的参数名]}} 只能使用工具声明中出现的参数禁止添加额外字段。 .format(tool_descriptionsjson.dumps(TOOLS, ensure_asciiFalse)) response model_chat( messages[{role: system, content: system_prompt}, {role: user, content: user_input}], response_format{type: json_object} ) return json.loads(response)这段代码落实了两件事。第一所有工具能力一次性传给模型模型不用“猜”有哪些工具。第二强制 JSON 输出把自由文本的生成变成了结构化填空。实际测试中加上response_format之后解析失败率从偶尔出现降到了几乎为零。3.3 执行命令与回传结果安全地跑起来得到 JSON 调用后执行器开始干活。核心有两点用参数数组方式传入子进程而不是拼命令字符串捕获退出码、stdout 和 stderr 并一起回传给调用方。import subprocess def execute_tool(tool_id, params): tool TOOLS.get(tool_id) if not tool: return {status: error, message: 未知工具} cmd tool[command] [params[path]] try: result subprocess.run( cmd, capture_outputTrue, textTrue, timeout15, checkFalse ) if result.returncode 0: return {status: ok, output: result.stdout} else: return {status: error, message: result.stderr} except FileNotFoundError: return {status: error, message: 底层命令不存在请检查程序路径} except subprocess.TimeoutExpired: return {status: error, message: 命令执行超时}subprocess.run加checkFalse是为了不让异常中断流程而是把错误信息正常返回给模型或用户去分析。这一步很多人容易写错直接用checkTrue导致程序崩溃或者忘了捕获超时导致整个任务卡死。一个小提示命令执行环境的cwd、环境变量也要由执行器主动设置不要继承终端里的任意环境变量避免模型生成的命令意外读到你不希望它接触的配置。4. 工具选型与参数设计从零填平自动化洼地写一个 demo 容易真正要把一套软件接入生产可用关键在于两点选对要接入的工具、设计好参数。这两件事做得好后面运行就顺做得不好模型再聪明也白搭。下面把我调出来的经验顺序分享出来。4.1 什么样的工具值得接先做“高频低风险”的我第一周接入了一堆五花八门的软件后来发现真正高频被调用的只有那么几个。总结下来优先接入符合三个特征的工具操作频次高、参数固定、破坏性低。比如文件格式转换、图片信息查询、批量重命名、文本处理管线。这些工具即使调用出错后果也可控。反过来参数极度灵活、输出极度复杂的工具不适合第一波接入。比如一个参数多达几十个的 PDF 处理软件模型很容易在参数组合上出错而且出错后很难排查。我的建议是先接入十个以内的简单工具跑通了再逐步上复杂度。4.2 参数设计的三条铁律参数设计是决定调用质量的隐藏变量。我吃过亏后才总结出三条铁律每一条都有实际教训支撑。第一条参数不要多够用就好。工具本身可能有 20 个配置项但暴露给 Agent 的只留 5 个最高频的其余全部设成默认值。模型的选择空间越小出错概率越低。第二条参数名要用用户能理解的词而不是软件内部的底层字段名。比如软件内部叫src_path但用户习惯说“文件”或“图片”注册名就统一叫input_file描述里再说明支持图片格式。第三条数字型参数必须给出合理范围。大模型对数字不敏感如果不限制范围它可能会把“缩小一半”翻译成scale2而不是scale0.5。我用一个简单规则规避这个问题设计描述时把语义说清楚例如scale 取值范围 0.1~1.01.0 表示原始大小。4.3 工具描述怎么写用“最小清晰”原则工具描述不是写论文越精炼越好。我对比过两种写法效果差距很明显。描述写法示例调用准确率过虚型“处理图片支持常见格式”低模型经常匹配错工具精准型“将一组图片统一缩放、格式转换支持 jpg/png/webp输出到目标目录”高模型几乎不会用错精准型描述的关键词是“动作 对象 约束 输出位置”。动作是“缩放、转换”对象是“一组图片”约束是“支持 jpg/png/webp”输出位置是“目标目录”。这样模型只需要做一次简单的语义匹配而不是反复猜测。4.4 调用链别设计得太长最后强调一个架构层面的经验能在单次调用里完成的事就不要拆成多步。比如“获取图片尺寸”本身是一步而“获取图片尺寸后如果宽度大于 1000 就缩小”是两步。如果你把第二步也封装进工具让 Agent 一次完成判断和操作整个链路既快又稳。否则模型每一步都要做一次推理任何一步出错后面都跟着错。我在一个批量处理工具里就把“文件识别 转换 重命名 移动到归档目录”打包成了一个原子工具。这样设计以后用户一句话就能完成之前需要四个工具编排的任务Agent 的调用频率和成功率都显著提高。5. 常见问题与排查技巧实录任何系统跑起来只是开始真正折磨人的是各种边界情况。下面这些坑有的是我在测试中主动踩的有的是上线后用户义务反馈的每一条都值得记下来。5.1 模型“幻觉”参数怎么办这是出现频率最高的问题。模型在生成 JSON 时偶尔会加入工具声明里没定义的字段或者把枚举值写错。比如某个工具只支持format取jpg/png/webp模型却输出gif。我处理的办法是双保险提示词里强制约束 校验器里拒绝未知字段。校验器会做一次严格比对把模型输出的参数键和工具声明里的properties比对出现未知字段直接返回“参数错误”并附上可接受的参数列表。这让模型有机会在下一次调用中自我修正。实测下来经过一轮修正后绝大多数幻觉参数都会消失。5.2 输出乱码和编码问题很多老软件的输出编码并不统一有的是 GBK有的是 UTF-8甚至同一个程序在不同参数下输出编码不一致。直观表现是 Agent 拿到的输出是乱码导致它无法分析结果。解决办法是在执行器里增加编码探测和强制转换。我写了一个封装函数先用chardet之类的工具探测字节流可能的编码再统一转成 UTF-8。如果探测失败就把 stdout 和 stderr 都按二进制返回并给调用方提示“无法识别编码”避免 Agent 强行解读。5.3 超时和“僵尸”进程有些图形软件的命令行外壳会在任务完成后不主动退出导致subprocess.run一直阻塞到超时。更麻烦的是超时后子进程可能还留在系统里占着资源。我的处理策略分两步。第一步所有调用都必须设置超时上限宁可杀错不可等死。第二步在超时处理中先尝试终止进程组如果不行再强制 kill。在 Python 里我用start_new_sessionTrue为每个任务开启独立进程组这样超时后可以精确杀掉整个进程树不会波及主程序。5.4 路径参数含空格怎么办这是个特别接地气的坑。用户说“把 我的图片 文件夹里的照片处理一下”模型生成的路径参数大概率带着空格。如果执行层用字符串拼接命令这个路径会被 shell 拆成两段直接报“找不到文件”。我的做法是坚持参数数组模式绝不把参数拼进命令行字符串。subprocess.run接收的列表会直接传给操作系统空格是参数的一部分不会引发任何解析问题。这一点几乎所有新手都会踩建议在设计执行层的第一天就定死这个规则。5.5 如何快速定位是模型问题还是工具问题排查问题时最忌讳的就是一团乱麻。我建立了一套简单的日志规范每个环节都记录输入输出和时间。打个比方Agent 单次完整调用会生成一条链路日志包含用户原始需求、模型输出的 JSON、执行器收到的参数、命令真实退出码、输出摘要。出现问题后我直接看模型输出的 JSON 是不是符合工具定义符合再看执行器的返回码和 stderr这两段都正常才考虑是不是环境或底层程序的问题。这种“分层排查”的思路帮我省了大量时间比对着终端输出瞎猜强多了。6. 后续还能怎么玩从工具化到工作流编排接入工具只是第一步真正有意思的是把这些工具交给 Agent 去编排。我在实践中发现一个规律一旦工具数量超过 5 个Agent 就慢慢展露出“规划”能力不只是机械地调用而是会根据用户目标选择工具、排序、必要时回退重试。我最近在做的就是给工具增加“组合提示”——在工具描述里写上“这个工具通常搭配某某工具一起使用典型流程是……”。这样 Agent 在面对复杂任务时会自动生成多步工作计划而不是试图用一个工具解决一切。比如“把这一批照片缩小并压缩成 zip 发给别人”这个需求会被拆成三步图片处理、压缩打包、生成下载链接。三个工具逐个调用前一步的输出作为后一步的输入这就是工作流编排的雏形。另外有不少值得扩展的方向适合自己动手做实验把工具注册表做成动态发现从远程拉取新工具的描述不用改主程序代码给执行器增加审批模式高风险命令先发通知由人工确认后再跑对 Agent 的高频调用记录做统计识别出使用率低的工具反推是不是参数设计得不合理把 CLI-Anything 嵌入一个更大的 Agent 框架让它可以调度本身附带的子 Agent。我个人在整套系统上最大的体会是别指望模型一步到位而是通过工程手段把不确定性一点一点压下去。工具描述写得模糊就多写几个示例参数容易混淆就砍参数数量命令危险就加预演和审批。这套系统后续还能扩展成可视化工具编排平台让我真正意识到把软件变成 Agent 的“手”只是开始变成它的“工作流习惯”才是更有想象力的终点。如果让我给正在考虑接入 AI Agent 的同学一个建议那就是从最小的命令入手选一个你每天都在用、但一直无法自动化的软件给它写第一份工具声明。跑通了第一个剩下的事情就是复制经验、滚雪球。 
长河君 · 2026/10/18 11:24:45 · 阅读 1.2k 让AI Agent通过CLI调用一切软件：从工具注册到安全执行
1. 为什么非要 CLI——大模型时代的工具调用困境先说我观察到的现象身边的开发者和非开发者都在用 AI Agent 处理杂事但几乎所有人都会撞上同一堵墙——AI 能“看懂”你的需求却“伸不出手”去操作软件。大多数桌面软件、老牌工具、行业专用程序只提供了图形界面别说开放 API连个像样的自动化接口都没有。而另一边大语言模型天然擅长的是文本生成、语义理解它没法直接挪动鼠标去点按钮也没法读懂屏幕上的像素内容。这个矛盾让我意识到真正缺的不是更强的模型而是一层让 Agent 与现有软件对话的桥。也正是出于这个想法我开始折腾 CLI-Anything一个把“所有软件”都变成 AI Agent 可原生调用的工具的方案。这里说的“原生调用”不是让它截屏后“看”界面来操作而是给每个软件配一套结构化的命令行访问入口再让大模型把自然语言请求翻译成标准命令。这样 Agent 就能像调用函数一样指挥任何一个程序。其实这条路有一个反直觉的结论GUI 反而是障碍CLI 才是答案。下面我详细讲讲我的思路、架构和一个能跑的极简实现最后再把我踩过的坑一次性列出来。这篇东西适合三种人想把本地工具接入 AI 工作流的爱折腾型选手、正在做 Agent 产品但卡在“工具接入”环节的开发者以及单纯好奇“LLM 到底怎么控制电脑”的读者。1.1 从 GUI 到 CLI 的一次认知升级先别急着把“图形界面”踩到地上它对人当然是友好的。问题出在 AI 这边。一个能熟练操作 Photoshop 的人靠的是多年积累的视觉经验和手眼协调但让大模型通过视觉定位按钮、猜测菜单层级、处理弹窗阻断每一步都是巨坑。不信你可以做个实验让一个 Agent 通过屏幕截图去操作某个绘图软件让它“把画布背景改成浅灰色”。模型需要先找到背景设置入口再识别颜色选择器期间任何弹窗、鼠标悬停变化、界面缩放都会导致定位失败。哪怕每一步都做对速度也慢得让人崩溃。反过来如果这个软件有一个命令行版本或者有人给它包了一层命令行适配器事情就变成了toolname set-bg --color e5e5e5一行命令确定、可控、可以重复执行。我们再让大模型负责“翻译意图 填参数”它只需要根据工具描述生成正确命令。这个思路的底层逻辑是语言模型最擅长的是处理文本和结构化数据CLI 恰好就是结构化的文本协议。不要求模型具备视觉能力不依赖 UI 坐标只要描述清楚“有什么工具、每个工具能干什么、参数是什么”模型就能稳定输出调用。我在实际测试中发现同一批任务走“读屏 模拟鼠标”的准确率经常在 70% 上下波动而走“自然语言转命令”的准确率可以稳定到 95% 以上。差距不是模型聪明与否而是问题形态根本不匹配。1.2 为什么说 CLI 是 Agent 时代的“标准插头”把电脑比作一个装满家电的房间AI Agent 是遥控器而各个软件就是电视、空调、音响。如果每个家电都有自己的遥控协议遥控器就得内置无数套规则任何一种新电器出来都要升级。但如果所有电器都统一用某种标准插头事情就简单了。CLI 就是那个事实上的标准插头。几乎所有正经软件哪怕只有 GUI底层也多半存在命令行入口或脚本化能力。即便是纯 GUI 程序也可以通过辅助工具包一层“命令行外壳”。而且 CLI 有一个天然优势它是长文本的、可拼接的、可编程的。这意味着 Agent 不仅可以执行单条命令还能把多条命令组合成流水线甚至根据前一步输出决定下一步动作。这在 GUI 场景里几乎不可能做到。所以我的结论是与其费劲教模型“看界面”不如花力气把软件的“操作面”重构成 CLI。这就像一个翻译官把人类自然语言翻译成软件能理解的执行动作。CLI-Anything 正是这个翻译官的系统化实现。2. 整体架构与设计思路把“调用”变成“协议”很多人第一次听到“让 AI 调用软件”第一反应是“直接让大模型生成 shell 命令不就行了”我在初期也这么干过让模型自由发挥写命令然后丢给终端执行。结果显而易见模型会编造不存在的参数、用错命令语法、甚至在一个危险操作上给我“自信满满”地执行。后来我彻底否定了这种“裸奔”方案转向协议化封装——不是让模型自由写命令而是给每个工具定义一套结构严谨的调用协议模型只负责在协议框架内填参数。整个系统分四层工具注册层、意图解析层、命令执行层、结果回传层。先说整体架构长什么样。我用一个简单的进程内调度器把四层串起来每个被接入的软件都声明成一个“工具”声明内容包括工具 ID、一句话描述、参数定义、调用示例、安全约束。Agent 收到用户需求后先从工具清单里找到匹配项再按参数定义生成结构化调用最后执行并返回结果。示意图不值得画文字很好理解注册表决定“有什么可用”调度器决定“怎么调用”执行器决定“能否安全落地”。2.1 工具注册给 Agent 一份“能力清单”工具注册是整个系统的地基。每个工具的声明必须精确到“参数名、类型、可选值、默认值”不能留模糊空间。我用 YAML 来写这份清单因为它的可读性最好既能给人看也能快速转成 JSON 喂给大模型。举个例子我接入过一个老旧的图像批处理软件它没有 API但提供了一个命令行 exe。我给它的注册描述长这样id: image_resizer description: 批量调整图片尺寸支持常见图像格式输出到指定目录 parameters: - name: input_dir type: string required: true description: 存放原始图片的文件夹路径 - name: width type: integer required: true description: 目标宽度像素值必须大于 0 - name: height type: integer required: true description: 目标高度像素值必须大于 0 - name: keep_ratio type: boolean default: false description: 是否保持原始宽高比为 true 时忽略 height examples: - 把 /tmp/pics 里的图缩到 800 宽保持比例 call: image_resizer --input /tmp/pics --width 800 --keep-ratio true这份清单最关键的地方在description和examples两处。description决定模型能不能正确找到这个工具examples则像给模型做了一次示范让它知道“这类说法应该翻译成那种调用”。我后来还发现示例的数量和质量比参数描述的详细程度更能影响调用准确率所以每个工具至少配三到五个典型示例覆盖“简单请求、带细枝末节的请求、容易混淆的写法”。另外每个工具都要显式声明安全约束比如执行目录白名单、禁止删除操作、超时上限。这部分不是给模型看的是给执行器做硬校验用的。模型可能给出合法但危险的参数执行器必须拦截。2.2 意图解析与参数绑定最关键的“翻译”环节有了工具清单接下来就是让大模型把用户的话翻译成结构化调用。这一步很容易做歪我反复调出来的稳定做法是不要求模型直接输出 shell 命令而是先输出一段 JSON。JSON 里包含工具 ID 和参数表再由调度器转换成实际命令。为什么绕一道因为 JSON 是结构化数据方便校验也方便在出问题时定位是“模型填错参数”还是“命令执行失败”。比如用户说“帮我把桌面上的照片都缩小一半”模型应该输出{ tool: image_resizer, parameters: { input_dir: /home/user/Desktop, width: null, height: null, keep_ratio: true, scale: 0.5 } }模型在翻译时可能会漏掉某个参数或者把“一半”直接误解为固定的 500 像素。为了减少这类问题我在提示词里做了三个约束第一用户没说具体数值时必须标出来不能自作主张补默认值第二参数类型必须严格匹配声明比如整数参数不能填字符串第三任何不确定的映射都要输出到ambiguous_fields字段由下游再向用户确认。这套机制跑下来误填参数的比例明显下降。不过“翻译”环节还有一个隐蔽的坑模型会根据工具描述里的相似词“幻觉”出不存在的参数。例如工具明明只支持width和height模型却因为用户提到“质量”而输出一个quality参数。解决的办法有两个一个是在提示词里强调“只能使用参数定义列表里的字段”另一个是在校验器中增加“未知字段拒绝”的硬规则。2.3 执行安全边界这条底线不能松命令执行层是整套系统里最需要敬畏的部分。直接让模型生成的命令在系统里跑等于把钥匙交给一个喝了三杯咖啡的实习生他可能很努力但偶尔会闯祸。我踩过一次深刻的教训某次测试时模型把用户说的“清理临时文件”翻译成了删除一整个目录差点把缓存里的其他东西清理掉。安全设计从三个层面同时进行。第一层是参数白名单每个工具声明允许的路径前缀、允许的文件类型、禁止触达的目录。第二层是命令模板不是把 JSON 里的值直接拼进 shell 命令而是通过子进程的参数数组传递避免任何可能被解释为 shell 语法的内容混进来。第三层是权限降级执行器尽量以当前用户运行绝不使用 sudo对危险操作单独二次确认。我强烈建议在执行层前加一道“预演模式”。所谓预演就是把命令跑一遍但不真正改文件只输出将要执行的动作和影响范围。等 Agent 确认无误后再执行正式版本。这个机制在接入真实工作环境时几乎是必需品因为模型偶尔会误解用户的意图预演能给流程留一个纠错机会。3. 核心实现手写一个极简 CLI-Anything 代理纸上谈兵到此为止下面直接上代码。我用来做演示的载体是一个 Python 脚本依赖很轻模型调用接口用普通的 OpenAI 兼容接口命令执行用 Python 标准的subprocess模块。为了不让代码篇幅超出控制我把演示聚焦在三件事上定义一个工具、让模型输出结构化调用、安全执行这个调用。3.1 定义第一个被封装的实际工具我先选了一个轻度工具来演示一个图片尺寸查询程序。大家可以类比理解成“任意一个仅有命令行入口的软件”。它的原始调用方式是这样的img-info /path/to/image.png输出是纯文本格式的尺寸信息。接入 CLI-Anything 后我们把它声明为工具注册到一个简单字典里TOOLS { image_info: { description: 获取图片的基础信息包括宽高、格式、大小, parameters: { type: object, properties: { path: {type: string, description: 图片文件的绝对路径} }, required: [path] }, command: [img-info], # 实际执行的命令列表 } }这里的command是执行器唯一允许拼接的内容。模型输出的参数会被塞到command后面但不会以字符串拼接的方式进入 shell这正是后面要讲的安全细节。3.2 让模型输出规范化调用有了工具清单接下来写调度函数。它的职责是把用户自然语言请求、可用工具描述、输出格式要求一并交给模型拿到 JSON 后做校验。为了让输出稳定我采用 JSON 模式约束。def parse_intent(user_input): system_prompt 你是工具调度器。根据用户请求从下列工具中选择一个并生成调用参数。 工具列表 {tool_descriptions} 输出格式必须严格为 JSON {{tool: 工具id, parameters: {{...}}, ambiguous_fields: [不确定的参数名]}} 只能使用工具声明中出现的参数禁止添加额外字段。 .format(tool_descriptionsjson.dumps(TOOLS, ensure_asciiFalse)) response model_chat( messages[{role: system, content: system_prompt}, {role: user, content: user_input}], response_format{type: json_object} ) return json.loads(response)这段代码落实了两件事。第一所有工具能力一次性传给模型模型不用“猜”有哪些工具。第二强制 JSON 输出把自由文本的生成变成了结构化填空。实际测试中加上response_format之后解析失败率从偶尔出现降到了几乎为零。3.3 执行命令与回传结果安全地跑起来得到 JSON 调用后执行器开始干活。核心有两点用参数数组方式传入子进程而不是拼命令字符串捕获退出码、stdout 和 stderr 并一起回传给调用方。import subprocess def execute_tool(tool_id, params): tool TOOLS.get(tool_id) if not tool: return {status: error, message: 未知工具} cmd tool[command] [params[path]] try: result subprocess.run( cmd, capture_outputTrue, textTrue, timeout15, checkFalse ) if result.returncode 0: return {status: ok, output: result.stdout} else: return {status: error, message: result.stderr} except FileNotFoundError: return {status: error, message: 底层命令不存在请检查程序路径} except subprocess.TimeoutExpired: return {status: error, message: 命令执行超时}subprocess.run加checkFalse是为了不让异常中断流程而是把错误信息正常返回给模型或用户去分析。这一步很多人容易写错直接用checkTrue导致程序崩溃或者忘了捕获超时导致整个任务卡死。一个小提示命令执行环境的cwd、环境变量也要由执行器主动设置不要继承终端里的任意环境变量避免模型生成的命令意外读到你不希望它接触的配置。4. 工具选型与参数设计从零填平自动化洼地写一个 demo 容易真正要把一套软件接入生产可用关键在于两点选对要接入的工具、设计好参数。这两件事做得好后面运行就顺做得不好模型再聪明也白搭。下面把我调出来的经验顺序分享出来。4.1 什么样的工具值得接先做“高频低风险”的我第一周接入了一堆五花八门的软件后来发现真正高频被调用的只有那么几个。总结下来优先接入符合三个特征的工具操作频次高、参数固定、破坏性低。比如文件格式转换、图片信息查询、批量重命名、文本处理管线。这些工具即使调用出错后果也可控。反过来参数极度灵活、输出极度复杂的工具不适合第一波接入。比如一个参数多达几十个的 PDF 处理软件模型很容易在参数组合上出错而且出错后很难排查。我的建议是先接入十个以内的简单工具跑通了再逐步上复杂度。4.2 参数设计的三条铁律参数设计是决定调用质量的隐藏变量。我吃过亏后才总结出三条铁律每一条都有实际教训支撑。第一条参数不要多够用就好。工具本身可能有 20 个配置项但暴露给 Agent 的只留 5 个最高频的其余全部设成默认值。模型的选择空间越小出错概率越低。第二条参数名要用用户能理解的词而不是软件内部的底层字段名。比如软件内部叫src_path但用户习惯说“文件”或“图片”注册名就统一叫input_file描述里再说明支持图片格式。第三条数字型参数必须给出合理范围。大模型对数字不敏感如果不限制范围它可能会把“缩小一半”翻译成scale2而不是scale0.5。我用一个简单规则规避这个问题设计描述时把语义说清楚例如scale 取值范围 0.1~1.01.0 表示原始大小。4.3 工具描述怎么写用“最小清晰”原则工具描述不是写论文越精炼越好。我对比过两种写法效果差距很明显。描述写法示例调用准确率过虚型“处理图片支持常见格式”低模型经常匹配错工具精准型“将一组图片统一缩放、格式转换支持 jpg/png/webp输出到目标目录”高模型几乎不会用错精准型描述的关键词是“动作 对象 约束 输出位置”。动作是“缩放、转换”对象是“一组图片”约束是“支持 jpg/png/webp”输出位置是“目标目录”。这样模型只需要做一次简单的语义匹配而不是反复猜测。4.4 调用链别设计得太长最后强调一个架构层面的经验能在单次调用里完成的事就不要拆成多步。比如“获取图片尺寸”本身是一步而“获取图片尺寸后如果宽度大于 1000 就缩小”是两步。如果你把第二步也封装进工具让 Agent 一次完成判断和操作整个链路既快又稳。否则模型每一步都要做一次推理任何一步出错后面都跟着错。我在一个批量处理工具里就把“文件识别 转换 重命名 移动到归档目录”打包成了一个原子工具。这样设计以后用户一句话就能完成之前需要四个工具编排的任务Agent 的调用频率和成功率都显著提高。5. 常见问题与排查技巧实录任何系统跑起来只是开始真正折磨人的是各种边界情况。下面这些坑有的是我在测试中主动踩的有的是上线后用户义务反馈的每一条都值得记下来。5.1 模型“幻觉”参数怎么办这是出现频率最高的问题。模型在生成 JSON 时偶尔会加入工具声明里没定义的字段或者把枚举值写错。比如某个工具只支持format取jpg/png/webp模型却输出gif。我处理的办法是双保险提示词里强制约束 校验器里拒绝未知字段。校验器会做一次严格比对把模型输出的参数键和工具声明里的properties比对出现未知字段直接返回“参数错误”并附上可接受的参数列表。这让模型有机会在下一次调用中自我修正。实测下来经过一轮修正后绝大多数幻觉参数都会消失。5.2 输出乱码和编码问题很多老软件的输出编码并不统一有的是 GBK有的是 UTF-8甚至同一个程序在不同参数下输出编码不一致。直观表现是 Agent 拿到的输出是乱码导致它无法分析结果。解决办法是在执行器里增加编码探测和强制转换。我写了一个封装函数先用chardet之类的工具探测字节流可能的编码再统一转成 UTF-8。如果探测失败就把 stdout 和 stderr 都按二进制返回并给调用方提示“无法识别编码”避免 Agent 强行解读。5.3 超时和“僵尸”进程有些图形软件的命令行外壳会在任务完成后不主动退出导致subprocess.run一直阻塞到超时。更麻烦的是超时后子进程可能还留在系统里占着资源。我的处理策略分两步。第一步所有调用都必须设置超时上限宁可杀错不可等死。第二步在超时处理中先尝试终止进程组如果不行再强制 kill。在 Python 里我用start_new_sessionTrue为每个任务开启独立进程组这样超时后可以精确杀掉整个进程树不会波及主程序。5.4 路径参数含空格怎么办这是个特别接地气的坑。用户说“把 我的图片 文件夹里的照片处理一下”模型生成的路径参数大概率带着空格。如果执行层用字符串拼接命令这个路径会被 shell 拆成两段直接报“找不到文件”。我的做法是坚持参数数组模式绝不把参数拼进命令行字符串。subprocess.run接收的列表会直接传给操作系统空格是参数的一部分不会引发任何解析问题。这一点几乎所有新手都会踩建议在设计执行层的第一天就定死这个规则。5.5 如何快速定位是模型问题还是工具问题排查问题时最忌讳的就是一团乱麻。我建立了一套简单的日志规范每个环节都记录输入输出和时间。打个比方Agent 单次完整调用会生成一条链路日志包含用户原始需求、模型输出的 JSON、执行器收到的参数、命令真实退出码、输出摘要。出现问题后我直接看模型输出的 JSON 是不是符合工具定义符合再看执行器的返回码和 stderr这两段都正常才考虑是不是环境或底层程序的问题。这种“分层排查”的思路帮我省了大量时间比对着终端输出瞎猜强多了。6. 后续还能怎么玩从工具化到工作流编排接入工具只是第一步真正有意思的是把这些工具交给 Agent 去编排。我在实践中发现一个规律一旦工具数量超过 5 个Agent 就慢慢展露出“规划”能力不只是机械地调用而是会根据用户目标选择工具、排序、必要时回退重试。我最近在做的就是给工具增加“组合提示”——在工具描述里写上“这个工具通常搭配某某工具一起使用典型流程是……”。这样 Agent 在面对复杂任务时会自动生成多步工作计划而不是试图用一个工具解决一切。比如“把这一批照片缩小并压缩成 zip 发给别人”这个需求会被拆成三步图片处理、压缩打包、生成下载链接。三个工具逐个调用前一步的输出作为后一步的输入这就是工作流编排的雏形。另外有不少值得扩展的方向适合自己动手做实验把工具注册表做成动态发现从远程拉取新工具的描述不用改主程序代码给执行器增加审批模式高风险命令先发通知由人工确认后再跑对 Agent 的高频调用记录做统计识别出使用率低的工具反推是不是参数设计得不合理把 CLI-Anything 嵌入一个更大的 Agent 框架让它可以调度本身附带的子 Agent。我个人在整套系统上最大的体会是别指望模型一步到位而是通过工程手段把不确定性一点一点压下去。工具描述写得模糊就多写几个示例参数容易混淆就砍参数数量命令危险就加预演和审批。这套系统后续还能扩展成可视化工具编排平台让我真正意识到把软件变成 Agent 的“手”只是开始变成它的“工作流习惯”才是更有想象力的终点。如果让我给正在考虑接入 AI Agent 的同学一个建议那就是从最小的命令入手选一个你每天都在用、但一直无法自动化的软件给它写第一份工具声明。跑通了第一个剩下的事情就是复制经验、滚雪球。