netspy 1.0.0__py3-none-any.whl

netspy/__about__.py

@@ -0,0 +1,3 @@
+"""单一版本号来源（hatchling 从此处读取，`netspy.__version__` 亦转发于此）。"""
+
+__version__ = "1.0.0"

netspy/__init__.py

@@ -0,0 +1,81 @@
+"""Netspy —— 一个上手简单、结构清晰的 Python 爬虫框架。
+
+已提供：
+    - `setting`               分层配置（框架默认 ← 项目 setting.py ← 环境变量 NETSPY_*）
+    - `get_logger`            基于 loguru 的日志
+    - 异常层级                 NetspyError 及其子类
+    - `Request` / `Response`      网络层
+    - `AirSpider` / `BaseParser`  轻量单机运行时（含浏览器渲染、中间件、代理池、指标、告警）
+    - `Spider`                    Redis 分布式（多进程 / 多机 + 断点续爬，需 netspy[redis]）
+    - `TaskSpider`                从任务源（Redis / DB）持续拉任务来爬
+    - `BatchSpider`               周期性批次采集（MySQL 任务表 + 批次记录 + 进度 / 防丢）
+    - `Item` / `UpdateItem`       结构化数据 + 管道落库 + 去重
+"""
+
+from __future__ import annotations
+
+from netspy import setting
+from netspy.__about__ import __version__
+from netspy.core.base_parser import BaseParser
+from netspy.core.spiders.air_spider import AirSpider
+from netspy.core.spiders.batch_spider import BatchSpider
+from netspy.core.spiders.spider import Spider
+from netspy.core.spiders.task_spider import TaskSpider
+from netspy.exceptions import (
+    ConfigError,
+    DedupError,
+    ItemError,
+    NetspyError,
+    NotRetryError,
+    PipelineError,
+    RequestError,
+    ResponseError,
+    SpiderError,
+    ValidationError,
+)
+from netspy.network.item import Item, UpdateItem
+from netspy.network.request import Request
+from netspy.network.response import Response
+from netspy.network.user_pool import (
+    GuestUserPool,
+    LocalUserPool,
+    RedisUserPool,
+    User,
+    UserPool,
+)
+from netspy.utils.log import get_logger, log
+
+# 应用项目 setting.py 与环境变量覆盖，并按最终配置初始化日志
+setting.reload()
+get_logger()
+
+__all__ = [
+    "AirSpider",
+    "BaseParser",
+    "BatchSpider",
+    "ConfigError",
+    "DedupError",
+    "GuestUserPool",
+    "Item",
+    "ItemError",
+    "LocalUserPool",
+    "NetspyError",
+    "NotRetryError",
+    "PipelineError",
+    "RedisUserPool",
+    "Request",
+    "RequestError",
+    "Response",
+    "ResponseError",
+    "Spider",
+    "SpiderError",
+    "TaskSpider",
+    "UpdateItem",
+    "User",
+    "UserPool",
+    "ValidationError",
+    "__version__",
+    "get_logger",
+    "log",
+    "setting",
+]

netspy/buffer/__init__.py

@@ -0,0 +1,8 @@
+"""RequestBuffer / ItemBuffer（阶段 02–03）：去重、批量入队、管道分发。"""
+
+from __future__ import annotations
+
+from netspy.buffer.item_buffer import ItemBuffer
+from netspy.buffer.request_buffer import RequestBuffer
+
+__all__ = ["ItemBuffer", "RequestBuffer"]

netspy/buffer/item_buffer.py

