CLI-Anything项目架构解析（通俗易懂版）

先来通俗理解

想象你有很多软件（比如 Blender、GIMP、LibreOffice），它们本来只有图形界面，没有命令行。你想用 AI 来控制它们，但 AI 不会直接点鼠标。

CLI-Anything 就是一本"AI 操作手册"：

你告诉 AI："去分析这个软件的代码，找出它的核心功能"
AI 按照手册（HARNESS.md）的 7 个步骤，自动写出一个命令行工具
这个命令行工具 可以像 blender-cli --export model.obj 这样被 AI 调用

它到底是什么？

它不是什么	它是什么
❌ 一个可双击运行的程序	✅ 一套方法论文档（告诉 AI 怎么干活）
❌ 一个框架库（像 Flask 那样 import）	✅ 一组AI 插件（Claude Code、Codex 等平台的命令）
❌ 直接帮你操作软件	✅ 一个代码生成器（AI 根据规范自动生成 CLI 代码）

打个比方

就像建筑行业的施工图纸 + 施工规范：

HARNESS.md = 施工规范（"第一步勘察、第二步设计、第三步施工..."）
cli-anything-plugin/ = 给不同施工队（Claude、Codex、OpenCode）的专用图纸
生成的 harness/ = 最终盖出来的房子（针对某个软件的 CLI 工具）

用户不直接运行 CLI-Anything，而是让 AI 运行它，去生成真正能用的命令行工具。

CLI-Anything 的代码架构可以从目录结构、核心模块和主流程实现三个维度分析。

一、顶层目录结构

仓库根目录按职责划分为三大区域：

区域	目录	职责
核心方法论与插件	`cli-anything-plugin/`	存放唯一的 7 阶段 SOP（`HARNESS.md`）、Claude Code 插件命令、统一 REPL 皮肤、辅助脚本
多平台适配层	`opencode-commands/`、`codex-skill/`、`hermes-skill/`、`reasonix-skill/`、`qoder-plugin/` 等	将同一套方法论绑定到不同 Agent 平台的命令体系
软件 Harness 实例	`gimp/agent-harness/`、`blender/agent-harness/`、`libreoffice/agent-harness/` 等 40+ 目录	每个目标软件独立生成的 Python CLI 包，是方法论的执行产物

二、核心模块详解

1. `cli-anything-plugin/` --- 唯一权威来源

这是整个项目的"源码真理"所在，关键文件包括：

HARNESS.md：7 阶段方法论的完整 SOP，定义了从代码分析到发布的标准流程。所有平台适配器都引用这份文件。
commands/ ：Claude Code 的斜杠命令定义
- cli-anything.md --- 主入口，触发完整 7 阶段流水线
- refine.md --- 对已有 Harness 做增量 Gap Analysis
- test.md、validate.md --- 测试与质量校验
repl_skin.py ：统一 REPL 界面组件（Banner、提示符、历史记录、进度条、表格输出），每个生成的 Harness 都会复制到 utils/repl_skin.py
guides/：细分场景指南（session 加锁、预览方法论、PyPI 发布、MCP 后端等）

2. 多平台适配层

各平台并不重新实现流程，而是引用同一套 HARNESS.md 和 cli-anything-plugin/ 中的模板，仅做命令格式和工具绑定差异：

平台	入口形式	安装方式
Claude Code	`/cli-anything <path>`	插件市场 `/plugin marketplace add`
OpenCode	`/cli-anything <path>`	复制 `*.md` + `HARNESS.md` 到 `~/.config/opencode/commands/`
Codex	自然语言指令	`codex-skill/scripts/install.sh` 安装到 `~/.codex/skills/`
Hermes / Reasonix	自然语言指令	各自 skill 安装器，绑定平台的 `bash`/`write_file`/`edit_file` 工具

3. 生成的 Harness 包结构

每个软件的 CLI 是一个独立 Python 包，遵循严格模板：

复制代码

