深度研究技能

利用 Google Gemini 深度研究智能体进行深度研究。上传文档至文件搜索存储库以获取基于 RAG 的答案。通过持久化工作区状态管理研究会话。

面向 AI 智能体

获取完整的功能清单、决策树和输出契约：

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

请参阅AGENTS.md以获取完整的结构化简报。

安全与透明度

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

文件上传：--context标志会将本地文件上传到 Google 的临时文件搜索存储中，用于 RAG 基础。敏感文件会被自动排除：.env*、credentials.json、secrets.*、私钥（.pem、.key）和身份验证令牌.npmrc,.pypirc,.netrc）。二进制文件会因MIME类型过滤而被拒绝。构建目录（node_modules,__pycache__,.git,dist,build）会被跳过。临时存储在研究完成后会自动删除，除非指定了--keep-context。使用--dry-run可以预览将要上传的内容而无需实际发送任何数据。只有你明确指向--context的文件会被上传——不会自动扫描父目录或主文件夹。

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

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

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

先决条件

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

快速开始

# Run a deep research query
uv run {baseDir}/scripts/research.py "What are the latest advances in quantum computing?"

# Check research status
uv run {baseDir}/scripts/research.py status <interaction-id>

# Save a completed report
uv run {baseDir}/scripts/research.py report <interaction-id> --output report.md

# Research grounded in local files (auto-creates store, uploads, cleans up)
uv run {baseDir}/scripts/research.py start "How does auth work?" --context ./src --output report.md

# Export as HTML or PDF
uv run {baseDir}/scripts/research.py start "Analyze the API" --context ./src --format html --output report.html

# Auto-detect prompt template based on context files
uv run {baseDir}/scripts/research.py start "How does auth work?" --context ./src --prompt-template auto --output report.md

环境变量

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

可选的模型配置：

研究命令

开始研究

uv run {baseDir}/scripts/research.py start "your research question"

---start子命令是默认的，因此research.py "问题"和research.py start "问题"是等效的。

重要当使用--output或--output-dir参数时，命令会阻塞直到研究完成（2-10+分钟）。请不要使用&将其置于后台。要立即获取ID，请使用非阻塞模式（省略--output参数），然后通过status命令轮询状态，并使用report

命令保存结果。

uv run {baseDir}/scripts/research.py status <interaction-id>

检查状态返回当前状态（进行中、已完成、失败

）以及可用的输出。

uv run {baseDir}/scripts/research.py report <interaction-id>

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

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

<output-dir>/
  research-<id>/
    report.md          # Full final report
    metadata.json      # Timing, status, output count, sizes
    interaction.json   # Full interaction data (all outputs, thinking steps)
    sources.json       # Extracted source URLs/citations

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

{
  "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": "First 200 chars of the report..."
}

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

自适应轮询

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

• 完成时间记录在.gemini-research.json文件的researchHistory下（最近50条记录，区分了基于上下文的研究与非上下文研究）。
• 当存在3个或更多匹配的数据点时，轮询间隔会根据历史分布进行调整：
  • 在没有任何研究完成过之前：慢速轮询（30秒）
  • 在可能的完成窗口内（25%分位数到75%分位数）：积极轮询（5秒）
  • 在尾部（超过75%分位数）：中等轮询（15-30秒）
  • 对于异常长时间运行（超过历史最长记录的1.5倍）：慢速轮询（60秒）
• 所有间隔都被限制在[2秒, 120秒]范围内作为安全措施。

当历史数据不足（少于3个数据点）或传递了 --no-adaptive-poll 参数时，则使用固定的递增曲线：5秒（前30秒），10秒（30秒到2分钟），30秒（2到10分钟），60秒（10分钟以上）。

成本估算（--dry-run）

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

uv run {baseDir}/scripts/research.py start "Analyze security architecture" --context ./src --dry-run

向标准输出打印一个JSON格式的成本估算，包含上下文上传成本、研究查询成本和总计。这些估算是基于启发式方法的（Gemini API不返回令牌计数或计费数据），并已明确标注。

当研究完成并使用了--output-dir参数后，生成的metadata.json文件中会包含一个usage键，其中提供了基于实际输出大小和运行时长计算的事后成本估算。

文件搜索存储管理命令

管理用于RAG基础研究和问答的文件搜索存储。

创建存储

uv run {baseDir}/scripts/store.py create "My Project Docs"

列出存储

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

查询存储

uv run {baseDir}/scripts/store.py query <store-name> "What does the auth module do?"

删除存储

uv run {baseDir}/scripts/store.py delete <store-name>

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

文件上传

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

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

哈希缓存会在成功上传时始终保存，因此后续的--smart-sync运行将能正确跳过未更改的文件，即使首次上传未使用--smart-sync也是如此。

MIME 类型支持

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

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

会话管理

研究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代理调用），提示会自动跳过。

非交互模式

当标准输入不是TTY时，所有确认提示（store.py delete、state.py clear）会被自动跳过。这使得AI代理和CI流水线能够调用这些命令，而不会在交互式提示上卡住。

工作流程示例

一个典型的、基于事实的研究工作流程：

# 1. Create a file search store
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. Upload your documents
uv run {baseDir}/scripts/upload.py ./docs "$STORE_NAME" --smart-sync

# 3. Query the store directly
uv run {baseDir}/scripts/store.py query "$STORE_NAME" "How is authentication handled?"

# 4. Start grounded deep research (blocking, saves to directory)
uv run {baseDir}/scripts/research.py start "Analyze the security architecture" \
  --store "$STORE_NAME" --output-dir ./research-output --timeout 3600

# 5. Or start non-blocking and check later
RESEARCH_JSON=$(uv run {baseDir}/scripts/research.py start "Analyze the security architecture" --store "$STORE_NAME")
RESEARCH_ID=$(echo "$RESEARCH_JSON" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# 6. Check progress
uv run {baseDir}/scripts/research.py status "$RESEARCH_ID"

# 7. Save the report when completed
uv run {baseDir}/scripts/research.py report "$RESEARCH_ID" --output-dir ./research-output

输出约定

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

• 标准错误输出：富格式、人类可读的输出（表格、面板、进度条）
• 标准输出：机器可读的JSON，供程序化使用

这意味着2>/dev/null可以隐藏面向人类的输出，而管道传输标准输出则会得到干净的JSON。