@@ -0,0 +1,304 @@
+"""``ItemBuffer`` —— 收集 parse 产出的数据，批量去重后交给管道落库。
+
+流程：``put`` 累积 → 定时 / 满量 ``flush`` → 按 (表, 是否 UpdateItem, 管道) 分组
+→ Item 级去重（fingerprint）→ 逐管道 ``save_items`` / ``update_items``
+→ 成功则写去重指纹；失败则 dump 到 ``FAILED_ITEM_PATH``。
+
+**落库之后才给任务销账**：每条 item 记着产出它的那条请求（``owner``），一批写完
+（入库成功、或 dump 进 failed_items —— 两者都落到了持久介质）才回调 ``ack``。
+销账早于落库的话，节点被硬杀就会**静默丢数据**：数据只在内存里，而任务已经
+销过账不会被回收，请求指纹又是入队前就写的，重跑一遍也补不回来。
+
+给了 ``handler`` 时走调试快路径：直接把原始批次交给 handler，不去重、不落库。
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import defaultdict
+from collections.abc import Callable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, NamedTuple
+
+from netspy import setting
+from netspy.exceptions import ItemError
+from netspy.network.item import Item, UpdateItem
+from netspy.utils import stats as sk
+from netspy.utils import tools
+from netspy.utils.log import get_logger
+
+if TYPE_CHECKING:
+    from netspy.dedup import Dedup
+    from netspy.pipelines.base import BasePipeline
+    from netspy.utils.stats import Stats
+
+log = get_logger("item_buffer")
+
+ItemHandler = Callable[[list[Any]], None]
+
+
+class _Norm(NamedTuple):
+    table: str
+    is_update: bool
+    data: dict[str, Any]
+    fingerprint: str | None
+    update_keys: tuple[str, ...]
+    pipelines: tuple[str, ...] | None
+
+
+def _normalize(obj: Any) -> _Norm:
+    if isinstance(obj, Item):
+        obj.pre_to_db()
+        is_update = isinstance(obj, UpdateItem)
+        keys = tuple(obj.update_key) if isinstance(obj, UpdateItem) else ()
+        fp = obj.fingerprint if setting.ITEM_FILTER_ENABLE else None
+        pipes = tuple(obj.pipelines) if obj.pipelines else None
+        return _Norm(obj.table_name, is_update, obj.to_dict(), fp, keys, pipes)
+    if isinstance(obj, dict):
+        return _Norm(setting.ITEM_DEFAULT_TABLE, False, obj, None, (), None)
+    raise ItemError(f"无法入库的类型：{type(obj)!r}（需要 Item 或 dict）")
+
+
+class ItemBuffer(threading.Thread):
+    def __init__(
+        self,
+        stats: Stats,
+        *,
+        handler: ItemHandler | None = None,
+        pipelines: list[str] | None = None,
+        dedup: Dedup | None = None,
+        ack: Callable[[Any], None] | None = None,
+    ) -> None:
+        super().__init__(name="item-buffer", daemon=True)
+        self._stats = stats
+        self._handler = handler
+        self._pipeline_paths = pipelines
+        self._pipeline_cache: dict[tuple[str, ...], list[BasePipeline]] = {}
+        self._dedup = dedup
+        #: 落库成功后给任务销账。分布式下就是 ``Collector.done``
+        self._ack = ack
+        #: (item, 产出它的请求) —— owner 为 None 表示没人等着它销账
+        self._pending: list[tuple[Any, Any]] = []
+        #: 按 owner 挂的「落库之后再做」回调。BatchSpider 用它把任务表的
+        #: 「已完成」推迟到数据真的落库之后 —— 否则任务标了 DONE 而数据还在内存里，
+        #: 节点一死，防丢机制只回收 DOING，这些任务永远不会被重跑
+        self._after_persist: dict[int, list[Any]] = {}
+        self._lock = threading.Lock()
+        self._stop_event = threading.Event()
+
+    # ------------------------------------------------------------------
+    def owns(self, owner: Any) -> bool:
+        """`owner` 还有 item 压在缓冲里没落库吗。
+
+        已经 flush 过就返回 False —— 那时数据已经在库里，调用方可以立刻动作。
+        """
+        with self._lock:
+            return any(o is owner for _, o in self._pending)
+
+    def after_persist(self, owner: Any, fn: Any) -> None:
+        """`owner` 产出的数据整批落库之后再执行 `fn`。
+
+        落库失败时**不执行** —— 让上游的状态留在「处理中」，由防丢机制回收重跑。
+        """
+        with self._lock:
+            self._after_persist.setdefault(id(owner), []).append(fn)
+
+    def put(self, item: Any, owner: Any = None) -> None:
+        with self._lock:
+            self._pending.append((item, owner))
+            size = len(self._pending)
+        if size >= setting.ITEM_MAX_CACHED_COUNT:
+            self.flush()
+
+    def is_empty(self) -> bool:
+        with self._lock:
+            return not self._pending
+
+    def pending_count(self) -> int:
+        with self._lock:
+            return len(self._pending)
+
+    def run(self) -> None:
+        while not self._stop_event.wait(setting.BUFFER_FLUSH_INTERVAL):
+            self.flush()
+        self.flush()
+
+    def stop(self) -> None:
+        self._stop_event.set()
+
+    def close(self) -> None:
+        for pipelines in self._pipeline_cache.values():
+            for pipeline in pipelines:
+                try:
+                    pipeline.close()
+                except Exception:
+                    log.exception("管道 {} close 异常", type(pipeline).__name__)
+        self._pipeline_cache.clear()
+
+    # ------------------------------------------------------------------
+    def flush(self) -> None:
+        with self._lock:
+            batch = self._pending
+            self._pending = []
+        if not batch:
+            return
+        objs = [obj for obj, _ in batch]
+        # 同一条请求可能产出多条 item，按 id 去重后只销一次账
+        owners = {id(owner): owner for _, owner in batch if owner is not None}
+        if self._handler is not None:
+            self._handler(objs)
+            self._stats.incr(sk.ITEM, len(objs))
+            self._ack_all(owners.values())
+            return
+        try:
+            self._persist(objs)
+        except Exception:
+            # 销账早于落库正是这个模块要堵的洞，所以这里**不能**销账。
+            # 不销账的任务会在租约到期后被别的节点重抓 —— 数据至少还有第二次机会。
+            # 顺带保住 flush 线程：以前这里一抛，整个 ItemBuffer 线程就悄悄死了
+            log.exception("落库异常，本批 {} 条不销账，等租约到期重抓", len(objs))
+            return
+        self._ack_all(owners.values())
+
+    def _ack_all(self, owners: Any) -> None:
+        for owner in owners:
+            self._run_after_persist(owner)
+            if self._ack is None:
+                continue
+            try:
+                self._ack(owner)
+            except Exception:
+                log.exception("任务销账失败")
+
+    def _run_after_persist(self, owner: Any) -> None:
+        with self._lock:
+            hooks = self._after_persist.pop(id(owner), None)
+        for fn in hooks or ():
+            try:
+                fn()
+            except Exception:
+                log.exception("落库后回调异常")
+
+    def _persist(self, batch: list[Any]) -> None:
+        dedup = self._get_dedup()
+        seen: set[str] = set()
+        groups: dict[tuple[str, bool, tuple[str, ...] | None], list[_Norm]] = defaultdict(list)
+        degraded = False
+        for obj in batch:
+            norm = _normalize(obj)
+            if norm.fingerprint is not None and dedup is not None:
+                try:
+                    duplicate = norm.fingerprint in seen or dedup.get(norm.fingerprint)
+                except Exception:
+                    # 查重也是一次 Redis 调用。抛出去的话异常会穿出这个循环，
+                    # 后面的数据既不写库、也不 dump ——
+                    # 实测 9 条数据在第 3 条上抖一次：整批 9 条全丢。
+                    # 去重是优化，丢数据不是可选项：按「没见过」放行
+                    degraded = True
+                    duplicate = False
+                if duplicate:
+                    self._stats.incr(sk.ITEM_DEDUP_DROPPED)
+                    continue
+                seen.add(norm.fingerprint)
+            groups[(norm.table, norm.is_update, norm.pipelines)].append(norm)
+
+        for (table, is_update, pipe_paths), rows in groups.items():
+            datas = [row.data for row in rows]
+            update_keys = list(rows[0].update_keys)
+            pipelines = self._resolve_pipelines(pipe_paths)
+            ok = all(
+                self._write(pipeline, table, is_update, datas, update_keys)
+                for pipeline in pipelines
+            )
+            if ok:
+                self._stats.incr(sk.ITEM, len(datas))
+                if dedup is not None:
+                    try:
+                        for row in rows:
+                            if row.fingerprint is not None:
+                                dedup.add(row.fingerprint)
+                    except Exception:
+                        # 数据已经写进去了，指纹没记上 —— 重抓时会重复入库。
+                        # 但让异常穿出去更糟：后面的分组会一起丢
+                        # （实测第一组写成功、剩下 6 条凭空消失）
+                        degraded = True
+            else:
+                self._dump_failed(
+                    table,
+                    datas,
+                    update_keys=update_keys if is_update else None,
+                    pipelines=pipe_paths,
+                )
+
+        if degraded:
+            # 按批记一次，别每条都刷屏；但必须记 —— 静默降级就是把一种无声换成另一种
+            self._stats.incr(sk.DEDUP_DEGRADED)
+            log.warning("Item 去重不可用，本批按「没见过」放行 —— 可能重复入库")
+
+    # ------------------------------------------------------------------
+    def _get_dedup(self) -> Dedup | None:
+        if not setting.ITEM_FILTER_ENABLE:
+            return None
+        if self._dedup is None:
+            from netspy.dedup import get_item_filter
+
+            self._dedup = get_item_filter()
+        return self._dedup
+
+    def _resolve_pipelines(self, paths: tuple[str, ...] | None) -> list[BasePipeline]:
+        key = (
+            paths
+            if paths is not None
+            else tuple(
+                self._pipeline_paths if self._pipeline_paths is not None else setting.ITEM_PIPELINES
+            )
+        )
+        cached = self._pipeline_cache.get(key)
+        if cached is None:
+            cached = [tools.load_object(path)() for path in key]
+            self._pipeline_cache[key] = cached
+        return cached
+
+    def _write(
+        self,
+        pipeline: BasePipeline,
+        table: str,
+        is_update: bool,
+        datas: list[dict[str, Any]],
+        update_keys: list[str],
+    ) -> bool:
+        try:
+            if is_update:
+                return pipeline.update_items(table, datas, update_keys)
+            return pipeline.save_items(table, datas)
+        except Exception:
+            log.exception("管道 {} 写入异常", type(pipeline).__name__)
+            return False
+
+    def _dump_failed(
+        self,
+        table: str,
+        datas: list[dict[str, Any]],
+        *,
+        update_keys: list[str] | None = None,
+        pipelines: tuple[str, ...] | None = None,
+    ) -> None:
+        """把写失败的一批落到磁盘，**带上回放所需的全部信息**。
+
+        只记 table + data 是不够的：`UpdateItem` 回放时会退化成普通 INSERT，
+        而 PG 默认 `ON CONFLICT DO NOTHING` 会让这条 INSERT 什么都不做**并返回成功** ——
+        于是 retry 报告成功、删掉文件，那次更新永久消失。
+
+        字段是可选的：老的 dump 文件没有它们，读的时候按普通插入处理（即今天的行为）。
+        """
+        path = Path(setting.FAILED_ITEM_PATH)
+        extra: dict[str, Any] = {}
+        if update_keys:
+            extra["update_keys"] = list(update_keys)
+        if pipelines:
+            extra["pipelines"] = list(pipelines)
+        with path.open("a", encoding="utf-8") as fh:
+            for data in datas:
+                fh.write(tools.dumps_json({"table": table, "data": data, **extra}) + "\n")
+        self._stats.incr(sk.ITEM_FAILED, len(datas))
+        log.error("[{}] {} 条数据写入失败，已 dump 到 {}", table, len(datas), path)

netspy/buffer/request_buffer.py

@@ -0,0 +1,140 @@
+"""``RequestBuffer`` —— 收集 yield 出的 Request，去重后批量写入任务队列。"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING, Any
+
+from netspy import setting
+from netspy.dedup import get_request_filter
+from netspy.utils import stats as stats_keys
+from netspy.utils.log import get_logger
+
+if TYPE_CHECKING:
+    from netspy.dedup import Filter
+    from netspy.network.request import Request
+    from netspy.utils.stats import Stats
+
+
+log = get_logger("buffer")
+
+
+class RequestBuffer(threading.Thread):
+    def __init__(
+        self,
+        task_queue: Any,
+        stats: Stats,
+        *,
+        dedup: Filter | None = None,
+    ) -> None:
+        super().__init__(name="request-buffer", daemon=True)
+        self._queue = task_queue
+        self._stats = stats
+        self._dedup = dedup if dedup is not None else get_request_filter()
+        self._pending: list[Request] = []
+        self._lock = threading.Lock()
+        self._stop_event = threading.Event()
+
+    # ------------------------------------------------------------------
+
+    @property
+    def dedup(self) -> Filter:
+        """实际在用的去重过滤器 —— 构造时传进来的可能是 None，这里给出真正生效的那个。"""
+        return self._dedup
+
+    def put(self, request: Request) -> None:
+        with self._lock:
+            self._pending.append(request)
+        if len(self._pending) >= setting.REQUEST_BUFFER_MAX_CACHED:
+            self.flush()
+
+    def put_retry(self, request: Request) -> None:
+        """重试请求：跳过去重再次入队。"""
+        request.filter_repeat = False
+        self.put(request)
+
+    def is_empty(self) -> bool:
+        with self._lock:
+            return not self._pending
+
+    def pending_count(self) -> int:
+        with self._lock:
+            return len(self._pending)
+
+    # ------------------------------------------------------------------
+    def flush(self) -> None:
+        """把缓冲区里的请求推进队列。**出错时不丢**：没入队的放回去下轮重试。
+
+        原来是「先把整批从 `_pending` 摘走，再逐个 put」—— 队列一次抖动
+        （Redis 断连 / OOM / 网络闪断），剩下的请求既不在 `_pending`、
+        也没进队列、也没像 Item 那样 dump 到文件，**静默消失**。
+        实测 10 个请求、第 3 个上抖一次：丢 8 个。
+
+        放回去还有个坑：`dedup.add()` 是在入队**之前**写指纹的，所以重试时
+        会被自己刚写下的那条指纹挡掉、当成重复丢弃 —— 等于没救回来。
+        因此放回的请求要清掉 `filter_repeat`：它们**已经过过去重**了。
+        """
+        with self._lock:
+            batch = self._pending
+            self._pending = []
+        for i, request in enumerate(batch):
+            try:
+                fresh = self._dedup.add(request.fingerprint) if request.filter_repeat else True
+            except Exception:
+                # 写指纹也是一次 Redis 调用，和下面的入队一样会抖。
+                # 这一条**没写成指纹**，所以放回时要保留 filter_repeat
+                self._requeue(batch[i:], first_passed_dedup=False)
+                raise
+            if not fresh:
+                self._stats.incr(stats_keys.DEDUP_DROPPED)
+                continue
+            try:
+                self._queue.put(request)
+            except Exception:
+                # 这一条和它后面的都还没入队，整体放回缓冲区。
+                # 这一条**已经写成指纹**了，放回时要清掉 filter_repeat
+                self._requeue(batch[i:], first_passed_dedup=True)
+                raise
+
+    def _requeue(self, requests: list[Request], *, first_passed_dedup: bool) -> None:
+        """把没能入队的请求放回缓冲区头部，保持原有顺序（优先级靠队列自己排）。
+
+        只有**第一条**可能已经过了去重 —— 它的指纹写成了、失败发生在入队那一步。
+        它必须清掉 `filter_repeat`，否则下一轮会被自己刚写的指纹挡掉（v4.7 修的就是这个）。
+
+        后面那些根本没走到去重。**它们必须保留 `filter_repeat`** ——
+        一起清掉的话，重复 URL 会绕过去重进队列。
+        实测：批次里两条相同 URL、`put` 抖一次，同一个 URL 进队列 2 次。
+        """
+        if first_passed_dedup and requests:
+            requests[0].filter_repeat = False
+        with self._lock:
+            self._pending[:0] = requests
+
+    def drain_pending(self) -> list[Request]:
+        with self._lock:
+            batch = self._pending
+            self._pending = []
+        return batch
+
+    def run(self) -> None:
+        while not self._stop_event.wait(setting.BUFFER_FLUSH_INTERVAL):
+            self._flush_guarded()
+        self._flush_guarded()
+
+    def _flush_guarded(self) -> None:
+        """后台线程里的 flush 必须兜住异常。
+
+        原来是裸调 `flush()` —— 队列一次抖动就把整个缓冲区线程打死，此后**所有**
+        请求都不再进队列，爬虫静默停止发现新页面（实测线程存活 False）。
+
+        但也不能静默吞掉：不留日志就只是把一种静默换成另一种。请求已经由
+        `flush` 放回缓冲区，下一轮自然重试。
+        """
+        try:
+            self.flush()
+        except Exception:
+            log.exception("请求入队失败，{} 条留在缓冲区等下轮重试", len(self._pending))
+
+    def stop(self) -> None:
+        self._stop_event.set()

