mineworker 0.4.0__tar.gz

mineworker-0.4.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# 虚拟环境
+.venv/
+venv/
+env/
+
+# 测试 / 类型检查 / lint 缓存
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# 运行产物
+logs/
+*.log
+failed_items.jsonl
+failed_requests.jsonl
+
+# IDE / 系统
+.idea/
+.vscode/
+.DS_Store
+
+# 文档构建
+site/

mineworker-0.4.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+本文件格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [Unreleased]
+
+## [0.4.0] - 2026-09-04
+
+**首次发行到 PyPI。** 0.3.0 之后积累的全部分布式能力（v2.1–v2.7）随本版本一次性发出。
+
+### 新增
+
+- **Redis 基础设施** —— `db/redisdb.py`（连接缓存、`acquire_once` 一次性锁、统一 key 前缀）、
+  `RedisTaskQueue`（zset 优先级队列，原子 `zpopmin`）、`RedisSetFilter` / `RedisBloomFilter`；
+  `DEDUP_FILTER=redis|redis-set` 即可整体切换去重后端
+- **`Spider`（分布式）** —— Redis 队列 + Redis 布隆去重 + 断点续爬 + `start_requests` 一次性锁 +
+  多节点心跳结束检测 + 失败请求落 Redis。抽出 `BaseScheduler` 公共骨架
+- **`TaskSpider`** —— 从 Redis / DB 任务源持续拉任务，多节点分摊，`keep_alive` 常驻
+- **账号 / Cookie 池** —— `LocalUserPool` / `GuestUserPool` / `RedisUserPool`；
+  `user_pool()` + `check_login()` 钩子，掉登录自动换号重试
+- **MySQL 管道** —— `MysqlPipeline`（`executemany` 批量写 + `ON DUPLICATE KEY UPDATE` upsert）、
+  `MysqlDB`（PooledDB 连接池）；`mineworker create -i --table <表>` 读 `SHOW FULL COLUMNS` 反射生成 Item
+- **`AsyncHttpxDownloader`** —— 可选异步下载器（`DOWNLOADER_ASYNC=True`），独立事件循环线程 +
+  共享 `AsyncClient`，爬虫代码零改动；新增 `HTTPX_HTTP2` 开关
+- **`BatchSpider`** —— 周期性批次采集：MySQL 任务表状态机 + 批次记录表 + 进度追踪 + 任务防丢；
+  master（`start_monitor`）/ worker（`start`）分离，抽象 `BatchStore`（`MysqlBatchStore` / `MemoryBatchStore`）
+- 文档站新增《分布式》《批次采集》《账号 / Cookie 池》《async 内核评估》四篇
+
+### 修复
+
+- `cb_kwargs` 从未传给 callback（`parser_control` 现在按 `callback(request, response, **request.cb_kwargs)` 调用）
+- `BaseScheduler.run()` 中 `_seed()` 移到 `_start_threads()` 之前，避免 worker 抢跑断点续爬遗留的队列
+- **刚启动的机器 / 容器上第一条告警被静默吞掉**：`AlertManager` 用 `0.0` 当「从没发过」的哨兵，
+  而 `time.monotonic()` 的原点是开机，`now - 0.0 < WARNING_INTERVAL` 在低 uptime 时恒真。
+  现在用「key 缺席」表示从没发过
+- **同源问题让代理池在新容器里起不来**：`ApiProxyPool` 的 `_last_fetch` 初值 `0.0` 会让第一次
+  拉取代理被间隔限流跳过，池子一直是空的。现在初值为 `None`
+- 只装核心包（不带 `[cli]`）时执行 `mineworker` 会抛 `ModuleNotFoundError` 堆栈，
+  现在提示 `pip install "mineworker[cli]"`
+
+### 变更
+
+- 包元数据：`Development Status` 提到 `4 - Beta`，补 `Typing :: Typed` 与完整的 `[project.urls]`
+- 新增 PyPI 发布与文档部署流水线（Trusted Publishing，无 token）
+
+### 说明
+
+- 关于「是否把内核改成全 async」的评估结论见
+  [async 内核评估](https://apersonw.github.io/mineworker/async-kernel/)：**不做全量重写**，
+  只落地隔离的异步下载器。工作线程仍是「1 线程 1 在途」，`AsyncHttpxDownloader` 的收益是
+  连接复用 / HTTP2 / 更低 FD
+
+## 0.3.0 - 2026-09-03
+
+轻量单机版（`AirSpider`）完整可用。**未发行到 PyPI**（当时仅本地开发）。
+
+### 新增
+
+- **运行时** —— 内存优先级队列、`Collector` / `ParserControl` / `RequestBuffer` / `ItemBuffer`、
+  优雅退出、`AirSpider`
+- **网络层** —— `Request` / `Response`（w3lib 编码检测 + parsel 选择器）、`Downloader` ABC +
+  `HttpxDownloader`、重试与超时
+- **数据与去重** —— `Item` / `UpdateItem`、内存布隆过滤器、
+  `Console` / `CSV` / `Mongo` 管道
+- **浏览器渲染** —— `PlaywrightDownloader` + 渲染池，`Request(render=True)`
+- **中间件与代理** —— `DownloaderMiddleware` 链、`ProxyPool` ABC + `ApiProxyPool`
+- **可观测性** —— `MetricsReporter` + Prometheus exporter、`AlertManager`（飞书 / 邮件 / 日志）
+- **命令行** —— `mineworker create` 脚手架、`shell` 交互调试、`retry` 失败重放
+- mkdocs-material 文档站
+
+[Unreleased]: https://github.com/apersonw/mineworker/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/apersonw/mineworker/releases/tag/v0.4.0

mineworker-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MineWorker contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mineworker-0.4.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: mineworker
+Version: 0.4.0
+Summary: 一个上手简单、结构清晰的 Python 爬虫框架（对标 feapder）
+Project-URL: Homepage, https://github.com/apersonw/mineworker
+Project-URL: Repository, https://github.com/apersonw/mineworker
+Project-URL: Documentation, https://apersonw.github.io/mineworker/
+Project-URL: Changelog, https://github.com/apersonw/mineworker/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/apersonw/mineworker/issues
+Author-email: Lucas <schummshelly26@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: crawler,feapder,scraping,spider,爬虫
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: bitarray>=2.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: loguru>=0.7
+Requires-Dist: parsel>=1.9
+Requires-Dist: w3lib>=2.1
+Provides-Extra: all
+Requires-Dist: dbutils>=3.0; extra == 'all'
+Requires-Dist: jinja2>=3.1; extra == 'all'
+Requires-Dist: playwright>=1.44; extra == 'all'
+Requires-Dist: prometheus-client>=0.20; extra == 'all'
+Requires-Dist: pymongo>=4.7; extra == 'all'
+Requires-Dist: pymysql>=1.1; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Requires-Dist: typer>=0.12; extra == 'all'
+Provides-Extra: cli
+Requires-Dist: jinja2>=3.1; extra == 'cli'
+Requires-Dist: typer>=0.12; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: dbutils>=3.0; extra == 'dev'
+Requires-Dist: fakeredis>=2.20; extra == 'dev'
+Requires-Dist: jinja2>=3.1; extra == 'dev'
+Requires-Dist: mongomock>=4.1; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: playwright>=1.44; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: prometheus-client>=0.20; extra == 'dev'
+Requires-Dist: pymongo>=4.7; extra == 'dev'
+Requires-Dist: pymysql>=1.1; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest-httpserver>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: redis>=5.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: typer>=0.12; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.20; extra == 'metrics'
+Provides-Extra: mongo
+Requires-Dist: pymongo>=4.7; extra == 'mongo'
+Provides-Extra: mysql
+Requires-Dist: dbutils>=3.0; extra == 'mysql'
+Requires-Dist: pymysql>=1.1; extra == 'mysql'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: render
+Requires-Dist: playwright>=1.44; extra == 'render'
+Description-Content-Type: text/markdown
+
+# MineWorker
+
+[![PyPI](https://img.shields.io/pypi/v/mineworker)](https://pypi.org/project/mineworker/)
+[![Python](https://img.shields.io/pypi/pyversions/mineworker)](https://pypi.org/project/mineworker/)
+[![CI](https://github.com/apersonw/mineworker/actions/workflows/ci.yml/badge.svg)](https://github.com/apersonw/mineworker/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-apersonw.github.io-teal)](https://apersonw.github.io/mineworker/)
+
+一个上手简单、结构清晰的 Python 爬虫框架，对标 [feapder](https://github.com/Boris-code/feapder)：
+你只写 `start_requests` 和 `parse`，框架负责调度、下载、重试、去重、批量落库。
+
+> **0.4.0** —— 单机（`AirSpider`）到分布式（`Spider` / `TaskSpider` / `BatchSpider`）全部可用。
+> 变更见 [CHANGELOG](CHANGELOG.md)，后续规划见 [Roadmap](https://apersonw.github.io/mineworker/roadmap/)。
+
+## 安装
+
+```bash
+pip install mineworker            # 核心
+pip install "mineworker[all]"     # 含渲染 / MongoDB / MySQL / Redis / CLI / 指标
+```
+
+也可以按需装单项：`render` · `mongo` · `mysql` · `redis` · `cli` · `metrics`。
+
+## 快速开始
+
+```bash
+pip install "mineworker[cli]"
+mineworker create -p news_crawler
+cd news_crawler && python main.py
+```
+
+或直接写：
+
+```python
+import mineworker as mw
+
+
+class NewsSpider(mw.AirSpider):
+    def start_requests(self):
+        yield mw.Request("https://news.ycombinator.com/", callback=self.parse)
+
+    def parse(self, request, response):
+        for a in response.css("span.titleline > a"):
+            yield {"title": a.css("::text").get(), "url": a.css("::attr(href)").get()}
+
+
+NewsSpider().start()
+```
+
+## 文档
+
+完整文档：**<https://apersonw.github.io/mineworker/>**
+（本地预览：`pip install "mineworker[docs]" && mkdocs serve`）
+
+设计与实施计划见 [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md)。
+
+## 能力一览
+
+| | |
+|---|---|
+| 运行时 | 单进程多线程、优先级队列、结束检测、`Ctrl-C` 优雅排空、崩溃 dump + `retry` 回放 |
+| 网络 | `Request`/`Response`（httpx + parsel）、自动重试、`validate`/`failed_request` 钩子、随机 UA、会话复用 |
+| 分布式 | `Spider`：Redis 队列 + 布隆去重 + 断点续爬 + 种子一次性锁 + 多节点心跳结束检测 |
+| 任务驱动 | `TaskSpider` 从任务源持续消费；`BatchSpider` 周期批次采集（任务表状态机 + 进度追踪 + 防丢） |
+| 数据 | `Item`/`UpdateItem`、`Pipeline`（Console/CSV/MongoDB/MySQL upsert）、请求级 + Item 级去重（布隆/精确） |
+| 渲染 | `Request(render=True)` —— Playwright 渲染池、`wait_for`/`render_time`/`render_script` |
+| 扩展 | 下载中间件链、代理池接口、账号 / Cookie 池（掉登录自动换号） |
+| 观测 | Prometheus exporter、卡死/失败率告警（飞书/邮件）、`debug=True` |
+| 工具 | `mineworker create/shell/retry`，`create -i --table` 读表结构反射生成 Item |
+
+## 开发
+
+```bash
+conda env create -f environment.yml && conda activate mineworker
+pre-commit install
+pytest && ruff check . && mypy
+```
+
+CI（GitHub Actions）：ruff + mypy(strict) + pytest（Python 3.10–3.13）+ mkdocs build。
+
+## License
+
+[MIT](LICENSE)

mineworker-0.4.0/README.md

@@ -0,0 +1,83 @@
+# MineWorker
+
+[![PyPI](https://img.shields.io/pypi/v/mineworker)](https://pypi.org/project/mineworker/)
+[![Python](https://img.shields.io/pypi/pyversions/mineworker)](https://pypi.org/project/mineworker/)
+[![CI](https://github.com/apersonw/mineworker/actions/workflows/ci.yml/badge.svg)](https://github.com/apersonw/mineworker/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-apersonw.github.io-teal)](https://apersonw.github.io/mineworker/)
+
+一个上手简单、结构清晰的 Python 爬虫框架，对标 [feapder](https://github.com/Boris-code/feapder)：
+你只写 `start_requests` 和 `parse`，框架负责调度、下载、重试、去重、批量落库。
+
+> **0.4.0** —— 单机（`AirSpider`）到分布式（`Spider` / `TaskSpider` / `BatchSpider`）全部可用。
+> 变更见 [CHANGELOG](CHANGELOG.md)，后续规划见 [Roadmap](https://apersonw.github.io/mineworker/roadmap/)。
+
+## 安装
+
+```bash
+pip install mineworker            # 核心
+pip install "mineworker[all]"     # 含渲染 / MongoDB / MySQL / Redis / CLI / 指标
+```
+
+也可以按需装单项：`render` · `mongo` · `mysql` · `redis` · `cli` · `metrics`。
+
+## 快速开始
+
+```bash
+pip install "mineworker[cli]"
+mineworker create -p news_crawler
+cd news_crawler && python main.py
+```
+
+或直接写：
+
+```python
+import mineworker as mw
+
+
+class NewsSpider(mw.AirSpider):
+    def start_requests(self):
+        yield mw.Request("https://news.ycombinator.com/", callback=self.parse)
+
+    def parse(self, request, response):
+        for a in response.css("span.titleline > a"):
+            yield {"title": a.css("::text").get(), "url": a.css("::attr(href)").get()}
+
+
+NewsSpider().start()
+```
+
+## 文档
+
+完整文档：**<https://apersonw.github.io/mineworker/>**
+（本地预览：`pip install "mineworker[docs]" && mkdocs serve`）
+
+设计与实施计划见 [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md)。
+
+## 能力一览
+
+| | |
+|---|---|
+| 运行时 | 单进程多线程、优先级队列、结束检测、`Ctrl-C` 优雅排空、崩溃 dump + `retry` 回放 |
+| 网络 | `Request`/`Response`（httpx + parsel）、自动重试、`validate`/`failed_request` 钩子、随机 UA、会话复用 |
+| 分布式 | `Spider`：Redis 队列 + 布隆去重 + 断点续爬 + 种子一次性锁 + 多节点心跳结束检测 |
+| 任务驱动 | `TaskSpider` 从任务源持续消费；`BatchSpider` 周期批次采集（任务表状态机 + 进度追踪 + 防丢） |
+| 数据 | `Item`/`UpdateItem`、`Pipeline`（Console/CSV/MongoDB/MySQL upsert）、请求级 + Item 级去重（布隆/精确） |
+| 渲染 | `Request(render=True)` —— Playwright 渲染池、`wait_for`/`render_time`/`render_script` |
+| 扩展 | 下载中间件链、代理池接口、账号 / Cookie 池（掉登录自动换号） |
+| 观测 | Prometheus exporter、卡死/失败率告警（飞书/邮件）、`debug=True` |
+| 工具 | `mineworker create/shell/retry`，`create -i --table` 读表结构反射生成 Item |
+
+## 开发
+
+```bash
+conda env create -f environment.yml && conda activate mineworker
+pre-commit install
+pytest && ruff check . && mypy
+```
+
+CI（GitHub Actions）：ruff + mypy(strict) + pytest（Python 3.10–3.13）+ mkdocs build。
+
+## License
+
+[MIT](LICENSE)

mineworker-0.4.0/docs/api.md

@@ -0,0 +1,53 @@
+# API
+
+::: mineworker.AirSpider
+    options:
+      members: [start, stop]
+
+::: mineworker.Spider
+    options:
+      members: [start, stop]
+
+::: mineworker.TaskSpider
+    options:
+      members: [task_requests, fetch_tasks, add_tasks, push_tasks, start, stop]
+
+::: mineworker.BatchSpider
+    options:
+      members: [task_requests, update_task, failed_request, start, start_monitor, stop]
+
+::: mineworker.core.batch_store.BatchStore
+
+::: mineworker.core.batch_monitor.BatchMonitor
+    options:
+      members: [run, run_once, stop]
+
+::: mineworker.BaseParser
+
+::: mineworker.Request
+
+::: mineworker.Response
+
+::: mineworker.Item
+
+::: mineworker.UpdateItem
+
+::: mineworker.pipelines.base.BasePipeline
+
+::: mineworker.pipelines.mysql.MysqlPipeline
+
+::: mineworker.db.mysqldb.MysqlDB
+
+::: mineworker.User
+
+::: mineworker.network.user_pool.base.UserPool
+
+::: mineworker.LocalUserPool
+
+::: mineworker.GuestUserPool
+
+::: mineworker.RedisUserPool
+
+::: mineworker.network.middleware.DownloaderMiddleware
+
+::: mineworker.network.proxy_pool.base.ProxyPool

mineworker-0.4.0/docs/async-kernel.md

@@ -0,0 +1,81 @@
+# async 内核评估
+
+> Roadmap 里「async 内核 —— 评估用 async httpx 替换线程模型」的结论。
+> **结论：不做全量 async 重写；落地一个隔离的异步下载器 `AsyncHttpxDownloader` 作为可选加速项。**
+
+## 现在的线程模型
+
+```
+主线程            run(): 注入种子 → 起线程 → _wait_until_done 轮询 → teardown
+N×ParserWorker    collector.get → 中间件 → download_request(阻塞 httpx) → validate → parse → 分发
+RequestBuffer     线程，周期 flush → 去重 → 任务队列
+ItemBuffer        线程，周期 flush → 去重 → pipeline.save_items(阻塞 pymongo / pymysql)
+_Heartbeat        线程，周期 hset(阻塞 redis)      —— 仅 Spider
+_TaskPoller       线程，周期 lpop(阻塞 redis)      —— 仅 TaskSpider
+_RenderPool       pool_size×线程，各持一个 sync chromium
+```
+
+并发靠 `SPIDER_THREAD_COUNT` 个工作线程。socket 等待时 GIL 释放，lxml 解析在 C 扩展里
+也释放 GIL，所以线程模型对 I/O 密集抓取是够用的——feapder 本身就这么跑生产。
+
+## async 能买到什么 / 买不到什么
+
+| | 说明 |
+|---|---|
+| ✅ 单线程驱动上千并发连接 | 每连接开销更低、FD 更省。仅在「大扇出 + 解析极轻 + 目标站不限速」时真正兑现 |
+| ✅ `redis.asyncio` / `httpx.AsyncClient` / playwright async API | 都现成 |
+| ⚠️ 解析是 CPU-bound | 单事件循环会把所有 `parse` 串行化，最终还得甩进 executor → 又回到线程 |
+| ❌ 落库 | `pymongo` / `pymysql` 没有干净的 async 路径（要换 `motor` / `aiomysql`）。而 ItemBuffer 本来就批量写，不是瓶颈 |
+| ❌ feapder 心智兼容 | 用户写同步 `def parse` + `yield` 是明确约束。async 内核要么逼用户写 `async def`，要么陷入混合模型 |
+
+**混合模型是陷阱**：保留同步 `def parse` 丢进 executor 跑 → 事件循环**和**线程池同时存在，
+只把「下载等待」挪出了线程，解析吞吐照旧，还多一套并发模型要 debug。Scrapy 能走 async 是
+因为它整个 API 都是 async 原生的——那正是本项目排除掉的路。
+
+## 重写的成本
+
+几乎是整个 core + network + dedup + 一半测试：`base_scheduler`（TaskGroup / `asyncio.Queue` /
+信号）、`parser_control`、`collector`、两个 buffer、`task_queue`、`_httpx`、`downloader/base`
+（连带 `Request.download()` 和 `mineworker shell` 的同步入口）、`redis_scheduler` /
+`redis_task_scheduler` / `redis_filter`、`proxy_pool`、`user_pool/redis`，以及
+`test_air_spider` / `test_spider` / `test_task_spider` / `test_integration_httpserver` /
+`test_downloader` / `test_render` / `test_spider_persistence` 全部重写（现有测试深度依赖
+「`start()` 阻塞 + 线程不泄漏 + `threading.Timer` 停止」）。这是 v3 级别的工作量。
+
+投入产出比不成立：收益只在少数派工作负载上兑现，而那类负载通常先撞上目标站限速。
+
+## 落地：`AsyncHttpxDownloader`
+
+作为评估的产出，做了一个**隔离的异步下载器**，捕获大部分收益而 API 零改动：
+
+- 一个专属事件循环线程 + 一个共享 `httpx.AsyncClient` 承载所有在途连接
+- 对外仍是同步 `Downloader.download()`：工作线程提交协程到内部 loop 并阻塞等结果（和渲染池同套路）
+- 连接池 / keep-alive / HTTP/2 多路复用被**所有 worker 共享**（同步下载器在 `use_session=False`
+  时每请求新建 client，没有 keep-alive）
+- `DOWNLOADER_ASYNC_CONCURRENCY` 信号量 + 连接池上限双重限流
+
+```python
+# setting.py
+DOWNLOADER_ASYNC = True             # 普通请求走 AsyncHttpxDownloader
+DOWNLOADER_ASYNC_CONCURRENCY = 200  # 最大在途请求数
+HTTPX_HTTP2 = True                  # 需 pip install "httpx[http2]"，同步 / 异步下载器都生效
+```
+
+`render=True` 的请求不受影响（仍走渲染池）。
+
+### 目前的天花板
+
+工作线程是「1 线程 : 1 在途请求」，所以真正在途的请求数仍 ≈ `SPIDER_THREAD_COUNT`。
+`AsyncHttpxDownloader` 现在的收益是**连接复用 + HTTP/2 + 更低 FD**，不是「少量线程跑上千并发」。
+
+要突破这个天花板，需要 worker 侧批量分发：少量 worker，每个从 collector 取一批、
+`await asyncio.gather(*downloads)` 拿到全部响应后再逐个 `parse`。这会改动 `parser_control`
+和结束检测，属于「真需要时再做」——目前没有实测证据表明线程调度是瓶颈。
+
+## 何时重新评估
+
+- 实测某目标：在途连接数远小于期望、且 CPU / 带宽 / 目标站限速都不是瓶颈
+- 需要单机十万级并发连接（此时线程栈内存和上下文切换才真正咬人）
+
+否则：调大 `SPIDER_THREAD_COUNT`（开到 ~100 无妨）、开 `HTTPX_HTTP2`、开 `DOWNLOADER_ASYNC`
+拿连接复用，通常就够了。

mineworker-0.4.0/docs/batch-spider.md

@@ -0,0 +1,110 @@
+# 批次采集（BatchSpider）
+
+`BatchSpider` 用于**周期性全量 / 增量批次采集**：任务放在 MySQL 任务表里，每隔
+`BATCH_INTERVAL` 天开一个新批次、重跑全部任务，进度写在批次记录表，卡死的任务会被
+自动回收重跑。
+
+```bash
+pip install "mineworker[redis,mysql]"
+```
+
+## 任务表
+
+由你自己建，至少要有：主键列、状态列、更新时间列（防丢检测用）。
+
+```sql
+CREATE TABLE `crawl_task` (
+  `id` BIGINT NOT NULL AUTO_INCREMENT,
+  `url` VARCHAR(500) NOT NULL,
+  `batch_status` TINYINT NOT NULL DEFAULT 0,   -- 0 待处理 / 1 完成 / 2 处理中 / -1 失败
+  `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  PRIMARY KEY (`id`)
+);
+```
+
+列名可配（`BATCH_TASK_ID_FIELD` / `BATCH_TASK_STATE_FIELD` / `BATCH_TASK_TIME_FIELD`）。
+批次记录表 `crawl_task_batch_record` 由框架自动建。
+
+## 写爬虫
+
+```python
+import mineworker as mw
+
+
+class CrawlTask(mw.BatchSpider):
+    __task_table__ = "crawl_task"
+
+    def task_requests(self, task):                 # 一行任务 -> 请求（必须实现）
+        yield mw.Request(task["url"], callback=self.parse)
+
+    def parse(self, request, response, task):      # 框架自动带上 task
+        yield {"url": task["url"], "title": response.css("h1::text").get()}
+        self.update_task(task["id"], ok=True)      # 关键：回写任务状态
+
+
+if __name__ == "__main__":
+    import sys
+
+    if sys.argv[1:] == ["monitor"]:
+        CrawlTask().start_monitor()   # master
+    else:
+        CrawlTask(keep_alive=True).start()   # worker
+```
+
+`self.update_task(task_id, ok=True)` 标完成，`ok=False` 标失败（不再重试）。
+不回写的任务会一直停在「处理中」，被防丢机制反复重跑。重试耗尽的请求，框架默认帮你
+`update_task(..., ok=False)`（覆写 `failed_request` 时记得 `super()`）。
+
+## 两种角色
+
+| | 启动 | 职责 |
+|---|---|---|
+| **master** | `spider.start_monitor()` | 批次生命周期：到点开新批次（重置任务表）、把待处理任务推进 Redis 待抓队列、按任务表刷新进度、回收卡死任务、批次跑完收尾 |
+| **worker** | `spider.start()` | 消费 Redis 队列，对每个任务调 `task_requests`，解析完回写状态。可多进程 / 多机 |
+
+同一命名空间只允许一个 master（Redis 锁），worker 随便起几个。
+
+```bash
+python main.py monitor     # 一台，常驻；或 cron 每天跑一次 start_monitor(once=True)
+python main.py             # 多台 / 多进程，worker
+```
+
+- `start_monitor(once=True)`：把当前批次跑到完成即返回，适合塞进 crontab。
+- `start_monitor()`：常驻，一个批次跑完后等到下个 `BATCH_INTERVAL` 再开下一批。
+- worker 建议 `keep_alive=True` 常驻（等 master 派活）；`keep_alive=False` 则队列抽干即退出。
+
+## 一次巡检做什么
+
+master 每 `BATCH_MONITOR_INTERVAL` 秒：
+
+1. 把卡在「处理中」超过 `BATCH_LOST_TASK_STALE` 秒的任务重置回「待处理」
+2. 认领「待处理」任务（置为处理中），最多 `BATCH_PUSH_LIMIT` 个，推进 Redis 队列 `<ns>:batch_pending`
+3. 按任务表统计刷新批次记录的 done / fail / total，打印「批次进度 X/Y」
+4. 所有任务都已结算（完成 + 失败 == 总数）→ 批次记录 `is_done=1`，置 `<ns>:batch_done` 标志
+
+## 换存储后端
+
+默认落 MySQL（`MysqlBatchStore`）。测试或小规模内存跑批可传 `batch_store=`：
+
+```python
+from mineworker.core.batch_store import MemoryBatchStore
+
+store = MemoryBatchStore([{"id": 1, "url": "..."}, {"id": 2, "url": "..."}])
+CrawlTask(batch_store=store).start_monitor(once=True)
+```
+
+自定义后端继承 `mineworker.core.batch_store.BatchStore`。
+
+## 配置
+
+| 配置 | 默认 | 说明 |
+|---|---|---|
+| `BATCH_INTERVAL` / `BATCH_INTERVAL_UNIT` | `7` / `"day"` | 批次间隔（`day` \| `hour`） |
+| `BATCH_MONITOR_INTERVAL` | `10.0` | master 巡检间隔（秒） |
+| `BATCH_LOST_TASK_STALE` | `600.0` | 「处理中」超过这么久算丢，重置回待处理 |
+| `BATCH_PUSH_LIMIT` | `5000` | master 单次最多认领 / 推送多少任务 |
+| `BATCH_TASK_ID_FIELD` | `"id"` | 任务表主键列名 |
+| `BATCH_TASK_STATE_FIELD` | `"batch_status"` | 任务表状态列名 |
+| `BATCH_TASK_TIME_FIELD` | `"update_time"` | 任务表更新时间列名 |
+
+队列 / 去重 / 命名空间沿用 [`Spider`](distributed.md) 那套（Redis）。

mineworker-0.4.0/docs/cli.md

@@ -0,0 +1,46 @@
+# 命令行
+
+需要 `pip install "mineworker[cli]"`。
+
+## create
+
+```bash
+mineworker create -p news_crawler      # 项目脚手架
+mineworker create -s ProductSpider     # 一个 AirSpider（写到 ./product_spider.py）
+mineworker create -i ProductItem       # 一个 Item
+mineworker create -i news --table news  # 读 MySQL 表结构反射字段（需 [mysql]）
+mineworker create --setting            # 一份注释齐全的 setting.py
+mineworker create -s Foo --force       # 覆盖已存在文件
+```
+
+名字会自动转换：`product-list` / `product_list` / `ProductList` 都能识别，
+生成 `class ProductListSpider` + 文件 `product_list_spider.py`。
+
+`-i --table <表名>` 会连 MySQL 读 `SHOW FULL COLUMNS`，按主键填 `__unique_key__` 并把字段
++ 注释列进 Item。连接默认取 `setting` 的 `MYSQL_*`，也可 `--mysql mysql://user:pwd@host:3306/db` 覆盖。
+
+## shell
+
+```bash
+mineworker shell https://example.com
+mineworker shell https://spa.example.com --render
+```
+
+抓一个页面进交互式 shell，绑定 `request` / `response` / `mw`。装了 IPython 用 IPython，
+否则用内置 REPL（带 tab 补全）。
+
+## retry
+
+```bash
+mineworker retry --items       # 重放 failed_items.jsonl 到当前 ITEM_PIPELINES
+mineworker retry --requests    # 重新下载 failed_requests.jsonl 里的 URL
+mineworker retry               # 两者都做
+```
+
+仍失败的记录写回文件，全部成功则删除文件。
+
+## 版本
+
+```bash
+mineworker --version
+```