paperforge 1.5.1

PaperForge — Obsidian + Zotero literature pipeline CLI

PaperForge

简体中文 · English

铸知识为器，启洞见之明。 — Forge Knowledge, Empower Insight.

PaperForge 让你在 Obsidian 里管理 Zotero 文献。同步、OCR 全文提取、图表解析、AI 精读，全在一个 Vault 里完成。

---

0. 先理解它是什么

PaperForge 不是一个纯 Obsidian 插件。它有两部分：

部分	是什么	干什么	装在哪
Obsidian 插件	main.js + manifest.json + styles.css	Dashboard、按钮、设置界面	Vault 的 .obsidian/plugins/paperforge/
Python 包	paperforge	同步、OCR、Doctor、修复	系统 Python 环境 (pip install)

插件是壳，Python 包是引擎。插件里的按钮点了之后，实际是调用 Python 命令行去干活。

所以装完插件之后，必须在设置里确认 Python 包也已安装，并且版本一致。

---

1. 安装 Obsidian 插件

方式一：BRAT（推荐）

1. 在 Obsidian 社区插件市场搜索安装 BRAT（Beta Reviewer's Auto-update Tester）
2. 打开 BRAT 设置 → Add Beta Plugin
3. 填入仓库地址：https://github.com/LLLin000/PaperForge
4. BRAT 会自动下载最新 Release 的 main.js、manifest.json、styles.css 并安装
5. 在 Obsidian 设置 → 社区插件 → 启用 PaperForge

BRAT 能自动检测 GitHub Release 更新，不需要手动下载。

方式二：手动下载

1. 打开 Releases 页面
2. 下载最新版本的三个文件：main.js、manifest.json、styles.css
3. 在 Vault 里创建文件夹 .obsidian/plugins/paperforge/
4. 把三个文件放进去
5. 重启 Obsidian → 设置 → 社区插件 → 启用 PaperForge

手动安装不会自动更新，每次新版本需要重新下载替换。

---

2. 安装 Python 包

插件装好后，打开 PaperForge 设置页面。你会看到 运行时状态 区域：

插件 v1.5.0 → Python 包 v1.5.0 ✓ 匹配

• 如果显示"未安装" → 点击 打开安装向导 重新执行安装流程
• 如果显示"版本不匹配" → 插件更新时 Python 包会自动同步升级，如果没成功，点 更新运行时 手动触发

---

3. Python 解释器识别逻辑

PaperForge 需要找到你系统里的 Python。它按以下顺序查找，找到就用：

优先级	来源	说明
1	你手动指定	设置 → 自定义 Python 路径，填入完整路径（如 C:\Users\你的用户名\AppData\Local\Programs\Python\Python311\python.exe）。这是最可靠的方式。
2	venv 自动检测	自动扫描 Vault 根目录下的 .paperforge-test-venv、.venv、venv 里的 Python
3	系统自动检测	依次尝试 py -3、python、python3，用 --version 验证，挑第一个能用的
4	兜底	以上都找不到，回退到 python

如果你系统里有多个 Python（比如系统自带的 3.9 + 自己装的 3.11），强烈建议在设置里手动指定路径，避免跑错环境。

设置里的 验证 按钮会立即测试当前选中的解释器，显示它能不能用、是什么版本。

---

4. 安装向导参数说明

打开插件设置界面（设置 → 第三方插件 → PaperForge），点击 打开安装向导 按钮，向导会引导你配置以下内容。每一步都解释在这里，免得你填的时候不知道是什么意思。

4.1 Vault 路径

你当前打开的 Obsidian Vault 根目录。安装向导自动检测，一般不用改。

4.2 AI Agent 平台

PaperForge 的精读功能通过 AI Agent 执行（如 /pf-deep 命令）。你需要选择你使用的 Agent 平台，安装向导会把对应的命令文件部署到正确位置。

