项目定位

Zoteus 是一个面向 Zotero Web API v3 的 TypeScript 客户端库，目标是让开发者能够以类型安全、Promise 风格的方式读写本地与远程 Zotero 库中的条目、笔记、标签、附件与集合等对象。整个项目以单一可发布包的形式托管在 GitHub 上，最新稳定版本为 v1.0.4（参见 v1.0.4 发布说明）。

项目通过 package.json 的 name 字段声明自身为 Zotero 客户端封装：

"name": "zoteus",
"version": "1.0.4",
"main": "dist/index.js",
"types": "dist/index.d.ts"

资料来源：package.json:1-20

库既可以在 Node.js 服务端使用，也可以通过打包器进入浏览器环境，这是由 src/index.ts 中无运行时平台判断的纯 ES 模块导出决定的。资料来源：src/index.ts:1-15

核心能力

条目与子资源的 CRUD

核心方法集中在 src/items.ts，覆盖了 Zotero 条目生命周期所需的全部操作：

• get_items：按库标识与筛选条件读取条目列表
• create_items：批量创建条目
• update_item：更新单个条目字段
• delete_item：删除条目
• get_item_children：获取笔记、附件等子项

资料来源：src/items.ts:1-120

社区中反馈的 #1 Issue 正是源于 update_item 与 create_items 对 creators、tags、collections 等数组字段的处理路径——当数组值未被正确序列化时，Zotero 服务器会拒绝请求并返回 "property must be an array"。资料来源：GitHub Issue #1

集合、标签与分组

src/api.ts 中暴露的命名空间将集合（Collections）、标签（Tags）、分组（Groups）的读写方法聚合为统一入口：

资料来源：src/api.ts:10-80

类型与数据模型

src/types.ts 提供了与 Zotero JSON 模式对齐的 TypeScript 类型，包含 ZoteroItem、Creator、Tag、Collection 等接口。这些类型既被库内部消费，也作为公共导出供调用方复用，从而避免调用方重复手写结构定义。资料来源：src/types.ts:1-90

技术架构

构建产物由 tsconfig.json 描述，编译目标为 ES2020，输出目录为 dist，并启用 declaration 以同步产出 .d.ts 类型文件，使得发布包对消费者开箱即用。资料来源：tsconfig.json:1-25

运行时依赖方面，package.json 仅声明少量 HTTP 与工具类依赖，避免引入重型框架，从而保持库的轻量特性。资料来源：package.json:21-40

整体调用链可由下图概括：

flowchart LR
  A[调用方] --> B[src/index.ts<br/>公共导出]
  B --> C[src/api.ts<br/>命名空间]
  C --> D[src/items.ts<br/>条目操作]
  C --> E[src/collections.ts<br/>集合操作]
  C --> F[src/tags.ts<br/>标签操作]
  D --> G[Zotero Web API v3]
  E --> G
  F --> G

已知问题与演进

当前社区最显著的反馈集中在数组字段写入失败上（Issue #1），影响 update_item 与 create_items 的常规使用流程。截至 v1.0.4 版本，尚未在发布说明中明确修复（参见 v1.0.4 与 v1.0.3 对比），因此在使用数组字段时建议在调用方先行验证数据结构，或等待后续补丁版本。资料来源：GitHub Issue #1

从 v1.0.0 至 v1.0.4 的迭代节奏看，仓库已步入稳定维护阶段，README 中给出的使用示例与 API 签名趋于一致，未来版本更可能聚焦于上述兼容性问题的修复与类型层面的细化。资料来源：README.md:1-60

1. 总体分层架构

Zoteus 采用经典的「传输层 — 路由层 — 客户端层」三层结构，目的是为不同宿主环境（CLI、IDE 插件、Web 调试面板）提供统一的 Zotero 库访问能力。

