Gemini Deep Research#

Executes a full Deep Research workflow via the gemini-deep-research MCP extension, with background polling and automatic report saving. The workflow is non-blocking — the agent sets up the task and exits immediately while a background script handles polling.

---

Prerequisites#

See references/setup-guide.md. If any prerequisite is missing, inform the user and stop.

---

Scripts#

Three scripts in <skill>/scripts/:

ScriptRolestart-research.jsCalls research_start, outputs JSON with research IDpoll-research.jsPolls research_status every 5 min until done/timeoutsave-report.jsCalls research_save_report once status is completed

All scripts read/write task.json in the task's temp directory.

---

Workflow#

Step 1 — Pre-Flight Confirmation (one message, all parameters)#

Write in the user's current session language.

text

请确认 Deep Research 参数：

① 研究主题：[用户描述]
   （将原样发给 Gemini，请确保表述清晰具体）

② 报告格式：
   - Comprehensive Research Report（推荐，最全面）
   - Executive Brief（精简版，1-2页）
   - Technical Deep Dive（技术深度分析）

③ 保存位置：~/ObsidianVault/Default/DeepResearch/
   （默认文件名：YYYYMMDD-<slug>.md，可自定义路径）

④ 轮询最大时长：40 分钟（5 分钟 × 8 次），超时后通知您手动处理

直接回复修改项，或"确认"以默认参数启动。

Step 2 — Create Task Temp Directory#

bash

mkdir -p /tmp/gemini-deep-research/<YYMMDD-HHmm>_<sanitized-topic>/

Write task.json:

json

{
  "input": "研究主题",
  "format": "Comprehensive Research Report",
  "outputPath": "/home/node/ObsidianVault/Default/DeepResearch/<YYYYMMDD>-<slug>.md",
  "pollIntervalSeconds": 300,
  "maxPolls": 8,
  "createdAt": "<ISO timestamp>"
}

Step 3 — Start Research#

bash

node <skill>/scripts/start-research.js /tmp/gemini-deep-research/<task-dir>/

Parse stdout JSON for { status: "started", researchId: "v1_..." }. If status: "error", inform the user and abort.

Step 4 — Write Background Poll Script#

Write <task-dir>/poll.sh:

bash

#!/bin/bash
set -euo pipefail
cd "$(dirname "$0")"

SKILL_DIR="<skill>/scripts"
TASK_DIR="$(pwd)"

log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >> poll.log; }

log "Starting poll-research..."
node "$SKILL_DIR/poll-research.js" "$TASK_DIR" >> poll-out.log 2>&1
RESULT=$(cat <<< "$(node "$SKILL_DIR/poll-research.js" "$TASK_DIR")")

STATUS=$(echo "$RESULT" | node -pe "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).status")
log "Poll result: $STATUS"

if [[ "$STATUS" == "completed" ]]; then
  log "Research completed. Saving report..."
  node "$SKILL_DIR/save-report.js" "$TASK_DIR" >> save-out.log 2>&1
  SAVE_STATUS=$(node -pe "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).status" <<< "$(node "$SKILL_DIR/save-report.js" "$TASK_DIR")")
  log "Save result: $SAVE_STATUS"
  echo "$SAVE_STATUS"
elif [[ "$STATUS" == "timeout" ]]; then
  echo "timeout"
else
  echo "failed"
fi

Step 5 — Launch Background Process#

bash

cd /tmp/gemini-deep-research/<task-dir>/
nohup bash poll.sh > /dev/null 2>&1 &
echo "Background PID: $!"

Step 6 — Notify User#

"🔬 Deep Research 已启动\n\n主题：[topic]\n格式：[format]\n预计完成：2–15 分钟（视主题复杂度而定）\n\n轮询后台运行，完成后我会通知您。如超时（40 分钟）未完成，我会告知并提供手动检查方法。"

Step 7 — Completion#

When the user asks "is it done?" or when notified by a new session:

bash

# Check done.flag or task.json status
cat /tmp/gemini-deep-research/<task-dir>/task.json

On success:

"✅ Deep Research 完成！\n\n主题：[topic]\n报告：[outputPath]\n轮询次数：N\n\n已保存到 ObsidianVault，可在 DeepResearch/ 目录找到。"

On timeout:

"⏰ Deep Research 超时\n\n主题：[topic]\nResearch ID： v1_...\n\n该 ID 在 Google 侧仍可能已完成。可手动保存：\n```bash\nnode /scripts/save-report.js /tmp/gemini-deep-research//\n```\n\n或前往 https://notebooklm.google.com/ 查看。"

On failure:

"❌ Deep Research 失败\n\n原因：[error message]\n\n请检查 API Key 配置（ gemini extensions config gemini-deep-research）或查询 references/setup-guide.md。"

---

Report Formats#

FormatDescriptionComprehensive Research ReportFull multi-section report with analysis and citations (default)Executive BriefCondensed summary for decision-makersTechnical Deep DiveDetailed technical analysis

---

File Naming#

Default pattern: YYYYMMDD-<slug>.md

• YYYYMMDD = today's date
• <slug> = lowercase, spaces→hyphens, strip special chars
• Example: 20260325-iran-hormuz-strait-market-impact.md

---

Error Handling#

ErrorCauseResolutionAPI key not foundKey not configuredGuide to references/setup-guide.md step 4429 Too Many RequestsFree-tier key / quota exceededRequires paid keyResearch timed outTook > 40 minCheck task.json, manually save if completed server-sideMCP server spawn failedExtension path wrongVerify ~/.gemini/extensions/gemini-deep-research/ exists

---

Temp Directory Structure#

text

/tmp/gemini-deep-research/
  <YYMMDD-HHmm>_<topic>/
    task.json       ← task parameters + research ID
    progress.json    ← poll count, last poll time (updated by poll-research.js)
    poll.log        ← each poll attempt log
    poll-out.log    ← stdout from poll-research.js
    save-out.log    ← stdout from save-report.js
    error.log       ← errors
    done.flag       ← created on success
    <report>.md     ← saved report