CLI-Anything 源码分析：代码分析与AI提示词生成

# CLI-Anything 源码分析：代码分析与AI提示词生成

## 1. 项目结构分析

### 1.1 核心目录结构

“`
CLI-Anything/
├── cli-anything-plugin/ # Claude Code 插件
│ ├── HARNESS.md # 核心方法论文档
│ ├── commands/ # 插件命令定义
│ │ ├── cli-anything.md # 主要构建命令
│ │ ├── refine.md # 扩展现有 harness 覆盖范围
│ │ ├── test.md # 测试运行器
│ │ └── validate.md # 标准验证
│ └── repl_skin.py # 统一的 REPL 界面
├── codex-skill/ # Codex 技能入口点
├── gimp/agent-harness/ # GIMP CLI (107 测试)
├── blender/agent-harness/ # Blender CLI (208 测试)
├── inkscape/agent-harness/ # Inkscape CLI (202 测试)
├── audacity/agent-harness/ # Audacity CLI (161 测试)
├── libreoffice/agent-harness/ # LibreOffice CLI (158 测试)
├── obs-studio/agent-harness/ # OBS Studio CLI (153 测试)
├── kdenlive/agent-harness/ # Kdenlive CLI (155 测试)
├── shotcut/agent-harness/ # Shotcut CLI (154 测试)
├── zoom/agent-harness/ # Zoom CLI (22 测试)
├── drawio/agent-harness/ # Draw.io CLI (138 测试)
└── anygen/agent-harness/ # AnyGen CLI (50 测试)
“`

### 1.2 关键文件分析

#### 1.2.1 `cli-anything-plugin/commands/cli-anything.md`

这是 CLI-Anything 的主要命令定义文件，包含了完整的 7 阶段流程：

– **阶段 0：源码获取** – 克隆 GitHub 仓库或验证本地路径
– **阶段 1：代码库分析** – 分析源代码、后端引擎和数据模型
– **阶段 2：CLI 架构设计** – 设计命令组、状态模型和输出格式
– **阶段 3：实现** – 创建目录结构、实现核心模块和 Click CLI
– **阶段 4：测试规划** – 创建 TEST.md 测试计划
– **阶段 5：测试实现** – 编写单元测试和端到端测试
– **阶段 6：测试文档** – 运行测试并更新 TEST.md
– **阶段 7：PyPI 发布和安装** – 创建 setup.py 并测试本地安装

#### 1.2.2 `cli-anything-plugin/HARNESS.md`

这是 CLI-Anything 的核心方法论文档，定义了：

– **代码分析方法论** – 如何识别后端引擎、映射 GUI 操作到 API 调用
– **CLI 架构设计原则** – 交互模型、命令组、状态模型和输出格式
– **实现指南** – 数据层、后端集成、渲染/导出和会话管理
– **测试策略** – 单元测试、端到端测试和输出验证
– **关键原则** – 使用真实软件、硬依赖、直接操作原生格式

## 2. 代码分析部分

### 2.1 代码分析流程

根据 HARNESS.md，代码分析阶段（阶段 1）包括以下步骤：

1. **识别后端引擎** – 大多数 GUI 应用将表示层与逻辑分离。找到核心库/框架（例如，Shotcut 的 MLT，GIMP 的 ImageMagick）。

2. **映射 GUI 操作到 API 调用** – 每个按钮点击、拖动和菜单项都对应一个函数调用。编目这些映射。

3. **识别数据模型** – 它使用什么文件格式？项目状态如何表示？（XML、JSON、二进制、数据库？）

4. **查找现有的 CLI 工具** – 许多后端附带自己的 CLI（`melt`、`ffmpeg`、`convert`）。这些是构建块。

5. **记录命令/撤销系统** – 如果应用程序有撤销/重做功能，它可能使用命令模式。这些命令是您的 CLI 操作。

### 2.2 代码分析技术

CLI-Anything 使用以下技术进行代码分析：

– **静态代码分析** – 扫描源代码文件，识别核心类、函数和 API
– **依赖分析** – 识别软件的核心依赖和后端引擎
– **文件格式分析** – 分析项目文件格式和数据结构
– **API 映射** – 将 GUI 操作映射到底层 API 调用
– **现有工具分析** – 识别并利用现有的 CLI 工具和脚本接口

## 3. AI 提示词生成部分

### 3.1 提示词结构

CLI-Anything 的 AI 提示词结构主要在 `cli-anything-plugin/commands/` 目录下的文件中定义，特别是 `cli-anything.md`。这些提示词指导 AI 代理执行以下任务：

1. **源码分析** – 分析软件的源代码结构和功能
2. **架构设计** – 设计适合该软件的 CLI 架构
3. **代码生成** – 生成完整的 CLI 实现
4. **测试规划** – 规划测试策略和测试用例
5. **测试实现** – 实现测试代码
6. **测试文档** – 记录测试结果
7. **发布准备** – 准备 PyPI 发布和安装

### 3.2 提示词示例

以下是 CLI-Anything 中使用的 AI 提示词示例：