Agent	命令文件放在	前缀	如何触发精读
OpenCode	.opencode/command/ + .opencode/skills/	/	打开 OpenCode，输入 /pf-deep <key>
Claude Code	.claude/skills/	/	打开 Claude Code，输入 /pf-deep <key>
Cursor	.cursor/skills/	/	打开 Cursor 的 AI Chat，输入 /pf-deep <key>
GitHub Copilot	.github/skills/	/	打开 Copilot Chat，输入 /pf-deep <key>
Windsurf	.windsurf/skills/	/	打开 Windsurf，输入 /pf-deep <key>
Codex	.codex/skills/	$	打开 Codex，输入 $pf-deep <key>
Cline	.clinerules/	/	打开 Cline，输入 /pf-deep <key>

注意：/pf-deep 和 /pf-paper 不是在终端里执行的命令。你需要先启动对应的 Agent 应用（比如打开 OpenCode），然后在这个 Agent 的对话输入框里输入命令，Agent 才会调用 PaperForge 的精读脚本去分析你的论文。

4.3 目录命名

安装向导会问你几个目录叫什么名字。这些都是给你自己看的，用来组织 Vault 里的文件结构。大部分情况用默认值就行。

参数	默认值	作用
system_dir	System	PaperForge 内部数据的总目录。下面会有 exports/（Zotero 导出的 JSON）、ocr/（OCR 结果）、config/ 等子目录。你一般不需要手动进去看。
resources_dir	Resources	资源根目录。你的正式文献笔记就放在这里下面的 literature_dir 里。
literature_dir	Literature	正式文献笔记的目录。paperforge sync 生成的带 frontmatter 的 .md 笔记在这里。你日常阅读、编辑笔记都在这个目录。
base_dir	Bases	Obsidian Base 视图文件目录。Dashboard 里的筛选视图（"待 OCR"、"待精读"等）存在这里。

4.4 PaddleOCR API Token

OCR 功能需要 PaddleOCR 的 API。在 .env 文件里配置：

PADDLEOCR_API_TOKEN=你的API密钥

安装向导会引导你填写，也可以之后手动在 Vault 根目录的 .env 文件里加。OCR URL 一般不需要改。

4.5 Zotero 数据目录

PaperForge 会创建一个 junction（Windows）或 symlink（macOS/Linux），把 Zotero 的数据目录连接到 Vault 里。这样 Obsidian 的 wikilink 才能找到 PDF 文件。

安装向导会自动检测 Zotero 的安装位置。如果检测失败，你需要手动指定 Zotero 数据目录的路径——也就是包含 storage 子目录的那个文件夹（不是 Zotero 程序本身）。

4.6 安装过程

确认配置后，安装向导会自动：

• 创建所有需要的目录结构
• 把 Agent 命令文件部署到对应位置
• 把 Obsidian 插件文件安装到位
• 创建 Zotero junction/symlink
• 写入 paperforge.json 和 .env

整个过程是增量的 — 如果你选的目录里已经有文件，安装向导只会补充缺失的，不会删除已有内容。

---

5. 首次使用

1. 确认版本一致：设置 → 运行时状态 → 确保插件和 Python 包版本一致
2. 确认 Python 正确：设置 → 验证按钮，确认连接的是你想要的 Python
3. 运行安装向导：Ctrl+P → PaperForge: Run Setup Wizard
4. 配置 PaddleOCR：在 .env 里填入 API Token（安装向导会引导你做这一步）
5. 在 Zotero 里导出文献：右键要同步的文献库 → 导出... → 格式选 Better BibTeX JSON → 勾选 Keep updated → 保存到 <system_dir>/PaperForge/exports/
6. 运行 Doctor：Dashboard → Run Doctor，确认所有检查通过

---

6. 日常使用

Dashboard（三模式视图）

Ctrl+P → PaperForge: Open Dashboard 打开控制面板，包含三种视图：

视图	用途
Global	系统首页：运行 Sync、OCR、Doctor 等机械操作
Collection	批量工作台：按领域查看文献队列、批量标记
Per-paper	单篇阅读伴侣：do_ocr / analyze 切换复选框，讨论记录卡片

Dashboard 里的 PDF 文件会自动进入 Per-paper 模式，无需手动切换。

AI 精读与问答（需 Agent）

打开你选择的 Agent 应用，在对话输入框里输入命令即可。你对文献描述得越具体（Zotero Key、标题、DOI），Agent 定位越快。