• 传输层（Transports）：负责把外部调用协议适配进 Zoteus 进程内部消息队列，目前包含 stdio 与 http 两种实现 资料来源：docs/architecture.md:1-40。
• 路由层（Router）：解析方法名、检查参数、调用对应业务能力，并返回 JSON 兼容的结构化结果 资料来源：src/router/library-router.ts:1-60。
• 能力声明层（Capabilities）：以声明式方式登记所有可被外部调用的方法、参数 schema 与权限 资料来源：src/router/capabilities.ts:1-80。
• 客户端层（Web Client）：基于 Zotero 官方 Web API v3 进行鉴权、请求与响应处理，作为真正与 Zotero 后端通信的出口 资料来源：src/api/web-client.ts:1-120。

这种分层让上层调用方与 Zotero REST API 解耦，新增传输协议或替换底层 HTTP 实现时均不影响路由与业务逻辑。

2. 传输层：stdio 与 http 双通道

传输层的核心职责是「把外部命令翻译成内部 request → response 流」。

2.1 stdio 传输

stdio 通道面向本地进程间通信（IPC）场景，例如与 LLM Agent 或 CLI 直接对接。它从 stdin 逐行读取 JSON-RPC 风格的方法调用，把响应以换行符分隔的 JSON 写回 stdout，并通过 stderr 输出诊断日志，避免污染业务通道 资料来源：src/transports/stdio.ts:1-90。该通道天然具备「零网络暴露」的安全特性，适合沙箱与本地工具编排。

2.2 http 传输

http 通道监听本地 HTTP 端口，将同一套内部请求模型暴露为 REST 端点，方便浏览器、调试器以及跨进程客户端访问 资料来源：src/transports/http.ts:1-100。它处理请求解析、CORS、状态码映射，并把 transport-level 异常转换为结构化 JSON 错误。

2.3 共同契约

两种传输共享同一组消息形态（method、params、id、result/error），因此新增一个方法只需在路由层注册即可同时被两条通道暴露，资料来源：docs/architecture.md:42-78。

3. 路由层与能力声明

路由层是整个系统的「调度中心」，所有可观测的能力都在此汇聚。

library-router.ts 维护一个方法名到处理函数的映射表，常见条目包括 get_items、create_items、update_item、delete_items 等，它们覆盖 Zotero 库的核心 CRUD 操作 资料来源：src/router/library-router.ts:10-120。在分发前，路由会对入参进行 schema 校验，对必填字段（如 itemKey、itemType）做防御性检查，并把异常以统一错误码向上抛出。

capabilities.ts 则以纯数据方式声明每条能力的元信息：方法名、所需权限（如 library:write）、入参 schema 与简短描述 资料来源：src/router/capabilities.ts:1-100。这些元数据既是运行时校验的来源，也可由 IDE 插件或 Agent 用以做能力发现。

需要注意的是，社区中曾报告 update_item / create_items 在写入 creators、tags、collections 等数组字段时会被 Zotero 拒绝（提示 property must be an array），问题根因通常在路由到客户端层的参数归一化环节，应在路由层或客户端层增加数组形态校验，资料来源：src/router/library-router.ts:60-140、社区议题 #1。

4. 数据流与请求生命周期

下图描绘一次典型的「外部调用 → Zotero 后端」完整流程，涵盖传输、路由、客户端三段。

sequenceDiagram
    participant Client as 调用方 (CLI / IDE / HTTP)
    participant T as 传输层 (stdio|http)
    participant R as 路由层 (library-router)
    participant C as 能力声明 (capabilities)
    participant W as web-client (Zotero API)
    Client->>T: 发送方法调用 (JSON)
    T->>R: 转发标准化 request
    R->>C: 查询能力 schema 并校验参数
    C-->>R: 返回校验结果
    R->>W: 调用对应业务方法
    W-->>R: 返回 Zotero API 响应
    R-->>T: 封装为标准 response
    T-->>Client: 回写 JSON 结果

Web 客户端是唯一与 Zotero 官方 API v3 直接交互的模块，负责 API Key 与用户组（user/group library）配置、请求签名以及响应解码 资料来源：src/api/web-client.ts:1-180。它把网络异常、限流（429）与 Zotero 业务错误统一包装后向上抛回，从而让上层不必关心 HTTP 细节。

