异步深度研究通过Gemini Interactions API（不依赖Gemini CLI）。在本地文件（–context）上进行RAG-ground查询，预览成本（–dry-run），结构化JSON输出，自适应轮询。适用于30多个AI代理，包括Claude Code、Amp、Codex和Gemini CLI。许可证：MIT 兼容性：需要uv（https://docs.astral.sh/uv/）和GOOGLE_API_KEY、GEMINI_API_KEY或GEMINI_DEEP_RESEARCH_API_KEY中的一个。需要访问Google Gemini API。–context标志将本地文件上传到Google的临时文件搜索存储（除非使用–keep-context，否则研究完成后自动删除）。允许的工具：Bash(uv:) Bash(python3:) 读取元数据：版本：“2.0.1” 作者：“24601” clawdis：主环境：“GOOGLE_API_KEY” 首页：“https://github.com/24601/agent-deep-research” 需要：二进制： - “uv” 环境： - “GOOGLE_API_KEY” - “GEMINI_API_KEY” - “GEMINI_DEEP_RESEARCH_API_KEY” 安装： - 类型：“uv” 标签：“uv (Python包运行器)” 包：“uv” clawdbot：表情：“🔬” 类别：“研究” 配置：必需环境： - “GOOGLE_API_KEY” 示例：“export GOOGLE_API_KEY=‘your-key-from-aistudio.google.com’”

深度研究技能

通过Google Gemini的深度研究代理进行深度研究。上传文件到文件搜索存储以获得RAG-grounded答案。管理具有持久工作区状态的研究会议。

针对AI代理

获取完整的能力清单、决策树和输出合同：

uv run {baseDir}/scripts/onboard.py --agent

查看AGENTS.md以获取完整的结构化简报。

命令	它的作用
`uv run {baseDir}/scripts/research.py start "问题"`	启动深度研究
`uv run {baseDir}/scripts/research.py start "问题" --context ./path --dry-run`	估计成本
`uv run {baseDir}/scripts/research.py start "问题" --context ./path --output report.md`	RAG-grounded研究
`uv run {baseDir}/scripts/store.py query <name> "问题"`	对上传的文档进行快速问答

安全与透明度

凭证：此技能需要Google/Gemini API密钥（GOOGLE_API_KEY、GEMINI_API_KEY或GEMINI_DEEP_RESEARCH_API_KEY中的一个）。密钥从环境变量中读取，并传递给google-genai SDK。它永远不会被记录、写入文件或传输到Google Gemini API之外的任何地方。

文件上传：--context标志将本地文件上传到Google的临时文件搜索存储以进行RAG grounding。文件按MIME类型过滤（拒绝二进制文件），除非指定--keep-context，否则临时存储在研究完成后自动删除。使用--dry-run预览将要上传的内容，而不会发送任何内容。只有你明确指向--context的文件才会被上传——不会自动扫描父目录或主文件夹。

非交互模式：当stdin不是TTY（代理/CI使用）时，确认提示会自动跳过。这是为了代理集成而设计的，但这意味着具有文件系统访问权限的自主代理可能会触发上传。限制代理可以访问的路径，或使用--dry-run和--max-cost保护。

无混淆：所有代码都是可读的Python，带有PEP 723内联元数据。没有二进制blob、没有压缩脚本、没有遥测、没有分析。完整的源代码可以在github.com/24601/agent-deep-research进行审计。

本地状态：研究会议状态写入工作目录中的.gemini-research.json。此文件包含交互ID、存储映射和上传哈希——没有凭证或研究内容。使用state.py gc清理崩溃运行中的孤立存储。

先决条件

一个Google API密钥（GOOGLE_API_KEY或GEMINI_API_KEY环境变量）
安装uv（参见uv安装文档）

快速开始

# 运行深度研究查询
uv run {baseDir}/scripts/research.py "量子计算的最新进展是什么？"

# 检查研究状态
uv run {baseDir}/scripts/research.py status <交互ID>

# 保存完成的报告
uv run {baseDir}/scripts/research.py report <交互ID> --output report.md

# 基于本地文件的研究（自动创建存储、上传、清理）
uv run {baseDir}/scripts/research.py start "认证工作方式如何？" --context ./src --output report.md

# 导出为HTML或PDF
uv run {baseDir}/scripts/research.py start "分析API" --context ./src --format html --output report.html

# 基于上下文文件自动检测提示模板
uv run {baseDir}/scripts/research.py start "认证工作方式如何？" --context ./src --prompt-template auto --output report.md

环境变量