“`markdown
# cli-anything Command

Build a complete, stateful CLI harness for any GUI application.

## CRITICAL: Read HARNESS.md First

**Before doing anything else, you MUST read `./HARNESS.md`.** It defines the complete methodology, architecture standards, and implementation patterns. Every phase below follows HARNESS.md. Do not improvise — follow the harness specification.

## Usage

“`bash
/cli-anything
“`

## Arguments

– “ – **Required.** Either:
– A **local path** to the software source code (e.g., `/home/user/gimp`, `./blender`)
– A **GitHub repository URL** (e.g., `https://github.com/GNOME/gimp`, `github.com/blender/blender`)

If a GitHub URL is provided, the agent clones the repo locally first, then works on the local copy.

**Note:** Software names alone (e.g., “gimp”) are NOT accepted. You must provide the actual source code path or repository URL so the agent can analyze the codebase.

## What This Command Does

This command implements the complete cli-anything methodology to build a production-ready CLI harness for any GUI application. **All phases follow the standards defined in HARNESS.md.**

### Phase 0: Source Acquisition
– If “ is a GitHub URL, clone it to a local working directory
– Verify the local path exists and contains source code
– Derive the software name from the directory name (e.g., `/home/user/gimp` -> `gimp`)

### Phase 1: Codebase Analysis
– Analyzes the local source code
– Analyzes the backend engine and data model
– Maps GUI actions to API calls
– Identifies existing CLI tools
– Documents the architecture

### Phase 2: CLI Architecture Design
– Designs command groups matching the app’s domains
– Plans the state model and output formats
– Creates the software-specific SOP document (e.g., GIMP.md)

### Phase 3: Implementation
– Creates the directory structure: `agent-harness/cli_anything//core`, `utils`, `tests`
– Implements core modules (project, session, export, etc.)
– Builds the Click-based CLI with REPL support
– Implements `–json` output mode for agent consumption
– All imports use `cli_anything..*` namespace

### Phase 4: Test Planning
– Creates `TEST.md` with comprehensive test plan
– Plans unit tests for all core modules
– Plans E2E tests with real files
– Designs realistic workflow scenarios

### Phase 5: Test Implementation
– Writes unit tests (`test_core.py`) – synthetic data, no external deps
– Writes E2E tests (`test_full_e2e.py`) – real files, full pipeline
– Implements workflow tests simulating real-world usage
– Adds output verification (pixel analysis, format validation, etc.)
– Adds `TestCLISubprocess` class with `_resolve_cli(“cli-anything-“)`
that tests the installed command via subprocess (no hardcoded paths or CWD)

### Phase 6: Test Documentation
– Runs all tests with `pytest -v –tb=no`
– Appends full test results to `TEST.md`
– Documents test coverage and any gaps

