# Paper Survey

> 中文学术综述报告自动生成 — 系统化完成多论文文献调研并产出 11 章 markdown 综述报告（含 LaTeX 公式可渲染）。集成 paper-search 自动检索下载、K 路并行 subagent 解析、reviewer 双层质量审查、跨 session 自动恢复。

- **Type:** Skill
- **Install:** `agentstack add skill-shirlytaylor73-personal-skills-paper-survey`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ShirlyTaylor73](https://agentstack.voostack.com/s/shirlytaylor73)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ShirlyTaylor73](https://github.com/ShirlyTaylor73)
- **Source:** https://github.com/ShirlyTaylor73/personal-skills/tree/master/plugins/personal-skills/skills/paper-survey

## Install

```sh
agentstack add skill-shirlytaylor73-personal-skills-paper-survey
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 进行中（续上从 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` 存在，`_综述报告.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
   ```
3. 用户给的主线综述：除非明确说"只用这一篇"，否则继续 paper-search 自动补搜
4. 下载 1-3 篇到 `_pre/`，按 naming_convention 重命名
5. 派发 `pre_survey_extractor` subagent 产出 `_work/pre_survey_notes.md`
6. **主 Claude 内联 reviewer**（不派 subagent）：regex 检查每条要点附引文 + verify_quotes_batch 抽样 3 条引文 + 子分类数 ∈ [3, 7]

**AskUserQuestion 阈值（0b）**：严格——综述检出 fuzzy /_work/survey_spec.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` 同层平铺）
2. 对 spec 论文清单逐条：有 arxiv_id 直接下载；无则先 search 补全
3. **下载后 3 项校验**：文件大小 > 30 KB / 第一页可抽取 / 标题作者 fuzzy ≥ 80%
4. 任一校验 FAIL → 自动重试下载 ≤ 2 次（不同源轮换）
5. 重试仍 FAIL → 三个用户出口（PDF URL / 本地 PDF / 移出清单）
6. 校验通过后立即按 naming_convention 重命名
7. 派发 `paper_search_reviewer` subagent 验证命名 + 元数据匹配
8. 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 在运行时解析（不要硬编码到具体用户机器路径）。
2. 输出：
   - 顶层 `/_综述报告.md`
   - stdout JSON: `{"status": "ok", "path": "...", "size_bytes": ..., "cn_chars": ..., "papers": ..., "refs": ...}`
3. **dry-run 自检**（脚本内置，失败 ≠ 0 退出）：
   - outline.md 全部 fenced JSON parse 成功
   - LaTeX `$` / `$$` 配对（行内偶数 + 行间偶数）
4. 失败处理：
   - JSON 解析错 → 主 Claude 直接 Edit `_work/outline.md` 修 JSON
   - LaTeX 配对错 → 主 Claude grep `\$` 数量 + 定位漏闭合
   - 不要修 assemble_md.py 副本（脚本不复制工作目录，统一改源即可）

## 阶段 5：完成度核查

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

**步骤**：

1. 派发 `validation_reviewer` subagent 跑反幻觉抽样（~49 处 verify_quotes_batch 并行 ≈ 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 自身文档）：
```bash
paper-search  [args]
```

## 资源索引

- **assets/**：每次调用必用
  - `spec_template.md` / `naming_convention.md`
  - `assemble_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.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 接管
4. **β 批量合并 AskUserQuestion**：歧义攒一次问完，不逐个打断
5. **完成度核查上限 3 次修复**，超过升级用户
6. **跨 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](https://github.com/ShirlyTaylor73)
- **Source:** [ShirlyTaylor73/personal-skills](https://github.com/ShirlyTaylor73/personal-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-shirlytaylor73-personal-skills-paper-survey
- Seller: https://agentstack.voostack.com/s/shirlytaylor73
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.