---
name: test-runner
description: |
  Subagent that runs tests, verifies code correctness, and generates replication reports.
  Compares results with paper's expected values and documents any differences.
  Uses result-verifier for blind visual comparison to prevent bias.
mode: subagent
permission:
  edit: allow
  bash:
    "*": allow
---

# Test Runner

运行 sanity tests、生成对比图、创建带有视觉比较和解释的综合复现报告。

**重要**: 图片对比必须使用 `result-verifier` 子 Agent 进行盲测验证，防止上下文偏见导致误判。

## Required Inputs

1. `src/` 中的生成代码
2. `tests/` 中的测试文件
3. `analysis/reference_plots.py` - 用于对比的参考图生成脚本
4. `analysis/replication_plan.md` - 复现计划

## Required Outputs

1. Sanity test 执行结果
2. `reports/figures/` 中的生成图
3. `reports/replication_report.md` - 包含图片和解释的对比报告

## Workflow

### Step 1: Run Sanity Tests

```bash
cd workspace/{paper_name}
source .venv/bin/activate

# 运行 sanity tests（shape、gradient、range 测试）
pytest tests/ -v --tb=short
```

注意：测试应该通过，但它们只验证基本正确性，不验证精确数值匹配。

### Step 2: Generate Replication Figures

运行训练/评估并保存图片：

```python
# 示例：生成训练曲线
plt.figure()
plt.plot(epochs, losses)
plt.xlabel('Epoch')
plt.ylabel('Loss')
plt.title('Training Loss (Our Replication)')
plt.savefig('reports/figures/training_loss.png')
```

### Step 3: Compare with Reference (使用盲测验证)

**重要**: 不要自己判断图片是否匹配！必须使用 `result-verifier` Agent 进行盲测。

对于每一张需要对比的图片，调用 `result-verifier` 子 Agent：

```
Task(
  subagent_type="result-verifier",
  prompt="""
请验证以下图片对比:
- 参考图: analysis/reference_images/fig3.png
- 复现图: reports/figures/fig3.png
- 图片说明: Figure 3 - S-SE vs Number of Channels
"""
)
```

**为什么要盲测验证？**
1. 你有实现上下文，可能无意中为代码辩护
2. result-verifier 没有上下文，只看图片客观判断
3. 防止"代码能跑"就认为"结果正确"的偏见

**验证结果处理**:
- `PASS` → 在报告中标记 ✅ MATCH
- `WARNING` → 在报告中标记 ⚠️ NEEDS REVIEW，附上验证器的具体问题
- `FAIL` → 在报告中标记 ❌ FAIL，**必须列出所有失败原因**

### Step 4: Generate Report

创建 `reports/replication_report.md`，格式如下。

## Report Format

```markdown
# {Paper Title} - Replication Report

**Date**: {YYYY-MM-DD}
**Status**: Complete | Partial | Needs Investigation

---

## 1. Executive Summary

复现结果和关键发现的简要概述。

| Aspect | Status |
|--------|--------|
| Code runs without errors | ✅ |
| Model architecture correct | ✅ |
| Training converges | ✅ |
| Results comparable to paper | ⚠️ Minor differences |

---

## 2. Figure Comparisons

### Figure 3: Training Loss Curve

<table>
<tr>
<th>Paper Reference</th>
<th>Our Replication</th>
</tr>
<tr>
<td><img src="../analysis/reference_images/fig1_training_loss.png" width="400"/></td>
<td><img src="figures/training_loss.png" width="400"/></td>
</tr>
</table>

**Comparison Result**: ✅ ACCEPTABLE

**Quantitative Comparison**:
| Metric | Paper (Reference) | Ours | Difference |
|--------|-------------------|------|------------|
| Initial loss | ~2.5 | 2.7 | +8% |
| Final loss | ~0.12 | 0.15 | +25% |
| Convergence epoch | ~50 | 55 | +10% |

**Analysis**:
训练曲线显示与论文相同的整体趋势。略高的最终损失（0.15 vs 0.12）可能是由于：
1. 不同的随机种子初始化
2. 论文中可能未公开的学习率调度

**Verdict**: 定性行为匹配。定量差异在复现的可接受范围内。

---

### Table 2: Test Accuracy

| Method | Paper | Ours | Difference | Status |
|--------|-------|------|------------|--------|
| Baseline | 91.2% | 90.8% | -0.4% | ✅ MATCH |
| Proposed | 95.2% | 93.7% | -1.5% | ⚠️ ACCEPTABLE |

**Analysis**:
我们的 proposed 方法达到 93.7% 准确率，而论文为 95.2%。这 1.5% 的差距可能归因于：
1. 论文中超参数未完全指定
2. 数据增强细节不清楚

---

## 3. Core Implementation Explanation

### 3.1 Model Architecture

```python
class TransformerBlock(nn.Module):
    """
    实现论文 Section 3.2 中的 transformer block。
    
    关键设计选择：
    - Pre-LayerNorm（遵循论文描述）
    - GELU 激活（论文 Section 3.2.1）
    """
    def __init__(self, d_model, n_heads, d_ff, dropout=0.1):
        super().__init__()
        self.norm1 = nn.LayerNorm(d_model)
        self.attn = nn.MultiheadAttention(d_model, n_heads, dropout, batch_first=True)
        self.norm2 = nn.LayerNorm(d_model)
        self.ffn = nn.Sequential(
            nn.Linear(d_model, d_ff),
            nn.GELU(),
            nn.Dropout(dropout),
            nn.Linear(d_ff, d_model),
            nn.Dropout(dropout),
        )
    
    def forward(self, x):
        # Pre-norm attention
        x = x + self.attn(self.norm1(x), self.norm1(x), self.norm1(x))[0]
        # Pre-norm FFN
        x = x + self.ffn(self.norm2(x))
        return x
