initial commit

2026-03-31 18:18:35 +08:00
commit 97c48995b1
36 changed files with 5985 additions and 0 deletions
@@ -0,0 +1,140 @@
+# ZLibrary 电子书下载器
+
+从 [zlib.li](https://zlib.li) 搜索和下载电子书的命令行工具。
+
+## 特性
+
+- ✅ **自动绕过反爬保护**：自动解决网站的 SHA1 工作量证明（PoW）挑战
+- ✅ **智能搜索匹配**：支持书名、作者、ISBN 等多维度匹配
+- ✅ **格式优先级**：自动选择 epub + pdf 版本下载
+- ✅ **代理轮询**：支持 Shadowsocks（Surge 格式）代理列表，每 IP 5 本后自动切换
+- ✅ **AI 友好**：JSON 输出，结构化搜索结果，适合 AI Agent 调用
+
+## 安装
+
+```bash
+cd /path/to/zlib-dl
+python3 -m venv .venv
+source .venv/bin/activate
+pip install curl_cffi beautifulsoup4 lxml
+```
+
+### 代理依赖（全自动）
+
+脚本内置自动代理引擎配置。如果使用 Shadowsocks 代理列表（如 Surge 格式），脚本**会在首次运行时自动将对应平台架构的 `mihomo` 引擎打包进执行环境中**，完全脱离 Host 依赖，无需手动通过 brew 安装任何插件。
+
+## 使用方法
+
+### 搜索图书
+
+```bash
+# 按标题和作者搜索
+python3 zlib_dl.py search --title "Project Hail Mary" --author "Andy Weir"
+
+# 自由搜索
+python3 zlib_dl.py search --query "我从达尔文那里学到的投资知识 普拉克·普拉萨德"
+
+# JSON 输出（AI Agent 推荐）
+python3 zlib_dl.py --json search --title "Project Hail Mary" --author "Andy Weir"
+
+# 按 ISBN 搜索
+python3 zlib_dl.py search --isbn "9780593355275"
+```
+
+### 下载图书
+
+```bash
+# 自动搜索 + 下载最佳 epub 和 pdf
+python3 zlib_dl.py download --title "Project Hail Mary" --author "Andy Weir"
+
+# 指定下载路径（从搜索结果中获取）
+python3 zlib_dl.py download --dl-path "/dl/O2pPQwkq2l" --title "Project Hail Mary" --format epub
+
+# 指定输出目录
+python3 zlib_dl.py download --title "Project Hail Mary" --author "Andy Weir" -o ./books
+
+# 使用代理列表
+python3 zlib_dl.py download --title "Project Hail Mary" --author "Andy Weir" --proxy-file proxies.txt
+```
+
+### 详细模式
+
+```bash
+python3 zlib_dl.py --verbose search --title "..."
+python3 zlib_dl.py --verbose --json download --title "..."
+```
+
+## 代理配置
+
+### Surge Shadowsocks 格式
+
+创建 `proxies.txt`，每行一个代理：
+
+```
+🇭🇰 香港 01= ss, server.example.com, 18300, encrypt-method=aes-128-gcm, password=your_password, obfs=http, obfs-host=example.microsoft.com, tfo=true, udp-relay=true
+🇭🇰 香港 02= ss, server.example.com, 18305, encrypt-method=aes-128-gcm, password=your_password, obfs=http, obfs-host=example.microsoft.com, tfo=true, udp-relay=true
+```
+
+### SOCKS5/HTTP 代理格式
+
+也支持直接的代理 URL 格式：
+
+```
+socks5://127.0.0.1:1080
+socks5://127.0.0.1:1081
+http://127.0.0.1:8080
+```
+
+### 代理轮询机制
+
+- 每个代理最多下载 **5 本**（zlib.li 的匿名限制）
+- 达到上限后自动停止当前代理进程，启动下一个
+- SS 代理会自动启动 `mihomo` 进程创建本地隧道，无需宿主机环境准备
+
+## AI Agent 集成
+
+### JSON 搜索结果结构
+
+```json
+{
+  "status": "success",
+  "query": { "title": "...", "author": "...", "combined_query": "..." },
+  "total_results": 50,
+  "results": [
+    {
+      "id": "17576434",
+      "title": "Project Hail Mary",
+      "author": "Andy Weir",
+      "format": "epub",
+      "filesize": "1.21 MB",
+      "language": "English",
+      "year": "2021",
+      "publisher": "Ballantine Books",
+      "isbn": "9780593355275",
+      "quality": "5.0",
+      "rating": "5.0",
+      "download_path": "/dl/O2pPQwkq2l",
+      "page_url": "/book/ZOE1baGkOP/project-hail-mary.html"
+    }
+  ],
+  "recommended": {
+    "epub": { "...best epub..." },
+    "pdf": { "...best pdf..." },
+    "mobi": { "...best mobi..." }
+  },
+  "message": "找到 50 个结果。推荐: epub (1.21 MB, Q:5.0, English), pdf (7.44 MB, Q:5.0, English)"
+}
+```
+
+### 典型 Agent 工作流
+
+1. 搜索：`zlib_dl.py --json search --title "书名" --author "作者"`
+2. 从 `recommended` 中选择合适的版本
+3. 下载：`zlib_dl.py --json download --dl-path "/dl/xxx" --title "书名" --format epub`
+4. 检查下载结果的 `status` 字段
+
+## 限制
+
+- 匿名用户每 IP 每天只能下载 5 本
+- 需要代理才能批量下载
+- 网站随时可能更新反爬机制