核心用法
Deep Research Skill 是一个异步深度研究工具，通过 Google Gemini Interactions API 驱动，无需依赖 Gemini CLI。核心功能包括：
- 深度研究启动：
research.py start "研究问题"启动异步研究任务，支持--context上传本地文件进行 RAG 增强 - 智能轮询：自适应轮询机制根据历史完成时间动态调整查询间隔（2-120 秒），或选择固定梯度轮询
- 成本预估：
--dry-run模式输出 JSON 格式成本估算，支持--max-cost设置预算上限 - 结构化输出：
--output-dir生成包含报告、元数据、来源引用的完整目录结构，适合 AI 代理集成 - 文件搜索存储：
store.py管理持久化文档库，upload.py支持智能同步（基于哈希去重）
显著优点
| 优势 | 说明 |
|------|------|
| 通用代理兼容 | 原生支持 Claude Code、Amp、Codex、Gemini CLI 等 30+ AI 框架 |
| 本地 RAG 增强 | 自动上传文件至 Google 临时存储，研究完成后自动清理 |
| 透明成本管控 | 前置成本估算 + 运行时预算限制，避免意外账单 |
| 双输出模式 | stderr 富文本人机交互 / stdout 纯 JSON 程序消费 |
| 完全可审计 | Python 源码 + PEP 723 元数据，无二进制混淆、无遥测 |
| 智能状态管理 | `.gemini-research.json` 本地持久化会话状态，支持垃圾回收 |
潜在局限
- API 依赖：必须使用有效的 Google/Gemini API key，国内网络环境需额外配置
- 文件限制：单文件 100MB，36 种扩展名原生支持，二进制文件被拒绝
- 成本估算偏差：Gemini API 不返回精确 token 计数，估价为启发式推算
- 自动确认风险：非 TTY 模式下确认提示自动跳过，需严格限制代理文件系统权限
- PDF 输出依赖：需额外安装
weasyprint库
适合人群
- 需要深度调研的开发者、产品经理、研究人员
- 构建自动化研究管道的 AI 代理开发者
- 希望将 RAG 能力集成到现有工作流的团队
- 对 API 成本敏感、需要预算控制的企业用户
常规风险
| 风险类别 | 等级 | 说明 |
|----------|------|------|
| 凭证安全 | 低 | API key 仅通过环境变量读取，不记录、不落盘 |
| 数据隐私 | 中 | 文件上传至 Google 临时存储，默认自动删除；`--keep-context` 可延长保留 |
| 代理滥用 | 中 | 非交互模式下无确认门槛，需通过路径白名单或 `--dry-run` 前置审核 |
| 成本超支 | 低 | 多层防护：dry-run 预估、max-cost 硬限制、历史成本追踪 |
| 供应商锁定 | 中 | 深度绑定 Gemini API，切换成本较高 |
该工具在安全性设计上表现优异（全源码开放、凭证零持久化、操作可审计），适合生产环境部署，但建议在代理场景下配合路径访问控制使用。