web-research

网络研究

将一个明确的研究问题交给并行网络搜索子 Agent，产出带引用、标明缺口的研究结果。

交付内容始终保存在磁盘上：一份供调用方审核的书面计划、每个子主题对应的一份研究结果文件，以及一份带编号引用的综合报告。不以行内文字形式返回任何内容，也不能在没有 URL、标题和逐字摘录作为依据时发布任何主张。

适用场景

• 用户要求对某个主题进行网络研究，例如“研究 X”“查找 Y 的资料”“收集 Z 的证据”。
• 其他 beagle 技能以编程方式调用此技能作为研究助手（参见 references/companion-contract.md）。
• 调用方需要可审计的输出：经用户批准的计划、每个子主题对应的研究结果文件，以及有引用依据的综合报告。

不适用场景

• 查询代码库（“这个函数定义在哪里”“搜索仓库”）。应改为搜索代码库。
• 搜索本地文件或提取文档内容。请使用本地文件搜索或 artifact-analysis。
• 对两种实现进行比较评估。请使用 llm-judge。
• 抓取付费墙或需要身份验证的内容。不在适用范围内——请让调用方粘贴提取出的内容。
• 改写或辅导研究问题。那是调用方的职责；此技能将收到的问题视为最终问题。

工作流

按顺序执行以下四个步骤，不得跳过任何步骤。

1. 编写 plan.md——逐字写入主要问题、1–5 个互不重叠的子主题、每个子主题需要证实的内容，以及如何综合研究结果。
2. 计划审核关卡——将计划展示给用户确认。仅当调用方传入 auto_proceed: true 时才跳过。
3. 分派子 Agent 并综合结果——最多启动 3 个并行子 Agent（每个子主题一个），等待全部返回，然后编写 report.md。
4. 返回前验证——运行 references/failure-modes.md 中的验证清单，确认所有预期产物均存在且格式正确。任何未通过的检查都应记入“缺口与限制”。

硬性关卡（客观通过条件）

只有前一关通过后才能继续。通过状态必须由磁盘上的文件、调用方标志或结构化错误证明，而不是内部的“我检查过了”。

关卡	阻止的操作	通过条件
G0 — 工具	Slug 派生、output_dir、任何写入操作	网络搜索（若可联网）可用。未通过时：按 references/failure-modes.md 中的“缺少网络工具时快速失败”输出 JSON；不要创建 plan.md 或任何其他产物。
G1 — 重新运行	首次写入 output_dir	output_dir 中没有 plan.md 或 report.md，或者设置了 refresh: true，且此前内容已按 references/failure-modes.md 中的“重新运行保护”归档。
G2 — 计划产物	分派子 Agent	plan.md 存在，并包含“研究计划（plan.md）”下的所有必需条目。
G3 — 审核	分派	用户已确认计划，或设置了 auto_proceed: true。
G4 — 研究结果集	综合结果	对于 plan.md 中的每个子主题，findings/<slug>.md 均存在，且包含 status: frontmatter（允许使用占位文件）。
G5 — 交付物	向调用方返回成功	report.md 存在；并且满足 references/failure-modes.md 中的运行结束检查清单（“验证清单”），或将每项未通过的检查记录在“缺口与限制”下。

Receive question ──→ Write plan.md ──→ Review gate (unless auto_proceed)
                                      ↓
                                    User confirms
                                      ↓
                                    Dispatch subagents (up to 3 parallel)
                                      ↓
                                    Collect findings/<slug>.md files
                                      ↓
                                    Synthesize report.md
                                      ↓
                                    Return paths to caller

在步骤 1 之前，先确认环境具备网络搜索功能（若可联网）。对于需要获取完整页面内容、而非仅使用搜索摘要的子 Agent，页面抓取功能很有帮助，但并非必需——仅支持搜索的环境仍可产出有价值的研究结果。如果没有网络搜索功能，请按 references/failure-modes.md 的要求快速失败——不要创建 plan.md，也不要启动子 Agent。

输入

输入契约简洁且严格：

