核心用法
Deep Research Skill 是一个基于 Google Gemini 深度研究代理的异步研究工具，无需安装 Gemini CLI，仅通过 uv 运行 Python 脚本即可。核心功能包括：
1. 深度研究执行：research.py start "研究问题" 启动异步研究，支持自定义报告格式（executive_summary/detailed_report/comprehensive）、研究深度（quick/standard/deep）、输出格式（md/html/pdf）。
2. RAG 本地文件检索：通过 --context PATH 自动上传本地文件到 Google 临时文件搜索存储，实现基于自有文档的检索增强生成研究。文件按 MIME 类型过滤，二进制文件被拒绝，研究完成后自动清理临时存储。
3. 成本预估与预算控制：--dry-run 可预览预估成本（JSON 格式），--max-cost USD 设置成本上限自动中止。
4. 结构化输出：--output-dir 生成包含完整报告、元数据、交互数据、引用来源的结构化目录，适合 AI 代理集成。
5. 自适应轮询：基于历史研究完成时间的智能轮询策略，或固定间隔曲线，自动等待研究完成。
6. 文件搜索存储管理：store.py 子命令创建、列出、查询、删除文件搜索存储，支持智能同步上传（--smart-sync 基于哈希跳过未更改文件）。
显著优点
- 广泛兼容性：支持 30+ AI 代理（Claude Code、Amp、Codex、Gemini CLI 等），纯异步 API 设计，无需 CLI 依赖。
- 安全透明：API 密钥仅通过环境变量读取，绝不记录或写入文件；代码完全可读（PEP 723 内联元数据），无二进制混淆、无遥测。
- 灵活输出：双输出模式——stderr 富格式人类可读输出，stdout 机器可读 JSON，便于脚本集成。
- 智能成本控制：预估成本、实际成本追踪、预算上限三重保护。
- 非交互式友好：自动检测 TTY，无确认提示挂起，适合 CI/代理自动化。
潜在缺点与局限性
- 成本不可完全精确：预估为启发式计算，Gemini API 不返回实际 token 计数，可能与实际账单有偏差。
- PDF 输出依赖：需额外安装
weasyprint库。 - 文件大小限制：单个文件 100MB 上限，36 种原生 MIME 类型，其他文件通过
text/plain回退处理。 - 网络依赖：必须能访问 Google Gemini API，国内用户需考虑网络连通性。
- 代理风险：非交互模式下，具有文件系统访问权限的自主代理可能触发非预期的文件上传，需通过路径限制或
--dry-run防范。
适合人群
- 需要深度研究报告的开发者、研究员、技术写作者
- 希望在 AI 工作流中集成自动化研究能力的 AI 代理用户
- 需要基于私有代码库/文档进行 RAG 检索分析的团队
- 追求成本可控、输出结构化、可脚本化的自动化研究流程的用户
常规风险
- API 密钥泄露风险：虽然工具本身安全处理密钥，但用户需妥善保管环境变量，避免提交到版本控制。
- 文件上传隐私：
--context上传的文件暂存于 Google 云端，虽为临时存储且自动清理，但敏感数据仍需谨慎评估。 - 长时间运行任务：深度研究可能耗时 15-45 分钟，需合理设置
--timeout。 - 成本累积：未设置
--max-cost时，复杂研究可能产生意外费用。