release: cut v0.02 with Surge API proxy rotation

README.md

@@ -7,7 +7,7 @@
 - ✅ **自动绕过反爬保护**：自动解决网站的 SHA1 工作量证明（PoW）挑战
 - ✅ **智能搜索匹配**：支持书名、作者、ISBN 等多维度匹配
 - ✅ **格式优先级**：自动选择 epub + pdf 版本下载
-- ✅ **代理轮询**：支持 Shadowsocks（Surge 格式）代理列表，每 IP 5 本后自动切换
+- ✅ **代理轮询**：支持 Shadowsocks（Surge 格式）代理列表，或直接通过 Surge `select` 组切换出口
 - ✅ **AI 友好**：JSON 输出，结构化搜索结果，适合 AI Agent 调用
 
 ## 安装
@@ -23,6 +23,8 @@ pip install curl_cffi beautifulsoup4 lxml
 
 脚本内置自动代理引擎配置。如果使用 Shadowsocks 代理列表（如 Surge 格式），脚本**会在首次运行时自动将对应平台架构的 `mihomo` 引擎打包进执行环境中**，完全脱离 Host 依赖，无需手动通过 brew 安装任何插件。
 
+如果你已经在 macOS 上使用 Surge，并且将 zlib 域名路由到一个专门的 `select` 组，也可以直接使用 Surge HTTP API 轮换该组，无需再让脚本自行启动 `mihomo`。
+
 ## 使用方法
 
 ### 搜索图书
@@ -55,6 +57,9 @@ python3 zlib_dl.py download --title "Project Hail Mary" --author "Andy Weir" -o
 
 # 使用代理列表
 python3 zlib_dl.py download --title "Project Hail Mary" --author "Andy Weir" --proxy-file proxies.txt
+
+# 使用 Surge 的 Z-Library 策略组轮换出口（推荐先配置 .env）
+python3 zlib_dl.py download --title "Project Hail Mary" --author "Andy Weir"
 ```
 
 ### 详细模式
@@ -91,6 +96,25 @@ http://127.0.0.1:8080
 - 达到上限后自动停止当前代理进程，启动下一个
 - SS 代理会自动启动 `mihomo` 进程创建本地隧道，无需宿主机环境准备
 
+### Surge 策略组模式
+
+- 为 Surge 打开 HTTP API，例如：`http-api = <key>@127.0.0.1:6171`
+- 将 zlib 相关域名规则指向一个 `select` 组，例如 `Z-Library`
+- 脚本会默认通过 `http://127.0.0.1:6152` 访问 Surge 本地 HTTP 代理
+- 当命中 IP 限额或下载失败时，脚本会调用 Surge API，把 `Z-Library` 切到下一个策略
+
+在项目根目录创建 `.env`：
+
+```env
+SURGE_API_URL=http://127.0.0.1:6171
+SURGE_API_KEY=6f8d2c1a9b4e7f35c0d2a8e1b7f94c63
+SURGE_GROUP=Z-Library
+SURGE_HTTP_PROXY=http://127.0.0.1:6152
+SURGE_SOCKS_PROXY=socks5://127.0.0.1:6153
+```
+
+CLI 参数优先级高于 `.env`；如果不传 `--surge-api`，但 `.env` 里存在 `SURGE_API_URL`，下载命令会自动进入 Surge 模式。
+
 ## AI Agent 集成
 
 ### JSON 搜索结果结构