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 使用。

核心用法

agent-deep-research 是一个基于 Google Gemini Interactions API 的异步深度研究工具，无需依赖 Gemini CLI。核心功能包括：

• 深度研究任务：通过 research.py start "问题" 启动异步研究，支持 quick/standard/deep 三种深度级别，耗时 2-45 分钟不等
• RAG 本地文件检索：--context 参数自动上传本地文件到 Google 临时文件搜索存储，实现基于私有文档的 grounded 研究
• 成本预估与管控：--dry-run 预览费用，--max-cost 设置上限，避免意外支出
• 多格式输出：支持 Markdown、HTML、PDF 导出，--output-dir 生成结构化目录（含 report.md、metadata.json、sources.json）
• 会话管理：.gemini-research.json 持久化研究状态，支持断点续研和状态查询

显著优点

1. Agent 原生设计：支持 30+ AI Agent（Claude Code、Amp、Codex 等），提供结构化 JSON 输出和机器可读 stdout
2. 安全文件上传：自动过滤 .env*、credentials.json、私钥、token 等敏感文件，二进制文件 MIME 类型拦截
3. 智能轮询：自适应历史学习算法，根据过往完成时间动态调整 poll 间隔，减少 API 调用成本
4. 透明可审计：纯 Python 代码，PEP 723 内联元数据，无二进制 blob、无遥测、无混淆
5. 双输出模式：stderr 面向人类（富文本表格、进度条），stdout 面向程序（JSON），便于管道集成

潜在缺点与局限性

• 阻塞式等待：--output 模式下需同步等待 2-10+ 分钟，不适合交互式场景
• 成本不可精确预测：--dry-run 为启发式估算，实际费用可能与预估存在偏差
• 依赖 Google API：需境外网络访问，国内用户需自行解决连接问题
• 临时存储限制：--context 上传的文件默认 24 小时后自动删除，需 --keep-context 保留
• PDF 依赖外部库：PDF 输出需额外安装 weasyprint，增加部署复杂度

适合人群

• AI Agent 开发者：需要结构化研究输出和状态管理的自动化工作流
• 技术研究人员：需要对代码库、文档进行深度 RAG 分析
• 安全审计团队：需要可审计、无黑盒组件的研究工具
• 成本敏感用户：需要明确预算控制和费用预览的研究场景

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| API Key 泄露 | 环境变量读取，无硬编码 | 确保 `.env` 文件在 `.gitignore` 中 |

| 敏感文件误传 | 已内置多层过滤 | 使用 `--dry-run` 预览上传清单 |

| 意外高额费用 | 研究任务可能持续较长时间 | 设置 `--max-cost` 上限 |

| 网络中间人攻击 | TLS 1.3 加密，官方 SDK | 验证证书链完整性 |

| 会话状态残留 | 本地 `.gemini-research.json` | 定期运行 `state.py gc` 清理 |

该工具在 CLS-Certify v2.1.0 安全认证中获得 A 级（82 分） 评级，六维检测全部通过，适合生产环境部署。