路由	命令	做什么	触发词举例	前置条件
精读	/pf-deep <key>	Keshav 三阶段组会式精读，结果写入 formal note	精读 XX、带我读这篇、组会讲讲	OCR 完成、analyze 为 true
问答	/pf-paper <key>	交互式论文 Q&A，不强制 OCR	帮我看看 XX、这篇文章讲了什么	已有正式笔记
存档	/pf-end	保存本次 /pf-paper 问答记录	保存、结束讨论	/pf-paper 会话中

/pf-end 详解

• /pf-end 仅对 /pf-paper 问答会话生效。精读（/pf-deep）的内容直接写入 formal note，不需要 /pf-end。
• 执行后会在论文 workspace 下生成两个文件：
  • discussion.md — 人类可读的 Q&A 讨论记录
  • discussion.json — 结构化 Q&A 数据（含时间戳、来源标记）
• Dashboard 的 Per-paper 视图会自动以讨论记录卡片形式展示这些记录

不同 Agent 的命令前缀可能不同（大部分是 /，Codex 是 $）。

---

7. 完整工作流

Zotero 添加论文
  ↓ Better BibTeX 自动导出 JSON 到 exports/ 目录
Dashboard → Sync Library
  ↓ 生成正式笔记（Literature/ 目录下，带 frontmatter 元数据）
在笔记 frontmatter 里把 do_ocr 设为 true
  ↓
Dashboard → Run OCR
  ↓ PaddleOCR 提取全文 + 图表 → ocr/ 目录
在笔记 frontmatter 里把 analyze 设为 true
  ↓
打开 Agent → 输入 /pf-deep <zotero_key>
  ↓ Agent 执行三阶段精读
笔记里出现 ## 🔍 精读 区域
  ↓（如需额外问答）
打开 Agent → 输入 /pf-paper <zotero_key>
  ↓ 交互式 Q&A
输入 /pf-end 保存讨论记录
  ↓
Dashboard Per-paper 视图展示讨论卡片

---

8. 常见问题

插件加载失败（Cannot find module）

• 确认 .obsidian/plugins/paperforge/ 下有 main.js、manifest.json、styles.css 三个文件
• 如果 BRAT 从旧版升级后出问题：删除整个 paperforge 插件文件夹，让 BRAT 重新下载
• 打开 Developer Console（Ctrl+Shift+I）看红色报错

"同步运行时" 点了还是旧版本

• 插件调用的 Python 可能和你终端用的是不同环境。检查设置 → Python 解释器路径
• pip 缓存问题，用 --no-cache-dir 重装
• 确认 https://github.com/LLLin000/PaperForge 网络能通

OCR 一直 pending

• 确认 .env 里有 PADDLEOCR_API_TOKEN
• 终端运行 paperforge ocr --diagnose 检查 API 连通性
• PDF 路径可能不对：运行 paperforge repair --fix-paths

同步后没有生成笔记

• Zotero Better BibTeX 是否配置了自动导出？JSON 是否在 exports/ 目录？
• 运行 paperforge doctor 看具体哪一步失败
• 运行 paperforge status 查看系统状态总览

/pf-deep 命令没反应

• 确认你在 Agent 软件里执行，不是在终端
• 确认 OCR 已完成（ocr_status: done）
• 确认 analyze 已设为 true

---

9. 更新

BRAT 会自动检测插件更新。Python 包更新：

paperforge update
# 或
pip install --upgrade git+https://github.com/LLLin000/PaperForge.git

---

10. 架构

paperforge/
├── core/          契约层 — PFResult/ErrorCode/状态机
├── adapters/      适配器层 — BBT 解析、路径、frontmatter
├── services/      服务层 — SyncService 编排
├── worker/        工人层 — OCR、状态、修复
├── commands/      CLI 分发
├── setup/         安装向导（目录创建、Agent 部署、Zotero 链接）
├── plugin/        Obsidian 插件（Dashboard、设置面板）
└── schema/        字段注册表

---

协议

CC BY-NC-SA 4.0。仅限非商业使用。

致谢

基于 PaddleOCR、Obsidian、Better BibTeX for Zotero 等开源项目构建。