deep-research

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deep Research Skill

Purpose

用途

This skill enables comprehensive, internet-enabled research on any topic using OpenAI's Deep Research API (o4-mini-deep-research model). It intelligently enhances user research prompts through interactive clarifying questions, ensures research parameters are saved for reproducibility, and executes deep research with full web search capabilities.

本Skill借助OpenAI的Deep Research API（o4-mini-deep-research模型），支持对任意主题开展联网式全面研究。它会通过交互式澄清问题智能优化用户的研究提示词，确保保存研究参数以实现可复现性，并结合完整的网页搜索能力执行深度研究。

When to Use This Skill

何时使用本Skill

Trigger this skill when:

User requests research on a specific topic
User asks for analysis, investigation, or comprehensive information gathering
User wants exploration of a subject with web search and reasoning
User provides a brief research query that could be refined
User wants to understand current state, trends, or comparisons in a field

Example user requests:

"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"

在以下场景触发本Skill：

用户请求对特定主题进行研究
用户需要分析、调查或全面收集信息
用户希望结合网页搜索与推理来探索某一主题
用户提供的研究查询较为简略，可进一步优化
用户想要了解某一领域的当前状态、趋势或对比情况

示例用户请求：

"研究性能表现优异的开源RAG解决方案"
"2025年AI的最新发展有哪些？"
"我需要一份分布式数据库系统的全面分析报告"
"查找实施向量搜索的最佳实践"
"调查AI对软件工程行业的影响"

Workflow Overview

工作流概述

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

用户输入
    ↓
评估：提示词是否过于简略？
    ↓
是 → 提出优化问题 → 收集答案
    ↓                               ↓
    └───────→ 构建优化后的提示词 ←──┘
                    ↓
            保存至带时间戳的文件
                    ↓
            执行deep_research.py
                    ↓
            输出报告 + 来源
                    ↓
            呈现给用户

How Claude Should Use This Skill

Claude如何使用本Skill

Important for Token Efficiency: Deep research takes 10-20 minutes to complete. The skill is designed to run synchronously (blocking) without intermediate status checks. This approach minimizes token usage during the wait. Claude should:

Start the research
Wait for completion (subprocess blocks automatically)
Present final results once complete

No need for periodic polling or status updates during execution.

关于Token效率的重要提示： 深度研究需耗时10-20分钟。本Skill设计为同步运行（阻塞式），无需中间状态检查。这种方式能在等待期间最大限度减少Token消耗。Claude应：

启动研究任务
等待任务完成（子进程会自动阻塞）
任务完成后呈现最终结果

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

Step 1: Accept Research Request

步骤1：接收研究请求

Receive the user's research prompt. This can range from brief ("Latest AI trends") to highly detailed ("Impact of language models on developer productivity with focus on 2024-2025").

接收用户的研究提示词。提示词可简略如“最新AI趋势”，也可非常详细如“2024-2025年大语言模型对开发者生产力的影响”。

Step 2: Execute the Orchestration Script

步骤2：执行编排脚本

Run the skill's main orchestration script with the user's research prompt:

bash

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

The script is located at

scripts/run_deep_research.py

within the skill's installation.

运行本Skill的主编排脚本，传入用户的研究提示词：

bash

python3 scripts/run_deep_research.py "你的研究提示词"

该脚本位于Skill安装目录下的

scripts/run_deep_research.py

路径。

Step 3: Script Execution Flow

步骤3：脚本执行流程

The script automatically:

Assesses prompt completeness: Checks if prompt is too brief or generic (< 15 words or starts with "what is", "how to", etc.)
Asks clarifying questions (if needed):
- Presents 2-3 focused questions relevant to the research type
- Detects if research is technical or general based on keywords
- Allows users to select from predefined options (1-4) or provide custom text
- Questions cover: Scope/Timeframe, Depth level, Focus areas
Enhances the prompt: Combines original prompt with user's answers into structured research parameters
Saves prompt file: Writes enhanced prompt to
```
research_prompt_YYYYMMDD_HHMMSS.txt
```
for reproducibility
Executes deep research: Runs the core
```
deep_research.py
```
script with:
- Model: o4-mini-deep-research (configurable via
```
--model
```
  )
