Medusa Claude Code 子代理体系：web-search-researcher 网络研究代理的设计与研究工作流全解析

本文以 Medusa 开源仓库中 .claude/agents/web-search-researcher.md 这份 Claude Code 子代理（subagent）定义文件为主体，完整拆解一个"网络研究专家型子代理"的设计骨架：从 YAML frontmatter 的工具与模型声明、四阶段研究职责，到面向 API 文档、最佳实践、技术难题、方案对比四类场景的检索策略，以及结构化的输出模板与质量准则。读完本文，你将掌握在大型 TypeScript monorepo（如 Medusa 这类 30+ 模块的 commerce 平台）中，如何借助 Claude Code 的子代理机制把"查外部资料"这一环节从主对话中剥离出去，形成可复用、可验证、带来源引用的研究流水线。

一、文档定位：一个子代理定义文件在仓库中的角色

web-search-researcher.md 位于仓库的 .claude/agents/ 目录，与 codebase-locator.md、codebase-analyzer.md、codebase-pattern-finder.md 并列。该目录下的 Agent Selection Guide 将这四个代理按"回答什么问题"划界：

代理	关注点	可用工具	使用时机
codebase-locator	WHERE（代码在哪）	Grep, Glob, LS	定位文件与目录
codebase-analyzer	HOW（如何实现）	Read, Grep, Glob, LS	理解技术细节与调用链
codebase-pattern-finder	EXAMPLES（范式示例）	Grep, Glob, Read, LS	寻找可参照的实现模板
web-search-researcher	EXTERNAL（外部研究）	WebSearch, WebFetch	获取代码库之外的信息

web-search-researcher 是唯一面向"代码库外部信息"的代理，其职责边界在 README 中被明确为：调研库/框架/工具、查找第三方包文档、理解行业标准或最佳实践、获取代码库中不存在的知识；典型查询例如"最新的 Stripe API 支付方式有哪些""TypeScript 依赖注入的最佳实践""OAuth 2.0 PKCE 流程如何实现"，产出则是"带来源引用的综合研究结果"。

这一划界体现了 Claude Code 子代理设计的核心思想：用工具白名单约束能力边界，用 description 字段承担路由决策。后文会看到，web-search-researcher 被授予的是 WebSearch 与 WebFetch 两个联网工具，而不是文件读写工具。

二、Frontmatter：子代理的身份声明与工具约束

定义文件前 7 行是标准的 Claude Code 子代理 frontmatter（web-search-researcher.md）：

---
name: web-search-researcher
description: Do you find yourself desiring information that you don't quite feel well-trained (confident) on? Information that is modern and potentially only discoverable on the web? Use the web-search-researcher subagent today...
tools: WebSearch, WebFetch, TodoWrite, Read, Grep, Glob, LS
color: yellow
model: sonnet
---

逐字段解读（以当前仓库文件实际内容为准）：

• name：子代理的唯一标识符，主代理派发任务时以此名称调用（/research 命令文档中即以 web-search-researcher 之名引用它，见 research.md）。
• description：这是主代理（或用户）决定"何时启用该子代理"的路由依据。Medusa 团队刻意把这段描述写得极具触发感——"当你发现自己想要掌握但自信不足的、可能只有网络上才找得到的现代信息时，使用 web-search-researcher"，甚至用"不满意可以重新换个 prompt 再跑一次"的玩笑口吻降低使用门槛。从源码结构看，description 的措辞质量直接决定了主对话在什么时机把任务委派出去。
• tools：工具白名单为 WebSearch, WebFetch, TodoWrite, Read, Grep, Glob, LS。这里有一个值得注意的细节——它并非"纯联网代理"，而是同时保留了 Read、Grep、Glob 等本地只读工具。这意味着该子代理既能联网检索，也能在需要时回到代码库做交叉验证（例如把网络查到的 API 行为与仓库内的实际调用比对），这与它"研究综合者"的定位一致。
• color: yellow：Claude Code 中用于标识该子代理输出的显示颜色。
• model: sonnet：指定子代理运行的模型档位。值得注意的是，同为 Medusa 仓库的 codebase-locator.md 同样声明 model: sonnet，而 research.md 编排整个研究流程的主命令则使用 model: opus。从源码结构看，这体现了一种"编排者用强模型、执行者用快模型"的成本/能力分层策略。

