7 阶段方法论详解

🔬 7 阶段方法论详解

CLI-Anything 的核心是一套全自动的 7 阶段流水线，能够将任意软件源码自动转换为 AI Agent 可用的 CLI harness。

无需手写一行代码，一条命令完成所有工作。

---

📋 7 阶段总览

阶段	名称	作用	输出
Phase 1	源码获取	克隆/下载软件源码	源码目录
Phase 2	结构分析	解析目录结构、文件类型	结构元数据
Phase 3	API 抽取	提取函数签名、类接口	API 文档（JSON）
Phase 4	语义理解	LLM 理解功能语义	功能描述（Markdown）
Phase 5	CLI 设计	设计命令行接口方案	CLI 规范（JSON）
Phase 6	代码生成	生成 Python CLI harness	完整源代码
Phase 7	打包发布	生成 setup.py + README	可安装 Python 包

---

🔍 Phase 1：源码获取

目标：获取目标软件的完整源码。

支持方式：

# 方式一：本地路径
/cli-anything ./gimp

# 方式二：Git 仓库 URL
/cli-anything https://github.com/GNOME/gimp.git

# 方式三：自动搜索（Claude Code 插件）
/cli-anything gimp

内部流程：

1. 判断输入是路径、URL 还是关键词
2. 如果是 URL，执行 git clone
3. 如果是关键词，调用 GitHub API 搜索最相关仓库
4. 校验源码完整性（检查关键文件是否存在）

---

🗋 Phase 2：结构分析

目标：理解软件的目录结构和代码组织方式。

分析内容：

• 目录树（过滤掉 node_modules、.git 等无关目录）
• 文件类型统计（.py、.js、.c、.java 等）
• 入口文件识别（main.py、./src/index.js 等）
• 构建系统识别（setup.py、package.json、CMakeLists.txt 等）

输出示例：

{
  "entry_points": ["bin/gimp", "app/main.py"],
  "languages": {"python": 342, "c": 1024, "javascript": 89},
  "build_system": "meson"
}

---

🔗 Phase 3：API 抽取

目标：从源码中提取所有可供调用的函数、类、方法。

抽取方式：

• Python：使用 ast 模块解析 AST，提取函数签名和 docstring
• C/C++：使用 clang 解析头文件
• JavaScript/TypeScript：使用 typescript compiler API
• 通用：正则表达式 + LLM 辅助校验

输出示例（函数列表）：

[
  {
    "name": "gimp_image_new",
    "file": "app/core/gimpimage.c",
    "signature": "gimp_image_new(width, height, type)",
    "docstring": "Create a new image with the specified width, height, and type."
  }
]

---

🧠 Phase 4：语义理解（LLM 核心）

目标：让 LLM 理解每个 API 的功能语义，而不仅是签名。

输入：Phase 3 抽取的 API 列表 + 源码片段 输出：每个 API 的功能描述（Markdown 格式）

Prompt 设计（简化版）：

你是一个代码分析专家。以下是 {SOFTWARE_NAME} 的部分源码和 API 列表。

请为每个 API 生成：
1. 一句话功能描述
2. 参数含义说明
3. 使用示例（如有）
4. 常见错误（如有）

要求：简洁、准确、面向 AI Agent 使用场景。

输出示例：

### gimp_image_new
- 功能：创建一个新的 GIMP 图像
- 参数：
  - width (int): 图像宽度（像素）
  - height (int): 图像高度（像素）
  - type (int): 图像类型（0=RGB, 1=Grayscale, 2=Indexed）
- 示例：`gimp_image_new(1920, 1080, 0)`

---

🎨 Phase 5：CLI 设计

目标：基于语义理解的结果，设计合理的命令行接口。

设计原则：

• 每个功能模块对应一个子命令（image、layer、filter…）
• 参数命名符合 CLI 惯例（--width、--height、--type）
• 支持 JSON 输入输出（方便 AI Agent 调用）
• 提供 --help 和 --json 选项

输出示例（CLI 规范）：

{
  "command": "cli-anything-gimp",
  "subcommands": [
    {
      "name": "image",
      "description": "操作 GIMP 图像",
      "actions": [
        {
          "name": "new",
          "description": "创建新图像",
          "args": [
            {"name": "--width", "type": "int", "required": true},
            {"name": "--height", "type": "int", "required": true},
            {"name": "--type", "type": "str", "default": "RGB"}
          ]
        }
      ]
    }
  ]
}

---

⚙️ Phase 6：代码生成

目标：根据 Phase 5 的 CLI 规范，自动生成完整的 Python CLI harness 源码。

生成内容：

• cli_main.py：CLI 主入口（使用 argparse 或 click）
• api_wrapper.py：API 封装层（调用原软件的 API）
• utils.py：工具函数（JSON 序列化、错误处理等）
• repl.py：交互式 REPL 实现

技术细节：

• 使用 subprocess 调用原软件（避免直接链接导致的兼容性问题）
• 使用 json 模块实现结构化输入输出
• 使用 try/except 实现健壮的错误处理
• 生成的代码符合 PEP 8 规范

生成代码示例（简化版）：

# cli_main.py (自动生成)
import argparse
import json
import subprocess

def cmd_image_new(args):
    """处理 `cli-anything-gimp image new` 命令"""
    width = args.width
    height = args.height
    img_type = args.type

    # 调用 GIMP 的 stdio API
    result = subprocess.run(
        ['gimp', '-c', f'script-fu-new-image {width} {height} {img_type}'],
        capture_output=True,
        text=True
    )

    if args.json:
        print(json.dumps({'status': 'success', 'image_id': ...}))
    else:
        print(f"Image created: {width}x{height} ({img_type})")

def main():
    parser = argparse.ArgumentParser(description='CLI for GIMP')
    subparsers = parser.add_subparsers(dest='command')

    # image 子命令
    image_parser = subparsers.add_parser('image')
    image_subparsers = image_parser.add_subparsers(dest='action')

    # image new
    new_parser = image_subparsers.add_parser('new')
    new_parser.add_argument('--width', type=int, required=True)
    new_parser.add_argument('--height', type=int, required=True)
    new_parser.add_argument('--type', type=str, default='RGB')
    new_parser.set_defaults(func=cmd_image_new)

    args = parser.parse_args()
    if hasattr(args, 'func'):
        args.func(args)
    else:
        parser.print_help()

if __name__ == '__main__':
    main()

---

📦 Phase 7：打包发布

目标：生成可安装的 Python 包（可通过 pip install -e . 安装）。

生成文件：

• setup.py：Python 包描述
• README.md：使用说明
• requirements.txt：依赖列表
• pyproject.toml：现代 Python 包配置（可选）

setup.py 示例（自动生成）：

from setuptools import setup, find_packages

setup(
    name='cli-anything-gimp',
    version='1.0.0',
    description='CLI harness for GIMP (generated by CLI-Anything)',
    packages=find_packages(),
    install_requires=[
        'argparse',
        'json5',
    ],
    entry_points={
        'console_scripts': [
            'cli-anything-gimp=cli_main:main',
        ]
    },
)

安装方式：

cd gimp/agent-harness
pip install -e .
cli-anything-gimp --help

---

🎯 完整流程演示

# 一行命令，完成所有 7 个阶段
/cli-anything ./gimp

# 输出：
> [Phase 1/7] 获取源码...
  ✅ 检测到本地路径 ./gimp
> [Phase 2/7] 分析结构...
  ✅ 识别为 C/Python 混合项目，发现 3 个入口点
> [Phase 3/7] 抽取 API...
  ✅ 抽取到 137 个 API
> [Phase 4/7] 语义理解（LLM）...
  ✅ 生成功能描述（137/137）
> [Phase 5/7] 设计 CLI...
  ✅ 设计完成：3 个子命令，18 个操作
> [Phase 6/7] 生成代码...
  ✅ 生成 cli_main.py (342 行)、api_wrapper.py (891 行)
> [Phase 7/7] 打包...
  ✅ 生成 setup.py、README.md

🎉 完成！CLI 已生成到 ./gimp/agent-harness
   安装：cd ./gimp/agent-harness && pip install -e .
   运行：cli-anything-gimp --help

---

📚 参考资料

• CLI-Anything 论文（arXiv）
• GitHub 仓库
• CLI-Hub 注册表

---

💡 提示：如果你不想自己运行这 7 个阶段，可以直接使用 CLI-Hub（pip install cli-anything-hub），一键安装社区已经生成好的 CLI！