research-online

GG → 在线研究 → Web Research

在高置信度作答前，请根据实时来源核实对版本敏感的答案。

快速开始

本技能中的工具名称： web_search 和 web_fetch 指当前运行环境提供的任何搜索和页面抓取工具（内置、MCP、CLI 或其他工具）。名称各不相同（web_search/web_fetch、WebSearch/WebFetch、open_page、浏览器抓取）。使用当前可用的工具。不要要求使用 Firecrawl 或其他任何指定供应商。

**搜索前，请先回答下方「研究规划」中的 3 个规划问题：**你需要什么、你已经知道什么，以及什么程度才算足够。然后按照以下 5 个步骤操作：

1. 发现 — 使用 web_search，并提供具体且消除歧义的查询。先浏览标题和摘要，不要通读所有结果。如果结果揭示了更具体的问题，请接着搜索（参见「研究方法 → 研究链式搜索」）。
2. 深入阅读 — 仅使用 web_fetch 抓取最相关的 1–2 个 URL。默认启用内容清理。
3. 评估 — 使用 5 项信号启发式方法为每个来源评分（官方文档 > GitHub 代码库 > 论坛/博客）。参见 references/source-evaluation.md。
4. 综合 — 先给出研究发现，为每项主张注明来源，按照以下优先级解决冲突（官方 > 社区、较新 > 过时、一手 > 二手、共识 > 个例、可验证 > 不可验证），并明确指出信息缺口。交付前，请根据「研究质量检查清单」核实。
5. 保存 — 使用 save-web-research.ts 保存产物，使用 consolidate-research.ts --auto-session 生成去重后的摘要。默认启用内容清理。

如果经过 2–3 次改写查询后结果仍不理想，请遵循研究陷入僵局流程（对失败进行分类，切换策略而非工具，记录信息缺口，并升级处理而非推断）。

何时已有足够证据停止研究，请参见研究方法 > 研究充分性。

默认使用运行环境提供的搜索/抓取工具。如果运行环境的抓取功能无法满足需求，可以选择专业后端（Firecrawl CLI 的 map/crawl/schema/browser，或任何已可用的同类工具）。参见下方的「混合两阶段研究模式」。

研究规划

首次搜索前，请先明确三件事。花 30 秒规划，可以避免 30 分钟漫无目的地搜索。

1. 你需要什么。 用一句话写下研究问题。如果写不出来，说明查询范围太广——请缩小范围，直到可以写出为止。
2. 你已经知道什么。 列出你确信的事实，以及你了解这些事实的版本或日期。这有助于避免重复发现已有信息。
3. 什么程度才算足够。 适用哪条「研究充分性」停止规则？（1 个权威来源？2 个相互印证的来源？注明版本的答案？）请在搜索前设定目标，以便知道何时停止。

如果无法回答第 1 个问题，请遵循研究陷入僵局流程：改写问题、切换策略并记录信息缺口。不要抱着碰碰运气的想法，直接开始模糊搜索。

概述

使用此技能开展在线研究，并返回有来源支持且附带可复现产物的答案。

工具选择应遵循务实的决策树，而非偏好某个供应商。 使用当前可运行的任意运行环境搜索和抓取工具。专业后端（Firecrawl CLI 或同类工具）是可选的额外工具，并非前提。

工具选择决策树

1. Is a host web search or page-fetch tool available?
   → YES: Use it (default path). Continue only if the task still needs more.
   → NO: Stop and report that no web search/fetch is available. Do not wait for a specialized backend.

2. Does the task need site mapping, multi-page crawl, schema extraction, or JS browser automation that host fetch cannot do?
   → NO: Stay on host search/fetch. Save artifacts. Done.
   → YES: continue

3. Is a specialized backend (Firecrawl CLI or equivalent) already available?
   → YES: Use it for those advanced steps only.
   → NO: Complete with host tools; note the capability gap in the synthesis. Do not install or authenticate a backend mid-research.

4. Need reproducible artifacts?
   → Always save via save-web-research.ts / session scripts. Firecrawl output dirs are only for Firecrawl runs.

**核心原则：**最好的工具是当前可用且足以完成任务的工具。如果运行环境的搜索/抓取工具能够回答问题，绝不要为了等待 Firecrawl（或任何其他后端）而暂停研究。

混合式两阶段研究模式

对于既需要广度又需要深度的多源研究，可分两个阶段组合使用这些工具：

阶段 1 — 发现（默认使用宿主搜索/抓取）：

1. 使用宿主 web_search 搜索研究查询，以发现相关 URL。
2. 查看结果标题和摘要，找出最有希望的 2–5 个来源。
3. 仅使用宿主 web_fetch 抓取最有希望的 1–2 个 URL，以便立即深入阅读。不要抓取所有结果——有选择地抓取可减少上下文噪声，并提升综合分析质量。
4. 如果答案已经足够，就直接给出综合结论——无需使用专用后端。

阶段 2 — 深度提取（可选的专用后端）： 5. 仅当宿主抓取无法生成干净的提取结果、结构化 JSON、站点地图或爬取结果，且 Firecrawl CLI 等后端已可用时：

firecrawl scrape "<url>" --only-main-content --format markdown

6. 对于需要映射的多页面网站（宿主抓取没有同等功能）：

   firecrawl map "<site-root>" --search "<topic>"
   

7. 将所有阶段 2 的输出保存到 .researches/<timestamp>/ 会话文件夹。

跳过阶段 2 的情况：

• 阶段 1 已提供足够的答案。
• 未安装或未通过身份验证的专用后端。
• 研究不需要映射、爬取、模式提取或双重表示归档。

适合使用阶段 2 的情况（仅当后端已可用时）：

• 研究需要提取结构化 JSON（firecrawl agent --schema 或同等工具）。
• 研究需要站点范围的映射或爬取。
• 研究需要宿主抓取无法生成的双重表示归档。

此模式使用始终可用的宿主工具进行发现，仅在专用后端能独特完成的提取任务上消耗后端资源。

搜索后有选择地抓取（关键效率模式）

