7 阶段自动流水线架构

学习目标

• 理解 7 阶段流水线的每个阶段的输入/输出契约
• 掌握 Agent 驱动 vs 脚本生成的架构选择原因
• 了解 refine 机制的 Gap Analysis 与增量非破坏性扩展
• 理解为什么测试计划先于测试编写

前置知识

本章涉及 Agent-Native 软件设计的通用原理，建议先阅读：

• Agent-Native 软件设计范式

下文直接聚焦 CLI-Anything 的流水线架构实现。

---

项目实践

流水线全景

Phase 0：源码获取

输入：本地路径或 GitHub URL 输出：本地源码目录 关键决策：如果提供 GitHub URL，Agent 先 clone 到本地再工作。不接受仅软件名——必须有源码。

Phase 1：代码分析

输入：源码目录 输出：架构分析文档 Agent 执行：

• 扫描顶层目录结构，判断项目类型
• 识别后端引擎（核心库/框架）
• 映射 GUI 操作到 API 调用
• 识别数据模型（文件格式）
• 发现现有 CLI 工具
• 梳理命令/撤销系统

Phase 2：架构设计

输入：Phase 1 的分析结果 输出：CLI 架构设计文档 + 软件专属 SOP（如 GIMP.md） Agent 执行：

• 设计命令组（匹配应用逻辑域）
• 规划状态模型（什么持久化、如何序列化）
• 设计输出格式（人类可读 + JSON）
• 编写软件特定的 SOP 文档

Phase 3：实现

输入：Phase 2 的设计文档 + HARNESS.md 输出：完整的 CLI 代码（agent-harness/ 目录） 目录结构：

agent-harness/
├── <SOFTWARE>.md              # 软件 SOP
├── setup.py                   # PEP 420 namespace package
├── cli_anything/              # 无 __init__.py（namespace）
│   └── <software>/            # 有 __init__.py（sub-package）
│       ├── <software>_cli.py  # Click CLI + REPL
│       ├── core/              # project / session / export / 领域模块
│       ├── utils/             # <software>_backend.py + repl_skin.py
│       └── tests/             # 测试目录（Phase 5 填充）

关键实现步骤：

1. 数据层先行（XML/JSON 操作项目文件）
2. 内省命令（info / list / status）
3. 变异命令（每个逻辑操作一个命令）
4. 后端集成（utils/<software>_backend.py）
5. 渲染/导出管线
6. 会话管理 + 文件锁定
7. REPL（统一 Skin）

Phase 4：测试计划

输入：Phase 3 的实现代码 输出：TEST.md（测试计划部分）

在写任何测试代码之前，先创建 TEST.md 文件：

• 测试清单：计划写哪些测试文件、预计测试数
• 单元测试计划：每个核心模块、边界情况
• E2E 测试计划：真实工作流场景
• 现实工作流场景：多段剪辑、蒙太奇、画中画、色彩分级等

Phase 5：测试编写

输入：TEST.md 测试计划 + 实现代码 输出：test_core.py + test_full_e2e.py

四层测试：

1. 单元测试：合成数据，无外部依赖
2. E2E 原生测试：中间文件格式验证
3. E2E 真实后端测试：调用真实软件，验证最终输出
4. CLI 子进程测试：通过 _resolve_cli() 测试已安装命令

Phase 6：测试文档

输入：测试结果 输出：TEST.md（追加测试结果）

执行 pytest -v --tb=no，将完整输出追加到 TEST.md。

Phase 6.5：SKILL.md 生成

输入：完整的 Harness 代码 输出：skills/cli-anything-<software>/SKILL.md + 兼容拷贝

使用 skill_generator.py 从 Click 装饰器自动提取元数据。

Phase 7：发布安装

输入：setup.py + 完整代码 输出：已安装的 CLI（pip install -e .）

关键：cli_anything/ 无 __init__.py（PEP 420 namespace），每个子包独立安装。

Refine 机制

/cli-anything:refine ./gimp                                    # 全面 Gap Analysis
/cli-anything:refine ./gimp "batch processing and filters"     # 针对性扩展

refine 命令执行 Gap Analysis：对比软件的全部能力与当前 CLI 覆盖率，识别缺口，实现新命令、测试和文档。非破坏性——每次运行增量的，可以多次执行逐步扩展覆盖。

---

问题与规避

问题	规避策略
Agent 不理解 HARNESS.md	需要前沿模型（Opus/Sonnet 级别）。README 明确标注依赖强模型
单次运行覆盖不全	refine 机制：多次执行增量扩展
测试计划与实际代码脱节	Phase 4 在代码完成后写测试计划，Phase 5 按计划编写
源码非开放（编译二进制）	HARNESS.md 限制：需要源码。反编译后质量会显著下降

设计取舍

Agent 驱动 vs 脚本生成

选择：Agent 阅读 HARNESS.md 自主生成代码，而非编写 Python 生成器脚本。

原因：

• 生成器脚本需要硬编码所有边界情况，维护成本随软件类型增长
• Agent 可以理解模式并灵活应用于新软件
• HARNESS.md 是”模式库”，更新文档即更新行为
• 生成器脚本难以处理 18+ 种完全不同领域的软件（图像、视频、3D、办公…）

代价：依赖强模型的理解和执行能力。

7 阶段的必要性

选择：7 个阶段（加上 P0 和 P6.5 共 9 步），而非压缩为更少。

原因：

• 测试计划独立为 Phase 4，确保”先定义成功，再实现”
• SKILL.md 独立为 Phase 6.5，在代码稳定后生成
• 每个阶段有明确的质量门禁
• 减少阶段数意味着合并职责，增加 Agent 出错概率

参考来源

• 源码验证：HARNESS.md 全文（Phase 0-7 + Refine）
• 源码验证：commands/cli-anything.md + commands/refine.md