name: academic-figure-engine description: > 学术论文出图引擎——覆盖所有常见图表类型，执行五层质量框架。 触发条件: (1) 用户说"画图"/"出图"/"generate figure"/"重新画", (2) 需要生成 KM曲线/森林图/热图/箱线图/散点图/雷达图/Table等, (3) manuscript-reviewer 或用户指出图表质量问题, (4) paper-pipeline 在分析完成后自动调用。 核心能力: 从原始数据生成达到期刊投稿标准的图表， 每个数字溯源验证，不通过对账不出图。 allowed-tools: Read, Write, Edit, Glob, Grep, Bash

Academic Figure Engine - 学术论文出图引擎

核心原则

图上每个元素都必须有数据出处，不允许"凭记忆"或"从稿件抄"。

来源: P-A 论文 STROBE 流程图 v1→v3 三次迭代经验 (2026-02-26)

触发条件

1. 用户说"画图"/"出图"/"generate figure"/"重新画"/"这个图不行"
2. paper-pipeline 编排器在分析完成后自动调用
3. manuscript-reviewer 发现图表质量问题
4. 用户提供已有图片说"改进"/"升级"/"重做"
5. 需要生成任何学术论文图表

输入

• 必需: 数据文件路径 或 分析结果文件
• 必需: 图表类型（自动推断或用户指定）
• 可选: 目标期刊（决定风格规范）
• 可选: 参考图示例
• 可选: 稿件路径（用于图文同步）

输出

• fig{N}_{type}.png — 预览版 (300 DPI)
• fig{N}_{type}.pdf — 矢量版 (投稿/排版)
• fig{N}_{type}.tiff — 投稿版 (300 DPI, 期刊常要求)
• 验证报告（打印到终端）

五层质量框架

每一张图都必须依次通过五层质量检查，缺一不可。

Layer 1: 规范理解 (Standard)

在动手画之前，先搞清楚这类图的学术标准。

1. 确认图表类型对应的学术规范
2. 查询目标期刊的 Figure Guidelines（DPI、尺寸、字体、颜色模式）
3. 如可能，找同期刊同类型已发表图作为参考

各图类型规范速查：

Layer 2: 数据溯源 (Data Truth)

在画图之前，从原始数据重新计算每一个将出现在图上的数字。

# 标准流程
import pandas as pd

# 1. 加载原始数据（不从稿件或分析报告抄数字）
df = pd.read_csv('data/analysis_ready.csv')

# 2. 按分析逻辑逐步计算
# ...

# 3. 生成数字清单
figure_numbers = {
    'total_n': len(df),
    'group_a_n': ...,
    'group_a_events': ...,
    'hr_value': ...,
    'ci_lower': ...,
    'ci_upper': ...,
    'p_value': ...,
}

必须检查的边界条件：

• 排除原因的精确分解（不笼统写 "excluded"）
• time=0、NaN vs 0 的区别
• 百分比的分母是谁
• 分组标签是否准确反映数据内容（P-A教训：326人"无TCM"实际281人有稀有证型）

Layer 3: 精确绘制 (Technical Execution)

通用技术配置：

import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt

# 通用字体设置
plt.rcParams.update({
    'font.family': 'Arial',
    'font.size': 9,
    'axes.linewidth': 0.8,
    'axes.labelsize': 9,
    'xtick.labelsize': 8,
    'ytick.labelsize': 8,
    'legend.fontsize': 8,
    'figure.dpi': 300,
})

# 通用色彩方案（医学期刊友好）
COLORS = {
    'primary':   '#2C3E50',  # 深蓝灰
    'secondary': '#7F8C8D',  # 中灰
    'accent':    '#E74C3C',  # 红（高亮用）
    'groups': ['#2C3E50', '#E74C3C', '#27AE60', '#F39C12'],  # 4组对比色
    'fill':      '#F5F5F5',  # 浅灰填充
    'grid':      '#EEEEEE',  # 网格线
}

# 通用保存函数
def save_figure(fig, base_path, pad=0.15):
    """三格式保存 + 消除空白"""
    for ext in ['png', 'pdf', 'tiff']:
        fig.savefig(f'{base_path}.{ext}',
                    dpi=300,
                    bbox_inches='tight',
                    pad_inches=pad,
                    facecolor='white',
                    edgecolor='none')
    plt.close(fig)

风格指南加载（可选）：

当指定了目标期刊时，在 Layer 3 开始前加载对应风格指南：

• 医学期刊（EJHF/Circulation/JAMA/Lancet/BMJ 等）→ 加载 references/medical_plot_style_guide.md
• 风格指南影响：色彩方案、轴线样式、网格设置、图例位置、图类型专项规范
• 优先级：期刊硬性要求 > 风格指南建议 > 上方默认配置
• 风格不得覆盖数据内容：Layer 2 数字 > 任何美学决策

技术标准：

Layer 4: 数据对账 (Verification)

图上每一个数字都必须通过自动化断言验证。不通过 = 不出图。

def verify_figure(checks):
    """
    checks: list of (label, expected, actual) tuples
    """
    all_pass = True
    for label, expected, actual in checks:
        ok = '✅' if expected == actual else '❌'
        if expected != actual:
            all_pass = False
        print(f"  {ok} {label:35s}  expected={expected}  actual={actual}")

    if all_pass:
        print("\n  ✅ ALL NUMBERS VERIFIED — FIGURE IS DATA-ACCURATE")
    else:
        raise ValueError("❌ VERIFICATION FAILED — DO NOT OUTPUT THIS FIGURE")

Layer 5: 图文同步 (Figure-Manuscript Sync)

出图/改图后，必须回头检查稿件：

1. 扫描稿件中引用该图数据的所有位置
2. 修正不一致的数字（如随访率 91.2% → 90.1%）
3. 修正不一致的措辞（如排除理由表述）
4. 确认 Figure legend 与图内容匹配
5. 确认 Figure 编号引用正确

Layer 6: Critic 迭代循环 (Visual Refinement)

来源：PaperBanana CriticAgent (Google, 2026) 适配。原 Layer 6 布局预检 6 项合并为 C3 子检查。

出图后进入 Critic 迭代循环，最多 3 轮。每轮：

1. 查看：用 Read 工具查看当前 PNG
2. 评估：按 6 维度逐项判断（✅ Pass / ❌ Needs Fix）
3. 修改：修改 matplotlib 代码
4. 重新生成：重新运行代码 + Layer 4 重新验证

6 维度评估摘要：

详细标准见 references/critic_evaluation_criteria.md

C3 布局预检清单（原 Layer 6 实战经验，合并入 Critic C3）：

Gemini 视觉审查代码模板：

import base64, json, os, requests

def gemini_visual_review(png_path: str) -> dict:
    """用 AiCodeWith Gemini 3 Pro Image 审查学术图表布局质量"""
    # API Key: AiCodeWith (api.with7.cn)
    api_key = os.environ.get("AICODEWITH_API_KEY")
    if not api_key:
        env_path = os.path.expanduser("~/.openclaw/credentials/.env")
        for line in open(env_path):
            if line.startswith("AICODEWITH_API_KEY="):
                api_key = line.strip().split("=", 1)[1].strip('"\'')

    with open(png_path, "rb") as f:
        img_b64 = base64.b64encode(f.read()).decode()

    prompt = (
        "You are reviewing a scientific figure for VISUAL LAYOUT quality. "
        "Check these 4 items and answer YES or NO for each:\n"
        "1. LABEL OVERLAP: Are any y-axis labels overlapping each other?\n"
        "2. ANNOTATION COLLISION: Do any annotations/text overlap with data elements or other labels?\n"
        "3. READABILITY: Are all text elements large enough to read at print size?\n"
        "4. PROFESSIONAL: Does this look publication-ready for a medical journal?\n"
        "Format: 1.YES/NO 2.YES/NO 3.YES/NO 4.YES/NO then brief explanation for any NO."
    )

    # Gemini 原生 API 格式 (AiCodeWith 代理)
    resp = requests.post(
        "https://api.with7.cn/api/image/gemini/v1beta/models/gemini-3-pro-image-preview:generateContent",
        headers={"Authorization": f"Bearer {api_key}",
                 "Content-Type": "application/json"},
        json={
            "contents": [{
                "role": "user",
                "parts": [
                    {"inline_data": {"mime_type": "image/png", "data": img_b64}},
                    {"text": prompt}
                ]
            }],
            "generationConfig": {
                "temperature": 0.2,
                "maxOutputTokens": 2048
            }
        },
        timeout=60,
    )
    data = resp.json()
    result = data["candidates"][0]["content"]["parts"][0]["text"]

    # 解析 YES/NO
    issues = []
    for line in result.split("\n"):
        if "NO" in line.upper() and any(f"{i}." in line for i in range(1, 5)):
            issues.append(line.strip())
    return {"pass": len(issues) == 0, "issues": issues, "raw": result}

