From 2b552be9e6938abc4e02075a6fedf9409875118a Mon Sep 17 00:00:00 2001 From: Research Assistant Date: Sat, 16 May 2026 22:38:43 +0800 Subject: [PATCH 1/4] feat: runtime contract hardening + skill/command truth alignment (Package A+B) Atomic snapshots, canonical index mutation serialization, sync post-clean truth, plugin path config-awareness, embed stop signal honesty, full snapshot bootstrap, pf_ prefix unification, workflow command/lifecycle/path corrections, mechanical/cognitive route separation with unknown-command guard. --- .../snapshots/paths_json/default_config.json | 2 +- paperforge/commands/agent_context.py | 6 +- paperforge/commands/embed.py | 23 ++++-- paperforge/config.py | 1 - paperforge/core/io.py | 11 ++- paperforge/memory/db.py | 8 +- paperforge/memory/runtime_health.py | 4 +- paperforge/memory/state_snapshot.py | 7 +- paperforge/memory/vector_db.py | 5 +- paperforge/plugin/main.js | 62 ++++++++++++--- paperforge/plugin/src/testable.js | 55 ++++++++++++- paperforge/plugin/tests/runtime.test.mjs | 47 +++++++++++ paperforge/services/sync_service.py | 12 +++ paperforge/skills/paperforge/SKILL.md | 15 +++- .../paperforge/workflows/deep-reading.md | 2 +- .../skills/paperforge/workflows/paper-qa.md | 16 +++- .../paperforge/workflows/paper-search.md | 11 +-- .../paperforge/workflows/project-log.md | 4 +- .../paperforge/workflows/reading-log.md | 2 +- paperforge/worker/asset_index.py | 77 ++++++++++++++----- paperforge/worker/repair.py | 45 ++--------- tests/cli/test_json_contracts.py | 2 +- tests/test_config.py | 12 +-- tests/unit/commands/test_embed.py | 33 ++++++++ tests/unit/core/test_io.py | 33 ++++++++ tests/unit/memory/test_refresh.py | 32 ++++++++ 26 files changed, 413 insertions(+), 114 deletions(-) create mode 100644 tests/unit/core/test_io.py diff --git a/fixtures/snapshots/paths_json/default_config.json b/fixtures/snapshots/paths_json/default_config.json index d8c3db2b..dd5e377f 100644 --- a/fixtures/snapshots/paths_json/default_config.json +++ b/fixtures/snapshots/paths_json/default_config.json @@ -1,5 +1,5 @@ { "vault": "", "worker_script": "/System/PaperForge/paperforge/worker", - "ld_deep_script": "/.opencode/skills/literature-qa/scripts/ld_deep.py" + "pf_deep_script": "/.opencode/skills/paperforge/scripts/pf_deep.py" } diff --git a/paperforge/commands/agent_context.py b/paperforge/commands/agent_context.py index 4ad294b5..453c9442 100644 --- a/paperforge/commands/agent_context.py +++ b/paperforge/commands/agent_context.py @@ -14,12 +14,12 @@ COMMANDS = { "purpose": "Look up one paper's full status and recommended next action", }, "search": { - "usage": "paperforge search --json [--collection NAME] [--domain NAME] [--ocr done|pending] [--year-from N] [--year-to N] [--limit N]", - "purpose": "Full-text search with optional collection/domain/lifecycle filters", + "usage": "paperforge search --json [--domain NAME] [--ocr done|pending|failed|processing] [--year-from N] [--year-to N] [--limit N] [--lifecycle indexed|pdf_ready|fulltext_ready|deep_read_done]", + "purpose": "Full-text search with optional domain and workflow-state filters", }, "retrieve": { "usage": "paperforge retrieve --json [--limit N]", - "purpose": "Search OCR fulltext chunks for evidence paragraphs (coming soon)", + "purpose": "Search OCR fulltext chunks for evidence paragraphs", }, "deep": { "usage": "/pf-deep ", diff --git a/paperforge/commands/embed.py b/paperforge/commands/embed.py index 560973dc..9041c4d1 100644 --- a/paperforge/commands/embed.py +++ b/paperforge/commands/embed.py @@ -1,6 +1,7 @@ from __future__ import annotations import argparse +import os import sys from pathlib import Path @@ -78,15 +79,27 @@ def run(args: argparse.Namespace) -> int: import signal try: os.kill(pid, signal.SIGTERM) - except Exception: - pass + except Exception as exc: + result = PFResult( + ok=False, + command="embed stop", + version=PF_VERSION, + error=PFError(code=ErrorCode.INTERNAL_ERROR, message=f"Failed to stop embed build: {exc}"), + data={"state": "running", "pid": pid}, + ) + if args.json: + print(result.to_json()) + else: + print(result.error.message, file=sys.stderr) + return 1 mark_vector_build_state(vault, status="stopping", message="Stop requested") - result = PFResult(ok=True, command="embed stop", version=PF_VERSION, - data={"state": "stopping" if pid else "idle"}) + result = PFResult(ok=True, command="embed stop", version=PF_VERSION, data={"state": "stopping", "pid": pid}) + else: + result = PFResult(ok=True, command="embed stop", version=PF_VERSION, data={"state": "idle"}) if args.json: print(result.to_json()) else: - print("Stop requested." if pid else "No active build.") + print("Stop requested." if result.data["state"] == "stopping" else "No active build.") return 0 # Build diff --git a/paperforge/config.py b/paperforge/config.py index 4ea35594..528ac80a 100644 --- a/paperforge/config.py +++ b/paperforge/config.py @@ -331,7 +331,6 @@ def paperforge_paths( # ── v2.2: canonical locations below paperforge/ ── "config": paperforge / "config" / "domain-collections.json", "index": paperforge / "indexes" / "formal-library.json", - "memory_db": paperforge / "indexes" / "paperforge.db", } diff --git a/paperforge/core/io.py b/paperforge/core/io.py index 80697ff7..389ac90f 100644 --- a/paperforge/core/io.py +++ b/paperforge/core/io.py @@ -9,7 +9,14 @@ def read_json(path: Path): return json.loads(path.read_text(encoding="utf-8")) +def write_json_atomic(path: Path, data) -> None: + """Write JSON atomically using a temp file and replace.""" + path.parent.mkdir(parents=True, exist_ok=True) + tmp = path.with_suffix(f"{path.suffix}.tmp") + tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8") + tmp.replace(path) + + def write_json(path: Path, data) -> None: """Write data as JSON, creating parent directories as needed.""" - path.parent.mkdir(parents=True, exist_ok=True) - path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8") + write_json_atomic(path, data) diff --git a/paperforge/memory/db.py b/paperforge/memory/db.py index 19dbf837..146df734 100644 --- a/paperforge/memory/db.py +++ b/paperforge/memory/db.py @@ -9,10 +9,10 @@ from paperforge.config import paperforge_paths def get_memory_db_path(vault: Path) -> Path: """Return the absolute path to paperforge.db.""" paths = paperforge_paths(vault) - db_path = paths.get("memory_db") - if not db_path: - raise FileNotFoundError("memory_db path not configured") - return db_path + index_path = paths.get("index") + if not index_path: + raise FileNotFoundError("index path not configured") + return index_path.parent / "paperforge.db" def get_connection(db_path: Path, read_only: bool = False) -> sqlite3.Connection: diff --git a/paperforge/memory/runtime_health.py b/paperforge/memory/runtime_health.py index 178a000e..6aa0b144 100644 --- a/paperforge/memory/runtime_health.py +++ b/paperforge/memory/runtime_health.py @@ -110,11 +110,11 @@ def _check_index(vault: Path) -> dict: if version: return _layer("ok", [f"Schema version: {version['value']}"]) return _layer("degraded", ["Schema version unknown"], - "Rebuild memory DB", "paperforge memory build --force") + "Rebuild memory DB", "paperforge memory build") except Exception as e: return _layer("blocked", [f"DB query failed: {e}"], "Rebuild memory DB", - "paperforge memory build --force") + "paperforge memory build") def _check_vector(vault: Path) -> dict: diff --git a/paperforge/memory/state_snapshot.py b/paperforge/memory/state_snapshot.py index f9308bf0..924f43ef 100644 --- a/paperforge/memory/state_snapshot.py +++ b/paperforge/memory/state_snapshot.py @@ -5,6 +5,7 @@ from datetime import datetime, timezone from pathlib import Path from paperforge.config import paperforge_paths +from paperforge.core.io import write_json_atomic def _snapshot_dir(vault: Path) -> Path: @@ -31,7 +32,7 @@ def write_memory_runtime(vault: Path, *, paper_count_db: int, "fts_ready": fts_ready, } path = _snapshot_dir(vault) / "memory-runtime-state.json" - path.write_text(json.dumps(snap, ensure_ascii=False, indent=2), encoding="utf-8") + write_json_atomic(path, snap) def write_vector_runtime(vault: Path, *, enabled: bool, mode: str, model: str, @@ -53,9 +54,9 @@ def write_vector_runtime(vault: Path, *, enabled: bool, mode: str, model: str, "build_state": build_state or {}, } path = _snapshot_dir(vault) / "vector-runtime-state.json" - path.write_text(json.dumps(snap, ensure_ascii=False, indent=2), encoding="utf-8") + write_json_atomic(path, snap) def write_runtime_health(vault: Path, health_data: dict) -> None: path = _snapshot_dir(vault) / "runtime-health.json" - path.write_text(json.dumps(health_data, ensure_ascii=False, indent=2), encoding="utf-8") + write_json_atomic(path, health_data) diff --git a/paperforge/memory/vector_db.py b/paperforge/memory/vector_db.py index d03221c6..c3be4730 100644 --- a/paperforge/memory/vector_db.py +++ b/paperforge/memory/vector_db.py @@ -40,7 +40,8 @@ def get_vector_db_path(vault: Path) -> Path: """Return the ChromaDB persistence directory.""" from paperforge.config import paperforge_paths paths = paperforge_paths(vault) - return (paths.get("memory_db", paths.get("index", vault / "System" / "PaperForge"))).parent / "vectors" + index_path = paths.get("index", vault / "System" / "PaperForge" / "indexes" / "formal-library.json") + return index_path.parent / "vectors" def get_collection(vault: Path): @@ -291,7 +292,7 @@ def get_vector_build_state_path(vault: Path) -> Path: """Return path to vector-build-state.json.""" from paperforge.config import paperforge_paths paths = paperforge_paths(vault) - index_dir = (paths.get("memory_db", paths.get("index", vault / "System" / "PaperForge"))).parent + index_dir = paths.get("index", vault / "System" / "PaperForge" / "indexes" / "formal-library.json").parent return index_dir / "vector-build-state.json" diff --git a/paperforge/plugin/main.js b/paperforge/plugin/main.js index 4a99c23d..ce59b6cd 100644 --- a/paperforge/plugin/main.js +++ b/paperforge/plugin/main.js @@ -10,8 +10,38 @@ const memoryState = (() => { const path = require('path'); const { execFileSync } = require('node:child_process'); + function readPathConfig(vaultPath) { + const pfPath = path.join(vaultPath, 'paperforge.json'); + const defaults = { + system_dir: 'System', + resources_dir: 'Resources', + literature_dir: 'Literature', + base_dir: 'Bases', + }; + + try { + if (!fs.existsSync(pfPath)) { + return { ...defaults, _warning: 'paperforge.json not found; using defaults' }; + } + const raw = fs.readFileSync(pfPath, 'utf-8'); + const data = JSON.parse(raw); + const vc = data.vault_config || {}; + return { + system_dir: vc.system_dir || data.system_dir || defaults.system_dir, + resources_dir: vc.resources_dir || data.resources_dir || defaults.resources_dir, + literature_dir: vc.literature_dir || data.literature_dir || defaults.literature_dir, + base_dir: vc.base_dir || data.base_dir || defaults.base_dir, + _warning: null, + }; + } catch (e) { + console.warn('PaperForge: Failed to read paperforge.json, using defaults', e); + return { ...defaults, _warning: 'paperforge.json invalid; using defaults' }; + } + } + function resolveVaultPaths(vaultPath) { - const systemDir = path.join(vaultPath, 'System', 'PaperForge'); + const cfg = readPathConfig(vaultPath); + const systemDir = path.join(vaultPath, cfg.system_dir, 'PaperForge'); return { vault: vaultPath, systemDir, @@ -22,8 +52,11 @@ const memoryState = (() => { vectorStatePath: path.join(systemDir, 'indexes', 'vector-runtime-state.json'), healthStatePath: path.join(systemDir, 'indexes', 'runtime-health.json'), buildStatePath: path.join(systemDir, 'indexes', 'vector-build-state.json'), + exportsDir: path.join(systemDir, 'exports'), + ocrDir: path.join(systemDir, 'ocr'), pluginDataPath: path.join(vaultPath, '.obsidian', 'plugins', 'paperforge', 'data.json'), pfJsonPath: path.join(vaultPath, 'paperforge.json'), + configWarning: cfg._warning, }; } @@ -99,7 +132,7 @@ const memoryState = (() => { return _cachedPython; } } - var sysCandidates = [{path:'python',extraArgs:[]},{path:'python3',extraArgs:[]}]; + var sysCandidates = [{path:'py',extraArgs:['-3']},{path:'python',extraArgs:[]},{path:'python3',extraArgs:[]}]; for (var j = 0; j < sysCandidates.length; j++) { try { var c = sysCandidates[j]; @@ -170,6 +203,7 @@ function resolvePythonExecutable(vaultPath, settings, _fs, _execFileSync) { } const systemCandidates = [ + { path: "py", extraArgs: ["-3"] }, { path: "python", extraArgs: [] }, { path: "python3", extraArgs: [] }, ]; @@ -242,7 +276,7 @@ function buildRuntimeInstallCommand(pythonExe, version, extraArgs) { const gitUrl = `git+https://github.com/LLLin000/PaperForge.git@v${version}`; const pypiArgs = [...extraArgs, "-m", "pip", "install", "--upgrade", pypiPkg]; const gitArgs = [...extraArgs, "-m", "pip", "install", "--upgrade", gitUrl]; - return { cmd: pythonExe, pypiArgs, gitArgs, timeout: 120000 }; + return { cmd: pythonExe, url: gitUrl.replace('@v', '@'), args: gitArgs, pypiArgs, gitArgs, timeout: 120000 }; } function parseRuntimeStatus(err, stdout, stderr) { @@ -4618,7 +4652,7 @@ module.exports = class PaperForgePlugin extends Plugin { /* ── Auto-update PaperForge (deferred — don't slow startup) ── */ - if (this.settings.auto_update !== false && this.settings.setup_complete) { + if (this.settings.auto_update_on_startup === true && this.settings.setup_complete) { setTimeout(() => this._autoUpdate(), 3000); } this._startFilePolling(); @@ -4627,14 +4661,22 @@ module.exports = class PaperForgePlugin extends Plugin { (() => { const vp = this.app.vault.adapter.basePath; if (!vp) return; - const memSnap = require('path').join(vp, 'System', 'PaperForge', 'indexes', 'memory-runtime-state.json'); + const runtimePaths = memoryState.resolveVaultPaths(vp); + const memSnap = runtimePaths.memoryStatePath; const fs = require('fs'); if (!fs.existsSync(memSnap)) { // No snapshots — first launch or upgrade. Fire and forget. const py = resolvePythonExecutable(vp, this.settings); const { execFile } = require('node:child_process'); - const args = [...py.extraArgs, '-m', 'paperforge', '--vault', vp, 'runtime-health', '--json']; - execFile(py.path, args, { cwd: vp, timeout: 60000, windowsHide: true }, () => {}); + const commands = [ + ['runtime-health', '--json'], + ['memory', 'status', '--json'], + ['embed', 'status', '--json'], + ]; + commands.forEach((cmdArgs) => { + const args = [...py.extraArgs, '-m', 'paperforge', '--vault', vp, ...cmdArgs]; + execFile(py.path, args, { cwd: vp, timeout: 60000, windowsHide: true }, () => {}); + }); } })(); } @@ -4692,7 +4734,7 @@ module.exports = class PaperForgePlugin extends Plugin { _checkExports(vaultPath, fs, path, exec) { if (this._autoSyncRunning) return; - const exportsDir = path.join(vaultPath, 'System', 'PaperForge', 'exports'); + const exportsDir = memoryState.resolveVaultPaths(vaultPath).exportsDir; if (!fs.existsSync(exportsDir)) return; let newestMtime = 0; @@ -4728,7 +4770,7 @@ module.exports = class PaperForgePlugin extends Plugin { try { const fs = require('fs'); const path = require('path'); - const exportsDir = path.join(vaultPath, 'System', 'PaperForge', 'exports'); + const exportsDir = memoryState.resolveVaultPaths(vaultPath).exportsDir; let newest = 0; fs.readdirSync(exportsDir).forEach(f => { if (!f.endsWith('.json')) return; @@ -4741,7 +4783,7 @@ module.exports = class PaperForgePlugin extends Plugin { _checkOcr(vaultPath, fs, path, exec) { if (this._autoSyncRunning) return; - const ocrDir = path.join(vaultPath, 'System', 'PaperForge', 'ocr'); + const ocrDir = memoryState.resolveVaultPaths(vaultPath).ocrDir; if (!fs.existsSync(ocrDir)) return; try { diff --git a/paperforge/plugin/src/testable.js b/paperforge/plugin/src/testable.js index f1ee3742..addbe4e2 100644 --- a/paperforge/plugin/src/testable.js +++ b/paperforge/plugin/src/testable.js @@ -6,6 +6,56 @@ const fs = require('fs'); const path = require('path'); const { execFile, spawn } = require('node:child_process'); +function readPathConfig(vaultPath, _fs) { + const f = _fs || fs; + const pfPath = path.join(vaultPath, 'paperforge.json'); + const defaults = { + system_dir: 'System', + resources_dir: 'Resources', + literature_dir: 'Literature', + base_dir: 'Bases', + }; + + try { + if (!f.existsSync(pfPath)) { + return { ...defaults, _warning: 'paperforge.json not found; using defaults' }; + } + const raw = f.readFileSync(pfPath, 'utf-8'); + const data = JSON.parse(raw); + const vc = data.vault_config || {}; + return { + system_dir: vc.system_dir || data.system_dir || defaults.system_dir, + resources_dir: vc.resources_dir || data.resources_dir || defaults.resources_dir, + literature_dir: vc.literature_dir || data.literature_dir || defaults.literature_dir, + base_dir: vc.base_dir || data.base_dir || defaults.base_dir, + _warning: null, + }; + } catch { + return { ...defaults, _warning: 'paperforge.json invalid; using defaults' }; + } +} + +function resolveRuntimePaths(vaultPath, _fs) { + const cfg = readPathConfig(vaultPath, _fs); + const systemRoot = path.join(vaultPath, cfg.system_dir, 'PaperForge'); + return { + vault: vaultPath, + systemDir: systemRoot, + indexesDir: path.join(systemRoot, 'indexes'), + logsDir: path.join(systemRoot, 'logs'), + dbPath: path.join(systemRoot, 'indexes', 'paperforge.db'), + memoryStatePath: path.join(systemRoot, 'indexes', 'memory-runtime-state.json'), + vectorStatePath: path.join(systemRoot, 'indexes', 'vector-runtime-state.json'), + healthStatePath: path.join(systemRoot, 'indexes', 'runtime-health.json'), + buildStatePath: path.join(systemRoot, 'indexes', 'vector-build-state.json'), + exportsDir: path.join(systemRoot, 'exports'), + ocrDir: path.join(systemRoot, 'ocr'), + pluginDataPath: path.join(vaultPath, '.obsidian', 'plugins', 'paperforge', 'data.json'), + pfJsonPath: path.join(vaultPath, 'paperforge.json'), + configWarning: cfg._warning, + }; +} + // ── Runtime helpers ── function resolvePythonExecutable(vaultPath, settings, _fs, _execFileSync) { @@ -33,6 +83,7 @@ function resolvePythonExecutable(vaultPath, settings, _fs, _execFileSync) { } const systemCandidates = [ + { path: "py", extraArgs: ["-3"] }, { path: "python", extraArgs: [] }, { path: "python3", extraArgs: [] }, ]; @@ -107,7 +158,7 @@ function buildRuntimeInstallCommand(pythonExe, version, extraArgs) { const gitUrl = `git+https://github.com/LLLin000/PaperForge.git@v${version}`; const pypiArgs = [...extraArgs, "-m", "pip", "install", "--upgrade", pypiPkg]; const gitArgs = [...extraArgs, "-m", "pip", "install", "--upgrade", gitUrl]; - return { cmd: pythonExe, pypiArgs, gitArgs, timeout: 120000 }; + return { cmd: pythonExe, url: gitUrl.replace('@v', '@'), args: gitArgs, pypiArgs, gitArgs, timeout: 120000 }; } function parseRuntimeStatus(err, stdout, stderr) { @@ -211,6 +262,8 @@ function shouldRenderVectorReady(vectorDepsOk, embedStatusText) { } module.exports = { + readPathConfig, + resolveRuntimePaths, resolvePythonExecutable, getPluginVersion, checkRuntimeVersion, diff --git a/paperforge/plugin/tests/runtime.test.mjs b/paperforge/plugin/tests/runtime.test.mjs index 93e0da08..16fd964b 100644 --- a/paperforge/plugin/tests/runtime.test.mjs +++ b/paperforge/plugin/tests/runtime.test.mjs @@ -7,11 +7,58 @@ import { describe, it, expect, vi, beforeEach } from 'vitest'; const { + readPathConfig, + resolveRuntimePaths, resolvePythonExecutable, getPluginVersion, checkRuntimeVersion, } = await import('../src/testable.js'); +describe('readPathConfig', () => { + it('uses vault_config system_dir when present', () => { + const mockFs = { + existsSync: vi.fn(() => true), + readFileSync: vi.fn(() => JSON.stringify({ vault_config: { system_dir: '99_System' } })), + }; + const cfg = readPathConfig('/vault', mockFs); + expect(cfg.system_dir).toBe('99_System'); + expect(cfg._warning).toBeNull(); + }); + + it('falls back to defaults with warning when config is missing', () => { + const mockFs = { + existsSync: vi.fn(() => false), + readFileSync: vi.fn(), + }; + const cfg = readPathConfig('/vault', mockFs); + expect(cfg.system_dir).toBe('System'); + expect(cfg._warning).toContain('using defaults'); + }); + + it('falls back to defaults with warning when config is invalid', () => { + const mockFs = { + existsSync: vi.fn(() => true), + readFileSync: vi.fn(() => '{bad json'), + }; + const cfg = readPathConfig('/vault', mockFs); + expect(cfg.system_dir).toBe('System'); + expect(cfg._warning).toContain('invalid'); + }); +}); + +describe('resolveRuntimePaths', () => { + it('uses configured system_dir for runtime file paths', () => { + const mockFs = { + existsSync: vi.fn(() => true), + readFileSync: vi.fn(() => JSON.stringify({ vault_config: { system_dir: '99_System' } })), + }; + const paths = resolveRuntimePaths('/vault', mockFs); + expect(paths.memoryStatePath).toContain('99_System'); + expect(paths.exportsDir).toContain('99_System'); + expect(paths.ocrDir).toContain('99_System'); + }); +}); + describe('resolvePythonExecutable', () => { /** Create injected fs + execFileSync mocks */ function mockDeps(existsSyncImpl, execFileSyncImpl) { diff --git a/paperforge/services/sync_service.py b/paperforge/services/sync_service.py index e4c59307..1f058e28 100644 --- a/paperforge/services/sync_service.py +++ b/paperforge/services/sync_service.py @@ -288,6 +288,18 @@ class SyncService: orphaned = self.clean_orphaned_records(exports, paths, json_output=json_output) flat_cleaned = self.clean_flat_notes(paths, json_output=json_output) + if orphaned > 0 or flat_cleaned > 0: + index_count = asset_index.build_index(self.vault, verbose) + + try: + from paperforge.memory.builder import build_from_index + from paperforge.memory.db import get_memory_db_path + + if get_memory_db_path(self.vault).exists(): + build_from_index(self.vault) + except Exception: + pass + if not json_output: print(f"index-refresh: {index_count} entries in index") total = sum(1 for _ in paths["literature"].rglob("*.md")) if paths["literature"].exists() else 0 diff --git a/paperforge/skills/paperforge/SKILL.md b/paperforge/skills/paperforge/SKILL.md index d6185602..48e719a7 100644 --- a/paperforge/skills/paperforge/SKILL.md +++ b/paperforge/skills/paperforge/SKILL.md @@ -98,7 +98,17 @@ Reading-log 不是事实源。它记录的是**之前的关注点、解读和预 ## 6. 意图路由 -用户输入对应唯一一个 workflow 文件（打开并执行其完整流程）： +用户输入分两类处理： + +### A. 机械命令（直接执行并解读结果，不走研究 workflow） + +| 用户说 | 动作 | +| --- | --- | +| `/pf-sync` | 执行 `paperforge sync`，检查结果并解释 | +| `/pf-ocr` | 执行 `paperforge ocr`，检查结果并解释 | +| `/pf-status` | 执行 `paperforge status --json` 或 `paperforge runtime-health --json`，解读状态 | + +### B. 研究工作流（打开唯一 workflow 文件并执行完整流程） | 用户说 | 打开 | | -------------------------------------------------------- | -------------------------------- | @@ -108,10 +118,11 @@ Reading-log 不是事实源。它记录的是**之前的关注点、解读和预 | "记一下" "记录阅读" "reading log" "读完这段记一下" | `workflows/reading-log.md` | | "总结会话" "工作记录" "项目记录" "project log" "记决策" | `workflows/project-log.md` | | "提取方法论" "总结规律" "存档写作规律" | `workflows/methodology.md` | -| "branch" "代码审查" "feature" "dashboard" "memory layer" "用户反馈" "报错" "安装失败" "Git" "Zotero" "BetterBibTeX" "OCR" "插件" | `workflows/project-engineering.md` | +| "branch" "代码审查" "feature" "dashboard" "memory layer" "用户反馈" "报错" "安装失败" "Git" "Zotero" "BetterBibTeX" "插件" | `workflows/project-engineering.md` | | 不确定 / 空输入 | 问用户：搜文献、精读、问答、记笔记、记工作、提方法论？ | 路由后如用户切换意图，重新判断并打开对应 workflow。 +未知或拼错的 `/pf-*` 命令不要静默掉进 `project-engineering`，必须明确提示用户命令不存在或请澄清意图。 --- diff --git a/paperforge/skills/paperforge/workflows/deep-reading.md b/paperforge/skills/paperforge/workflows/deep-reading.md index 10cebc8d..771d07c2 100644 --- a/paperforge/skills/paperforge/workflows/deep-reading.md +++ b/paperforge/skills/paperforge/workflows/deep-reading.md @@ -120,7 +120,7 @@ $PYTHON "$SKILL_DIR/scripts/pf_deep.py" prepare --key --vault "$VAU ### Step 4: Postprocess（跑校验，修正问题） ```bash -$PYTHON "$SKILL_DIR/scripts/pf_deep.py" postprocess-pass2 "" --figures --vault "$VAULT" +$PYTHON "$SKILL_DIR/scripts/pf_deep.py" postprocess-pass2 "" --figures ``` - 输出 `OK` → 继续 Step 5 diff --git a/paperforge/skills/paperforge/workflows/paper-qa.md b/paperforge/skills/paperforge/workflows/paper-qa.md index 98a4f3aa..f7f349dd 100644 --- a/paperforge/skills/paperforge/workflows/paper-qa.md +++ b/paperforge/skills/paperforge/workflows/paper-qa.md @@ -21,21 +21,29 @@ 用户可能给 zotero_key、DOI、标题片段、作者+年份。按以下方式查找： -**优先用 paper-context（一次拿到全部信息）：** +**如果用户给的是 zotero_key：** ```bash -$PYTHON -m paperforge --vault "$VAULT" paper-context --json +$PYTHON -m paperforge --vault "$VAULT" paper-context --json ``` 返回 JSON 包含 paper 元数据、OCR 状态、prior_notes 等。 -**paper-context 无结果时的备选：** +**如果用户给的是 DOI、标题片段、作者+年份，先解析成候选：** + +```bash +$PYTHON -m paperforge --vault "$VAULT" paper-status "" --json +``` + +如果 `paper-status` 直接唯一命中，取返回的 `zotero_key` 再调 `paper-context`。 + +**paper-status 无法唯一定位时的备选：** ```bash $PYTHON -m paperforge --vault "$VAULT" search "" --json --limit 5 ``` -如果多候选，列出让用户选（同 paper-search 的 Step 4-5 格式）。 +如果多候选，列出让用户选（同 paper-search 的 Step 4-5 格式）；用户选定后，再用选中的 `zotero_key` 调 `paper-context`。 如果无结果，告知用户并停止。 ### Step 2: 加载文献内容 diff --git a/paperforge/skills/paperforge/workflows/paper-search.md b/paperforge/skills/paperforge/workflows/paper-search.md index 56803a04..07426a78 100644 --- a/paperforge/skills/paperforge/workflows/paper-search.md +++ b/paperforge/skills/paperforge/workflows/paper-search.md @@ -16,8 +16,8 @@ 提取以下信息（缺什么就问用户）： - **搜索词**：关键词、作者名、年份 -- **范围**：domain（如"骨科"）、collection（如"DC"）、不指定=全库 -- **过滤条件**：OCR 状态（done/pending）、年份范围（--year-from/--year-to）、lifecycle +- **范围**：domain（如"骨科"）、不指定=全库；如果用户说 collection，只把它当结果展示时的二级筛选条件 +- **过滤条件**：OCR 状态（done/pending/failed/processing）、年份范围（--year-from/--year-to）、lifecycle ### Step 2: 执行搜索 @@ -25,8 +25,8 @@ $PYTHON -m paperforge --vault "$VAULT" search --json --limit 15 \ [--domain ""] \ [--year-from ] [--year-to ] \ - [--ocr ] \ - [--lifecycle ] + [--ocr ] \ + [--lifecycle ] ``` 返回 JSON 结构： @@ -46,7 +46,7 @@ $PYTHON -m paperforge --vault "$VAULT" search --json --limit 15 \ "collection_path": "...", "ocr_status": "done", "deep_reading_status": "pending", - "lifecycle": "active", + "lifecycle": "pdf_ready", "has_pdf": true, "rank": "..." } @@ -69,6 +69,7 @@ $PYTHON -m paperforge --vault "$VAULT" paper-context --json ``` 目的：拿到 `ocr_status`、`prior_notes` 数量、`analyze` 状态，帮助用户判断哪些可以直接读。 +如果用户一开始明确要求 collection 范围，在这一步根据 `collection_path` 做结果后筛选，而不是给 `search` 传不存在的 `--collection` 参数。 ### Step 4: 展示候选清单 diff --git a/paperforge/skills/paperforge/workflows/project-log.md b/paperforge/skills/paperforge/workflows/project-log.md index 98bde2af..9106748b 100644 --- a/paperforge/skills/paperforge/workflows/project-log.md +++ b/paperforge/skills/paperforge/workflows/project-log.md @@ -79,7 +79,7 @@ Agent 按 JSON schema 写入 project-log.jsonl。 展示给用户确认后再写入： ``` -即将记录到 Project/综述写作/project-log.md: +即将记录到 Resources/Projects/综述写作/project-log.md: 日期: 2026-05-14 类型: session_summary 标题: DC 段参数窗审计完成 @@ -111,7 +111,7 @@ $PYTHON -m paperforge --vault "$VAULT" project-log --write \ $PYTHON -m paperforge --vault "$VAULT" project-log --render --project "" ``` -输出到 `Project//project-log.md`。 +输出到 `Resources/Projects//project-log.md`。 --- diff --git a/paperforge/skills/paperforge/workflows/reading-log.md b/paperforge/skills/paperforge/workflows/reading-log.md index 5fcf5ccd..8aba3fa8 100644 --- a/paperforge/skills/paperforge/workflows/reading-log.md +++ b/paperforge/skills/paperforge/workflows/reading-log.md @@ -100,7 +100,7 @@ $PYTHON -m paperforge --vault "$VAULT" reading-log --write \ $PYTHON -m paperforge --vault "$VAULT" reading-log --render --project "" ``` -输出到 `Project//reading-log.md`。 +输出到 `Resources/Projects//reading-log.md`。 --- diff --git a/paperforge/worker/asset_index.py b/paperforge/worker/asset_index.py index 1c7b9a17..ba051ccb 100644 --- a/paperforge/worker/asset_index.py +++ b/paperforge/worker/asset_index.py @@ -59,6 +59,46 @@ LOCK_TIMEOUT = 10 ``filelock.Timeout``.""" +def _index_lock(path: Path) -> filelock.FileLock: + return filelock.FileLock(path.with_suffix(".json.lock"), timeout=LOCK_TIMEOUT) + + +def mutate_index(vault: Path, mutator) -> bool: + """Read, mutate, and write the canonical index under one lock.""" + path = get_index_path(vault) + path.parent.mkdir(parents=True, exist_ok=True) + + with _index_lock(path): + if not path.exists(): + return False + try: + with open(path, encoding="utf-8") as fh: + current = json.load(fh) + except (json.JSONDecodeError, OSError) as exc: + logger.warning("Corrupt index at %s during mutation: %s", path, exc) + return False + + updated = mutator(current) + if updated is None: + return False + + tmp = tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", delete=False, dir=path.parent) + try: + json.dump(updated, tmp, ensure_ascii=False, indent=2) + tmp.flush() + os.fsync(tmp.fileno()) + tmp.close() + os.replace(tmp.name, path) + except BaseException: + tmp.close() + try: + os.unlink(tmp.name) + except OSError: + pass + raise + return True + + # --------------------------------------------------------------------------- # Path resolution # --------------------------------------------------------------------------- @@ -123,10 +163,7 @@ def atomic_write_index(path: Path, data: dict) -> None: """ path.parent.mkdir(parents=True, exist_ok=True) - lock_path = path.with_suffix(".json.lock") - lock = filelock.FileLock(lock_path, timeout=LOCK_TIMEOUT) - - with lock: + with _index_lock(path): tmp = None try: tmp = tempfile.NamedTemporaryFile( @@ -587,9 +624,6 @@ def refresh_index_entry(vault: Path, key: str) -> bool: build_index(vault) return False - # Envelope format — incremental refresh - items = existing.get("items", []) - # Find the export item for the requested key config = load_domain_config(paths) domain_lookup = {entry["export_file"]: entry["domain"] for entry in config["domains"]} @@ -623,19 +657,24 @@ def refresh_index_entry(vault: Path, key: str) -> bool: except Exception: pass # memory DB refresh is best-effort - replaced = False - for i, existing_entry in enumerate(items): - if existing_entry.get("zotero_key") == key: - items[i] = new_entry - replaced = True - break - if not replaced: - items.append(new_entry) + def _apply(current): + if is_legacy_format(current) or not isinstance(current, dict): + return None + items = list(current.get("items", [])) + replaced = False + for i, existing_entry in enumerate(items): + if existing_entry.get("zotero_key") == key: + items[i] = new_entry + replaced = True + break + if not replaced: + items.append(new_entry) + return build_envelope(items) + + if not mutate_index(vault, _apply): + build_index(vault) + return False - # Write back atomically - index_path = paths["index"] - envelope = build_envelope(items) - atomic_write_index(index_path, envelope) logger.info("refresh_index_entry: updated entry %s (%s)", key, found_domain) return True diff --git a/paperforge/worker/repair.py b/paperforge/worker/repair.py index c57dea33..b8a93671 100644 --- a/paperforge/worker/repair.py +++ b/paperforge/worker/repair.py @@ -287,25 +287,6 @@ def run_repair(vault: Path, paths: dict, verbose: bool = False, fix: bool = Fals if new_record_text != record_text: record_path.write_text(new_record_text, encoding="utf-8") fixed_formal_note_primary = True - if index_ocr_status is not None: - try: - index_data = read_json(paths["index"]) - if isinstance(index_data, dict): - idx_items = index_data.get("items", []) - elif isinstance(index_data, list): - idx_items = index_data - else: - idx_items = [] - for entry in idx_items: - if isinstance(entry, dict) and entry.get("zotero_key") == zotero_key: - entry["ocr_status"] = new_status - break - if isinstance(index_data, dict): - index_data["items"] = idx_items - write_json(paths["index"], index_data) - fixed_index_entry = True - except Exception as e: - logger.warning("Failed to update index entry for %s: %s", zotero_key, e) if meta_validated_status is not None and meta_validated_status != "done": if meta_path.exists(): try: @@ -328,25 +309,6 @@ def run_repair(vault: Path, paths: dict, verbose: bool = False, fix: bool = Fals if new_record_text != record_text: record_path.write_text(new_record_text, encoding="utf-8") fixed_formal_note_primary = True - if index_ocr_status is not None: - try: - index_data = read_json(paths["index"]) - if isinstance(index_data, dict): - idx_items = index_data.get("items", []) - elif isinstance(index_data, list): - idx_items = index_data - else: - idx_items = [] - for entry in idx_items: - if isinstance(entry, dict) and entry.get("zotero_key") == zotero_key: - entry["ocr_status"] = new_status - break - if isinstance(index_data, dict): - index_data["items"] = idx_items - write_json(paths["index"], index_data) - fixed_index_entry = True - except Exception as e: - logger.warning("Failed to update index entry for %s: %s", zotero_key, e) if meta_path.exists(): try: meta = read_json(meta_path) @@ -370,9 +332,14 @@ def run_repair(vault: Path, paths: dict, verbose: bool = False, fix: bool = Fals logger.info("fixed %d files for %s", fixed_count, zotero_key) if fixed_count > 0: try: - refresh_index_entry(vault, zotero_key) + fixed_index_entry = refresh_index_entry(vault, zotero_key) except Exception as e: logger.warning("Failed to refresh index for %s: %s", zotero_key, e) + else: + if fixed_index_entry: + result["fixed"] += 1 + else: + logger.warning("Failed to update index entry for %s via shared refresh", zotero_key) # Path error detection and repair path_errors = _detect_path_errors(paths, verbose) if path_errors["total"] > 0: diff --git a/tests/cli/test_json_contracts.py b/tests/cli/test_json_contracts.py index d4e4afc7..0381b709 100644 --- a/tests/cli/test_json_contracts.py +++ b/tests/cli/test_json_contracts.py @@ -16,7 +16,7 @@ from .test_contract_helpers import ( class TestPathsJson: """Contract: 'paperforge paths --json' returns valid JSON with correct value types.""" - REQUIRED_KEYS = {"vault", "worker_script", "ld_deep_script"} + REQUIRED_KEYS = {"vault", "worker_script", "pf_deep_script"} def test_paths_json_value_semantics(self, cli_invoker): """paths --json returns paths with correct value types (all non-empty strings).""" diff --git a/tests/test_config.py b/tests/test_config.py index 10c1b92b..04e93486 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -318,7 +318,7 @@ def test_paperforge_paths_returns_exact_keys(tmp_path: Path): "bases", "worker_script", "skill_dir", - "ld_deep_script", + "pf_deep_script", # ── v2.2: canonical locations below paperforge/ ── "config", "index", @@ -370,8 +370,8 @@ def test_paperforge_paths_includes_worker_script(tmp_path: Path): assert paths["worker_script"].name == "__init__.py" -def test_paperforge_paths_includes_ld_deep_script(tmp_path: Path): - """ld_deep_script key must point to ld_deep.py.""" +def test_paperforge_paths_includes_pf_deep_script(tmp_path: Path): + """pf_deep_script key must point to pf_deep.py.""" from paperforge.config import paperforge_paths vault = tmp_path / "vault_ld" @@ -385,8 +385,8 @@ def test_paperforge_paths_includes_ld_deep_script(tmp_path: Path): (vault / ".opencode" / "command").mkdir(parents=True) paths = paperforge_paths(vault) - assert "ld_deep_script" in paths - assert paths["ld_deep_script"].name == "ld_deep.py" + assert "pf_deep_script" in paths + assert paths["pf_deep_script"].name == "pf_deep.py" # --------------------------------------------------------------------------- @@ -413,7 +413,7 @@ def test_paths_as_strings_returns_string_values(): "bases": Path("/some/vault/05_Bases"), "worker_script": Path("/some/vault/99_System/PaperForge/worker/scripts/literature_pipeline.py"), "skill_dir": Path("/some/vault/.opencode/skills"), - "ld_deep_script": Path("/some/vault/.opencode/skills/literature-qa/scripts/ld_deep.py"), + "pf_deep_script": Path("/some/vault/.opencode/skills/paperforge/scripts/pf_deep.py"), } result = paths_as_strings(paths) diff --git a/tests/unit/commands/test_embed.py b/tests/unit/commands/test_embed.py index ab434a11..b2d0c92f 100644 --- a/tests/unit/commands/test_embed.py +++ b/tests/unit/commands/test_embed.py @@ -28,3 +28,36 @@ def test_embed_status_includes_build_state(tmp_path): mock_read.return_value = {"status": "running", "current": 3, "total": 10} result_code = run(args) assert result_code == 0 + + +def test_embed_stop_requests_signal_for_running_job(tmp_path): + from argparse import Namespace + + vault = tmp_path / "vault" + vault.mkdir() + args = Namespace(vault_path=vault, embed_subcommand="stop", json=True) + + with patch("paperforge.commands.embed.read_vector_build_state") as mock_read: + mock_read.return_value = {"status": "running", "pid": 12345} + with patch("paperforge.commands.embed.os.kill") as mock_kill: + with patch("paperforge.commands.embed.mark_vector_build_state") as mock_mark: + result_code = run(args) + + assert result_code == 0 + mock_kill.assert_called_once() + mock_mark.assert_called_once() + + +def test_embed_stop_returns_error_when_signal_fails(tmp_path): + from argparse import Namespace + + vault = tmp_path / "vault" + vault.mkdir() + args = Namespace(vault_path=vault, embed_subcommand="stop", json=True) + + with patch("paperforge.commands.embed.read_vector_build_state") as mock_read: + mock_read.return_value = {"status": "running", "pid": 12345} + with patch("paperforge.commands.embed.os.kill", side_effect=OSError("denied")): + result_code = run(args) + + assert result_code == 1 diff --git a/tests/unit/core/test_io.py b/tests/unit/core/test_io.py new file mode 100644 index 00000000..415e0857 --- /dev/null +++ b/tests/unit/core/test_io.py @@ -0,0 +1,33 @@ +from __future__ import annotations + +import json + +from paperforge.core.io import read_json, write_json, write_json_atomic + + +def test_write_json_atomic_creates_parent_dirs(tmp_path): + path = tmp_path / "nested" / "state.json" + + write_json_atomic(path, {"ok": True}) + + assert path.exists() + assert read_json(path) == {"ok": True} + + +def test_write_json_atomic_replaces_existing_file(tmp_path): + path = tmp_path / "state.json" + path.write_text(json.dumps({"old": True}), encoding="utf-8") + + write_json_atomic(path, {"new": True}) + + assert read_json(path) == {"new": True} + assert not path.with_suffix(".json.tmp").exists() + + +def test_write_json_uses_atomic_writer(tmp_path): + path = tmp_path / "state.json" + + write_json(path, {"value": 1}) + + assert read_json(path) == {"value": 1} + assert not path.with_suffix(".json.tmp").exists() diff --git a/tests/unit/memory/test_refresh.py b/tests/unit/memory/test_refresh.py index 103440fa..6c1f457e 100644 --- a/tests/unit/memory/test_refresh.py +++ b/tests/unit/memory/test_refresh.py @@ -15,3 +15,35 @@ def test_refresh_paper_returns_false_for_empty_key(): def test_refresh_paper_returns_false_for_missing_key(): assert refresh_paper(Path("/nonexistent/vault"), {"title": "No Key"}) is False + + +def test_refresh_paper_rebuild_from_index_removes_stale_rows(tmp_path): + from paperforge.memory.builder import build_from_index + from paperforge.memory.db import get_connection, get_memory_db_path + from paperforge.worker.asset_index import build_envelope, get_index_path + + vault = tmp_path / "vault" + vault.mkdir() + (vault / "paperforge.json").write_text( + '{"vault_config":{"system_dir":"System","resources_dir":"Resources","literature_dir":"Literature","base_dir":"Bases","control_dir":"LiteratureControl"}}', + encoding="utf-8", + ) + + index_path = get_index_path(vault) + index_path.parent.mkdir(parents=True, exist_ok=True) + first = [{"zotero_key": "AAA", "title": "Paper A", "domain": "test", "has_pdf": False, "ocr_status": "pending", "analyze": False, "deep_reading_status": "pending", "pdf_path": "", "note_path": "", "main_note_path": "", "fulltext_path": "", "ocr_json_path": "", "ai_path": "", "paper_root": "", "citation_key": "", "doi": "", "journal": "", "first_author": "", "collection_path": "", "collections": [], "authors": [], "abstract": "", "zotero_storage_key": "", "attachment_count": 0, "supplementary": [], "recommend_analyze": False, "path_error": "", "analysis_note": "", "lifecycle": "indexed", "maturity": {"score": 0}, "next_step": "ready"}] + index_path.write_text(__import__("json").dumps(build_envelope(first), ensure_ascii=False, indent=2), encoding="utf-8") + + build_from_index(vault) + + second = [] + index_path.write_text(__import__("json").dumps(build_envelope(second), ensure_ascii=False, indent=2), encoding="utf-8") + build_from_index(vault) + + conn = get_connection(get_memory_db_path(vault), read_only=True) + try: + count = conn.execute("SELECT COUNT(*) AS c FROM papers").fetchone()["c"] + finally: + conn.close() + + assert count == 0 From 97a2875d481f9163e6e50265699d2fcf38783421 Mon Sep 17 00:00:00 2001 From: Research Assistant Date: Sat, 16 May 2026 22:47:00 +0800 Subject: [PATCH 2/4] docs: reset documentation IA (readme entry pages, tutorial/troubleshooting split, AGENTS agent-only, pure command ref, maintainer guide) Separate audiences: README as navigation entry, getting-started as canonical tutorial, troubleshooting as failure recovery, AGENTS as agent-only operating contract, COMMANDS as pure reference, maintainer-guide for release/versioning/architecture. --- AGENTS.md | 651 ++++--------------------------------- README.en.md | 228 ++----------- README.md | 230 ++----------- docs/COMMANDS.md | 145 ++++----- docs/getting-started.md | 90 +++++ docs/maintainer-guide.md | 74 +++++ docs/troubleshooting.md | 67 ++++ docs/update-upgrade.md | 32 ++ tests/test_command_docs.py | 4 +- 9 files changed, 429 insertions(+), 1092 deletions(-) create mode 100644 docs/getting-started.md create mode 100644 docs/maintainer-guide.md create mode 100644 docs/troubleshooting.md create mode 100644 docs/update-upgrade.md diff --git a/AGENTS.md b/AGENTS.md index 397a9d7b..2abafc86 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,627 +1,90 @@ -# PaperForge - Agent Guide +# PaperForge - Agent Operating Guide -> 本文档面向 **安装完成后的新用户** 和 **AI Agent**。如果还没有安装 PaperForge，请通过 Obsidian 插件市场安装，或查看 [README.md](README.md) 中的安装说明。Docs 版本与 v1.4.18 对应。 +> 本文档面向 **AI Agent**（OpenCode / Claude Code / GPT / Cursor 等）。终端用户请阅读 [使用教程](docs/getting-started.md)。 --- -## 0. 安装后检查清单（第一次使用前必做） +## 1. 核心不变式 -``` -[ ] Zotero 已安装 + Better BibTeX 插件已启用 -[ ] Obsidian 已打开当前 Vault -[ ] PaperForge 已安装 (pip install paperforge) -[ ] PaddleOCR API Key 已配置（在 .env 中） -[ ] 目录结构已创建（安装向导会自动完成） -[ ] Zotero 数据目录已链接到 /Zotero -[ ] Better BibTeX 已按下方步骤导出 JSON 到 /PaperForge/exports/ -``` - -> 安装向导是增量式的：如果你选择的 Vault 或目录里已经有文件，PaperForge 只会补充缺失的目录和文件，不会删除已有内容。 - -### Better BibTeX 自动导出配置 - -这一步应在安装向导完成之后再做，因为 `exports/` 目录需要先由安装流程创建。 - -1. 打开 Zotero -2. 对你要同步的文献库或分类右键 → `导出...` -3. 选择格式：**Better BibTeX JSON** -4. 勾选 **"Keep updated"**（自动导出） -5. 保存到：`{你的Vault路径}//PaperForge/exports/` -6. JSON 文件名会作为 Base 名称，例如 `library.json`、`骨科.json` +1. **CLI 是命令真相源。** 所有 skill、workflow、文档命令引用必须对齐 `paperforge/cli.py`。 +2. **Python 是运行时真相源。** Plugin 只读 canonical 快照，不做业务推断。 +3. **`paperforge.json` 是路径真相源。** Plugin 和 Python 共享同源路径解析，不硬编码目录名。 +4. **Agent 机械命令和思考工作流分层。** `/pf-sync` `/pf-ocr` `/pf-status` 是机械执行，`/pf-deep` `/pf-paper` 是思考工作流。 --- -## 1. 核心架构（v2.1 契约驱动） +## 2. 架构边界 -PaperForge 在 v2.1（1.4.17rc4）重构为 **契约驱动架构**，分 5 层： +| 层 | 做什么 | 不做什么 | +|----|--------|---------| +| Plugin JS | 读快照、render UI、`execFile` 调 Python | 不读 SQLite、不推断 runtime 状态 | +| Python CLI | 写快照、sync/ocr/repair/embed/memory | 不被 JS 轮询驱动 | +| Memory DB | SQLite + FTS5，由 Python 全权重建 | JS 不读 memory DB | +| Vector DB | ChromaDB，由 `embed build` 管理 | 不与 memory DB 合并语义 | +| Skill/workflow | 路由 → 执行 CLI → 解释结果 | 不绕过 CLI 直操作文件 | + +**运行时快照契约：** ``` -CLI/Plugin 调用 - ↓ PFResult 契约 {ok, command, version, data, error} -┌─────────────────────────────────────────────┐ -│ commands/ CLI 分发层 │ -├─────────────────────────────────────────────┤ -│ adapter/bbt, zotero_paths, frontmatter │ ← 独立可测 -│ services/sync_service ← 编排适配器 │ -├─────────────────────────────────────────────┤ -│ core/result, errors, state ← 共享数据契约 │ -├─────────────────────────────────────────────┤ -│ worker/sync, ocr, status ← 机械劳动 │ -│ setup/6个类 ← 安装流程 │ -├─────────────────────────────────────────────┤ -│ schema/field_registry.yaml ← 字段注册表 │ -│ doctor/field_validator.py ← 字段校验 │ -└─────────────────────────────────────────────┘ -``` +Python 写（每次相关 CLI 命令结束时）: + runtime-health --json → runtime-health.json + memory status --json → memory-runtime-state.json + embed status --json → vector-runtime-state.json + embed build → vector-build-state.json -| 层级 | 组件 | 触发方式 | 作用 | -|------|------|----------|------| -| **契约层** | `core/`（PFResult, ErrorCode, 状态机） | 被所有模块引用 | 定义 CLI/Plugin/Worker 之间的数据交换格式 | -| **适配器层** | `adapters/`（bbt, zotero_paths, frontmatter） | 被服务层调用 | 封装外部数据格式与 I/O 操作 | -| **服务层** | `services/sync_service` | 被 worker 调度 | 编排适配器，实现业务逻辑 | -| **Worker 层** | `worker/`（sync, ocr, status, repair 等） | Python CLI | 后台自动化（机械劳动） | -| **Agent 层** | `/pf-deep`, `/pf-paper` | 用户手动触发 | 交互式精读（深度思考） | - -**操作速查**： -| 你要做什么 | 在终端输入 | 在 OpenCode 输入 | -|-----------|-----------|-----------------| -| 同步 Zotero 并生成笔记 | `paperforge sync` | `/pf-sync` | -| 运行 OCR | `paperforge ocr` | `/pf-ocr` | -| 查看精读队列 | `paperforge deep-reading` | `/pf-deep`（精读具体文献） | -| 查看系统状态 | `paperforge status` | `/pf-status` | -| 修复状态分歧 | `paperforge repair` | （终端操作） | -| 验证安装配置 | `paperforge doctor` | （终端操作） | -| 查看帮助 | `paperforge --help` | （终端操作） | - ---- - -## 2. 完整数据流 - -``` -Zotero 添加文献 - ↓ Better BibTeX 自动导出 JSON -/PaperForge/exports/library.json - ↓ 运行 sync -/// - .md（正式笔记，含 frontmatter） - ↓ 用户在正式笔记 frontmatter 中设置 do_ocr: true -运行 ocr → <system_dir>/PaperForge/ocr/<key>/ - ↓ 用户在正式笔记 frontmatter 中设置 analyze: true -运行 deep-reading（查看队列，确认就绪） - ↓ 用户执行 Agent 命令 -/pf-deep <zotero_key> - ↓ Agent 生成 -正式笔记中新增 ## 🔍 精读 区域 +JS 读（同步，不推断）: + memoryState.getMemoryRuntime() + memoryState.getVectorRuntime() + memoryState.getRuntimeHealth() ``` --- -## 3. 目录结构（Lite 版，5 个核心目录） +## 3. 安全命令惯例 -``` -{你的Vault根目录}/ -├── <resources_dir>/ -│ ├── <literature_dir>/ ← 正式文献笔记（sync 生成，含 frontmatter 状态跟踪） -│ │ ├── 骨科/ -│ │ ├── 运动医学/ -│ │ └── ...（你的分类） -│ -├── <system_dir>/ -│ ├── PaperForge/ -│ │ ├── exports/ ← Better BibTeX 自动导出的 JSON -│ │ │ └── library.json -│ │ ├── ocr/ ← OCR 结果（每个文献一个子目录） -│ │ │ └── ABCDEFG/ ← Zotero key 作为目录名 -│ │ │ ├── fulltext.md ← OCR 提取的全文 -│ │ │ ├── images/ ← 图表切割图片 -│ │ │ ├── meta.json ← OCR 元数据（含 ocr_status） -│ │ │ └── figure-map.json ← 图表索引（自动创建） -│ │ ├── indexes/ ← 索引缓存（formal-library.json 等） -│ │ └── config/ ← 领域-收藏夹映射等配置 -│ └── Zotero/ ← Junction/Symlink 到 Zotero 数据目录 -│ -├── <agent_config_dir>/ ← OpenCode Agent 配置（自动创建） -│ └── skills/ -│ └── literature-qa/ ← 深度阅读 Skill -│ ├── scripts/ -│ │ └── ld_deep.py ← /pf-deep 核心脚本 -│ ├── prompt_deep_subagent.md ← Agent 精读提示词 -│ └── chart-reading/ ← 14 种图表阅读指南 -│ -├── .env ← API Key 等敏感配置 -└── AGENTS.md ← 本文件 -``` - -### 各目录作用速查 - -| 目录 | 内容 | 谁生成/修改 | -|------|------|------------| -| `<resources_dir>/<literature_dir>/` | 正式文献笔记（含 frontmatter + 精读内容） | sync 生成，Agent 写入精读 | -| `<system_dir>/PaperForge/exports/` | Better BibTeX JSON 导出 | Zotero 自动导出 | -| `<system_dir>/PaperForge/ocr/` | OCR 全文 + 图表切割 | ocr worker 生成 | -| `<system_dir>/PaperForge/indexes/` | 索引缓存（formal-library.json） | sync 生成 | -| `<system_dir>/PaperForge/config/` | 领域-收藏夹映射等 | 用户/安装向导配置 | -| `<system_dir>/Zotero/` | Zotero 数据目录的链接 | 安装时手动创建 junction | +- 搜索用 `$PYTHON -m paperforge search`，不用 `grep`/`glob` 扫库。 +- 路径从 bootstrap 或 paper-context 获取，禁止自行拼接。 +- 未完成 paper-context 检查前不读原文（deep-reading、paper-qa）。 +- Reading-log 不是事实源，只能用做复查定位。 +- 未知或拼错的 `/pf-*` 必须提示用户，禁止静默掉进 `project-engineering`。 --- -## 4. 核心 Workers（Lite 版，4 个） +## 4. 机械 vs 思考路由 -### sync -- **作用**：检测 Zotero 中的新条目并生成正式文献笔记 -- **运行时机**：添加新文献到 Zotero 后，或需要更新笔记格式时 -- **输出**： - - `<resources_dir>/<literature_dir>/<domain>/<key> - <Title>.md` -- **示例**： - ```bash - paperforge sync - # Legacy (备用): - # python -m paperforge sync --vault "{vault路径}" - ``` - -### ocr -- **作用**：将 PDF 上传到 PaddleOCR API，提取全文文本和图表 -- **触发条件**：正式笔记 frontmatter 中 `do_ocr: true` -- **输出**：`<system_dir>/PaperForge/ocr/<key>/` 目录 - - `fulltext.md`：提取的全文（含 `<!-- page N -->` 分页标记） - - `images/`：自动切割的图表图片 - - `meta.json`：OCR 状态（`ocr_status: done/pending/processing/failed`） - - `figure-map.json`：图表索引（后续自动生成） -- **注意**：OCR 是异步的，大文件可能需要几分钟 -- **示例**： - ```bash - paperforge ocr - # 诊断模式（不运行，仅检查状态） - paperforge ocr --diagnose - # Legacy (备用): - # python -m paperforge ocr --vault "{vault路径}" - ``` - -### deep-reading -- **作用**：扫描所有正式笔记，列出 `analyze=true` 且 OCR 完成的文献 -- **运行时机**：用户想看看哪些文献可以开始精读了 -- **输出**：控制台表格，显示队列状态 -- **重要**：这只是**查看队列**，不会自动触发 Agent 精读 -- **示例**： - ```bash - paperforge deep-reading - paperforge deep-reading --verbose # 显示阻塞条目的修复指令 - # Legacy (备用): - # python -m paperforge deep-reading --vault "{vault路径}" - ``` +| Route | 类型 | 动作 | +|-------|------|------| +| `/pf-sync` | 机械 | 执行 `paperforge sync`，解释结果 | +| `/pf-ocr` | 机械 | 执行 `paperforge ocr`，解释结果 | +| `/pf-status` | 机械 | 执行 `paperforge status --json` 或 `paperforge runtime-health --json`，解读状态 | +| `/pf-deep` | 思考 | 打开 `workflows/deep-reading.md` 执行完整流程 | +| `/pf-paper` | 思考 | 打开 `workflows/paper-qa.md` 执行完整流程 | --- -## 5. Agent 命令（用户手动触发） - -PaperForge 的命令分为两类： - -| 类型 | 命令 | 用途 | 说明 | -|------|------|------|------| -| **深度思考** | `/pf-deep <key>` | 完整 Keshav 三阶段精读 | **必须 Agent 执行** — 需要理解论文、分析图表、生成 callout | -| **深度思考** | `/pf-paper <key>` | 文献问答 | **必须 Agent 执行** — 需要理解内容并写作 | -| **机械操作** | `/pf-sync` | 同步 Zotero 并生成笔记 | Agent 可帮你检查状态并执行 | -| **机械操作** | `/pf-ocr` | 运行 PDF OCR | Agent 可帮你检查队列并执行 | -| **机械操作** | `/pf-status` | 查看系统状态 | Agent 可帮你解读诊断结果 | - -> **双模式调用**：`/pf-sync`、`/pf-ocr`、`/pf-status` 本质上是 CLI 命令的 Agent 包装。你可以在终端直接运行 `paperforge sync/ocr/status`，也可以在 OpenCode 中使用 `/pf-*` 让 Agent 帮你检查前置条件、执行命令、解读输出。 - -> **v1.4 新增**：所有命令支持全局 `--verbose` / `-v` 参数（如 `paperforge sync --verbose`），输出 DEBUG 级别的诊断信息到 stderr，不影响 stdout 的正常输出。 - -> **v1.4 新增 — auto_analyze_after_ocr**：如果开启了 `paperforge.json` 中的 `auto_analyze_after_ocr`，OCR 完成后 `analyze` 会自动设为 `true`，无需手动修改 formal note frontmatter。 - -### 必须 Agent 执行的命令 - -#### `/pf-deep <zotero_key>` — 完整精读 - -**用途**：完整 Keshav 三阶段精读 -**前置条件**：OCR 完成 (`ocr_status: done`) - -执行流程： -1. **prepare 阶段**（自动）：查找正式笔记、检查 OCR、生成 figure-map -2. **精读阶段**（Agent 执行）：Pass 1 概览 → Pass 2 精读还原 → Pass 3 深度理解 -3. **验证阶段**（自动）：检查 callout 间距、section 完整性 - -#### `/pf-paper <zotero_key>` — 文献问答 - -**用途**：文献问答（无 OCR 要求） -**前置条件**：有正式笔记即可 - ---- - -## 6. Path Resolution（路径解析） - -PaperForge 支持三种 Better BibTeX 导出路径格式，并统一转换为 Obsidian wikilink： - -### 支持的 BBT 路径格式 - -| 格式 | 示例 | 处理方式 | -|------|------|----------| -| **Absolute Windows** | `D:\Zotero\storage\KEY\file.pdf` | 提取 8 位 KEY，转换为 `storage:KEY/file.pdf` | -| **storage: prefix** | `storage:KEY/file.pdf` | 直接透传，仅规范化斜杠 | -| **Bare relative** | `KEY/file.pdf` | 自动添加 `storage:` 前缀 | - -### Wikilink 生成规则 - -- 所有 PDF 路径在正式笔记中存储为 **Obsidian wikilink** 格式：`[[relative/path/to/file.pdf]]` -- 使用正斜杠 `/`（即使 Windows 系统） -- 支持中文文件名，无需转义 -- 示例：`[[99_System/Zotero/storage/KEY/中文论文.pdf]]` - -### Junction / Symlink 设置 - -如果 Zotero 数据目录在 Vault 外部，需创建 junction： - -```powershell -# 以管理员身份运行 PowerShell -New-Item -ItemType Junction -Path "C:\你的Vault\99_System\Zotero" -Target "C:\Users\用户名\Zotero" -``` - -或 CMD： - -```cmd -mklink /J "C:\你的Vault\99_System\Zotero" "C:\Users\用户名\Zotero" -``` - -运行 `paperforge doctor` 会自动检测 Zotero 位置并推荐正确的 junction 命令。 - -### 多附件处理 - -当一篇文献有多个 PDF 附件时： -- **Main PDF**：title="PDF" 的附件，或最大文件，或第一个 PDF -- **Supplementary**：其他 PDF 附件列表，以 wikilink 数组形式存储 - ---- - -## 7. Frontmatter 字段参考 - -### Formal Note（`Literature/<domain>/<key> - <Title>.md`） - -这是**用户控制工作流的核心**。每个文献对应一个 formal note 文件，frontmatter 包含元数据 + 工作流控制字段： - -```yaml ---- -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/storage/KEY/文件名.pdf]]" # Wikilink 格式 -bbt_path_raw: "D:\\Zotero\\storage\\KEY\\文件名.pdf" # 原始 BBT 路径（调试用） -zotero_storage_key: "KEY" # 8 位 Zotero storage key -attachment_count: 2 # 附件总数 -supplementary: # 其他 PDF 附件（wikilink 列表） - - "[[99_System/Zotero/storage/KEY/supp1.pdf]]" - - "[[99_System/Zotero/storage/KEY/supp2.pdf]]" -fulltext_md_path: "[[99_System/PaperForge/ocr/KEY/fulltext.md]]" -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） -path_error: "" # 路径错误（not_found/invalid/permission_denied） -analysis_note: "" # 预留字段 ---- -``` - -**用户操作方式**： -- 在 Obsidian 中打开 formal note 文件 -- 修改 `analyze: false` → `analyze: true` 标记要精读的文献 -- 修改 `do_ocr: false` → `do_ocr: true` 触发 OCR -- 或使用 Obsidian Base 视图批量操作 - ---- - -## 8. 第一次使用指南（手把手） - -### Step 1: 完成 Better BibTeX 自动导出 - -先按上面的步骤把 JSON 导出到 `<system_dir>/PaperForge/exports/`。这一步没完成前，`sync` 不会读到文献。 - -### Step 2: 确认 Zotero 有文献 - -确保 Zotero 中已有至少一篇带 PDF 的文献，且 Better BibTeX 已导出 JSON。 - -### Step 3: 运行 sync +## 5. 测试 ```bash -# 在 Vault 根目录执行 -paperforge sync -``` +# Python +python -m pytest tests/unit/ tests/cli/ -v --tb=short -预期输出： -``` -[INFO] Found 5 new items -[INFO] Created 骨科/XXXXXXX.md -[INFO] Generated 5 formal notes -[INFO] Output: <resources_dir>/<literature_dir>/骨科/XXXXXXX - Title.md -... -``` +# JS +cd paperforge/plugin && npx vitest run -### Step 4: 在 Base 视图中标记 OCR - -打开 Obsidian Base 视图，找到该文献，将 `do_ocr` 设为 `true`。 - -### Step 5: 运行 OCR - -```bash -paperforge ocr -``` - -等待完成（可能需要几分钟）。 - -### Step 6: 在 Base 视图中标记精读 - -OCR 完成后，在 Base 视图中找到该文献，将 `analyze` 设为 `true`。 - -### Step 7: 执行精读 - -先确认队列就绪： -```bash -paperforge deep-reading -``` - -然后在 OpenCode Agent 中输入： -``` -/pf-deep XXXXXXX -``` - -Agent 会自动： -1. 准备精读骨架（prepare） -2. 逐阶段填写精读内容 -3. 验证结构完整性 - -### Step 8: 查看结果 - -在 Obsidian 中打开正式笔记，找到 `## 🔍 精读` 区域，精读已完成。 - ---- - -## 9. 常用命令速查 - -```bash -# 检测 Zotero 新条目并生成正式笔记 -paperforge sync -paperforge sync --verbose # 显示详细诊断信息 - - - -# 运行 OCR（处理 do_ocr=true 的文献） -paperforge ocr -paperforge ocr --verbose # 显示 OCR 详细日志 -paperforge ocr --diagnose # 诊断模式，不实际运行 -paperforge ocr --no-progress # 静默模式，不显示进度条 - -# 查看精读队列 -paperforge deep-reading -paperforge deep-reading --verbose # 显示阻塞条目修复指令 - -# 修复状态分歧（默认 dry-run） -paperforge repair --verbose # 查看三向状态分歧详情 -paperforge repair --fix # 实际修复（慎用） - -# 查看整体状态 -paperforge status - -# 验证安装配置 -paperforge doctor -``` - -> 如果 `paperforge` 命令未注册，可使用 fallback： -> ```bash -> python -m paperforge <command> -> ``` -> 例如：`python -m paperforge status` - -### Agent 命令 -``` -/pf-deep <zotero_key> # 完整三阶段精读（必须 Agent 执行） -/pf-paper <zotero_key> # 文献问答（必须 Agent 执行） -/pf-sync # 同步 Zotero（Agent 包装 CLI） -/pf-ocr # 运行 OCR（Agent 包装 CLI） -/pf-status # 查看状态（Agent 包装 CLI） -``` - -> 注：`/pf-sync`、`/pf-ocr`、`/pf-status` 与 `paperforge sync/ocr/status` 是同一命令的两种调用方式。在终端直接运行 CLI 即可；在 OpenCode 中使用 `/pf-*` 可以让 Agent 帮你检查前置条件并解读输出。 - -### Chart-Reading 指南索引 - -`/pf-deep` 精读时会参考 19 种图表类型的阅读指南，按生物医学文献常见度排序。完整索引参见 `chart-reading/INDEX.md`。 - ---- - -## 10. 常见问题 - -### Q: 运行 sync 后没有生成正式笔记？ -- 检查 Better BibTeX JSON 导出路径是否正确 -- 检查 JSON 文件是否包含文献数据 -- 确认 Zotero 中该文献有 citation key - -### Q: OCR 一直显示 pending？ -- 检查 PaddleOCR API Key 是否配置正确（`.env` 文件） -- 检查网络连接 -- 查看 `<system_dir>/PaperForge/ocr/<key>/meta.json` 中的错误信息 - -### Q: /pf-deep 提示 OCR 未完成？ -- 确认正式笔记 frontmatter 中 `ocr_status: done` -- 如 OCR 失败，可重新设置 `do_ocr: true` 再运行 ocr worker - -### Q: Base 视图中 pdf_path 显示为绝对路径？ -- 这是 Obsidian 渲染问题，数据本身是相对路径 -- 不影响功能，可忽略 - -### Q: 可以批量操作吗？ -- 可以。使用 Obsidian Base 视图批量修改 `do_ocr` 和 `analyze` 字段 -- 或使用脚本批量修改 formal note frontmatter - ---- - -## 11. 升级与维护 - -### 更新 PaperForge 代码 - -#### 方式 1：自动更新（推荐） - -```bash -# 自动检测安装方式并更新 -paperforge update -``` - -系统会自动检测你是通过 pip、git 还是手动安装，并执行对应的更新方式。 - -#### 方式 2：Windows 一键脚本 - -双击运行 Vault 根目录下的 `scripts/update-paperforge.ps1`： -- 自动检测安装方式 -- 自动执行更新 -- 无需手动输入命令 - -```powershell -# 或在 PowerShell 中执行 -.\scripts\update-paperforge.ps1 - -# 强制更新（跳过确认） -.\scripts\update-paperforge.ps1 -Force - -# 只检测不更新 -.\scripts\update-paperforge.ps1 -DryRun -``` - -#### 方式 3：手动更新 - -**推荐：自动更新** -```bash -paperforge update -``` -系统会自动检测安装方式并执行对应的更新命令。 - -**pip 安装用户：** -```bash -pip install --upgrade paperforge -``` - -**pip editable / git clone 用户：** -```bash -cd 你的仓库目录 -git pull origin master -pip install -e . -``` - -#### 方式 4：手动复制（最后手段） - -```bash -cp -r 新下载的代码/* <vault_path>/ -``` - -> [!WARNING] 手动复制容易遗漏文件，建议优先使用自动更新。 - -### 备份注意事项 -- `<resources_dir>/` 和 `<system_dir>/PaperForge/ocr/` 包含你的数据，需备份 -- `.env` 包含 API Key，不要提交到 git -- `<system_dir>/PaperForge/exports/` 可重新生成（由 Zotero 自动导出） - ---- - -## 12. 命令迁移说明（v1.1 → v1.2） - -从 v1.2 开始，PaperForge 采用统一的命令接口： - -- **CLI 统一入口**：`paperforge sync`（替代 `selection-sync` + `index-refresh`）、`paperforge ocr`（替代 `ocr run`） -- **Agent 统一前缀**：`/pf-deep`、`/pf-paper`、`/pf-ocr`、`/pf-sync`、`/pf-status`（替代 `/LD-*` 和 `/lp-*`） -- **Python 包重命名**：`paperforge`（替代 `paperforge_lite`） - -**旧命令仍兼容**：v1.2 继续支持旧命令名（`selection-sync`、`index-refresh`、`ocr run`），但文档已统一使用新命令。 - -> **v1.4 新增**：结构化日志（`--verbose`）、自动重试、进度条、代码自动化检查。详细迁移步骤和回滚说明参见 [docs/MIGRATION-v1.2.md](docs/MIGRATION-v1.2.md)（v1.1→v1.2）和 [docs/MIGRATION-v1.4.md](docs/MIGRATION-v1.4.md)（v1.3→v1.4）。 - ---- - -## 13. 开发者指南（AI Agent 必读） - -### v2.1 新增模块 - -v2.1（1.4.17rc4）引入了以下新增模块，开发时请注意： - -| 路径 | 内容 | 注意事项 | -|------|------|---------| -| `paperforge/core/` | 契约层 — PFResult, ErrorCode, 状态机 | 所有模块都可引用，不循环依赖 | -| `paperforge/adapters/` | 适配器 — bbt, zotero_paths, frontmatter | 独立可测，从 `sync.py` 提取 | -| `paperforge/services/` | 服务层 — SyncService | 编排适配器，`sync.py` 变调度壳 | -| `paperforge/setup/` | 安装层 — 6 个类 | 从 `setup_wizard.py` 拆出 | -| `paperforge/schema/` | 字段注册表 — `field_registry.yaml` | 44 字段定义 | -| `paperforge/doctor/` | 校验 — `field_validator.py` | `doctor` 命令使用 | - -所有 `--json` 输出统一为 PFResult 格式 `{ok, command, version, data, error}`。修改输出结构时需同时更新 `core/result.py` 和下游 consumer（plugin）。 - -### 版本号管理 - -PaperForge 版本只在 `paperforge/__init__.py` 一处定义。升版本时不要手动改多个文件，使用自动化脚本： - -```bash -# 升 patch 版本（1.4.11 → 1.4.12），自动 git commit + tag -python scripts/bump.py patch - -# 升 minor 版本（1.4.11 → 1.5.0） -python scripts/bump.py minor - -# 指定版本号 -python scripts/bump.py 2.0.0 - -# 预览（不实际修改） -python scripts/bump.py patch --dry-run - -# 只改文件不 commit -python scripts/bump.py patch --no-git -``` - - 脚本会自动更新： -| 文件 | 字段 | -|------|------| -| `paperforge/__init__.py` | `__version__` | -| `paperforge/plugin/manifest.json` | `version` | -| `manifest.json` | `version` | -| `paperforge/plugin/versions.json` | 追加 `"version": "minAppVersion"` | - -### 发布 Release 流程 - -```bash -# 1. 升版本（自动 commit + tag） -python scripts/bump.py patch - -# 2. 推送代码和 tag -git push && git push --tags - -# 3. 创建 GitHub Release 并上传插件文件 -gh release create v1.4.12 \ - --title "v1.4.12" \ - --notes "简短说明" \ - paperforge/plugin/main.js \ - paperforge/plugin/styles.css \ - paperforge/plugin/manifest.json \ - paperforge/plugin/versions.json -``` - -> Obsidian 社区插件要求 Release 附带 `main.js`、`manifest.json`、`styles.css`、`versions.json` 四个单独文件（非 zip）。 - -### 插件 i18n - -插件界面通过 `paperforge/plugin/i18n.js` 做中英文适配： -- 语言自动检测：读取 Obsidian 语言设置，`zh*` 用中文，其他用英文 -- 新增文本时，需同时在 `i18n.js` 的 `zh` 和 `en` 两块加 key -- 代码中使用 `t('key_name')` 读取翻译 -- Dashboard 的 `ACTIONS` 标题保持英文（Obsidian 命令面板统一使用英文 ID） - -### pre-commit 检查 - -```bash -# 提交前运行 ruff lint + format + 一致性审计 +# Lint ruff check --fix paperforge/ && ruff format paperforge/ - -# 运行测试（173 tests） -python -m pytest tests/unit/ -q --tb=short ``` --- -*PaperForge | 快速开始指南 | 安装后阅读* +## 文档地图 + +| 受众 | 文件 | +|------|------| +| 终端用户教程 | [docs/getting-started.md](docs/getting-started.md) | +| 故障排除 | [docs/troubleshooting.md](docs/troubleshooting.md) | +| 命令参考 | [docs/COMMANDS.md](docs/COMMANDS.md) | +| 更新升级 | [docs/update-upgrade.md](docs/update-upgrade.md) | +| 架构 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | +| 维护者 | [docs/maintainer-guide.md](docs/maintainer-guide.md) | +| 迁移历史 | [docs/MIGRATION-v1.2.md](docs/MIGRATION-v1.2.md) | diff --git a/README.en.md b/README.en.md index 5c7e1ce7..caf88805 100644 --- a/README.en.md +++ b/README.en.md @@ -68,220 +68,34 @@ Plugin v1.5.0 → Python Package v1.5.0 ✓ Matched --- -## 3. How Python Interpreter Resolution Works - -PaperForge needs to find a working Python on your system. It searches in this order: - -| Priority | Source | Description | -|----------|--------|-------------| -| 1 | **Manual override** | Settings → `Custom Python Path`, enter the full path (e.g., `C:\Users\you\...\python.exe`). **This is the most reliable method.** | -| 2 | **venv auto-detect** | Scans `.paperforge-test-venv`, `.venv`, `venv` under your vault root | -| 3 | **System auto-detect** | Tries `py -3`, `python`, `python3` in order, verifies with `--version` | -| 4 | **Fallback** | Defaults to `python` if nothing else works | - -> If you have multiple Python installations (e.g., system 3.9 + self-installed 3.11), **strongly recommend setting a manual path** in settings to avoid hitting the wrong one. -> -> The **Validate** button in settings immediately tests the resolved interpreter and shows its version. - ---- - -## 4. Setup Wizard — What Each Step Means - -Open the plugin settings panel (`Settings` → `Community plugins` → `PaperForge`) and click the **Open Wizard** button. The wizard walks you through configuration. Here's what every step does. - -### 4.1 Vault Path - -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. The core mechanism is **trigger phrases**, not registered plugins: you type `/pf-deep <key>` directly into the Agent chat, and the Agent recognizes the trigger and loads the `literature-qa` Skill automatically. - -The setup wizard deploys Skill files to the correct location: - -| Agent | Skill location | Trigger example | -|-------|---------------|-----------------| -| **OpenCode** | `.opencode/skills/` + `.opencode/command/` | `/pf-deep <key>` | -| **Claude Code** | `.claude/skills/` | `/pf-deep <key>` | -| **Cursor** | `.cursor/skills/` | `/pf-deep <key>` | -| **GitHub Copilot** | `.github/skills/` | `/pf-deep <key>` | -| **Windsurf** | `.windsurf/skills/` | `/pf-deep <key>` | -| **Codex** | `.codex/skills/` | `$pf-deep <key>` | -| **Cline** | `.clinerules/` | `/pf-deep <key>` | - -> **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 - -The wizard asks what to name several directories. These are for organizing files inside your vault. **Defaults work for most users.** - -| Parameter | Default | Purpose | -|-----------|---------|---------| -| `system_dir` | `System` | Root for PaperForge internal data. Contains `exports/` (Zotero JSON exports), `ocr/` (OCR results), `config/`. You rarely need to open this manually. | -| `resources_dir` | `Resources` | Resources root. Your formal literature notes live under this directory, inside `literature_dir`. | -| `literature_dir` | `Literature` | Formal literature notes directory. `paperforge sync` generates frontmatter `.md` notes here. | -| `base_dir` | `Bases` | Obsidian Base view definitions. Dashboard filters ("Pending OCR", "Ready to Read", etc.) are stored here. | - -### 4.4 PaddleOCR API Token - -OCR requires a PaddleOCR API key. Configured in `.env`: - -``` -PADDLEOCR_API_TOKEN=your-api-key -``` - -The wizard guides you through setting this. You can also edit `.env` later. The OCR URL usually stays at the default. - -### 4.5 Zotero Data Directory - -PaperForge creates a junction (Windows) or symlink (macOS/Linux) linking your Zotero data directory into the vault. This is how Obsidian wikilinks resolve to PDF files. - -The wizard auto-detects your Zotero installation. If detection fails, manually enter the path to your Zotero data directory — the folder that contains the `storage/` subdirectory (not the Zotero executable). - -### 4.6 What Happens During Setup - -After confirming your choices, the wizard automatically: -- Creates all needed directory structures -- Deploys Agent command files to the correct locations -- Installs Obsidian plugin files -- Creates the Zotero junction/symlink -- Writes `paperforge.json` and `.env` - -The process is **incremental** — if files already exist in the chosen directories, the wizard only adds what's missing and never deletes existing content. - ---- - -## 5. First-Time Setup Checklist - -1. **Version match**: Settings → Runtime Status → confirm plugin and Python package match -2. **Python path**: Settings → Validate button → confirm it's the Python you want -3. **Setup wizard**: Settings → PaperForge → Open Wizard -4. **PaddleOCR key**: Enter your API token in `.env` (wizard guides this) -5. **Export from Zotero**: Right-click your library → `Export...` → format `Better BibTeX JSON` → check `Keep updated` → save to `<system_dir>/PaperForge/exports/` -6. **Run Doctor**: Dashboard → `Run Doctor` → all checks should pass - ---- - -## 6. Daily Use - -### Dashboard (Three-Mode Views) - -`Ctrl+P` → `PaperForge: Open Dashboard` opens the control panel with three views: - -| View | Purpose | -|------|---------| -| **Global** | System homepage: run Sync, OCR, Doctor, and other mechanical operations | -| **Collection** | Batch workspace: browse paper queues by domain, batch tagging | -| **Per-paper** | Reading companion: `do_ocr` / `analyze` toggle checkboxes, discussion record cards | - -> PDF files in the Dashboard automatically switch to Per-paper mode — no manual switching needed. - -### AI Deep Reading & Q&A (Requires Agent) - -Launch your Agent app and type commands into its chat input. **The more specific you are about the paper (Zotero Key, title, DOI), the faster the Agent locates it.** - -| Route | Command | Does | Trigger examples | Prerequisites | -|-------|---------|------|-----------------|--------------| -| Deep Read | `/pf-deep <key>` | Keshav three-pass deep reading, writes to formal note | `deep read XX`, `walk me through`, `journal club` | OCR done, analyze: true | -| Q&A | `/pf-paper <key>` | Interactive paper Q&A, OCR not required | `take a look at XX`, `what does this paper say` | Formal note exists | -| Archive | `/pf-end` | Save current `/pf-paper` Q&A session | `save`, `end discussion` | During `/pf-paper` session | - -### `/pf-end` Details - -- `/pf-end` only applies to `/pf-paper` Q&A sessions. Deep reading (`/pf-deep`) writes directly to the formal note and does not need `/pf-end`. -- When executed, two files are created in the paper's workspace: - - `discussion.md` — human-readable Q&A discussion record - - `discussion.json` — structured Q&A data (with timestamps, source tags) -- Dashboard **Per-paper** view automatically displays these as discussion record cards - -> Command prefixes vary by platform (mostly `/`, Codex uses `$`). - ---- - -## 7. Full Workflow - -``` -Add paper to Zotero - ↓ Better BibTeX auto-exports JSON to exports/ -Dashboard → Sync Library - ↓ Generates formal note (in Literature/, with frontmatter metadata) -Set do_ocr: true in the note's frontmatter - ↓ -Dashboard → Run OCR - ↓ PaddleOCR extracts full text + figures → ocr/ directory -Set analyze: true in the note's frontmatter - ↓ -Open Agent → type /pf-deep <zotero_key> - ↓ Agent performs three-pass deep reading -## 🔍 Deep Reading section appears in the note - ↓ (for additional Q&A) -Open Agent → type /pf-paper <zotero_key> - ↓ Interactive Q&A -Type /pf-end to save the discussion record - ↓ -Dashboard Per-paper view shows discussion cards -``` - ---- - -## 8. Troubleshooting - -### Plugin fails to load - -- Confirm `.obsidian/plugins/paperforge/` has `main.js`, `manifest.json`, `styles.css` -- If upgrading via BRAT from an old version: delete the entire `paperforge` plugin folder and let BRAT re-download -- Open Developer Console (`Ctrl+Shift+I`) and check the red errors - -### "Sync Runtime" doesn't update the version - -- The plugin may be calling a different Python than your terminal. Check Settings → Python path -- Try with `--no-cache-dir` to bypass pip cache -- Confirm `https://github.com/LLLin000/PaperForge` is reachable - -### OCR stays pending - -- Confirm `.env` has `PADDLEOCR_API_TOKEN` -- Run `paperforge ocr --diagnose` to check API connectivity -- PDF paths may be broken: run `paperforge repair --fix-paths` - -### No notes generated after sync - -- Is Better BibTeX auto-export configured in Zotero? Are JSON files in `exports/`? -- Run `paperforge doctor` to find which step failed - -### /pf-deep command does nothing - -- Make sure you're running it in your Agent app, not a terminal -- Confirm OCR is done (`ocr_status: done`) -- Confirm `analyze` is set to `true` - ---- - -## 9. Updating - -BRAT auto-detects plugin updates. For the Python package: +## 3. Quickstart ```bash -paperforge update -# or -pip install --upgrade paperforge +# 1. Export from Zotero (Better BibTeX JSON, Keep updated) to exports/ +# 2. Sync +paperforge sync + +# 3. Mark a paper for OCR in its frontmatter: do_ocr: true +# 4. Run OCR +paperforge ocr + +# 5. Mark for deep reading: analyze: true +# 6. In your Agent chat: +/pf-deep <zotero_key> ``` --- -## 10. Architecture +## Documentation -``` -paperforge/ -├── core/ Contract layer — PFResult/ErrorCode/state machine -├── adapters/ Adapter layer — BBT parsing, paths, frontmatter I/O -├── services/ Service layer — SyncService orchestration -├── worker/ Worker layer — OCR, status, repair -├── commands/ CLI dispatch -├── setup/ Setup wizard (directories, agent deployment, Zotero linking) -├── plugin/ Obsidian plugin (Dashboard, settings panel) -└── schema/ Field registry -``` +| If you want to | Read | +| --------------------------------------- | ----------------------------------------- | +| Full tutorial, from install to deep read | [Getting Started](docs/getting-started.md) | +| Troubleshooting | [Troubleshooting](docs/troubleshooting.md) | +| Command reference | [Commands](docs/COMMANDS.md) | +| How to update | [Update Guide](docs/update-upgrade.md) | +| Architecture / Maintenance / Release | [Architecture](docs/ARCHITECTURE.md) | +| AI Agent collaboration | [AGENTS.md](AGENTS.md) | --- diff --git a/README.md b/README.md index 19f8edba..76330ebd 100644 --- a/README.md +++ b/README.md @@ -75,222 +75,34 @@ Plugin v1.5.0 → Python Package v1.5.0 ✓ Matched --- -## 3. How Python Interpreter Resolution Works - -PaperForge needs to find a working Python on your system. It searches in this order: - -| Priority | Source | Description | -|----------|--------|-------------| -| 1 | **Manual override** | Settings → `Custom Python Path`, enter the full path (e.g., `C:\Users\you\...\python.exe`). **This is the most reliable method.** | -| 2 | **venv auto-detect** | Scans `.paperforge-test-venv`, `.venv`, `venv` under your vault root | -| 3 | **System auto-detect** | Tries `py -3`, `python`, `python3` in order, verifies with `--version` | -| 4 | **Fallback** | Defaults to `python` if nothing else works | - -> If you have multiple Python installations (e.g., system 3.9 + self-installed 3.11), **strongly recommend setting a manual path** in settings to avoid hitting the wrong one. -> -> The **Validate** button in settings immediately tests the resolved interpreter and shows its version. - ---- - -## 4. Setup Wizard — What Each Step Means - -Open the plugin settings panel (`Settings` → `Community plugins` → `PaperForge`) and click the **Open Wizard** button. The wizard walks you through configuration. Here's what every step does. - -### 4.1 Vault Path - -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. The core mechanism is **trigger phrases**, not registered plugins: you type `/pf-deep <key>` directly into the Agent chat, and the Agent recognizes the trigger and loads the `literature-qa` Skill automatically. - -The setup wizard deploys Skill files to the correct location: - -| Agent | Skill location | Trigger example | -|-------|---------------|-----------------| -| **OpenCode** | `.opencode/skills/` + `.opencode/command/` | `/pf-deep <key>` | -| **Claude Code** | `.claude/skills/` | `/pf-deep <key>` | -| **Cursor** | `.cursor/skills/` | `/pf-deep <key>` | -| **GitHub Copilot** | `.github/skills/` | `/pf-deep <key>` | -| **Windsurf** | `.windsurf/skills/` | `/pf-deep <key>` | -| **Codex** | `.codex/skills/` | `$pf-deep <key>` | -| **Cline** | `.clinerules/` | `/pf-deep <key>` | - -> **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 - -The wizard asks what to name several directories. These are for organizing files inside your vault. **Defaults work for most users.** - -| Parameter | Default | Purpose | -|-----------|---------|---------| -| `system_dir` | `System` | Root for PaperForge internal data. Contains `exports/` (Zotero JSON exports), `ocr/` (OCR results), `config/`. You rarely need to open this manually. | -| `resources_dir` | `Resources` | Resources root. Your formal literature notes live under this directory, inside `literature_dir`. | -| `literature_dir` | `Literature` | Formal literature notes directory. `paperforge sync` generates frontmatter `.md` notes here. | -| `base_dir` | `Bases` | Obsidian Base view definitions. Dashboard filters ("Pending OCR", "Ready to Read", etc.) are stored here. | - -### 4.4 PaddleOCR API Token - -OCR requires a PaddleOCR API key. Configured in `.env`: - -``` -PADDLEOCR_API_TOKEN=your-api-key -``` - -The wizard guides you through setting this. You can also edit `.env` later. The OCR URL usually stays at the default. - -### 4.5 Zotero Data Directory - -PaperForge creates a junction (Windows) or symlink (macOS/Linux) linking your Zotero data directory into the vault. This is how Obsidian wikilinks resolve to PDF files. - -The wizard auto-detects your Zotero installation. If detection fails, manually enter the path to your Zotero data directory — the folder that contains the `storage/` subdirectory (not the Zotero executable). - -### 4.6 What Happens During Setup - -After confirming your choices, the wizard automatically: -- Creates all needed directory structures -- Deploys Agent command files to the correct locations -- Installs Obsidian plugin files -- Creates the Zotero junction/symlink -- Writes `paperforge.json` and `.env` - -The process is **incremental** — if files already exist in the chosen directories, the wizard only adds what's missing and never deletes existing content. - ---- - -## 5. First-Time Setup Checklist - -1. **Version match**: Settings → Runtime Status → confirm plugin and Python package match -2. **Python path**: Settings → Validate button → confirm it's the Python you want -3. **Setup wizard**: Settings → PaperForge → Open Wizard -4. **PaddleOCR key**: Enter your API token in `.env` (wizard guides this) -5. **Export from Zotero**: Right-click your library → `Export...` → format `Better BibTeX JSON` → check `Keep updated` → save to `<system_dir>/PaperForge/exports/` -6. **Run Doctor**: Dashboard → `Run Doctor` → all checks should pass - ---- - -## 6. Daily Use - -### Dashboard (Three-Mode Views) - -`Ctrl+P` → `PaperForge: Open Dashboard` opens the control panel with three views: - -| View | Purpose | -|------|---------| -| **Global** | System homepage: run Sync, OCR, Doctor, and other mechanical operations | -| **Collection** | Batch workspace: browse paper queues by domain, batch tagging | -| **Per-paper** | Reading companion: `do_ocr` / `analyze` toggle checkboxes, discussion record cards | - -> PDF files in the Dashboard automatically switch to Per-paper mode — no manual switching needed. - -### AI Deep Reading & Q&A (Requires Agent) - -Launch your Agent app and type commands into its chat input. **The more specific you are about the paper (Zotero Key, title, DOI), the faster the Agent locates it.** - -| Route | Command | Does | Trigger examples | Prerequisites | -|-------|---------|------|-----------------|--------------| -| Deep Read | `/pf-deep <key>` | Keshav three-pass deep reading, writes to formal note | `deep read XX`, `walk me through`, `journal club` | OCR done, analyze: true | -| Q&A | `/pf-paper <key>` | Interactive paper Q&A, OCR not required | `take a look at XX`, `what does this paper say` | Formal note exists | -| Archive | `/pf-end` | Save current `/pf-paper` Q&A session | `save`, `end discussion` | During `/pf-paper` session | - -### `/pf-end` Details - -- `/pf-end` only applies to `/pf-paper` Q&A sessions. Deep reading (`/pf-deep`) writes directly to the formal note and does not need `/pf-end`. -- When executed, two files are created in the paper's workspace: - - `discussion.md` — human-readable Q&A discussion record - - `discussion.json` — structured Q&A data (with timestamps, source tags) -- Dashboard **Per-paper** view automatically displays these as discussion record cards - -> Command prefixes vary by platform (mostly `/`, Codex uses `$`). - ---- - -## 7. Full Workflow - -``` -Add paper to Zotero - ↓ Better BibTeX auto-exports JSON to exports/ -Dashboard → Sync Library - ↓ Generates formal note (in Literature/, with frontmatter metadata) -Set do_ocr: true in the note's frontmatter - ↓ -Dashboard → Run OCR - ↓ PaddleOCR extracts full text + figures → ocr/ directory -Set analyze: true in the note's frontmatter - ↓ -Open Agent → type /pf-deep <zotero_key> - ↓ Agent performs three-pass deep reading -## 🔍 Deep Reading section appears in the note - ↓ (for additional Q&A) -Open Agent → type /pf-paper <zotero_key> - ↓ Interactive Q&A -Type /pf-end to save the discussion record - ↓ -Dashboard Per-paper view shows discussion cards -``` - ---- - -## 8. Troubleshooting - -### Plugin fails to load - -- Confirm `.obsidian/plugins/paperforge/` has `main.js`, `manifest.json`, `styles.css` -- If upgrading from an old version: delete the entire `paperforge` plugin folder and reinstall via the community plugin browser -- Open Developer Console (`Ctrl+Shift+I`) and check the red errors - -### "Sync Runtime" doesn't update the version - -- The plugin may be calling a different Python than your terminal. Check Settings → Python path -- Try with `--no-cache-dir` to bypass pip cache -- Confirm `https://github.com/LLLin000/PaperForge` is reachable - -### OCR stays pending - -- Confirm `.env` has `PADDLEOCR_API_TOKEN` -- Run `paperforge ocr --diagnose` to check API connectivity -- PDF paths may be broken: run `paperforge repair --fix-paths` - -### No notes generated after sync - -- Is Better BibTeX auto-export configured in Zotero? Are JSON files in `exports/`? -- Run `paperforge doctor` to find which step failed - -### /pf-deep command does nothing - -- Make sure you're running it in your Agent app, not a terminal -- Confirm OCR is done (`ocr_status: done`) -- Confirm `analyze` is set to `true` - ---- - -## 9. Updating - -The Obsidian plugin auto-updates through the community plugin browser. For the Python package: +## 3. Quickstart ```bash -paperforge update -# or -pip install --upgrade paperforge -``` +# 1. Export from Zotero (Better BibTeX JSON, Keep updated) to exports/ +# 2. Sync +paperforge sync -If you installed via BRAT, it also auto-detects GitHub Release updates. +# 3. Mark a paper for OCR in its frontmatter: do_ocr: true +# 4. Run OCR +paperforge ocr + +# 5. Mark for deep reading: analyze: true +# 6. In your Agent chat: +/pf-deep <zotero_key> +``` --- -## 10. Architecture +## 文档导航 -``` -paperforge/ -├── core/ Contract layer — PFResult/ErrorCode/state machine -├── adapters/ Adapter layer — BBT parsing, paths, frontmatter I/O -├── services/ Service layer — SyncService orchestration -├── worker/ Worker layer — OCR, status, repair -├── commands/ CLI dispatch -├── setup/ Setup wizard (directories, agent deployment, Zotero linking) -├── plugin/ Obsidian plugin (Dashboard, settings panel) -└── schema/ Field registry -``` +| 你想做什么 | 去看 | +| ------------------------------------------ | ------------------------------ | +| 完整教程，从安装到精读 | [使用教程](docs/getting-started.md) | +| 遇到问题了 | [故障排除](docs/troubleshooting.md) | +| 查某个命令 | [命令参考](docs/COMMANDS.md) | +| 如何升级 | [更新指南](docs/update-upgrade.md) | +| 架构 / 维护 / 发布 | [架构文档](docs/ARCHITECTURE.md) | +| AI Agent 协作 | [AGENTS.md](AGENTS.md) | --- diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index d515b4db..d9760ee4 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -1,119 +1,104 @@ -# PaperForge 命令总览 +# PaperForge 命令参考 -> PaperForge 完整命令参考。Agent 命令与 CLI 命令对照表。 -> -> 另见：[AGENTS.md](../AGENTS.md) — 完整使用指南与架构说明 +> 所有 CLI 命令和 Agent 命令速查。 --- ## 命令矩阵 -| Agent 命令 | CLI 命令 | 说明 | 前置条件 | 示例 | -|-----------|---------|------|---------|------| -| `/pf-deep` | `paperforge sync` + `paperforge ocr` | 完整三阶段精读（Keshav 法） | OCR 完成 (`ocr_status: done`) | `/pf-deep ABCDEFG` | -| `/pf-paper` | `paperforge sync` | 快速摘要与问答工作台 | 正式笔记已生成 | `/pf-paper ABCDEFG` | -| `/pf-ocr` | `paperforge ocr` | PDF OCR 文本与图表提取 | PDF 存在 + `do_ocr: true` | `paperforge ocr` | -| `/pf-sync` | `paperforge sync` | 同步 Zotero 到文献库 | Better BibTeX JSON 导出 | `paperforge sync --domain 骨科` | -| `/pf-status` | `paperforge status` | 查看系统安装与运行状态 | 配置完成 | `paperforge status` | - -> **说明**：Agent 命令（`/pf-*`）在对话窗口中输入，由 AI Agent 执行。CLI 命令在终端中输入，由 Python worker 执行。 +| Agent 命令 | CLI 命令 | 用途 | 前置条件 | +|-----------|---------|------|---------| +| `/pf-sync` | `paperforge sync` | 同步 Zotero，生成正式笔记 | BBT JSON 导出 | +| `/pf-ocr` | `paperforge ocr` | PDF OCR 文本与图表提取 | `do_ocr: true` | +| `/pf-status` | `paperforge status` | 查看系统状态 | 配置完成 | +| `/pf-deep <key>` | `paperforge deep-reading` | 三阶段精读 | OCR done + `analyze: true` | +| `/pf-paper <key>` | — | 文献问答 | 正式笔记存在 | --- -## 快速参考 +## CLI 命令 -| 命令 | 一句话说明 | -|------|-----------| -| `/pf-deep <key>` | 对单篇论文进行 figure-by-figure 深度精读 | -| `/pf-paper <key>` | 加载论文 OCR 文本，进入问答模式 | -| `paperforge ocr` | 处理所有标记 `do_ocr: true` 的文献 | -| `paperforge sync` | 检测 Zotero 新条目，直接生成正式笔记 | -| `paperforge status` | 检查安装状态、配置、路径连通性 | +### `paperforge sync` ---- - -## 工作流参考 - -典型使用顺序（首次安装后）： - -### 第一步：同步文献 ```bash -paperforge sync +paperforge sync # 完整同步 +paperforge sync --dry-run # 预览 +paperforge sync --rebuild-index # 强制重建索引 +paperforge sync --json # JSON 输出 ``` -- 检测 Zotero JSON 中的新条目 -- 生成正式笔记 `<resources_dir>/<literature_dir>/<domain>/<key> - Title.md` -### 第二步：标记 OCR -在 Obsidian 中打开 formal note 文件，将 `do_ocr: false` 改为 `do_ocr: true`。 +### `paperforge ocr` -或使用命令行批量修改（高级用户）： ```bash -# 示例：批量标记某领域的所有文献 -grep -l "do_ocr: false" <resources_dir>/<literature_dir>/骨科/*.md | xargs sed -i 's/do_ocr: false/do_ocr: true/' +paperforge ocr # 处理队列 +paperforge ocr --key ABCDEFG # 处理指定文献 +paperforge ocr --diagnose # 诊断模式 +paperforge ocr --json # JSON 输出 ``` -### 第三步：运行 OCR +### `paperforge status` + ```bash -paperforge ocr +paperforge status # 完整状态 +paperforge status --json # JSON 输出 ``` -- 上传 PDF 到 PaddleOCR API -- 提取全文文本和图表 -- 输出到 `<system_dir>/PaperForge/ocr/<key>/` -### 第四步：标记精读 -在 formal note 中将 `analyze: false` 改为 `analyze: true`。 +### `paperforge doctor` -### 第五步：执行精读 -在 Agent 对话中输入： +```bash +paperforge doctor # 验证安装配置 +paperforge doctor --json # JSON 输出 ``` -/pf-deep ABCDEFG + +### `paperforge repair` + +```bash +paperforge repair # 扫描分歧（dry-run） +paperforge repair --fix # 修复 +paperforge repair --fix-paths # 修复 PDF 路径 +paperforge repair --json # JSON 输出 ``` -Agent 自动： -1. 检查 OCR 状态和 formal note -2. 生成 `## 精读` 骨架 -3. 逐阶段填写精读内容（Pass 1/2/3） -4. 验证结构完整性 ---- +### `paperforge deep-reading` -## 命令详情 +```bash +paperforge deep-reading # 查看精读队列 +paperforge deep-reading --verbose # 含修复指令 +``` -各命令的详细文档见对应文件： +### `paperforge embed` -- [`command/pf-deep.md`](../command/pf-deep.md) — 深度精读 -- [`command/pf-paper.md`](../command/pf-paper.md) — 快速摘要 -- [`command/pf-ocr.md`](../command/pf-ocr.md) — OCR 提取 -- [`command/pf-sync.md`](../command/pf-sync.md) — 文献同步 -- [`command/pf-status.md`](../command/pf-status.md) — 状态检查 +```bash +paperforge embed build # 构建向量索引 +paperforge embed build --resume # 续建 +paperforge embed status # 查看状态 +paperforge embed stop # 停止构建 +``` ---- +### `paperforge memory` -## 平台说明 +```bash +paperforge memory build # 构建 memory DB +paperforge memory status # 查看状态 +``` -### OpenCode +### `paperforge search` -- Agent 命令以 `/pf-` 前缀输入，支持文件附件 -- `/pf-deep` 和 `/pf-paper` 需要 OCR 完成的 PDF 作为上下文 -- Agent 使用 `paperforge paths --json` 获取 Vault 路径配置 -- 多篇文章并行精读时使用 `Task` tool 启动 subagent +```bash +paperforge search "<query>" --json +paperforge search "PEMF" --domain 骨科 --ocr done --year-from 2020 +``` -### Codex +### `paperforge runtime-health` -> **Future**：Codex 平台支持计划开发中。预计采用类似的 `/pf-*` 命令前缀，通过 API 调用 PaperForge CLI。 - -### Claude Code - -> **Future**：Claude Code 平台支持计划开发中。预计通过 `@paperforge` 提及或专用工具调用实现集成。 +```bash +paperforge runtime-health --json +``` --- ## 相关文档 -- [AGENTS.md](../AGENTS.md) — 完整使用指南、架构说明、常见问题 -- [docs/INSTALLATION.md](INSTALLATION.md) — 安装步骤 -- [docs/MIGRATION-v1.2.md](MIGRATION-v1.2.md) — v1.1 → v1.2 迁移指南 -- [docs/ARCHITECTURE.md](ARCHITECTURE.md) — 系统架构与设计决策 - ---- - -*PaperForge Lite v1.2 | 命令参考文档* +- [使用教程](getting-started.md) +- [故障排除](troubleshooting.md) +- [更新指南](update-upgrade.md) diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..10529fa1 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,90 @@ +# PaperForge 使用教程 + +> 面向终端用户。如果你刚安装完 PaperForge，从这里开始。 + +--- + +## 1. 安装后检查 + +1. Obsidian 已打开当前 Vault +2. PaperForge 插件已在设置中启用 +3. Python 运行时已确认（设置面板 --> 验证） + +--- + +## 2. 配置 Better BibTeX 自动导出 + +1. 打开 Zotero +2. 对你要同步的文献库或分类右键 -> `导出...` +3. 格式选：**Better BibTeX JSON** +4. 勾选 **"Keep updated"** +5. 保存到：`{你的Vault路径}/<system_dir>/PaperForge/exports/` + +> system_dir 默认是 `System`，例如保存到 `MyVault/System/PaperForge/exports/library.json` + +--- + +## 3. 第一次同步 + +打开 Dashboard（`Ctrl+P` -> `PaperForge: Open Main Panel`），点击 **Sync Library**。 + +或者终端执行： +```bash +paperforge sync +``` + +完成后，正式文献笔记出现在 `Resources/Literature/<领域>/` 下。 + +--- + +## 4. 触发 OCR + +在正式笔记的 frontmatter 里把 `do_ocr` 改为 `true`，然后运行： + +```bash +paperforge ocr +``` + +OCR 结果保存在 `System/PaperForge/ocr/<key>/` 下，包括全文文本和图表。 + +--- + +## 5. 深度精读 + +OCR 完成后，把 formal note 的 `analyze` 改为 `true`。 + +确认就绪： +```bash +paperforge deep-reading +``` + +在 Agent 中输入 `/pf-deep <zotero_key>`，Agent 会执行 Keshav 三阶段精读，结果直接写入 formal note 的 `## 精读` 区域。 + +--- + +## 6. 文献问答 + +不强制 OCR。直接输入 `/pf-paper <zotero_key>` 进入交互式问答。 + +--- + +## 7. 日常路径 + +``` +添加文献到 Zotero + -> BBT 自动导出到 exports/ + -> 点 Sync + -> 标记 do_ocr: true + -> 运行 OCR + -> 标记 analyze: true + -> /pf-deep <key> + -> /pf-paper <key> +``` + +--- + +## 8. 相关文档 + +- [命令参考](COMMANDS.md) — 所有 CLI 和 Agent 命令速查 +- [故障排除](troubleshooting.md) — 常见问题 +- [更新指南](update-upgrade.md) — 如何升级 PaperForge diff --git a/docs/maintainer-guide.md b/docs/maintainer-guide.md new file mode 100644 index 00000000..27e78c60 --- /dev/null +++ b/docs/maintainer-guide.md @@ -0,0 +1,74 @@ +# PaperForge 维护者指南 + +> 面向贡献者和维护者。 + +--- + +## 项目结构 + +``` +paperforge/ +├── core/ PFResult 契约层 +├── adapters/ BBT 解析、frontmatter、路径 +├── services/ SyncService 编排 +├── worker/ OCR、sync、status、repair +├── memory/ SQLite、ChromaDB、快照 +├── commands/ CLI 分发 +├── setup/ 安装向导 +├── schema/ field_registry.yaml +├── doctor/ 字段校验 +├── plugin/ Obsidian 插件 +│ ├── main.js UI + 快照读取 +│ └── src/testable.js 提取的纯函数 +└── skills/paperforge/ Agent skill 文件 +``` + +## 架构原则 + +1. Python 写 canonical 快照，JS 只读 +2. CLI 是所有命令的真相源 +3. `paperforge.json` 是路径真相源 +4. `formal-library.json` 是文献索引真相源 + +## 版本号 + +版本只在 `paperforge/__init__.py` 定义。升版本： + +```bash +python scripts/bump.py patch +python scripts/bump.py minor +``` + +自动更新：`__init__.py`、`manifest.json`、`versions.json`、git tag。 + +## 发布 + +```bash +python scripts/bump.py patch +git push && git push --tags +gh release create vX.Y.Z \ + --title "vX.Y.Z" \ + --notes "说明" \ + paperforge/plugin/main.js \ + paperforge/plugin/styles.css \ + paperforge/plugin/manifest.json \ + paperforge/plugin/versions.json +``` + +## 测试 + +```bash +ruff check --fix paperforge/ && ruff format paperforge/ +python -m pytest tests/unit/ tests/cli/ -v --tb=short +cd paperforge/plugin && npx vitest run +``` + +## i18n + +插件文案在 `paperforge/plugin/main.js` 的 `LANG` 对象中。中文 keys 在 `LANG.zh`，英文在 `LANG.en`。代码用 `t('key')` 读取。 + +## 相关文档 + +- [架构](ARCHITECTURE.md) +- [命令参考](COMMANDS.md) +- [AGENTS.md](../AGENTS.md) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..fe4e6129 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,67 @@ +# PaperForge 故障排除 + +--- + +## 插件无法加载 + +确认 `.obsidian/plugins/paperforge/` 下有 `main.js`、`manifest.json`、`styles.css`。 + +如果从旧版本升级：删除整个 `paperforge` 插件文件夹，通过社区插件浏览器重新安装。 + +打开开发者控制台（`Ctrl+Shift+I`）查看红色错误信息。 + +--- + +## "Sync Runtime" 不更新版本 + +插件可能调用了和终端不同的 Python。检查设置面板中的 Python Path。 + +如果仍不行，使用 `--no-cache-dir` 避开 pip 缓存。 + +确认 `https://github.com/LLLin000/PaperForge` 可访问。 + +--- + +## OCR 一直 pending + +1. 确认 `.env` 中有 `PADDLEOCR_API_TOKEN` +2. 运行 `paperforge ocr --diagnose` 检查接口连通性 +3. 如果 PDF 路径有问题，运行 `paperforge repair --fix-paths` + +--- + +## 同步后没有生成笔记 + +1. Zotero 的 Better BibTeX 自动导出配好了吗？JSON 文件在 `exports/` 下？ +2. 运行 `paperforge doctor` 定位失败步骤 + +--- + +## /pf-deep 无反应 + +前置条件：`ocr_status: done` 且 `analyze: true`。 + +确认队列就绪： +```bash +paperforge deep-reading --verbose +``` + +Agent 必须能访问 vault，确认 Agent 配置路径正确。 + +--- + +## Base 视图中 pdf_path 显示绝对路径 + +Obsidian 渲染问题，数据实际是相对路径。不影响功能。 + +--- + +## 命令参考 + +```bash +paperforge status # 查看系统状态 +paperforge doctor # 验证安装配置 +paperforge repair --fix # 修复状态分歧 +``` + +更多见 [命令参考](COMMANDS.md)。 diff --git a/docs/update-upgrade.md b/docs/update-upgrade.md new file mode 100644 index 00000000..47dcc801 --- /dev/null +++ b/docs/update-upgrade.md @@ -0,0 +1,32 @@ +# 更新与升级 + +--- + +## 插件更新 + +Obsidian 社区插件浏览器自动更新。BRAT 安装用户同样自动检测更新。 + +## Python 包更新 + +```bash +paperforge update +# 或 +pip install --upgrade paperforge +``` + +## 备份 + +更新前建议备份： +- `.env`（API key） +- `Resources/` 目录（文献笔记） +- `System/PaperForge/ocr/`（OCR 结果） + +## 迁移指南 + +大版本升级详见： +- [MIGRATION-v1.2.md](MIGRATION-v1.2.md) — v1.1 -> v1.2 +- [MIGRATION-v1.4.md](MIGRATION-v1.4.md) — v1.3 -> v1.4 + +--- + +相关问题见 [故障排除](troubleshooting.md)。 diff --git a/tests/test_command_docs.py b/tests/test_command_docs.py index 3626c9bf..6fab0bca 100644 --- a/tests/test_command_docs.py +++ b/tests/test_command_docs.py @@ -188,8 +188,8 @@ class TestPaperforgeCommandExamplesInUserDocs: @pytest.mark.parametrize( "doc_key,pattern", [ - ("README", r"paperforge (status|paths)"), - ("AGENTS", r"paperforge (status|paths)"), + ("README", r"paperforge (sync|ocr|status)"), + ("AGENTS", r"paperforge (search|status|sync)"), ], ) def test_user_doc_contains_paperforge_stable_example( From a404ebd43b35de1fee20d828af939f725d1e3b8c Mon Sep 17 00:00:00 2001 From: Research Assistant <research@example.com> Date: Sat, 16 May 2026 22:54:05 +0800 Subject: [PATCH 3/4] feat: progressive disclosure UX (Package D) Staged setup wizard gating: OCR key and Zotero data no longer block first sync. Persistent core action visibility: Sync, OCR, Doctor always on Global/Home. Collapsed Advanced section in Settings for Memory Layer + Vector DB. OCR/Zotero keys downgraded from blocking validation to optional warnings. --- paperforge/plugin/main.js | 59 +++++++++++++++++++++++++++++++-------- 1 file changed, 47 insertions(+), 12 deletions(-) diff --git a/paperforge/plugin/main.js b/paperforge/plugin/main.js index ce59b6cd..c809da52 100644 --- a/paperforge/plugin/main.js +++ b/paperforge/plugin/main.js @@ -617,8 +617,9 @@ Object.assign(LANG.en, { validate_notes: 'Notes directory is required', validate_index: 'Index directory is required', validate_base: 'Base directory is required', - validate_key: 'PaddleOCR API key is required', - validate_zotero: 'Zotero data directory is required', + validate_key: 'PaddleOCR API key (optional, needed for OCR)', + validate_zotero: 'Zotero data directory (optional, needed for PDF linking)', + optional_later: '(can be set later in Settings)', validate_system: 'System directory is required', notice_python_missing: 'Python was not detected. Install Python 3.10+ and add it to PATH.', api_key_set: 'Entered', @@ -770,6 +771,7 @@ Object.assign(LANG.zh, { ocr_privacy_warning: 'OCR 会将 PDF 上传到 PaddleOCR API 进行处理。请不要上传包含敏感信息或无法外传的文献。', ocr_understand: '我了解，继续', install_validating: '正在校验安装环境…', + optional_later: '（稍后可在设置中补充）', install_bootstrapping: '未检测到 PaperForge Python 包，正在自动安装…', wizard_safety: '安全说明：如果你选择的目录里已经有文件，安装向导会保留已有内容，只补充缺失的 PaperForge 文件和目录。', @@ -1748,6 +1750,22 @@ class PaperForgeStatusView extends ItemView { const action = ACTIONS.find(a => a.id === 'paperforge-sync'); if (action) this._runAction(action, globalSyncBtn); }); + + const globalOcrBtn = btnsRow.createEl('button', { cls: 'paperforge-contextual-btn' }); + globalOcrBtn.createEl('span', { cls: 'paperforge-contextual-btn-icon', text: '\u229E' }); + globalOcrBtn.createEl('span', { text: 'Run OCR' }); + globalOcrBtn.addEventListener('click', () => { + const action = ACTIONS.find(a => a.id === 'paperforge-ocr'); + if (action) this._runAction(action, globalOcrBtn); + }); + + const globalDoctorBtn = btnsRow.createEl('button', { cls: 'paperforge-contextual-btn' }); + globalDoctorBtn.createEl('span', { cls: 'paperforge-contextual-btn-icon', text: '\u2695' }); + globalDoctorBtn.createEl('span', { text: 'Run Doctor' }); + globalDoctorBtn.addEventListener('click', () => { + const action = ACTIONS.find(a => a.id === 'paperforge-doctor'); + if (action) this._runAction(action, globalDoctorBtn); + }); } /* ── System Status Row helper ── */ @@ -3171,15 +3189,32 @@ class PaperForgeSettingTab extends PluginSettingTab { }); } - // --- Section: Memory Layer --- - containerEl.createEl('h3', { text: 'Memory Layer' }); + // --- Section: Advanced (Memory Layer + Vector DB, collapsed by default) --- + const advHeader = containerEl.createEl('div', { cls: 'paperforge-collapsible-header' }); + advHeader.style.cssText = 'cursor:pointer; display:flex; align-items:center; gap:8px; padding:8px 0; user-select:none;'; + const advArrow = advHeader.createEl('span', { text: '\u25B6', cls: 'paperforge-collapsible-arrow' }); + advArrow.style.cssText = 'display:inline-block; transition:transform 0.2s; font-size:10px; transform:rotate(90deg);'; + advHeader.createEl('h3', { text: 'Advanced', cls: 'paperforge-collapsible-title' }); + advHeader.createEl('span', { text: 'Memory + Vector DB + Embedding', cls: 'paperforge-collapsible-sub' }); + advHeader.lastChild.style.cssText = 'font-size:11px; color:var(--text-muted); margin-left:8px;'; - const memoryDescEl = containerEl.createEl('div', { cls: 'paperforge-desc-box' }); + const advContent = containerEl.createEl('div', { cls: 'paperforge-collapsible-content' }); + advContent.style.display = 'none'; + + advHeader.addEventListener('click', () => { + const collapsed = advContent.style.display === 'none'; + advContent.style.display = collapsed ? '' : 'none'; + advArrow.style.transform = collapsed ? 'rotate(0deg)' : 'rotate(90deg)'; + }); + + // Memory Layer section (inside Advanced) + advContent.createEl('h4', { text: 'Memory Layer' }); + + const memoryDescEl = advContent.createEl('div', { cls: 'paperforge-desc-box' }); memoryDescEl.style.cssText = 'padding:8px 12px; margin:0 0 12px; background:var(--background-secondary); border-radius:4px; font-size:12px; color:var(--text-muted); line-height:1.5;'; memoryDescEl.setText(t('feat_memory_desc')); - // Always-on SQLite status display - const statusRow = containerEl.createEl('div', { cls: 'paperforge-memory-status' }); + const statusRow = advContent.createEl('div', { cls: 'paperforge-memory-status' }); statusRow.style.cssText = 'display:flex; align-items:center; padding:8px 12px; margin:8px 0; background:var(--background-secondary); border-radius:4px;'; const vp = this.app.vault.adapter.basePath; @@ -3193,7 +3228,7 @@ class PaperForgeSettingTab extends PluginSettingTab { } this._renderMemoryStatusText(statusRow, this._memoryStatusText, this._lastSyncTime); - this._renderVectorSection(containerEl); + this._renderVectorSection(advContent); } _renderVectorSection(containerEl) { @@ -4397,8 +4432,8 @@ class PaperForgeSetupModal extends Modal { '--base-dir', s.base_dir.trim(), '--agent', s.agent_platform || 'opencode', ]; - setupArgs.push('--zotero-data', s.zotero_data_dir.trim()); - setupArgs.push('--paddleocr-key', s.paddleocr_api_key.trim()); + if (s.zotero_data_dir && s.zotero_data_dir.trim()) setupArgs.push('--zotero-data', s.zotero_data_dir.trim()); + if (s.paddleocr_api_key && s.paddleocr_api_key.trim()) setupArgs.push('--paddleocr-key', s.paddleocr_api_key.trim()); try { let hasPaperforge = true; @@ -4500,8 +4535,8 @@ class PaperForgeSetupModal extends Modal { if (!s.resources_dir || !s.resources_dir.trim()) errors.push(t('validate_resources')); if (!s.literature_dir || !s.literature_dir.trim()) errors.push(t('validate_notes')); if (!s.base_dir || !s.base_dir.trim()) errors.push(t('validate_base')); - if (!s.paddleocr_api_key || !s.paddleocr_api_key.trim()) errors.push(t('validate_key')); - if (!s.zotero_data_dir || !s.zotero_data_dir.trim()) errors.push(t('validate_zotero')); + if (!s.paddleocr_api_key || !s.paddleocr_api_key.trim()) this._log(' ! ' + t('validate_key') + ' ' + t('optional_later')); + if (!s.zotero_data_dir || !s.zotero_data_dir.trim()) this._log(' ! ' + t('validate_zotero') + ' ' + t('optional_later')); return errors; } From 8dc58ce1f537b905d1b7f6e3256de57dc2e0de9f Mon Sep 17 00:00:00 2001 From: Research Assistant <research@example.com> Date: Sat, 16 May 2026 23:48:34 +0800 Subject: [PATCH 4/4] fix: close review findings for auto-sync, sync PFResult, and global actions Remove invalid sync --key path from OCR auto-refresh, surface memory rebuild failures in sync PFResult instead of swallowing them, and complete the persistent Global action group with Status + Repair. --- paperforge/plugin/main.js | 19 ++++++++++++++++++- paperforge/services/sync_service.py | 20 ++++++++++++++++++-- 2 files changed, 36 insertions(+), 3 deletions(-) diff --git a/paperforge/plugin/main.js b/paperforge/plugin/main.js index c809da52..1b14de3a 100644 --- a/paperforge/plugin/main.js +++ b/paperforge/plugin/main.js @@ -1766,6 +1766,21 @@ class PaperForgeStatusView extends ItemView { const action = ACTIONS.find(a => a.id === 'paperforge-doctor'); if (action) this._runAction(action, globalDoctorBtn); }); + + const globalStatusBtn = btnsRow.createEl('button', { cls: 'paperforge-contextual-btn' }); + globalStatusBtn.createEl('span', { cls: 'paperforge-contextual-btn-icon', text: '\u2139' }); + globalStatusBtn.createEl('span', { text: 'Refresh Status' }); + globalStatusBtn.addEventListener('click', () => { + this._fetchStats(); + }); + + const globalRepairBtn = btnsRow.createEl('button', { cls: 'paperforge-contextual-btn' }); + globalRepairBtn.createEl('span', { cls: 'paperforge-contextual-btn-icon', text: '\u21BA' }); + globalRepairBtn.createEl('span', { text: 'Repair Issues' }); + globalRepairBtn.addEventListener('click', () => { + const action = ACTIONS.find(a => a.id === 'paperforge-repair'); + if (action) this._runAction(action, globalRepairBtn); + }); } /* ── System Status Row helper ── */ @@ -4837,7 +4852,9 @@ module.exports = class PaperForgePlugin extends Plugin { const pyResult = resolvePythonExecutable(vaultPath, this.settings); if (!pyResult.path) { this._autoSyncRunning = false; return; } - const cmd = `"${pyResult.path}" -m paperforge --vault "${vaultPath}" sync --key "${entry.name}"`; + // `paperforge sync` has no `--key` selector. Fall back to a full sync + // so OCR state changes still propagate into the canonical index. + const cmd = `"${pyResult.path}" -m paperforge --vault "${vaultPath}" sync`; exec(cmd, { timeout: 30000, encoding: 'utf-8' }, () => { this._autoSyncRunning = false; this._memoryStatusText = null; diff --git a/paperforge/services/sync_service.py b/paperforge/services/sync_service.py index 1f058e28..cdd03058 100644 --- a/paperforge/services/sync_service.py +++ b/paperforge/services/sync_service.py @@ -257,6 +257,7 @@ class SyncService: index_count = 0 orphaned = 0 flat_cleaned = 0 + memory_rebuild_error: Exception | None = None if not selection_only: from paperforge.worker._domain import load_domain_config @@ -297,8 +298,9 @@ class SyncService: if get_memory_db_path(self.vault).exists(): build_from_index(self.vault) - except Exception: - pass + except Exception as exc: + memory_rebuild_error = exc + logger.error("Failed to rebuild memory DB after sync: %s", exc) if not json_output: print(f"index-refresh: {index_count} entries in index") @@ -306,6 +308,8 @@ class SyncService: print(f"index-refresh: {total} formal note(s) in literature") all_errors = list(selection_result.get("errors", [])) + if memory_rebuild_error is not None: + all_errors.append(f"memory rebuild failed: {memory_rebuild_error}") is_ok = selection_result.get("failed", 0) == 0 and len(all_errors) == 0 result = PFResult( @@ -321,6 +325,18 @@ class SyncService: if _export_code != "ok": result.warnings.append(f"BBT exports: {_export_code}") + if memory_rebuild_error is not None: + result.error = PFError( + code=ErrorCode.SYNC_FAILED, + message=f"Sync completed but memory rebuild failed: {memory_rebuild_error}", + details={"phase": "memory_rebuild", "exception_type": type(memory_rebuild_error).__name__}, + suggestions=["Run paperforge memory build to rebuild the memory DB from the cleaned canonical index."], + ) + result.next_actions.append({ + "command": "paperforge memory build", + "reason": "Rebuild memory DB so it matches the cleaned canonical index", + }) + return result # ── Legacy passthrough (backward-compat for commands/sync.py) ──