| name | paper-analysis |
| description | 论文数据分析与建模。根据论文大纲执行数据处理、统计分析、模型训练，输出结果数据供图表生成使用。有用户数据则用真实数据，无数据则模拟高质量仿真数据。 |
| argument-hint | ["paper-plan-or-topic"] |
| allowed-tools | Bash(*), Read, Write, Edit, Grep, Glob, Agent |
论文数据分析与建模
根据论文大纲执行数据分析：$ARGUMENTS
输入
-
PAPER_PLAN.md — 论文大纲（必须存在）
-
TOPIC_PLAN.md — 选题规划（如有）
-
user_data/ — 用户上传的数据文件（可选）
-
data/ — 已有数据目录（可选）
工作流程
Step 0: 恢复检查
检查已有产出：
Step 1: 读取论文大纲 + 确定分析任务
从 PAPER_PLAN.md（或 TOPIC_PLAN.md）提取：
-
研究问题与假设
-
需要的统计方法/模型
-
变量定义（自变量、因变量、控制变量）
-
预期的图表清单（从图表预规划部分提取）
⛔ MANDATORY: 输出分析任务清单：
ANALYSIS CHECKLIST (from PAPER_PLAN.md):
[ ] 数据准备: [数据来源], [变量列表], [样本量]
[ ] 描述性统计: 均值/标准差/分布
[ ] 分析任务1: [方法名] — 输入: [xxx], 输出: [yyy]
[ ] 分析任务2: [方法名] — 输入: [xxx], 输出: [yyy]
[ ] 稳健性检验: [方法]
Step 1.5: 提取图表预规划
⛔ MANDATORY: 读取规划文档的图表预规划，了解 paper-figure 需要哪些数据。
echo "=== 图表预规划 ==="
for plan in PAPER_PLAN.md TOPIC_PLAN.md; do
[ -f "$plan" ] || continue
echo "--- $plan ---"
grep -i 'fig_\|图表\|TABLE_\|figure\|预规划\|配方' "$plan" | head -30
done
确保每个图表对应的数据都会在分析过程中输出到 JSON。
Step 2: 数据来源判断 + 环境准备
⛔ 关键决策：真实数据 vs 模拟数据
echo "=== 数据来源检查 ==="
DATA_SOURCE="simulate"
for dir in user_data data; do
if [ -d "$dir" ] && [ "$(ls -A $dir 2>/dev/null)" ]; then
echo "✅ 发现用户数据: $dir/"
ls -la $dir/
DATA_SOURCE="real"
fi
done
echo "数据来源: $DATA_SOURCE"
安装必要库：numpy, pandas, scipy, scikit-learn, statsmodels。
Step 3: 代码目录结构
code/
main.py # 主程序（串联所有分析）
data_preparation.py # 数据准备（读取/模拟 + 清洗）
analysis_1.py # 分析任务 1
analysis_2.py # 分析任务 2
robustness.py # 稳健性检验
utils.py # 公共工具
requirements.txt
Step 4: 数据准备
有用户数据时：
-
读取 CSV/Excel/JSON 文件
-
数据清洗：缺失值、异常值、类型转换
-
变量构造：交互项、滞后项、虚拟变量
-
描述性统计输出到 figures/descriptive_stats.json
无用户数据时（模拟）：
-
根据论文主题构造合理的模拟数据
-
数据必须符合 data_quality 规则（见下方）
-
设置随机种子 np.random.seed(42) 保证可复现
-
模拟数据保存到 data/simulated_data.csv
-
描述性统计输出到 figures/descriptive_stats.json
Step 5: 逐任务分析执行
必须按顺序逐项执行：编写 → 执行 → 验证 → 下一项。
⛔ MANDATORY: 数值必须从真实计算/真实数据得出，不得硬编码、不得编造。
禁止行为：
-
❌ 在 Python 代码里写死结果值，如 accuracy = 0.95（必须从 model.score() 或 accuracy_score() 得出）
-
❌ 在 RESULTS.md 里直接写数字但没有对应代码（所有数字都必须能从 figures/*.json 中找到出处）
-
❌ 为了配合论文叙述而篡改结果（结果不理想就改数字、调 seed 直到好看）
-
❌ LLM 脑补实验结果（必须真实跑代码）
正确做法：
-
✅ 代码真实执行，结果存入 figures/analysis_N_results.json
-
✅ 关键指标（accuracy、rmse、r2、p_value 等）必须通过 sklearn/statsmodels/scipy 等库真实计算
-
✅ 结果异常（太完美或太差）时回去查代码/数据，不要调参凑好看的结果
每个分析任务：
-
编写独立 Python 文件
-
执行并检查输出
-
验证结果合理性（系数方向、显著性、R²范围）
-
保存结果到 figures/analysis_N_results.json
-
结果异常则修改代码重跑
代码性能要求：
-
优先使用 numpy/pandas 向量化运算
-
每个脚本执行前后打印进度信息
-
如果代码跑超过 3 分钟，立即重写优化版本
Step 5.5: 稳健性检验
根据论文类型执行适当的稳健性检验：
结果保存到 figures/robustness_results.json。
Step 6: 结果验证 + 完整性检查
⛔ 第一步：自动化"太完美"检测（查 AI 编造结果 / 过拟合）：
import json, os, sys, math
results = {}
for f in sorted(os.listdir('figures')):
if f.endswith('_results.json') or f == 'all_results.json':
try:
with open(f'figures/{f}', 'r') as fh:
results[f] = json.load(fh)
except: pass
errors, warnings, suspicious = [], [], []
def check_unrealistic(name, val):
if not isinstance(val, (int, float)) or isinstance(val, bool): return
key = name.lower()
if any(w in key for w in ['r2', 'r_squared', 'accuracy', 'acc', 'precision', 'recall', 'f1', 'auc']):
if val > 0.99:
suspicious.append(f"🚩 {name} = {val:.4f}（>0.99），请在审查中确认是否过拟合")
val < :
errors.append()
val < (w key w [, ]):
errors.append()
(w key w [, , , ]):
val == :
suspicious.append()
val < :
errors.append()
(w key w [, , , , ]):
val > :
suspicious.append()
key key key:
val == :
suspicious.append()
val > :
errors.append()
():
(obj, ):
k, v obj.items(): walk(v, )
(obj, ):
i, v (obj): walk(v, )
(obj, (, )):
(obj, ):
math.isnan(obj): errors.append()
math.isinf(obj): errors.append()
check_unrealistic(path, obj)
fname, data results.items():
walk(data, fname)
e errors: (e)
s suspicious: (s)
errors:
(); sys.exit()
suspicious:
()
()
()
()
()
errors:
()
⛔ 第 1.5 步：结合研究背景的全面合理性审查（最关键）：
前面的自动 sanity check 只能抓固定模式。真正的合理性必须结合论文选题的实际场景来判断——只有你自己（AI）结合常识和研究背景才能发现所有问题。
强制执行以下审查流程：
echo "=== 结合研究背景的合理性审查 ==="
echo "--- 选题与研究设计 ---"
for src in PAPER_PLAN.md TOPIC_PLAN.md FINAL_PROPOSAL.md; do
[ -f "$src" ] && echo "=== $src ===" && cat "$src" | head -150
done
echo "--- 用户上传的数据概况 ---"
for src in user_data/*.csv user_data/*.xlsx; do
[ -f "$src" ] && echo "文件: $src ($(wc -l < "$src" 2>/dev/null) 行)"
done
echo "--- 所有结果数值 ---"
python3 -c "
import json, os
for f in sorted(os.listdir('figures')):
if not (f.endswith('_results.json') or f == 'all_results.json'): continue
try:
data = json.load(open(f'figures/{f}', 'r', encoding='utf-8'))
print(f'=== {f} ===')
print(json.dumps(data, ensure_ascii=False, indent=2)[:3000])
except: pass
" 2>/dev/null
然后你必须逐条回答以下 9 个问题（不能跳过，必须写在 RESULTS.md 末尾的"合理性审查"章节）：
=== 合理性审查（结合研究背景）===
Q1. [数值量级] 每个关键指标的数值量级是否符合研究场景？
举例：
- 社会科学：回归系数绝对值一般 < 10（标准化后一般 < 1）
- 经济学：GDP 增长率一般 0-20%，通货膨胀率一般 0-50%
- 机器学习：准确率 0-1，训练时间 < 100 小时（中等规模）
- 医学：OR 值一般 0.1-10，RR 值一般 0.5-5
- 你的研究领域：[自行判断]
逐条列出每个关键结果的数值，判断量级是否合理。
Q2. [符号方向] 结果的正负/大小方向是否符合先验假设和文献？
举例：
- 已知文献显示 X 对 Y 有正向影响，我的系数也应该是正的
- 理论预期：教育投入越多，收入越高 → 系数应为正
- 如果结果方向与主流文献相反，要么是重大发现（极罕见），
要么是代码 bug（更常见），必须深入检查
逐条检查结果方向是否与文献/理论一致。
Q3. [统计显著性分布] p 值分布是否合理？
- 所有变量的 p 值都 < 0.001？（太完美，可能过度拟合或数据泄漏）
- 所有 p 值都 > 0.05？（研究设计可能有问题）
- 正常应该：关键变量显著，控制变量部分显著，一些不显著
如果 p 值分布异常，说明数据或模型有问题。
Q4. [效应大小] 效应大小是否在文献报告范围内？
- 同类研究的效应大小一般 [a, b] 区间
- 我的效应大小是否与该区间一致？
- 如果效应特别大（比同类研究大 10 倍），要么是真正的重大发现，
要么是我的模型/数据处理有问题
查阅文献比较，在 RESULTS.md 中引用 2-3 篇同类研究作为对照。
Q5. [R² / 拟合优度] 拟合优度是否在合理范围？
**⛔ 关键：R² 的合理范围取决于任务类型，不能一刀切！**
- 截面数据经济学/社科研究：R² 一般 0.2-0.6（因为噪声大、变量多）
- 时间序列（含趋势）：R² 一般 0.7-0.95
- **物理/工程曲线拟合（如光谱拟合、信号拟合、传递函数拟合）：R² 应 > 0.8**
- 如果 R² < 0.5 → 模型形式错误（如缺少基线项、频率估计错误），必须换模型
- 如果 R² 在 0.5-0.8 → 模型可能遗漏了重要物理效应，需要检查
- 机器学习测试集：accuracy 一般 0.7-0.95（视任务难度）
- 物理仿真/确定性问题：R² 可能接近 1.0（正常）
**⛔ R² < 0.5 的拟合结果绝对不能直接写入论文。** 必须先诊断原因：
1. 模型形式是否正确？（是否遗漏了基线漂移、非线性项、相位偏移等）
2. 数据预处理是否正确？（是否需要去趋势、归一化、截取有效区间）
3. 初始参数是否合理？（非线性拟合对初值敏感）
修复后 R² 应显著提升，否则说明模型假设与数据不匹配。
如果 R² > 0.99 而任务又不是确定性问题，极大概率过拟合或数据泄漏。
Q6. [样本量与自由度] 样本量是否支撑所用方法？
- OLS 回归：每个参数至少 10-20 个样本
- Logistic 回归：每个事件至少 10 个（EPV 原则）
- 面板：截面 × 时间 至少 > 3 × 参数数量
- 机器学习：训练集至少 > 10 × 特征数（防维度灾难）
如果样本量不足，结果可能不稳定。
Q7. [变量间关系] 关键变量间的相关性是否合理？
- 互斥变量不应正相关（如 A 组 vs B 组）
- 同一概念的不同度量应正相关（如学历水平和毕业年限）
- 如果出现违反常识的相关性，检查数据处理是否出错
Q8. [稳健性] 稳健性检验结果是否与主模型一致？
- 替换变量/子样本/不同方法后，系数方向应基本一致
- 如果稳健性检验结果方向相反或差异巨大，主模型可能不可靠
至少做 2 种稳健性检验，并在 RESULTS.md 中对比报告。
Q9. [与研究设计一致] 实际结果是否与 PAPER_PLAN.md 中的研究设计预期一致？
逐条对照：
- 论文大纲说用 XX 方法 → 代码里确实用了 XX 方法？（不是偷换成更简单的）
- 论文大纲的研究假设 → 结果支持还是拒绝？（都支持太完美，都拒绝说明设计有问题）
- 论文大纲规划的分析任务 → 全部完成了？有遗漏的吗？
- 论文大纲预期的效应方向 → 实际方向一致？
- 如果结果与研究设计严重不符 → 要么代码有 bug（回去查），
要么研究设计需要调整（回去改 PAPER_PLAN.md 再重跑）
- 如果假设被拒绝 → 这是正常的科研结果，诚实报告，不要篡改
对每个问题必须明确回答 ✅（通过）、⚠️（需说明）、❌（有问题）。
如果任何一项打 ❌：
⛔ 第二步：智能自检（代码跑完后，你必须逐项回答以下问题）：
读取 PAPER_PLAN.md（或 TOPIC_PLAN.md）和 RESULTS.md，对照研究设计逐项自检。
通用检查（必做）：
=== 通用自检 ===
1. [研究覆盖] 论文大纲中规划的分析任务是否全部完成？缺了哪个？
2. [数值合理] 结果数值是否符合领域常识？（回归系数方向、效应大小）
3. [NaN/Inf] JSON 结果中是否有 NaN、Inf、null？
4. [统计规范] 是否报告了所有必要的统计量？（系数、标准误、p值、R²、样本量）
5. [数据一致] 描述性统计的样本量是否与回归分析一致？
统计/实证类检查（论文写作场景必做）：
=== 统计/实证类 ===
S1. [多重共线性] VIF 是否有 > 10 的变量？
S2. [内生性] 是否考虑了遗漏变量/反向因果？
S3. [异方差] 是否用了稳健标准误？
S4. [p值分布] 是否所有 p 值都 < 0.001？（太完美=可疑）
S5. [样本量] 截面 ≥ 200？面板 ≥ 30×10？时间序列 ≥ 100？
S6. [稳健性] 是否做了至少一种稳健性检验？
S7. [过拟合] R² < 0.99？训练集和测试集差距 < 10%？
对每项回答 ✅ 或 ❌ + 原因。如果有 ❌，修改代码重跑。
⛔ MANDATORY: 对照 Step 1 的分析清单，逐项验证：
echo "=== 分析清单对照 ==="
echo "检查结果文件："
for f in figures/descriptive_stats.json figures/all_results.json figures/robustness_results.json; do
if [ -f "$f" ] && [ -s "$f" ]; then
echo " ✅ $f ($(wc -c < "$f") bytes)"
else
echo " ❌ $f — MISSING or EMPTY"
fi
done
echo ""
echo "检查分析结果 JSON："
ls -la figures/analysis_*_results.json 2>/dev/null || echo " (无)"
echo ""
echo "检查代码文件："
for f in code/*.py; do
[ -f "$f" ] && echo " ✅ $(basename $f)" || echo " ❌ $(basename $f)"
done
如果有 ❌，必须回去补完再继续。
⛔ MANDATORY: 下游预期检查（paper-figure / paper-write 需要什么）：
echo "=== 下游预期检查 ==="
if [ -f PAPER_PLAN.md ]; then
echo "--- 图表规划 vs JSON 数据 ---"
PLANNED_FIGS=$(grep -o 'fig_[a-zA-Z_0-9]*' PAPER_PLAN.md 2>/dev/null | sort -u)
for fig in $PLANNED_FIGS; do
if [ -f figures/all_results.json ] && grep -q "$fig\|${fig#fig_}" figures/all_results.json 2>/dev/null; then
echo " ✅ $fig — 在 all_results.json 中找到对应数据"
elif [ -f "figures/${fig}_results.json" ]; then
echo " ✅ $fig — 有独立 JSON 文件"
else
echo " ⚠ $fig — 未找到支撑数据（paper-figure 将难以画图）"
fi
done
fi
if [ -f PAPER_PLAN.md ]; then
echo ""
echo "--- Claims-Evidence 回填检查 ---"
python3 -c "
import re, json, os
try:
plan = open('PAPER_PLAN.md', 'r', encoding='utf-8').read()
except: exit(0)
# 提取 claims-evidence 表格（| Claim | Evidence | ... |）
rows = re.findall(r'\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|', plan)
# 过滤表头和分隔符
claims = [(c.strip(), e.strip()) for c, e in rows if c.strip() not in ('Claim', '---') and '---' not in c and len(c.strip()) > 5]
if not claims:
print(' （未检测到 Claims-Evidence 矩阵）')
exit(0)
# 加载实验数据
results_text = ''
for f in ['figures/all_results.json', 'RESULTS.md', 'experiment_results.md']:
if os.path.exists(f):
try: results_text += open(f, 'r', encoding='utf-8').read()
except: pass
missing = []
for c, e in claims[:10]: # 最多检查前 10 个
# Evidence 里提到的关键词是否在结果数据中出现
keywords = re.findall(r'[a-zA-Z_]{4,}|[\u4e00-\u9fff]{2,}', e)[:3]
if not any(kw.lower() in results_text.lower() for kw in keywords):
missing.append(c[:40])
if missing:
print(f' ⚠ {len(missing)}/{len(claims)} claims 在实验数据中找不到对应证据:')
for m in missing[:5]: print(f' - {m}')
else:
print(f' ✅ {len(claims)} claims 在实验数据中都能找到对应证据')
" 2>/dev/null ||
如果下游预期检查发现缺失，考虑补充对应的分析代码再重跑，或在 RESULTS.md 中明确标注该 claim 需要的数据还没算。
Step 7: 结果汇总
-
汇总所有分析结果到 figures/all_results.json
-
编写 RESULTS.md：每个分析任务的方法、关键发现、数据文件路径
关键规则
-
paper-analysis 只负责数据处理、统计分析、输出结果数据（JSON/CSV）。不画图。
-
⛔ 禁止生成 PDF 图表。 不要调用 plt.savefig() 或 save_fig()。图表全部由下一步 paper-figure 生成。
-
主输出文件：RESULTS.md + figures/*.json + code/*.py
-
代码必须能运行：写完必须执行验证
-
结果必须保存为 JSON/CSV 文件（供 paper-figure 读取画图）
-
代码要有注释
-
数据路径用相对路径
-
requirements.txt 必须生成
<data_quality>
数据模拟质量规则（无用户数据时）
-
真实范围：数值必须符合研究领域 — 如 GDP 用万亿元不是随机 0-1，温度用 °C 不是任意整数
-
有意义的模式：数据应体现模型要捕捉的趋势/关系 — 如研究季节性需求，数据应有季节性波动
-
图表友好：设计数据使图表看起来专业且有信息量：
-
避免极端异常值把主数据压缩到很小的范围
-
不同方法/组之间有可见但不夸张的差异（5-20% 差距，不是 0.1% 或 500%）
-
足够的数据点保证曲线平滑（折线图 ≥50 点，分布图 ≥200 点）
-
方法对比：本文方法应最优但不要不切实际地碾压 — 其他方法在某些指标上也有优势
-
与论文主题一致：所有生成的数据必须可追溯到论文大纲的描述
-
可复现：设置随机种子 np.random.seed(42)
-
样本量合理：
-
实证论文：至少 200+ 观测值
-
面板数据：至少 30 个体 × 10 期
-
时间序列：至少 100 个时间点
-
截面数据：至少 500 个样本
</data_quality>
