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

agent-deep-research

写作与研究

查看项目

更新于 10-15 11:07

技能介绍

用途

agent-deep-research 用于调用 Google Gemini 的深度研究智能体执行研究任务，支持启动研究、检查状态、保存报告，并可通过文件搜索存储实现基于自有资料的 RAG 研究。

主要能力

  • 深度研究：通过 research.py 启动研究问题，支持指定报告格式（executive_summary、detailed_report、comprehensive），可隐藏中间思考步骤，也可通过 --follow-up 继续之前的会话。
  • 状态与报告：使用 status 子命令查询研究状态（in_progress、completed、failed）；使用 report 子命令保存完成的报告到文件或目录。
  • 结构化输出：使用 --output-dir 时，结果保存为结构化目录，包含 report.md、metadata.json、interaction.json 和 sources.json，同时向 stdout 打印小于 500 字符的紧凑 JSON 摘要，便于智能体集成。
  • 文件搜索存储：通过 store.py 创建、列出、查询和删除搜索存储；通过 upload.py 上传文件或整个目录，支持 --smart-sync 跳过未变更文件，并可按扩展名过滤。
  • 自适应轮询：使用 --output 或 --output-dir 时，脚本会轮询 Gemini API 直至完成。默认使用历史自适应轮询，从 .gemini-research.json 的 researchHistory（最近 50 条，区分是否基于资料）学习完成时间分布；历史不足 3 条或传入 --no-adaptive-poll 时使用固定递增曲线（5s/10s/30s/60s）。所有间隔限制在 [2s, 120s]。
  • 会话管理：研究 ID 与存储映射缓存在当前工作目录的 .gemini-research.json 中，state.py 支持 show、research、stores、clear，并可加 --json 输出结构化 JSON。
  • 非交互模式：当 stdin 不是 TTY（如被 AI 智能体或 CI 调用）时，确认提示自动跳过。

使用方式

前置条件：配置 Google API 密钥（按优先级检查 GEMINI_DEEP_RESEARCH_API_KEY、GOOGLE_API_KEY、GEMINI_API_KEY），并安装 uv（curl -LsSf https://astral.sh/uv/install.sh | sh）。

快速开始：

  • 研究查询：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

可选模型配置环境变量：GEMINI_DEEP_RESEARCH_MODEL（默认 models/gemini-flash-latest）、GEMINI_MODEL（默认 models/gemini-flash-latest）、GEMINI_DEEP_RESEARCH_AGENT（默认 deep-research-pro-preview-12-2025）。

研究命令支持 --report-format、--store、--no-thoughts、--follow-up、--output、--output-dir、--timeout（默认 1800 秒）、--no-adaptive-poll 等参数。start 为默认子命令。

文件上传支持 --smart-sync 与 --extensions；MIME 类型方面，Gemini File Search API 原生支持 36 种扩展名，常见编程文件（JS、TS、JSON、CSS、YAML 等）通过回退机制以 text/plain 上传，二进制文件被拒绝，单文件上限 100 MB。

输出约定：所有脚本 stderr 输出人类可读格式，stdout 输出机器可读 JSON，因此 2>/dev/null 可隐藏人类输出，管道 stdout 可获取干净 JSON。

适用场景

适合需要基于自有文档或代码库进行深度研究、问答和报告生成的场景，尤其适合 AI 智能体集成（通过紧凑 JSON 摘要与磁盘完整报告分离的模式）以及 CI 流水线中的非交互调用。

限制

运行依赖 Google API 密钥与 uv 环境；上传文件单文件不得超过 100 MB；二进制文件不被接受；轮询间隔有 [2s, 120s] 的上下限；部分高级行为（如自适应轮询）需要至少 3 条历史数据才能启用。文档未提供收费、价格或效果相关的信息。