Mortimer

以 Mortimer J. Adler 命名——将检视、分析与主题阅读转化为证据优先的自适应全文精读流程。

自动获取书籍或论文内容，利用 Gemini 的长上下文能力进行证据优先的结构化精读，并将精华笔记、知识卡和文章写入 Obsidian。

支持两种交互方式：Claude Code 终端（完整功能）和 Claudian（Obsidian 插件）（笔记上下文感知）。底层统一入口现为 tools/read.py，内部再分流到 book / paper / batch。

下载/查看 HTML 原稿（本地打开可导出 Copy / PNG / PDF）

系统架构

下载/查看 HTML 原稿（本地打开可导出 Copy / PNG / PDF）

图示使用 Cocoon AI Architecture Diagram Generator v1.1 设计系统生成；HTML 原稿为自包含 SVG，README 展示高分辨率 PNG。

文本速览

用户 ──→ Claude Code (/read 技能编排)
         │
         ├─ 终端模式 (CLI)
         │   └─ 完整功能：单本 + 批量 + 自由探索
         │
         └─ Claudian 模式 (Obsidian 内嵌)
             └─ 同一 /read 技能，额外感知当前编辑的笔记
         │
         ├─ 单本模式: 书籍 / 论文阅读
         │   书籍：完整正文 → 阅读画像 → 证据账本 → 精读+知识卡+文章 → 质量门禁
         │   论文：元数据 → 最优内容源 → 摘要卡+方法结果+证据评估
         │
         └─ 批量模式: 书单驱动全自动
             书单准备 → 批量搜索下载 → 并行分析 → 验证完整性
         │
         ├── Anna's Archive ─── 书籍搜索与下载
         ├── AlphaXiv / PMC ─── 论文 Markdown / XML 内容源
         ├── extract_book.py ── EPUB/PDF/TXT 文本提取
         ├── paper_fetch.py ─── 论文 provider 路由与 bundle 生成
         ├── adaptive_reader.py ─ 自适应读法、证据账本、知识与文章
         ├── Gemini ─────────── 书籍 / 论文长上下文分析
         ├── Obsidian ───────── 笔记写入
         └── Google Drive ──── 备份 (rclone，可选)

分工: Claude Code 负责编排和用户交互，Gemini 负责全书文本分析。Claude 从不直接读取书籍原文——正式精读通过 adaptive_reader.py，自由追问和深挖通过 gemini_analyzer.py。

两种模式对比:

	终端 (CLI)	Claudian (Obsidian)
触发方式	终端输入 `/read 书名`	Obsidian 内输入 `/read 书名`
单本模式	✅	✅
批量模式	✅	✅
笔记上下文感知	❌	✅ 自动注入当前编辑的笔记
额外进程	无	独立 Claude Code 进程 (~300MB)
适用场景	首次阅读、批量处理	在 Obsidian 中浏览笔记时追问、深度探索

功能

单本模式

能力	说明
一键读书	输入书名，自动完成搜索、下载、分析、笔记全流程
单篇论文	输入 arXiv URL / arXiv ID / PDF / DOI / PMID，自动获取最优内容源并生成论文笔记
证据优先精读	完整正文只做一次证据提取，概览、精读、知识卡和文章复用同一证据账本
自适应阅读画像	领域 `category` 与读法 `form` 分离，支持论证、实证、实践、传记、历史、文学、技术及复合类型
知识与文章沉淀	自动生成知识卡、实践清单、文章选题和一篇核心精华文章
语义质量门禁	检查来源定位、边界条件、反例、章节覆盖、笔记重复度和文章证据引用
断点续读	检测 Obsidian 已有笔记，从断点继续

精读完成后进入自由探索阶段：

操作	说明
深度探索	选择推荐视角或自定义主题，生成结构化深度笔记（`03-深度-{主题}.md`）
全部探索	一次性并行生成 5 个推荐视角的深度笔记
自由提问	基于全文回答任意问题，直接展示答案，不写入笔记
结束阅读	标记阅读状态为 completed