三、核心职责：四阶段研究流水线

文件的主体部分（L11-L37）定义了子代理接到研究查询后的标准工作流，共四个阶段。这四个阶段构成一个"分解 → 检索 → 取证 → 综合"的完整闭环，值得逐段拆解。

3.1 阶段一：分析查询（Analyze the Query）

子代理首先要拆解用户请求，识别三件事：

1. 关键搜索词与概念——把自然语言问题转成可检索的术语；
2. 可能持有答案的源类型——文档、博客、论坛、学术论文各有其信息特征；
3. 多个搜索切入角度——确保覆盖面的多样性，避免单一角度漏检。

这一步的本质是把"研究问题"降维成一组"检索任务"，为后面的策略化搜索做准备。

3.2 阶段二：执行策略化搜索（Execute Strategic Searches）

这是定义文件中检索方法论的核心，包含四条战术规则：

• 先广后精：先做宽泛搜索建立领域版图（understand the landscape），再用具体的技术术语和短语收窄；
• 多变体搜索：对同一问题使用多种搜索措辞，捕获不同立场与视角的信息；
• 站点定向搜索：当已知权威来源时，使用 site: 算子精确锁定。文档给出的原始示例是 "site:docs.stripe.com webhook signature"——在 Medusa 语境下非常贴切，因为 Medusa 生态本身就依赖 Stripe 支付（仓库内置 payment-stripe 提供方），研究支付相关外部资料时锁定官方文档域正是这一条策略的直接应用。

3.3 阶段三：抓取并分析内容（Fetch and Analyze Content）

搜索只是入口，WebFetch 用于从有前景的结果中获取全文，且要求遵循三条取证纪律：

• 来源优先级：官方文档 > 可信技术博客 > 其他权威来源；
• 精确摘录：提取与查询直接相关的具体引文（quotes）和段落，而非泛泛概括；
• 时效标注：记录发布日期，确保信息仍然有效（对 API 文档类信息尤其关键——Web 资料会随版本迭代失效）。

3.4 阶段四：综合发现（Synthesize Findings）

最后一步决定研究输出的可用性，要求做到五点：按相关性与权威性组织信息；为每条信息附上精确引文与出处归属；提供指向来源的直接链接；显式高亮相互矛盾的信息或版本相关差异；并记录现有信息的空白点（gaps）。后两条是这份定义区别于"简单摘要型搜索"的关键：它要求子代理不仅输出"找到了什么"，还要输出"哪里没找到、哪里有分歧"，让主代理和用户对信息边界保持清醒。

四、分场景搜索策略：四类问题的检索套路

定义文件第 39-66 行（Search Strategies 一节）按问题类型给出了四套可照抄的检索套路。这套"按场景分桶"的策略库是全文最有实战价值的部分之一：

4.1 查 API / 库文档

• 先搜官方文档，句式模板："[库名] official documentation [具体功能]"；
• 查 changelog 或 release notes 获取版本特定信息；
• 从官方仓库或可信教程中找代码示例。

4.2 查最佳实践

• 搜索时带上年份（relevant 场景下），确保内容足够新；
• 优先采信公认专家或权威组织发布的内容；
• 多来源交叉比对以识别行业共识；
• 同时搜索 "best practices" 和 "anti-patterns" 两个词，正反两面才能看到完整图景——这一条在研究架构模式时特别有效。

4.3 查技术解决方案

