lit-synthesis

文献综合

以下脚本路径均相对于此技能的基础目录（技能加载时由 Claude Code 报告的 $SKILL_DIR）。

你将帮助社会学家从一组论文中深入理解某个领域。这是从查找论文（lit-search）到撰写自己的文献综述之间的分析桥梁。

项目集成

此技能会在 project.yaml 可用时读取该文件：

# From project.yaml
paths:
  lit_synthesis: literature/synthesis/

项目类型： 此技能适用于所有项目类型。文献综合对定性、定量和混合方法研究都至关重要。

完成后更新 progress.yaml：

status:
  lit_synthesis: done
artifacts:
  field_synthesis: literature/synthesis/field-synthesis.md

适用场景

此技能承接 lit-search 的工作：

技能	作用	关键输出
lit-search	通过 OpenAlex 查找论文	database.json、references.bib、下载清单
lit-synthesis	通过本地文库分析和整理	field-synthesis.md（包含理论图谱、主题集群和辩论图谱章节）

输入：library/ 中的 Markdown 论文文件（由 PDF 转换而来）和 references.bib（来自 lit-search 或用户现有的文库）
输出：经过整理的领域认知，为撰写文献综述提供支持

何时使用此技能

在以下情况下使用此技能：

• 已有一组论文（来自 lit-search 或自己的收藏）
• 写作前需要了解理论格局
• 想要识别辩论、张力和相互竞争的立场
• 需要按主题或理论传统整理论文
• 想要深入的阅读笔记，而不只是提取元数据

核心原则

1. 深入阅读，而非广泛浏览：彻底理解 15 篇论文，胜过浅尝辄止地浏览 50 篇。

2. 理论传统至关重要：论文存在于思想脉络之中。梳理谁引用了谁，以及原因。

3. 辩论弥足珍贵：相互竞争的立场为研究贡献创造空间。找出其中的张力。

4. 组织服务于写作：你创建的集群和图谱应为文献综述搭建结构。

5. 尽可能阅读全文：摘要告诉你是什么；全文告诉你如何以及为什么。

文件管理

此技能使用 git 跟踪各阶段的进度。在新阶段修改任何输出文件之前： 1.暂存并提交当前状态：git add [files] && git commit -m "lit-synthesis: Phase N complete" 2. 然后继续修改。

不要创建带版本后缀的副本（例如 -v2、-final、-working）。git 历史记录就是版本轨迹。

---

本地文库集成

此技能会从本地文库读取由 PDF 转换而成的 Markdown 论文，并从 references.bib 读取书目信息。

预期文库布局

project/
├── references.bib          # BibTeX from lit-search (or user's reference manager)
└── library/
    └── markdown/
        ├── smith2020-cultural-frames.md
        ├── jones2019-institutional.md
        └── ...             # One .md per paper, converted from PDF

将 PDF 转换为 Markdown

使用导入脚本将论文添加到文库：

uv run "$SKILL_DIR"/scripts/ingest.py --file /path/to/paper.pdf

此脚本会将 PDF 转换为 library/markdown/ 中的 Markdown 文件，并将元数据添加到 references.bib。

语义搜索

要在文库中进行概念／语义搜索（例如，即使确切术语不同，也能查找有关某个概念的段落），请使用 RAG 索引：

# Build/update the index (run after adding new papers)
uv run "$SKILL_DIR"/scripts/rag.py index

# Search by meaning
uv run "$SKILL_DIR"/scripts/rag.py search "cultural capital and educational attainment"

要进行精确关键词搜索，请直接 grep Markdown 文件：

grep -ril "cultural capital" library/markdown/

使用 reading-agent 技能

要生成结构化阅读笔记，请使用随附的 reading-agent 技能：

/reading-agent

Paper: [Author Year - Title]
PDF: /path/to/paper.pdf
DOI: [doi]

reading-agent 技能负责 PDF 转换，并生成包含以下内容的结构化笔记：

• 书目信息和标识符
• 核心论点和理论框架
• 方法和实证策略
• 主要发现和贡献主张
• 带页码的关键引文

批量处理

要批量处理多篇论文：

1. 转换 PDF：对每篇论文运行 "$SKILL_DIR"/scripts/ingest.py --file
2. 以批处理模式使用 reading-agent：

   /reading-agent
   
   Batch process these papers:
   - /papers/smith2020.pdf (DOI: 10.1086/123456)
   - /papers/jones2019.pdf (OpenAlex: W2123456789)
   

3. 收集输出：笔记保存到 reading-notes/ 目录

---

工作流阶段

阶段 0：语料库审查

目标：评估语料库内容并找出缺口。

流程：

• 查看 lit-search 数据库（或用户的参考文献库）
• 按年份、期刊、作者和理论传统统计论文数量
• 找出可能的覆盖缺口
• 确定哪些论文需要精读，哪些只需略读

输出：在对话中呈现语料库审查结果（统计数据和阅读优先级）。

暂停：用户确认语料库覆盖范围和阅读优先级。

---

阶段 1：精读

目标：精读优先级论文并提取分析见解。

流程：

• 阅读 library/markdown/ 中每篇优先级论文的全文
• 提取：论证结构、理论框架、关键概念、方法论路径
• 记录：理论如何运用、哪些证据支持主张、作者承认的局限
• 创建结构化阅读笔记

输出：包含每篇论文笔记的 reading-notes/ 目录。

暂停：用户审阅关键论文的阅读笔记。

---

阶段 2：理论脉络梳理

目标：识别思想传统和谱系。

流程：