web_search 会返回 5 条结果，每条结果都包含完整页面内容——文本可能多达数千个 token。完整处理所有结果会浪费上下文，并引入无关页面带来的噪声。

高效工作流：

1. 浏览，不要通读。 web_search 返回结果后，只阅读响应中的标题、URL 和摘要文本。不要将完整内容全部放入上下文。
2. 选出最相关的 1–2 条结果。 根据标题相关性、域名权威性和摘要质量，挑选最有可能回答问题的 URL。
3. 有选择地深入阅读。 仅对这 1–2 个 URL 使用 web_fetch。如果第一条结果已回答问题，就此停止——无需抓取更多结果。
4. 保存发现结果。 使用 save-web-research.ts 保存完整搜索结果，以便复现，即使你只对其中一部分进行了深入阅读。

反模式：

❌ web_search → read all 5 full results → try to synthesize from 5 noisy pages
✅ web_search → scan titles + snippets → select 1-2 best → web_fetch → synthesize

何时抓取更多内容： 如果排名前 2 的结果无法回答问题，就扩展到第 3–5 条结果。如果仍无结果能回答，就细化搜索查询。只有在宿主抓取不足且专用后端已可用时，才升级到阶段 2。如果结果回答了宽泛问题，却引出了更具体的问题，就串联后续搜索（参见 研究方法 → 研究串联）。有关按查询类型设定的停止标准，请参见 研究方法 → 研究充分性。

如需查询直接命令，请参见下方的 快速命令。

与专用后端的关系

research-online/SKILL.md 是工作流和归档层，不依赖 Firecrawl。

• 当任务需要执行端到端研究会话时，使用此技能：初始化带时间戳的 .researches/<timestamp>/ 目录，使用任何可用的搜索/抓取工具收集多源证据，整合发现结果，并发布可复现的产物集。
• 如果已安装同级的 firecrawl 技能（或其他地图/爬取/模式/浏览器入门指南），且该后端已可用，则按需加载它，仅用于查询命令级语法。
• 缺少 Firecrawl 并非阻碍。宿主搜索/抓取是一条完整的默认路径。

使用此技能的时机

在以下情况触发：

• 用户询问最新网络信息、多来源发现或站点映射。
• 任务需要从网页中提取结构化信息，或进行自主研究。
• 研究涉及比较多个站点的文档。
• 需要根据实时网络来源核实某项说法。
• 处理需要忠实归档的 GitHub 仓库文档。

在以下情况跳过：

• 问题可根据本地代码库或已提交的文档回答。
• 用户明确要求提供观点或创意写作，不需要事实依据。
• 已有专门的相邻专家技能单独涵盖特定工具的使用范围（例如 Firecrawl CLI 语法）。此技能仍负责研究过程。

常见误解

#	误解	更正	关键概念
1	此技能必须使用 Firecrawl（或其他指定供应商）	默认使用宿主环境的搜索/抓取功能。已有专用后端时，可将其作为可选补充。切勿因等待配置而阻碍研究。	务实地选择工具
2	一种文档格式就够了	对于文档目标，应同时保留 Markdown 和 HTML	双重表示约定
3	firecrawl browser 简写可靠	它取决于版本且不稳定；优先使用明确的命令	浏览器回退方案的脆弱性
4	GitHub blob 页面中的 Markdown 是干净的源文本	其中包含 GitHub 页面元素；请使用 raw.githubusercontent.com 或本地克隆	混合归档模式
5	无需发布研究会话	默认发布已完成的会话，除非用户另有说明	限定范围的成果发布
6	宿主环境的网页工具不如 Firecrawl	宿主环境的搜索/抓取是默认方式：无需额外配置，任何提供搜索或抓取功能的运行环境都能使用。专用后端仅增加映射、爬取、架构和浏览器功能。	工具互补性
7	应完整阅读所有 web_search 结果	先浏览标题和摘要，再仅对最相关的 1-2 个 URL 使用 web_fetch。完整阅读所有结果会浪费上下文并引入噪声。使用 save-web-research.ts 保存所有结果，以便复现。	选择性抓取
8	搜索查询质量无关紧要——工具总会返回最佳结果	查询措辞是最具影响力的研究技能。具体且无歧义的查询比模糊查询能返回相关得多的结果。获取更多内容前，先改写查询。	查询措辞
9	任何与主题相关的来源都同样可靠	评估来源有助于区分权威答案与噪声。优先选择官方文档、GitHub 仓库和注明版本的来源，而非论坛和 SEO 博客。	来源评估
10	搜索失败时，换一个搜索工具试试	如果宿主环境的搜索返回结果不佳，使用相同查询的其他搜索后端也会返回不佳结果。先改写查询，再考虑切换工具。	查询改写
11	搜索越多，结果总会越好	改写查询 2-3 次仍未成功后，继续搜索只会浪费上下文和额度。遵循研究陷入僵局协议：判定失败类型、切换策略并记录信息缺口。	僵局处理协议
12	来源越多，综合结论总会越好	对大多数问题而言，2 个相互独立且结论一致的来源就足够了。3 个以上来源确认相同答案属于确认，而非改进。当证据相互印证、找到官方来源或获得注明版本的答案时，就应停止。参见研究方法 → 研究充分性。	研究充分性
13	研究应该从搜索开始	研究应该从规划开始。如果没有一句话的研究问题、对已有认知的了解和停止规则，搜索就会缺乏重点，结果也会充满噪声。参见研究规划。	研究规划
14	一次搜索总是够用	复杂问题往往需要串联后续搜索，初始结果会揭示更具体的问题（“X 如何运作？” → “X 如何处理 Y？”）。在后续查询中沿用初始结果里的版本号和关键术语。参见研究方法 → 研究串联。	研究串联

快速命令

混合发现模式（推荐用于大多数研究）：

1. 使用主机 web_search 发现内容，然后使用主机 web_fetch 深入阅读：