• 把具体报错信息或技术术语加引号精确检索；
• 搜 Stack Overflow 与技术论坛获取实战解法；
• 查相关仓库的 GitHub issues 和 discussions——bug 现场与社区讨论往往比文档更接近真实问题；
• 寻找描述类似实现的 blog post。

4.4 查方案对比

• 搜 "X vs Y" 对比文章；
• 找技术间的迁移指南（migration guides）；
• 找基准测试与性能对比数据；
• 搜索决策矩阵（decision matrices）或评估标准。

这四套策略的共同点是全部给出了可直接复用的搜索句式，而非抽象原则，使得子代理的行为高度可预测、可复现。

五、输出格式：结构化的研究报告模板

定义文件第 70-94 行规定了子代理必须遵守的输出骨架（Output Format 一节）：

## Summary
[关键发现的简要概述]

## Detailed Findings

### [主题/来源 1]
**Source**: [名称 + 链接]
**Relevance**: [该来源为何权威/有用]
**Key Information**:
- 直接引文或发现（尽可能链接到具体小节）
- 其他相关要点

### [主题/来源 2]
[延续上述模式...]

## Additional Resources
- [相关链接 1] - 简述
- [相关链接 2] - 简述

## Gaps or Limitations
[记录未能找到或需进一步调查的信息]

这个模板有三个值得借鉴的设计：

1. 逐来源三段式（Source / Relevance / Key Information）：每条发现必须自带"出处 + 为什么可信 + 具体信息"三要素，杜绝无出处的断言；
2. Summary 前置、Gaps 收尾：头部给结论，尾部给边界，读者可以先 30 秒判断价值，再看细节，最后知道信息盲区；
3. Additional Resources 单独成节：把"没采纳但可能有用的来源"也保留下来，为后续深挖留接口。

这一子代理级模板并非孤立存在——它的上层编排命令 research.md 在综合所有子代理结果后，会以同样的 Summary / Detailed Findings / Code References / Open Questions 骨架生成一份带 YAML frontmatter（date、git_commit、branch、topic、tags、status 等字段）的研究文档，落盘到 thoughts/shared/research/YYYY-MM-DD-<主题>.md。仓库中已存在真实产物 2026-01-05-claude-md-research.md，其 frontmatter 完整包含 git_commit、branch、repository 等溯源字段，验证了这套"子代理输出 → 主代理综合 → 带版本溯源的研究文档"的流水线在 Medusa 团队日常工作中真实运转。

六、质量准则与检索效率：让研究"准、新、省"

6.1 六条质量准则（Quality Guidelines）

文件第 96-103 行列出了输出质量的六条硬性准则（Quality Guidelines）：

• Accuracy（准确）：引用必须忠实于原文，且必须附直接链接；
• Relevance（相关）：只聚焦直接回应用户查询的信息，拒绝跑题；
• Currency（时效）：涉及版本敏感内容时，必须标注发布日期与版本信息；
• Authority（权威）：官方来源、公认专家、同行评审内容优先；
• Completeness（完整）：多角度搜索确保覆盖；
• Transparency（透明）：信息过时、冲突或不确定的地方必须明说。

其中 Accuracy 与 Transparency 两条与第五节的输出模板首尾呼应：模板保证结构，准则保证内容，二者共同构成"可审计的研究输出"。

6.2 检索效率规则（Search Efficiency）

第 105-111 行给出了一组反"过度检索"的节流阀（Search Efficiency）：

• 先搜后抓：先做 2-3 次精心设计的搜索，再决定抓哪些页面；
• 抓取配额：初始只抓最有希望的 3-5 个页面；
• 失败重试：初始结果不足时，改写检索词再试，而不是无脑翻页；
• 搜索算子清单：引号做精确短语、- 做排除、site: 锁定域名；
• 形式多样化：在教程、文档、Q&A 站、讨论区等不同内容形态中分别搜索。

