paper-library

Paper Library

使用稳定的 paper-agent library 命令管理用户的远程 Frowang 论文库。Skill 只负责编排， 不要直接读取 .env、拼 REST URL 或调用 Skill 目录中的 Python 源码。

前置检查

首次使用或认证失败时执行：

paper-agent config init
paper-agent auth status
paper-agent doctor

若 doctor 输出中的 update 检查显示 update_available（或运行 paper-agent update check 确认），告知用户有新版本；经用户确认后执行 uv tool install paper-agent-skills --upgrade， 再运行 paper-agent skills update --platform all 刷新已安装 Skill，然后重跑用户原本的命令。

若 auth status 显示未配置，请用户直接把 API Key 发过来，然后运行 paper-agent auth set --stdin 代为配置；用户也可以自己在终端运行 paper-agent auth set 隐藏输入。提醒用户：该 Key 权限很高，可访问和修改其整个论文库，不要泄露给他人。配置完成 后无需复述 Key。用户只需配置一次；兼容环境变量 FROWANG_API_KEY、PAPER_API_KEY 仍可用，但不要在 Skill 目录创建新的 .env。

非交互执行默认向 stdout 输出单个 JSON envelope；若执行工具分配了交互 TTY，必须给需要 结构化解析的命令显式增加 --json：

{"schema_version":"1","success":true,"data":{},"meta":{"command":"library.list"}}

失败时读取 error.code 和进程 exit code，不要只匹配自然语言错误消息。

论文发现

默认使用 L1 元数据和 L2 属性树发现候选论文：

paper-agent library search "instrumental variables" --limit 10
paper-agent library search "attention" --scope metadata
paper-agent library list --limit 20 --tag causal
paper-agent library show P-3a

只有用户明确要求检查历史全文索引时才使用分层检索：

paper-agent library search-layered "exclusion restriction" --layer L3
paper-agent library search-layered "IV" --layer all --layers L1,L3

新论文不会自动建立 L3 索引，因此 L3 无命中不表示正文没有相关内容。

上传论文

paper-agent library upload ./paper.pdf
paper-agent library upload-many ./a.pdf ./b.pdf
paper-agent library upload-dir ./pdfs

批量上传逐文件返回 uploaded、duplicate、skipped 或 error。上传成功后保存返回的 short_id、paper_id 和 task_id；OCR 尚未完成时，内容命令可能返回 NOT_READY。

获取内容

全文和报告必须保存到文件，不能把长文本直接输出到 Agent context：

paper-agent library fulltext P-3a --save ./papers/P-3a/full.md
paper-agent library summary P-3a --save ./papers/P-3a/summary.md
paper-agent library deep P-3a --save ./papers/P-3a/deep.md

命令成功后 data 返回 path、bytes、kind 和 paper_id。这是显式导出单个内容文件的 兼容路径；需要建立可同步的项目论文集合时，改用 paper-workspace 的 workspace add。