deep-research

深度研究技能

借助 Google Gemini 的深度研究 Agent 开展深度研究。将文档上传到文件搜索存储，以获取基于 RAG 的回答。通过持久化工作区状态管理研究会话。

面向 AI Agent

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

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

完整的结构化简介请参阅 AGENTS.md。

命令	功能
uv run {baseDir}/scripts/research.py start "question"	启动深度研究
uv run {baseDir}/scripts/research.py start "question" --context ./path --dry-run	估算费用
uv run {baseDir}/scripts/research.py start "question" --context ./path --output report.md	开展基于 RAG 的研究
uv run {baseDir}/scripts/store.py query <name> "question"	针对已上传文档进行快速问答

安全与透明度

凭据：此技能需要 Google/Gemini API 密钥（GOOGLE_API_KEY、GEMINI_API_KEY 或 GEMINI_DEEP_RESEARCH_API_KEY 之一）。密钥从环境变量中读取，并传递给 google-genai SDK。密钥绝不会被记录、写入文件，也不会发送到 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 明确指定的文件，不会自动扫描父目录或主目录。

非交互模式：当 stdin 不是 TTY（Agent/CI 场景）时，系统会自动跳过确认提示。这是为 Agent 集成而设计的，但也意味着拥有文件系统访问权限的自主 Agent 可能会触发上传。请限制 Agent 可访问的路径，或使用 --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

环境变量

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

变量	说明
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	深度研究 Agent 标识符	deep-research-pro-preview-12-2025

研究命令

开始研究

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

标志	描述
--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 的研究
--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}	特定领域的提示词前缀；auto 会根据上下文文件扩展名自动检测
--depth {quick,standard,deep}	研究深度：quick（约 2-5 分钟）、standard（约 5-15 分钟）、deep（约 15-45 分钟）
--max-cost USD	如果预估费用超出此限额，则中止（例如 --max-cost 3.00）
--input-file PATH	从文件读取研究问题，而不是使用位置参数
--no-cache	跳过研究缓存并强制重新运行

start 子命令是默认子命令，因此 research.py "question" 与 research.py start "question" 等效。

重要：使用 --output 或 --output-dir 时，命令会一直阻塞，直到研究完成（2-10 分钟以上）。不要使用 & 将其置于后台。若要以非阻塞模式运行（省略 --output），可立即获取 ID，然后使用 status 轮询，并使用 report 保存报告。

检查状态

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

返回当前状态（in_progress、completed、failed），并在有输出时一并返回。

保存报告

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

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

结构化输出（--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 Agent 集成的推荐模式——Agent 会收到较小的 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 "Analyze security architecture" --context ./src --dry-run

将 JSON 成本估算输出到 stdout，其中包含上下文上传成本、研究查询成本和总成本。估算基于启发式方法（Gemini API 不会返回 token 数量或账单数据），并会明确标注为估算值。

使用 --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?"

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

删除存储

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

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

文件上传

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

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 File Search 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

面向 Agent 的 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 Agent 调用），会自动跳过提示。

非交互模式

当 stdin 不是 TTY 时，所有确认提示（store.py delete、state.py clear）都会自动跳过。这样，AI Agent 和 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

输出约定

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

• stderr：使用 Rich 格式呈现的人类可读输出（表格、面板、进度条）
• stdout：供程序处理的机器可读 JSON

因此，2>/dev/null 会隐藏人类可读输出，而通过管道传递 stdout 则会得到干净的 JSON。