Deep Research (Gemini)

核心功能

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 清理

核心用法

该 Skill 基于 Google Gemini 的深度研究代理（Deep Research Agent），为 AI 智能体提供异步研究能力。用户可通过 research.py start "问题" 启动研究任务，支持 --context 参数将本地文件上传至 Google 的临时文件搜索存储（File Search Store）进行 RAG grounding 检索。研究过程采用自适应轮询算法，根据历史完成时间动态调整查询频率（2-120 秒区间），支持 --output 或 --output-dir 保存结构化结果（含报告、元数据、引用来源）。

显著优点

1. 多智能体兼容：明确支持 Claude Code、Amp、Codex、Gemini CLI 等 30+ AI 代理，提供 AGENTS.md 结构化简报和 --agent onboarding 模式。
2. 成本可控：--dry-run 提供 JSON 格式的成本预估，--max-cost 支持硬上限中断，研究完成后 metadata.json 包含实际用量估算。
3. RAG 深度集成：自动创建临时存储、MIME 类型过滤（拒绝二进制文件）、--smart-sync 基于哈希跳过未变更文件，临时存储默认自动清理。
4. 输出友好：双输出模式（stderr 富文本 / stdout JSON），--output-dir 生成标准目录结构，特别适合 AI agent 集成——stdout 仅返回 <500 字符的 JSON 摘要。
5. 透明可信：PEP 723 内联元数据、纯 Python 实现、MIT 许可证、GitHub 完全开源，无遥测、无混淆代码。

潜在缺点与局限性

1. 外部 API 强依赖：核心功能完全依赖 Google Gemini API，网络中断或 API 限流将导致功能失效；数据需上传至 Google 云端处理，存在合规顾虑场景受限。
2. 凭证管理风险：API Key 通过环境变量读取（GOOGLE_API_KEY/GEMINI_API_KEY/GEMINI_DEEP_RESEARCH_API_KEY），虽实现规范，但用户配置不当可能导致泄露；无内置 credential helper 或子进程环境隔离。
3. 文件上传边界：虽拒绝二进制文件（.exe, .dll, .zip 等），但无客户端文件大小预检查（仅依赖 API 端 100MB 限制），无敏感文件模式警告（如 .env）。
4. 成本估算精度：--dry-run 为启发式估算，API 不返回 token 计数，实际费用可能与预估存在偏差。
5. Bash 权限范围：SKILL.md 申请 Bash(uv:*) 和 Bash(python3:*)，权限较宽泛，虽与功能匹配但存在潜在滥用面。

适合人群

• 开发者与研究员：需要基于代码库或文档进行深度技术分析（支持 TypeScript/Python/通用领域模板）。
• AI 智能体工作流：Claude Code、Codex 等代理用户，需结构化研究输出与程序化集成。
• 成本敏感用户：需预览研究成本、设置硬性预算上限的场景。

常规风险

• 数据出境：研究查询及 --context 文件内容上传至 Google 服务器，需评估数据合规性。
• 环境变量泄露：API Key 存储于环境变量，避免提交至版本控制或打印至日志。
• 临时存储残留：虽默认自动清理，但 --keep-context 或异常中断可能导致云端残留，需定期 state.py gc 清理。