Publication Chart 技能

目标

使用该技能将研究成果转化为符合出版标准的图表与表格。

主要生产工具栈：

• pubfig>=0.3.0 JSON CLI — 用于生成图表
• pubtab — 用于生成出版级表格

默认交付流程：

1. 明确科学传播目标，
2. 确定交付物类型：图表 / 表格 / 图表+表格混合形式，
3. 选择最具表现力的可视化形式，
4. 路由至 pubfig、pubtab 或两者协同，
5. 生成可执行的完整流程，
6. 导出可直接用于论文的资产，
7. 执行出版质量审查（publication QA），
8. 在必要时提出修订建议。

适用场景

当收到以下请求时，触发本技能：

• “生成一张出版质量的图表”
• “为这些结果选择最合适的图表类型”
• “将这些结果转化为论文就绪的图表”
• “生成 benchmark / ablation / calibration / forest / heatmap / scatter / line / bar 类型的图表”
• “从 Excel 文件生成 benchmark / appendix / ablation 表格”
• “将该 Excel 表格转换为出版就绪的 LaTeX 格式”
• “为结果章节准备一张摘要图加一张配套表格”
• “审查并优化这张科学图表/表格”
• “我已有初稿图表 / 截图 / 草图 —— 请将其提升至出版就绪水平”
• “导出论文图表所需的各子图面板（panels）”

不适用场景

当任务主要属于以下类型时，请勿使用本技能：

• 论文正文撰写（manuscript prose writing），
• 无产出设计需求的统计检验（statistical testing without artifact design），
• 无明确出版交付目标的原始探索性分析（raw exploratory analysis with no publication deliverable），
• 在图表或表格内容尚未稳定前，以 Figma 为起点的排版工作（Figma-first layout work before the figure or table content is solid）。

复合组装（Composite assembly）属于次要分支。默认情况下，不应将普通图表任务升级为 panel/Figma 工作流。

核心契约

输入

预期接收以下部分或全部信息：

• 科学传播目标，
• 可用数据的结构（data shape），
• 投稿期刊或格式规范（venue or style constraints），
• 产出物类型：图表、表格或混合交付形式，
• 可选辅助资产：代码、电子表格、.tex 文件、截图或草图，
• 任务性质：初稿生成、出版就绪导出，或审查/修订。

最小有效输出

高质量响应应至少包含以下内容：

• 推荐的产出物形式（artifact form），
• 推荐的 pubfig CLI / pubtab 执行路径，
• 最小可运行的 JSON 规范、CLI 命令或代码片段，
• 明确的输出文件名及格式，
• 出版质量审查（publication QA）摘要，
• 若当前产出物质量不足，则提供具体修订计划。

默认工作流

0. 探查环境与任务状态

在生成任何内容前，需首先确认：

• pubfig>=0.3.0 或 pubtab 是否已安装并可用，
• 用户是否已拥有代码、电子表格、.tex 文件、截图或草图，
• 交付物属于首次生成还是修订，
• 结果是否需支持视觉模式识别（pattern perception）、精确数值查询（exact value lookup），或二者兼顾。

此步骤应尽量轻量。当可执行性至关重要时，优先使用封装好的辅助脚本。

若缺失必需依赖，请先在当前环境中安装。标准 pip 安装命令如下：

• python -m pip install --upgrade "pubfig>=0.3.0"
• python -m pip install --upgrade pubtab

当封装辅助脚本可用时，仍应作为首选路径：

• python3 scripts/ensure_publication_tooling.py --require pubfig --json
• python3 scripts/ensure_publication_tooling.py --require pubtab --json

安装完成后：

• 重新检查工具可用性，
• 若安装成功，则继续执行可运行工作流，
• 否则降级为设计方案/规格说明（design/specification answer），而非直接失败。

关于 uv 管理及其他回退方案，请参阅 references/execution-and-verification.md。

1. 任务分类

沿以下维度对任务进行分类：

