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

Name		Name	Last commit message	Last commit date
assets/diagrams		assets/diagrams
skill		skill
tests		tests
tools		tools
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLOUD.md		CLOUD.md
README.md		README.md

Navigation Menu

Repository files navigation

Mortimer

系统架构

文本速览

功能

单本模式

批量模式

分析引擎

安装

前置条件

安装 /read 技能

Claudian 集成（可选）

环境变量

使用

/read 技能（推荐）

命令行

标准流程

Obsidian 输出结构

书单格式

工具一览

兼容性

技术特点

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Mortimer

系统架构

文本速览

功能

单本模式

批量模式

分析引擎

安装

前置条件

安装 /read 技能

Claudian 集成（可选）

环境变量

使用

/read 技能（推荐）

命令行

标准流程

Obsidian 输出结构

书单格式

工具一览

兼容性

技术特点

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages