# Paper Replication Agent Design Specification

**Date**: 2026-03-31
**Status**: Draft
**Author**: OpenCode AI

---

## 1. Overview

### 1.1 Purpose

设计一个基于 OpenCode 平台的论文复现 Agent 系统，专注于机器学习/深度学习论文的自动化复现。该系统能够：

- 解析论文内容和图片
- 自动生成 PyTorch 复现代码
- 运行测试验证代码正确性
- 生成复现报告并对比原论文结果

### 1.2 Scope

- **目标论文类型**: 机器学习/深度学习论文
- **输入格式**: Markdown 文件、纯文本内容
- **输出框架**: PyTorch
- **自动化程度**: 解析后人工核验，之后自动执行（TDD 模式）

### 1.3 Success Criteria

1. 能够准确解析论文结构和关键信息
2. 能够理解论文中的架构图和实验图表
3. 生成可运行的 PyTorch 代码
4. 代码通过单元测试验证
5. 生成复现报告，明确标注与原论文的差异

---

## 2. Architecture

### 2.1 System Architecture

采用 **主 Agent 编排 + 专业化 Subagent** 的架构模式。

```
┌─────────────────────────────────────────────────────────┐
│                   paper-director                         │
│                  (Primary Agent)                         │
│           流程编排 / 质量控制 / 人工核验                  │
└─────────────────────────────────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        ▼                 ▼                 ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│paper-analyzer │ │paper-image-   │ │ code-writer   │
│   (Subagent)  │ │extractor      │ │  (Subagent)   │
│   论文解析    │ │  (Subagent)   │ │   代码生成    │
└───────────────┘ │  图片理解     │ └───────────────┘
                  └───────────────┘
                                          │
                                          ▼
                                  ┌───────────────┐
                                  │ test-runner   │
                                  │  (Subagent)   │
                                  │   测试验证    │
                                  └───────────────┘
```

### 2.2 File Structure

```
PaperTool/
├── .opencode/
│   ├── agents/                    # Agent 定义
│   │   ├── paper-director.md      # 主 Agent（编排者）
│   │   ├── paper-analyzer.md      # 论文解析 Subagent
│   │   ├── paper-image-extractor.md # 图片理解 Subagent
│   │   ├── code-writer.md         # 代码生成 Subagent
│   │   └── test-runner.md         # 测试验证 Subagent
│   │
│   ├── skills/                    # 项目级 Skills
│   │   ├── paper-parsing/         # 论文解析技能
│   │   │   └── SKILL.md
│   │   ├── code-generation/       # 代码生成技能
│   │   │   └── SKILL.md
│   │   ├── pytorch-patterns/      # PyTorch 最佳实践
│   │   │   └── SKILL.md
│   │   ├── verification/          # 验证与对比技能
│   │   │   └── SKILL.md
│   │   └── environment-management/ # 环境管理技能（Conda + uv）
│   │       └── SKILL.md
│   │
│   └── commands/                  # 快捷命令
│       ├── replicate.md           # /replicate 启动复现流程
│       └── verify.md              # /verify 验证复现结果
│
├── docs/superpowers/specs/        # 设计文档
│
├── workspace/                     # 工作区
│   ├── paper_name.md              # 论文源文件（Markdown）
│   └── {paper_name}/              # 每篇论文一个工作目录
│       ├── .venv/                 # uv 创建的项目虚拟环境
│       ├── pyproject.toml         # 项目依赖配置
│       ├── analysis/              # 解析结果
│       │   ├── paper_structure.md # 论文结构分析
│       │   ├── image_understanding.md # 图片理解
│       │   └── replication_plan.md # 复现计划
│       ├── src/                   # 生成的代码
│       │   ├── models/            # 模型定义
│       │   ├── training/          # 训练脚本
│       │   └── utils/             # 工具函数
│       ├── tests/                 # 单元测试
│       ├── docs/                  # 使用文档
│       │   └── README.md
│       └── reports/               # 复现报告
│           └── replication_report.md
│
└── opencode.json                  # 项目配置
```