netspy/commands/__init__.py

@@ -0,0 +1,21 @@
+"""命令行（阶段 05）：typer 应用 + create / shell / retry 子命令。
+
+需要 ``pip install netspy[cli]``（typer + jinja2）。
+"""
+
+from __future__ import annotations
+
+
+def main() -> None:
+    """``netspy`` 控制台脚本入口。
+
+    脚本随核心包一起装，但 CLI 依赖只在 ``[cli]`` extra 里。缺依赖时给一句照着做就能
+    修好的提示，而不是甩一个 ``ModuleNotFoundError`` 堆栈给刚 ``pip install`` 完的人。
+    """
+    try:
+        from netspy.commands.cmdline import main as _main
+    except ModuleNotFoundError as exc:  # pragma: no cover - 走到这里说明没装 [cli]
+        raise SystemExit(
+            f'netspy 命令行需要额外依赖（缺少 "{exc.name}"）。\n安装：pip install "netspy[cli]"'
+        ) from exc
+    _main()

netspy/commands/cmdline.py

@@ -0,0 +1,127 @@
+"""``netspy`` 命令行入口（typer）。"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from netspy.__about__ import __version__
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Netspy 爬虫框架命令行",
+)
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(f"netspy {__version__}")
+        raise typer.Exit
+
+
+@app.callback()
+def _root(
+    version: Annotated[
+        bool,
+        typer.Option("-V", "--version", callback=_version, is_eager=True, help="版本号"),
+    ] = False,
+) -> None:
+    pass
+
+
+@app.command()
+def create(
+    project: Annotated[str | None, typer.Option("-p", "--project", help="生成项目脚手架")] = None,
+    spider: Annotated[str | None, typer.Option("-s", "--spider", help="生成一个 AirSpider")] = None,
+    item: Annotated[str | None, typer.Option("-i", "--item", help="生成一个 Item")] = None,
+    table: Annotated[
+        str | None,
+        typer.Option("--table", help="配合 -i：读该 MySQL 表结构反射字段"),
+    ] = None,
+    mysql: Annotated[
+        str | None,
+        typer.Option("--mysql", help="MySQL 连接串 mysql://user:pass@host/db（默认取 setting）"),
+    ] = None,
+    setting_file: Annotated[bool, typer.Option("--setting", help="生成 setting.py")] = False,
+    force: Annotated[bool, typer.Option("-f", "--force", help="覆盖已存在文件")] = False,
+) -> None:
+    """生成项目 / 爬虫 / Item / 配置文件。"""
+    from netspy.commands import create as gen
+
+    if project:
+        root = gen.create_project(project, force=force)
+        typer.echo(f"✓ 项目已生成 → cd {root} && python main.py")
+    elif spider:
+        typer.echo(f"✓ {gen.create_spider(spider, force=force)}")
+    elif item:
+        typer.echo(f"✓ {gen.create_item(item, force=force, table=table, mysql=mysql)}")
+    elif setting_file:
+        typer.echo(f"✓ {gen.create_setting(force=force)}")
+    else:
+        typer.echo("指定 -p / -s / -i / --setting 之一", err=True)
+        raise typer.Exit(1)
+
+
+@app.command()
+def shell(
+    url: Annotated[str, typer.Argument(help="要抓取的 URL")],
+    render: Annotated[bool, typer.Option("--render", help="用浏览器渲染")] = False,
+) -> None:
+    """抓一个页面并进入交互式 shell（变量 request / response）。"""
+    from netspy.commands.shell import run_shell
+
+    run_shell(url, render=render)
+
+
+@app.command()
+def retry(
+    requests: Annotated[
+        bool, typer.Option("--requests", help="回放 failed_requests.jsonl")
+    ] = False,
+    items: Annotated[bool, typer.Option("--items", help="回放 failed_items.jsonl")] = False,
+) -> None:
+    """回放 dump 文件里的失败请求 / 数据（默认两者都回放）。"""
+    from netspy.commands.retry import retry_items, retry_requests
+
+    if not requests and not items:
+        requests = items = True
+    if items:
+        ok, failed = retry_items()
+        typer.echo(f"failed_items：成功 {ok}，仍失败 {failed}")
+    if requests:
+        ok, failed = retry_requests()
+        typer.echo(f"failed_requests：恢复 {ok}，仍失败 {failed}")
+
+
+@app.command()
+def cache(
+    clear: Annotated[bool, typer.Option("--clear", help="清空响应缓存目录")] = False,
+) -> None:
+    """查看 / 清理响应缓存（`RESPONSE_CACHE_PATH`）。
+
+    改了解析逻辑想重新抓一遍真实页面时，清一下就行 —— 不必等过期。
+    """
+    from pathlib import Path
+
+    from netspy import setting
+    from netspy.network import cache as cache_mod
+
+    root = Path(setting.RESPONSE_CACHE_PATH)
+    if clear:
+        typer.echo(f"已清理 {cache_mod.clear()} 条缓存（{root}）")
+        return
+    entries = list(root.rglob("*.json")) if root.is_dir() else []
+    size = sum(e.stat().st_size for e in entries)
+    typer.echo(f"{root}：{len(entries)} 条，{size / 1024 / 1024:.1f}MB")
+    if not setting.RESPONSE_CACHE_ENABLE:
+        typer.echo("提示：RESPONSE_CACHE_ENABLE 当前是关的，缓存不会被读写")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()