update-study

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update Study - Academic-Quality Experiment Report Generation

Update Study - 学术级实验报告生成

실험 로그를 분석하여 학술 논문 수준의 실험 보고서를 생성하는 스킬입니다. matplotlib 시각화, Executive Summary, 구현 구조, 결과 해석, 개선안, LaTeX PDF 변환을 포함합니다.

这是一款通过分析实验日志生成学术论文级实验报告的Skill。包含matplotlib可视化、执行摘要（Executive Summary）、实现结构、结果解读、改进方案、LaTeX PDF转换等功能。

Core Features

核心特性

Incremental Detection - 새 실험만 분석 (이미 문서화된 실험 스킵)
Data Extraction - W&B/로그 파일에서 메트릭 시계열 추출, pandas DataFrame 구조화
Automated Plot Generation - matplotlib 기반 비교 차트, 트렌드 패널, 조건별 분석 차트
Iterative Writing Loop - 학술 논문 수준 품질 개선 루프 (>=80점 통과)
Zero Hallucination - 로그 레벨 교차 검증
LaTeX PDF Export - Figure 포함 LaTeX 변환 및 PDF 생성

增量检测 - 仅分析新实验（已文档化的实验自动跳过）
数据提取 - 从W&B/日志文件中提取指标时间序列，结构化为pandas DataFrame
自动图表生成 - 基于matplotlib的对比图表、趋势面板、条件分析图表
迭代写作循环 - 学术论文级质量优化循环（需达到≥80分）
零幻觉验证 - 日志级交叉验证
LaTeX PDF导出 - 包含图表的LaTeX转换及PDF生成

Usage

使用方法

/update-study <log_path(s)> <study_md_path>

```
log_path(s)
```
: 실험 로그 파일 경로 (공백으로 구분하여 여러 개 가능, W&B export CSV 포함)
```
study_md_path
```
: 업데이트할 study markdown 파일 경로

/update-study <log_path(s)> <study_md_path>

```
log_path(s)
```
: 实验日志文件路径（可通过空格分隔多个文件，支持W&B导出的CSV）
```
study_md_path
```
: 待更新的研究markdown文件路径

Arguments Parsing

参数解析

$ARGUMENTS

에서 마지막 인자가

.md

파일이면 study 파일, 나머지는 로그 파일로 파싱합니다.

예시:
  /update-study logs/exp1.log results/study.md
  → log_files: ["logs/exp1.log"]
  → study_file: "results/study.md"

  /update-study logs/exp1.log logs/exp2.log memgen_ablation_study.md
  → log_files: ["logs/exp1.log", "logs/exp2.log"]
  → study_file: "memgen_ablation_study.md"

从

$ARGUMENTS

中解析参数，最后一个参数若为

.md

文件则视为研究文件，其余为日志文件。

示例:
  /update-study logs/exp1.log results/study.md
  → log_files: ["logs/exp1.log"]
  → study_file: "results/study.md"

  /update-study logs/exp1.log logs/exp2.log memgen_ablation_study.md
  → log_files: ["logs/exp1.log", "logs/exp2.log"]
  → study_file: "memgen_ablation_study.md"

Report Template

报告模板

최종 보고서는 다음 구조를 따릅니다. 학술 논문 수준의 형식을 유지합니다.

markdown

undefined

最终报告遵循以下结构，保持学术论文级格式。

markdown

undefined

{Title} Experiment Report

{标题} 实验报告

Author: {name} Date: {date} Project: {project}

作者: {姓名} 日期: {日期} 项目: {项目名}

Executive Summary

执行摘要

Task	Key Metric	Baseline	Proposed	Difference
{task_a}	{metric}	{baseline_val}	{proposed_val}	{delta}
{task_b}	{metric}	{baseline_val}	{proposed_val}	{delta}

{1-2 sentence overall conclusion}

任务	核心指标	基准线	改进方案	差异
{任务A}	{指标}	{基准值}	{改进值}	{差值}
{任务B}	{指标}	{基准值}	{改进值}	{差值}

{1-2句话的整体结论}

1. Implementation

1. 实现方案

1.1 Overview

1.1 概述

{실험의 목적과 접근 방식을 Definition-First 원칙으로 기술}

{按照定义优先原则，描述实验目的与实现思路}

1.2 Implementation Structure

1.2 实现结构

{핵심 코드 구조를 코드 스니펫으로 제시}

python

class ProposedModule(nn.Module):
    """모듈 설명 - 무엇을, 왜 하는지"""
    def __init__(self, config):
        ...
    def forward(self, x):
        ...

{展示核心代码结构的代码片段}

python

class ProposedModule(nn.Module):
    """模块说明 - 功能与设计初衷"""
    def __init__(self, config):
        ...
    def forward(self, x):
        ...

2. Experimental Results

2. 实验结果

2.1 {Task A}: {핵심 결과 한 줄 요약}

2.1 {任务A}: {核心结果一句话总结}

{결과 테이블 + Figure 참조 + 해석}

Figure 1 해석: {figure에서 관찰되는 패턴, 의미, baseline 대비 차이}

{结果表格 + 图表引用 + 解读}

Figure 1 解读: {图表中观察到的模式、意义、与基准线的差异} {可能的原因/机制分析}

2.2 {Task B}: {핵심 결과 한 줄 요약}

2.2 {任务B}: {核心结果一句话总结}

{동일 구조}

{相同结构}

2.3 {분석 제목}: {교차 분석 또는 상관 분석}

2.3 {分析标题}: {交叉分析或相关性分析}

{여러 실험/조건 간 비교 분석}

{多实验/条件间的对比分析}

2.4 {한계 분석 제목}

2.4 {局限性分析标题}

{실험 결과에서 발견된 한계점, 예상과 다른 결과에 대한 분석}

{从实验结果中发现的局限性、与预期不符结果的分析}

2.5 Experimental Setup

2.5 实验配置

Parameter	Value
Model	{model_name}
Dataset	{dataset}
Epochs	{N}
Learning Rate	{lr}
Batch Size	{batch_size}
Hardware	{gpu_info}

参数	值
模型	{模型名}
数据集	{数据集}
训练轮数	{N}
学习率	{lr}
批次大小	{batch_size}
硬件	{gpu信息}

