深度研究技能
目的
本技能利用 OpenAI 的 Deep Research API(o4-mini-deep-research 模型),支持对任意主题进行全面的、具备互联网搜索能力的研究。它能够通过交互式澄清问题智能地增强用户的研究提示词,确保研究参数被保存以实现可重复性,并执行带有完整网络搜索功能的深度研究。
何时使用此技能
当出现以下情况时,触发此技能:
- 用户请求研究一个特定主题
- 用户要求进行分析、调查或全面的信息收集
- 用户希望通过网络搜索和推理来探索一个主题
- 用户提供了一个可以优化的简短研究查询
- 用户希望了解某个领域的最新状态、趋势或比较分析
用户请求示例:
- "研究性能基准测试最高的开源 RAG 解决方案"
- "2025 年人工智能的最新发展是什么?"
- "我需要一份分布式数据库系统的全面分析"
- "找到实现向量搜索的最佳实践"
- "调查人工智能如何影响软件工程行业"
工作流程概览
用户输入
↓
评估:提示词过于简短?
↓
是 → 提出优化问题 → 收集答案
↓ ↓
└───────→ 构建增强后的提示词 ←──┘
↓
保存到带时间戳的文件
↓
执行 deep_research.py
↓
输出报告 + 来源
↓
呈现给用户
Claude 应如何使用此技能
Token 效率重要提示: 深度研究需要 10-20 分钟才能完成。该技能被设计为同步(阻塞)运行,无需中间的状态检查。这种方法可以在等待期间最小化 token 使用。Claude 应该:
- 启动研究
- 等待完成(子进程会自动阻塞)
- 完成后呈现最终结果
在执行期间无需进行周期性的轮询或状态更新。
步骤 1:接受研究请求
接收用户的研究提示词。这可以很简短(如“最新AI趋势”)或非常详细(如“语言模型对开发者生产力的影响,重点关注2024-2025年”)。
步骤 2:执行编排脚本
使用用户的研究提示词运行技能的主编排脚本:
python3 scripts/run_deep_research.py "您的研究提示词在这里"
该脚本位于技能安装目录的 scripts/run_deep_research.py。
步骤 3:脚本执行流程
脚本会自动:
-
评估提示词完整性:检查提示词是否过于简短或通用(少于 15 个单词或开头是“什么是”、“如何”等)
-
提出澄清问题(如果需要):
- 根据研究类型提出 2-3 个重点问题
- 根据关键词检测研究是技术性的还是通用性的
- 允许用户从预设选项(1-4)中选择或提供自定义文本
- 问题涵盖:范围/时间框架、深度级别、重点领域
-
增强提示词:将原始提示词与用户的答案组合成结构化的研究参数
-
保存提示词文件:将增强后的提示词写入
research_prompt_YYYYMMDD_HHMMSS.txt以保证可重复性 -
执行深度研究:运行核心的
deep_research.py脚本,参数包括:- 模型:o4-mini-deep-research(可通过
--model配置) - 超时:1800 秒 / 30 分钟(可通过
--timeout配置) - 工具:默认启用网络搜索
- 模型:o4-mini-deep-research(可通过
步骤 4:向用户呈现结果
脚本会自动:
- 保存 markdown 文件:包含来源的研究报告,保存为
research_report_YYYYMMDD_HHMMSS.md - 打印到终端:完整的 Markdown 格式研究报告
- 列出网络来源:研究中引用的带编号的 URL
- 确认完成:研究文件保存的路径
Token 效率说明:深度研究需要 10-20 分钟。脚本同步(阻塞)运行,无需中间轮询,从而在等待期间最小化 token 使用。
捆绑资源
脚本
scripts/run_deep_research.py(主入口点)
负责以下功能的编排脚本:
- 提示词质量评估
- 交互式优化问题(具备技术研究与通用研究的智能检测)
- 提示词保存和打时间戳
- 执行核心深度研究
主要特性:
- 智能优化:仅在提示词简短/通用时提出问题
- 基于模板的问题:为技术研究与通用研究提供不同的问题集
- 灵活的输入:数字选项 + 自定义文本输入
- 错误处理:如果找不到 deep_research.py,则显示有帮助的消息
可用选项:
python3 run_deep_research.py <prompt> [OPTIONS]
--no-enhance 跳过优化问题
--model <model> 要使用的模型(默认:o4-mini-deep-research)
--timeout <seconds> 超时时间,单位秒(默认:1800)
--output-dir <path> 保存提示词文件的目录
assets/deep_research.py
与 OpenAI Deep Research API 交互的核心脚本。负责:
- 通过 OPENAI_API_KEY 进行 API 身份验证
- 请求创建和执行
- 自动 markdown 保存:默认保存带时间戳的报告文件
- 输出格式化(报告 + 带元数据的来源)
- 错误处理和重试
新的命令行选项:
--output-file <path> 自定义输出文件路径
--no-save 禁用自动 markdown 保存
参考文献
references/workflow.md
详细的工作流程文档,涵盖:
- 包含示例的完整技能工作流程
- 提示词增强策略
- 研究参数说明
- 针对 Claude 的集成指南
- 命令行界面参考
- 错误处理和故障排除
- 有效研究的技巧
关键行为
智能提示词增强
该技能智能地判断是否需要增强:
- 触发增强:对于少于 15 个单词或以通用开头开头的提示词
- 跳过增强:对于详细、具体的提示词
- 允许用户:使用
--no-enhance标志禁用 - 模板感知:为技术性研究和通用性研究使用不同的问题
研究参数
增强后的提示词包括:
- 带有完整上下文的原始用户查询
- 范围和时间框架偏好
- 期望的深度级别(摘要、技术、实现、对比)
- 具体的重点领域(性能、成本、安全性等)
这些参数有助于深度研究模型提供更具针对性和相关性的结果。
可重复性
每次研究执行:
- 将使用的确切提示词保存到带时间戳的文件中
- 能够追溯研究决策过程
- 允许使用相同/修改后的提示词进行后续研究
- 维护研究参数的审计跟踪
示例
简短提示词并增强
用户: “研究最有效的开源 RAG 解决方案”
脚本行为:
- 检测到简短提示词(12 个单词)+ 技术关键词(“开源”、“RAG”)
- 提出技术研究问题:
- 技术范围:仅开源?(用户:是)
- 关键指标:性能/基准测试?(用户:速度和准确性)
- 用例:生产部署?(用户:多方面)
- 增强为包含参数的详细提示词
- 保存并执行深度研究
- 返回包含对比基准测试结果和来源 URL 的综合报告
详细提示词且无需增强
用户: “分析大型语言模型在 2024-2025 年对软件开发者生产力的影响,重点关注代码生成工具、结对编程和生产力指标。”
脚本行为:
- 检测到详细提示词(24 个单词),包含具体范围/重点
- 跳过优化问题
- 立即保存并执行深度研究
- 返回与用户规范相符的重点分析
要求
- Python 3.7+
- OpenAI API 密钥(通过
OPENAI_API_KEY环境变量或.env文件设置) - 互联网连接(用于网络搜索)
- 研究完成需要 30 分钟以上时间(可配置超时)
Token 高效工作流
长时间运行任务优化
深度研究查询通常需要 10-20 分钟 才能完成。该技能经过优化,可在长时间等待期间最小化 token 使用:
工作原理:
- 同步执行:脚本作为阻塞的子进程运行(无后台轮询)
- 无中间检查:Claude 静默等待完成,无需状态更新
- 单次输出:结果在最后一次性呈现
- 自动保存:Markdown 文件自动保存,无需人工干预
Token 节省:
- 传统方法:每 30 秒检查一次状态 = 大约 40 次检查 × 500 tokens = 浪费约 20,000 tokens
- 本方法:单次等待 = 总共约 1,000 tokens
自动文件管理
该技能自动生成并保存文件:
生成的文件:
research_prompt_YYYYMMDD_HHMMSS.txt- 包含参数的增强研究提示词research_report_YYYYMMDD_HHMMSS.md- 完整的 Markdown 报告,包含:- 研究章节(历史、认知、文化等)
- 编号的源引用
- 元数据页脚(日期、模型)
自定义选项:
# 自定义输出位置
python3 deep_research.py --prompt-file prompt.txt --output-file my_research.md
# 禁用自动保存(仅终端输出)
python3 deep_research.py --prompt-file prompt.txt --no-save
故障排除
缺少 OPENAI_API_KEY
错误: “缺少 OPENAI_API_KEY”
解决方案:
- 设置环境变量:
export OPENAI_API_KEY="your-key" - 或者在工作目录中创建
.env文件,内容为OPENAI_API_KEY=your-key
找不到 deep_research.py
错误: “找不到 deep_research.py”
解决方案:
- 确保技能已正确安装,包含资产文件
- 脚本搜索路径:技能资产文件夹 → 当前目录 → 父目录
研究超时
错误: 请求在 30 分钟后超时
解决方案:
- 增加超时时间:
--timeout 5400(90 分钟) - 简化提示词以缩小研究范围
- 在非高峰时段运行,以获得更快的 API 响应