feat(v1.8.0): 稳定性修复 + AI Agent 体验增强

稳定性修复:

- 修复 cache.py SQLite 连接泄漏(contextlib.closing 包装)

- 修复 fetch.py requests stream=True 连接泄漏(try/finally resp.close())

- RETRYABLE_STATUS 新增 403,激活 UA fallback 切换逻辑

- --cache-stats 移至实例解析前,无需实例即可查询

- classify_error 从错误消息提取 HTTP 状态码,正确分类 E_AUTH/E_RATE_LIMIT

- --stream 与 --queries-file 互斥检查,违规报 E_INPUT

- batch 退出码语义统一(0=有结果 / 1=全部错误 / 2=全部空结果)

AI Agent 体验增强:

- 错误码体系完善:E_CONFIG/E_AUTH/E_NETWORK/E_RATE_LIMIT/E_PARSE/E_EMPTY/E_INPUT/E_INTERNAL

- recovery_hint 恢复提示字段,AI Agent 可程序化决策恢复策略

- stream 模式新增 error 事件类型(含 error_code + recovery_hint)

- 进度事件扩展:instance_try/instance_ok/instance_fail

- batch 模式统一 schema(status 字段区分 success/failed)

- JSON 输出含 schema_version 字段确保版本兼容

测试与文档:

- 测试覆盖:330 -> 352

- SKILL.md / README.md 同步更新
This commit is contained in:
2026-08-01 19:02:44 +08:00
parent dea899143d
commit fb9b2af45f
12 changed files with 871 additions and 131 deletions
+11 -3
View File
@@ -22,6 +22,7 @@ Design notes:
cache failure must never break a search.
"""
import contextlib
import hashlib
import json
import os
@@ -40,8 +41,15 @@ def _cache_path() -> Path:
return DEFAULT_CACHE_DIR / "cache.db"
def _connect(path: Path) -> sqlite3.Connection:
"""Open a connection with WAL mode and ensure the schema exists."""
def _connect(path: Path):
"""Open a connection with WAL mode and ensure the schema exists.
Returns a :class:`contextlib.closing` wrapper so ``with _connect(...) as conn:``
closes the connection on exit. ``sqlite3.Connection.__exit__`` only commits /
rolls back the transaction — it does **not** call ``close()``, which leaks
file descriptors across many cache operations (especially under
``--queries-file`` + ``--cache-ttl`` batch runs).
"""
path.parent.mkdir(parents=True, exist_ok=True)
conn = sqlite3.connect(str(path), timeout=10)
# WAL allows concurrent readers alongside a single writer, which matters
@@ -59,7 +67,7 @@ def _connect(path: Path) -> sqlite3.Connection:
"""
)
conn.commit()
return conn
return contextlib.closing(conn)
def _make_key(params: dict) -> str: