Deep Research (Gemini)

核心功能

Deep Research Skill 是一个围绕 Google Gemini Deep Research Agent 构建的命令行研究工具，无需安装 Gemini CLI 即可调用 Google 的异步深度研究能力。其核心用法包括：启动研究查询、基于本地文件的 RAG 增强研究、实时状态监控、以及多格式报告导出。

该工具设计为AI 代理原生友好，所有命令均遵循 stderr 输出人类可读内容、stdout 输出机器可读 JSON 的双输出模式，便于 Claude Code、Amp、Codex 等 30+ 代理集成。

显著优点

1. RAG 原生支持：通过 --context 自动创建临时文件搜索存储，将代码库、文档目录作为研究上下文，无需手动预处理
2. 智能成本管理：--dry-run 提供研究前成本预估，避免意外支出；自适应轮询根据历史完成时间动态调整 API 调用频率
3. 结构化输出：--output-dir 生成标准化目录结构（report.md/metadata.json/sources.json），专为自动化工作流设计
4. 会话持久化：.gemini-research.json 缓存研究 ID 和存储映射，支持跨命令会话续接
5. 非交互安全：自动检测 TTY，AI 代理调用时跳过确认提示，避免管道挂起

潜在局限

• 成本不可控：实际费用依赖 Gemini API 内部计费，预估仅为启发式估算
• 异步复杂性：研究完成时间从数分钟到数小时不等，需要轮询或回调机制
• PDF 依赖外部工具：PDF 导出需要额外安装 weasyprint
• 历史数据敏感：自适应轮询依赖本地 .gemini-research.json，删除后优化失效

适用场景

适合需要对大规模代码库、技术文档进行深度分析的开发团队，以及构建自动化研究管道的 AI 代理开发者。特别适合安全审计、架构评审、竞品分析等需要引用原始材料的场景。

常规风险

• API 密钥泄露风险（需妥善管理 GOOGLE_API_KEY）
• 长时运行任务可能因网络中断导致状态丢失
• 文件上传存在 100MB 单文件限制，大代码库需分批处理

核心用法

deep-research 是一套面向 AI 代理与开发者设计的 Gemini 深度研究工具链，提供异步研究执行、RAG 本地文件 grounding、成本预演及结构化输出。核心工作流包括：

1. 启动研究：uv run scripts/research.py start "问题" [--context ./路径] [--dry-run]
2. 状态监控：uv run scripts/research.py status <interaction-id>
3. 报告导出：支持 Markdown、HTML、PDF 格式，可通过 --output-dir 导出完整结构（含元数据、引用来源、思考过程）
4. 文件搜索存储：store.py 管理持久化 RAG 存储，upload.py 支持智能同步与扩展名过滤

关键特性：

• 零 CLI 依赖：直接调用 Gemini Interactions API，无需安装 Gemini CLI
• 自适应轮询：基于历史完成时间动态调整轮询间隔（2s-120s），平衡实时性与 API 成本
• 成本预演：--dry-run 输出 JSON 格式成本估算（启发式算法）
• 双输出模式：stderr 富文本人机界面，stdout 纯 JSON 供程序解析

显著优点

• 代理原生设计：输出契约明确，支持 30+ AI 代理（Claude Code、Amp、Codex 等）无缝集成
• RAG 完整闭环：从本地文件上传、自动建库、研究 grounding 到库清理/保留，一键完成
• 非交互安全：所有确认提示在 TTY 检测失败时自动跳过，适合 CI/CD 与自动化流水线
• 智能模板：--prompt-template auto 根据代码文件扩展名自动选择领域提示（TypeScript/Python/General）

潜在局限

• 外部依赖刚性：功能完全依赖 Google Gemini API，服务中断即失效；文件内容需出境至 Google 服务器
• 成本估算非精确：基于启发式算法，实际计费以 Google 账单为准
• Python 3.10+ 与 uv 强绑定：老旧环境或偏好其他包管理器的用户需额外适配
• PDF 导出额外依赖：需安装 weasyprint，非纯 Python 方案

适合人群

• AI 代理开发者（需要结构化、可预测的 research API）
• 需要快速对本地代码库进行深度分析的技术团队
• 追求"研究即代码"工作流的自动化工程师
• 对 Gemini 生态有既有 API Key 预算的组织

常规风险

• 数据出境：通过 --context 上传的文件及研究查询均发送至 Google 服务器，需评估合规要求
• API 密钥管理：需配置 GOOGLE_API_KEY/GEMINI_API_KEY 等环境变量，存在密钥泄露风险（建议最小权限+轮换）
• 持久化文件：.gemini-research.json 状态文件存储于工作目录，共享环境需注意隔离
• T3 来源：个人开发者维护，虽开源可审计，但生产环境关键任务建议代码审查后使用