survey-visuals

Survey Visuals（时间线 + 图示规格；无正文）

触发条件与路由

• 触发词：survey visuals、timeline、figures、visuals、图表、时间线、figure spec。
• 使用场景：survey 的 C4（无正文）；已有大纲 + 论点/证据 + 引用，需要先将时间线/图示规格写入文件。

此技能用于创建非正文类产物，让写作阶段不那么像套用模板：

• 时间线 / 演进要点
• 图示规格（绘制内容、意义以及支持它的论文）

加载顺序

始终阅读：

• references/overview.md
• references/figure_archetypes.md

按任务阅读：

• 构建时间线里程碑时，阅读 references/timeline_patterns.md

机器可读资源：

• assets/figure_templates.yaml — 图示原型规格（无需更改代码即可扩展）

脚本边界

仅将 scripts/run.py 用于：

• 根据 paper_notes + bibkeys 确定性地组装时间线要点
• 根据大纲 + 映射生成表格
• 使用 assets/figure_templates.yaml 生成图示规格框架

不要将 run.py 用作：

• 硬编码图示描述或叙述内容
• 处理本应能从参考资料中检查的里程碑选择启发式规则

表格由专门的表格技能处理：

• table-schema -> outline/table_schema.md
• table-filler -> outline/tables_index.md（内部索引）
• appendix-table-writer -> outline/tables_appendix.md（面向读者的附录表格）

输入

• outline/outline.yml
• outline/claim_evidence_matrix.md
• papers/paper_notes.jsonl
• citations/ref.bib

输出

• outline/timeline.md
• outline/figures.md

工作流输入（明确指定）

• 使用 outline/outline.yml + outline/claim_evidence_matrix.md 决定可视化内容。
• 使用 papers/paper_notes.jsonl 获取年份/里程碑候选项。
• 仅使用 citations/ref.bib 中的引用键。

工作流（启发式）

1. 阅读大纲 + 论点—证据矩阵，选出反复出现的比较维度。
2. 时间线（outline/timeline.md）：
   • 编写“年份 -> 关键里程碑”要点（力求覆盖面广并附上引用）。
3. 图示（outline/figures.md）：
   • 编写 2-4 个供人绘制的图示规格：
     • 目的（此图传达什么见解）
     • 必需元素（方框/箭头/坐标轴）
     • 支持各元素的论文（引用键）
4. 仅使用 citations/ref.bib 中存在的引用键。

质量检查清单

• 输出中不留有 TODO 或 `` 标记。
• outline/timeline.md 至少包含 8 条年份要点，且每条要点至少包含 1 个引用标记 [@...]。
• outline/figures.md 至少包含 2 个图示规格，且每个规格都提及至少 1 个支持性引用。

辅助脚本（可选）

快速开始

• 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>（可选；仅用于运行器记录）
• --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

说明

• 该辅助脚本刻意保持精简，且绝不会覆盖非占位产物。
• 在严格模式下，只有仍存在占位符标记时（以及未满足时间线/图示最低要求时），脚本才会阻止执行。

故障排查

问题：时间线内容单薄或没有引用

修复方法：

• 优先选取数量较少但信号更强的里程碑，同时确保每条要点都至少包含 1 个 [@...]。
• 如果笔记内容不足，应向上游反馈：完善 paper-notes / evidence-draft，而不是填充内容。

问题：图示规范读起来像散文

修复：

• 将规范保留为绘图说明：用途 + 元素 + 支持各元素的依据（引用键）。
• 将叙述性说明移至正文；此文件应保持非散文形式。