标签。\n\n**输入参数**：\n\n```json\n{\n \"url\": {\n \"type\": \"string\",\n \"description\": \"目标网页 URL（必填）\"\n },\n \"timeout\": {\n \"type\": \"integer\",\n \"description\": \"抓取超时（秒），默认 10\",\n \"default\": 10\n }\n}\n```\n\n**响应格式**：\n\n```json\n{\n \"url\": \"https://example.com\",\n \"text\": \"正文内容...\",\n \"success\": true,\n \"length\": 1234\n}\n```\n\n---\n\n## 超时与降级策略\n\n### 超时配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `mcp_server.timeout` | 30s | 单次工具调用超时 |\n| `mcp_server.max_results` | 10 | search 工具默认最大结果数 |\n| `mcp_server.max_sources` | 5 | synthesize 工具默认最大引用来源数 |\n| `synthesis.fetch_timeout` | 10s | 单个页面抓取超时 |\n| `search.timeout` | 15s | 单个引擎搜索超时 |\n\n### 降级策略\n\n| 场景 | 降级行为 |\n|------|----------|\n| LLM API Key 未配置 | synthesize 自动降级为抽取式摘要 + 来源列表 |\n| LLM 调用失败 | 同上 |\n| 页面正文抓取失败 | 降级使用该结果的 snippet |\n| 所有页面正文抓取失败 | 降级为抽取式摘要 |\n| 搜索引擎限流 | 自动重试 + 指数退避 |\n| strict 模式引擎全部失败 | 默认拒绝降级（隐私优先），可配置 `allow_fallback` |\n\n### 错误处理\n\n所有工具调用返回统一的错误格式：\n\n```json\n{\n \"error\": \"错误描述\"\n}\n```\n\n---\n\n## 生态桥接示例\n\n### 其他 skill 接入本 MCP Server\n\n根据\"章首桥接原则\"，其他 skill 可按以下方式探测并调用 privacy-search：\n\n```python\n# 1. 探测 privacy-search 是否已安装\nimport shutil\ndef is_privacy_search_available() -> bool:\n return shutil.which(\"python\") is not None # 检查 python 环境\n\n# 2. 调用 MCP Server（stdio 模式）\nimport subprocess\nproc = subprocess.Popen(\n [\"python\", \"scripts/mcp_server.py\"],\n stdin=subprocess.PIPE,\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n)\n\n# 3. 发送 initialize 请求\nimport json\ndef send_request(proc, method, params=None):\n msg = {\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": method}\n if params:\n msg[\"params\"] = params\n body = json.dumps(msg, ensure_ascii=False)\n length = len(body.encode(\"utf-8\"))\n proc.stdin.write(f\"Content-Length: {length}\\r\\n\\r\\n{body}\".encode())\n proc.stdin.flush()\n # 读取响应...\n```\n\n### 典型调用场景\n\n| 调用方 | 场景 | 推荐工具 |\n|--------|------|----------|\n| gov-procurement | 政策资料查询 | `search` + `fetch` |\n| contract-review | 法条补充检索 | `search` + `synthesize` |\n| 其他 skill | 通用搜索 | `search` |\n\n---\n\n## 接口契约稳定性承诺\n\n1. **版本化 schema**：工具 schema 随 SKILL.md 版本号同步更新\n2. **向后兼容**：小版本（1.x）内不删除/重命名工具参数\n3. **降级保证**：所有外部依赖（LLM、搜索引擎）都有降级方案\n4. **超时可控**：所有网络调用都有可配置的超时\n\n---\n\n## 配置示例\n\n```yaml\n# config.yaml\nmcp_server:\n enabled: true\n timeout: 30\n max_results: 10\n max_sources: 5\n\nsynthesis:\n enabled: true\n api_key: \"\" # 留空则强制降级\n provider: auto\n max_sources: 5\n\nsearch:\n timeout: 15\n num_results: 10\n```\n\nFile v1.9.0:references/QUICK_START.md\n\n# 隐私搜索 - 5 分钟快速上手指南\n\n> 从零开始，5 分钟内完成安装并执行你的第一次隐私搜索。\n\n---\n\n## 🚀 一键安装（推荐）\n\n```bash\npython scripts/quick_setup.py\n```\n\n一键完成：创建 venv → 安装依赖 → 复制配置 → 验证安装。\n\n---\n\n## 📋 手动安装（如需控制每一步）\n\n### Step 1: 创建虚拟环境\n\n```bash\npython -m venv .venv\n# Windows\n.venv\\Scripts\\activate\n# Linux/macOS\nsource .venv/bin/activate\n```\n\n### Step 2: 安装依赖\n\n```bash\npip install -r requirements.txt\n```\n\n### Step 3: 复制配置\n\n```bash\ncp references/config.yaml.example config.yaml\n```\n\n### Step 4: 验证安装\n\n```bash\npython scripts/search.py \"test\"\n```\n\n---\n\n## 🔍 你的第一次搜索\n\n### 基础搜索（默认引擎）\n\n```bash\npython scripts/search.py \"Python asyncio 教程\"\n```\n\n输出示例：\n```\n🔍 搜索: Python asyncio 教程 | 模式: normal | 结果: 18 条\n\n[1] Python asyncio 异步编程入门教程\n https://docs.python.org/zh-cn/3/library/asyncio.html\n 本教程将带你了解 Python asyncio 模块的基础知识...\n — bing\n\n[2] 超详细的 Python asyncio 教程，从入门到精通\n https://www.cnblogs.com/...\n 本文详细介绍 Python asyncio 的使用方法...\n — baidu\n```\n\n### 隐私搜索（strict 模式）\n\n```bash\npython scripts/search.py \"Python asyncio 教程\" --privacy strict\n```\n\n输出示例：\n```\n搜索: Python asyncio 教程 | 模式: strict | 来源: 实时 | 结果: 12 条\n\n[1] Python Asynchronous Programming\n https://docs.python.org/3/library/asyncio.html\n Learn how to use asyncio for concurrent programming...\n — yandex\n\n[2] Async IO in Python: A Complete Walkthrough\n https://realpython.com/async-io-python/\n Async IO is a concurrent programming design...\n — startpage, qwant\n```\n\n> strict 模式仅使用 SearXNG/Yandex/Startpage/Qwant/Brave/DDG。\n> 即使显式指定 `--engines baidu` 也会被拒绝，避免隐私承诺被绕过。\n\n### 缓存加速\n\n相同查询在 1 小时内直接复用结果，输出标注「来源: 缓存」。\n\n```bash\npython scripts/search.py \"Python asyncio 教程\" # 来源: 实时\npython scripts/search.py \"Python asyncio 教程\" # 来源: 缓存，秒回\npython scripts/search.py \"Python asyncio 教程\" --no-cache # 强制刷新\n```\n\n### 引擎体检\n\n搜不到结果时，先判断是引擎坏了还是关键词没匹配：\n\n```bash\npython scripts/search.py --selftest\n```\n\n输出会标明每个引擎是「正常」「被拦截」还是「选择器失效」。\n\n### 显示错误诊断网络问题时\n\n```bash\npython scripts/search.py \"test\" --privacy strict --verbose\n```\n\n网络故障时的输出：\n```\n============================================================\n🔍 错误诊断报告：\n\n🌐 网络问题：\n ✗ duckduckgo: 网络连接失败: Connection timed out after 10s\n 1. 检查网络连接是否正常（ping www.baidu.com）\n 2. 确认网络环境不受限制\n\n🔧 引擎问题：\n ✗ yandex: 引擎解析或请求失败: HTML parser error\n 1. yandex 可能已更新页面结构\n 2. 暂不支持该引擎（可排除）\n```\n\n---\n\n## strict 模式可用引擎\n\n| 引擎 | 来源 | 国内速度 | 隐私保护 | 状态 |\n|------|------|---------|---------|------|\n| **SearXNG** | 本机 | ⭐⭐⭐⭐⭐ 极快 | 极高 | ✅ 最优先 |\n| **Yandex** | 俄罗斯 | ⭐⭐⭐⭐ 快 | 中等 | ✅ 默认启用 |\n| **Startpage** | 荷兰（Google 代理） | ⭐⭐⭐ 中等 | 高 | ✅ 默认启用 |\n| **Qwant** | 法国 | ⭐⭐⭐ 中等 | 高 | ✅ 默认启用 |\n| **Brave** | 美国 | ⭐⭐ 较慢 | 高 | ✅ 默认启用 |\n| **DuckDuckGo** | 美国 | ⭐ 不稳定 | 极高 | ⚠️ 最后备选 |\n\n优先顺序：SearXNG → Yandex → Startpage → Qwant → Brave → DuckDuckGo\n\n若以上全部不可用，默认**停止搜索**而非降级到国内引擎——因为 strict 用户的预期是宁可无结果也不泄露查询词。确需降级请加 `--allow-fallback`。\n\n---\n\n## 📝 推荐配置（首次只需改 3 项）\n\n```yaml\n# config.yaml - 新手推荐修改项\nsearch:\n default_engines: [\"baidu\", \"bing\", \"duckduckgo\", \"searxng\"] # ✅ 第1项\n timeout: 15 # ✅ 第2项（网速慢可增大）\n\nprivacy:\n default_mode: strict # ✅ 第3项（默认 privacy）\n```\n\n其他配置项暂不需要修改。\n\n### 想隐藏 IP\n\nstrict 模式不隐藏 IP，需自行配置代理：\n\n```yaml\nprivacy:\n strict:\n proxy: \"http://127.0.0.1:7890\" # 支持 http:// 与 socks5://\n```\n\n---\n\n## 🔧 启动 SearXNG（推荐）\n\nSearXNG 本地实例是 strict 模式的隐私基石，建议启动。\n\n### Docker 方式（推荐）\n\n```bash\npython scripts/searxng_manager start --method docker\n```\n\n### pip 方式（无 Docker）\n\n```bash\npython scripts/searxng_manager start --method pip\n```\n\n### 验证\n\n```bash\npython scripts/searxng_manager status\n# 应显示 running: true\n```\n\n---\n\n## ❓ 常见问题\n\n### Q1: 安装依赖失败？\n\n```bash\n# 换用国内镜像\npip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple\n```\n\n### Q2: SearXNG 启动失败？\n\nDocker 方式失败时，改用 pip：\n```bash\npython scripts/searxng_manager start --method pip\n```\n\n### Q3: 国内使用 strict 模式搜不到结果？\n\n按顺序自动尝试 Yandex → Startpage → Qwant → Brave → DDG。全部失败时默认停止并提示，不会静默降级。\n\n只用国内直连较好的几个：\n```bash\npython scripts/search.py \"关键词\" --privacy strict --engines yandex,startpage,qwant,searxng\n```\n\n确需降级到国内引擎：\n```bash\npython scripts/search.py \"关键词\" --privacy strict --allow-fallback\n```\n\n### Q4: 如何排除某个引擎？\n\n```bash\n# 排除 yandex，用其他 strict 引擎\npython scripts/search.py \"关键词\" --privacy strict --engines startpage,qwant,searxng\n```\n\n### Q5: 如何查看隐私保护详情？\n\n```bash\n# 独立的隐私报告\npython scripts/privacy report\n\n# 搜索时附带本次实际生效的隐私设置\npython scripts/search.py \"关键词\" --privacy strict --privacy-report\n```\n\n### Q6: 搜索记录会留在本地吗？\n\n会。缓存与历史存于 `~/.workbuddy/output/privacy-search-cache.db`。\n\n```bash\npython scripts/search.py --cache-stats # 查看占用\npython scripts/search.py --history # 查看历史\npython scripts/search.py --clear-cache # 清空缓存\npython scripts/search.py --clear-history # 清空历史\n```\n\n共享设备上建议在 config.yaml 设 `cache.enabled: false`。\n\n---\n\n## 📚 下一步\n\n- 完整文档 → [SKILL.md](../SKILL.md)\n- 搜索引擎适配器详情 → [engines_zh.md](engines_zh.md)\n- 配置说明 → [config.yaml.example](config.yaml.example)\n\n有建议？联系邮箱：njskills@agent.qq.com\n\nFile v1.9.0:skill-card.md\n\n## Description:\n\nHelps agents search multiple engines with configurable privacy settings, ranked results, optional source-backed answers, and web-page retrieval.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[fyniujin](https://clawhub.ai/user/fyniujin)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use this skill to search across web engines, review ranked sources, and optionally synthesize cited answers or retrieve page text while controlling search privacy settings.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Searches and update checks send requests to external services and may expose queries or the user's IP address.\n\nMitigation: Use an appropriate proxy or local search setup for sensitive searches, and disable startup update checks when needed.\n\nRisk: Local cache, history, and logs can retain sensitive search activity.\n\nMitigation: Disable cache, history, and logging for sensitive searches, or clear retained data afterward.\n\nRisk: Optional answer synthesis may share prompts and fetched page text with an LLM provider when an API key is configured.\n\nMitigation: Do not configure synthesis with sensitive content unless that provider and data transfer are approved.\n\nRisk: MCP page retrieval and synthesis can request arbitrary URLs from the user's machine.\n\nMitigation: Restrict MCP tools to those needed; disable fetch and synthesize in untrusted contexts.\n\n## Reference(s):\n\n- [ClawHub release](https://clawhub.ai/fyniujin/skills/privacy-search)\n- [Quick start](references/QUICK_START.md)\n- [Search engines](references/engines.md)\n- [Search syntax and FAQ](references/detail_engine_syntax_faq.md)\n- [MCP tool schema](references/mcp_schema.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, JSON, Guidance]\n\n**Output Format:** [Search results and optional cited answers as text, Markdown, or JSON]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Results can include source links and engine-count confidence indicators; optional answer synthesis and page retrieval.]\n\n## Skill Version(s):\n\n1.9.0 (source: skill frontmatter and ClawHub release)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.9.0:requirements.txt\n\naiohttp>=3.9.0,<4.0.0\nbeautifulsoup4>=4.12.0,<5.0.0\nlxml>=5.0.0,<6.0.0\njieba>=0.42.1,<1.0.0\npyyaml>=6.0,<7.0.0\n\nArchive v1.8.0: 45 files, 169429 bytes\n\nFiles: references/config.yaml.example (8374b), references/engines_zh.md (5685b), references/engines.md (6702b), references/mcp_schema.md (6296b), references/QUICK_START.md (6889b), requirements.txt (111b), scripts/__init__.py (120b), scripts/cache.py (18188b), scripts/engine_selectors.py (11179b), scripts/engines_registry.py (8379b), scripts/exporters.py (7254b), scripts/fact_checker.py (12487b), scripts/http_client.py (9067b), scripts/logging_util.py (6073b), scripts/mcp_server.py (19637b), scripts/page_fetcher.py (4628b), scripts/privacy.py (13415b), scripts/query_parser.py (11168b), scripts/quick_setup.py (6264b), scripts/ranking.py (25652b), scripts/search.py (60245b), scripts/searxng_manager.py (16141b), scripts/selftest_scheduler.py (8792b), scripts/summarizer.py (5769b), scripts/synthesiser.py (11961b), scripts/update_checker.py (16494b), scripts/version_util.py (7701b), scripts/vertical_search.py (10339b), skill-card.md (2728b), SKILL.md (24903b), tests/__init__.py (1134b), tests/test_fact_checker.py (5305b), tests/test_mcp_server.py (14515b), tests/test_privacy.py (4413b), tests/test_query_parser.py (5507b), tests/test_search_v11.py (8269b), tests/test_search_v12.py (40380b), tests/test_search_v15.py (15182b), tests/test_search_v16.py (15210b), tests/test_search.py (7705b), tests/test_searxng.py (3469b), tests/test_update_checker.py (6124b), tests/test_v18_all.py (12249b), tests/test_vertical_search.py (4603b), _meta.json (133b)\n\nFile v1.8.0:SKILL.md\n\n---\nname: privacy-search\ndescription: \"隐私优先的多引擎并行搜索 Skill，提供十大搜索引擎（百度/必应/搜狗/360/DuckDuckGo/Yandex/Startpage/Qwant/Brave/本地SearXNG）并行检索。V1.8 新增可信合成与垂直搜索：事实核查层逐论断回链原文做相似度比对（标注支撑度三级，无源论断默认剔除），垂直搜索模式（news/realtime/academic/image 四类），高级检索语法（after:/before:/site:/filetype:），与现有 bangs 语法统一为查询语法表。V1.7 新增 MCP Server 形态（stdio JSON-RPC 2.0 暴露 search/synthesize/fetch 三工具），可被 Claude Code/Cursor/n8n 直接挂载，让搜索能力成为任何 Agent 的即插组件。V1.6 新增 Perplexity 式答案合成（引用+正文抓取+citation）和定时引擎失效告警，jieba 默认安装提升中文精度。V1.5 新增网页正文抓取、搜索结果导出（Markdown/HTML/PDF）、LLM 摘要（智谱 GLM-4-Flash + 抽取式降级）。V1.2 统一 HTTP 出口（隐私头/UA池/代理/自动重试真正生效）、标准 SimHash 去重、多因子加权排序、多套备选选择器与解析诊断、bangs 语法透传、结果缓存与搜索历史、SearXNG 本地实例双路径部署、隐私模式 normal/strict 一键切换，不污染系统 Python 环境。\"\nversion: 1.8.0\n---\n\n\n# 隐私搜索（Privacy Search）\n\n隐私优先的多引擎并行搜索 Skill。V1.8 新增 **可信合成与垂直搜索**：事实核查层逐论断回链原文做相似度比对（标注支撑度三级：充分/部分/无源，无源论断默认剔除），正文抓取与摘要合并为显式「内容处理管线」；垂直搜索模式（news/realtime/academic/image 四类，各配引擎优先级与参数）；高级检索语法（after:/before:/site:/filetype:），与现有 bangs 语法统一为查询语法表。V1.7 新增 MCP Server 形态（stdio JSON-RPC 2.0 暴露 search/synthesize/fetch 三工具）。V1.6 新增 Perplexity 式答案合成（引用+正文抓取+citation）和定时引擎失效告警。V1.5 新增网页正文抓取、结果导出（Markdown/HTML/PDF）与 LLM 摘要（智谱 GLM-4-Flash + 抽取式降级）。V1.2 统一 HTTP 出口、SimHash 去重、多因子排序、结果缓存与搜索历史、SearXNG 本地双路径部署、隐私模式 normal/strict 一键切换。\n\n## 环境要求\n\n- Python 3.10+\n- Docker（可选，推荐用于 SearXNG）\n- 网络连接（本地 SearXNG 启动后可离线搜索）\n- Windows / macOS / Linux\n\n## 🚀 快速开始\n\n```bash\n# 一键安装\npython scripts/quick_setup.py\n\n# 搜索\npython scripts/search.py \"关键词\"\npython scripts/search.py \"关键词\" --privacy strict\n\n# 隐私报告\npython scripts/privacy report\n\n# 检查更新\npython scripts/update_checker check\n```\n\n详细 5 分钟上手指南 → [QUICK_START.md](references/QUICK_START.md)\n\n## 核心命令\n\n### F1：多引擎并行搜索\n\n```bash\n# 基础搜索\npython -m scripts.search \"搜索关键词\"\n\n# 指定引擎\npython -m scripts.search \"关键词\" --engines baidu,bing,duckduckgo\n\n# strict 隐私模式\npython -m scripts.search \"关键词\" --privacy strict\n\n# strict 引擎全部失败时，显式授权降级到国内引擎\npython -m scripts.search \"关键词\" --privacy strict --allow-fallback\n\n# JSON 输出\npython -m scripts.search \"关键词\" --json\n\n# 错误诊断（网络/配置/引擎问题）\npython -m scripts.search \"关键词\" --privacy strict --verbose\n\n# 查看全部可用引擎\npython -m scripts.search --list-engines\n\n# 引擎连通性与解析健康度体检\npython -m scripts.search --selftest\n\n# 搜索后附带隐私保护摘要\npython -m scripts.search \"关键词\" --privacy strict --privacy-report\n```\n\n### F4：Perplexity 式答案合成（V1.6 新增）\n\n```bash\n# Pro 模式：抓取正文 + LLM 带 citation 生成答案\npython -m scripts.search \"关键词\" --synthesize-pro\n\n# 无 API Key 时自动降级为抽取式摘要+来源列表\npython -m scripts.search \"关键词\" --synthesize-pro --privacy strict\n```\n\n### F5：定时引擎告警（V1.6 新增）\n\n```bash\n# 手动执行一次 selftest 并发送告警\npython -m scripts.search --selftest-schedule run\n\n# 查看上次 selftest 结果\npython -m scripts.search --selftest-schedule status\n\n# 独立运行（支持阻塞式定时循环）\npython -m scripts.selftest_scheduler run\npython -m scripts.selftest_scheduler status\n```\n\n### F7：可信合成与垂直搜索（V1.8 新增）\n\n```bash\n# 事实核查（逐论断回链原文，标注支撑度三级）\npython -m scripts.search \"量子计算最新进展\" --synthesize-pro --fact-check\n\n# 新闻搜索（时效性排序，优先百度资讯/必应新闻）\npython -m scripts.search \"AI 大模型\" --vertical news\n\n# 实时搜索（秒级/分钟级更新）\npython -m scripts.search \"突发新闻\" --vertical realtime\n\n# 学术搜索（Semanticscholar 学术数据库）\npython -m scripts.search \"quantum computing\" --vertical academic\n\n# 图片搜索\npython -m scripts.search \"猫咪\" --vertical image\n\n# 高级检索语法（时间/站点/文件类型限定）\npython -m scripts.search \"python教程 site:github.com filetype:pdf\"\npython -m scripts.search \"AI新闻 after:2025 before:2026\"\n\n# 组合使用\npython -m scripts.search \"量子计算 site:mit.edu after:2024\" --vertical academic\n```\n\n> 高级语法支持引擎：baidu(site), bing(site,filetype), duckduckgo(site), yandex(site), searxng(site,after,brave)。不支持语法的引擎自动本地过滤。\n> 统一查询语法表 → `python -m scripts.query_parser`\n\n### F6：MCP Server（V1.7 新增）\n\n```bash\n# 启动 MCP Server（stdio 模式）\npython -m scripts.mcp_server\n\n# 查看工具 schema\npython -m scripts.mcp_server --schema\n\n# 协议自测\npython -m scripts.mcp_server --test\n```\n\nMCP Server 暴露三个工具：`search`（多引擎并行搜索）、`synthesize`（Perplexity 式答案合成）、`fetch`（网页正文抓取）。\n\n> 详细工具 schema 与桥接文档 → [references/mcp_schema.md](references/mcp_schema.md)\n\n### 缓存与搜索历史\n\n相同查询在有效期内直接复用结果，输出会标注「来源: 缓存」。\n\n```bash\n# 跳过缓存，强制重新搜索\npython -m scripts.search \"关键词\" --no-cache\n\n# 查看缓存占用\npython -m scripts.search --cache-stats\n\n# 清空缓存\npython -m scripts.search --clear-cache\n\n# 查看最近搜索历史（默认 20 条）\npython -m scripts.search --history\npython -m scripts.search --history 50\n\n# 清空搜索历史\npython -m scripts.search --clear-history\n```\n\n### bangs 快捷语法\n\n查询词中带 `!` 前缀时自动路由到本地 SearXNG，由其转发到目标站点。\n\n```bash\npython -m scripts.search \"!w 量子计算\" # 维基百科\npython -m scripts.search \"!gh asyncio\" # GitHub\npython -m scripts.search \"!yt python 教程\" # YouTube\n```\n\n> 该语法依赖本地 SearXNG。未启用时会提示并按普通关键词搜索。\n\n### F2：SearXNG 本地实例管理\n\n```bash\n# Docker 启动（推荐）\npython -m scripts.searxng_manager start --method docker\n\n# pip 启动\npython -m scripts.searxng_manager start --method pip\n\n# 状态检查\npython -m scripts.searxng_manager status\n\n# 停止\npython -m scripts.searxng_manager stop\n```\n\n### F3：隐私模式切换\n\n```bash\n# 状态查看\npython -m scripts.privacy status\n\n# 切换到 strict\npython -m scripts.privacy mode --set strict\n\n# 切换到 normal\npython -m scripts.privacy mode --set normal\n\n# 生成隐私保护报告\npython -m scripts.privacy report\n```\n\n### 版本更新检查（死规则 11）\n\n```bash\npython -m scripts.update_checker check\npython -m scripts.update_checker status\n```\n\n## 能做哪些\n\n| 能力 | 说明 |\n|------|------|\n| 多引擎并发搜索 | 10 引擎并行，标准 SimHash 去重 |\n| 多因子加权排序 | 共识度 + 位次 + 相关度 + 权威度 + 域名质量，权重可配 |\n| 结果缓存 | 相同查询秒回，容量上限自动淘汰 |\n| 搜索历史 | 本地留存最近 500 条，可查可清 |\n| 统一隐私出口 | 隐私头 / UA 池 / 代理 / 重试对全部引擎一致生效 |\n| 隐私优先兜底 | strict 下拒绝非白名单引擎，失败不静默降级 |\n| 本地 SearXNG | Docker/pip 双路径，query 不出本机 |\n| bangs 语法 | `!w` `!gh` `!yt` 等快捷跳转，经 SearXNG 转发 |\n| 解析健壮性 | 每引擎多套备选选择器，改版后自动尝试 |\n| 解析诊断 | 区分「确实无结果」「被拦截」「选择器失效」 |\n| 引擎体检 | `--selftest` 一次性检查各引擎连通与解析状态 |\n| 网络自动重试 | 指数退避 + 随机抖动，仅对网络类错误重试 |\n| 运行日志 | 级别可配，默认不记录查询词原文 |\n| 错误分类诊断 | 网络/配置/引擎三类问题，针对性排查 |\n| 版本更新提醒 | 启动异步检查，24h 不重复 |\n| 请求频率控制 | 单引擎日上限 200 + 随机延迟 |\n| venv 隔离 | pip 依赖全虚拟环境，不污染系统 |\n| Perplexity 式合成 | 抓取正文→分块→LLM 带 citation 生成答案（Pro 模式） |\n| 事实核查层 | 逐论断回链原文做相似度比对，三级标注支撑度 |\n| 垂直搜索 | news/realtime/academic/image 四类，各配引擎优先级 |\n| 高级检索语法 | after:/before:/site:/filetype:，与 bangs 语法统一 |\n| 内容处理管线 | 正文抓取→分块→摘要显式链，中间产物可查 |\n| 定时引擎告警 | 每日/每小时自动 selftest，失效引擎主动通知 |\n| jieba 中文分词 | 默认安装，中文相关度精度提升 |\n| MCP Server | stdio JSON-RPC 2.0 服务，暴露 search/synthesize/fetch 三工具 |\n| 生态桥接 | 可被 gov-procurement/contract-review 等 skill 经 MCP 调用 |\n\n## 不能做哪些（V1.6 限制）\n\n- ❌ **不隐藏 IP 地址**：未配置 `privacy.strict.proxy` 时搜索引擎仍可见您的 IP\n- ❌ **不保证 100% 正文抓取**：部分网站反爬严格，正文抓取可能失败\n- ❌ **不保证 LLM 摘要 100% 准确**：LLM 可能产生幻觉，建议核对来源\n- ❌ **不提供浏览器插件**（V2.0+ 规划）\n- ❌ **不保证引擎长期可解析**：搜索引擎改版后需等待选择器更新\n\n## 风险声明\n\n### 隐私边界\n\n| 风险 | 说明 | 缓解 |\n|------|------|------|\n| IP 可见性 | 不配置代理时引擎可见真实 IP | 设置 `privacy.strict.proxy` 或配合 VPN |\n| 搜索词明文传输 | 查询词需发送至引擎 | strict 走隐私引擎，或用本地 SearXNG |\n| 本地缓存留痕 | 缓存与历史含查询词，明文存于本地 | `--clear-cache` / `--clear-history`，或 `cache.enabled: false` |\n| 日志留痕 | 默认 INFO 只记录查询词长度 | 需完全静默可设 `logging.level: OFF` |\n| SearXNG 端口暴露 | 默认 127.0.0.1 | 禁止改为 0.0.0.0 |\n\n### 合规使用\n\n| 风险 | 说明 | 缓解 |\n|------|------|------|\n| 搜索引擎条款 | 自动化访问可能受限 | 尊重 robots.txt，勿调高频率上限 |\n| 数据合规 | 缓存与历史存于本地磁盘 | 共享设备建议关闭缓存 |\n\n## 常见错误\n\n> 遇到错误时，使用 `--verbose` 查看详细诊断\n\n### 网络故障 🌐\n\n```\n💡 网络连接失败，请检查网络或使用 --verbose 查看详情\n```\n\n排查：\n1. 检查网络：`ping www.baidu.com`\n2. 确认网络环境不受限\n3. 增大超时：`config.yaml` 中 `search.timeout: 20`\n\n### 配置错误 ⚙️\n\n```\n💡 配置错误，请检查 config.yaml 或使用 --verbose 查看详情\n```\n\n排查：\n1. 确认 YAML 格式正确（冒号后有空格）\n2. 复制 `references/config.yaml.example` 重新配置\n\n### 引擎错误 🔧\n\n```\n💡 搜索引擎解析失败，请稍后重试或更换引擎\n```\n\n排查：\n1. 运行 `python -m scripts.search --selftest` 定位具体原因\n2. 按诊断结论处理（见下表）\n3. 临时规避：用 `--engines` 排除该引擎\n\n### 解析诊断对照\n\n`--selftest` 与 `--verbose` 会输出诊断结论：\n\n| 诊断 | 含义 | 处理 |\n|------|------|------|\n| 正常 | 解析成功 | 无需处理 |\n| 确认无结果 | 该关键词确实无匹配 | 换关键词或换引擎 |\n| 被拦截 | 触发验证码或风控 | 降低频率，稍后重试 |\n| 选择器失效 | 引擎改版导致解析不到 | 更新到最新版本 |\n| 未知 | 页面结构异常 | 用 `--verbose` 查看详情 |\n\n## 常见问题\n\n**Q: strict 模式在国内能用吗？**\nA: 可以。strict 默认使用 Yandex（国内快）+ Startpage + Qwant + Brave，DDG 作最后备选。\n\n**Q: strict 模式下指定 `--engines baidu` 为什么没生效？**\nA: 这是有意设计。strict 模式会拒绝隐私保护不足的引擎，避免\"以为开了 strict 实际仍在向百度发送查询词\"。需要用百度请改用 `--privacy normal`。\n\n**Q: strict 模式搜不到结果，直接返回空？**\nA: 隐私引擎全部不可用时默认停止搜索，而非静默降级到国内引擎——因为 strict 用户的预期是宁可无结果也不泄露查询词。确需降级请加 `--allow-fallback`，或在配置中开启 `privacy.strict.allow_fallback`。\n\n**Q: 结果是旧的怎么办？**\nA: 默认缓存 1 小时。加 `--no-cache` 强制刷新，或调小 `cache.ttl_seconds`。\n\n**Q: 缓存文件会无限增长吗？**\nA: 不会。超过 `cache.max_size_mb`（默认 50MB）时自动淘汰最久未使用的条目，历史记录上限 500 条。\n\n**Q: 缓存和历史存在哪？如何彻底清除？**\nA: 默认在 `~/.workbuddy/output/privacy-search-cache.db`。`--clear-cache` 清结果，`--clear-history` 清历史，两者独立。\n\n**Q: 怎么确认隐私设置真的生效了？**\nA: 加 `--privacy-report` 查看本次搜索实际使用的请求头、代理与被屏蔽引擎。\n\n**Q: 如何隐藏 IP？**\nA: 在 config.yaml 设置 `privacy.strict.proxy`，支持 `http://` 与 `socks5://`。留空为直连。\n\n**Q: 某个引擎突然搜不到结果？**\nA: 先跑 `--selftest`。若显示「选择器失效」说明该引擎改版了，请更新到最新版本；显示「被拦截」则是触发了风控，稍后再试或换引擎。\n\n**Q: 为什么指定了 searxng 却没用上？**\nA: 检查 `searxng.enabled` 是否为 true，以及本地实例是否已启动（`python -m scripts.searxng_manager status`）。\n\n**Q: 排序结果不满意能调吗？**\nA: 可以。config.yaml 的 `ranking` 段可调五个权重，例如更看重多引擎共识就调高 `consensus`。\n\n**Q: 中文分词报缺少 jieba？**\nA: jieba 为可选依赖，缺失时自动降级为字符级切分，搜索仍可用。安装后相关度排序更准。\n\n**Q: 会记录我搜了什么吗？**\nA: 日志默认 INFO 级别，只记录查询词长度不记录原文；搜索历史存于本地且可随时清空。需完全静默可设 `logging.level: OFF`。\n\n**Q: SearXNG 启动失败？**\nA: 尝试切换：`--method pip`。确保 Docker 或 Python 3.10+ 可用。\n\n**Q: 如何关闭更新检查？**\nA: `python -m scripts.update_checker disable`\n\n**Q: 安装依赖失败？**\nA: `pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple`\n\n**Q: 支持哪些引擎？**\nA: 10 个：百度、必应、搜狗、360、DuckDuckGo、Yandex、Startpage、Qwant、Brave、本地 SearXNG。运行 `--list-engines` 查看完整属性。\n\n**Q: 如何在其他程序里调用？**\nA: 当前支持两种方式：① 命令行 `--json` 获取结构化输出；② MCP Server（V1.7 新增），通过 stdio JSON-RPC 2.0 暴露 search/synthesize/fetch 三工具，可被 Claude Code、Cursor、n8n 等直接挂载。详见 `references/mcp_schema.md`。\n\n**Q: Pro 模式和普通摘要的区别？**\nA: Pro 模式会抓取搜索结果正文并生成带 citation 的答案，每个论断都能追溯到来源。普通摘要（`--summarize`）只基于 snippet 生成简短总结。Pro 模式需要配置 `synthesis.api_key`，无 Key 时自动降级为抽取式摘要。\n\n**Q: Pro 模式抓取正文失败怎么办？**\nA: 系统会自动降级为该结果的 snippet，不会中断整体流程。可在 config.yaml 调整 `synthesis.fetch_timeout` 和 `synthesis.chunk_size`。\n\n**Q: 定时 selftest 怎么配置每天跑一次？**\nA: config.yaml 中设置 `selftest_schedule.interval: daily`，然后用系统 cron 或任务计划程序定时触发 `python scripts/search.py --selftest-schedule run`。当前不支持后台常驻进程。\n\n**Q: selftest 告警发到哪？**\nA: 默认写入 `~/.workbuddy/output/privacy-search-selftest.log`，设置 `selftest_schedule.alert_channel: both` 可同时推送到企业微信 webhook。\n\n**Q: 如何配置 webhook 告警？**\nA: 在 config.yaml 的 `selftest_schedule.webhook_url` 填入企业微信/钉钉机器人的 webhook 地址。\n\n**Q: 配置项太多，哪些必须改？**\nA: 首次只需改 3 项（config.yaml 中标注 [推荐修改]）：`default_engines`、`timeout`、`default_mode`。其他保持默认。\n\n**Q: 事实核查是什么？怎么用？**\nA: 事实核查是 V1.8 新增的可信合成层。用 `--synthesize-pro --fact-check` 启用，逐条论断回链原文做 TF-IDF 余弦相似度比对，标注支撑度三级（充分/部分/无源），无源论断默认剔除。核查报告自动追加在答案末尾，含引用清单与核查方法说明。\n\n**Q: 无源论断怎么处理？**\nA: 默认自动剔除（`fact_check.remove_unsupported: true`）。如想保留但标注警告，设置 `fact_check.remove_unsupported: false`。阈值也可调：`sufficient_threshold`（默认 0.55）、`partial_threshold`（默认 0.25）。\n\n**Q: 垂直搜索怎么用？**\nA: `--vertical news/realtime/academic/image` 四类。新闻走百度资讯/必应新闻，学术走 Semanticscholar 开放接口（不可用时降级为通用引擎+学术关键词），图片走引擎图片端。每类有独立的引擎优先级和排序权重。\n\n**Q: 高级检索语法和 bangs 冲突吗？**\nA: 不冲突，统一为查询语法表。bangs（`!w` `!gh` `!yt`）走 SearXNG 原生快捷跳转，高级语法（`after:/before:/site:/filetype:`）映射为各引擎等价参数。不支持语法的引擎本地过滤并注明。\n\n**Q: MCP Server 是什么？怎么用？**\nA: MCP Server 是 V1.7 新增的 stdio JSON-RPC 2.0 服务，把搜索/合成/抓取能力暴露为标准工具协议。V1.8 为 synthesize 工具新增事实核查层。运行 `python scripts/mcp_server.py` 即可启动，可被 Claude Code、Cursor、n8n 等支持 MCP 的客户端挂载。详见 `references/mcp_schema.md`。\n\n**Q: MCP Server 暴露了哪些工具？**\nA: 3 个工具：`search`（多引擎隐私搜索）、`synthesize`（Perplexity 式答案合成 + V1.8 事实核查）、`fetch`（URL 正文抓取）。可通过 config.yaml 的 `mcp_server.tools` 缩减子集。\n\n**Q: MCP Server 超时怎么办？**\nA: 默认单次调用 30 秒，超时返回 JSON-RPC 错误响应，不中断服务。可在 config.yaml 调整 `mcp_server.timeout`。LLM 不可用时自动降级为抽取式，不影响 search/fetch 工具。\n\n## 项目结构\n\n```\nprivacy-search/\n├── SKILL.md # 本文件\n├── requirements.txt # Python 依赖\n├── scripts/\n│ ├── __init__.py\n│ ├── search.py # F1: 搜索编排与 CLI\n│ ├── searxng_manager.py # F2: SearXNG 管理\n│ ├── privacy.py # F3: 隐私模式与请求上下文\n│ ├── engines_registry.py # 引擎清单单一真相源\n│ ├── engine_selectors.py # 各引擎选择器与解析诊断\n│ ├── http_client.py # 统一 HTTP 出口（UA池/代理/重试）\n│ ├── ranking.py # SimHash 去重与多因子排序\n│ ├── cache.py # 结果缓存与搜索历史\n│ ├── logging_util.py # 运行日志\n│ ├── version_util.py # 版本解析单一真相源\n│ ├── update_checker.py # 更新检查（死规则 11）\n│ ├── quick_setup.py # 一键安装\n│ ├── synthesiser.py # F4: Perplexity 式答案合成（V1.6 新增）\n│ ├── selftest_scheduler.py # F5: 定时 selftest 告警（V1.6 新增）\n│ ├── mcp_server.py # F6: MCP Server stdio JSON-RPC 2.0（V1.7 新增）\n│ ├── fact_checker.py # F7: 事实核查层（V1.8 新增）\n│ ├── vertical_search.py # F7: 垂直搜索路由（V1.8 新增）\n│ └── query_parser.py # F7: 高级检索语法（V1.8 新增）\n├── references/\n│ ├── config.yaml.example # 配置模板（含推荐配置标注）\n│ ├── engines.md # 引擎适配器文档\n│ ├── engines_zh.md # 国内引擎与降级策略\n│ ├── mcp_schema.md # MCP 工具 Schema 文档（V1.7 新增）\n│ └── QUICK_START.md # 快速上手\n└── tests/\n ├── test_search.py # 搜索基础测试\n ├── test_search_v11.py # 引擎与降级测试\n ├── test_search_v12.py # 缓存/排序/日志测试\n ├── test_search_v15.py # V1.5 新模块测试\n ├── test_search_v16.py # V1.6 新模块测试\n ├── test_mcp_server.py # MCP Server 协议与工具测试（V1.7 新增）\n ├── test_fact_checker.py # 事实核查层测试（V1.8 新增）\n ├── test_vertical_search.py # 垂直搜索测试（V1.8 新增）\n ├── test_query_parser.py # 高级语法解析测试（V1.8 新增）\n ├── test_searxng.py # SearXNG 管理测试\n ├── test_privacy.py # 隐私模式测试\n └── test_update_checker.py # 更新检查测试\n```\n\n## 更新日志\n\n| v1.8.0 | 2026-09-19 | 增加：事实核查层（逐论断回链原文做相似度比对，标注支撑度三级：充分/部分/无源，无源论断默认剔除）；增加：垂直搜索模式（news/realtime/academic/image 四类，各配引擎优先级与参数）；增加：高级检索语法（after:/before:/site:/filetype: 解析为各引擎等价参数，不支持的引擎本地过滤并注明）；增加：内容处理管线（正文抓取→分块→摘要显式链，中间产物可查）；调整：synthesiser 集成事实核查层，--synthesize-pro 输出自动附带核查报告；调整：MCP Server synthesize 工具 schema 更新（V1.8 新增事实核查层说明） |\n| v1.7.0 | 2026-08-28 | 增加：MCP Server 形态（stdio JSON-RPC 2.0 暴露 search/synthesize/fetch 三工具）；增加：生态桥接文档（references/mcp_schema.md）；增加：MCP Server 配置段（config.yaml） |\n| v1.6.0 | 2026-08-17 | 增加：Perplexity 式答案合成（抓取正文→分块→LLM 带 citation 生成答案）；增加：定时 selftest 调度+引擎失效告警（每日/每小时，支持 webhook）；调整：jieba 从可选改为默认安装，中文相关度精度提升；优化：无 API Key 时 Pro 模式自动降级为抽取式摘要+来源列表 |\n| v1.5.0 | 2026-08-07 | 增加：网页正文抓取模块（trafilatura/boilerpy3/正则三层降级）；增加：搜索结果导出（Markdown/HTML/PDF，PDF 有降级方案）；增加：LLM 摘要（智谱 GLM-4-Flash + 抽取式降级）；增加：引擎统计与动态降级（按历史成功率选引擎）；增加：UA 池可配置化（config.yaml 追加）；增加：TF-IDF 相关度算法（jieba 分词 + 余弦相似度）；增加：降级引擎列表可配置；优化：域名质量表扩展（+30 常用中文站点）；优化：SearXNG Secret 持久化（重启不失效）；优化：request_delay 默认值与示例文件一致（1.0-5.0）；优化：update_check 接入 search.py 启动检查；修复：github_url 占位符替换为 njskills；修复：引擎改版 mock 回归测试 |\n| v1.1.0 | 2026-07-19 | 增加4个国内可用备选引擎（Yandex/Startpage/Qwant/Brave）；strict模式自动降级与故障转移；增强错误分类（网络/配置/引擎三类）；增加10+FAQ与常见错误反模式对照；增加normal/strict模式搜索输出示例；增加5分钟快速上手指南QUICK_START.md；增加一键安装脚本quick_setup.py |\n| v1.0.0 | 2026-07-18 | 初始版本发布：多引擎并行搜索（F1）；SearXNG本地实例双路径部署（F2）；隐私模式normal/strict切换（F3）；版本更新检查提醒（死规则11）；SimHash去重与交叉验证排序 |\n\n## 支持与反馈\n\n- **联系邮箱**：njskills@agent.qq.com\n- **问题反馈**：欢迎通过邮件或 SkillHub 评论提出建议\n- **版本更新**：运行 `python -m scripts.update_checker check` 检查新版本\n\nFile v1.8.0:_meta.json\n\n{\n \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n \"slug\": \"privacy-search\",\n \"version\": \"1.8.0\",\n \"publishedAt\": 1789797670140\n}\n\nFile v1.8.0:references/engines_zh.md\n\n# 国内可用搜索引擎指南\n\n本文档说明 strict 模式下各引擎的国内可用性、隐私保护级别和自动降级策略。\n\n## 引擎对比\n\n| 引擎 | 国家 | 国内速度 | 隐私保护 | 数据收集 | 追踪 | strict 默认 | 备注 |\n|------|------|---------|---------|---------|------|-----------|------|\n| **SearXNG（本地）** | 本机 | ⭐⭐⭐⭐⭐ 极快 | 极高 | ❌ 无 | ❌ 无 | ✅ 最优先 | query 不出本机，最佳隐私 |\n| **Yandex** | 俄罗斯 | ⭐⭐⭐⭐ 快 | 中等 | 部分 | 少量 | ✅ | 俄文界面可用，中文搜索能力较好 |\n| **Startpage** | 荷兰 | ⭐⭐⭐ 中等 | 高 | ❌ 无 | ❌ 无 | ✅ | Google 代理，结果质量高 |\n| **Qwant** | 法国 | ⭐⭐⭐ 中等 | 高 | ❌ 无 | ❌ 无 | ✅ | 欧洲隐私法保护 |\n| **Brave** | 美国 | ⭐⭐ 较慢 | 高 | ❌ 无 | ❌ 无 | ✅ | 独立搜索引擎，不依赖 Google |\n| **DuckDuckGo** | 美国 | ⭐ 不稳定 | 极高 | ❌ 无 | ❌ 无 | ⚠️ 最后 | 国内连接不稳定，仅作兜底 |\n\n## 自动降级策略\n\n```\nstrict 模式搜索流程：\n┌──────────────────────────────────────────────────────┐\n│ SearXNG（本地，最优先） │\n│ query 不出本机，极速响应 │\n└────────────────────┬─────────────────────────────────┘\n │ (不可用时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ Yandex + Startpage + Qwant + Brave │\n│ 并发请求，SimHash 去重 │\n└────────────────────┬─────────────────────────────────┘\n │ (全部失败时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ DuckDuckGo（不稳定时使用） │\n└────────────────────┬─────────────────────────────────┘\n │ (仍失败时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ 默认：停止搜索并提示，不泄露查询词 │\n│ 显式加 --allow-fallback 才降级到 bing/baidu │\n└──────────────────────────────────────────────────────┘\n```\n\n### 为什么默认不降级\n\nstrict 模式的用户预期是「宁可没有结果，也不把查询词发给隐私保护不足的引擎」。\n静默降级到百度/必应会让用户在毫不知情的情况下失去隐私保护，属于违背预期的危险默认值。\n因此 V1.2 起改为默认拒绝，需通过 `--allow-fallback` 或配置项 `privacy.strict.allow_fallback` 显式授权。\n\n同理，strict 模式下即使用 `--engines baidu` 显式指定，也会被拒绝并提示改用 normal 模式。\n\n## 推荐使用方式\n\n### 最佳隐私（推荐）\n```bash\npython scripts/search.py \"关键词\" --privacy strict --engines searxng,yandex,startpage\n```\n- query 完全在本地\n- Yandex + Startpage 作为离线后备\n\n### 最佳速度\n```bash\npython scripts/search.py \"关键词\" --engines baidu,bing\n```\n- 国内引擎最快\n- normal 模式下的推荐选择\n\n### 平衡模式\n```bash\npython scripts/search.py \"关键词\" --privacy strict --engines yandex,searxng\n```\n- 速度隐私均衡\n- Yandex 国内速度快 + SearXNG 极致隐私\n\n## 常见问题：特定引擎故障\n\n### Yandex 故障\n- 可能原因：反爬升级、IP 限制\n- 解决：等待自动降级到 Startpage/Qwant\n\n### 全部 strict 引擎失败\n- 可能原因：网络受限、DNS 污染\n- 解决：\n ```bash\n 1. 检查网络：ping yandex.com\n 2. 配置代理（config.yaml 中 search.proxy）\n 3. 降级使用 normal 模式\n ```\n\n### DDG 在国内不可用\n- 常见现象，自动使用其他隐私引擎替代\n- 配置 `privacy.strict.proxy` 后可恢复\n\n### 判断是引擎坏了还是关键词没匹配\n\n```bash\npython scripts/search.py --selftest\n```\n\n输出会区分「正常」「确认无结果」「被拦截」「选择器失效」四种状态。\n显示「选择器失效」说明该引擎改版了，需更新插件版本；「被拦截」则是触发风控，降低频率后重试。\n\n## 限制与规避\n\n| 问题 | 影响 | 规避方式 |\n|------|------|---------|\n| 搜索引擎改版 | HTML 解析失败 | 多套备选选择器自动尝试，仍失败则等待版本更新 |\n| 触发风控 | 返回验证码页 | 降低 `daily_request_limit`，增大请求间隔 |\n| CDN 劫持 | 结果被篡改 | 全程 HTTPS + 多引擎交叉验证 |\n| DNS 污染 | 域名解析到错误 IP | 配置 `privacy.strict.proxy` |\n| IP 过滤 | 特定 IP 被封锁 | 配置代理，或改用本地 SearXNG |\n| 跳转链接 | 国内引擎返回中转地址 | 排序时自动识别并降权 |\n\n---\n\n有更好建议：njskills@agent.qq.com\n\nFile v1.8.0:references/engines.md\n\n# 搜索引擎适配器文档\n\n本文档说明各搜索引擎的实现细节、解析规则与扩展方式，对应 V1.2 架构。\n\n## 引擎列表\n\n引擎清单的唯一来源是 `scripts/engines_registry.py`，运行 `python -m scripts.search --list-engines` 可查看实时属性。\n\n| 引擎名称 | 标识 | 类型 | 区域 | 隐私等级 | strict 可用 | 说明 |\n|---------|------|------|------|---------|------------|------|\n| 本地 SearXNG | `searxng` | JSON API | 本机 | 高 | ✅ | 元搜索，query 不出本机，支持 bangs |\n| Yandex | `yandex` | HTML 解析 | 俄罗斯 | 中 | ✅ | 国内直连速度较好 |\n| Startpage | `startpage` | HTML 解析 | 荷兰 | 高 | ✅ | Google 结果代理 |\n| Qwant | `qwant` | HTML 解析 | 法国 | 高 | ✅ | 受欧盟隐私法约束 |\n| Brave Search | `brave` | HTML 解析 | 美国 | 高 | ✅ | 独立索引 |\n| DuckDuckGo | `duckduckgo` | HTML 解析 | 美国 | 高 | ✅ | 国内直连不稳定，作兜底 |\n| 百度 | `baidu` | HTML 解析 | 中国 | 低 | ❌ | 反爬较强，返回跳转链接 |\n| 必应 | `bing` | HTML 解析 | 中国 | 低 | ❌ | 国内可直接访问 |\n| 搜狗 | `sogou` | HTML 解析 | 中国 | 低 | ❌ | 返回跳转链接 |\n| 360 搜索 | `360` | HTML 解析 | 中国 | 低 | ❌ | 返回跳转链接 |\n\n## 架构分层\n\nV1.2 将传输与解析彻底分离，适配器不再各自处理 HTTP 细节。\n\n```\nCLI / SearchOrchestrator\n │\n ├── engines_registry.py 引擎清单与元数据（单一真相源）\n │\n ├── privacy.py 隐私配置 → RequestContext\n │ │\n ├── http_client.py 统一出口：UA 池 / 隐私头 / 代理 / 重试\n │ │\n ├── EngineAdapter 仅负责 build_url() 与结果映射\n │ │\n ├── engine_selectors.py 多套备选选择器 + 解析诊断\n │\n ├── ranking.py SimHash 去重 + 多因子加权排序\n │\n ├── cache.py 结果缓存与搜索历史\n │\n └── logging_util.py 运行日志\n```\n\n这样设计的原因：V1.1 时九个适配器各自硬编码请求头，导致隐私配置无法统一生效——只有三个适配器偶然带了 `DNT: 1`。收归统一出口后，隐私设置对所有引擎一致有效。\n\n## 请求策略\n\n### 超时与重试\n- 超时由 `search.timeout` 控制，默认 15 秒\n- 仅对网络类错误重试（连接失败、超时、连接重置），解析失败不重试\n- 指数退避 + 随机抖动，避免多引擎同时重试形成请求尖峰\n- 重试次数由 `search.retry_max` 控制，默认 2 次\n\n### 频率控制\n- 每日上限：单引擎 200 次（`search.daily_request_limit`）\n- 请求间隔：1–5 秒随机延迟\n- 超限自动跳过该引擎，不影响其他引擎\n\n### 请求头\n所有引擎统一经由 `http_client` 出口，不再逐引擎硬编码。\n\n| 模式 | User-Agent | DNT | Cookie | Referer | 代理 |\n|------|-----------|-----|--------|---------|------|\n| normal | UA 池随机 | 按配置 | 保留 | 保留 | 按配置 |\n| strict | UA 池随机 | `1` | 移除 | 移除 + `Referrer-Policy: no-referrer` | 按配置 |\n\nUA 池内置 8 个主流浏览器标识，随机轮换以降低指纹一致性。在 `privacy.strict.user_agent` 填入固定值可覆盖此行为。\n\n## 解析规则\n\n每个引擎配置多套备选选择器（见 `engine_selectors.py`）。首套解析不到结果时自动尝试下一套，用于缓解搜索引擎改版。\n\n### 百度\n- 容器：`div.result, div.result-op` → `div[class*='result']` → `div#content_left > div`\n- 标题：`h3 a`\n- 摘要：`div.c-abstract` 等\n\n### 必应\n- 容器：`li.b_algo` → `.b_algo`\n- 标题：`h2 a`\n- 摘要：`p`\n\n### DuckDuckGo\n- 容器：`div.result` → `div.web-result`\n- 标题：`a.result__a`\n- 摘要：`a.result__snippet`\n\n### SearXNG\n- 端点：`GET /search?q=...&format=json`\n- 响应：`results[].title / url / content`\n- 支持 bangs 语法透传（`!w` `!gh` `!yt` 等）\n\n### 解析诊断\n\n解析为空时不直接判定\"无结果\"，而是区分四种情况：\n\n| 诊断 | 判定依据 | 含义 |\n|------|---------|------|\n| `EMPTY_CONFIRMED` | 页面含\"没有找到相关结果\"等标记 | 确实无匹配 |\n| `BLOCKED` | 页面含验证码、安全验证等标记 | 触发风控 |\n| `SELECTOR_STALE` | 页面正常但所有选择器均未命中 | 引擎已改版 |\n| `UNKNOWN` | 其余情况 | 需人工查看 |\n\n这个区分很重要：把\"引擎改版\"误报为\"无结果\"会让用户以为搜索词有问题，而非插件需要更新。\n\n### 跳转链接处理\n\n百度、搜狗、360 返回的是形如 `baidu.com/link?url=...` 的中转地址而非真实 URL。这类链接会导致跨引擎去重失效（同一结果在不同引擎下 URL 不同）且域名质量评分失准，因此排序时统一降权。\n\n## SimHash 去重\n\nV1.2 采用标准 SimHash 实现（V1.1 的 MD5 异或合并并非真正的 SimHash，近似文本无法识别）。\n\n1. 中文用 jieba 分词，缺失时降级为 2-gram 字符切分\n2. 统计词频作为特征权重\n3. 每个特征取 MD5 哈希，按位加权投票：该位为 1 则加权重，为 0 则减权重\n4. 投票结果 > 0 的位置为 1，得到 64 位指纹\n5. 汉明距离 ≤ 3 视为重复\n\n## 多因子加权排序\n\n综合得分由五个因子加权求和，权重可在 `config.yaml` 的 `ranking` 段调整：\n\n| 因子 | 默认权重 | 说明 |\n|------|---------|------|\n| 共识度 | 6.0 | 被越多引擎收录越可信 |\n| 位次 | 3.0 | 引擎内原始排名，对数衰减 |\n| 相关度 | 4.0 | 查询词在标题摘要中的覆盖率 |\n| 权威度 | 2.0 | 引擎自身权威度，取自注册表 |\n| 域名质量 | 1.5 | 优质站点加分，低质站点与跳转链接降权 |\n\n## 扩展指南\n\n新增引擎只需三步，无需改动传输层：\n\n1. 在 `engines_registry.py` 的 `ENGINE_REGISTRY` 中登记元数据\n2. 在 `engine_selectors.py` 的 `SELECTORS` 中配置选择器\n3. 在 `search.py` 中实现适配器，只需覆盖 `build_url()`\n\n```python\nclass NewEngineAdapter(EngineAdapter):\n \"\"\"新引擎适配器：仅需构造 URL，解析与传输由框架承担\"\"\"\n\n def __init__(self):\n super().__init__(\"newengine\")\n\n def build_url(self, query: str, num: int) -> str:\n return f\"https://example.com/search?q={quote(query)}&n={num}\"\n```\n\n若引擎返回 JSON 而非 HTML，参考 `SearXNGAdapter` 覆盖 `search()` 方法。\n\n完成后运行 `python -m scripts.search --selftest` 验证连通性与解析状态。\n\n---\n\n有更好建议：njskills@agent.qq.com\n\nFile v1.8.0:references/mcp_schema.md\n\n# MCP Server 工具 Schema 文档（V1.7）\n\n本文档描述 privacy-search MCP Server 的工具接口契约，供其他 skill 作者接入参考。\n\n## 运行方式\n\n```bash\n# 启动 MCP Server（stdio 模式）\npython scripts/mcp_server.py\n\n# 查看工具 schema\npython scripts/mcp_server.py --schema\n\n# 协议自测\npython scripts/mcp_server.py --test\n```\n\n## 工具列表\n\n| 工具名 | 描述 | 主要能力 |\n|--------|------|----------|\n| `search` | 多引擎并行搜索 | 10 引擎并发、SimHash 去重、多因子排序 |\n| `synthesize` | Perplexity 式答案合成 | 抓取正文、LLM 带 citation 生成 |\n| `fetch` | 网页正文抓取 | 三层降级提取正文 |\n\n---\n\n## 工具详细 Schema\n\n### 1. search — 多引擎并行搜索\n\n**描述**：同时检索百度、必应、DuckDuckGo、Yandex 等十大搜索引擎，SimHash 去重、多因子加权排序。\n\n**输入参数**：\n\n```json\n{\n \"query\": {\n \"type\": \"string\",\n \"description\": \"搜索查询词（必填）\"\n },\n \"engines\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"string\" },\n \"description\": \"指定引擎列表。可选值：baidu, bing, sogou, 360, duckduckgo, yandex, startpage, qwant, brave, searxng。留空时按隐私模式自动选择。\"\n },\n \"num\": {\n \"type\": \"integer\",\n \"description\": \"每个引擎返回结果数（默认 10，最大 20）\",\n \"default\": 10\n },\n \"privacy\": {\n \"type\": \"string\",\n \"enum\": [\"normal\", \"strict\"],\n \"description\": \"隐私模式：normal（全引擎）或 strict（仅隐私友好引擎）\",\n \"default\": \"normal\"\n },\n \"no_cache\": {\n \"type\": \"boolean\",\n \"description\": \"跳过缓存，强制重新搜索\",\n \"default\": false\n }\n}\n```\n\n**响应格式**：\n\n```json\n{\n \"results\": [\n {\n \"title\": \"标题\",\n \"url\": \"https://example.com\",\n \"snippet\": \"摘要\",\n \"engine\": \"baidu\",\n \"engines\": [\"baidu\", \"bing\"],\n \"rank\": 1,\n \"score\": 8.5\n }\n ],\n \"notices\": [\"提示信息\"],\n \"from_cache\": false,\n \"count\": 10\n}\n```\n\n---\n\n### 2. synthesize — Perplexity 式答案合成\n\n**描述**：抓取搜索结果正文，分块编号后调用 LLM 生成带 citation 的答案。每个论断都能追溯到具体来源。无 API Key 时自动降级为抽取式摘要。\n\n**输入参数**：\n\n```json\n{\n \"query\": {\n \"type\": \"string\",\n \"description\": \"用户问题（必填）\"\n },\n \"results\": {\n \"type\": \"array\",\n \"description\": \"搜索结果数组（可选）。未提供时自动先执行搜索。格式：[{\\\"title\\\":\\\"...\\\",\\\"url\\\":\\\"...\\\",\\\"snippet\\\":\\\"...\\\"}, ...]\"\n },\n \"max_sources\": {\n \"type\": \"integer\",\n \"description\": \"最多引用几个来源（默认 5，最大 10）\",\n \"default\": 5\n }\n}\n```\n\n**响应格式**：\n\n```json\n{\n \"answer\": \"这是 LLM 生成的答案 [1][2]。\\n\\n--- 来源 ---\\n[1] https://example.com/1\\n[2] https://example.com/2\",\n \"notices\": [\"提示信息\"]\n}\n```\n\n---\n\n### 3. fetch — 网页正文抓取\n\n**描述**：从指定 URL 提取正文内容，三层降级：trafilatura → boilerpy3 → 正则
标签。\n\n**输入参数**：\n\n```json\n{\n \"url\": {\n \"type\": \"string\",\n \"description\": \"目标网页 URL（必填）\"\n },\n \"timeout\": {\n \"type\": \"integer\",\n \"description\": \"抓取超时（秒），默认 10\",\n \"default\": 10\n }\n}\n```\n\n**响应格式**：\n\n```json\n{\n \"url\": \"https://example.com\",\n \"text\": \"正文内容...\",\n \"success\": true,\n \"length\": 1234\n}\n```\n\n---\n\n## 超时与降级策略\n\n### 超时配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `mcp_server.timeout` | 30s | 单次工具调用超时 |\n| `mcp_server.max_results` | 10 | search 工具默认最大结果数 |\n| `mcp_server.max_sources` | 5 | synthesize 工具默认最大引用来源数 |\n| `synthesis.fetch_timeout` | 10s | 单个页面抓取超时 |\n| `search.timeout` | 15s | 单个引擎搜索超时 |\n\n### 降级策略\n\n| 场景 | 降级行为 |\n|------|----------|\n| LLM API Key 未配置 | synthesize 自动降级为抽取式摘要 + 来源列表 |\n| LLM 调用失败 | 同上 |\n| 页面正文抓取失败 | 降级使用该结果的 snippet |\n| 所有页面正文抓取失败 | 降级为抽取式摘要 |\n| 搜索引擎限流 | 自动重试 + 指数退避 |\n| strict 模式引擎全部失败 | 默认拒绝降级（隐私优先），可配置 `allow_fallback` |\n\n### 错误处理\n\n所有工具调用返回统一的错误格式：\n\n```json\n{\n \"error\": \"错误描述\"\n}\n```\n\n---\n\n## 生态桥接示例\n\n### 其他 skill 接入本 MCP Server\n\n根据\"章首桥接原则\"，其他 skill 可按以下方式探测并调用 privacy-search：\n\n```python\n# 1. 探测 privacy-search 是否已安装\nimport shutil\ndef is_privacy_search_available() -> bool:\n return shutil.which(\"python\") is not None # 检查 python 环境\n\n# 2. 调用 MCP Server（stdio 模式）\nimport subprocess\nproc = subprocess.Popen(\n [\"python\", \"scripts/mcp_server.py\"],\n stdin=subprocess.PIPE,\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n)\n\n# 3. 发送 initialize 请求\nimport json\ndef send_request(proc, method, params=None):\n msg = {\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": method}\n if params:\n msg[\"params\"] = params\n body = json.dumps(msg, ensure_ascii=False)\n length = len(body.encode(\"utf-8\"))\n proc.stdin.write(f\"Content-Length: {length}\\r\\n\\r\\n{body}\".encode())\n proc.stdin.flush()\n # 读取响应...\n```\n\n### 典型调用场景\n\n| 调用方 | 场景 | 推荐工具 |\n|--------|------|----------|\n| gov-procurement | 政策资料查询 | `search` + `fetch` |\n| contract-review | 法条补充检索 | `search` + `synthesize` |\n| 其他 skill | 通用搜索 | `search` |\n\n---\n\n## 接口契约稳定性承诺\n\n1. **版本化 schema**：工具 schema 随 SKILL.md 版本号同步更新\n2. **向后兼容**：小版本（1.x）内不删除/重命名工具参数\n3. **降级保证**：所有外部依赖（LLM、搜索引擎）都有降级方案\n4. **超时可控**：所有网络调用都有可配置的超时\n\n---\n\n## 配置示例\n\n```yaml\n# config.yaml\nmcp_server:\n enabled: true\n timeout: 30\n max_results: 10\n max_sources: 5\n\nsynthesis:\n enabled: true\n api_key: \"\" # 留空则强制降级\n provider: auto\n max_sources: 5\n\nsearch:\n timeout: 15\n num_results: 10\n```\n\nFile v1.8.0:references/QUICK_START.md\n\n# 隐私搜索 - 5 分钟快速上手指南\n\n> 从零开始，5 分钟内完成安装并执行你的第一次隐私搜索。\n\n---\n\n## 🚀 一键安装（推荐）\n\n```bash\npython scripts/quick_setup.py\n```\n\n一键完成：创建 venv → 安装依赖 → 复制配置 → 验证安装。\n\n---\n\n## 📋 手动安装（如需控制每一步）\n\n### Step 1: 创建虚拟环境\n\n```bash\npython -m venv .venv\n# Windows\n.venv\\Scripts\\activate\n# Linux/macOS\nsource .venv/bin/activate\n```\n\n### Step 2: 安装依赖\n\n```bash\npip install -r requirements.txt\n```\n\n### Step 3: 复制配置\n\n```bash\ncp references/config.yaml.example config.yaml\n```\n\n### Step 4: 验证安装\n\n```bash\npython scripts/search.py \"test\"\n```\n\n---\n\n## 🔍 你的第一次搜索\n\n### 基础搜索（默认引擎）\n\n```bash\npython scripts/search.py \"Python asyncio 教程\"\n```\n\n输出示例：\n```\n🔍 搜索: Python asyncio 教程 | 模式: normal | 结果: 18 条\n\n[1] Python asyncio 异步编程入门教程\n https://docs.python.org/zh-cn/3/library/asyncio.html\n 本教程将带你了解 Python asyncio 模块的基础知识...\n — bing\n\n[2] 超详细的 Python asyncio 教程，从入门到精通\n https://www.cnblogs.com/...\n 本文详细介绍 Python asyncio 的使用方法...\n — baidu\n```\n\n### 隐私搜索（strict 模式）\n\n```bash\npython scripts/search.py \"Python asyncio 教程\" --privacy strict\n```\n\n输出示例：\n```\n搜索: Python asyncio 教程 | 模式: strict | 来源: 实时 | 结果: 12 条\n\n[1] Python Asynchronous Programming\n https://docs.python.org/3/library/asyncio.html\n Learn how to use asyncio for concurrent programming...\n — yandex\n\n[2] Async IO in Python: A Complete Walkthrough\n https://realpython.com/async-io-python/\n Async IO is a concurrent programming design...\n — startpage, qwant\n```\n\n> strict 模式仅使用 SearXNG/Yandex/Startpage/Qwant/Brave/DDG。\n> 即使显式指定 `--engines baidu` 也会被拒绝，避免隐私承诺被绕过。\n\n### 缓存加速\n\n相同查询在 1 小时内直接复用结果，输出标注「来源: 缓存」。\n\n```bash\npython scripts/search.py \"Python asyncio 教程\" # 来源: 实时\npython scripts/search.py \"Python asyncio 教程\" # 来源: 缓存，秒回\npython scripts/search.py \"Python asyncio 教程\" --no-cache # 强制刷新\n```\n\n### 引擎体检\n\n搜不到结果时，先判断是引擎坏了还是关键词没匹配：\n\n```bash\npython scripts/search.py --selftest\n```\n\n输出会标明每个引擎是「正常」「被拦截」还是「选择器失效」。\n\n### 显示错误诊断网络问题时\n\n```bash\npython scripts/search.py \"test\" --privacy strict --verbose\n```\n\n网络故障时的输出：\n```\n============================================================\n🔍 错误诊断报告：\n\n🌐 网络问题：\n ✗ duckduckgo: 网络连接失败: Connection timed out after 10s\n 1. 检查网络连接是否正常（ping www.baidu.com）\n 2. 确认网络环境不受限制\n\n🔧 引擎问题：\n ✗ yandex: 引擎解析或请求失败: HTML parser error\n 1. yandex 可能已更新页面结构\n 2. 暂不支持该引擎（可排除）\n```\n\n---\n\n## strict 模式可用引擎\n\n| 引擎 | 来源 | 国内速度 | 隐私保护 | 状态 |\n|------|------|---------|---------|------|\n| **SearXNG** | 本机 | ⭐⭐⭐⭐⭐ 极快 | 极高 | ✅ 最优先 |\n| **Yandex** | 俄罗斯 | ⭐⭐⭐⭐ 快 | 中等 | ✅ 默认启用 |\n| **Startpage** | 荷兰（Google 代理） | ⭐⭐⭐ 中等 | 高 | ✅ 默认启用 |\n| **Qwant** | 法国 | ⭐⭐⭐ 中等 | 高 | ✅ 默认启用 |\n| **Brave** | 美国 | ⭐⭐ 较慢 | 高 | ✅ 默认启用 |\n| **DuckDuckGo** | 美国 | ⭐ 不稳定 | 极高 | ⚠️ 最后备选 |\n\n优先顺序：SearXNG → Yandex → Startpage → Qwant → Brave → DuckDuckGo\n\n若以上全部不可用，默认**停止搜索**而非降级到国内引擎——因为 strict 用户的预期是宁可无结果也不泄露查询词。确需降级请加 `--allow-fallback`。\n\n---\n\n## 📝 推荐配置（首次只需改 3 项）\n\n```yaml\n# config.yaml - 新手推荐修改项\nsearch:\n default_engines: [\"baidu\", \"bing\", \"duckduckgo\", \"searxng\"] # ✅ 第1项\n timeout: 15 # ✅ 第2项（网速慢可增大）\n\nprivacy:\n default_mode: strict # ✅ 第3项（默认 privacy）\n```\n\n其他配置项暂不需要修改。\n\n### 想隐藏 IP\n\nstrict 模式不隐藏 IP，需自行配置代理：\n\n```yaml\nprivacy:\n strict:\n proxy: \"http://127.0.0.1:7890\" # 支持 http:// 与 socks5://\n```\n\n---\n\n## 🔧 启动 SearXNG（推荐）\n\nSearXNG 本地实例是 strict 模式的隐私基石，建议启动。\n\n### Docker 方式（推荐）\n\n```bash\npython scripts/searxng_manager start --method docker\n```\n\n### pip 方式（无 Docker）\n\n```bash\npython scripts/searxng_manager start --method pip\n```\n\n### 验证\n\n```bash\npython scripts/searxng_manager status\n# 应显示 running: true\n```\n\n---\n\n## ❓ 常见问题\n\n### Q1: 安装依赖失败？\n\n```bash\n# 换用国内镜像\npip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple\n```\n\n### Q2: SearXNG 启动失败？\n\nDocker 方式失败时，改用 pip：\n```bash\npython scripts/searxng_manager start --method pip\n```\n\n### Q3: 国内使用 strict 模式搜不到结果？\n\n按顺序自动尝试 Yandex → Startpage → Qwant → Brave → DDG。全部失败时默认停止并提示，不会静默降级。\n\n只用国内直连较好的几个：\n```bash\npython scripts/search.py \"关键词\" --privacy strict --engines yandex,startpage,qwant,searxng\n```\n\n确需降级到国内引擎：\n```bash\npython scripts/search.py \"关键词\" --privacy strict --allow-fallback\n```\n\n### Q4: 如何排除某个引擎？\n\n```bash\n# 排除 yandex，用其他 strict 引擎\npython scripts/search.py \"关键词\" --privacy strict --engines startpage,qwant,searxng\n```\n\n### Q5: 如何查看隐私保护详情？\n\n```bash\n# 独立的隐私报告\npython scripts/privacy report\n\n# 搜索时附带本次实际生效的隐私设置\npython scripts/search.py \"关键词\" --privacy strict --privacy-report\n```\n\n### Q6: 搜索记录会留在本地吗？\n\n会。缓存与历史存于 `~/.workbuddy/output/privacy-search-cache.db`。\n\n```bash\npython scripts/search.py --cache-stats # 查看占用\npython scripts/search.py --history # 查看历史\npython scripts/search.py --clear-cache # 清空缓存\npython scripts/search.py --clear-history # 清空历史\n```\n\n共享设备上建议在 config.yaml 设 `cache.enabled: false`。\n\n---\n\n## 📚 下一步\n\n- 完整文档 → [SKILL.md](../SKILL.md)\n- 搜索引擎适配器详情 → [engines_zh.md](engines_zh.md)\n- 配置说明 → [config.yaml.example](config.yaml.example)\n\n有建议？联系邮箱：njskills@agent.qq.com\n\nFile v1.8.0:skill-card.md\n\n## Description:\n\nPrivacy Search provides privacy-oriented multi-engine search, optional local SearXNG routing, result ranking, content fetching, synthesized answers with citations, fact checking, vertical search modes, and MCP tools for agent integrations.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[fyniujin](https://clawhub.ai/user/fyniujin)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent builders use Privacy Search to add privacy-aware web search, result export, content fetching, citation-backed synthesis, fact checking, and MCP-accessible search tools to local or agent workflows.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Search queries and fetched URLs may be sent to external search engines or web services.\n\nMitigation: Use strict privacy mode, prefer local SearXNG where appropriate, and configure a proxy or VPN when IP hiding matters.\n\nRisk: Local cache and search history can retain sensitive query data on shared devices.\n\nMitigation: Use --no-cache for sensitive searches, disable cache/history in configuration, or clear cache and history after use.\n\nRisk: MCP tools can let connected agents search, synthesize, or fetch arbitrary web content.\n\nMitigation: Expose MCP tools only to trusted agents and restrict tool availability when arbitrary URL fetches or external queries are not acceptable.\n\nRisk: Automated search can encounter engine rate limits, parsing failures, or service-term constraints.\n\nMitigation: Keep default rate limits, respect robots.txt and search engine terms, and run self-tests before relying on specific engines.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/fyniujin/skills/privacy-search)\n- [Quick Start](references/QUICK_START.md)\n- [Search engine adapter documentation](references/engines.md)\n- [MCP Server tool schema](references/mcp_schema.md)\n- [Configuration example](references/config.yaml.example)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, JSON, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown and JSON responses, with CLI command examples and MCP JSON-RPC tool payloads.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include web URLs, citations, search result metadata, fetched page text, cache/history notices, and privacy-mode diagnostics.]\n\n## Skill Version(s):\n\n1.8.0 (source: SKILL.md frontmatter and server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.8.0:requirements.txt\n\naiohttp>=3.9.0,<4.0.0\nbeautifulsoup4>=4.12.0,<5.0.0\nlxml>=5.0.0,<6.0.0\njieba>=0.42.1,<1.0.0\npyyaml>=6.0,<7.0.0\n\nArchive v1.7.0: 37 files, 143067 bytes\n\nFiles: references/engines_zh.md (5685b), references/engines.md (6702b), references/mcp_schema.md (6296b), references/QUICK_START.md (6889b), requirements.txt (111b), scripts/__init__.py (120b), scripts/cache.py (18188b), scripts/engine_selectors.py (11179b), scripts/engines_registry.py (8379b), scripts/exporters.py (7254b), scripts/http_client.py (9067b), scripts/logging_util.py (6073b), scripts/mcp_server.py (19512b), scripts/page_fetcher.py (4628b), scripts/privacy.py (13415b), scripts/quick_setup.py (6264b), scripts/ranking.py (25652b), scripts/search.py (57996b), scripts/searxng_manager.py (16141b), scripts/selftest_scheduler.py (8792b), scripts/summarizer.py (5769b), scripts/synthesiser.py (11201b), scripts/update_checker.py (16494b), scripts/version_util.py (7701b), skill-card.md (2718b), SKILL.md (20286b), tests/__init__.py (1134b), tests/test_mcp_server.py (14515b), tests/test_privacy.py (4413b), tests/test_search_v11.py (8269b), tests/test_search_v12.py (40380b), tests/test_search_v15.py (15182b), tests/test_search_v16.py (15210b), tests/test_search.py (7705b), tests/test_searxng.py (3469b), tests/test_update_checker.py (6124b), _meta.json (133b)\n\nFile v1.7.0:SKILL.md\n\n---\nname: privacy-search\ndescription: \"隐私优先的多引擎并行搜索 Skill，提供十大搜索引擎（百度/必应/搜狗/360/DuckDuckGo/Yandex/Startpage/Qwant/Brave/本地SearXNG）并行检索。V1.7 新增 MCP Server 形态（stdio JSON-RPC 2.0 暴露 search/synthesize/fetch 三工具），可被 Claude Code/Cursor/n8n 直接挂载，让搜索能力成为任何 Agent 的即插组件。V1.6 新增 Perplexity 式答案合成（引用+正文抓取+citation）和定时引擎失效告警，jieba 默认安装提升中文精度。支持结果缓存与搜索历史、统一 HTTP 出口（隐私头/UA池/代理/自动重试真正生效）、标准 SimHash 去重、多因子加权排序（共识度/位次/相关度/权威度/域名质量）、多套备选选择器与解析诊断、bangs 语法透传、网页正文抓取、搜索结果导出（Markdown/HTML/PDF）、LLM 摘要（智谱 GLM-4-Flash + 抽取式降级）、定时 selftest + 告警、MCP Server 生态桥接。SearXNG 本地实例双路径部署，隐私模式 normal/strict 一键切换，不污染系统 Python 环境。\"\nversion: 1.7.0\n---\n\n# 隐私搜索（Privacy Search）\n\n隐私优先的多引擎并行搜索 Skill。V1.7 新增 **MCP Server 形态**（stdio JSON-RPC 2.0 暴露 search/synthesize/fetch 三工具），可被 Claude Code / Cursor / n8n 直接挂载，让搜索能力成为任何 Agent 的即插组件。V1.6 新增 Perplexity 式答案合成（引用+正文抓取+citation）和定时引擎失效告警，jieba 默认安装提升中文相关度精度。V1.5 在搜索质量与隐私真实生效基础上，新增网页正文抓取、结果导出（Markdown/HTML/PDF）与 LLM 摘要（智谱 GLM-4-Flash + 抽取式降级）。\n\n## 环境要求\n\n- Python 3.10+\n- Docker（可选，推荐用于 SearXNG）\n- 网络连接（本地 SearXNG 启动后可离线搜索）\n- Windows / macOS / Linux\n\n## 🚀 快速开始\n\n```bash\n# 一键安装\npython scripts/quick_setup.py\n\n# 搜索\npython scripts/search.py \"关键词\"\npython scripts/search.py \"关键词\" --privacy strict\n\n# 隐私报告\npython scripts/privacy report\n\n# 检查更新\npython scripts/update_checker check\n```\n\n详细 5 分钟上手指南 → [QUICK_START.md](references/QUICK_START.md)\n\n## 核心命令\n\n### F1：多引擎并行搜索\n\n```bash\n# 基础搜索\npython -m scripts.search \"搜索关键词\"\n\n# 指定引擎\npython -m scripts.search \"关键词\" --engines baidu,bing,duckduckgo\n\n# strict 隐私模式\npython -m scripts.search \"关键词\" --privacy strict\n\n# strict 引擎全部失败时，显式授权降级到国内引擎\npython -m scripts.search \"关键词\" --privacy strict --allow-fallback\n\n# JSON 输出\npython -m scripts.search \"关键词\" --json\n\n# 错误诊断（网络/配置/引擎问题）\npython -m scripts.search \"关键词\" --privacy strict --verbose\n\n# 查看全部可用引擎\npython -m scripts.search --list-engines\n\n# 引擎连通性与解析健康度体检\npython -m scripts.search --selftest\n\n# 搜索后附带隐私保护摘要\npython -m scripts.search \"关键词\" --privacy strict --privacy-report\n```\n\n### F4：Perplexity 式答案合成（V1.6 新增）\n\n```bash\n# Pro 模式：抓取正文 + LLM 带 citation 生成答案\npython -m scripts.search \"关键词\" --synthesize-pro\n\n# 无 API Key 时自动降级为抽取式摘要+来源列表\npython -m scripts.search \"关键词\" --synthesize-pro --privacy strict\n```\n\n### F5：定时引擎告警（V1.6 新增）\n\n```bash\n# 手动执行一次 selftest 并发送告警\npython -m scripts.search --selftest-schedule run\n\n# 查看上次 selftest 结果\npython -m scripts.search --selftest-schedule status\n\n# 独立运行（支持阻塞式定时循环）\npython -m scripts.selftest_scheduler run\npython -m scripts.selftest_scheduler status\n```\n\n### F6：MCP Server（V1.7 新增）\n\n```bash\n# 启动 MCP Server（stdio 模式）\npython -m scripts.mcp_server\n\n# 查看工具 schema\npython -m scripts.mcp_server --schema\n\n# 协议自测\npython -m scripts.mcp_server --test\n```\n\nMCP Server 暴露三个工具：`search`（多引擎并行搜索）、`synthesize`（Perplexity 式答案合成）、`fetch`（网页正文抓取）。\n\n> 详细工具 schema 与桥接文档 → [references/mcp_schema.md](references/mcp_schema.md)\n\n### 缓存与搜索历史\n\n相同查询在有效期内直接复用结果，输出会标注「来源: 缓存」。\n\n```bash\n# 跳过缓存，强制重新搜索\npython -m scripts.search \"关键词\" --no-cache\n\n# 查看缓存占用\npython -m scripts.search --cache-stats\n\n# 清空缓存\npython -m scripts.search --clear-cache\n\n# 查看最近搜索历史（默认 20 条）\npython -m scripts.search --history\npython -m scripts.search --history 50\n\n# 清空搜索历史\npython -m scripts.search --clear-history\n```\n\n### bangs 快捷语法\n\n查询词中带 `!` 前缀时自动路由到本地 SearXNG，由其转发到目标站点。\n\n```bash\npython -m scripts.search \"!w 量子计算\" # 维基百科\npython -m scripts.search \"!gh asyncio\" # GitHub\npython -m scripts.search \"!yt python 教程\" # YouTube\n```\n\n> 该语法依赖本地 SearXNG。未启用时会提示并按普通关键词搜索。\n\n### F2：SearXNG 本地实例管理\n\n```bash\n# Docker 启动（推荐）\npython -m scripts.searxng_manager start --method docker\n\n# pip 启动\npython -m scripts.searxng_manager start --method pip\n\n# 状态检查\npython -m scripts.searxng_manager status\n\n# 停止\npython -m scripts.searxng_manager stop\n```\n\n### F3：隐私模式切换\n\n```bash\n# 状态查看\npython -m scripts.privacy status\n\n# 切换到 strict\npython -m scripts.privacy mode --set strict\n\n# 切换到 normal\npython -m scripts.privacy mode --set normal\n\n# 生成隐私保护报告\npython -m scripts.privacy report\n```\n\n### 版本更新检查（死规则 11）\n\n```bash\npython -m scripts.update_checker check\npython -m scripts.update_checker status\n```\n\n## 能做哪些\n\n| 能力 | 说明 |\n|------|------|\n| 多引擎并发搜索 | 10 引擎并行，标准 SimHash 去重 |\n| 多因子加权排序 | 共识度 + 位次 + 相关度 + 权威度 + 域名质量，权重可配 |\n| 结果缓存 | 相同查询秒回，容量上限自动淘汰 |\n| 搜索历史 | 本地留存最近 500 条，可查可清 |\n| 统一隐私出口 | 隐私头 / UA 池 / 代理 / 重试对全部引擎一致生效 |\n| 隐私优先兜底 | strict 下拒绝非白名单引擎，失败不静默降级 |\n| 本地 SearXNG | Docker/pip 双路径，query 不出本机 |\n| bangs 语法 | `!w` `!gh` `!yt` 等快捷跳转，经 SearXNG 转发 |\n| 解析健壮性 | 每引擎多套备选选择器，改版后自动尝试 |\n| 解析诊断 | 区分「确实无结果」「被拦截」「选择器失效」 |\n| 引擎体检 | `--selftest` 一次性检查各引擎连通与解析状态 |\n| 网络自动重试 | 指数退避 + 随机抖动，仅对网络类错误重试 |\n| 运行日志 | 级别可配，默认不记录查询词原文 |\n| 错误分类诊断 | 网络/配置/引擎三类问题，针对性排查 |\n| 版本更新提醒 | 启动异步检查，24h 不重复 |\n| 请求频率控制 | 单引擎日上限 200 + 随机延迟 |\n| venv 隔离 | pip 依赖全虚拟环境，不污染系统 |\n| Perplexity 式合成 | 抓取正文→分块→LLM 带 citation 生成答案（Pro 模式） |\n| 定时引擎告警 | 每日/每小时自动 selftest，失效引擎主动通知 |\n| jieba 中文分词 | 默认安装，中文相关度精度提升 |\n| MCP Server | stdio JSON-RPC 2.0 服务，暴露 search/synthesize/fetch 三工具 |\n| 生态桥接 | 可被 gov-procurement/contract-review 等 skill 经 MCP 调用 |\n\n## 不能做哪些（V1.6 限制）\n\n- ❌ **不隐藏 IP 地址**：未配置 `privacy.strict.proxy` 时搜索引擎仍可见您的 IP\n- ❌ **不保证 100% 正文抓取**：部分网站反爬严格，正文抓取可能失败\n- ❌ **不保证 LLM 摘要 100% 准确**：LLM 可能产生幻觉，建议核对来源\n- ❌ **不提供浏览器插件**（V2.0+ 规划）\n- ❌ **不保证引擎长期可解析**：搜索引擎改版后需等待选择器更新\n\n## 风险声明\n\n### 隐私边界\n\n| 风险 | 说明 | 缓解 |\n|------|------|------|\n| IP 可见性 | 不配置代理时引擎可见真实 IP | 设置 `privacy.strict.proxy` 或配合 VPN |\n| 搜索词明文传输 | 查询词需发送至引擎 | strict 走隐私引擎，或用本地 SearXNG |\n| 本地缓存留痕 | 缓存与历史含查询词，明文存于本地 | `--clear-cache` / `--clear-history`，或 `cache.enabled: false` |\n| 日志留痕 | 默认 INFO 只记录查询词长度 | 需完全静默可设 `logging.level: OFF` |\n| SearXNG 端口暴露 | 默认 127.0.0.1 | 禁止改为 0.0.0.0 |\n\n### 合规使用\n\n| 风险 | 说明 | 缓解 |\n|------|------|------|\n| 搜索引擎条款 | 自动化访问可能受限 | 尊重 robots.txt，勿调高频率上限 |\n| 数据合规 | 缓存与历史存于本地磁盘 | 共享设备建议关闭缓存 |\n\n## 常见错误\n\n> 遇到错误时，使用 `--verbose` 查看详细诊断\n\n### 网络故障 🌐\n\n```\n💡 网络连接失败，请检查网络或使用 --verbose 查看详情\n```\n\n排查：\n1. 检查网络：`ping www.baidu.com`\n2. 确认网络环境不受限\n3. 增大超时：`config.yaml` 中 `search.timeout: 20`\n\n### 配置错误 ⚙️\n\n```\n💡 配置错误，请检查 config.yaml 或使用 --verbose 查看详情\n```\n\n排查：\n1. 确认 YAML 格式正确（冒号后有空格）\n2. 复制 `references/config.yaml.example` 重新配置\n\n### 引擎错误 🔧\n\n```\n💡 搜索引擎解析失败，请稍后重试或更换引擎\n```\n\n排查：\n1. 运行 `python -m scripts.search --selftest` 定位具体原因\n2. 按诊断结论处理（见下表）\n3. 临时规避：用 `--engines` 排除该引擎\n\n### 解析诊断对照\n\n`--selftest` 与 `--verbose` 会输出诊断结论：\n\n| 诊断 | 含义 | 处理 |\n|------|------|------|\n| 正常 | 解析成功 | 无需处理 |\n| 确认无结果 | 该关键词确实无匹配 | 换关键词或换引擎 |\n| 被拦截 | 触发验证码或风控 | 降低频率，稍后重试 |\n| 选择器失效 | 引擎改版导致解析不到 | 更新到最新版本 |\n| 未知 | 页面结构异常 | 用 `--verbose` 查看详情 |\n\n## 常见问题\n\n**Q: strict 模式在国内能用吗？**\nA: 可以。strict 默认使用 Yandex（国内快）+ Startpage + Qwant + Brave，DDG 作最后备选。\n\n**Q: strict 模式下指定 `--engines baidu` 为什么没生效？**\nA: 这是有意设计。strict 模式会拒绝隐私保护不足的引擎，避免\"以为开了 strict 实际仍在向百度发送查询词\"。需要用百度请改用 `--privacy normal`。\n\n**Q: strict 模式搜不到结果，直接返回空？**\nA: 隐私引擎全部不可用时默认停止搜索，而非静默降级到国内引擎——因为 strict 用户的预期是宁可无结果也不泄露查询词。确需降级请加 `--allow-fallback`，或在配置中开启 `privacy.strict.allow_fallback`。\n\n**Q: 结果是旧的怎么办？**\nA: 默认缓存 1 小时。加 `--no-cache` 强制刷新，或调小 `cache.ttl_seconds`。\n\n**Q: 缓存文件会无限增长吗？**\nA: 不会。超过 `cache.max_size_mb`（默认 50MB）时自动淘汰最久未使用的条目，历史记录上限 500 条。\n\n**Q: 缓存和历史存在哪？如何彻底清除？**\nA: 默认在 `~/.workbuddy/output/privacy-search-cache.db`。`--clear-cache` 清结果，`--clear-history` 清历史，两者独立。\n\n**Q: 怎么确认隐私设置真的生效了？**\nA: 加 `--privacy-report` 查看本次搜索实际使用的请求头、代理与被屏蔽引擎。\n\n**Q: 如何隐藏 IP？**\nA: 在 config.yaml 设置 `privacy.strict.proxy`，支持 `http://` 与 `socks5://`。留空为直连。\n\n**Q: 某个引擎突然搜不到结果？**\nA: 先跑 `--selftest`。若显示「选择器失效」说明该引擎改版了，请更新到最新版本；显示「被拦截」则是触发了风控，稍后再试或换引擎。\n\n**Q: 为什么指定了 searxng 却没用上？**\nA: 检查 `searxng.enabled` 是否为 true，以及本地实例是否已启动（`python -m scripts.searxng_manager status`）。\n\n**Q: 排序结果不满意能调吗？**\nA: 可以。config.yaml 的 `ranking` 段可调五个权重，例如更看重多引擎共识就调高 `consensus`。\n\n**Q: 中文分词报缺少 jieba？**\nA: jieba 为可选依赖，缺失时自动降级为字符级切分，搜索仍可用。安装后相关度排序更准。\n\n**Q: 会记录我搜了什么吗？**\nA: 日志默认 INFO 级别，只记录查询词长度不记录原文；搜索历史存于本地且可随时清空。需完全静默可设 `logging.level: OFF`。\n\n**Q: SearXNG 启动失败？**\nA: 尝试切换：`--method pip`。确保 Docker 或 Python 3.10+ 可用。\n\n**Q: 如何关闭更新检查？**\nA: `python -m scripts.update_checker disable`\n\n**Q: 安装依赖失败？**\nA: `pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple`\n\n**Q: 支持哪些引擎？**\nA: 10 个：百度、必应、搜狗、360、DuckDuckGo、Yandex、Startpage、Qwant、Brave、本地 SearXNG。运行 `--list-engines` 查看完整属性。\n\n**Q: 如何在其他程序里调用？**\nA: 当前支持两种方式：① 命令行 `--json` 获取结构化输出；② MCP Server（V1.7 新增），通过 stdio JSON-RPC 2.0 暴露 search/synthesize/fetch 三工具，可被 Claude Code、Cursor、n8n 等直接挂载。详见 `references/mcp_schema.md`。\n\n**Q: Pro 模式和普通摘要的区别？**\nA: Pro 模式会抓取搜索结果正文并生成带 citation 的答案，每个论断都能追溯到来源。普通摘要（`--summarize`）只基于 snippet 生成简短总结。Pro 模式需要配置 `synthesis.api_key`，无 Key 时自动降级为抽取式摘要。\n\n**Q: Pro 模式抓取正文失败怎么办？**\nA: 系统会自动降级为该结果的 snippet，不会中断整体流程。可在 config.yaml 调整 `synthesis.fetch_timeout` 和 `synthesis.chunk_size`。\n\n**Q: 定时 selftest 怎么配置每天跑一次？**\nA: config.yaml 中设置 `selftest_schedule.interval: daily`，然后用系统 cron 或任务计划程序定时触发 `python scripts/search.py --selftest-schedule run`。当前不支持后台常驻进程。\n\n**Q: selftest 告警发到哪？**\nA: 默认写入 `~/.workbuddy/output/privacy-search-selftest.log`，设置 `selftest_schedule.alert_channel: both` 可同时推送到企业微信 webhook。\n\n**Q: 如何配置 webhook 告警？**\nA: 在 config.yaml 的 `selftest_schedule.webhook_url` 填入企业微信/钉钉机器人的 webhook 地址。\n\n**Q: 配置项太多，哪些必须改？**\nA: 首次只需改 3 项（config.yaml 中标注 [推荐修改]）：`default_engines`、`timeout`、`default_mode`。其他保持默认。\n\n**Q: MCP Server 是什么？怎么用？**\nA: MCP Server 是 V1.7 新增的 stdio JSON-RPC 2.0 服务，把搜索/合成/抓取能力暴露为标准工具协议。运行 `python scripts/mcp_server.py` 即可启动，可被 Claude Code、Cursor、n8n 等支持 MCP 的客户端挂载。详见 `references/mcp_schema.md`。\n\n**Q: MCP Server 暴露了哪些工具？**\nA: 3 个工具：`search`（多引擎隐私搜索）、`synthesize`（Perplexity 式答案合成）、`fetch`（URL 正文抓取）。可通过 config.yaml 的 `mcp_server.tools` 缩减子集。\n\n**Q: MCP Server 超时怎么办？**\nA: 默认单次调用 30 秒，超时返回 JSON-RPC 错误响应，不中断服务。可在 config.yaml 调整 `mcp_server.timeout`。LLM 不可用时自动降级为抽取式，不影响 search/fetch 工具。\n\n## 项目结构\n\n```\nprivacy-search/\n├── SKILL.md # 本文件\n├── requirements.txt # Python 依赖\n├── scripts/\n│ ├── __init__.py\n│ ├── search.py # F1: 搜索编排与 CLI\n│ ├── searxng_manager.py # F2: SearXNG 管理\n│ ├── privacy.py # F3: 隐私模式与请求上下文\n│ ├── engines_registry.py # 引擎清单单一真相源\n│ ├── engine_selectors.py # 各引擎选择器与解析诊断\n│ ├── http_client.py # 统一 HTTP 出口（UA池/代理/重试）\n│ ├── ranking.py # SimHash 去重与多因子排序\n│ ├── cache.py # 结果缓存与搜索历史\n│ ├── logging_util.py # 运行日志\n│ ├── version_util.py # 版本解析单一真相源\n│ ├── update_checker.py # 更新检查（死规则 11）\n│ ├── quick_setup.py # 一键安装\n│ ├── synthesiser.py # F4: Perplexity 式答案合成（V1.6 新增）\n│ ├── selftest_scheduler.py # F5: 定时 selftest 告警（V1.6 新增）\n│ └── mcp_server.py # F6: MCP Server stdio JSON-RPC 2.0（V1.7 新增）\n├── references/\n│ ├── config.yaml.example # 配置模板（含推荐配置标注）\n│ ├── engines.md # 引擎适配器文档\n│ ├── engines_zh.md # 国内引擎与降级策略\n│ ├── mcp_schema.md # MCP 工具 Schema 文档（V1.7 新增）\n│ └── QUICK_START.md # 快速上手\n└── tests/\n ├── test_search.py # 搜索基础测试\n ├── test_search_v11.py # 引擎与降级测试\n ├── test_search_v12.py # 缓存/排序/日志测试\n ├── test_search_v15.py # V1.5 新模块测试\n ├── test_search_v16.py # V1.6 新模块测试\n ├── test_mcp_server.py # MCP Server 协议与工具测试（V1.7 新增）\n ├── test_searxng.py # SearXNG 管理测试\n ├── test_privacy.py # 隐私模式测试\n └── test_update_checker.py # 更新检查测试\n```\n\n## 更新日志\n\n| v1.7.0 | 2026-08-28 | 增加：MCP Server 形态（stdio JSON-RPC 2.0 暴露 search/synthesize/fetch 三工具）；增加：生态桥接文档（references/mcp_schema.md）；增加：MCP Server 配置段（config.yaml） |\n| v1.6.0 | 2026-08-17 | 增加：Perplexity 式答案合成（抓取正文→分块→LLM 带 citation 生成答案）；增加：定时 selftest 调度+引擎失效告警（每日/每小时，支持 webhook）；调整：jieba 从可选改为默认安装，中文相关度精度提升；优化：无 API Key 时 Pro 模式自动降级为抽取式摘要+来源列表 |\n| v1.5.0 | 2026-08-07 | 增加：网页正文抓取模块（trafilatura/boilerpy3/正则三层降级）；增加：搜索结果导出（Markdown/HTML/PDF，PDF 有降级方案）；增加：LLM 摘要（智谱 GLM-4-Flash + 抽取式降级）；增加：引擎统计与动态降级（按历史成功率选引擎）；增加：UA 池可配置化（config.yaml 追加）；增加：TF-IDF 相关度算法（jieba 分词 + 余弦相似度）；增加：降级引擎列表可配置；优化：域名质量表扩展（+30 常用中文站点）；优化：SearXNG Secret 持久化（重启不失效）；优化：request_delay 默认值与示例文件一致（1.0-5.0）；优化：update_check 接入 search.py 启动检查；修复：github_url 占位符替换为 njskills；修复：引擎改版 mock 回归测试 |\n| v1.1.0 | 2026-07-19 | 增加4个国内可用备选引擎（Yandex/Startpage/Qwant/Brave）；strict模式自动降级与故障转移；增强错误分类（网络/配置/引擎三类）；增加10+FAQ与常见错误反模式对照；增加normal/strict模式搜索输出示例；增加5分钟快速上手指南QUICK_START.md；增加一键安装脚本quick_setup.py |\n| v1.0.0 | 2026-07-18 | 初始版本发布：多引擎并行搜索（F1）；SearXNG本地实例双路径部署（F2）；隐私模式normal/strict切换（F3）；版本更新检查提醒（死规则11）；SimHash去重与交叉验证排序 |\n\n## 支持与反馈\n\n- **联系邮箱**：njskills@agent.qq.com\n- **问题反馈**：欢迎通过邮件或 SkillHub 评论提出建议\n- **版本更新**：运行 `python -m scripts.update_checker check` 检查新版本\n\nFile v1.7.0:_meta.json\n\n{\n \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n \"slug\": \"privacy-search\",\n \"version\": \"1.7.0\",\n \"publishedAt\": 1787580853706\n}\n\nFile v1.7.0:references/engines_zh.md\n\n# 国内可用搜索引擎指南\n\n本文档说明 strict 模式下各引擎的国内可用性、隐私保护级别和自动降级策略。\n\n## 引擎对比\n\n| 引擎 | 国家 | 国内速度 | 隐私保护 | 数据收集 | 追踪 | strict 默认 | 备注 |\n|------|------|---------|---------|---------|------|-----------|------|\n| **SearXNG（本地）** | 本机 | ⭐⭐⭐⭐⭐ 极快 | 极高 | ❌ 无 | ❌ 无 | ✅ 最优先 | query 不出本机，最佳隐私 |\n| **Yandex** | 俄罗斯 | ⭐⭐⭐⭐ 快 | 中等 | 部分 | 少量 | ✅ | 俄文界面可用，中文搜索能力较好 |\n| **Startpage** | 荷兰 | ⭐⭐⭐ 中等 | 高 | ❌ 无 | ❌ 无 | ✅ | Google 代理，结果质量高 |\n| **Qwant** | 法国 | ⭐⭐⭐ 中等 | 高 | ❌ 无 | ❌ 无 | ✅ | 欧洲隐私法保护 |\n| **Brave** | 美国 | ⭐⭐ 较慢 | 高 | ❌ 无 | ❌ 无 | ✅ | 独立搜索引擎，不依赖 Google |\n| **DuckDuckGo** | 美国 | ⭐ 不稳定 | 极高 | ❌ 无 | ❌ 无 | ⚠️ 最后 | 国内连接不稳定，仅作兜底 |\n\n## 自动降级策略\n\n```\nstrict 模式搜索流程：\n┌──────────────────────────────────────────────────────┐\n│ SearXNG（本地，最优先） │\n│ query 不出本机，极速响应 │\n└────────────────────┬─────────────────────────────────┘\n │ (不可用时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ Yandex + Startpage + Qwant + Brave │\n│ 并发请求，SimHash 去重 │\n└────────────────────┬─────────────────────────────────┘\n │ (全部失败时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ DuckDuckGo（不稳定时使用） │\n└────────────────────┬─────────────────────────────────┘\n │ (仍失败时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ 默认：停止搜索并提示，不泄露查询词 │\n│ 显式加 --allow-fallback 才降级到 bing/baidu │\n└──────────────────────────────────────────────────────┘\n```\n\n### 为什么默认不降级\n\nstrict 模式的用户预期是「宁可没有结果，也不把查询词发给隐私保护不足的引擎」。\n静默降级到百度/必应会让用户在毫不知情的情况下失去隐私保护，属于违背预期的危险默认值。\n因此 V1.2 起改为默认拒绝，需通过 `--allow-fallback` 或配置项 `privacy.strict.allow_fallback` 显式授权。\n\n同理，strict 模式下即使用 `--engines baidu` 显式指定，也会被拒绝并提示改用 normal 模式。\n\n## 推荐使用方式\n\n### 最佳隐私（推荐）\n```bash\npython scripts/search.py \"关键词\" --privacy strict --engines searxng,yandex,startpage\n```\n- query 完全在本地\n- Yandex + Startpage 作为离线后备\n\n### 最佳速度\n```bash\npython scripts/search.py \"关键词\" --engines baidu,bing\n```\n- 国内引擎最快\n- normal 模式下的推荐选择\n\n### 平衡模式\n```bash\npython scripts/search.py \"关键词\" --privacy strict --engines yandex,searxng\n```\n- 速度隐私均衡\n- Yandex 国内速度快 + SearXNG 极致隐私\n\n## 常见问题：特定引擎故障\n\n### Yandex 故障\n- 可能原因：反爬升级、IP 限制\n- 解决：等待自动降级到 Startpage/Qwant\n\n### 全部 strict 引擎失败\n- 可能原因：网络受限、DNS 污染\n- 解决：\n ```bash\n 1. 检查网络：ping yandex.com\n 2. 配置代理（config.yaml 中 search.proxy）\n 3. 降级使用 normal 模式\n ```\n\n### DDG 在国内不可用\n- 常见现象，自动使用其他隐私引擎替代\n- 配置 `privacy.strict.proxy` 后可恢复\n\n### 判断是引擎坏了还是关键词没匹配\n\n```bash\npython scripts/search.py --selftest\n```\n\n输出会区分「正常」「确认无结果」「被拦截」「选择器失效」四种状态。\n显示「选择器失效」说明该引擎改版了，需更新插件版本；「被拦截」则是触发风控，降低频率后重试。\n\n## 限制与规避\n\n| 问题 | 影响 | 规避方式 |\n|------|------|---------|\n| 搜索引擎改版 | HTML 解析失败 | 多套备选选择器自动尝试，仍失败则等待版本更新 |\n| 触发风控 | 返回验证码页 | 降低 `daily_request_limit`，增大请求间隔 |\n| CDN 劫持 | 结果被篡改 | 全程 HTTPS + 多引擎交叉验证 |\n| DNS 污染 | 域名解析到错误 IP | 配置 `privacy.strict.proxy` |\n| IP 过滤 | 特定 IP 被封锁 | 配置代理，或改用本地 SearXNG |\n| 跳转链接 | 国内引擎返回中转地址 | 排序时自动识别并降权 |\n\n---\n\n有更好建议：njskills@agent.qq.com\n\nFile v1.7.0:references/engines.md\n\n# 搜索引擎适配器文档\n\n本文档说明各搜索引擎的实现细节、解析规则与扩展方式，对应 V1.2 架构。\n\n## 引擎列表\n\n引擎清单的唯一来源是 `scripts/engines_registry.py`，运行 `python -m scripts.search --list-engines` 可查看实时属性。\n\n| 引擎名称 | 标识 | 类型 | 区域 | 隐私等级 | strict 可用 | 说明 |\n|---------|------|------|------|---------|------------|------|\n| 本地 SearXNG | `searxng` | JSON API | 本机 | 高 | ✅ | 元搜索，query 不出本机，支持 bangs |\n| Yandex | `yandex` | HTML 解析 | 俄罗斯 | 中 | ✅ | 国内直连速度较好 |\n| Startpage | `startpage` | HTML 解析 | 荷兰 | 高 | ✅ | Google 结果代理 |\n| Qwant | `qwant` | HTML 解析 | 法国 | 高 | ✅ | 受欧盟隐私法约束 |\n| Brave Search | `brave` | HTML 解析 | 美国 | 高 | ✅ | 独立索引 |\n| DuckDuckGo | `duckduckgo` | HTML 解析 | 美国 | 高 | ✅ | 国内直连不稳定，作兜底 |\n| 百度 | `baidu` | HTML 解析 | 中国 | 低 | ❌ | 反爬较强，返回跳转链接 |\n| 必应 | `bing` | HTML 解析 | 中国 | 低 | ❌ | 国内可直接访问 |\n| 搜狗 | `sogou` | HTML 解析 | 中国 | 低 | ❌ | 返回跳转链接 |\n| 360 搜索 | `360` | HTML 解析 | 中国 | 低 | ❌ | 返回跳转链接 |\n\n## 架构分层\n\nV1.2 将传输与解析彻底分离，适配器不再各自处理 HTTP 细节。\n\n```\nCLI / SearchOrchestrator\n │\n ├── engines_registry.py 引擎清单与元数据（单一真相源）\n │\n ├── privacy.py 隐私配置 → RequestContext\n │ │\n ├── http_client.py 统一出口：UA 池 / 隐私头 / 代理 / 重试\n │ │\n ├── EngineAdapter 仅负责 build_url() 与结果映射\n │ │\n ├── engine_selectors.py 多套备选选择器 + 解析诊断\n │\n ├── ranking.py SimHash 去重 + 多因子加权排序\n │\n ├── cache.py 结果缓存与搜索历史\n │\n └── logging_util.py 运行日志\n```\n\n这样设计的原因：V1.1 时九个适配器各自硬编码请求头，导致隐私配置无法统一生效——只有三个适配器偶然带了 `DNT: 1`。收归统一出口后，隐私设置对所有引擎一致有效。\n\n## 请求策略\n\n### 超时与重试\n- 超时由 `search.timeout` 控制，默认 15 秒\n- 仅对网络类错误重试（连接失败、超时、连接重置），解析失败不重试\n- 指数退避 + 随机抖动，避免多引擎同时重试形成请求尖峰\n- 重试次数由 `search.retry_max` 控制，默认 2 次\n\n### 频率控制\n- 每日上限：单引擎 200 次（`search.daily_request_limit`）\n- 请求间隔：1–5 秒随机延迟\n- 超限自动跳过该引擎，不影响其他引擎\n\n### 请求头\n所有引擎统一经由 `http_client` 出口，不再逐引擎硬编码。\n\n| 模式 | User-Agent | DNT | Cookie | Referer | 代理 |\n|------|-----------|-----|--------|---------|------|\n| normal | UA 池随机 | 按配置 | 保留 | 保留 | 按配置 |\n| strict | UA 池随机 | `1` | 移除 | 移除 + `Referrer-Policy: no-referrer` | 按配置 |\n\nUA 池内置 8 个主流浏览器标识，随机轮换以降低指纹一致性。在 `privacy.strict.user_agent` 填入固定值可覆盖此行为。\n\n## 解析规则\n\n每个引擎配置多套备选选择器（见 `engine_selectors.py`）。首套解析不到结果时自动尝试下一套，用于缓解搜索引擎改版。\n\n### 百度\n- 容器：`div.result, div.result-op` → `div[class*='result']` → `div#content_left > div`\n- 标题：`h3 a`\n- 摘要：`div.c-abstract` 等\n\n### 必应\n- 容器：`li.b_algo` → `.b_algo`\n- 标题：`h2 a`\n- 摘要：`p`\n\n### DuckDuckGo\n- 容器：`div.result` → `div.web-result`\n- 标题：`a.result__a`\n- 摘要：`a.result__snippet`\n\n### SearXNG\n- 端点：`GET /search?q=...&format=json`\n- 响应：`results[].title / url / content`\n- 支持 bangs 语法透传（`!w` `!gh` `!yt` 等）\n\n### 解析诊断\n\n解析为空时不直接判定\"无结果\"，而是区分四种情况：\n\n| 诊断 | 判定依据 | 含义 |\n|------|---------|------|\n| `EMPTY_CONFIRMED` | 页面含\"没有找到相关结果\"等标记 | 确实无匹配 |\n| `BLOCKED` | 页面含验证码、安全验证等标记 | 触发风控 |\n| `SELECTOR_STALE` | 页面正常但所有选择器均未命中 | 引擎已改版 |\n| `UNKNOWN` | 其余情况 | 需人工查看 |\n\n这个区分很重要：把\"引擎改版\"误报为\"无结果\"会让用户以为搜索词有问题，而非插件需要更新。\n\n### 跳转链接处理\n\n百度、搜狗、360 返回的是形如 `baidu.com/link?url=...` 的中转地址而非真实 URL。这类链接会导致跨引擎去重失效（同一结果在不同引擎下 URL 不同）且域名质量评分失准，因此排序时统一降权。\n\n## SimHash 去重\n\nV1.2 采用标准 SimHash 实现（V1.1 的 MD5 异或合并并非真正的 SimHash，近似文本无法识别）。\n\n1. 中文用 jieba 分词，缺失时降级为 2-gram 字符切分\n2. 统计词频作为特征权重\n3. 每个特征取 MD5 哈希，按位加权投票：该位为 1 则加权重，为 0 则减权重\n4. 投票结果 > 0 的位置为 1，得到 64 位指纹\n5. 汉明距离 ≤ 3 视为重复\n\n## 多因子加权排序\n\n综合得分由五个因子加权求和，权重可在 `config.yaml` 的 `ranking` 段调整：\n\n| 因子 | 默认权重 | 说明 |\n|------|---------|------|\n| 共识度 | 6.0 | 被越多引擎收录越可信 |\n| 位次 | 3.0 | 引擎内原始排名，对数衰减 |\n| 相关度 | 4.0 | 查询词在标题摘要中的覆盖率 |\n| 权威度 | 2.0 | 引擎自身权威度，取自注册表 |\n| 域名质量 | 1.5 | 优质站点加分，低质站点与跳转链接降权 |\n\n## 扩展指南\n\n新增引擎只需三步，无需改动传输层：\n\n1. 在 `engines_registry.py` 的 `ENGINE_REGISTRY` 中登记元数据\n2. 在 `engine_selectors.py` 的 `SELECTORS` 中配置选择器\n3. 在 `search.py` 中实现适配器，只需覆盖 `build_url()`\n\n```python\nclass NewEngineAdapter(EngineAdapter):\n \"\"\"新引擎适配器：仅需构造 URL，解析与传输由框架承担\"\"\"\n\n def __init__(self):\n super().__init__(\"newengine\")\n\n def build_url(self, query: str, num: int) -> str:\n return f\"https://example.com/search?q={quote(query)}&n={num}\"\n```\n\n若引擎返回 JSON 而非 HTML，参考 `SearXNGAdapter` 覆盖 `search()` 方法。\n\n完成后运行 `python -m scripts.search --selftest` 验证连通性与解析状态。\n\n---\n\n有更好建议：njskills@agent.qq.com\n\nFile v1.7.0:references/mcp_schema.md\n\n# MCP Server 工具 Schema 文档（V1.7）\n\n本文档描述 privacy-search MCP Server 的工具接口契约，供其他 skill 作者接入参考。\n\n## 运行方式\n\n```bash\n# 启动 MCP Server（stdio 模式）\npython scripts/mcp_server.py\n\n# 查看工具 schema\npython scripts/mcp_server.py --schema\n\n# 协议自测\npython scripts/mcp_server.py --test\n```\n\n## 工具列表\n\n| 工具名 | 描述 | 主要能力 |\n|--------|------|----------|\n| `search` | 多引擎并行搜索 | 10 引擎并发、SimHash 去重、多因子排序 |\n| `synthesize` | Perplexity 式答案合成 | 抓取正文、LLM 带 citation 生成 |\n| `fetch` | 网页正文抓取 | 三层降级提取正文 |\n\n---\n\n## 工具详细 Schema\n\n### 1. search — 多引擎并行搜索\n\n**描述**：同时检索百度、必应、DuckDuckGo、Yandex 等十大搜索引擎，SimHash 去重、多因子加权排序。\n\n**输入参数**：\n\n```json\n{\n \"query\": {\n \"type\": \"string\",\n \"description\": \"搜索查询词（必填）\"\n },\n \"engines\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"string\" },\n \"description\": \"指定引擎列表。可选值：baidu, bing, sogou, 360, duckduckgo, yandex, startpage, qwant, brave, searxng。留空时按隐私模式自动选择。\"\n },\n \"num\": {\n \"type\": \"integer\",\n \"description\": \"每个引擎返回结果数（默认 10，最大 20）\",\n \"default\": 10\n },\n \"privacy\": {\n \"type\": \"string\",\n \"enum\": [\"normal\", \"strict\"],\n \"description\": \"隐私模式：normal（全引擎）或 strict（仅隐私友好引擎）\",\n \"default\": \"normal\"\n },\n \"no_cache\": {\n \"type\": \"boolean\",\n \"description\": \"跳过缓存，强制重新搜索\",\n \"default\": false\n }\n}\n```\n\n**响应格式**：\n\n```json\n{\n \"results\": [\n {\n \"title\": \"标题\",\n \"url\": \"https://example.com\",\n \"snippet\": \"摘要\",\n \"engine\": \"baidu\",\n \"engines\": [\"baidu\", \"bing\"],\n \"rank\": 1,\n \"score\": 8.5\n }\n ],\n \"notices\": [\"提示信息\"],\n \"from_cache\": false,\n \"count\": 10\n}\n```\n\n---\n\n### 2. synthesize — Perplexity 式答案合成\n\n**描述**：抓取搜索结果正文，分块编号后调用 LLM 生成带 citation 的答案。每个论断都能追溯到具体来源。无 API Key 时自动降级为抽取式摘要。\n\n**输入参数**：\n\n```json\n{\n \"query\": {\n \"type\": \"string\",\n \"description\": \"用户问题（必填）\"\n },\n \"results\": {\n \"type\": \"array\",\n \"description\": \"搜索结果数组（可选）。未提供时自动先执行搜索。格式：[{\\\"title\\\":\\\"...\\\",\\\"url\\\":\\\"...\\\",\\\"snippet\\\":\\\"...\\\"}, ...]\"\n },\n \"max_sources\": {\n \"type\": \"integer\",\n \"description\": \"最多引用几个来源（默认 5，最大 10）\",\n \"default\": 5\n }\n}\n```\n\n**响应格式**：\n\n```json\n{\n \"answer\": \"这是 LLM 生成的答案 [1][2]。\\n\\n--- 来源 ---\\n[1] https://example.com/1\\n[2] https://example.com/2\",\n \"notices\": [\"提示信息\"]\n}\n```\n\n---\n\n### 3. fetch — 网页正文抓取\n\n**描述**：从指定 URL 提取正文内容，三层降级：trafilatura → boilerpy3 → 正则
标签。\n\n**输入参数**：\n\n```json\n{\n \"url\": {\n \"type\": \"string\",\n \"description\": \"目标网页 URL（必填）\"\n },\n \"timeout\": {\n \"type\": \"integer\",\n \"description\": \"抓取超时（秒），默认 10\",\n \"default\": 10\n }\n}\n```\n\n**响应格式**：\n\n```json\n{\n \"url\": \"https://example.com\",\n \"text\": \"正文内容...\",\n \"success\": true,\n \"length\": 1234\n}\n```\n\n---\n\n## 超时与降级策略\n\n### 超时配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `mcp_server.timeout` | 30s | 单次工具调用超时 |\n| `mcp_server.max_results` | 10 | search 工具默认最大结果数 |\n| `mcp_server.max_sources` | 5 | synthesize 工具默认最大引用来源数 |\n| `synthesis.fetch_timeout` | 10s | 单个页面抓取超时 |\n| `search.timeout` | 15s | 单个引擎搜索超时 |\n\n### 降级策略\n\n| 场景 | 降级行为 |\n|------|----------|\n| LLM API Key 未配置 | synthesize 自动降级为抽取式摘要 + 来源列表 |\n| LLM 调用失败 | 同上 |\n| 页面正文抓取失败 | 降级使用该结果的 snippet |\n| 所有页面正文抓取失败 | 降级为抽取式摘要 |\n| 搜索引擎限流 | 自动重试 + 指数退避 |\n| strict 模式引擎全部失败 | 默认拒绝降级（隐私优先），可配置 `allow_fallback` |\n\n### 错误处理\n\n所有工具调用返回统一的错误格式：\n\n```json\n{\n \"error\": \"错误描述\"\n}\n```\n\n---\n\n## 生态桥接示例\n\n### 其他 skill 接入本 MCP Server\n\n根据\"章首桥接原则\"，其他 skill 可按以下方式探测并调用 privacy-search：\n\n```python\n# 1. 探测 privacy-search 是否已安装\nimport shutil\ndef is_privacy_search_available() -> bool:\n return shutil.which(\"python\") is not None # 检查 python 环境\n\n# 2. 调用 MCP Server（stdio 模式）\nimport subprocess\nproc = subprocess.Popen(\n [\"python\", \"scripts/mcp_server.py\"],\n stdin=subprocess.PIPE,\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n)\n\n# 3. 发送 initialize 请求\nimport json\ndef send_request(proc, method, params=None):\n msg = {\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": method}\n if params:\n msg[\"params\"] = params\n body = json.dumps(msg, ensure_ascii=False)\n length = len(body.encode(\"utf-8\"))\n proc.stdin.write(f\"Content-Length: {length}\\r\\n\\r\\n{body}\".encode())\n proc.stdin.flush()\n # 读取响应...\n```\n\n### 典型调用场景\n\n| 调用方 | 场景 | 推荐工具 |\n|--------|------|----------|\n| gov-procurement | 政策资料查询 | `search` + `fetch` |\n| contract-review | 法条补充检索 | `search` + `synthesize` |\n| 其他 skill | 通用搜索 | `search` |\n\n---\n\n## 接口契约稳定性承诺\n\n1. **版本化 schema**：工具 schema 随 SKILL.md 版本号同步更新\n2. **向后兼容**：小版本（1.x）内不删除/重命名工具参数\n3. **降级保证**：所有外部依赖（LLM、搜索引擎）都有降级方案\n4. **超时可控**：所有网络调用都有可配置的超时\n\n---\n\n## 配置示例\n\n```yaml\n# config.yaml\nmcp_server:\n enabled: true\n timeout: 30\n max_results: 10\n max_sources: 5\n\nsynthesis:\n enabled: true\n api_key: \"\" # 留空则强制降级\n provider: auto\n max_sources: 5\n\nsearch:\n timeout: 15\n num_results: 10\n```\n\nFile v1.7.0:references/QUICK_START.md\n\n# 隐私搜索 - 5 分钟快速上手指南\n\n> 从零开始，5 分钟内完成安装并执行你的第一次隐私搜索。\n\n---\n\n## 🚀 一键安装（推荐）\n\n```bash\npython scripts/quick_setup.py\n```\n\n一键完成：创建 venv → 安装依赖 → 复制配置 → 验证安装。\n\n---\n\n## 📋 手动安装（如需控制每一步）\n\n### Step 1: 创建虚拟环境\n\n```bash\npython -m venv .venv\n# Windows\n.venv\\Scripts\\activate\n# Linux/macOS\nsource .venv/bin/activate\n```\n\n### Step 2: 安装依赖\n\n```bash\npip install -r requirements.txt\n```\n\n### Step 3: 复制配置\n\n```bash\ncp references/config.yaml.example config.yaml\n```\n\n### Step 4: 验证安装\n\n```bash\npython scripts/search.py \"test\"\n```\n\n---\n\n## 🔍 你的第一次搜索\n\n### 基础搜索（默认引擎）\n\n```bash\npython scripts/search.py \"Python asyncio 教程\"\n```\n\n输出示例：\n```\n🔍 搜索: Python asyncio 教程 | 模式: normal | 结果: 18 条\n\n[1] Python asyncio 异步编程入门教程\n https://docs.python.org/zh-cn/3/library/asyncio.html\n 本教程将带你了解 Python asyncio 模块的基础知识...\n — bing\n\n[2] 超详细的 Python asyncio 教程，从入门到精通\n https://www.cnblogs.com/...\n 本文详细介绍 Python asyncio 的使用方法...\n — baidu\n```\n\n### 隐私搜索（strict 模式）\n\n```bash\npython scripts/search.py \"Python asyncio 教程\" --privacy strict\n```\n\n输出示例：\n```\n搜索: Python asyncio 教程 | 模式: strict | 来源: 实时 | 结果: 12 条\n\n[1] Python Asynchronous Programming\n https://docs.python.org/3/library/asyncio.html\n Learn how to use asyncio for concurrent programming...\n — yandex\n\n[2] Async IO in Python: A Complete Walkthrough\n https://realpython.com/async-io-python/\n Async IO is a concurrent programming design...\n — startpage, qwant\n```\n\n> strict 模式仅使用 SearXNG/Yandex/Startpage/Qwant/Brave/DDG。\n> 即使显式指定 `--engines baidu` 也会被拒绝，避免隐私承诺被绕过。\n\n### 缓存加速\n\n相同查询在 1 小时内直接复用结果，输出标注「来源: 缓存」。\n\n```bash\npython scripts/search.py \"Python asyncio 教程\" # 来源: 实时\npython scripts/search.py \"Python asyncio 教程\" # 来源: 缓存，秒回\npython scripts/search.py \"Python asyncio 教程\" --no-cache # 强制刷新\n```\n\n### 引擎体检\n\n搜不到结果时，先判断是引擎坏了还是关键词没匹配：\n\n```bash\npython scripts/search.py --selftest\n```\n\n输出会标明每个引擎是「正常」「被拦截」还是「选择器失效」。\n\n### 显示错误诊断网络问题时\n\n```bash\npython scripts/search.py \"test\" --privacy strict --verbose\n```\n\n网络故障时的输出：\n```\n============================================================\n🔍 错误诊断报告：\n\n🌐 网络问题：\n ✗ duckduckgo: 网络连接失败: Connection timed out after 10s\n 1. 检查网络连接是否正常（ping www.baidu.com）\n 2. 确认网络环境不受限制\n\n🔧 引擎问题：\n ✗ yandex: 引擎解析或请求失败: HTML parser error\n 1. yandex 可能已更新页面结构\n 2. 暂不支持该引擎（可排除）\n```\n\n---\n\n## strict 模式可用引擎\n\n| 引擎 | 来源 | 国内速度 | 隐私保护 | 状态 |\n|------|------|---------|---------|------|\n| **SearXNG** | 本机 | ⭐⭐⭐⭐⭐ 极快 | 极高 | ✅ 最优先 |\n| **Yandex** | 俄罗斯 | ⭐⭐⭐⭐ 快 | 中等 | ✅ 默认启用 |\n| **Startpage** | 荷兰（Google 代理） | ⭐⭐⭐ 中等 | 高 | ✅ 默认启用 |\n| **Qwant** | 法国 | ⭐⭐⭐ 中等 | 高 | ✅ 默认启用 |\n| **Brave** | 美国 | ⭐⭐ 较慢 | 高 | ✅ 默认启用 |\n| **DuckDuckGo** | 美国 | ⭐ 不稳定 | 极高 | ⚠️ 最后备选 |\n\n优先顺序：SearXNG → Yandex → Startpage → Qwant → Brave → DuckDuckGo\n\n若以上全部不可用，默认**停止搜索**而非降级到国内引擎——因为 strict 用户的预期是宁可无结果也不泄露查询词。确需降级请加 `--allow-fallback`。\n\n---\n\n## 📝 推荐配置（首次只需改 3 项）\n\n```yaml\n# config.yaml - 新手推荐修改项\nsearch:\n default_engines: [\"baidu\", \"bing\", \"duckduckgo\", \"searxng\"] # ✅ 第1项\n timeout: 15 # ✅ 第2项（网速慢可增大）\n\nprivacy:\n default_mode: strict # ✅ 第3项（默认 privacy）\n```\n\n其他配置项暂不需要修改。\n\n### 想隐藏 IP\n\nstrict 模式不隐藏 IP，需自行配置代理：\n\n```yaml\nprivacy:\n strict:\n proxy: \"http://127.0.0.1:7890\" # 支持 http:// 与 socks5://\n```\n\n---\n\n## 🔧 启动 SearXNG（推荐）\n\nSearXNG 本地实例是 strict 模式的隐私基石，建议启动。\n\n### Docker 方式（推荐）\n\n```bash\npython scripts/searxng_manager start --method docker\n```\n\n### pip 方式（无 Docker）\n\n```bash\npython scripts/searxng_manager start --method pip\n```\n\n### 验证\n\n```bash\npython scripts/searxng_manager status\n# 应显示 running: true\n```\n\n---\n\n## ❓ 常见问题\n\n### Q1: 安装依赖失败？\n\n```bash\n# 换用国内镜像\npip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple\n```\n\n### Q2: SearXNG 启动失败？\n\nDocker 方式失败时，改用 pip：\n```bash\npython scripts/searxng_manager start --method pip\n```\n\n### Q3: 国内使用 strict 模式搜不到结果？\n\n按顺序自动尝试 Yandex → Startpage → Qwant → Brave → DDG。全部失败时默认停止并提示，不会静默降级。\n\n只用国内直连较好的几个：\n```bash\npython scripts/search.py \"关键词\" --privacy strict --engines yandex,startpage,qwant,searxng\n```\n\n确需降级到国内引擎：\n```bash\npython scripts/search.py \"关键词\" --privacy strict --allow-fallback\n```\n\n### Q4: 如何排除某个引擎？\n\n```bash\n# 排除 yandex，用其他 strict 引擎\npython scripts/search.py \"关键词\" --privacy strict --engines startpage,qwant,searxng\n```\n\n### Q5: 如何查看隐私保护详情？\n\n```bash\n# 独立的隐私报告\npython scripts/privacy report\n\n# 搜索时附带本次实际生效的隐私设置\npython scripts/search.py \"关键词\" --privacy strict --privacy-report\n```\n\n### Q6: 搜索记录会留在本地吗？\n\n会。缓存与历史存于 `~/.workbuddy/output/privacy-search-cache.db`。\n\n```bash\npython scripts/search.py --cache-stats # 查看占用\npython scripts/search.py --history # 查看历史\npython scripts/search.py --clear-cache # 清空缓存\npython scripts/search.py --clear-history # 清空历史\n```\n\n共享设备上建议在 config.yaml 设 `cache.enabled: false`。\n\n---\n\n## 📚 下一步\n\n- 完整文档 → [SKILL.md](../SKILL.md)\n- 搜索引擎适配器详情 → [engines_zh.md](engines_zh.md)\n- 配置说明 → [config.yaml.example](config.yaml.example)\n\n有建议？联系邮箱：njskills@agent.qq.com\n\nFile v1.7.0:skill-card.md\n\n## Description:\n\nPrivacy Search provides privacy-oriented multi-engine web search, source-backed answer synthesis, page fetching, exports, and stdio MCP tools for agent workflows.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[fyniujin](https://clawhub.ai/user/fyniujin)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and external agent builders use Privacy Search to add privacy-oriented search, cited answer synthesis, and page fetching to CLI or MCP-based agent workflows.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: MCP fetch and synthesis tools can make unrestricted requests from the host and may expose localhost or private-network page contents.\n\nMitigation: Review before installing, expose the MCP server only to trusted agents, disable or remove fetch and synthesize unless needed, and avoid running it on hosts with sensitive localhost or private-network services.\n\nRisk: Search activity can leave local cache, history, or log traces.\n\nMitigation: Disable cache, history, and logs for sensitive searches, or clear cache and history after use.\n\nRisk: External search engines may receive query text and can see the host IP address when no proxy or local SearXNG path is used.\n\nMitigation: Use strict mode, prefer local SearXNG where appropriate, and configure a proxy or VPN when IP privacy is required.\n\nRisk: Setup depends on Python packages and optional containerized SearXNG components.\n\nMitigation: Prefer pinned dependencies or reviewed container digests before deployment.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/fyniujin/skills/privacy-search)\n- [Quick start guide](references/QUICK_START.md)\n- [MCP tool schema](references/mcp_schema.md)\n- [Search engine adapter documentation](references/engines.md)\n- [Domestic engine and fallback documentation](references/engines_zh.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, JSON, Files, Shell commands, Configuration, Guidance]\n\n**Output Format:** [CLI text, JSON-RPC JSON, Markdown/HTML/PDF exports, and markdown guidance with shell commands.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Search results may include source URLs, snippets, cache status, notices, fetched page text, and synthesized answers with citations; MCP exposes search, synthesize, and fetch tools.]\n\n## Skill Version(s):\n\n1.7.0 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.7.0:requirements.txt\n\naiohttp>=3.9.0,<4.0.0\nbeautifulsoup4>=4.12.0,<5.0.0\nlxml>=5.0.0,<6.0.0\njieba>=0.42.1,<1.0.0\npyyaml>=6.0,<7.0.0\n\nArchive v1.6.0: 34 files, 130277 bytes\n\nFiles: references/engines_zh.md (5685b), references/engines.md (6702b), references/QUICK_START.md (6889b), requirements.txt (111b), scripts/__init__.py (120b), scripts/cache.py (18188b), scripts/engine_selectors.py (11179b), scripts/engines_registry.py (8379b), scripts/exporters.py (7254b), scripts/http_client.py (9067b), scripts/logging_util.py (6073b), scripts/page_fetcher.py (4628b), scripts/privacy.py (13415b), scripts/quick_setup.py (6264b), scripts/ranking.py (25652b), scripts/search.py (57996b), scripts/searxng_manager.py (16141b), scripts/selftest_scheduler.py (8792b), scripts/summarizer.py (5769b), scripts/synthesiser.py (11201b), scripts/update_checker.py (16494b), scripts/version_util.py (7701b), skill-card.md (2729b), SKILL.md (17748b), tests/__init__.py (1134b), tests/test_privacy.py (4413b), tests/test_search_v11.py (8269b), tests/test_search_v12.py (40380b), tests/test_search_v15.py (15182b), tests/test_search_v16.py (15210b), tests/test_search.py (7705b), tests/test_searxng.py (3469b), tests/test_update_checker.py (6124b), _meta.json (133b)\n\nFile v1.6.0:SKILL.md\n\n---\nname: privacy-search\ndescription: \"隐私优先的多引擎并行搜索 Skill，提供十大搜索引擎（百度/必应/搜狗/360/DuckDuckGo/Yandex/Startpage/Qwant/Brave/本地SearXNG）并行检索。V1.6 新增 Perplexity 式答案合成（引用+正文抓取+citation）和定时引擎失效告警，jieba 默认安装提升中文精度。支持结果缓存与搜索历史、统一 HTTP 出口（隐私头/UA池/代理/自动重试真正生效）、标准 SimHash 去重、多因子加权排序（共识度/位次/相关度/权威度/域名质量）、多套备选选择器与解析诊断、bangs 语法透传、网页正文抓取、搜索结果导出（Markdown/HTML/PDF）、LLM 摘要（智谱 GLM-4-Flash + 抽取式降级）、定时 selftest + 告警。SearXNG 本地实例双路径部署，隐私模式 normal/strict 一键切换，不污染系统 Python 环境。\"\nversion: 1.6.0\n---\n\n\n# 隐私搜索（Privacy Search）\n\n隐私优先的多引擎并行搜索 Skill。V1.6 新增 **Perplexity 式答案合成**（引用+正文抓取+citation）和 **定时引擎失效告警**，jieba 默认安装提升中文相关度精度。V1.5 在搜索质量与隐私真实生效基础上，新增网页正文抓取、结果导出（Markdown/HTML/PDF）与 LLM 摘要（智谱 GLM-4-Flash + 抽取式降级）。\n\n## 环境要求\n\n- Python 3.10+\n- Docker（可选，推荐用于 SearXNG）\n- 网络连接（本地 SearXNG 启动后可离线搜索）\n- Windows / macOS / Linux\n\n## 🚀 快速开始\n\n```bash\n# 一键安装\npython scripts/quick_setup.py\n\n# 搜索\npython scripts/search.py \"关键词\"\npython scripts/search.py \"关键词\" --privacy strict\n\n# 隐私报告\npython scripts/privacy report\n\n# 检查更新\npython scripts/update_checker check\n```\n\n详细 5 分钟上手指南 → [QUICK_START.md](references/QUICK_START.md)\n\n## 核心命令\n\n### F1：多引擎并行搜索\n\n```bash\n# 基础搜索\npython -m scripts.search \"搜索关键词\"\n\n# 指定引擎\npython -m scripts.search \"关键词\" --engines baidu,bing,duckduckgo\n\n# strict 隐私模式\npython -m scripts.search \"关键词\" --privacy strict\n\n# strict 引擎全部失败时，显式授权降级到国内引擎\npython -m scripts.search \"关键词\" --privacy strict --allow-fallback\n\n# JSON 输出\npython -m scripts.search \"关键词\" --json\n\n# 错误诊断（网络/配置/引擎问题）\npython -m scripts.search \"关键词\" --privacy strict --verbose\n\n# 查看全部可用引擎\npython -m scripts.search --list-engines\n\n# 引擎连通性与解析健康度体检\npython -m scripts.search --selftest\n\n# 搜索后附带隐私保护摘要\npython -m scripts.search \"关键词\" --privacy strict --privacy-report\n```\n\n### F4：Perplexity 式答案合成（V1.6 新增）\n\n```bash\n# Pro 模式：抓取正文 + LLM 带 citation 生成答案\npython -m scripts.search \"关键词\" --synthesize-pro\n\n# 无 API Key 时自动降级为抽取式摘要+来源列表\npython -m scripts.search \"关键词\" --synthesize-pro --privacy strict\n```\n\n### F5：定时引擎告警（V1.6 新增）\n\n```bash\n# 手动执行一次 selftest 并发送告警\npython -m scripts.search --selftest-schedule run\n\n# 查看上次 selftest 结果\npython -m scripts.search --selftest-schedule status\n\n# 独立运行（支持阻塞式定时循环）\npython -m scripts.selftest_scheduler run\npython -m scripts.selftest_scheduler status\n```\n\n### 缓存与搜索历史\n\n相同查询在有效期内直接复用结果，输出会标注「来源: 缓存」。\n\n```bash\n# 跳过缓存，强制重新搜索\npython -m scripts.search \"关键词\" --no-cache\n\n# 查看缓存占用\npython -m scripts.search --cache-stats\n\n# 清空缓存\npython -m scripts.search --clear-cache\n\n# 查看最近搜索历史（默认 20 条）\npython -m scripts.search --history\npython -m scripts.search --history 50\n\n# 清空搜索历史\npython -m scripts.search --clear-history\n```\n\n### bangs 快捷语法\n\n查询词中带 `!` 前缀时自动路由到本地 SearXNG，由其转发到目标站点。\n\n```bash\npython -m scripts.search \"!w 量子计算\" # 维基百科\npython -m scripts.search \"!gh asyncio\" # GitHub\npython -m scripts.search \"!yt python 教程\" # YouTube\n```\n\n> 该语法依赖本地 SearXNG。未启用时会提示并按普通关键词搜索。\n\n### F2：SearXNG 本地实例管理\n\n```bash\n# Docker 启动（推荐）\npython -m scripts.searxng_manager start --method docker\n\n# pip 启动\npython -m scripts.searxng_manager start --method pip\n\n# 状态检查\npython -m scripts.searxng_manager status\n\n# 停止\npython -m scripts.searxng_manager stop\n```\n\n### F3：隐私模式切换\n\n```bash\n# 状态查看\npython -m scripts.privacy status\n\n# 切换到 strict\npython -m scripts.privacy mode --set strict\n\n# 切换到 normal\npython -m scripts.privacy mode --set normal\n\n# 生成隐私保护报告\npython -m scripts.privacy report\n```\n\n### 版本更新检查（死规则 11）\n\n```bash\npython -m scripts.update_checker check\npython -m scripts.update_checker status\n```\n\n## 能做哪些\n\n| 能力 | 说明 |\n|------|------|\n| 多引擎并发搜索 | 10 引擎并行，标准 SimHash 去重 |\n| 多因子加权排序 | 共识度 + 位次 + 相关度 + 权威度 + 域名质量，权重可配 |\n| 结果缓存 | 相同查询秒回，容量上限自动淘汰 |\n| 搜索历史 | 本地留存最近 500 条，可查可清 |\n| 统一隐私出口 | 隐私头 / UA 池 / 代理 / 重试对全部引擎一致生效 |\n| 隐私优先兜底 | strict 下拒绝非白名单引擎，失败不静默降级 |\n| 本地 SearXNG | Docker/pip 双路径，query 不出本机 |\n| bangs 语法 | `!w` `!gh` `!yt` 等快捷跳转，经 SearXNG 转发 |\n| 解析健壮性 | 每引擎多套备选选择器，改版后自动尝试 |\n| 解析诊断 | 区分「确实无结果」「被拦截」「选择器失效」 |\n| 引擎体检 | `--selftest` 一次性检查各引擎连通与解析状态 |\n| 网络自动重试 | 指数退避 + 随机抖动，仅对网络类错误重试 |\n| 运行日志 | 级别可配，默认不记录查询词原文 |\n| 错误分类诊断 | 网络/配置/引擎三类问题，针对性排查 |\n| 版本更新提醒 | 启动异步检查，24h 不重复 |\n| 请求频率控制 | 单引擎日上限 200 + 随机延迟 |\n| venv 隔离 | pip 依赖全虚拟环境，不污染系统 |\n| Perplexity 式合成 | 抓取正文→分块→LLM 带 citation 生成答案（Pro 模式） |\n| 定时引擎告警 | 每日/每小时自动 selftest，失效引擎主动通知 |\n| jieba 中文分词 | 默认安装，中文相关度精度提升 |\n\n## 不能做哪些（V1.6 限制）\n\n- ❌ **不隐藏 IP 地址**：未配置 `privacy.strict.proxy` 时搜索引擎仍可见您的 IP\n- ❌ **不保证 100% 正文抓取**：部分网站反爬严格，正文抓取可能失败\n- ❌ **不保证 LLM 摘要 100% 准确**：LLM 可能产生幻觉，建议核对来源\n- ❌ **不提供浏览器插件 / MCP Server**（V2.0+ 规划）\n- ❌ **不保证引擎长期可解析**：搜索引擎改版后需等待选择器更新\n\n## 风险声明\n\n### 隐私边界\n\n| 风险 | 说明 | 缓解 |\n|------|------|------|\n| IP 可见性 | 不配置代理时引擎可见真实 IP | 设置 `privacy.strict.proxy` 或配合 VPN |\n| 搜索词明文传输 | 查询词需发送至引擎 | strict 走隐私引擎，或用本地 SearXNG |\n| 本地缓存留痕 | 缓存与历史含查询词，明文存于本地 | `--clear-cache` / `--clear-history`，或 `cache.enabled: false` |\n| 日志留痕 | 默认 INFO 只记录查询词长度 | 需完全静默可设 `logging.level: OFF` |\n| SearXNG 端口暴露 | 默认 127.0.0.1 | 禁止改为 0.0.0.0 |\n\n### 合规使用\n\n| 风险 | 说明 | 缓解 |\n|------|------|------|\n| 搜索引擎条款 | 自动化访问可能受限 | 尊重 robots.txt，勿调高频率上限 |\n| 数据合规 | 缓存与历史存于本地磁盘 | 共享设备建议关闭缓存 |\n\n## 常见错误\n\n> 遇到错误时，使用 `--verbose` 查看详细诊断\n\n### 网络故障 🌐\n\n```\n💡 网络连接失败，请检查网络或使用 --verbose 查看详情\n```\n\n排查：\n1. 检查网络：`ping www.baidu.com`\n2. 确认网络环境不受限\n3. 增大超时：`config.yaml` 中 `search.timeout: 20`\n\n### 配置错误 ⚙️\n\n```\n💡 配置错误，请检查 config.yaml 或使用 --verbose 查看详情\n```\n\n排查：\n1. 确认 YAML 格式正确（冒号后有空格）\n2. 复制 `references/config.yaml.example` 重新配置\n\n### 引擎错误 🔧\n\n```\n💡 搜索引擎解析失败，请稍后重试或更换引擎\n```\n\n排查：\n1. 运行 `python -m scripts.search --selftest` 定位具体原因\n2. 按诊断结论处理（见下表）\n3. 临时规避：用 `--engines` 排除该引擎\n\n### 解析诊断对照\n\n`--selftest` 与 `--verbose` 会输出诊断结论：\n\n| 诊断 | 含义 | 处理 |\n|------|------|------|\n| 正常 | 解析成功 | 无需处理 |\n| 确认无结果 | 该关键词确实无匹配 | 换关键词或换引擎 |\n| 被拦截 | 触发验证码或风控 | 降低频率，稍后重试 |\n| 选择器失效 | 引擎改版导致解析不到 | 更新到最新版本 |\n| 未知 | 页面结构异常 | 用 `--verbose` 查看详情 |\n\n## 常见问题\n\n**Q: strict 模式在国内能用吗？**\nA: 可以。strict 默认使用 Yandex（国内快）+ Startpage + Qwant + Brave，DDG 作最后备选。\n\n**Q: strict 模式下指定 `--engines baidu` 为什么没生效？**\nA: 这是有意设计。strict 模式会拒绝隐私保护不足的引擎，避免\"以为开了 strict 实际仍在向百度发送查询词\"。需要用百度请改用 `--privacy normal`。\n\n**Q: strict 模式搜不到结果，直接返回空？**\nA: 隐私引擎全部不可用时默认停止搜索，而非静默降级到国内引擎——因为 strict 用户的预期是宁可无结果也不泄露查询词。确需降级请加 `--allow-fallback`，或在配置中开启 `privacy.strict.allow_fallback`。\n\n**Q: 结果是旧的怎么办？**\nA: 默认缓存 1 小时。加 `--no-cache` 强制刷新，或调小 `cache.ttl_seconds`。\n\n**Q: 缓存文件会无限增长吗？**\nA: 不会。超过 `cache.max_size_mb`（默认 50MB）时自动淘汰最久未使用的条目，历史记录上限 500 条。\n\n**Q: 缓存和历史存在哪？如何彻底清除？**\nA: 默认在 `~/.workbuddy/output/privacy-search-cache.db`。`--clear-cache` 清结果，`--clear-history` 清历史，两者独立。\n\n**Q: 怎么确认隐私设置真的生效了？**\nA: 加 `--privacy-report` 查看本次搜索实际使用的请求头、代理与被屏蔽引擎。\n\n**Q: 如何隐藏 IP？**\nA: 在 config.yaml 设置 `privacy.strict.proxy`，支持 `http://` 与 `socks5://`。留空为直连。\n\n**Q: 某个引擎突然搜不到结果？**\nA: 先跑 `--selftest`。若显示「选择器失效」说明该引擎改版了，请更新到最新版本；显示「被拦截」则是触发了风控，稍后再试或换引擎。\n\n**Q: 为什么指定了 searxng 却没用上？**\nA: 检查 `searxng.enabled` 是否为 true，以及本地实例是否已启动（`python -m scripts.searxng_manager status`）。\n\n**Q: 排序结果不满意能调吗？**\nA: 可以。config.yaml 的 `ranking` 段可调五个权重，例如更看重多引擎共识就调高 `consensus`。\n\n**Q: 中文分词报缺少 jieba？**\nA: jieba 为可选依赖，缺失时自动降级为字符级切分，搜索仍可用。安装后相关度排序更准。\n\n**Q: 会记录我搜了什么吗？**\nA: 日志默认 INFO 级别，只记录查询词长度不记录原文；搜索历史存于本地且可随时清空。需完全静默可设 `logging.level: OFF`。\n\n**Q: SearXNG 启动失败？**\nA: 尝试切换：`--method pip`。确保 Docker 或 Python 3.10+ 可用。\n\n**Q: 如何关闭更新检查？**\nA: `python -m scripts.update_checker disable`\n\n**Q: 安装依赖失败？**\nA: `pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple`\n\n**Q: 支持哪些引擎？**\nA: 10 个：百度、必应、搜狗、360、DuckDuckGo、Yandex、Startpage、Qwant、Brave、本地 SearXNG。运行 `--list-engines` 查看完整属性。\n\n**Q: 如何在其他程序里调用？**\nA: 当前仅支持命令行，可用 `--json` 获取结构化输出。MCP Server 在 V2.0 规划中。\n\n**Q: Pro 模式和普通摘要的区别？**\nA: Pro 模式会抓取搜索结果正文并生成带 citation 的答案，每个论断都能追溯到来源。普通摘要（`--summarize`）只基于 snippet 生成简短总结。Pro 模式需要配置 `synthesis.api_key`，无 Key 时自动降级为抽取式摘要。\n\n**Q: Pro 模式抓取正文失败怎么办？**\nA: 系统会自动降级为该结果的 snippet，不会中断整体流程。可在 config.yaml 调整 `synthesis.fetch_timeout` 和 `synthesis.chunk_size`。\n\n**Q: 定时 selftest 怎么配置每天跑一次？**\nA: config.yaml 中设置 `selftest_schedule.interval: daily`，然后用系统 cron 或任务计划程序定时触发 `python scripts/search.py --selftest-schedule run`。当前不支持后台常驻进程。\n\n**Q: selftest 告警发到哪？**\nA: 默认写入 `~/.workbuddy/output/privacy-search-selftest.log`，设置 `selftest_schedule.alert_channel: both` 可同时推送到企业微信 webhook。\n\n**Q: 如何配置 webhook 告警？**\nA: 在 config.yaml 的 `selftest_schedule.webhook_url` 填入企业微信/钉钉机器人的 webhook 地址。\n\n**Q: 配置项太多，哪些必须改？**\nA: 首次只需改 3 项（config.yaml 中标注 [推荐修改]）：`default_engines`、`timeout`、`default_mode`。其他保持默认。\n\n## 项目结构\n\n```\nprivacy-search/\n├── SKILL.md # 本文件\n├── requirements.txt # Python 依赖\n├── scripts/\n│ ├── __init__.py\n│ ├── search.py # F1: 搜索编排与 CLI\n│ ├── searxng_manager.py # F2: SearXNG 管理\n│ ├── privacy.py # F3: 隐私模式与请求上下文\n│ ├── engines_registry.py # 引擎清单单一真相源\n│ ├── engine_selectors.py # 各引擎选择器与解析诊断\n│ ├── http_client.py # 统一 HTTP 出口（UA池/代理/重试）\n│ ├── ranking.py # SimHash 去重与多因子排序\n│ ├── cache.py # 结果缓存与搜索历史\n│ ├── logging_util.py # 运行日志\n│ ├── version_util.py # 版本解析单一真相源\n│ ├── update_checker.py # 更新检查（死规则 11）\n│ ├── quick_setup.py # 一键安装\n│ ├── synthesiser.py # F4: Perplexity 式答案合成（V1.6 新增）\n│ └── selftest_scheduler.py # F5: 定时 selftest 告警（V1.6 新增）\n├── references/\n│ ├── config.yaml.example # 配置模板（含推荐配置标注）\n│ ├── engines.md # 引擎适配器文档\n│ ├── engines_zh.md # 国内引擎与降级策略\n│ └── QUICK_START.md # 快速上手\n└── tests/\n ├── test_search.py # 搜索基础测试\n ├── test_search_v11.py # 引擎与降级测试\n ├── test_search_v12.py # 缓存/排序/日志测试\n ├── test_search_v15.py # V1.5 新模块测试\n ├── test_search_v16.py # V1.6 新模块测试\n ├── test_searxng.py # SearXNG 管理测试\n ├── test_privacy.py # 隐私模式测试\n └── test_update_checker.py # 更新检查测试\n```\n\n## 更新日志\n\n| v1.6.0 | 2026-08-17 | 增加：Perplexity 式答案合成（抓取正文→分块→LLM 带 citation 生成答案）；增加：定时 selftest 调度+引擎失效告警（每日/每小时，支持 webhook）；调整：jieba 从可选改为默认安装，中文相关度精度提升；优化：无 API Key 时 Pro 模式自动降级为抽取式摘要+来源列表 |\n| v1.5.0 | 2026-08-07 | 增加：网页正文抓取模块（trafilatura/boilerpy3/正则三层降级）；增加：搜索结果导出（Markdown/HTML/PDF，PDF 有降级方案）；增加：LLM 摘要（智谱 GLM-4-Flash + 抽取式降级）；增加：引擎统计与动态降级（按历史成功率选引擎）；增加：UA 池可配置化（config.yaml 追加）；增加：TF-IDF 相关度算法（jieba 分词 + 余弦相似度）；增加：降级引擎列表可配置；优化：域名质量表扩展（+30 常用中文站点）；优化：SearXNG Secret 持久化（重启不失效）；优化：request_delay 默认值与示例文件一致（1.0-5.0）；优化：update_check 接入 search.py 启动检查；修复：github_url 占位符替换为 njskills；修复：引擎改版 mock 回归测试 |\n| v1.1.0 | 2026-07-19 | 增加4个国内可用备选引擎（Yandex/Startpage/Qwant/Brave）；strict模式自动降级与故障转移；增强错误分类（网络/配置/引擎三类）；增加10+FAQ与常见错误反模式对照；增加normal/strict模式搜索输出示例；增加5分钟快速上手指南QUICK_START.md；增加一键安装脚本quick_setup.py |\n| v1.0.0 | 2026-07-18 | 初始版本发布：多引擎并行搜索（F1）；SearXNG本地实例双路径部署（F2）；隐私模式normal/strict切换（F3）；版本更新检查提醒（死规则11）；SimHash去重与交叉验证排序 |\n\n## 支持与反馈\n\n- **联系邮箱**：njskills@agent.qq.com\n- **问题反馈**：欢迎通过邮件或 SkillHub 评论提出建议\n- **版本更新**：运行 `python -m scripts.update_checker check` 检查新版本\n\nFile v1.6.0:_meta.json\n\n{\n \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n \"slug\": \"privacy-search\",\n \"version\": \"1.6.0\",\n \"publishedAt\": 1786957895199\n}\n\nFile v1.6.0:references/engines_zh.md\n\n# 国内可用搜索引擎指南\n\n本文档说明 strict 模式下各引擎的国内可用性、隐私保护级别和自动降级策略。\n\n## 引擎对比\n\n| 引擎 | 国家 | 国内速度 | 隐私保护 | 数据收集 | 追踪 | strict 默认 | 备注 |\n|------|------|---------|---------|---------|------|-----------|------|\n| **SearXNG（本地）** | 本机 | ⭐⭐⭐⭐⭐ 极快 | 极高 | ❌ 无 | ❌ 无 | ✅ 最优先 | query 不出本机，最佳隐私 |\n| **Yandex** | 俄罗斯 | ⭐⭐⭐⭐ 快 | 中等 | 部分 | 少量 | ✅ | 俄文界面可用，中文搜索能力较好 |\n| **Startpage** | 荷兰 | ⭐⭐⭐ 中等 | 高 | ❌ 无 | ❌ 无 | ✅ | Google 代理，结果质量高 |\n| **Qwant** | 法国 | ⭐⭐⭐ 中等 | 高 | ❌ 无 | ❌ 无 | ✅ | 欧洲隐私法保护 |\n| **Brave** | 美国 | ⭐⭐ 较慢 | 高 | ❌ 无 | ❌ 无 | ✅ | 独立搜索引擎，不依赖 Google |\n| **DuckDuckGo** | 美国 | ⭐ 不稳定 | 极高 | ❌ 无 | ❌ 无 | ⚠️ 最后 | 国内连接不稳定，仅作兜底 |\n\n## 自动降级策略\n\n```\nstrict 模式搜索流程：\n┌──────────────────────────────────────────────────────┐\n│ SearXNG（本地，最优先） │\n│ query 不出本机，极速响应 │\n└────────────────────┬─────────────────────────────────┘\n │ (不可用时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ Yandex + Startpage + Qwant + Brave │\n│ 并发请求，SimHash 去重 │\n└────────────────────┬─────────────────────────────────┘\n │ (全部失败时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ DuckDuckGo（不稳定时使用） │\n└────────────────────┬─────────────────────────────────┘\n │ (仍失败时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ 默认：停止搜索并提示，不泄露查询词 │\n│ 显式加 --allow-fallback 才降级到 bing/baidu │\n└──────────────────────────────────────────────────────┘\n```\n\n### 为什么默认不降级\n\nstrict 模式的用户预期是「宁可没有结果，也不把查询词发给隐私保护不足的引擎」。\n静默降级到百度/必应会让用户在毫不知情的情况下失去隐私保护，属于违背预期的危险默认值。\n因此 V1.2 起改为默认拒绝，需通过 `--allow-fallback` 或配置项 `privacy.strict.allow_fallback` 显式授权。\n\n同理，strict 模式下即使用 `--engines baidu` 显式指定，也会被拒绝并提示改用 normal 模式。\n\n## 推荐使用方式\n\n### 最佳隐私（推荐）\n```bash\npython scripts/search.py \"关键词\" --privacy strict --engines searxng,yandex,startpage\n```\n- query 完全在本地\n- Yandex + Startpage 作为离线后备\n\n### 最佳速度\n```bash\npython scripts/search.py \"关键词\" --engines baidu,bing\n```\n- 国内引擎最快\n- normal 模式下的推荐选择\n\n### 平衡模式\n```bash\npython scripts/search.py \"关键词\" --privacy strict --engines yandex,searxng\n```\n- 速度隐私均衡\n- Yandex 国内速度快 + SearXNG 极致隐私\n\n## 常见问题：特定引擎故障\n\n### Yandex 故障\n- 可能原因：反爬升级、IP 限制\n- 解决：等待自动降级到 Startpage/Qwant\n\n### 全部 strict 引擎失败\n- 可能原因：网络受限、DNS 污染\n- 解决：\n ```bash\n 1. 检查网络：ping yandex.com\n 2. 配置代理（config.yaml 中 search.proxy）\n 3. 降级使用 normal 模式\n ```\n\n### DDG 在国内不可用\n- 常见现象，自动使用其他隐私引擎替代\n- 配置 `privacy.strict.proxy` 后可恢复\n\n### 判断是引擎坏了还是关键词没匹配\n\n```bash\npython scripts/search.py --selftest\n```\n\n输出会区分「正常」「确认无结果」「被拦截」「选择器失效」四种状态。\n显示「选择器失效」说明该引擎改版了，需更新插件版本；「被拦截」则是触发风控，降低频率后重试。\n\n## 限制与规避\n\n| 问题 | 影响 | 规避方式 |\n|------|------|---------|\n| 搜索引擎改版 | HTML 解析失败 | 多套备选选择器自动尝试，仍失败则等待版本更新 |\n| 触发风控 | 返回验证码页 | 降低 `daily_request_limit`，增大请求间隔 |\n| CDN 劫持 | 结果被篡改 | 全程 HTTPS + 多引擎交叉验证 |\n| DNS 污染 | 域名解析到错误 IP | 配置 `privacy.strict.proxy` |\n| IP 过滤 | 特定 IP 被封锁 | 配置代理，或改用本地 SearXNG |\n| 跳转链接 | 国内引擎返回中转地址 | 排序时自动识别并降权 |\n\n---\n\n有更好建议：njskills@agent.qq.com\n\nFile v1.6.0:references/engines.md\n\n# 搜索引擎适配器文档\n\n本文档说明各搜索引擎的实现细节、解析规则与扩展方式，对应 V1.2 架构。\n\n## 引擎列表\n\n引擎清单的唯一来源是 `scripts/engines_registry.py`，运行 `python -m scripts.search --list-engines` 可查看实时属性。\n\n| 引擎名称 | 标识 | 类型 | 区域 | 隐私等级 | strict 可用 | 说明 |\n|---------|------|------|------|---------|------------|------|\n| 本地 SearXNG | `searxng` | JSON API | 本机 | 高 | ✅ | 元搜索，query 不出本机，支持 bangs |\n| Yandex | `yandex` | HTML 解析 | 俄罗斯 | 中 | ✅ | 国内直连速度较好 |\n| Startpage | `startpage` | HTML 解析 | 荷兰 | 高 | ✅ | Google 结果代理 |\n| Qwant | `qwant` | HTML 解析 | 法国 | 高 | ✅ | 受欧盟隐私法约束 |\n| Brave Search | `brave` | HTML 解析 | 美国 | 高 | ✅ | 独立索引 |\n| DuckDuckGo | `duckduckgo` | HTML 解析 | 美国 | 高 | ✅ | 国内直连不稳定，作兜底 |\n| 百度 | `baidu` | HTML 解析 | 中国 | 低 | ❌ | 反爬较强，返回跳转链接 |\n| 必应 | `bing` | HTML 解析 | 中国 | 低 | ❌ | 国内可直接访问 |\n| 搜狗 | `sogou` | HTML 解析 | 中国 | 低 | ❌ | 返回跳转链接 |\n| 360 搜索 | `360` | HTML 解析 | 中国 | 低 | ❌ | 返回跳转链接 |\n\n## 架构分层\n\nV1.2 将传输与解析彻底分离，适配器不再各自处理 HTTP 细节。\n\n```\nCLI / SearchOrchestrator\n │\n ├── engines_registry.py 引擎清单与元数据（单一真相源）\n │\n ├── privacy.py 隐私配置 → RequestContext\n │ │\n ├── http_client.py 统一出口：UA 池 / 隐私头 / 代理 / 重试\n │ │\n ├── EngineAdapter 仅负责 build_url() 与结果映射\n │ │\n ├── engine_selectors.py 多套备选选择器 + 解析诊断\n │\n ├── ranking.py SimHash 去重 + 多因子加权排序\n │\n ├── cache.py 结果缓存与搜索历史\n │\n └── logging_util.py 运行日志\n```\n\n这样设计的原因：V1.1 时九个适配器各自硬编码请求头，导致隐私配置无法统一生效——只有三个适配器偶然带了 `DNT: 1`。收归统一出口后，隐私设置对所有引擎一致有效。\n\n## 请求策略\n\n### 超时与重试\n- 超时由 `search.timeout` 控制，默认 15 秒\n- 仅对网络类错误重试（连接失败、超时、连接重置），解析失败不重试\n- 指数退避 + 随机抖动，避免多引擎同时重试形成请求尖峰\n- 重试次数由 `search.retry_max` 控制，默认 2 次\n\n### 频率控制\n- 每日上限：单引擎 200 次（`search.daily_request_limit`）\n- 请求间隔：1–5 秒随机延迟\n- 超限自动跳过该引擎，不影响其他引擎\n\n### 请求头\n所有引擎统一经由 `http_client` 出口，不再逐引擎硬编码。\n\n| 模式 | User-Agent | DNT | Cookie | Referer | 代理 |\n|------|-----------|-----|--------|---------|------|\n| normal | UA 池随机 | 按配置 | 保留 | 保留 | 按配置 |\n| strict | UA 池随机 | `1` | 移除 | 移除 + `Referrer-Policy: no-referrer` | 按配置 |\n\nUA 池内置 8 个主流浏览器标识，随机轮换以降低指纹一致性。在 `privacy.strict.user_agent` 填入固定值可覆盖此行为。\n\n## 解析规则\n\n每个引擎配置多套备选选择器（见 `engine_selectors.py`）。首套解析不到结果时自动尝试下一套，用于缓解搜索引擎改版。\n\n### 百度\n- 容器：`div.result, div.result-op` → `div[class*='result']` → `div#content_left > div`\n- 标题：`h3 a`\n- 摘要：`div.c-abstract` 等\n\n### 必应\n- 容器：`li.b_algo` → `.b_algo`\n- 标题：`h2 a`\n- 摘要：`p`\n\n### DuckDuckGo\n- 容器：`div.result` → `div.web-result`\n- 标题：`a.result__a`\n- 摘要：`a.result__snippet`\n\n### SearXNG\n- 端点：`GET /search?q=...&format=json`\n- 响应：`results[].title / url / content`\n- 支持 bangs 语法透传（`!w` `!gh` `!yt` 等）\n\n### 解析诊断\n\n解析为空时不直接判定\"无结果\"，而是区分四种情况：\n\n| 诊断 | 判定依据 | 含义 |\n|------|---------|------|\n| `EMPTY_CONFIRMED` | 页面含\"没有找到相关结果\"等标记 | 确实无匹配 |\n| `BLOCKED` | 页面含验证码、安全验证等标记 | 触发风控 |\n| `SELECTOR_STALE` | 页面正常但所有选择器均未命中 | 引擎已改版 |\n| `UNKNOWN` | 其余情况 | 需人工查看 |\n\n这个区分很重要：把\"引擎改版\"误报为\"无结果\"会让用户以为搜索词有问题，而非插件需要更新。\n\n### 跳转链接处理\n\n百度、搜狗、360 返回的是形如 `baidu.com/link?url=...` 的中转地址而非真实 URL。这类链接会导致跨引擎去重失效（同一结果在不同引擎下 URL 不同）且域名质量评分失准，因此排序时统一降权。\n\n## SimHash 去重\n\nV1.2 采用标准 SimHash 实现（V1.1 的 MD5 异或合并并非真正的 SimHash，近似文本无法识别）。\n\n1. 中文用 jieba 分词，缺失时降级为 2-gram 字符切分\n2. 统计词频作为特征权重\n3. 每个特征取 MD5 哈希，按位加权投票：该位为 1 则加权重，为 0 则减权重\n4. 投票结果 > 0 的位置为 1，得到 64 位指纹\n5. 汉明距离 ≤ 3 视为重复\n\n## 多因子加权排序\n\n综合得分由五个因子加权求和，权重可在 `config.yaml` 的 `ranking` 段调整：\n\n| 因子 | 默认权重 | 说明 |\n|------|---------|------|\n| 共识度 | 6.0 | 被越多引擎收录越可信 |\n| 位次 | 3.0 | 引擎内原始排名，对数衰减 |\n| 相关度 | 4.0 | 查询词在标题摘要中的覆盖率 |\n| 权威度 | 2.0 | 引擎自身权威度，取自注册表 |\n| 域名质量 | 1.5 | 优质站点加分，低质站点与跳转链接降权 |\n\n## 扩展指南\n\n新增引擎只需三步，无需改动传输层：\n\n1. 在 `engines_registry.py` 的 `ENGINE_REGISTRY` 中登记元数据\n2. 在 `engine_selectors.py` 的 `SELECTORS` 中配置选择器\n3. 在 `search.py` 中实现适配器，只需覆盖 `build_url()`\n\n```python\nclass NewEngineAdapter(EngineAdapter):\n \"\"\"新引擎适配器：仅需构造 URL，解析与传输由框架承担\"\"\"\n\n def __init__(self):\n super().__init__(\"newengine\")\n\n def build_url(self, query: str, num: int) -> str:\n return f\"https://example.com/search?q={quote(query)}&n={num}\"\n```\n\n若引擎返回 JSON 而非 HTML，参考 `SearXNGAdapter` 覆盖 `search()` 方法。\n\n完成后运行 `python -m scripts.search --selftest` 验证连通性与解析状态。\n\n---\n\n有更好建议：njskills@agent.qq.com\n\nFile v1.6.0:references/QUICK_START.md\n\n# 隐私搜索 - 5 分钟快速上手指南\n\n> 从零开始，5 分钟内完成安装并执行你的第一次隐私搜索。\n\n---\n\n## 🚀 一键安装（推荐）\n\n```bash\npython scripts/quick_setup.py\n```\n\n一键完成：创建 venv → 安装依赖 → 复制配置 → 验证安装。\n\n---\n\n## 📋 手动安装（如需控制每一步）\n\n### Step 1: 创建虚拟环境\n\n```bash\npython -m venv .venv\n# Windows\n.venv\\Scripts\\activate\n# Linux/macOS\nsource .venv/bin/activate\n```\n\n### Step 2: 安装依赖\n\n```bash\npip install -r requirements.txt\n```\n\n### Step 3: 复制配置\n\n```bash\ncp references/config.yaml.example config.yaml\n```\n\n### Step 4: 验证安装\n\n```bash\npython scripts/search.py \"test\"\n```\n\n---\n\n## 🔍 你的第一次搜索\n\n### 基础搜索（默认引擎）\n\n```bash\npython scripts/search.py \"Python asyncio 教程\"\n```\n\n输出示例：\n```\n🔍 搜索: Python asyncio 教程 | 模式: normal | 结果: 18 条\n\n[1] Python asyncio 异步编程入门教程\n https://docs.python.org/zh-cn/3/library/asyncio.html\n 本教程将带你了解 Python asyncio 模块的基础知识...\n — bing\n\n[2] 超详细的 Python asyncio 教程，从入门到精通\n https://www.cnblogs.com/...\n 本文详细介绍 Python asyncio 的使用方法...\n — baidu\n```\n\n### 隐私搜索（strict 模式）\n\n```bash\npython scripts/search.py \"Python asyncio 教程\" --privacy strict\n```\n\n输出示例：\n```\n搜索: Python asyncio 教程 | 模式: strict | 来源: 实时 | 结果: 12 条\n\n[1] Python Asynchronous Programming\n https://docs.python.org/3/library/asyncio.html\n Learn how to use asyncio for concurrent programming...\n — yandex\n\n[2] Async IO in Python: A Complete Walkthrough\n https://realpython.com/async-io-python/\n Async IO is a concurrent programming design...\n — startpage, qwant\n```\n\n> strict 模式仅使用 SearXNG/Yandex/Startpage/Qwant/Brave/DDG。\n> 即使显式指定 `--engines baidu` 也会被拒绝，避免隐私承诺被绕过。\n\n### 缓存加速\n\n相同查询在 1 小时内直接复用结果，输出标注「来源: 缓存」。\n\n```bash\npython scripts/search.py \"Python asyncio 教程\" # 来源: 实时\npython scripts/search.py \"Python asyncio 教程\" # 来源: 缓存，秒回\npython scripts/search.py \"Python asyncio 教程\" --no-cache # 强制刷新\n```\n\n### 引擎体检\n\n搜不到结果时，先判断是引擎坏了还是关键词没匹配：\n\n```bash\npython scripts/search.py --selftest\n```\n\n输出会标明每个引擎是「正常」「被拦截」还是「选择器失效」。\n\n### 显示错误诊断网络问题时\n\n```bash\npython scripts/search.py \"test\" --privacy strict --verbose\n```\n\n网络故障时的输出：\n```\n============================================================\n🔍 错误诊断报告：\n\n🌐 网络问题：\n ✗ duckduckgo: 网络连接失败: Connection timed out after 10s\n 1. 检查网络连接是否正常（ping www.baidu.com）\n 2. 确认网络环境不受限制\n\n🔧 引擎问题：\n ✗ yandex: 引擎解析或请求失败: HTML parser error\n 1. yandex 可能已更新页面结构\n 2. 暂不支持该引擎（可排除）\n```\n\n---\n\n## strict 模式可用引擎\n\n| 引擎 | 来源 | 国内速度 | 隐私保护 | 状态 |\n|------|------|---------|---------|------|\n| **SearXNG** | 本机 | ⭐⭐⭐⭐⭐ 极快 | 极高 | ✅ 最优先 |\n| **Yandex** | 俄罗斯 | ⭐⭐⭐⭐ 快 | 中等 | ✅ 默认启用 |\n| **Startpage** | 荷兰（Google 代理） | ⭐⭐⭐ 中等 | 高 | ✅ 默认启用 |\n| **Qwant** | 法国 | ⭐⭐⭐ 中等 | 高 | ✅ 默认启用 |\n| **Brave** | 美国 | ⭐⭐ 较慢 | 高 | ✅ 默认启用 |\n| **DuckDuckGo** | 美国 | ⭐ 不稳定 | 极高 | ⚠️ 最后备选 |\n\n优先顺序：SearXNG → Yandex → Startpage → Qwant → Brave → DuckDuckGo\n\n若以上全部不可用，默认**停止搜索**而非降级到国内引擎——因为 strict 用户的预期是宁可无结果也不泄露查询词。确需降级请加 `--allow-fallback`。\n\n---\n\n## 📝 推荐配置（首次只需改 3 项）\n\n```yaml\n# config.yaml - 新手推荐修改项\nsearch:\n default_engines: [\"baidu\", \"bing\", \"duckduckgo\", \"searxng\"] # ✅ 第1项\n timeout: 15 # ✅ 第2项（网速慢可增大）\n\nprivacy:\n default_mode: strict # ✅ 第3项（默认 privacy）\n```\n\n其他配置项暂不需要修改。\n\n### 想隐藏 IP\n\nstrict 模式不隐藏 IP，需自行配置代理：\n\n```yaml\nprivacy:\n strict:\n proxy: \"http://127.0.0.1:7890\" # 支持 http:// 与 socks5://\n```\n\n---\n\n## 🔧 启动 SearXNG（推荐）\n\nSearXNG 本地实例是 strict 模式的隐私基石，建议启动。\n\n### Docker 方式（推荐）\n\n```bash\npython scripts/searxng_manager start --method docker\n```\n\n### pip 方式（无 Docker）\n\n```bash\npython scripts/searxng_manager start --method pip\n```\n\n### 验证\n\n```bash\npython scripts/searxng_manager status\n# 应显示 running: true\n```\n\n---\n\n## ❓ 常见问题\n\n### Q1: 安装依赖失败？\n\n```bash\n# 换用国内镜像\npip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple\n```\n\n### Q2: SearXNG 启动失败？\n\nDocker 方式失败时，改用 pip：\n```bash\npython scripts/searxng_manager start --method pip\n```\n\n### Q3: 国内使用 strict 模式搜不到结果？\n\n按顺序自动尝试 Yandex → Startpage → Qwant → Brave → DDG。全部失败时默认停止并提示，不会静默降级。\n\n只用国内直连较好的几个：\n```bash\npython scripts/search.py \"关键词\" --privacy strict --engines yandex,startpage,qwant,searxng\n```\n\n确需降级到国内引擎：\n```bash\npython scripts/search.py \"关键词\" --privacy strict --allow-fallback\n```\n\n### Q4: 如何排除某个引擎？\n\n```bash\n# 排除 yandex，用其他 strict 引擎\npython scripts/search.py \"关键词\" --privacy strict --engines startpage,qwant,searxng\n```\n\n### Q5: 如何查看隐私保护详情？\n\n```bash\n# 独立的隐私报告\npython scripts/privacy report\n\n# 搜索时附带本次实际生效的隐私设置\npython scripts/search.py \"关键词\" --privacy strict --privacy-report\n```\n\n### Q6: 搜索记录会留在本地吗？\n\n会。缓存与历史存于 `~/.workbuddy/output/privacy-search-cache.db`。\n\n```bash\npython scripts/search.py --cache-stats # 查看占用\npython scripts/search.py --history # 查看历史\npython scripts/search.py --clear-cache # 清空缓存\npython scripts/search.py --clear-history # 清空历史\n```\n\n共享设备上建议在 config.yaml 设 `cache.enabled: false`。\n\n---\n\n## 📚 下一步\n\n- 完整文档 → [SKILL.md](../SKILL.md)\n- 搜索引擎适配器详情 → [engines_zh.md](engines_zh.md)\n- 配置说明 → [config.yaml.example](config.yaml.example)\n\n有建议？联系邮箱：njskills@agent.qq.com\n\nFile v1.6.0:skill-card.md\n\n## Description:\n\nPrivacy Search helps agents run privacy-oriented, multi-engine web searches with strict and normal privacy modes, local SearXNG support, ranking and deduplication, result exports, synthesized answers, and engine health alerts.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[fyniujin](https://clawhub.ai/user/fyniujin)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users, developers, and agent operators use this skill to perform configurable web search workflows, inspect privacy posture, export results, and generate source-linked summaries while managing local SearXNG and engine health.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Local search history and cache may retain sensitive queries on disk.\n\nMitigation: Decide whether local history is acceptable before installing; for sensitive searches, disable or clear cache/history and use strict mode.\n\nRisk: Network integrations can disclose query or result details to configured search engines, LLM providers, webhook endpoints, or update checks.\n\nMitigation: Prefer local SearXNG for sensitive searches, disable update checks when needed, and only configure API keys or webhooks when that disclosure is acceptable.\n\nRisk: The referenced configuration template is missing from the artifact.\n\nMitigation: Verify the expected settings or create config.yaml manually before running the skill.\n\nRisk: Synthesized answers and fetched page content may be incomplete or inaccurate.\n\nMitigation: Review the cited sources and use fallback snippets or direct search results when page fetching or answer synthesis is unreliable.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/fyniujin/skills/privacy-search)\n- [Quick Start](references/QUICK_START.md)\n- [Search Engine Adapter Documentation](references/engines.md)\n- [Domestic Engine and Fallback Guide](references/engines_zh.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, json, html, pdf, shell commands, configuration, guidance]\n\n**Output Format:** [CLI text, JSON output, Markdown/HTML/PDF exports, configuration guidance, and source-linked synthesized answers.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Outputs may include cached search results, local history, privacy reports, self-test status, and citation-style answer synthesis.]\n\n## Skill Version(s):\n\n1.6.0 (source: evidence release and SKILL.md frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.6.0:requirements.txt\n\naiohttp>=3.9.0,<4.0.0\nbeautifulsoup4>=4.12.0,<5.0.0\nlxml>=5.0.0,<6.0.0\njieba>=0.42.1,<1.0.0\npyyaml>=6.0,<7.0.0\n\nArchive v1.5.0: 31 files, 117182 bytes\n\nFiles: references/engines_zh.md (5685b), references/engines.md (6702b), references/QUICK_START.md (6889b), requirements.txt (111b), scripts/__init__.py (120b), scripts/cache.py (18188b), scripts/engine_selectors.py (11179b), scripts/engines_registry.py (8379b), scripts/exporters.py (7254b), scripts/http_client.py (9067b), scripts/logging_util.py (6073b), scripts/page_fetcher.py (4628b), scripts/privacy.py (13415b), scripts/quick_setup.py (6264b), scripts/ranking.py (25652b), scripts/search.py (55951b), scripts/searxng_manager.py (16141b), scripts/summarizer.py (5769b), scripts/update_checker.py (16494b), scripts/version_util.py (7701b), skill-card.md (2396b), SKILL.md (14605b), tests/__init__.py (1134b), tests/test_privacy.py (4413b), tests/test_search_v11.py (8269b), tests/test_search_v12.py (40380b), tests/test_search_v15.py (14921b), tests/test_search.py (7705b), tests/test_searxng.py (3469b), tests/test_update_checker.py (6124b), _meta.json (133b)\n\nFile v1.5.0:SKILL.md\n\n---\nname: privacy-search\ndescription: \"隐私优先的多引擎并行搜索 Skill，提供十大搜索引擎（百度/必应/搜狗/360/DuckDuckGo/Yandex/Startpage/Qwant/Brave/本地SearXNG）并行检索。V1.5 提供结果缓存与搜索历史、统一 HTTP 出口（隐私头/UA池/代理/自动重试真正生效）、标准 SimHash 去重、多因子加权排序（共识度/位次/相关度/权威度/域名质量）、多套备选选择器与解析诊断、bangs 语法透传、网页正文抓取、搜索结果导出（Markdown/HTML/PDF）、LLM 摘要（智谱 GLM-4-Flash + 抽取式降级）。SearXNG 本地实例双路径部署，隐私模式 normal/strict 一键切换，不污染系统 Python 环境。\"\nversion: 1.5.0\n---\n\n\n# 隐私搜索（Privacy Search）\n\n隐私优先的多引擎并行搜索 Skill。V1.5 在搜索质量与隐私真实生效基础上，新增**网页正文抓取**、**结果导出**（Markdown/HTML/PDF）与**LLM 摘要**（智谱 GLM-4-Flash + 抽取式降级）。\n\n## 环境要求\n\n- Python 3.10+\n- Docker（可选，推荐用于 SearXNG）\n- 网络连接（本地 SearXNG 启动后可离线搜索）\n- Windows / macOS / Linux\n\n## 🚀 快速开始\n\n```bash\n# 一键安装\npython scripts/quick_setup.py\n\n# 搜索\npython scripts/search.py \"关键词\"\npython scripts/search.py \"关键词\" --privacy strict\n\n# 隐私报告\npython scripts/privacy report\n\n# 检查更新\npython scripts/update_checker check\n```\n\n详细 5 分钟上手指南 → [QUICK_START.md](references/QUICK_START.md)\n\n## 核心命令\n\n### F1：多引擎并行搜索\n\n```bash\n# 基础搜索\npython -m scripts.search \"搜索关键词\"\n\n# 指定引擎\npython -m scripts.search \"关键词\" --engines baidu,bing,duckduckgo\n\n# strict 隐私模式\npython -m scripts.search \"关键词\" --privacy strict\n\n# strict 引擎全部失败时，显式授权降级到国内引擎\npython -m scripts.search \"关键词\" --privacy strict --allow-fallback\n\n# JSON 输出\npython -m scripts.search \"关键词\" --json\n\n# 错误诊断（网络/配置/引擎问题）\npython -m scripts.search \"关键词\" --privacy strict --verbose\n\n# 查看全部可用引擎\npython -m scripts.search --list-engines\n\n# 引擎连通性与解析健康度体检\npython -m scripts.search --selftest\n\n# 搜索后附带隐私保护摘要\npython -m scripts.search \"关键词\" --privacy strict --privacy-report\n```\n\n### 缓存与搜索历史\n\n相同查询在有效期内直接复用结果，输出会标注「来源: 缓存」。\n\n```bash\n# 跳过缓存，强制重新搜索\npython -m scripts.search \"关键词\" --no-cache\n\n# 查看缓存占用\npython -m scripts.search --cache-stats\n\n# 清空缓存\npython -m scripts.search --clear-cache\n\n# 查看最近搜索历史（默认 20 条）\npython -m scripts.search --history\npython -m scripts.search --history 50\n\n# 清空搜索历史\npython -m scripts.search --clear-history\n```\n\n### bangs 快捷语法\n\n查询词中带 `!` 前缀时自动路由到本地 SearXNG，由其转发到目标站点。\n\n```bash\npython -m scripts.search \"!w 量子计算\" # 维基百科\npython -m scripts.search \"!gh asyncio\" # GitHub\npython -m scripts.search \"!yt python 教程\" # YouTube\n```\n\n> 该语法依赖本地 SearXNG。未启用时会提示并按普通关键词搜索。\n\n### F2：SearXNG 本地实例管理\n\n```bash\n# Docker 启动（推荐）\npython -m scripts.searxng_manager start --method docker\n\n# pip 启动\npython -m scripts.searxng_manager start --method pip\n\n# 状态检查\npython -m scripts.searxng_manager status\n\n# 停止\npython -m scripts.searxng_manager stop\n```\n\n### F3：隐私模式切换\n\n```bash\n# 状态查看\npython -m scripts.privacy status\n\n# 切换到 strict\npython -m scripts.privacy mode --set strict\n\n# 切换到 normal\npython -m scripts.privacy mode --set normal\n\n# 生成隐私保护报告\npython -m scripts.privacy report\n```\n\n### 版本更新检查（死规则 11）\n\n```bash\npython -m scripts.update_checker check\npython -m scripts.update_checker status\n```\n\n## 能做哪些\n\n| 能力 | 说明 |\n|------|------|\n| 多引擎并发搜索 | 10 引擎并行，标准 SimHash 去重 |\n| 多因子加权排序 | 共识度 + 位次 + 相关度 + 权威度 + 域名质量，权重可配 |\n| 结果缓存 | 相同查询秒回，容量上限自动淘汰 |\n| 搜索历史 | 本地留存最近 500 条，可查可清 |\n| 统一隐私出口 | 隐私头 / UA 池 / 代理 / 重试对全部引擎一致生效 |\n| 隐私优先兜底 | strict 下拒绝非白名单引擎，失败不静默降级 |\n| 本地 SearXNG | Docker/pip 双路径，query 不出本机 |\n| bangs 语法 | `!w` `!gh` `!yt` 等快捷跳转，经 SearXNG 转发 |\n| 解析健壮性 | 每引擎多套备选选择器，改版后自动尝试 |\n| 解析诊断 | 区分「确实无结果」「被拦截」「选择器失效」 |\n| 引擎体检 | `--selftest` 一次性检查各引擎连通与解析状态 |\n| 网络自动重试 | 指数退避 + 随机抖动，仅对网络类错误重试 |\n| 运行日志 | 级别可配，默认不记录查询词原文 |\n| 错误分类诊断 | 网络/配置/引擎三类问题，针对性排查 |\n| 版本更新提醒 | 启动异步检查，24h 不重复 |\n| 请求频率控制 | 单引擎日上限 200 + 随机延迟 |\n| venv 隔离 | pip 依赖全虚拟环境，不污染系统 |\n\n## 不能做哪些（V1.2 限制）\n\n- ❌ **不隐藏 IP 地址**：未配置 `privacy.strict.proxy` 时搜索引擎仍可见您的 IP\n- ❌ **不提供 LLM 摘要**（V1.3+ 规划）\n- ❌ **不提供网页正文抓取**（V1.3+ 规划）\n- ❌ **不提供浏览器插件 / MCP Server**（V2.0+ 规划）\n- ❌ **不保证引擎长期可解析**：搜索引擎改版后需等待选择器更新\n\n## 风险声明\n\n### 隐私边界\n\n| 风险 | 说明 | 缓解 |\n|------|------|------|\n| IP 可见性 | 不配置代理时引擎可见真实 IP | 设置 `privacy.strict.proxy` 或配合 VPN |\n| 搜索词明文传输 | 查询词需发送至引擎 | strict 走隐私引擎，或用本地 SearXNG |\n| 本地缓存留痕 | 缓存与历史含查询词，明文存于本地 | `--clear-cache` / `--clear-history`，或 `cache.enabled: false` |\n| 日志留痕 | 默认 INFO 只记录查询词长度 | 需完全静默可设 `logging.level: OFF` |\n| SearXNG 端口暴露 | 默认 127.0.0.1 | 禁止改为 0.0.0.0 |\n\n### 合规使用\n\n| 风险 | 说明 | 缓解 |\n|------|------|------|\n| 搜索引擎条款 | 自动化访问可能受限 | 尊重 robots.txt，勿调高频率上限 |\n| 数据合规 | 缓存与历史存于本地磁盘 | 共享设备建议关闭缓存 |\n\n## 常见错误\n\n> 遇到错误时，使用 `--verbose` 查看详细诊断\n\n### 网络故障 🌐\n\n```\n💡 网络连接失败，请检查网络或使用 --verbose 查看详情\n```\n\n排查：\n1. 检查网络：`ping www.baidu.com`\n2. 确认网络环境不受限\n3. 增大超时：`config.yaml` 中 `search.timeout: 20`\n\n### 配置错误 ⚙️\n\n```\n💡 配置错误，请检查 config.yaml 或使用 --verbose 查看详情\n```\n\n排查：\n1. 确认 YAML 格式正确（冒号后有空格）\n2. 复制 `references/config.yaml.example` 重新配置\n\n### 引擎错误 🔧\n\n```\n💡 搜索引擎解析失败，请稍后重试或更换引擎\n```\n\n排查：\n1. 运行 `python -m scripts.search --selftest` 定位具体原因\n2. 按诊断结论处理（见下表）\n3. 临时规避：用 `--engines` 排除该引擎\n\n### 解析诊断对照\n\n`--selftest` 与 `--verbose` 会输出诊断结论：\n\n| 诊断 | 含义 | 处理 |\n|------|------|------|\n| 正常 | 解析成功 | 无需处理 |\n| 确认无结果 | 该关键词确实无匹配 | 换关键词或换引擎 |\n| 被拦截 | 触发验证码或风控 | 降低频率，稍后重试 |\n| 选择器失效 | 引擎改版导致解析不到 | 更新到最新版本 |\n| 未知 | 页面结构异常 | 用 `--verbose` 查看详情 |\n\n## 常见问题\n\n**Q: strict 模式在国内能用吗？**\nA: 可以。strict 默认使用 Yandex（国内快）+ Startpage + Qwant + Brave，DDG 作最后备选。\n\n**Q: strict 模式下指定 `--engines baidu` 为什么没生效？**\nA: 这是有意设计。strict 模式会拒绝隐私保护不足的引擎，避免\"以为开了 strict 实际仍在向百度发送查询词\"。需要用百度请改用 `--privacy normal`。\n\n**Q: strict 模式搜不到结果，直接返回空？**\nA: 隐私引擎全部不可用时默认停止搜索，而非静默降级到国内引擎——因为 strict 用户的预期是宁可无结果也不泄露查询词。确需降级请加 `--allow-fallback`，或在配置中开启 `privacy.strict.allow_fallback`。\n\n**Q: 结果是旧的怎么办？**\nA: 默认缓存 1 小时。加 `--no-cache` 强制刷新，或调小 `cache.ttl_seconds`。\n\n**Q: 缓存文件会无限增长吗？**\nA: 不会。超过 `cache.max_size_mb`（默认 50MB）时自动淘汰最久未使用的条目，历史记录上限 500 条。\n\n**Q: 缓存和历史存在哪？如何彻底清除？**\nA: 默认在 `~/.workbuddy/output/privacy-search-cache.db`。`--clear-cache` 清结果，`--clear-history` 清历史，两者独立。\n\n**Q: 怎么确认隐私设置真的生效了？**\nA: 加 `--privacy-report` 查看本次搜索实际使用的请求头、代理与被屏蔽引擎。\n\n**Q: 如何隐藏 IP？**\nA: 在 config.yaml 设置 `privacy.strict.proxy`，支持 `http://` 与 `socks5://`。留空为直连。\n\n**Q: 某个引擎突然搜不到结果？**\nA: 先跑 `--selftest`。若显示「选择器失效」说明该引擎改版了，请更新到最新版本；显示「被拦截」则是触发了风控，稍后再试或换引擎。\n\n**Q: 为什么指定了 searxng 却没用上？**\nA: 检查 `searxng.enabled` 是否为 true，以及本地实例是否已启动（`python -m scripts.searxng_manager status`）。\n\n**Q: 排序结果不满意能调吗？**\nA: 可以。config.yaml 的 `ranking` 段可调五个权重，例如更看重多引擎共识就调高 `consensus`。\n\n**Q: 中文分词报缺少 jieba？**\nA: jieba 为可选依赖，缺失时自动降级为字符级切分，搜索仍可用。安装后相关度排序更准。\n\n**Q: 会记录我搜了什么吗？**\nA: 日志默认 INFO 级别，只记录查询词长度不记录原文；搜索历史存于本地且可随时清空。需完全静默可设 `logging.level: OFF`。\n\n**Q: SearXNG 启动失败？**\nA: 尝试切换：`--method pip`。确保 Docker 或 Python 3.10+ 可用。\n\n**Q: 如何关闭更新检查？**\nA: `python -m scripts.update_checker disable`\n\n**Q: 安装依赖失败？**\nA: `pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple`\n\n**Q: 支持哪些引擎？**\nA: 10 个：百度、必应、搜狗、360、DuckDuckGo、Yandex、Startpage、Qwant、Brave、本地 SearXNG。运行 `--list-engines` 查看完整属性。\n\n**Q: 如何在其他程序里调用？**\nA: 当前仅支持命令行，可用 `--json` 获取结构化输出。MCP Server 在 V2.0 规划中。\n\n**Q: 配置项太多，哪些必须改？**\nA: 首次只需改 3 项（config.yaml 中标注 [推荐修改]）：`default_engines`、`timeout`、`default_mode`。其他保持默认。\n\n## 项目结构\n\n```\nprivacy-search/\n├── SKILL.md # 本文件\n├── requirements.txt # Python 依赖\n├── scripts/\n│ ├── __init__.py\n│ ├── search.py # F1: 搜索编排与 CLI\n│ ├── searxng_manager.py # F2: SearXNG 管理\n│ ├── privacy.py # F3: 隐私模式与请求上下文\n│ ├── engines_registry.py # 引擎清单单一真相源\n│ ├── engine_selectors.py # 各引擎选择器与解析诊断\n│ ├── http_client.py # 统一 HTTP 出口（UA池/代理/重试）\n│ ├── ranking.py # SimHash 去重与多因子排序\n│ ├── cache.py # 结果缓存与搜索历史\n│ ├── logging_util.py # 运行日志\n│ ├── version_util.py # 版本解析单一真相源\n│ ├── update_checker.py # 更新检查（死规则 11）\n│ └── quick_setup.py # 一键安装\n├── references/\n│ ├── config.yaml.example # 配置模板（含推荐配置标注）\n│ ├── engines.md # 引擎适配器文档\n│ ├── engines_zh.md # 国内引擎与降级策略\n│ └── QUICK_START.md # 快速上手\n└── tests/\n ├── test_search.py # 搜索基础测试\n ├── test_search_v11.py # 引擎与降级测试\n ├── test_search_v12.py # 缓存/排序/日志测试\n ├── test_searxng.py # SearXNG 管理测试\n ├── test_privacy.py # 隐私模式测试\n └── test_update_checker.py # 更新检查测试\n```\n\n## 更新日志\n\n| v1.5.0 | 2026-08-07 | 增加：网页正文抓取模块（trafilatura/boilerpy3/正则三层降级）；增加：搜索结果导出（Markdown/HTML/PDF，PDF 有降级方案）；增加：LLM 摘要（智谱 GLM-4-Flash + 抽取式降级）；增加：引擎统计与动态降级（按历史成功率选引擎）；增加：UA 池可配置化（config.yaml 追加）；增加：TF-IDF 相关度算法（jieba 分词 + 余弦相似度）；增加：降级引擎列表可配置；优化：域名质量表扩展（+30 常用中文站点）；优化：SearXNG Secret 持久化（重启不失效）；优化：request_delay 默认值与示例文件一致（1.0-5.0）；优化：update_check 接入 search.py 启动检查；修复：github_url 占位符替换为 njskills；修复：引擎改版 mock 回归测试 |\n| v1.1.0 | 2026-07-19 | 增加4个国内可用备选引擎（Yandex/Startpage/Qwant/Brave）；strict模式自动降级与故障转移；增强错误分类（网络/配置/引擎三类）；增加10+FAQ与常见错误反模式对照；增加normal/strict模式搜索输出示例；增加5分钟快速上手指南QUICK_START.md；增加一键安装脚本quick_setup.py |\n| v1.0.0 | 2026-07-18 | 初始版本发布：多引擎并行搜索（F1）；SearXNG本地实例双路径部署（F2）；隐私模式normal/strict切换（F3）；版本更新检查提醒（死规则11）；SimHash去重与交叉验证排序 |\n\n## 支持与反馈\n\n- **联系邮箱**：njskills@agent.qq.com\n- **问题反馈**：欢迎通过邮件或 SkillHub 评论提出建议\n- **版本更新**：运行 `python -m scripts.update_checker check` 检查新版本\n\nFile v1.5.0:_meta.json\n\n{\n \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n \"slug\": \"privacy-search\",\n \"version\": \"1.5.0\",\n \"publishedAt\": 1786085615818\n}\n\nFile v1.5.0:references/engines_zh.md\n\n# 国内可用搜索引擎指南\n\n本文档说明 strict 模式下各引擎的国内可用性、隐私保护级别和自动降级策略。\n\n## 引擎对比\n\n| 引擎 | 国家 | 国内速度 | 隐私保护 | 数据收集 | 追踪 | strict 默认 | 备注 |\n|------|------|---------|---------|---------|------|-----------|------|\n| **SearXNG（本地）** | 本机 | ⭐⭐⭐⭐⭐ 极快 | 极高 | ❌ 无 | ❌ 无 | ✅ 最优先 | query 不出本机，最佳隐私 |\n| **Yandex** | 俄罗斯 | ⭐⭐⭐⭐ 快 | 中等 | 部分 | 少量 | ✅ | 俄文界面可用，中文搜索能力较好 |\n| **Startpage** | 荷兰 | ⭐⭐⭐ 中等 | 高 | ❌ 无 | ❌ 无 | ✅ | Google 代理，结果质量高 |\n| **Qwant** | 法国 | ⭐⭐⭐ 中等 | 高 | ❌ 无 | ❌ 无 | ✅ | 欧洲隐私法保护 |\n| **Brave** | 美国 | ⭐⭐ 较慢 | 高 | ❌ 无 | ❌ 无 | ✅ | 独立搜索引擎，不依赖 Google |\n| **DuckDuckGo** | 美国 | ⭐ 不稳定 | 极高 | ❌ 无 | ❌ 无 | ⚠️ 最后 | 国内连接不稳定，仅作兜底 |\n\n## 自动降级策略\n\n```\nstrict 模式搜索流程：\n┌──────────────────────────────────────────────────────┐\n│ SearXNG（本地，最优先） │\n│ query 不出本机，极速响应 │\n└────────────────────┬─────────────────────────────────┘\n │ (不可用时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ Yandex + Startpage + Qwant + Brave │\n│ 并发请求，SimHash 去重 │\n└────────────────────┬─────────────────────────────────┘\n │ (全部失败时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ DuckDuckGo（不稳定时使用） │\n└────────────────────┬─────────────────────────────────┘\n │ (仍失败时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ 默认：停止搜索并提示，不泄露查询词 │\n│ 显式加 --allow-fallback 才降级到 bing/baidu │\n└──────────────────────────────────────────────────────┘\n```\n\n### 为什么默认不降级\n\nstrict 模式的用户预期是「宁可没有结果，也不把查询词发给隐私保护不足的引擎」。\n静默降级到百度/必应会让用户在毫不知情的情况下失去隐私保护，属于违背预期的危险默认值。\n因此 V1.2 起改为默认拒绝，需通过 `--allow-fallback` 或配置项 `privacy.strict.allow_fallback` 显式授权。\n\n同理，strict 模式下即使用 `--engines baidu` 显式指定，也会被拒绝并提示改用 normal 模式。\n\n## 推荐使用方式\n\n### 最佳隐私（推荐）\n```bash\npython scripts/search.py \"关键词\" --privacy strict --engines searxng,yandex,startpage\n```\n- query 完全在本地\n- Yandex + Startpage 作为离线后备\n\n### 最佳速度\n```bash\npython scripts/search.py \"关键词\" --engines baidu,bing\n```\n- 国内引擎最快\n- normal 模式下的推荐选择\n\n### 平衡模式\n```bash\npython scripts/search.py \"关键词\" --privacy strict --engines yandex,searxng\n```\n- 速度隐私均衡\n- Yandex 国内速度快 + SearXNG 极致隐私\n\n## 常见问题：特定引擎故障\n\n### Yandex 故障\n- 可能原因：反爬升级、IP 限制\n- 解决：等待自动降级到 Startpage/Qwant\n\n### 全部 strict 引擎失败\n- 可能原因：网络受限、DNS 污染\n- 解决：\n ```bash\n 1. 检查网络：ping yandex.com\n 2. 配置代理（config.yaml 中 search.proxy）\n 3. 降级使用 normal 模式\n ```\n\n### DDG 在国内不可用\n- 常见现象，自动使用其他隐私引擎替代\n- 配置 `privacy.strict.proxy` 后可恢复\n\n### 判断是引擎坏了还是关键词没匹配\n\n```bash\npython scripts/search.py --selftest\n```\n\n输出会区分「正常」「确认无结果」「被拦截」「选择器失效」四种状态。\n显示「选择器失效」说明该引擎改版了，需更新插件版本；「被拦截」则是触发风控，降低频率后重试。\n\n## 限制与规避\n\n| 问题 | 影响 | 规避方式 |\n|------|------|---------|\n| 搜索引擎改版 | HTML 解析失败 | 多套备选选择器自动尝试，仍失败则等待版本更新 |\n| 触发风控 | 返回验证码页 | 降低 `daily_request_limit`，增大请求间隔 |\n| CDN 劫持 | 结果被篡改 | 全程 HTTPS + 多引擎交叉验证 |\n| DNS 污染 | 域名解析到错误 IP | 配置 `privacy.strict.proxy` |\n| IP 过滤 | 特定 IP 被封锁 | 配置代理，或改用本地 SearXNG |\n| 跳转链接 | 国内引擎返回中转地址 | 排序时自动识别并降权 |\n\n---\n\n有更好建议：njskills@agent.qq.com\n\nFile v1.5.0:references/engines.md\n\n# 搜索引擎适配器文档\n\n本文档说明各搜索引擎的实现细节、解析规则与扩展方式，对应 V1.2 架构。\n\n## 引擎列表\n\n引擎清单的唯一来源是 `scripts/engines_registry.py`，运行 `python -m scripts.search --list-engines` 可查看实时属性。\n\n| 引擎名称 | 标识 | 类型 | 区域 | 隐私等级 | strict 可用 | 说明 |\n|---------|------|------|------|---------|------------|------|\n| 本地 SearXNG | `searxng` | JSON API | 本机 | 高 | ✅ | 元搜索，query 不出本机，支持 bangs |\n| Yandex | `yandex` | HTML 解析 | 俄罗斯 | 中 | ✅ | 国内直连速度较好 |\n| Startpage | `startpage` | HTML 解析 | 荷兰 | 高 | ✅ | Google 结果代理 |\n| Qwant | `qwant` | HTML 解析 | 法国 | 高 | ✅ | 受欧盟隐私法约束 |\n| Brave Search | `brave` | HTML 解析 | 美国 | 高 | ✅ | 独立索引 |\n| DuckDuckGo | `duckduckgo` | HTML 解析 | 美国 | 高 | ✅ | 国内直连不稳定，作兜底 |\n| 百度 | `baidu` | HTML 解析 | 中国 | 低 | ❌ | 反爬较强，返回跳转链接 |\n| 必应 | `bing` | HTML 解析 | 中国 | 低 | ❌ | 国内可直接访问 |\n| 搜狗 | `sogou` | HTML 解析 | 中国 | 低 | ❌ | 返回跳转链接 |\n| 360 搜索 | `360` | HTML 解析 | 中国 | 低 | ❌ | 返回跳转链接 |\n\n## 架构分层\n\nV1.2 将传输与解析彻底分离，适配器不再各自处理 HTTP 细节。\n\n```\nCLI / SearchOrchestrator\n │\n ├── engines_registry.py 引擎清单与元数据（单一真相源）\n │\n ├── privacy.py 隐私配置 → RequestContext\n │ │\n ├── http_client.py 统一出口：UA 池 / 隐私头 / 代理 / 重试\n │ │\n ├── EngineAdapter 仅负责 build_url() 与结果映射\n │ │\n ├── engine_selectors.py 多套备选选择器 + 解析诊断\n │\n ├── ranking.py SimHash 去重 + 多因子加权排序\n │\n ├── cache.py 结果缓存与搜索历史\n │\n └── logging_util.py 运行日志\n```\n\n这样设计的原因：V1.1 时九个适配器各自硬编码请求头，导致隐私配置无法统一生效——只有三个适配器偶然带了 `DNT: 1`。收归统一出口后，隐私设置对所有引擎一致有效。\n\n## 请求策略\n\n### 超时与重试\n- 超时由 `search.timeout` 控制，默认 15 秒\n- 仅对网络类错误重试（连接失败、超时、连接重置），解析失败不重试\n- 指数退避 + 随机抖动，避免多引擎同时重试形成请求尖峰\n- 重试次数由 `search.retry_max` 控制，默认 2 次\n\n### 频率控制\n- 每日上限：单引擎 200 次（`search.daily_request_limit`）\n- 请求间隔：1–5 秒随机延迟\n-\n\nArchive v1.2.0: 27 files, 103496 bytes\n\nFiles: references/engines_zh.md (5685b), references/engines.md (6702b), references/QUICK_START.md (6889b), requirements.txt (111b), scripts/__init__.py (120b), scripts/cache.py (15726b), scripts/engine_selectors.py (11179b), scripts/engines_registry.py (8379b), scripts/http_client.py (8361b), scripts/logging_util.py (6073b), scripts/privacy.py (13303b), scripts/quick_setup.py (6264b), scripts/ranking.py (22388b), scripts/search.py (51508b), scripts/searxng_manager.py (15304b), scripts/update_checker.py (16494b), scripts/version_util.py (7701b), skill-card.md (2565b), SKILL.md (16587b), tests/__init__.py (1134b), tests/test_privacy.py (4413b), tests/test_search_v11.py (8269b), tests/test_search_v12.py (40380b), tests/test_search.py (7705b), tests/test_searxng.py (3469b), tests/test_update_checker.py (6124b), _meta.json (133b)\n\nArchive v1.1.0: 19 files, 40897 bytes\n\nFiles: references/engines_zh.md (4526b), references/engines.md (3008b), references/QUICK_START.md (5487b), requirements.txt (111b), scripts/__init__.py (35b), scripts/privacy.py (8923b), scripts/quick_setup.py (5179b), scripts/search.py (37736b), scripts/searxng_manager.py (14062b), scripts/update_checker.py (15541b), skill-card.md (2525b), SKILL.md (8011b), tests/__init__.py (0b), tests/test_privacy.py (4338b), tests/test_search_v11.py (8031b), tests/test_search.py (7496b), tests/test_searxng.py (3394b), tests/test_update_checker.py (6049b), _meta.json (133b)\n\nArchive v1.0.0: 15 files, 29610 bytes\n\nFiles: references/engines.md (3008b), requirements.txt (111b), scripts/__init__.py (35b), scripts/privacy.py (8740b), scripts/search.py (20999b), scripts/searxng_manager.py (14062b), scripts/update_checker.py (15541b), skill-card.md (2337b), SKILL.md (7646b), tests/__init__.py (0b), tests/test_privacy.py (4338b), tests/test_search.py (7496b), tests/test_searxng.py (3394b), tests/test_update_checker.py (6049b), _meta.json (133b)","readmeExcerpt":"Skill: privacy-search Owner: fyniujin Summary: 隐私优先的多引擎并行搜索 Skill，十大搜索引擎并行检索。V1.9 新增可信度标记和口语化错误建议，SKILL.md 瘦身至 ≤12KB。V1.8 新增可信合成与垂直搜索。V1.7 新增 MCP Server 形态。V1.6 新增 Perplexity 式答案合成。V1.5 新增网页正文抓取、结果导出、LLM 摘要。V1.2 统一 HTTP 出口、SimHash 去重、多因子排序、结果缓存、SearXNG 本地部署、隐私模式切换。 Tags: latest:1.9.0 Version history: v1.9.0 | 2026-10-10T11:13:29.396Z | auto Privacy Search v1.9.0 - 新增结果可信度标记：每条结果显示「引擎数/10 引擎返回」提升权威性评估。 - 错误诊断全面升级为口语化建","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"python scripts/quick_setup.py # 一键安装\npython scripts/search.py \"关键词\" # 一条命令搜索\npython scripts/search.py \"关键词\" --privacy strict # 隐私搜索\npython scripts/update_checker check # 检查更新"},{"language":"bash","snippet":"python -m scripts.search \"关键词\"\npython -m scripts.search \"关键词\" --engines baidu,bing\npython -m scripts.search \"关键词\" --privacy strict\npython -m scripts.search \"关键词\" --privacy strict --allow-fallback\npython -m scripts.search \"关键词\" --json\npython -m scripts.search \"关键词\" --verbose\npython -m scripts.search --list-engines\npython -m scripts.search --selftest\npython -m scripts.search \"关键词\" --privacy-report"},{"language":"bash","snippet":"python -m scripts.search \"关键词\" --synthesize-pro\npython -m scripts.search \"关键词\" --synthesize-pro --privacy strict"},{"language":"bash","snippet":"python -m scripts.search --selftest-schedule run\npython -m scripts.search --selftest-schedule status"},{"language":"bash","snippet":"python -m scripts.search \"量子计算\" --synthesize-pro --fact-check\npython -m scripts.search \"AI 大模型\" --vertical news\npython -m scripts.search \"突发新闻\" --vertical realtime\npython -m scripts.search \"quantum computing\" --vertical academic\npython -m scripts.search \"猫咪\" --vertical image\npython -m scripts.search \"python教程 site:github.com filetype:pdf\""},{"language":"bash","snippet":"python -m scripts.mcp_server\npython -m scripts.mcp_server --schema\npython -m scripts.mcp_server --test"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: privacy-search\ndescription: \"隐私优先的多引擎并行搜索 Skill，十大搜索引擎并行检索。V1.9 新增可信度标记和口语化错误建议，SKILL.md 瘦身至 ≤12KB。V1.8 新增可信合成与垂直搜索。V1.7 新增 MCP Server 形态。V1.6 新增 Perplexity 式答案合成。V1.5 新增网页正文抓取、结果导出、LLM 摘要。V1.2 统一 HTTP 出口、SimHash 去重、多因子排序、结果缓存、SearXNG 本地部署、隐私模式切换。\"\nversion: 1.9.0\n---\n\n\n# 隐私搜索（Privacy Search）\n\n隐私优先的多引擎并行搜索 Skill。V1.9 新增 **结果可信度标记**（每条结果标注「引擎数/10 引擎返回」）和 **口语化错误建议**。V1.8 新增可信合成与垂直搜索。V1.7 新增 MCP Server 形态。\n\n## 环境要求\n\n- Python 3.10+\n- Docker（可选，推荐用于 SearXNG）\n- 网络连接（本地 SearXNG 启动后可离线搜索）\n- Windows / macOS / Linux\n\n## 🚀 快速开始\n\n```bash\npython scripts/quick_setup.py # 一键安装\npython scripts/search.py \"关键词\" # 一条命令搜索\npython scripts/search.py \"关键词\" --privacy strict # 隐私搜索\npython scripts/update_checker check # 检查更新\n```\n\n详细上手指南 → [QUICK_START.md](references/QUICK_START.md)\n\n## 核心命令速查\n\n### F1：多引擎并行搜索\n\n```bash\npython -m scripts.search \"关键词\"\npython -m scripts.search \"关键词\" --engines baidu,bing\npython -m scripts.search \"关键词\" --privacy strict\npython -m scripts.search \"关键词\" --privacy strict --allow-fallback\npython -m scripts.search \"关键词\" --json\npython -m scripts.search \"关键词\" --verbose\npython -m scripts.search --list-engines\npython -m scripts.search --selftest\npython -m scripts.search \"关键词\" --privacy-report\n```\n\n### F4：Perplexity 式答案合成（V1.6）\n\n```bash\npython -m scripts.search \"关键词\" --synthesize-pro\npython -m scripts.search \"关键词\" --synthesize-pro --privacy strict\n```\n\n### F5：定时引擎告警（V1.6）\n\n```bash\npython -m scripts.search --selftest-schedule run\npython -m scripts.search --selftest-schedule status\n```\n\n### F7：可信合成与垂直搜索（V1.8）\n\n```bash\npython -m scripts.search \"量子计算\" --synthesize-pro --fact-check\npython -m scripts.search \"AI 大模型\" --vertical news\npython -m scripts.search \"突发新闻\" --vertical realtime\npython -m scripts.search \"quantum computing\" --vertical academic\npython -m scripts.search \"猫咪\" --vertical image\npython -m scripts.search \"python教程 site:github.com filetype:pdf\"\n```\n\n### F6：MCP Server（V1.7）\n\n```bash\npython -m scripts.mcp_server\npython -m scripts.mcp_server --schema\npython -m scripts.mcp_server --test\n```\n\n### 缓存与历史\n\n```bash\npython -m scripts.search \"关键词\" --no-cache\npython -m scripts.search --cache-stats\npython -m scripts.search --clear-cache\npython -m scripts.search --history\npython -m scripts.search --clear-history\n```\n\n### bangs 快捷语法\n\n```bash\npython -m scripts.search \"!w 量子计算\"\npython -m scripts.search \"!gh asyncio\"\npython -m scripts.search \"!yt python 教程\"\n```\n\n### F2：SearXNG 管理 / F3：隐私模式\n\n```bash\npython -m scripts.searxng_manager start --method docker\npython -m scripts.searxng_manager status\npython -m scripts.privacy mode --set strict\npython -m scripts.privacy report\n```\n\n### 版本更新检查（死规则 11）\n\n```bash\npython -m scripts.update_checker check\npython -m scripts.update_checker status\n```\n\n## 能做哪些\n\n| 能力 | 说明 |\n|------|------|\n| 多引擎并发搜索 | 10 引擎并行，SimHash 去重 |\n| 多因子加权排序 | 共识度 + 位次 + 相关度 + 权威度 + 域名质量 |\n| 结果缓存 | 相同查询秒回，容量上限自动淘汰 |\n| 搜索历史 | 本地留存最近 500 条 |\n| 统一隐私出口 | 隐私头 / UA 池 / 代理 / 重试一致生效 |\n| 隐私优先兜底 | strict 下拒绝非白名单引擎 |\n| 本地 SearXNG | Docke"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n \"slug\": \"privacy-search\",\n \"version\": \"1.9.0\",\n \"publishedAt\": 1791630809396\n}"},{"path":"references/detail_engine_syntax_faq.md","content":"# 引擎细节、语法表与完整 FAQ\n\n本文档收录 SKILL.md 瘦身后移出的详细内容。\n\n---\n\n## 一、引擎详情\n\n引擎清单唯一来源：`scripts/engines_registry.py`，运行 `--list-engines` 查看实时属性。\n\n| 引擎 | 标识 | 类型 | 区域 | 隐私等级 | strict 可用 | 说明 |\n|------|------|------|------|---------|------------|------|\n| 本地 SearXNG | `searxng` | JSON API | 本机 | 高 | ✅ | 元搜索，query 不出本机，支持 bangs |\n| Yandex | `yandex` | HTML 解析 | 俄罗斯 | 中 | ✅ | 国内直连速度较好 |\n| Startpage | `startpage` | HTML 解析 | 荷兰 | 高 | ✅ | Google 结果代理 |\n| Qwant | `qwant` | HTML 解析 | 法国 | 高 | ✅ | 受欧盟隐私法约束 |\n| Brave Search | `brave` | HTML 解析 | 美国 | 高 | ✅ | 独立索引 |\n| DuckDuckGo | `duckduckgo` | HTML 解析 | 美国 | 高 | ✅ | 国内直连不稳定，作兜底 |\n| 百度 | `baidu` | HTML 解析 | 中国 | 低 | ❌ | 反爬较强，返回跳转链接 |\n| 必应 | `bing` | HTML 解析 | 中国 | 低 | ❌ | 国内可直接访问 |\n| 搜狗 | `sogou` | HTML 解析 | 中国 | 低 | ❌ | 返回跳转链接 |\n| 360 搜索 | `360` | HTML 解析 | 中国 | 低 | ❌ | 返回跳转链接 |\n\n### 架构分层\n\n```\nCLI / SearchOrchestrator\n │\n ├── engines_registry.py 引擎清单与元数据（单一真相源）\n │\n ├── engine_*.py 各引擎适配器（仅负责构建 URL + 解析 HTML）\n │\n ├── http_client.py 统一 HTTP 出口（UA池/代理/重试/隐私头）\n │\n ├── ranking.py SimHash 去重 + 多因子排序\n │\n └── cache.py 结果缓存 + 搜索历史\n```\n\n### 选择器与诊断\n\n每引擎配多套备选选择器，引擎改版时自动尝试下一套。诊断结论：\n\n| 诊断 | 含义 | 处理 |\n|------|------|------|\n| 正常 | 解析成功 | 无需处理 |\n| 确认无结果 | 该关键词确实无匹配 | 换关键词或换引擎 |\n| 被拦截 | 触发验证码或风控 | 降低频率，稍后重试 |\n| 选择器失效 | 引擎改版导致解析不到 | 更新到最新版本 |\n| 未知 | 页面结构异常 | 用 `--verbose` 查看详情 |\n\n---\n\n## 二、统一查询语法表\n\n### bangs 语法（走 SearXNG 快捷跳转）\n\n| 语法 | 目标 |\n|------|------|\n| `!w 关键词` | 维基百科 |\n| `!gh 关键词` | GitHub |\n| `!yt 关键词` | YouTube |\n| `!gm 关键词` | Google Maps |\n| `!scholar 关键词` | Google Scholar |\n\n### 高级检索语法（V1.8 新增）\n\n| 语法 | 说明 | 支持引擎 |\n|------|------|---------|\n| `site:example.com` | 站点限定 | baidu, bing, duckduckgo, yandex, searxng |\n| `filetype:pdf` | 文件类型 | bing, searxng |\n| `after:2025` | 时间下限 | searxng, baidu |\n| `before:2026` | 时间上限 | searxng, baidu |\n\n不支持语法的引擎自动本地过滤并注明。\n\n### 垂直搜索模式（V1.8 新增）\n\n| 模式 | 标识 | 优先引擎 | 排序权重 |\n|------|------|---------|---------|\n| 新闻 | `news` | 百度资讯、必应新闻 | 时效性↑ |\n| 实时 | `realtime` | 百度、必应、SearXNG | 新鲜度↑ |\n| 学术 | `academic` | Semanticscholar、百度学术 | 引用数↑ |\n| 图片 | `image` | 百度图片、必应图片 | 相关度↑ |\n\n---\n\n## 三、完整 FAQ\n\n### strict 模式\n\n**Q: strict 模式在国内能用吗？**\nA: 可以。strict 默认使用 Yandex（国内快）+ Startpage + Qwant + Brave，DDG 作最后备选。\n\n**Q: strict 模式下指定 `--engines baidu` 为什么没生效？**\nA: 这是有意设计。strict 模式会拒绝隐私保护不足的引擎，避免\"以为开了 strict 实际仍在向百度发送查询词\"。需要用百度请改用 `--privacy normal`。\n\n**Q: strict 模式搜不到结果，直接返回空？**\nA: 隐私引擎全部不可用时默认停止搜索，而非静默降级到国内引擎——因为 strict 用户的预期是宁可无结果也不泄露查询词。确需降级请加 `--allow-fallback`。\n\n### 缓存与历史\n\n**Q: 结果是旧的怎么办？**\nA: 默认缓存 1 小时。加 `--no-cache` 强制刷新，或调小 `cache.ttl_seconds`。\n\n**Q: 缓存文件会无限增长吗？**\nA: 不会。超过 `cache.max_size_mb`（默认 50MB）时自动淘汰最久未使用的条目，历史记录上限 500 条。\n\n**Q: 缓存和历史存在哪？如何彻底清除？**\nA: 默认在 `~/.workbuddy/output/privacy-search-cache.db`。`--clear-cache` 清结果，`--clear-history` 清历史，两者独立。\n\n### 隐私\n\n**Q: 怎么确认隐私设置真的生效了？**\nA: 加 `--privacy-report` 查看本次搜索实际使用的请求头、代理与被屏蔽引擎。\n\n**Q: 如何隐藏 IP？**\nA: 在 config.yaml 设置 `privacy.strict.proxy`，支持 `http://` 与 `sock"},{"path":"references/engines_zh.md","content":"# 国内可用搜索引擎指南\n\n本文档说明 strict 模式下各引擎的国内可用性、隐私保护级别和自动降级策略。\n\n## 引擎对比\n\n| 引擎 | 国家 | 国内速度 | 隐私保护 | 数据收集 | 追踪 | strict 默认 | 备注 |\n|------|------|---------|---------|---------|------|-----------|------|\n| **SearXNG（本地）** | 本机 | ⭐⭐⭐⭐⭐ 极快 | 极高 | ❌ 无 | ❌ 无 | ✅ 最优先 | query 不出本机，最佳隐私 |\n| **Yandex** | 俄罗斯 | ⭐⭐⭐⭐ 快 | 中等 | 部分 | 少量 | ✅ | 俄文界面可用，中文搜索能力较好 |\n| **Startpage** | 荷兰 | ⭐⭐⭐ 中等 | 高 | ❌ 无 | ❌ 无 | ✅ | Google 代理，结果质量高 |\n| **Qwant** | 法国 | ⭐⭐⭐ 中等 | 高 | ❌ 无 | ❌ 无 | ✅ | 欧洲隐私法保护 |\n| **Brave** | 美国 | ⭐⭐ 较慢 | 高 | ❌ 无 | ❌ 无 | ✅ | 独立搜索引擎，不依赖 Google |\n| **DuckDuckGo** | 美国 | ⭐ 不稳定 | 极高 | ❌ 无 | ❌ 无 | ⚠️ 最后 | 国内连接不稳定，仅作兜底 |\n\n## 自动降级策略\n\n```\nstrict 模式搜索流程：\n┌──────────────────────────────────────────────────────┐\n│ SearXNG（本地，最优先） │\n│ query 不出本机，极速响应 │\n└────────────────────┬─────────────────────────────────┘\n │ (不可用时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ Yandex + Startpage + Qwant + Brave │\n│ 并发请求，SimHash 去重 │\n└────────────────────┬─────────────────────────────────┘\n │ (全部失败时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ DuckDuckGo（不稳定时使用） │\n└────────────────────┬─────────────────────────────────┘\n │ (仍失败时)\n ▼\n┌──────────────────────────────────────────────────────┐\n│ 默认：停止搜索并提示，不泄露查询词 │\n│ 显式加 --allow-fallback 才降级到 bing/baidu │\n└──────────────────────────────────────────────────────┘\n```\n\n### 为什么默认不降级\n\nstrict 模式的用户预期是「宁可没有结果，也不把查询词发给隐私保护不足的引擎」。\n静默降级到百度/必应会让用户在毫不知情的情况下失去隐私保护，属于违背预期的危险默认值。\n因此 V1.2 起改为默认拒绝，需通过 `--allow-fallback` 或配置项 `privacy.strict.allow_fallback` 显式授权。\n\n同理，strict 模式下即使用 `--engines baidu` 显式指定，也会被拒绝并提示改用 normal 模式。\n\n## 推荐使用方式\n\n### 最佳隐私（推荐）\n```bash\npython scripts/search.py \"关键词\" --privacy strict --engines searxng,yandex,startpage\n```\n- query 完全在本地\n- Yandex + Startpage 作为离线后备\n\n### 最佳速度\n```bash\npython scripts/search.py \"关键词\" --engines baidu,bing\n```\n- 国内引擎最快\n- normal 模式下的推荐选择\n\n### 平衡模式\n```bash\npython scripts/search.py \"关键词\" --privacy strict --engines yandex,searxng\n```\n- 速度隐私均衡\n- Yandex 国内速度快 + SearXNG 极致隐私\n\n## 常见问题：特定引擎故障\n\n### Yandex 故障\n- 可能原因：反爬升级、IP 限制\n- 解决：等待自动降级到 Startpage/Qwant\n\n### 全部 strict 引擎失败\n- 可能原因：网络受限、DNS 污染\n- 解决：\n ```bash\n 1. 检查网络：ping yandex.com\n 2. 配置代理（config.yaml 中 search.proxy）\n 3. 降级使用 normal 模式\n ```\n\n### DDG 在国内不可用\n- 常见现象，自动使用其他隐私引擎替代\n- 配置 `privacy.strict.proxy` 后可恢复\n\n### 判断是引擎坏了还是关键词没匹配\n\n```bash\npython scripts/search.py --selftest\n```\n\n输出会区分「正常」「确认无结果」「被拦截」「选择器失效」四种状态。\n显示「选择器失效」说明该引擎改版了，需更新插件版本；「被拦截」则是触发风控，降低频率后重试。\n\n## 限制与规避\n\n| 问题 | 影响 | 规避方式 |\n|------|------|---------|\n| 搜索引擎改版 | HTML 解析失败 | 多套备选选择器自动尝试，仍失败则等待版本更新 |\n| 触发风控 | 返回验证码页 | 降低 `daily_request_limit`，增大请求间隔 |\n| CDN 劫持 | 结果被篡改 | 全程 HTTPS + 多引擎交叉验证 |\n| DNS 污染 | 域名解析到错误 IP | 配置 `privacy.strict.proxy` |\n| IP 过滤 | 特定 IP 被封锁 | 配置代理，或改用本地 SearXNG |\n| 跳转链接"},{"path":"references/engines.md","content":"# 搜索引擎适配器文档\n\n本文档说明各搜索引擎的实现细节、解析规则与扩展方式，对应 V1.2 架构。\n\n## 引擎列表\n\n引擎清单的唯一来源是 `scripts/engines_registry.py`，运行 `python -m scripts.search --list-engines` 可查看实时属性。\n\n| 引擎名称 | 标识 | 类型 | 区域 | 隐私等级 | strict 可用 | 说明 |\n|---------|------|------|------|---------|------------|------|\n| 本地 SearXNG | `searxng` | JSON API | 本机 | 高 | ✅ | 元搜索，query 不出本机，支持 bangs |\n| Yandex | `yandex` | HTML 解析 | 俄罗斯 | 中 | ✅ | 国内直连速度较好 |\n| Startpage | `startpage` | HTML 解析 | 荷兰 | 高 | ✅ | Google 结果代理 |\n| Qwant | `qwant` | HTML 解析 | 法国 | 高 | ✅ | 受欧盟隐私法约束 |\n| Brave Search | `brave` | HTML 解析 | 美国 | 高 | ✅ | 独立索引 |\n| DuckDuckGo | `duckduckgo` | HTML 解析 | 美国 | 高 | ✅ | 国内直连不稳定，作兜底 |\n| 百度 | `baidu` | HTML 解析 | 中国 | 低 | ❌ | 反爬较强，返回跳转链接 |\n| 必应 | `bing` | HTML 解析 | 中国 | 低 | ❌ | 国内可直接访问 |\n| 搜狗 | `sogou` | HTML 解析 | 中国 | 低 | ❌ | 返回跳转链接 |\n| 360 搜索 | `360` | HTML 解析 | 中国 | 低 | ❌ | 返回跳转链接 |\n\n## 架构分层\n\nV1.2 将传输与解析彻底分离，适配器不再各自处理 HTTP 细节。\n\n```\nCLI / SearchOrchestrator\n │\n ├── engines_registry.py 引擎清单与元数据（单一真相源）\n │\n ├── privacy.py 隐私配置 → RequestContext\n │ │\n ├── http_client.py 统一出口：UA 池 / 隐私头 / 代理 / 重试\n │ │\n ├── EngineAdapter 仅负责 build_url() 与结果映射\n │ │\n ├── engine_selectors.py 多套备选选择器 + 解析诊断\n │\n ├── ranking.py SimHash 去重 + 多因子加权排序\n │\n ├── cache.py 结果缓存与搜索历史\n │\n └── logging_util.py 运行日志\n```\n\n这样设计的原因：V1.1 时九个适配器各自硬编码请求头，导致隐私配置无法统一生效——只有三个适配器偶然带了 `DNT: 1`。收归统一出口后，隐私设置对所有引擎一致有效。\n\n## 请求策略\n\n### 超时与重试\n- 超时由 `search.timeout` 控制，默认 15 秒\n- 仅对网络类错误重试（连接失败、超时、连接重置），解析失败不重试\n- 指数退避 + 随机抖动，避免多引擎同时重试形成请求尖峰\n- 重试次数由 `search.retry_max` 控制，默认 2 次\n\n### 频率控制\n- 每日上限：单引擎 200 次（`search.daily_request_limit`）\n- 请求间隔：1–5 秒随机延迟\n- 超限自动跳过该引擎，不影响其他引擎\n\n### 请求头\n所有引擎统一经由 `http_client` 出口，不再逐引擎硬编码。\n\n| 模式 | User-Agent | DNT | Cookie | Referer | 代理 |\n|------|-----------|-----|--------|---------|------|\n| normal | UA 池随机 | 按配置 | 保留 | 保留 | 按配置 |\n| strict | UA 池随机 | `1` | 移除 | 移除 + `Referrer-Policy: no-referrer` | 按配置 |\n\nUA 池内置 8 个主流浏览器标识，随机轮换以降低指纹一致性。在 `privacy.strict.user_agent` 填入固定值可覆盖此行为。\n\n## 解析规则\n\n每个引擎配置多套备选选择器（见 `engine_selectors.py`）。首套解析不到结果时自动尝试下一套，用于缓解搜索引擎改版。\n\n### 百度\n- 容器：`div.result, div.result-op` → `div[class*='result']` → `div#content_left > div`\n- 标题：`h3 a`\n- 摘要：`div.c-abstract` 等\n\n### 必应\n- 容器：`li.b_algo` → `.b_algo`\n- 标题：`h2 a`\n- 摘要：`p`\n\n### DuckDuckGo\n- 容器：`div.result` → `div.web-result`\n- 标题：`a.result__a`\n- 摘要：`a.result__snippet`\n\n### SearXNG\n- 端点：`GET /search?q=...&format=json`\n- 响应：`results[].title / url / content`\n- 支持 bangs 语法透传（`!w` `!gh` `!yt` 等）\n\n### 解析诊断\n\n解析为空时不直接判定\"无结果\"，而是区分四种情况：\n\n| 诊断 | 判定依据 | 含义 |\n|------|---------|------|\n| `EMPTY_CONFIRMED` | 页面含\"没有找到相关结果\"等标记 | 确实无匹配 |\n| `BLOCKED` | 页面含验证码、安全验证等标记 | 触发风控 |\n| `SELECTOR_STALE` | 页面正常但所有选择器均未命中 | 引擎已改版 |\n| `UNKNOWN` | 其余情况 | 需人工查看 |\n\n这个区分很重要：把\"引擎改版\"误报为\"无结果\"会让用户以为搜索词有问题，而非插件需要更新。\n\n### 跳转链接处理\n\n百度、搜狗、360 返回的是形如 `baidu.com/link?url=...` 的中转地址而非真实 URL。这类链接会导致跨引擎去重失效（同一结果在不同引擎下 URL 不同"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"隐私优先的多引擎并行搜索 Skill，十大搜索引擎并行检索。V1.9 新增可信度标记和口语化错误建议，SKILL.md 瘦身至 ≤12KB。V1.8 新增可信合成与垂直搜索。V1.7 新增 MCP Server 形态。V1.6 新增 Perplexity 式答案合成。V1.5 新增网页正文抓取、结果导出、LLM 摘要。V1.2 统一 HTTP 出口、SimHash 去重、多因子排序、结果缓存、SearXNG 本地部署、隐私模式切换。 Skill: privacy-search Owner: fyniujin Summary: 隐私优先的多引擎并行搜索 Skill，十大搜索引擎并行检索。V1.9 新增可信度标记和口语化错误建议，SKILL.md 瘦身至 ≤12KB。V1.8 新增可信合成与垂直搜索。V1.7 新增 MCP Server 形态。V1.6 新增 Perplexity 式答案合成。V1.5 新增网页正文抓取、结果导出、LLM 摘要。V1.2 统一 HTTP 出口、SimHash 去重、多因子排序、结果缓存、SearXNG 本地部署、隐私模式切换。 Tags: latest:1.9.0 Version history: v1.9.0 | 2026-10-10T11:13:29.396Z | auto Privacy Search v1.9.0 - 新增结果可信度标记：每条结果显示「引擎数/10 引擎返回」提升权威性评估。 - 错误诊断全面升级为口语化建","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1075,"uniquenessScore":49,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T12:18:54.948Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T12:18:54.948Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T15:26:28.502Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}