paperzilla

Paperzilla

当你想要与 Agent 聊 Paperzilla 中的项目、推荐和经典论文时，请使用此技能。

你可以问什么

• “给我项目 X 的最新推荐。”
• “打开推荐 Y，并解释它为什么重要。”
• “以 markdown 获取经典论文 Z，并总结它。”
• “告诉我这篇论文与我的研究有什么关系。”
• “给我看看项目 X 的信息流。”
• “对某条推荐留下反馈。”
• “将这篇论文、推荐或信息流导出为 JSON。”

这是 Paperzilla 的核心技能。它让 Agent 直接访问 Paperzilla 数据，但不会强加工作流或外部投递集成。

访问方式

使用官方 pz 命令行。此技能面向 0.7.1，并已对照官方发布源码和二进制文件进行核验。命令示例使用占位符 ID；请将它们替换为你的账号返回的记录。命令行行为已对照本地 mock 服务进行测试，而非经过身份验证的 Paperzilla 账号。

从 pz --version 开始，然后列出项目、选择项目、浏览或搜索其信息流，并查看选定的推荐。在总结或导出时，请将项目推荐与底层的经典论文分开处理。

安装

macOS

brew install paperzilla-ai/tap/pz

如果 Homebrew 6 或更高版本因该 formula 不受信任而拒绝它，官方指南会使用 brew trust --formula paperzilla-ai/tap/pz，然后重试安装。只信任该 formula。安装和升级命令经过文档核验，但未在本次审查期间执行。

Windows (Scoop)

scoop bucket add paperzilla-ai https://github.com/paperzilla-ai/scoop-bucket
scoop install pz

Linux

使用官方 Linux 安装指南：

• https://docs.paperzilla.ai/guides/cli-getting-started

从源码构建（Go 1.23+）

有关从源码构建，请参阅命令行：

• https://github.com/paperzilla-ai/pz

更新

检查你的命令行是否为最新版本，并获取针对具体安装方式的升级步骤：

pz update

如果检测结果不明确，请显式覆盖：

pz update --install-method homebrew
pz update --install-method scoop
pz update --install-method release
pz update --install-method source

支持的值为 auto、homebrew、scoop、release 和 source。

身份验证

pz login

登录会向账号邮箱发送一次性验证码，并在本地保存会话。请在运行 JSON 导出前以交互方式完成登录：凭据缺失或过期可能会在 stdout 上触发登录提示。命令行会检查账号访问权限并自动刷新令牌；请报告访问/升级错误，而不要将其视为空信息流。

版本特定差异： 在线指南描述了匿名访问经典论文，但 0.7.1 二进制文件即使对 pz paper 也要求登录和命令行访问检查。其后续的经典论文 HTTP 请求使用公开路由。不要承诺此版本支持匿名命令行工作流。

命令行参考

如果当前 profile 使用 pz，这些是核心命令。

列出项目

pz project list
pz project list --json

显示单个项目

pz project <project-id>
pz project <project-id> --json

列表 JSON 是一个数组，包含 id、name、mode 和 visibility。 单项目 JSON 还包含关键词、关注来源和类别。

浏览项目信息流

pz feed <project-id>

有用的标志：

• --must-read
• --since YYYY-MM-DD
• --limit N
• --offset N（要跳过的从零开始的结果数）
• --json
• --atom

示例：

pz feed <project-id> --must-read --since 2026-03-01 --limit 5
pz feed <project-id> --limit 20 --offset 20 --json
pz feed <project-id> --json
pz feed <project-id> --atom

--since 过滤的是推荐就绪的时间，而不是论文发表日期。 浏览 JSON 包含 items、total、limit 和 offset。一条命令获取 一页；它不会自动导出整个信息流。保留相同的过滤器，根据收到的条目数从返回的 offset 继续前进，并在页面为空或达到返回的 total 时停止。如果在分页过程中实时信息流发生变化，请按推荐 ID 去重。

信息流输出可能包含现有的推荐反馈标记：

• [↑] 点赞
• [↓] 点踩
• [★] 收藏

