CLI-Anything 架构:任意软件如何接入 Agent

CLI-Anything 将软件已有能力重新封装为供 Agent 直接调用的接口层,提供稳定输出和可重复执行能力,并建立软件与 Agent 之间的可编程交互基础。 根据公开资料,CLI-Anything 由香港大学数据科学实验室(HKUDS)主导开发,定位之一是通过自动生成 CLI,让原本主要面向人的软件获得可编程入口。 CLI-Anything 同时也是 Agent 与真实软件之间的适配层;实际适配效果取决于目标软件是否提供 API、IPC、扩展点或其他可控入口。

因此,“让任意软件 Agent 化”更接近一种架构目标,而不是无条件的自动化承诺。应优先接入已经有 CLI、API 或内部扩展点的软件;只有图形界面的软件也能适配,但稳定性、权限和维护成本会明显上升;完全封闭且没有扩展点的软件,则很难做出可靠接口。

CLI-Anything 解决的是哪一类交互断层?

当前多数面向用户的软件围绕人类交互习惯设计:按钮、菜单、窗口、拖拽和鼠标点击。Agent 则更依赖文本命令、结构化参数、稳定输出和可重复执行。

“让所有软件都能被 Agent 驱动”是对项目目标的概括性表达,但实现前提始终是目标软件存在某种可调用入口,或者其界面可以被可靠地自动化。 CLI-Anything 试图处理这种交互断层:把软件能力从“人操作界面”转换为“Agent 调用接口”。

一个面向 Agent 的 CLI 至少应满足以下要求。命令要具备可发现性,Agent 应当能够通过帮助信息、能力描述或工具定义知道有什么功能。参数必须可解析,不能依赖自然语言猜测诸如日期格式、账户范围和文件路径。输出要能被稳定消费,错误也要使用固定结构表达,不能只返回一段面向人的报错提示。执行过程应当可重复,同一组输入尽量得到等价结果,写操作还要能够识别重复请求。此外,接口还应具备可治理性,Agent 需要知道某项能力是只读,还是会删除、覆盖、支付等高风险操作。

这也解释了 CLI-Anything 与普通“给程序套一个命令行入口”的区别。普通 CLI 主要改善人类操作体验;Agent-Native CLI 更像一份机器接口契约:Agent 消费的是稳定的命令、参数、结果和错误,而不是一页排版精细的帮助文档。

从 Agent 指令到软件动作,调用链怎样闭合?

下面的调用链是依据项目目标整理出的分析模型,不是未经核实的官方模块图:

Agent 意图
    ↓
选择命令并生成结构化参数
    ↓
CLI 解析与参数校验
    ↓
目标软件连接器
    ↓
API / IPC / HTTP / WebSocket / UI 自动化执行
    ↓
标准化结果或错误
    ↓
Agent 消费结果并决定下一步

关键分界位于自然语言与确定性执行之间。Agent 可以根据任务描述选择 invoice export,再生成账户编号、输出格式等参数;进入 CLI 后,参数类型、必填项、权限和执行分支应当由程序校验,而不是继续依赖模型即兴判断。

目标软件连接器承担翻译工作。以 Electron 应用为例,CLI 可以通过 IPC/RPC 把请求转给主进程中的业务模块,再由主进程完成真正的数据读取、导出或更新。移动端服务和云端系统可以通过 HTTP API 或 WebSocket 接入;只有图形界面的软件,才需要借助 Windows UI Automation、macOS Accessibility 等平台机制执行界面操作。

结果返回同样重要。一次成功的导出不能只打印“操作完成”,还要告诉 Agent 导出了什么、目标位置在哪里、是否发生部分失败。失败时则应区分权限不足、网络超时、参数非法和目标软件未运行等不同情况。标准化错误让 Agent 可以决定重试、修改参数还是停止任务,而不是把所有异常都当成同一种字符串。

因此,CLI-Anything 的核心是建立一条从意图到执行、再从结果回到 Agent 的闭环。

CLI-Hub、SKILL.md 和 OpenClaw 处在哪一层?

依据现有资料,CLI-Anything 的发展方向可以拆成四层:

