核心用法
Deep Research Skill 是调用 Google Gemini Deep Research Agent 的通用型研究工具，无需 Gemini CLI 依赖。核心功能包括：
1. 深度研究查询：research.py start "question" 启动异步研究，支持多轮追问 (--follow-up)
2. RAG 文件 grounding：--context PATH 自动创建临时文件搜索存储，上传本地文档进行 grounding 研究
3. 成本预估：--dry-run 在运行前估算成本，避免意外支出
4. 结构化输出：--output-dir 生成包含报告、元数据、来源引用的完整目录结构
5. 自适应轮询：根据历史完成时间智能调整查询频率，减少 API 调用
显著优点
- Agent 原生设计：stdout 输出 JSON、stderr 输出人类可读格式，完美适配 Claude Code、Amp、Codex 等 30+ AI Agent
- 安全文件过滤：自动排除
.env、私钥、凭证文件；二进制文件被拒绝；构建目录被跳过 - 透明无混淆：纯 Python 源码，PEP 723 内联元数据，无二进制 blob、无遥测
- 智能成本管控：
--max-cost硬限制、--dry-run预估、--format html/pdf多格式输出 - 会话持久化：
.gemini-research.json本地状态管理，支持研究续接和存储清理
潜在缺点/局限性
- API 依赖：完全依赖 Google Gemini API 可用性，无离线降级方案
- 成本不确定性：成本估算为启发式（API 不返回 token 计数），可能与实际账单有偏差
- 文件上传风险：非 TTY 模式下自动跳过确认，恶意 Agent 可能滥用
--context上传敏感路径 - Python/uv 依赖：必须安装 uv 和 Python 环境，对纯 Node.js 环境不友好
- 研究深度固定：
quick/standard/deep三档预设，无法精细控制研究步数或 token 上限
适合人群
- AI Agent 开发者：需要结构化研究输出的自动化工作流
- 技术研究人员：代码库分析、架构审查、技术调研
- 知识工作者：需 grounding 本地文档的深度报告生成
- 成本敏感用户：希望预估和控制 API 支出的团队
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| 凭证泄露 | API Key 需通过环境变量传递 | 使用 `.env` 文件（skill 会自动排除上传），避免硬编码 |
| 文件意外上传 | `--context` 可能包含敏感文件 | 先用 `--dry-run` 预览，审查上传列表 |
| Agent 滥用 | 非交互模式自动确认 | 限制 Agent 文件系统访问范围，设置 `--max-cost` |
| 临时存储残留 | 崩溃可能导致 orphaned stores | 定期运行 `state.py gc` 清理 |
| API 成本失控 | 深度研究可能消耗大量 token | 始终先用 `--dry-run` 估算，设置 `--max-cost` 上限 |