Web Search Techniques 是一套共享知识库，服务于 research:quick-searcher、research:deep-researcher 以及 /research:team-research 的负责人，适用范围限定为网络检索。其内容涵盖查询构造、来源权威性、工具使用、反爬回退与防循环规则。
一、用途 该知识库用于规范网络研究流程，使不同研究角色在检索、阅读、引用来源时遵循一致的方法，并明确检索后端的选择与成本、失败时的回退路径以及避免无效重复的规则。
二、查询构造 在发起查询前，先从问题中提取核心概念：识别同义词与领域术语（例如 authentication 对应 auth、login、signin、session、token、jwt、oauth、credentials）；兼顾缩写与全称；当查询具有时效依赖时加入年份（如 2026）；加入 official 或 documentation 以偏向权威来源；用引号包裹精确短语以做精确匹配；用 site: 限定到已知可信域名（如 site:developer.mozilla.org）。策略上先宽后窄、逐步收敛，因为过于具体的首次查询会遗漏相邻信息，每一轮细化都应纳入前序结果中出现的术语。
三、来源权威性排序 在引用前对每个来源排序：官方文档站点与 API 参考权威性最高；RFC 与规范文档是标准方面的权威；GitHub issue、讨论与源代码对特定库具有权威性；经同行评审或社区验证的内容（如高票 Stack Overflow、维护者博客）次之；一般博客文章与教程仅在无更好来源时使用。应降低优先级的有：SEO 内容农场、AI 生成的摘要、抓取聚合站。时效性检查包括：页面最后修改日期、所引版本号与最新发布版本的对比、弃用警告。
四、检索后端 两种后端用于产出候选页面，但都不产生论断：只有被实际阅读过的页面才能产生论断。
原生 WebSearch：默认后端，只要该工具在工具集中就始终可用，通过工具调用并配合上述操作符使用。
serper.dev（Google）：当存在密钥，或指定 --backend serper 时使用，调用方式为 python "${CLAUDE_PLUGIN_ROOT}/skills/web-search-techniques/scripts/websearch.py" "" [--vertical search。
选择规则：由负责人在每次运行中决定一次，并写入每个 spawn 提示中。auto 表示有密钥时用 serper，否则用原生。所选后端需在计划、每位研究者的报告以及最终报告头部中说明。
密钥来源顺序：环境变量 SERPER_API_KEY，然后是 ~/.serper_key。应询问脚本而非自行查看：python "${CLAUDE_PLUGIN_ROOT}/skills/web-search-techniques/scripts/websearch.py" --check-key 在有密钥时退出码为 0，无密钥时为 2，不发起网络调用也不消耗额度。用户在聊天中粘贴的密钥通过管道传给 --set-key 保存，这是负责人在预检阶段的职责，其他人不参与：研究者从不接触密钥，他们调用脚本，由脚本读取密钥。绝不回显密钥，绝不把密钥写入提示、报告或任何其他文件，也绝不自行读取密钥文件。
运行不会静默升级或降级：auto 且无密钥时后端为原生搜索，计划中会说明；强制 --backend serper 且无密钥时，要么在聊天中收集密钥，要么以设置提示停止，绝不悄悄改用其他方式搜索。
serper 值得调用的场景：--vertical scholar 用于学术线索，--vertical news --since w|m 用于时效性线索；--num 30 到 50 用于定向轮，一次调用即可摸清主题词汇（超过 10 条结果消耗 2 个额度，脚本会在 stderr 中说明）；--since 用于“最近有什么变化”类问题，查询内使用 before:YYYY-MM-DD / after:YYYY-MM-DD 可精确限定时间窗口；跨索引佐证：同时出现在两个索引上的来源，其排名高于仅出现在一个索引上的来源。
两种后端都支持的操作符：site:（限定域名）、"exact phrase"（精确短语）、-term（排除）、filetype:pdf、年份标记（2026）用于时效查询、official 或 documentation 以偏向一手来源、相关时加入版本号（react 19）。
成本说明（2026-08-23 核对）：serper.dev 提供 2,500 次免费查询，之后入门方案为每 1,000 次 1.00 美元，批量可低至每 1,000 次 0.30 美元；额度仅在成功响应时扣除。标准运行约 45-75 次调用，深度运行 150-300 次。Tavily 与 Exa 是面向 LLM 的替代方案（LLM 就绪片段、神经搜索），可接入同一脚本接口，但尚未构建。
五、阅读而非略读 搜索结果只是候选。论断只有来自被阅读过的页面才能进入研究者的台账：用 WebFetch 抓取页面（优先文档与一手来源；长页面定位到锚点）；遇到反爬（403、429、挑战页）或内容过薄（有用字符少于约 200）时，使用 python3 "${CLAUDE_PLUGIN_ROOT}/skills/web-search-techniques/scripts/webfetch.py" <url>；如果 playwright 插件的 Playwright MCP 工具可用，且页面是答案所依赖的一手来源，可作为最后手段用真实浏览器驱动（browser_navigate，然后 browser_snapshot）；若不可用，则把该 URL 记入限制项并继续。这是指引，不是依赖。记录内容：URL、标题、页面所载日期、权威等级以及从中取得的论断。
六、WebFetch 指引 优先文档页面与 API 参考而非博客文章；评估抓取内容，低权威来源应丢弃并重新检索；大页面可能被截断，尽量定位到具体章节（锚点 URL）；记录访问的 URL 与日期以便引用。
七、webfetch.py 回退 当 WebFetch 返回反爬（403、429、Cloudflare 挑战）或内容过薄（有用文本少于约 200 字符）时，回退到插件的隐蔽抓取器：python3 "${CLAUDE_PLUGIN_ROOT}/skills/web-search-techniques/scripts/webfetch.py" <url>。行为：通过 curl_cffi 模拟 Chrome TLS 指纹；在 stdout 返回干净的提取文本；成功退出码 0，超时或错误退出码 1；失败时继续而不使用该结果（不要循环重试）。调用选项：--timeout SECONDS（默认 30）、--max-chars CHARS（截断输出）、--raw（返回原始 HTML 而非提取文本）。需要在 agent 的 tools: frontmatter 中具备 Bash 工具。
八、防循环规则 绝不重复完全相同的查询或搜索参数；若搜索无结果，更换术语、放宽正则或切换工具/目标；每个子主题最多失败 2 次后即转向或上报；同一角度失败 2 次后，记录该缺口并带着已有内容继续。