effective-web-research

effective-web-research

让每次外部网页查询都高效且可信，并将“深入研究”请求转化为可审计、经过来源评估的报告。本技能以两个成熟框架为基础——CRAAP（数十年来的信息素养科学）和 Google E-E-A-T（网络上占主导地位的内容质量标准），因此这些规则有据可依，而非主观臆断。

本技能针对外部网络，不与内部代码搜索工具竞争。

何时使用 / 何时不使用

在以下情况使用：Agent 即将（或被要求）从外部网络收集信息，例如官方文档网站、第三方库文档、RFC、知名博客、论文、现实世界数据。

以下情况不要使用：

• 读取工作区／仓库中的文件（read、grep、ast-grep）
• 浏览本地代码库（LSP、goto_definition、explore Agent）
• 阅读 node_modules / venv / site-packages 中已安装的依赖项
• 创建或编辑文档

这些属于内部搜索任务，需要使用不同工具，并遵循不同的质量标准。

---

步骤 0 — 分流：真的需要查外部资料吗？

在进行任何网络搜索之前，先判断外部研究是否确有必要。许多 Agent 会不假思索地用 Google 搜索的问题，其实通过内部代码库就能更快、更可靠地解答。如果答案就在本地却仍查外部资料，不仅浪费精力，还会带来不确定性。

任务信号	路径	本技能的作用
答案可能就在仓库中：我们的代码逻辑、AGENTS.md 约定、现有技能、代码注释、已安装的依赖项源码	优先内部搜索 — 使用 grep / read / LSP / explore。不要启动网络搜索。	不要启用（提示一句“考虑先检查内部资料”即可）
涉及第三方库／框架／外部 API／工具行为／特定版本的特性	外部搜索 — 网络研究	默认模式（4 条准则）适用
现实世界信息：新闻、市场数据、人物、时事、论文	外部搜索	默认模式适用
混合问题——外部概念 + 内部应用（“我们使用的 X 库是否容易受到 Y 攻击”“将 X 模式应用于我们的代码”）	先外部、再内部 — 先在外部研究相关概念，再在内部核实／应用	外部阶段采用默认／严格模式；内部阶段使用内部工具
静态方式无法访问内容（需要登录／由 JS 渲染／小红书·公众号等反爬平台）	通过 web-access 技能升级到 CDP（运行时检查；如果没有 web-access，则中止并提示安装）——真实浏览器会保留登录状态	web-access 负责获取内容；本技能的可信度规范仍适用于所有获取到的内容

分流信号：

• 内部：问题提到“我们的／这个项目／这段代码／我们的约定”，或答案显然存在于仓库中。
• 外部：问题提到带版本号的第三方库／框架／API／工具，或询问外部对象的“如何使用／如何运作／最佳实践／是否存在漏洞”。
• 混合：涉及外部概念，并同时出现“我们的／应用到／检查我们的”以及内部对象。

如果不确定，优先从内部开始——对于“我们自己的”问题，这样更快，也更权威。只有在内部搜索无果时，才转向外部资料。

升级处理 — 静态层无法访问内容时（通过 web-access 使用 CDP）

当 WebSearch / WebFetch / curl / Jina 返回的内容缺少目标信息，原因是页面拒绝非浏览器客户端访问（例如登录墙、JS 渲染的页面外壳，或小红书·公众号等平台的反爬拦截），请加载 web-access 技能并遵循其 CDP 指引——它会连接到用户日常使用的浏览器（原生保留登录状态），并通过其 curl HTTP API 获取内容。

这是运行时本地依赖，不是 frontmatter 中的 dependencies 条目：核心研究规范无需 web-access 也能正常工作，上游工作流（known-issue-research → solve-workflow 系列）也不依赖任何外部插件。仅在实际升级处理时检查 web-access；如果未安装，则中止并告知用户如何安装（不得静默回退）。

内容获取与可信度评估相互独立——4 条准则 / 严格模式仍会评估 CDP 获取的所有内容。有关升级处理决策树和 curl API 速查表，请参阅 reference.md · CDP upgrade。

---

默认模式 — 4 条准则（适用于活动任务中的每次网络搜索）

