deep-research

深度研究技能

研究某个主题的最新实践者见解、官方文档和社区讨论，然后创建或更新一份实战指南。

步骤 0：解析参数

用户输入为：$ARGUMENTS

如果没有参数：显示此帮助并停止：

Usage:
  /deep-research swift concurrency
  /deep-research kubernetes cost optimization --file infra-playbook.md
  /deep-research --file existing-playbook.md   (updates all sections)
Playbook is created in your current working directory by default.

解析规则 — 必须按以下顺序执行：

1. 如果 $ARGUMENTS 包含 --file <path>，则提取该路径作为文件路径。其余内容为主题。
2. 否则，如果某个标记以 .md 结尾或包含 /，则将其视为文件路径。其余内容为主题。
3. 否则，将 $ARGUMENTS 的全部内容视为主题。自动生成文件路径：在当前工作目录中使用 <topic-slug>.md（例如，“swift concurrency” → swift-concurrency.md）。

示例：

• /deep-research swift concurrency → 主题：“swift concurrency”，文件：swift-concurrency.md
• /deep-research kubernetes cost optimization --file infra-playbook.md → 主题：“kubernetes cost optimization”，文件：infra-playbook.md
• /deep-research --file docs/playbook.md → 根据现有文件推断主题，文件：docs/playbook.md
• /deep-research docs/react-hooks.md state management → 主题：“state management”，文件：docs/react-hooks.md

步骤 0.5：澄清假设

继续之前，如果符合以下任一情况，请使用 AskUserQuestion：

• 主题含义不明确：主题有多种常见含义（例如，“swift”、“python”、“spring”、“agent”、“mercury”）。询问用户指的是哪一种。
• 主题范围过宽：主题过于宽泛，难以进行深入研究（例如，“machine learning”、“AI safety”）。询问用户关注的方面或受众。
• 缺少会影响结果的背景信息：主题暗示了用户未说明的特定背景（例如，云服务提供商、编程语言、受众水平）。
• 更新模式但未提供主题：如果要根据现有文件推断研究重点，请在启动 Agent 前确认推断出的重点。

如果主题具体明确且没有歧义，则跳过此步骤。

步骤 1：读取或创建实战指南

如果目标文件已存在：

• 读取该文件。检查它是否看起来像一份实战指南（是否包含 Sources 部分或 *Captured:* 日期）。
• 如果是：记录所有章节标题、Sources 列表以及语气和风格。设置 mode = update。
• 如果不是：警告用户：“此文件已存在，但看起来不像实战指南。仍要更新它，还是创建新文件？”

如果目标文件不存在：

• 如果未提供主题，则停止并提示：“新建实战指南需要指定主题。用法：/deep-research <topic>”
• 如果父目录不存在，则创建该目录。
• 设置 mode = create。研究 Agent 将确定文档结构。

告知用户：“正在 <absolute path> 创建实战指南”或“正在更新 <absolute path>”。

步骤 2：确定研究范围

mode = update（已有实战指南）：

根据标题和章节标题确定实战指南的主题。

提供了主题：启动 2-3 个 Agent，在实战指南的主题领域内研究该主题。每个 Agent 必须从不同角度进行搜索：

1. 官方文档和权威来源
2. 社区讨论和实践者博客
3. （可选）社交媒体和近期报告

未提供主题：将现有章节标题归纳为 3-5 个研究主题。每个主题启动一个 Agent，查找自实战指南 *Captured:* 日期以来的更新。

mode = create（新建实战指南）：

主题即研究主题。启动 3-5 个 Agent，每个 Agent 负责不同方面：

1. 核心概念和官方文档
2. 最佳实践和常见模式
3. 注意事项、陷阱和故障排查
4. 工具、库和生态系统
5. （可选）高级技巧和新兴趋势

根据主题调整研究方面 — 并非每个主题都需要涵盖以上五项。

第 3 步：启动研究 Agent

启动前，告诉用户：

Launching [N] research agents in parallel:
  1. [Agent 1 angle]
  2. [Agent 2 angle]
  ...

使用 Agent 工具并行启动 Agent。每个 Agent 都必须使用 subagent_type: general-purpose 和 run_in_background: false。

为每个 Agent 构建提示词——必须包含：

