Paper Survey

paper-survey

> TRIGGER 关键词：「文献调研」「综述报告」「research survey」「literature review」「调研报告」「学术综述」 / 任何要求多论文系统化整理 + 正式 markdown 报告输出的场景。 > > SKIP（不要使用本 skill）：单篇论文阅读 / 简单论文检索（用 paper-search） / 不需要正式综述报告的快速摘要 / 仅需要论文清单 PDF 下载（用 paper-search）。

中文学术综述报告自动化 skill。9 个流程节点 / 6 个主阶段全自动流程，每主阶段 implementor + reviewer 双 subagent 质量门控（0b 综述选择由主 Claude 内联检查），跨 session 可恢复，集成 paper-search。

流程总览

启动检测 (-1) ─────────── spec.md 当前阶段字段权威 + 文件存在性辅助 + AskUserQuestion 确认
    ↓
头脑风暴 (0a) ─────────── 与用户对话对齐主题、范围、深度、模板分支、cwd 工作目录
    ↓
预调研 (0b) ───────────── 下载 1-3 篇主线综述 → 主 Claude 阅读 → pre_survey_notes.md
                          （无独立 reviewer，主 Claude 内联 regex 验引文）
    ↓
写 spec (0c) ──────────── spec_writer 生成 survey_spec.md + spec_reviewer 验证 + 用户最终确认
    ↓
检索下载 (1) ──────────── 按 spec 清单批量下载 PDF + 立即按 naming_convention 重命名
                          + 下载校验（size/标题/作者 fuzzy）+ 自动重试 ≤2
                          + paper_search_reviewer 验证元数据匹配
    ↓
并行解析 (2) ──────────── K 路 paper_extractor 并行（D 分组+β 时序）
                          → 全完后串行 K 路 extract_reviewer 验证
    ↓
报告骨架 (3) ──────────── outline_writer 写 outline.md（严格标题+fenced JSON block）
                          + outline_reviewer 抽样幻觉验证
    ↓
md 组装 (4) ───────────── python assets/assemble_md.py （源路径直调，不复制）
                          → outline.md 中间产物渲染为顶层 _综述报告.md
                          → 内置 dry-run：fenced JSON parse + LaTeX $/$$ 配对
    ↓
完成度核查 (5) ─────────── validation.py 跑 17 项（16 项机械 + 1 项消费 reviewer 报告反幻觉）
                          validation_reviewer 用 ~49 处 verify_quotes_batch 并行 ≈ 2 秒，输出 reviewer 报告
    ↓
交付（用户口头确认）

关键约束：

• 阶段间严格串行：禁止跨阶段提前执行（如还在阶段 2 不能开始 outline 起草）
• 阶段内 K 路 implementor 并行（阶段 2 D + β 派发，单路 ≤6 篇，总并发上限 5）
• 阶段内 reviewer 等本阶段 implementor 全完才开始

阶段 -1：启动检测

每次 skill 调用第一步执行。spec.md 当前阶段字段是权威状态源，文件存在性是辅助验证（不一致时 AskUserQuestion 升级用户）。

状态机表（覆盖 missing / empty / partial / inconsistent / corrupted）

| spec.md 状态 | 当前阶段字段 | 文件存在性 | 推断阶段 | |---|---|---|---| | 不存在 | — | 无任何子目录 | 0a 新开 | | 不存在 | — | _pre/ 已下载 | 0b 进行中（续上从 presurveyextractor） | | 不存在 | — | _work/pre_survey_notes.md 存在 | 0c 写 spec | | 存在 | 0c-completed | _pre/ 与 _work/extracts/ 空 / 顶层无 *.pdf | 阶段 1 | | 存在 | 1-completed | 顶层 *.pdf 非空，_work/extracts/ 空 | 阶段 2 | | 存在 | 2-completed | _work/extracts/ 全有，_work/outline.md 缺 | 阶段 3 | | 存在 | 3-completed | _work/outline.md 存在，_综述报告.md 缺 | 阶段 4 | | 存在 | 4-completed | _综述报告.md 存在，_reviews/validation_report.md 缺 | 阶段 5 | | 存在 | 5-completed | 全部存在 + 17/17 PASS | 完成 | | 存在 | 字段缺失 | — | 用文件存在性回退推断 | | 存在 | 字段与文件存在性矛盾 | — | AskUserQuestion 升级用户 | | 损坏（解析异常） | — | — | AskUserQuestion 升级用户 |

