Pyzotero

Python scripts for Zotero - supports search, browse, add items, and full collection management. Both local API and online Web API modes.

Security Scan

The skill appears to do what it claims (a pyzotero-based Zotero CLI wrapper) and its requirements/instructions are mostly proportional, but there are a few small inconsistencies you should be aware of before installing.

Purpose & Capability

Name/description (pyzotero CLI for Zotero local/online APIs) match the included code and instructions: scripts call the pyzotero library, support search, list collections, add items, and collection management. Declared required binaries (python3, pyzotero) are appropriate for the stated purpose.

Instruction Scope

SKILL.md and other docs instruct running the included Python scripts, calling the local Zotero local API or the Zotero Web API, and setting environment variables for online mode. Instructions reference absolute paths inside the OpenClaw workspace and show examples that run subprocesses — expected for a CLI skill but worth noting because the skill will execute local commands and call network APIs. No instructions attempt to read unrelated system files or transmit data to unknown endpoints.

Install Mechanism

There is no automated install spec in the registry (instruction-only), and the docs recommend installing the upstream pyzotero package via pipx or pip. That is a low-to-moderate risk approach; the skill does include code files (scripts/) which will be present in the skill folder, but there is no downloader URL or archive extraction in the install metadata.

Credentials

Online mode legitimately requires secrets (ZOTERO_USER_ID and ZOTERO_API_KEY) and the documentation instructs setting them. However, the registry metadata lists no required environment variables and no primary credential — a minor inconsistency. Requesting the Zotero API key is proportional to the stated functionality, but users should be aware the skill will read those env vars if switched to online mode.

Persistence & Privilege

Skill is not always-included and does not request special system privileges. The docs show optional user instructions to create a wrapper in /usr/local/bin (requires sudo) but the skill does not automatically write system-wide files or modify other skills' configs.

Assessment

This skill is consistent with a Zotero CLI wrapper: it runs local Python scripts that call the pyzotero library and either the Zotero local API or the Zotero Web API. Before installing: 1) Review the included scripts (scripts/zotero_tool.py) yourself — the skill will execute them and they perform network calls and read environment variables. 2) If you plan to use online mode, only set ZOTERO_API_KEY and ZOTERO_USER_ID when you trust the environment; avoid committing API keys into shell startup files if you don't want them stored in plaintext history. 3) The registry metadata did not declare required env vars even though the docs describe them; this is likely because local mode is default, but confirm you understand which mode you'll use. 4) Installing the upstream pyzotero package via pipx (recommended) is sensible; do not blindly run commands that write to /usr/local without checking. If you want higher assurance, run the scripts in a sandboxed environment or inspect all code paths that create items (add/create_items) to ensure they behave as you expect.

Pyzotero CLI - Python Scripts

使用 Python 脚本调用 pyzotero 库，支持本地 Zotero API 和在线 Web API 两种模式。

快速开始

# 安装 pyzotero 库
pipx install pyzotero

# 设置环境变量 (可选)
export ZOTERO_LOCAL="true"  # 使用本地 API (默认)
# export ZOTERO_LOCAL="false"  # 使用在线 API

# 搜索库
python3 scripts/zotero_tool.py search -q "machine learning"

# 全文搜索 (包括 PDF)
python3 scripts/zotero_tool.py search -q "attention mechanisms" --fulltext

# 列出所有集合
python3 scripts/zotero_tool.py listcollections

📖 详细指南: QUICKSTART.md

环境变量配置

ZOTERO_LOCAL (必需)

控制使用本地 API 还是在线 API:

值	模式	说明
"true" (默认)	本地模式	使用本地 Zotero 7+ 的本地 API
"false"	在线模式	使用 Zotero Web API

ZOTERO_USER_ID (在线模式必需)

您的 Zotero 用户 ID，在在线模式下需要设置。

ZOTERO_API_KEY (在线模式必需)

您的 Zotero API Key，在在线模式下需要设置。

配置示例

本地模式 (推荐):

export ZOTERO_LOCAL="true"
python3 scripts/zotero_tool.py search -q "python"

