名称： deep-research
描述： "通过 Gemini Interactions API 进行异步深度研究（无需依赖 Gemini CLI）。基于本地文件进行 RAG 查询（--context）、预估成本（--dry-run）、输出结构化 JSON、自适应轮询。适用于 30+ AI 代理的通用技能，包括 Claude Code、Amp、Codex 和 Gemini CLI。"
许可证： MIT
compatibility: "需要 uv 以及 GOOGLE_API_KEY / GEMINI_API_KEY / GEMINI_DEEP_RESEARCH_API_KEY 其中之一。可选环境变量用于模型配置：GEMINI_DEEP_RESEARCH_AGENT, GEMINI_DEEP_RESEARCH_MODEL, GEMINI_MODEL。需能访问 Google Gemini API 网络。--context 会将本地文件上传至临时存储（自动删除）。"
允许工具： "Bash(uv:) Bash(python3:) Read"
元数据：
version: "2.1.2"
author: "24601"
clawdbot:
emoji: "🔬"
category: "research"
primaryEnv: "GOOGLE_API_KEY"
homepage: "https://github.com/24601/agent-deep-research"
requires:
bins:
- "uv"
env:
- "GOOGLE_API_KEY"
- "GEMINI_API_KEY"
- "GEMINI_DEEP_RESEARCH_API_KEY"
- "GEMINI_DEEP_RESEARCH_AGENT"
- "GEMINI_DEEP_RESEARCH_MODEL"
- "GEMINI_MODEL"
install:
- kind: "uv"
label: "uv (Python 包运行器)"
package: "uv"
config:
requiredEnv:
- "GOOGLE_API_KEY"
- "GEMINI_API_KEY"
- "GEMINI_DEEP_RESEARCH_API_KEY"
example: "export GOOGLE_API_KEY=your-key-from-aistudio.google.com"

Deep Research 技能

利用 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-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 的文件会被上传——不会自动扫描父目录或主文件夹。

非交互模式：当标准输入不是 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 安装文档）

快速开始

# 运行深度研究查询
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

环境变量

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

可选模型配置：

研究命令

启动研究

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

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

重要提示：当使用 --output 或 --output-dir 时，命令会阻塞直到研究完成（2-10+ 分钟）。请勿使用 & 将其放入后台。使用非阻塞模式（省略 --output）可立即获取 ID，然后使用 status 轮询并使用 report 保存。

检查状态

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

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

保存报告

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

结构化输出 (--output-dir)

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

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

一个紧凑的 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 个或更多匹配数据点时，轮询间隔会根据历史分布进行调整：
• 在任何研究完成之前：慢速轮询（30秒）
• 在可能的完成窗口内（p25-p75）：积极轮询（5秒）
• 在尾部（超过 p75）：中等轮询（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 "分析安全架构" --context ./src --dry-run

将 JSON 成本估算输出到标准输出，包括上下文上传成本、研究查询成本和总计。估算是基于启发式的（Gemini API 不返回令牌计数或计费数据），并明确标记为估算。

研究完成后，如果使用了 --output-dir，metadata.json 文件中的 usage 键会包含基于实际输出大小和持续时间的运行后成本估算。

文件搜索存储命令

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

创建存储

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

列出存储

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

查询存储

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

删除存储

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

使用 --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 输出到标准输出：

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 跳过确认提示。当标准输入不是 TTY 时（例如，由 AI 代理调用），提示会自动跳过。

非交互模式

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

工作流示例

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

# 1. 创建文件搜索存储
STORE_JSON=$(uv run {baseDir}/scripts/store.py create "项目代码库")
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 会隐藏人类输出，而管道传输标准输出会得到干净的 JSON。