🔬 Deep Research — 统一深度研究工具

双模式研究流水线：Claude 规划 → Gemini 执行 → Claude 验证。

依赖

依赖	用途	安装
`gemini` CLI	Lite 模式	见 github.com/google/gemini-cli
`google-genai`	Deep 模式	`pip install -r requirements.txt`
`python-dotenv`	.env 加载	可选，但推荐安装
`GEMINI_API_KEY`	API 认证	设置环境变量或写入 `.env`

模式选择

用户意图	模式	执行方式	耗时	输出质量
"深度研究/全面分析/深度调研"	Deep	Gemini Deep Research API	10-30min	完整研究报告+引用
"快速调研/初步看看/先出个草稿"	Lite	Gemini CLI	3-8min	研究草稿
"研究" (模糊)	询问用户选择	—	—	—

Stage 1: 规划（Claude，两种模式共用）

触发后的第一步：理解需求

阅读 references/research_methodology.md 后，与用户进行多轮对话：

1. 理解目标（1-2个问题）

"你的研究目标是什么？学习、投资决策、写报告、还是做方案？"

根据回答调整后续问题：

学习/好奇 → 问深度偏好和关注焦点
投资决策 → 问决策标准和约束条件
写报告 → 问受众和格式要求

2. 消化用户素材

用户可能提供：思路文档、讨论框架、参考资料、数据文件夹。

阅读所有素材
提取关键信息和约束
在提纲中体现用户的思路

3. 讨论并确认研究提纲（核心步骤）

生成结构化提纲并与用户讨论确认：

# 研究主题：{topic}

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

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

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

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

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

用户确认后保存为 {output_dir}/{slug}/outline.md，进入 Stage 2。

Stage 2: 执行

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}/

耗时 10-30 分钟
支持 file_search（自有数据）、多模态输入、流式输出
参数/用法详见 docs/guide.md

Lite Mode → Gemini CLI

使用 scripts/lite_research.sh：

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

耗时 3-8 分钟，草稿质量
使用模型：gemini-3-pro-preview（可配置）

异步通知（两种模式共用）

执行完成后，通过 cron(wake) 通知主 agent：

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

注意：Stage 2 耗时较长（最多30分钟），必须使用 sessions_spawn 后台执行。

Stage 3: 验证（仅 Deep Mode）

收到 wake 通知后：

读取完整报告
按 references/research_methodology.md 的质量标准审查：
- 源多样性和权威性
- 关键事实交叉验证
- 偏见和利益冲突评估
- 信息时效性
- 与用户提纲的覆盖度

如有遗漏/问题 → 用 --followup 在原会话上追问：

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

整合为最终报告

输出结构

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

gemini-deepresearch