zotagent

zotagent

zotagent 是用于 Zotero 文献库的命令行工具：可搜索和检索已编入索引的附件（PDF / EPUB / HTML / TXT）及书目元数据；通过 DOI、网页 URL、标识符（ISBN / PMID / arXiv）、Semantic Scholar paperId、JSON 或手动填写的字段添加条目；通过 Semantic Scholar 跟踪论文的参考文献和引用；并查看最近的 Zotero 条目。任务命令会输出 JSON（成功时为 {ok: true, data, meta?}，失败时为 {ok: false, error, meta?}，并以退出码 1 退出）。

不要编造引文键、条目键或段落文本。如果查询没有结果，请如实说明。

三种搜索层——选择合适的一种

命令	搜索范围	适用场景
zotagent search "<q>" [--semantic] [--tag <tag>] [--collection-key <key>] [--limit n] [--min-score n]	仅搜索已编入索引的全文——正文，不包括标题（默认使用 FTS5 关键词搜索；使用 --semantic 时使用 qmd 向量搜索；关键词搜索可选按 Zotero 标签和／或文库筛选）	在整个文库或带标签、限定文库的子集中查找讨论某个主题的段落
zotagent search-in "<q>" --key <k> [--limit n]	单个条目中已编入索引的附件全文	在某篇论文中深入查找术语或引用短语
zotagent metadata ["<q>"] [metadata filters...] [--tag <tag>] [--collection-key <key>] [--field f] [--abstract] [--indexed] [--limit n]	书目字段：标题 / 作者 / 年份 / 期刊 / 出版商 / 摘要；可选按 Zotero 标签或文库筛选	按元数据或标题查找论文、确认条目是否存在、解析 itemKey

元数据速查规则：

• 可使用位置查询、字段筛选器（--author / --year / --title / --journal / --publisher），或两者同时使用。
• --field 仅限定位置查询的字段；筛选标志之间按 AND 逻辑组合。
• --tag "PhD Thesis" 会从 Zotero Web API 获取匹配的顶层条目键，然后筛选本地结果——因此请将工作流标签添加到父条目，而非 PDF 附件。重复使用 --tag 可按 AND 逻辑匹配多个标签。此操作需要 Zotero 读取 API 配置。如果没有顶层条目带有该标签，会返回警告而非错误——在断定文库中没有内容之前，请先检查标签拼写。
• --collection-key ABCD1234 会筛选仅直接位于指定 Zotero 文库中的顶层条目（该 8 字符键显示在 zotero.org/<user>/collections/<key> 的末尾）。重复使用 --collection-key 可合并多个文库的结果；与 --tag 组合时则取交集。仅包含直接条目——不包括子文库。此操作需要 Zotero 读取 API 配置。未知键会导致 COLLECTION_NOT_FOUND；没有顶层条目的文库会返回警告。
• --abstract 会在输出中包含摘要文本（默认省略，以保持响应简洁）。如需搜索摘要文本，请使用带 --field abstract 的位置查询。
• 每条结果都会报告 indexed / indexedFiles，数据读取自共享全文索引：表示 search-in / fulltext 能否读取该条目。此信息与设备无关——它不表示当前机器上是否存在附件文件，而且仅在 Zotero 中有 file 条目并不代表满足条件；附件必须经过 sync 提取。若扫描件没有文本层，即使执行过 sync，仍会保持 indexed: false：提取会将其记录为错误，直到 PDF 完成 OCR。--indexed 仅保留已编入索引的条目。
• metadata "Pratt 1985" 通常不会返回结果（年份不会按 OR 逻辑匹配）——请拆分为 --author "Pratt" --year "1985"。
• CJK 作者姓名无论连写或带空格都能匹配：--author 余泳泽 和 --author "余 泳泽" 均可找到姓余、名泳泽的作者。

关键词语法——search 和 search-in 均使用 SQLite FTS5 和 porter 词干提取器，在繁体转简体的折叠索引上运行：