层级 主要角色 解决的问题
基础 CLI 执行具体软件能力 将一次操作变成确定、可解析的命令
SKILL.md generation 描述能力与使用条件 让 Agent 知道何时调用、参数是什么、结果如何解释
CLI-Hub 集中分发与管理接口 降低发现、安装、维护多个 CLI 的成本
OpenClaw support 提供兼容性支持 让相关 Agent 环境能够接入既有 CLI 能力

这几层不能混为一谈。CLI 是执行端,SKILL.md 是能力描述层,CLI-Hub 是分发与管理层,OpenClaw 则属于生态兼容方向。 一份 SKILL.md 即使写得再完整,也不能替代真正的软件连接器;同样,一个可以运行的 CLI,如果没有清晰的命令和错误契约,也很难稳定地进入 Agent 工作流。

从工程角度看,SKILL.md 至少应回答几类问题:能力名称和用途、适用场景、必填参数、输出格式、权限要求、是否具有副作用,以及失败后的处理方式。CLI-Hub 解决的是规模化问题:当适配器数量增加后,团队需要统一发现版本、升级依赖、记录兼容性和处理权限,而不是逐个复制脚本。

现有资料将 CLI-Hub、SKILL.md generation 和 OpenClaw support 描述为项目继续推进的方向,不能据此直接认定它们都已作为稳定功能发布。 当前模块名称、安装方式和支持列表应以 GitHub README 和 CLI-Hub 页面为准,本文不把二手文章中的示例当作官方 API。

把一个软件 Agent 化,实际要完成哪些步骤?

下面以“给一个 Electron 应用增加 Agent 可用的账单导出能力”为例。完整适配并不止于写出一个命令,还需要依次处理能力、连接、执行契约和验证。

首先,需要盘点软件能力并区分风险。业务人员日常使用的“查看、筛选、导出、更新、删除、支付”对应不同接口和风险等级。可以先挑选只读查询,或只产生派生文件的导出能力,不要一开始就接删除、覆盖和支付操作。

其次,应确认软件的内部扩展点。如果业务逻辑已经集中在 Electron 主进程,可以通过 IPC/RPC 暴露一小组明确能力;如果只有渲染页面,则应先判断能否把核心逻辑下沉,而不是让 Agent 依赖页面元素。涉及移动端或云端服务时,HTTP API 通常适合请求—响应任务,WebSocket 更适合持续事件或流式状态。

完成扩展点确认后,选择连接器形态。对 Electron 应用,连接器负责建立 CLI 与主进程之间的通信;对网络服务,连接器负责鉴权、请求和响应转换;对 UI 自动化,连接器则要解析控件、等待状态并模拟操作。连接器应尽量薄,把软件业务规则留在目标应用内部。

接下来是设计命令和参数。一个适合 Agent 的命令应采用清晰的动词结构,例如 invoice export,而不是含义模糊的 run 或 process。资源、范围和格式应通过具名参数表达,必填项不能依赖交互式提问。

在此基础上定义输出契约。stdout 承载机器可解析的结果,诊断日志写入 stderr;成功与失败使用稳定字段,退出码反映执行状态。面向 Agent 的新命令可以让 JSON 成为默认输出;如果需要兼容既有人类 CLI,也可以保留文本输出并提供显式 --format json。

完成基本设计后执行稳定性测试,测试范围至少包括合法参数、缺失参数、非法参数、空结果、大结果量、权限不足、目标程序未启动、网络超时和重复执行。写操作还需要测试重复请求、部分成功、进程中断与恢复。

最后考虑打包与生态接入。CLI 应按实际运行系统提供可执行形式,并固定依赖版本,避免同一命令在开发机和 Agent 环境中表现不同。最小能力稳定后,再决定是否生成 SKILL.md、提交 CLI-Hub,或接入 OpenClaw 等生态。

下面的代码只是一个接口形态参考。它使用资料中提到的 Node.js 与 Commander.js 组合,但不代表 CLI-Anything 的官方模块名或强制技术栈;connector.exportInvoices() 仍需由目标应用实现。

#!/usr/bin/env node
const { Command } = require('commander');

const program = new Command();

