# PaperForge 命令参考 > 所有 CLI 命令和 Agent 命令速查。 --- ## 命令矩阵 | Agent 命令 | CLI 命令 | 用途 | 前置条件 | |-----------|---------|------|---------| | `/pf-sync` | `paperforge sync` | 同步 Zotero，生成正式笔记 | BBT JSON 导出 | | `/pf-ocr` | `paperforge ocr` | PDF OCR 文本与图表提取 | `do_ocr: true` | | `/pf-status` | `paperforge status` / `paperforge runtime-health` | 查看系统状态 | 配置完成 | | `/pf-deep ` | `paperforge deep-reading` (队列) | 三阶段精读 (Agent 层) | OCR done + `analyze: true` | | `/pf-paper ` | — | 文献问答 (Agent 层) | 正式笔记存在 | | `/pf-end ` | — | 结束精读/问答 Session (Agent 层) | 精读或问答进行中 | | `/pf-log-reading` | `paperforge reading-log --write ` | 记录阅读笔记 | 精读进行中 | | `/pf-log-session` | `paperforge project-log --write` | 总结会话决策 | 会话结束 | --- ## CLI 命令 ### `paperforge paths` ```bash paperforge paths # 打印 vault 路径清单 paperforge paths --json # JSON 格式输出 ``` ### `paperforge status` ```bash paperforge status # 完整状态检查 paperforge status --json # JSON 输出 ``` ### `paperforge sync` ```bash paperforge sync # 完整同步 paperforge sync --dry-run # 预览 paperforge sync --selection # 仅 selection-sync paperforge sync --index # 仅 index-refresh paperforge sync --rebuild-index # 强制重建索引 paperforge sync --prune # 预览清理孤儿笔记 (dry-run) paperforge sync --prune-force # 执行清理 paperforge sync --json # JSON 输出 ``` ### `paperforge selection-sync` ```bash paperforge selection-sync # 同步 Zotero 选择到文献记录 (向后兼容) ``` ### `paperforge index-refresh` ```bash paperforge index-refresh # 刷新正式文献笔记 (向后兼容) ``` ### `paperforge deep-reading` ```bash paperforge deep-reading # 查精读队列状态 paperforge deep-reading --json # JSON 输出 ``` ### `paperforge deep-finalize` ```bash paperforge deep-finalize # 标记精读完成并通知 Dashboard paperforge deep-finalize --json ``` ### `paperforge repair` ```bash paperforge repair # 扫描分歧 (dry-run) paperforge repair --fix # 修复 paperforge repair --fix-paths # 修复 PDF 路径 paperforge repair --json # JSON 输出 ``` ### `paperforge ocr` ```bash paperforge ocr # 处理队列 (旧式) paperforge ocr --key # 处理指定文献 paperforge ocr --diagnose # 诊断模式 paperforge ocr --json # JSON 输出 paperforge ocr run # 运行 OCR 队列 (新式) paperforge ocr doctor # 诊断 OCR 配置和连接 paperforge ocr doctor --live # 运行真实 PDF 测试 (L4) paperforge ocr redo # 重新运行所有标记 ocr_redo 的文献 paperforge ocr redo [KEY...] # 重新运行指定文献 paperforge ocr redo --dry-run # 预览待重做的文献 paperforge ocr list # 列出所有 OCR 维护状态 paperforge ocr list --json # JSON 输出 paperforge ocr list --manifest # 输出 key→sha256 清单 paperforge ocr list --keys ... # 仅指定 key 的信息 paperforge ocr rebuild # 从已有 raw blocks 重建 OCR 产物 paperforge ocr rebuild ... # 重建指定文献 paperforge ocr rebuild --all # 重建全部 paperforge ocr rebuild --status done # 按状态过滤 paperforge ocr rebuild --dry-run # 预览 paperforge ocr rebuild --resume # 跳过已有检查点的文献 ``` ### `paperforge context` ```bash paperforge context # 单篇文献的 AI context 包 (JSON) paperforge context --domain 骨科 # 按 domain 过滤 (JSON 数组) paperforge context --collection "path/to/coll" # 按 collection 过滤 paperforge context --all # 输出全部 canonical index ``` ### `paperforge dashboard` ```bash paperforge dashboard # 聚合统计和 Dashboard 权限 paperforge dashboard --json # JSON 输出 ``` ### `paperforge embed` ```bash paperforge embed build # 构建向量索引 paperforge embed build --resume # 续建 paperforge embed build --force # 强制重建 paperforge embed build --json # JSON 输出 paperforge embed status # 查看向量 DB 状态 paperforge embed status --json # JSON 输出 paperforge embed stop # 停止构建 paperforge embed stop --json # JSON 输出 ``` ### `paperforge retrieve` ```bash paperforge retrieve "" # 跨 OCR 全文语义检索 paperforge retrieve "PEMF" --limit 10 --json paperforge retrieve "75 Hz" --no-expand ``` ### `paperforge query-plan` ```bash paperforge query-plan "" --intent discover # 文献发现 paperforge query-plan "" --intent content # 内容检索 paperforge query-plan "" --intent known-paper # 已知论文定位 paperforge query-plan "" --intent discover --json ``` ### `paperforge prune` ```bash paperforge prune # 预览删除孤儿产物 (dry-run) paperforge prune --force # 实际删除 paperforge prune [KEY...] # 仅处理指定 key paperforge prune --json # JSON 输出 ``` ### `paperforge memory` ```bash paperforge memory build # 构建 memory DB paperforge memory build --json # JSON 输出 paperforge memory status # 查看 memory DB 状态 paperforge memory status --json # JSON 输出 ``` ### `paperforge search` ```bash paperforge search "" # 元数据全文搜索 paperforge search "" --json paperforge search "PEMF" --domain 骨科 --ocr done --year-from 2020 paperforge search "PEMF" --deep done --lifecycle fulltext_ready paperforge search "PEMF" --next-step ocr --limit 10 ``` ### `paperforge paper-status` ```bash paperforge paper-status # 查找文献状态 (key/DOI/title/alias) paperforge paper-status "XGT9Z257" --json ``` ### `paperforge paper-context` ```bash paperforge paper-context # 文献完整上下文 paperforge paper-context "XGT9Z257" --json ``` ### `paperforge reading-log` ```bash paperforge reading-log --write --section "Discussion P12" --excerpt "..." --usage "..." # 写阅读笔记 paperforge reading-log --render # 渲染 reading-log.md paperforge reading-log --lookup # 查某文献的阅读笔记 paperforge reading-log --since 2026-01-01 --limit 100 --output notes.md # 导出 paperforge reading-log --validate reading-log.md paperforge reading-log --import reading-log.md paperforge reading-log --correct --correction "..." --reason "..." # 修正笔记 paperforge reading-log --json ``` ### `paperforge project-log` ```bash paperforge project-log --write --project "ProjectX" --payload '{"hours":2,"status":"progress"}' # 写工作日志 paperforge project-log --list --project "ProjectX" paperforge project-log --render --project "ProjectX" paperforge project-log --project "ProjectX" --json ``` ### `paperforge agent-context` ```bash paperforge agent-context # 生成 Agent 引导上下文 paperforge agent-context --json # JSON 输出 ``` ### `paperforge runtime-health` ```bash paperforge runtime-health # 检查 memory layer 运行时健康 paperforge runtime-health --json # JSON 输出 ``` ### `paperforge base-refresh` ```bash paperforge base-refresh # 刷新 Obsidian Base 视图 paperforge base-refresh --force # 强制全量重建 ``` ### `paperforge doctor` ```bash paperforge doctor # 验证安装配置 paperforge doctor --json # JSON 输出 ``` ### `paperforge update` ```bash paperforge update # 更新到最新版本 ``` ### `paperforge setup` ```bash paperforge setup # 交互式设置 paperforge setup --headless # 非交互式 (AI 代理) paperforge setup --agent opencode # 指定 AI Agent 平台 paperforge setup --paddleocr-key "KEY" --paddleocr-url "URL" paperforge setup --skip-checks # 跳过环境检查 paperforge setup --modular # 使用模块化设置 (v2.1+) ``` ### `paperforge paper-lookup` ```bash paperforge paper-lookup "" # L4 网关: 定位文献 paperforge paper-lookup "PEMF" --json --limit 10 ``` ### `paperforge content-discovery` ```bash paperforge content-discovery "" # L4 网关: 内容发现 paperforge content-discovery "骨科 生物力学" --json --limit 10 ``` ### `paperforge paper-navigation` ```bash paperforge paper-navigation "" # L4 网关: 文献结构导航 paperforge paper-navigation "XGT9Z257" --json ``` ### `paperforge scoped-fetch` ```bash paperforge scoped-fetch "" # L4 网关: 范围受限获取 paperforge scoped-fetch "PEMF 75 Hz treatment protocol" --json --limit 10 ``` --- ## 相关文档 - [使用教程](getting-started.md) - [故障排除](troubleshooting.md) - [更新指南](update-upgrade.md) --- ## 测试 ### 合成 OCR 测试（CI 默认） ```bash python -m pytest tests/test_ocr_synthetic_fixtures.py -q --tb=short ``` ### 真实文献 OCR 回归测试（可选集成测试） 需要设置环境变量指定 vault 路径和要测试的文献 key： **Unix/macOS:** ```bash PAPERFORGE_REAL_OCR_VAULT="/path/to/Literature-hub" PAPERFORGE_REAL_OCR_KEYS="SAN9AYVR,2GN9LMCW" python -m pytest tests/test_ocr_real_paper_regressions.py -q ``` **PowerShell:** ```powershell $env:PAPERFORGE_REAL_OCR_VAULT="D:\path\to\Literature-hub"; $env:PAPERFORGE_REAL_OCR_KEYS="SAN9AYVR,2GN9LMCW"; python -m pytest tests/test_ocr_real_paper_regressions.py -q ``` 不设置环境变量时，真实文献测试自动 SKIP。