Paper Survey Builder

Description

--- 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 只暴露结构化动作： ```powershell 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。 - 若证据不足，就明确写 `待补` 与缺口类型，不要用脚本或模板伪造结论。

Security Status