Metadata-Version: 2.4
Name: zop-cli
Version: 0.2.4
Summary: High-throughput Zotero CLI focused on batch operations and automation
Project-URL: Homepage, https://github.com/anomalyco/zop
Project-URL: Issues, https://github.com/anomalyco/zop/issues
Author: zop contributors
License-Expression: MIT
License-File: LICENSE
Keywords: batch,bibliography,cli,zotero
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4.2
Requires-Dist: pydantic>=2.7
Requires-Dist: pypdf>=4.0
Description-Content-Type: text/markdown

# zop

一个面向批量操作和自动化场景的高吞吐 Zotero 命令行工具。

## 安装

从 PyPI 安装(推荐):

```bash
uv tool install zop-cli
```

也可用 pipx:`pipx install zop-cli`,或 pip:`pip install zop-cli`。安装后命令名为 `zop`。

开发安装(可编辑,含开发依赖):

```bash
uv sync
```

贡献与维护流程见 [CONTRIBUTING](CONTRIBUTING.md)。

## 配置

zop 按以下顺序查找配置(首个存在的文件生效):`ZOP_CONFIG` 环境变量 → 平台配置目录(platformdirs)→ `~/.config/zop/config.toml`。平台配置目录:Windows 为 `%LOCALAPPDATA%\zop\`、macOS 为 `~/Library/Application Support/zop/`、Linux 为 `~/.config/zop/`。在任一位置创建 `config.toml`:

```toml
[zotero]
data_dir = "D:\\Program Data\\zotero"
library_id = "12345"
api_key = "your-api-key"
```

读取操作走本地 SQLite(`data_dir/zotero.sqlite`),写入操作走 Zotero Web API。
读取无需联网,也不需要 API key。

## 用法

```bash
zop collection list                    # 列出所有集合
zop collection list --tree              # 以父子树形展示
zop collection items ABC12345           # 列出某集合下的条目
zop collection create "新主题"          # 创建集合
zop collection create "子主题" --parent "新主题"
zop collection delete ABC12345          # 删除集合(级联)
zop collection reparent ABC12345 --parent "新父级"
zop collection move KEY1 KEY2 --to TARGET_KEY   # 移动条目
zop collection plan plan.json --dry-run        # 校验批量计划
zop collection plan plan.json --execute       # 执行批量计划
```

## Agent skill

为 AI 编程助手(Claude Code、Codex、Cursor 等)配套了一个 [agent skill](https://skills.sh),教 agent 如何调用 `zop`、解析 JSON 信封输出、以及批量 plan 的 dry-run → execute 流程:

```bash
npx skills add kingdomad/zop --skill zop -a claude-code -y
```

详见 [`skills/zop/SKILL.md`](skills/zop/SKILL.md)。

## 与 `zot` 的差异

- **真正的批量**:创建集合使用 Zotero 的批量 POST(每请求 50 条)
- **有界并发 PATCH**:移动条目使用并行 PATCH(默认 8 路并发),而非逐条顺序调用
- **真正的 dry-run**:`zop collection plan --dry-run` 会实际检查名称冲突、父级解析与条目存在性
- **reparent 支持**:`zop collection reparent` 可用(`zot` 未暴露此能力)
- **单条失败隔离**:批量移动中某一条失败不会中断整批任务
