Deep Research (Gemini)

核心功能

deep-research 是 Google Gemini 深度研究能力的异步封装工具，通过 Gemini Interactions API 实现无需 Gemini CLI 的独立研究流程。核心用法包括：启动研究查询 (research.py start)、基于本地文件上下文的 RAG 检索 (--context)、成本预估预览 (--dry-run)、结构化 JSON 输出及自适应轮询等待。

显著优点

• 广泛兼容性：明确支持 Claude Code、Amp、Codex、Gemini CLI 等 30+ AI 代理，提供结构化 onboarding 和 AGENTS.md 指南
• 成本透明：--dry-run 提供启发式成本估算，--max-cost 可设置硬性预算上限
• RAG 原生：自动创建临时文件搜索存储，支持 36 种 MIME 类型，智能排除敏感文件（.env、私钥、凭证等）
• 输出灵活：支持 Markdown、HTML、PDF 格式，--output-dir 生成包含报告、元数据、引用来源的结构化目录
• 自适应轮询：基于历史完成时间学习，动态调整轮询间隔，减少 API 调用与等待时间
• 安全设计：无埋点、无混淆代码、无凭证日志，临时存储自动清理（--keep-context 可保留）

潜在局限

• 依赖 Google API：需有效的 Google/Gemini API 密钥，国内网络环境可能受限
• 成本黑盒：估算为启发式，实际计费以 Google 账单为准；深度研究（15-45 分钟）可能产生较高费用
• 非交互模式风险：CI/代理调用时自动跳过确认提示，需配合 --dry-run 和路径限制防止意外上传
• Python 生态依赖：依赖 uv 和 google-genai SDK，需 Python 环境支持

适合人群

AI 代理开发者、研究人员、需要自动化深度调研的技术团队，特别适合已将 Gemini API 集成到工作流的用户。

常规风险

API 密钥泄露、敏感文件意外上传（虽有自动排除机制但仍需审查 --context 路径）、长时间阻塞任务占用资源。建议配合 --timeout 和 --max-cost 使用。