停止条件：

• 所有 6 维度 ✅ Pass + Gemini 4 项全 YES → 输出 "No changes needed." → 跳出循环
• 有维度 ❌ 或 Gemini 有 NO → 修改代码 → 重新生成 → Layer 4 重新验证 → 下一轮
• 最多 3 轮（超过后使用当前最佳版本）

回滚规则：

• 每轮保留当前最佳 PNG（fig{N}_{type}_round{R}.png）
• 新版本必须同时通过 Layer 4 验证 + Critic 评估才可替换
• 任一轮生成失败 → 停止迭代，使用上一轮最佳版本

各图类型生成模板

Template A: Kaplan-Meier 生存曲线

from lifelines import KaplanMeierFitter
from lifelines.statistics import logrank_test

def plot_km(df, time_col, event_col, group_col, groups, labels,
            title='', xlabel='Time (days)', ylabel='Event-free survival'):
    fig, ax = plt.subplots(figsize=(7, 5))
    kmf = KaplanMeierFitter()

    for grp, label, color in zip(groups, labels, COLORS['groups']):
        mask = df[group_col] == grp
        kmf.fit(df.loc[mask, time_col], df.loc[mask, event_col], label=label)
        kmf.plot_survival_function(ax=ax, ci_show=True, color=color, linewidth=1.5)

    # Log-rank test
    # ... (计算并标注 p 值)

    # Number at risk 表格
    # ... (在图下方添加)

    ax.set_xlabel(xlabel)
    ax.set_ylabel(ylabel)
    ax.set_ylim(0, 1.05)
    ax.legend(loc='lower left', frameon=True, edgecolor='#CCCCCC')
    ax.spines['top'].set_visible(False)
    ax.spines['right'].set_visible(False)

    return fig

# 必须附带验证:
# - 每组 N 和 Events 数
# - Log-rank p 值
# - 中位生存时间（如适用）

KM 特殊检查项：

• Number at risk 表格（每个时间点各组剩余人数）
• 95% CI 阴影或虚线
• Log-rank p 值标注
• Y 轴从 0 或从合理起点开始
• 组标签与稿件一致
• 删失标记（tick marks）

Template B: Cox Forest Plot

def plot_forest(results, models, ref_label='Reference'):
    """
    results: list of dict with keys:
        model, variable, hr, ci_lower, ci_upper, p, events, total
    """
    fig, ax = plt.subplots(figsize=(8, 6))

    # HR=1 参考线
    ax.axvline(x=1, color='#999999', linestyle='--', linewidth=0.8, zorder=0)

    # 绘制每个变量的 HR 和 CI
    for i, r in enumerate(results):
        y = len(results) - i - 1
        ax.plot([r['ci_lower'], r['ci_upper']], [y, y],
                color=COLORS['primary'], linewidth=1.5, zorder=2)
        ax.plot(r['hr'], y, 'o', color=COLORS['primary'],
                markersize=6, zorder=3)

    # 右侧数值标注
    # ... HR (95% CI) 和 p 值

    ax.set_xscale('log')
    ax.spines['top'].set_visible(False)
    ax.spines['right'].set_visible(False)

    return fig