设置以下之一（按优先级顺序检查）：

变量	描述
`GEMINI_DEEP_RESEARCH_API_KEY`	此技能的专用密钥（最高优先级）
`GOOGLE_API_KEY`	标准Google AI密钥
`GEMINI_API_KEY`	Gemini特定密钥

可选模型配置：

变量	描述	默认值
`GEMINI_DEEP_RESEARCH_MODEL`	文件搜索查询的模型	`gemini-3.1-pro-preview`
`GEMINI_MODEL`	回退模型名称	`gemini-3.1-pro-preview`
`GEMINI_DEEP_RESEARCH_AGENT`	深度研究代理标识符	`deep-research-pro-preview-12-2025`

研究命令

开始研究

uv run {baseDir}/scripts/research.py start "你的研究问题"

标志	描述
`--report-format FORMAT`	输出结构：`executive_summary`、`detailed_report`、`comprehensive`
`--store STORE_NAME`	在文件搜索存储中进行研究（显示名称或资源ID）
`--no-thoughts`	隐藏中间思考步骤
`--follow-up ID`	继续以前的研究会议
`--output FILE`	等待完成并将报告保存到单个文件
`--output-dir DIR`	等待完成并将结构化结果保存到目录（见下文）
`--timeout SECONDS`	轮询时的最大等待时间（默认：1800 = 30分钟）
`--no-adaptive-poll`	禁用历史自适应轮询；改用固定间隔曲线
`--context PATH`	从文件或目录自动创建临时存储以进行RAG-grounded研究
`--context-extensions EXT`	按扩展名过滤上下文上传（例如`py,md`或`.py .md`）
`--keep-context`	研究完成后保留临时上下文存储（默认：自动删除）
`--dry-run`	估计成本而不启动研究（打印JSON成本估计）
`--format {md,html,pdf}`	报告的输出格式（默认：md；pdf需要weasyprint）
`--prompt-template {typescript,python,general,auto}`	特定于领域的提示前缀；自动从上下文文件扩展名检测
`--depth {quick,standard,deep}`	研究深度：快速（约2-5分钟）、标准（约5-15分钟）、深入（约15-45分钟）
`--max-cost USD`	如果估计成本超过此限制则中止（例如`--max-cost 3.00`）
`--input-file PATH`	从文件而不是位置参数读取研究查询
`--no-cache`	跳过研究缓存并强制重新运行

start子命令是默认的，所以research.py "问题"和research.py start "问题"是等效的。

检查状态

uv run {baseDir}/scripts/research.py status <交互ID>

返回当前状态（in_progress、completed、failed）和可用的输出。

保存报告

uv run {baseDir}/scripts/research.py report <交互ID>

标志	描述
`--output FILE`	将报告保存到特定文件路径（默认：`report-<id>.md`）
`--output-dir DIR`	将结构化结果保存到目录

结构化输出（`--output-dir`）

当使用--output-dir时，结果被保存到结构化目录：

<output-dir>/
  research-<id>/
    report.md          # 完整的最终报告
    metadata.json      # 计时、状态、输出计数、大小
    interaction.json   # 完整的交互数据（所有输出、思考步骤）
    sources.json       # 提取的源URL/引用

打印到stdout的紧凑JSON摘要（少于500个字符）：

{
  "id": "interaction-123",
  "status": "completed",
  "output_dir": "research-output/research-interaction-1/",
  "report_file": "research-output/research-interaction-1/report.md",
  "report_size_bytes": 45000,
  "duration_seconds": 154,
  "summary": "报告的前200个字符..."
}

这是AI代理集成的推荐模式——代理接收一个小JSON负载，而完整的报告被写入磁盘。

自适应轮询

当使用--output或--output-dir时，脚本会轮询Gemini API直到研究完成。默认情况下，它使用历史自适应轮询，从过去的研究完成时间中学习：

完成时间记录在.gemini-research.json下的researchHistory（最后50条条目，针对有基础和无基础研究分别有不同的曲线）。
当存在3个以上匹配的数据点时，轮询间隔会根据历史分布进行调整：
- 在任何研究完成之前：慢速轮询（30s）
- 在可能的完成窗口（p25-p75）：积极轮询（5s）
- 在尾部（过去p75）：适度轮询（15-30s）
- 异常长运行时间（过去最长的1.5倍）：慢速轮询（60s）
所有间隔都限制在[2s, 120s]之间作为故障保护。

