CLI-Anything 教程 1：入门与安装（Claude Code / Cursor / Codex / OpenCode）

教程概述

系列目录：CLI-Anything 教程系列索引

本教程是 CLI-Anything 系列的第一篇，将带你完成从零开始的安装配置过程。无论你使用哪个平台，都能找到对应的安装方法。

你将学到

✅ CLI-Anything 的核心工作原理
✅ 在 4 个主流平台上安装 CLI-Anything
✅ 验证安装是否成功
✅ 常见问题排查

CLI-Anything 是什么？

CLI-Anything 是一个自动化 CLI 生成框架，通过分析软件源代码，自动生成完整的命令行工具，使任何软件都能被 AI Agent 调用。

核心特点

7 阶段自动化 - 从分析到发布全自动完成
多平台支持 - Claude Code、Cursor、Codex、OpenCode
生产级质量 - 16+ 软件案例，1,800+ 测试验证
REPL + JSON - 双模式设计，兼顾人机交互
真实软件集成 - 调用真实软件，非模拟实现

工作流程示意

flowchart TD
    A[软件源代码] --> B{阶段1: Analyze}
    B --> C{阶段2: Design}
    C --> D{阶段3: Implement}
    D --> E{阶段4: Plan Tests}
    E --> F{阶段5: Write Tests}
    F --> G{阶段6: Document}
    G --> H{阶段7: Publish}
    H --> I[完整 CLI 工具]

    style B fill:#e3f2fd
    style C fill:#e3f2fd
    style D fill:#e8f5e9
    style E fill:#fff3e0
    style F fill:#fff3e0
    style G fill:#fff3e0
    style H fill:#f3e5f5

安装前准备

系统要求

组件	要求
Python	3.10+
Git	已配置用户名和邮箱
目标软件	需要安装（如 GIMP、Blender 等）
AI 平台	Claude Code / Cursor / Codex / OpenCode

Python 环境检查

# 检查 Python 版本
python3 --version
# 要求: Python 3.10+

# 检查 pip
pip3 --version

# 检查 Click（CLI-Anything 使用 Click 框架）
pip3 show click
# 要求: Click >= 8.0

Git 配置

确保 Git 已正确配置：

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

平台 1：Claude Code 安装

方法 A：通过 Plugin Marketplace（推荐）

步骤 1：注册 Marketplace

在 Claude Code 中运行：

/plugin marketplace add HKUDS/CLI-Anything

步骤 2：安装插件

/plugin install cli-anything

步骤 3：验证安装

# 查看可用命令
/cli-anything --help

期望输出：

CLI-Anything: Generate CLI harnesses for any software

Usage:
  /cli-anything <software-path-or-repo>  Build complete CLI harness
  /cli-anything:refine <path> [focus]     Refine existing harness
  /cli-anything:test <path>               Run tests
  /cli-anything:validate <path>           Validate standards

方法 B：手动安装

如果 Marketplace 不可用：

# 克隆仓库
git clone https://github.com/HKUDS/CLI-Anything.git

# 复制插件到 Claude Code 插件目录
cp -r CLI-Anything/cli-anything-plugin ~/.claude/plugins/cli-anything

# 重载插件
/reload-plugins

Windows 用户注意事项

Claude Code 通过 bash 运行 shell 命令。在 Windows 上：

# 选项 1：安装 Git for Windows（推荐）
# 下载地址: https://git-scm.com/download/win
# 包含 bash 和 cygpath

# 选项 2：使用 WSL
# 在 WSL 环境中运行 Claude Code

更新插件

/plugin update cli-anything

平台 2：Cursor 安装

安装步骤

步骤 1：打开 Cursor

启动 Cursor IDE，打开 Agent 聊天窗口。

步骤 2：安装插件

在 Agent 聊天中输入：

Fetch and follow instructions from https://raw.githubusercontent.com/HKUDS/CLI-Anything/main/.cursor/INSTALL.md

步骤 3：确认安装

Cursor 会自动下载并安装。安装完成后会显示确认消息。

配置建议

在 Cursor 的设置中，确保以下选项已启用：

✅ Agent Mode
✅ Auto-accept suggestions（可选，建议初期关闭）
✅ Git integration

验证安装

在 Cursor 中打开一个项目，然后在 Agent 聊天中输入：

/cli-anything --help

如果显示 CLI-Anything 的帮助信息，说明安装成功！

平台 3：Codex 安装

安装命令

告诉 Codex：

Fetch and follow instructions from https://raw.githubusercontent.com/HKUDS/CLI-Anything/main/.codex/INSTALL.md

详细配置

详见官方文档：codex-skill/README.md

自定义配置

创建 ~/.codex/config.yaml：

cli-anything:
  enabled: true
  auto_trigger: true
  defaults:
    output_format: json
    include_tests: true
    include_skill_md: true

平台 4：OpenCode 安装

安装命令

告诉 OpenCode：

Fetch and follow instructions from https://raw.githubusercontent.com/HKUDS/CLI-Anything/main/.opencode/INSTALL.md

详细配置

详见官方文档：.opencode/README.md

环境变量配置

# ~/.bashrc 或 ~/.zshrc
export CLI_ANYTHING_ENABLED=true
export CLI_ANYTHING_AUTO_TRIGGER=true
export CLI_ANYTHING_OUTPUT_FORMAT=json

验证安装成功

测试场景 1：基础命令

输入：

/cli-anything --help

期望行为：

