| name | gen-report |
| description | Generate a comprehensive experiment report with full output discovery, visualization generation, and paper-style figure analysis. Use when the user asks to write a report, summarize an experiment, document results, 写报告, 整理实验, 总结实验结果, or invokes /gen-report. |
gen-report
生成完整实验报告。报告结构：理论 → 实现 → 实验结果分析。要求覆盖所有现有输出文件，并对每个图表做论文级别讲解。
输出位置
report/project_report_zh.md（或用户指定路径）
Phase 0 — 确认实验目标
从上下文推断项目根目录和报告主题。若不明确，问用户。
Phase 1 — 代码扫描：发现所有可能的输出文件（必须执行）
目的：通过读源码，预判实验会生成哪些文件，再去实际检查是否存在。
1a. 扫描所有脚本/代码（并行）
- 递归列出
code/ 或同等目录下的所有 .py 文件
- 对每个脚本，提取：
- 所有写文件的路径（
open()、np.save、to_csv、savefig、json.dump 等）
- 所有
output_dir、OUT_DIR、save_path 等变量的值
- 列出推断出的完整输出文件列表（路径 + 文件类型 + 生成哪个脚本）
1b. 扫描配置文件
- 读取所有
config.yaml、*.toml、*.json 配置
- 提取：输出路径配置、数据集路径、关键超参数
Phase 2 — 实际输出盘点：逐目录检查（必须执行）
目的：确认哪些输出文件真实存在于磁盘上。
2a. 列出所有输出目录的内容
ls -lh <output_dir>/
find <output_dir>/ -type f | sort
2b. 分类现有输出
将实际存在的文件分三类：
- 图像文件（
.png、.jpg、.svg）：直接可插入
- 表格/数值文件（
.csv、.jsonl、.json、.npz、.npy）：需读取数值 + 考虑可视化
- 文本日志（
.log、.err、.out、.md）：提取关键数值
2c. 读取所有数值文件
- 每个 CSV：读取全部或最后20行，记录关键列和数值范围
- 每个 JSON/JSONL：读取并解析关键字段
- 每个 NPZ：用
np.load 列出所有 key、shape、dtype、min/max/mean
Phase 3 — 可视化生成（对纯数据文件强制执行）
目的：将没有对应图像的数值数据转化为图表，插入报告。
规则
- 对每个只有数据没有图的重要数据文件，必须生成对应图表
- 图表保存到
report/figures/ 目录（相对于 repo 根目录）
- 使用 Python + matplotlib，风格：
plt.style.use('seaborn-v0_8-whitegrid')，figsize 合理，标注 xlabel/ylabel/title/legend
可视化脚本规范
import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt
import numpy as np
fig, ax = plt.subplots(figsize=(10, 6))
ax.set_xlabel('...')
ax.set_ylabel('...')
ax.set_title('...')
ax.legend()
plt.tight_layout()
plt.savefig('report/figures/<name>.png', dpi=150, bbox_inches='tight')
plt.close()
print("Saved: report/figures/<name>.png")
执行方式
- 将脚本写入
report/figures/gen_<name>.py
- 用 Bash 执行：
python report/figures/gen_<name>.py
- 执行后验证文件存在：
ls -lh report/figures/<name>.png
Phase 4 — 逻辑顺序规划
在写报告前，先在内部规划叙事顺序：
理论动机（为什么做这个实验）
↓
核心假设（用什么方法验证）
↓
实现细节（怎么实现的，关键工程决策）
↓
实验结果（按逻辑因果顺序，不按文件顺序）
├── 数据采集/预处理结果
├── 中间分析结果（差分、统计等）
├── 注入/干预效果
└── 最终对比结论
↓
综合结论与局限性
Phase 5 — 填充报告模板
使用以下结构。所有 {{}} 占位符必须替换为真实内容，不得留空。
# {{PROJECT_NAME}} — 综合实验报告
**生成时间：** {{YYYY-MM-DD}}
**项目根目录：** `{{REPO_ROOT}}`
---
## 摘要
{{2-3句话：核心假设、实验做了什么、最关键的结论}}
---
## 1. 理论动机与核心假设
### 1.1 问题定义
{{描述实验试图回答的科学问题}}
### 1.2 核心假设
{{明确陈述假设。格式："我们假设 X，因为 Y，验证方法是 Z"}}
### 1.3 核心公式（若有）
$$
{{公式}}
$$
**直觉解释**：{{高值/低值意味着什么，物理意义}}
---
## 2. 实现架构
### 2.1 实验流程
{{按阶段描述整体流程，用简洁的文字 + 列表}}
### 2.2 模型与数据
| 属性 | 值 |
|------|-----|
| {{ATTR_1}} | {{VAL_1}} |
| {{ATTR_2}} | {{VAL_2}} |
### 2.3 关键工程决策
{{描述实现中非显而易见的选择，以及选择的原因}}
- **决策1**：{{决策内容}} — **原因**：{{为什么这样做，有何替代方案}}
- **决策2**：...
### 2.4 运行配置
```yaml
{{粘贴关键配置，来源：config.yaml 或等效文件}}
3. 实验结果分析
本节覆盖所有已生成的输出文件。每个子节对应一类输出。
3.X {{现象/结果名称}}
数据来源：{{文件路径}}（{{文件类型}}，{{行数/shape}}）
图X说明：
- 横轴（x轴）：{{含义、单位}}
- 纵轴（y轴）：{{含义、单位}}
- 图例：{{每条线/每个颜色代表什么}}
- 颜色编码（若有）：{{颜色 → 含义的映射}}
结果分析：
- 观察到的现象：{{描述图中最显著的模式，数值要具体}}
- 因果解释：{{为什么会出现这个现象，与假设的关系}}
- 与预期的对比：{{符合/不符合假设，偏差有多大}}
- 异常/亮点：{{值得特别注意的点，若无则删去此行}}
4. 综合结论
4.1 假设验证结果
| 假设 | 验证结果 | 支持证据 |
|---|
| {{HYPOTHESIS_1}} | 支持/不支持/部分支持 | {{图X / 表Y / 数值Z}} |
4.2 关键数值汇总
| 指标 | 值 | 来源 |
|---|
| {{METRIC_1}} | {{VAL_1}} | {{文件:行号}} |
4.3 局限性
4.4 下一步
附录：文件位置参考
| 文件/目录 | 路径 | 说明 |
|---|
| {{FILE_1}} | {{PATH_1}} | {{DESC_1}} |
---
## Phase 6 — 图片插入规范（强制）
### 路径规则
- 使用**相对路径**，相对于报告文件所在目录
- 已有图片（如 `stage2_output/*.png`）：`../stage2_output/heatmap_delta_gsm8k.png`
- 新生成图片（存放在 `report/figures/`）：`figures/gen_xxx.png`
### 每张图的完整格式（缺一不可）
```markdown
**图N说明**：
- **横轴**：{{含义 + 单位}}
- **纵轴**：{{含义 + 单位}}
- **图例**：{{每个系列的含义}}
- **颜色/标记**：{{若有颜色编码，逐一说明}}
**结果分析**：
- **现象**：{{数值具体，如"层6的p值为2.09e-8，是所有层中最显著的"}}
- **解释**：{{因果，与假设的关联}}
- **结论**：{{这张图支持/否定/部分支持什么}}
强制覆盖规则
- 实验目录下所有
.png 文件必须全部出现在报告中
- 每个数值文件（CSV/NPZ/JSON），若无对应图，必须生成图后插入
- 不允许"数据存在但报告里没有图"的情况
Phase 7 — 保存与验证
- 确保
report/figures/ 目录存在（mkdir -p report/figures）
- 将报告写入目标路径
- 验证所有图片路径可访问：逐一检查
report/ 下图片路径是否指向实际文件
- 告知用户：报告路径 + 插入了哪些图（新生成 vs 已有）+ 核心结论摘要
指标汇报规范（全局强制）
- 所有数值必须来自实际读取的文件，禁止推断或估算
- 每个数值必须标注：来源文件路径 + 行号/key
- 禁止使用"约"、"大约"、"可能"、"应该"
- 图中数值与文字描述必须一致，不允许矛盾