- Timeout: 1800 seconds / 30 minutes (configurable via
```
--timeout
```
  )
- Tools: Web search enabled by default

脚本会自动执行以下操作：

评估提示词完整性：检查提示词是否过于简略或通用（少于15个单词，或以“what is”“how to”等开头）
提出澄清问题（如需）：
- 根据研究类型提出2-3个针对性问题
- 根据关键词判断研究是技术类还是通用类
- 允许用户从预定义选项（1-4）中选择，或提供自定义文本
- 问题涵盖：范围/时间框架、深度级别、重点领域
优化提示词：将原始提示词与用户的回答结合，构建结构化研究参数
保存提示词文件：将优化后的提示词写入
```
research_prompt_YYYYMMDD_HHMMSS.txt
```
文件，确保可复现性
执行深度研究：运行核心脚本
```
deep_research.py
```
，配置如下：
- 模型：o4-mini-deep-research（可通过
```
--model
```
  参数配置）
- 超时时间：1800秒/30分钟（可通过
```
--timeout
```
  参数配置）
- 工具：默认启用网页搜索

Step 4: Present Results to User

步骤4：向用户呈现结果

The script automatically:

Saves markdown file: Research report with sources saved to
```
research_report_YYYYMMDD_HHMMSS.md
```
Prints to terminal: Complete research report with markdown formatting
Lists web sources: Numbered URLs referenced in the research
Confirms completion: Path where research files were saved

Token Efficiency Note: Deep research takes 10-20 minutes. The script runs synchronously (blocking) without intermediate polling, minimizing token usage during the wait.

脚本会自动执行以下操作：

保存Markdown文件：将包含来源的研究报告保存至
```
research_report_YYYYMMDD_HHMMSS.md
```
输出至终端：输出带Markdown格式的完整研究报告
列出网页来源：列出研究中引用的带编号的URL
确认完成：告知用户研究文件的保存路径

Token效率提示：深度研究需耗时10-20分钟。脚本以同步方式运行（阻塞式），无需中间轮询，可在等待期间最大限度减少Token消耗。

Bundled Resources

配套资源

Scripts

脚本

scripts/run_deep_research.py

(Main Entry Point)

scripts/run_deep_research.py

（主入口）

The orchestration script that handles:

Prompt quality assessment
Interactive enhancement questions (with smart detection for technical vs. general research)
Prompt saving and timestamping
Execution of core deep research

Key Features:

Smart enhancement: Only asks questions if prompt is brief/generic
Template-based questions: Different question sets for technical vs. general research
Flexible input: Numbered options + custom text input
Error handling: Helpful messages if deep_research.py is not found

Available options:

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

该编排脚本负责：

提示词质量评估
交互式优化问题（可智能检测技术类/通用类研究）
提示词保存与时间戳标记
核心深度研究任务的执行

核心特性：

智能优化：仅在提示词简略/通用时才提出问题
模板化问题：针对技术类和通用类研究使用不同的问题模板
灵活输入：支持编号选项+自定义文本输入
错误处理：当未找到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

assets/deep_research.py

Core script that interfaces with OpenAI's Deep Research API. Handles:

API authentication via OPENAI_API_KEY
Request creation and execution
Automatic markdown saving: Saves timestamped report files by default
Output formatting (report + sources with metadata)
Error handling and retries

New command-line options:

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

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

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

新增命令行选项：

--output-file <path>      自定义输出文件路径
--no-save                 禁用自动Markdown保存

References

参考文档

references/workflow.md

references/workflow.md

Detailed workflow documentation covering:

Complete skill workflow with examples
Prompt enhancement strategies
Research parameters explanation
Integration guidance for Claude
Command-line interface reference
Error handling and troubleshooting
Tips for effective research

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

完整的Skill工作流及示例
提示词优化策略
研究参数说明
与Claude的集成指南
命令行界面参考
错误处理与故障排除
高效研究技巧

Key Behaviors

核心特性

Smart Prompt Enhancement

智能提示词优化

The skill intelligently determines whether enhancement is needed:

Triggers enhancement for prompts with < 15 words or generic starts
Skips enhancement for detailed, specific prompts
Allows users to disable with
```
--no-enhance
```
flag
Template-aware: Uses different questions for technical vs. general research