在线模式:

export ZOTERO_LOCAL="false"
export ZOTERO_USER_ID="your_user_id"
export ZOTERO_API_KEY="your_api_key"
python3 scripts/zotero_tool.py search -q "python"

安装

pipx (推荐)

pipx install pyzotero

pip (通用)

pip install --user pyzotero
export PATH="$HOME/.local/bin:$PATH"

📖 完整安装指南: INSTALL.md

前提条件

本地模式配置

需要在 Zotero 7+ 中启用本地 API:

1. 打开 Zotero 7 (或更新版本)
2. 进入 编辑 > 首选项 > 高级 (macOS: Zotero > 设置 > 高级)
3. 勾选 "允许此计算机上的其他应用程序与 Zotero 通信"
4. 重启 Zotero

在线模式配置

需要获取 API 密钥:

1. 访问 https://www.zotero.org/settings/keys
2. 点击 "Create new private key"
3. 授予读取权限 (Read access to library and files)
4. 复制密钥并设置环境变量:

   export ZOTERO_USER_ID="your_user_id"
   export ZOTERO_API_KEY="your_key"
   

核心命令

命令	说明
python3 scripts/zotero_tool.py search -q "关键词"	搜索库
python3 scripts/zotero_tool.py search --fulltext	全文搜索 (包括 PDF)
python3 scripts/zotero_tool.py search --collection ID	在特定集合中搜索
python3 scripts/zotero_tool.py listcollections	列出所有集合
python3 scripts/zotero_tool.py itemtypes	列出项目类型
python3 scripts/zotero_tool.py item KEY	获取单个项目详情
python3 scripts/zotero_tool.py add -t "标题"	添加单个项目
python3 scripts/zotero_tool.py add-from-json file.json	批量添加项目
python3 scripts/zotero_tool.py collection-create -n "名称"	创建新集合
python3 scripts/zotero_tool.py collection-rename KEY -n "新名"	重命名集合
python3 scripts/zotero_tool.py collection-delete KEY -y	删除集合
python3 scripts/zotero_tool.py collection-add-item ITEM -c COLL	添加项目到集合
python3 scripts/zotero_tool.py collection-remove-item ITEM -c COLL	从集合移除项目
python3 scripts/zotero_tool.py collection-list KEY	列出集合中的项目

使用示例

基本搜索

# 搜索标题和元数据
python3 scripts/zotero_tool.py search -q "machine learning"

# 短语搜索
python3 scripts/zotero_tool.py search -q "\"deep learning\""

全文搜索

# 在 PDF 和附件中搜索
python3 scripts/zotero_tool.py search -q "neural networks" --fulltext

高级过滤

# 按项目类型过滤
python3 scripts/zotero_tool.py search -q "methodology" --itemtype book

# 在特定集合中搜索
python3 scripts/zotero_tool.py search --collection ABC123 -q "test"

# 限制结果数量
python3 scripts/zotero_tool.py search -q "python" -l 10

获取项目详情

# 获取单个项目
python3 scripts/zotero_tool.py item ABC123XYZ

添加单个项目

# 添加期刊文章
python3 scripts/zotero_tool.py add -t "文章标题" -a "FirstName LastName" -p "期刊名" -d "2024"

# 添加带 DOI 和标签的文章
python3 scripts/zotero_tool.py add -t "AI 在医学中的应用" -a "张三" "李四" -p "中华医学杂志" -d "2024" --doi "10.xxxx/xxxxx" --tags AI 医学 machine-learning

# 添加带摘要和 URL 的文章
python3 scripts/zotero_tool.py add -t "Python 数据分析" -a "王五" -p "计算机学报" -d "2024" --url "https://example.com" --abstract "本文介绍了..." --tags python 数据分析

批量添加项目

# 从 JSON 文件批量添加
python3 scripts/zotero_tool.py add-from-json papers.json

# JSON 文件格式示例:
[
  {
    "itemType": "journalArticle",
    "title": "文章标题",
    "creators": [{"firstName": "First", "lastName": "Last", "creatorType": "author"}],
    "publicationTitle": "期刊名",
    "date": "2024",
    "DOI": "10.xxxx/xxxxx",
    "tags": [{"tag": "tag1", "type": 1}],
    "abstractNote": "摘要"
  }
]

