ea-obsidian-world-builder

学术 Obsidian 世界构建器

此技能可将一组学术 PDF 转化为内容丰富、相互关联的 Obsidian 知识网络——一个 Wikipedia 风格的概念笔记网，每篇笔记都包含直接取自文献的原子句，并与其他笔记相链接。

工作流概览

此技能有两种模式。开始任何操作前，请先判断适用哪种模式：

• 构建模式 — 从头创建新的知识网络（阶段 1–4）
• 扩展模式 — 将新论文添加到现有库中（阶段 5）

如果用户提到已有库，或表示想将论文添加到现有网络，请使用扩展模式（阶段 5）。否则，使用构建模式。

构建模式 — 四个依次进行的阶段

必须完整完成每个阶段后，才能开始下一个阶段。论文较多（≥5 篇）或概念较多（≥10 个）时，阶段 1 和阶段 3 可使用并行子 Agent。

1. 提取 — 阅读每篇 PDF，提取文本，并为每篇论文生成结构化数据（概念 + 原子发现）
2. 综合 — 汇总所有论文中的概念，去重，并向用户展示概念列表供其审核
3. 构建知识世界 — 为每个概念生成一篇 Wikipedia 风格的 Obsidian 笔记，填入带引用的原子句和维基链接
4. 论文存根 — 为每篇论文创建参考笔记

开始前，询问用户：

• PDF 所在位置（如果上下文中尚不明确）
• 输出位置（存放笔记的 Obsidian 库文件夹，或新建文件夹）

如果用户可以使用 obsidian:obsidian-cli 技能，请使用它将笔记直接写入其库中。否则，将 .md 文件写入输出目录，并告知用户文件位置。

---

阶段 1：PDF 提取

安装依赖项

pip install pdfplumber --break-system-packages 2>/dev/null

从每个 PDF 提取文本

对每个 PDF 使用随附脚本：

python <skill_dir>/scripts/extract_pdf_text.py "<pdf_path>" "<workspace>/_extracted/<paper_slug>.txt"

脚本会输出纯文本。将所有提取的文本存储在 <workspace>/_extracted/ 中。

如果某个 PDF 提取出的文本很少（< 200 个词），则它可能是扫描版或纯图像 PDF。请记录这一情况并跳过该文件，并在最后告知用户。

从每篇论文中提取结构化数据

阅读每篇论文提取出的文本，并在 <workspace>/_paper_data/<paper_slug>.json 中生成 JSON 文件。

如果论文数量达到 5 篇或更多，请为每篇论文（或每 3 篇论文）启动一个子 Agent，并行处理此任务。 每个子 Agent 会收到：

• 分配给它的论文完整提取文本
• 生成下方 JSON 的说明
• 要写入的输出路径

每个 JSON 文件都必须遵循以下架构：

{
  "title": "Full paper title as it appears in the document",
  "authors": ["Smith J", "Jones K", "Brown L"],
  "year": 2023,
  "citation_key": "Smith 2023",
  "abstract": "The abstract text...",
  "concepts": [
    "biodiversity",
    "climate change",
    "species richness",
    "habitat fragmentation"
  ],
  "findings": [
    {
      "concept": "biodiversity",
      "statement": "Global biodiversity loss is accelerating at rates 100–1000 times above natural background levels.",
      "related_concepts": ["climate change", "habitat fragmentation"],
      "section": "results"
    },
    {
      "concept": "climate change",
      "statement": "Elevated atmospheric CO₂ concentrations correlate with a 2.3°C increase in mean annual temperature across temperate biomes.",
      "related_concepts": ["biodiversity", "species distribution"],
      "section": "discussion"
    }
  ]
}

提取指南：

引用键格式：

• 无论作者人数多少，所有论文都采用 Smith 2023 格式（第一作者姓氏 + 空格 + 年份）
• 如果年份不明确，使用 Smith ND（无日期）
• 始终采用此格式——不要在键中添加“Etal”或包含合著者姓名

概念（每篇论文列出 5–20 个）：

• 同时包含具体概念（例如 “beta diversity”“nitrogen fixation”）和更宽泛的概念（例如 “biodiversity”“ecosystem function”）
• 概念应为名词或名词短语，而不是动词或形容词
• 概念统一使用小写

发现——这是最重要的部分：

