Literature snowball

文献滚雪球（Literature Snowball）

把「散落的文献清单」变成「可写综述的文献地图」。从几篇种子文献出发，双向滚雪球（顺参考文献往回滚 + 查被引文献往前滚），逐篇判断相关性，映射到综述章节，并把结果持续维护在一个 Obsidian 文献地图笔记里。池子可以跨会话越滚越大。

适用一切文献综述场景：学位论文、开题报告、投稿论文、课程论文、新领域入门。

默认约定（用户未另行说明时一律遵守）

1. 输出语言为中文：分类理由、贡献判断、阅读建议、缺口诊断都用中文。英文文献保留英文原题名与标准参考文献格式（默认 APA 7），不翻译题名。
2. 分类轴默认按理论路径 / 概念框架，不按作者谱系或被引频次。被引数只是参考信号。
3. 产出物是单一「文献地图」大笔记（Markdown，Obsidian 兼容），结构见 templates/literature-map.md。
4. 双向滚雪球：backward（参考文献，找理论源头）+ forward（被引文献，找最新进展）。
5. 每轮滚完必须停下汇报，等用户确认方向后再滚下一轮。绝不自顾自连滚多轮。
6. 种子即核心：用户给的起点文献（如导师推荐的 5 篇）既是种子也是初始核心文献，不需要预先区分。

启动时确认

最多问三个短问题，已经知道的不要问：

1. 焦点主题或综述要回答的问题是什么？
2. 已有综述框架吗（如 概念界定 / 影响因素 / 机制解释 或 P1/P2/P3/P4）？有则直接用于章节映射；没有则先滚，再从文献中归纳候选框架供用户选。
3. 文献地图笔记保存到哪个路径（Obsidian vault 内的 .md 文件）？如果该路径已有地图笔记，本次是续滚。

联网查公开摘要是本 skill 的基础能力，默认允许；首轮开始前向用户说明一句即可，不必反复请示。

核心循环（每一轮都按此执行）

第 0 步：恢复状态

若地图笔记已存在，先完整读取：载入已收录文献、已排除文献、当前轮次、未完成的下一轮计划。已处理过的文献绝不重复评级、重复联网查询。

第 1 步：读种子

对用户给的每个 PDF / DOCX / 文本：

• 必须先读这篇本身——它自己就是文献池的一员，先入池。
• 读题名、摘要、关键词、研究问题、理论框架、结论。可用 scripts/reference_slice.py 快速切出摘要与参考文献段；脚本输出有噪声时回去人工读原文，脚本只是辅助不是证据。
• 判定这篇与主题的相关性（强 / 中 / 弱）+ 一句话中文理由 + 证据等级。
• 弱相关的种子不滚：它本身与主题关系弱，它的参考文献大概率把方向带偏。入池留档即可。

用户给的若是 DOI / 题名清单而非全文，用 scripts/snowball_api.py lookup 先拉元数据和摘要，再按同样标准判级。

第 2 步：双向取候选

对每篇强相关文献（中相关选择性执行）：

• backward：reference_slice.py 从全文提取参考文献文本，同时 snowball_api.py refs 拉取 OpenAlex 上该文献的结构化参考文献记录（含每条的摘要与被引数），两边对照补全。
• forward：snowball_api.py cited-by 查「谁引用了这篇」，默认看两批——被引最高的（领域共识）和最近发表的（最新进展）。理论奠基文献的 forward 结果尤其值得细看。
• 所有候选先与地图中的已收录、已排除清单去重，再进入下一步。

第 3 步：批量查摘要

• 首选 snowball_api.py lookup --file candidates.txt 批量查询：脚本自动按 OpenAlex → Semantic Scholar → Crossref 的顺序兜底。
• API 查不到的少数条目，用网页搜索补：DOI 页、期刊页、出版社页、机构仓储。只用官方来源。
• 中文文献：三个 API 大多查不到。改用网页搜索（百度学术、万方、期刊官网页面），查到的也标 需核对；查不到时请用户提供 PDF 或确认题录。
• 任何渠道都拿不到摘要的，只能按「仅见题名」处理。绝不编造摘要、DOI、页码、引文或结论。

第 4 步：相关性评级

判断标准按权重排序：

1. 与用户主题 / 综述章节的贴合度——最重要，压倒一切。
2. 理论奠基性——是否提供概念、理论路径、机制解释的源头。
3. 被多篇种子反复引用 / 同一核心作者反复出现。

名气和引用数本身不构成入选理由。每篇候选给出：

• 等级：强相关 / 中相关 / 弱相关
• 一句话中文理由，讲清它对这篇综述的具体贡献（不是泛泛的"很重要"）
• 证据等级：已读全文 / 已读摘要 / 仅见题名 / 需核对

第 5 步：章节映射

