From 4c3fe5335181673614ebd6972924e05d0083af16 Mon Sep 17 00:00:00 2001 From: Research Assistant Date: Fri, 24 Apr 2026 17:41:05 +0800 Subject: [PATCH] docs(phase-10): add MIGRATION-v1.2.md - Complete migration guide from v1.1 to v1.2 - Covers all breaking changes: package rename, CLI unification, Agent namespace change - 7 step-by-step migration instructions with copy-pasteable commands - Import path changes for custom scripts - 3 rollback options with state compatibility notes - 9 FAQ entries covering common upgrade issues - Quick reference card for old vs new commands - Cross-references to ARCHITECTURE.md, COMMANDS.md, AGENTS.md --- docs/MIGRATION-v1.2.md | 485 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 485 insertions(+) create mode 100644 docs/MIGRATION-v1.2.md diff --git a/docs/MIGRATION-v1.2.md b/docs/MIGRATION-v1.2.md new file mode 100644 index 00000000..70876f1a --- /dev/null +++ b/docs/MIGRATION-v1.2.md @@ -0,0 +1,485 @@ +# Migration Guide: v1.1 to v1.2 + +> This guide covers all breaking changes when upgrading PaperForge from v1.1 to v1.2. +> +> **Who should read this:** Anyone upgrading from v1.1 — whether you installed via `pip install paperforge-lite`, cloned the repo, or use custom scripts referencing the old package or command names. +> +> **Estimated time:** 5-10 minutes to follow the steps, plus time to update any custom scripts or templates. + +--- + +## What's New in v1.2 + +v1.2 is a **systematization release**. The core functionality is unchanged — Zotero sync, OCR, deep reading, and note generation all work the same way — but the command interface has been unified to reduce confusion and simplify the mental model. + +Key improvements: + +- **Unified CLI commands:** `paperforge sync` replaces `selection-sync` and `index-refresh`; `paperforge ocr` replaces `ocr run` and `ocr doctor`. Fewer commands to remember. +- **Unified Agent namespace:** All Agent commands now use `/pf-*` (`/pf-deep`, `/pf-paper`, `/pf-ocr`, etc.), replacing the fragmented `/LD-*` and `/lp-*` prefixes from v1.1. +- **Package rename:** The Python package is now `paperforge` (not `paperforge_lite`), matching the CLI command name. +- **Shared command modules:** CLI and Agent commands now share the same implementation in `paperforge/commands/`, reducing code duplication and making the system easier to extend (see [`ARCHITECTURE.md`](ARCHITECTURE.md) for details). + +> **Backward compatibility note:** v1.2 still accepts the old CLI command names (`selection-sync`, `index-refresh`, `ocr run`) as aliases, so existing scripts will not break immediately. However, these aliases are deprecated and may be removed in v1.3. Agent commands (`/LD-*`, `/lp-*`) are **not** backward compatible — your Agent platform must use the new `/pf-*` namespace. + +--- + +## Breaking Changes Summary + +| Change | Old (v1.1) | New (v1.2) | Impact | +|--------|-----------|-----------|--------| +| Package name | `paperforge_lite` | `paperforge` | `pip uninstall` + reinstall required | +| CLI sync (full) | `paperforge selection-sync` then `paperforge index-refresh` | `paperforge sync` | Single command; old names still work as aliases | +| CLI sync (selection only) | `paperforge selection-sync` | `paperforge sync --selection` | Old name still works as alias | +| CLI sync (index only) | `paperforge index-refresh` | `paperforge sync --index` | Old name still works as alias | +| CLI OCR (run) | `paperforge ocr run` | `paperforge ocr` | Old name still works as alias | +| CLI OCR (diagnose) | `paperforge ocr doctor` | `paperforge ocr --diagnose` | Old name still works as alias | +| Agent deep reading | `/LD-deep ` | `/pf-deep ` | **Not backward compatible** | +| Agent paper summary | `/LD-paper ` | `/pf-paper ` | **Not backward compatible** | +| Agent OCR | `/lp-ocr` | `/pf-ocr` | **Not backward compatible** | +| Agent sync | `/lp-selection-sync`, `/lp-index-refresh` | `/pf-sync` | **Not backward compatible** | +| Agent status | `/lp-status` | `/pf-status` | **Not backward compatible** | +| Python import | `from paperforge_lite.cli import main` | `from paperforge.cli import main` | Update all custom scripts | +| Module import | `from paperforge_lite.config import load_config` | `from paperforge.config import load_config` | Update all custom scripts | + +--- + +## Detailed Breaking Changes + +### 1. Package Rename: `paperforge_lite` -> `paperforge` + +The Python package installed by pip has been renamed to match the CLI command name. + +**What you need to do:** +- Uninstall the old package: `pip uninstall paperforge-lite` +- Install the new package: `pip install -e .` (from the repo root) or `pip install paperforge` + +**Why this changed:** Having `paperforge_lite` as the Python package but `paperforge` as the CLI command was confusing. Now they match. + +### 2. CLI Commands Unified + +In v1.1, syncing required two separate commands: +```bash +paperforge selection-sync # Create library-records +paperforge index-refresh # Generate formal notes +``` + +In v1.2, these are unified under `paperforge sync`: +```bash +paperforge sync # Runs both selection and index +paperforge sync --selection # Only selection-sync +paperforge sync --index # Only index-refresh +``` + +Similarly, OCR commands were unified: +```bash +# v1.1 +paperforge ocr run +paperforge ocr doctor + +# v1.2 +paperforge ocr +paperforge ocr --diagnose +``` + +**Backward compatibility:** The old command names (`selection-sync`, `index-refresh`, `ocr run`, `ocr doctor`) still work in v1.2 as internal aliases, but they are deprecated. Update your scripts and muscle memory to the new names. + +### 3. Agent Commands Unified to `/pf-*` + +All Agent commands now use the `/pf-*` (PaperForge) namespace: + +| Old Command | New Command | Purpose | +|-------------|-------------|---------| +| `/LD-deep ` | `/pf-deep ` | Deep reading (Keshav three-pass) | +| `/LD-paper ` | `/pf-paper ` | Quick paper summary | +| `/lp-ocr` | `/pf-ocr` | Run OCR on marked papers | +| `/lp-selection-sync` | `/pf-sync` | Sync Zotero to library-records | +| `/lp-index-refresh` | *(part of /pf-sync)* | Generate formal notes | +| `/lp-status` | `/pf-status` | Show system status | + +**No backward compatibility:** Your Agent platform (OpenCode, Codex, Claude Code, etc.) must be configured to use the new command names. The old `/LD-*` and `/lp-*` prefixes will not be recognized. + +--- + +## Migration Steps + +Follow these steps in order. Each step is copy-pasteable. + +### Step 1: Backup Your Vault + +> [!WARNING] +> Always back up your data before upgrading. While v1.2 does not modify your notes or library-records automatically, it's good practice. + +```bash +# Option A: Copy the entire vault +cp -r "你的Vault路径" "你的Vault路径-backup-$(date +%Y%m%d)" + +# Option B: If using git, commit current state +cd "你的Vault路径" +git add -A +git commit -m "backup before v1.2 upgrade" +``` + +At minimum, back up these directories: +- `/` — your literature notes and library-records +- `/PaperForge/ocr/` — OCR results (can be regenerated, but takes time) +- `.env` — your API keys + +### Step 2: Uninstall the Old Package + +```bash +pip uninstall paperforge-lite +``` + +If you see `WARNING: Skipping paperforge-lite as it is not installed`, that's fine — you may have installed it in a different environment. + +### Step 3: Install the New Package + +**If installing from the repo (recommended for development/customization):** + +```bash +cd "你的Vault路径" +pip install -e . +``` + +**If installing from PyPI (when available):** + +```bash +pip install paperforge +``` + +### Step 4: Verify Installation + +```bash +# Should show the new unified help output +python -m paperforge --help + +# Verify the package name changed +python -c "from paperforge.cli import main; print('OK: import works')" +``` + +Expected output for `--help`: +``` +usage: paperforge [-h] [--version] {sync,ocr,deep-reading,repair,status,doctor} ... + +PaperForge Lite v1.2 — Literature workflow for Zotero + Obsidian + +positional arguments: + {sync,ocr,deep-reading,repair,status,doctor} + sync Sync Zotero library and generate notes + ocr Run OCR on marked PDFs + ... +``` + +### Step 5: Update Scripts and Aliases + +Search your system for references to old commands and update them: + +```bash +# Find old command references in your shell history, aliases, scripts +grep -r "paperforge selection-sync" ~/scripts/ ~/.bashrc ~/.zshrc 2>/dev/null || true +grep -r "paperforge index-refresh" ~/scripts/ ~/.bashrc ~/.zshrc 2>/dev/null || true +grep -r "paperforge ocr run" ~/scripts/ ~/.bashrc ~/.zshrc 2>/dev/null || true + +# Find old Python imports +grep -r "from paperforge_lite" ~/scripts/ 2>/dev/null || true +``` + +**Update checklist:** +- [ ] Shell aliases in `.bashrc`, `.zshrc`, or `.bash_profile` +- [ ] Custom scripts in `~/scripts/` or your vault +- [ ] Makefile targets +- [ ] CI/CD pipeline scripts +- [ ] Obsidian Templater or Dataview scripts that invoke CLI commands + +**Example updates:** +```bash +# Old alias +alias pfs='paperforge selection-sync && paperforge index-refresh' + +# New alias +alias pfs='paperforge sync' + +# Old script line +python -m paperforge_lite.cli selection-sync + +# New script line +python -m paperforge sync +``` + +### Step 6: Update Obsidian Notes and Templates + +If any of your Obsidian notes, templates, or Dataview queries reference old command names, update them: + +**Common places to check:** +- Templater templates that insert command examples +- DataviewJS scripts that call `dv.view()` with CLI commands +- Documentation notes in your vault +- Checklists or SOP notes for literature workflow + +**Old references to search for:** +``` +/LD-deep +/LD-paper +/lp-ocr +/lp-selection-sync +/lp-index-refresh +/lp-status +paperforge selection-sync +paperforge index-refresh +paperforge ocr run +paperforge ocr doctor +paperforge_lite +``` + +> **Tip:** Use Obsidian's global search (`Ctrl+Shift+F` or `Cmd+Shift+F`) to search for these strings across your vault. + +### Step 7: Verify Sync Works + +Run a dry-run sync to confirm everything is wired correctly: + +```bash +paperforge sync --dry-run +``` + +Expected behavior: +- No files are modified +- You see a preview of what would happen (new items detected, records that would be created) +- No import errors or path resolution errors + +If the dry-run succeeds, run the real sync: + +```bash +paperforge sync +``` + +Then verify: +1. New library-records are created in `//library-records/` +2. Formal notes are generated in `//` +3. Existing notes and records are **not** corrupted + +--- + +## Import Path Changes + +If you have custom Python scripts that import from `paperforge_lite`, update the import paths: + +### CLI Main Entry Point + +```python +# v1.1 +from paperforge_lite.cli import main + +# v1.2 +from paperforge.cli import main +``` + +### Configuration + +```python +# v1.1 +from paperforge_lite.config import load_config, load_vault_config, paperforge_paths + +# v1.2 +from paperforge.config import load_config, load_vault_config, paperforge_paths +``` + +### Command Modules (Advanced) + +```python +# v1.1 — commands were inline in cli.py or literature_pipeline.py +from paperforge_lite.cli import run_selection_sync + +# v1.2 — commands are in shared modules +from paperforge.commands.sync import sync +from paperforge.commands.ocr import ocr +from paperforge.commands.deep import deep_reading_queue +from paperforge.commands.status import show_status +``` + +### Script Invocation + +```python +# v1.1 +import subprocess +subprocess.run(["python", "-m", "paperforge_lite", "selection-sync"]) + +# v1.2 +import subprocess +subprocess.run(["python", "-m", "paperforge", "sync", "--selection"]) +``` + +--- + +## Rollback Instructions + +If something goes wrong after upgrading to v1.2, you can downgrade to v1.1. + +### Option A: Rollback via Git (Recommended if you cloned the repo) + +```bash +cd "你的Vault路径" + +# Check out the v1.1 tag or branch +git checkout v1.1 +# OR +git checkout + +# Reinstall the old package +pip uninstall paperforge +pip install -e . +``` + +### Option B: Rollback via PyPI (If installed from PyPI) + +```bash +# Uninstall v1.2 +pip uninstall paperforge + +# Install the last v1.1 release +pip install paperforge-lite==1.1.x +``` + +Replace `1.1.x` with the specific version you were using. + +### Option C: Quick Restore from Backup + +If you created a backup in Step 1: + +```bash +# Remove the upgraded vault +rm -rf "你的Vault路径" + +# Restore from backup +cp -r "你的Vault路径-backup-YYYYMMDD" "你的Vault路径" + +# Reinstall v1.1 package +pip uninstall paperforge +pip install paperforge-lite==1.1.x +``` + +### What to Watch Out For + +**State compatibility:** v1.2 does not change the format of `library-records`, formal notes, or OCR output. If you downgrade to v1.1 after running v1.2: +- Your `library-records` will still work (frontmatter format unchanged) +- Your formal notes will still work +- Your OCR output will still work +- **Exception:** If you used new v1.2 features (e.g., `paperforge repair`), the v1.1 scripts may not recognize new fields. These fields are harmless — v1.1 will ignore them. + +**Agent commands:** If you downgraded the package but your Agent platform still has `/pf-*` commands configured, those commands will fail. Revert your Agent configuration to use `/LD-deep`, `/LD-paper`, etc. + +--- + +## FAQ + +### Q: Do I need to reconfigure my vault? + +**A:** No. `paperforge.json`, `.env`, directory structure, and all your data remain compatible. The only changes are command names and the Python package name. + +### Q: Will my existing notes break? + +**A:** No. v1.2 does not modify existing notes or library-records during sync unless you explicitly run `paperforge sync` and new items are detected. Existing notes keep their frontmatter, content, and `## 精读` sections unchanged. + +### Q: Can I use both old and new commands at the same time? + +**A:** For CLI commands: yes, temporarily. v1.2 accepts `selection-sync`, `index-refresh`, and `ocr run` as deprecated aliases. However, these aliases may be removed in v1.3, so update your habits and scripts. + +For Agent commands: no. `/LD-deep`, `/LD-paper`, `/lp-*` are not recognized in v1.2. You must use `/pf-deep`, `/pf-paper`, `/pf-*`. + +### Q: What about my custom scripts that import `paperforge_lite`? + +**A:** You must update the import paths. `paperforge_lite` no longer exists after you uninstall it. Search your scripts for `from paperforge_lite` and `import paperforge_lite` and replace with `paperforge`. + +### Q: The sync command seems slower — is this normal? + +**A:** `paperforge sync` (full) runs both selection-sync and index-refresh sequentially. If you previously ran them separately and only ran one at a time, the full sync will take longer because it does more work. Use `paperforge sync --selection` or `paperforge sync --index` if you only need one phase. + +If it's significantly slower than running the old commands back-to-back, check: +1. Are there many new items in Zotero? First sync after upgrade may take longer. +2. Is your vault on a slow drive (network drive, spinning disk)? +3. Run with `--verbose` to see per-step timing: `paperforge sync --verbose` + +### Q: How do I update my Obsidian templates? + +**A:** If your templates contain command examples (e.g., in a "Literature Workflow" template), update the command references: + +```markdown + +1. Run `paperforge selection-sync` +2. Run `paperforge index-refresh` +3. Run `/LD-deep {{zotero_key}}` + + +1. Run `paperforge sync` +2. Run `/pf-deep {{zotero_key}}` +``` + +Use Obsidian's global search (`Ctrl+Shift+F`) to find old command names in your templates. + +### Q: I get `ModuleNotFoundError: No module named 'paperforge_lite'` after upgrading. + +**A:** You have a script, alias, or Obsidian plugin still referencing the old package name. Search for `paperforge_lite` in: +- Your shell aliases (`~/.bashrc`, `~/.zshrc`) +- Custom Python scripts +- Obsidian Templater or DataviewJS scripts +- Systemd services or cron jobs + +Replace all occurrences with `paperforge`. + +### Q: Do I need to update my `.opencode/skills/` or `.opencode/command/` files? + +**A:** Yes, if you manually copied or symlinked the Agent command files. The v1.2 repository includes updated `command/pf-*.md` files and updated skill scripts. Re-copy or re-symlink them from the v1.2 repo: + +```bash +# If you previously symlinked: +ln -sf "$(pwd)/command/pf-deep.md" .opencode/command/pf-deep.md +ln -sf "$(pwd)/command/pf-paper.md" .opencode/command/pf-paper.md +# ... etc for all 5 command files +``` + +Also update the skill script if you symlinked it: +```bash +ln -sf "$(pwd)/.agents/skills/literature-qa/scripts/ld_deep.py" .opencode/skills/literature-qa/scripts/ld_deep.py +``` + +### Q: Will v1.1 command aliases be removed? + +**A:** They are deprecated in v1.2 and may be removed in v1.3. There is no set timeline, but the recommendation is to migrate your scripts and documentation to the new command names as soon as convenient. + +--- + +## Quick Reference Card + +Print this and keep it handy: + +``` ++------------------+---------------------------+---------------------------+ +| Task | Old (v1.1) | New (v1.2) | ++------------------+---------------------------+---------------------------+ +| Full sync | selection-sync + | paperforge sync | +| | index-refresh | | +| Selection only | paperforge selection-sync | paperforge sync --selection| +| Index only | paperforge index-refresh | paperforge sync --index | +| Run OCR | paperforge ocr run | paperforge ocr | +| Diagnose OCR | paperforge ocr doctor | paperforge ocr --diagnose | +| Deep reading | /LD-deep | /pf-deep | +| Paper summary | /LD-paper | /pf-paper | +| Agent OCR | /lp-ocr | /pf-ocr | +| Agent sync | /lp-selection-sync | /pf-sync | +| Agent status | /lp-status | /pf-status | +| Python package | paperforge_lite | paperforge | ++------------------+---------------------------+---------------------------+ +``` + +--- + +## Need Help? + +- **Architecture details:** See [`ARCHITECTURE.md`](ARCHITECTURE.md) +- **Command reference:** See [`COMMANDS.md`](COMMANDS.md) +- **Installation guide:** See [`INSTALLATION.md`](INSTALLATION.md) +- **User guide:** See [`AGENTS.md`](../AGENTS.md) +- **Report issues:** Open an issue with the tag `migration-v1.2` + +--- + +*PaperForge Lite | Migration Guide | v1.1 -> v1.2*