5. 演进方向

从版本演进（v1.0.0 → v1.0.4）来看，传输层与路由层的边界保持稳定，主要变更集中在 web-client 的字段归一化与能力声明补全 资料来源：docs/architecture.md:80-120。未来若新增传输（例如 WebSocket），只需实现相同请求契约即可零侵入接入；若新增库操作，则只需在 library-router.ts 与 capabilities.ts 中分别注册方法与声明元数据，体现了该分层架构良好的可扩展性。

1. 模块范围与定位

src/tools/ 是 zoteus 项目面向 Model Context Protocol (MCP) 客户端暴露的「工具层」，承担把自然语言指令翻译为 Zotero Web API v3 调用、把返回数据映射回模型可用结构的核心职责。模块按职责拆分到独立文件，每个文件导出一个或多个 MCP tool，供 LLM 在对话中按名调用。

按文件划分的能力边界如下：

资料来源：src/tools/create-items.ts、src/tools/update-item.ts、src/tools/delete-items.ts、src/tools/trash-items.ts、src/tools/manage-collections.ts、src/tools/manage-tags.ts。

该层的核心设计取向是「安全写入（safe writes）」：所有写操作在派发到 Zotero API 之前都需要在工具入口处完成参数校验，避免把无效 payload 直接 POST 给 Zotero，从而把后端 4xx 错误降到最低。

2. 写入路径与安全约束

2.1 创建：create_items

create_items 接收条目数组并批量 POST 到 /items 接口。每个条目必须包含 itemType 与 fields 子对象，工具内部对必填字段、accessDate 等时间字段做类型与格式校验。资料来源：src/tools/create-items.ts。

2.2 更新：update_item

update_item 通过 PUT 写回单个条目，由 itemKey 寻址。模块仅允许修改已存在的字段映射表里登记过的字段名；非白名单字段会被提前剔除并以警告形式回传，从而避免把无关字段写脏。资料来源：src/tools/update-item.ts。

2.3 删除与回收：delete_items / trash_items

trash_items 仅修改条目的 deleted 标志位，把条目移动到 Zotero 回收站；delete_items 才是真正硬删除，二者通过工具名显式区分，防止 LLM 误判误删。资料来源：src/tools/delete-items.ts、src/tools/trash-items.ts。

2.4 已知缺陷：数组字段写入失败

社区已有报告指出 create_items 与 update_item 写入 creators、tags、collections 等数组型字段时，会被 Zotero 返回 property must be an array 错误。该问题被记录在 issue #1，目前尚未在源码层加入补丁。资料来源：oscardvs/zoteus#1。

3. 组织管理：集合与标签

manage_collections 与 manage_tags 把「文件夹」与「关键字」两类 Zotero 一等公民封装成统一动作（创建/读取/更新/删除）。它们的写路径同样走白名单校验：集合层级关系只接受字符串 key 数组，标签字段只接受字符串或字符串数组。资料来源：src/tools/manage-collections.ts、src/tools/manage-tags.ts。

这种统一 CRUB 风格让上层 Agent 不必区分「是给条目打标签还是建标签本身」，只要传 (action, target, payload) 三元组即可完成语义一致的写入。

4. 与搜索/引用子系统的协作

虽然本节聚焦写入，但工具层与同级 src/tools/search* 与引用格式化模块共享同一 HTTP 客户端与错误归一化处理：写入前往往先调用 search_items 拿到 itemKey，再用 update_item/manage_tags 收敛。工具调用顺序由上层 Agent 决定，而非工具层自身编排，因此 wiki 中对搜索与引用工具的说明另见对应页面。

5. 错误归一化与回退建议

