隐私搜索（Privacy Search）

隐私优先的多引擎并行搜索 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 一键切换。

环境要求

• Python 3.10+
• Docker（可选，推荐用于 SearXNG）
• 网络连接（本地 SearXNG 启动后可离线搜索）
• Windows / macOS / Linux

🚀 快速开始

# 一键安装
python scripts/quick_setup.py

# 搜索
python scripts/search.py "关键词"
python scripts/search.py "关键词" --privacy strict

# 隐私报告
python scripts/privacy report

# 检查更新
python scripts/update_checker check

详细 5 分钟上手指南 → QUICK_START.md

核心命令

F1：多引擎并行搜索

# 基础搜索
python -m scripts.search "搜索关键词"

# 指定引擎
python -m scripts.search "关键词" --engines baidu,bing,duckduckgo

# strict 隐私模式
python -m scripts.search "关键词" --privacy strict

# strict 引擎全部失败时，显式授权降级到国内引擎
python -m scripts.search "关键词" --privacy strict --allow-fallback

# JSON 输出
python -m scripts.search "关键词" --json

# 错误诊断（网络/配置/引擎问题）
python -m scripts.search "关键词" --privacy strict --verbose

# 查看全部可用引擎
python -m scripts.search --list-engines

# 引擎连通性与解析健康度体检
python -m scripts.search --selftest

# 搜索后附带隐私保护摘要
python -m scripts.search "关键词" --privacy strict --privacy-report

F4：Perplexity 式答案合成（V1.6 新增）

# Pro 模式：抓取正文 + LLM 带 citation 生成答案
python -m scripts.search "关键词" --synthesize-pro

# 无 API Key 时自动降级为抽取式摘要+来源列表
python -m scripts.search "关键词" --synthesize-pro --privacy strict

F5：定时引擎告警（V1.6 新增）

# 手动执行一次 selftest 并发送告警
python -m scripts.search --selftest-schedule run

# 查看上次 selftest 结果
python -m scripts.search --selftest-schedule status

# 独立运行（支持阻塞式定时循环）
python -m scripts.selftest_scheduler run
python -m scripts.selftest_scheduler status

F7：可信合成与垂直搜索（V1.8 新增）

# 事实核查（逐论断回链原文，标注支撑度三级）
python -m scripts.search "量子计算最新进展" --synthesize-pro --fact-check

# 新闻搜索（时效性排序，优先百度资讯/必应新闻）
python -m scripts.search "AI 大模型" --vertical news

# 实时搜索（秒级/分钟级更新）
python -m scripts.search "突发新闻" --vertical realtime

# 学术搜索（Semanticscholar 学术数据库）
python -m scripts.search "quantum computing" --vertical academic

# 图片搜索
python -m scripts.search "猫咪" --vertical image

# 高级检索语法（时间/站点/文件类型限定）
python -m scripts.search "python教程 site:github.com filetype:pdf"
python -m scripts.search "AI新闻 after:2025 before:2026"

# 组合使用
python -m scripts.search "量子计算 site:mit.edu after:2024" --vertical academic

高级语法支持引擎：baidu(site), bing(site,filetype), duckduckgo(site), yandex(site), searxng(site,after,brave)。不支持语法的引擎自动本地过滤。 统一查询语法表 → python -m scripts.query_parser

F6：MCP Server（V1.7 新增）

# 启动 MCP Server（stdio 模式）
python -m scripts.mcp_server

# 查看工具 schema
python -m scripts.mcp_server --schema

# 协议自测
python -m scripts.mcp_server --test

MCP Server 暴露三个工具：search（多引擎并行搜索）、synthesize（Perplexity 式答案合成）、fetch（网页正文抓取）。

详细工具 schema 与桥接文档 → references/mcp_schema.md

缓存与搜索历史

相同查询在有效期内直接复用结果，输出会标注「来源: 缓存」。

# 跳过缓存，强制重新搜索
python -m scripts.search "关键词" --no-cache

# 查看缓存占用
python -m scripts.search --cache-stats

# 清空缓存
python -m scripts.search --clear-cache

# 查看最近搜索历史（默认 20 条）
python -m scripts.search --history
python -m scripts.search --history 50

# 清空搜索历史
python -m scripts.search --clear-history

bangs 快捷语法

查询词中带 ! 前缀时自动路由到本地 SearXNG，由其转发到目标站点。

python -m scripts.search "!w 量子计算"      # 维基百科
python -m scripts.search "!gh asyncio"      # GitHub
python -m scripts.search "!yt python 教程"  # YouTube

该语法依赖本地 SearXNG。未启用时会提示并按普通关键词搜索。

F2：SearXNG 本地实例管理

# Docker 启动（推荐）
python -m scripts.searxng_manager start --method docker

# pip 启动
python -m scripts.searxng_manager start --method pip

# 状态检查
python -m scripts.searxng_manager status

# 停止
python -m scripts.searxng_manager stop

F3：隐私模式切换

# 状态查看
python -m scripts.privacy status

# 切换到 strict
python -m scripts.privacy mode --set strict

# 切换到 normal
python -m scripts.privacy mode --set normal

# 生成隐私保护报告
python -m scripts.privacy report

版本更新检查（死规则 11）

python -m scripts.update_checker check
python -m scripts.update_checker status

能做哪些

不能做哪些（V1.6 限制）

• ❌ 不隐藏 IP 地址：未配置 privacy.strict.proxy 时搜索引擎仍可见您的 IP
• ❌ 不保证 100% 正文抓取：部分网站反爬严格，正文抓取可能失败
• ❌ 不保证 LLM 摘要 100% 准确：LLM 可能产生幻觉，建议核对来源
• ❌ 不提供浏览器插件（V2.0+ 规划）
• ❌ 不保证引擎长期可解析：搜索引擎改版后需等待选择器更新

风险声明

隐私边界

合规使用

常见错误

遇到错误时，使用 --verbose 查看详细诊断

网络故障 🌐

💡 网络连接失败，请检查网络或使用 --verbose 查看详情

排查：

1. 检查网络：ping www.baidu.com
2. 确认网络环境不受限
3. 增大超时：config.yaml 中 search.timeout: 20

配置错误 ⚙️

💡 配置错误，请检查 config.yaml 或使用 --verbose 查看详情

排查：

1. 确认 YAML 格式正确（冒号后有空格）
2. 复制 references/config.yaml.example 重新配置

引擎错误 🔧

💡 搜索引擎解析失败，请稍后重试或更换引擎

排查：

1. 运行 python -m scripts.search --selftest 定位具体原因
2. 按诊断结论处理（见下表）
3. 临时规避：用 --engines 排除该引擎

解析诊断对照

--selftest 与 --verbose 会输出诊断结论：

常见问题

Q: strict 模式在国内能用吗？ A: 可以。strict 默认使用 Yandex（国内快）+ Startpage + Qwant + Brave，DDG 作最后备选。

Q: strict 模式下指定 --engines baidu 为什么没生效？ A: 这是有意设计。strict 模式会拒绝隐私保护不足的引擎，避免"以为开了 strict 实际仍在向百度发送查询词"。需要用百度请改用 --privacy normal。

Q: strict 模式搜不到结果，直接返回空？ A: 隐私引擎全部不可用时默认停止搜索，而非静默降级到国内引擎——因为 strict 用户的预期是宁可无结果也不泄露查询词。确需降级请加 --allow-fallback，或在配置中开启 privacy.strict.allow_fallback。

Q: 结果是旧的怎么办？ A: 默认缓存 1 小时。加 --no-cache 强制刷新，或调小 cache.ttl_seconds。

Q: 缓存文件会无限增长吗？ A: 不会。超过 cache.max_size_mb（默认 50MB）时自动淘汰最久未使用的条目，历史记录上限 500 条。

Q: 缓存和历史存在哪？如何彻底清除？ A: 默认在 ~/.workbuddy/output/privacy-search-cache.db。--clear-cache 清结果，--clear-history 清历史，两者独立。

Q: 怎么确认隐私设置真的生效了？ A: 加 --privacy-report 查看本次搜索实际使用的请求头、代理与被屏蔽引擎。

Q: 如何隐藏 IP？ A: 在 config.yaml 设置 privacy.strict.proxy，支持 http:// 与 socks5://。留空为直连。

Q: 某个引擎突然搜不到结果？ A: 先跑 --selftest。若显示「选择器失效」说明该引擎改版了，请更新到最新版本；显示「被拦截」则是触发了风控，稍后再试或换引擎。

Q: 为什么指定了 searxng 却没用上？ A: 检查 searxng.enabled 是否为 true，以及本地实例是否已启动（python -m scripts.searxng_manager status）。

Q: 排序结果不满意能调吗？ A: 可以。config.yaml 的 ranking 段可调五个权重，例如更看重多引擎共识就调高 consensus。

Q: 中文分词报缺少 jieba？ A: jieba 为可选依赖，缺失时自动降级为字符级切分，搜索仍可用。安装后相关度排序更准。

Q: 会记录我搜了什么吗？ A: 日志默认 INFO 级别，只记录查询词长度不记录原文；搜索历史存于本地且可随时清空。需完全静默可设 logging.level: OFF。

Q: SearXNG 启动失败？ A: 尝试切换：--method pip。确保 Docker 或 Python 3.10+ 可用。

Q: 如何关闭更新检查？ A: python -m scripts.update_checker disable

Q: 安装依赖失败？ A: pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

Q: 支持哪些引擎？ A: 10 个：百度、必应、搜狗、360、DuckDuckGo、Yandex、Startpage、Qwant、Brave、本地 SearXNG。运行 --list-engines 查看完整属性。

Q: 如何在其他程序里调用？ A: 当前支持两种方式：① 命令行 --json 获取结构化输出；② MCP Server（V1.7 新增），通过 stdio JSON-RPC 2.0 暴露 search/synthesize/fetch 三工具，可被 Claude Code、Cursor、n8n 等直接挂载。详见 references/mcp_schema.md。

Q: Pro 模式和普通摘要的区别？ A: Pro 模式会抓取搜索结果正文并生成带 citation 的答案，每个论断都能追溯到来源。普通摘要（--summarize）只基于 snippet 生成简短总结。Pro 模式需要配置 synthesis.api_key，无 Key 时自动降级为抽取式摘要。

Q: Pro 模式抓取正文失败怎么办？ A: 系统会自动降级为该结果的 snippet，不会中断整体流程。可在 config.yaml 调整 synthesis.fetch_timeout 和 synthesis.chunk_size。

Q: 定时 selftest 怎么配置每天跑一次？ A: config.yaml 中设置 selftest_schedule.interval: daily，然后用系统 cron 或任务计划程序定时触发 python scripts/search.py --selftest-schedule run。当前不支持后台常驻进程。

Q: selftest 告警发到哪？ A: 默认写入 ~/.workbuddy/output/privacy-search-selftest.log，设置 selftest_schedule.alert_channel: both 可同时推送到企业微信 webhook。

Q: 如何配置 webhook 告警？ A: 在 config.yaml 的 selftest_schedule.webhook_url 填入企业微信/钉钉机器人的 webhook 地址。

Q: 配置项太多，哪些必须改？ A: 首次只需改 3 项（config.yaml 中标注 [推荐修改]）：default_engines、timeout、default_mode。其他保持默认。

Q: 事实核查是什么？怎么用？ A: 事实核查是 V1.8 新增的可信合成层。用 --synthesize-pro --fact-check 启用，逐条论断回链原文做 TF-IDF 余弦相似度比对，标注支撑度三级（充分/部分/无源），无源论断默认剔除。核查报告自动追加在答案末尾，含引用清单与核查方法说明。

Q: 无源论断怎么处理？ A: 默认自动剔除（fact_check.remove_unsupported: true）。如想保留但标注警告，设置 fact_check.remove_unsupported: false。阈值也可调：sufficient_threshold（默认 0.55）、partial_threshold（默认 0.25）。

Q: 垂直搜索怎么用？ A: --vertical news/realtime/academic/image 四类。新闻走百度资讯/必应新闻，学术走 Semanticscholar 开放接口（不可用时降级为通用引擎+学术关键词），图片走引擎图片端。每类有独立的引擎优先级和排序权重。

Q: 高级检索语法和 bangs 冲突吗？ A: 不冲突，统一为查询语法表。bangs（!w !gh !yt）走 SearXNG 原生快捷跳转，高级语法（after:/before:/site:/filetype:）映射为各引擎等价参数。不支持语法的引擎本地过滤并注明。

Q: MCP Server 是什么？怎么用？ A: 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。

Q: MCP Server 暴露了哪些工具？ A: 3 个工具：search（多引擎隐私搜索）、synthesize（Perplexity 式答案合成 + V1.8 事实核查）、fetch（URL 正文抓取）。可通过 config.yaml 的 mcp_server.tools 缩减子集。

Q: MCP Server 超时怎么办？ A: 默认单次调用 30 秒，超时返回 JSON-RPC 错误响应，不中断服务。可在 config.yaml 调整 mcp_server.timeout。LLM 不可用时自动降级为抽取式，不影响 search/fetch 工具。

项目结构

privacy-search/
├── SKILL.md                          # 本文件
├── requirements.txt                  # Python 依赖
├── scripts/
│   ├── __init__.py
│   ├── search.py                     # F1: 搜索编排与 CLI
│   ├── searxng_manager.py            # F2: SearXNG 管理
│   ├── privacy.py                    # F3: 隐私模式与请求上下文
│   ├── engines_registry.py           # 引擎清单单一真相源
│   ├── engine_selectors.py           # 各引擎选择器与解析诊断
│   ├── http_client.py                # 统一 HTTP 出口（UA池/代理/重试）
│   ├── ranking.py                    # SimHash 去重与多因子排序
│   ├── cache.py                      # 结果缓存与搜索历史
│   ├── logging_util.py               # 运行日志
│   ├── version_util.py               # 版本解析单一真相源
│   ├── update_checker.py             # 更新检查（死规则 11）
│   ├── quick_setup.py                # 一键安装
│   ├── synthesiser.py                # F4: Perplexity 式答案合成（V1.6 新增）
│   ├── selftest_scheduler.py         # F5: 定时 selftest 告警（V1.6 新增）
│   ├── mcp_server.py                 # F6: MCP Server stdio JSON-RPC 2.0（V1.7 新增）
│   ├── fact_checker.py               # F7: 事实核查层（V1.8 新增）
│   ├── vertical_search.py            # F7: 垂直搜索路由（V1.8 新增）
│   └── query_parser.py               # F7: 高级检索语法（V1.8 新增）
├── references/
│   ├── config.yaml.example           # 配置模板（含推荐配置标注）
│   ├── engines.md                    # 引擎适配器文档
│   ├── engines_zh.md                 # 国内引擎与降级策略
│   ├── mcp_schema.md                 # MCP 工具 Schema 文档（V1.7 新增）
│   └── QUICK_START.md                # 快速上手
└── tests/
    ├── test_search.py                # 搜索基础测试
    ├── test_search_v11.py            # 引擎与降级测试
    ├── test_search_v12.py            # 缓存/排序/日志测试
    ├── test_search_v15.py            # V1.5 新模块测试
    ├── test_search_v16.py            # V1.6 新模块测试
    ├── test_mcp_server.py            # MCP Server 协议与工具测试（V1.7 新增）
    ├── test_fact_checker.py          # 事实核查层测试（V1.8 新增）
    ├── test_vertical_search.py       # 垂直搜索测试（V1.8 新增）
    ├── test_query_parser.py          # 高级语法解析测试（V1.8 新增）
    ├── test_searxng.py               # SearXNG 管理测试
    ├── test_privacy.py               # 隐私模式测试
    └── test_update_checker.py        # 更新检查测试

更新日志

| v1.8.0 | 2026-09-19 | 增加：事实核查层（逐论断回链原文做相似度比对，标注支撑度三级：充分/部分/无源，无源论断默认剔除）；增加：垂直搜索模式（news/realtime/academic/image 四类，各配引擎优先级与参数）；增加：高级检索语法（after:/before:/site:/filetype: 解析为各引擎等价参数，不支持的引擎本地过滤并注明）；增加：内容处理管线（正文抓取→分块→摘要显式链，中间产物可查）；调整：synthesiser 集成事实核查层，--synthesize-pro 输出自动附带核查报告；调整：MCP Server synthesize 工具 schema 更新（V1.8 新增事实核查层说明） | | v1.7.0 | 2026-08-28 | 增加：MCP Server 形态（stdio JSON-RPC 2.0 暴露 search/synthesize/fetch 三工具）；增加：生态桥接文档（references/mcp_schema.md）；增加：MCP Server 配置段（config.yaml） | | v1.6.0 | 2026-08-17 | 增加：Perplexity 式答案合成（抓取正文→分块→LLM 带 citation 生成答案）；增加：定时 selftest 调度+引擎失效告警（每日/每小时，支持 webhook）；调整：jieba 从可选改为默认安装，中文相关度精度提升；优化：无 API Key 时 Pro 模式自动降级为抽取式摘要+来源列表 | | 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 回归测试 | | v1.1.0 | 2026-07-19 | 增加4个国内可用备选引擎（Yandex/Startpage/Qwant/Brave）；strict模式自动降级与故障转移；增强错误分类（网络/配置/引擎三类）；增加10+FAQ与常见错误反模式对照；增加normal/strict模式搜索输出示例；增加5分钟快速上手指南QUICK_START.md；增加一键安装脚本quick_setup.py | | v1.0.0 | 2026-07-18 | 初始版本发布：多引擎并行搜索（F1）；SearXNG本地实例双路径部署（F2）；隐私模式normal/strict切换（F3）；版本更新检查提醒（死规则11）；SimHash去重与交叉验证排序 |

支持与反馈

• 联系邮箱：njskills@agent.qq.com
• 问题反馈：欢迎通过邮件或 SkillHub 评论提出建议
• 版本更新：运行 python -m scripts.update_checker check 检查新版本