运算符	示例	说明
完整短语	"institutional change"	匹配相邻的词元。用引号括起多词短语。内部带标点的词（COVID-19、U.S.、Olson's）无需加引号，也会作为短语匹配。
AND（默认）	alpha beta	裸词元之间隐含 AND。
OR	Acemoglu OR Robinson	必须大写。小写 or 是字面词项，不是运算符。
NOT	alpha NOT beta	排除右侧表达式。大小写规则相同。没有 -beta 这种形式；词项前带 -（-beta、- beta、-(a OR b)）会返回 INVALID_ARGUMENT，孤立的 AND / OR / NOT 或只包含标点的查询也会如此。
邻近	"土地" NEAR/20 "开发"	在 N 个词元范围内匹配，顺序不限。请使用 NEAR/<n>，不要使用单独的 NEAR 或 NEAR(...)。
前缀通配符	Pete*	匹配所有以 Pete 开头的词元：Peter、Petersen 等。通配符只能放在末尾。

search 和 search-in 都会针对每个区块的全文搜索索引评估大多数查询。search-in 会返回目标文档中符合条件的区块，最多为 --limit 指定的数量；对于单个带引号的短语，还会执行一次清单级跨区块扫描。search 每个匹配项返回一行——某个项有多个已索引附件时，只会通过其中排名最佳的区块（依据所有附件中的 FTS5 bm25 评分）显示一次。search --limit 默认值为 10，上限为 100（更大的值会返回 INVALID_ARGUMENT）；请缩小查询范围，或使用 --tag / --collection-key 限定范围，而不要继续翻页。search --semantic 使用约 40 个候选文档的固定池，因此即使资料库中还有更多相关内容，返回行数也可能少于 --limit。

NEAR/<n> 是最适合优先尝试的方式，适用于你有 2–3 个应该共同出现、但不一定相邻的锚点词的情况，例如 "土地" NEAR/20 "利用"。与普通关键词相比，它通常更精准，也比 --semantic 快得多。

关键词搜索与语义搜索的经验法则：查找名称、锚点词、引文，或使用 --tag / --collection-key 限定范围时，先用关键词搜索（完整短语、OR、NEAR）；当措辞模糊或希望查找概念相近的内容时，再切换到 --semantic。--tag、--collection-key 和 --min-score 不能与 --semantic 组合使用；--semantic 与关键词搜索一样，会拒绝不含字母或数字的文本（INVALID_ARGUMENT）。语义搜索的 score 表示排名位置（1、0.5、0.33……），并非相关性数值，因此应通过段落判断语义搜索结果。对于 OCR 处理或扫描的资料（如民国时期的竖排文本、旧方志等），NEAR/<n> 尤其有用，因为单个关键词往往会淹没在噪声中。

中文繁简转换：关键词 search、search-in 和 metadata 均支持繁体 ↔ 简体双向匹配（汉字 ≡ 漢字），因此使用其中一种写法即可。未加引号的连续 CJK 字符串会按有序短语处理：会社 只匹配会社，不匹配社会；用空格分隔词语（国家 能力），即可要求它们在区块中的任意位置同时出现。关键词搜索也会对连字和全角形式进行折叠（NFKC），因此 exemplifies 可以找到 exemplifies，1949年 可以找到 １９４９年。search --semantic 不会进行折叠，因为它使用基于源文本的 qmd 嵌入。返回的文本（passage、blocks、fulltext、expand）会保留附件中存储的原始形式。

引用段落

默认使用转述，并采用返回的 itemKey 以 Pandoc 源格式引用。只有在措辞本身很重要时（如独特短语、原始来源引文或定义）才使用逐字引文——不加区分地引用会让文档变成逐字稿。

引用中不要写入 pageStart / pageEnd。它们是 PDF 文件中的位置，从 1 开始计数，并非论文或书籍上印刷的页码：印刷页码为 pp. 1360–1380 的期刊文章会返回 pages 1–21；书籍的前置页会使每一页的位置偏移（印刷页码 p. 96 可能返回为 pageStart: 98）。

• 转述：[@itemKey]
• 措辞至关重要时使用逐字短语：... a "non-trivial role" [@itemKey]
• 叙述式引用：@itemKey says ...

面向用户的文本中不要引用 charOffset 或块索引。charOffset 是传递给 expand 以获取更多上下文的参数；块索引会出现在 blocks 输出中，但 PDF/EPUB 阅读器无法通过这些索引定位。

不要编造引文。如果返回的 passage 看起来被截断（带有 … 标记）或有乱码（OCR 噪声、单词中间被截断），请调用 expand 获取干净的文本片段，再进行引用。