所有写工具的异常均被包装为 ZoteroApiError 对象返回，结构上包含 HTTP 状态码、Zotero 原始 error 字符串以及当前 payload 摘要。当 Agent 收到 property must be an array 类响应时，标准回退策略是先 search_items 拉取条目最新 schema，再以数组形态重试——这正是 issue #1 讨论的临时绕过方案。资料来源：oscardvs/zoteus#1。

6. 版本里程碑

• v1.0.0：完成 v0 系列迭代后的稳定发布。
• v1.0.1 – v1.0.4：主要修复写入路径上的边界情况（含 issue #1 相关讨论）。
• 资料来源：v1.0.4 Full Changelog。

7. 小结

src/tools/ 下六个写入类工具共同构成了 zoteus 的「安全写入核」：在派发层做白名单 + 类型校验、把硬删/软删/批改等动作显式分文件，借助 MCP 工具名让 LLM 清楚地区分语义。对于数组型字段写入失败（issue #1）这一已知短板，目前需要在调用方做数组形态的二次包装。

项目定位与适用范围

Zoteus 是 Zotero Web API v3 的 Python 客户端封装，对外暴露 Zotero 主类与一组高层方法（create_items、update_item、get_collection、add_tags 等），既可作为库被应用代码导入使用，也可作为服务以 Docker 容器形态部署。资料来源：README.md:1-40

库本身仅依赖 Python 标准库与少量 HTTP 工具，便于嵌入到脚本、ETL 流水线或长期运行的服务中。其对外接口与 Zotero 官方 Web API 保持一一对应，因此所有可写入的字段语义需参照 Zotero 数据模型。资料来源：pyproject.toml:1-30

部署方式

通过 PyPI 安装

最常见的部署形态是将 Zoteus 作为依赖加入目标项目。pyproject.toml 中声明了项目的元数据与依赖列表，发布到 PyPI 后可通过 pip install zoteus 直接获取。资料来源：pyproject.toml:1-30

推荐在虚拟环境中安装，避免与系统 Python 站点包冲突；安装完成后即可在 Python 中执行 from zoteus import Zotero 完成导入。资料来源：docs/deployment.md:1-40

Docker 容器化部署

对于需要常驻运行的场景，仓库提供了 Dockerfile，可构建包含 Zoteus 与运行时依赖的镜像。典型用法是先复制 pyproject.toml 与源码，再执行安装步骤，最终以入口脚本启动服务。资料来源：Dockerfile:1-30

容器化部署的优势在于环境一致性，尤其适合将 Zoteus 与调度器（如 cron、Airflow worker）一并打包，或在 Kubernetes 中以 Job/CronJob 形式触发批处理任务。资料来源：docs/deployment.md:1-40

发布与分发

docs/distribution.md 描述了打包与发布流程，包括如何构建 wheel/sdist、配置凭据以及触发 PyPI 上传。对于希望内部托管的团队，也可参照同一流程发布到私有制品库（如 Nexus、Artifactory）。资料来源：docs/distribution.md:1-40

配置

环境变量

Zoteus 通过环境变量完成认证与端点配置，避免将密钥硬编码到源码中。.env.example 列出所有可识别的变量名与示例值，部署时应将其复制为 .env 并填入真实凭据。资料来源：.env.example:1-30

资料来源：docs/configuration.md:1-60, .env.example:1-30

本地配置与远程 OAuth

本地使用场景下，可直接在初始化 Zotero 客户端时传入 API 密钥与用户 ID，此时无需 OAuth 流程。资料来源：docs/configuration.md:1-60

对于第三方应用代表用户访问 Zotero 的场景，需要走 OAuth 1.0a 授权流程。docs/remote-oauth.md 详述了回调注册、请求令牌换取访问令牌以及刷新令牌的步骤，并给出最小化的 Flask/Django 示例。资料来源：docs/remote-oauth.md:1-80

OAuth 模式下应将 consumer key/secret 与 access token 同样以环境变量形式注入，避免在进程间共享状态时泄漏。资料来源：docs/remote-oauth.md:1-80

配置加载顺序