当历史数据不足（<3个数据点）或传递--no-adaptive-poll时，使用固定的逐步升级曲线：5s（前30s）、10s（30s-2min）、30s（2-10min）、60s（10min+）。

成本估计（`--dry-run`）

在运行研究之前预览估计成本：

uv run {baseDir}/scripts/research.py start "分析安全架构" --context ./src --dry-run

将JSON成本估计输出到stdout，包括上下文上传成本、研究查询成本和总计。估计基于启发式（Gemini API不返回令牌计数或计费数据），并清楚地标记为如此。

研究完成后使用--output-dir，metadata.json文件包括一个usage键，包含基于实际输出大小和持续时间的运行后成本估计。

文件搜索存储命令

管理RAG-grounded研究和Q&A的文件搜索存储。

创建存储

uv run {baseDir}/scripts/store.py create "我的项目文档"

列出存储

uv run {baseDir}/scripts/store.py list

查询存储

uv run {baseDir}/scripts/store.py query <存储名称> "认证模块的作用是什么？"

标志	描述
`--output-dir DIR`	将响应和元数据保存到目录

删除存储

uv run {baseDir}/scripts/store.py delete <存储名称>

使用--force跳过确认提示。当stdin不是TTY（例如，由AI代理调用）时，提示自动跳过。

文件上传

将文件或整个目录上传到文件搜索存储。

uv run {baseDir}/scripts/upload.py ./src fileSearchStores/abc123

标志	描述
`--smart-sync`	跳过未更改的文件（哈希比较）
`--extensions EXT [EXT ...]`	包括的文件扩展名（逗号或空格分隔，例如`py,ts,md`或`.py .ts .md`）

哈希缓存总是在成功上传后保存，因此即使第一次上传没有使用--smart-sync，后续的--smart-sync运行也会正确跳过未更改的文件。

MIME类型支持

Gemini文件搜索API原生支持36个文件扩展名。常见的编程文件（JS、TS、JSON、CSS、YAML等）通过回退机制自动以text/plain上传。拒绝二进制文件。参见references/file_search_guide.md了解完整列表。

文件大小限制：每个文件100MB。

会话管理

研究ID和存储映射缓存在当前工作目录的.gemini-research.json中。

显示会话状态

uv run {baseDir}/scripts/state.py show

仅显示研究会议

uv run {baseDir}/scripts/state.py research

仅显示存储

uv run {baseDir}/scripts/state.py stores

代理的JSON输出

向任何状态子命令添加--json以将结构化JSON输出到stdout：

uv run {baseDir}/scripts/state.py --json show
uv run {baseDir}/scripts/state.py --json research
uv run {baseDir}/scripts/state.py --json stores

清除会话状态

uv run {baseDir}/scripts/state.py clear

使用-y跳过确认提示。当stdin不是TTY（例如，由AI代理调用）时，提示自动跳过。

非交互模式

所有确认提示（store.py delete、state.py clear）在stdin不是TTY时自动跳过。这允许AI代理和CI管道调用这些命令而不会因交互提示而挂起。

工作流程示例

典型的基于基础的研究工作流程：

# 1. 创建文件搜索存储
STORE_JSON=$(uv run {baseDir}/scripts/store.py create "Project Codebase")
STORE_NAME=$(echo "$STORE_JSON" | python3 -c "import sys,json; print(json.load(sys.stdin)['name'])")

# 2. 上传你的文档
uv run {baseDir}/scripts/upload.py ./docs "$STORE_NAME" --smart-sync

# 3. 直接查询存储
uv run {baseDir}/scripts/store.py query "$STORE_NAME" "认证如何处理？"

# 4. 开始基于基础的深度研究（阻塞，保存到目录）
uv run {baseDir}/scripts/research.py start "分析安全架构" \
  --store "$STORE_NAME" --output-dir ./research-output --timeout 3600

# 5. 或者开始非阻塞并在稍后检查
RESEARCH_JSON=$(uv run {baseDir}/scripts/research.py start "分析安全架构" --store "$STORE_NAME")
RESEARCH_ID=$(echo "$RESEARCH_JSON" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# 6. 检查进度
uv run {baseDir}/scripts/research.py status "$RESEARCH_ID"

# 7. 完成后保存报告
uv run {baseDir}/scripts/research.py report "$RESEARCH_ID" --output-dir ./research-output

输出约定

所有脚本遵循双输出模式：

stderr：富格式化的人类可读输出（表格、面板、进度条）
stdout：机器可读的JSON，用于程序消费

这意味着2>/dev/null隐藏了人类输出，并且将stdout管道输出可以给出干净的JSON。