• 产出物类型（artifact type） — 图表 / 表格 / 混合交付形式
• 成熟度（maturity） — 探索性草稿 / 出版就绪生成 / 修订
• 结构（structure） — 单面板 / 多面板 / 图表+表格组合包
• 证据模式（evidence mode） — 模式感知 / 精确值查询 / 二者兼具

在传播目标未明确前，切勿急于绘图。

2. 选择表达形式

应基于科学主张（scientific claim）选择表达形式，而非视觉新奇性。

常用图表族（families）包括：

• 对比（comparison） — 分组散点图、柱状图、折线对比图、benchmark 汇总图、配套表格
• 消融（ablation） — 分组对比、哑铃图（dumbbell）、配对比较、紧凑表格
• 分布（distribution） — 箱线图（box）、小提琴图（violin）、雨云图（raincloud）、直方图（histogram）、密度图（density）、经验累积分布函数（ECDF）、QQ 图
• 关系（relationship） — 散点图（scatter）、气泡图（bubble）、二维等高线图（contour2d）、六边形图（hexbin）
• 趋势（trend） — 折线图（line）、面积图（area）
• 评估/诊断（evaluation / diagnostic） — 校准图（calibration）、ROC 曲线、PR 曲线、Bland–Altman 图、森林图（forest plot）、火山图（volcano）
• 构成/层级（composition / hierarchy） — UpSet 图、堆叠比例图（stacked ratio）、环形图（donut）、径向层级图（radial hierarchy）、环形分组/堆叠柱状图（circular grouped or stacked bars）
• 表格（table） — benchmark 表格、ablation 表格、数据集摘要、附录表格、误差分解表

避免弱默认选项：

• 当柱状图或表格更能清晰传达精确对比时，避免使用饼图（pie）/环形图（donut），
• 除非主张本身确实是低基数（low-cardinality）且具轮廓特征（profile-like），否则避免使用雷达图（radar），
• 避免使用三维图、装饰性渐变、纯样式复杂度（style-only complexity），
• 当结果高度依赖精确数值时，若表格更具优势，则不应强行塞入图表中。

详细的任务到图表映射规则，请参阅 references/chart-selection.md。

3. 映射至工具链

默认映射关系：

• 图表 → 默认使用 pubfig>=0.3.0 JSON CLI
• 表格 → 使用 pubtab
• 混合交付物 → 同时使用两者，并赋予各自明确的传播角色

路由规则：

• 对于 Agent 生成的图表，优先使用 pubfig JSON CLI，
• 仅当用户明确处于 notebook/script 环境中，或需实现 pubfig 当前不支持的自定义逻辑时，才使用其 Python API，
• 对于以文件驱动的表格工作流，优先使用 pubtab CLI，
• 在混合请求中，保持图表与表格职责分离，
• 将面板导出（panel export）/复合组装（composite assembly）视为可选的下游工作。

关于精确路由选择与验证行为，请参阅：

• references/workflow.md
• references/execution-and-verification.md
• references/pubfig-recipes.md
• references/pubtab-recipes.md

4. 生成最小可运行产出物

优先采用最小但生产就绪的执行路径：

• 图表：一个 figure.spec.json 文件，配合 pubfig validate-spec 和 pubfig render 命令，
• 表格：一条 pubtab 路径，可生成预览用的 .tex 文件或渲染后预览，
• 混合请求：一条图表路径 + 一条表格路径，二者须清晰区分。

确保文件名和导出格式显式声明。

针对图表特有的导出模式（如 save_figure、batch_export、export_panels），请参考 references/pubfig-recipes.md。

5. 定义交付契约

每次响应中，尽可能明确以下内容：

• 该产出物所支撑的科学主张（scientific claim），
• 所选产出物类型及其依据，
• 哪些部分由 pubfig 处理、哪些由 pubtab 处理，
• 输出文件名与格式，
• 该产出物属于草稿 / 终稿 / 修订版本，
• 尚需用户提供的数据或稿件上下文。

6. 执行出版质量审查（Publication QA）

生成后需检查以下方面：

