From 97a2875d481f9163e6e50265699d2fcf38783421 Mon Sep 17 00:00:00 2001 From: Research Assistant Date: Sat, 16 May 2026 22:47:00 +0800 Subject: [PATCH] docs: reset documentation IA (readme entry pages, tutorial/troubleshooting split, AGENTS agent-only, pure command ref, maintainer guide) Separate audiences: README as navigation entry, getting-started as canonical tutorial, troubleshooting as failure recovery, AGENTS as agent-only operating contract, COMMANDS as pure reference, maintainer-guide for release/versioning/architecture. --- AGENTS.md | 651 ++++--------------------------------- README.en.md | 228 ++----------- README.md | 230 ++----------- docs/COMMANDS.md | 145 ++++----- docs/getting-started.md | 90 +++++ docs/maintainer-guide.md | 74 +++++ docs/troubleshooting.md | 67 ++++ docs/update-upgrade.md | 32 ++ tests/test_command_docs.py | 4 +- 9 files changed, 429 insertions(+), 1092 deletions(-) create mode 100644 docs/getting-started.md create mode 100644 docs/maintainer-guide.md create mode 100644 docs/troubleshooting.md create mode 100644 docs/update-upgrade.md diff --git a/AGENTS.md b/AGENTS.md index 397a9d7b..2abafc86 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,627 +1,90 @@ -# PaperForge - Agent Guide +# PaperForge - Agent Operating Guide -> 本文档面向 **安装完成后的新用户** 和 **AI Agent**。如果还没有安装 PaperForge，请通过 Obsidian 插件市场安装，或查看 [README.md](README.md) 中的安装说明。Docs 版本与 v1.4.18 对应。 +> 本文档面向 **AI Agent**（OpenCode / Claude Code / GPT / Cursor 等）。终端用户请阅读 [使用教程](docs/getting-started.md)。 --- -## 0. 安装后检查清单（第一次使用前必做） +## 1. 核心不变式 -``` -[ ] Zotero 已安装 + Better BibTeX 插件已启用 -[ ] Obsidian 已打开当前 Vault -[ ] PaperForge 已安装 (pip install paperforge) -[ ] PaddleOCR API Key 已配置（在 .env 中） -[ ] 目录结构已创建（安装向导会自动完成） -[ ] Zotero 数据目录已链接到 /Zotero -[ ] Better BibTeX 已按下方步骤导出 JSON 到 /PaperForge/exports/ -``` - -> 安装向导是增量式的：如果你选择的 Vault 或目录里已经有文件，PaperForge 只会补充缺失的目录和文件，不会删除已有内容。 - -### Better BibTeX 自动导出配置 - -这一步应在安装向导完成之后再做，因为 `exports/` 目录需要先由安装流程创建。 - -1. 打开 Zotero -2. 对你要同步的文献库或分类右键 → `导出...` -3. 选择格式：**Better BibTeX JSON** -4. 勾选 **"Keep updated"**（自动导出） -5. 保存到：`{你的Vault路径}//PaperForge/exports/` -6. JSON 文件名会作为 Base 名称，例如 `library.json`、`骨科.json` +1. **CLI 是命令真相源。** 所有 skill、workflow、文档命令引用必须对齐 `paperforge/cli.py`。 +2. **Python 是运行时真相源。** Plugin 只读 canonical 快照，不做业务推断。 +3. **`paperforge.json` 是路径真相源。** Plugin 和 Python 共享同源路径解析，不硬编码目录名。 +4. **Agent 机械命令和思考工作流分层。** `/pf-sync` `/pf-ocr` `/pf-status` 是机械执行，`/pf-deep` `/pf-paper` 是思考工作流。 --- -## 1. 核心架构（v2.1 契约驱动） +## 2. 架构边界 -PaperForge 在 v2.1（1.4.17rc4）重构为 **契约驱动架构**，分 5 层： +| 层 | 做什么 | 不做什么 | +|----|--------|---------| +| Plugin JS | 读快照、render UI、`execFile` 调 Python | 不读 SQLite、不推断 runtime 状态 | +| Python CLI | 写快照、sync/ocr/repair/embed/memory | 不被 JS 轮询驱动 | +| Memory DB | SQLite + FTS5，由 Python 全权重建 | JS 不读 memory DB | +| Vector DB | ChromaDB，由 `embed build` 管理 | 不与 memory DB 合并语义 | +| Skill/workflow | 路由 → 执行 CLI → 解释结果 | 不绕过 CLI 直操作文件 | + +**运行时快照契约：** ``` -CLI/Plugin 调用 - ↓ PFResult 契约 {ok, command, version, data, error} -┌─────────────────────────────────────────────┐ -│ commands/ CLI 分发层 │ -├─────────────────────────────────────────────┤ -│ adapter/bbt, zotero_paths, frontmatter │ ← 独立可测 -│ services/sync_service ← 编排适配器 │ -├─────────────────────────────────────────────┤ -│ core/result, errors, state ← 共享数据契约 │ -├─────────────────────────────────────────────┤ -│ worker/sync, ocr, status ← 机械劳动 │ -│ setup/6个类 ← 安装流程 │ -├─────────────────────────────────────────────┤ -│ schema/field_registry.yaml ← 字段注册表 │ -│ doctor/field_validator.py ← 字段校验 │ -└─────────────────────────────────────────────┘ -``` +Python 写（每次相关 CLI 命令结束时）: + runtime-health --json → runtime-health.json + memory status --json → memory-runtime-state.json + embed status --json → vector-runtime-state.json + embed build → vector-build-state.json -| 层级 | 组件 | 触发方式 | 作用 | -|------|------|----------|------| -| **契约层** | `core/`（PFResult, ErrorCode, 状态机） | 被所有模块引用 | 定义 CLI/Plugin/Worker 之间的数据交换格式 | -| **适配器层** | `adapters/`（bbt, zotero_paths, frontmatter） | 被服务层调用 | 封装外部数据格式与 I/O 操作 | -| **服务层** | `services/sync_service` | 被 worker 调度 | 编排适配器，实现业务逻辑 | -| **Worker 层** | `worker/`（sync, ocr, status, repair 等） | Python CLI | 后台自动化（机械劳动） | -| **Agent 层** | `/pf-deep`, `/pf-paper` | 用户手动触发 | 交互式精读（深度思考） | - -**操作速查**： -| 你要做什么 | 在终端输入 | 在 OpenCode 输入 | -|-----------|-----------|-----------------| -| 同步 Zotero 并生成笔记 | `paperforge sync` | `/pf-sync` | -| 运行 OCR | `paperforge ocr` | `/pf-ocr` | -| 查看精读队列 | `paperforge deep-reading` | `/pf-deep`（精读具体文献） | -| 查看系统状态 | `paperforge status` | `/pf-status` | -| 修复状态分歧 | `paperforge repair` | （终端操作） | -| 验证安装配置 | `paperforge doctor` | （终端操作） | -| 查看帮助 | `paperforge --help` | （终端操作） | - ---- - -## 2. 完整数据流 - -``` -Zotero 添加文献 - ↓ Better BibTeX 自动导出 JSON -/PaperForge/exports/library.json - ↓ 运行 sync -/// - .md（正式笔记，含 frontmatter） - ↓ 用户在正式笔记 frontmatter 中设置 do_ocr: true -运行 ocr → <system_dir>/PaperForge/ocr/<key>/ - ↓ 用户在正式笔记 frontmatter 中设置 analyze: true -运行 deep-reading（查看队列，确认就绪） - ↓ 用户执行 Agent 命令 -/pf-deep <zotero_key> - ↓ Agent 生成 -正式笔记中新增 ## 🔍 精读 区域 +JS 读（同步，不推断）: + memoryState.getMemoryRuntime() + memoryState.getVectorRuntime() + memoryState.getRuntimeHealth() ``` --- -## 3. 目录结构（Lite 版，5 个核心目录） +## 3. 安全命令惯例 -``` -{你的Vault根目录}/ -├── <resources_dir>/ -│ ├── <literature_dir>/ ← 正式文献笔记（sync 生成，含 frontmatter 状态跟踪） -│ │ ├── 骨科/ -│ │ ├── 运动医学/ -│ │ └── ...（你的分类） -│ -├── <system_dir>/ -│ ├── PaperForge/ -│ │ ├── exports/ ← Better BibTeX 自动导出的 JSON -│ │ │ └── library.json -│ │ ├── ocr/ ← OCR 结果（每个文献一个子目录） -│ │ │ └── ABCDEFG/ ← Zotero key 作为目录名 -│ │ │ ├── fulltext.md ← OCR 提取的全文 -│ │ │ ├── images/ ← 图表切割图片 -│ │ │ ├── meta.json ← OCR 元数据（含 ocr_status） -│ │ │ └── figure-map.json ← 图表索引（自动创建） -│ │ ├── indexes/ ← 索引缓存（formal-library.json 等） -│ │ └── config/ ← 领域-收藏夹映射等配置 -│ └── Zotero/ ← Junction/Symlink 到 Zotero 数据目录 -│ -├── <agent_config_dir>/ ← OpenCode Agent 配置（自动创建） -│ └── skills/ -│ └── literature-qa/ ← 深度阅读 Skill -│ ├── scripts/ -│ │ └── ld_deep.py ← /pf-deep 核心脚本 -│ ├── prompt_deep_subagent.md ← Agent 精读提示词 -│ └── chart-reading/ ← 14 种图表阅读指南 -│ -├── .env ← API Key 等敏感配置 -└── AGENTS.md ← 本文件 -``` - -### 各目录作用速查 - -| 目录 | 内容 | 谁生成/修改 | -|------|------|------------| -| `<resources_dir>/<literature_dir>/` | 正式文献笔记（含 frontmatter + 精读内容） | sync 生成，Agent 写入精读 | -| `<system_dir>/PaperForge/exports/` | Better BibTeX JSON 导出 | Zotero 自动导出 | -| `<system_dir>/PaperForge/ocr/` | OCR 全文 + 图表切割 | ocr worker 生成 | -| `<system_dir>/PaperForge/indexes/` | 索引缓存（formal-library.json） | sync 生成 | -| `<system_dir>/PaperForge/config/` | 领域-收藏夹映射等 | 用户/安装向导配置 | -| `<system_dir>/Zotero/` | Zotero 数据目录的链接 | 安装时手动创建 junction | +- 搜索用 `$PYTHON -m paperforge search`，不用 `grep`/`glob` 扫库。 +- 路径从 bootstrap 或 paper-context 获取，禁止自行拼接。 +- 未完成 paper-context 检查前不读原文（deep-reading、paper-qa）。 +- Reading-log 不是事实源，只能用做复查定位。 +- 未知或拼错的 `/pf-*` 必须提示用户，禁止静默掉进 `project-engineering`。 --- -## 4. 核心 Workers（Lite 版，4 个） +## 4. 机械 vs 思考路由 -### sync -- **作用**：检测 Zotero 中的新条目并生成正式文献笔记 -- **运行时机**：添加新文献到 Zotero 后，或需要更新笔记格式时 -- **输出**： - - `<resources_dir>/<literature_dir>/<domain>/<key> - <Title>.md` -- **示例**： - ```bash - paperforge sync - # Legacy (备用): - # python -m paperforge sync --vault "{vault路径}" - ``` - -### ocr -- **作用**：将 PDF 上传到 PaddleOCR API，提取全文文本和图表 -- **触发条件**：正式笔记 frontmatter 中 `do_ocr: true` -- **输出**：`<system_dir>/PaperForge/ocr/<key>/` 目录 - - `fulltext.md`：提取的全文（含 `<!-- page N -->` 分页标记） - - `images/`：自动切割的图表图片 - - `meta.json`：OCR 状态（`ocr_status: done/pending/processing/failed`） - - `figure-map.json`：图表索引（后续自动生成） -- **注意**：OCR 是异步的，大文件可能需要几分钟 -- **示例**： - ```bash - paperforge ocr - # 诊断模式（不运行，仅检查状态） - paperforge ocr --diagnose - # Legacy (备用): - # python -m paperforge ocr --vault "{vault路径}" - ``` - -### deep-reading -- **作用**：扫描所有正式笔记，列出 `analyze=true` 且 OCR 完成的文献 -- **运行时机**：用户想看看哪些文献可以开始精读了 -- **输出**：控制台表格，显示队列状态 -- **重要**：这只是**查看队列**，不会自动触发 Agent 精读 -- **示例**： - ```bash - paperforge deep-reading - paperforge deep-reading --verbose # 显示阻塞条目的修复指令 - # Legacy (备用): - # python -m paperforge deep-reading --vault "{vault路径}" - ``` +| Route | 类型 | 动作 | +|-------|------|------| +| `/pf-sync` | 机械 | 执行 `paperforge sync`，解释结果 | +| `/pf-ocr` | 机械 | 执行 `paperforge ocr`，解释结果 | +| `/pf-status` | 机械 | 执行 `paperforge status --json` 或 `paperforge runtime-health --json`，解读状态 | +| `/pf-deep` | 思考 | 打开 `workflows/deep-reading.md` 执行完整流程 | +| `/pf-paper` | 思考 | 打开 `workflows/paper-qa.md` 执行完整流程 | --- -## 5. Agent 命令（用户手动触发） - -PaperForge 的命令分为两类： - -| 类型 | 命令 | 用途 | 说明 | -|------|------|------|------| -| **深度思考** | `/pf-deep <key>` | 完整 Keshav 三阶段精读 | **必须 Agent 执行** — 需要理解论文、分析图表、生成 callout | -| **深度思考** | `/pf-paper <key>` | 文献问答 | **必须 Agent 执行** — 需要理解内容并写作 | -| **机械操作** | `/pf-sync` | 同步 Zotero 并生成笔记 | Agent 可帮你检查状态并执行 | -| **机械操作** | `/pf-ocr` | 运行 PDF OCR | Agent 可帮你检查队列并执行 | -| **机械操作** | `/pf-status` | 查看系统状态 | Agent 可帮你解读诊断结果 | - -> **双模式调用**：`/pf-sync`、`/pf-ocr`、`/pf-status` 本质上是 CLI 命令的 Agent 包装。你可以在终端直接运行 `paperforge sync/ocr/status`，也可以在 OpenCode 中使用 `/pf-*` 让 Agent 帮你检查前置条件、执行命令、解读输出。 - -> **v1.4 新增**：所有命令支持全局 `--verbose` / `-v` 参数（如 `paperforge sync --verbose`），输出 DEBUG 级别的诊断信息到 stderr，不影响 stdout 的正常输出。 - -> **v1.4 新增 — auto_analyze_after_ocr**：如果开启了 `paperforge.json` 中的 `auto_analyze_after_ocr`，OCR 完成后 `analyze` 会自动设为 `true`，无需手动修改 formal note frontmatter。 - -### 必须 Agent 执行的命令 - -#### `/pf-deep <zotero_key>` — 完整精读 - -**用途**：完整 Keshav 三阶段精读 -**前置条件**：OCR 完成 (`ocr_status: done`) - -执行流程： -1. **prepare 阶段**（自动）：查找正式笔记、检查 OCR、生成 figure-map -2. **精读阶段**（Agent 执行）：Pass 1 概览 → Pass 2 精读还原 → Pass 3 深度理解 -3. **验证阶段**（自动）：检查 callout 间距、section 完整性 - -#### `/pf-paper <zotero_key>` — 文献问答 - -**用途**：文献问答（无 OCR 要求） -**前置条件**：有正式笔记即可 - ---- - -## 6. Path Resolution（路径解析） - -PaperForge 支持三种 Better BibTeX 导出路径格式，并统一转换为 Obsidian wikilink： - -### 支持的 BBT 路径格式 - -| 格式 | 示例 | 处理方式 | -|------|------|----------| -| **Absolute Windows** | `D:\Zotero\storage\KEY\file.pdf` | 提取 8 位 KEY，转换为 `storage:KEY/file.pdf` | -| **storage: prefix** | `storage:KEY/file.pdf` | 直接透传，仅规范化斜杠 | -| **Bare relative** | `KEY/file.pdf` | 自动添加 `storage:` 前缀 | - -### Wikilink 生成规则 - -- 所有 PDF 路径在正式笔记中存储为 **Obsidian wikilink** 格式：`[[relative/path/to/file.pdf]]` -- 使用正斜杠 `/`（即使 Windows 系统） -- 支持中文文件名，无需转义 -- 示例：`[[99_System/Zotero/storage/KEY/中文论文.pdf]]` - -### Junction / Symlink 设置 - -如果 Zotero 数据目录在 Vault 外部，需创建 junction： - -```powershell -# 以管理员身份运行 PowerShell -New-Item -ItemType Junction -Path "C:\你的Vault\99_System\Zotero" -Target "C:\Users\用户名\Zotero" -``` - -或 CMD： - -```cmd -mklink /J "C:\你的Vault\99_System\Zotero" "C:\Users\用户名\Zotero" -``` - -运行 `paperforge doctor` 会自动检测 Zotero 位置并推荐正确的 junction 命令。 - -### 多附件处理 - -当一篇文献有多个 PDF 附件时： -- **Main PDF**：title="PDF" 的附件，或最大文件，或第一个 PDF -- **Supplementary**：其他 PDF 附件列表，以 wikilink 数组形式存储 - ---- - -## 7. Frontmatter 字段参考 - -### Formal Note（`Literature/<domain>/<key> - <Title>.md`） - -这是**用户控制工作流的核心**。每个文献对应一个 formal note 文件，frontmatter 包含元数据 + 工作流控制字段： - -```yaml ---- -zotero_key: "ABCDEFG" # Zotero citation key（自动生成） -domain: "骨科" # 分类领域（对应 Zotero 收藏夹） -title: "论文标题" -year: 2024 -doi: "10.xxxx/xxxxx" -collection_path: "子分类" # Zotero 子收藏夹路径 -has_pdf: true # 是否有 PDF 附件（自动生成） -pdf_path: "[[99_System/Zotero/storage/KEY/文件名.pdf]]" # Wikilink 格式 -bbt_path_raw: "D:\\Zotero\\storage\\KEY\\文件名.pdf" # 原始 BBT 路径（调试用） -zotero_storage_key: "KEY" # 8 位 Zotero storage key -attachment_count: 2 # 附件总数 -supplementary: # 其他 PDF 附件（wikilink 列表） - - "[[99_System/Zotero/storage/KEY/supp1.pdf]]" - - "[[99_System/Zotero/storage/KEY/supp2.pdf]]" -fulltext_md_path: "[[99_System/PaperForge/ocr/KEY/fulltext.md]]" -recommend_analyze: true # 系统推荐精读（有 PDF 时自动设为 true） -analyze: false # 【用户控制】是否生成精读？设为 true 触发 -do_ocr: true # 【用户控制】是否运行 OCR？设为 true 触发 -ocr_status: "done" # OCR 状态（pending/processing/done/failed） -deep_reading_status: "pending" # 精读状态（pending/done） -path_error: "" # 路径错误（not_found/invalid/permission_denied） -analysis_note: "" # 预留字段 ---- -``` - -**用户操作方式**： -- 在 Obsidian 中打开 formal note 文件 -- 修改 `analyze: false` → `analyze: true` 标记要精读的文献 -- 修改 `do_ocr: false` → `do_ocr: true` 触发 OCR -- 或使用 Obsidian Base 视图批量操作 - ---- - -## 8. 第一次使用指南（手把手） - -### Step 1: 完成 Better BibTeX 自动导出 - -先按上面的步骤把 JSON 导出到 `<system_dir>/PaperForge/exports/`。这一步没完成前，`sync` 不会读到文献。 - -### Step 2: 确认 Zotero 有文献 - -确保 Zotero 中已有至少一篇带 PDF 的文献，且 Better BibTeX 已导出 JSON。 - -### Step 3: 运行 sync +## 5. 测试 ```bash -# 在 Vault 根目录执行 -paperforge sync -``` +# Python +python -m pytest tests/unit/ tests/cli/ -v --tb=short -预期输出： -``` -[INFO] Found 5 new items -[INFO] Created 骨科/XXXXXXX.md -[INFO] Generated 5 formal notes -[INFO] Output: <resources_dir>/<literature_dir>/骨科/XXXXXXX - Title.md -... -``` +# JS +cd paperforge/plugin && npx vitest run -### Step 4: 在 Base 视图中标记 OCR - -打开 Obsidian Base 视图，找到该文献，将 `do_ocr` 设为 `true`。 - -### Step 5: 运行 OCR - -```bash -paperforge ocr -``` - -等待完成（可能需要几分钟）。 - -### Step 6: 在 Base 视图中标记精读 - -OCR 完成后，在 Base 视图中找到该文献，将 `analyze` 设为 `true`。 - -### Step 7: 执行精读 - -先确认队列就绪： -```bash -paperforge deep-reading -``` - -然后在 OpenCode Agent 中输入： -``` -/pf-deep XXXXXXX -``` - -Agent 会自动： -1. 准备精读骨架（prepare） -2. 逐阶段填写精读内容 -3. 验证结构完整性 - -### Step 8: 查看结果 - -在 Obsidian 中打开正式笔记，找到 `## 🔍 精读` 区域，精读已完成。 - ---- - -## 9. 常用命令速查 - -```bash -# 检测 Zotero 新条目并生成正式笔记 -paperforge sync -paperforge sync --verbose # 显示详细诊断信息 - - - -# 运行 OCR（处理 do_ocr=true 的文献） -paperforge ocr -paperforge ocr --verbose # 显示 OCR 详细日志 -paperforge ocr --diagnose # 诊断模式，不实际运行 -paperforge ocr --no-progress # 静默模式，不显示进度条 - -# 查看精读队列 -paperforge deep-reading -paperforge deep-reading --verbose # 显示阻塞条目修复指令 - -# 修复状态分歧（默认 dry-run） -paperforge repair --verbose # 查看三向状态分歧详情 -paperforge repair --fix # 实际修复（慎用） - -# 查看整体状态 -paperforge status - -# 验证安装配置 -paperforge doctor -``` - -> 如果 `paperforge` 命令未注册，可使用 fallback： -> ```bash -> python -m paperforge <command> -> ``` -> 例如：`python -m paperforge status` - -### Agent 命令 -``` -/pf-deep <zotero_key> # 完整三阶段精读（必须 Agent 执行） -/pf-paper <zotero_key> # 文献问答（必须 Agent 执行） -/pf-sync # 同步 Zotero（Agent 包装 CLI） -/pf-ocr # 运行 OCR（Agent 包装 CLI） -/pf-status # 查看状态（Agent 包装 CLI） -``` - -> 注：`/pf-sync`、`/pf-ocr`、`/pf-status` 与 `paperforge sync/ocr/status` 是同一命令的两种调用方式。在终端直接运行 CLI 即可；在 OpenCode 中使用 `/pf-*` 可以让 Agent 帮你检查前置条件并解读输出。 - -### Chart-Reading 指南索引 - -`/pf-deep` 精读时会参考 19 种图表类型的阅读指南，按生物医学文献常见度排序。完整索引参见 `chart-reading/INDEX.md`。 - ---- - -## 10. 常见问题 - -### Q: 运行 sync 后没有生成正式笔记？ -- 检查 Better BibTeX JSON 导出路径是否正确 -- 检查 JSON 文件是否包含文献数据 -- 确认 Zotero 中该文献有 citation key - -### Q: OCR 一直显示 pending？ -- 检查 PaddleOCR API Key 是否配置正确（`.env` 文件） -- 检查网络连接 -- 查看 `<system_dir>/PaperForge/ocr/<key>/meta.json` 中的错误信息 - -### Q: /pf-deep 提示 OCR 未完成？ -- 确认正式笔记 frontmatter 中 `ocr_status: done` -- 如 OCR 失败，可重新设置 `do_ocr: true` 再运行 ocr worker - -### Q: Base 视图中 pdf_path 显示为绝对路径？ -- 这是 Obsidian 渲染问题，数据本身是相对路径 -- 不影响功能，可忽略 - -### Q: 可以批量操作吗？ -- 可以。使用 Obsidian Base 视图批量修改 `do_ocr` 和 `analyze` 字段 -- 或使用脚本批量修改 formal note frontmatter - ---- - -## 11. 升级与维护 - -### 更新 PaperForge 代码 - -#### 方式 1：自动更新（推荐） - -```bash -# 自动检测安装方式并更新 -paperforge update -``` - -系统会自动检测你是通过 pip、git 还是手动安装，并执行对应的更新方式。 - -#### 方式 2：Windows 一键脚本 - -双击运行 Vault 根目录下的 `scripts/update-paperforge.ps1`： -- 自动检测安装方式 -- 自动执行更新 -- 无需手动输入命令 - -```powershell -# 或在 PowerShell 中执行 -.\scripts\update-paperforge.ps1 - -# 强制更新（跳过确认） -.\scripts\update-paperforge.ps1 -Force - -# 只检测不更新 -.\scripts\update-paperforge.ps1 -DryRun -``` - -#### 方式 3：手动更新 - -**推荐：自动更新** -```bash -paperforge update -``` -系统会自动检测安装方式并执行对应的更新命令。 - -**pip 安装用户：** -```bash -pip install --upgrade paperforge -``` - -**pip editable / git clone 用户：** -```bash -cd 你的仓库目录 -git pull origin master -pip install -e . -``` - -#### 方式 4：手动复制（最后手段） - -```bash -cp -r 新下载的代码/* <vault_path>/ -``` - -> [!WARNING] 手动复制容易遗漏文件，建议优先使用自动更新。 - -### 备份注意事项 -- `<resources_dir>/` 和 `<system_dir>/PaperForge/ocr/` 包含你的数据，需备份 -- `.env` 包含 API Key，不要提交到 git -- `<system_dir>/PaperForge/exports/` 可重新生成（由 Zotero 自动导出） - ---- - -## 12. 命令迁移说明（v1.1 → v1.2） - -从 v1.2 开始，PaperForge 采用统一的命令接口： - -- **CLI 统一入口**：`paperforge sync`（替代 `selection-sync` + `index-refresh`）、`paperforge ocr`（替代 `ocr run`） -- **Agent 统一前缀**：`/pf-deep`、`/pf-paper`、`/pf-ocr`、`/pf-sync`、`/pf-status`（替代 `/LD-*` 和 `/lp-*`） -- **Python 包重命名**：`paperforge`（替代 `paperforge_lite`） - -**旧命令仍兼容**：v1.2 继续支持旧命令名（`selection-sync`、`index-refresh`、`ocr run`），但文档已统一使用新命令。 - -> **v1.4 新增**：结构化日志（`--verbose`）、自动重试、进度条、代码自动化检查。详细迁移步骤和回滚说明参见 [docs/MIGRATION-v1.2.md](docs/MIGRATION-v1.2.md)（v1.1→v1.2）和 [docs/MIGRATION-v1.4.md](docs/MIGRATION-v1.4.md)（v1.3→v1.4）。 - ---- - -## 13. 开发者指南（AI Agent 必读） - -### v2.1 新增模块 - -v2.1（1.4.17rc4）引入了以下新增模块，开发时请注意： - -| 路径 | 内容 | 注意事项 | -|------|------|---------| -| `paperforge/core/` | 契约层 — PFResult, ErrorCode, 状态机 | 所有模块都可引用，不循环依赖 | -| `paperforge/adapters/` | 适配器 — bbt, zotero_paths, frontmatter | 独立可测，从 `sync.py` 提取 | -| `paperforge/services/` | 服务层 — SyncService | 编排适配器，`sync.py` 变调度壳 | -| `paperforge/setup/` | 安装层 — 6 个类 | 从 `setup_wizard.py` 拆出 | -| `paperforge/schema/` | 字段注册表 — `field_registry.yaml` | 44 字段定义 | -| `paperforge/doctor/` | 校验 — `field_validator.py` | `doctor` 命令使用 | - -所有 `--json` 输出统一为 PFResult 格式 `{ok, command, version, data, error}`。修改输出结构时需同时更新 `core/result.py` 和下游 consumer（plugin）。 - -### 版本号管理 - -PaperForge 版本只在 `paperforge/__init__.py` 一处定义。升版本时不要手动改多个文件，使用自动化脚本： - -```bash -# 升 patch 版本（1.4.11 → 1.4.12），自动 git commit + tag -python scripts/bump.py patch - -# 升 minor 版本（1.4.11 → 1.5.0） -python scripts/bump.py minor - -# 指定版本号 -python scripts/bump.py 2.0.0 - -# 预览（不实际修改） -python scripts/bump.py patch --dry-run - -# 只改文件不 commit -python scripts/bump.py patch --no-git -``` - - 脚本会自动更新： -| 文件 | 字段 | -|------|------| -| `paperforge/__init__.py` | `__version__` | -| `paperforge/plugin/manifest.json` | `version` | -| `manifest.json` | `version` | -| `paperforge/plugin/versions.json` | 追加 `"version": "minAppVersion"` | - -### 发布 Release 流程 - -```bash -# 1. 升版本（自动 commit + tag） -python scripts/bump.py patch - -# 2. 推送代码和 tag -git push && git push --tags - -# 3. 创建 GitHub Release 并上传插件文件 -gh release create v1.4.12 \ - --title "v1.4.12" \ - --notes "简短说明" \ - paperforge/plugin/main.js \ - paperforge/plugin/styles.css \ - paperforge/plugin/manifest.json \ - paperforge/plugin/versions.json -``` - -> Obsidian 社区插件要求 Release 附带 `main.js`、`manifest.json`、`styles.css`、`versions.json` 四个单独文件（非 zip）。 - -### 插件 i18n - -插件界面通过 `paperforge/plugin/i18n.js` 做中英文适配： -- 语言自动检测：读取 Obsidian 语言设置，`zh*` 用中文，其他用英文 -- 新增文本时，需同时在 `i18n.js` 的 `zh` 和 `en` 两块加 key -- 代码中使用 `t('key_name')` 读取翻译 -- Dashboard 的 `ACTIONS` 标题保持英文（Obsidian 命令面板统一使用英文 ID） - -### pre-commit 检查 - -```bash -# 提交前运行 ruff lint + format + 一致性审计 +# Lint ruff check --fix paperforge/ && ruff format paperforge/ - -# 运行测试（173 tests） -python -m pytest tests/unit/ -q --tb=short ``` --- -*PaperForge | 快速开始指南 | 安装后阅读* +## 文档地图 + +| 受众 | 文件 | +|------|------| +| 终端用户教程 | [docs/getting-started.md](docs/getting-started.md) | +| 故障排除 | [docs/troubleshooting.md](docs/troubleshooting.md) | +| 命令参考 | [docs/COMMANDS.md](docs/COMMANDS.md) | +| 更新升级 | [docs/update-upgrade.md](docs/update-upgrade.md) | +| 架构 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | +| 维护者 | [docs/maintainer-guide.md](docs/maintainer-guide.md) | +| 迁移历史 | [docs/MIGRATION-v1.2.md](docs/MIGRATION-v1.2.md) | diff --git a/README.en.md b/README.en.md index 5c7e1ce7..caf88805 100644 --- a/README.en.md +++ b/README.en.md @@ -68,220 +68,34 @@ Plugin v1.5.0 → Python Package v1.5.0 ✓ Matched --- -## 3. How Python Interpreter Resolution Works - -PaperForge needs to find a working Python on your system. It searches in this order: - -| Priority | Source | Description | -|----------|--------|-------------| -| 1 | **Manual override** | Settings → `Custom Python Path`, enter the full path (e.g., `C:\Users\you\...\python.exe`). **This is the most reliable method.** | -| 2 | **venv auto-detect** | Scans `.paperforge-test-venv`, `.venv`, `venv` under your vault root | -| 3 | **System auto-detect** | Tries `py -3`, `python`, `python3` in order, verifies with `--version` | -| 4 | **Fallback** | Defaults to `python` if nothing else works | - -> If you have multiple Python installations (e.g., system 3.9 + self-installed 3.11), **strongly recommend setting a manual path** in settings to avoid hitting the wrong one. -> -> The **Validate** button in settings immediately tests the resolved interpreter and shows its version. - ---- - -## 4. Setup Wizard — What Each Step Means - -Open the plugin settings panel (`Settings` → `Community plugins` → `PaperForge`) and click the **Open Wizard** button. The wizard walks you through configuration. Here's what every step does. - -### 4.1 Vault Path - -Your Obsidian vault root. Auto-detected, usually no need to change. - -### 4.2 AI Agent Platform - -PaperForge's deep reading features run through an AI Agent. The core mechanism is **trigger phrases**, not registered plugins: you type `/pf-deep <key>` directly into the Agent chat, and the Agent recognizes the trigger and loads the `literature-qa` Skill automatically. - -The setup wizard deploys Skill files to the correct location: - -| Agent | Skill location | Trigger example | -|-------|---------------|-----------------| -| **OpenCode** | `.opencode/skills/` + `.opencode/command/` | `/pf-deep <key>` | -| **Claude Code** | `.claude/skills/` | `/pf-deep <key>` | -| **Cursor** | `.cursor/skills/` | `/pf-deep <key>` | -| **GitHub Copilot** | `.github/skills/` | `/pf-deep <key>` | -| **Windsurf** | `.windsurf/skills/` | `/pf-deep <key>` | -| **Codex** | `.codex/skills/` | `$pf-deep <key>` | -| **Cline** | `.clinerules/` | `/pf-deep <key>` | - -> **Key concept**: `/pf-deep` is NOT a plugin you install on the Agent platform — it's a Skill file deployed inside your Vault. Once the setup wizard copies the files into place, the Agent auto-discovers the triggers on startup. You type the trigger phrase just like any other chat input. - -### 4.3 Directory Names - -The wizard asks what to name several directories. These are for organizing files inside your vault. **Defaults work for most users.** - -| Parameter | Default | Purpose | -|-----------|---------|---------| -| `system_dir` | `System` | Root for PaperForge internal data. Contains `exports/` (Zotero JSON exports), `ocr/` (OCR results), `config/`. You rarely need to open this manually. | -| `resources_dir` | `Resources` | Resources root. Your formal literature notes live under this directory, inside `literature_dir`. | -| `literature_dir` | `Literature` | Formal literature notes directory. `paperforge sync` generates frontmatter `.md` notes here. | -| `base_dir` | `Bases` | Obsidian Base view definitions. Dashboard filters ("Pending OCR", "Ready to Read", etc.) are stored here. | - -### 4.4 PaddleOCR API Token - -OCR requires a PaddleOCR API key. Configured in `.env`: - -``` -PADDLEOCR_API_TOKEN=your-api-key -``` - -The wizard guides you through setting this. You can also edit `.env` later. The OCR URL usually stays at the default. - -### 4.5 Zotero Data Directory - -PaperForge creates a junction (Windows) or symlink (macOS/Linux) linking your Zotero data directory into the vault. This is how Obsidian wikilinks resolve to PDF files. - -The wizard auto-detects your Zotero installation. If detection fails, manually enter the path to your Zotero data directory — the folder that contains the `storage/` subdirectory (not the Zotero executable). - -### 4.6 What Happens During Setup - -After confirming your choices, the wizard automatically: -- Creates all needed directory structures -- Deploys Agent command files to the correct locations -- Installs Obsidian plugin files -- Creates the Zotero junction/symlink -- Writes `paperforge.json` and `.env` - -The process is **incremental** — if files already exist in the chosen directories, the wizard only adds what's missing and never deletes existing content. - ---- - -## 5. First-Time Setup Checklist - -1. **Version match**: Settings → Runtime Status → confirm plugin and Python package match -2. **Python path**: Settings → Validate button → confirm it's the Python you want -3. **Setup wizard**: Settings → PaperForge → Open Wizard -4. **PaddleOCR key**: Enter your API token in `.env` (wizard guides this) -5. **Export from Zotero**: Right-click your library → `Export...` → format `Better BibTeX JSON` → check `Keep updated` → save to `<system_dir>/PaperForge/exports/` -6. **Run Doctor**: Dashboard → `Run Doctor` → all checks should pass - ---- - -## 6. Daily Use - -### Dashboard (Three-Mode Views) - -`Ctrl+P` → `PaperForge: Open Dashboard` opens the control panel with three views: - -| View | Purpose | -|------|---------| -| **Global** | System homepage: run Sync, OCR, Doctor, and other mechanical operations | -| **Collection** | Batch workspace: browse paper queues by domain, batch tagging | -| **Per-paper** | Reading companion: `do_ocr` / `analyze` toggle checkboxes, discussion record cards | - -> PDF files in the Dashboard automatically switch to Per-paper mode — no manual switching needed. - -### AI Deep Reading & Q&A (Requires Agent) - -Launch your Agent app and type commands into its chat input. **The more specific you are about the paper (Zotero Key, title, DOI), the faster the Agent locates it.** - -| Route | Command | Does | Trigger examples | Prerequisites | -|-------|---------|------|-----------------|--------------| -| Deep Read | `/pf-deep <key>` | Keshav three-pass deep reading, writes to formal note | `deep read XX`, `walk me through`, `journal club` | OCR done, analyze: true | -| Q&A | `/pf-paper <key>` | Interactive paper Q&A, OCR not required | `take a look at XX`, `what does this paper say` | Formal note exists | -| Archive | `/pf-end` | Save current `/pf-paper` Q&A session | `save`, `end discussion` | During `/pf-paper` session | - -### `/pf-end` Details - -- `/pf-end` only applies to `/pf-paper` Q&A sessions. Deep reading (`/pf-deep`) writes directly to the formal note and does not need `/pf-end`. -- When executed, two files are created in the paper's workspace: - - `discussion.md` — human-readable Q&A discussion record - - `discussion.json` — structured Q&A data (with timestamps, source tags) -- Dashboard **Per-paper** view automatically displays these as discussion record cards - -> Command prefixes vary by platform (mostly `/`, Codex uses `$`). - ---- - -## 7. Full Workflow - -``` -Add paper to Zotero - ↓ Better BibTeX auto-exports JSON to exports/ -Dashboard → Sync Library - ↓ Generates formal note (in Literature/, with frontmatter metadata) -Set do_ocr: true in the note's frontmatter - ↓ -Dashboard → Run OCR - ↓ PaddleOCR extracts full text + figures → ocr/ directory -Set analyze: true in the note's frontmatter - ↓ -Open Agent → type /pf-deep <zotero_key> - ↓ Agent performs three-pass deep reading -## 🔍 Deep Reading section appears in the note - ↓ (for additional Q&A) -Open Agent → type /pf-paper <zotero_key> - ↓ Interactive Q&A -Type /pf-end to save the discussion record - ↓ -Dashboard Per-paper view shows discussion cards -``` - ---- - -## 8. Troubleshooting - -### Plugin fails to load - -- Confirm `.obsidian/plugins/paperforge/` has `main.js`, `manifest.json`, `styles.css` -- If upgrading via BRAT from an old version: delete the entire `paperforge` plugin folder and let BRAT re-download -- Open Developer Console (`Ctrl+Shift+I`) and check the red errors - -### "Sync Runtime" doesn't update the version - -- The plugin may be calling a different Python than your terminal. Check Settings → Python path -- Try with `--no-cache-dir` to bypass pip cache -- Confirm `https://github.com/LLLin000/PaperForge` is reachable - -### OCR stays pending - -- Confirm `.env` has `PADDLEOCR_API_TOKEN` -- Run `paperforge ocr --diagnose` to check API connectivity -- PDF paths may be broken: run `paperforge repair --fix-paths` - -### No notes generated after sync - -- Is Better BibTeX auto-export configured in Zotero? Are JSON files in `exports/`? -- Run `paperforge doctor` to find which step failed - -### /pf-deep command does nothing - -- Make sure you're running it in your Agent app, not a terminal -- Confirm OCR is done (`ocr_status: done`) -- Confirm `analyze` is set to `true` - ---- - -## 9. Updating - -BRAT auto-detects plugin updates. For the Python package: +## 3. Quickstart ```bash -paperforge update -# or -pip install --upgrade paperforge +# 1. Export from Zotero (Better BibTeX JSON, Keep updated) to exports/ +# 2. Sync +paperforge sync + +# 3. Mark a paper for OCR in its frontmatter: do_ocr: true +# 4. Run OCR +paperforge ocr + +# 5. Mark for deep reading: analyze: true +# 6. In your Agent chat: +/pf-deep <zotero_key> ``` --- -## 10. Architecture +## Documentation -``` -paperforge/ -├── core/ Contract layer — PFResult/ErrorCode/state machine -├── adapters/ Adapter layer — BBT parsing, paths, frontmatter I/O -├── services/ Service layer — SyncService orchestration -├── worker/ Worker layer — OCR, status, repair -├── commands/ CLI dispatch -├── setup/ Setup wizard (directories, agent deployment, Zotero linking) -├── plugin/ Obsidian plugin (Dashboard, settings panel) -└── schema/ Field registry -``` +| If you want to | Read | +| --------------------------------------- | ----------------------------------------- | +| Full tutorial, from install to deep read | [Getting Started](docs/getting-started.md) | +| Troubleshooting | [Troubleshooting](docs/troubleshooting.md) | +| Command reference | [Commands](docs/COMMANDS.md) | +| How to update | [Update Guide](docs/update-upgrade.md) | +| Architecture / Maintenance / Release | [Architecture](docs/ARCHITECTURE.md) | +| AI Agent collaboration | [AGENTS.md](AGENTS.md) | --- diff --git a/README.md b/README.md index 19f8edba..76330ebd 100644 --- a/README.md +++ b/README.md @@ -75,222 +75,34 @@ Plugin v1.5.0 → Python Package v1.5.0 ✓ Matched --- -## 3. How Python Interpreter Resolution Works - -PaperForge needs to find a working Python on your system. It searches in this order: - -| Priority | Source | Description | -|----------|--------|-------------| -| 1 | **Manual override** | Settings → `Custom Python Path`, enter the full path (e.g., `C:\Users\you\...\python.exe`). **This is the most reliable method.** | -| 2 | **venv auto-detect** | Scans `.paperforge-test-venv`, `.venv`, `venv` under your vault root | -| 3 | **System auto-detect** | Tries `py -3`, `python`, `python3` in order, verifies with `--version` | -| 4 | **Fallback** | Defaults to `python` if nothing else works | - -> If you have multiple Python installations (e.g., system 3.9 + self-installed 3.11), **strongly recommend setting a manual path** in settings to avoid hitting the wrong one. -> -> The **Validate** button in settings immediately tests the resolved interpreter and shows its version. - ---- - -## 4. Setup Wizard — What Each Step Means - -Open the plugin settings panel (`Settings` → `Community plugins` → `PaperForge`) and click the **Open Wizard** button. The wizard walks you through configuration. Here's what every step does. - -### 4.1 Vault Path - -Your Obsidian vault root. Auto-detected, usually no need to change. - -### 4.2 AI Agent Platform - -PaperForge's deep reading features run through an AI Agent. The core mechanism is **trigger phrases**, not registered plugins: you type `/pf-deep <key>` directly into the Agent chat, and the Agent recognizes the trigger and loads the `literature-qa` Skill automatically. - -The setup wizard deploys Skill files to the correct location: - -| Agent | Skill location | Trigger example | -|-------|---------------|-----------------| -| **OpenCode** | `.opencode/skills/` + `.opencode/command/` | `/pf-deep <key>` | -| **Claude Code** | `.claude/skills/` | `/pf-deep <key>` | -| **Cursor** | `.cursor/skills/` | `/pf-deep <key>` | -| **GitHub Copilot** | `.github/skills/` | `/pf-deep <key>` | -| **Windsurf** | `.windsurf/skills/` | `/pf-deep <key>` | -| **Codex** | `.codex/skills/` | `$pf-deep <key>` | -| **Cline** | `.clinerules/` | `/pf-deep <key>` | - -> **Key concept**: `/pf-deep` is NOT a plugin you install on the Agent platform — it's a Skill file deployed inside your Vault. Once the setup wizard copies the files into place, the Agent auto-discovers the triggers on startup. You type the trigger phrase just like any other chat input. - -### 4.3 Directory Names - -The wizard asks what to name several directories. These are for organizing files inside your vault. **Defaults work for most users.** - -| Parameter | Default | Purpose | -|-----------|---------|---------| -| `system_dir` | `System` | Root for PaperForge internal data. Contains `exports/` (Zotero JSON exports), `ocr/` (OCR results), `config/`. You rarely need to open this manually. | -| `resources_dir` | `Resources` | Resources root. Your formal literature notes live under this directory, inside `literature_dir`. | -| `literature_dir` | `Literature` | Formal literature notes directory. `paperforge sync` generates frontmatter `.md` notes here. | -| `base_dir` | `Bases` | Obsidian Base view definitions. Dashboard filters ("Pending OCR", "Ready to Read", etc.) are stored here. | - -### 4.4 PaddleOCR API Token - -OCR requires a PaddleOCR API key. Configured in `.env`: - -``` -PADDLEOCR_API_TOKEN=your-api-key -``` - -The wizard guides you through setting this. You can also edit `.env` later. The OCR URL usually stays at the default. - -### 4.5 Zotero Data Directory - -PaperForge creates a junction (Windows) or symlink (macOS/Linux) linking your Zotero data directory into the vault. This is how Obsidian wikilinks resolve to PDF files. - -The wizard auto-detects your Zotero installation. If detection fails, manually enter the path to your Zotero data directory — the folder that contains the `storage/` subdirectory (not the Zotero executable). - -### 4.6 What Happens During Setup - -After confirming your choices, the wizard automatically: -- Creates all needed directory structures -- Deploys Agent command files to the correct locations -- Installs Obsidian plugin files -- Creates the Zotero junction/symlink -- Writes `paperforge.json` and `.env` - -The process is **incremental** — if files already exist in the chosen directories, the wizard only adds what's missing and never deletes existing content. - ---- - -## 5. First-Time Setup Checklist - -1. **Version match**: Settings → Runtime Status → confirm plugin and Python package match -2. **Python path**: Settings → Validate button → confirm it's the Python you want -3. **Setup wizard**: Settings → PaperForge → Open Wizard -4. **PaddleOCR key**: Enter your API token in `.env` (wizard guides this) -5. **Export from Zotero**: Right-click your library → `Export...` → format `Better BibTeX JSON` → check `Keep updated` → save to `<system_dir>/PaperForge/exports/` -6. **Run Doctor**: Dashboard → `Run Doctor` → all checks should pass - ---- - -## 6. Daily Use - -### Dashboard (Three-Mode Views) - -`Ctrl+P` → `PaperForge: Open Dashboard` opens the control panel with three views: - -| View | Purpose | -|------|---------| -| **Global** | System homepage: run Sync, OCR, Doctor, and other mechanical operations | -| **Collection** | Batch workspace: browse paper queues by domain, batch tagging | -| **Per-paper** | Reading companion: `do_ocr` / `analyze` toggle checkboxes, discussion record cards | - -> PDF files in the Dashboard automatically switch to Per-paper mode — no manual switching needed. - -### AI Deep Reading & Q&A (Requires Agent) - -Launch your Agent app and type commands into its chat input. **The more specific you are about the paper (Zotero Key, title, DOI), the faster the Agent locates it.** - -| Route | Command | Does | Trigger examples | Prerequisites | -|-------|---------|------|-----------------|--------------| -| Deep Read | `/pf-deep <key>` | Keshav three-pass deep reading, writes to formal note | `deep read XX`, `walk me through`, `journal club` | OCR done, analyze: true | -| Q&A | `/pf-paper <key>` | Interactive paper Q&A, OCR not required | `take a look at XX`, `what does this paper say` | Formal note exists | -| Archive | `/pf-end` | Save current `/pf-paper` Q&A session | `save`, `end discussion` | During `/pf-paper` session | - -### `/pf-end` Details - -- `/pf-end` only applies to `/pf-paper` Q&A sessions. Deep reading (`/pf-deep`) writes directly to the formal note and does not need `/pf-end`. -- When executed, two files are created in the paper's workspace: - - `discussion.md` — human-readable Q&A discussion record - - `discussion.json` — structured Q&A data (with timestamps, source tags) -- Dashboard **Per-paper** view automatically displays these as discussion record cards - -> Command prefixes vary by platform (mostly `/`, Codex uses `$`). - ---- - -## 7. Full Workflow - -``` -Add paper to Zotero - ↓ Better BibTeX auto-exports JSON to exports/ -Dashboard → Sync Library - ↓ Generates formal note (in Literature/, with frontmatter metadata) -Set do_ocr: true in the note's frontmatter - ↓ -Dashboard → Run OCR - ↓ PaddleOCR extracts full text + figures → ocr/ directory -Set analyze: true in the note's frontmatter - ↓ -Open Agent → type /pf-deep <zotero_key> - ↓ Agent performs three-pass deep reading -## 🔍 Deep Reading section appears in the note - ↓ (for additional Q&A) -Open Agent → type /pf-paper <zotero_key> - ↓ Interactive Q&A -Type /pf-end to save the discussion record - ↓ -Dashboard Per-paper view shows discussion cards -``` - ---- - -## 8. Troubleshooting - -### Plugin fails to load - -- Confirm `.obsidian/plugins/paperforge/` has `main.js`, `manifest.json`, `styles.css` -- If upgrading from an old version: delete the entire `paperforge` plugin folder and reinstall via the community plugin browser -- Open Developer Console (`Ctrl+Shift+I`) and check the red errors - -### "Sync Runtime" doesn't update the version - -- The plugin may be calling a different Python than your terminal. Check Settings → Python path -- Try with `--no-cache-dir` to bypass pip cache -- Confirm `https://github.com/LLLin000/PaperForge` is reachable - -### OCR stays pending - -- Confirm `.env` has `PADDLEOCR_API_TOKEN` -- Run `paperforge ocr --diagnose` to check API connectivity -- PDF paths may be broken: run `paperforge repair --fix-paths` - -### No notes generated after sync - -- Is Better BibTeX auto-export configured in Zotero? Are JSON files in `exports/`? -- Run `paperforge doctor` to find which step failed - -### /pf-deep command does nothing - -- Make sure you're running it in your Agent app, not a terminal -- Confirm OCR is done (`ocr_status: done`) -- Confirm `analyze` is set to `true` - ---- - -## 9. Updating - -The Obsidian plugin auto-updates through the community plugin browser. For the Python package: +## 3. Quickstart ```bash -paperforge update -# or -pip install --upgrade paperforge -``` +# 1. Export from Zotero (Better BibTeX JSON, Keep updated) to exports/ +# 2. Sync +paperforge sync -If you installed via BRAT, it also auto-detects GitHub Release updates. +# 3. Mark a paper for OCR in its frontmatter: do_ocr: true +# 4. Run OCR +paperforge ocr + +# 5. Mark for deep reading: analyze: true +# 6. In your Agent chat: +/pf-deep <zotero_key> +``` --- -## 10. Architecture +## 文档导航 -``` -paperforge/ -├── core/ Contract layer — PFResult/ErrorCode/state machine -├── adapters/ Adapter layer — BBT parsing, paths, frontmatter I/O -├── services/ Service layer — SyncService orchestration -├── worker/ Worker layer — OCR, status, repair -├── commands/ CLI dispatch -├── setup/ Setup wizard (directories, agent deployment, Zotero linking) -├── plugin/ Obsidian plugin (Dashboard, settings panel) -└── schema/ Field registry -``` +| 你想做什么 | 去看 | +| ------------------------------------------ | ------------------------------ | +| 完整教程，从安装到精读 | [使用教程](docs/getting-started.md) | +| 遇到问题了 | [故障排除](docs/troubleshooting.md) | +| 查某个命令 | [命令参考](docs/COMMANDS.md) | +| 如何升级 | [更新指南](docs/update-upgrade.md) | +| 架构 / 维护 / 发布 | [架构文档](docs/ARCHITECTURE.md) | +| AI Agent 协作 | [AGENTS.md](AGENTS.md) | --- diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index d515b4db..d9760ee4 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -1,119 +1,104 @@ -# PaperForge 命令总览 +# PaperForge 命令参考 -> PaperForge 完整命令参考。Agent 命令与 CLI 命令对照表。 -> -> 另见：[AGENTS.md](../AGENTS.md) — 完整使用指南与架构说明 +> 所有 CLI 命令和 Agent 命令速查。 --- ## 命令矩阵 -| Agent 命令 | CLI 命令 | 说明 | 前置条件 | 示例 | -|-----------|---------|------|---------|------| -| `/pf-deep` | `paperforge sync` + `paperforge ocr` | 完整三阶段精读（Keshav 法） | OCR 完成 (`ocr_status: done`) | `/pf-deep ABCDEFG` | -| `/pf-paper` | `paperforge sync` | 快速摘要与问答工作台 | 正式笔记已生成 | `/pf-paper ABCDEFG` | -| `/pf-ocr` | `paperforge ocr` | PDF OCR 文本与图表提取 | PDF 存在 + `do_ocr: true` | `paperforge ocr` | -| `/pf-sync` | `paperforge sync` | 同步 Zotero 到文献库 | Better BibTeX JSON 导出 | `paperforge sync --domain 骨科` | -| `/pf-status` | `paperforge status` | 查看系统安装与运行状态 | 配置完成 | `paperforge status` | - -> **说明**：Agent 命令（`/pf-*`）在对话窗口中输入，由 AI Agent 执行。CLI 命令在终端中输入，由 Python worker 执行。 +| Agent 命令 | CLI 命令 | 用途 | 前置条件 | +|-----------|---------|------|---------| +| `/pf-sync` | `paperforge sync` | 同步 Zotero，生成正式笔记 | BBT JSON 导出 | +| `/pf-ocr` | `paperforge ocr` | PDF OCR 文本与图表提取 | `do_ocr: true` | +| `/pf-status` | `paperforge status` | 查看系统状态 | 配置完成 | +| `/pf-deep <key>` | `paperforge deep-reading` | 三阶段精读 | OCR done + `analyze: true` | +| `/pf-paper <key>` | — | 文献问答 | 正式笔记存在 | --- -## 快速参考 +## CLI 命令 -| 命令 | 一句话说明 | -|------|-----------| -| `/pf-deep <key>` | 对单篇论文进行 figure-by-figure 深度精读 | -| `/pf-paper <key>` | 加载论文 OCR 文本，进入问答模式 | -| `paperforge ocr` | 处理所有标记 `do_ocr: true` 的文献 | -| `paperforge sync` | 检测 Zotero 新条目，直接生成正式笔记 | -| `paperforge status` | 检查安装状态、配置、路径连通性 | +### `paperforge sync` ---- - -## 工作流参考 - -典型使用顺序（首次安装后）： - -### 第一步：同步文献 ```bash -paperforge sync +paperforge sync # 完整同步 +paperforge sync --dry-run # 预览 +paperforge sync --rebuild-index # 强制重建索引 +paperforge sync --json # JSON 输出 ``` -- 检测 Zotero JSON 中的新条目 -- 生成正式笔记 `<resources_dir>/<literature_dir>/<domain>/<key> - Title.md` -### 第二步：标记 OCR -在 Obsidian 中打开 formal note 文件，将 `do_ocr: false` 改为 `do_ocr: true`。 +### `paperforge ocr` -或使用命令行批量修改（高级用户）： ```bash -# 示例：批量标记某领域的所有文献 -grep -l "do_ocr: false" <resources_dir>/<literature_dir>/骨科/*.md | xargs sed -i 's/do_ocr: false/do_ocr: true/' +paperforge ocr # 处理队列 +paperforge ocr --key ABCDEFG # 处理指定文献 +paperforge ocr --diagnose # 诊断模式 +paperforge ocr --json # JSON 输出 ``` -### 第三步：运行 OCR +### `paperforge status` + ```bash -paperforge ocr +paperforge status # 完整状态 +paperforge status --json # JSON 输出 ``` -- 上传 PDF 到 PaddleOCR API -- 提取全文文本和图表 -- 输出到 `<system_dir>/PaperForge/ocr/<key>/` -### 第四步：标记精读 -在 formal note 中将 `analyze: false` 改为 `analyze: true`。 +### `paperforge doctor` -### 第五步：执行精读 -在 Agent 对话中输入： +```bash +paperforge doctor # 验证安装配置 +paperforge doctor --json # JSON 输出 ``` -/pf-deep ABCDEFG + +### `paperforge repair` + +```bash +paperforge repair # 扫描分歧（dry-run） +paperforge repair --fix # 修复 +paperforge repair --fix-paths # 修复 PDF 路径 +paperforge repair --json # JSON 输出 ``` -Agent 自动： -1. 检查 OCR 状态和 formal note -2. 生成 `## 精读` 骨架 -3. 逐阶段填写精读内容（Pass 1/2/3） -4. 验证结构完整性 ---- +### `paperforge deep-reading` -## 命令详情 +```bash +paperforge deep-reading # 查看精读队列 +paperforge deep-reading --verbose # 含修复指令 +``` -各命令的详细文档见对应文件： +### `paperforge embed` -- [`command/pf-deep.md`](../command/pf-deep.md) — 深度精读 -- [`command/pf-paper.md`](../command/pf-paper.md) — 快速摘要 -- [`command/pf-ocr.md`](../command/pf-ocr.md) — OCR 提取 -- [`command/pf-sync.md`](../command/pf-sync.md) — 文献同步 -- [`command/pf-status.md`](../command/pf-status.md) — 状态检查 +```bash +paperforge embed build # 构建向量索引 +paperforge embed build --resume # 续建 +paperforge embed status # 查看状态 +paperforge embed stop # 停止构建 +``` ---- +### `paperforge memory` -## 平台说明 +```bash +paperforge memory build # 构建 memory DB +paperforge memory status # 查看状态 +``` -### OpenCode +### `paperforge search` -- Agent 命令以 `/pf-` 前缀输入，支持文件附件 -- `/pf-deep` 和 `/pf-paper` 需要 OCR 完成的 PDF 作为上下文 -- Agent 使用 `paperforge paths --json` 获取 Vault 路径配置 -- 多篇文章并行精读时使用 `Task` tool 启动 subagent +```bash +paperforge search "<query>" --json +paperforge search "PEMF" --domain 骨科 --ocr done --year-from 2020 +``` -### Codex +### `paperforge runtime-health` -> **Future**：Codex 平台支持计划开发中。预计采用类似的 `/pf-*` 命令前缀，通过 API 调用 PaperForge CLI。 - -### Claude Code - -> **Future**：Claude Code 平台支持计划开发中。预计通过 `@paperforge` 提及或专用工具调用实现集成。 +```bash +paperforge runtime-health --json +``` --- ## 相关文档 -- [AGENTS.md](../AGENTS.md) — 完整使用指南、架构说明、常见问题 -- [docs/INSTALLATION.md](INSTALLATION.md) — 安装步骤 -- [docs/MIGRATION-v1.2.md](MIGRATION-v1.2.md) — v1.1 → v1.2 迁移指南 -- [docs/ARCHITECTURE.md](ARCHITECTURE.md) — 系统架构与设计决策 - ---- - -*PaperForge Lite v1.2 | 命令参考文档* +- [使用教程](getting-started.md) +- [故障排除](troubleshooting.md) +- [更新指南](update-upgrade.md) diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..10529fa1 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,90 @@ +# PaperForge 使用教程 + +> 面向终端用户。如果你刚安装完 PaperForge，从这里开始。 + +--- + +## 1. 安装后检查 + +1. Obsidian 已打开当前 Vault +2. PaperForge 插件已在设置中启用 +3. Python 运行时已确认（设置面板 --> 验证） + +--- + +## 2. 配置 Better BibTeX 自动导出 + +1. 打开 Zotero +2. 对你要同步的文献库或分类右键 -> `导出...` +3. 格式选：**Better BibTeX JSON** +4. 勾选 **"Keep updated"** +5. 保存到：`{你的Vault路径}/<system_dir>/PaperForge/exports/` + +> system_dir 默认是 `System`，例如保存到 `MyVault/System/PaperForge/exports/library.json` + +--- + +## 3. 第一次同步 + +打开 Dashboard（`Ctrl+P` -> `PaperForge: Open Main Panel`），点击 **Sync Library**。 + +或者终端执行： +```bash +paperforge sync +``` + +完成后，正式文献笔记出现在 `Resources/Literature/<领域>/` 下。 + +--- + +## 4. 触发 OCR + +在正式笔记的 frontmatter 里把 `do_ocr` 改为 `true`，然后运行： + +```bash +paperforge ocr +``` + +OCR 结果保存在 `System/PaperForge/ocr/<key>/` 下，包括全文文本和图表。 + +--- + +## 5. 深度精读 + +OCR 完成后，把 formal note 的 `analyze` 改为 `true`。 + +确认就绪： +```bash +paperforge deep-reading +``` + +在 Agent 中输入 `/pf-deep <zotero_key>`，Agent 会执行 Keshav 三阶段精读，结果直接写入 formal note 的 `## 精读` 区域。 + +--- + +## 6. 文献问答 + +不强制 OCR。直接输入 `/pf-paper <zotero_key>` 进入交互式问答。 + +--- + +## 7. 日常路径 + +``` +添加文献到 Zotero + -> BBT 自动导出到 exports/ + -> 点 Sync + -> 标记 do_ocr: true + -> 运行 OCR + -> 标记 analyze: true + -> /pf-deep <key> + -> /pf-paper <key> +``` + +--- + +## 8. 相关文档 + +- [命令参考](COMMANDS.md) — 所有 CLI 和 Agent 命令速查 +- [故障排除](troubleshooting.md) — 常见问题 +- [更新指南](update-upgrade.md) — 如何升级 PaperForge diff --git a/docs/maintainer-guide.md b/docs/maintainer-guide.md new file mode 100644 index 00000000..27e78c60 --- /dev/null +++ b/docs/maintainer-guide.md @@ -0,0 +1,74 @@ +# PaperForge 维护者指南 + +> 面向贡献者和维护者。 + +--- + +## 项目结构 + +``` +paperforge/ +├── core/ PFResult 契约层 +├── adapters/ BBT 解析、frontmatter、路径 +├── services/ SyncService 编排 +├── worker/ OCR、sync、status、repair +├── memory/ SQLite、ChromaDB、快照 +├── commands/ CLI 分发 +├── setup/ 安装向导 +├── schema/ field_registry.yaml +├── doctor/ 字段校验 +├── plugin/ Obsidian 插件 +│ ├── main.js UI + 快照读取 +│ └── src/testable.js 提取的纯函数 +└── skills/paperforge/ Agent skill 文件 +``` + +## 架构原则 + +1. Python 写 canonical 快照，JS 只读 +2. CLI 是所有命令的真相源 +3. `paperforge.json` 是路径真相源 +4. `formal-library.json` 是文献索引真相源 + +## 版本号 + +版本只在 `paperforge/__init__.py` 定义。升版本： + +```bash +python scripts/bump.py patch +python scripts/bump.py minor +``` + +自动更新：`__init__.py`、`manifest.json`、`versions.json`、git tag。 + +## 发布 + +```bash +python scripts/bump.py patch +git push && git push --tags +gh release create vX.Y.Z \ + --title "vX.Y.Z" \ + --notes "说明" \ + paperforge/plugin/main.js \ + paperforge/plugin/styles.css \ + paperforge/plugin/manifest.json \ + paperforge/plugin/versions.json +``` + +## 测试 + +```bash +ruff check --fix paperforge/ && ruff format paperforge/ +python -m pytest tests/unit/ tests/cli/ -v --tb=short +cd paperforge/plugin && npx vitest run +``` + +## i18n + +插件文案在 `paperforge/plugin/main.js` 的 `LANG` 对象中。中文 keys 在 `LANG.zh`，英文在 `LANG.en`。代码用 `t('key')` 读取。 + +## 相关文档 + +- [架构](ARCHITECTURE.md) +- [命令参考](COMMANDS.md) +- [AGENTS.md](../AGENTS.md) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..fe4e6129 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,67 @@ +# PaperForge 故障排除 + +--- + +## 插件无法加载 + +确认 `.obsidian/plugins/paperforge/` 下有 `main.js`、`manifest.json`、`styles.css`。 + +如果从旧版本升级：删除整个 `paperforge` 插件文件夹，通过社区插件浏览器重新安装。 + +打开开发者控制台（`Ctrl+Shift+I`）查看红色错误信息。 + +--- + +## "Sync Runtime" 不更新版本 + +插件可能调用了和终端不同的 Python。检查设置面板中的 Python Path。 + +如果仍不行，使用 `--no-cache-dir` 避开 pip 缓存。 + +确认 `https://github.com/LLLin000/PaperForge` 可访问。 + +--- + +## OCR 一直 pending + +1. 确认 `.env` 中有 `PADDLEOCR_API_TOKEN` +2. 运行 `paperforge ocr --diagnose` 检查接口连通性 +3. 如果 PDF 路径有问题，运行 `paperforge repair --fix-paths` + +--- + +## 同步后没有生成笔记 + +1. Zotero 的 Better BibTeX 自动导出配好了吗？JSON 文件在 `exports/` 下？ +2. 运行 `paperforge doctor` 定位失败步骤 + +--- + +## /pf-deep 无反应 + +前置条件：`ocr_status: done` 且 `analyze: true`。 + +确认队列就绪： +```bash +paperforge deep-reading --verbose +``` + +Agent 必须能访问 vault，确认 Agent 配置路径正确。 + +--- + +## Base 视图中 pdf_path 显示绝对路径 + +Obsidian 渲染问题，数据实际是相对路径。不影响功能。 + +--- + +## 命令参考 + +```bash +paperforge status # 查看系统状态 +paperforge doctor # 验证安装配置 +paperforge repair --fix # 修复状态分歧 +``` + +更多见 [命令参考](COMMANDS.md)。 diff --git a/docs/update-upgrade.md b/docs/update-upgrade.md new file mode 100644 index 00000000..47dcc801 --- /dev/null +++ b/docs/update-upgrade.md @@ -0,0 +1,32 @@ +# 更新与升级 + +--- + +## 插件更新 + +Obsidian 社区插件浏览器自动更新。BRAT 安装用户同样自动检测更新。 + +## Python 包更新 + +```bash +paperforge update +# 或 +pip install --upgrade paperforge +``` + +## 备份 + +更新前建议备份： +- `.env`（API key） +- `Resources/` 目录（文献笔记） +- `System/PaperForge/ocr/`（OCR 结果） + +## 迁移指南 + +大版本升级详见： +- [MIGRATION-v1.2.md](MIGRATION-v1.2.md) — v1.1 -> v1.2 +- [MIGRATION-v1.4.md](MIGRATION-v1.4.md) — v1.3 -> v1.4 + +--- + +相关问题见 [故障排除](troubleshooting.md)。 diff --git a/tests/test_command_docs.py b/tests/test_command_docs.py index 3626c9bf..6fab0bca 100644 --- a/tests/test_command_docs.py +++ b/tests/test_command_docs.py @@ -188,8 +188,8 @@ class TestPaperforgeCommandExamplesInUserDocs: @pytest.mark.parametrize( "doc_key,pattern", [ - ("README", r"paperforge (status|paths)"), - ("AGENTS", r"paperforge (status|paths)"), + ("README", r"paperforge (sync|ocr|status)"), + ("AGENTS", r"paperforge (search|status|sync)"), ], ) def test_user_doc_contains_paperforge_stable_example(