diff --git a/README.en.md b/README.en.md index 5a9258df..5c7e1ce7 100644 --- a/README.en.md +++ b/README.en.md @@ -95,19 +95,21 @@ 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. Choose your platform, and the wizard deploys the command files to the right location. +PaperForge's deep reading features run through an AI Agent. The core mechanism is **trigger phrases**, not registered plugins: you type `/pf-deep ` directly into the Agent chat, and the Agent recognizes the trigger and loads the `literature-qa` Skill automatically. -| Agent | Files deployed to | Prefix | How to trigger deep reading | -|-------|------------------|--------|---------------------------| -| **OpenCode** | `.opencode/command/` + `.opencode/skills/` | `/` | Open OpenCode, type `/pf-deep ` | -| **Claude Code** | `.claude/skills/` | `/` | Open Claude Code, type `/pf-deep ` | -| **Cursor** | `.cursor/skills/` | `/` | Open Cursor AI Chat, type `/pf-deep ` | -| **GitHub Copilot** | `.github/skills/` | `/` | Open Copilot Chat, type `/pf-deep ` | -| **Windsurf** | `.windsurf/skills/` | `/` | Open Windsurf, type `/pf-deep ` | -| **Codex** | `.codex/skills/` | `$` | Open Codex, type `$pf-deep ` | -| **Cline** | `.clinerules/` | `/` | Open Cline, type `/pf-deep ` | +The setup wizard deploys Skill files to the correct location: -> Important: `/pf-deep` and `/pf-paper` are **NOT terminal commands**. You must first launch the Agent application, then type the command into that Agent's chat input. The Agent will invoke PaperForge's deep reading scripts to analyze your paper. +| Agent | Skill location | Trigger example | +|-------|---------------|-----------------| +| **OpenCode** | `.opencode/skills/` + `.opencode/command/` | `/pf-deep ` | +| **Claude Code** | `.claude/skills/` | `/pf-deep ` | +| **Cursor** | `.cursor/skills/` | `/pf-deep ` | +| **GitHub Copilot** | `.github/skills/` | `/pf-deep ` | +| **Windsurf** | `.windsurf/skills/` | `/pf-deep ` | +| **Codex** | `.codex/skills/` | `$pf-deep ` | +| **Cline** | `.clinerules/` | `/pf-deep ` | + +> **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 diff --git a/README.md b/README.md index f873a015..493b86b5 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ PaperForge **不是一个纯 Obsidian 插件**。它有两部分: 插件 v1.5.0 → Python 包 v1.5.0 ✓ 匹配 ``` -- 如果显示"未安装" → 点击 **打开安装向导** 重新执行安装流程 +- 如果显示"未安装" → 在设置里确认 Python 解释器路径,然后点击 **验证** 重新检测 - 如果显示"版本不匹配" → 插件更新时 Python 包会自动同步升级,如果没成功,点 **更新运行时** 手动触发 --- @@ -85,28 +85,30 @@ PaperForge 需要找到你系统里的 Python。它按以下顺序查找,找 --- -## 4. 安装向导参数说明 +## 4. 配置说明 -打开插件设置界面(`设置` → `第三方插件` → `PaperForge`),点击 **打开安装向导** 按钮,向导会引导你配置以下内容。每一步都解释在这里,免得你填的时候不知道是什么意思。 +以下参数在**插件设置页面**中配置(设置 → 第三方插件 → PaperForge → 打开安装向导)。首次安装时基础配置已是正确默认值,一般不需要手动改。以下解释供你了解每个参数的作用: ### 4.1 Vault 路径 你当前打开的 Obsidian Vault 根目录。安装向导自动检测,一般不用改。 ### 4.2 AI Agent 平台 -PaperForge 的精读功能通过 AI Agent 执行(如 `/pf-deep` 命令)。你需要选择你使用的 Agent 平台,安装向导会把对应的命令文件部署到正确位置。 +PaperForge 的精读功能通过 AI Agent 执行。核心机制是 **触发词** 而非注册插件:你直接在 Agent 对话里输入 `/pf-deep `,Agent 识别到触发词后自动加载 `literature-qa` Skill 来定位论文并执行精读。 -| Agent | 命令文件放在 | 前缀 | 如何触发精读 | -|-------|-------------|------|------------| -| **OpenCode** | `.opencode/command/` + `.opencode/skills/` | `/` | 打开 OpenCode,输入 `/pf-deep ` | -| **Claude Code** | `.claude/skills/` | `/` | 打开 Claude Code,输入 `/pf-deep ` | -| **Cursor** | `.cursor/skills/` | `/` | 打开 Cursor 的 AI Chat,输入 `/pf-deep ` | -| **GitHub Copilot** | `.github/skills/` | `/` | 打开 Copilot Chat,输入 `/pf-deep ` | -| **Windsurf** | `.windsurf/skills/` | `/` | 打开 Windsurf,输入 `/pf-deep ` | -| **Codex** | `.codex/skills/` | `$` | 打开 Codex,输入 `$pf-deep ` | -| **Cline** | `.clinerules/` | `/` | 打开 Cline,输入 `/pf-deep ` | +安装向导会把 Skill 文件部署到对应位置: -> 注意:`/pf-deep` 和 `/pf-paper` **不是在终端里执行的命令**。你需要先启动对应的 Agent 应用(比如打开 OpenCode),然后在这个 Agent 的对话输入框里输入命令,Agent 才会调用 PaperForge 的精读脚本去分析你的论文。 +| Agent | Skill 安装位置 | 触发词示例 | +|-------|---------------|-----------| +| **OpenCode** | `.opencode/skills/` + `.opencode/command/` | `/pf-deep ` | +| **Claude Code** | `.claude/skills/` | `/pf-deep ` | +| **Cursor** | `.cursor/skills/` | `/pf-deep ` | +| **GitHub Copilot** | `.github/skills/` | `/pf-deep ` | +| **Windsurf** | `.windsurf/skills/` | `/pf-deep ` | +| **Codex** | `.codex/skills/` | `$pf-deep ` | +| **Cline** | `.clinerules/` | `/pf-deep ` | + +> **关键理解**:`/pf-deep` 不是 Agent 平台的插件,而是部署在 Vault 里的 Skill 文件。安装向导把文件拷过去之后,Agent 启动时自动发现并识别这些触发词。你不需要在 Agent 平台里做任何"安装插件"的操作。 ### 4.3 目录命名 @@ -152,10 +154,9 @@ PaperForge 会创建一个 junction(Windows)或 symlink(macOS/Linux), 1. **确认版本一致**:设置 → 运行时状态 → 确保插件和 Python 包版本一致 2. **确认 Python 正确**:设置 → 验证按钮,确认连接的是你想要的 Python -3. **运行安装向导**:`Ctrl+P` → `PaperForge: Run Setup Wizard` -4. **配置 PaddleOCR**:在 `.env` 里填入 API Token(安装向导会引导你做这一步) -5. **在 Zotero 里导出文献**:右键要同步的文献库 → `导出...` → 格式选 `Better BibTeX JSON` → 勾选 `Keep updated` → 保存到 `/PaperForge/exports/` -6. **运行 Doctor**:Dashboard → `Run Doctor`,确认所有检查通过 +3. **配置 PaddleOCR**:在 Vault 根目录 `.env` 里填入 API Token +4. **在 Zotero 里导出文献**:右键要同步的文献库 → `导出...` → 格式选 `Better BibTeX JSON` → 勾选 `Keep updated` → 保存到 `/PaperForge/exports/` +5. **运行 Doctor**:Dashboard → `Run Doctor`,确认所有检查通过 --- @@ -175,13 +176,19 @@ PaperForge 会创建一个 junction(Windows)或 symlink(macOS/Linux), ### AI 精读与问答(需 Agent) -打开你选择的 Agent 应用,在对话输入框里输入命令即可。**你对文献描述得越具体(Zotero Key、标题、DOI),Agent 定位越快。** +打开 Agent 应用,直接输入触发词即可。Agent 识别到触发词后会自动加载 `literature-qa` Skill,按标准化流程定位论文并执行操作。 -| 路由 | 命令 | 做什么 | 触发词举例 | 前置条件 | -|------|------|--------|-----------|---------| -| 精读 | `/pf-deep ` | Keshav 三阶段组会式精读,结果写入 formal note | `精读 XX`、`带我读这篇`、`组会讲讲` | OCR 完成、analyze 为 true | -| 问答 | `/pf-paper ` | 交互式论文 Q&A,不强制 OCR | `帮我看看 XX`、`这篇文章讲了什么` | 已有正式笔记 | -| 存档 | `/pf-end` | 保存本次 `/pf-paper` 问答记录 | `保存`、`结束讨论` | `/pf-paper` 会话中 | +**你对文献描述得越具体(Zotero Key、标题、DOI),Agent 定位越快。** + +| 路由 | 触发词 | 做什么 | 前置条件 | +|------|--------|--------|---------| +| 精读 | `/pf-deep ` 或 `精读 ` | Keshav 三阶段组会式精读,结果写入 formal note | OCR 完成、analyze 为 true | +| 问答 | `/pf-paper ` 或 `文献问答 ` | 交互式论文 Q&A,不强制 OCR | 已有正式笔记 | +| 存档 | `/pf-end` 或 `结束讨论` | 保存本次 `/pf-paper` 问答记录 | `/pf-paper` 会话中 | + +> **两种触发方式等效**:你可以用 Agent 原生命令 `/pf-deep ABC12345`,也可以用自然语言 `精读 ABC12345`。Agent 识别到触发词后会自动加载 `literature-qa` Skill。 + +> `/pf-deep` 和 `/pf-paper` **不是终端命令**,也不是 Agent 平台的注册插件。它们是部署在 Vault 里的 Skill 文件的触发词。安装向导把 Skill 文件放到正确位置后,Agent 启动时自动发现。使用方式就是打开 Agent 对话,输入触发词 —— 和你在终端敲 `ls` 一样直接。 ### `/pf-end` 详解 @@ -209,7 +216,7 @@ Dashboard → Run OCR 在笔记 frontmatter 里把 analyze 设为 true ↓ 打开 Agent → 输入 /pf-deep - ↓ Agent 执行三阶段精读 + ↓ Agent 识别触发词 → 加载 literature-qa Skill → 三阶段精读 笔记里出现 ## 🔍 精读 区域 ↓(如需额外问答) 打开 Agent → 输入 /pf-paper @@ -247,9 +254,10 @@ Dashboard Per-paper 视图展示讨论卡片 - 运行 `paperforge doctor` 看具体哪一步失败 - 运行 `paperforge status` 查看系统状态总览 -### /pf-deep 命令没反应 +### /pf-deep 触发词没反应 -- 确认你在 Agent 软件里执行,不是在终端 +- 确认你在 **Agent 应用** 里输入,不是在终端 +- 确认安装向导已运行,Skill 文件已部署到正确的 Vault 目录 - 确认 OCR 已完成(ocr_status: done) - 确认 analyze 已设为 true diff --git a/paperforge/skills/literature-qa/SKILL.md b/paperforge/skills/literature-qa/SKILL.md index 97646693..eb6d2830 100644 --- a/paperforge/skills/literature-qa/SKILL.md +++ b/paperforge/skills/literature-qa/SKILL.md @@ -1,9 +1,11 @@ --- name: literature-qa description: > - 学术文献精读、问答与检索。Triggered by: /pf-deep /pf-paper /pf-end, - "精读 ", "文献问答 ", "结束讨论", "保存记录", - "找一下...文献", "查一下...", "库里有没有", "精读队列". + 学术文献库操作:精读、问答、检索、浏览。Triggered by: + /pf-deep /pf-paper /pf-end, + "精读", "文献问答", "结束讨论", "保存记录", + "找文献", "搜文献", "文献库", "文献检索", "精读队列", "库里有什么", + "搜一下库里", "看一下文献库", "浏览文献库". Uses Zotero key, DOI, title, or domain keywords to locate papers. license: Apache-2.0 compatibility: all @@ -47,16 +49,16 @@ python -m paperforge.worker.paper_resolver paths --vault "$VAULT" ## 路由表 -Agent 根据用户意图路由到对应的 reference 文件: +加载本 Skill 后,根据用户的 **具体意图** 选择一条路由,加载对应的 reference 文件: -| 用户意图 | 典型输入 | 加载文件 | -|---------|---------|---------| -| 查看 Vault 概况 | "看一下库里内容", "看一下文献库", "库里有什么", "浏览文献" | [references/vault-knowledge.md](references/vault-knowledge.md) | -| 文献检索 | "找一下骨科...文献", "查一下 TGF-beta", "库里有没有支架材料的", "搜一下 Smith 的文章", "collection 里有没有" | [references/paper-search.md](references/paper-search.md) | -| 三阶段精读(指定论文) | `/pf-deep `, `pf-deep `, "精读 XXX", "深度阅读 XXX", "带我读", "组会讲这篇", "读一下这篇" | [references/deep-reading.md](references/deep-reading.md) | -| 三阶段精读(查看队列) | `/pf-deep`(无参数), "精读队列", "有哪些该读了" | [references/deep-reading.md](references/deep-reading.md) | -| 论文问答 | `/pf-paper `, `pf-paper `, "做这篇的问答", "帮我看看 XXX", "这篇文章讲了什么", "查一下" | [references/paper-qa.md](references/paper-qa.md) | -| 保存讨论记录 | `/pf-end`, `pf-end`, "保存", "结束讨论", "完成讨论", "保存记录" | [references/save-session.md](references/save-session.md) | +| 用户意图 | 典型输入 | 加载文件 | 说明 | +|---------|---------|---------|------| +| 了解库概况 | "看一下库里有什么", "库里内容" | [vault-knowledge.md](references/vault-knowledge.md) | 展示 domain 分布和统计 | +| 文献检索 | "找文献", "搜文献", "库里有没有XX", "文献检索", "搜一下库里" | [paper-search.md](references/paper-search.md) | 在库里搜索论文 | +| 精读 | `/pf-deep `, "精读 " | [deep-reading.md](references/deep-reading.md) | Keshav 三阶段精读 | +| 精读队列 | `/pf-deep` 无参数, "精读队列" | [deep-reading.md](references/deep-reading.md) | 查看待精读列表 | +| 论文问答 | `/pf-paper `, "文献问答 " | [paper-qa.md](references/paper-qa.md) | 交互式 Q&A | +| 保存记录 | `/pf-end`, "结束讨论", "保存记录" | [save-session.md](references/save-session.md) | 存档问答记录 | > **重要:** 加载 reference 文件后,**严格按照该文件的流程执行,不要跳过任何步骤。** 如果你不知道下一步干什么,回顾 reference 文件的流程,不要自己发明步骤。