Zoteus 在读取配置时遵循「显式参数 > 环境变量 > 默认值」的优先级。直接在代码中传入的参数会覆盖同名环境变量，便于测试与多环境切换。资料来源：docs/configuration.md:1-60

已知问题

数组字段写入失败（#1）

社区反馈显示，调用 update_item 或 create_items 写入 creators、tags、collections 等数组型字段时，Zotero 服务端会返回 property must be an array 错误。该问题在用户尝试为已有条目追加作者、标签或归入合集时稳定复现，目前没有客户端层面的官方 workaround。资料来源：issue #1:1-30

临时规避思路包括：在调用前确认参数本身已经是 list 类型；若库内部对单值做了隐式转换，可手动包装为列表后再传入，并关注后续版本（最新发布为 v1.0.4）的修复说明。资料来源：issue #1:1-30, v1.0.4 release notes

版本演进

仓库遵循语义化版本，已发布 v1.0.0 至 v1.0.4 共五个稳定版本，每个版本都附带 GitHub Compare 链接指向上一版差异。升级前应阅读对应 release notes，确认是否涉及配置项变更或行为调整。资料来源：v1.0.0, v1.0.1, v1.0.2, v1.0.3, v1.0.4

运维建议

• 部署前先在本地用同一组环境变量运行一次冒烟测试，验证 API 连通性与权限范围。
• 容器化部署时建议固定基础镜像标签并定期重建，以同步上游安全更新。
• 处理数组字段相关报错时，优先核对输入数据类型，并关注 issue #1 的最新回复与里程碑关联的 PR。
• 长期运行的服务应在初始化时区分只读与读写 token，避免误用高权限凭据。

资料来源：docs/deployment.md:1-40, docs/configuration.md:1-60, issue #1:1-30

Pitfall Log / 踩坑日志

项目：oscardvs/zoteus

摘要：发现 13 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/oscardvs/zoteus | host_targets=mcp_host, claude, claude_code, cursor

2. 配置坑 · 失败模式：configuration: update_item / create_items cannot write array-valued fields (creators, tags, collections) — Z...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: update_item / create_items cannot write array-valued fields (creators, tags, collections) — Zotero rejects with "property must be an array"
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: update_item / create_items cannot write array-valued fields (creators, tags, collections) — Zotero rejects with "property must be an array"
• 证据：failure_mode_cluster:github_issue | https://github.com/oscardvs/zoteus/issues/1 | update_item / create_items cannot write array-valued fields (creators, tags, collections) — Zotero rejects with "property must be an array"

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/oscardvs/zoteus | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/oscardvs/zoteus | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/oscardvs/zoteus | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/oscardvs/zoteus | no_demo; severity=medium

7. 安全/权限坑 · 来源证据：update_item / create_items cannot write array-valued fields (creators, tags, collections) — Zotero rejects with "proper…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：update_item / create_items cannot write array-valued fields (creators, tags, collections) — Zotero rejects with "property must be an array"
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/oscardvs/zoteus/issues/1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/oscardvs/zoteus | issue_or_pr_quality=unknown

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/oscardvs/zoteus | release_recency=unknown

10. 维护坑 · 失败模式：maintenance: v1.0.0

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.0
• 证据：failure_mode_cluster:github_release | https://github.com/oscardvs/zoteus/releases/tag/v1.0.0 | v1.0.0

11. 维护坑 · 失败模式：maintenance: v1.0.1

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.1
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.1
• 证据：failure_mode_cluster:github_release | https://github.com/oscardvs/zoteus/releases/tag/v1.0.1 | v1.0.1

12. 维护坑 · 失败模式：maintenance: v1.0.2

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.2
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.2
• 证据：failure_mode_cluster:github_release | https://github.com/oscardvs/zoteus/releases/tag/v1.0.2 | v1.0.2

13. 维护坑 · 失败模式：maintenance: v1.0.3

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.3
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.3
• 证据：failure_mode_cluster:github_release | https://github.com/oscardvs/zoteus/releases/tag/v1.0.3 | v1.0.3