| name | paper-survey |
| description | 中文学术综述报告自动生成 — 系统化完成多论文文献调研并产出 11 章 markdown 综述报告（含 LaTeX 公式可渲染）。集成 paper-search 自动检索下载、K 路并行 subagent 解析、reviewer 双层质量审查、跨 session 自动恢复。 |
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 <workdir>（源路径直调，不复制）
→ outline.md 中间产物渲染为顶层 <topic>_综述报告.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 进行中（续上从 pre_survey_extractor） |
| 不存在 | — | _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 存在，<topic>_综述报告.md 缺 | 阶段 4 |
| 存在 | 4-completed | <topic>_综述报告.md 存在，_reviews/validation_report.md 缺 | 阶段 5 |
| 存在 | 5-completed | 全部存在 + 17/17 PASS | 完成 |
| 存在 | 字段缺失 | — | 用文件存在性回退推断 |
| 存在 | 字段与文件存在性矛盾 | — | AskUserQuestion 升级用户 |
| 损坏（解析异常） | — | — | AskUserQuestion 升级用户 |
流程
- 扫描
{cwd}/ 下子目录，识别 <topic>/ 工作目录
- 对每个工作目录按上表推断当前阶段
- 调用
AskUserQuestion：「检测到现有任务：[A] {topic-A} 阶段 X / [B] {topic-B} 阶段 Y。请选续哪个 / 新开 / 重跑某主题」
- 用户选「续上」 → 跳到对应阶段；选「新开」 → 进 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。
步骤：
- 创建工作目录
{cwd}/<topic_slug>/（含子目录 _pre/ 与 _work/）
- 检索综述（默认源不含 semantic）：
paper-search search "{topic} survey OR review OR tutorial" -n 5 -s arxiv,crossref,openreview,doaj
- 用户给的主线综述：除非明确说"只用这一篇"，否则继续 paper-search 自动补搜
- 下载 1-3 篇到
_pre/，按 naming_convention 重命名
- 派发
pre_survey_extractor subagent 产出 _work/pre_survey_notes.md
- 主 Claude 内联 reviewer（不派 subagent）：regex 检查每条要点附引文 + verify_quotes_batch 抽样 3 条引文 + 子分类数 ∈ [3, 7]
AskUserQuestion 阈值（0b）：严格——综述检出 fuzzy < 80% / 多候选 / 0 命中都问
失败处理：默认源返 0 → fallback 加 semantic → 仍 0 则降级"高引论文+奠基工作" + AskUserQuestion 复述
阶段 0c：写 spec
目标：生成 <workdir>/_work/survey_spec.md 契约文件。
步骤：
- 派发
spec_writer subagent
- subagent 读
_work/pre_survey_notes.md + 0a 对话纪要 + 用户已知清单
- subagent 用
paper-search search 补全每条论文的 arxiv_id（fuzzy ≥ 80% 直采）
- 歧义条目攒到「待问用户」清单，一次性
AskUserQuestion 批量问（β 合并）
- 派发
spec_reviewer subagent 验证（结构合规 + 论文清单完整 + 关键词覆盖）
- 主 Claude 复述 spec.md 关键字段给用户最终确认
失败处理：reviewer FAIL → γ 修复 + 重试 ≤2
阶段 1：检索下载
目标：按 spec 清单批量下载所有 PDF。
AskUserQuestion 阈值：严格——任一论文 fuzzy < 80% / 多候选 / 0 命中 / 元数据不匹配 → 批量问
步骤：
- PDF 直接落
<workdir>/ 顶层（与 <topic>_综述报告.md 同层平铺）
- 对 spec 论文清单逐条：有 arxiv_id 直接下载；无则先 search 补全
- 下载后 3 项校验：文件大小 > 30 KB / 第一页可抽取 / 标题作者 fuzzy ≥ 80%
- 任一校验 FAIL → 自动重试下载 ≤ 2 次（不同源轮换）
- 重试仍 FAIL → 三个用户出口（PDF URL / 本地 PDF / 移出清单）
- 校验通过后立即按 naming_convention 重命名
- 派发
paper_search_reviewer subagent 验证命名 + 元数据匹配
- reviewer FAIL → γ 修复 + 重试 ≤2
阶段 2：并行 subagent 解析
目标：K 路 implementor 并行解析所有 PDF。
派发规则（D 分组 + 二级切分）：
- K = spec.md 第 5 章子节数
- 每子节论文 ≤6 篇 → 单路 implementor
- 单子节论文 > 6 篇 → 二级切分（如 5.1 7 篇 → 5.1A 4 篇 + 5.1B 3 篇）
- 总并发上限 5：超出时分两批，主 Claude 用 TodoWrite 跟踪进度
β 时序：
- 同一条主消息内同时发起 K 个
Agent(subagent_type="general-purpose") 调用 paper_extractor
- K 路全完 → 主 Claude 顺序派 K 个 extract_reviewer
- reviewer 写入
<workdir>/_reviews/group_<group_id>_review.md
FAIL 处理：仅重派失败那一路，γ 修复 + 重试 ≤2
阶段 3：报告骨架
目标：合并所有 extracts → outline.md。
步骤：
- 派发
outline_writer subagent（严格标题层级 + 第 5/7 章 fenced JSON block）
- subagent 读所有
_work/extracts/*.md + _work/pre_survey_notes.md + _work/survey_spec.md
- 主 Claude 用
python -c "import json; ..." dry run 验证所有 fenced JSON block（assemble_md.py 阶段 4 也会再次自检）
- 派发
outline_reviewer 验证（结构合规 + 反幻觉抽样 + 引用对齐）
- reviewer FAIL → γ 修复 + 重试 ≤2
阶段 4：md 组装
目标：把 outline.md 中间产物渲染为顶层 <topic_slug>_综述报告.md（含 LaTeX 公式）。
步骤：
- 直接调用 skill 内置 python 脚本（不复制到工作目录 — 满足顶层只 *.pdf + 综述报告.md 约束）：
python <skill-path>/assets/assemble_md.py <workdir>
<skill-path> 表示本 skill 的安装目录（即包含本 SKILL.md 的目录）的绝对路径，由主 Claude 在运行时解析（不要硬编码到具体用户机器路径）。
- 输出：
- 顶层
<workdir>/<topic_slug>_综述报告.md
- stdout JSON:
{"status": "ok", "path": "...", "size_bytes": ..., "cn_chars": ..., "papers": ..., "refs": ...}
- dry-run 自检（脚本内置，失败 ≠ 0 退出）：
- outline.md 全部 fenced JSON parse 成功
- LaTeX
$ / $$ 配对（行内偶数 + 行间偶数）
- 失败处理：
- JSON 解析错 → 主 Claude 直接 Edit
_work/outline.md 修 JSON
- LaTeX 配对错 → 主 Claude grep
\$ 数量 + 定位漏闭合
- 不要修 assemble_md.py 副本（脚本不复制工作目录，统一改源即可）
阶段 5：完成度核查
目标：17 项核查全 PASS 才算完成。FAIL 上限 3 次。
步骤：
- 派发
validation_reviewer subagent 跑反幻觉抽样（~49 处 verify_quotes_batch 并行 ≈ 2 秒）→ <workdir>/_reviews/validation_review.md
- 主 Claude 跑
python <skill-path>/assets/validation.py <workdir> --reviewer-report <workdir>/_reviews/validation_review.md（<skill-path> 含义同阶段 4）
- 综合写
<workdir>/_reviews/validation_report.md，列每项 PASS/FAIL
- 任一 FAIL → γ 修复（按修复路径表分发）；3 轮仍 FAIL → 升级用户
- 全部 PASS → Edit
_work/survey_spec.md 当前阶段为 5-completed，向用户口头汇报
工作目录约定
{cwd}/<topic_slug>/
├── 2022_CoRL_R3M.pdf # 顶层论文 PDF（命名规范，平铺）
├── 2022_arXiv_RT1.pdf
├── ...
├── <topic_slug>_综述报告.md # 顶层最终交付（阶段 4 输出）
├── _pre/ # 0b 预调研综述 PDF
│ └── 2025_arXiv_<survey>.pdf
├── _work/ # 过程文件
│ ├── survey_spec.md # 0c 输出
│ ├── pre_survey_notes.md # 0b 输出
│ ├── outline.md # 3 输出（含 fenced JSON）
│ └── extracts/
│ ├── group_<group_id>_<paper_index>.md
│ └── _tmp_<group_id>_<paper_index>_full.md
└── _reviews/ # reviewer 报告
├── spec_review.md # 0c reviewer
├── paper_search_review.md # 1 reviewer
├── group_<group_id>_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（论文）+ <topic_slug>_综述报告.md（最终交付）两类文件
- 其他所有过程产物归
_pre/ _work/ _reviews/ 三个下划线前缀子目录
assemble_md.py 与 validation.py 直接以 <skill-path>/assets/... 形式从 skill 安装目录调用，不复制到工作目录
集成 paper-search
paper-survey 通过 paper-search skill 完成所有检索/下载，详见 references/paper_search_cheatsheet.md。
CLI 模式（要求 paper-search 已在 PATH 中可用；安装方式见 paper-search skill 自身文档）：
paper-search <command> [args]
资源索引
- assets/：每次调用必用
spec_template.md / naming_convention.mdassemble_md.py（阶段 4 markdown 组装入口，标准库无依赖）pdf_extraction.py（含 verify_quotes_batch 并行 CLI）validation.py（17 项核查 + reviewer-report 参数 + 弹性字数档）subagent_prompts/：9 个 prompt 模板
pre_survey_extractor.md / spec_writer.md / spec_reviewer.mdpaper_search_reviewer.md / paper_extractor.md / extract_reviewer.mdoutline_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）
关键约束
- 阶段间严格串行 / 阶段内 K 路并行
- 反幻觉契约 B + 抽样 C：每字段附引文
〔p.{页码}: "{≤30字}"〕，未定位 → N/A-源文本未覆盖
- AskUserQuestion 阶段差异化：
- 0a 自由对话：主 Claude 与用户直接对话收集主题/范围/目录，不强约束 AskUserQuestion 调用
- 0b 严格：综述检索 fuzzy < 80% / 多候选 / 0 命中 → 必问；批量上限 5 个 question/次
- 0c 中等：仅论文清单 arxiv_id 补全的关键歧义问；关键词扩展 / 章节顺序 / 命名细节不问
- 1 严格：每篇论文检索/下载/校验失败都问；批量合并（β）攒到一次问完
- 2-5 不直接调：subagent 内不许调 AskUserQuestion；FAIL 升级时由主 Claude 接管
- β 批量合并 AskUserQuestion：歧义攒一次问完，不逐个打断
- 完成度核查上限 3 次修复，超过升级用户
- 跨 session 重读 spec.md 不依赖对话上下文，spec.md「当前阶段」字段为权威状态
