Literature Review

文献综述写作

基于工作区中的论文，撰写结构化的文献综述。

前提

用户必须指定一个 workspace（--ws NAME）。如果用户未指定：

1. 运行 scholaraio ws list 列出已有工作区
2. 让用户选择或创建一个

综述输出写入 workspace/<name>/ 目录。

模式选择

本 skill 支持两种工作模式：

• 手动模式（默认）：逐步确认大纲和章节，适合精密打磨的综述写作
• 快速模式：用户明确要求快速生成时，跳过人工确认，自动完成文献扫描、分组、分析和初稿生成

输出格式选择（必须在开始时明确确认）

在了解写作需求时，必须主动询问用户期望的输出格式：

1. Markdown 速览稿：轻量、便于在线阅读、快速迭代
2. LaTeX 正式学术综述：遵循 docs/writing-guide/academic-survey-writing-guide.md 的规范，适用于长文深度分析，最终输出 PDF

如果用户未明确选择，默认追问一次。 若用户选择 LaTeX 正式学术综述，执行以下准备步骤：

• 必读文档：
  • docs/writing-guide/academic-survey-writing-guide.md（项目内置精简版流程）
  • 若宿主环境提供项目记忆中的学术写作指南文件（如 academic_writing_guidelines.md、academic_writing_rich_elements.md、chinese_latex_typesetting.md），可一并参考；若不可用，则以仓库内文档为准
• 硬性要求：
  • 使用 \documentclass[12pt,a4paper]{article} + ctex 编译；中文综述用 xelatex，英文综述用 lualatex
  • 作者字段必须包含 Claude (AI Assistant)
  • 所有非原创论述必须标注数字上标引用 [n]，使用 BibTeX 管理；最终编译前必须执行引用闭合检查：确保所有 \cite{} 都有对应 bibitem，所有 bibitem 都被引用或经 \nocite{} 声明，无孤儿文献
  • 禁止生成 AI 风格的密集 bullet point 罗列；优先使用连贯段落、批判性分析、因果推演
  • 每章至少包含 2–3 种丰富元素（源论文插图 + 数据表格/伪代码算法/TikZ 概念图）
  • 图注描述必须与图片实际内容严格对应；插入任何图片前必须先打开查看
  • 学术综述必须包含独立的“批判性讨论”章节：对资料不对称、方法论局限、厂商宣称与独立验证的鸿沟、封闭生态权衡等进行分析
  • 若涉及硬件/微架构演进，必须区分同代内的不同变体（如训练版 vs 推理版），并在结论中逐一总结每一代/变体的核心贡献；如资料充足，建议补充专利布局分析
  • 正文完成后执行“补充插入源论文插图”步骤，最后编译 PDF 并做视觉检查

快速模式（Fast Mode）

触发条件（满足任一即可）：

• 用户明确说"快速生成"、"直接写"、"跳过确认"、"先给我一版"
• 用户在请求中体现出明显的时间紧迫或对完整度的要求高于精雕细琢

快速模式执行流程：

重要原则：快速模式 ≠ 低质量模式。 快速模式跳过的是与用户的人工确认环节，而不是深度分析环节。以下流程强制执行三道质量控制：Critic 骨架重组、Subagent 批判性精读模板、每章最低丰富元素。

1. 自动摸底文献：运行 ws show <name> 和 ws search <name> "<主题>"，快速扫描工作区所有论文的 L1-L2
2. 自动构建骨架：
   • 如已存在主题模型，参考 scholaraio topics 的分组结构（注意：topics 反映的是全局主库分布，若工作区与主库差异较大，应优先基于工作区论文摘要直接推断分组）
   • 否则直接基于摘要由 LLM 推断最优分组（主题式/方法论式/时间线式/争议式），不中断用户确认
3. Critic 骨架重组（强制）： 在写初稿前，必须由 critic subagent 审查自动生成的骨架。审查标准：
   • 分组是否按"方法论演进"或"核心争议"组织，而非机械的年份/机构罗列
   • 各章节标题是否暗示了明确的论点，而非模糊的"XX 年研究"
   • 章节间是否有清晰的逻辑递进（问题 → 方法 → 对比 → 局限） 若骨架被判定为"清单式"而非"论证式"，必须重写骨架后再进入下一步。
4. 自动深度阅读（强制提示词模板）： 对每章节的核心论文，启动 subagent 并行提取 L3/L4 关键发现。Subagent 必须使用 _templates/critic-reading.md 中的批判性精读模板，不得简化。
   • 将值得保留的发现自动追加到各论文的 notes.md。优先使用 CLI：scholaraio show "<paper-id>" --append-notes "## YYYY-MM-DD | <workspace> | literature-review-fast\n- Finding 1\n- Finding 2"；若需要批量自动化，再由主 agent 直接读写文件实现
   • 利用 images/ 和公式进行多模态分析（如适用）