1. 该 Agent 负责的主题和具体角度（例如，“Swift async/await 最佳实践”或“Claude Code opus 4.7 官方文档”）
2. 操作手册中的上下文：
   • mode = update：列出现有章节标题，让 Agent 跳过已有内容
   • mode = create：告知 Agent 这是一本新的操作手册——返回所有发现
3. 搜索说明：告知 Agent 使用 WebSearch，根据主题和话题构建查询。模式：
   • "[subject] [topic] [current year]"（一般网页）
   • 在该主题的权威网站上搜索 "[subject] [topic]"
   • "[subject] [topic] blog [current year]"（从业者博客）
   • 然后使用 WebFetch 从有前景的网址提取详细信息
4. 输出格式：对每项发现，返回：
   • 洞见：具体、可执行的发现（1-2 句话）
   • 来源 URL：直接链接
   • 建议章节：该内容所属章节（更新模式下使用准确名称，创建模式下使用建议名称）
   • 置信度：高（官方文档／多个来源）或中（单篇从业者报告）
5. 规则：仅返回具有真实来源 URL 的发现。绝不要返回没有来源的发现。重点关注从业者的实践经验，而非营销内容。优先提供具体技巧、数字和易错点，而非泛泛建议。

如果 Agent 没有返回结果，放弃前先尝试不带年份限定词的更宽泛搜索词。

第 4 步：整合发现

如果 mode = update（现有操作手册）：

针对每个研究 Agent 的结果：

1. 筛选：删除没有来源 URL 或与现有内容重复的内容
2. 定位：在操作手册中找到每项发现所属的准确章节
3. 编辑：使用 Edit 工具将发现合并到现有章节中
   • 必须与操作手册现有的文风一致——写作前先阅读几段内容，熟悉其风格。语气对比：
     • 不佳：“通常建议考虑实施缓存，以提升性能。”
     • 良好：“积极使用缓存。共享状态用 Redis，热点路径用内存缓存。先进行性能分析。”
   • 格式：[洞见文本]. — [来源名称](URL)（来源前用空格、长破折号、空格）
   • 添加到现有段落、表格或项目符号列表中——绝不要创建新的子章节，除非内容涉及现有章节均未涵盖的主题，且需要超过 3 个项目符号
4. 来源列表：将任何新的来源 URL 添加到文末的 Sources 列表

整合规则：

• 绝不要创建单独的“新发现”或“更新”章节——应将内容合并到现有结构中
• 绝不要添加没有来源 URL 的说法
• 绝不要改变文风——与现有风格保持一致
• 如果某项发现与现有内容矛盾，且置信度为高，则更新现有内容——保留旧来源和新来源，让读者了解内容的演变
• 如果某项发现与现有内容矛盾，但置信度仅为中，则将其作为另一种观点添加，而不是替换原内容
• 始终保留现有内容，除非高置信度来源明确取代了它

如果 mode = create（新建操作手册）：

1. 筛选：删除没有来源 URL 的内容
2. 分组：按主题将发现归类到逻辑清晰的章节中（目标为 5-10 个章节）
3. 撰写：使用 Write 工具创建文件。结构如下：

   # [Title derived from topic]
   
   [Sections — group related insights under clear headings]
   
   ---
   ## Sources
   
   [All source URLs from research]
   
   ---
   *Captured: YYYY-MM-DD*
   

   对于每个章节：
   • 撰写一段简洁的总结，综合各项发现，然后以项目符号列出关键见解
   • 每项陈述都必须有来源：[Insight]. — [Source Name](URL)
   • 语气：直接、简洁、面向实践者——不说空话，不含糊其辞
4. 来源列表：在底部的 Sources 章节中汇总所有来源 URL

如果所有发现都被筛除，请告知用户：“未找到此主题的带来源发现。请尝试更宽泛或更具体的主题。”

第 5 步：验证并报告

完成所有编辑后：

1. 阅读操作手册并验证：

   • 每项新增陈述都有来源 URL
   • 没有重复条目
   • 各章节衔接流畅（新增内容不会显得生硬）
   • Sources 列表包含所有 URL

2. 向用户报告：

   ## Playbook [Created | Updated]
   
   **File**: [absolute file path]
   **Mode**: [create | update]
   **Topic**: [what was researched]
   **Agents launched**: [N]
   
   ### Sections [created | modified]:
   - **Section Name** — [brief description of content]
   - ...
   
   ### Sources: [count]
   ### Findings integrated: [count]
   ### Findings dropped (no source / duplicate): [count]