批量模式

能力	说明
书单驱动	提供 Markdown 书单、JSON 文件或直接粘贴书目；支持 mixed `doc_type`
批量搜索下载	Anna's Archive 评分选择最佳候选，支持中英混合文件名识别、低质量候选预警与断点续跑
TPM 感知并行	动态令牌桶调度，最多 5 本并行，并通过批量安全模式降低 429 风险
完整性验证	书籍检查 8 个阅读产物与语义质量状态；论文检查 3 个论文产物
失败处理	重试或降级到单本模式逐个处理

分析引擎

Evidence-first Map-Reduce: 超长书籍只做一次分片证据提取，后续阶段复用账本
批量安全模式: 在批量场景下自动收敛长书内部并发，避免配额突刺
Content-addressed Cache: 按正文哈希、模型、Prompt 版本、阶段和阅读画像缓存，避免旧内容误命中
Adaptive methods: category 负责领域，form + goal 决定读法与产物侧重点
Call-level TPM guard: 多进程共享 60 秒 TPM 窗口，减少 reducer 阶段的配额突刺
Paper provider routing: 单篇论文优先走 AlphaXiv Markdown -> PMC XML -> PDF fallback

安装

前置条件

Python 3.10+
pdftotext — PDF 文本提取
Claude Code — 流程编排
Obsidian + obsidian CLI — 笔记写入
rclone — Google Drive 备份

云备份细节见 CLOUD.md。

# macOS
brew install poppler
brew install rclone

# 克隆
git clone https://github.com/anon019/Mortimer.git
cd Mortimer

# 配置环境变量
cp .env.example .env
# 编辑 .env，填入 GEMINI_API_KEY

安装 /read 技能

mkdir -p ~/.claude/skills/read
cp -R skill/. ~/.claude/skills/read/

# 编辑 SKILL.md，将 ~/coding/read 替换为你的实际克隆路径

Claudian 集成（可选）

Claudian 是一个 Obsidian 插件，在 vault 内嵌入 Claude Code 作为 AI 协作者。安装后可直接在 Obsidian 中使用 /read 技能。

原理：Claudian 通过 Claude Agent SDK 启动本机的 claude CLI 作为子进程，工作目录设为 Obsidian vault。它加载 user 级 skill（~/.claude/skills/），因此已安装的 /read 技能可直接使用。

配置步骤：

在 Obsidian 中安装 Claudian 插件
确保 Claudian 设置中 loadUserClaudeSettings 为 true（默认已开启）
开放工具链路径——编辑 Claudian 设置（Obsidian 设置 → Claudian，或直接编辑 .claude/claudian-settings.json）：

{
  "persistentExternalContextPaths": [
    "<Mortimer 克隆路径>",
    "/tmp"
  ]
}

为什么需要这一步？ Claudian 有 vault restriction hook，默认拒绝访问 vault 外路径。Mortimer 克隆路径是工具链目录，/tmp 是 Gemini 分析器的临时文件路径，两者都需要开放。

重启 Obsidian 或新建 Claudian 会话使配置生效

验证：在 Claudian 中输入 /read Atomic Habits，应能正常启动阅读流程。

Claudian 特有优势：

在 Obsidian 中浏览已生成的读书笔记时，Claudian 会自动将当前笔记内容注入上下文。这意味着：

打开 02-精读.md 后直接说"探索第 3 个视角"，无需指定书名
选中一段笔记内容，问"展开讲讲这个观点"
打开两本书的笔记，问"对比这两本书的观点"

环境变量