典型工作流

查找段落，然后检索周边上下文

# Library-wide search — keyword by default; --semantic for fuzzy/conceptual queries
zotagent search "party secretary governance"
zotagent search "informal political networks in contemporary China" --semantic --limit 20
zotagent search "local fiscal capacity" --tag "PhD Thesis"

# Scope by Zotero collection key (8-char ID at the end of the collection URL).
# Repeatable for union; combine with --tag for an intersection.
zotagent search "local fiscal capacity" --collection-key ABCD1234
zotagent search "land reform" --collection-key ABCD1234 --tag "PhD Thesis"

# Drill into one paper. A bare surname catches both in-text "Acemoglu and
# Robinson 2012" and bibliography "Acemoglu, Daron. 2012".
zotagent search-in 'Acemoglu' --key CMJ3N8TL

# Expand around a returned hit. `--offset` is the `charOffset` from a search
# result; `--radius` is the half-window in characters (default 1000). Increase
# the radius when the search passage looks truncated or you need more context.
zotagent expand --key KG326EEI --offset 18432 --radius 1500
zotagent fulltext --key KG326EEI --clean

查询论文元数据

# Search selected fields with a positional query
zotagent metadata "aging in China" --field title --field abstract

# Narrow by specific metadata fields
zotagent metadata --author "Pratt" --year "1985"

# Use a year prefix for a range; `--year 198` matches the 1980s
zotagent metadata --author "Pratt" --year "198"

# Combine a positional query with a filter
zotagent metadata "imperial" --author "Pratt"

# Narrow to manually tagged Zotero items
zotagent metadata --tag "PhD Thesis"
zotagent metadata "land reform" --tag "PhD Thesis"

# Narrow to a Zotero collection (or intersect a collection with a tag)
zotagent metadata --collection-key ABCD1234
zotagent metadata "land reform" --collection-key ABCD1234 --tag "PhD Thesis"

# Keep only indexed items; include abstract text only when needed
zotagent metadata "dangwei shuji" --indexed
zotagent metadata "aging in China" --abstract

# Use a returned key with retrieval commands
zotagent fulltext --key KG326EEI --clean
zotagent blocks --key KG326EEI --limit-blocks 40    # paginated structured view; rarely needed

将论文添加到 Zotero

添加时的来源优先级：DOI → --doi（可使用裸 DOI、doi:10.… 或 doi.org 链接；arXiv ID 可用作 --doi 10.48550/arXiv.<id>；PMID 可在 PubMed 上解析为 DOI）；CNKI 或其他已提取的元数据 → --json；网页 → 在页面上查找 DOI（引用区块、元标签），并使用 --doi，否则自行提取元数据并填入 --json 或手动字段；ISBN → 使用 Open Library / Google Books 的元数据填入 --json 或手动字段，并指定 --item-type book；完全没有 DOI 的论文 → 使用 s2 搜索，然后执行 add --s2-paper-id。

# Add by DOI (arXiv IDs have a DOI form)
zotagent add --doi "10.1111/dech.70058"
zotagent add --doi "10.48550/arXiv.2406.01234"

# Search Semantic Scholar, then add by paperId
zotagent s2 "state-owned enterprise governance" --limit 5
zotagent add --s2-paper-id <paperId>

# --s2-paper-id also takes a DOI, an arXiv id, or a prefixed identifier
zotagent add --s2-paper-id "10.1093/ajae/aaq063"
zotagent add --s2-paper-id "ARXIV:2106.15928"

# Manual fallback — authors go in Zotero "Last, First" form; repeat --author for multiple
zotagent add --title "Title of a paper" --author "Zhang, San" --year 2026 --publication "Journal of Important Studies"

# Add a book — pass --item-type, otherwise manual adds default to journalArticle
# (URL-only manual adds become webpage)
zotagent add --title "Fifty Years of Land Reform" --author "Hsiao, Cheng" --year 1980 --publication "China Land Policy Institute" --item-type book

# Add from pre-shaped JSON (best for CNKI)
zotagent add --json paper.json
zotagent add --json batch.json --collection-key COLL1234
your-extractor | zotagent add --json -

