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

deep-research

写作与研究

查看项目

更新于 10-15 11:44

技能介绍

用途

deep-research 是一个由 Google Gemini 深度研究智能体驱动的深度研究技能，用于执行异步深度研究任务。它不依赖 Gemini CLI，而是通过 Gemini Interactions API 工作，并支持将本地文件上传至文件搜索存储，实现基于 RAG（检索增强生成）的答案。该技能面向需要自动化研究流程的 AI 智能体与开发者，提供命令行脚本进行任务启动、状态查询、报告保存和文件存储管理。

主要能力

  • 深度研究：通过 research.py start 启动研究任务，支持指定研究深度（quick 约 2-5 分钟、standard 约 5-15 分钟、deep 约 15-45 分钟）。
  • RAG 接地研究：使用 --context 参数自动创建临时文件搜索存储，上传本地文件或目录，使研究结果基于本地资料。
  • 成本预估：使用 --dry-run 在不启动研究的情况下输出 JSON 格式的成本估算。
  • 报告导出：支持将报告保存为 Markdown、HTML 或 PDF（PDF 需要 weasyprint）。
  • 结构化输出：使用 --output-dir 可将结果保存为包含 report.md、metadata.json、interaction.json、sources.json 的目录结构。
  • 文件搜索存储管理：通过 store.py 创建、列出、查询和删除文件搜索存储；通过 upload.py 上传文件，支持 --smart-sync 跳过未变更文件。
  • 会话状态管理：研究 ID 和存储映射缓存在 .gemini-research.json 中，可通过 state.py 查看、清理。
  • 自适应轮询：默认根据历史完成时间调整轮询间隔，也可通过 --no-adaptive-poll 使用固定间隔曲线。

使用方式

前置条件

  • 一个 Google API 密钥（环境变量 GOOGLE_API_KEY 或 GEMINI_API_KEY）
  • 已安装 uv

快速开始

# 运行深度研究查询
uv run {baseDir}/scripts/research.py "What are the latest advances in quantum computing?"

# 检查研究状态
uv run {baseDir}/scripts/research.py status <interaction-id>

# 保存完成的报告
uv run {baseDir}/scripts/research.py report <interaction-id> --output report.md

# 基于本地文件的研究（自动创建存储、上传、清理）
uv run {baseDir}/scripts/research.py start "How does auth work?" --context ./src --output report.md

# 导出为 HTML 或 PDF
uv run {baseDir}/scripts/research.py start "Analyze the API" --context ./src --format html --output report.html

环境变量

按优先级检查以下之一：GEMINI_DEEP_RESEARCH_API_KEY、GOOGLE_API_KEY、GEMINI_API_KEY。

可选模型配置：GEMINI_DEEP_RESEARCH_MODEL（默认 gemini-3.1-pro-preview）、GEMINI_MODEL（回退模型名）、GEMINI_DEEP_RESEARCH_AGENT（默认 deep-research-pro-preview-12-2025）。

研究命令常用参数

  • --report-format：输出结构（executive_summary、detailed_report、comprehensive）
  • --store：基于文件搜索存储进行研究
  • --follow-up ID：继续之前的研究会话
  • --output / --output-dir：等待完成并保存报告
  • --timeout：最大等待时间（默认 1800 秒）
  • --context：自动创建临时存储用于 RAG 接地
  • --context-extensions：按扩展名过滤上传文件
  • --keep-context：研究完成后保留临时存储（默认自动删除）
  • --dry-run：仅估算成本
  • --format：报告格式（md/html/pdf）
  • --prompt-template：领域特定提示前缀（typescript、python、general、auto）
  • --depth：研究深度（quick、standard、deep）
  • --max-cost：超过估算成本则中止
  • --input-file：从文件读取研究查询
  • --no-cache：跳过缓存强制新运行

注意：使用 --output 或 --output-dir 时命令会阻塞直到研究完成（2-10+ 分钟），不要用 & 后台运行。非阻塞模式（省略 --output）会立即返回 ID，之后用 status 轮询、用 report 保存。

文件搜索存储命令

uv run {baseDir}/scripts/store.py create "My Project Docs"
uv run {baseDir}/scripts/store.py list
uv run {baseDir}/scripts/store.py query <store-name> "What does the auth module do?"
uv run {baseDir}/scripts/store.py delete <store-name>
uv run {baseDir}/scripts/upload.py ./src fileSearchStores/abc123 --smart-sync

会话状态命令

uv run {baseDir}/scripts/state.py show
uv run {baseDir}/scripts/state.py research
uv run {baseDir}/scripts/state.py stores
uv run {baseDir}/scripts/state.py --json show
uv run {baseDir}/scripts/state.py clear

适用场景

  • 需要基于本地代码库或文档进行深度研究并生成报告
  • AI 智能体集成，通过结构化 JSON 输出获取研究结果
  • 对研究成本敏感，需要预先估算
  • 需要管理文件搜索存储并进行快速问答

限制与安全说明

  • 凭证：需要 Google/Gemini API 密钥，仅从环境变量读取，传递给 google-genai SDK，不会记录、写入文件或传输到 Google Gemini API 以外的任何地方。
  • 文件上传：--context 会将本地文件上传至 Google 的临时文件搜索存储。敏感文件自动排除（.env*、credentials.json、secrets.*、私钥、认证令牌等），二进制文件被拒绝，构建目录被跳过。临时存储在研究完成后自动删除，除非指定 --keep-context。仅上传显式指向的文件，不会自动扫描父目录或主目录。
  • 非交互模式：当 stdin 不是 TTY 时，确认提示自动跳过，适用于智能体和 CI，但意味着有文件系统访问权限的自主智能体可能触发上传。建议限制路径访问或使用 --dry-run 和 --max-cost 防护。
  • 本地状态：研究会话状态写入工作目录的 .gemini-research.json，包含交互 ID、存储映射和上传哈希，不含凭证或研究内容。
  • 文件大小限制：每个文件 100 MB。
  • MIME 类型支持：36 种文件扩展名原生支持，常见编程文件通过回退机制以 text/plain 上传。
  • 成本估算：基于启发式，Gemini API 不返回 token 数或计费数据，估算结果已明确标注。
  • PDF 导出：需要 weasyprint。
  • 输出约定：所有脚本遵循双输出模式，stderr 为人类可读格式，stdout 为机器可读 JSON。