变量	必需	说明
`GEMINI_API_KEY`	是	Google AI Studio API key
`GEMINI_MODEL`	否	覆盖默认模型（默认 `gemini-3-flash-preview`）
`GEMINI_GLOBAL_TPM_LIMIT`	否	多进程共享的调用级 TPM 上限；批量流程自动设置
`READ_CACHE_DIR`	否	内容寻址分析缓存目录（默认 `.read-cache`）
`READ_RESULT_CACHE_HOURS`	否	旧式追问/深挖结果缓存时长（默认 720 小时）
`ANNAS_ARCHIVE_KEY`	否	Anna's Archive 会员 key，搜索免费，下载需要
`OBSIDIAN_VAULT_PATH`	否	Obsidian vault 路径（默认 `~/Documents/Obsidian Vault`）
`OBSIDIAN_USE_CLI`	否	设为 `0` 时跳过 Obsidian CLI，直接写入指定 vault；测试或多 vault 场景推荐
`RCLONE_REMOTE`	否	覆盖默认 Drive remote 名称（默认 `mortimer-books`）
`RCLONE_UPLOAD_WORKERS`	否	批量补传并发数（默认 `3`）

使用

/read 技能（推荐）

单本：

/read 史蒂夫·乔布斯传
/read Atomic Habits
帮我读一下穷查理宝典
/read https://arxiv.org/abs/1706.03762

批量：

/read booklists/my-list.md
/read booklists/my-list.json
帮我批量读这 10 本书：<粘贴书单>
python3 tools/read.py booklists/my-list.md --download-confirm --verify

命令行

# 搜索
python3 tools/annas-archive/annas.py search "Steve Jobs Walter Isaacson" --format epub --limit 5

# 下载
python3 tools/annas-archive/annas.py download <md5> --output books/

# 提取文本
python3 tools/extract_book.py books/steve-jobs.epub -o /tmp/book_stevejobs.txt

# 证据优先的完整阅读
python3 tools/adaptive_reader.py --book /tmp/book.txt --title "书名" --author "作者" --category finance --output-dir /tmp/read-output

# 自由追问和深挖
python3 tools/gemini_analyzer.py overview-skim --book /tmp/book.txt --title "书名" --author "作者" --category biography
python3 tools/gemini_analyzer.py deep-read    --book /tmp/book.txt --title "书名" --author "作者" --category biography
python3 tools/gemini_analyzer.py deep-dive    --book /tmp/book.txt --title "书名" --author "作者" --category biography --topic "主题"
python3 tools/gemini_analyzer.py ask          --book /tmp/book.txt --title "书名" --author "作者" --question "问题"

# 单本全流程 (提取 → 分析 → Obsidian)
bash tools/process_book.sh "books/book.epub" "书名" "作者" "category" "年份" "prefix"

# 单篇论文全流程 (元数据 → provider → 分析 → Obsidian)
bash tools/process_paper.sh "https://arxiv.org/abs/1706.03762" "Attention Is All You Need" "Ashish Vaswani; Noam Shazeer" "science" "2017" "attention"

# 统一入口
python3 tools/read.py books/book.epub --doc-type book --title "书名" --author "作者" --category finance --form auto --goal understand-and-write
# 忽略旧分析缓存并重新生成
python3 tools/read.py books/book.epub --doc-type book --title "书名" --author "作者" --category finance --no-cache
python3 tools/read.py https://arxiv.org/abs/1706.03762 --category science
python3 tools/read.py booklists/list.md --download-confirm --verify

# 批量流程
python3 tools/booklist_to_json.py booklists/list.md          # MD → JSON
python3 tools/batch_download.py booklists/list.json           # 搜索候选
python3 tools/batch_download.py booklists/list.json --confirm # 下载
python3 tools/batch_read.py booklists/list.json               # 并行分析（book 或 mixed doc_type JSON）
python3 tools/batch_read.py booklists/list.json --dry-run     # 预览计划
python3 tools/batch_verify.py booklists/list.json             # 验证完整性（book 或 mixed doc_type JSON）
python3 tools/rclone_upload.py ensure-remote                  # 检查 rclone 远端是否可用
python3 tools/rclone_upload.py upload books/<file> <category> # 单本备份到 Google Drive
python3 tools/batch_upload_cloud.py booklists/list.json       # 按书单 category 批量补传 Google Drive

