Deep Research (Gemini)

核心用法

Deep Research 是一个围绕 Google Gemini 深度研究 API 构建的异步研究工具集，无需 Gemini CLI 依赖即可运行。核心能力包括：

• 异步深度研究：通过 research.py start 启动长时研究任务，支持 --context 参数实现本地文件 RAG 增强
• 成本预览：--dry-run 模式可在执行前输出 JSON 格式的成本估算
• 结构化输出：--output-dir 生成包含 report.md、metadata.json、interaction.json、sources.json 的完整目录
• 自适应轮询：基于历史完成时间智能调整查询间隔（5s-120s），优化 API 调用效率

显著优点

1. 多智能体兼容：明确支持 Claude Code、Amp、Codex、Gemini CLI 等 30+ AI 代理
2. 非交互式设计：TTY 检测自动跳过确认提示，适合 CI/CD 和自动化工作流
3. 智能文件管理：--smart-sync 基于哈希跳过未变更文件，36 种 MIME 类型自动识别
4. 领域自适应：--prompt-template auto 根据文件扩展名自动选择 TypeScript/Python/General 模板

潜在缺点

• 成本不可知性：API 不返回真实 token 计数，成本估算为启发式计算
• 外部依赖：必须配置 Google API Key，且依赖 uv 包管理器
• 文件限制：单文件 100MB 上限，二进制文件被拒绝
• 延迟敏感：深度研究耗时 15-45 分钟，虽有自适应轮询仍需较长等待

适合人群

• 需要代码库级 RAG 问答的开发者
• 构建自动化研究报告的 AI 智能体
• 追求结构化输出（非纯文本）的科研/商业分析师

常规风险

• API 密钥泄露：需环境变量管理 GEMINI_DEEP_RESEARCH_API_KEY 等敏感配置
• 成本超支：长文本+深度模式可能产生意外费用，建议配合 --max-cost 使用
• 数据残留：--keep-context 可能意外保留临时文件搜索存储
• 轮询滥用：自适应机制虽优化但仍存在 API 调用频率风险

核心功能

Deep Research Skill 是一个基于 Google Gemini Interactions API 的异步深度研究工具，专为 AI 智能体设计。它允许用户提交复杂研究问题，由 Gemini 的 deep research agent 自动执行多轮检索、分析与综合，最终生成结构化研究报告。

显著优点

1. RAG 本地文件支持：通过 --context 参数自动创建临时文件搜索存储，将本地代码库、文档作为研究上下文，实现基于私有数据的深度分析
2. 成本透明可控：--dry-run 提供事前成本估算，--max-cost 支持硬上限控制，避免意外支出
3. 多格式输出：支持 Markdown、HTML、PDF 导出，结构化目录输出（--output-dir）包含报告、元数据、引用来源，便于程序化处理
4. 智能轮询机制：自适应历史学习算法，根据过往研究完成时间动态调整轮询频率，平衡响应速度与 API 调用成本
5. 通用兼容：不依赖 Gemini CLI，通过标准 JSON 输出与双通道（stdout/stderr）设计，无缝集成 Claude Code、Amp、Codex 等 30+ AI 智能体

潜在局限

• 外部依赖：完全依赖 Google Gemini API，服务可用性受制于 Google 基础设施
• 成本累积：深度研究（--depth deep）可能产生较高费用（15-45 分钟研究时长）
• 文件限制：单文件 100MB 上限，二进制文件不支持上传
• T3 来源：个人开发者维护项目，虽通过 CLS A 级认证，但长期维护稳定性需用户自行评估

适合人群

• 需要快速理解大型代码库、技术文档的开发者
• 希望自动化研究报告生成的知识工作者
• 在 AI 智能体工作流中集成深度研究能力的工程师
• 对成本敏感、需要本地数据 RAG 支持的用户

常规风险

1. API 密钥泄露：需通过环境变量配置，避免硬编码
2. 本地状态文件：.gemini-research.json 存储于工作目录，共享环境可能暴露会话信息
3. 成本超支：深度模式可能产生意外费用，建议始终配合 --dry-run 与 --max-cost 使用
4. 数据出境：文件内容上传至 Google 云服务，敏感数据需评估合规性