### 2.3 Environment Management Strategy

采用 **Conda + uv** 混合模式管理 Python 环境：

#### 2.3.1 Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Conda (系统底座)                      │
│  ├─ ai_base 环境                                        │
│  │   ├─ Python 3.10+                                    │
│  │   ├─ cuda-toolkit                                    │
│  │   └─ 底层 C++ 编译链工具                              │
│  │                                                      │
│  └─ 不安装任何纯 Python 业务包                           │
└─────────────────────────────────────────────────────────┘
                          │
                          │ 提供 Python 解释器
                          ▼
┌─────────────────────────────────────────────────────────┐
│                    uv (项目隔离舱)                       │
│  ├─ workspace/paper_a/.venv/                            │
│  │   └─ torch, transformers, ...                        │
│  │                                                      │
│  ├─ workspace/paper_b/.venv/                            │
│  │   └─ torch, jax, ...                                 │
│  │                                                      │
│  └─ 每个项目独立的轻量级虚拟环境                         │
└─────────────────────────────────────────────────────────┘
```

#### 2.3.2 Environment Setup Flow

```
开始代码生成
    │
    ▼
检查 Conda ai_base 环境是否存在？
    │
    ├─ 否 → 创建 Conda 环境：
    │       conda create -n ai_base python=3.10 cuda-toolkit -y
    │
    ▼
进入项目目录 workspace/{paper_name}/
    │
    ▼
检查 .venv 是否存在？
    │
    ├─ 否 → 创建 uv 虚拟环境：
    │       uv venv --python $(conda run -n ai_base which python)
    │
    ▼
激活环境并安装依赖：
    uv pip install -r requirements.txt
    │
    ▼