流程

1. 扫描 {cwd}/ 下子目录，识别 / 工作目录
2. 对每个工作目录按上表推断当前阶段
3. 调用 AskUserQuestion：「检测到现有任务：[A] {topic-A} 阶段 X / [B] {topic-B} 阶段 Y。请选续哪个 / 新开 / 重跑某主题」
4. 用户选「续上」 → 跳到对应阶段；选「新开」 → 进 0a；选「重跑」 → 删除该阶段产物后重跑

每阶段完成必做：主 Claude 完成某阶段后立即 Edit _work/survey_spec.md 的 ## 当前阶段 段为 {N}-completed，作为下次 session 的恢复锚点。

阶段 0a：头脑风暴

目标：与用户对话对齐：

• 主题词（中英文）
• 主题边界（明确"是什么不是什么"）
• 目标深度（学位综述 / 技术调研 / 文献快报）
• 目标论文数（≥5 篇）
• 报告字数目标（弹性，与论文数 N 挂钩；中文字符数；validation.py 按 spec.md 字段读取，缺省时按 N fallback 推算）：
• N ≤ 3 → 2000（mini test 场景）
• N ∈ [4, 7] → 3500（小规模）
• N ∈ [8, 15] → 5500（中等规模）
• N ≥ 16 → 7000（大规模）
• 模板分支（默认通用学术；non-technical 跳过第 4 章）
• 用户已知论文清单 / 主线综述（如有）
• 工作目录 slug

关键确认：必须复述工作目录绝对路径让用户确认，避免在代码仓库根目录误落 50 篇 PDF 污染 git。

阶段 0b：预调研

目标：下载 1-3 篇主线综述，主 Claude 阅读后形成 pre_survey_notes.md。

步骤：

1. 创建工作目录 {cwd}//（含子目录 _pre/ 与 _work/）
2. 检索综述（默认源不含 semantic）：

``bash paper-search search "{topic} survey OR review OR tutorial" -n 5 -s arxiv,crossref,openreview,doaj ``

1. 用户给的主线综述：除非明确说"只用这一篇"，否则继续 paper-search 自动补搜
2. 下载 1-3 篇到 _pre/，按 naming_convention 重命名
3. 派发 pre_survey_extractor subagent 产出 _work/pre_survey_notes.md
4. 主 Claude 内联 reviewer（不派 subagent）：regex 检查每条要点附引文 + verifyquotesbatch 抽样 3 条引文 + 子分类数 ∈ [3, 7]

AskUserQuestion 阈值（0b）：严格——综述检出 fuzzy /work/surveyspec.md` 契约文件。

步骤：

1. 派发 spec_writer subagent
2. subagent 读 _work/pre_survey_notes.md + 0a 对话纪要 + 用户已知清单
3. subagent 用 paper-search search 补全每条论文的 arxiv_id（fuzzy ≥ 80% 直采）
4. 歧义条目攒到「待问用户」清单，一次性 AskUserQuestion 批量问（β 合并）
5. 派发 spec_reviewer subagent 验证（结构合规 + 论文清单完整 + 关键词覆盖）
6. 主 Claude 复述 spec.md 关键字段给用户最终确认

失败处理：reviewer FAIL → γ 修复 + 重试 ≤2

阶段 1：检索下载

目标：按 spec 清单批量下载所有 PDF。

AskUserQuestion 阈值：严格——任一论文 fuzzy / 顶层（与 _综述报告.md` 同层平铺）