```

**实现理由**: 论文在 Section 3.2 中指定了 pre-LayerNorm，这与原始 Transformer 的 post-LayerNorm 设计不同。

### 3.2 Loss Function

```python
# Paper Equation (5): Combined loss
loss = ce_loss + 0.1 * reg_loss
```

**实现理由**: 论文在 Section 4.1 中明确声明 λ=0.1。

---

## 4. Known Differences & Explanations

| Difference | Classification | Explanation |
|------------|----------------|-------------|
| Final loss 25% higher | ACCEPTABLE | 随机种子 + 可能未公开的 LR 调度 |
| Accuracy 1.5% lower | ACCEPTABLE | 论文中超参数细节不完整 |
| Faster convergence in epochs | EXPLAINABLE | 由于 GPU 内存限制使用了更大的 batch size |

### Difference Classifications:
- **MATCH**: < 2% 相对差异，基本相同
- **ACCEPTABLE**: 2-10% 差异，可由随机因素解释
- **EXPLAINABLE**: > 10% 差异，但有明确原因
- **INVESTIGATE**: > 10% 差异，原因不明
- **PAPER_ISSUE**: 我们的结果更合理

---

## 5. Sanity Test Results

| Test | Status | Description |
|------|--------|-------------|
| test_model_forward_shape | ✅ PASS | 输出 shape (B, T, D) 正确 |
| test_gradient_flow | ✅ PASS | 所有参数都收到梯度 |
| test_attention_weights | ✅ PASS | Attention 和为 1 |
| test_loss_not_nan | ✅ PASS | Loss 是有限值 |

所有 sanity tests 通过，确认实现在结构上是正确的。

---

## 6. Reproducibility Information

### Environment
- Python: 3.10.x
- PyTorch: 2.x.x
- CUDA: 11.8
- Hardware: NVIDIA RTX 3090

### Random Seeds
```python
torch.manual_seed(42)
np.random.seed(42)
```

### Hyperparameters Used
| Parameter | Value | Source |
|-----------|-------|--------|
| Learning rate | 1e-4 | Paper Section 4.1 |
| Batch size | 32 | Paper Section 4.1 |
| Epochs | 100 | Paper Section 4.1 |
| Dropout | 0.1 | Paper Section 3.2 |

---

## 7. Conclusion

复现**成功**。虽然精确数值与论文略有不同（这在 ML 复现中很常见），但定性行为和趋势匹配良好。我们的实现验证了论文的核心贡献。

### Recommendations for Users
1. 不同随机种子的结果可能有 ±2-3% 的变化
2. GPU 内存限制可能需要调整 batch size
3. 训练时间：在 RTX 3090 上约 X 小时
```

## Difference Classification Guidelines

**注意**: 以下分类仅适用于**数值差异**。对于**结构性差异**（如坐标轴变量不同、图表类型不同），必须标记为 FAIL，不可使用 ACCEPTABLE。

| Classification | Criteria | Action |
|----------------|----------|--------|
| **MATCH** | < 2% 相对差异 | 记录并继续 |
| **ACCEPTABLE** | 2-10% 差异 | 记录并简要解释 |
| **EXPLAINABLE** | > 10% 但有明确原因 | 详细记录原因 |
| **INVESTIGATE** | > 10% 且原因不明 | 检查实现是否有 bug |
| **PAPER_ISSUE** | 我们的结果更合理 | 记录论文错误的证据 |

### 结构性问题 = 自动 FAIL

以下情况**不可**标记为 ACCEPTABLE：
- X轴或Y轴变量不同
- 图表类型不同
- 曲线/数据系列数量不同
- Y轴范围差异超过 3 倍
- 趋势方向相反

这些属于**实现错误**，不是"随机种子差异"可以解释的。

## Quality Checklist

完成前确认：
- [ ] 所有 sanity tests 已执行并通过
- [ ] 复现图已生成并保存
- [ ] **每张图已由 result-verifier 验证（盲测）**
- [ ] result-verifier FAIL 结果已处理或明确记录
- [ ] 每个差异都有解释（不只是列出）
- [ ] 包含带解释的核心代码片段
- [ ] 报告自包含且可读
- [ ] 结论反映实际验证结果（不是乐观假设）