SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场deep-research

deep-research

写作与研究

查看项目

更新于 10-15 17:04

技能介绍

用途

Deep Research 技能用于对任意主题进行综合性、联网式的研究。它借助 OpenAI Deep Research API（o4-mini-deep-research 模型）完成任务，能够通过交互式澄清问题智能增强用户的研究提示词，确保研究参数被保存以便复现，并利用完整的网页搜索能力执行深度研究。

适用触发场景：

  • 用户请求对特定主题进行研究
  • 用户要求分析、调查或综合信息收集
  • 用户希望借助网页搜索与推理探索某一主题
  • 用户给出可被细化的简短研究查询
  • 用户想了解某领域的现状、趋势或对比

示例请求：

  • “Research the most effective open-source RAG solutions with high benchmark performance”
  • “What are the latest AI developments in 2025?”
  • “I need a comprehensive analysis of distributed database systems”
  • “Find best practices for implementing vector search”
  • “Investigate how AI is impacting the software engineering industry”

工作流程

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

使用步骤

步骤 1：接受研究请求 接收用户的研究提示词，范围可以从简短（“Latest AI trends”）到高度详细（“Impact of language models on developer productivity with focus on 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 脚本，参数包括模型 o4-mini-deep-research（可通过 --model 配置）、超时 1800 秒/30 分钟（可通过 --timeout 配置）、默认启用网页搜索工具

步骤 4：向用户呈现结果 脚本会自动将研究报告与来源保存为 research_report_YYYYMMDD_HHMMSS.md；在终端打印带 Markdown 格式的完整研究报告；列出引用的编号网页来源 URL；确认完成并给出研究文件保存路径。

令牌效率说明

深度研究需要 10-20 分钟完成。技能设计为同步（阻塞）运行，不做中间状态检查，以尽量降低等待期间的 token 消耗。Claude 应当：启动研究；等待完成（子进程自动阻塞）；完成后一次性呈现最终结果。无需周期性轮询或状态更新。

对比：传统做法每 30 秒检查一次状态 = 约 40 次检查 × 500 token = 约 20,000 token 浪费；本做法单次等待 = 总计约 1,000 token。

捆绑资源

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: o4-mini-deep-research)
  --timeout <seconds>       Timeout in seconds (default: 1800)
  --output-dir <path>       Where to save prompt file

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 标志禁用；模板感知：技术类与通用类研究使用不同问题。

研究参数

增强后的提示词包含：带完整上下文的原始用户查询；范围与时间框架偏好；期望的深度级别（摘要、技术、实现、对比）；特定关注领域（性能、成本、安全等）。这些参数帮助深度研究模型输出更有针对性、更相关的结果。

可复现性

每次研究执行都会将使用的确切提示词保存到带时间戳的文件；便于追溯研究决策；允许使用相同/修改后的提示词进行后续研究；保留研究参数的审计记录。

示例

简短提示词（带增强）

用户：“Research the most effective opensource RAG solutions” 脚本行为：检测到简短提示词（12 个词）+ 技术关键词（“opensource”“RAG”）；提出技术类研究问题——技术范围：仅限开源？（用户：Yes）；关键指标：性能/基准？（用户：Speed and Accuracy）；使用场景：生产部署？（用户：Multiple aspects）；增强为带参数的详细提示词；保存并执行深度研究；返回包含对比基准和来源 URL 的综合报告。

详细提示词（不增强）

用户：“Analyze the impact of large language models on software developer productivity in 2024-2025, focusing on code generation tools, pair programming, and productivity metrics.” 脚本行为：检测到详细提示词（24 个词）且范围/关注点明确；跳过增强问题；直接保存并执行深度研究；返回符合用户规格的聚焦分析。

要求

  • Python 3.7+
  • OpenAI API key（通过 OPENAI_API_KEY 环境变量或 .env 文件设置）
  • 网络连接（用于网页搜索）
  • 研究完成需 30 分钟以上（超时可配置）

自动文件管理

技能自动生成并保存：

  • research_prompt_YYYYMMDD_HHMMSS.txt —— 带参数的增强研究提示词
  • research_report_YYYYMMDD_HHMMSS.md —— 完整 Markdown 报告，包含研究分节（历史、认知、文化等）、编号来源引用、元数据页脚（日期、模型）

自定义选项：

# 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” 解决：确保技能已正确安装并包含 assets；脚本搜索路径为：技能 assets 文件夹 → 当前目录 → 父目录。

研究超时 错误：请求在 30 分钟后超时 解决：增加超时 --timeout 5400（90 分钟）；简化提示词以缩小研究范围；在非高峰时段运行，可能获得更快的 API 响应。