本Skill会智能判断是否需要优化提示词：

当提示词少于15个单词或开头通用时，触发优化流程
对于详细、具体的提示词，跳过优化步骤
允许用户通过
```
--no-enhance
```
参数禁用优化
模板感知：针对技术类和通用类研究使用不同的问题

Research Parameters

研究参数

Enhanced prompts include:

Original user query with full context
Scope and timeframe preferences
Desired depth level (summary, technical, implementation, comparative)
Specific focus areas (performance, cost, security, etc.)

These parameters help the deep research model deliver more targeted, relevant results.

优化后的提示词包含：

带完整上下文的原始用户查询
范围和时间框架偏好
所需深度级别（摘要、技术、实现、对比）
特定重点领域（性能、成本、安全等）

这些参数可帮助深度研究模型输出更具针对性、相关性的结果。

Reproducibility

可复现性

Every research execution:

Saves the exact prompt used to a timestamped file
Enables tracing research decisions
Allows follow-up research using same/modified prompts
Maintains audit trail of research parameters

每次研究执行都会：

将使用的精确提示词保存至带时间戳的文件
可追溯研究决策
允许使用相同/修改后的提示词进行后续研究
保留研究参数的审计轨迹

Examples

示例

Brief Prompt with Enhancement

简略提示词的优化流程

User: "Research the most effective opensource RAG solutions"

Script behavior:

Detects brief prompt (12 words) + technical keywords ("opensource", "RAG")
Asks technical research questions:
- Technology scope: Open-source only? (User: Yes)
- Key metrics: Performance/benchmarks? (User: Speed and Accuracy)
- Use cases: Production deployment? (User: Multiple aspects)
Enhances to detailed prompt with parameters
Saves and executes deep research
Returns comprehensive report with comparative benchmarks and source URLs

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

脚本行为：

检测到提示词简略（12个单词）且包含技术关键词（“开源”“RAG”）
提出技术类研究问题：
- 技术范围：仅开源方案？（用户：是）
- 核心指标：性能/基准测试？（用户：速度与准确性）
- 使用场景：生产部署？（用户：多个方面）
将提示词优化为包含参数的详细版本
保存提示词并执行深度研究
返回包含对比基准和来源URL的全面报告

Detailed Prompt Without Enhancement

无需优化的详细提示词

User: "Analyze the impact of large language models on software developer productivity in 2024-2025, focusing on code generation tools, pair programming, and productivity metrics."

Script behavior:

Detects detailed prompt (24 words) with specific scope/focus
Skips enhancement questions
Saves and executes deep research immediately
Returns focused analysis aligned with user specifications

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

脚本行为：

检测到提示词详细（24个单词）且包含具体范围/重点
跳过优化问题
保存提示词并立即执行深度研究
返回符合用户指定要求的聚焦分析报告

Requirements

环境要求

Python 3.7+
OpenAI API key (set via
```
OPENAI_API_KEY
```
environment variable or
```
.env
```
file)
Internet connection (for web search)
30+ minutes for research completion (configurable timeout)

Python 3.7+
OpenAI API密钥（通过环境变量
```
OPENAI_API_KEY
```
或
```
.env
```
文件设置）
互联网连接（用于网页搜索）
30+分钟的研究时间（可配置超时时间）

Token-Efficient Workflow

Token高效工作流

Long-Running Task Optimization

长时任务优化

Deep research queries typically take 10-20 minutes to complete. This skill is optimized to minimize token usage during long waits:

How it works:

Synchronous execution: The script runs as a blocking subprocess (no background polling)
No intermediate checks: Claude waits silently for completion without status updates
Single output: Results are presented once at the end
Automatic saving: Markdown files are saved automatically, no manual intervention needed

Token savings:

Traditional approach: Checking status every 30 seconds = ~40 checks × 500 tokens = ~20,000 tokens wasted
This approach: Single wait = ~1,000 tokens total

深度研究查询通常需耗时10-20分钟。本Skill经过优化，可在等待期间最大限度减少Token消耗：

工作原理：

同步执行：脚本以阻塞式子进程运行，无需后台轮询
无中间检查：Claude静默等待完成，无需状态更新
单次输出：任务完成后一次性呈现结果
自动保存：自动保存Markdown文件，无需手动干预

Token节省效果：

传统方式：每30秒检查一次状态=约40次检查×500 Token=约20,000 Token浪费
本方式：仅需等待=约1,000 Token总消耗

Automatic File Management

自动文件管理

The skill automatically generates and saves files:

Generated files:

```
research_prompt_YYYYMMDD_HHMMSS.txt
```
- Enhanced research prompt with parameters
```
research_report_YYYYMMDD_HHMMSS.md
```
- Complete markdown report with:
- Research sections (historical, cognitive, cultural, etc.)
- Numbered source citations
- Metadata footer (date, model)

Customization options:

bash

undefined

本Skill会自动生成并保存文件：

生成的文件：

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

自定义选项：

bash

undefined

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

undefined

python3 deep_research.py --prompt-file prompt.txt --no-save

undefined

Troubleshooting

故障排除

Missing OPENAI_API_KEY

缺失OPENAI_API_KEY

Error: "Missing OPENAI_API_KEY"

Solution:

Set environment variable:
```
export OPENAI_API_KEY="your-key"
```
Or create
```
.env
```
file in working directory with
```
OPENAI_API_KEY=your-key
```

错误信息： "Missing OPENAI_API_KEY"

解决方案：

设置环境变量：
```
export OPENAI_API_KEY="你的密钥"
```
或在工作目录创建
```
.env
```
文件，写入
```
OPENAI_API_KEY=你的密钥
```

deep_research.py Not Found

未找到deep_research.py

Error: "Could not find deep_research.py"

Solution:

Ensure skill is properly installed with assets
Script searches in: skill assets folder → current directory → parent directory

错误信息： "Could not find deep_research.py"

解决方案：

确保Skill已正确安装并包含资产文件
脚本会按以下顺序查找：Skill资产文件夹 → 当前目录 → 父目录

Research Timeout

研究超时

Error: Request times out after 30 minutes

Solution:

Increase timeout:
```
--timeout 5400
```
(90 minutes)
Simplify prompt to reduce research scope
Run during off-peak hours for potentially faster API responses

错误信息： 请求在30分钟后超时

解决方案：

增加超时时间：
```
--timeout 5400
```
（90分钟）
简化提示词以缩小研究范围
在非高峰时段运行，可能获得更快的API响应速度",

deep-research

Original

Translation

Deep Research Skill

Deep Research Skill

Purpose

用途

When to Use This Skill

何时使用本Skill

Workflow Overview

工作流概述

How Claude Should Use This Skill

Claude如何使用本Skill

Step 1: Accept Research Request

步骤1：接收研究请求

Step 2: Execute the Orchestration Script

步骤2：执行编排脚本

Step 3: Script Execution Flow

步骤3：脚本执行流程

Step 4: Present Results to User

步骤4：向用户呈现结果

Bundled Resources

配套资源

Scripts

脚本

scripts/run_deep_research.py (Main Entry Point)

scripts/run_deep_research.py（主入口）

assets/deep_research.py

assets/deep_research.py

References

参考文档

references/workflow.md

references/workflow.md

Key Behaviors

核心特性

Smart Prompt Enhancement

智能提示词优化

Research Parameters

研究参数

Reproducibility

可复现性

Examples

示例

Brief Prompt with Enhancement

简略提示词的优化流程

Detailed Prompt Without Enhancement

无需优化的详细提示词

Requirements

环境要求

Token-Efficient Workflow

Token高效工作流

Long-Running Task Optimization

长时任务优化

Automatic File Management

自动文件管理

Custom output location

自定义输出位置

Disable automatic saving (terminal output only)

禁用自动保存（仅输出至终端）

Troubleshooting

故障排除

Missing OPENAI_API_KEY

缺失OPENAI_API_KEY

deep_research.py Not Found

未找到deep_research.py

Research Timeout

研究超时

`scripts/run_deep_research.py`
(Main Entry Point)

`scripts/run_deep_research.py`
（主入口）

`assets/deep_research.py`

`assets/deep_research.py`

`references/workflow.md`

`references/workflow.md`