ai-experiment-report

name	ai-experiment-report
description	为 AI 训练和推理实验生成结构化的 Markdown 实验报告。当用户完成了一次 AI 实验（模型训练、推理测试等）并希望记录结果时使用此技能。 触发场景：用户说"写实验报告"、"记录这次实验"、"总结一下这次训练/推理结果"、"生成 report"， 或者在完成训练/推理任务后需要归档实验信息。即使用户只是说"记录一下"或"总结一下"， 只要上下文涉及 AI 实验，就应该触发此技能。

AI 实验报告生成器

为 AI 训练和推理实验生成详细、可追溯的 Markdown 报告，自动对比上次实验的差异。

整个过程全自动完成，不向用户询问任何信息。所有数据从项目环境中自动提取。

工作流程

1. 自动收集实验信息

所有信息均通过以下方式自动获取，不要向用户提问。

实验名称 — 从最近执行的训练/推理脚本名称或配置文件推断。例如脚本叫 train_bert.sh，则实验名称为 bert-training。如果脚本名不够语义化，结合模型名、任务类型等信息命名。

实验目的 — 综合以下信息推断本次实验目的：

• 与上次实验相比的参数变化（改了什么往往说明想验证什么）
• git commit message（如果有近期提交）
• 代码改动的内容和方向
• 当前对话上下文中用户提到的意图

关键指标 — 从训练/推理日志中自动提取：

• 查找最近的日志文件（如 *.log、output/、logs/、wandb/、tensorboard 日志等）
• 提取 loss、accuracy、throughput、latency 等指标
• 如果日志在终端输出中（当前对话上下文），直接从中提取

实验标签 — 根据实验内容自动生成标签，如：

• 实验类型：training / inference
• 模型名：bert / llama / gpt
• 调优方向：lr-tuning / batch-size / data-augmentation

GPU 卡数 — 自动检测：

# 从训练命令中提取（如 --nproc_per_node=4）
# 或从环境中检测
nvidia-smi -L 2>/dev/null | wc -l

也可以从训练脚本的参数（--nproc_per_node、--num_gpus、CUDA_VISIBLE_DEVICES）中推断。

命令和参数 — 从 shell history 和脚本文件中提取本次实验使用的命令：

# 查看最近的相关命令（从 zsh history 文件读取，因为内置 history 命令在非交互 shell 中不可用）
cat ~/.zsh_history | grep -E '(python|torchrun|deepspeed|accelerate|bash.*\.sh)' | tail -30

同时检查项目目录下的训练/推理脚本（如 train.sh、run.sh、inference.py 等），读取其中的关键参数。

代码变更 — 通过 git diff 检测自上次提交以来的修改：

git diff --stat
git diff

如果没有未提交的改动，再对比最近两次 commit 之间的差异：

git log --oneline -5
git diff HEAD~1..HEAD --stat

如果没有改动，在报告中注明"本次实验无代码修改"。

上次实验报告 — 读取 ./report/ 目录下按文件名排序最新的报告，用于对比：

ls -1 ./report/*.md | sort | tail -1

读取该报告的全部内容，提取命令参数和关键指标用于对比。如果没有历史报告，跳过对比，注明"首次实验，无历史对比"。

2. 生成报告

报告保存路径：./report/YYMMDD-实验名称.md

例如：./report/260426-bert-lr-tuning.md

确保 ./report/ 目录存在（不存在则创建）。

3. 报告模板

严格按照以下结构生成报告：

# 实验名称

**日期**: YYYY-MM-DD
**标签**: `tag1` `tag2` `tag3`

## 关键指标摘要

| 指标 | 本次结果 | 上次结果 | 变化 |
|------|---------|---------|------|
| Loss | 0.xxx | 0.xxx | -x.x% |
| Accuracy | xx.x% | xx.x% | +x.x% |

> 首次实验时省略"上次结果"和"变化"两列。

## 实验目的

从参数变化、代码改动、commit message 等信息推断出的实验目标。

## 运行文件与实验参数

**运行文件**: `path/to/train.sh` 或 `path/to/run.py`（给出实际执行的脚本或入口文件的完整路径）

**运行命令**:

\```bash
# 完整命令，包含所有参数
\```

**基本参数**:

| 参数 | 值 |
|------|------|
| GPU 数量 | 4 |
| Batch Size | 32 |
| Steps / Epochs | 10000 steps |
| Learning Rate | 5e-5 |

**实验特有参数**（根据具体实验列出影响实验结果的关键参数，如 warmup ratio、weight decay、模型结构参数、量化位数、序列长度等）:

| 参数 | 值 |
|------|------|
| warmup_ratio | 0.1 |
| max_seq_length | 512 |

> 基本参数（GPU 数量、batch size、step/epoch 数、learning rate）是每份报告的必填项，从脚本、命令行参数或配置文件中提取。实验特有参数根据实验类型不同而不同，选择对结果影响最大的参数列出。

### 与上次实验的参数差异

| 参数 | 上次 | 本次 |
|------|------|------|
| learning_rate | 1e-4 | 5e-5 |
| batch_size | 16 | 32 |

> 首次实验时注明"首次实验，无历史对比"。

## 代码修改

git diff 检测到的代码变更摘要：
- `文件名`: 改动简述

无修改时写"本次实验无代码修改"。

## 实验结果

从日志中提取的详细实验数据。训练实验侧重 loss 曲线和收敛情况，推理实验侧重速度和输出质量。

## 结果分析

- 结果是否符合预期
- 与上次实验对比的改进/退步原因
- 值得注意的现象

## 实验结论与下一步

**结论**: 本次实验的核心发现。

**下一步计划**:
- 后续实验方向
- 待验证的假设

4. 对比逻辑

对比上次实验时，重点关注：

• 参数变化：学习率、batch size、epoch 数、模型结构参数等，用表格清晰列出差异。
• 指标变化：在摘要表中用百分比或绝对值展示变化幅度。进步如实记录，退步也如实记录。
• 命令变化：如果训练命令本身发生了变化（换了启动方式、加了新 flag），标注出来。

5. 写作原则

• 用数据说话，避免模糊描述（"效果有所提升" → "accuracy 从 85.2% 提升至 87.1%"）
• 对比部分具体到参数名和数值
• 分析部分结合实验上下文来解读
• 如果某项信息确实无法自动获取，标注"未检测到"而不是编造数据