内容
# zotbridge
zotbridge 是一个为代理、应用程序和脚本提供的 Zotero 集成层，支持 Web API 同步、HTTP/MCP 访问、库的语义搜索和可恢复的无头状态。它保持本地运行时的专注：
- 规范的 SQLite 存储
- Zotero Web API 同步，用于个人和组库
- HTTP API 和 MCP 服务器，用于支持工具的客户端
- 基于 qmd 的导出 Markdown 的语义搜索
- 适用于支持它们的客户端的技能
- 规范状态和派生工件的恢复快照
它不再附带 Zotero Desktop 助手，读取或写入 `zotero.sqlite`，或捆绑原生客户端插件项目；兼容性跟踪针对 Zotero `9.0.5`，同时依赖 Zotero Web API 而不是 Desktop 内部实现。
## 安装
```bash
uv tool install zotbridge
# 或，从检出：
uv run --no-editable zotbridge version
```
有用入口点：
```bash
zotbridge # 面向人类的 CLI
zotbridge raw ... # 严格的 JSON/机器友好命令
zotbridge-daemon serve # HTTP API 守护进程
zotbridge-mcp # MCP stdio 服务器
```
## 设置
运行向导：
```bash
zotbridge setup start
```
或直接配置：
```bash
zotbridge config init \
--api-key "$ZOTERO_API_KEY" \
--remote-library-id user:123456 \
--default-library-id user:123456
```
发现和同步远程库：
```bash
zotbridge raw sync discover
zotbridge raw sync pull --library user:123456
```
## 集成
当客户端可以调用 MCP 工具时，使用 MCP 设置：
```bash
zotbridge setup add codex --scope user
zotbridge setup add claude-code --scope project
zotbridge setup add cursor --scope project
zotbridge setup add json
```
当客户端支持技能时，使用技能：
```bash
zotbridge skill install codex
zotbridge skill install claude-code
zotbridge skill install cline
zotbridge skill export claude-desktop
```
没有原生客户端插件安装/更新流程。预期的分发边界是 Python 运行时加上 MCP/HTTP 配置和技能。
## 运行时
启动 API 守护进程：
```bash
zotbridge-daemon serve --host 127.0.0.1 --port 23119 --sync-interval 300
```
有用端点：
- `GET /health`
- `GET /capabilities`
- `GET /daemon/status`
- `GET /libraries`
- `GET /libraries/{library_id}/items`
- `POST /sync/discover`
- `POST /sync/pull`
- `POST /sync/push`
- `POST /recovery/snapshots`
## 搜索
导出 Markdown 并通过 qmd 查询：
```bash
zotbridge qmd export --library user:123456
zotbridge qmd query "检索增强生成"
zotbridge qmd vsearch "论文的语义搜索"
zotbridge qmd get "<target-from-result>"
```
使用 qmd 进行发现和相关工作检索，然后使用 `qmd get` 恢复有用的命中结果背后的导出源。对于精确的项目键、集合和权威元数据，请使用直接 API/CLI/MCP 读取。
## 恢复
创建和检查快照：
```bash
zotbridge recovery snapshot-create --reason before-large-sync
zotbridge recovery snapshot-list
zotbridge recovery restore-plan --snapshot <snapshot_id>
```
仅在明确确认的情况下执行恢复：
```bash
zotbridge recovery restore-execute --snapshot <snapshot_id> --confirm
```
对于远程库，可选地通过 Zotero Web API 推送恢复的待处理更改：
```bash
zotbridge recovery restore-execute --snapshot <snapshot_id> --library user:123456 --push-remote --confirm
```
## 项目布局
- `src/zotbridge/core/`：规范存储和更改模型
- `src/zotbridge/adapters/web_sync.py`：Zotero Web API 同步适配器
- `src/zotbridge/api.py`：HTTP API
- `src/zotbridge/mcp.py`：MCP stdio 服务器
- `src/zotbridge/agent_setup.py`：MCP 配置和技能安装程序
- `src/zotbridge/recovery.py`：快照和恢复流程
- `tests/`：Python 运行时和集成测试
- `docs/`：专注的 CLI、API、MCP、技能、同步和恢复文档
## 验证
```bash
uv run pytest -q
```
