From e5573a9c8c719269f4c0b11ca1119b9a01255f2f Mon Sep 17 00:00:00 2001 From: Research Assistant Date: Tue, 28 Apr 2026 15:01:31 +0800 Subject: [PATCH] docs: split AI setup guide into EN and ZH versions --- README.zh-CN.md | 4 +- docs/ai-agent-setup-guide-zh.md | 282 ++++++++++++++++++++++++++++++++ docs/ai-agent-setup-guide.md | 221 ++++++++----------------- 3 files changed, 354 insertions(+), 153 deletions(-) create mode 100644 docs/ai-agent-setup-guide-zh.md diff --git a/README.zh-CN.md b/README.zh-CN.md index 94ba0e7b..65d251f3 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -109,7 +109,7 @@ PaperForge 把你的 Zotero 文献库转化为**AI 可直接读取的知识库** ``` 在当前的 vault 里安装 PaperForge。参考下面的文档完成安装： -https://raw.githubusercontent.com/LLLin000/PaperForge/master/docs/ai-agent-setup-guide.md +https://raw.githubusercontent.com/LLLin000/PaperForge/master/docs/ai-agent-setup-guide-zh.md ``` Agent 会问你几个问题，然后全自动装好。 @@ -126,7 +126,7 @@ paperforge setup 安装向导引导你完成：Agent 平台选择、Vault 目录配置、Zotero 数据目录链接、PaddleOCR API Key 配置。详细步骤见 [setup-guide.md](docs/setup-guide.md)。 -> 如果你是 AI Agent 正在读这个：使用 headless 模式 — `paperforge setup --headless`。完整指引见 [docs/ai-agent-setup-guide.md](docs/ai-agent-setup-guide.md)。 +> 如果你是 AI Agent 正在读这个：使用 headless 模式 — `paperforge setup --headless`。完整指引见 [docs/ai-agent-setup-guide-zh.md](docs/ai-agent-setup-guide-zh.md)。 ### 前置条件 diff --git a/docs/ai-agent-setup-guide-zh.md b/docs/ai-agent-setup-guide-zh.md new file mode 100644 index 00000000..6b4baa1a --- /dev/null +++ b/docs/ai-agent-setup-guide-zh.md @@ -0,0 +1,282 @@ +# PaperForge Headless Setup — For LLM Agents (简体中文) + +> **IMPORTANT**: 直接读取此文件。不要用 WebFetch 或摘要——会丢失关键的 CLI 参数和决策逻辑。 + +--- + +## For Humans（给人类用户） + +复制粘贴给你的 AI Agent： + +``` +在当前的 vault 里安装 PaperForge。参考下面的文档完成安装： +https://raw.githubusercontent.com/LLLin000/PaperForge/master/docs/ai-agent-setup-guide-zh.md +``` + +--- + +## For LLM Agents（给 AI Agent） + +你正在帮用户在 Obsidian Vault 里安装 PaperForge。**按顺序执行每一步，不要跳过。**每步完成后报告结果再继续。 + +**用中文和用户对话。** + +--- + +### Step 0: 收集信息 — 先问清楚再动手 + +**以下所有问题必须在执行任何命令之前问完。不能猜，不能用默认值糊弄。** + +**Q1: Vault 路径** + +> 你的 Obsidian Vault 的完整绝对路径是什么？ +> （如果不知道：打开 Obsidian → 左下角点 vault 名称 → "管理 Vault" → 右键 vault → "在系统文件管理器中显示"。把那个文件夹的完整路径发给我。） + +要求绝对路径，不接受相对路径。 + +**Q2: AI Agent 平台** + +> 你正在使用哪个 AI Agent？ + +展示表格让用户选： + +| Key | Name | +|-----|------| +| `opencode` | OpenCode | +| `cursor` | Cursor | +| `claude` | Claude Code | +| `windsurf` | Windsurf | +| `github_copilot` | GitHub Copilot | +| `cline` | Cline | +| `augment` | Augment | +| `trae` | Trae | + +不回答则默认 `opencode`。 + +**Q3: Zotero 数据目录** + +先尝试自动检测： +```bash +python -c "from pathlib import Path; d = Path.home() / 'Zotero'; print(str(d) if (d / 'zotero.sqlite').exists() else 'NOT_FOUND')" +``` + +把检测结果告诉用户并确认： + +> 我检测到 Zotero 数据目录可能在这个位置：`` +> 这个目录应该包含 zotero.sqlite 和 storage/ 文件夹。 +> — 正确就回复"对" +> — 不对就把正确的 Zotero 数据目录完整路径发给我 + +如果是 `NOT_FOUND`： + +> 未检测到 Zotero 数据目录。请把你的 Zotero 数据目录完整路径发给我。 +> （需要包含 zotero.sqlite 和 storage/ 文件夹的那个目录） + +**拿不到绝对路径不往下走。** + +**Q4: PaddleOCR API Key** + +> PaperForge 的 OCR 功能依赖 PaddleOCR。你有 API Key 吗？ +> 没有的话去 https://paddleocr.baidu.com 注册（免费额度）。 +> 如果现在跳过，OCR 功能暂时不可用。是否跳过？ + +**Q5: 目录名称** + +解释每个目录用途，逐一确认或修改： + +| 参数 | 默认值 | 用途 | +|------|--------|------| +| 系统目录 | `99_System` | 存放 PaperForge 自身文件（插件、OCR 结果、导出 JSON） | +| 资源目录 | `03_Resources` | 存放文献笔记和状态跟踪文件 | +| 文献目录 | `Literature` | 存放正式文献卡片（你的笔记） | +| 控制目录 | `LiteratureControl` | 存放文献状态跟踪（每篇文献的 OCR/精读状态） | +| Base 目录 | `05_Bases` | 存放 Obsidian Base 视图文件（表格化浏览文献队列） | + +Vault 最终结构： +``` +/ +├── <系统目录>/ +│ └── PaperForge/ ← OCR 结果、导出 JSON、worker 脚本 +├── <资源目录>/ +│ ├── <文献目录>/ ← 正式文献笔记 +│ └── <控制目录>/ ← 文献状态跟踪 +└── / ← Obsidian Base 视图 +``` + +逐一确认： +> 1. 系统目录，默认 `99_System`，你用这个还是改？ +> 2. 资源目录，默认 `03_Resources`？ +> 3. 文献目录，默认 `Literature`？ +> 4. 控制目录，默认 `LiteratureControl`？ +> 5. Base 目录，默认 `05_Bases`？ + +用户改了的记下来，没改的用默认值。 + +--- + +### Step 1: 检查 Python 版本 + +```bash +python --version +``` + +- Python >= 3.10 → 继续 Step 2 +- Python < 3.10 或不存在 → **停止**。 + +> PaperForge 需要 Python 3.10 或更高版本。请从 https://python.org 下载安装（勾选 "Add Python to PATH"），装好后告诉我。 + +**等用户确认后再继续。** + +--- + +### Step 2: 安装 paperforge 包 + +```bash +pip install git+https://github.com/LLLin000/PaperForge.git +``` + +- 成功 → "paperforge 已安装"，继续 Step 3 +- 权限错误 → 重试：`pip install --user git+https://github.com/LLLin000/PaperForge.git` +- 其他错误 → 把错误信息展示给用户，**停止** + +--- + +### Step 3: 检测 Zotero + +```bash +python -c "from paperforge.setup_wizard import EnvChecker; from pathlib import Path; c = EnvChecker(Path('')); r = c.check_zotero(); print('OK' if r.passed else 'NOT_FOUND'); print(r.detail)" +``` + +- `OK` → 继续 Step 4 +- `NOT_FOUND` → **停止**。 + +> 未检测到 Zotero。请从 https://zotero.org 下载安装，装好后告诉我。 + +**等用户确认后再继续。** + +--- + +### Step 4: 检测 Better BibTeX 插件 + +```bash +python -c "from paperforge.setup_wizard import EnvChecker; from pathlib import Path; c = EnvChecker(Path('')); r = c.check_bbt(); print('OK' if r.passed else 'NOT_FOUND'); print(r.detail)" +``` + +- `OK` → 继续 Step 5 +- `NOT_FOUND` → **停止**。 + +> 未检测到 Better BibTeX 插件。请安装： +> 1. 下载：https://retorque.re/zotero-better-bibtex/ +> 2. Zotero → 工具 → 插件 → 齿轮 → Install Plugin From File +> 3. 选择 .xpi → 重启 Zotero +> 装好后告诉我。 + +**等用户确认后再继续。** + +--- + +### Step 5: 创建目录并部署文件 + +把 Step 0 收集到的所有信息拼成一条命令： + +```bash +paperforge setup --headless \ + --vault "" \ + --agent "" \ + --zotero-data "" \ + --system-dir "" \ + --resources-dir "" \ + --literature-dir "" \ + --control-dir "" \ + --base-dir "" \ + --paddleocr-key "" \ + --skip-checks +``` + +- 用 Step 0 收集到的实际值替换每个 `<...>` +- 如果用户在 Q4 跳过了 PaddleOCR，去掉 `--paddleocr-key` 那一行 +- 如果用户某个目录用了默认值，就写默认值 +- `--skip-checks` 因为 Step 1-4 已经逐项检测过了 + +**示例（Windows，全部默认值）：** +```bash +paperforge setup --headless --vault "D:\Documents\MyVault" --agent opencode --zotero-data "C:\Users\name\Zotero" --system-dir "99_System" --resources-dir "03_Resources" --literature-dir "Literature" --control-dir "LiteratureControl" --base-dir "05_Bases" --paddleocr-key "sk-xxx" --skip-checks +``` + +**期望输出：** +``` +[*] Phase 2: Creating directories... [OK] 10 directories ready +[*] Phase 4: Deploying files... [OK] worker scripts / skill files / ... +[*] Phase 5: Creating config files... [OK] .env / paperforge.json +[*] Phase 6: Registering CLI... [OK] paperforge CLI registered +[*] Phase 7: Verifying installation... [OK] All 12 checks passed +``` + +**失败退出码：** + +| 退出码 | 含义 | 处理 | +|--------|------|------| +| 1 | 找不到 paperforge 包目录 | 重新 pip install | +| 4 | Worker 脚本缺失 | 同上 | +| 5 | Skill 文件缺失 | 同上 | +| 6 | 文件完整性验证失败 | 检查磁盘空间和写权限 | + +--- + +### Step 6: 验证安装 + +```bash +paperforge status +``` + +如果 `paperforge` 命令找不到，试： +```bash +python -m paperforge status +``` + +--- + +### Step 7: 告诉用户下一步 + +> 安装完成。接下来你需要做 3 件事： +> +> **1. 配置 Zotero 自动导出 JSON（必须）** +> PaperForge 的数据来源，不做这一步 sync 无法工作： +> - 打开 Zotero +> - 文件 → 导出库 → 格式选 Better BibTeX +> - 保存到 Vault 里的 /PaperForge/exports/ +> - 必须勾选 "保持更新" +> +> **2. 在 Obsidian 里启用 PaperForge 插件** +> - 设置 → 社区插件 → 已安装 → PaperForge → 启用 +> - Ctrl+P 输入 "PaperForge" +> +> **3. 若跳过了 PaddleOCR Key** +> - 在 /PaperForge/.env 里添加： +> PADDLEOCR_API_TOKEN=<你的key> + +--- + +## 常见问题 + +### 用户卡在某个步骤 + +回到那个步骤重新检测，确认用户已完成后再继续。不要跳过。 + +### vault 路径有空格 + +用双引号括起来：`--vault "D:\My Documents\MyVault"` + +### macOS/Linux 上 pip 权限错误 + +加 `--user`： +```bash +pip install --user git+https://github.com/LLLin000/PaperForge.git +``` + +### 用户已经装过 PaperForge（升级场景） + +跳过 Step 0-1，直接： +```bash +paperforge setup --headless --vault "" --agent "" --skip-checks +``` diff --git a/docs/ai-agent-setup-guide.md b/docs/ai-agent-setup-guide.md index f9b74095..b0b7361b 100644 --- a/docs/ai-agent-setup-guide.md +++ b/docs/ai-agent-setup-guide.md @@ -1,4 +1,4 @@ -# PaperForge Headless Setup — For LLM Agents +# PaperForge Headless Setup — For LLM Agents (English) > **IMPORTANT**: Read this file directly. Do NOT use WebFetch or summarization — you will lose critical CLI flags and decision logic. @@ -6,59 +6,39 @@ ## For Humans -**English users** — copy this and paste it to your AI agent: +Copy this and paste it to your AI agent: ``` Install PaperForge in this vault by following: https://raw.githubusercontent.com/LLLin000/PaperForge/master/docs/ai-agent-setup-guide.md ``` -**中文用户** — 复制粘贴给 AI： - -``` -在当前的 vault 里安装 PaperForge。参考下面的文档完成安装： -https://raw.githubusercontent.com/LLLin000/PaperForge/master/docs/ai-agent-setup-guide.md -``` -请帮我安装 PaperForge。 -参考 https://raw.githubusercontent.com/LLLin000/PaperForge/master/docs/ai-agent-setup-guide.md 完成安装。 -``` - --- ## For LLM Agents You are installing PaperForge into the user's Obsidian Vault. Follow each step in order. **Do not skip steps.** Report results at each step before proceeding. -### Language - -**Detect the user's language from their initial message.** The prompts in this guide are provided in Chinese (for Chinese-speaking users) and English (for English-speaking users). Use the language the user first spoke to you in. - -- 用户说中文 → 用中文提问 -- User speaks English → use English prompts - -All command outputs and technical terms can stay in English — only the conversational prompts need to match the user's language. +**Speak to the user in English.** --- -### Step 0: 收集信息 — 必须先问清楚 +### Step 0: Collect information — ask before doing anything -**以下所有问题必须在执行任何命令之前问完。不能猜，不能用默认值糊弄。** +Ask ALL questions below before running any command. Do not guess. Do not skip. -**EN**: Ask all questions before running anything. Do not guess. +**Q1: Vault Path** -**Q1: Obsidian Vault 路径 / Vault Path** - -中文： -> 你的 Obsidian Vault 的完整绝对路径是什么？ -> （如果不知道：打开 Obsidian → 左下角点 vault 名称 → "管理 Vault" → 右键 vault → "在系统文件管理器中显示"。把那个文件夹的完整路径发给我。） - -English: > What is the absolute path to your Obsidian Vault? -> (If you don't know: Open Obsidian → bottom-left vault name → "Manage Vaults" → right-click your vault → "Show in system explorer". Send me the full path.) +> (If you don't know: Open Obsidian → bottom-left vault name → "Manage Vaults" → right-click → "Show in system explorer". Send me the full path.) -**Q2: AI Agent 平台 / Agent Platform** +Require an absolute path. Do not accept relative paths. -Show the user this table and wait for one choice: +**Q2: AI Agent Platform** + +> Which AI Agent are you using? + +Show the table and wait for one choice: | Key | Name | |-----|------| @@ -71,25 +51,17 @@ Show the user this table and wait for one choice: | `augment` | Augment | | `trae` | Trae | -中文：你正在使用哪个 AI Agent？选一个。 -English: Which AI Agent are you using? Pick one. - Default if no answer: `opencode`. -**Q3: Zotero 数据目录 / Zotero Data Directory** +**Q3: Zotero Data Directory** First try auto-detection: ```bash python -c "from pathlib import Path; d = Path.home() / 'Zotero'; print(str(d) if (d / 'zotero.sqlite').exists() else 'NOT_FOUND')" ``` -中文： -> 我检测到 Zotero 数据目录可能在这个位置：`` -> 这个目录应该包含 zotero.sqlite 和 storage/ 文件夹。 -> — 正确就回复"对" -> — 不对就把正确的 Zotero 数据目录完整路径发给我 +Then tell the user and ask for confirmation: -English: > I detected a Zotero data directory at: `` > This should contain zotero.sqlite and a storage/ folder. > — Reply "yes" if correct @@ -97,36 +69,28 @@ English: If `NOT_FOUND`: -中文：未检测到 Zotero 数据目录。请把你的 Zotero 数据目录完整路径发给我。 -English: Could not auto-detect Zotero data directory. Please send me the full path. +> Could not auto-detect Zotero data directory. Please send me the full path. +> (Should contain zotero.sqlite and storage/) **Do not proceed without this path.** **Q4: PaddleOCR API Key** -中文： -> PaperForge 的 OCR 功能依赖 PaddleOCR。你有 API Key 吗？ -> 没有的话去 https://paddleocr.baidu.com 注册（免费额度）。 -> 如果现在跳过，OCR 功能暂时不可用。是否跳过？ - -English: > PaperForge needs a PaddleOCR API Key for OCR. Do you have one? > If not, sign up at https://paddleocr.baidu.com (free tier). > If you skip now, OCR won't work until configured later. Skip? -**Q5: 目录名称 / Directory Names** +**Q5: Directory Names** -Explain each directory and ask user to confirm or change. +Explain each directory and ask user to confirm or change, one by one: -Show this table and ask about each one: - -| 参数 / Parameter | 默认 / Default | 用途 / Purpose | -|------|--------|------| -| system dir / 系统目录 | `99_System` | PaperForge internal files (plugins, OCR results, export JSON) | -| resources dir / 资源目录 | `03_Resources` | Literature notes and state tracking | -| literature dir / 文献目录 | `Literature` | Formal literature note cards (your notes) | -| control dir / 控制目录 | `LiteratureControl` | Per-paper state tracking (OCR/deep-reading status) | -| base dir / Base目录 | `05_Bases` | Obsidian Base view files (tabular queue browser) | +| Parameter | Default | Purpose | +|-----------|---------|---------| +| System dir | `99_System` | PaperForge internal files (plugin, OCR results, export JSON) | +| Resources dir | `03_Resources` | Literature notes and state tracking | +| Literature dir | `Literature` | Formal literature note cards | +| Control dir | `LiteratureControl` | Per-paper state tracking (OCR/deep-reading status) | +| Base dir | `05_Bases` | Obsidian Base view files (tabular queue browser) | Final vault structure: ``` @@ -139,27 +103,18 @@ Final vault structure: └── / ← Obsidian Base views ``` -Ask one by one: - -中文： -> 1. 系统目录，默认 99_System，你用这个还是改？ -> 2. 资源目录，默认 03_Resources？ -> 3. 文献目录，默认 Literature？ -> 4. 控制目录，默认 LiteratureControl？ -> 5. Base 目录，默认 05_Bases？ - -English: -> 1. System directory, default 99_System. Keep or change? -> 2. Resources directory, default 03_Resources? -> 3. Literature directory, default Literature? -> 4. Control directory, default LiteratureControl? -> 5. Base directory, default 05_Bases? +Ask: +> 1. System directory, default `99_System`. Keep or change? +> 2. Resources directory, default `03_Resources`? +> 3. Literature directory, default `Literature`? +> 4. Control directory, default `LiteratureControl`? +> 5. Base directory, default `05_Bases`? Use defaults for any the user doesn't change. --- -### Step 1: 检查 Python 版本 / Check Python +### Step 1: Check Python version ```bash python --version @@ -168,27 +123,25 @@ python --version - Python >= 3.10 → proceed to Step 2 - Python < 3.10 or missing → **STOP**. -中文：PaperForge 需要 Python 3.10 或更高版本。请从 https://python.org 下载安装（勾选 "Add Python to PATH"），装好后告诉我。 - -English: PaperForge requires Python 3.10+. Please install from https://python.org (check "Add Python to PATH"), then tell me when done. +> PaperForge requires Python 3.10+. Please install from https://python.org (check "Add Python to PATH"), then tell me when done. **Wait for user before continuing.** --- -### Step 2: 安装 paperforge 包 +### Step 2: Install paperforge package ```bash pip install git+https://github.com/LLLin000/PaperForge.git ``` -- 成功 → 告诉用户"paperforge 已安装"，进入 Step 3 -- 权限错误 → 重试 `pip install --user git+https://github.com/LLLin000/PaperForge.git` -- 其他错误 → 把错误信息展示给用户，**停止** +- Success → "paperforge installed." Proceed to Step 3. +- Permission error → retry: `pip install --user git+https://github.com/LLLin000/PaperForge.git` +- Other errors → show the error to user, **STOP**. --- -### Step 3: 检测 Zotero / Check Zotero +### Step 3: Check Zotero ```bash python -c "from paperforge.setup_wizard import EnvChecker; from pathlib import Path; c = EnvChecker(Path('')); r = c.check_zotero(); print('OK' if r.passed else 'NOT_FOUND'); print(r.detail)" @@ -197,15 +150,13 @@ python -c "from paperforge.setup_wizard import EnvChecker; from pathlib import P - `OK` → proceed to Step 4 - `NOT_FOUND` → **STOP**. -中文：未检测到 Zotero。请从 https://zotero.org 下载安装，装好后告诉我。 - -English: Zotero not found. Please install from https://zotero.org, then tell me when done. +> Zotero not found. Please install from https://zotero.org, then tell me when done. **Wait for user before continuing.** --- -### Step 4: 检测 Better BibTeX 插件 / Check BBT +### Step 4: Check Better BibTeX plugin ```bash python -c "from paperforge.setup_wizard import EnvChecker; from pathlib import Path; c = EnvChecker(Path('')); r = c.check_bbt(); print('OK' if r.passed else 'NOT_FOUND'); print(r.detail)" @@ -214,14 +165,6 @@ python -c "from paperforge.setup_wizard import EnvChecker; from pathlib import P - `OK` → proceed to Step 5 - `NOT_FOUND` → **STOP**. -中文： -> 未检测到 Better BibTeX 插件。请安装： -> 1. 下载：https://retorque.re/zotero-better-bibtex/ -> 2. Zotero → 工具 → 插件 → 齿轮 → Install Plugin From File -> 3. 选择 .xpi → 重启 Zotero -> 装好后告诉我。 - -English: > Better BibTeX plugin not found. Please install: > 1. Download: https://retorque.re/zotero-better-bibtex/ > 2. Zotero → Tools → Add-ons → gear icon → Install Add-on From File @@ -232,9 +175,9 @@ English: --- -### Step 5: 创建目录并部署文件 +### Step 5: Create directories and deploy files -把 Step 0 收集到的所有信息拼成一条命令： +Assemble one command from all Step 0 values: ```bash paperforge setup --headless \ @@ -250,19 +193,17 @@ paperforge setup --headless \ --skip-checks ``` -- 用 Step 0 收集到的实际值替换每个 `<...>` -- 如果用户 Q4 跳过了 PaddleOCR，去掉 `--paddleocr-key` 那一行 -- 如果用户 Q5 某个目录用了默认值，就用默认值（`99_System` / `03_Resources` / `Literature` / `LiteratureControl` / `05_Bases`） -- `--skip-checks` 因为 Step 1-4 已经逐项检测过了 +- Replace each `<...>` with the actual value from Step 0 +- If user skipped PaddleOCR in Q4, remove `--paddleocr-key` line +- If any directory kept the default, use the default value +- `--skip-checks` because Steps 1-4 already verified everything -**示例（Windows，全部显式传参）：** +**Example (Windows, all defaults):** ```bash -paperforge setup --headless --vault "D:\Documents\医学文献" --agent opencode --zotero-data "C:\Users\lin\Zotero" --system-dir "99_System" --resources-dir "03_Resources" --literature-dir "Literature" --control-dir "LiteratureControl" --base-dir "05_Bases" --paddleocr-key "sk-xxx" --skip-checks +paperforge setup --headless --vault "D:\Documents\MyVault" --agent opencode --zotero-data "C:\Users\name\Zotero" --system-dir "99_System" --resources-dir "03_Resources" --literature-dir "Literature" --control-dir "LiteratureControl" --base-dir "05_Bases" --paddleocr-key "sk-xxx" --skip-checks ``` -**输出解读** - -成功时输出类似： +**Expected output:** ``` [*] Phase 2: Creating directories... [OK] 10 directories ready [*] Phase 4: Deploying files... [OK] worker scripts / skill files / ... @@ -271,54 +212,32 @@ paperforge setup --headless --vault "D:\Documents\医学文献" --agent opencode [*] Phase 7: Verifying installation... [OK] All 12 checks passed ``` -失败时查看退出码： +**Failure exit codes:** -| 退出码 | 含义 | 处理 | -|--------|------|------| -| 1 | 找不到 paperforge 包目录 | 包安装不完整，重新 pip install | -| 4 | Worker 脚本缺失 | 同上 | -| 5 | Skill 文件缺失 | 同上 | -| 6 | 文件完整性验证失败 | 检查磁盘空间和写权限 | +| Exit code | Meaning | Action | +|-----------|---------|--------| +| 1 | Package root not found | Reinstall: `pip install --force-reinstall git+https://github.com/LLLin000/PaperForge.git` | +| 4 | Worker scripts missing | Same as above | +| 5 | Skill files missing | Same as above | +| 6 | File integrity check failed | Check disk space and write permissions on vault path | --- -### Step 6: 验证安装 +### Step 6: Verify installation ```bash paperforge status ``` -如果能正常输出状态信息 → 安装成功。 - +If `paperforge` command not found, try: ```bash python -m paperforge status ``` -如果 `paperforge` 命令找不到，用这个备选。两者等效。 - --- -### Step 7: 告诉用户下一步 / Tell User Next Steps +### Step 7: Tell user next steps -中文： -> 安装完成。接下来你需要做 3 件事： -> -> **1. 配置 Zotero 自动导出 JSON（必须）** -> PaperForge 的数据来源，不做这一步 sync 无法工作： -> - 打开 Zotero -> - 文件 → 导出库 → 格式选 Better BibTeX -> - 保存到 Vault 里的 /PaperForge/exports/ -> - 必须勾选 "保持更新" ← 这是自动同步的关键 -> -> **2. 在 Obsidian 里启用 PaperForge 插件** -> - 设置 → 社区插件 → 已安装 → PaperForge → 启用 -> - Ctrl+P 输入 "PaperForge" -> -> **3. 若跳过了 PaddleOCR Key** -> - 在 /PaperForge/.env 里添加： -> PADDLEOCR_API_TOKEN=<你的key> - -English: > Installation complete. Three things to do next: > > **1. Configure Zotero auto-export JSON (required)** @@ -326,7 +245,7 @@ English: > - Open Zotero > - File → Export Library → Format: Better BibTeX > - Save to /PaperForge/exports/ in your vault -> - Must check "Keep Updated" ← critical for auto-sync +> - Must check "Keep Updated" > > **2. Enable PaperForge plugin in Obsidian** > - Settings → Community Plugins → Installed → PaperForge → Enable @@ -338,26 +257,26 @@ English: --- -## 常见问题 +## Common Issues -### 用户卡在某个步骤 +### User stuck on a step -回到那个步骤重新检测，确认用户已完成后再继续。不要跳过。 +Go back to that step and re-check. Confirm user completed it before continuing. -### vault 路径有空格 +### Vault path has spaces -用双引号括起来：`--vault "D:\My Documents\MyVault"` +Wrap in quotes: `--vault "D:\My Documents\MyVault"` -### macOS/Linux 上的 pip 权限问题 +### pip permission error on macOS/Linux -加 `--user`： +Add `--user`: ```bash pip install --user git+https://github.com/LLLin000/PaperForge.git ``` -### 用户已装过 PaperForge（upgrade 场景） +### User already has PaperForge (upgrade scenario) -跳过 Step 0-1，直接： +Skip Steps 0-1. Run: ```bash paperforge setup --headless --vault "" --agent "" --skip-checks ```