deep-research

深度研究技能

用途

此技能通过 OpenAI Responses API 和网页搜索（默认模型为 gpt-5.6-sol，可使用 --model 或 DEEP_RESEARCH_MODEL 覆盖）对任何主题开展全面的联网研究。o3-deep-research 和 o4-mini-deep-research 计划于 2026-07-23 停止服务，且已不再是默认模型。此技能会通过交互式澄清问题智能优化用户的研究提示词，确保保存研究参数以便复现，并利用完整的网页搜索功能开展深度研究。

何时使用此技能

在以下情况下触发此技能：

• 用户要求研究特定主题
• 用户要求分析、调查或全面收集信息
• 用户希望通过网页搜索和推理来探索某个主题
• 用户提供了可以进一步完善的简短研究查询
• 用户想了解某个领域的现状、趋势或比较

用户请求示例：

• “研究性能基准表现出色的最佳开源 RAG 解决方案”
• “2025 年有哪些最新的 AI 发展？”
• “我需要对分布式数据库系统进行全面分析”
• “查找实现向量搜索的最佳实践”
• “调查 AI 如何影响软件工程行业”

工作流概览

User Input
    ↓
Assessment: Prompt too brief?
    ↓
YES → Ask Enhancement Questions → Collect Answers
    ↓                               ↓
    └───────→ Construct Enhanced Prompt ←──┘
                    ↓
            Save to Timestamped File
                    ↓
            Execute deep_research.py
                    ↓
            Output Report + Sources
                    ↓
            Present to User

Claude 应如何使用此技能

关于 Token 效率的重要说明： 深度研究需要 10–20 分钟甚至更久。运行器会使用后台模式，每隔 15 秒静默轮询；命令会一直阻塞，直到运行结束，因此 Claude 无需检查状态。Claude 应：

1. 开始研究
2. 等待研究完成（子进程会自动阻塞）
3. 完成后呈现最终结果

执行期间无需定期轮询或更新状态。

步骤 1：接受研究请求

接收用户的研究提示词。内容可以很简短（“最新 AI 趋势”），也可以非常详细（“重点关注 2024–2025 年语言模型对开发者生产力的影响”）。

步骤 2：执行编排脚本

使用用户的研究提示词运行此技能的主编排脚本：

python3 scripts/run_deep_research.py "Your research prompt here"

该脚本位于此技能安装目录中的 scripts/run_deep_research.py。

步骤 3：脚本执行流程

脚本会自动：

1. 评估提示词是否完整：检查提示词是否过于简短或笼统（少于 15 个词，或以 “what is”“how to” 等开头）

2. 提出澄清问题（如有需要）：

   • 提出 2–3 个与研究类型相关的重点问题
   • 根据关键词判断研究属于技术类还是通用类
   • 允许用户从预设选项（1–4）中选择，或提供自定义文本
   • 问题涵盖：范围/时间段、深度级别、重点领域

3. 优化提示词：将原始提示词与用户的回答整合为结构化的研究参数

4. 保存提示词文件：将优化后的提示词写入 research_prompt_YYYYMMDD_HHMMSS.txt，以便复现

5. 执行深度研究：运行核心脚本 deep_research.py，参数如下：

   • 模型：gpt-5.6-sol，推理强度为 high（可通过 --model、--reasoning 或环境变量 DEEP_RESEARCH_MODEL 配置）
   • 最长等待时间：3600 秒 / 60 分钟（可通过 --timeout 配置）
   • 工具：默认启用网页搜索

步骤 4：向用户呈现结果

脚本会自动：

• 先保存原始 JSON：research_response_YYYYMMDD_HHMMSS.json 保存精确的 API 响应字节（引用片段、网页搜索步骤日志）。任务创建后会立即写入，并在每次轮询时再次写入，确保已付费获取的内容不会丢失。
• 保存请求：research_request_…json（模型、工具、提示词；绝不包含密钥）
• 保存 Markdown 文件：research_report_YYYYMMDD_HHMMSS.md，并在页脚注明模型、响应 ID 和原始响应文件
• 打印到终端：完整的研究报告，采用 Markdown 格式
• 列出查阅过的来源：## Sources consulted (web search) 会列出网页搜索步骤搜索或打开过的每个 URL。这些是查阅过的，而非引用的；引用内容是文内链接。
• 确认完成：显示研究文件的保存路径

Token 效率说明：脚本会在后台轮询时阻塞，因此 Claude 只需等待一条命令。

中断的任务：响应 ID 会在等待前打印并保存。若任务仍在运行，或等待超时，可使用 python3 assets/deep_research.py --resume <response_id> --output-dir <dir> 获取结果。这不会发送新的（付费）请求。

导入到知识库：使用 research-runs 技能导入原始 JSON，而非 Markdown：python3 ~/.claude/skills/research-runs/scripts/research_run.py import research_response_….json --vault <vault> --adapter openai-json --provider openai --surface api --prompt research_prompt_….txt。JSON 会保留引用片段以及查阅过但未引用的页面。

捆绑资源

脚本

scripts/run_deep_research.py（主入口）

用于协调各项任务的脚本，负责：

• 提示词质量评估
• 交互式增强问题（智能识别技术类与通用研究）
• 保存提示词并添加时间戳
• 执行核心深度研究

主要功能：

• 智能增强：仅在提示词简短或泛泛而谈时提问
• 基于模板的问题：针对技术类与通用研究采用不同的问题集
• 灵活输入：编号选项 + 自定义文本输入
• 错误处理：找不到 deep_research.py 时提供实用提示

可用选项：

