survey-generator

Survey Generator

プロバイダーに依存しない文献サーベイの成果物ジェネレーターです。出力は単独の HTML ファイルではなく、プロワークフローの Wiki に反映されるため、セッションをまたいで保持され、FTS5 検索でインデックス化されます。

dair-academy 版との差分

dair	プロワークフロー
Fireworks 上の Kimi K2.6 に固定	プロバイダー非依存（Anthropic/OpenAI/OpenRouter/Fireworks/custom）
出力＝インライン SVG を含む単一ファイルの HTML	出力＝Wiki の Markdown ページ＋sources.md の書誌情報行
一度限りの成果物で、後続処理なし	FTS5 インデックスに保持され、wiki-research-loop で再利用
手動実行のみ	/wiki research と組み合わせて、書誌情報を自動で拡張可能

使用するタイミング

• 「 のサーベイ」／「 の文献レビュー」
• 新しい分野への導入時 — その分野の全体像を生成
• Wiki に 10～30 件のソースが集まった後、それらを統合したページを作成
• /wiki research の実行前のステップとして — ループに質の高いシードバンドルを渡す

入力

入力	必須	説明
topic	はい	「推論モデル」、「エージェント型エンジニアリング」
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	いいえ	モデルを上書き

ワークフロー（エージェントは以下の順序で実行します）

Step 1 — 参照元を読む

WebFetch source_url。サブトピックと引用論文を抽出します。GitHub の awesome リストの場合は、README とリンク先の論文ファイルをたどります。arXiv のサーベイ PDF の場合は、要旨と目次を使用します。

Step 2 — build 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 セクションにします。

Step 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 なし）を指定して LLM に送信します。
3. 出力を <wiki>/derived/surveys/<topic-slug>.md に書き込みます。
4. sources.md に書誌情報の行を追記します（キーで重複を除去）。
5. wiki-cli.js page を呼び出して FTS5 インデックスに登録します。

Step 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 の書誌情報行では、スラッグ形式の 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