字段	类型	必填	默认值	用途
research_question	string	是	—	要回答的问题，已提炼完成。此技能不会重新组织问题。
output_dir	绝对路径	否	派生	plan.md、findings/ 和 report.md 的存放位置。
auto_proceed	bool	否	false	为 true 时，跳过计划审查关卡并立即分派。
refresh	bool	否	false	为 true 时，允许覆盖同一 output_dir 中先前运行的内容。

此技能不会解析调用方特有的结构。调用方在调用前，需将其简报提炼为一个明确的问题字符串。

何时传入 auto_proceed: true，何时传入 false。 当用户仍会受益于在搜索消耗资源前查看子主题计划时，传入 false（默认值）——例如，调用方希望此技能的计划审查关卡发挥检查作用。当调用方已通过与用户的交互解决了“这个问题的框架是否正确”这一问题，而再增加一道关卡只会造成阻碍时，传入 true——例如，用户在对话中途明确要求进行背景研究，或调用方已在上游运行自己的审查循环。关键在于审查发生在哪里，而不是审查是否发生。

输出位置

如果调用方提供了 output_dir，则原样使用。否则，按以下规则派生默认值：

.beagle/research/<YYYY-MM-DD>-<topic-kebab>/

Slug 派生规则（保持稳定，以便同一天重新运行相同问题时落在同一文件夹中）：

1. 获取研究问题。
2. 转为小写。
3. 去除标点（保留字母、数字、空格和连字符）。
4. 将连续空白字符合并为单个连字符。
5. 在单词边界处截断为 60 个字符（在 60 个字符之前的最后一个连字符处截断）。如果第 60 个字符之前没有连字符，则直接在第 60 个字符处截断。
6. 添加前缀 YYYY-MM-DD-。

重新运行保护。 写入任何内容之前，检查 output_dir 中是否已有 plan.md 或 report.md。如果有，且 refresh 不为 true，则拒绝操作，并在提示中指出现有文件夹。当 refresh: true 时，先将之前的内容归档到 <output_dir>/.archive-<timestamp>/，然后重新开始。请参阅 references/failure-modes.md 和 references/companion-contract.md。

每次运行都会存放在独立文件夹中，以便调用方在几周后无需重新运行此技能，也能重新查看计划、研究结果和报告。

研究计划（plan.md）

计划须在任何子 Agent 运行前编写，让调用方有机会在搜索消耗资源前发现问题框架不当。

plan.md 包含：

• 研究问题——输入字符串，原样保留。
• 子主题——1 到 5 个，彼此不重叠，每个子主题都有一个单行名称。
• 每个子主题应确定的内容——具体要点，而非“研究 X 的所有内容”。
• 综合方法——说明如何将各子主题的研究结果整合到 report.md 中。
• 预算——将启动多少个子 Agent，以及每个子 Agent 可进行多少次搜索（请参阅下文的默认预算）。

计划审查关卡。 默认情况下，向用户展示 plan.md，并等待确认后再进行分派。用户可以修改、添加或删除子主题，也可以完全否定当前的问题框架。当调用方传入 auto_proceed: true 时，跳过该关卡并立即分派——这是调用方拥有自身审查循环时使用的程序化配套流程。

子 Agent 调度

最多并发运行 3 个子 Agent。每个子 Agent 都会收到一份根据 plan.md 机械生成的任务简报，确保用户批准的计划与子 Agent 收到的简报之间不会出现理解偏差。简报模板位于 references/subagent-brief.md。

每个子 Agent 都会：

• 执行分配的网络搜索预算（默认 3-5 次）。
• 在 output_dir 下写入 findings/<subtopic-slug>.md。
• 向协调器返回一行简短状态（路径 + 状态），绝不直接内联研究结果。

协调器会等待所有子 Agent 完成，然后确认每个预期的研究结果文件都存在，再进入综合阶段。缺少文件属于静默失败，需记录在“差距与局限”中，参见 references/failure-modes.md。

完整的简报格式以及每个研究结果文件必需的 frontmatter，参见 references/subagent-brief.md。

引用

研究结果文件和 report.md 中的每项结论都必须附带引用。格式详见 references/citation-schema.md。概括如下：

