# https://github.com/oscardvs/zoteus 项目说明书

生成时间：2026-07-20 19:06:24 UTC

## 目录

- [项目概述与核心特性](#page-1)
- [系统架构与传输层](#page-2)
- [工具、安全写入、搜索与引用](#page-3)
- [部署、配置与已知问题](#page-4)

<a id='page-1'></a>

## 项目概述与核心特性

### 相关页面

相关主题：[系统架构与传输层](#page-2), [工具、安全写入、搜索与引用](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/oscardvs/zoteus/blob/main/README.md)
- [package.json](https://github.com/oscardvs/zoteus/blob/main/package.json)
- [src/index.ts](https://github.com/oscardvs/zoteus/blob/main/src/index.ts)
- [src/api.ts](https://github.com/oscardvs/zoteus/blob/main/src/api.ts)
- [src/items.ts](https://github.com/oscardvs/zoteus/blob/main/src/items.ts)
- [src/types.ts](https://github.com/oscardvs/zoteus/blob/main/src/types.ts)
- [tsconfig.json](https://github.com/oscardvs/zoteus/blob/main/tsconfig.json)
</details>

# 项目概述与核心特性

## 项目定位

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

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

```json
"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](https://github.com/oscardvs/zoteus/issues/1)

### 集合、标签与分组

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

| 命名空间 | 关键方法 | 用途 |
| --- | --- | --- |
| `items` | `get_items`、`update_item` | 条目级操作 |
| `collections` | `get_collections`、`create_collection` | 分类层级管理 |
| `tags` | `get_tags`、`add_tags` | 标签维护 |
| `groups` | `get_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]()

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

```mermaid
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 对比](https://github.com/oscardvs/zoteus/compare/v1.0.3...v1.0.4)），因此在使用数组字段时建议在调用方先行验证数据结构，或等待后续补丁版本。资料来源：[GitHub Issue #1](https://github.com/oscardvs/zoteus/issues/1)

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

---

<a id='page-2'></a>

## 系统架构与传输层

### 相关页面

相关主题：[项目概述与核心特性](#page-1), [部署、配置与已知问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/architecture.md](https://github.com/oscardvs/zoteus/blob/main/docs/architecture.md)
- [src/transports/stdio.ts](https://github.com/oscardvs/zoteus/blob/main/src/transports/stdio.ts)
- [src/transports/http.ts](https://github.com/oscardvs/zoteus/blob/main/src/transports/http.ts)
- [src/router/library-router.ts](https://github.com/oscardvs/zoteus/blob/main/src/router/library-router.ts)
- [src/router/capabilities.ts](https://github.com/oscardvs/zoteus/blob/main/src/router/capabilities.ts)
- [src/api/web-client.ts](https://github.com/oscardvs/zoteus/blob/main/src/api/web-client.ts)
</details>

# 系统架构与传输层

## 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 后端」完整流程，涵盖传输、路由、客户端三段。

```mermaid
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` 中分别注册方法与声明元数据，体现了该分层架构良好的可扩展性。

---

<a id='page-3'></a>

## 工具、安全写入、搜索与引用

### 相关页面

相关主题：[项目概述与核心特性](#page-1), [部署、配置与已知问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/tools/create-items.ts](https://github.com/oscardvs/zoteus/blob/main/src/tools/create-items.ts)
- [src/tools/update-item.ts](https://github.com/oscardvs/zoteus/blob/main/src/tools/update-item.ts)
- [src/tools/delete-items.ts](https://github.com/oscardvs/zoteus/blob/main/src/tools/delete-items.ts)
- [src/tools/trash-items.ts](https://github.com/oscardvs/zoteus/blob/main/src/tools/trash-items.ts)
- [src/tools/manage-collections.ts](https://github.com/oscardvs/zoteus/blob/main/src/tools/manage-collections.ts)
- [src/tools/manage-tags.ts](https://github.com/oscardvs/zoteus/blob/main/src/tools/manage-tags.ts)
</details>

# 工具、安全写入、搜索与引用

## 1. 模块范围与定位

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

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

| 文件 | MCP 工具名 | 写入/读取性质 |
|---|---|---|
| `create-items.ts` | `create_items` | 写入 |
| `update-item.ts` | `update_item` | 写入 |
| `delete-items.ts` | `delete_items` | 写入（硬删） |
| `trash-items.ts` | `trash_items` | 写入（软删/回收站） |
| `manage-collections.ts` | `manage_collections` | 写入 |
| `manage-tags.ts` | `manage_tags` | 写入 |

资料来源：[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](https://github.com/oscardvs/zoteus/issues/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](https://github.com/oscardvs/zoteus/issues/1)。

## 6. 版本里程碑

- v1.0.0：完成 v0 系列迭代后的稳定发布。
- v1.0.1 – v1.0.4：主要修复写入路径上的边界情况（含 issue #1 相关讨论）。
- 资料来源：[v1.0.4 Full Changelog](https://github.com/oscardvs/zoteus/compare/v1.0.3...v1.0.4)。

## 7. 小结

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

---

<a id='page-4'></a>

## 部署、配置与已知问题

### 相关页面

相关主题：[系统架构与传输层](#page-2), [工具、安全写入、搜索与引用](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/configuration.md](https://github.com/oscardvs/zoteus/blob/main/docs/configuration.md)
- [docs/deployment.md](https://github.com/oscardvs/zoteus/blob/main/docs/deployment.md)
- [docs/remote-oauth.md](https://github.com/oscardvs/zoteus/blob/main/docs/remote-oauth.md)
- [docs/distribution.md](https://github.com/oscardvs/zoteus/blob/main/docs/distribution.md)
- [.env.example](https://github.com/oscardvs/zoteus/blob/main/.env.example)
- [Dockerfile](https://github.com/oscardvs/zoteus/blob/main/Dockerfile)
- [pyproject.toml](https://github.com/oscardvs/zoteus/blob/main/pyproject.toml)
- [README.md](https://github.com/oscardvs/zoteus/blob/main/README.md)
</details>

# 部署、配置与已知问题

本页汇总 Zoteus 的部署形态、运行配置项以及当前社区反馈的已知问题，便于使用者快速完成安装、配置与故障定位。

## 项目定位与适用范围

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]()

| 变量名 | 作用 | 必填 |
| --- | --- | --- |
| `ZOTEUS_API_KEY` | Zotero 个人 API 密钥 | 是 |
| `ZOTEUS_USER_ID` | Zotero 用户/群组 ID | 是 |
| `ZOTEUS_LIBRARY_TYPE` | 库类型 `user` 或 `group` | 否 |
| `ZOTEUS_API_BASE` | 自定义 API 根地址 | 否 |

资料来源：[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]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: oscardvs/zoteus; human_manual_source: deepwiki_human_wiki -->