mirror of
https://github.com/lllin000/PaperForge.git
synced 2026-07-22 06:50:53 +00:00
docs: split AI setup guide into EN and ZH versions
This commit is contained in:
Research Assistant
parent
506b6ef6d7
commit
e5573a9c8c
3 changed files with 354 additions and 153 deletions
|
|
@ -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)。
|
||||
|
||||
### 前置条件
|
||||
|
||||
|
|
|
|||
282
docs/ai-agent-setup-guide-zh.md
Normal file
282
docs/ai-agent-setup-guide-zh.md
Normal file
|
|
@ -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 数据目录可能在这个位置：`<path>`
|
||||
> 这个目录应该包含 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 最终结构：
|
||||
```
|
||||
<Vault>/
|
||||
├── <系统目录>/
|
||||
│ └── PaperForge/ ← OCR 结果、导出 JSON、worker 脚本
|
||||
├── <资源目录>/
|
||||
│ ├── <文献目录>/ ← 正式文献笔记
|
||||
│ └── <控制目录>/ ← 文献状态跟踪
|
||||
└── <Base目录>/ ← 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('<vault_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('<vault_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 "<vault_path>" \
|
||||
--agent "<agent_key>" \
|
||||
--zotero-data "<zotero_data_dir>" \
|
||||
--system-dir "<system_dir>" \
|
||||
--resources-dir "<resources_dir>" \
|
||||
--literature-dir "<literature_dir>" \
|
||||
--control-dir "<control_dir>" \
|
||||
--base-dir "<base_dir>" \
|
||||
--paddleocr-key "<api_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 里的 <system_dir>/PaperForge/exports/
|
||||
> - 必须勾选 "保持更新"
|
||||
>
|
||||
> **2. 在 Obsidian 里启用 PaperForge 插件**
|
||||
> - 设置 → 社区插件 → 已安装 → PaperForge → 启用
|
||||
> - Ctrl+P 输入 "PaperForge"
|
||||
>
|
||||
> **3. 若跳过了 PaddleOCR Key**
|
||||
> - 在 <system_dir>/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 "<path>" --agent "<key>" --skip-checks
|
||||
```
|
||||
|
|
@ -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 数据目录可能在这个位置：`<path>`
|
||||
> 这个目录应该包含 zotero.sqlite 和 storage/ 文件夹。
|
||||
> — 正确就回复"对"
|
||||
> — 不对就把正确的 Zotero 数据目录完整路径发给我
|
||||
Then tell the user and ask for confirmation:
|
||||
|
||||
English:
|
||||
> I detected a Zotero data directory at: `<path>`
|
||||
> 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:
|
|||
└── <base-dir>/ ← 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('<vault_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('<vault_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 里的 <system_dir>/PaperForge/exports/
|
||||
> - 必须勾选 "保持更新" ← 这是自动同步的关键
|
||||
>
|
||||
> **2. 在 Obsidian 里启用 PaperForge 插件**
|
||||
> - 设置 → 社区插件 → 已安装 → PaperForge → 启用
|
||||
> - Ctrl+P 输入 "PaperForge"
|
||||
>
|
||||
> **3. 若跳过了 PaddleOCR Key**
|
||||
> - 在 <system_dir>/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 <system_dir>/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 "<path>" --agent "<key>" --skip-checks
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue