 thzxx
|
0c8fdc1e45
|
fix(v2.1.1): 修复执行问题记录中的真实 bug + 文档对齐
源码修复（5 项）:
1. search.py --time-range choices 加入 week（对齐 SearXNG API 四档）
2. fetch.py stdlib 路径处理 gzip/deflate 解压（被沙箱伪响应掩盖的真实 bug，
无 requests 环境抓取压缩服务器会全页 U+FFFD 乱码）
3. search.py --research 模式实现跨角度合并去重，输出 merged_results 字段
（兑现文档承诺 "Results are merged and deduplicated"）
4. search.py fetch_page 返回 error_code 字段 + AdaptiveThrottle 用
E_RATE_LIMIT 结构化检测 429（原字符串匹配 "429" 会漏判
"Too Many Requests"）
5. search.py _retry_with_backoff 复用 compute_backoff_delay（60s 封顶）
+ 处理 Retry-After header，与 fetch.py 保持一致
增强（3 项）:
- common.py 精确化 baidu 子域列表（pan.baidu.com/cloud.baidu.com 不再误伤）
- search.py expand_research_queries 根据主题语言切换中英文后缀
- search.py 新增 _warn_unresponsive_engines，识别实例侧引擎挂起并提示
文档/版本:
- _config.py VERSION 2.1.0 → 2.1.1
- SKILL.md 同步更新（time-range week、merged_results、error_code、baidu 精确化）
- README.md 同步更新 + 测试数量 503 → 539
测试: 539 个全部通过，含 6 个新增验证测试
|
2026-08-03 12:54:27 +08:00 |
|
|
thzxx
|
e94cbe0783
|
feat(v2.1.0): 研究模式 + fetch.py Wayback 兜底 + 被墙站点智能回退
A. fetch.py 补齐 Wayback 兜底 (修复重大 gap)
- v2.0.1 gap: fetch.py 独立调用 403 时无 Wayback 兜底 (仅 search.py --fetch 有)
- AI Agent 用 fetch.py -u URL 直接抓取被墙站点时, 403 后无任何回退
- 修复: fetch.py main() 增加 Wayback 兜底逻辑 + --no-fallback flag
- 共享逻辑抽取到 common.py: should_try_wayback() + build_wayback_url()
B. --research 研究模式
- 给定主题自动扩展 5 个多角度查询: overview/profile/background/works/review
- 确定性规则 (不依赖 AI 判断), 跨进程可复现
- 输出含 research_topic + research_queries 元数据, AI Agent 可按角度结构化汇编
- 与 --query/--queries-file 互斥, 支持所有输出格式 (json/brief/urls/csv)
- 三态退出码: 0=有结果, 2=全部空, 1=全部错误
C. 被墙站点智能回退
- common.py 增加 HARD_BLOCKED_DOMAINS: 百度百科/知乎/微博/微信公众号/豆瓣等
- is_hard_blocked_domain() 精确匹配 + 子域匹配
- 命中被墙站点时: 主抓取失败后立即 Wayback (不等 should_try_wayback 判断)
- search.py _should_try_fallback 增加 url 参数, 被墙站点直接触发兜底
真实测试验证 (search.metona.cn 实例):
- fetch.py 百度百科兜底: 403 → Wayback 恢复 150,493 chars ✓
- --research 模式: 5 角度查询扩展 + research 元数据 + 三态退出码 ✓
- 被墙站点检测: Hard-blocked domain detected 日志 + 自动 Wayback ✓
测试: 503 个全部通过 (新增 45 个: test_wayback_shared + test_research_mode)
来源: 另一个 AI Agent 反馈 Wikipedia/百度百科/知乎 fetch 失败, 需要多角度搜索+失败回退+被墙站点列表
|
2026-08-02 08:27:45 +08:00 |
|
|
thzxx
|
b62095570d
|
docs(SKILL.md): 铁律新增第 1 条 - 加载技能后禁止使用其他搜索/抓取工具
明确要求 AI Agent 加载本技能后, 搜索和抓取必须且只能使用 scripts/search.py 和 scripts/fetch.py, 禁止 WebSearch/WebFetch/curl/wget/浏览器自动化/第三方 SDK/自写脚本/MCP 网络工具等任何替代方式
理由: 本技能已内置反爬(UA 轮换+浏览器指纹头+WAF 检测)/重试(指数退避+Retry-After)/兜底(Wayback)/限流(自适应节流)/缓存/多实例故障转移等工程能力, 绕过等于放弃保障且可能封禁用户实例
原 5 条铁律顺延为 2-6 条
|
2026-08-01 21:47:45 +08:00 |
|
|
thzxx
|
d9a08716bc
|
fix(v2.0.1): 修复反爬误判 + Wayback 兜底未触发两个 bug
Bug 1: Wayback 兜底未触发 (search.py fetch_page)
- 根因: Cloudflare JS 质询页常返回 HTTP 200 (非 403), 主抓取 result 非 None
- _should_try_fallback 在 result 非 None 时直接返回 False, 跳过兜底
- 反爬检测在兜底判断之后执行, 错过兜底入口
- 修复: 反爬检测提前到兜底判断之前, anti_bot_detected=True 也触发 Wayback
- Wayback 结果重新做反爬检测 (防御性)
Bug 2: WAF 指纹库误判正常内容 (search.py WAF_FINGERPRINTS)
- 根因: 裸公司名 (cloudflare/akamai) 和宽泛词 (captcha/challenge/dd-) 做全文匹配
- DataCamp 文章引用 cloudflare.com 文档链接 -> 误判为 cloudflare WAF
- 'coding challenges' 正常内容 -> 误判为 generic 反爬
- Wayback 归档正文被误判, 兜底返回的有效内容被丢弃
- 修复: 移除裸公司名和宽泛词, 改用技术标识符 (cf-ray/incap_ses/bm_sz 等)
- 通用文案用完整短语 (please complete the captcha) 替代单词
- 增加 <title> 标签精准检测 (反爬页 title 是特征文案, 误判率极低)
- 新增 Anubis 反爬系统检测 (anubis_challenge/miserere)
真实测试验证 (search.metona.cn 实例):
- v2.0.0: --fetch 3 全部失败 (3 ERR: cloudflare/generic, Wayback 未触发)
- v2.0.1: --fetch 3 全部成功 (3 OK: 38100/93442/1945 chars, UA 轮换绕过 Cloudflare)
测试: 458 个全部通过 (新增 7 个测试覆盖修复行为)
|
2026-08-01 21:44:58 +08:00 |
|
|
thzxx
|
28ff7c0a48
|
feat(v2.0.0): 反爬增强 + 抓取稳定性大幅提升
反爬措施:
- 浏览器指纹头 build_browser_headers(): Sec-Ch-Ua/Sec-Fetch-*/Accept-Language/Accept-Encoding, 绕过 80%+ 轻量 WAF
- 12 个 UA 池 (Chrome/Edge/Firefox x Win/macOS/Linux x v129-131)
- 确定性 UA 轮换 get_ua_for_domain(): SHA-256 按域名固定 UA, 会话内稳定跨进程可复现
- WAF 指纹库 _detect_anti_bot(): 识别 Cloudflare/Imperva/PerimeterX/DataDome/Akamai/通用, 全文档扫描
- Retry-After 遵守: 429/503 读取 header (数字或 HTTP date) 作为最小重试延迟
- 退避封顶 60s (原无上限, N=10 时 1536s 卡死进程)
抓取稳定性:
- requests.Session 复用: 连接池(10/host) + cookie 持久化 + TLS 会话恢复
- 超时分离 (connect, read) 元组, 避免大页面浪费已建连接
- Wayback Machine 兜底: 404/403/超时自动重试 web.archive.org, 默认启用 --no-fallback 关闭
- AdaptiveThrottle 自适应限流: 3 次失败翻倍延迟+减半并发, 5 次成功渐进恢复, 429 全局暂停 30s
- readability-lite 提取: article/main 缺失时按文本密度选最可能正文 div
新增 CLI flags:
- --fetch-report: 结构化抓取报告到 stderr (每 URL 状态/WAF 类型/兜底方式/字符数 + JSON 摘要)
- --no-fallback: 禁用 Wayback 兜底
- --referer: 设置 Referer 头 (默认实例 URL)
- --request-delay: 抓取请求间隔秒数 (默认 0.3, 自适应可能增大)
fetch 结果新字段: anti_bot_detected (bool), waf_type (str|null), fallback_used (str|null)
测试: 新增 4 个测试文件 (test_browser_headers/test_anti_bot/test_wayback_fallback/test_adaptive_throttle), 451 个测试全部通过
|
2026-08-01 21:34:57 +08:00 |
|
|
thzxx
|
ea7a60a460
|
fix(test): subprocess 显式指定 encoding=utf-8，修复 Windows GBK 解码崩溃
_run_cli 辅助函数的 subprocess.run 用 text=True 但未指定 encoding，Windows 中文系统默认用 GBK 解码子进程输出，--help 的非 ASCII 字符（box-drawing/em-dash）触发 UnicodeDecodeError。显式指定 encoding='utf-8' 与脚本的 force_utf8_stdout() 对齐。
测试: 362/362 全部通过
|
2026-08-01 20:57:08 +08:00 |
|
|
thzxx
|
f7cdc81c7f
|
feat(v1.8.1): Windows 兼容性修复 + SKILL.md 铁律区块
Windows 兼容性修复（基于真实使用痛点）:
- force_utf8_stdout(): 强制 stdout/stderr 为 UTF-8，修复 Windows GBK 崩溃（print('\\xa0') 不再炸）
- resolve_instances/load_config 新增 %APPDATA%/searxng-cli/ 路径，覆盖 Windows 配置约定
- fetch.py 失败诊断增强：输出 status_code=/cause=/url= 字段，AI Agent 可程序化区分 404/403/DNS 失败
SKILL.md 铁律区块（5 条，置顶）:
- stdout=数据/stderr=日志 永不混淆
- 禁用 2>/dev/null（丢弃 stderr = 失败时零诊断）
- 排错去 --quiet 加 --verbose
- 配置查找覆盖 WSL + Windows 双路径
- 实例 URL 必填，公共实例发现已移除
测试: 352 -> 362（新增 10 个：force_utf8_stdout 幂等性/GBK 替换/非 ASCII 打印/APPDATA 路径发现/txt 回退/空 APPDATA）
|
2026-08-01 20:50:42 +08:00 |
|
|
thzxx
|
657af0a221
|
docs: 精简 SKILL.md，移除 AI Agent 无关章节
删除：SearXNG Search API Quick Reference、Common Workflow、Troubleshooting、Common Pitfalls、Verification Checklist
精简：Cross-Agent Compatibility 表格压缩为段落
SKILL.md: 43KB -> 30KB（-32%），聚焦 AI Agent 核心需求
|
2026-08-01 19:36:23 +08:00 |
|
|
thzxx
|
fb9b2af45f
|
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 同步更新
|
2026-08-01 19:02:44 +08:00 |
|
|
thzxx
|
dea899143d
|
feat: searxng.toml 支持 auth_basic/auth_bearer 认证配置
- common.py: resolve_auth_basic/bearer 新增 config_value 参数，优先级 CLI > file > config > env
- search.py: main() 从 load_config() 读取 auth_basic/auth_bearer；修复 --config 指定文件中 instance 字段不被解析的问题
- LICENSE: 补齐 MIT 协议文件
- tests: +21 测试覆盖配置文件认证优先级链与 main() 集成（309→330）
- docs: SKILL.md/README.md 同步更新认证配置说明与安全提醒
|
2026-08-01 18:01:32 +08:00 |
|
|
thzxx
|
f983a9377e
|
feat(v1.7.0): AI 友好度增强 + 测试补全 (155→309)
核心新增（面向 AI Agent 程序化使用）：
- 结构化错误码体系：E_CONFIG/E_AUTH/E_NETWORK/E_RATE_LIMIT/E_PARSE/E_EMPTY/E_INPUT/E_INTERNAL
classify_error() 自动分类异常，JSON 错误输出含 error_code 字段
- JSON Lines 流式输出 (--stream)：每条结果独立一行，AI 可增量处理
- 进度事件 (--progress)：JSON Lines 事件流到 stderr（start/cache_hit/fetch_ok/done 等）
测试补全（+154 例，覆盖全部高风险盲区）：
- HTML 回退搜索路径 (19)
- --fetch 自动抓取 (21)
- --verify 健康检查 (15)
- 输出格式化 (15)
- 实例解析链 (20)
- 并行多实例搜索 (10)
- CLI 入口与端到端 (17)
- 错误码分类 (27)
- 流式输出与进度事件 (10)
源码改进：
- search.py: h3 内 a 标签 href 作为 url fallback，提升 SearXNG 主题兼容性
- common.py: 新增 classify_error/emit_progress/set_progress_enabled
文档同步：SKILL.md 新增 AI Agent Integration Guide 章节，README.md 更新参数与错误码表
|
2026-08-01 17:40:14 +08:00 |
|