Google Drive 备份默认走 rclone，具体配置与约束见 CLOUD.md。

先在本机执行一次 rclone config，创建名为 mortimer-books 的 Google Drive remote
这个 remote 应该直接锁定到你的 Books/ 文件夹；不要把项目代码写成依赖整盘根目录
如果本机已存在该 remote，只需在需要时执行 rclone config reconnect mortimer-books:
运行期只需要 RCLONE_REMOTE 这个覆盖项；默认值是 mortimer-books
batch_download.py --confirm 在每本书下载、校验、重命名后会立即上传到 Drive
batch_upload_cloud.py 是补传入口，用于处理历史漏传或上传失败重试
批量补传默认使用小并发（RCLONE_UPLOAD_WORKERS=3），避免把 Drive API 打满

如果使用 mixed JSON，可在条目中加入：

{
  "id": 1,
  "doc_type": "paper",
  "title": "Attention Is All You Need",
  "author": "Ashish Vaswani; Noam Shazeer",
  "category": "science",
  "year": "2017",
  "arxiv_id": "1706.03762",
  "paper_type": "paper"
}

如果你希望 Markdown 书单本身就能无损转回 mixed JSON，可在搜索行后增加一行机器元数据：

`2025 ESC Clinical Consensus Statement on mental health and cardiovascular disease|pdf`
<!-- read-meta: doc_type=paper; paper_type=guideline; doi=10.1093/eurheartj/ehaf191; pmid=40878270; url=https://pubmed.ncbi.nlm.nih.gov/40878270/ -->

标准流程

推荐型书单和批量阅读默认按这条 SOP 走：

