privacy-search

隐私搜索（Privacy Search）

隐私优先的多引擎并行搜索 Skill。V1.6 新增 Perplexity 式答案合成（引用+正文抓取+citation）和 定时引擎失效告警，jieba 默认安装提升中文相关度精度。V1.5 在搜索质量与隐私真实生效基础上，新增网页正文抓取、结果导出（Markdown/HTML/PDF）与 LLM 摘要（智谱 GLM-4-Flash + 抽取式降级）。

环境要求

• 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

缓存与搜索历史

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

# 跳过缓存，强制重新搜索
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 可能产生幻觉，建议核对来源
• ❌ 不提供浏览器插件 / MCP Server（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 在 V2.0 规划中。

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。其他保持默认。

项目结构

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 新增）
├── references/
│   ├── config.yaml.example           # 配置模板（含推荐配置标注）
│   ├── engines.md                    # 引擎适配器文档
│   ├── engines_zh.md                 # 国内引擎与降级策略
│   └── 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_searxng.py               # SearXNG 管理测试
    ├── test_privacy.py               # 隐私模式测试
    └── test_update_checker.py        # 更新检查测试

更新日志

| 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 检查新版本