# Attach a local PDF as a linkMode=linked_file child (file stays on disk;
# no Zotero storage quota used). When the path is under attachmentsRoot,
# zotagent stores it as 'attachments:<rel>' for cross-device portability.
zotagent add --title "Paper" --author "Doe, Jane" --attach-file ~/Downloads/foo.pdf
# In --json mode, each item carries its own attachFile / attach-file field.
echo '{"itemType":"journalArticle","title":"...","attachFile":"/path/to/foo.pdf"}' | zotagent add --json -

与 --doi 一起提供的手动标志（--title、--author、--year、--publication、--item-type）会覆盖 DOI 记录中的字段；--title 还兼作后备项：如果 DOI 查询失败，或 Zotero 拒绝该 DOI 记录，则会根据手动字段创建条目，并在 data.warnings 中说明原因。如果未提供 --title，DOI 查询失败时命令也会失败。

add --json 的输入字段——只有 title 是必填项：itemType（默认为 journalArticle）；authors 可为字符串（"Last, First" 或 "First Last"；"李华" 这样的单个词元会保留为一个姓名），也可为符合 Zotero 格式的 creators；date 或 year（可使用数字）；publicationTitle / publication / journal（会根据条目类型转入 bookTitle、proceedingsTitle 等字段）；abstract；doi；字符串形式的 keywords 或 tags；url；accessDate；collections（单个键或键数组）；attachFile。任何其他 Zotero 字段名（volume、issue、pages、publisher、place、ISBN、language、extra 等）都会直接传递；如果该条目类型没有相应字段，则会静默丢弃。完整的别名表见 README。

add --json 始终将 data 作为数组返回，即使输入只有一个对象也是如此。单条目失败会在对应位置返回 {ok: false, error: ...}，不会中止批次中的其余条目；解析、配置或空输入错误会导致整个响应失败。单条目错误代码：INVALID_ITEM_TYPE — Zotero 不识别该 itemType；修正类型后，只重新发送该条目。INVALID_ATTACH_FILE — 条目的附件路径无效（见下文）。JSON_ITEM_FAILED — 其他错误（网络、超时、速率限制、Zotero 错误）；错误消息会说明具体原因，若属暂时性问题，之后重试该条目一次即可。 当创建了附件时，会设置 AddResult.attachmentItemKey。不正确的 --attach-file 路径会在写入父条目之前失败，因此不会在 Zotero 中留下孤立的引用（单条目失败代码：INVALID_ATTACH_FILE）。如果父条目创建成功，但附件 POST 失败，仍会返回父条目的 itemKey，并将失败作为警告提示。上文未列出的其他 add 标志：--url, --url-date（别名 --access-date）、--collection-key。

如果有可用的 openAccessPdfUrl，s2 结果会包含该字段——将它作为免费 PDF 链接与 add 建议一起展示给用户。

S2 速率限制：每秒 1 个请求，在 Semantic Scholar 各端点之间累计计算（s2、s2-refs、s2-citations、add --s2-paper-id）。请依次运行，绝不要并行运行——并行调用会触发 429。zotagent 会自行重试 429（最多重试 2 次，遵循 Retry-After，每次等待最多 10 秒），因此偶尔发生的冲突可以自行化解；如果重试次数用尽，命令会以 RATE_LIMITED 失败，此时应放慢速度，而不是加大重试力度。不同工具调用之间通常留出间隔就足够了，无需休眠。所有这四个命令都需要在配置中设置 semanticScholarApiKey；未设置时会以 SEMANTIC_SCHOLAR_NOT_CONFIGURED 失败——这是配置问题，绝不值得重试。Semantic Scholar 不认识的标识符会以 PAPER_NOT_FOUND 失败：请检查标识符，或通过标题运行 s2 "<title>" 查找论文，并传入返回的 paperId——重试相同的 ID 没有帮助。

add --from-url / add --identifier 确实存在，但默认假定使用可自托管的 Zotero 翻译服务，而该服务通常未配置——预期会出现 TRANSLATION_SERVER_NOT_CONFIGURED，此时应按上述来源优先级改用其他方式，而不是重试。仅在翻译服务实际运行时才设置 translationServerUrl（已配置但未运行时，--doi 也会失败）；服务模式的详情见 README。

探索论文的参考文献和引用

在文献综述中，引用链是最有力的发现信号：s2-refs 返回一篇作品引用的论文（即其参考文献列表，沿时间向后追溯），s2-citations 则返回引用该作品的论文（沿时间向前追溯）。