• 严格聚焦于结果、讨论和结论——不要纳入引言或文献综述中的论断（这些属于背景内容，并非该论文的贡献）
• 每条发现都应是一个原子句：只包含一项具体论断或测量结果
• 发现应体现论文的自身贡献，而不是对其他研究的引用
• 每个论文实质性论述的概念列出 2–3 条发现——不要只列论文提及的概念
• 仅使用学术语言；保留数值、单位和统计术语（如有）
• related_concepts：论文概念列表中，在同一论断中有实质关联的其他概念
• section："results"、"discussion" 或 "conclusions" 之一

---

阶段 2：概念综合

读取所有 _paper_data/*.json 文件。然后：

1. 收集每篇论文 "concepts" 数组中的所有概念
2. 合并同义词和近似重复项——例如，“biodiversity loss”和“biodiversity decline”→选择更常见或更准确的术语；“CO₂”和“carbon dioxide”→“carbon dioxide”。请自行判断；优先选择具体的术语，而非含糊的术语。
3. 统计每个概念被多少篇不同的论文提及
4. 按论文数量降序排序（跨领域概念排在最前）
5. 如果概念总数超过 30 个，则筛除仅被一篇论文提及的概念——在单独的部分中标记它们，供用户酌情纳入

将概念列表写入 <workspace>/concept_list.md：

# Concept List — Please Review Before Proceeding

I've extracted **N concepts** from **M papers**. Review this list:
- ✏️ Edit names (this becomes the note title)
- ❌ Delete lines you don't want
- ➕ Add new lines for concepts you feel are underrepresented
- The indented lines show which papers discuss each concept

When you're happy, let me know and I'll build the knowledge network.

---

## Core Concepts (discussed in 3+ papers)

- biodiversity (12 papers: Smith 2023, Jones 2022, ...)
- climate change (10 papers)
- species richness (8 papers)

## Supporting Concepts (1–2 papers)

- trophic cascade (2 papers)
- keystone predator (1 paper)

## Concepts I'm Unsure About (possible duplicates — your call)

- biodiversity loss ↔ biodiversity (may overlap)
- CO₂ emissions ↔ carbon dioxide (may overlap)

**向用户展示此文件，并明确请他们审核。**可以这样说：

“这是我从你的所有论文中提取的概念列表。请审核并修改名称、删除无关内容、补充遗漏的概念，然后告诉我你准备好了。我会等你确认后再开始创建笔记。”

未经用户明确确认，不要继续进入阶段 3。

---

阶段 3：构建知识体系

用户确认概念列表后，解析该列表以获取最终批准的概念列表（忽略任何看起来不像概念条目的行）。

为每个概念生成一篇 Obsidian 笔记。**如果概念数量达到 10 个或以上，则按每批 10–15 个概念启动子 Agent。**每个子 Agent：

• 接收分配给它的概念名称批次
• 可以读取所有 _paper_data/*.json 文件
• 扫描所有论文，查找与每个概念相关的发现（而不只是列出该概念的论文）
• 将完成的笔记写入 <vault_output>/Concepts/

笔记结构

每篇概念笔记都遵循以下确切模板：

---
tags: [concept, knowledge-network]
aliases: []
---

# <Concept Name>

<A 2–3 sentence academic definition of this concept, written in your own words. This sets the stage — no citations needed here. Be precise and accurate.>

## <Thematic Section 1>

- <Atomic sentence with [[related concept]] linked inline where it appears.> [[CitationKey]]
- <Atomic sentence linking [[another concept]] where meaningful.> [[CitationKey]]

## <Thematic Section 2>

- <Atomic sentence.> [[CitationKey]]

## Related Concepts

- [[concept-a]] — <5–10 words explaining how it relates to this concept>
- [[concept-b]] — <5–10 words explaining how it relates to this concept>
- [[concept-c]] — <5–10 words explaining how it relates to this concept>

Wikilink 约定

这些是 Obsidian wikilink，必须与批准列表中的概念名称完全一致（Obsidian 不区分大小写，但请保持一致）：

• 概念链接：[[biodiversity]]、[[climate change]]、[[habitat fragmentation]]
  • 每当概念在原子句中有实际意义地出现时，就在行内链接该概念——替换句子中的词或短语本身，不要另行添加链接
  • 仅链接批准概念列表中的概念；不要自行创建链接
  • 也要在底部的“相关概念”部分列出这些链接
• 引用链接：[[Smith 2023]]——始终放在原子句末尾，用独立的方括号括起，并置于句号之后
  • 格式：句子文本。 [[CitationKey]]
  • 不要将引用嵌入句子中间

原子句规则

原子句是归属于单一来源的一项可验证论断。它必须：

• 仅表达一项论断
• 具体——尽可能提供量化信息，绝不含糊
• 使用学术语言——不使用口语表达
• 最多为1–2 个句子（偶尔可用 2 个句子，但仅限内容不可分割的情况）
• 来自论文的自身研究发现，而非其背景引用
• 对论断中出现的批准列表概念添加行内 wikilink——在句子中替换该术语：[[Habitat fragmentation]] reduces [[species richness]] in old-growth temperate forests. [[Pereira 2022]]
• 如果句子中没有自然出现的批准概念，则无需添加行内链接——不要强行添加链接

相关概念规则

“相关概念”部分必须：

• 列出所有与本条概念有实质关联的已批准概念
• 使用项目符号列表，每行一个概念：- [[concept]] — <关系短语>
• 关系短语必须为 5–10 个词，说明具体关联——不要泛泛描述链接概念，而要说明它与本条概念的联系
• 良好示例：
  • - [[poleward shift]] — most range shifts move poleward specifically
  • - [[habitat fragmentation]] — reduces corridors needed for range expansion
  • - [[species richness]] — declines as ranges contract under warming
• 不良示例（过于含糊，或只是在定义概念）：
  • - [[poleward shift]] — a type of range shift ✗
  • - [[habitat fragmentation]] — fragmentation of natural habitats ✗

主题部分

将原子句分组为每条笔记 2–5 个主题部分。选择适合概念的标题。合适的选项包括：全球趋势、作用机制、测量与指数、区域模式、生态影响、政策影响、方法学考量、干预与恢复、驱动因素、与其他因素的关系。

并非每条笔记都需要相同的部分——根据内容灵活安排。

覆盖要求

每条概念笔记至少应包含来自至少 2 篇不同论文的 3 个原子句（如有）。如果某个概念只在一篇论文中讨论，请写出相关内容，并用提示块注明：

> [!note] Limited sources
> This concept is currently documented from a single paper. Consider adding more literature.

---

第 4 阶段：论文占位笔记

在 <vault_output>/Papers/<CitationKey>.md 中为每篇论文创建一条笔记：

---
tags: [paper]
title: "<Full paper title>"
authors: [<comma-separated author list>]
year: <year>
citation_key: <CitationKey>
---

# [[<CitationKey>.pdf|<Full paper title>]]

> [!abstract]
> <Abstract text>

## Key Concepts

[[concept-a]] | [[concept-b]] | [[concept-c]]

## Main Contributions

- <One atomic sentence summarising each major finding from this paper>
- <Another finding>

“Key Concepts”行应列出该论文涉及的已批准概念列表中的所有概念。

---

质量检查

在宣布完成前，请确认：

1. 每条概念笔记至少有 3 个原子句（或包含“Limited sources”提示块）
2. 每个原子句末尾都有一个 [[CitationKey]] 双链链接
3. “Related Concepts”部分至少有 2 个条目，每个条目都包含非泛化的关系短语
4. 所有概念笔记中使用的每个引用键都对应一条论文占位笔记
5. 没有孤立概念——每个概念都至少出现在另一条笔记的“Related Concepts”部分中

如果任何检查未通过，请先修正，再提交输出。

---

呈现结果

写完所有笔记后，告知用户：

• 创建的概念笔记总数
• 创建的论文占位笔记总数
• 引用次数最多的前 5 个概念（按其出现于多少个原子句中计算）
• 跳过的 PDF（扫描版／无法读取）
• 已批准列表中最终少于 3 个句子的概念（覆盖有限）

示例：

✅ 已在你的 Obsidian 知识库中创建 47 条概念笔记和 18 条论文占位笔记。

**关联最多的概念：**生物多样性（34 个句子）、气候变化（28）、物种丰富度（21）、栖息地破碎化（19）、生态系统功能（17）

跳过的 PDF：jones_2019_scan.pdf（仅含图像，无法提取文本）

覆盖有限：“keystone predator”（仅 1 篇论文，2 个句子）

---

关于大型论文集的说明

对于非常大的文献集（30 篇以上），提取过程可能耗时较长。请及时向用户更新进度：

• “正在处理第 5/30 篇论文……”
• “概念综合完成——在 30 篇论文中发现 68 个独特概念”
• “正在并行创建概念笔记——第 1/4 批进行中……”

透明地汇报进度，能让等待更有意义。

---

第 5 阶段：扩展——向现有知识库添加新论文

当用户已使用此技能建立知识网络，并希望将一篇或多篇新论文整合进其中时，请使用此阶段。

开始之前

在进行任何其他操作之前，务必先发出以下警告：

⚠️ **继续之前，请备份你的知识库。**扩展网络会直接修改现有的概念笔记。如果出现问题，你需要能够恢复这些笔记。请将 Concepts/ 和 Papers/ 文件夹复制到安全位置，然后告诉我你已准备就绪。

等待用户确认已完成备份后再继续。

然后询问：

• 新 PDF 的存放位置
• 现有知识库的位置（Concepts/ 和 Papers/ 文件夹的路径）

---

第 5.1 步：提取新论文数据

仅对新论文运行阶段 1（PDF 提取），并像往常一样将结果写入 <workspace>/_extracted/ 和 <workspace>/_paper_data/。

---

第 5.2 步：识别概念——新概念与现有概念

读取现有知识库：扫描 Concepts/ 中的所有 .md 文件，并收集笔记标题作为现有概念列表。

从新论文的提取数据中收集其中的概念。然后对每个概念进行分类：

• 现有概念——与知识库中已有的概念匹配（或近义）
• 新概念——知识库中确实没有的概念

在进行任何更改之前，先向用户展示分类结果：

Here's what I found in the new paper(s):

**Concepts already in your vault** (will be expanded with new sentences):
- biodiversity (matches existing note)
- species richness (matches existing note)
- climate change (matches existing note)

**New concepts not yet in your vault** (new notes will be created):
- thermal tolerance
- microhabitat heterogeneity

**Possible overlaps — your call:**
- "range contraction" ↔ existing "range shift" — treat as same or separate?

Shall I proceed with this plan, or would you like to adjust anything?

**在用户确认之前，不要修改任何文件。**用户可能希望合并、重命名或跳过某些概念。

---

第 5.3 步：更新现有概念笔记

对于新论文涉及的每个现有概念，打开 Concepts/<concept>.md 中对应的概念笔记，并添加来自论文的原子句子。

更新规则：

• 找到最合适的主题章节，并在其中追加新句子。如果没有合适的现有章节，就新建一个章节。
• 不要删除或更改任何现有内容——只添加内容。
• 遵循所有原子句子规则（行内概念维基链接，末尾附引用链接）。
• 如果新论文提出了该概念与 Related Concepts 部分中尚未列出的概念之间的关系，请使用关系短语将其添加进去。

---

第 5.4 步：创建新概念笔记

对于分类为新概念的内容，按照阶段 3 的相同模板和规则，生成完整的概念笔记。将这些新笔记与相关的现有概念交叉链接——在原子句子中和 Related Concepts 部分中都要添加。

同时检查反向关系：对于与某个新概念存在实质关联的现有概念，打开该现有概念笔记，并将新概念添加到其 Related Concepts 部分。

---

第 5.5 步：创建论文存根

按照阶段 4 的模板，为新论文在 Papers/<CitationKey>.md 中创建论文存根。

---

第 5.6 步：展示扩展摘要

所有编辑完成后，向用户提供清晰的摘要：

✅ Expansion complete.

**New paper added:** Smith 2024 — "Full title here"

**Existing concept notes updated (N):**
- [[biodiversity]] — 3 new sentences added (Results, Drivers sections)
- [[species richness]] — 2 new sentences added (Regional Patterns section)
- [[climate change]] — 1 new sentence added; also added new related concept [[thermal tolerance]]

**New concept notes created (N):**
- [[thermal tolerance]] — 4 sentences from Smith 2024
- [[microhabitat heterogeneity]] — 3 sentences from Smith 2024

**Anything worth noting:**

利用最后一部分标出任何值得注意的情况，例如：

• 某个新概念与许多现有概念的联系异常紧密
• 某项发现似乎与知识库中已有内容存在冲突（例如，同一概念上出现相互矛盾的论断）
• 新论文中的某个概念异常孤立（与网络其他部分的链接很少）
• 某个现有概念笔记现在的句子数量远多于其他笔记，可能需要拆分

保持此部分简短具体——只提及真正突出的情况，不要写泛泛而谈的观察。