paper-survey-builder

name	paper-survey-builder
description	围绕某个研究主题搭建可长期维护的 Obsidian 调研工作区。适用于主题仍然模糊、需要先重构研究问题与关键词，再由 Codex/subagent 扩论文池、归纳主脉络、生成逐文精读、补方法图与可比组说明，最后由脚本装配 preview 并做 Obsidian 校验。

Paper Survey Builder

概览

• 这是一个 agent-first skill：先由 Codex 明确范围、拆任务、并行组织 subagent，再让脚本处理结构化落盘、图候选提取、preview 装配与校验。
• 目标不是“尽快吐出一篇固定格式报告”，而是沉淀一套可回溯、可复查、可长期维护的调研工作区。
• 默认把 index-style 当作深度调研主模式；master-style 保留为轻量长期维护视图。

角色分工

Codex / Subagent 负责

• 模糊需求重构为明确调研问题
• 关键词簇、排除项、时间范围、venue 范围、近邻方向拆分
• 扩论文池、核 venue/year/repo/OpenReview/arXiv
• 流派/主脉络归纳与边界说明
• 单篇 note 的非结构化理解与写作
• benchmark 可比性判断、不可横比说明
• 方法图语义核对与 Mermaid 兜底图生成

脚本负责

• 初始化 staging 工作区与 schema
• seed/PDF 规范化为 candidate_inventory.csv
• 外部调研结果合并回 staging
• 提取图候选并生成 figure_manifest.csv
• 装配 preview、复制图文件、维护相对路径
• Obsidian lint、图文一致性基础检查、dry-run publish

推荐流程

1. scope Codex 根据用户原始需求生成 scope_brief、query_map、范围边界与排除项。
2. discover paper-scout 等 subagent 并行扩论文池、核基础事实，并把结果沉淀到 sources/。
3. inventory 脚本把 seed/PDF/外部结果规范化成 candidate_inventory.csv；经人工或 subagent 核验后，回写 validated_inventory.csv。
4. lineage lineage-architect 生成 lineage_map.json 与 paper_assignments.csv。
5. paper-briefs paper-summarizer 为每篇论文输出语义 brief，放到 drafts/paper_briefs/。
6. benchmarks benchmark-normalizer 补 benchmark_records.csv 与不可横比说明。
7. figures 脚本先提图，figure-verifier 再做语义核对；若没有可信方法图，再生成 Mermaid fallback。
8. assemble 脚本读取结构化表、paper brief、report blocks、figure manifest，生成 preview/。
9. validate / publish 校验链接、embed、图路径、证据锚点与图文一致性；默认先 dry-run，再决定是否发布。

默认入口

新的薄工具层 CLI 只暴露结构化动作：

python scripts/survey_pipeline.py init-workspace --topic "主题名" --vault "Obsidian Vault" --target-dir "主题目录" --mode index
python scripts/survey_pipeline.py build-candidate-inventory --staging-root "<staging_root>" --seed-file "papers.csv"
python scripts/survey_pipeline.py merge-research-results --staging-root "<staging_root>" --validated-inventory "validated_inventory.csv" --paper-briefs-dir "paper_briefs"
python scripts/survey_pipeline.py extract-figure-candidates --staging-root "<staging_root>"
python scripts/survey_pipeline.py render-preview --staging-root "<staging_root>" --mode index
python scripts/survey_pipeline.py validate-preview --staging-root "<staging_root>"
python scripts/survey_pipeline.py publish-preview --staging-root "<staging_root>" --target-dir "主题目录" --apply

结构化产物

• scope/
  • scope_brief.md
  • scope_brief.json
  • query_map.json
• data/
  • candidate_inventory.csv
  • validated_inventory.csv
  • lineage_map.json
  • paper_assignments.csv
  • benchmark_records.csv
  • figure_manifest.csv
• drafts/paper_briefs/ 每篇论文一个语义 brief，至少包含：
  • scientific_problem_1_7
  • task_dataset_summary
  • baseline_summary
  • result_summary
  • remarks
  • uncertainty_notes
  • evidence_anchors
  • 可选 figure_mermaid
• drafts/report_blocks/ 用于主文档总述、脉络说明、总观察、前沿扩展和附录说明。
• logs/ 保留 validate / publish 报告，并单独记录 lineage_review.md、figure_review.md。

方法论约束

• 没有 scope_brief，就不要开始大量搜文献。
• 没有 validated_inventory.csv，就不要写正式主索引和结论。
• 没有 paper_brief 与 evidence_anchors，就不要让脚本代写逐文精读内容。
• 不能横向比较时，必须显式写出 不可直接横比 或等价说明。
• 方法图优先级固定为 arxiv-source > pdf-figure > pdf-extraction > page-crop > mermaid-fallback。
• Mermaid 只作为方法图兜底，不替代真实可信的原始图。
• staging 是工作区，不要直接在正式 vault 里边搜边改。

能力复用

• 文献发现优先参考 research-lookup，结果保存回 sources/
• 方法图提取优先复用 extract-paper-images
• 本地复用与去重遵循 paper-search 风格
• Mermaid fallback 建议参考 markdown-mermaid-writing
• 图像路径修复与语义核对可借鉴 obsidian-paper-figure-repair
• 统计图仍优先 seaborn，需要细控制时再用 matplotlib

并行与人工关卡

• scope 完成前不并行拆任务。
• discover、paper-briefs、benchmark normalization、figure verification 可以并行。
• lineage 定稿、最终结论收口、assemble、publish 必须串行。
• 同一篇论文的 paper-summarizer 与 figure-verifier 可以并行，但最终 note 合并必须串行。
• 即使强自动化，也保留两个必须的人审门：
  • 主脉络与口径锁定后，再大批量补条目。
  • validate 通过并人工看过报告后，再 publish --apply。

资源索引

• references/workflow-overview.md：agent-first 总流程、阶段门禁、失败回退
• references/report-modes.md：index-style 与 master-style 的职责边界
• references/evidence-policy.md：证据锚点、不确定性、外部采证与保存规则
• references/figure-policy.md：图源优先级、图文一致性、Mermaid fallback
• references/obsidian-style.md：表格、链接、embed、assets 命名约束
• references/visualization-recipes.md：结构化图表 helper 的使用方式
• references/subagent-playbook.md：subagent 工种契约、输入输出与并行边界
• references/quality-gates.md：交付前检查清单
• assets/templates/：index-style 与 master-style 模板
• assets/schemas/：workspace 关键文件的 schema 样例
• scripts/survey_pipeline.py：薄工具层主入口

输出要求

• 默认中文叙述，保留英文论文标题、venue、指标原文。
• 逐文精读的结构化字段由脚本装配，非结构化判断必须来自 Codex/subagent。
• 若证据不足，就明确写 待补 与缺口类型，不要用脚本或模板伪造结论。