3. Proposed Improvements

3. 改进建议

3.1 {Method A}

3.1 {方法A}

Problem: {현재 결과에서 발견된 구체적 문제, 수치 근거}

Solution: {제안하는 해결 방법과 근거}

python

undefined

问题: {从当前结果中发现的具体问题，附数值依据}

解决方案: {提出的解决方法及依据}

python

undefined

구현 예시

实现示例

class ImprovedModule(nn.Module): def init(self, config): ...


**Expected Effect**: {예상되는 개선 효과와 근거}

class ImprovedModule(nn.Module): def init(self, config): ...


**预期效果**: {预期的改进效果及依据}

3.2 {Method B}

3.2 {方法B}

{동일 구조: Problem → Solution → Code → Expected Effect}

{相同结构: 问题 → 解决方案 → 代码 → 预期效果}

4. Limitations

4. 局限性

{한계 1}: {구체적 설명 + 영향 범위}
{한계 2}: {구체적 설명 + 영향 범위}
{한계 3}: {구체적 설명 + 영향 범위}

{局限性1}: {具体说明 + 影响范围}
{局限性2}: {具体说明 + 影响范围}
{局限性3}: {具体说明 + 影响范围}

5. Conclusion

5. 结论

{주요 발견 요약, 기여, 의미}

{主要发现总结、贡献、意义}

6. Next Experiments

6. 后续实验计划

E{N}: {실험 이름}

E{N}: {实验名称}

Tests: H{N}

Config changes:

yaml

{parameter}: {new_value}  # was: {old_value}

Expected: {가설이 맞다면 예상되는 결과}

验证目标: H{N}
配置变更:
yaml
```
{参数}: {新值}  # 原: {旧值}
```
预期结果: {若假设成立的预期结果}

E{N+1}: {실험 이름}

E{N+1}: {实验名称}

Tests: H{N+1}
Config changes:
yaml
```
{config_changes}
```
Expected: {prediction}

验证目标: H{N+1}
配置变更:
yaml
```
{配置变更内容}
```
预期结果: {预测结果}

References

参考文献

{관련 논문/자료 목록}

---

{相关论文/资料列表}

---

Workflow Overview

工作流程概述

Phase 0: Incremental Detection
  ├── logs/ 스캔
  ├── 기존 study 파싱 (이미 분석된 실험 식별)
  └── 새 실험 목록 생성 → 없으면 "No new experiments" 출력 후 종료

Phase 1: File Verification
  ├── 로그 파일 존재 확인
  └── study.md 읽기

Phase 2: Data Extraction (NEW)
  ├── 로그/W&B 파일에서 메트릭 시계열 추출
  ├── pandas DataFrame으로 구조화
  └── 메트릭: accuracy, loss, ratio, entropy 등

Phase 3: Plot Generation (NEW)
  ├── scripts/generate_plots.py 호출
  ├── Training curve 비교 (Filter OFF vs ON 스타일)
  ├── Metric trend (multi-subplot panel)
  ├── 조건별 비교 차트
  └── 출력: figures/ 디렉토리에 PNG 저장

Phase 4: Interpretation + Writing (확장)
  ├── experiment-interpreter 에이전트 호출
  ├── Executive Summary 비교 테이블 생성
  ├── 각 Figure에 대한 해석 작성
  ├── Proposed Improvements 섹션 (Problem → Solution → Code → Expected Effect)
  ├── Limitations, Conclusion, Next Experiments 작성
  └── Writing Quality Loop (>=80점, 최대 3회 반복)

Phase 5: Verification
  ├── experiment-verifier 에이전트 호출
  ├── 숫자 정확성 검증
  └── 논리 일관성 검증

Phase 6: Export (확장)
  ├── Markdown 최종 확정
  ├── LaTeX 변환 + Figure 포함 (scripts/export_latex_pdf.py)
  ├── PDF 생성
  └── Fallback: scripts/export_pdf.py (기존 pandoc/weasyprint 방식)

Phase 0: 增量检测
  ├── 扫描logs/目录
  ├── 解析现有研究文档（识别已分析的实验）
  └── 生成新实验列表 → 若无新实验则输出"No new experiments"并终止

Phase 1: 文件验证
  ├── 验证日志文件是否存在
  └── 读取study.md内容

Phase 2: 数据提取（针对新实验）
  ├── 从日志/W&B文件中提取指标时间序列
  ├── 结构化为pandas DataFrame
  └── 指标包括: accuracy, loss, ratio, entropy等

Phase 3: 图表生成（针对新实验）
  ├── 调用scripts/generate_plots.py
  ├── 训练曲线对比（Filter OFF vs ON风格）
  ├── 指标趋势图（多子图面板）
  ├── 条件对比图表
  └── 输出: 将PNG文件保存至figures/目录

Phase 4: 结果解读 + 文档撰写（扩展内容）
  ├── 调用experiment-interpreter代理
  ├── 生成执行摘要对比表格
  ├── 为每个图表撰写解读内容
  ├── 撰写改进建议章节（问题→解决方案→代码→预期效果）
  ├── 撰写局限性、结论、后续实验计划
  └── 写作质量循环（需≥80分，最多重复3次）

Phase 5: 验证
  ├── 调用experiment-verifier代理
  ├── 验证数值准确性
  └── 验证逻辑一致性

Phase 6: 导出（扩展内容）
  ├── 最终确定Markdown内容
  ├── LaTeX转换 + 嵌入图表（scripts/export_latex_pdf.py）
  ├── 生成PDF
  └── 备选方案: scripts/export_pdf.py（基于pandoc/weasyprint的传统方式）

Phase 0: Incremental Detection

Phase 0: 增量检测

Step 0.1: 로그 디렉토리 스캔

Step 0.1: 扫描日志目录

1. logs/ 디렉토리에서 모든 로그 파일 목록 생성
   - 패턴: *_train.log, *_eval.log, *.log, *.csv (W&B export)
   - 파일 수정 시간 기준 정렬

2. 입력된 로그 파일 목록과 교차 확인

