深度研究技能
目的
此技能使用 OpenAI 的 Deep Research API (o4-mini-deep-research 模型),實現對任何主題進行全面、具備網際網路搜尋能力的研究。它能透過互動式釐清問題,智慧地強化使用者的研究提示詞,確保研究參數可儲存以利重現,並利用完整的網路搜尋功能執行深度研究。
何時使用此技能
在以下情況觸發此技能:
- 使用者要求研究特定主題
- 使用者要求分析、調查或全面收集資訊
- 使用者希望透過網路搜尋和推理來探索某個主題
- 使用者提供了一個可以進一步完善的簡短研究查詢
- 使用者想要了解某一領域的當前狀態、趨勢或比較
使用者請求範例:
- "研究最高效的開源 RAG 解決方案,且具備高基準測試成績"
- "2025 年 AI 的最新發展是什麼?"
- "我需要對分散式資料庫系統進行全面分析"
- "尋找實施向量搜尋的最佳實務"
- "調查 AI 如何影響軟體工程產業"
工作流程概述
使用者輸入
↓
評估:提示詞過於簡短?
↓
是 → 提出強化問題 → 收集答案
↓ ↓
└───────→ 建立強化後的提示詞 ←──┘
↓
儲存至帶時間戳記的檔案
↓
執行 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 <提示詞> [選項]
--no-enhance 跳過強化問題
--model <模型> 要使用的模型(預設:o4-mini-deep-research)
--timeout <秒數> 超時秒數(預設:1800)
--output-dir <路徑> 提示詞檔案的儲存位置
assets/deep_research.py
與 OpenAI Deep Research API 介接的核心腳本。負責處理:
- 透過 OPENAI_API_KEY 進行 API 驗證
- 請求建立與執行
- 自動 Markdown 儲存:預設儲存帶時間戳記的報告檔案
- 輸出格式化(包含中繼資料的報告與來源)
- 錯誤處理與重試
新增的命令列選項:
--output-file <路徑> 自訂輸出檔案路徑
--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="您的金鑰" - 或在工作目錄中建立
.env檔案,內容為OPENAI_API_KEY=您的金鑰
找不到 deep_research.py
錯誤: "找不到 deep_research.py"
解決方案:
- 確保技能已正確安裝資產檔案
- 腳本搜尋順序為:技能資產資料夾 → 目前目錄 → 父目錄
研究超時
錯誤: 請求在 30 分鐘後超時
解決方案:
- 增加超時時間:
--timeout 5400(90 分鐘) - 簡化提示詞以減少研究範圍
- 在非尖峰時段執行以獲得更快的 API 回應