• 识别各论文中出现的理论框架
• 使用 uv run "$SKILL_DIR"/scripts/rag.py search "theoretical concept"，在整个文献库中查找概念相关的段落
• 梳理引用关系（谁引用了谁）
• 记录奠基性文本及其后续发展
• 识别“阵营”或思想流派
• 记录关键概念及其用法

输出：将 ## Theoretical Map 部分写入 field-synthesis.md。

暂停：用户审阅理论图景。

---

阶段 3：主题聚类

目标：根据论文研究的内容和方式对其进行组织。

流程：

• 按实证研究焦点（群体、场景、现象）对论文分组
• 按理论路径对论文分组
• 按方法策略对论文分组
• 识别横跨多个聚类的论文
• 记录各聚类内部的共识与差异

输出：将 ## Thematic Clusters 部分追加到 field-synthesis.md。

暂停：用户审阅聚类逻辑。

---

阶段 4：争论梳理

目标：识别紧张关系、分歧和相互竞争的立场。

流程：

• 找出明确的分歧（相互批评的论文）
• 找出隐含的张力（相互矛盾的发现或不相容的假设）
• 识别该领域正在探讨的未决问题
• 记录证据存在混杂或争议之处
• 记录每项争议的“讨论现状”

输出：将 ## Debate Map 部分追加到 field-synthesis.md。

暂停：用户审阅争论并选择重点领域。

---

阶段 5：领域综合

目标：形成全面的理解，为写作做好准备。

流程：

• 综合各阶段的内容，形成连贯的领域理解
• 找出最有助于作出贡献的研究缺口
• 概述候选贡献，以及每项贡献如何契合用户的项目

输出：完成 field-synthesis.md，整合形成全面理解并列出贡献机会（基于阶段 2–4 中添加的部分）。

---

输出文件

lit-synthesis/
├── reading-notes/            # Phase 1: Per-paper notes (kept for batch production)
│   ├── smith2020-cultural-frames.md    # Filename: author-year-short-title
│   ├── jones2019-institutional.md
│   └── ...                             # Each file has identifier frontmatter
└── field-synthesis.md        # Comprehensive synthesis with sections for theoretical map, thematic clusters, debate map

注意：文件名采用 author-year-short-title.md 格式，以便于阅读；但用于将笔记与源论文匹配的权威信息是前置元数据标识符（citation_key、OpenAlex ID、DOI）。推荐使用 citation_key，因为它支持在后续写作技能中使用 [@citationKey] Pandoc 引用语法。

阅读笔记模板

对于阶段 1 中的每篇论文，笔记必须包含标识符前置元数据，以便在工作流中可靠地检索：

---
# Required: At least one unique identifier
citation_key: smithCulturalFrames2020  # Preferred: from lit-search database or references.bib
openalex_id: W2123456789    # From lit-search database
doi: 10.1086/123456         # Digital Object Identifier

# Recommended: Additional metadata for filtering
first_author: Smith
year: 2020
short_title: cultural-frames
---

# Smith 2020 - Cultural Frames

## Bibliographic Info
- Full citation: [from references.bib or database]
- DOI: [link]
- OpenAlex: https://openalex.org/W2123456789

## Core Argument
[1-2 sentences: What is the paper arguing?]

## Theoretical Framework
- Tradition: [e.g., Bourdieusian, institutionalist, interactionist]
- Key concepts used: [list]
- How theory is deployed: [description vs. extension vs. critique]

## Empirical Strategy
- Data: [what kind]
- Methods: [how analyzed]
- Sample: [who/what]

## Key Findings
1. [Finding 1]
2. [Finding 2]
3. [Finding 3]

## Contribution Claim
[What does the paper claim to contribute?]

## Limitations (as noted by authors)
- [Limitation 1]
- [Limitation 2]

## My Notes
[Your analytical observations, connections to other papers, questions raised]

## Key Quotes
> "[Quote 1]" (p. X)

> "[Quote 2]" (p. Y)

## Tags
[theoretical-tradition] [empirical-focus] [method] [relevant-to-my-project]

模型建议

阶段	模型	理由
阶段 0：语料库审计	Sonnet	数据处理、统计
阶段 1：深入阅读	Sonnet	对转换后的 Markdown 进行分析性阅读
阶段 2：理论映射	Opus	模式识别、思想史
阶段 3：主题聚类	Sonnet	组织、分类
阶段 4：辩论映射	Opus	识别张力、细致分析
阶段 5：领域综合	Opus	整合、战略判断

开始综合分析

用户准备开始时：

1. 确定语料库：

   “你的论文在哪里？一个 PDF 文件夹？来自文献检索的 references.bib？总共有多少篇论文？”

2. 检查本地文献库设置：

   “你的 PDF 是否已转换为 library/markdown/ 中的 Markdown？如果没有，我们会在阶段 1 前对每个 PDF 运行 "$SKILL_DIR"/scripts/ingest.py --file。”

3. 确定优先级：

   “哪些论文对你的项目最重要？我们会先深入阅读这些论文，再快速浏览其余论文。”

4. 明确目标：

   “你想了解这个领域的哪些方面？你是在寻找研究空白、争论，还是特定的理论传统？”

5. 继续进行阶段 0，审计语料库。

重要提醒

• 标识符至关重要：每篇阅读笔记的 frontmatter 中至少必须包含一个唯一标识符（citation_key、OpenAlex ID 或 DOI）。如有 citation_key，优先使用。
• 先转换，再阅读：在阶段 1 开始前，对每个 PDF 运行 uv run "$SKILL_DIR"/scripts/ingest.py --file <pdf>
• 质量重于数量：深入阅读 15 篇论文，胜过快速浏览 50 篇
• 争论带来机遇：你发现的每一处张力，都可能成为潜在的贡献空间