1. 生成logs/目录下所有日志文件列表
   - 匹配模式: *_train.log, *_eval.log, *.log, *.csv（W&B导出文件）
   - 按文件修改时间排序

2. 与输入的日志文件列表交叉验证

Step 0.2: 기존 Study 분석

Step 0.2: 分析现有研究文档

기존 study.md에서 이미 문서화된 실험 식별:

1. 실험 헤더 패턴 검색:
   - `### E{N}:` 또는 `### Experiment:`
   - `## Experiment {N}:`

2. 로그 파일 참조 추출:
   - `[*_train.log:*]` 형식의 출처 표기
   - `Source:` 열의 파일명

3. 문서화된 실험 목록 구축:
   documented_experiments = {
       "evolve_h_only_train.log",
       "cross_attn_train.log",
       ...
   }

从现有study.md中识别已文档化的实验:

1. 搜索实验标题模式:
   - `### E{N}:` 或 `### Experiment:`
   - `## Experiment {N}:`

2. 提取日志文件引用:
   - `[*_train.log:*]`格式的来源标注
   - `Source:`列中的文件名

3. 构建已文档化实验列表:
   documented_experiments = {
       "evolve_h_only_train.log",
       "cross_attn_train.log",
       ...
   }

Step 0.3: 새 실험 결정

Step 0.3: 确定新实验

python

new_experiments = set(input_logs) - set(documented_experiments)

if len(new_experiments) == 0:
    print("No new experiments to analyze")
    print(f"  Already documented: {len(documented_experiments)} experiments")
    exit()  # 종료
else:
    print(f"Found {len(new_experiments)} new experiment(s) to analyze:")
    for exp in new_experiments:
        print(f"  - {exp}")

python

new_experiments = set(input_logs) - set(documented_experiments)

if len(new_experiments) == 0:
    print("No new experiments to analyze")
    print(f"  已文档化实验: {len(documented_experiments)}个")
    exit()  # 终止程序
else:
    print(f"发现{len(new_experiments)}个待分析的新实验:")
    for exp in new_experiments:
        print(f"  - {exp}")

Phase 1: File Verification

Phase 1: 文件验证

Step 1.1: 파일 확인

Step 1.1: 文件检查

1. 새 실험 로그 파일 존재 확인
   - 각 log_path에 대해 파일 존재 여부 확인
   - 존재하지 않으면 에러 메시지 출력 후 중단

2. study.md 파일 확인
   - 파일이 존재하면 Read tool로 전체 내용 읽기
   - 파일이 없으면 새로 생성할 것임을 안내

3. 로그 파일 요약 정보 추출 (빠른 스캔)
   - 실험 config 파일 경로
   - 실험 모드 (train/evaluate)
   - 최종 metric 라인 위치

1. 验证新实验日志文件是否存在
   - 检查每个log_path对应的文件
   - 若不存在则输出错误信息并终止

2. 检查study.md文件
   - 若文件存在则用Read工具读取全部内容
   - 若不存在则提示将新建文件

3. 快速扫描日志文件提取摘要信息
   - 实验配置文件路径
   - 实验模式（train/evaluate）
   - 最终指标行位置

Step 1.2: 기존 study.md 분석

Step 1.2: 分析现有study.md

기존 study.md에서 확인할 사항:
- 이미 기록된 실험 목록
- 비교 가능한 baseline 결과
- 미해결 가설 목록
- 계획된 실험 목록 (이번 실험이 기존 계획에 해당하는지)

从现有study.md中确认以下信息:
- 已记录的实验列表
- 可对比的基准线结果
- 未解决的假设列表
- 本次实验是否匹配原有计划

Phase 2: Data Extraction

Phase 2: 数据提取

로그 파일 및 W&B export에서 메트릭 시계열 데이터를 추출하여 구조화합니다.

从日志文件及W&B导出文件中提取指标时间序列并结构化。

Step 2.1: 메트릭 시계열 추출

Step 2.1: 提取指标时间序列

1. 로그 파일 파싱
   - 정규표현식으로 epoch/step별 메트릭 추출
   - 패턴 예시:
     - "Epoch {N}: accuracy={X.XX}, loss={X.XXXX}"
     - "Step {N} | train_loss: {X.XXXX} | eval_acc: {X.XX}"
     - W&B CSV: 컬럼 기반 직접 로드

2. W&B API/CSV 지원
   - wandb export CSV 파일 자동 인식
   - 컬럼명 표준화 (step, epoch, metric_name)

1. 解析日志文件
   - 用正则表达式提取epoch/step级指标
   - 示例模式:
     - "Epoch {N}: accuracy={X.XX}, loss={X.XXXX}"
     - "Step {N} | train_loss: {X.XXXX} | eval_acc: {X.XX}"
     - W&B CSV: 直接按列加载

2. 支持W&B API/CSV
   - 自动识别wandb导出的CSV文件
   - 标准化列名（step, epoch, metric_name）

Step 2.2: pandas DataFrame 구조화

Step 2.2: 结构化为pandas DataFrame

python

undefined

python

undefined

추출 결과 구조

提取结果结构

import pandas as pd

각 실험별 DataFrame

每个实验对应一个DataFrame