<software>/agent-harness/
├── setup.py                          # Phase 7: PyPI 配置
├── <SOFTWARE>.md                     # 针对该软件的架构 SOP
├── cli_anything/                     # PEP 420 命名空间包（无 __init__.py）
│   └── <software>/
│       ├── __init__.py
│       ├── __main__.py               # python -m cli_anything.<software>
│       ├── <software>_cli.py         # 主 CLI：Click Group + REPL 入口
│       ├── core/
│       │   ├── project.py            # 项目增删改查
│       │   ├── export.py           # 渲染/导出管道
│       │   └── session.py          # 状态、undo/redo
│       ├── utils/
│       │   ├── <software>_backend.py # 调用真实软件后端（subprocess）
│       │   └── repl_skin.py        # 从插件复制的统一 REPL 皮肤
│       └── tests/
│           ├── TEST.md             # 测试计划与结果
│           ├── test_core.py        # 单元测试（合成数据，零外部依赖）
│           └── test_full_e2e.py    # E2E 测试（必须调用真实后端）
└── examples/                         # 示例脚本

三、主流程在哪实现

CLI-Anything 的主流程不是由传统意义上的一个 Python main.py 驱动 ，而是由 Agent 读取 HARNESS.md 方法论后，自主执行 7 阶段任务 实现的。可以理解为"提示词即主流程"（Prompt-as-Code）。

7 阶段流水线（主流程）

完整主流程定义在 cli-anything-plugin/HARNESS.md 中，各阶段如下：

阶段	名称	做什么	输出产物
P1	Codebase Analysis	扫描源码，识别后端引擎、数据模型、GUI→API 映射、现有 CLI 工具	`<SOFTWARE>.md`（软件专属 SOP）
P2	CLI Architecture Design	设计命令分组（project/export/config）、状态模型、输出格式（人读 + JSON）	架构文档写入 SOP
P3	Implementation	实现数据层 → Probe 命令 → 变更命令 → 后端包装器 → 渲染导出 → Session 管理 → REPL	`cli_anything/<software>/` 完整代码
P4	Test Planning	规划单元测试、E2E 测试、工作流测试	`TEST.md` Part 1
P5	Test Implementation	编写 `test_core.py`（合成数据）、`test_full_e2e.py`（真实后端 + 文件探针）	可运行测试套件
P6	Document	更新测试文档与结果	`TEST.md` Part 2
P6.5	SKILL.md Generation	生成 Agent 可发现的 Skill 定义	`skills/cli-anything-<software>/SKILL.md`
P7	Publish	编写 `setup.py`，PEP 420 命名空间包，安装到 PATH	可 pip 安装的包

触发入口

Claude Code ：/cli-anything <software-path-or-repo> 命令，定义在 cli-anything-plugin/commands/cli-anything.md
OpenCode ：/cli-anything <path>，命令定义在 opencode-commands/cli-anything.md，引用同一份 HARNESS.md
Codex ：通过 codex-skill/SKILL.md 中的自然语言指令触发，如 "Use CLI-Anything to build a harness for ./gimp"

关键设计约束（主流程的"硬规则"）

HARNESS.md 中规定了主流程必须遵守的约束，这些约束决定了代码生成的风格：

真实后端原则 ：必须调用真实软件（如 libreoffice --headless、blender --background、gimp -i -b），禁止用 Python 库模拟功能。
双模式交互 ：每个 CLI 必须同时支持 REPL 状态机模式 （invoke_without_command=True，裸命令进入 REPL）和 子命令模式（脚本/流水线）。
JSON 输出 ：所有命令必须支持 --json 标志，供 Agent 消费。
测试不降级 ：E2E 测试若后端软件未安装，必须失败（fail）而非跳过（skip），确保功能真实性。
命名空间包 ：所有 Harness 共享 cli_anything 命名空间（PEP 420），便于统一发现。

四、总结

CLI-Anything 的主流程实现 并不在某一具体 Python 文件的 if __name__ == "__main__" 中，而是分布在：

流程定义层 ：cli-anything-plugin/HARNESS.md --- 7 阶段 SOP，是"主流程的规范"
平台触发层 ：cli-anything-plugin/commands/cli-anything.md（Claude Code）、opencode-commands/*.md（OpenCode）、codex-skill/SKILL.md（Codex）--- 将规范转化为 Agent 可执行的指令
产物执行层 ：各 <software>/agent-harness/cli_anything/<software>/<software>_cli.py --- 最终生成的 Click CLI 入口，包含 REPL 和子命令双模式

简言之，这是一个**"方法论驱动、Agent 执行、产物标准化"**的架构，而非传统框架式的"调用库函数"架构。

它不是传统意义上的"软件"，更像是一套让 AI 自动给软件"做外套"的说明书和工具包。