• 必填字段： url、title、excerpt（页面原文摘录）。
• 可选字段： retrieved_at（ISO 日期）、source_type（official-docs / vendor / blog / forum / news / other）。
• 绝不编造缺失的元数据。 如果子 Agent 没有检索日期，则省略该字段，不要伪造日期。

行内引用使用 [^n] 脚注；完整引用列在报告底部编号为 Sources 的部分中。

综合（report.md）

报告采用固定的四部分布局，顺序如下。每次都必须包含所有部分。

1. ## TL;DR — 用 3-5 个项目符号概括最重要的研究发现。
2. ## Findings — 按子主题或主题组织；每项结论都必须附带 [^n] 脚注。
3. ## Gaps & Limitations — 说明研究无法确认的内容，包括任何失败的子 Agent。
4. ## Sources — 与脚注编号对应的编号参考文献。

即使研究结果看起来完整，也必须包含 Gaps & Limitations。如实说明哪些内容可以验证、哪些无法验证，是产品的一部分。该技能复制的完整字面模板位于 references/report-template.md。

失败模式

• 部分成功 — 一个或多个子 Agent 失败。该技能会使用成功部分的结果继续，并在 Gaps & Limitations 中逐一列出失败的子主题，包括最后已知的任务简报和占位文件中的失败原因。整个运行不会中止。
• 快速失败 — 网络搜索不可用（如果可访问网络）。在进行任何磁盘写入（包括 plan.md）之前中止；按照 references/failure-modes.md 返回结构化 JSON。页面抓取对各子 Agent 来说是可选项，不属于此检查门槛。
• 静默失败检测 — 每个子 Agent 在返回前至少要写入占位文件 findings/<slug>.md，并在 frontmatter 中包含 status:（ok、empty、failed）。调度后文件缺失即为静默失败，需记录在 Gaps & Limitations 中。
• 重运行保护 — 见上文“输出位置”；详情参见 references/failure-modes.md。

完整规则和结构化错误格式位于 references/failure-modes.md。

默认预算

可调参数，并非硬编码的不变量：

参数	默认值
每次运行的子主题数	1-5
并行子 Agent 数	最多 3 个
每个子 Agent 的网络搜索次数	3-5

如需扩大或缩小范围，调用方可以通过任务简报进行覆盖。计划审查关卡是调整范围的合适时机，可避免浪费搜索资源。

配套调用约定

其他 beagle 技能通过一份简短、已记录的约定调用此技能。最简调用只传入 research_question；完整调用还会添加 output_dir、auto_proceed 和 refresh。

三个已知调用方（prfaq-beagle、brainstorm-beagle、strategy-interview）的完整示例，以及成功和快速失败时的返回格式，都位于 references/companion-contract.md。调用方应原样遵循此约定，而不是另行发明调用方式。

语气

此技能是一个语气中立的基础工具。它不会：

• 指导调用方判断问题是否恰当。
• 重塑、完善或质疑研究问题。
• 采取某种态度（强硬、苏格拉底式、温和）——这是调用方的职责。
• 在研究发现或报告中加入主观评论。

如果调用方是辅导型技能（prfaq-beagle、brainstorm-beagle），辅导会在此技能运行前后进行。在此技能内部，问题会被视为最终定稿。

不在范围内

• 长时间运行或定期执行的研究任务。
• 使用大模型作为评判者评估来源可信度——llm-judge 已涵盖比较评估。
• 抓取付费墙或需要身份验证才能访问的来源。
• 辅导、质疑或带有主观倾向地重塑研究问题。
• 多语言研究。
• 缓存或跨调用去重研究发现。
• 非 Web 研究模式（本地文件、项目文档、数据库）——请使用 artifact-analysis。

参考文件

• references/subagent-brief.md — 调度每个子 Agent 时，编排器根据 plan.md 机械填充的模板。
• references/citation-schema.md — 必填和选填的引用字段、脚注约定，以及格式正确的示例。
• references/report-template.md — 包含全部四个固定章节的 report.md 原样框架。
• references/failure-modes.md — 部分成功、快速失败、静默失败检测和重新运行保护规则。
• references/companion-contract.md — 程序化调用格式，以及针对 prfaq-beagle、brainstorm-beagle 和 strategy-interview 的完整示例。