这套"2-3 次搜索 + 3-5 次抓取"的配额制，本质是在子代理的上下文窗口与任务耗时之间做工程化取舍——研究类子代理最常见的失败模式不是"搜得不够深"，而是"抓得太多、综合太少"。

七、在 Medusa 工作流中的实际挂载点

web-search-researcher 并非悬空的定义文件，它在 Medusa 仓库的 Claude Code 工作流中有两个明确的挂载点。

7.1 /research 命令：按需外呼的编排者

.claude/commands/research.md 定义了 Medusa 的代码库研究命令。其编排逻辑（L45-L70）是：主代理先把研究问题拆解为可并行的子任务，然后按性质派发——

• 代码定位类 → codebase-locator；
• 实现原理类 → codebase-analyzer；
• 模式示例类 → codebase-pattern-finder；
• 外部资料类 → web-search-researcher，且仅当用户明确要求时启用。

命令文档中还有一条针对性指令：若使用了 web 研究子代理，必须要求其随结果一起返回链接，并把链接保留进最终报告。这与 web-search-researcher 自身定义中"提供指向来源的直接链接""高亮矛盾信息"的要求完全对齐——子代理的输出契约被上层编排再次加固，避免引用在综合环节丢失。

另一个值得注意的边界是：research.md 反复强调所有子代理是 "documentarians, not critics"（记录者而非批评者），只描述现状、不做建议。web-search-researcher 的 "Gaps or Limitations" 输出恰好承接了这一约束：它报告"哪些信息缺失"，但把"该如何取舍"的决策权交还给主代理。

7.2 全局约束：只读、客观、精确

Agent Selection Guide 的 Constraints 一节 对全部四个代理统一施加了五条约束：

• Read-only：不修改任何代码；
• Objective：不做推荐、不做批判；
• Focused：留在各自领域内；
• Accurate：给出精确的 file:line 引用；
• Complete：整文件读取，不做部分读取。

这五条约束解释了为什么 web-search-researcher 的 tools 白名单里没有任何写文件工具：即使它被允许 Read/Grep，全局约定也把它钉死在"只读研究者"的角色上。README 最后给出的组合拳建议——先 locator 找位置、再 analyzer 析原理、pattern-finder 找范式、web-search-researcher 补外部信息、必要时多代理并行——实际上就是 Medusa 团队使用这套子代理体系的标准操作手册。

八、可复用的设计要点

把 web-search-researcher.md 从 Medusa 仓库的语境中抽象出来，可以提炼出一套编写"研究型子代理"的通用要点，这套要点同样适用于任何希望让 Agent 做外部调研的项目：

1. frontmatter 即契约：description 负责"何时被调用"的路由，tools 白名单负责能力边界，model 档位负责成本分层——三者共同定义了子代理在整个多代理系统中的生态位；
2. 流程分阶段：把"分解查询 → 策略搜索 → 抓取取证 → 综合输出"显式写成编号步骤，子代理的行为就可预测；
3. 策略按场景分桶：与其给一条万能搜索建议，不如像本文第四节那样，为每类常见问题给一套带句式模板的检索套路；
4. 输出模板强制三段式溯源：Source / Relevance / Key Information + Gaps 收尾，让每条结论可审计、让每个盲区可见；
5. 效率配额写进定义：2-3 次搜索起步、3-5 页抓取上限，用硬约束防止上下文被搜索结果淹没；
6. 与上层编排双向加固：子代理定义内部要求附链接，上层命令（如 /research）再次要求链接必须进入最终报告，输出契约在两层间闭环。

回到 Medusa 本身：这套定义文件与 README 选型指南、/research 编排命令、以及 thoughts/shared/research/ 下的研究产物共同构成了一个完整的多代理研究系统——web-search-researcher 在其中承担"把代码库之外的世界翻译成带引用证据"这一单一职责，而单职责、带工具约束、带输出模板的分工，正是多代理协作保持可靠的关键。