当此技能在某项任务中处于启用状态时，对该任务期间执行的每次网络搜索 / webfetch 都应用以下准则。（技能会在描述与任务匹配时按任务启用——因此，这些准则适用于该任务内的每次搜索，而不适用于无关任务中的搜索。）不会生成额外产物。之所以制定这些准则，是因为网络上充斥着过时、权威性低、相互抄袭以及 AI 生成的内容——若缺乏规范，Agent 只会放大这些噪声。

1. 权威来源优先

来源优先级：官方文档 / 网站 ＞ 权威次级来源（MDN、官方博客、RFC / 规范）＞ 信誉良好的社区来源（StackOverflow 上高赞的回答、官方仓库中的议题 / PR）＞ 一般网络内容。

应用方式：网络搜索结果返回后，先查看域名——这是官方网站（react.dev、developer.mozilla.org、nodejs.org、<lib>.<org>）吗？先阅读这些来源，再看普通博客。 原因：某篇 2019 年的博客对 React Hooks 的解读，远不如 react.dev 自己的文档可靠，但搜索引擎可能会把该博客排在更靠前的位置。

2. 检查时效性

对于快速变化的主题（框架、API、工具、安全），在采信内容前先查找页面的发布日期 / 更新日期。超过约 2 年的内容属于“可能已过时”——请对照官方的当前版本文档核实其说法。

