Deep Research via Gemini CLI Extension

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 /scripts/:

| Script | Role | |--------|------| | start-research.js | Calls research_start, outputs JSON with research ID | | poll-research.js | Polls research_status every 5 min until done/timeout | | save-report.js | Calls 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.

请确认 Deep Research 参数：
① 研究主题：[用户描述]
   （将原样发给 Gemini，请确保表述清晰具体）
② 报告格式：
   - Comprehensive Research Report（推荐，最全面）
   - Executive Brief（精简版，1-2页）
   - Technical Deep Dive（技术深度分析）
③ 保存位置：~/ObsidianVault/Default/DeepResearch/
   （默认文件名：YYYYMMDD-.md，可自定义路径）
④ 轮询最大时长：40 分钟（5 分钟 × 8 次），超时后通知您手动处理
直接回复修改项，或"确认"以默认参数启动。

Step 2 — Create Task Temp Directory

mkdir -p /tmp/gemini-deep-research/_/

Write task.json:

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

Step 3 — Start Research

node /scripts/start-research.js /tmp/gemini-deep-research//

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

Step 4 — Write Background Poll Script

Write /poll.sh:

#!/bin/bash
set -euo pipefail
cd "$(dirname "$0")"
SKILL_DIR="/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

cd /tmp/gemini-deep-research//
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:

# Check done.flag or task.json status
cat /tmp/gemini-deep-research//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

| Format | Description | |--------|-------------| | Comprehensive Research Report | Full multi-section report with analysis and citations (default) | | Executive Brief | Condensed summary for decision-makers | | Technical Deep Dive | Detailed technical analysis |

File Naming

Default pattern: YYYYMMDD-.md

Error Handling

| Error | Cause | Resolution | |-------|-------|-----------| | API key not found | Key not configured | Guide to references/setup-guide.md step 4 | | 429 Too Many Requests | Free-tier key / quota exceeded | Requires paid key | | Research timed out | Took > 40 min | Check task.json, manually save if completed server-side | | MCP server spawn failed | Extension path wrong | Verify ~/.gemini/extensions/gemini-deep-research/ exists |

Temp Directory Structure

/tmp/gemini-deep-research/
  _/
    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
    .md     ← saved report

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