名称: 安娜存档电子书查找与下载描述: 当需要查找书籍内容、通过标题/作者查找书籍、下载电子书或参考已出版书籍的材料时使用。触发于书籍查找、电子书下载、“找书”、“获取PDF/EPUB”。下载生成PDF/EPUB/MOBI文件 - 使用电子书提取技能转换为文本。

安娜存档电子书查找与下载

概述

从安娜存档搜索和下载电子书，安娜存档索引了数百万本书籍，支持多种格式（PDF、EPUB、MOBI等）。

先决条件

重要：下载需要安娜存档会员密钥。

在使用下载功能之前，用户必须：

拥有安娜存档会员（https://annas-archive.org/donate）
设置API密钥：export ANNAS_ARCHIVE_KEY="your-key"

密钥在成为会员后的账户设置中找到。搜索功能无需密钥，但下载会失败。

如果密钥未设置： 通知用户需要设置 ANNAS_ARCHIVE_KEY 并提供上述设置说明。

何时使用

用户要求查找/下载书籍
需要查找已出版书籍的内容
搜索特定版本或格式
“获取Clean Code的PDF”
“查找Design Patterns的最新版本”

快速参考

任务	命令
搜索	`python3 annas.py search "query" --format pdf`
获取详情	`python3 annas.py details <md5>`
下载	`python3 annas.py download <md5> --output /path/`
验证匹配	`python3 annas.py search "title author" --verify "expected title"`

环境设置

export ANNAS_ARCHIVE_KEY="your-membership-key"

密钥在您的安娜存档账户设置中找到。

工作流程

digraph download_flow {
    rankdir=TB;
    node [shape=box];

    search [label="按标题/作者搜索"];
    verify [label="验证正确书籍
(检查标题、作者、年份)"];
    multiple [label="多个版本？" shape=diamond];
    prefer_recent [label="偏好最新版本
除非请求特定版本"];
    format_ok [label="首选格式可用？" shape=diamond];
    download [label="通过快速API下载"];
    convert [label="使用电子书提取器
转换为文本"];

    search -> verify;
    verify -> multiple;
    multiple -> prefer_recent [label="是"];
    multiple -> format_ok [label="否"];
    prefer_recent -> format_ok;
    format_ok -> download [label="是"];
    format_ok -> search [label="否 - 尝试不同格式"];
    download -> convert;
}

常见模式

查找并下载书籍

# 搜索并指定格式偏好
python3 annas.py search "Clean Code Robert Martin" --format pdf --limit 5

# 验证是正确书籍，获取详情
python3 annas.py details adb5293cf369256a883718e71d3771c3

# 下载
python3 annas.py download adb5293cf369256a883718e71d3771c3 --output ./books/

处理多个版本

当搜索返回多个版本时：

检查年份 - 偏好最新版本，除非用户指定版本
检查格式 - 匹配用户的偏好（pdf/epub）
验证作者完全匹配

格式优先级

当用户未指定时，默认优先级：pdf > epub > mobi > azw3 > djvu

API详情

搜索端点： https://annas-archive.org/search

q - 查询字符串
ext - 格式过滤器（pdf, epub, mobi, azw3, djvu）
sort - year_desc 以最新为先

快速下载API： https://annas-archive.org/dyn/api/fast_download.json

md5 - 书籍标识符
key - 来自 ANNAS_ARCHIVE_KEY 环境变量

常见错误

错误	修复
密钥未设置	检查 `echo $ANNAS_ARCHIVE_KEY`
错误版本	使用 `--verify` 标志与预期标题
格式不匹配	明确设置 `--format`
书籍未找到	尝试较短查询，作者名称变体

转换为文本

下载的文件是其原始格式（PDF、EPUB、MOBI等）。要转换为纯文本以进行分析或处理，下载后使用电子书提取器技能。

典型工作流程：

使用此技能下载 → books/Clean_Code.pdf
使用电子书提取器转换 → books/Clean_Code.txt

镜像回退

脚本在主要域名不可用时自动尝试多个镜像域：

第一个工作的镜像被缓存用于会话。当使用回退时，您将在stderr中看到 Using mirror: <domain>。

错误处理

“无效md5” - MD5哈希格式错误或不存在
“非会员” - 密钥无效或过期
无结果 - 扩大搜索词，尝试仅作者搜索
“无法连接到任何镜像” - 所有镜像都宕机，稍后再试

故障排除

macOS上的SSL证书错误

如果看到此错误：

[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate

这是因为Python在macOS上找不到系统的CA证书包。

快速修复：

安装certifi：
```
pip3 install certifi
```

查找您的证书路径：

python3 -c "import certifi; print(certifi.where())"

添加到 ~/.zshrc：

export SSL_CERT_FILE=/path/from/step/2/cacert.pem

重新加载shell：source ~/.zshrc

验证是否工作：

python3 -c "import urllib.request; urllib.request.urlopen('https://google.com')"

为什么发生： macOS使用Keychain处理证书，但Python默认不使用它。框架安装（如 /Library/Frameworks/Python.framework）通常缺少证书配置。

不要使用 verify=False 或 PYTHONHTTPSVERIFY=0 - 这会完全禁用SSL，不安全。