deep-research

深度研究

生成 Gemini Deep Research 级别的成果：包含嵌入式截图、mermaid 图表、对比表格和综合分析的丰富内容。专为开发者决策优化，涵盖框架选择、架构模式、依赖项评估和竞争分析。

何时使用此技能

• “研究 X 的现状”
• “比较框架 A 和框架 B”
• “……有哪些最佳实践？”
• “深入探究……”
• 任何需要综合多个来源的信息才能回答的请求

不要用于：快速查询事实、基于单一来源的回答，或“帮我找一个 CSS 按钮”（请改用 design-lookup）。

输入流程——搜索前

1. 分解主题，划分为 3～5 个研究方向。
   • 示例：“比较 Next.js 和 Remix”→ 性能、开发体验、生态系统、部署、社区
2. 明确决策背景——用户实际需要做出什么决定？
   • 选择框架？架构模式？自建还是购买？迁移风险？
3. 起草研究计划——向用户展示 3～5 个方向及计划使用的查询词。
   • 将其保存为成果文件（例如 research_plan.md）。
   • 获得批准后继续；如果用户调整范围，则进行相应优化。

阶段 1：广度扫描

目标：勾勒全貌。在阅读任何内容之前，先找出有哪些资料。

1. 围绕不同方向并行执行 5～8 次搜索。至少使用两种工具：
   • search（Firecrawl）——宽泛的主题查询
   • search_web（Google）——从另一角度搜索
   • 使用特定 scrapeOptions 的 search——定向发现
2. 开发者专项广度搜索：
   • 使用 search_code 或 search_repositories 查找相关的 GitHub 仓库
   • 评估软件包时，搜索 npm 趋势、包体积和下载量
   • 搜索迁移经验：“从 X 迁移到 Y”的实践报告
3. 收集 15～25 个候选 URL，而不是 5 个。根据权威性分级对每个来源评分（参见 references/research-heuristics.md）。
4. **不要只看摘要。**摘要仅用于筛选候选来源。

输出：附带分级评分的候选来源列表。如果需要交互，则展示给用户；如果是自主执行，则继续。

阶段 2：深入阅读

目标：提取实际内容——实现细节、代码示例、基准测试和数据。

1. 从阶段 1 中选择排名靠前的 8～12 个来源（优先选择 S 级和 A 级）。
2. 完整提取——获取完整页面内容：
   • 对于文本较多的页面，使用 scrape（Firecrawl）或 read_url_content
   • 使用 crawl（Firecrawl）遍历多页文档结构
   • 使用 browser_subagent 对关键页面截图（界面、仪表盘、架构图）
   • 使用 get_file_contents（GitHub MCP）读取仓库中的实际源代码
3. 分析每个来源：
   • 提取具体论点、数字、模式和代码示例
   • 记录权威性等级及潜在偏见（这是否是该框架自己的营销内容？）
   • 按研究方向标记发现
4. 自我纠正：如果来源内容空泛（只有营销内容、浅层教程、SEO 填充内容）：
   • 弃用该来源
   • 使用更具体的词语进行后续搜索
   • 尝试添加：“benchmark”“technical deep dive”“lessons learned”“postmortem”

输出：按研究方向整理的来源注释。

第 3 阶段：综合整理

目标：构建研究简报成果。这是主要交付物。

1. 从 references/report-templates.md 中选择报告模板：
   • 综合简报 — 用于行业全景／技术现状研究
   • 比较简报 — 用于正面对比评估
2. 将报告写成内容丰富的 Markdown 成果：
   • 执行摘要使用叙述性文字，不要用项目符号或列表。写得像是在向技术负责人汇报。
   • 对比表格应包含从来源中提取的真实数据
   • 使用 Mermaid 图表呈现架构、决策树和生态系统图
   • 嵌入在第 2 阶段通过 browser_subagent 捕获的屏幕截图
   • 引用实际代码库或文档中的代码示例
   • 如果没有屏幕截图能呈现相关概念，请使用 generate_image 创建自定义可视化图
3. 为每项论述添加引用——在文中链接到来源 URL。格式为：[Source Name](URL)。
4. 差距分析——明确指出：
   • 哪些内容无法确定，以及原因
   • 来源之间存在的矛盾信息
   • 仅找到低等级来源的领域

输出：研究成果（例如，research_report.md）。

第 4 阶段：迭代

目标：填补第 3 阶段发现的差距。

1. 查看报告中的差距分析部分。
2. 对每个可填补的差距：
   • 使用优化后的查询词进行 1 至 2 次定向搜索
   • 提取并阅读搜索结果
   • 直接更新报告成果
3. 最多进行 3 轮迭代（第 1 至第 3 阶段计为第 1 轮，之后最多再进行 2 轮定向搜索）。
4. 最后一轮迭代后，将剩余差距标记为“未解决”，并说明原因。

Agentic 工作流与 Vibe Coding

• 迭代式综合整理： 不要指望初稿就能成为完美、全面的报告。先撰写初步综合内容，检查提取的数据和格式，找出具体差距或有问题的图表，一次完善一个部分，并反复生成，直至成果达到简报标准。
• Vibe Coding： 启动后续深度阅读循环前，先在本地提交正在编写的 Markdown 报告以及任何本地屏幕截图／资源，确保搜索偏离方向时仍能保留结构基础。

工具策略

用途	首选	备用
主题探索	search（Firecrawl）	search_web
委派深度研究	search + scrape	手动进行多轮搜索
完整页面提取	scrape（Firecrawl）	read_url_content
多页面文档	crawl（Firecrawl）	search + 手动处理
视觉证据	browser_subagent（屏幕截图）	generate_image
GitHub 分析	search_code、get_file_contents	在原始 GitHub 页面使用 read_url_content
架构图	Markdown 中的 Mermaid	generate_image
数据可视化	Markdown 表格	使用 generate_image 生成图表

质量门槛

交付报告前，请确认：

• 来源多样性 — 引用了至少 1 个 S 级和 2 个 A 级来源（若无法获取，请明确说明）
• 视觉丰富度 — 至少嵌入 1 张屏幕截图／图片，以及 1 个图表／表格
• 叙述质量 — 执行摘要为叙述性文字，而非项目符号
• 引用完整性 — 每项事实性论述均附有来源链接
• 差距透明度 — 明确记录差距和冲突
• 输出可执行性 — 包含建议部分，并提供具体、分优先级的建议

反模式

• 仅凭片段开展研究——搜索结果中仅查看简介，未进行完整提取
• 通篇文字的报告——没有可视化内容、表格或图表。丰富的呈现才是重点。
• 按来源逐一组织内容——研究发现必须按研究维度进行主题归类，而不是按 URL 排列
• 依赖单一工具——至少使用 2 种不同的搜索／提取工具，确保来源多样
• 未标注引用的说法——每项实质性发现都必须链接到其来源
• 照搬营销说法——未经独立验证便重复框架自身的营销宣传
• 过早停止——当主题需要 15 个以上来源时，仅查阅 3～5 个来源便提交结果

Agentic OS 集成

如果当前项目根目录中包含 .agent/ 目录，此技能 MUST 参与 Agentic OS 共享记忆模型。

执行结束时，检查 .agent/state/last-run.json。如果该文件存在，请按照其规定的架构追加或更新记录，记下本次运行信息。确保记录运行时环境（agent_runtime）、skill_executed、简要的 summary、decisions 和 next_steps。

参考资料

• 来源权威性评分与查询模式：references/research-heuristics.md
• 报告结构模板：references/report-templates.md