1. 对 spec 论文清单逐条：有 arxiv_id 直接下载；无则先 search 补全
2. 下载后 3 项校验：文件大小 > 30 KB / 第一页可抽取 / 标题作者 fuzzy ≥ 80%
3. 任一校验 FAIL → 自动重试下载 ≤ 2 次（不同源轮换）
4. 重试仍 FAIL → 三个用户出口（PDF URL / 本地 PDF / 移出清单）
5. 校验通过后立即按 naming_convention 重命名
6. 派发 paper_search_reviewer subagent 验证命名 + 元数据匹配
7. reviewer FAIL → γ 修复 + 重试 ≤2

阶段 2：并行 subagent 解析

目标：K 路 implementor 并行解析所有 PDF。

派发规则（D 分组 + 二级切分）：

1. K = spec.md 第 5 章子节数
2. 每子节论文 ≤6 篇 → 单路 implementor
3. 单子节论文 > 6 篇 → 二级切分（如 5.1 7 篇 → 5.1A 4 篇 + 5.1B 3 篇）
4. 总并发上限 5：超出时分两批，主 Claude 用 TodoWrite 跟踪进度

β 时序：

1. 同一条主消息内同时发起 K 个 Agent(subagent_type="general-purpose") 调用 paper_extractor
2. K 路全完 → 主 Claude 顺序派 K 个 extract_reviewer
3. reviewer 写入 /_reviews/group__review.md

FAIL 处理：仅重派失败那一路，γ 修复 + 重试 ≤2

阶段 3：报告骨架

目标：合并所有 extracts → outline.md。

步骤：

