文献管理器

管理学术文献集合：搜索 → 下载 → 转换 → 归档 → 校验。

依赖项

• pdftotext（poppler-utils）—— PDF 文本提取
• curl —— 下载工具
• python3 —— audit 中的 JSON 处理
• file（coreutils）—— PDF 文件有效性校验
• uvx markitdown[pdf]（可选）—— 作为 PDF→MD 转换的备用方案（注意：纯 uvx markitdown 不支持 PDF 转换，必须使用 uvx markitdown[pdf]）

快速开始

# 通过 DOI 下载单篇论文
bash scripts/download.sh "10.1038/s41592-024-02200-1" output_dir/

# 将 PDF 转为 Markdown
bash scripts/convert.sh paper.pdf output.md

# 校验单个 PDF+MD 对
bash scripts/verify.sh paper.pdf paper.md

# 对 references/ 目录执行完整审计
bash scripts/audit.sh /path/to/references/

工作流

1. 搜索

在 Google Scholar 上使用 web_fetch：

https://scholar.google.com/scholar?q=QUERY&as_ylo=YEAR

提取字段：标题、作者、年份、期刊、DOI、PDF 链接。

对每条结果，识别最佳的开放获取 PDF 来源（参见“下载策略”）。

2. 下载

对每篇论文运行 scripts/download.sh 。脚本按以下顺序尝试各来源：

1. 出版商直连 PDF（Nature、eLife、Frontiers、PNAS、bioRxiv、arXiv）
2. EuropePMC（通过 PMC_ID 获取 PDF）
3. bioRxiv/arXiv 预印本
4. Sci-Hub —— https://sci-hub.box/（仅在出版商设付费墙时启用）

# Sci-Hub 下载示例：
curl -L "https://sci-hub.box/10.1038/nature12345" -o paper.pdf

⚠️ 法律提示： Sci-Hub 在部分司法管辖区可能违反出版商服务条款或版权法。请确保您已充分理解并自愿承担所在地区适用的法律风险。

若所有来源（含 Sci-Hub）均失败，则标记为永久性付费墙。向用户返回 DOI，并提示其手动下载。

3. 转换

运行 scripts/convert.sh 。默认使用 pdftotext（稳定可靠），以 uvx markitdown[pdf] 作为备用方案。

# 正确的 PDF 转换命令：
uvx markitdown[pdf] input.pdf > output.md

# ⚠️ 下列命令不适用于 PDF（缺少 [pdf] 扩展）：
# uvx markitdown input.pdf

当需高保真还原（如表格、图表标题等）时，优先选用 uvx markitdown[pdf] 而非 pdftotext。

4. 归档

标准目录结构如下：

references/
├── README.md              # 人工索引（按类别分组的摘要）
├── index.json             # 机器索引（结构化元数据）
├── RESOURCES.md           # 代码仓库 + 数据集列表
├── resources.json         # 结构化版本
├── /
│   ├── papers/            # PDF 文件
│   └── markdown/          # 转换后的文本
└── /
    ├── papers/
    └── markdown/

类别由用户自定义；建议使用数字前缀控制排序（例如：01-theoretical-frameworks/）。

index.json 中单篇论文的 Schema

{
  "id": "short_id",
  "title": "Full title",
  "authors": ["Author1", "Author2"],
  "year": 2024,
  "journal": "Journal Name",
  "doi": "10.xxxx/...",
  "category": "category_name",
  "subcategory": "optional",
  "pdf_path": "category/papers/filename.pdf",
  "markdown_path": "category/markdown/filename.md",
  "tags": ["tag1", "tag2"],
  "one_line_summary": "English one-liner",
  "key_concepts": ["concept1"],
  "relevance_to_project": "English description"
}

README.md 编写规范

每个类别下，按论文逐条列出：标题、作者、年份、期刊、DOI、以及用户语言撰写的简明摘要。

4b. 基于 DOI 的文件命名与路径映射

下载的文件常采用 DOI 格式而非 AuthorYear 命名：

10-1038_ncomms3018.md        # DOI: 10.1038/ncomms3018
10-1016_j-neuron-2015-03-034.md

当 index.json 中的 markdown_path 因目录结构调整而失效时，应维护一个独立的映射文件：

// temp/paper_md_mapping.json
{
  "author2024_keyword": "references/new-downloads/10-1038_s41592-024-02200-1.md",
  ...
}

构建该映射的方法：将 index.json 中每篇论文的 DOI 与磁盘上实际存在的文件进行交叉比对。可通过 find + Python 自动完成。

index.json 常见陷阱

• id: null 数据损坏：若大量条目 id=null 且共享相同 pdf_path，说明批量写入过程中索引已损坏。请基于磁盘上的真实文件重建。
• DOI 错误：务必验证 DOI 是否可正确解析——DOI 字段中常见的拼写错误（如末尾数字错误）需通过出版商页面反复核对。
• 失效的 markdown_path：目录结构调整后，index.json 中的 markdown_path 常指向旧路径。此时应以上述映射文件为准。

5. 校验

运行 scripts/audit.sh 执行全量校验：

• 每份 PDF 均为有效文件（file -b 输出含 “PDF”）
• 每份 PDF 的标题与文件名一致（pdftotext | head 提取）
• 每份 PDF 均有对应 Markdown 文件（反之亦然）
• index.json 格式合法、内容完整、所有路径存在、无重复 ID
• README.md 中统计数字与实际文件数量一致

6. 收集资源

针对工具类/方法论文，查找其 GitHub 仓库及公开数据集，统一记录至 RESOURCES.md 与 resources.json。

子智能体策略

处理大批量任务时，采用并行化分工：

• 下载：每批约 5–8 篇论文分配一个子智能体
• 归档：由一个子智能体统一构建索引
• 校验：由一个独立子智能体执行（不得复用归档智能体）

校验环节必须由专用子智能体完成（质量控制不可自我评分）。

⚠️ 子智能体运行规范（来自实践经验）

1. 一次仅处理一个批次 —— 切勿同时启动多个笔记撰写批次；LLM 调用频次限制将导致静默失败
2. 启动长时运行智能体时，必须配置 cron 监控 —— 智能体可能静默失败且不触发自动通知；cron 可及时捕获异常
3. cron 监控模式：

   1. 启动智能体（们）
   2. 立即设置 cron 任务（每 10–15 分钟执行一次，隔离 agentTurn）
      → 检查预期输出文件是否存在
      → 对失败任务重新启动智能体
      → 全部完成后：发送通知 + 清除 cron 任务
   3. 任务结束后，确认 cron 已被移除
   

增量添加论文

向已有文献库中新增论文的操作流程：

1. 将新论文下载并转换后，存入对应类别目录
2. 向 index.json 追加新条目
3. 更新 README.md 中的统计信息
4. 运行 audit 校验整体一致性