强相关文献逐篇标注写作位置，粒度到段落功能而不止章节名。例如：

适合 P2 开头立论 ｜ 概念界定 ｜ 理论基础 ｜ 政策背景 ｜ 批判与边界 ｜ 过渡到 P3 ｜ 影响因素-家庭 ｜ 机制解释-理论路径 ｜ 经验证据锚点 ｜ 争论的一方

用户没有框架时，按理论路径把强相关文献聚类，归纳出一个候选框架（每条路径配代表文献）供用户确认后再做映射。

第 6 步：更新文献地图笔记

把本轮结果写入单一地图笔记（结构见 templates/literature-map.md），写入规则：

• 追加与更新，不重写：保留用户在笔记中的手动修改；同一篇文献状态变化（如「仅见题名 → 已读摘要」）就地更新。
• 已排除的文献必须留名目（题名 + 一句话排除理由），防止下一轮重复查询、重复劳动。
• 滚雪球日志每轮追加一行，记录来源、筛选量、保留量。
• frontmatter 更新轮次、池子规模、最后更新日期。

第 7 步：本轮汇报，然后停下

每轮结束必须给用户一份汇报，包含全部五项：

1. 本轮新增强相关文献表：引用 + 中文贡献理由 + 章节映射 + 证据等级 + 引自哪篇（引用链）。
2. 池子总览：强 / 中 / 弱 / 已排除的数量，框架各板块的覆盖情况。
3. 缺口诊断：要具体到可执行，如「缺纵向因果证据」「缺中国语境实证」「缺社会比较与自我呈现的概念桥接」，不许说"还需要更多文献"这种空话。
4. 下一轮滚雪球建议 + 检索关键词：每个缺口配一组可以直接复制去搜索的中英文关键词（如 social comparison adolescent well-being / 短视频 青少年 心理健康 / longitudinal social media effects），并指明建议从池中哪几篇继续滚。
5. 推荐下载清单：强相关但尚无全文的文献，按优先级排序。

汇报完停下等用户确认，用户说继续才滚下一轮。

停止与饱和判断

出现以下任一情况，明确报告而不是继续硬滚：

• 新候选大面积重复已见的作者与概念 → 报告「接近饱和」，说明剩余缺口。
• 池子达到用户要求的规模。
• 用户只要快速地图。

未饱和就说清还缺什么、下一步该下载或搜索什么。

证据与诚信规则（铁律）

• 每条判断都标证据等级：已读全文 / 已读摘要 / 仅见题名 / 需核对。
• 不编造摘要、DOI、页码、引文、文献贡献。拿不到就标注拿不到。
• 没读过摘要或全文，不得声称某文献支持某个观点。
• API 与网搜得到的信息附来源（OpenAlex ID、DOI 链接、页面 URL）。
• 文献地图是初筛层：每轮汇报结尾提醒用户，正式写作引用前需人工核对原文与出版信息。

脚本用法

脚本保下限，AI 做判断。脚本失败或网络不可用时，优雅降级为网页搜索并告知用户，不要中断整轮流程。

reference_slice.py — 本地文件切片

python3 scripts/reference_slice.py paper1.pdf paper2.pdf

从 PDF / DOCX / TXT / Markdown 粗略切出题名、摘要、参考文献段（JSON 输出）。PDF 依赖 pdftotext，缺失时脚本会提示。

snowball_api.py — 联网元数据与双向滚雪球

依赖：仅 Python 标准库，无需安装任何包。数据源：OpenAlex（主）→ Semantic Scholar → Crossref（兜底），全部免费、无需 API key。

# 批量解析 DOI 或题名 → 元数据 + 摘要（--file 每行一条）
python3 scripts/snowball_api.py lookup "10.2307/2092789" "Cultural capital and school success"
python3 scripts/snowball_api.py lookup --file candidates.txt

# backward：某篇文献的参考文献（含各自摘要与被引数）
python3 scripts/snowball_api.py refs "10.2307/2092789" --max 60

# forward：谁引用了这篇（默认被引最高优先；--sort recent 看最新）
python3 scripts/snowball_api.py cited-by "10.2307/2092789" --max 25
python3 scripts/snowball_api.py cited-by "10.2307/2092789" --max 25 --sort recent

所有子命令输出 JSON（含 abstract、cited_by_count、doi、openalex_id、source 字段）。--mailto 用户邮箱 可进入 OpenAlex 礼貌池提高限额。

默认最终交付

用户要完整滚雪球结果时，交付：

1. 种子文献诊断（每篇强中弱 + 理由）。
2. 强 / 中 / 弱相关清单。
3. 综述章节映射表（段落功能粒度）。
4. 核心作者与概念网络、争论与分歧。
5. 下一轮下载 / 检索清单 + 中英文关键词。
6. 缺口与不确定性说明 + 人工核对提醒。