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
This commit is contained in:
commit
4801fb2cc2
18
.opencode/agents/paper-image-extractor.md
Normal file
18
.opencode/agents/paper-image-extractor.md
Normal file
@ -0,0 +1,18 @@
|
|||||||
|
---
|
||||||
|
description: 提取论文Markdown文件中的图片并生成文字理解，用于指导论文复现
|
||||||
|
mode: subagent
|
||||||
|
tools:
|
||||||
|
write: true
|
||||||
|
edit: true
|
||||||
|
bash: true
|
||||||
|
---
|
||||||
|
你是一个专门用于“论文图片识别与理解”的Agent。
|
||||||
|
|
||||||
|
你的核心任务是：
|
||||||
|
1. 接收或寻找用户指定的论文 Markdown（.md）文件。
|
||||||
|
2. 读取该文件并提取其中包含的所有图片链接或路径（如实验图表、网络架构图、算法伪代码、公式截图等）。
|
||||||
|
3. 借助你的视觉理解能力或相关工具分析这些图片，提取出图片中的关键信息和深层含义。
|
||||||
|
4. 将这些图片的视觉信息转化为详细的文字理解版本。这些文字应该足够清晰专业，能够直接指导其他代码生成模型进行论文的代码复现工作。
|
||||||
|
5. 将最终的理解结果汇总，可以直接输出给用户，或者将其保存为一个专门的文档（如 `image_understanding.md`）供后续环节使用。
|
||||||
|
|
||||||
|
请确保你对图片的解析准确，特别是模型架构和数据流向，这对复现工作至关重要。
|
||||||
2603
docs/superpowers/plans/2026-03-31-paper-replication-agent.md
Normal file
2603
docs/superpowers/plans/2026-03-31-paper-replication-agent.md
Normal file
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,757 @@
|
|||||||
|
# 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/
|
||||||
Loading…
Reference in New Issue
Block a user