# 必须附带验证:
# - 每个 HR, CI, p 值与分析报告一致
# - Events/Total 正确
# - 参考组标注

Forest plot 特殊检查项：

• 参考组标注（HR=1 线）
• HR, 95%CI, p 值数值列
• Events/Total 列
• Model 编号清晰
• 对数刻度 (log scale)
• CI 不超出图边界（必要时截断并标注）

Template C: 热图

import seaborn as sns

def plot_heatmap(data, row_labels, col_labels, title='',
                 cmap='RdBu_r', center=0, vmin=None, vmax=None):
    fig, ax = plt.subplots(figsize=(8, 6))
    sns.heatmap(data, ax=ax, cmap=cmap, center=center,
                xticklabels=col_labels, yticklabels=row_labels,
                linewidths=0.5, linecolor='white',
                cbar_kws={'label': 'Z-score', 'shrink': 0.8},
                annot=True, fmt='.1f', annot_kws={'size': 7})
    ax.set_title(title, fontsize=10, fontweight='bold', pad=10)
    plt.xticks(rotation=45, ha='right')
    plt.yticks(rotation=0)

    return fig

# 必须附带验证:
# - 标准化方法正确（z-score / min-max / raw）
# - 每个 cell 数值与分析结果一致
# - 行列标签与变量名对应

热图特殊检查项：

• 标准化方法说明（z-score / min-max / raw）
• Colorbar 有标签和单位
• 行列标签完整可读
• 聚类树状图（如使用，需说明距离度量和连接方法）
• 缺失值处理说明

Template D: Table 1 (基线特征表)

非图像但同样适用五层框架。

Table 1 特殊检查项：

• 连续变量: 正态→Mean±SD / 偏态→Median(IQR)（需正态性检验决定）
• 分类变量: n (%)
• 组间比较: ANOVA/Kruskal-Wallis + Chi-square
• 多重比较校正: Benjamini-Hochberg FDR 或 Bonferroni
• 每个变量的 N（如有缺失需标注）
• 数字精度: 连续变量1位小数，p值3位小数，百分比1位小数

完整工作流

Step 1: 接收任务
  ├─ 识别图表类型
  ├─ 确认目标期刊
  └─ 加载 Layer 1 规范

Step 1.5: 风格指南加载（可选）
  ├─ 根据目标期刊加载 references/medical_plot_style_guide.md
  ├─ 提取色彩/轴线/网格/图例等美学配置
  └─ 优先级: 期刊硬性要求 > 风格指南 > 默认值

Step 2: 数据准备 (Layer 2)
  ├─ 加载原始数据
  ├─ 按分析逻辑计算所有待展示数字
  ├─ 检查边界条件
  └─ 生成 figure_numbers 字典

Step 3: 绘图 (Layer 3)
  ├─ 选择对应 Template
  ├─ 应用风格指南配置覆盖默认参数
  ├─ 三格式输出 (PNG+PDF+TIFF)
  └─ 消除空白

Step 4: 对账 (Layer 4)
  ├─ 构建 checks 列表
  ├─ 运行 verify_figure()
  └─ 全部 ✅ 才继续，否则回到 Step 2/3

Step 5: Critic 迭代 (Layer 6) ← 最多 3 轮
  ├─ 5a. 坐标分析（程序化预检）
  │   ├─ fig.canvas.draw() + get_window_extent() 获取所有文字 bbox
  │   ├─ 检查相邻标签 gap ratio ≥ 0.8×
  │   └─ 检查 annotation 与 tick label / CI line 碰撞
  ├─ 5b. Gemini 视觉审查（多模态 AI）
  │   ├─ AiCodeWith API → gemini-3-pro-image-preview
  │   ├─ 发送 PNG base64 (inline_data) + 结构化 prompt
  │   ├─ 4 项 YES/NO: 标签重叠/注释遮挡/字号可读/整体专业
  │   └─ Auth: Bearer $AICODEWITH_API_KEY
  ├─ 5c. 6 维度评估（人工/AI 综合）
  │   C1 数据保真度 / C2 文本质量 / C3 布局遮挡
  │   C4 图例管理 / C5 风格一致性 / C6 整体专业度
  ├─ 全部 ✅ → "No changes needed." → 跳出
  ├─ 有 ❌ → 修改代码 → 重新生成 → Layer 4 重新验证
  └─ 3 轮用尽 → 使用当前最佳版本

