lllin000_PaperForge/docs/COMMANDS.md

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 <key>	paperforge deep-reading (队列)	三阶段精读 (Agent 层)	OCR done + analyze: true
/pf-paper <key>	—	文献问答 (Agent 层)	正式笔记存在
/pf-end <key>	—	结束精读/问答 Session (Agent 层)	精读或问答进行中
/pf-log-reading	paperforge reading-log --write <key>	记录阅读笔记	精读进行中
/pf-log-session	paperforge project-log --write	总结会话决策	会话结束

---

CLI 命令

paperforge paths

paperforge paths                    # 打印 vault 路径清单
paperforge paths --json             # JSON 格式输出

paperforge status

paperforge status                   # 完整状态检查
paperforge status --json            # JSON 输出

paperforge sync

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

paperforge selection-sync           # 同步 Zotero 选择到文献记录 (向后兼容)

paperforge index-refresh

paperforge index-refresh            # 刷新正式文献笔记 (向后兼容)

paperforge deep-reading

paperforge deep-reading             # 查精读队列状态
paperforge deep-reading --json      # JSON 输出

paperforge deep-finalize

paperforge deep-finalize <KEY>      # 标记精读完成并通知 Dashboard
paperforge deep-finalize <KEY> --json

paperforge repair

paperforge repair                   # 扫描分歧 (dry-run)
paperforge repair --fix             # 修复
paperforge repair --fix-paths       # 修复 PDF 路径
paperforge repair --json            # JSON 输出

paperforge ocr

paperforge ocr                      # 处理队列 (旧式)
paperforge ocr --key <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> [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>... # 仅指定 key 的信息
paperforge ocr rebuild              # 从已有 raw blocks 重建 OCR 产物
paperforge ocr rebuild <KEY>...     # 重建指定文献
paperforge ocr rebuild --all        # 重建全部
paperforge ocr rebuild --status done # 按状态过滤
paperforge ocr rebuild --dry-run    # 预览
paperforge ocr rebuild --resume     # 跳过已有检查点的文献

paperforge context

paperforge context <KEY>            # 单篇文献的 AI context 包 (JSON)
paperforge context --domain 骨科    # 按 domain 过滤 (JSON 数组)
paperforge context --collection "path/to/coll" # 按 collection 过滤
paperforge context --all            # 输出全部 canonical index

paperforge dashboard

paperforge dashboard                # 聚合统计和 Dashboard 权限
paperforge dashboard --json         # JSON 输出

paperforge embed

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

paperforge retrieve "<query>"       # 跨 OCR 全文语义检索
paperforge retrieve "PEMF" --limit 10 --json
paperforge retrieve "75 Hz" --no-expand

paperforge query-plan

paperforge query-plan "<query>" --intent discover    # 文献发现
paperforge query-plan "<query>" --intent content      # 内容检索
paperforge query-plan "<query>" --intent known-paper  # 已知论文定位
paperforge query-plan "<query>" --intent discover --json

paperforge prune

paperforge prune                     # 预览删除孤儿产物 (dry-run)
paperforge prune --force             # 实际删除
paperforge prune <KEY> [KEY...]      # 仅处理指定 key
paperforge prune --json              # JSON 输出

paperforge memory

paperforge memory build              # 构建 memory DB
paperforge memory build --json       # JSON 输出
paperforge memory status             # 查看 memory DB 状态
paperforge memory status --json      # JSON 输出

paperforge search

paperforge search "<query>"          # 元数据全文搜索
paperforge search "<query>" --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

paperforge paper-status <query>      # 查找文献状态 (key/DOI/title/alias)
paperforge paper-status "XGT9Z257" --json

paperforge paper-context

paperforge paper-context <key>       # 文献完整上下文
paperforge paper-context "XGT9Z257" --json

paperforge reading-log

paperforge reading-log --write <KEY> --section "Discussion P12" --excerpt "..." --usage "..." # 写阅读笔记
paperforge reading-log --render      # 渲染 reading-log.md
paperforge reading-log --lookup <KEY> # 查某文献的阅读笔记
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 <ID> --correction "..." --reason "..." # 修正笔记
paperforge reading-log --json

paperforge project-log

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

paperforge agent-context             # 生成 Agent 引导上下文
paperforge agent-context --json      # JSON 输出

paperforge runtime-health

paperforge runtime-health            # 检查 memory layer 运行时健康
paperforge runtime-health --json     # JSON 输出

paperforge base-refresh

paperforge base-refresh              # 刷新 Obsidian Base 视图
paperforge base-refresh --force      # 强制全量重建

paperforge doctor

paperforge doctor                    # 验证安装配置
paperforge doctor --json             # JSON 输出

paperforge update

paperforge update                    # 更新到最新版本

paperforge setup

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

paperforge paper-lookup "<query>"    # L4 网关: 定位文献
paperforge paper-lookup "PEMF" --json --limit 10

paperforge content-discovery

paperforge content-discovery "<query>" # L4 网关: 内容发现
paperforge content-discovery "骨科 生物力学" --json --limit 10

paperforge paper-navigation

paperforge paper-navigation "<query>"  # L4 网关: 文献结构导航
paperforge paper-navigation "XGT9Z257" --json

paperforge scoped-fetch

paperforge scoped-fetch "<query>"      # L4 网关: 范围受限获取
paperforge scoped-fetch "PEMF 75 Hz treatment protocol" --json --limit 10

---

相关文档

• 使用教程
• 故障排除
• 更新指南

---

测试

合成 OCR 测试（CI 默认）

python -m pytest tests/test_ocr_synthetic_fixtures.py -q --tb=short

真实文献 OCR 回归测试（可选集成测试）

需要设置环境变量指定 vault 路径和要测试的文献 key：

Unix/macOS:

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:

$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。