Analysis Summary Report

Analysis Summary Report — 分析后总结报告

🔒 报告完整性铁律（禁止偷懒）

1. 只要检查到有分析结果，所有分析辩论、图片都要加入报告，不许漏。
2. 如果有图才几十 KB，那就是有问题的——必须报告并重新生成。
3. 不特定说明的情况下，报告必须覆盖本次分析的所有模块和所有图片。
4. 每张图的 4 个面板（method/result/bio/param_source）全部必填，传空直接报错。
5. 报告中每张图的解读结论必须经过 debate_figure_conclusions 辩论。
6. 报告中每个分析模块的总结论必须经过 debate_figure_conclusions 辩论。

🔒 报告语言铁律

• 检测用户交互语言：用户用中文 → 报告全程中文；用户用英文 → 报告全英文。
• 无论重新生成多少次，语言必须与用户首次交互语言一致。

🔒 图片健康度铁律

• 放入 HTML 的每张图片必须检查（rail_review POST 审查会自动检测）：
  • 文件大小 < 5KB → 强制重新生成
  • 全白/全黑/全单一色 → 强制重新生成
  • 含大量 NA 值 → 画图不全，强制重新生成
  • 文件损坏 → 强制重新生成
• 不允许跳过任何问题图。

触发场景

触发条件（必须全部满足）：

1. 已经完成真实分析（有 terminal 执行结果 + 生成了 figures）
2. 用户要求总结/报告/归纳

不触发：

• 没有做过分析，只是文献综述/整理结果
• 只有个别步骤完成，没有系统分析
• 概念咨询、闲聊

报告 7 模块结构

模块 1：📊 数据概览

• 数据来源（文件路径、格式）
• 细胞数、基因数
• 物种、组织、测序方法
• 硬件环境（CPU/内存/GPU/磁盘，来自 scan_data）

模块 2：🔬 分析流程

• 每步分析用了什么 skill
• 每步的参数（归一化方法、聚类分辨率、PC数等）
• 每步的执行时间
• 每步的 rail_review 结果（通过/不通过）

模块 3：📚 知识库来源

• 每个参数推荐来自哪条知识库记录
• 知识库类目（标准化/批次校正/聚类/注释/DEG等）
• 匹配的文献引用

模块 4：🗣️ 辩论记录

• 每轮 debate_analysis 的完整记录
• 正方论点（生物学/统计学/生信角度）
• 反方论点（同样角度 + 历史经验/报错记录）
• 裁决结果、分数、行动项

模块 5：📈 图表结果

• 每张图带 4 个面板：
  • 方法：用了什么方法生成
  • 结果：图展示了什么
  • 生物学意义：图说明了什么生物学发现
  • 参数来源：参数来自知识库/文献/辩论/经验
• 图片按分析模块排列（QC图 → PCA → UMAP → 标记基因 → DEG → 通路等）

模块 6：🧬 生物结论

• 结论辩论（必须）：
  • 正方：从生物学（marker gene验证、已知生物学知识）、统计学（显著性、效应量）、生信（质量指标）角度支持结论
  • 反方：从同样角度 + 历史经验记录 + 报错记录质疑结论
  • 裁判：综合裁决，给出置信度（高/中/低）
  • 不互通上下文：正方不知道反方说了什么
• 结论必须根据真实结果总结，不能凭空编造
• 每条结论标注证据来源（哪张图、哪个分析、哪个辩论）

模块 7：⚠️ 质量评估

• QC 指标：nFeature、nCount、percent.mt 分布
• 双胞率
• 污染率（如果做了去污染）
• 线粒体阈值
• 细胞过滤前后数量对比

技术实现

基于 bioinformatics-html-report 的 ReportBuilder API：

import sys
sys.path.insert(0, "hermes_home/skills/bioinformatics/bioinformatics-html-report")
from html_report_builder import ReportBuilder

rb = ReportBuilder(
    title="MemOmics Analysis Summary",
    subtitle="scRNA-seq Analysis Report",
    stats=[("细胞数", "30,000"), ("基因数", "20,000"), ("聚类数", "12")],
    key_findings=["发现 X 个主要细胞群", "衰老相关基因在 Type II 纤维中上调"]
)

# 模块 1-7 分别用 section
with rb.section("overview", "Data Overview", "数据概览"):
    ...

with rb.section("pipeline", "Analysis Pipeline", "分析流程"):
    ...

# 每张图用 add_figure（4面板）
rb.add_figure(
    fig_path="figures/umap.png",
    caption_en="UMAP Visualization",
    method_zh="Seurat UMAP 降维可视化",
    result_zh="12个细胞群清晰分离",
    bio_zh="Type II 纤维细胞是最大群体，符合骨骼肌组织特征",
    param_source_zh="聚类分辨率0.5来自知识库推荐（139条匹配）"
)

# 辩论记录用 add_debate
rb.add_debate(topic="聚类分辨率选择", rounds=[...])

rb.save("analysis_summary_report.html")