zlib-download

图书工具

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

语言

匹配用户的语言：使用与用户相同的语言回复。

后端

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

预检

执行任何工作流之前，运行预检以检查环境是否就绪：

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

返回标准化 JSON：

{
  "ready": true,
  "dependencies": { "python3": {"status": "ok"}, "requests": {"status": "ok"} },
  "credentials": { "zlib": {"status": "configured"}, "annas_api_key": {"status": "not_configured"} },
  "services": { "annas_binary": {"status": "ok"} }
}

• 如果 ready: true，请直接继续“工作流”部分。
• 如果 ready: false，请按照下表进行检查和修复，然后运行设置流程。

检查项	修复方法
缺少 requests	bash ${SKILL_PATH}/scripts/setup.sh install-deps（或手动运行：pip3 install requests / uv pip install requests）
未配置 zlib	指导用户编辑 ~/.claude/book-tools/.env，设置 ZLIB_EMAIL 和 ZLIB_PASSWORD
zlib 已过期	缓存的令牌已过期，且 .env 中没有邮箱/密码。指导用户将凭据重新添加到 ~/.claude/book-tools/.env
未配置 annas_api_key	指导用户向 Anna's Archive 捐赠以获取 API 密钥，然后将 ANNAS_SECRET_KEY 添加到 ~/.claude/book-tools/.env
缺少 annas_binary	bash ${SKILL_PATH}/scripts/setup.sh install-annas（或手动运行：从 annas-mcp releases 下载，并解压到 ~/.local/bin/annas-mcp）

设置（仅首次运行）

仅当预检报告 ready: false 时才运行设置。通过交互方式指导用户完成配置。

步骤 1：安装依赖项

bash ${SKILL_PATH}/scripts/setup.sh install-deps

步骤 2：配置凭据

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

mkdir -p ~/.claude/book-tools
# Only copy if .env does not already exist — never overwrite existing credentials
if [ ! -f ~/.claude/book-tools/.env ]; then
  cp ${SKILL_PATH}/scripts/.env.example ~/.claude/book-tools/.env
else
  echo "Existing .env found — skipping copy to preserve your credentials."
fi

.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. 然后继续搜索

步骤 3：验证

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

确认 ready: true 后再继续。

凭据存储

规范路径：~/.claude/book-tools/.env——用户应在此处编辑凭据。

变量	用途	必需
ZLIB_EMAIL	Z-Library 邮箱	用于 Z-Library 后端
ZLIB_PASSWORD	Z-Library 密码	用于 Z-Library 后端
ANNAS_SECRET_KEY	Anna's Archive API 密钥	用于 Anna's Archive 后端

首次成功登录 Z-Library 后，系统会自动将会话令牌缓存到 ~/.claude/book-tools/config.json，以提升性能。此文件由系统自动管理，请勿手动编辑。如果登录出现问题，请删除 config.json，脚本将使用 .env 中的凭据重新登录。

工作流

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

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. 向用户报告

下载后，提供结构化的完成报告：

[Book Download] Complete!
Book: [title] by [author]
Source: [zlib/annas]
Path: [file path]
Size: [file size]

如果使用 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 的域名会发生变化——如果问题持续存在，可能需要更新 vendored 的 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 不可用	自动回退到 Anna's Archive（--source auto 会处理这种情况）
Anna's Archive 不可用	仅使用 Z-Library
两者均未配置	停止操作并指导用户完成设置流程

提示

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