program
  .name('invoice-cli')
  .description('Export invoice data through the desktop application')
  .showHelpAfterError();

program
  .command('export')
  .requiredOption('--account <id>', 'account identifier')
  .option('--format <format>', 'json or text', 'json')
  .option('--output <path>', 'output file path')
  .action(async (options) => {
    try {
      const data = await connector.exportInvoices({
        accountId: options.account,
        outputPath: options.output
      });

      if (options.format === 'json') {
        process.stdout.write(
          JSON.stringify({ ok: true, data }) + '\n'
        );
      } else {
        process.stdout.write(formatText(data) + '\n');
      }
    } catch (error) {
      process.stderr.write(
        JSON.stringify({
          ok: false,
          error: {
            code: error.code || 'EXPORT_FAILED',
            message: error.message,
            retryable: Boolean(error.retryable)
          }
        }) + '\n'
      );
      process.exitCode = 1;
    }
  });

program.parse();

目标软件不同,接入路线怎么选?

接入路线应优先选择离软件内部语义最近的接口。下表依据资料中的实践路径作工程分类,不代表这些能力都由 CLI-Anything 自动提供。

目标软件 优先接入方式 优点 主要成本
已有 CLI 或 API 的软件 包装或规范化原有接口 语义清楚、稳定性较高 原有接口的一致性、鉴权和输出可能需要整理
Electron 桌面应用 IPC/RPC 调用主进程业务模块 可直接复用业务逻辑 需要调整进程边界、权限和启动方式
移动端服务与云端系统 HTTP API;必要时使用 WebSocket 适合远程调用和跨平台部署 网络失败、超时、认证与限流必须进入错误契约
只有图形界面的软件 Windows UI Automation、macOS Accessibility 可以覆盖缺少公开 API 的应用 强依赖界面结构、平台权限和软件版本
完全封闭且无扩展点的软件 通常只能间接自动化 理论上仍可尝试 脆弱、可审计性差,维护成本最高

这条路线存在清晰的稳定性梯度,越接近软件内部接口,语义越明确,越不容易受到布局变化影响;越依赖界面元素,版本升级和系统差异带来的维护成本越高。

对于网络服务,连接器不应把所有失败都转换成同一个 ERROR。至少应区分连接失败、请求超时、认证失效、权限不足、服务端限流和业务校验失败,并标记是否适合重试。对于不可逆操作,超时并不一定意味着动作没有发生,Agent 需要先查询状态,再决定是否重试。

命令和输出如何设计,才能降低 Agent 的误用风险?

Agent-Native CLI 的设计目标,是让模型根据接口契约调用,而不是依赖猜测界面文字或解析松散日志。

在命令层面,动词应当明确,list、get、export、update 和 delete 这样的表达比含义宽泛的动作词更容易被发现和组合。资源需要使用明确名称,多资源操作应避免含糊的默认范围,日期、金额、状态等值必须采用固定格式。帮助信息需要面向机器,命令名称、参数类型、默认值、必填关系、退出码和副作用都应结构化暴露,而非只提供人类可读说明。命令执行应保持非交互,所需参数全部显式传入,不得在缺少参数时等待终端输入。

在输出层面,JSON 应当保持结构稳定,字段名称、类型和空值表达不能随软件版本随意变化。文本模式需要作为展示层保留,它可以是 JSON 的渲染结果,但不应成为 Agent 的主解析路径。错误信息必须采用固定格式,例如:

{
  "ok": false,
  "error": {
    "code": "TIMEOUT",
    "message": "The export service did not respond in time",
    "retryable": true
  }
}

这只是建议的契约示例,并非官方格式。 实际项目中还可以加入 schema_version、请求标识和分页信息。日志必须与结果分离,带 ANSI 颜色的提示、进度条和调试信息不应混入标准输出。

重复执行也需要被单独设计。查询应当尽可能无副作用;更新操作要说明是覆盖、合并还是追加;删除和支付类操作则应具备明确的权限、确认和审计机制。对 Agent 来说,“命令执行成功”不能等同于“业务目标已经完成”。

“任意软件”是否等于没有前提?