1. 派发 outline_writer subagent（严格标题层级 + 第 5/7 章 fenced JSON block）
2. subagent 读所有 _work/extracts/*.md + _work/pre_survey_notes.md + _work/survey_spec.md
3. 主 Claude 用 python -c "import json; ..." dry run 验证所有 fenced JSON block（assemble_md.py 阶段 4 也会再次自检）
4. 派发 outline_reviewer 验证（结构合规 + 反幻觉抽样 + 引用对齐）
5. reviewer FAIL → γ 修复 + 重试 ≤2

阶段 4：md 组装

目标：把 outline.md 中间产物渲染为顶层 _综述报告.md（含 LaTeX 公式）。

步骤：

1. 直接调用 skill 内置 python 脚本（不复制到工作目录 — 满足顶层只 *.pdf + 综述报告.md 约束）：

``bash python /assets/assemble_md.py ` ` 表示本 skill 的安装目录（即包含本 SKILL.md 的目录）的绝对路径，由主 Claude 在运行时解析（不要硬编码到具体用户机器路径）。

1. 输出：

• 顶层 /_综述报告.md
• stdout JSON: {"status": "ok", "path": "...", "size_bytes": ..., "cn_chars": ..., "papers": ..., "refs": ...}

1. dry-run 自检（脚本内置，失败 ≠ 0 退出）：

• outline.md 全部 fenced JSON parse 成功
• LaTeX $ / $$ 配对（行内偶数 + 行间偶数）

1. 失败处理：

• JSON 解析错 → 主 Claude 直接 Edit _work/outline.md 修 JSON
• LaTeX 配对错 → 主 Claude grep \$ 数量 + 定位漏闭合
• 不要修 assemble_md.py 副本（脚本不复制工作目录，统一改源即可）

阶段 5：完成度核查

目标：17 项核查全 PASS 才算完成。FAIL 上限 3 次。

步骤：

1. 派发 validation_reviewer subagent 跑反幻觉抽样（~49 处 verifyquotesbatch 并行 ≈ 2 秒）→ /_reviews/validation_review.md
2. 主 Claude 跑 python /assets/validation.py --reviewer-report /_reviews/validation_review.md（`` 含义同阶段 4）
3. 综合写 /_reviews/validation_report.md，列每项 PASS/FAIL
4. 任一 FAIL → γ 修复（按修复路径表分发）；3 轮仍 FAIL → 升级用户
5. 全部 PASS → Edit _work/survey_spec.md 当前阶段为 5-completed，向用户口头汇报

工作目录约定

{cwd}//
├── 2022_CoRL_R3M.pdf                # 顶层论文 PDF（命名规范，平铺）
├── 2022_arXiv_RT1.pdf
├── ...
├── _综述报告.md         # 顶层最终交付（阶段 4 输出）
├── _pre/                            # 0b 预调研综述 PDF
│   └── 2025_arXiv_.pdf
├── _work/                           # 过程文件
│   ├── survey_spec.md               # 0c 输出
│   ├── pre_survey_notes.md          # 0b 输出
│   ├── outline.md                   # 3 输出（含 fenced JSON）
│   └── extracts/
│       ├── group__.md
│       └── _tmp___full.md
└── _reviews/                        # reviewer 报告
    ├── spec_review.md               # 0c reviewer
    ├── paper_search_review.md       # 1 reviewer
    ├── group__review.md   # 2 reviewer
    ├── outline_review.md            # 3 reviewer
    ├── validation_review.md         # 5 reviewer
    ├── validation_report.md         # 5 综合报告
    ├── _validation_claims.json
    └── _validation_results.json

关键约定：

• 顶层只允许 *.pdf（论文）+ _综述报告.md（最终交付）两类文件
• 其他所有过程产物归 _pre/ _work/ _reviews/ 三个下划线前缀子目录
• assemble_md.py 与 validation.py 直接以 /assets/... 形式从 skill 安装目录调用，不复制到工作目录

集成 paper-search

paper-survey 通过 paper-search skill 完成所有检索/下载，详见 references/paper_search_cheatsheet.md。

CLI 模式（要求 paper-search 已在 PATH 中可用；安装方式见 paper-search skill 自身文档）：

paper-search  [args]

资源索引

• assets/：每次调用必用
• spec_template.md / naming_convention.md
• assemble_md.py（阶段 4 markdown 组装入口，标准库无依赖）
• pdf_extraction.py（含 verifyquotesbatch 并行 CLI）
• validation.py（17 项核查 + reviewer-report 参数 + 弹性字数档）
• subagent_prompts/：9 个 prompt 模板
• pre_survey_extractor.md / spec_writer.md / spec_reviewer.md
• paper_search_reviewer.md / paper_extractor.md / extract_reviewer.md
• outline_writer.md / outline_reviewer.md / validation_reviewer.md
• references/：按需查询
• report_structure_11chapters.md：11 章 markdown 渲染规范
• markdown_formula_convention.md：LaTeX 公式契约（行内/行间分隔符 + 中文紧邻空格 + 强制级别）
• gb_t_7714_format.md：参考文献格式
• paper_search_cheatsheet.md：paper-search 命令速查
• field_extraction_schema.md：字段抽取契约 + 阶段 5 抽样规则（含公式抽样）
• troubleshooting.md：md 时代失败模式（LaTeX 配对 / fenced JSON / pipe table）

关键约束

1. 阶段间严格串行 / 阶段内 K 路并行
2. 反幻觉契约 B + 抽样 C：每字段附引文 〔p.{页码}: "{≤30字}"〕，未定位 → N/A-源文本未覆盖
3. AskUserQuestion 阶段差异化：

• 0a 自由对话：主 Claude 与用户直接对话收集主题/范围/目录，不强约束 AskUserQuestion 调用
• 0b 严格：综述检索 fuzzy < 80% / 多候选 / 0 命中 → 必问；批量上限 5 个 question/次
• 0c 中等：仅论文清单 arxiv_id 补全的关键歧义问；关键词扩展 / 章节顺序 / 命名细节不问
• 1 严格：每篇论文检索/下载/校验失败都问；批量合并（β）攒到一次问完
• 2-5 不直接调：subagent 内不许调 AskUserQuestion；FAIL 升级时由主 Claude 接管

1. β 批量合并 AskUserQuestion：歧义攒一次问完，不逐个打断
2. 完成度核查上限 3 次修复，超过升级用户
3. 跨 session 重读 spec.md 不依赖对话上下文，spec.md「当前阶段」字段为权威状态

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ShirlyTaylor73
• Source: ShirlyTaylor73/personal-skills
• License: MIT

Install and usage instructions live in the source repository linked above.