Step 6: 图文同步 (Layer 5)
  ├─ 扫描稿件中引用该图的位置
  ├─ 修正不一致的数字和措辞
  └─ 确认 Figure legend

Step 7: 完成
  └─ 输出确认信息 + 验证摘要

行动追踪

每次出图完成后，必须调用行动追踪系统记录结果：

TRACK="/Users/terry/ai-research-army/systems/action-tracker/track"

# Layer 4 对账通过 → 记录成功
$TRACK ok! $PROJECT_ID figure_generate "生成KM曲线：3组对比+Number at risk" --skill academic-figure-engine

# Layer 4 对账失败 → 记录失败（不要等修复后再记，先记失败）
$TRACK fail! $PROJECT_ID figure_generate "热图colorbar无标签，注释溢出" --skill academic-figure-engine \
  --pattern FP-6 --cause "未检查annot与colorbar重叠" --lesson "热图出图后必须视觉确认标注区域"

# 修复后重新通过 → 记录新的成功
$TRACK ok! $PROJECT_ID figure_generate "热图修复版：缩小annot字号+调整colorbar位置" --skill academic-figure-engine

追踪时机：在 Step 4（对账）或 Step 5（Critic 迭代）完成后立即记录。

与其他 Skill 的协作

• 上游: statistical-analysis 提供分析结果 → 本Skill 可视化
• 上游: flow-diagram-generator 专门处理 STROBE/CONSORT（本Skill 处理其他所有类型）
• 下游: 生成的图 → manuscript-drafter 引用
• 验证: manuscript-reviewer 可调用本Skill 重新生成有问题的图
• 协作: journal-benchmarker 提供参考图示例 → 本Skill 匹配风格

经验教训库

P-A 论文 STROBE 流程图 (2026-02-26)

更新日志

• v1.3 (2026-03-11): Gemini 视觉审查切换至 AiCodeWith
  • API: api.with7.cn → gemini-3-pro-image-preview，Gemini 原生格式
  • Auth: AICODEWITH_API_KEY（~/.openclaw/credentials/.env）
  • 替换原 OpenRouter gemini-2.5-pro-preview（OpenAI 兼容格式）
• v1.2 (2026-03-09): Gemini 视觉审查集成
  • Critic 迭代新增双通道审查：坐标分析（程序化）+ Gemini 多模态（视觉）
  • 新增 gemini_visual_review() 代码模板
  • 来源：EG_Behavior Fig.1 重叠修复实战（坐标分析+Gemini 双重验证）
• v1.1 (2026-03-03): PaperBanana 集成
  • 新增 Step 1.5 风格指南加载（医学期刊统计图/框架图风格指南）
  • Layer 3 增加风格感知配置段落（风格指南 → matplotlib 参数覆盖）
  • Layer 6 重构：原布局预检 → Critic 迭代循环（6 维度评估，最多 3 轮）
  • 新增参考文件：medical_plot_style_guide.md、medical_diagram_style_guide.md、critic_evaluation_criteria.md
  • 来源：Google PaperBanana (2026) CriticAgent + StylistAgent 机制适配
• v1.0 (2026-02-26): 初始版本
  • 五层质量框架从 STROBE 流程图实战中提炼
  • 覆盖 KM/Forest/热图/雷达图/箱线图/Table 1 等类型
  • 通用技术配置(字体/色彩/保存函数)
  • 经验教训库