• 标题与图例的信息密度（title and legend density），
• 坐标轴标签与单位（axis labels and units），
• 类别排序与基线清晰度（category ordering and baseline clarity），
• 颜色可访问性与灰度鲁棒性（color accessibility and grayscale robustness），
• 字体与线宽一致性（font and line-weight consistency），
• 图注就绪程度（caption readiness），
• 缩放后可读性（readability after downscaling），
• 多面板导出时各面板间的一致性（panel consistency for multi-panel exports），
• 适配投稿期刊的问题：如宽度、拥挤、过度标注（venue-fit issues such as width, crowding, or over-annotation）。

QA 输出必须具体：明确指出实际问题及对应修复方式。

更完整的检查清单，请参阅 references/publication-qa-checklist.md。

7. 当产出物质量不足时进行修订

典型修订操作包括：

• 切换图表族（chart family），
• 移除图表垃圾（chartjunk），
• 重排类别顺序，
• 将精确数值移入表格，
• 拆分过于拥挤的面板，
• 简化或强化图注（caption），
• 调整导出宽度，
• 将交付物由“图表优先”转为“表格优先”。

缺失依赖项的行为策略

若 pubfig>=0.3.0 或 pubtab 不可用：

• 不可立即失败，
• 优先尝试封装的安装/探查路径，
• 清晰报告依赖项状态，
• 安装成功后继续执行可运行工作流，
• 否则提供含伪代码或草拟命令的设计/规格说明，
• 仍需保留产出物选型、QA 及修订指导。

所有具体的探查/安装命令均位于 references/execution-and-verification.md。

输出风格规范

• 优先输出直接可用、面向实现的成果。
• 简要解释为何该图表或表格形式合适，再给出执行路径。
• 当可执行性重要时，需附带简短的环境状态块（environment status block）。
• 明确指出表格强于图表的情形。
• 明确指出图表强于表格的情形。
• 当两者均需时，为其分配不同角色。
• 确保修订建议具备可操作性与可证伪性（actionable and falsifiable）。

推荐响应结构

高质量响应通常包含以下 6 个部分：

1. 产出物决策（Artifact decision） — 图表 / 表格 / 配套交付物，及其依据
2. 工具路径（Tool route） — pubfig>=0.3.0 JSON CLI、pubtab 或两者
3. 最小实现（Minimal implementation） — 可运行的 JSON 规范、CLI 命令或代码
4. 导出计划（Export plan） — 文件名、格式、宽度/后端/预览选项
5. 出版质量审查（Publication QA） — 论文投稿前需验证的内容
6. 修订计划（Revision plan） — 若当前产出物质量不足，应如何修改

参考资料

按需加载以下文档：

• references/workflow.md — 决策顺序、交付契约、图表/表格划分规则
• references/chart-selection.md — 任务到图表映射及反模式（anti-patterns）
• references/execution-and-verification.md — 环境探查、安装行为、可执行性验证
• scripts/ensure_publication_tooling.py — 封装的探查 + 自动安装辅助脚本（支持 pubfig>=0.3.0 / pubtab）
• references/pubfig-recipes.md — 面向 Agent 的 JSON CLI 图表规范与导出模式
• references/pubtab-recipes.md — 最简实用表格路径与后端指导
• references/source-guides/pubfig-architecture.md — 包结构与图表生成边界（源码视角）
• references/source-guides/pubfig-api-map.md — 稳定公开的 pubfig 接口表面与图表族映射（源自 __init__.py）
• references/source-guides/pubfig-export-flow.md — 图表导出、出版尺寸适配与面板导出流程（源码视角）
• references/source-guides/pubtab-architecture.md — 包结构与正向/逆向转换架构（源码视角）
• references/source-guides/pubtab-cli-api-flow.md — CLI 到 API 控制流及批量/表格行为（源码视角）
• references/source-guides/pubtab-backend-and-preview.md — 后端/主题划分与预览编译流水线（源码视角）
• references/publication-qa-checklist.md — 图表/表格 QA 检查清单
• references/composite-assembly.md — 可选的多面板与 Figma 分支

提示词格式示例请参见 examples/ 目录。