核心功能
Deep Research Skill 是一个调用 Google Gemini Interactions API 的异步深度研究工具，无需依赖 Gemini CLI。核心能力包括：
1. 异步深度研究：通过 research.py start 启动长时间运行的研究任务，支持自适应轮询（adaptive polling）根据历史完成时间优化查询频率，减少 API 调用次数。
2. RAG 本地文件检索：--context 参数可将本地文件自动上传至 Google 的临时文件搜索存储（ephemeral store），实现基于私有文档的检索增强生成。支持 36 种 MIME 类型，编程文件自动转 text/plain，二进制文件被拒绝。
3. 成本预估与管控：--dry-run 可在执行前输出 JSON 格式的成本估算；--max-cost 支持设定成本上限自动终止；完成后 metadata.json 包含基于实际输出的后验成本估算。
4. 结构化输出：--output-dir 生成包含 report.md、metadata.json、interaction.json、sources.json 的完整目录，适合 AI Agent 自动化处理。同时提供精简 JSON 摘要至 stdout。
5. 会话状态管理：.gemini-research.json 持久化研究 ID、存储映射和上传哈希，支持研究续接（--follow-up）和孤儿存储清理（state.py gc）。
显著优点
- Agent 原生设计：stdout 输出机器可读 JSON，stderr 输出富格式人类可读内容，完美适配 Claude Code、Codex、Amp 等 30+ AI Agent 的自动化调用
- 零二进制依赖：纯 Python 代码，PEP 723 内联元数据，无混淆、无遥测、可完整审计
- 安全透明：API Key 仅通过环境变量读取，绝不记录或写入文件；临时文件存储自动清理；所有确认提示在非 TTY 环境自动跳过
- 智能优化：历史自适应轮询算法基于过去 50 条完成记录动态调整查询间隔，显著降低等待期间的 API 消耗
潜在局限
- 供应商锁定：完全依赖 Google Gemini API，无备用 LLM 提供商支持
- 成本不可知性：Gemini API 不返回精确 token 计费数据，成本估算为启发式预测，可能存在偏差
- 文件上传限制：单文件 100MB 上限，二进制文件被拒绝，大规模代码库需分片处理
- 网络依赖：所有研究流程必须在线完成，无离线缓存或本地模型回退
适合人群
- AI Agent 开发者（Claude Code、Codex、Amp 等）需要可编程调用的深度研究后端
- 技术团队需要基于私有代码库或文档的 RAG 研究分析
- 研究人员需要生成结构化、带引用的长篇研究报告（支持 md/html/pdf 输出）
常规风险
- 凭证泄露风险：需配置
GOOGLE_API_KEY等环境变量，共享环境或 CI 配置需严格管控 - 意外文件上传：非交互模式下
--context自动上传指定路径文件，需限制 Agent 文件系统访问范围，或先用--dry-run验证 - 长时任务管理：深度研究可能耗时 15-45 分钟，超时或中断可能导致孤儿存储，需定期运行
state.py gc清理