✅ 显示帮助信息，包含所有子命令 → 成功
❌ 命令未找到 → 失败

测试场景 2：为 GIMP 生成 CLI

前提：已安装 GIMP

输入：

/cli-anything /usr/share/gimp  # 或你的 GIMP 路径

期望行为：

✅ AI 开始分析 GIMP 源码，进入 Phase 1 → 成功
❌ 报错 “path not found” → 检查路径是否正确

测试场景 3：查看生成的 CLI

输入：

ls gimp/agent-harness/

期望输出：

gimp/agent-harness/
├── cli_anything/
│   ├── gimp/
│   ├── __init__.py
│   ├── cli.py           # 主 CLI 入口
│   ├── repl.py          # REPL 实现
│   ├── core/            # 核心模块
│   └── tests/           # 测试目录
├── setup.py
├── README.md
└── SKILL.md             # AI 技能定义

常见问题排查

问题 1：插件不加载

症状：/cli-anything 命令未找到

排查步骤：

检查插件是否正确安装：
```
/plugin list
```
确认插件名称正确：
```
/plugin list | grep cli-anything
```
尝试重载插件：
```
/reload-plugins
```
重启 Claude Code

问题 2：生成过程报错

症状：运行 /cli-anything 时报错

常见原因与解决方案：

# 错误："Python 3.10+ required"
# 解决方案：升级 Python
pyenv install 3.11
pyenv global 3.11

# 错误："Click not found"
# 解决方案：安装依赖
pip3 install click>=8.0

# 错误："Target software not found"
# 解决方案：确认软件已安装
which gimp
which blender

问题 3：权限不足

症状：无法写入生成的文件

解决方案：

# 检查目录权限
ls -la /path/to/software

# 修复权限（如果需要）
chmod -R u+w /path/to/software

# 或使用 sudo（不推荐，仅测试）
sudo /cli-anything /path/to/software

问题 4：Windows 路径问题

症状：cygpath: command not found

解决方案：

# 安装 Git for Windows
# 或使用 WSL
# 或使用完整路径（Windows 格式）
/cli-anything "C:\Program Files\GIMP 2\share\gimp"

问题 5：生成质量不佳

症状：生成的 CLI 功能不完整或有错误

原因：CLI-Anything 依赖强大的基础模型（如 Claude Opus 4.6、GPT-4.5）

解决方案：

使用更强大的模型

运行 refine 命令进行迭代改进：

/cli-anything:refine ./gimp "focus on layer operations"

最佳实践建议

1. 从简单软件开始

不要一开始就尝试为 Blender 或 GIMP 生成 CLI。建议顺序：

第 1 步：简单工具（如命令行工具包装）
第 2 步：中等复杂度（如 Mubu、Zotero）
第 3 步：复杂软件（如 GIMP、Blender）

2. 配置个性化

根据你的需求调整配置：

# ~/.cli-anything/config.yaml
cli-anything:
  # 快速原型模式
  mode: rapid
  skip_tests: false
  skip_skill_md: false

  # 生产环境模式
  mode: production
  require_tests: true
  coverage_minimum: 80

3. 版本控制

生成的 CLI 应该纳入版本控制：

# 初始化 git
cd software/agent-harness
git init
git add .
git commit -m "Initial CLI harness generated by CLI-Anything"

# 后续修改也提交
git add .
git commit -m "Refine: add batch processing commands"

性能优化

模型选择

cli-anything:
  model:
    phase_1_analyze: claude-opus-4-6      # 分析阶段需要最强模型
    phase_2_design: claude-opus-4-6       # 设计阶段需要最强模型
    phase_3_implement: claude-sonnet-4-6  # 实现可用较快的模型
    phase_4_7: claude-sonnet-4-6          # 测试和发布用较快的模型

缓存设计文档

cli-anything:
  cache:
    enabled: true
    ttl_hours: 24
    path: ~/.cli-anything/cache/

下一步

安装完成后，继续学习：

📖 教程 2：第一阶段：软件分析
📖 教程 3：第二阶段：架构设计

参考资源

官方仓库：github.com/HKUDS/CLI-Anything
CLI-Hub：hkuds.github.io/CLI-Anything
HARNESS.md：核心方法论文档
QUICKSTART.md：5 分钟快速开始

📚 完整教程系列导航

你正在阅读本系列的 教程 1，以下是完整目录：

系列导航：

教程概述

你将学到

CLI-Anything 是什么？

核心特点

工作流程示意

安装前准备

系统要求

Python 环境检查

Git 配置

平台 1：Claude Code 安装

方法 A：通过 Plugin Marketplace（推荐）

方法 B：手动安装

Windows 用户注意事项

更新插件

平台 2：Cursor 安装

安装步骤

配置建议

验证安装

平台 3：Codex 安装

安装命令

详细配置

自定义配置

平台 4：OpenCode 安装

安装命令

详细配置

环境变量配置

验证安装成功

测试场景 1：基础命令

测试场景 2：为 GIMP 生成 CLI

测试场景 3：查看生成的 CLI

常见问题排查

问题 1：插件不加载

问题 2：生成过程报错

问题 3：权限不足

问题 4：Windows 路径问题

问题 5：生成质量不佳

最佳实践建议

1. 从简单软件开始

2. 配置个性化

3. 版本控制

性能优化

模型选择

缓存设计文档

下一步

参考资源

📚 完整教程系列导航

🍪 Cookie 使用通知

Cookie 偏好设置

必要 Cookie

分析 Cookie

广告 Cookie