mirror of https://github.com/lllin000/PaperForge.git synced 2026-07-22 06:50:53 +00:00

Research Assistant abab8df3f5 feat(phase-10): add consistency audit script

- Add scripts/consistency_audit.py with 4 automated checks
- Check 1: No old command names in active code/docs
- Check 2: No paperforge_lite references in Python code
- Check 3: No dead internal links in markdown
- Check 4: Command docs have required sections

Fix violations found by audit:
- Update paperforge/ocr_diagnostics.py error messages to use new commands
- Update pipeline/worker/literature_pipeline.py generated content to use /pf-deep
- Update scripts/welcome.py to recommend /pf-deep
- Update skills/literature-qa/prompt_deep_subagent.md title to /pf-deep
- Update skills/literature-qa/scripts/ld_deep.py docstrings to /pf-deep
- Fix dead links in docs/COMMANDS.md and command/*.md
- Update AGENTS.md migration section to reference MIGRATION-v1.2.md
- Update paperforge/cli.py module docstring to use current commands

2026-04-24 18:06:35 +08:00

14 KiB

Raw Blame History

PaperForge Lite - Agent Guide

本文档面向 安装完成后的新用户 和 AI Agent。安装步骤见 INSTALLATION.md。

0. 安装后检查清单（第一次使用前必做）

[ ] Zotero 已安装 + Better BibTeX 插件已启用
[ ] Better BibTeX 已配置自动导出 JSON（见下方配置）
[ ] Obsidian 已打开当前 Vault
[ ] Python 依赖已安装 (pip install requests pymupdf pillow)
[ ] PaddleOCR API Key 已配置（在 .env 中）
[ ] 目录结构已创建（setup.py 会自动完成）
[ ] Zotero 数据目录已链接到 <system_dir>/Zotero

Better BibTeX 自动导出配置

Zotero → Edit → Preferences → Better BibTeX
勾选 "Keep updated"（自动导出）
选择导出格式：Better BibLaTeX 或 Better BibTeX
导出路径设置为：{你的Vault路径}/<system_dir>/PaperForge/exports/library.json
点击 OK，JSON 文件会自动生成并保持同步

1. 核心架构（Lite 版）

PaperForge Lite 采用 两层设计：

层级	组件	触发方式	作用
Worker 层	`literature_pipeline.py`（4 个 workers）	Python CLI	后台自动化
Agent 层	`/pf-deep`, `/pf-paper` 命令	用户手动触发	交互式精读

关键区别：

Worker 只做机械劳动（检测新文献、生成笔记、OCR）
Agent 只做深度思考（精读、分析、写作）
Worker 不会自动触发 Agent，Agent 不会自动触发 Worker

2. 完整数据流

Zotero 添加文献
    ↓ Better BibTeX 自动导出 JSON
<system_dir>/PaperForge/exports/library.json
    ↓ 运行 sync（selection-sync 阶段）
<resources_dir>/<control_dir>/library-records/<domain>/<key>.md
    ↓ 运行 sync（index-refresh 阶段）
<resources_dir>/<literature_dir>/<domain>/<key> - <Title>.md（正式笔记）
    ↓ 用户在 library-record 中设置 do_ocr: true
运行 ocr → <system_dir>/PaperForge/ocr/<key>/
    ↓ 用户在 library-record 中设置 analyze: true
运行 deep-reading（查看队列，确认就绪）
    ↓ 用户执行 Agent 命令
/pf-deep <zotero_key>
    ↓ Agent 生成
正式笔记中新增 ## 🔍 精读 区域

3. 目录结构（Lite 版，5 个核心目录）

{你的Vault根目录}/
├── <resources_dir>/
│   ├── <literature_dir>/                    ← 正式文献笔记（index-refresh 生成）
│   │   ├── 骨科/
│   │   ├── 运动医学/
│   │   └── ...（你的分类）
│   └── <control_dir>/             ← 状态跟踪
│       └── library-records/           ← selection-sync 输出
│           ├── 骨科/
│           │   └── ABCDEFG.md         ← 单条文献状态记录
│           └── 运动医学/
│               └── HIJKLMN.md
│
├── <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    ← 图表索引（自动创建）
│   │   └── worker/scripts/
│   │       └── literature_pipeline.py ← 核心脚本
│   └── 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（index-refresh 阶段）生成，Agent 写入精读
`<resources_dir>/<control_dir>/library-records/`	文献状态跟踪（analyze, ocr_status 等）	sync（selection-sync 阶段）生成，用户修改状态
`<system_dir>/PaperForge/exports/`	Better BibTeX JSON 导出	Zotero 自动导出
`<system_dir>/PaperForge/ocr/`	OCR 全文 + 图表切割	ocr worker 生成
`<system_dir>/Zotero/`	Zotero 数据目录的链接	安装时手动创建 junction

4. 核心 Workers（Lite 版，4 个）

sync

作用：检测 Zotero 中的新条目并生成正式文献笔记（selection-sync + index-refresh 的统一入口）
运行时机：添加新文献到 Zotero 后，或需要更新笔记格式时
输出：
- <resources_dir>/<control_dir>/library-records/<domain>/<key>.md
- <resources_dir>/<literature_dir>/<domain>/<key> - <Title>.md

示例：

paperforge sync
# 仅同步 Zotero 到 library-records
paperforge sync --selection
# 仅根据现有 library-records 生成正式笔记
paperforge sync --index
# Legacy (备用):
# python <system_dir>/PaperForge/worker/scripts/literature_pipeline.py \
#   --vault "{vault路径}" selection-sync
# python <system_dir>/PaperForge/worker/scripts/literature_pipeline.py \
#   --vault "{vault路径}" index-refresh

ocr

作用：将 PDF 上传到 PaddleOCR API，提取全文文本和图表
触发条件：library-record 中 do_ocr: true
输出：<system_dir>/PaperForge/ocr/<key>/ 目录
- fulltext.md：提取的全文（含  分页标记）
- images/：自动切割的图表图片
- meta.json：OCR 状态（ocr_status: done/pending/processing/failed）
- figure-map.json：图表索引（后续自动生成）
注意：OCR 是异步的，大文件可能需要几分钟

示例：

paperforge ocr
# 诊断模式（不运行，仅检查状态）
paperforge ocr --diagnose
# Legacy (备用):
# python <system_dir>/PaperForge/worker/scripts/literature_pipeline.py \
#   --vault "{vault路径}" ocr

deep-reading

作用：扫描所有 library-records，列出 analyze=true 且 OCR 完成的文献
运行时机：用户想看看哪些文献可以开始精读了
输出：控制台表格，显示队列状态
重要：这只是查看队列，不会自动触发 Agent 精读

示例：

paperforge deep-reading
paperforge deep-reading --verbose  # 显示阻塞条目的修复指令
# Legacy (备用):
# python <system_dir>/PaperForge/worker/scripts/literature_pipeline.py \
#   --vault "{vault路径}" deep-reading

5. Agent 命令（用户手动触发）

命令	用途	前置条件
`/pf-deep <zotero_key>`	完整 Keshav 三阶段精读	OCR 完成 (`ocr_status: done`)
`/pf-paper <zotero_key>`	快速摘要（无 OCR 要求）	有正式笔记即可

/pf-deep 执行流程

prepare 阶段（自动）：
- 查找 library-record（确认 analyze: true）
- 检查 OCR 状态
- 读取 formal note
- 生成 figure-map.json（图表索引）
- 生成 chart-type-map.json（图表类型识别）
- 在正式笔记中插入 ## 🔍 精读 骨架
精读阶段（Agent 执行）：
- Pass 1: 概览（5-10 分钟快速扫描）
- Pass 2: 精读还原（逐图逐表分析）
- Pass 3: 深度理解（批判性评估 + 迁移思考）
验证阶段（自动）：
- 检查 callout 间距
- 检查必要 section 是否完整
- 检查 figure/table embed 是否存在

6. Frontmatter 字段参考

Library Record（`library-records/<domain>/<key>.md`）

这是用户控制工作流的核心。每个文献对应一个 record 文件：

---
zotero_key: "ABCDEFG"           # Zotero citation key（自动生成）
domain: "骨科"                   # 分类领域（对应 Zotero 收藏夹）
title: "论文标题"
year: 2024
doi: "10.xxxx/xxxxx"
collection_path: "子分类"        # Zotero 子收藏夹路径
has_pdf: true                    # 是否有 PDF 附件（自动生成）
pdf_path: "<system_dir>/Zotero/..." # PDF 相对路径（自动生成）
fulltext_md_path: "<system_dir>/PaperForge/ocr/..."
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）
analysis_note: ""                # 预留字段
---

用户操作方式：

在 Obsidian 中打开 library-record 文件
修改 analyze: false → analyze: true 标记要精读的文献
修改 do_ocr: false → do_ocr: true 触发 OCR
或使用 Obsidian Base 视图批量操作

Formal Note（`Literature/<domain>/<key> - <Title>.md`）

这是最终产出的笔记，包含元数据 + 精读内容：

---
title: "论文标题"
year: 2024
type: "journal"
journal: "Journal Name"
impact_factor: 5.2
category: "骨科"
tags:
  - 文献阅读
  - 子分类
keywords: ["keyword1", "keyword2"]
pdf_link: "<system_dir>/Zotero/..."
---

7. 第一次使用指南（手把手）

Step 1: 确认 Zotero 有文献

确保 Zotero 中已有至少一篇带 PDF 的文献，且 Better BibTeX 已导出 JSON。

Step 2: 运行 sync

# 在 Vault 根目录执行
paperforge sync

预期输出：

[INFO] Found 5 new items
[INFO] Created library-records/骨科/XXXXXXX.md
[INFO] Generated 5 formal notes
[INFO] Output: <resources_dir>/<literature_dir>/骨科/XXXXXXX - Title.md
...

如需分阶段执行：

paperforge sync --selection — 仅同步 Zotero 到 library-records

paperforge sync --index — 仅根据现有 library-records 生成正式笔记

Step 3: 标记要精读的文献

在 Obsidian 中：

打开 <resources_dir>/<control_dir>/library-records/骨科/XXXXXXX.md
将 do_ocr: false 改为 do_ocr: true
将 analyze: false 改为 analyze: true
保存文件

Step 4: 运行 OCR

paperforge ocr

等待完成（可能需要几分钟）。

Step 5: 检查 OCR 状态

paperforge deep-reading

预期输出：

## 就绪 (1 篇) — OCR 完成
- `XXXXXXX` | 骨科 | 论文标题

Step 6: 执行精读

在 OpenCode Agent 中输入：

/pf-deep XXXXXXX

Agent 会自动：

准备精读骨架（prepare）
逐阶段填写精读内容
验证结构完整性

Step 7: 查看结果

在 Obsidian 中打开正式笔记，找到 ## 🔍 精读 区域，精读已完成。

8. 常用命令速查

# 检测 Zotero 新条目并生成正式笔记
paperforge sync

# 仅同步 Zotero 到 library-records
paperforge sync --selection

# 仅根据现有 library-records 生成正式笔记
paperforge sync --index

# 运行 OCR（处理 do_ocr=true 的文献）
paperforge ocr
paperforge ocr --diagnose  # 诊断模式，不实际运行

# 查看精读队列
paperforge deep-reading
paperforge deep-reading --verbose  # 显示阻塞条目修复指令

# 修复状态分歧（默认 dry-run）
paperforge repair --verbose        # 查看三向状态分歧详情
paperforge repair --fix           # 实际修复（慎用）

# 查看整体状态
paperforge status

# 验证安装配置
paperforge doctor

如果 paperforge 命令未注册，可使用 fallback：
python -m paperforge <command>
例如：python -m paperforge status

Agent 命令

/pf-deep <zotero_key>    # 完整三阶段精读
/pf-paper <zotero_key>   # 快速摘要

9. 常见问题

Q: 运行 sync 后没有生成 library-records？

检查 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 未完成？

确认 library-record 中 ocr_status: done
如 OCR 失败，可重新设置 do_ocr: true 再运行 ocr worker

Q: Base 视图中 pdf_path 显示为绝对路径？

这是 Obsidian 渲染问题，数据本身是相对路径
不影响功能，可忽略

Q: 可以批量操作吗？

可以。使用 Obsidian Base 视图批量修改 do_ocr 和 analyze 字段
或使用脚本批量修改 library-records 中的 frontmatter

10. 升级与维护

更新 PaperForge 代码

cd 你的Vault路径
# 如果你有 git 跟踪 PaperForge
git pull origin main

# 或手动复制更新文件
cp -r 新下载的scripts/* <system_dir>/PaperForge/worker/scripts/

备份注意事项

<resources_dir>/ 和 <system_dir>/PaperForge/ocr/ 包含你的数据，需备份
.env 包含 API Key，不要提交到 git
<system_dir>/PaperForge/exports/ 可重新生成（由 Zotero 自动导出）

11. 命令迁移说明（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），但文档已统一使用新命令。

详细迁移步骤和回滚说明参见 docs/MIGRATION-v1.2.md。

PaperForge Lite | 快速开始指南 | 安装后阅读

14 KiB Raw Blame History Unescape Escape