继续代码生成/测试
```

#### 2.3.3 Implementation: Skill vs Subagent

**推荐方案：使用 Skill**

**`environment-management` Skill 职责**：

1. 提供 Conda + uv 最佳实践指南
2. 提供环境检测和创建的命令模板
3. 提供 pyproject.toml 模板
4. 提供常见依赖配置（PyTorch + CUDA）

**由 `code-writer` Subagent 负责**：

1. 在生成代码前调用 `environment-management` Skill
2. 执行环境检测和创建命令
3. 生成项目的 pyproject.toml
4. 安装依赖

---

## 3. Workflow

### 3.1 Complete Workflow

```
用户输入论文 (Markdown/Text)
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│ 阶段 1：论文解析                                         │
│ ├─ paper-director 创建工作区目录                         │
│ ├─ 调用 @paper-image-extractor 提取并理解图片            │
│ │   └─ 输出: image_understanding.md                      │
│ ├─ 调用 @paper-analyzer 解析论文结构                     │
│ │   └─ 输入: 论文 + image_understanding.md               │
│ │   └─ 输出: paper_structure.md + replication_plan.md    │
│ └─ 汇总解析结果                                          │
└─────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│ 🔴 人工核验点                                            │
│ ├─ 展示论文结构分析                                      │
│ ├─ 展示图片理解结果                                      │
│ ├─ 展示复现计划和预期产出                                │
│ ├─ 展示需要复现的实验图表清单                            │
│ └─ 等待用户确认或修正                                    │
└─────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│ 阶段 2：代码生成（TDD 模式）                             │
│ ├─ paper-director 根据复现计划生成测试用例               │
│ ├─ 调用 @code-writer 生成模型代码                        │
│ │   └─ 输入: 分析文档 + 测试用例                         │
│ │   └─ 输出: src/models/*.py                             │
│ ├─ 运行测试，验证代码正确性                              │
│ ├─ 如果测试失败，迭代修复                                │
│ ├─ 调用 @code-writer 生成训练脚本                        │
│ │   └─ 输出: src/training/*.py                           │
│ └─ 生成使用文档 docs/README.md                           │
└─────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│ 阶段 3：验证与报告                                       │
│ ├─ 调用 @test-runner 运行完整测试套件                    │
│ ├─ 尝试运行训练脚本（验证可执行性）                      │
│ ├─ 对比论文中的预期结果                                  │
│ ├─ 分析差异并说明原因                                    │
│ └─ 生成 replication_report.md                            │
└─────────────────────────────────────────────────────────┘
         │
         ▼
      最终产出
```

### 3.2 Human Checkpoint Details

人工核验点需要展示以下内容供用户确认：

1. **论文基本信息**
   
   - 标题、作者、发表年份
   - 核心贡献点摘要

2. **模型架构理解**
   
   - 架构图的文字描述
   - 关键组件清单

3. **实验复现目标**
   
   - 需要复现的图表清单
   - 每个图表的数据来源说明
   - 预期的数值范围

4. **复现计划**
   
   - 代码模块划分
   - 实现顺序
   - 预估工作量

5. **风险点和限制**
   
   - 可能无法复现的部分
   - 需要的外部资源（数据集等）

---

## 4. Agent Specifications

### 4.1 paper-director (Primary Agent)

**Mode**: `primary`

**Description**: 论文复现项目的编排者和质量控制负责人

**Responsibilities**:

- 接收用户的论文复现请求
- 创建和管理工作区目录
- 规划复现流程并创建任务清单
- 调度各个 Subagent 执行具体任务
- 在人工核验点暂停，等待用户确认
- 汇总结果并生成最终复现报告
- 处理异常情况和错误恢复

**Tools**: 全部启用

**Model**: inherit（继承用户配置）

### 4.2 paper-analyzer (Subagent)

**Mode**: `subagent`

**Description**: 解析论文文本内容，提取结构化信息，规划复现任务

**Input**:

- 论文 Markdown 文件或纯文本
- `image_understanding.md`（图片理解结果）

**Output**:

- `paper_structure.md` - 论文结构分析
- `replication_plan.md` - 复现计划

**Output Content**:

- 论文标题、作者、摘要
- 核心贡献点
- 方法论概述
- 模型架构描述（文字）
- 损失函数和优化器
- 实验设置（数据集、超参数）
- 关键公式（LaTeX）
- **实验结果复现目标**（基于图片理解）
  - 需要复现的图表清单
  - 每个图表的数据来源
  - 预期的数值范围
  - 复现优先级
- 待实现的功能清单

**Tools**: read, write, edit

**Model**: inherit

### 4.3 paper-image-extractor (Subagent)

**Mode**: `subagent`

**Description**: 提取并理解论文中的图片内容

**Input**:

- 论文 Markdown 文件（含图片链接/路径）

**Output**:

- `image_understanding.md` - 图片理解文档

**Output Content** (每张图片):

- 图片类型识别（架构图/实验图/算法伪代码/公式）
- 详细文字描述
- 架构图: 数据流向、层结构、连接关系
- 实验图: 数值提取、趋势分析、关键数据点
- 算法伪代码: 文字化描述、步骤拆解
- 关键信息提炼

**Tools**: read, write, edit, bash

**Model**: inherit

### 4.4 code-writer (Subagent)

**Mode**: `subagent`

**Description**: 根据分析结果生成 PyTorch 代码，并管理项目环境

**Input**:

- `paper_structure.md` - 论文结构分析
- `image_understanding.md` - 图片理解
- 测试用例（TDD 模式）

**Output**:

- `.venv/` - uv 创建的项目虚拟环境
- `pyproject.toml` - 项目依赖配置
- `src/models/*.py` - 模型定义
- `src/training/*.py` - 训练脚本
- `src/utils/*.py` - 工具函数
- `docs/README.md` - 使用文档

**Working Mode**: TDD 驱动 + 环境管理

1. **调用 `environment-management` Skill**
2. 检测并创建 Conda 基础环境（如不存在）
3. 创建项目 uv 虚拟环境
4. 生成 pyproject.toml
5. 安装依赖
6. 接收测试用例
7. 编写代码使测试通过
8. 迭代修复直到所有测试通过

**Tools**: read, write, edit, bash

**Model**: inherit

### 4.5 test-runner (Subagent)

**Mode**: `subagent`

**Description**: 运行测试并验证复现结果

**Input**:

- 生成的代码
- 测试用例
- 论文预期结果

**Output**:

- 测试运行结果
- `replication_report.md` - 复现报告

**Report Content**:

- 测试通过率
- 代码可运行性验证
- 与论文结果的对比分析
- 差异说明和原因分析
- 改进建议

**Tools**: read, write, edit, bash

**Model**: inherit

---

## 5. Skills Specifications

### 5.1 paper-parsing

**Purpose**: 指导如何系统性、全面地解析 ML/DL 论文

**Core Philosophy**: 强调**开放性**和**全面性**，避免漏解析和片面理解

**Content**:

1. **开放性提示框架**
   
   - 论文各部分可能包含的信息类型（非固定模板）
   - 每个部分的"可能存在"检查清单
   - 鼓励发现论文独特之处

2. **全面性检查清单**
   
   - Abstract → 是否提取了核心贡献？
   - Introduction → 是否理解了问题背景和动机？
   - Related Work → 是否识别了与现有方法的关键差异？
   - Method → 是否完整理解了方法细节？
   - Experiments → 是否识别了所有需要复现的实验？
   - Appendix → 是否检查了补充材料？

3. **任务分解指南**
   
   - 如何将复杂论文拆分为可执行的子任务
   - 依赖关系识别
   - 优先级排序原则

4. **示例模板**
   
   - 不同类型论文的解析示例
   - 常见遗漏点提醒

### 5.2 code-generation

**Purpose**: 指导如何根据论文生成高质量代码

**Content**:

- 从论文描述到代码的映射规则
- 模块化设计原则
- 代码风格规范
- 常见实现模式

### 5.3 pytorch-patterns

**Purpose**: 提供 PyTorch 代码的最佳实践模板

**Content**:

- 模型定义模板（nn.Module）
- 训练循环模板
- 常见层实现参考
- 性能优化技巧
- 设备管理（CPU/GPU）
- 数据加载最佳实践

### 5.4 verification

**Purpose**: 指导如何验证复现结果

**Content**:

- 测试用例设计指南
- 论文结果对比方法
- 差异分析框架
- 常见差异原因清单

### 5.5 environment-management

**Purpose**: 指导如何使用 Conda + uv 混合模式管理项目环境

**Content**:

1. **环境架构说明**
   
   - Conda 作为系统底座的职责
   - uv 作为项目隔离的职责
   - 两者的协作方式

2. **Conda 基础环境配置**
   
   - ai_base 环境创建命令
   - 必要的系统级依赖（cuda-toolkit 等）
   - 环境检测脚本

3. **uv 项目环境配置**
   
   - .venv 创建命令模板
   - pyproject.toml 模板
   - 常见 ML 依赖配置
   - PyTorch + CUDA 版本对应关系

4. **环境管理命令清单**
   
   ```bash
   # 检查 Conda 环境
   conda env list | grep ai_base
   
   # 创建 Conda 基础环境
   conda create -n ai_base python=3.10 cuda-toolkit -y
   
   # 获取 Conda Python 路径
   conda run -n ai_base which python
   
   # 创建 uv 虚拟环境
   uv venv --python $(conda run -n ai_base which python)
   
   # 激活并安装依赖
   source .venv/bin/activate  # Linux/Mac
   .venv\Scripts\activate     # Windows
   uv pip install -e .
   ```

5. **pyproject.toml 模板**
   
   ```toml
   [project]
   name = "{paper_name}"
   version = "0.1.0"
   requires-python = ">=3.10"
   dependencies = [
       "torch>=2.0.0",
       "numpy>=1.24.0",
       "matplotlib>=3.7.0",
       "pytest>=7.0.0",
   ]
   
   [project.optional-dependencies]
   dev = ["pytest", "black", "ruff"]
   ```

---

## 6. Commands Specifications

### 6.1 /replicate

**Purpose**: 一键启动论文复现流程

**Usage**:

```
/replicate path/to/paper.md
```

**Behavior**:

1. 验证输入文件存在
2. 从文件名提取论文名称
3. 创建 `workspace/{paper_name}/` 目录结构
4. 切换到 paper-director 主 Agent
5. 启动完整复现流程

### 6.2 /verify

**Purpose**: 验证已生成的复现代码

**Usage**:

```
/verify workspace/paper_name/
```

**Behavior**:

1. 检查工作区目录结构
2. 运行所有测试
3. 对比论文结果
4. 生成/更新验证报告

---

## 7. Data Flow

### 7.1 Analysis Phase Data Flow

```
论文.md
   │
   ├──────────────────────────────────┐
   │                                  │
   ▼                                  ▼
paper-image-extractor          (等待图片理解完成)
   │                                  │
   └─> image_understanding.md ────────┘
                                      │
                                      ▼
                              paper-analyzer
                                      │
                                      ├─> paper_structure.md
                                      └─> replication_plan.md
```

### 7.2 Code Generation Phase Data Flow

```
paper_structure.md + image_understanding.md
                    │
                    ▼
            paper-director
         (生成测试用例)
                    │
                    ▼
             code-writer
                    │
   ┌────────────────┼────────────────┐
   ▼                ▼                ▼
src/models/    src/training/    src/utils/
   │                │                │
   └────────────────┴────────────────┘
                    │
                    ▼
             运行测试 (TDD)
                    │
          ┌────────┴────────┐
          ▼                 ▼
       通过            失败 → 回到 code-writer 修复
          │
          ▼
      docs/README.md
```

### 7.3 Verification Phase Data Flow

```
src/* + tests/* + replication_plan.md
                    │
                    ▼
              test-runner
                    │
   ┌────────────────┼────────────────┐
   ▼                ▼                ▼
运行测试      对比论文结果      分析差异
   │                │                │
   └────────────────┴────────────────┘
                    │
                    ▼
         replication_report.md
```

---

## 8. Error Handling

### 8.1 Analysis Phase Errors

| 错误类型    | 处理方式             |
| ------- | ---------------- |
| 论文文件不存在 | 提示用户检查路径         |
| 图片无法访问  | 标记为无法解析，继续处理其他图片 |
| 解析结果不完整 | 在人工核验点展示，请求用户补充  |

### 8.2 Code Generation Phase Errors

| 错误类型 | 处理方式                             |
| ---- | -------------------------------- |
| 测试失败 | 迭代修复，最多 3 次；如仍失败，标记为需人工干预并继续其他模块 |
| 依赖缺失 | 提示用户安装                           |
| 语法错误 | 自动修复                             |

### 8.3 Verification Phase Errors

| 错误类型   | 处理方式        |
| ------ | ----------- |
| 测试运行失败 | 记录错误，标注在报告中 |
| 结果差异大  | 分析原因，在报告中说明 |

---

## 9. Configuration

### 9.1 opencode.json

```json
{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "paper-director",
  "agent": {
    "paper-director": {
      "mode": "primary"
    }
  }
}
```

---

## 10. Future Enhancements

1. **支持更多输入格式**: PDF 直接解析、arXiv URL
2. **支持更多框架**: TensorFlow、JAX
3. **数据集自动准备**: 自动下载和预处理常用数据集
4. **结果可视化**: 自动生成对比图表
5. **增量复现**: 支持部分复现和断点续传

---

## Appendix A: Glossary

| 术语            | 说明                        |
| ------------- | ------------------------- |
| Primary Agent | 主 Agent，用户直接交互的 Agent     |
| Subagent      | 子 Agent，由主 Agent 调度执行特定任务 |
| Skill         | 技能，为 Agent 提供特定领域的指导      |
| TDD           | 测试驱动开发，先写测试再写代码           |
| Workspace     | 工作区，存放每篇论文复现结果的目录         |

---

## Appendix B: References

- OpenCode Agents Documentation: https://opencode.ai/docs/zh-cn/agents/
- Superpowers Skills: https://github.com/obra/superpowers
- PyTorch Documentation: https://pytorch.org/docs/