# Backward: what does this paper build on?
zotagent s2-refs "10.18653/v1/N18-1022" --limit 20

# Forward: who has cited it since?
zotagent s2-citations "DOI:10.18653/v1/N18-1022" --limit 20

# Page through a long bibliography — data.next is the offset for the next call
zotagent s2-refs 649def34f8be52c8b66281af98ae884c09aef38b --limit 50 --offset 50

# Quote URLs so the shell does not eat the ? and &
zotagent s2-refs "https://arxiv.org/abs/2106.15928" --limit 10

两者都只接受一个标识符，绝不接受标题：40 个字符的 paperId、DOI、arXiv ID、带前缀的 ID（DOI:、ARXIV:、PMID:、CorpusId:、URL:），或 doi.org / arxiv.org / semanticscholar.org URL。如果只知道论文标题，请先运行 s2 "<title>"，并传入返回的 paperId。无效标识符会在本地以 INVALID_ARGUMENT 失败，不会消耗请求。

当 Semantic Scholar 将某条引用边标记为有影响力时，行中会带有 isInfluential: true——这是长篇参考文献列表中很有用的排序参考。行中有意省略摘要；如需阅读摘要，请将该行的 paperId 传给 add --s2-paper-id（该命令会获取完整记录），或使用 metadata 在文献库中查找论文。Semantic Scholar 没有记录的条目会被排除，并在 data.warnings 中报告。

results 为空且 ok: true 表示查询结果确实为空，并非失败：某些出版商不向 Semantic Scholar 提供参考文献列表，因此对这类论文运行 s2-refs 不会返回结果，但运行 s2-citations 仍然有效。不要重试——请尝试另一个方向，或为同一作品换用其他标识符。

列出最近添加或修改的条目

# Most recent 10 additions (default)
zotagent recent

# Top 20 most recently modified items
zotagent recent --limit 20 --sort modified

recent 直接访问 Zotero Web API（无需索引），因此通过 add 刚创建的条目会立即显示——可用于确认 add 已成功写入，也可用于快速了解文献库内容。仅返回常规的顶层书目条目；独立笔记和附件会跳过。--limit 最大值为 100。

检查或修复本地索引

切勿在用户未明确要求时运行 sync。 你正在使用的设备可能并未保存完整的附件集（例如，attachmentsRoot 中的 PDF 仍是云端占位文件或正在下载）：从不完整的副本进行同步会重写共享索引／数据文件，并可能在这些文件同步到其他设备时将其损坏。是否刷新陈旧索引由用户决定，而不是由你决定。

# Counts, paths, and qmd status
zotagent status

# Rebuild / refresh local full-text indexes
zotagent sync

# Retry unchanged files that previously failed extraction
zotagent sync --retry-errors

# Tune heavy PDF extraction on large libraries
zotagent sync --pdf-concurrency 1 --pdf-batch-size 4 --pdf-timeout-ms 900000

# Surface suspicious extraction output before quoting heavily from a corpus
zotagent diagnose --limit 20

同步排除项由 Zotero 标签控制，而不是本地文件：在 Zotero 中为顶层条目添加 zotagent:exclude 标签，下一次 sync 就会完全跳过该条目（不提取、不建立索引），并将其从本地索引中移除。可通过 ~/.zotagent/config.json 中的 excludeTag 或环境变量 ZOTAGENT_EXCLUDE_TAG 更改标签名；要处理带标签的条目，需要配置 Zotero 读取 API（zoteroLibraryId + zoteroApiKey）。使用 diagnose 查找候选项，例如 OCR 失败的扫描件、竖排 CJK PDF 或多栏地名录，然后在重新同步前为其添加标签或重新进行 OCR。

三种同步拒绝情况会在触及任何内容前停止；请告知用户，不要尝试绕过。SYNC_DISABLED：此主机已配置为只读（syncEnabled: false），因为它与另一台负责维护索引的机器共享索引，或者其设置包含无法读取的值（消息会指出该值）——切勿更改设置来绕过此限制。ZOTERO_TAG_LOOKUP_FAILED：已配置的 Zotero API 无法列出带标签的条目，且此前没有成功的查询保存过可供回退的列表（成功查询一次后，sync 可根据已保存的列表离线运行）——请等 API 恢复可用后重试；切勿删除 Zotero 凭据来绕过此限制，因为这样会以错误的阅读顺序重新提取所有竖排文本 PDF。MASS_REMOVAL_REFUSED：书目中未解析出任何附件，或索引条目减少超过 10%（且至少减少 50 项）——通常是书目导出被截断或 attachmentsRoot 配置错误；如果确实要执行删除，消息会说明后续步骤。

