用途
Survey Visuals 用于综述（survey）写作流程中的可视化准备阶段。它的目标是在正式写作之前，先把时间线和图规格落盘，使后续写作阶段减少模板化。该技能明确不产出散文（NO PROSE），只生成非散文类可视化产物。
主要能力
- 生成时间线：以年份加关键里程碑的形式，写入 outline/timeline.md。
- 生成图规格：写入 outline/figures.md，描述图表目的、所需元素（框、箭头、坐标轴等）以及每个元素由哪些论文支撑。
- 使用引用键：所有引用仅使用 citations/ref.bib 中存在的引用键。
- 机器可读资产：assets/figure_templates.yaml 提供图原型规格，可在不修改代码的情况下扩展。
使用方式
触发词包括：survey visuals、timeline、figures、visuals、图表、时间线、figure spec。
适用时机：综述的 C4 阶段（NO PROSE），已有 outline + claim/evidence + citations，需要先落盘时间线或图规格。
输入：
- outline/outline.yml
- outline/claim_evidence_matrix.md
- papers/paper_notes.jsonl
- citations/ref.bib
输出：
- outline/timeline.md
- outline/figures.md
工作流（启发式）：
- 读取大纲与论点-证据矩阵，选取反复出现的比较轴。
- 时间线：写入年份到关键里程碑的条目，追求广度与引用覆盖。
- 图规格：写入 2-4 个可供人工绘制的图规格，每个包含目的、所需元素、支撑论文的引用键。
辅助脚本（可选）：
- 快速开始： uv run python .codex/skills/survey-visuals/scripts/run.py --help uv run python .codex/skills/survey-visuals/scripts/run.py --workspace <workspace>
- 全部选项： --workspace <workspace>（必填） --unit-id <id>（可选，仅用于 runner 记账） --inputs <a;b;c>（可选，默认使用上述四个输入） --outputs <timeline_rel;figures_rel>（可选，默认 outline/timeline.md;outline/figures.md） --checkpoint <C#>（可选，辅助脚本忽略）
- 示例： 使用默认值生成时间线与图规格： uv run python .codex/skills/survey-visuals/scripts/run.py --workspace <workspace> 生成到自定义输出路径： uv run python .codex/skills/survey-visuals/scripts/run.py --workspace <workspace> --outputs outline/timeline.md;outline/figures.md
脚本边界：
- run.py 仅用于：从 paper_notes + bibkeys 确定性组装时间线条目；从 outline + mapping 生成表格；使用 assets/figure_templates.yaml 生成图规格骨架。
- run.py 不用于：硬编码图描述或叙述；应从 references 中可检查的里程碑选择启发式。
表格由专门的表格技能处理：
- table-schema -> outline/table_schema.md
- table-filler -> outline/tables_index.md（内部索引）
- appendix-table-writer -> outline/tables_appendix.md（面向读者的附录表格）
加载顺序：
- 始终读取：references/overview.md、references/figure_archetypes.md
- 按任务读取：构建时间线里程碑时读取 references/timeline_patterns.md
- 机器可读资产：assets/figure_templates.yaml
适用场景
- 综述写作流程中需要先产出时间线和图规格的阶段。
- 已有大纲、论点-证据矩阵、论文笔记和引用库，需要将可视化内容结构化落盘。
- 希望避免写作阶段模板化，先以非散文形式明确图表要表达的内容和支撑文献。
限制
- 不产出散文，图规格应保持为绘制指令（目的 + 元素 + 各元素的引用键支撑），叙述性解释应放入正文。
- 引用仅限 citations/ref.bib 中存在的引用键。
- 辅助脚本故意保持最小化，不会覆盖非占位符产物。
- 严格模式下，仅当占位符标记仍存在（且未满足最低时间线/图要求）时才会阻止。
- 质量检查要求：输出中无 TODO 和 <!-- SCAFFOLD ... --> 标记；outline/timeline.md 至少 8 个年份条目，每条至少 1 个引用标记 [@...]；outline/figures.md 至少 2 个图规格，每个至少提及一个支撑引用。
- 若时间线单薄或无引用，应优先选择更少但信号更强的里程碑，并确保每条至少 1 个 [@...]；若笔记单薄，应加强 paper-notes / evidence-draft，而非填充。
- 若图规格读起来像散文，应保持为绘制指令，将叙述性解释移入正文。