5. 自动生成初稿（丰富元素强制）：
   • 若用户选择 Markdown：按骨架一次性撰写完整综述（含开头、各章节、结尾），保存为 literature-review.md。每章必须包含至少 1 个数据对比表或自动生成的概念图（scholaraio diagram --from-text ...），禁止纯文字大段罗列
   • 若用户选择 LaTeX：按骨架一次性撰写 literature-review.tex，每章至少包含 2 种丰富元素（源论文插图 / 数据表格 / 伪代码算法 / TikZ 概念图），编译输出 literature-review.pdf
6. 保存产物：
   • Markdown 模式：
     • 综述正文：workspace/<name>/literature-review.md
     • 章节大纲：workspace/<name>/literature-review-outline.md
     • 参考文献：workspace/<name>/references.bib
   • LaTeX 模式：
     • LaTeX 源文件：workspace/<name>/literature-review.tex
     • 编译后的 PDF：workspace/<name>/literature-review.pdf
     • 章节大纲：workspace/<name>/literature-review-outline.md
     • 参考文献：workspace/<name>/references.bib
7. 向用户汇报：仅输出文件路径、总字数/页数、章节概览，不 dump 全文

快速模式不改变学术态度要求：仍须指出矛盾、区分事实与推测、如实引用来源。

执行逻辑（手动模式）

1. 了解写作需求（含格式确认）

向用户确认：

• 综述主题：围绕什么研究问题？
• 目标读者：期刊论文的 Related Work？学位论文的文献综述章节？独立 review article？
• 语言：中文 / English
• 篇幅：大致字数或页数
• 输出格式：Markdown 速览稿 / LaTeX 正式学术综述（默认必须追问）
• 风格参考（可选）：用户可提供一篇范文或已有文本，你来分析其结构、叙述风格、引用密度、段落组织方式，然后仿照

若用户选择 LaTeX 正式学术综述，立即读取上述必读文档，并将其规范贯彻到后续全部步骤中。

2. 摸底文献范围

scholaraio ws show <name>                    # 查看工作区论文列表
scholaraio ws search <name> "<主题>"          # 范围内搜索
scholaraio topics                             # 主题聚类概览（如已建模）

对工作区内论文做 L1-L2 快速扫描（标题 + 摘要），建立全局认知：

scholaraio show <paper-id> --layer 2          # 逐篇扫描摘要

3. 构建综述骨架

根据文献内容，提出分组方案（按方法/时间线/研究问题/理论流派），形成章节大纲。向用户展示大纲并确认。

常见组织方式：

• 主题式：按研究子问题分组（最常用）
• 时间线式：按发展阶段梳理
• 方法论式：按技术路线对比
• 争议式：按观点分歧组织正反论证

骨架可视化：若采用方法论式或时间线式，可生成结构图辅助用户理解章节组织：

# 例如：方法演进时间线
scholaraio diagram --from-text "2000: Method A; 2010: Method B; 2020: Method C" --type tech_route --format drawio

# 例如：主题分类树
scholaraio diagram --from-text "Theme 1 contains X and Y; Theme 2 contains Z" --type model_arch --format svg

将图文件路径附在大纲之后供用户参考。

4. 深度阅读关键论文

对每个章节的核心论文，先检查 configured papers library 中是否有历史分析笔记（<paper-dir>/notes.md），有则复用已有发现，避免重复劳动。

然后加载 L3（结论）或 L4（全文）：

scholaraio show <paper-id> --layer 3          # 结论
scholaraio show <paper-id> --layer 4          # 全文（仅关键论文）

分析完成后，将值得跨会话保留的关键发现追加到论文的 notes.md。优先使用 CLI：

scholaraio show "<paper-id>" --append-notes "## YYYY-MM-DD | <workspace> | literature-review
- 方法特点
- 核心贡献
- 与其他论文的关键对比"

也可由主 agent 直接读写文件实现。格式：## YYYY-MM-DD | <workspace> | literature-review，内容包括方法特点、核心贡献、与其他论文的关键对比。

多模态分析（MinerU 解析的论文保留了图表和公式）：

• 读取论文中的关键图表（configured papers library 下的 <dir>/images/），辅助理解实验结果和方法流程
• 分析论文中的数学公式（LaTeX），对比不同论文的建模方法差异
• 必要时编写 Python 代码做定量对比（如提取多篇论文报告的数值结果，绘制对比表格）

引用图谱辅助发现关联：

scholaraio shared-refs "<id1>" "<id2>"        # 共同引用分析
scholaraio refs "<id>"                        # 参考文献
scholaraio citing "<id>"                      # 被引论文