输出格式易错点

• passage 是以命中位置为中心的紧凑字符窗口，上限约为 500 个 token。开头或结尾的 … 表示返回片段之外还有文本，或已达到 token 上限；调用 expand --key <k> --offset <charOffset>（并设置更大的 --radius）可获取更长的片段。
• charOffset 是条目级偏移量，不是附件级偏移量。 当一个条目包含多个已建立索引的附件时，偏移量会在合并后的 Markdown 中依次递增，各附件之间以 # Attachment: <name> 分隔。将任一搜索结果中的 charOffset 直接传给 expand。
• --key 接受 itemKey 或 citationKey，可带或不带前导 @（因此可以直接粘贴 Pandoc 的 @citekey）。输出始终只通过 itemKey 标识条目——虽然可输入 citationKey，但不会在输出中显示，因此后续调用请使用 itemKey。
• 对章节键使用 search-in 可能无法找到结果。 SEARCH_IN_FAILED: No indexed attachment found 通常表示该章节的 PDF 仅在其父卷中建立了索引。使用 metadata 查找父卷，然后针对父卷的键运行 search-in，并通过标题定位章节。这在编著文集和论文集中很常见。
• search-in 返回范围限定的匹配项；search 为每个条目返回一个片段。 大多数 search-in 行是单个区块的 FTS 匹配；借助清单级精确扫描，单个带引号的短语也可能跨越多个区块。search 结果表示此文档匹配，并提供一个代表性片段。当用户问“这篇论文是否提到 X”或“这篇论文的什么位置出现了 Y”时，应使用 search-in。
• search-in --limit 限制返回的匹配区块数。 默认值 10 通常足够——搜索范围已限定为一份文档。要查看更多排名较低的匹配项，可增大该值；如果返回的区块与用户意图不符，则更改查询内容。

索引新鲜度

search / search-in / blocks / expand / fulltext 会读取本地索引。INDEX_EMPTY 表示索引中没有文档：将消息中的建议转告用户——消息会说明应运行 sync，还是从负责同步的主机复制索引——不要自行运行 sync。如果 search / search-in 提示关键词索引“由不同版本的 zotagent 构建”，将警告中的建议转告用户——运行 sync 会重建索引；如果主机禁用了同步，则应确保各主机上的 zotagent 版本一致（在此之前，搜索结果可能会漏掉匹配项）——不要自行运行 sync。--semantic 返回 SEMANTIC_INDEX_MISMATCH，表示此主机的嵌入模型计算出的向量与索引中的向量不同，因此语义搜索结果会是随机的：告知用户（消息会指出需要修复哪台主机），然后改用关键词搜索。使用 --tag / --collection-key 时，如果警告说匹配项“在此处没有可搜索文本”，消息会说明每组条目的原因：被标签排除、提取失败、文件缺失、类型不受支持，或不在本地索引中。只有最后一组可以通过同步解决。metadata / add / s2 / s2-refs / s2-citations / recent 无需本地索引也能运行（此时 metadata 会报告所有条目的 indexed: false，并警告索引目录为空）。运行 add 后，新论文在下次 sync 之前无法进行全文搜索。

编辑 Zotero，以及 CLI 不会返回的字段

zotagent 会读取本地索引和本地书目导出文件，唯一的写入操作是通过 add 创建条目。如需获取某个条目的完整字段集（DOI、卷号、页码、URL、标签、收藏集、日期）、收藏集键和标签列表，或进行任何编辑——更改字段、添加或移除标签、归入收藏集、附加笔记、将条目移入废纸篓——请直接调用 Zotero API。首次进行此类调用前，请阅读 references/zotero-web-api.md：其中介绍了凭据处理、可防止编辑覆盖未发送字段的读取-修改-写入规则，以及删除操作的确认关卡。

如果需要此处未涵盖的命令或标志，请运行 zotagent help。