diff --git a/AGENTS.md b/AGENTS.md index 7c962f2a..f26a4db1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,173 +1,402 @@ -# Agent Guide for Medical Research Vault +# PaperForge Lite - Agent Guide -This repository is an Obsidian Vault dedicated to Medical Research (Sports Medicine, Orthopedics). It integrates closely with Zotero and PubMed via MCP tools. - -## 0. AGENT PROTOCOL (MANDATORY) - -**You possess superhuman capabilities via 147+ specialized skills.** -Most tasks fail because agents try to "wing it" instead of using the specialized tools provided. - -### 🛑 STOP & CHECK: The Skill Audit -**Before executing ANY task, you MUST perform this audit:** - -1. **CLASSIFY**: What is the domain? (Bioinformatics, Clinical, Writing, Dev, Data) -2. **SCAN**: Look at the [Skill Domain Index](#1-skill-domain-index) below. -3. **SELECT**: Pick the best tool for the job. -4. **LOAD**: Execute `skill({ name: "selected-skill" })`. - -**Rule of Thumb**: If you are writing Python code for biology, chemistry, or plotting from scratch, **YOU ARE WRONG**. Load a skill instead. +> 本文档面向 **安装完成后的新用户** 和 **AI Agent**。安装步骤见 [INSTALLATION.md](docs/INSTALLATION.md)。 --- -## 1. Skill Domain Index +## 0. 安装后检查清单（第一次使用前必做） -Use this index to quickly find the right tool. +``` +[ ] Zotero 已安装 + Better BibTeX 插件已启用 +[ ] Better BibTeX 已配置自动导出 JSON（见下方配置） +[ ] Obsidian 已打开当前 Vault +[ ] Python 依赖已安装 (pip install requests pymupdf pillow) +[ ] PaddleOCR API Key 已配置（在 .env 中） +[ ] 目录结构已创建（setup.py 会自动完成） +[ ] Zotero 数据目录已链接到 99_System/Zotero +``` -### 🧬 Bioinformatics & Genomics -| Skill | Use When... | -| -------------------- | ------------------------------------------------------------------- | -| `biopython` | Parsing FASTA/GenBank, BLAST, basic sequence manipulation. | -| `scanpy` / `anndata` | **Single-cell RNA-seq** analysis, clustering, trajectory inference. | -| `pysam` | Handling **BAM/SAM/VCF** files (NGS data). | -| `deeptools` | ChIP-seq/ATAC-seq visualization (heatmaps, profiles). | -| `scvi-tools` | Deep probabilistic modeling for single-cell data. | -| `etetoolkit` | Phylogenetic trees, evolution, orthology. | -| `scikit-bio` | Microbiome analysis, diversity metrics (UniFrac). | +### Better BibTeX 自动导出配置 -### 🏥 Clinical & Medical -| Skill | Use When... | -|-------|-------------| -| `pubmed-database` | **Literature search**, retrieving abstracts/citations. | -| `clinicaltrials-database` | Searching ClinicalTrials.gov for study protocols/status. | -| `clinical-decision-support` | Generating GRADE-based guidelines or patient cohort analysis. | -| `pyhealth` | Analyzing **EHR data**, clinical prediction models (ICD/CPT). | -| `pydicom` | Reading/processing **DICOM** medical images (CT/MRI). | -| `clinvar-database` | Checking variant pathogenicity/clinical significance. | -| `iso-13485-certification` | Medical device QMS documentation. | - -### 🧪 Chemistry & Drug Discovery -| Skill | Use When... | -|-------|-------------| -| `rdkit` / `datamol` | **Cheminformatics**, SMILES parsing, molecule generation. | -| `chembl-database` | Looking up bioactivity data ($IC_{50}$, $K_i$), drug targets. | -| `pubchem-database` | Searching chemical properties, structures by name. | -| `drugbank-database` | Detailed drug pharmacology, interactions, targets. | -| `diffdock` | **Molecular docking** (protein-ligand binding poses). | -| `alphafold-database` | Retrieving 3D protein structures. | - -### 📊 Data Science & Statistics -| Skill | Use When... | -|-------|-------------| -| `polars` | Processing **Large DataFrames** (faster than Pandas). | -| `scikit-survival` | **Survival analysis** (Kaplan-Meier, Cox Proportional Hazards). | -| `statistical-analysis` | Performing rigorous statistical tests (ANOVA, t-tests) with APA reporting. | -| `scientific-visualization` | Creating **Publication-Ready** figures (Matplotlib/Seaborn wrappers). | -| `shap` | Explaining ML model predictions (Feature importance). | -| `pymc` | Bayesian modeling and probabilistic programming. | - -### ✍️ Writing & Research -| Skill | Use When... | -|-------|-------------| -| `scientific-writing` | Drafting **Full Manuscripts** (IMRAD structure, academic tone). | -| `literature-review` | Conducting systematic reviews across multiple databases. | -| `citation-management` | Finding citations, formatting BibTeX, verifying references. | -| `latex-posters` | Creating conference posters in LaTeX. | -| `research-grants` | Writing NSF/NIH grant proposals. | -| `zotero-lit-review` | **Local Vault Search**. ALWAYS check this before external search. | - -### 🛠️ Dev & Automation -| Skill | Use When... | -|-------|-------------| -| `git-master` | Any GIT operation (commit, log, blame). | -| `frontend-ui-ux` | React/Web UI tasks. | -| `playwright` | Browser automation / scraping. | -| `opentrons-integration` | Writing lab automation scripts (OT-2 robots). | +1. Zotero → Edit → Preferences → Better BibTeX +2. 勾选 **"Keep updated"**（自动导出） +3. 选择导出格式：**Better BibLaTeX** 或 **Better BibTeX** +4. 导出路径设置为：`{你的Vault路径}/99_System/LiteraturePipeline/exports/library.json` +5. 点击 OK，JSON 文件会自动生成并保持同步 --- -## 2. Environment & Tech Stack +## 1. 核心架构（Lite 版） -- **Platform**: Obsidian (Knowledge Management) -- **Reference Manager**: Zotero (via MCP & Direct SQLite Access) -- **Data Source**: PubMed (via MCP) -- **Primary Language**: Simplified Chinese (简体中文) -- **Scripting**: JavaScript (Handlebars helpers for Templater), Markdown, Python (Zotero interaction) +PaperForge Lite 采用 **两层设计**： -## 3. Workflows & Commands ("Build/Test") +| 层级 | 组件 | 触发方式 | 作用 | +|------|------|----------|------| +| **Worker 层** | `literature_pipeline.py`（4 个 workers） | Python CLI | 后台自动化 | +| **Agent 层** | `/LD-deep`, `/LD-paper` 命令 | 用户手动触发 | 交互式精读 | -Since this is a knowledge base, "Build" corresponds to importing and structuring knowledge, and "Test" corresponds to verification. +**关键区别**： +- **Worker 只做机械劳动**（检测新文献、生成笔记、OCR） +- **Agent 只做深度思考**（精读、分析、写作） +- Worker 不会自动触发 Agent，Agent 不会自动触发 Worker -### Literature Search (The "Build" Loop) -Agents must follow this strict loop when asked to find literature: -1. **Analyze**: Use `parse_pico` to structure the research question. -2. **Search**: Use `search_literature` (PubMed) or `zotero-lit-review` (Local Library). - * *Constraint*: Always check existing library first using `check_articles_owned`, `search_pubmed_exclude_owned`, or `zotero-lit-review search`. -3. **Verify**: Use `get_session_pmids` to confirm what was found. -4. **Import**: - * **CRITICAL**: Ask user for Target Collection first (`list_collections`). - * Use `batch_import_from_pubmed` for multiple items. - * Use `import_from_pmids` for specific items. +--- -### Library Maintenance (The "Lint" Loop) -- **Check Duplicates**: Before adding, always check if PMID exists (`check_articles_owned`). -- **Stats**: Use `get_library_stats` to understand collection size. +## 2. 完整数据流 -## 4. Style Guidelines +``` +Zotero 添加文献 + ↓ Better BibTeX 自动导出 JSON +99_System/LiteraturePipeline/exports/library.json + ↓ 运行 selection-sync +03_Resources/LiteratureControl/library-records//.md + ↓ 运行 index-refresh +03_Resources/Literature// - .md（正式笔记） + ↓ 用户在 library-record 中设置 do_ocr: true +运行 ocr → 99_System/LiteraturePipeline/ocr/<key>/ + ↓ 用户在 library-record 中设置 analyze: true +运行 deep-reading（查看队列，确认就绪） + ↓ 用户执行 Agent 命令 +/LD-deep <zotero_key> + ↓ Agent 生成 +正式笔记中新增 ## 🔍 精读 区域 +``` -### Markdown & Note Structure +--- -Literature notes are generated automatically by the pipeline with standard frontmatter. +## 3. 目录结构（Lite 版，5 个核心目录） + +``` +{你的Vault根目录}/ +├── 03_Resources/ +│ ├── Literature/ ← 正式文献笔记（index-refresh 生成） +│ │ ├── 骨科/ +│ │ ├── 运动医学/ +│ │ └── ...（你的分类） +│ └── LiteratureControl/ ← 状态跟踪 +│ └── library-records/ ← selection-sync 输出 +│ ├── 骨科/ +│ │ └── ABCDEFG.md ← 单条文献状态记录 +│ └── 运动医学/ +│ └── HIJKLMN.md +│ +├── 99_System/ +│ ├── LiteraturePipeline/ +│ │ ├── 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 ← 核心脚本 +│ ├── Template/ +│ │ └── 科研读图指南.md ← 图表阅读参考 +│ └── Zotero/ ← Junction/Symlink 到 Zotero 数据目录 +│ +├── .opencode/ ← OpenCode Agent 配置（自动创建） +│ └── skills/ +│ └── literature-qa/ ← 深度阅读 Skill +│ ├── scripts/ +│ │ └── ld_deep.py ← /LD-deep 核心脚本 +│ ├── prompt_deep_subagent.md ← Agent 精读提示词 +│ └── chart-reading/ ← 14 种图表阅读指南 +│ +├── .env ← API Key 等敏感配置 +└── AGENTS.md ← 本文件 +``` + +### 各目录作用速查 + +| 目录 | 内容 | 谁生成/修改 | +|------|------|------------| +| `03_Resources/Literature/` | 正式文献笔记（含 frontmatter + 精读内容） | index-refresh 生成，Agent 写入精读 | +| `03_Resources/LiteratureControl/library-records/` | 文献状态跟踪（analyze, ocr_status 等） | selection-sync 生成，用户修改状态 | +| `99_System/LiteraturePipeline/exports/` | Better BibTeX JSON 导出 | Zotero 自动导出 | +| `99_System/LiteraturePipeline/ocr/` | OCR 全文 + 图表切割 | ocr worker 生成 | +| `99_System/Zotero/` | Zotero 数据目录的链接 | 安装时手动创建 junction | + +--- + +## 4. 核心 Workers（Lite 版，4 个） + +### selection-sync +- **作用**：检测 Zotero 中的新条目，创建 library-records +- **运行时机**：添加新文献到 Zotero 后 +- **输出**：`03_Resources/LiteratureControl/library-records/<domain>/<key>.md` +- **示例**： + ```bash + python 99_System/LiteraturePipeline/worker/scripts/literature_pipeline.py \ + --vault "{vault路径}" selection-sync + ``` + +### index-refresh +- **作用**：基于 library-records 生成正式文献笔记 +- **运行时机**：selection-sync 之后，或需要更新笔记格式时 +- **输出**：`03_Resources/Literature/<domain>/<key> - <Title>.md` +- **说明**：会读取 Better BibTeX JSON 提取元数据，生成带 frontmatter 的 Obsidian 笔记 + +### ocr +- **作用**：将 PDF 上传到 PaddleOCR API，提取全文文本和图表 +- **触发条件**：library-record 中 `do_ocr: true` +- **输出**：`99_System/LiteraturePipeline/ocr/<key>/` 目录 + - `fulltext.md`：提取的全文（含 `<!-- page N -->` 分页标记） + - `images/`：自动切割的图表图片 + - `meta.json`：OCR 状态（`ocr_status: done/pending/processing/failed`） + - `figure-map.json`：图表索引（后续自动生成） +- **注意**：OCR 是异步的，大文件可能需要几分钟 + +### deep-reading +- **作用**：扫描所有 library-records，列出 `analyze=true` 且 OCR 完成的文献 +- **运行时机**：用户想看看哪些文献可以开始精读了 +- **输出**：控制台表格，显示队列状态 +- **重要**：这只是**查看队列**，不会自动触发 Agent 精读 + +--- + +## 5. Agent 命令（用户手动触发） + +| 命令 | 用途 | 前置条件 | +|------|------|----------| +| `/LD-deep <zotero_key>` | 完整 Keshav 三阶段精读 | OCR 完成 (`ocr_status: done`) | +| `/LD-paper <zotero_key>` | 快速摘要（无 OCR 要求） | 有正式笔记即可 | + +### /LD-deep 执行流程 + +1. **prepare 阶段**（自动）： + - 查找 library-record（确认 `analyze: true`） + - 检查 OCR 状态 + - 读取 formal note + - 生成 figure-map.json（图表索引） + - 生成 chart-type-map.json（图表类型识别） + - 在正式笔记中插入 `## 🔍 精读` 骨架 + +2. **精读阶段**（Agent 执行）： + - Pass 1: 概览（5-10 分钟快速扫描） + - Pass 2: 精读还原（逐图逐表分析） + - Pass 3: 深度理解（批判性评估 + 迁移思考） + +3. **验证阶段**（自动）： + - 检查 callout 间距 + - 检查必要 section 是否完整 + - 检查 figure/table embed 是否存在 + +--- + +## 6. Frontmatter 字段参考 + +### Library Record（`library-records/<domain>/<key>.md`） + +这是**用户控制工作流的核心**。每个文献对应一个 record 文件： -**Frontmatter (YAML) is MANDATORY:** ```yaml --- -title: " {{Title}} " -year: {{Year}} -type: {{Type}} -journal: " {{Journal}} " -impact_factor: {{IF}} -category: {{Category}} -tags: - - 文献阅读 - - {{Subject_Tag}} -keywords: [ {{Keywords}} ] -pdf_link: "[[{{Link_To_PDF}}]]" +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/..." # PDF 相对路径（自动生成） +fulltext_md_path: "99_System/LiteraturePipeline/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: "" # 预留字段 --- ``` -**Content Structure:** -- H1: Title -- H2: 📄 文献基本信息 (Basic Info) -- H2: 💡 文献内容总结 (Summary) -- H2: 🚀 未来方向 (Future Directions) -- H2: 📝 个人备注与补充 (Notes) +**用户操作方式**： +- 在 Obsidian 中打开 library-record 文件 +- 修改 `analyze: false` → `analyze: true` 标记要精读的文献 +- 修改 `do_ocr: false` → `do_ocr: true` 触发 OCR +- 或使用 Obsidian Base 视图批量操作 -### JavaScript (Templater/Handlebars) -- **Location**: `99_System/Template/*.js` -- **Style**: Standard ES6+. -- **Helpers**: Register helpers using `handlebars.registerHelper`. -- **Error Handling**: Fail gracefully (return empty string) if data is missing. +### Formal Note（`Literature/<domain>/<key> - <Title>.md`） -## 5. Interaction Rules +这是最终产出的笔记，包含元数据 + 精读内容： -### Language -- **Output**: Simplified Chinese (简体中文) ONLY, unless asked otherwise. -- **Search Terms**: English (for PubMed), but explain in Chinese. +```yaml +--- +title: "论文标题" +year: 2024 +type: "journal" +journal: "Journal Name" +impact_factor: 5.2 +category: "骨科" +tags: + - 文献阅读 + - 子分类 +keywords: ["keyword1", "keyword2"] +pdf_link: "99_System/Zotero/..." +--- +``` -### Protocol -1. **No Hallucinations**: Never invent PMIDs or citations. -2. **User Confirmation**: - - Confirm **Search Strategy** before executing deep searches. - - Confirm **Target Collection** before importing to Zotero. -3. **Session Awareness**: Use `get_session_summary` to track context. +--- -## 6. Custom Skills +## 7. 第一次使用指南（手把手） -The following skills are installed in `.opencode/skills` and available for complex tasks. -**NOTE: This list is exhaustive. Use the Index in Section 1 for quick lookup.** +### Step 1: 确认 Zotero 有文献 -(Complete skill list would be here - truncated for brevity) +确保 Zotero 中已有至少一篇带 PDF 的文献，且 Better BibTeX 已导出 JSON。 -## 7. External Rules Integration -- **Copilot Instructions**: See `.github/copilot-instructions.md` for detailed MCP tool usage. -- **Workflow**: See `.github/zotero-research-workflow.md` for the authorized PICO -> Search -> Import pipeline. +### Step 2: 运行 selection-sync + +```bash +# 在 Vault 根目录执行 +python 99_System/LiteraturePipeline/worker/scripts/literature_pipeline.py \ + --vault "你的Vault路径" selection-sync +``` + +预期输出： +``` +[INFO] Found 5 new items +[INFO] Created library-records/骨科/XXXXXXX.md +... +``` + +### Step 3: 运行 index-refresh + +```bash +python 99_System/LiteraturePipeline/worker/scripts/literature_pipeline.py \ + --vault "你的Vault路径" index-refresh +``` + +预期输出： +``` +[INFO] Generated 5 formal notes +[INFO] Output: 03_Resources/Literature/骨科/XXXXXXX - Title.md +... +``` + +### Step 4: 标记要精读的文献 + +在 Obsidian 中： +1. 打开 `03_Resources/LiteratureControl/library-records/骨科/XXXXXXX.md` +2. 将 `do_ocr: false` 改为 `do_ocr: true` +3. 将 `analyze: false` 改为 `analyze: true` +4. 保存文件 + +### Step 5: 运行 OCR + +```bash +python 99_System/LiteraturePipeline/worker/scripts/literature_pipeline.py \ + --vault "你的Vault路径" ocr +``` + +等待完成（可能需要几分钟）。 + +### Step 6: 检查 OCR 状态 + +```bash +python 99_System/LiteraturePipeline/worker/scripts/literature_pipeline.py \ + --vault "你的Vault路径" deep-reading +``` + +预期输出： +``` +## 就绪 (1 篇) — OCR 完成 +- `XXXXXXX` | 骨科 | 论文标题 +``` + +### Step 7: 执行精读 + +在 OpenCode Agent 中输入： +``` +/LD-deep XXXXXXX +``` + +Agent 会自动： +1. 准备精读骨架（prepare） +2. 逐阶段填写精读内容 +3. 验证结构完整性 + +### Step 8: 查看结果 + +在 Obsidian 中打开正式笔记，找到 `## 🔍 精读` 区域，精读已完成。 + +--- + +## 8. 常用命令速查 + +```bash +# 检测 Zotero 新条目 +python 99_System/LiteraturePipeline/worker/scripts/literature_pipeline.py \ + --vault "你的Vault路径" selection-sync + +# 生成/更新正式笔记 +python 99_System/LiteraturePipeline/worker/scripts/literature_pipeline.py \ + --vault "你的Vault路径" index-refresh + +# 运行 OCR（处理 do_ocr=true 的文献） +python 99_System/LiteraturePipeline/worker/scripts/literature_pipeline.py \ + --vault "你的Vault路径" ocr + +# 查看精读队列 +python 99_System/LiteraturePipeline/worker/scripts/literature_pipeline.py \ + --vault "你的Vault路径" deep-reading + +# 查看整体状态 +python 99_System/LiteraturePipeline/worker/scripts/literature_pipeline.py \ + --vault "你的Vault路径" status +``` + +### Agent 命令 +``` +/LD-deep <zotero_key> # 完整三阶段精读 +/LD-paper <zotero_key> # 快速摘要 +``` + +--- + +## 9. 常见问题 + +### Q: 运行 selection-sync 后没有生成 library-records？ +- 检查 Better BibTeX JSON 导出路径是否正确 +- 检查 JSON 文件是否包含文献数据 +- 确认 Zotero 中该文献有 citation key + +### Q: OCR 一直显示 pending？ +- 检查 PaddleOCR API Key 是否配置正确（`.env` 文件） +- 检查网络连接 +- 查看 `99_System/LiteraturePipeline/ocr/<key>/meta.json` 中的错误信息 + +### Q: /LD-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 代码 +```bash +cd 你的Vault路径 +# 如果你有 git 跟踪 PaperForge +git pull origin main + +# 或手动复制更新文件 +cp -r 新下载的scripts/* 99_System/LiteraturePipeline/worker/scripts/ +``` + +### 备份注意事项 +- `03_Resources/` 和 `99_System/LiteraturePipeline/ocr/` 包含你的数据，需备份 +- `.env` 包含 API Key，不要提交到 git +- `99_System/LiteraturePipeline/exports/` 可重新生成（由 Zotero 自动导出） + +--- + +*PaperForge Lite | 快速开始指南 | 安装后阅读* diff --git a/scripts/setup.py b/scripts/setup.py index 94ea017f..19f6228e 100644 --- a/scripts/setup.py +++ b/scripts/setup.py @@ -302,7 +302,11 @@ def create_env_file(vault_path: Path, config: dict, paths: dict) -> None: def create_agents_md(vault_path: Path, config: dict, paths: dict, agent_config: dict) -> None: - """Create generic AGENTS.md template.""" + """Generate AGENTS.md with user-configured paths embedded. + + This creates a complete Lite-version workflow guide that is personalized + to the user's chosen directory structure, not a static template. + """ agents_path = vault_path / "AGENTS.md" if agents_path.exists(): @@ -310,123 +314,430 @@ def create_agents_md(vault_path: Path, config: dict, paths: dict, agent_config: print_warning("Skipping AGENTS.md creation") return - content = f"""# Agent Guide for PaperForge Literature Workflow + # Build the personalized AGENTS.md content + # All paths come from the user's configuration (paths dict) + content = f"""# PaperForge Lite - Agent Guide -This vault uses PaperForge -- an automated literature research pipeline. +> 本文档面向 **安装完成后的新用户** 和 **AI Agent**。 +> 安装步骤见 [INSTALLATION.md](docs/INSTALLATION.md)。 +> 本 Vault 使用自定义目录结构生成，路径以实际配置为准。 -## Agent Configuration +--- -- **Platform**: {agent_config['name']} -- **Skill Directory**: `{agent_config['skill_dir']}` -- **Config File**: {agent_config.get('config_file', 'None')} - -## PaperForge Directory Structure - -PaperForge manages the following directories (do NOT rename): +## 0. 安装后检查清单（第一次使用前必做） ``` -{paths['system_dir']}/ - LiteraturePipeline/ # Core pipeline (managed by PaperForge) - candidates/ # Candidate literature - inbox/ # Search result inbox - archive/ # Archived events - exports/ # Better BibTeX JSON exports - indexes/ # Generated indices - ocr/ # OCR outputs - <zotero_key>/ # fulltext.md + images/ - search/ # Search tasks & results - tasks/ # Search configurations - results/ # Result cache - writeback/ # Writeback queue & logs - worker/ # Worker scripts - scripts/ # literature_pipeline.py - tests/ # Test files - Template/ # Templates - 文献阅读.md # Literature note template - 科研读图指南.md # Chart reading guide index - 读图指南/ # 14 chart type guides - Zotero/ # Zotero data (junction) - zotero.sqlite # Linked via junction/symlink - -03_Resources/ - Literature/ # Your literature notes (generated by index-refresh) - <domain>/ # e.g., 骨科/, 运动医学/ - LiteratureControl/ # PaperForge control files - library-records/ # Library tracking (analyze/ocr/deep flags) +[ ] Zotero 已安装 + Better BibTeX 插件已启用 +[ ] Better BibTeX 已配置自动导出 JSON（见下方配置） +[ ] Obsidian 已打开当前 Vault +[ ] Python 依赖已安装 (pip install requests pymupdf pillow) +[ ] PaddleOCR API Key 已配置（在 .env 中） +[ ] 目录结构已创建（setup.py 会自动完成） +[ ] Zotero 数据目录已链接到 {paths['system_dir']}/Zotero ``` -Your personal PARA folders (00_Inbox, 01_Projects, 02_Areas, 04_Archives, 05_Bases, 06_AI_Wiki) are NOT managed by PaperForge. +### Better BibTeX 自动导出配置 -## 1. Environment & Tech Stack +1. Zotero → Edit → Preferences → Better BibTeX +2. 勾选 **"Keep updated"**（自动导出） +3. 选择导出格式：**Better BibLaTeX** 或 **Better BibTeX** +4. 导出路径设置为：`{vault_path}/{paths['pipeline_path']}/exports/library.json` +5. 点击 OK，JSON 文件会自动生成并保持同步 -- **Platform**: Obsidian (Knowledge Management) -- **Reference Manager**: Zotero (Better BibTeX auto-export) -- **OCR**: PaddleOCR-VL API -- **Primary Language**: Simplified Chinese (简体中文) -- **Scripting**: Python 3.10+ +--- -## 2. Workflows +## 1. 核心架构（Lite 版） -### Phase 1: Index & Notes -Better BibTeX auto-export JSON → selection_sync + index_refresh → formal-library.json + 03_Resources/Literature/<domain>/*.md +PaperForge Lite 采用 **两层设计**： -### Phase 2: Deep Processing -Library records flagged for analyze → OCR (PaddleOCR) → LD-deep agent → ## 🔍 精读 section +| 层级 | 组件 | 触发方式 | 作用 | +|------|------|----------|------| +| **Worker 层** | `literature_pipeline.py`（4 个 workers） | Python CLI | 后台自动化 | +| **Agent 层** | `/LD-deep`, `/LD-paper` 命令 | 用户手动触发 | 交互式精读 | -## 3. Available Functions +**关键区别**： +- **Worker 只做机械劳动**（检测新文献、生成笔记、OCR） +- **Agent 只做深度思考**（精读、分析、写作） +- Worker 不会自动触发 Agent，Agent 不会自动触发 Worker -- **Quick Lookup** - Search and preview literature (single or batch) -- **Deep Reading** - Keshav three-pass reading method (ensure-scaffold + fill) -- **Queue Processing** - Batch process papers awaiting deep reading -- **Figure Analysis** - Extract and analyze figures/tables from OCR +--- -## 4. Style Guidelines +## 2. 完整数据流 -### Markdown & Note Structure -Follow the template in `{paths['template_path']}/文献阅读.md`. +``` +Zotero 添加文献 + ↓ Better BibTeX 自动导出 JSON +{paths['pipeline_path']}/exports/library.json + ↓ 运行 selection-sync +{paths['resources_dir']}/LiteratureControl/library-records/<domain>/<key>.md + ↓ 运行 index-refresh +{paths['literature_path']}/<domain>/<key> - <Title>.md（正式笔记） + ↓ 用户在 library-record 中设置 do_ocr: true +运行 ocr → {paths['pipeline_path']}/ocr/<key>/ + ↓ 用户在 library-record 中设置 analyze: true +运行 deep-reading（查看队列，确认就绪） + ↓ 用户执行 Agent 命令 +/LD-deep <zotero_key> + ↓ Agent 生成 +正式笔记中新增 ## 🔍 精读 区域 +``` + +--- + +## 3. 目录结构（本 Vault 配置） + +``` +{vault_path}/ +├── {paths['resources_dir']}/ +│ ├── {paths['literature_dir']}/ ← 正式文献笔记（index-refresh 生成） +│ │ ├── 骨科/ +│ │ ├── 运动医学/ +│ │ └── ...（你的分类） +│ └── LiteratureControl/ ← 状态跟踪 +│ └── library-records/ ← selection-sync 输出 +│ ├── 骨科/ +│ │ └── ABCDEFG.md ← 单条文献状态记录 +│ └── 运动医学/ +│ └── HIJKLMN.md +│ +├── {paths['system_dir']}/ +│ ├── LiteraturePipeline/ +│ │ ├── 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 ← 核心脚本 +│ ├── Template/ +│ │ └── 科研读图指南.md ← 图表阅读参考 +│ └── Zotero/ ← Junction/Symlink 到 Zotero 数据目录 +│ +├── {agent_config['skill_dir']}/ ← {agent_config['name']} Skill 目录 +│ └── literature-qa/ ← 深度阅读 Skill +│ ├── scripts/ +│ │ └── ld_deep.py ← /LD-deep 核心脚本 +│ ├── prompt_deep_subagent.md ← Agent 精读提示词 +│ └── chart-reading/ ← 14 种图表阅读指南 +│ +├── .env ← API Key 等敏感配置 +└── AGENTS.md ← 本文件 +``` + +### 各目录作用速查 + +| 目录 | 内容 | 谁生成/修改 | +|------|------|------------| +| `{paths['literature_path']}/` | 正式文献笔记（含 frontmatter + 精读内容） | index-refresh 生成，Agent 写入精读 | +| `{paths['resources_dir']}/LiteratureControl/library-records/` | 文献状态跟踪（analyze, ocr_status 等） | selection-sync 生成，用户修改状态 | +| `{paths['pipeline_path']}/exports/` | Better BibTeX JSON 导出 | Zotero 自动导出 | +| `{paths['pipeline_path']}/ocr/` | OCR 全文 + 图表切割 | ocr worker 生成 | +| `{paths['system_dir']}/Zotero/` | Zotero 数据目录的链接 | 安装时手动创建 junction | + +--- + +## 4. 核心 Workers（Lite 版，4 个） + +### selection-sync +- **作用**：检测 Zotero 中的新条目，创建 library-records +- **运行时机**：添加新文献到 Zotero 后 +- **输出**：`{paths['resources_dir']}/LiteratureControl/library-records/<domain>/<key>.md` +- **示例**： + ```bash + python {paths['pipeline_path']}/worker/scripts/literature_pipeline.py \\ + --vault "{vault_path}" selection-sync + ``` + +### index-refresh +- **作用**：基于 library-records 生成正式文献笔记 +- **运行时机**：selection-sync 之后，或需要更新笔记格式时 +- **输出**：`{paths['literature_path']}/<domain>/<key> - <Title>.md` +- **说明**：会读取 Better BibTeX JSON 提取元数据，生成带 frontmatter 的 Obsidian 笔记 + +### ocr +- **作用**：将 PDF 上传到 PaddleOCR API，提取全文文本和图表 +- **触发条件**：library-record 中 `do_ocr: true` +- **输出**：`{paths['pipeline_path']}/ocr/<key>/` 目录 + - `fulltext.md`：提取的全文（含 `<!-- page N -->` 分页标记） + - `images/`：自动切割的图表图片 + - `meta.json`：OCR 状态（`ocr_status: done/pending/processing/failed`） + - `figure-map.json`：图表索引（后续自动生成） +- **注意**：OCR 是异步的，大文件可能需要几分钟 + +### deep-reading +- **作用**：扫描所有 library-records，列出 `analyze=true` 且 OCR 完成的文献 +- **运行时机**：用户想看看哪些文献可以开始精读了 +- **输出**：控制台表格，显示队列状态 +- **重要**：这只是**查看队列**，不会自动触发 Agent 精读 + +--- + +## 5. Agent 命令（用户手动触发） + +| 命令 | 用途 | 前置条件 | +|------|------|----------| +| `/LD-deep <zotero_key>` | 完整 Keshav 三阶段精读 | OCR 完成 (`ocr_status: done`) | +| `/LD-paper <zotero_key>` | 快速摘要（无 OCR 要求） | 有正式笔记即可 | + +### /LD-deep 执行流程 + +1. **prepare 阶段**（自动）： + - 查找 library-record（确认 `analyze: true`） + - 检查 OCR 状态 + - 读取 formal note + - 生成 figure-map.json（图表索引） + - 生成 chart-type-map.json（图表类型识别） + - 在正式笔记中插入 `## 🔍 精读` 骨架 + +2. **精读阶段**（Agent 执行）： + - Pass 1: 概览（5-10 分钟快速扫描） + - Pass 2: 精读还原（逐图逐表分析） + - Pass 3: 深度理解（批判性评估 + 迁移思考） + +3. **验证阶段**（自动）： + - 检查 callout 间距 + - 检查必要 section 是否完整 + - 检查 figure/table embed 是否存在 + +--- + +## 6. Frontmatter 字段参考 + +### Library Record（`{paths['resources_dir']}/LiteratureControl/library-records/<domain>/<key>.md`） + +这是**用户控制工作流的核心**。每个文献对应一个 record 文件： -**Frontmatter (YAML) is MANDATORY:** ```yaml --- -title: " {{{{Title}}}} " -year: {{{{Year}}}} -type: {{{{Type}}}} -journal: " {{{{Journal}}}} " -category: {{{{Category}}}} -tags: - - 文献阅读 - - {{{{Subject_Tag}}}} +zotero_key: "ABCDEFG" # Zotero citation key（自动生成） +domain: "骨科" # 分类领域（对应 Zotero 收藏夹） +title: "论文标题" +year: 2024 +doi: "10.xxxx/xxxxx" +collection_path: "子分类" # Zotero 子收藏夹路径 +has_pdf: true # 是否有 PDF 附件（自动生成） +pdf_path: "{paths['system_dir']}/Zotero/..." # PDF 相对路径（自动生成） +fulltext_md_path: "{paths['pipeline_path']}/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: "" # 预留字段 --- ``` -### Output Language -- **Output**: Simplified Chinese (简体中文) ONLY, unless asked otherwise. -- **Search Terms**: English (for PubMed), but explain in Chinese. +**用户操作方式**： +- 在 Obsidian 中打开 library-record 文件 +- 修改 `analyze: false` → `analyze: true` 标记要精读的文献 +- 修改 `do_ocr: false` → `do_ocr: true` 触发 OCR +- 或使用 Obsidian Base 视图批量操作 -## 5. Interaction Rules +### Formal Note（`{paths['literature_path']}/<domain>/<key> - <Title>.md`） -### Protocol -1. **No Hallucinations**: Never invent PMIDs or citations. -2. **User Confirmation**: - - Confirm **Search Strategy** before executing deep searches. - - Confirm **Target Collection** before importing to Zotero. -3. **Session Awareness**: Track context across sessions. +这是最终产出的笔记，包含元数据 + 精读内容： -## 6. Configuration +```yaml +--- +title: "论文标题" +year: 2024 +type: "journal" +journal: "Journal Name" +impact_factor: 5.2 +category: "骨科" +tags: + - 文献阅读 + - 子分类 +keywords: ["keyword1", "keyword2"] +pdf_link: "{paths['system_dir']}/Zotero/..." +--- +``` -- Zotero Data: `{zotero_path}` -- Zotero Storage: `{storage_path}` -- Vault Path: `{vault_path}` -- System Dir: `{paths['system_dir']}` -- Pipeline Path: `{paths['pipeline_path']}` -- OCR API: PaddleOCR -- Skill Dir: `{agent_config['skill_dir']}` +--- -Generated by PaperForge setup.py on {platform.system()} +## 7. 第一次使用指南（手把手） + +### Step 1: 确认 Zotero 有文献 + +确保 Zotero 中已有至少一篇带 PDF 的文献，且 Better BibTeX 已导出 JSON。 + +### Step 2: 运行 selection-sync + +```bash +# 在 Vault 根目录执行 +python {paths['pipeline_path']}/worker/scripts/literature_pipeline.py \\ + --vault "{vault_path}" selection-sync +``` + +预期输出： +``` +[INFO] Found 5 new items +[INFO] Created library-records/骨科/XXXXXXX.md +... +``` + +### Step 3: 运行 index-refresh + +```bash +python {paths['pipeline_path']}/worker/scripts/literature_pipeline.py \\ + --vault "{vault_path}" index-refresh +``` + +预期输出： +``` +[INFO] Generated 5 formal notes +[INFO] Output: {paths['literature_path']}/骨科/XXXXXXX - Title.md +... +``` + +### Step 4: 标记要精读的文献 + +在 Obsidian 中： +1. 打开 `{paths['resources_dir']}/LiteratureControl/library-records/骨科/XXXXXXX.md` +2. 将 `do_ocr: false` 改为 `do_ocr: true` +3. 将 `analyze: false` 改为 `analyze: true` +4. 保存文件 + +### Step 5: 运行 OCR + +```bash +python {paths['pipeline_path']}/worker/scripts/literature_pipeline.py \\ + --vault "{vault_path}" ocr +``` + +等待完成（可能需要几分钟）。 + +### Step 6: 检查 OCR 状态 + +```bash +python {paths['pipeline_path']}/worker/scripts/literature_pipeline.py \\ + --vault "{vault_path}" deep-reading +``` + +预期输出： +``` +## 就绪 (1 篇) — OCR 完成 +- `XXXXXXX` | 骨科 | 论文标题 +``` + +### Step 7: 执行精读 + +在 {agent_config['name']} Agent 中输入： +``` +/LD-deep XXXXXXX +``` + +Agent 会自动： +1. 准备精读骨架（prepare） +2. 逐阶段填写精读内容 +3. 验证结构完整性 + +### Step 8: 查看结果 + +在 Obsidian 中打开正式笔记，找到 `## 🔍 精读` 区域，精读已完成。 + +--- + +## 8. 常用命令速查 + +```bash +# 检测 Zotero 新条目 +python {paths['pipeline_path']}/worker/scripts/literature_pipeline.py \\ + --vault "{vault_path}" selection-sync + +# 生成/更新正式笔记 +python {paths['pipeline_path']}/worker/scripts/literature_pipeline.py \\ + --vault "{vault_path}" index-refresh + +# 运行 OCR（处理 do_ocr=true 的文献） +python {paths['pipeline_path']}/worker/scripts/literature_pipeline.py \\ + --vault "{vault_path}" ocr + +# 查看精读队列 +python {paths['pipeline_path']}/worker/scripts/literature_pipeline.py \\ + --vault "{vault_path}" deep-reading + +# 查看整体状态 +python {paths['pipeline_path']}/worker/scripts/literature_pipeline.py \\ + --vault "{vault_path}" status +``` + +### Agent 命令 +``` +/LD-deep <zotero_key> # 完整三阶段精读 +/LD-paper <zotero_key> # 快速摘要 +``` + +--- + +## 9. 常见问题 + +### Q: 运行 selection-sync 后没有生成 library-records？ +- 检查 Better BibTeX JSON 导出路径是否正确：`{paths['pipeline_path']}/exports/library.json` +- 检查 JSON 文件是否包含文献数据 +- 确认 Zotero 中该文献有 citation key + +### Q: OCR 一直显示 pending？ +- 检查 PaddleOCR API Key 是否配置正确（`.env` 文件） +- 检查网络连接 +- 查看 `{paths['pipeline_path']}/ocr/<key>/meta.json` 中的错误信息 + +### Q: /LD-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 代码 +```bash +cd {vault_path} +# 如果你有 git 跟踪 PaperForge +git pull origin main + +# 或手动复制更新文件 +cp -r 新下载的scripts/* {paths['pipeline_path']}/worker/scripts/ +``` + +### 备份注意事项 +- `{paths['resources_dir']}/` 和 `{paths['pipeline_path']}/ocr/` 包含你的数据，需备份 +- `.env` 包含 API Key，不要提交到 git +- `{paths['pipeline_path']}/exports/` 可重新生成（由 Zotero 自动导出） + +--- + +## 配置摘要 + +| 配置项 | 值 | +|--------|-----| +| Vault 路径 | `{vault_path}` | +| System 目录 | `{paths['system_dir']}` | +| Pipeline 路径 | `{paths['pipeline_path']}` | +| 文献目录 | `{paths['literature_path']}` | +| Agent 平台 | {agent_config['name']} ({config['agent']}) | +| Skill 目录 | `{agent_config['skill_dir']}` | +| Zotero 路径 | {config['zotero_path']} | + +--- + +*PaperForge Lite | 本文件由 setup.py 根据你的自定义配置自动生成* +*生成时间：{platform.system()} | 请勿手动编辑路径，重装时会被覆盖* """ agents_path.write_text(content, encoding="utf-8") - print_success(f"AGENTS.md created at {agents_path}") + print_success(f"AGENTS.md created at {agents_path} ({len(content)} chars, fully customized)") def safe_copy(src: Path, dst: Path, backup: bool = True) -> bool: