name: survey-generator
description: “Generate source-backed AI/ML survey paper artifacts with curated bibliographies and Fireworks/Kimi HTML rendering.”
allowed-tools: Read, Write, Bash, WebFetch, AskUserQuestion
category: “research”
risk: “safe”
source: “official”
source_repo: “dair-ai/dair-academy-plugins”
source_type: “official”
date_added: “2026-06-19”
author: “DAIR.AI”
license: “MIT”
license_source: “https://github.com/dair-ai/dair-academy-plugins/blob/main/README.md#license”
tags:
- dair-academy
- ai
- workflow
tools: - claude-code
- codex-cli
- cursor
Survey Generator 技能
何时使用
当此工作流与用户请求匹配时使用：为已文档化的工作流使用此技能。
来源：dair-ai/dair-academy-plugins（MIT）。
将学术风格的综述论文生成为单个自包含的 HTML 文件。
此技能做什么
给定一个主题和一个公开的锚点资源，此技能：
- 读取锚点资源并提取相关工作全景。
- 构建结构化的
research_bundle.json（标题、分类法、章节、真实论文的参考文献）。 - 通过 Fireworks chat completions API 调用 Kimi K2.6，传入研究包和固定的
style_spec.json。 - 写出单文件 HTML 产物，包含内联 SVG 图、学术布局、编号章节和参考文献列表。
使用此技能的代理只负责研究策展。所有散文、图表和 HTML 都由 Kimi K2.6 在一次 API 调用中生成。
用户输入
用户至少以以下内容调用此技能：
topic：一个简洁的综述主题，例如"Agentic Engineering"或"Reasoning Models"。source_url：一个公开的锚点资源。任何精选列表、权威博客文章、arXiv 综述、GitHub awesome 列表或索引页面都可以。建议的起点：DAIR.AI AI Papers of the Week（一个持续更新的知名 AI/ML 论文开源索引，非常适合宽泛主题）、GitHub awesome-* 仓库、arXiv 综述 PDF 或维护良好的论文页面。
可选：
bibliography_size：目标参考文献规模。快速综述默认 20。综合综述用 40 到 50，详尽综述用 80 到 100。章节长度和 token 预算随此缩放。section_count：章节数量，默认 6 到 10。
如果用户没有提供这些，在继续前使用 AskUserQuestion 收集。
要求
- 环境中导出
FIREWORKS_API_KEY。构建脚本从os.environ读取它。 - Python 3，仅标准库（urllib）。无外部依赖。
代理工作流
按顺序执行以下步骤。不要跳过步骤。
第 1 步：读取锚点资源
获取并读取source_url。如果是 GitHub 仓库，获取 README 以及任何相关的README-*.md或papers.md索引。如果是 arXiv 综述，使用摘要、图表和章节标题。如果是博客文章，完整阅读。提取关键子主题以及它按名称引用的论文或系统。
对于宽泛的 AI/ML 主题，DAIR.AI AI Papers of the Week 是一个特别丰富的锚点：它有持续多年的周报，每期包含 6 到 10 篇知名论文的简短摘要，因此很容易跨时间浏览并过滤出与你的主题匹配的子集。
如果你的代理可以使用论文搜索工具（Papers-of-the-Week MCP、arXiv 搜索、Semantic Scholar、Google Scholar、组织内部索引等），请使用它把候选池扩展到锚点资源直接引用的范围之外。
第 2 步：定义分类法和章节
起草一棵以主题为根的分类法，包含 4 到 8 个分支，每个分支有 2 到 4 个子节点。分支应覆盖主题的不同子领域，不要重叠。起草 6 到 10 个编号章节，与分类法的递进保持一致：引言、基础、方法、评估、开放问题。图 1 的视口高度通过style_spec.json中的几何契约随叶子总数自动缩放，因此更深的分类法也能干净渲染。
第 3 步：策展参考文献
挑选与bibliography_size规模相符的真实论文。对于综合综述，40 到 50 条是最佳区间；此技能已在build_artifact.py中max_tokens=81920的条件下测试到 100 条。每条必须有：key、authors、year、title、venue和 1 到 2 句的summary。不要编造论文。每个章节的papers数组必须引用参考文献中存在的键。
第 4 步：编写research_bundle.json
在技能目录中（build_artifact.py旁边）写入research_bundle.json。使用templates/research_bundle_template.json作为结构骨架。必需的顶层字段：title、authors_placeholder、anchor_source、abstract_hints、taxonomy、paradigms、stack、sections、table、bibliography。查看examples/agentic-engineering/research_bundle.json获取完整的工作示例。
第 5 步：运行生成器
python3 build_artifact.py从技能目录运行此命令。脚本读取research_bundle.json和style_spec.json，调用 Fireworks 上的 Kimi K2.6，并写出output/survey_kimi-k2p6_v{N}.html。每次运行都会产生一个新的带版本号的文件。
要使用不同的 Fireworks 模型（例如 Kimi K2.5 做并排对比）：
FIREWORKS_MODEL=accounts/fireworks/models/kimi-k2p5 python3 build_artifact.py输出文件名按模型 slug 化，因此你可以跨模型比较版本。
第 6 步：预览与迭代
在本地打开 HTML 文件。它是一个完全自包含的 HTML 文档，因此你也可以从任何静态主机提供服务、嵌入面板，或交给你的代理暴露的任何产物预览机制。
如果图表看起来不够好，调整style_spec.json（required_figures和figure_quality_note键）并重新运行。如果散文单薄或章节缺失，收紧research_bundle.json中的章节guidance字段。不要直接编辑 Kimi 的输出；对输入进行迭代。
常见图表失败模式及修复它们的 style_spec 模式：
- 不同面板的节点折叠到同一面板：要求
<g transform="translate(OFFSET,0)">组使用面板局部坐标（图 2 强制）。 - 叶子矩形垂直重叠导致标签被裁剪：强制 rect_pitch 大于 rect_height，配合显式公式和健全性检查（图 1 强制）。
- 根标签溢出其胶囊：在规范中固定最小矩形宽度（图 1 强制，width=200）。
- 一行中的兄弟节点水平重叠（例如编排器-工作器面板中的 Worker A、Worker B、Worker C）：在固定宽度面板中为 N 个节点强制确定性的 rect_width 和 center_x 公式，相邻矩形之间留最小水平间隙（图 2 多节点行强制）。
- 面板内容漂移到左或右边缘而不是位于面板背景中间：将每个组的 translate 偏移固定为匹配面板背景的 x 位置（10、270、530），并将所有内容居中于面板局部 x=120（图 2 强制）。
- 因为模型偏好不同的叙述流程而导致图表以错误的数字顺序输出：要求标题按顺序使用 required_figures 中的确切 ID（图 1 在图 2 之前，图 2 在图 3 之前），即使这意味着在同一章节放置两个图（通过 hard_rules_for_generation 强制）。
- 堆栈图右侧标签在视口边缘被裁剪：将堆栈 SVG 视口加宽到 720，并要求角色文本 tspan 适配在 x=710 内（图 3 强制）。
添加新图或修改现有图时，遵循同样的模式：声明绝对视口、逐元素坐标或确定性公式，以及在描述末尾加上硬性不变量检查子句。
此技能中的文件
SKILL.md- 本文件。build_artifact.py- 调用 Fireworks 的 Python 脚本。style_spec.json- 视觉和结构规范（与主题无关）。templates/research_bundle_template.json- 新主题的空模板。examples/agentic-engineering/- 参考性 100 篇论文的运行（research_bundle.json + survey.html）。
代理必须遵守的硬性规则
- 绝不编造参考文献条目。每篇被引用的论文都必须是带有真实发表场所的真实工作。
- 每个章节的
papers数组必须引用参考文献中存在的键。 - 绝不编辑生成的 HTML。对
research_bundle.json或style_spec.json迭代并重新运行。 - 不要修改
style_spec.json.hard_rules_for_generation中的硬性规则。 - 保持 style_spec 与主题无关。主题特定内容只存在于
research_bundle.json中。 - 不要在 research bundle 的散文字段中使用破折号或箭头符号。
局限性
- 当工作流指明需要上游工具、账户、API 密钥或本地设置时，需要具备这些。
- 未经用户明确批准，不授权破坏性、生产、付费或外部消息操作。
- 在将生成的产物或建议视为最终结果之前，对照用户的真实来源进行验证。