搜索完整项目 feed

pz feed search --project-id <project-id> --query "latent retrieval" --json
pz feed search --project-id <project-id> --query "retrieval" --feedback-filter starred --must-read --limit 20 --offset 20 --json

搜索会对整个项目 feed 中的结果进行排序。使用长度为 3–200 个字符的去除首尾空白的查询，以及最大为 100 的正数 --limit。--offset 必须为非负数。反馈过滤器包括 all、unrated、liked、disliked、starred、not-relevant 和 low-quality；这些带连字符的过滤器与下方带下划线的反对理由不同。搜索不接受 --since。

搜索 JSON 包含 items、limit、offset、has_more 和 query，不包含精确总数。仅在 has_more 为 true 时请求下一个 offset，并保持查询和过滤器不变。若遇到不一致的空页面，应停止并报告，而不是无限循环。第二个示例展示了后续页面。

阅读一篇规范论文

pz paper <paper-id>
pz paper <paper-id> --json
pz paper <paper-id> --markdown
pz paper <paper-id> --project <project-id>

从你的某个项目中打开一条推荐

pz rec <project-paper-id>
pz rec <project-paper-id> --json
pz rec <project-paper-id> --markdown

留下推荐反馈

pz feedback <project-paper-id> upvote
pz feedback <project-paper-id> star
pz feedback <project-paper-id> downvote --reason not_relevant
pz feedback clear <project-paper-id>

反馈会更改账户数据；当用户请求该更改时使用它。反对理由为 not_relevant 或 low_quality，且 --reason 仅适用于反对。添加 --json 可获取反馈对象；清除会返回 {"project_paper_ref": "...", "cleared": true}。clear 是位于推荐 ID 之前的子命令。

保持论文身份与推荐身份相互独立

规范的 paper-id 标识论文；project-paper-id 标识其在某个项目内的推荐。两者都应从返回的记录中获取，并在导出结果时保留项目关联。即使同一篇论文出现在多个项目中，rec 和反馈操作也应使用推荐 ID。在 feed JSON 中，items[].id/items[].short_id 是推荐标识符；items[].paper.id/items[].paper.short_id 是规范论文标识符。不要从 DOI 或规范论文 ID 推断推荐 ID。参见官方 CLI 文档。

当 markdown 仍在准备中时，报告该状态并仅总结实际返回的元数据或摘要。重试消息不是全文证据。

输出与自动化

• 完成登录后，优先使用 --json 以便机器解析。paper 和 rec 拒绝将 --json 与 --markdown 组合使用。
• pz paper --markdown 仅在 markdown 已准备就绪时返回 markdown。
• pz rec --markdown 和项目范围的 pz paper --project ... --markdown 可以排队生成 markdown。待处理消息可以成功退出；在将 stdout 视为全文之前检查内容。避免反复立即重试，并报告待处理状态。
• --atom 会返回供 feed 阅读器使用的个人 feed URL，并可以创建 feed token。任何持有该 URL 的人都可以读取该 feed；请将其 token 排除在日志、公开报告和代码库之外。它不会返回 Atom XML 或页面 JSON，且浏览过滤器不会应用于生成的 URL。
• 相关性评分表示项目匹配程度，而非科学有效性或效应估计。请标注摘要使用的是元数据、摘要还是实际 markdown。缺少 PDF URL 并不意味着来源落地页不存在。

配置

export PZ_API_URL="https://paperzilla.ai"

默认已指向 Paperzilla；仅针对受信任的服务或本地测试服务器更改它。经过身份验证的请求会向该处发送会话凭据。PZ_TOKENS_PATH 可选地指定会话文件；默认情况下，CLI 使用 ~/.paperzilla/tokens.json。切勿将该文件作为研究数据导出。

有关请求路由、响应结构、分页以及文档/源代码差异，请参见经过验证的 CLI 契约。

参考资料

• 文档：https://docs.paperzilla.ai/guides/cli
• 快速开始：https://docs.paperzilla.ai/guides/cli-getting-started
• 代码库：https://github.com/paperzilla-ai/pz