Deep Research (Gemini)

核心用法

Deep Research Skill 是一个调用 Google Gemini Deep Research Agent 的命令行工具，通过异步 API 执行深度研究任务。核心工作流分为三类：

1. 基础研究

• research.py start "问题"：启动研究，返回交互 ID
• research.py status <id>：查询状态
• research.py report <id> --output report.md：保存报告

2. RAG 检索增强研究

• --context ./path：自动上传本地文件到临时存储，研究完成后自动清理
• --store <name>：使用持久化文件搜索存储
• store.py create/query/delete：管理文件存储

3. 结构化输出与集成

• --output-dir：生成包含 report.md、metadata.json、sources.json 的完整目录
• --json：所有命令支持机器可读 JSON 输出到 stdout
• 自适应轮询：基于历史完成时间动态调整查询频率

显著优点

• 零依赖部署：仅需 uv 和 API key，无 Gemini CLI 依赖
• 智能成本控制：--dry-run 预估成本，--max-cost 硬上限
• 安全设计：敏感文件自动排除（.env、私钥、token），二进制文件拒绝上传
• 代理友好：非 TTY 模式下自动跳过确认，结构化 JSON 输出，适合 Claude Code、Amp、Codex 等代理集成
• 透明可审计：纯 Python 源码，无混淆、无埋点，PEP 723 元数据

潜在局限

• 成本不确定性：费用估算为启发式算法，非精确计费
• API 依赖性：完全依赖 Google Gemini API 可用性
• 轮询开销：长时研究需持续 HTTP 轮询，默认 30 分钟超时可能不足
• 文件限制：单文件 100MB 上限，36 种 MIME 类型原生支持
• 无离线能力：必须联网调用 Gemini API

适合人群

• AI 代理/Agent 开发者（Claude Code、Codex、自定义代理）
• 需要批量文档分析的技术团队
• 研究人员需快速生成结构化报告
• CI/CD 流程中需自动化研究任务

常规风险

• API Key 泄露：需通过环境变量管理，代码中无硬编码但需确保执行环境安全
• 文件误上传：--context 可能意外包含敏感文件，虽有自动排除但仍需 --dry-run 确认
• 长时任务中断：研究可能持续 15-45 分钟（deep 模式），需合理设置 --timeout
• 成本超支：深度研究费用可能累积，建议始终使用 --max-cost 约束
• 临时存储残留：崩溃可能导致孤儿存储，需定期运行 state.py gc 清理