集合管理

# 创建新集合
python3 scripts/zotero_tool.py collection-create -n "新集合名称"

# 创建子集合
python3 scripts/zotero_tool.py collection-create -n "子集合" -p PARENT_KEY

# 重命名集合
python3 scripts/zotero_tool.py collection-rename COLLECTION_KEY -n "新名称"

# 删除集合（需要确认）
python3 scripts/zotero_tool.py collection-delete COLLECTION_KEY
python3 scripts/zotero_tool.py collection-delete COLLECTION_KEY -y  # 跳过确认

# 添加项目到集合
python3 scripts/zotero_tool.py collection-add-item ITEM_KEY -c COLLECTION_KEY

# 从集合移除项目
python3 scripts/zotero_tool.py collection-remove-item ITEM_KEY -c COLLECTION_KEY

# 列出集合中的项目
python3 scripts/zotero_tool.py collection-list COLLECTION_KEY
python3 scripts/zotero_tool.py collection-list COLLECTION_KEY -l 50  # 显示 50 个

输出格式

人类可读格式 (默认)

python3 scripts/zotero_tool.py search -q "python"

JSON 输出

# 输出 JSON 格式
python3 scripts/zotero_tool.py search -q "topic" --json

# 使用 jq 处理
python3 scripts/zotero_tool.py search -q "topic" --json | jq '.[].data.title'

# 保存到文件
python3 scripts/zotero_tool.py search -q "topic" --json > results.json

文档

文档	说明
QUICKSTART.md	5 分钟快速入门
INSTALL.md	详细安装指南
EXAMPLES.md	实用使用示例
README.md	项目概览

故障排除

本地模式连接错误:

确保 Zotero 正在运行
启用本地 API: 设置 > 高级 > "允许此计算机上的其他应用程序与 Zotero 通信"
重启 Zotero

在线模式认证错误:

# 检查环境变量是否正确设置
echo $ZOTERO_USER_ID
echo $ZOTERO_API_KEY

# 确认 ZOTERO_LOCAL 设置为 false
export ZOTERO_LOCAL="false"

模块未找到错误:

# 确保已安装 pyzotero
pipx install pyzotero
# 或
pip install --user pyzotero

权限错误 (PEP 668 系统):

pipx install pyzotero

📖 详细故障排除: INSTALL.md

快速参考

# 设置模式
export ZOTERO_LOCAL="true"   # 本地模式 (默认)
export ZOTERO_LOCAL="false"  # 在线模式

# 在线模式需要额外设置
export ZOTERO_USER_ID="your_id"
export ZOTERO_API_KEY="your_key"

# 搜索
python3 scripts/zotero_tool.py search -q "topic"
python3 scripts/zotero_tool.py search -q "topic" --fulltext
python3 scripts/zotero_tool.py search -q "topic" --json

# 列表
python3 scripts/zotero_tool.py listcollections
python3 scripts/zotero_tool.py itemtypes

# 获取项目
python3 scripts/zotero_tool.py item ITEM_KEY

# 过滤
python3 scripts/zotero_tool.py search -q "topic" --itemtype journalArticle
python3 scripts/zotero_tool.py search --collection ABC123 -q "topic"

---

完整文档:

• QUICKSTART.md - 快速入门
• INSTALL.md - 安装详情
• EXAMPLES.md - 使用示例
• README.md - 完整概览

脚本说明

本技能提供 Python 脚本 scripts/zotero_tool.py，通过 pyzotero 库与 Zotero 交互:

• 本地模式 (ZOTERO_LOCAL="true"): 直接连接到运行中的 Zotero 7+ 本地实例
• 在线模式 (ZOTERO_LOCAL="false"): 通过 Zotero Web API 访问您的在线库

所有功能与原版 pyzotero-cli 保持一致，但使用 Python 脚本方式调用，更灵活且易于集成到其他 Python 项目中。