hc 4801fb2cc2 Initial commit: design spec and implementation plan

- Design spec: docs/superpowers/specs/2026-03-31-paper-replication-agent-design.md
- Implementation plan: docs/superpowers/plans/2026-03-31-paper-replication-agent.md
- Existing agent: .opencode/agents/paper-image-extractor.md

2026-03-31 17:29:53 +08:00

24 KiB

Raw Blame History

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

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

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 职责：

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

由 code-writer Subagent 负责：

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

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

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

论文基本信息
- 标题、作者、发表年份
- 核心贡献点摘要
模型架构理解
- 架构图的文字描述
- 关键组件清单
实验复现目标
- 需要复现的图表清单
- 每个图表的数据来源说明
- 预期的数值范围
复现计划
- 代码模块划分
- 实现顺序
- 预估工作量
风险点和限制
- 可能无法复现的部分
- 需要的外部资源（数据集等）

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 驱动 + 环境管理

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

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:

开放性提示框架
- 论文各部分可能包含的信息类型（非固定模板）
- 每个部分的"可能存在"检查清单
- 鼓励发现论文独特之处
全面性检查清单
- Abstract → 是否提取了核心贡献？
- Introduction → 是否理解了问题背景和动机？
- Related Work → 是否识别了与现有方法的关键差异？
- Method → 是否完整理解了方法细节？
- Experiments → 是否识别了所有需要复现的实验？
- Appendix → 是否检查了补充材料？
任务分解指南
- 如何将复杂论文拆分为可执行的子任务
- 依赖关系识别
- 优先级排序原则
示例模板
- 不同类型论文的解析示例
- 常见遗漏点提醒

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:

环境架构说明
- Conda 作为系统底座的职责
- uv 作为项目隔离的职责
- 两者的协作方式
Conda 基础环境配置
- ai_base 环境创建命令
- 必要的系统级依赖（cuda-toolkit 等）
- 环境检测脚本
uv 项目环境配置
- .venv 创建命令模板
- pyproject.toml 模板
- 常见 ML 依赖配置
- PyTorch + CUDA 版本对应关系

环境管理命令清单

# 检查 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 .

pyproject.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:

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

6.2 /verify

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

Usage:

/verify workspace/paper_name/

Behavior:

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

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

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

10. Future Enhancements

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

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/

24 KiB Raw Blame History Unescape Escape

Paper Replication Agent Design Specification

1. Overview

1.1 Purpose

1.2 Scope

1.3 Success Criteria

2. Architecture

2.1 System Architecture

2.2 File Structure

2.3 Environment Management Strategy

2.3.1 Architecture

2.3.2 Environment Setup Flow

2.3.3 Implementation: Skill vs Subagent

3. Workflow

3.1 Complete Workflow

3.2 Human Checkpoint Details

4. Agent Specifications

4.1 paper-director (Primary Agent)

4.2 paper-analyzer (Subagent)

4.3 paper-image-extractor (Subagent)

4.4 code-writer (Subagent)

4.5 test-runner (Subagent)

5. Skills Specifications

5.1 paper-parsing

5.2 code-generation

5.3 pytorch-patterns

5.4 verification

5.5 environment-management

6. Commands Specifications

6.1 /replicate

6.2 /verify

7. Data Flow

7.1 Analysis Phase Data Flow

7.2 Code Generation Phase Data Flow

7.3 Verification Phase Data Flow

8. Error Handling

8.1 Analysis Phase Errors

8.2 Code Generation Phase Errors

8.3 Verification Phase Errors

9. Configuration

9.1 opencode.json

10. Future Enhancements

Appendix A: Glossary

Appendix B: References

24 KiB

Raw Blame History