### Phase 7: PyPI Publishing and Installation
– Creates `setup.py` with `find_namespace_packages(include=[“cli_anything.*”])`
– Package name: `cli-anything-`, namespace: `cli_anything.`
– `cli_anything/` has NO `__init__.py` (PEP 420 namespace package)
– Configures console_scripts entry point for PATH installation
– Tests local installation with `pip install -e .`
– Verifies CLI is available in PATH: `which cli-anything-`
“`

### 3.3 提示词生成策略

CLI-Anything 使用以下策略生成有效的 AI 提示词：

1. **结构化提示** – 使用清晰的标题和章节组织提示内容
2. **明确的指令** – 提供具体的步骤和要求
3. **方法论引用** – 引用 HARNESS.md 作为权威指南
4. **示例代码** – 提供代码示例和模板
5. **成功标准** – 明确定义成功的标准和要求
6. **错误处理** – 提供错误处理和边缘情况的指导

## 4. 核心实现技术

### 4.1 代码分析实现

CLI-Anything 的代码分析实现依赖于以下技术：

– **静态代码分析** – 扫描源代码文件，识别核心类和函数
– **依赖解析** – 分析软件的依赖关系和后端引擎
– **文件格式分析** – 分析项目文件格式和数据结构
– **API 映射** – 将 GUI 操作映射到底层 API 调用
– **模式识别** – 识别常见的代码模式和架构

### 4.2 AI 提示词生成实现

CLI-Anything 的 AI 提示词生成实现包括：

– **模板化提示** – 使用预定义的模板生成提示词
– **上下文感知** – 根据软件类型和结构调整提示词
– **方法论集成** – 集成 HARNESS.md 中的方法论指导
– **输出格式控制** – 确保生成的代码符合预期格式
– **测试驱动** – 确保生成的代码通过测试

## 5. 代码生成过程

### 5.1 代码生成流程

CLI-Anything 的代码生成流程包括：

1. **分析阶段** – 分析软件的源代码和架构
2. **设计阶段** – 设计 CLI 架构和命令组
3. **实现阶段** – 生成核心模块和 CLI 代码
4. **测试阶段** – 生成测试代码和测试计划
5. **文档阶段** – 生成文档和使用指南
6. **发布阶段** – 准备 PyPI 发布和安装

### 5.2 生成的代码结构

生成的 CLI 代码结构遵循以下模式：

“`
agent-harness/
├── .md # 软件特定的 SOP
├── setup.py # PyPI 包配置
└── cli_anything/ # 命名空间包（无 __init__.py）
└── / # 子包
├── README.md # 安装和使用指南
├── _cli.py # 主要 CLI 入口点
├── core/ # 核心模块
│ ├── project.py
│ ├── session.py
│ ├── export.py
│ └── …
├── utils/ # 工具
└── tests/
├── TEST.md # 测试计划和结果
├── test_core.py # 单元测试
└── test_full_e2e.py # 端到端测试
“`

## 6. 关键技术亮点

### 6.1 真实软件集成

CLI-Anything 的核心原则是使用真实软件作为后端，而不是重新实现其功能：

– **使用软件的原生 CLI/脚本接口**作为后端
– **生成有效的项目/中间文件**（ODF、MLT XML、.blend、SVG 等）
– **调用真实软件**进行渲染和导出
– **验证输出**确保渲染结果正确

### 6.2 命名空间包架构

CLI-Anything 使用 PEP 420 命名空间包，允许多个 CLI 包在同一 Python 环境中共存：

– `cli_anything/` 目录没有 `__init__.py`
– 每个子包（`gimp/`、`blender/` 等）有 `__init__.py`
– 所有导入使用 `cli_anything.` 前缀
– 多个 CLI 可以独立安装/卸载

### 6.3 统一的 REPL 界面

CLI-Anything 提供统一的 REPL 界面（`repl_skin.py`），确保所有生成的 CLI 具有一致的用户体验：

– 品牌横幅和样式化提示
– 命令历史和自动补全
– 标准化的输出格式
– 统一的错误和成功消息

## 7. 代码分析与 AI 提示词生成的关系

### 7.1 相互依赖

代码分析和 AI 提示词生成是相互依赖的：

– **代码分析**提供了生成准确 AI 提示词所需的信息
– **AI 提示词生成**指导 AI 代理执行代码分析和生成
– **循环反馈** – 分析结果影响提示词生成，提示词生成指导进一步分析

### 7.2 协同工作流程

1. **初始分析** – AI 代理分析软件源代码
2. **提示词调整** – 根据分析结果调整提示词
3. **代码生成** – 基于调整后的提示词生成 CLI 代码
4. **测试验证** – 测试生成的代码
5. **迭代改进** – 根据测试结果改进代码和提示词

## 8. 应用示例

### 8.1 示例：为 GIMP 生成 CLI

1. **代码分析** – 分析 GIMP 源代码，识别 Script-Fu API 和 XCF 文件格式
2. **架构设计** – 设计命令组（项目、图层、滤镜、导出）
3. **实现** – 生成核心模块和 CLI 代码
4. **测试** – 生成测试代码并验证功能
5. **发布** – 准备 PyPI 发布和安装

### 8.2 示例：为 LibreOffice 生成 CLI

1. **代码分析** – 分析 LibreOffice 源代码，识别 ODF 文件格式和 headless 模式
2. **架构设计** – 设计命令组（文档、 writer、 calc、 impress、导出）
3. **实现** – 生成核心模块和 CLI 代码
4. **测试** – 生成测试代码并验证功能
5. **发布** – 准备 PyPI 发布和安装

## 9. 改进建议

### 9.1 代码分析改进

1. **自动化程度** – 增加自动化代码分析工具，减少手动分析
2. **深度分析** – 增加对复杂代码库的深度分析能力
3. **模式识别** – 改进对常见代码模式的识别能力
4. **依赖分析** – 增强对软件依赖关系的分析

### 9.2 AI 提示词生成改进

1. **个性化提示** – 根据软件类型和结构生成个性化提示
2. **上下文感知** – 增强提示词的上下文感知能力
3. **错误处理** – 改进提示词中的错误处理指导
4. **测试驱动** – 增加测试驱动的提示词生成

### 9.3 整体流程改进

1. **并行处理** – 增加并行处理能力，加快大型代码库的分析
2. **增量更新** – 支持增量更新，避免重新生成整个 CLI
3. **用户反馈** – 增加用户反馈机制，改进生成结果
4. **文档生成** – 增强自动文档生成能力

## 10. 结论

CLI-Anything 是一个强大的工具，通过代码分析和 AI 提示词生成，将 GUI 应用程序转换为 AI 代理可使用的 CLI 接口。它的核心优势在于：

1. **使用真实软件**作为后端，确保功能完整性和准确性
2. **结构化的 7 阶段流程**，确保生成的 CLI 质量
3. **统一的架构设计**，确保所有生成的 CLI 具有一致的用户体验
4. **强大的测试策略**，确保生成的 CLI 可靠可用
5. **命名空间包架构**，允许多个 CLI 包共存

通过不断改进代码分析和 AI 提示词生成技术，CLI-Anything 有望成为 AI 代理与传统软件之间的重要桥梁，为 AI 时代的软件使用方式带来革命性的变化。