核心用法
Deep Research Skill 是一套基于 Google Gemini API 的深度研究代理工具，通过异步 Interactions API 实现无需等待的长时研究任务。核心工作流程为：启动研究（research.py start）→ 自适应轮询等待 → 获取结构化报告。支持三种研究深度（quick/standard/deep，耗时 2-45 分钟），可直接上传本地文件（--context）自动创建临时文件搜索存储实现 RAG 增强，也可绑定持久化 store 进行定向知识库问答。
文件管理方面，支持创建/查询/删除文件搜索存储（store.py），通过 upload.py 批量上传目录并支持 --smart-sync 哈希增量同步。36 种 MIME 类型原生支持，编程文件自动降级为 text/plain 处理，二进制文件被拒，单文件上限 100MB。
输出层面采用人机分离设计：stderr 输出富格式表格/进度条，stdout 输出纯 JSON 供程序消费。--output-dir 模式生成结构化目录（report.md + metadata.json + sources.json），特别针对 AI agent 优化，stdout 仅输出 500 字以内的紧凑 JSON 摘要。
显著优点
1. 零 CLI 依赖：直接调用 HTTP API，不依赖 Gemini CLI，兼容 Claude Code、Amp、Codex 等 30+ 代理
2. RAG 原生：--context 自动完成上传→创建临时 store→研究→清理的全生命周期，也可 --keep-context 保留
3. 成本可控：--dry-run 预估成本，--max-cost 硬上限，历史自适应轮询减少 API 调用频次
4. 全源码可审计：纯 Python + PEP 723 内联元数据，无混淆、无遥测、无二进制 blob
5. 智能轮询：基于历史完成时间分布（p25-p75 区间）动态调整轮询间隔，兼顾响应速度与 API 配额
6. 结构化集成：JSON Schema 友好的输出，agent 可无缝解析研究状态与结果
潜在缺点与局限性
- 成本不透明：Gemini API 不返回精确 token 计数，成本估算为启发式推算，存在偏差
- 文件泄露风险：
--context将本地文件上传至 Google 云端临时存储，虽自动清理且遵守 .gitignore，但敏感文件需人工审查 - 非交互模式风险：TTY 检测自动跳过确认提示，若代理权限过大可能在无确认下触发文件上传
- 轮询硬性上限：超时默认 30 分钟，深度研究可能失败；虽可
--timeout 3600延长，但超长任务无 webhook 回调机制 - PDF 依赖外部：PDF 输出需额外安装 weasyprint，非开箱即用
- 模型锁定：深度研究代理标识符
deep-research-pro-preview-12-2025为硬编码预览版，生产稳定性待验证
适合人群
- 需要深度研究报告的 AI 代理开发者（Claude Code、Codex、Amp 等集成场景）
- 处理大型代码库分析的技术 lead / 安全审计人员
- 需要将本地文档与联网搜索结合的 RAG 用户
- 对成本敏感、需要预估算和上限控制的自动化流水线
常规风险
1. API 密钥泄露：需配置 GOOGLE_API_KEY/GEMINI_API_KEY，虽声明不记录，但环境变量管理不善仍存在泄露面
2. 意外文件上传：--context 若指向根目录可能上传过量数据，建议始终配合 --dry-run 预览
3. 临时存储残留：崩溃或强制终止可能导致 .gemini-research.json 中记录 orphaned store，需定期 state.py gc
4. 计费失控：深度研究 + 大文件上下文可能产生意外高费用，--max-cost 为必要安全阀
5. 供应链风险：依赖 uv 与 google-genai SDK，需保持更新以应对 API 变更