应用方式：执行 webfetch 后，查找“Last updated” / 文章日期 / <time> 标签。完全没有日期的页面值得怀疑——在证实并非过时之前，先将其视为过时。例外：官方的常青参考文档网站（react.dev/reference/*、developer.mozilla.org、框架官方文档）没有逐页标注日期，但由厂商维护并持续更新；可将其视为当前版本的权威来源。如果需要锁定特定次要版本，请查看页面上的版本选择器或项目变更日志。 原因：一篇 2021 年的 Node.js 文章描述的是 v16 的行为；到了 v22，API 可能已经改变。

3. 交叉验证重要说法

任何不显而易见的说法——行为断言、性能数据、安全声明、兼容性说法、“最佳实践”意见——在转述为事实前都需要 ≥2 个独立来源。

更严格的判断标准：如果某个说法会影响决策（选择安装哪个库、如何设计架构、某种方法是否安全），它就属于重要说法，必须交叉验证。简单事实（语法、参数名称、类型签名）只需一个权威来源。

应用方式：如果单一来源提出了重要说法，请再次搜索以佐证。措辞几乎相同的两个网站不算独立来源（很可能是其中一个抄袭了另一个）；应寻找独立的论证或一手证据。 原因：一篇错误的博客文章被聚合网站反复转载，就会变成“大家都这么说”的迷思。

4. 跳过内容农场

识别并降低以下内容的优先级：聚合／抓取网站、AI 生成的 SEO 内容农场、纯复制内容、广告泛滥的低质量页面，以及没有作者、没有日期的填充内容。

应用：当排名靠前的结果中，有 10 个来自未知域名、内容浅薄且几乎相同的页面时，直接查找官方来源或信誉良好的英文权威来源。 重要性：内容农场优化的是搜索排名，而非准确性，并且越来越多地污染搜索结果。

推论 — 引用规范

转述外部发现时，附上来源链接 +（日期），让用户能一键核实：

“React 19 的 use hook 可以在条件语句中调用（react.dev，2024-12）。”

这是四条准则自然导出的结果，并非第五条规则。

---

严格模式 — 7 维度来源评估 + 报告

当用户明确要求严谨性时触发：「严格调研」「深度调研」「严格查证」「严谨调研」/“严格研究”“深入研究”“事实核查”——并且目标是外部内容（第 0 步确认）。当结论至关重要时使用（技术选型、安全决策、将据此采取行动的主张）。

如果用户要求严格研究，但目标是内部代码（例如「严格分析我们 auth 模块的实现」），则不适用此技能——内部深度分析属于另一种任务；应转交给 explore / debug-workflow / 代码审查工具。

严格模式包含默认模式（搜索阶段仍遵循 4 条准则），并增加结构化评估。

7 个维度（CRAAP + E-E-A-T 合并）

两个框架存在重叠；合并后得到 7 个不同的维度。E-E-A-T 的可信度是综合结论，而不是独立维度。

#	维度	问题
1	权威性	谁发布了这份内容？其地位如何？
2	专业知识	作者具备哪些资历？
3	经验	是否展示了第一手的实践证据？
4	时效性	何时发布／更新？是否符合当前版本？
5	准确性	能否核实？是否引用来源？是否有交叉验证？
6	目的／偏见	为何创建？是否存在商业／意识形态倾向？
7	相关性	是否直接回答了问题？

每个维度按高 / 中 / 低评分，并依据具体标准评定——完整评分标准见 参考文档，以便让此文件保持简明，专注于决策。综合结论为可信 / 谨慎 / 不可靠。

工作流

1. 拆解研究问题，划分为可验证的子主张。
2. 按照默认模式的 4 条准则进行搜索。资料充足时停止搜索——对于安全／保障关键结论，这意味着至少有 2 个相互独立的一手来源达成一致；对于一般主张，则需要足够的来源覆盖各项子主张，且没有明显遗漏。
3. 对每个来源按 7 个维度评分，并评定综合可信度。
4. 在主张层面进行综合分析——哪些主张有多个来源支持且可信度高，哪些只有单一来源支持，哪些存在冲突。对于安全／保障关键主张，在将其标记为“强／可信”之前，必须有多个来源在权威性 + 准确性维度上均获得高分（标准高于一般主张）。
5. 使用下方模板生成报告。
6. 标出缺口——仍需核查的内容，以及来源之间存在分歧之处。

报告模板

# Strict research report: <topic>

## Research question
<the specific question, including version/context>

## Source evaluation

### Source 1: <title> (<URL>, <date>)
- Authority: H/M/L — <basis>
- Expertise: ...
- Experience: ...
- Currency: ...
- Accuracy: ...
- Purpose/Bias: ...
- Relevance: ...
- **Verdict**: Trustworthy / Cautious / Unreliable

### Source 2: ...

## Claims & confidence
- <claim 1>: ✅ Strong (multi-source High) — Sources 1, 2
- <claim 2>: ⚠️ Moderate (single source or Med) — Source 3, suggest follow-up
- <claim 3>: ❌ Disputed (Low or sources conflict) — Source 4 vs 5 contradict

## Gaps & next steps
- Still needed: <what's missing>
- Unresolved conflicts: <where sources disagree>

参考文档中提供了完整示例（针对一个仿真的真实问题撰写的严格模式报告）。

---

易忽略的陷阱

• “官方”不一定指供应商网站。 对于开源项目，权威来源可能是 GitHub 仓库的 README / 文档目录，或 RFC，而不是用于营销的 .com 网站。应根据项目本身发布准确信息的位置来判断什么是“官方”。
• 同一页面内的版本可能不一致。 单个文档页面可能涵盖多个主版本；请确保引用的代码片段描述的是用户正在使用的版本，而不是已弃用的部分。检查页面上的版本选择器 / 横幅。
• 没有日期的页面 ≠ 长期有效。 有些无日期页面经久不变（如规范、算法）；大多数无日期的网页内容只是疏于维护。对于快速变化的主题，应将无日期内容视为过时。
• StackOverflow 的高票答案可能已有十年历史。 票数反映的是过去的实用性，并不代表当前仍然正确。务必核对日期，并根据当前版本进行测试。
• 两个来源，实际只有一个源头。 如果博客 B 引用了博客 A，它们就不是独立来源。独立性要求各自有独立的推理或原始证据。
• AI 生成的搜索摘要是汇总内容，不是来源。 Google AI Overviews、Perplexity、Bing Copilot 等会综合其他页面的内容——它们是方便的起点，但属于二手资料。在转述仅由 AI 摘要支持的说法之前，应追溯到摘要引用的底层原始来源；如果没有，就将其视为单一来源并交叉核验。
• 相同的包名，不同的生态系统。 不同生态系统中的包名可能重名——jsonwebtoken（npm）与 jsonwebtoken（Rust crate，Keats/jsonwebtoken）；jwt-go 与 golang-jwt。搜索结果或安全公告提到某个包时，请先检查生态系统字段（npm/cargo/go/pypi），再判断它是否与目标包匹配。Rust crate 的 CVE 与 npm 用户无关，反之亦然。
• 默认模式不是用户可见的预检清单。 它是一种无声的行为准则。不要叙述“正在应用准则 2……”——直接照做并妥善引用即可。

---

参考

完整材料——包含 7 个维度的 High/Med/Low 评分标准、扩展后的严格模式报告模板，以及一个完整示例——见 reference.md。需要严格模式的评分标准，或对某个维度的判断存在歧义时，请阅读该文档。