zlib-download

图书工具

通过统一的 CLI 从多个来源搜索和下载图书。

后端

后端	来源	是否需要身份验证	适用场景
zlib	Z-Library（EAPI）	邮箱 + 密码	最大的书目，直接下载
annas	Anna's Archive	API 密钥（捐赠后获取）	聚合来源，提供多个镜像

首次设置

首次调用时，运行设置检查，并引导用户通过交互方式完成配置。

步骤 1：检查依赖项

bash ${SKILL_PATH}/scripts/setup.sh check

输出为键值对。逐项检查：

键	正常	缺失时的操作
PYTHON	ok	未找到 Python 3 — 用户必须安装
REQUESTS	ok	运行 bash ${SKILL_PATH}/scripts/setup.sh install-deps
ANNAS_BINARY	ok	运行 bash ${SKILL_PATH}/scripts/setup.sh install-annas（可选）

步骤 2：配置凭据

凭据存储在 ~/.claude/book-tools/.env 中。根据技能自带的模板创建该文件：

mkdir -p ~/.claude/book-tools
cp ${SKILL_PATH}/scripts/.env.example ~/.claude/book-tools/.env

.env 文件如下所示：

# Z-Library credentials
[email protected]
ZLIB_PASSWORD=your_password_here

# Anna's Archive (optional, requires donation for API key)
# ANNAS_SECRET_KEY=your_api_key_here

重要：不要在聊天中直接向用户索要凭据。请按以下步骤操作：

1. 创建 .env 文件（或 .env.example 模板）
2. 告知用户在 ~/.claude/book-tools/.env 中填写凭据
3. 等待用户确认已填写完毕
4. 然后继续搜索

也可以通过 CLI 设置凭据（较不推荐 — 凭据会显示在 shell 历史记录中）：

python3 ${SKILL_PATH}/scripts/book.py config set --zlib-email "[email protected]" --zlib-password "password"

步骤 3：验证

python3 ${SKILL_PATH}/scripts/book.py setup

配置 Z-Library 后的预期输出：

{
  "zlib": { "requests_installed": true, "configured": true },
  "annas": { "binary_found": true, "api_key_configured": false }
}

如果 configured 为 true，则技能已准备就绪。

凭据存储详情

两个来源会合并（.env 中的值优先）：

来源	路径	格式
.env 文件	~/.claude/book-tools/.env	每行一个 KEY=value
配置 JSON	~/.claude/book-tools/config.json	JSON（自动管理）

首次成功登录 Z-Library 后，混合令牌会缓存到 config.json 中 — 后续调用会跳过邮箱/密码登录，直接使用令牌。

工作流

典型流程为：搜索 → 选择 → 下载。

1. 搜索

# Auto-detect backend (tries zlib first, then annas)
python3 ${SKILL_PATH}/scripts/book.py search "machine learning" --limit 10

# Z-Library with filters
python3 ${SKILL_PATH}/scripts/book.py search "deep learning" --source zlib --lang english --ext pdf --limit 5

# Anna's Archive
python3 ${SKILL_PATH}/scripts/book.py search "reinforcement learning" --source annas

# Chinese books
python3 ${SKILL_PATH}/scripts/book.py search "莱姆 索拉里斯" --source zlib --lang chinese --limit 5

输出（JSON 输出到 stdout）：

{
  "source": "zlib",
  "count": 5,
  "books": [
    {
      "source": "zlib",
      "id": "12345",
      "hash": "abc123def",
      "title": "Deep Learning",
      "author": "Ian Goodfellow",
      "year": "2016",
      "language": "english",
      "extension": "pdf",
      "filesize": "22.5 MB"
    }
  ]
}

2. 向用户展示结果

搜索后，将结果以编号表格的形式展示，供用户选择：

| # | Title | Author | Year | Format | Size |
|---|-------|--------|------|--------|------|
| 1 | Deep Learning | Ian Goodfellow | 2016 | pdf | 22.5 MB |
| 2 | ... | ... | ... | ... | ... |

如果结果涵盖多种语言或版本，请按语言或类别分组并添加子标题，以便清晰查看。

询问：“您想下载哪本书？（编号）”

3. 下载

# Z-Library download (needs id + hash from search results)
python3 ${SKILL_PATH}/scripts/book.py download --source zlib --id 12345 --hash abc123def -o ~/Downloads/

# Anna's Archive download (needs MD5 hash from search results)
python3 ${SKILL_PATH}/scripts/book.py download --source annas --hash a1b2c3d4e5 --filename "deep_learning.pdf" -o ~/Downloads/

输出：

{
  "source": "zlib",
  "status": "ok",
  "path": "~/Downloads/Deep Learning (Ian Goodfellow).pdf",
  "size": 23592960
}

4. 向用户报告

下载后，报告以下信息：

• 文件路径（方便用户打开）
• 文件大小
• 剩余下载配额（Z-Library 有每日限额）

其他命令

图书信息（仅限 Z-Library）

python3 ${SKILL_PATH}/scripts/book.py info --source zlib --id 12345 --hash abc123def

返回完整元数据：简介、ISBN、页数、目录等。

检查配置

python3 ${SKILL_PATH}/scripts/book.py config show

检查后端状态

python3 ${SKILL_PATH}/scripts/book.py setup

错误处理

错误	原因	操作
"Z-Library not configured"	未设置凭据	引导用户编辑 ~/.claude/book-tools/.env
"Z-Library login failed"	凭据错误或服务不可用	请用户核实凭据。Z-Library 域名会变更 — 如果问题持续存在，可能需要更新随附的 Zlibrary.py 中的域名。
"annas-mcp binary not found"	尚未安装二进制文件	运行 setup.sh install-annas
"Anna's Archive API key not configured"	未设置 API 密钥	引导用户向 Anna's Archive 捐赠以获取 API 访问权限，然后将密钥添加到 .env
搜索超时	网络问题	重试一次。如果问题持续存在，请尝试另一个后端。
"No backend available"	两个后端均未配置	从步骤 1 开始引导用户完成整个设置流程

提示

• Z-Library 每日有下载限额（免费账户通常为每天 10 本）。下载前使用 info 检查书籍，避免浪费配额。
• 搜索和下载 Anna's Archive 都需要 API 密钥（通过捐赠获取）。
• 搜索中文书籍时，在 Z-Library 中使用 --lang chinese 可获得最佳结果。
• 如果无法访问 Z-Library，使用 --source auto 自动切换到 Anna's Archive。
• 用多种语言搜索特定作者时，可并行搜索（例如，英文名和中文名），并将结果合并到一个表格中。