Deep Research (Gemini)

Deep Research 技能评估

核心用法

Deep Research 是一个通过 Google Gemini Interactions API 实现异步深度研究的通用技能，无需安装 Gemini CLI。它提供完整的 RAG（检索增强生成）工作流：将本地文件上传至 Gemini 的临时文件搜索存储，基于文档内容进行深度研究，并以 Markdown、HTML 或 PDF 格式输出结构化报告。

主要命令包括：research.py start 启动研究（支持 --context 上传文件、--dry-run 成本预估、--output 阻塞等待结果）、status 检查进度、report 获取最终报告。配套工具涵盖 store.py（管理文件搜索存储）、upload.py（上传文档）和 state.py（会话状态管理）。

显著优点

1. Agent 原生设计：为非 TTY 环境自动跳过确认提示，输出 JSON 到 stdout、富格式到 stderr 的双通道设计，便于 AI 代理解析。
2. 智能轮询机制：历史自适应轮询根据过往研究完成时间动态调整查询频率，减少 API 调用同时保证响应速度。
3. 安全透明：API 密钥仅通过环境变量读取，绝不记录或外传；敏感文件（.env、密钥、token）自动排除上传；所有代码为可读 Python，无混淆或遥测。
4. 成本可控：--dry-run 预估费用，--max-cost 硬上限，研究完成后 metadata.json 包含实际成本估算。
5. 生态兼容：明确支持 Claude Code、Amp、Codex、Gemini CLI 等 30+ AI 代理。

潜在局限

• 阻塞模式风险：--output 或 --output-dir 会阻塞至研究完成（通常 2-45 分钟），脚本警告勿用 & 后台运行，但在 CI/Agent 场景中需合理设置 --timeout。
• 成本估算为启发式：基于输出大小和时长推算，非 Gemini API 返回的实际计费数据，存在偏差可能。
• 文件上传限制：单文件 100MB，36 种 MIME 类型原生支持，二进制文件被拒绝。
• 环境依赖：需 uv 运行时和有效 Google API 密钥，对网络环境有要求。

适合人群

• AI 代理/自动化工作流开发者
• 需要 RAG 增强研究的开发者、技术写作者、安全审计人员
• 希望在 Claude Code、Cursor 等环境中集成 Gemini 深度研究能力的用户

常规风险

• 凭证泄露：需妥善保管 GOOGLE_API_KEY 等环境变量，避免提交到版本控制。
• 非交互模式安全隐患：Agent 拥有文件系统访问权限时，可能自动触发 --context 上传，建议配合 --dry-run 审核或限制 Agent 路径权限。
• 临时存储残留：默认自动清理，但 --keep-context 或崩溃可能导致文件留存，需定期 state.py gc 清理。

核心功能

agent-deep-research 是一款面向 AI Agent 生态的深度研究技能，通过 Google Gemini Interactions API 实现异步深度研究，无需依赖 Gemini CLI。核心能力包括：

1. RAG 检索增强研究：通过 --context 自动上传本地文件至 Google 临时文件搜索存储，实现基于私有文档的研究问答
2. 成本预估机制：--dry-run 提供 JSON 格式的成本估算，支持 --max-cost 预算硬限制
3. 自适应轮询：基于历史完成时间智能调整轮询策略，优化 API 调用效率
4. 结构化输出：--output-dir 生成包含报告、元数据、引用来源的标准化目录结构
5. 多格式导出：支持 Markdown、HTML、PDF 输出（PDF 需 WeasyPrint）

显著优点

• Agent 原生设计：专为 Claude Code、Amp、Codex 等 30+ AI Agent 优化，非 TTY 模式下自动跳过交互提示
• 安全透明：纯 Python 实现（PEP 723 标准），无二进制混淆、无遥测、无分析追踪
• 完善的敏感文件过滤：自动排除 .env*、credentials.json、私钥（.pem/.key）、认证令牌等敏感文件
• 凭证管理规范：API 密钥仅通过环境变量读取，无硬编码、无日志记录
• SSR 防护：PDF 导出配置自定义 url_fetcher 阻止 URL 获取，防范 SSRF 攻击

潜在局限

• T3 来源风险：个人开发者（GitHub @24601）维护，需关注供应链安全更新
• 网络依赖：研究过程需持续调用 Google Gemini API，受限网络环境需额外配置
• 异步复杂：完整研究需 2-45 分钟，需理解阻塞/非阻塞模式差异
• 成本不确定性：预估为启发式计算，实际费用可能与预估存在偏差

适合人群

• AI Agent 开发者：需要为 Agent 接入结构化深度研究能力
• 技术调研人员：需要基于私有代码库或文档进行深度分析
• 安全审计团队：需要生成可审计的 HTML/PDF 研究报告
• 合规敏感场景：对数据外泄风险有严格控制需求的用户

常规风险

| 风险项 | 等级 | 说明 |

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

| API 密钥泄露 | 低 | 代码规范读取环境变量，但用户需自行保护 shell 历史记录 |

| 敏感文件上传 | 低 | 自动过滤机制完善，但仍建议 `--dry-run` 预览 |

| 临时存储残留 | 低 | 默认自动清理， `--keep-context` 需显式启用 |

| 供应链攻击 | 中 | T3 来源需关注上游仓库更新，建议 fork 后维护关键补丁 |

| 网络监听 | 低 | 全链路 TLS 1.3 加密，但数据发送至 Google 云端 |

> 综合评估：这是一款架构清晰、安全设计周到的专业研究工具，特别适合需要 RAG 增强的自动化研究场景。T3 来源是主要信任降级因素，建议生产环境使用前进行代码审计并建立更新审查机制。