“任意软件”更适合被理解为适配范围的潜力,而不是零成本、零前提的承诺。

适合优先适配的软件通常拥有稳定的 CLI、API、插件机制或内部扩展点,其输入输出可以明确定义。这类软件支持脚本化调用,提供不依赖界面的命令结构,身份认证与权限边界也能被程序化处理。此外,运行结果应具备可观察性和可验证性,这也是重要前提。

Electron 应用、移动端服务和只有图形界面的软件主要属于条件适配。它们并非不能接入,只是连接器需要承担更多翻译、协议和错误处理工作。桌面 UI 自动化尤其容易因控件层级、弹窗、窗口状态和权限配置而失败。

完全封闭、没有扩展点的软件则不适合强行适配。逆向协议或模拟点击有时能够工作,但很难同时保证稳定性、可审计性和长期兼容性。更务实的做法,是先寻找其导出文件、后台服务、插件或官方 API 等替代入口。

还要区分两件事:提供可调用接口,不等于替 Agent 理解业务语义。CLI 可以准确完成“导出某账户的账单”,却无法自行判断“哪个账户符合业务要求”“导出哪些字段足够”。后者仍然需要任务上下文、权限规则和结果校验。

只读查询和派生文件导出通常适合作为第一阶段能力;删除、覆盖、支付、发布等操作则需要额外控制,包括最小权限、操作前确认、幂等标识、结果审计和必要的人工介入。生成一个 CLI 命令不会自然带来这些能力,应用方必须承担相应的安全责任。

跨平台和长期维护的成本在哪里?

跨平台命令行接口可以统一命令名称、参数和输出结构,但无法消除不同系统的执行差异。Windows UI Automation 与 macOS Accessibility 使用不同的定位、元素和权限机制;同一业务能力往往需要两套后端连接器,以及各自的安装、授权和回归测试。

UI 自动化尤其需要关注版本漂移。控件名称、层级、快捷键和弹窗流程都可能随软件更新改变。一次适配完成并不意味着适配永久有效,至少需要针对关键目标软件版本维护冒烟测试,并记录失败是否来自业务变化、界面变化还是连接器变化。

网络型软件的维护重点则是另一组问题:连接超时、认证过期、限流、部分成功、服务端版本变化和重试安全。CLI 的输出契约应把这些状态固定下来,否则 Agent 的上层工作流会随网络波动频繁失效。

跨平台分发还需要处理运行时依赖、动态库、可执行文件格式和权限模型。可以在统一命令层之下保留平台专用连接器,但不应为了表面统一而隐藏差异。构建产物还应记录依赖版本和目标环境,否则复现一次成功调用会变得困难。

这些问题都属于落地时的工程成本,不能因为项目采用了“任意软件”的表述,就假设它们已经被自动解决。

读者现在能先做哪一步验证?

验证时应避免一开始就改造整个软件,可以按以下顺序逐步推进。首先核对项目当前状态,阅读 GitHub README,并查看 CLI-Hub 的当前说明,以确认安装方式、模块名称和支持列表,不要直接沿用二手文章中的命令。

随后选择一个已有 API、CLI 或扩展点的软件能力,该能力应具有明确输入、稳定输出,且最好不产生不可逆副作用。在此基础上先实现最小 CLI,只覆盖一个动作,例如读取列表或导出文件,不在第一版加入完整业务菜单。

实现后必须验证契约。需要测试正常结果、空结果、非法参数、权限错误、目标程序未运行和重复执行,并确认 stdout 可以被稳定解析。验证通过后,再逐步加入写操作,为更新、覆盖、删除等动作增加显式权限、确认、幂等和审计。

最后决定是否进入生态层。只有当底层 CLI 足够稳定,SKILL.md 才有可靠内容可描述,CLI-Hub 和 OpenClaw 等分发或兼容机制也才有持续维护的基础。

先让一项高价值能力拥有稳定的连接器和输出契约,用可重复的测试证明它适合 Agent,再逐步扩展到写操作与生态分发,不必立刻改造所有软件。

© 版权声明
THE END
喜欢就支持一下吧
点赞0 分享
评论 抢沙发

请登录后发表评论

    暂无评论内容