df = pd.DataFrame({ 'step': [...], 'epoch': [...], 'train_loss': [...], 'eval_accuracy': [...], 'learning_rate': [...], 'grad_norm': [...], # 실험별 추가 메트릭 'ratio': [...], # 필터링 비율 등 'entropy': [...], # 분포 엔트로피 등 })

df = pd.DataFrame({ 'step': [...], 'epoch': [...], 'train_loss': [...], 'eval_accuracy': [...], 'learning_rate': [...], 'grad_norm': [...], # 实验专属指标 'ratio': [...], # 过滤比例、压缩比例等 'entropy': [...], # 分布熵等 })

메타데이터

元数据

metadata = { 'experiment_name': '...', 'config_path': '...', 'log_path': '...', 'total_epochs': N, 'final_metrics': { 'accuracy': X.XX, 'loss': X.XXXX, } }

undefined

metadata = { 'experiment_name': '...', 'config_path': '...', 'log_path': '...', 'total_epochs': N, 'final_metrics': { 'accuracy': X.XX, 'loss': X.XXXX, } }

undefined

Step 2.3: 대상 메트릭

Step 2.3: 目标指标

필수 메트릭 (로그에 존재하는 경우):
- accuracy (eval/test)
- loss (train/eval)
- learning_rate
- grad_norm

선택 메트릭 (실험 유형에 따라):
- ratio (필터링 비율, 압축 비율 등)
- entropy (분포 엔트로피)
- perplexity
- BLEU / ROUGE
- custom metrics (로그에서 자동 감지)

必填指标（日志中存在时）:
- accuracy（eval/test）
- loss（train/eval）
- learning_rate
- grad_norm

可选指标（依实验类型而定）:
- ratio（过滤比例、压缩比例等）
- entropy（分布熵）
- perplexity
- BLEU / ROUGE
- 自定义指标（从日志中自动检测）

Phase 3: Plot Generation

Phase 3: 图表生成

scripts/generate_plots.py

를 호출하여 matplotlib 기반 시각화를 생성합니다.

调用

scripts/generate_plots.py

生成基于matplotlib的可视化图表。

Step 3.1: 차트 유형

Step 3.1: 图表类型

1. Training Curve 비교 (필수)
   - X축: epoch 또는 step
   - Y축: loss / accuracy
   - 여러 실험을 한 차트에 오버레이
   - 스타일: "Filter OFF vs Filter ON" 비교 형태
   - 범례, 그리드, 타이틀 포함

2. Metric Trend Panel (필수)
   - Multi-subplot 레이아웃 (2x2 또는 3x2)
   - 각 subplot: 하나의 메트릭 시계열
   - 예: loss, accuracy, grad_norm, learning_rate
   - 실험 간 동일 스케일 사용

3. 조건별 비교 차트 (조건부)
   - Bar chart: 최종 메트릭 비교 (실험별)
   - Grouped bar: 여러 메트릭을 실험별로 그룹화
   - 예: baseline vs proposed 최종 accuracy 비교

4. 분포 차트 (조건부)
   - Histogram: metric 분포 비교
   - Box plot: 실험 간 변동성 비교

1. 训练曲线对比（必填）
   - X轴: epoch或step
   - Y轴: loss / accuracy
   - 多实验曲线叠加
   - 风格: "Filter OFF vs Filter ON"对比形式
   - 包含图例、网格、标题

2. 指标趋势面板（必填）
   - 多子图布局（2x2或3x2）
   - 每个子图对应一个指标时间序列
   - 示例: loss, accuracy, grad_norm, learning_rate
   - 实验间使用相同刻度

3. 条件对比图表（可选）
   - 柱状图: 最终指标对比（按实验分组）
   - 分组柱状图: 多指标按实验分组对比
   - 示例: baseline vs proposed的最终accuracy对比

4. 分布图表（可选）
   - 直方图: 指标分布对比
   - 箱线图: 实验间波动性对比

Step 3.2: 스크립트 호출

Step 3.2: 调用脚本

bash

python scripts/generate_plots.py \
  --data extracted_metrics.json \
  --output-dir figures/ \
  --experiments "exp1,exp2,baseline" \
  --plots training_curve,metric_panel,comparison_bar

bash

python scripts/generate_plots.py \
  --data extracted_metrics.json \
  --output-dir figures/ \
  --experiments "exp1,exp2,baseline" \
  --plots training_curve,metric_panel,comparison_bar

Step 3.3: 출력

Step 3.3: 输出结果

figures/
  ├── training_curve_comparison.png    # Loss/accuracy 비교 곡선
  ├── metric_trend_panel.png           # Multi-subplot 메트릭 패널
  ├── final_metric_comparison.png      # Bar chart 최종 비교
  └── {custom_name}.png                # 실험별 추가 차트

figures/
  ├── training_curve_comparison.png    # Loss/accuracy对比曲线
  ├── metric_trend_panel.png           # 多子图指标面板
  ├── final_metric_comparison.png      # 最终指标对比柱状图
  └── {自定义名称}.png                # 实验专属图表

Step 3.4: Figure 스타일 기준

Step 3.4: 图表风格标准

python

undefined

python

undefined

학술 논문 수준 matplotlib 설정

学术论文级matplotlib配置

import matplotlib.pyplot as plt

plt.rcParams.update({ 'figure.figsize': (10, 6), 'figure.dpi': 150, 'font.size': 12, 'font.family': 'serif', 'axes.labelsize': 13, 'axes.titlesize': 14, 'legend.fontsize': 11, 'xtick.labelsize': 11, 'ytick.labelsize': 11, 'axes.grid': True, 'grid.alpha': 0.3, 'lines.linewidth': 2.0, 'figure.constrained_layout.use': True, })

import matplotlib.pyplot as plt

색상 팔레트 (colorblind-friendly)

色弱友好配色方案

COLORS = ['#0072B2', '#D55E00', '#009E73', '#CC79A7', '#F0E442', '#56B4E9']

---

COLORS = ['#0072B2', '#D55E00', '#009E73', '#CC79A7', '#F0E442', '#56B4E9']

---

Phase 4: Interpretation + Writing

Phase 4: 结果解读 + 文档撰写

Step 4.1: Experiment-Interpreter 에이전트 호출

Step 4.1: 调用Experiment-Interpreter代理

Task tool 사용:
- subagent_type: "experiment-interpreter"
- prompt:

  "다음 실험 로그와 생성된 Figure를 분석하여
   학술 논문 수준의 실험 보고서를 작성해주세요.

  ## 데이터
  {추출된 DataFrame 요약}

  ## 생성된 Figure 목록
  {figures/ 디렉토리의 PNG 파일 목록과 각 차트 설명}

  ## 로그 파일
  {각 로그 파일의 전체 경로}

  ## 기존 study.md 내용 (비교용)
  {기존 study.md의 결과 요약 테이블}

  ## 이전 검증 피드백 (있는 경우)
  {verifier의 feedback_summary - 첫 iteration에는 없음}

  ## 요구사항
  1. Report Template 구조를 따를 것
  2. Executive Summary 비교 테이블 생성
  3. 각 Figure에 대한 구체적 해석 작성
     - 패턴, 추세, 이상점 기술
     - baseline 대비 차이 설명
     - Figure 번호로 참조 (Figure 1, Figure 2, ...)
  4. Implementation Structure 섹션에 핵심 코드 스니펫 포함
  5. Proposed Improvements: Problem → Solution → Code → Expected Effect
  6. Limitations 섹션: 구체적 한계와 영향 범위
  7. Conclusion: 주요 발견 요약
  8. Next Experiments: 가설과 연결된 구체적 계획
  9. 모든 수치에 출처 표기 (source: filepath:L행번호)
  10. 각 가설은 falsifiable + prediction + falsification 포함
  11. 출력은 Report Template 형식의 markdown

  ## 출력 형식
  references/interpretation-template.md 템플릿을 따르되,
  Report Template의 전체 구조에 맞게 확장해주세요."

使用Task工具:
- subagent_type: "experiment-interpreter"
- 提示词:

  "请分析以下实验日志及生成的图表，撰写学术论文级的实验报告。

  ## 数据
  {提取的DataFrame摘要}

  ## 生成的图表列表
  {figures/目录下的PNG文件列表及各图表说明}

  ## 日志文件
  {各日志文件的完整路径}

  ## 现有study.md内容（用于对比）
  {现有study.md的结果摘要表格}

  ## 之前的验证反馈（如有）
  {verifier的feedback_summary - 第一次迭代时为空}

  ## 要求
  1. 严格遵循Report Template结构
  2. 生成执行摘要对比表格
  3. 为每个图表撰写具体解读
     - 描述模式、趋势、异常点
     - 说明与baseline的差异
     - 用图表编号引用（Figure 1, Figure 2, ...）
  4. 在实现结构章节中包含核心代码片段
  5. 改进建议章节遵循: 问题→解决方案→代码→预期效果
  6. 局限性章节: 说明具体局限及影响范围
  7. 结论: 总结主要发现
  8. 后续实验计划: 制定与假设关联的具体方案
  9. 所有数值需标注来源（source: 文件路径:行号）
  10. 所有假设需可证伪 + 包含预测 + 证伪条件
  11. 输出为符合Report Template格式的markdown

  ## 输出格式
  请遵循references/interpretation-template.md模板，并按Report Template的完整结构扩展内容。"

Step 4.2: Executive Summary 생성

Step 4.2: 生成执行摘要

markdown

undefined

markdown

undefined

Executive Summary

执行摘要

Task	Key Metric	Baseline	Proposed	Difference
{각 실험 task별 핵심 비교 결과}

생성 규칙:

Baseline은 기존 study에 기록된 vanilla/default 결과
Proposed는 이번 실험의 결과
Difference는 절대값 + 방향 (+/-) 포함
가장 중요한 메트릭 우선 배치

undefined

任务	核心指标	基准线	改进方案	差异
{各实验任务的核心对比结果}

生成规则:

Baseline为现有study中记录的vanilla/default结果
Proposed为本次实验结果
Difference包含绝对值 + 方向(+/-)
优先展示最重要的指标

undefined

Step 4.3: Figure 해석 작성

Step 4.3: 撰写图表解读

각 Figure에 대해:

1. Figure 참조 삽입:
   ![Figure N: {descriptive caption}](figures/{filename}.png)

2. 해석 문단 작성 (Topic-First 원칙):
   **Figure N 해석**: {핵심 관찰}. {상세 설명}. {baseline 대비 차이}.
   {가능한 원인/메커니즘 분석}.

3. 해석 품질 기준:
   - 정량적: 수치로 차이를 기술
   - 비교적: baseline 또는 이전 실험과 대비
   - 인과적: 왜 이런 패턴이 나타나는지 가설 제시

每个图表需包含:

1. 插入图表引用:
   ![Figure N: {描述性标题}](figures/{文件名}.png)

2. 撰写解读段落（主题优先原则）:
   **Figure N 解读**: {核心观察结论}。{详细说明}。{与baseline的差异}。
   {可能的原因/机制分析}。

3. 解读质量标准:
   - 定量: 用数值描述差异
   - 对比: 与baseline或之前实验对比
   - 因果: 提出导致该模式的假设

Step 4.4: Proposed Improvements 작성

Step 4.4: 撰写改进建议

각 개선안에 대해 4-part 구조:

每个改进建议遵循4部分结构:

3.N {Method Name}

3.N {方法名称}

Problem: {실험 결과에서 발견된 구체적 문제}

수치 근거 포함 (source: filepath:L행번호)
Figure 참조 포함 (Figure N 참조)

Solution: {제안하는 해결 방법}

기존 연구/이론적 근거 제시
구현 방향 설명

python

undefined

问题: {从实验结果中发现的具体问题}

包含数值依据（source: 文件路径:行号）
包含图表引用（参考Figure N）

解决方案: {提出的解决方法}

提供现有研究/理论依据
说明实现方向

python

undefined

구현 예시 코드

实现示例代码

class ImprovedComponent: ...


**Expected Effect**: {예상 개선 효과}
  - 정량적 예측 (예: "accuracy +2-3%p 향상 예상")
  - 근거 설명

class ImprovedComponent: ...


**预期效果**: {预期的改进效果}
  - 定量预测（例如: "预计accuracy提升2-3%p"）
  - 说明依据

Step 4.5: Writing Quality Loop

Step 4.5: 写作质量循环

작성된 초안에 대해 품질 평가 수행:

평가 기준 (references/quality-criteria.md 참조, 가중치 업데이트):

1. Definition-First (25점)
   - 모든 전문 용어가 "X is Y" 형태로 정의되었는가?
   - 새로운 개념이 사용 전에 정의되었는가?

2. Topic-First Paragraphs (20점)
   - 모든 문단이 핵심 결과/주장으로 시작하는가?
   - 첫 문장만 읽어도 문단 내용을 파악할 수 있는가?

3. Compare-Contrast (15점)
   - 새 결과가 이전 실험과 비교되었는가?
   - 차이의 원인/해석이 제시되었는가?

4. Insight Depth (15점)
   - 표면적 기술을 넘어 "왜"에 대한 분석이 있는가?
   - 예상과 다른 결과에 대한 가설이 있는가?

5. Minimal Adjectives (5점)
   - 불필요한 수식어가 없는가?
   - 주관적 표현 대신 구체적 수치가 사용되었는가?

6. Figure Quality (10점) [NEW]
   - 모든 Figure에 해석 문단이 있는가?
   - Figure caption이 내용을 정확히 기술하는가?
   - Figure 참조가 본문에서 올바르게 연결되었는가?

7. Next Steps Clarity (10점) [NEW]
   - 다음 실험이 가설과 명확히 연결되었는가?
   - Config 변경 사항이 구체적인가?
   - 예상 결과와 근거가 제시되었는가?

총점: /100
통과 기준: >= 80점

对初稿进行质量评估:

评估标准（参考references/quality-criteria.md，权重已更新）:

1. 定义优先（25分）
   - 所有专业术语是否以"X is Y"形式定义？
   - 新概念是否在使用前定义？

2. 主题优先段落（20分）
   - 所有段落是否以核心结果/主张开头？
   - 仅读第一句能否理解段落内容？

3. 对比分析（15分）
   - 新结果是否与之前实验对比？
   - 是否说明了差异的原因/解读？

4. 洞察深度（15分）
   - 是否超越表面描述，分析"为什么"？
   - 是否对与预期不符的结果提出假设？

5. 最少修饰词（5分）
   - 是否无不必要的修饰词？
   - 是否用具体数值替代主观表述？

6. 图表质量（10分）[新增]
   - 所有图表是否都有解读段落？
   - 图表标题是否准确描述内容？
   - 图表引用是否与正文正确关联？

7. 后续步骤清晰度（10分）[新增]
   - 后续实验是否与假设明确关联？
   - 配置变更是否具体？
   - 是否提供预期结果及依据？

总分: /100
通过标准: >= 80分

Step 4.6: Revision (점수 < 80인 경우)

Step 4.6: 修订（得分<80时）

1. [Critical: Definition Missing]
   - 미정의 용어 목록 작성
   - 각 용어에 대해 "X is Y" 정의 추가

2. [Critical: Topic-Last Paragraph]
   - 문단 재구성: 핵심 → 설명 → 근거 순서로

3. [Warning: No Comparison]
   - 이전 실험과의 비교 테이블 추가
   - 차이 분석 문단 추가

4. [Warning: Shallow Insight]
   - "왜 이런 결과가 나왔는가?" 분석 추가
   - 가설 강화

5. [Minor: Excessive Adjectives]
   - "significantly improved" → "+12.5%p"
   - "much faster" → "2.3x speedup"

6. [Warning: Figure Without Interpretation]
   - 해석 없는 Figure에 해석 문단 추가
   - Caption이 부정확한 경우 수정

7. [Warning: Vague Next Steps]
   - 가설과의 연결 명확화
   - Config 변경 구체화

1. [严重问题: 缺失定义]
   - 列出未定义的术语
   - 为每个术语添加"X is Y"形式的定义

2. [严重问题: 主题后置段落]
   - 重构段落: 核心→说明→依据的顺序

3. [警告: 无对比分析]
   - 添加与之前实验的对比表格
   - 添加差异分析段落

4. [警告: 洞察浅显]
   - 添加"为什么会出现该结果？"的分析
   - 强化假设

5. [次要问题: 修饰词过多]
   - "significantly improved" → "+12.5%p"
   - "much faster" → "2.3x speedup"

6. [警告: 图表无解读]
   - 为无解读的图表添加解读段落
   - 修正不准确的标题

7. [警告: 后续步骤模糊]
   - 明确与假设的关联
   - 具体化配置变更

Step 4.7: Iteration Control

Step 4.7: 迭代控制

최대 반복: 3회

Iteration 1: 초안 → 품질 평가 → 수정 (필요시)
  → Score >= 80: Phase 5로 진행
  → Score < 80: feedback 수집

Iteration 2: 수정안 → 재평가
  → Score >= 80: Phase 5로 진행
  → Score < 80: feedback 수집

Iteration 3: 최종 수정 → 재평가
  → Score >= 80: Phase 5로 진행
  → Score < 80: 현재 최선 버전으로 진행 + 이슈 보고

最大迭代次数: 3次

Iteration 1: 初稿 → 质量评估 → 修订（如需）
  → 得分 >=80: 进入Phase 5
  → 得分 <80: 收集反馈

Iteration 2: 修订稿 → 重新评估
  → 得分 >=80: 进入Phase 5
  → 得分 <80: 收集反馈

Iteration 3: 最终修订 → 重新评估
  → 得分 >=80: 进入Phase 5
  → 得分 <80: 使用当前最优版本 + 向用户报告问题

Phase 5: Verification (experiment-verifier)

Phase 5: 验证（experiment-verifier）

Task Tool 호출

调用Task工具

Task tool 사용:
- subagent_type: "experiment-verifier"
- prompt:

  "다음 study.md 업데이트 내용을 검증해주세요.

  ## 검증 대상 (새로 추가된 섹션)
  {Phase 4에서 작성한 내용}

  ## 원본 로그 파일 경로
  {각 로그 파일의 전체 경로}

  ## 기존 study.md (변경 여부 확인용)
  {기존 study.md 내용}

  ## 생성된 Figure 목록
  {figures/ 디렉토리 내용}

  ## 검증 요구사항
  1. 모든 수치를 원본 로그와 대조 (파일:라인 직접 확인)
  2. Executive Summary 테이블의 수치 정확성
  3. Figure 해석이 실제 데이터와 일치하는지 확인
  4. 해석의 논리적 타당성 검증
  5. 모든 가설의 falsifiability 확인
  6. 다음 실험의 실행 가능성 확인
  7. 기존 결과 변경 여부 확인
  8. 코드 스니펫의 문법 정확성

  ## 출력
  JSON 형식의 검증 보고서를 반환해주세요."

使用Task工具:
- subagent_type: "experiment-verifier"
- 提示词:

  "请验证以下study.md的更新内容。

  ## 验证对象（新增章节）
  {Phase 4中撰写的内容}

  ## 原始日志文件路径
  {各日志文件的完整路径}

  ## 现有study.md（用于确认变更）
  {现有study.md内容}

  ## 生成的图表列表
  {figures/目录内容}

  ## 验证要求
  1. 将所有数值与原始日志核对（直接查看文件:行号）
  2. 验证执行摘要表格的数值准确性
  3. 确认图表解读与实际数据一致
  4. 验证解读的逻辑合理性
  5. 确认所有假设的可证伪性
  6. 确认后续实验的可行性
  7. 确认是否修改了现有结果
  8. 验证代码片段的语法正确性

  ## 输出
  请返回JSON格式的验证报告。"

결과 처리

结果处理

python

if verdict == "PASS":
    # Phase 6로 진행
elif iteration < 3:
    # feedback_summary를 Phase 4로 전달
    # interpreter에게 수정 요청
else:
    # 최대 반복 도달
    # 현재 최선 버전 저장
    # 미해결 이슈 사용자에게 보고

python

if verdict == "PASS":
    # 进入Phase 6
elif iteration < 3:
    # 将feedback_summary传递给Phase 4
    # 请求interpreter修订
else:
    # 达到最大迭代次数
    # 保存当前最优版本
    # 向用户报告未解决问题

Phase 6: Export

Phase 6: 导出

Step 6.1: Markdown 확정

Step 6.1: 确定Markdown内容

1. study.md 최종 내용 저장
2. [NEW] 태그가 포함된 섹션 확인
3. Figure 참조 경로 검증 (figures/*.png 존재 확인)
4. 상대 경로 정규화

1. 保存study.md最终内容
2. 检查包含[NEW]标签的章节
3. 验证图表引用路径（确认figures/*.png存在）
4. 标准化相对路径

Step 6.2: LaTeX 변환 + PDF 생성 (우선 방식)

Step 6.2: LaTeX转换 + PDF生成（优先方式）

bash

undefined

bash

undefined

scripts/export_latex_pdf.py 사용 (Figure 포함 LaTeX 변환)

使用scripts/export_latex_pdf.py（包含图表的LaTeX转换）

python scripts/export_latex_pdf.py
study.md
study.pdf
--figures-dir figures/
--template academic

기능:

Markdown → LaTeX 변환
Figure 자동 삽입 (\includegraphics)
학술 논문 레이아웃 (twocolumn 옵션 가능)
TOC (Table of Contents) 포함
[NEW] 태그 시각적 강조
테이블 포맷팅 (booktabs 스타일)
코드 블록 문법 강조 (listings/minted)
참고문헌 섹션

undefined

python scripts/export_latex_pdf.py
study.md
study.pdf
--figures-dir figures/
--template academic

功能:

Markdown → LaTeX转换
自动插入图表（\includegraphics）
学术论文布局（支持twocolumn选项）
包含目录（TOC）
视觉化突出[NEW]标签
表格格式化（booktabs风格）
代码块语法高亮（listings/minted）
参考文献章节

undefined

Step 6.3: Fallback PDF 변환

Step 6.3: 备选PDF转换方案

bash

undefined

bash

undefined

LaTeX 변환 실패 시 기존 방식 사용

LaTeX转换失败时使用传统方式

python scripts/export_pdf.py study.md study.pdf

Fallback 순서:

scripts/export_latex_pdf.py (LaTeX + Figure, 최상의 품질)
scripts/export_pdf.py → pandoc + LaTeX (Figure 수동 포함)
scripts/export_pdf.py → weasyprint (HTML 기반)
Markdown만 저장 (PDF 변환 실패 시 경고)

undefined

python scripts/export_pdf.py study.md study.pdf

备选顺序:

scripts/export_latex_pdf.py（LaTeX + 图表，最高质量）
scripts/export_pdf.py → pandoc + LaTeX（手动嵌入图表）
scripts/export_pdf.py → weasyprint（基于HTML）
仅保存Markdown（PDF转换失败时发出警告）

undefined

Step 6.4: 완료 보고

Step 6.4: 完成报告

Update Complete!
  Markdown: study.md
  PDF: study.pdf
  Figures: figures/ ({N}개 PNG)
  New experiments: {N}개
  Writing quality: {score}/100
  Hypotheses: {N}개
  Next experiments: {N}개

Update Complete!
  Markdown: study.md
  PDF: study.pdf
  Figures: figures/ ({N}个PNG)
  New experiments: {N}个
  Writing quality: {score}/100
  Hypotheses: {N}个
  Next experiments: {N}个

Document Update Rules

文档更新规则

Append Only 원칙

仅追加原则

Append Only: 기존 내용 뒤에 새 섹션 추가. 기존 내용 수정 금지.
[NEW] 태그: 새로 추가된 실험에
```
[NEW]
```
태그 표시 (다음 업데이트 시 제거)
구분선: 새 실험 전에
```
---
```
구분선 삽입
날짜 표기: 실험 실행 날짜 (로그 타임스탬프 기반)
일관된 포맷: Report Template + references/interpretation-template.md 준수

仅追加: 在现有内容后添加新章节，禁止修改原有内容
[NEW]标签: 为新增实验添加
```
[NEW]
```
标签（下次更新时移除）
分隔线: 在新实验前插入
```
---
```
分隔线
日期标注: 基于日志时间戳标注实验执行日期
格式一致: 严格遵循Report Template + references/interpretation-template.md

[NEW] 태그 처리

[NEW]标签处理

markdown

---

markdown

---

[NEW] Experiment: {experiment_name} ({YYYY-MM-DD})

[NEW] Experiment: {实验名} ({YYYY-MM-DD})

...


다음 `/update-study` 실행 시:
1. 이전에 추가된 `[NEW]` 태그 모두 제거
2. 새로 추가되는 섹션에만 `[NEW]` 태그 부여

---

...


下次执行`/update-study`时:
1. 移除所有之前添加的`[NEW]`标签
2. 仅为本次新增章节添加`[NEW]`标签

---

Progress Reporting

进度报告

실행 중 사용자에게 상태를 보고합니다:

[Phase 0] Incremental Detection...
  Scanned logs/: {N}개 파일
  Already documented: {M}개 실험
  New experiments: {K}개 발견

[Phase 1] File Verification...
  로그 파일 확인: {K}개
  study.md 읽기 완료

[Phase 2] Data Extraction...
  메트릭 추출: {N}개 시계열
  DataFrame 구조화 완료
  메트릭 종류: accuracy, loss, grad_norm, ...

[Phase 3] Plot Generation...
  Training curve comparison: figures/training_curve_comparison.png
  Metric trend panel: figures/metric_trend_panel.png
  Final metric comparison: figures/final_metric_comparison.png
  총 {N}개 Figure 생성

[Phase 4] Interpretation + Writing...
  Executive Summary 생성 완료
  Figure 해석 작성: {N}개
  Proposed Improvements: {N}개
  → Writing Quality Loop:
    Iteration 1: Score 72/100
      - Critical: Definition missing (2)
      - Warning: Figure without interpretation (1)
    Iteration 2: Score 85/100
      All critical issues resolved

[Phase 5] Verification...
  → Numerical: {verified}/{total}
  → Logic: {sound}/{total}
  → Figure consistency: {matched}/{total}
  → Verdict: PASS

[Phase 6] Export...
  LaTeX 변환 완료
  PDF 생성 완료: study.pdf

Complete!
  - New experiments: {experiment_names}
  - Writing quality: {score}/100
  - Figures: {N}개
  - Hypotheses: {N}개
  - Next experiments: {N}개

执行过程中向用户实时报告状态:

[Phase 0] 增量检测...
  扫描logs/: {N}个文件
  已文档化实验: {M}个
  发现新实验: {K}个

[Phase 1] 文件验证...
  验证日志文件: {K}个
  读取study.md完成

[Phase 2] 数据提取...
  提取指标: {N}个时间序列
  DataFrame结构化完成
  指标类型: accuracy, loss, grad_norm, ...

[Phase 3] 图表生成...
  训练曲线对比: figures/training_curve_comparison.png
  指标趋势面板: figures/metric_trend_panel.png
  最终指标对比: figures/final_metric_comparison.png
  共生成{N}个图表

[Phase 4] 结果解读 + 文档撰写...
  执行摘要生成完成
  图表解读: {N}个
  改进建议: {N}个
  → 写作质量循环:
    Iteration 1: 得分72/100
      - 严重问题: 缺失2个定义
      - 警告: 1个图表无解读
    Iteration 2: 得分85/100
      所有严重问题已解决

[Phase 5] 验证...
  → 数值验证: {verified}/{total}
  → 逻辑验证: {sound}/{total}
  → 图表一致性: {matched}/{total}
  → 结论: PASS

[Phase 6] 导出...
  LaTeX转换完成
  PDF生成完成: study.pdf

完成!
  - 新实验: {实验名列表}
  - 写作质量: {score}/100
  - 图表: {N}个
  - 假设: {N}个
  - 后续实验: {N}个

Quality Criteria Summary

质量标准摘要

Criterion	Weight	Description
Definition-First	25점	용어 100% 정의, "X is Y" 형태
Topic-First	20점	문단 90% 두괄식
Compare-Contrast	15점	비교 테이블 + 차이 분석 필수
Insight Depth	15점	"왜" 분석 + mechanism 가설 포함
Minimal Adjectives	5점	수치 기반 표현, 형용사 최소화
Figure Quality	10점	Figure 해석 + caption + 참조 연결
Next Steps Clarity	10점	가설 연결 + config 구체성 + 예측

Overall Pass: >= 80점

标准	权重	描述
定义优先	25分	100%术语定义，采用"X is Y"形式
主题优先	20分	90%段落采用总起句结构
对比分析	15分	必须包含对比表格 + 差异分析
洞察深度	15分	包含"为什么"分析 + 机制假设
最少修饰词	5分	基于数值表述，最小化形容词
图表质量	10分	图表解读 + 标题 + 引用关联
后续步骤清晰度	10分	关联假设 + 具体配置 + 预测

通过标准: >= 80分

Additional Resources

附加资源

```
references/interpretation-template.md
```
- 실험 해석 템플릿
```
references/quality-criteria.md
```
- 글 품질 평가 상세 기준
```
scripts/generate_plots.py
```
- matplotlib 기반 차트 생성 유틸리티
```
scripts/export_latex_pdf.py
```
- LaTeX 변환 + Figure 포함 PDF 생성
```
scripts/export_pdf.py
```
- PDF 변환 유틸리티 (Fallback)

```
references/interpretation-template.md
```
- 实验解读模板
```
references/quality-criteria.md
```
- 写作质量评估详细标准
```
scripts/generate_plots.py
```
- 基于matplotlib的图表生成工具
```
scripts/export_latex_pdf.py
```
- LaTeX转换 + 嵌入图表的PDF生成工具
```
scripts/export_pdf.py
```
- PDF转换工具（备选方案）

Cautions

注意事项

로그 파일이 ground truth: 로그에 없는 수치는 사용 불가
Append Only: 이전 결과를 절대 수정하지 않음
매 수치에 출처:
```
(source: filepath:L행번호)
```
필수
가설은 falsifiable: 검증 불가능한 가설은 삭제
최대 3회 반복: Writing Quality Loop + Verification 각각 최대 3회
새 실험 우선: 이미 문서화된 실험은 자동 스킵
[NEW] 태그: 새 추가분 명확히 표시
Figure 필수: 모든 실험 보고서에 최소 1개 이상의 Figure 포함
코드 스니펫 검증: Implementation/Improvements 코드는 문법 정확성 확인
LaTeX 호환성: Markdown 내 특수문자 이스케이프 확인 (_, %, #, & 등)

日志文件为唯一依据: 禁止使用日志中不存在的数值
仅追加: 绝对不能修改之前的结果
数值必标来源: 必须添加
```
(source: 文件路径:行号)
```
假设需可证伪: 删除无法验证的假设
最大3次迭代: 写作质量循环 + 验证各最多3次
新实验优先: 自动跳过已文档化的实验
[NEW]标签: 明确标注新增内容
图表必填: 所有实验报告至少包含1个图表
代码片段验证: 实现/改进建议中的代码需确认语法正确性
LaTeX兼容性: 需转义Markdown中的特殊字符（_, %, #, &等）