明确需求：先确认主题、学习目标、数量、是否经典优先、是否排除历史书单/本地已有、是否包含 paper
先做本地查重：检查仓库 booklists/*.md、Obsidian Reading/书单/、本地 books/、Obsidian Reading/<category>/
组候选池：优先选“经典 + 贴合目标 + 彼此互补”的书，不要只按热度堆书
先写两份书单：仓库 booklists/ 和 Obsidian Reading/书单/
给用户先 review 主题覆盖、重复项、下载可行性；需要改动时直接回写到书单文件
用 booklist_to_json.py 转 JSON，并搜索候选；脚本会给出 needs_review 提示（低分、分差小、标题疑似低质量）供你逐一确认，再下载
用 batch_download.py --confirm 下载；下载成功的书会立即备份到 Google Drive
用 batch_read.py 批量分析并写入 Obsidian
用 batch_verify.py 做最终完整性验证

现在也可以直接用统一入口跑完整流程：

python3 tools/read.py booklists/list.md --download-confirm --verify

如果云端有漏传，再用 batch_upload_cloud.py 补传

Obsidian 输出结构

Reading/{category}/{书名} ({作者}, {年份})/
├── 00-概览.md            ← 阅读画像、核心主题、精简路径
├── 01-粗读.md            ← 覆盖完整结构的全书地图
├── 02-精读.md            ← 跨章证据链、反例、边界、主动回忆
├── 03-知识卡片.md        ← 可复用的原子知识
├── 04-实践清单.md        ← 实验、指标或观察清单
├── 05-文章选题.md        ← 5 个有证据基础的写作方向
├── 06-文章-核心精华.md   ← 完成的一篇核心文章
└── 07-质量报告.md        ← 来源、覆盖、重复度和质量状态

论文输出：

Reading/papers/{category}/{标题} ({第一作者}, {年份})/
├── 00-摘要卡.md
├── 01-方法与结果.md
└── 02-证据评估.md

11 个领域分类仍用于目录：health, biography, business, psychology, self-growth, technology, history, philosophy, finance, literature, science。阅读方法另分为 argument, empirical, practical, biography, history, literature, technical。

书单格式

## 传记 (Biography)

**1. 史蒂夫·乔布斯传** — Walter Isaacson
`steve jobs walter isaacson|epub`

**2. 埃隆·马斯克传** — Walter Isaacson
`elon musk walter isaacson|epub`

## 商业 (Business)

**3. 从零到一** — Peter Thiel
`zero to one peter thiel|epub`

推荐型书单约定：

默认双写两份：仓库入口书单写到 booklists/YYYY-MM-DD.md；如果同一天有多份或不能覆盖已有书单，改用 booklists/YYYY-MM-DD-topic-slug.md
Obsidian 书单写到 ~/Documents/Obsidian Vault/Reading/书单/YYYY-MM-DD 主题书单.md；如果设置了 OBSIDIAN_VAULT_PATH，则使用该 vault 下的 Reading/书单/
两份书单的主题、书目、搜索行、推荐理由、阅读路径保持一致；Obsidian 版可额外带 frontmatter
健康管理主题默认使用 health 作为物理目录分类，统一写入 Reading/health/
新书单默认同时对四个地方查重：booklists/*.md、Obsidian Reading/书单/、本地 books/、Obsidian Reading/<category>/
查重时要把双语标题、括号副标题和中英文顺序变化视为同一本，不只看完全同名
每本书都要写详细推荐理由，至少说明：为什么推荐这本、它解决什么问题或补哪一块、它适合放在这份书单的什么位置
推荐型批量流程默认是：先写书单并给用户 review，再转 JSON、搜索候选、检查低质量候选，最后才下载和批量阅读
推荐时默认剔除或降权：导读、摘要、workbook、合集、儿童版、明显重复修订版，以及与主题关系过弱的泛商业畅销书
多轮沟通里如果用户改主题、增删书目或改推荐理由，直接更新书单文件；如果改动了书目、搜索行或 read-meta，要重建 JSON，并视情况重跑候选搜索

工具一览

工具	用途
`tools/adaptive_reader.py`	完整正文 → 阅读画像 → 证据账本 → 8 个阅读产物
`tools/reading_methods.py`	复合阅读画像与七种基础读法
`tools/reading_quality.py`	来源定位、边界、反例、重复度和结构验证
`tools/gemini_analyzer.py`	Gemini API、上下文缓存、共享 TPM、自由追问和深挖
`tools/extract_book.py`	EPUB/PDF/TXT → 纯文本 + 目录索引
`tools/annas-archive/annas.py`	Anna's Archive 搜索与下载（mirror 自动切换）
`tools/process_book.sh`	单本全流程（提取 → 分析 → 写入 Obsidian，CLI 失败时回退直写 vault）
`tools/batch_download.py`	批量搜索 + 下载（评分选择、断点续传）
`tools/batch_read.py`	TPM 感知并行分析（令牌桶、checkpoint）
`tools/batch_verify.py`	笔记完整性验证（模糊匹配、frontmatter 检查）
`tools/booklist_to_json.py`	Markdown 书单 → JSON
`tools/rclone_upload.py`	rclone remote 校验 + 上传/校验
`tools/batch_upload_cloud.py`	云端批量补传（rclone + category 路径）

兼容性

平台	支持	说明
Claude Code (终端)	完整	安装 SKILL.md 后 `/read` 即用，单本+批量全支持
Claudian (Obsidian)	完整	需配置 `persistentExternalContextPaths`，额外支持笔记上下文感知
其他编程工具	工具层	Python 脚本独立可用，SKILL.md 可作为指令文档参考
纯命令行	完全	所有工具都是标准 CLI，可手动使用

技术特点

零 pip 依赖 — 全部 Python stdlib（urllib, json, zipfile, xml.etree）
系统依赖仅 pdftotext — brew install poppler（处理 PDF 时需要）

License

MIT

FilesExpand file tree

README.md

Latest commit

History