将任意CLI工具封装为AI代理原生接口：命令Schema自动提取与状态机映射

问题背景：Agent 与软件的鸿沟

AI 代理在推理和规划方面表现出色，却在使用真实专业软件时频频受阻。当前主流方案要么依赖脆弱的 UI 自动化（截图、点击、RPA），要么受限于软件提供的有限 API，只能覆盖不到 10% 的功能。CLI-Anything 提出了一条不同路径：将命令行界面（CLI）作为人机通用的 "最大公约数"，通过自动化流水线把任意软件转化为 Agent 原生接口。

CLI 被选作统一接口并非偶然。它具有结构化且可组合的特性（文本命令与 LLM 输出格式天然匹配）、轻量且跨平台（无需依赖即可在所有系统运行）、自描述（--help标志提供自动文档），以及确定性输出（一致的结果使 Agent 行为可预测）。正如项目文档所言："Today's Software Serves Humans. Tomorrow's Users will be Agents."

七阶段流水线：从代码到 Agent 工具

CLI-Anything 的核心是一个全自动化的七阶段流水线，输入软件源码或 GitHub 仓库，输出可直接安装的 Python CLI 包：

1. Analyze（分析）：扫描源代码，将 GUI 操作映射到底层 API
2. Design（设计）：架构命令分组、状态模型和输出格式
3. Implement（实现）：基于 Click 构建 CLI，包含 REPL、JSON 输出、undo/redo
4. Plan Tests（规划测试）：创建 TEST.md，规划单元测试和 E2E 测试
5. Write Tests（编写测试）：实现全面的测试套件
6. Document（文档）：更新 TEST.md 记录结果，生成 SKILL.md
7. Publish（发布）：创建 setup.py，安装到 PATH

每个阶段都有明确的交付物和验收标准。以 Blender 为例，生成的 CLI 包含 208 个测试用例（150 个单元测试 + 58 个 E2E 测试），能够直接调用真实的bpy Python API 进行 3D 渲染，而非使用简化的替代方案。

命令 Schema 自动提取与状态机映射

Schema 提取机制

CLI-Anything 通过扫描目标软件的源代码，识别可编程入口点：

• GUI Action 映射：分析菜单项、工具栏按钮对应的内部函数调用
• API 表面识别：定位公共 Python 模块、REST 端点或命令行接口
• 参数推断：从函数签名、文档字符串、配置文件提取参数类型和约束

生成的命令 Schema 遵循 Click 的装饰器模式，每个命令都有类型化的参数、选项和文档。例如 GIMP 的 CLI 包含 107 个测试覆盖的命令，能够调用真实的 Pillow + GEGL/Script-Fu 后端。

状态机与 REPL 设计

为了支持复杂的交互式工作流，每个生成的 CLI 都包含统一的状态管理机制：

• 持久化项目状态：支持 undo/redo 操作历史
• REPL 模式：运行裸命令进入交互式会话，提供命令历史、进度指示器和标准化格式化
• 会话隔离：不同项目的状态相互独立，避免副作用污染

REPL 界面通过repl_skin.py统一实现，所有 CLI 共享一致的交互体验。这种设计使 Agent 能够在多步骤任务中保持上下文，例如 Blender 中的 "创建场景→添加网格→渲染输出" 流程。

工具调用协议适配：Agent 原生设计

结构化输出

每个命令都支持--json标志，输出机器可解析的 JSON 格式：

{
  "name": "Q1 Report",
  "type": "writer",
  "pages": 1,
  "elements": 2,
  "modified": true
}

同时保留人类可读的表格输出，便于调试和交互使用。

技能发现协议（SKILL.md）

每个生成的 CLI 都附带SKILL.md文件，这是 Agent 发现工具能力的标准契约：

• YAML 前置元数据：包含名称和描述，供 Agent 技能发现
• 命令分组：记录所有可用子命令
• 使用示例：常见工作流的调用方式
• Agent 专属指导：JSON 输出、错误处理、程序化使用的最佳实践

SKILL.md 使 Agent 能够自主理解 CLI 的能力边界，无需人工编写集成代码。

跨代理兼容性设计

CLI-Anything 并非绑定到特定 Agent 平台，而是通过适配层实现跨平台兼容：

统一的命令语义和输出格式确保 Agent 在不同平台间迁移时无需重新学习。

CLI-Hub：Agent 自主发现与安装

CLI-Hub 是项目的中央注册表，使 Agent 能够自主发现和安装所需 CLI：

# 安装CLI-Hub
pip install cli-anything-hub

# Agent可用的命令
cli-hub list      # 浏览注册表
cli-hub search    # 按关键词搜索
cli-hub install   # 安装指定CLI
cli-hub info      # 查看CLI详情

通过npx skills add HKUDS/CLI-Anything --skill cli-hub-meta-skill，Agent 可以读取实时目录，自主选择合适的 CLI 完成任务。目前已覆盖 18 个领域，包括创意工具（Blender、GIMP、Inkscape）、办公软件（LibreOffice）、视频编辑（Kdenlive、Shotcut）、AI 平台（ComfyUI、Ollama）等。

可落地的工程参数

环境要求

• Python 3.10+
• 目标软件已安装（如 GIMP、Blender 等）
• 支持的前端模型：Claude Opus 4.6、Claude Sonnet 4.6、GPT-5.4 等

安装与使用

# 通过CLI-Hub安装
pip install cli-anything-hub

# 生成CLI
cli-hub install gimp
# 或直接对本地源码
/cli-anything ./gimp

# 使用生成的CLI
cli-anything-gimp --help
cli-anything-gimp --json project new -o poster.json

测试策略

• 单元测试：核心函数隔离测试，使用合成数据
• E2E 测试（原生）：验证项目文件生成（ODF ZIP 结构、MLT XML、SVG 格式）
• E2E 测试（真实后端）：调用真实软件验证输出（LibreOffice→PDF、Blender→PNG）
• CLI 子进程测试：通过subprocess.run验证安装后的命令

当前测试覆盖 2,330 个用例，通过率 100%。

迭代优化

单次生成可能无法覆盖全部功能，通过/cli-anything:refine命令进行增量扩展：

# 广度优化：分析所有能力的覆盖缺口
/cli-anything:refine ./gimp

# 定向优化：针对特定功能领域
/cli-anything:refine ./gimp "batch processing and filters"

局限与建议

CLI-Anything 的当前版本存在以下限制：

1. 模型依赖：需要前沿级模型（Claude Opus/GPT-5.4 级别）才能可靠生成，较小模型可能产生不完整或错误的 CLI
2. 源码依赖：七阶段流水线依赖源代码分析，纯二进制软件需要反编译，生成质量会显著下降
3. 迭代需求：单次运行可能无法达到生产质量，通常需要 1-3 轮 refine 迭代

建议在使用时预留迭代优化时间，对于关键业务场景，应在生成后进行人工审核和补充测试。

资料来源

• CLI-Anything GitHub 仓库
• CLI-Hub 官方网站

ai-systems