gemini-deepresearch

🔬 Deep Research — Unified Deep Research Tool

Dual-mode research pipeline: Claude plans → Gemini executes → Claude verifies.

Dependencies

Dependency	Purpose	Installation
`gemini` CLI	Lite mode	See github.com/google/gemini-cli
`google-genai`	Deep mode	`pip install -r requirements.txt`
`python-dotenv`	.env loading	Optional, but recommended to install
`GEMINI_API_KEY`	API authentication	Set environment variables or write to `.env`

Mode selection

User intent	Mode	Execution method	Time required	Output quality
"Deep research/comprehensive analysis/in-depth investigation"	Deep	Gemini Deep Research API	10-30min	Complete research report + citations
"Quick research/preliminary look/produce a draft first"	Lite	Gemini CLI	3-8min	Research draft
"Research" (ambiguous)	Ask the user to choose	—	—	—

Stage 1: Planning (Claude, shared by both modes)

The first step after triggering: understand the requirements

After reading references/research_methodology.md , conduct multi-turn dialogue with the user:

1. Understand the goal (1-2 questions)

"What is your research goal? Learning, investment decision-making, writing a report, or making a plan?"

Adjust subsequent questions based on the answer:

Learning/curiosity → ask about depth preference and focus
Investment decision-making → ask about decision criteria and constraints
Writing a report → ask about audience and format requirements

2. Digest user materials

The user may provide: idea documents, discussion frameworks, reference materials, data folders.

Read all materials
Extract key information and constraints
Reflect the user's ideas in the outline

3. Discuss and confirm the research outline (core step)

Generate a structured outline and discuss and confirm it with the user:

# 研究主题：{topic}

## 研究目标
{由讨论确定}

## 核心研究问题
1. {问题1}
2. {问题2}
3. {问题3}

## 报告结构要求
### 1. {章节1}
- 重点关注：...
- 数据来源要求：...
### 2. {章节2}
...

## 质量标准
- 必须交叉验证的事实：...
- 信息时效要求：...

## 用户素材/约束
- {摘要}

After the user confirms, save it as {output_dir}/{slug}/outline.md, and proceed to Stage 2.

Stage 2: Execution

Deep Mode → Gemini Deep Research API

python {SKILL_DIR}/scripts/deep_research.py \
  "{topic}" \
  --outline {outline_path} \
  --data-dir {data_dir} \
  --attach {file1} --attach {file2} \
  --output {output_dir}/{slug}/

Takes 10-30 minutes
Supports file_search (own data), multimodal input, streaming output
For parameters/usage, see docs/guide.md

Lite Mode → Gemini CLI

Use scripts/lite_research.sh：

bash {SKILL_DIR}/scripts/lite_research.sh \
  --topic "{topic}" \
  --outline "{outline_path}" \
  --output "{output_dir}/{slug}/" \
  --model "{gemini_model}"

Takes 3-8 minutes, draft quality
Model used:gemini-3.1-pro-preview(configurable)

Asynchronous notification (shared by both modes)

After execution is complete, notify the main agent via cron(wake):

cron(
  action: 'wake',
  text: '🔬 研究完成: {topic}
  模式: {deep|lite}
  关键发现: {2-3 bullet points}
  报告路径: {output_path}',
  mode: 'now'
)

Note: Stage 2 takes a long time (up to 30 minutes), so sessions_spawn must be used for background execution.

Stage 3: Verification (Deep Mode only)

After receiving the wake notification:

Read the complete report
Review according to the quality standards of references/research_methodology.md :
- Source diversity and authority
- Cross-verification of key facts
- Assessment of bias and conflicts of interest
- Timeliness of information
- Coverage of the user's outline

If there are omissions/issues → use --followup to follow up in the original session:

python {SKILL_DIR}/scripts/deep_research.py \
  --followup {session_json} "请展开第二点的论据"

Integrate into the final report

Output structure

{output_dir}/{slug}/
├── outline.md                    # Stage 1 生成的研究提纲
├── {topic}_{ts}_report.md        # 研究报告（Deep/Lite）
├── {topic}_{ts}_report.session.json  # 会话文件（Deep，用于追问）
└── verification_notes.md         # 验证记录（Deep 可选）

About this skill