python3 run_deep_research.py <prompt> [OPTIONS]
  --no-enhance              Skip enhancement questions
  --model <model>           Model to use (default: runner default, gpt-5.6-sol)
  --timeout <seconds>       Maximum wait in seconds (default: 3600)
  --output-dir <path>       Where to save the prompt, request, raw response, and report

assets/deep_research.py

与 OpenAI 的 Deep Research API 交互的核心脚本，负责：

• 通过 OPENAI_API_KEY 进行 API 身份验证
• 创建和执行请求
• 自动保存 Markdown：默认保存带时间戳的报告文件
• 输出格式化（报告 + 带元数据的来源）
• 错误处理和重试

新增命令行选项：

--output-file <path>      Custom output file path
--no-save                 Disable automatic markdown saving

参考文档

references/workflow.md

详细的工作流文档，涵盖：

• 完整的技能工作流及示例
• 提示词增强策略
• 研究参数说明
• Claude 集成指南
• 命令行接口参考
• 错误处理和故障排查
• 高效研究技巧

关键行为

智能提示词增强

该技能会智能判断是否需要增强：

• 提示词少于 15 个单词或以泛泛的内容开头时，触发增强
• 提示词详细且具体时，跳过增强
• 用户可以使用 --no-enhance 标志禁用增强
• 感知模板：针对技术类与通用研究使用不同的问题

研究参数

增强后的提示词包含：

• 带有完整上下文的原始用户查询
• 范围和时间范围偏好
• 期望的深度级别（摘要、技术、实施、比较）
• 具体关注领域（性能、成本、安全性等）

这些参数有助于深度研究模型提供更有针对性、更相关的结果。

可复现性

每次研究执行都会：

• 将使用的确切提示词保存到带时间戳的文件
• 支持追溯研究决策
• 支持使用相同或修改后的提示词进行后续研究
• 保留研究参数的审计记录

示例

简短提示词与增强

用户：“研究最有效的开源 RAG 解决方案”

脚本行为：

1. 检测到提示词较短（12 个词）且包含技术关键词（“开源”“RAG”）
2. 提出技术研究问题：
   • 技术范围：仅限开源？（用户：是）
   • 关键指标：性能／基准测试？（用户：速度和准确性）
   • 使用场景：生产环境部署？（用户：多个方面）
3. 补充参数，将提示词扩展为详细版本
4. 保存并执行深度研究
5. 返回包含对比基准和来源 URL 的综合报告

未经增强的详细提示词

用户：“分析大语言模型在 2024-2025 年对软件开发者生产力的影响，重点关注代码生成工具、结对编程和生产力指标。”

脚本行为：

1. 检测到提示词较详细（24 个词），且范围／重点明确
2. 跳过增强问题
3. 立即保存并执行深度研究
4. 返回符合用户要求的聚焦分析

要求

• Python 3.7+
• OpenAI API 密钥：优先从 SOPS（~/.claude/skills/secrets.enc.yaml）读取，其次从 OPENAI_API_KEY 或 .env 文件读取
• 互联网连接（用于网页搜索）
• 研究最多需要 60 分钟才能完成（可通过 --timeout 配置；超过该时限时使用 --resume）

节省 Token 的工作流

长时间运行任务优化

深度研究查询通常需要 10-20 分钟 才能完成。此技能经过优化，可最大限度减少长时间等待期间的 Token 消耗：

工作原理：

1. 同步执行：脚本作为阻塞子进程运行（不进行后台轮询）
2. 不进行中间检查：Claude 静默等待任务完成，不提供状态更新
3. 单次输出：仅在最后呈现结果
4. 自动保存：自动保存 Markdown 文件，无需手动操作

节省的 Token：

• 传统方式：每 30 秒检查一次状态 = 约 40 次检查 × 500 个 Token = 浪费约 20,000 个 Token
• 此方式：单次等待 = 总计约 1,000 个 Token

自动文件管理

此技能会自动生成并保存文件：

生成的文件：

• research_prompt_YYYYMMDD_HHMMSS.txt - 包含参数的增强版研究提示词
• research_request_YYYYMMDD_HHMMSS.json - 已发送的内容：模型、工具、推理内容、提示词（不含密钥）
• research_response_YYYYMMDD_HHMMSS.json - 完整的原始 API 响应：报告文本、带字符范围的 url_citation 注释、包含已查阅来源的 web_search_call 步骤。规范记录；请导入此文件。
• research_report_YYYYMMDD_HHMMSS.md - 易读的报告，包含：
  • 行内引用链接
  • ## Sources consulted (web search)：搜索或打开过的所有 URL，无论是否引用
  • 元数据页脚（日期、模型、响应 ID、原始响应文件名）

自定义选项：

# Custom output location
python3 deep_research.py --prompt-file prompt.txt --output-file my_research.md

# Disable automatic saving (terminal output only)
python3 deep_research.py --prompt-file prompt.txt --no-save

故障排除

缺少 OPENAI_API_KEY

错误：“Missing OPENAI_API_KEY”

解决方案：

• 设置环境变量：export OPENAI_API_KEY="your-key"
• 或在工作目录中创建 .env 文件，并设置 OPENAI_API_KEY=your-key

找不到 deep_research.py

错误：“Could not find deep_research.py”

解决方案：

• 确保已正确安装技能及其资源文件
• 脚本会按以下顺序搜索：技能资源文件夹 → 当前目录 → 父目录

研究超时

错误：“Still in_progress after …s. Resume later with: --resume ”

解决方案：

• 稍后获取结果：使用 --resume <id>（不会产生新费用），或增加 --timeout 5400（90 分钟）
• 简化提示词以缩小研究范围
• 在非高峰时段运行，API 响应可能更快