web_search: "What changed in Next.js 15?"
→ scan titles + snippets (don't read all results in full)
→ select 1-2 most relevant URLs
web_fetch: top URL for deep content
→ optional, only if host fetch is insufficient AND a specialized backend is already available:
   firecrawl scrape "<url>" --only-main-content --format markdown

初始化研究会话：

npm run research:session:init -- --query "What changed in Next.js 15?"

可选的 Firecrawl 搜索（仅当该 CLI 已可用且主机搜索无法满足需求时）：

export FIRECRAWL_OUTPUT_DIR=".researches/<timestamp>/firecrawl/raw"
firecrawl search "site:nextjs.org Next.js 15" --scrape --limit 10 --json \
  -o "$FIRECRAWL_OUTPUT_DIR/search.json"

可选的双重表示抓取（条件相同）：

firecrawl scrape "https://docs.nextjs.org/14" --format markdown \
  -o ".researches/<timestamp>/documentation/markdown/nextjs-14.md"
firecrawl scrape "https://docs.nextjs.org/14" --format html \
  -o ".researches/<timestamp>/documentation/html/nextjs-14.html"

使用会话自动发现功能整合（如存在，则会拾取 web-search、web-fetch、web-research 和 firecrawl 目录）：

# Runner alternatives: bunx tsx / pnpm dlx tsx / deno run -A npm:tsx / node --import tsx / yarn dlx tsx
npx tsx .agents/skills/research-online/scripts/consolidate-research.ts \
  --session-dir .researches/<timestamp> \
  --query "What changed in Next.js 15?" \
  --format thematic

# Content cleaning is enabled by default during consolidation.
# Use --no-clean to disable it when raw content is needed:
npx tsx .agents/skills/research-online/scripts/consolidate-research.ts \
  --session-dir .researches/<timestamp> \
  --query "What changed in Next.js 15?" \
  --format thematic \
  --no-clean

# Or consolidate the latest session automatically:
npx tsx .agents/skills/research-online/scripts/consolidate-research.ts \
  --auto-session \
  --query "What changed in Next.js 15?" \
  --format thematic

从指定目录整合（旧版，单个输入目录）：

# Runner alternatives: bunx tsx / pnpm dlx tsx / deno run -A npm:tsx / node --import tsx / yarn dlx tsx
npx tsx .agents/skills/research-online/scripts/consolidate-research.ts \
  --input-dir .researches/<timestamp>/firecrawl/reports \
  --query "What changed in Next.js 15?" \
  --format thematic

将主机 Web 工具的结果保存到会话中：

# Save web_search results
# Runner alternatives: bunx tsx / pnpm dlx tsx / deno run -A npm:tsx / node --import tsx / yarn dlx tsx
npx tsx .agents/skills/research-online/scripts/save-web-research.ts \
  --query "Drizzle ORM connection pooling" \
  --source search \
  --content '{"results": [...]}'

# Save web_fetch content (content cleaning enabled by default for fetch sources)
npx tsx .agents/skills/research-online/scripts/save-web-research.ts \
  --query "Drizzle ORM connection pooling" \
  --source fetch \
  --content "$(cat page.md)" \
  --url "https://orm.drizzle.team/docs/connect-overview"

# Save web_fetch content with raw content preserved (--no-clean)
npx tsx .agents/skills/research-online/scripts/save-web-research.ts \
  --query "Drizzle ORM connection pooling" \
  --source fetch \
  --content "$(cat page.md)" \
  --url "https://orm.drizzle.team/docs/connect-overview" \
  --no-clean

完整的命令列表请参阅 references/tool-selection.md。

命令选择指南

场景	最佳工具	理由
快速查找事实或发现内容	主机 web_search	默认路径；使用任何可用的搜索功能
已知 URL，需要阅读	主机 web_fetch	默认路径；使用任何可用的抓取功能
不知道确切 URL，需要定向搜索	主机 web_search，然后 web_fetch	扫描摘要，再有选择地深入阅读
需要了解网站结构	专用后端 map（例如 Firecrawl），前提是已可用	没有等效的主机工具
深入研究某个文档部分	对列出的 URL 使用主机 web_fetch；可选专用 crawl	仅在后端可用时抓取
提取结构化字段	专用 agent --schema，前提是已可用	否则抓取并手动解析
复杂的自主探索	专用 agent --wait，前提是已可用	否则串联主机搜索
JS 密集型或交互式页面	专用 browser，前提是已可用	否则注明这一限制
为仓库文档进行多源归档	archive-github-repo-docs.ts	混合捕获 Markdown 和 HTML
可复现的研究会话	会话脚本 + .researches/	不受所用搜索/抓取方式影响
未安装专用后端	主机 web_search / web_fetch	完整的默认路径，而非备用方案

**经验法则：**使用足以满足需求的最简单可用工具。使用主机搜索/抓取进行发现和阅读。仅在需要执行映射、抓取、模式提取或浏览器操作，且专用后端能提供独特支持时才使用它们；并且仅限后端已可用的情况。

快速决策指南

场景	推荐路径	权衡
需要从 Web 获取最新事实	主机 web_search	默认方式；无需额外安装
深入提取文档内容	单个页面使用主机 web_fetch；多页面网站可选专用 map/scrape	主机工具速度更快；仅在后端已可用时使用后端
从已知页面获取结构化数据	专用 agent --schema，前提是已可用；否则抓取并解析	模式提取是可选的
JS 密集型或交互式页面	专用 browser，前提是已可用；否则注明这一限制	速度最慢；仅在主机抓取失败时使用
GitHub 仓库文档	archive-github-repo-docs.ts	避免 blob 页面中的 Markdown 噪声
无需会话的快速提问	主机 web_search	获取答案的最快方式
系统化的多源研究	主机搜索/抓取 + .researches/ 会话	可复现性不依赖 Firecrawl
结合内容发现与深入提取	阶段 1：主机 web_search → 阶段 2：仅在必要且后端可用时执行	默认仅使用主机工具

研究方法

除了工具选择之外，研究质量还取决于三个因素：查询设计、来源评估和综合归纳的严谨性。本节为每项提供具体的启发式方法。

查询表述

搜索结果的质量直接取决于查询的构造。请遵循以下原则：

如需查看包含改写技巧、特定领域模式和反模式示例的完整速查卡，请加载 references/query-formulation.md。

1. 从具体问题开始，必要时再放宽范围。 围绕确切的技术概念、API 或错误消息来构造查询。如果结果较少，每次放宽一个词。

   ❌ "how to use drizzle"          → too broad, returns marketing pages
   ❌ "drizzle orm"                → returns overview, not specifics
   ✅ "drizzle ORM connection pooling postgres"  → targets the exact topic
   ✅ "drizzle pgPool2 connection config"          → uses the specific API name
   

2. 加入用于消除歧义的上下文关键词。 “Auth”可能指很多东西；“Better Auth Next.js session cookie”则能消除歧义。

   ❌ "authentication setup"
   ✅ "Better Auth Next.js App Router session configuration"
   

3. 对于时效性强的主题，注明版本和年份。 框架和 API 会变化；包含版本的查询能找到最新答案。

   ❌ "Next.js App Router changes"
   ✅ "Next.js 15 App Router changes 2025"
   

4. 引用确切的错误消息。 调试时，使用完整的错误字符串（或其中最独特的片段）作为查询。

5. 注明技术名称。 “connection pooling”这类通用词语会返回无关结果；“pg-pool connection pooling Node.js”则能缩小搜索范围。

6. 避免使用疑问词。 以“how to”“what is”或“why does”开头的查询会削弱搜索信号。应以技术名词短语开头。

7. 迭代：改写查询，而不是只获取更多结果。 如果首个查询返回的结果质量不高，请先使用不同术语改写查询，再获取更多页面。

来源评估

并非所有结果都同样可靠。浏览 web_search 结果或为 web_fetch 选择 URL 时，请运用以下启发式原则：

如需查看包含域名权威性速查表、危险信号和查询改写指南的完整速查卡，请加载 references/source-evaluation.md。

信号	优质来源	较弱来源
域名	官方文档、GitHub 仓库、.dev 网站	论坛、SEO 内容过多的博客、内容农场
时效性	发布于最近 12 个月，或注明版本	未注明日期、未提及版本
深度	代码示例、API 签名、迁移指南	高层概述、营销文案
权威性	一手来源（作者是维护者或官方团队）	未引用官方来源的第三方教程
规范性	引用 RFC、规范或官方变更日志	未提供来源链接的转述摘要

优先级规则： 如果某个结果符合 3 项或更多优质信号，优先深入阅读。如果没有结果符合 2 项或更多优质信号，请改写查询。

综合质量

研究综合内容应是结构化答案，而不是片段的拼接：

1. 先给出直接答案。 在第一句话中说明结论，然后用证据支持。
2. 为每项主张注明来源。 对每条事实陈述，都应附上来源 URL 和日期。
3. 指出冲突。 如果两个来源存在分歧，应同时说明，并依据冲突解决优先级作出判断（官方 > 社区、较新 > 过时、一手 > 二手、共识 > 少数意见、可验证 > 不可验证）。
4. 明确标出缺口。 如果没有来源能完整回答问题，请说明这一点，不要进行外推。
5. 区分事实与观点。 如果唯一可用的证据来自论坛帖子或博客观点，应将其标注为观点。
6. 提供版本背景。 如果研究涉及变化迅速的库或 API，请注明结论适用的版本。

冲突解决

当两个或更多来源存在分歧时，按以下优先级进行判断：

1. 官方文档 > 社区内容。 如果官方文档说 X，而 Stack Overflow 上的回答说 Y，则优先采用官方文档——除非官方文档已过时（请检查发布日期）。
2. 近期内容 > 过时内容。 如果一篇 2025 年的文章与一篇 2023 年的文章对某个快速迭代的库持不同观点，则优先采用 2025 年的文章。务必注明版本或日期。
3. 一手来源 > 二手来源。 如果原始来源（RFC、规范、一手方文档）说 X，而第三方教程说 Y，则优先采用一手来源。
4. 共识 > 少数观点。 如果 4 个来源说 X，而 1 个来源说 Y，则注明少数观点，但遵循共识——除非少数观点来自官方来源。
5. 可验证 > 不可验证。 如果一个来源提供代码示例、可复现的步骤或一手来源链接，而另一个来源提出了缺乏依据的主张，则优先采用可验证的来源。

如果应用这些规则后仍无法解决冲突，请在综合结果的“相互矛盾的证据”部分呈现双方观点，并说明为何无法明确判定哪一方更可靠。

迭代优化模式

当初始查询未能返回有用结果时：

Step 1: Classify the failure
  - No results → query too specific or uses uncommon terminology
  - Irrelevant results → query too broad or ambiguous
  - Outdated results → add version/year qualifiers
  - Low-authority results → add technology name or scope qualifier

Step 2: Reformulate using one tactic at a time
  - Generalize: remove the most specific term
  - Rephrase: swap in synonyms or alternate terminology
  - Scope: add technology/framework name as context
  - Version: add year or version number
  - Error-quote: use exact error message

Step 3: Stop after 2-3 reformulations
  - If still unsuccessful, note the gap in the synthesis
  - Consider whether the information exists online at all
  - Suggest alternative research angles if appropriate

研究链式检索

当初始搜索取得成功，但引出了更具体的问题时，应继续进行后续搜索，而不是从头开始：

1. 提取具体问题。 初始结果回答了宽泛的问题，但也引出了更狭窄、更深入的问题（“X 如何工作？”→“X 如何专门处理 Y？”）。将后续问题写成一个新的单句研究问题。
2. 沿用已有信息。 在后续查询中加入初始结果里的版本号、框架名称和关键术语。这样能让后续查询更加具体，也更有可能返回相关结果。
3. 采用更严格的充分性标准。 现在你进行的是第二次或第三次搜索。只要有一个权威来源直接回答了后续问题，就足够了——不需要重新查找宽泛背景信息。

Chain example:
  Search 1: "Next.js App Router" → reveals Server Components are the key concept
  Search 2: "Next.js 15 Server Components data fetching" → reveals caching behavior
  Search 3: "Next.js fetch cache revalidation" → targeted answer found, stop

何时继续搜索、何时停止： 当初始答案不完整，或揭示了你未预料到的依赖关系时，继续搜索。当你获得了直接且注明版本的原始问题答案时，停止搜索。

避免过度链式搜索： 如果已连续进行 3 次或更多次后续搜索，却仍未找到直接答案，说明原始问题可能过于宽泛，或者相关信息可能不存在于网上。请改用“无结果处理协议”，而不是继续搜索。

研究陷入僵局协议

当 2-3 次改写查询后仍未获得理想结果时，请遵循此协议，而不是继续搜索：

1. 判断陷入僵局的类型：

   • 主题过于小众： 相关信息可能没有公开记录。转而查阅一手来源（官方文档、GitHub 仓库、RFC）。
   • 主题过新： 相关信息可能尚未发布。搜索预发布文档、GitHub issues 或讨论论坛。
   • 主题过于模糊： 拓宽问题范围并研究相关领域，然后再缩小到具体问题。
   • 语言障碍： 相关信息可能只有其他语言版本。尝试使用翻译后的关键词调用 web_search。

2. 转换策略，而不是工具：

   • 如果主机的 web_search 返回的结果不理想，不要用相同的查询切换到另一个搜索后端——问题出在查询，而不是工具。
   • 首先尝试限定站点的搜索：site:docs.example.com <topic> 可直接针对官方文档进行搜索。
   • 尝试限定版本的搜索："<library> <version>" <feature> 可查找特定版本的信息。
   • 尝试搜索错误原文：粘贴完整错误消息或其中最独特的片段。

3. 在综合整理中记录搜索僵局：

   • 说明搜索了什么以及哪些尝试无效。
   • 记录返回结果不理想的查询。
   • 明确指出信息缺口：“未找到关于 [topic] 的权威来源。”
   • 建议后续行动：“直接查看 [URL] 上的官方文档”或“通过 GitHub issues 联系维护者。”

4. 升级处理，而不是推断：

   • 切勿根据薄弱证据编造答案。
   • 如果有部分信息，请使用恰当的置信度限定词呈现。
   • 如果没有相关信息，请如实说明。诚实地说“我不知道”，胜过自信地给出错误答案。

研究充分性

知道何时停止研究，与知道如何研究同样重要。研究过度会浪费上下文和额度；研究不足则会导致综合结论不可靠。

满足以下条件时停止：

1. 证据相互印证。 至少 2 个独立来源对同一答案达成一致。一个来源是线索，两个是信号，三个则是确认。
2. 找到官方来源。 如果官方文档直接回答了问题，就停止。除非官方文档已过时，否则无需再找次级来源确认。
3. 答案限定了版本。 如果答案包含版本号和日期（例如，“Next.js 15，2025”），证据就有时间标记，不太可能被较新的搜索结果推翻。
4. 涵盖所有子问题。 如果原始研究问题有 3 个方面，且你已回答全部 3 个，就停止——即使还能为方面 1 找到更多来源。

以下情况应继续研究：

• 来源相互矛盾（遵循“冲突解决”流程）。
• 唯一的来源是论坛、博客文章或 AI 生成内容（寻找官方或一手来源）。
• 答案取决于版本，且没有注明版本（在查询中添加版本限定条件）。
• 你只找到了间接证据（没有来源直接回答问题）。

不同查询类型的实用停止规则：

查询类型	满足以下条件后停止	满足以下条件前切勿停止
简单事实查询	1 个权威来源确认	1 个来源确认
限定版本的问题	1 个注明版本的官方来源	已注明版本
操作指南 / 配置	1 篇官方文档 + 1 个可运行示例	文档和示例均与指定版本相符
比较 / 权衡	至少 2 个观点不同的来源	已涵盖所有观点
错误诊断	1 个经版本验证的有效修复方案	修复方案与版本相符

不可妥协的政策

1. 默认使用宿主搜索／抓取工具。 使用运行环境提供的任何 web_search／web_fetch（或同类工具）。专用后端（Firecrawl CLI 或同类工具）仅可用于其独有的映射、爬取、架构和浏览器任务。
2. 切勿因后端设置而停滞。 对于常规研究，不要在预检时运行 firecrawl --status。如果需要某个专用步骤，但后端不可用，请使用宿主工具完成任务并注明限制——不要在研究过程中安装或进行身份验证。
3. 仅当专用后端已可用且你需要查询命令语法时，才使用 references/tool-selection.md；切勿凭记忆还原 CLI 标志。
4. 从成本最低的工作流开始（宿主搜索，然后选择性抓取；如果有后端，再优先使用专用 search／scrape，然后才使用 agent／browser）。
5. 只加载任务所需的 references/ 子集。默认不要读取所有文件。
6. 将研究会话保存在 .researches/<timestamp>/ 下；对于文档目标，同时保留 Markdown 和 HTML 两种表示形式。
7. 在每份综合材料中保留来源归属，并在发布前使用 scripts/consolidate-research.ts 进行整合。
8. 对于任何有关专用后端定价、模型或当前版本的回答：应认为捆绑数据很可能已过时，陈述具体信息并给予高度确信前，先使用该工具的 --help 进行核实。
9. 当宿主工具无法完成映射、爬取、架构或 JS 浏览器任务时， 在综合材料中注明这一限制。不要将仅使用宿主工具进行的研究视为不完整。

工作流

0. 搜索前先制定计划。 回答 3 个研究规划问题：(1) 你的研究问题用一句话怎么表述？(2) 你已经了解什么？(3) 适用哪条研究充分性停止规则？问题尚未明确时，不要跳到步骤 1。

1. 判断研究复杂度。

   • 简单（快速查询、单一事实、比较）：直接使用主机 web_search / web_fetch。跳到步骤 7。
   • 高级（多来源、结构化提取、站点映射、可复现归档）：先使用主机工具，然后继续步骤 2。

2. 使用主机搜索/抓取工具。 专用后端为可选项：仅当主机工具无法完成映射/爬取/架构/浏览，且后端已可用时才使用。对于常规研究，切勿预先运行 firecrawl --status。

3. 初始化研究会话：

   npm run research:session:init -- --query "<research question>"
   

4. 对任务进行分类，并加载最少量的实用参考资料（见下表）。

5. 使用选定的工具收集数据，并将数据保存到当前会话文件夹。

   • 谨慎拟定查询（参见“研究方法论” > “查询拟定”）。从具体查询开始，必要时再扩大范围；结果不理想时应重新拟定查询，而不是继续抓取更多内容。
   • 深入阅读前评估来源（参见“研究方法论” > “来源评估”）。优先选择符合 3 项或以上强信号的结果（官方文档、近期内容、代码示例、权威来源、规范来源）。
   • 主机 Web 工具：通过 save-web-research.ts 将结果保存到 .researches/<timestamp>/（web-search/、web-fetch/、documentation/markdown/ 和 html/）。
   • 专用后端（可选）： 如果使用 Firecrawl CLI，请设置 FIRECRAWL_OUTPUT_DIR=".researches/<timestamp>/firecrawl/raw"。
   • 对于文档页面，同时保留 Markdown 和 HTML 版本。
   • 对于 GitHub 仓库文件，请使用 scripts/archive-github-repo-docs.ts（参见 references/github-repository-doc-archival.md）。

6. 如果不清楚专用后端命令的用法，请在扩大范围前查阅同级指南。不要因为缺少指南而阻碍研究。

7. 当上下文或并行任务较多时，使用 harness workers 并行处理相互独立的来源（参见 references/harness-patterns.md）。

8. 使用 scripts/consolidate-research.ts 汇总研究结果。

   • 默认启用内容清理；使用 --no-clean 可保留原始内容。
   • 使用 --auto-session 自动发现会话。
   • 检查汇总输出中的清理统计，确认已移除页面杂项内容。

9. 返回简洁的综合结论，并明确指出信息缺口和置信度。

   • 遵循综合分析规范（参见“研究方法论” > “综合质量”）：先给出直接答案，为每项主张标明来源，指出冲突，标记信息缺口，区分事实与观点，并说明版本背景。
   • 交付前，根据“完成输出规范” > “研究质量检查清单”进行核验。
   • 如果 2–3 次重新拟定查询后仍无结果，请遵循“研究方法论” > “研究无果处理协议”，不要继续搜索。

按任务类型加载参考资料

仅加载任务所需的子集。普通研究前不要运行专用后端状态检查。

任务类型	加载这些文件	跳过
选择专用后端命令（仅当该后端已可用时）	tool-selection.md	consolidation-patterns.md
并行开展多来源研究	harness-patterns.md	github-repository-doc-archival.md
归档 GitHub 仓库文档	github-repository-doc-archival.md	harness-patterns.md
整合子 Agent 结果	consolidation-patterns.md	tool-selection.md
评估来源可信度	source-evaluation.md	consolidation-patterns.md
制定有效查询	query-formulation.md + source-evaluation.md	github-repository-doc-archival.md
改进糟糕的搜索结果	query-formulation.md（改写技巧）	source-evaluation.md
快速研究（宿主工具）	query-formulation.md + source-evaluation.md	tool-selection.md、harness-patterns.md、github-repository-doc-archival.md
保存并整合资料	consolidation-patterns.md（会话发现）	source-evaluation.md

完成输出约定

综合格式

使用以下结构交付研究结果：

## [Topic]

**Answer:** [Direct answer to the research question — 1–3 sentences]

### Key Findings
1. [Finding 1 with attribution — `source URL (date)`]
2. [Finding 2 with attribution]

### Conflicting Evidence
- [Conflict: Source A says X, Source B says Y. Resolved: prefer A because (official docs > community / recent > outdated / primary > secondary)]

### Gaps
- [Explicitly state what could not be determined]

### Sources
- [Source 1: URL — version/date — signal score]
- [Source 2: URL — version/date — signal score]

省略没有内容的部分（例如，没有相互矛盾的证据时，省略该部分）。

研究会话完成后，将 Next steps: 作为 CHOOSEABLE_OPTIONS 列出，格式遵循 chooseable-options/SKILL.md（打印令牌并且在该工具可用时使用 harness Ask User 选择器）：

• ACTION_NAME_IN_SCREAMING_SNAKE_CASE：选择后将执行的操作说明。

必需的基础选项：

• CREATE_RESEARCH_DERIVED_EXPERT_SKILL：基于本研究主题创建可复用的专家技能，并使用确切的 .researches/<timestamp>/ 载荷（consolidated.md、consolidated.json、web-search/、web-fetch/、metadata.json，以及使用了专用后端时的任何 firecrawl/ 目录）。

跨技能路由选项（根据已发现的信号动态生成）：

• PREPARE_IMPLEMENTATION_PLAN：当研究结果已可用于实施时，路由至 plan/SKILL.md。
• DEEPEN_RESEARCH_WITH_ONLINE_STUDY：仍有重要未知事项时，路由至 study/SKILL.md。
• RESOLVE_COMPETING_APPROACHES：权衡取舍尚未解决时，路由至 decisions/SKILL.md。
• SYNC_GUIDANCE_DOCUMENTATION：需要更新政策或文档时，路由至 documentation-sync 工作流。
• REFINE_SPECIALIZED_BACKEND：仅当使用了该后端且仍存在命令缺口时，路由至同级入门指南（firecrawl 或同类工具）。
• VALIDATE_RESEARCH_CLAIMS_IN_UI：研究发现涉及面向用户的行为时，路由至 playwright-cli 工作流。
• TARGET_PRIMARY_DOC_RESEARCH：来源冲突或置信度较低时，使用更精确的范围继续执行 research-online/SKILL.md。

研究质量检查清单

完成任何研究综合前，请核实以下每一项：

#	检查项	重要性
1	先给出直接答案——综合内容是否先呈现结论，而不是来源？	读者应先看到答案，再看证据
2	为每项主张注明来源——每条事实陈述是否都附有来源 URL 和日期？	未注明来源的主张无法核实，也可能有误
3	解决冲突——如果两个来源意见不一，是否都已注明，并依据冲突优先级（官方 > 社区、近期 > 过时、一手 > 二手、共识 > 少数观点、可核实 > 不可核实）得出结论？	忽略冲突会造成虚假的确定感
4	明确标注信息缺口——尚未解答的问题是否标为信息缺口，而非推断补全？	坦诚说明信息缺口，好过编造答案
5	区分事实与观点——是否将论坛帖子和博客观点标注为观点？	并非所有来源都具有同等可信度
6	提供版本背景——对于快速迭代的库，是否注明版本号和日期？	不注明版本的答案很快就会过时
7	评估来源——引用的来源是否在 5 项信号启发式评估中得分达到 3 分以上？	低质量来源会削弱整个综合内容的可信度
8	重新拟定查询——如果初始结果不理想，是否在获取更多结果前优化了查询？	无论选择什么工具，糟糕的查询都会产生糟糕的研究结果
9	清理内容——是否已从获取的页面中移除导航界面元素（save-web-research 和 consolidate 默认会执行此操作）？	冗杂内容会降低综合质量
10	保存研究产物——是否已将所有结果保存到 .researches/<timestamp>/，以便复现？	未保存的结果无法核实或重新分析

会话存储

在 .researches/ 下使用带时间戳的会话文件夹：

.researches/
└── 2026-02-11T134626Z/
    ├── documentation/
    │   ├── html/
    │   ├── markdown/
    │   └── screenshots/
    │       └── full-page/
    ├── firecrawl/           ← only if a Firecrawl backend was used
    │   ├── raw/
    │   └── reports/
    ├── web-search/          ← host search artifacts (JSON)
    ├── web-fetch/           ← host fetch artifacts (markdown, HTML)
    ├── web-research/        ← hybrid search+fetch artifacts
    ├── metadata.json
    ├── subagent-reports/
    ├── consolidated.md
    └── consolidated.json

请保留已提交的 .researches/.gitkeep，并发布已完成的生成会话文件夹。

常见误区

1. 因等待 Firecrawl（或任何专用后端）而阻塞研究。 主机搜索和抓取是默认方式。不要停下研究去安装并验证 CLI。
2. 简单查询也要求使用专用后端。 主机 web_search 是快速查询事实和发现信息的默认方式。
3. 只保留 Markdown 文档而没有 HTML 备份。 文档目标需要同时具备两种表示形式，以确保源内容保真。
4. 将 GitHub blob 页面抓取结果视为规范源文本。 blob 页面 Markdown 包含 GitHub 页面元素；请使用 raw.githubusercontent.com 或本地克隆来获取规范文本。
5. 使用 Firecrawl 批处理命令前忘记设置 FIRECRAWL_OUTPUT_DIR。 仅在实际使用该 CLI 时才需要；每个会话设置一次即可。
6. 用 firecrawl agent 进行简单搜索。 如果使用 Firecrawl，对于已知目标，search 和 scrape 更省钱、更快捷。主机搜索更省钱。
7. 爬取时未使用 --limit 和 --max-depth 限定范围。 不受限制的爬取成本高昂，还可能触发速率限制。
8. 把主机网页工具当作备用方案。 它们是发现信息、读取单页和进行完整研究的默认方式。专用后端只是额外选项。
9. 使用含糊或范围过广的搜索查询。 “如何使用 X”会返回营销页面；“X v2 API 配置”则会返回有针对性的文档。拟定查询是最具杠杆效应的研究技能。
10. 把所有来源都视为同等可信。 官方文档和 GitHub 仓库的可信度高于随机博客文章。深入阅读前先评估来源的可靠性。
11. 失败改写 2-3 次后仍继续搜索。 如果多次改写查询后结果仍不理想，就判断卡点所在（主题太小众、太新、太含糊或存在语言障碍），然后改用其他策略或记录信息缺口。不要在无效方法上浪费额度或上下文。
12. 不改写查询，只切换工具。 如果主机搜索结果不理想，使用相同查询换另一个搜索后端也不会有好结果。问题在于查询，而不是工具——先改写查询，再切换工具。
13. 找到相互印证的证据后仍过度研究。 对于大多数问题，2 个相互独立且结论一致的来源就足够了。为同一观点继续搜索 5 个以上的来源会浪费上下文和额度。停止标准请参阅“研究方法 → 研究充分性”。
14. 跳过研究规划，直接开始搜索。 如果没有用一句话明确研究问题、了解自己已掌握的信息，并设定停止规则，第一次搜索很可能范围过广。搜索前的 3 个问题检查清单请参阅“研究规划”。
15. 后续搜索时从头开始。 如果初始结果揭示了更具体的问题，就在后续搜索中沿用版本号和关键术语，不要丢弃已有信息。请参阅“研究方法 → 研究串联”。

故障排除

症状	可能原因及解决方法
没有可用的主机搜索或抓取工具	报告此缺口。不要因为需要安装 Firecrawl 或任何其他后端而停滞。
找不到 firecrawl 命令（仅在你原本打算使用它时适用）	跳过专用步骤。继续使用主机搜索／抓取。
firecrawl scrape 的 Markdown 包含界面杂项	添加 --only-main-content。对于 GitHub 仓库，改用原始 URL 或归档辅助工具。
firecrawl browser 简写命令失败	使用显式命令 firecrawl browser execute --node ...，不要使用简写语法。
截图未返回 URL	确认已安装的 CLI 支持 --format screenshot。必要时切换到浏览器模式。
汇总结果为空	确认输入目录中包含 .json 或 .md 文件，并且已提供 --query。
会话文件夹未自动发布	输出必须位于 .researches/ 中，并且包含有效的 metadata.json。如需有意跳过，请使用 --no-publish。
主机 web_search 或 web_fetch 未返回结果	尝试其他查询词。不要使用相同的查询切换搜索后端。
主机 web_search 返回不相关的结果	重新组织查询：添加技术名称、版本／年份限定词，或使用准确的错误消息。参见 Research Methodology > Query Formulation。
需要评估来源可信度	优先选择官方文档、GitHub 仓库和注明版本的来源。有关 5 信号启发法，请参见 Research Methodology > Source Evaluation。
多次重新组织查询后，结果仍然不理想	对无进展情况进行分类（过于冷门、太新、含义模糊），并遵循 Research Dead End Protocol。不要继续使用相同策略搜索。
两种不同的搜索后端都返回不理想的结果	问题出在查询，而不是工具。切换工具前，先使用限定网站、限定版本或引用错误消息的方式重新组织查询。
需要结构化提取，但没有专用后端	使用主机 web_fetch 获取页面内容，然后手动解析。在综合结果中注明此缺口。

可靠性与成本控制

1. 从能回答问题的最简单可用工具开始。 使用主机 web_search 发现信息；使用主机 web_fetch 抓取已知 URL。
2. 如果正在使用专用爬取／抓取后端，在迭代调试期间优先使用 --max-age 命中缓存。
3. 使用爬取后端时，严格限定爬取范围（--limit、--include-paths、--exclude-paths）。
4. 只有在需要结构化输出且相应后端已可用时，才使用架构提取 Agent。
5. 将自主浏览器／Agent 模式作为最后手段，并加入超时回退逻辑。
6. 将主机搜索／抓取结果保存到 .researches/<timestamp>/，以便复现。Firecrawl 目录为可选项。
7. 如果需要的专用能力不可用，请注明此缺口，并使用主机工具完成任务。
8. 启动搜索前先组织好查询。 具体且无歧义的查询比含糊的查询更容易获得良好结果。结果不理想时，应重新组织查询，而不是抓取更多页面。
9. 深入阅读前先评估来源。 优先选择官方文档、GitHub 仓库和近期且注明版本的来源。除非没有更好的来源，否则忽略论坛和 SEO 博客。
10. 连续 2-3 次重新组织查询仍然失败后，就停止搜索。 遵循 Research Dead End Protocol：对失败进行分类，切换策略（限定网站搜索、引用错误消息搜索、限定版本搜索），记录缺口并升级处理，不要推断补全。切勿继续采用无效方法。
11. 切换工具前先重新组织查询。 如果主机搜索返回的结果不理想，使用相同查询切换到另一个搜索后端也不会改善结果。问题出在查询，而不是工具。

脚本清单

脚本	用途	关键标志
scripts/init-research-session.ts	初始化带时间戳的研究会话目录	--query、--metadata
scripts/save-research.ts	将专用后端生成的产物（如使用 Firecrawl，则包括其转储文件）导入会话	--query、--results、--results-dir、--session-dir、--list
scripts/save-web-research.ts	将主机搜索／抓取结果导入会话；抓取／混合模式默认启用内容清理（--no-clean 可禁用）	--query、--source、--results、--content、--url、--clean、--no-clean、--session-dir、--metadata
scripts/clean-web-content.ts	从网页内容中剔除导航栏、Cookie 横幅、页脚、编辑链接、反馈提示、复制按钮、分页、页内目录、返回顶部链接、赞助商版块、社交媒体提示和新闻简报号召性用语	--content、--file、--output、--source、--no-cookie、--no-nav、--no-footer、--no-social、--no-newsletter、--no-edit-links、--no-feedback、--no-related、--no-copy-buttons、--no-pagination、--no-toc、--no-back-to-top、--no-sponsors、--no-whitespace
scripts/clean-web-content.test.ts	内容清理的回归测试：10 项剔除测试 + 8 项误报防护	运行：npx tsx .agents/skills/research-online/scripts/clean-web-content.test.ts1
scripts/consolidate-research.ts	对报告去重并合并至 consolidated.md + consolidated.json。默认启用内容清理；使用 --no-clean 可输出原始内容。通过 --session-dir 或 --auto-session 自动发现所有产物目录	--session-dir、--auto-session、--input-dir、--input-file、--query、--format、--no-clean、--no-dedupe、--no-publish、--output
scripts/finalize-research-session.ts	通过限定范围的提交／推送发布已完成的会话	--session-dir、--latest、--dry-run
scripts/archive-github-repo-docs.ts	归档 GitHub 仓库文档，包括规范 Markdown、HTML 和可选截图	--session-dir、--github-repo、--branch、--repo-dir、--screenshot-mode、--file、--files-from
scripts/research-session.ts	库：会话目录布局构建器和辅助函数	由其他脚本导入

本地语料库布局

references/ 目录包含 6 个手工编写的综合文件。没有子文件夹，也没有随附的上游文档页面。

文件	用途
consolidation-patterns.md	六种合并子 Agent 发现结果的策略，以及去重和验证检查清单
github-repository-doc-archival.md	GitHub 仓库文档的混合归档模式：规范 Markdown、渲染后的 HTML 和可选截图
harness-patterns.md	Harness 工作器模式：主机搜索／抓取并行化（默认）、可选的专用后端模式，以及会话目录参考
query-formulation.md	查询构造速查：改写技巧、特定领域模式、查询结构、反模式和针对不同阶段的指导
source-evaluation.md	来源评估速查：5 项信号启发式方法、领域权威性速查表、带版本限定的查询模式、时效性信号、警示信号和改写指导
tool-selection.md	主机优先的工具决策树；存在 Firecrawl 后端时，提供可选的 Firecrawl CLI 命令模式和成本防护措施

指导一致性

• 按照 AGENTS.md 一致应用仓库指导。
• 如果更新此技能文件，请运行 npm run skills:sync，以便 IDE 立即获取新版本。
• 使用专用后端时，先通过该工具的 --help 验证 CLI 行为，再依赖新发布版本的命令语法。仅在后端已可用时才加载该路径。

临时文件

如果此技能需要创建临时文件，请将其放在 .tmp/research-online/YYYY-MM-DD-{subject} 下。根目录 .tmp/ 已加入 git 忽略。不要创建顶层的点文件临时目录。

Footnotes

1. npx tsx 支持任何标准运行器——bunx tsx、pnpm dlx tsx、deno run -A npm:tsx、node --import tsx 或 yarn dlx tsx。前五种会按需自动获取 tsx；只有 node --import tsx 要求先在本地安装 tsx（npm i -D tsx，或者如果无法访问 npm registry，则运行 npm i -g tsx）。Bun 用户也可以完全跳过 tsx，直接通过 bun <script> 运行 TypeScript。选择项目自带的运行器即可。规范的运行时决策表位于 skills-manager 技能的 Runtime Selection 部分（仅在完整的 gg-skills monorepo 中可用）。 ↩