survey-generator

Survey Generator

与提供方无关的文献综述产物生成器。输出会写入专业工作流 wiki，而非独立的 HTML 文件——可跨会话保留，并建立索引以供 FTS5 检索。

与 dair-academy 版本的差异

dair	pro-workflow
在 Fireworks 上硬编码使用 Kimi K2.6	与提供方无关（Anthropic/OpenAI/OpenRouter/Fireworks/自定义）
输出 = 带内联 SVG 的单文件 HTML	输出 = wiki Markdown 页面 + sources.md 中的参考文献条目
一次性产物，无后续操作	保存在 FTS5 索引中；由 wiki-research-loop 重复使用
仅支持手动运行	可与 /wiki research 组合使用以自动扩展参考文献

适用场景

• “关于 的综述” /“关于 的文献综述”
• 入门新领域——生成领域全景图
• wiki 已有 10-30 个来源后，编写综合概述页面
• /wiki research 运行前的准备步骤：为循环提供高质量的种子资料包

输入

输入	必需	说明
topic	是	“推理模型”、“Agent 式工程”
source_url	是	公开的参考来源：arXiv 综述、GitHub awesome 列表、权威博客文章
--wiki <slug>	是	产物的目标 wiki
--bibliography-size N	否	默认 20。40-50 条为全面综述，80-100 条为详尽综述
--section-count N	否	默认 6-10 个编号章节
--provider name	否	覆盖提供方（默认：第一个显式配置的提供方）
--model id	否	覆盖模型

工作流（Agent 按顺序执行以下步骤）

第 1 步 — 阅读参考来源

使用 WebFetch source_url。提取子主题和引用论文。对于 GitHub awesome 列表，遍历 README 和链接的论文文件。对于 arXiv 综述 PDF，使用摘要和目录。

第 2 步 — 构建 research_bundle.json

使用 templates/research_bundle.template.json 作为框架。必需的键：

{
  "topic": "...",
  "anchor_source": "...",
  "abstract_hints": ["..."],
  "taxonomy": [{"branch": "...", "children": [{"name": "...", "description": "..."}]}],
  "sections": [{"title": "...", "guidance": "...", "papers": ["key1","key2"]}],
  "bibliography": [{"key": "author-year-shortname", "authors": "...", "year": 2024, "title": "...", "venue": "...", "summary": "..."}]
}

硬性规则：

• bibliography 中的每篇论文都必须真实存在。不得编造条目。
• sections[].papers 中引用的每个 key 都必须存在于 bibliography 中。
• 包含 4-8 个分类分支，每个分支包含 2-4 个子项。
• 包含 6-10 个编号章节，涵盖：引言 → 基础 → 方法 → 评估 → 未解决问题。

第 3 步 — 运行生成器

在插件会话中，调用 providers MCP 服务的 run_provider_task 工具，参数为 task: "survey" 和 args: ["--bundle", "/absolute/path/research_bundle.json", "--wiki", "<slug>", "--provider", "openai"]。密钥来自插件配置对话框。切勿在聊天中索要密钥或检索现有的机器凭据。

以下直接命令用于通过显式设置 PRO_WORKFLOW_*_API_KEY 变量来独立使用 CLI。参见提供方配置。

node $SKILL_ROOT/scripts/build-survey.js \
  --bundle <path-to-research_bundle.json> \
  --wiki <slug> \
  [--provider anthropic|openai|openrouter|fireworks|custom] \
  [--model <id>]

生成器：

1. 读取资料包。
2. 将其发送给大模型，并遵循严格的 Markdown 规范（编号章节、内联 [^paper-key] 引用、不使用 HTML）。
3. 将输出写入 <wiki>/derived/surveys/<topic-slug>.md。
4. 将参考文献条目追加到 <wiki>/sources.md（按键去重）。
5. 调用 wiki-cli.js page，将内容写入 FTS5 索引。

第 4 步 — 迭代

如果正文内容单薄：收紧 sections[].guidance 的要求并重新运行。输出文件名会自动添加版本号（<slug>-v2.md、<slug>-v3.md）。

比较不同提供方：

node build-survey.js --bundle bundle.json --wiki agent-memory --provider openai --model gpt-4o
node build-survey.js --bundle bundle.json --wiki agent-memory --provider anthropic --model claude-opus-5-5

每个提供方都会写入单独的带版本号文件；对这些文件进行差异比较。

输出结构

<wiki-root>/
├── sources.md                                 # bibliography rows appended (deduped)
└── derived/surveys/
    └── <topic-slug>-v1.md                     # the survey
        # title (h1)
        # ## 1. Introduction
        # ## 2. Foundations
        # ...
        # ## References
        # [^src-bib-<slug>] author year. title. venue.

硬性规则

1. 切勿编造参考文献条目——每篇论文都必须是带有发表出处的真实作品。
2. 每个章节的 papers 数组都必须引用 bibliography 中的键。
3. 输出只能是 Markdown。不得包含 HTML、内联 SVG 或 JS。
4. sources.md 中的参考文献条目使用 slug 风格的 ID src-bib-<slug>（由参考文献的 key 派生）；引用格式为 [^src-bib-<slug>]。手动添加的非参考文献来源继续使用 src-NNN。
5. 迭代输入（research_bundle.json），而非生成的输出。
6. 提供方和模型由用户选择——切勿硬编码。

与 research loop 组合使用

/wiki init reasoning-models --title "Reasoning Models" --flavor research
# Manually compile a research_bundle.json
node skills/survey-generator/scripts/build-survey.js --bundle bundle.json --wiki reasoning-models
# Now the wiki has a structured survey + 50 bibliography rows
# Enable auto-research to expand:
# (edit reasoning-models/wiki.config.md, set auto_research.enabled: true)
node skills/wiki-research-loop/scripts/research-loop.js seed reasoning-models "chain-of-thought failure modes" --depth 0
node skills/wiki-research-loop/scripts/research-loop.js run reasoning-models