gemini-deep-research

Gemini Deep Research

ブラウザー自動化（Playwright CDP）を通じて、Google の Gemini Deep Research で長文の調査クエリを実行します。出典引用付きの 40,000 文字以上の Markdown レポートを生成します。

自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある、パラメーターがずれている、または回避策が必要だった場合は、先送りせず、このファイルをすぐに修正してください。実際に再現できる問題がある場合にのみ更新してください。

前提条件

1. デバッグポート付き Chrome：--remote-debugging-port=9222 を指定して起動している必要があります
2. Gemini Advanced のサブスクリプション：デバッグ用 Chrome で gemini.google.com にログインしている必要があります
3. playwright-core：bun add -g playwright-core（またはプロジェクトローカルにインストール）
4. ランタイム：npx tsx を使用してください（bun run は使用しないでください）。Bun の CDP connectOverCDP はタイムアウトしますが、Node.js なら 1 秒未満で接続できます

Chrome を起動する（起動していない場合）

chrome-profiles プラグインの共有ポートスクリプトを使用してください（ブラウザールートの信頼できる唯一の情報源です）。このスクリプトは専用のプロファイルを固定します。これはデバッグポートに必要な Chrome 136 以降の仕様に対応するためです。また、down を実行すると、そのポートだけが確実に閉じられます。

CHROME_DEBUG_PROFILE="$HOME/.local/share/gemini-research-profile" \
  bash "$(cc-plugin-root chrome-profiles)/scripts/chrome-debug-port-control.sh" up

次に、そのウィンドウで https://gemini.google.com/app を開き、Gemini Advanced アカウントで一度ログインしてください。プロファイルにはログイン状態が保存され、再起動後も維持されます。終了したら … down を実行してください。

使用方法

CLI（直接実行）

# Health check — verify Chrome CDP + Gemini login
npx tsx {{skill_dir}}/scripts/research.ts --health

# Basic research (runs preflight automatically)
npx tsx {{skill_dir}}/scripts/research.ts "your research query"

# Save to specific file
npx tsx {{skill_dir}}/scripts/research.ts \
  --output /tmp/report.md \
  --timeout 45 \
  "comprehensive analysis of quantum computing error correction 2025-2026"

# Auto-save to directory (creates {date}-{slug}.md)
npx tsx {{skill_dir}}/scripts/research.ts \
  --output-dir ~/.claude/automation/gemini-deep-research/output \
  "your query"

# Without auto-confirming plan (lets you review first)
npx tsx {{skill_dir}}/scripts/research.ts --no-confirm "query"

プログラムから使用（インポート）

import { GeminiDeepResearchClient } from "{{skill_dir}}/scripts/client.js";

const client = new GeminiDeepResearchClient({
  cdpUrl: "http://127.0.0.1:9222",
  maxResearchTimeMs: 30 * 60 * 1000,
  autoConfirm: true,
  onProgress: (msg) => console.log(msg),
});

await client.init();
const result = await client.research("your query");
// result.report — full markdown report (40k+ chars)
// result.plan — research plan text
// result.completed — boolean
// result.durationMs — execution time
// result.shareLink — Gemini share URL (if Firecrawl enabled)
await client.close();

事前チェック

調査を実行するたびに、自動の事前ヘルスチェックが行われ、以下を確認します。

1. Chrome CDP に到達可能か（設定済みのポート）
2. ブラウザー接続（WebSocket 接続が成功すること）
3. Gemini ページが開いているか（gemini.google.com）
4. ログイン状態が正常か（サインイン画面が表示されていないこと）

いずれかのチェックに失敗すると、明確なエラーメッセージを表示して調査を中止します。スキップするには --no-preflight を使用してください。

自動化のフロー

Preflight (CDP + login check) → abort if unhealthy
    ↓
Chrome CDP:9222 → Navigate gemini.google.com/app
    ↓
Tools button → Deep Research drawer item → Active chip verification
    ↓
Type query (30ms/char) → Send button (or Enter fallback)
    ↓
Wait for research plan (~18-120s) → Extract plan text
    ↓
Auto-confirm "Start research" (or manual)
    ↓
Poll completion: mic button + text stability (5s intervals, 30min max)
    ↓
Extract report (longest .markdown element) → Optional share link + Firecrawl

デバッグプローブ

セレクターが機能しなくなった場合（Google による Gemini UI の更新時）は、プローブスクリプトを使用してください。

# Check Chrome connectivity
bun run {{skill_dir}}/scripts/probes/dom-inspector.ts status

# Test all selectors against live DOM
bun run {{skill_dir}}/scripts/probes/dom-inspector.ts selectors

# Full DOM inspection
bun run {{skill_dir}}/scripts/probes/dom-inspector.ts probe

# Monitor active research execution
bun run {{skill_dir}}/scripts/probes/research-monitor.ts confirm-and-monitor

# Check research completion + extract share link
bun run {{skill_dir}}/scripts/probes/share-link.ts status
bun run {{skill_dir}}/scripts/probes/share-link.ts extract

セレクターレジストリ

CSS セレクターはすべて scripts/selectors.ts にあります。Google が Gemini UI を更新した場合は、以下の手順を実行してください。

1. dom-inspector.ts selectors を実行して、機能しなくなったセレクターを特定します
2. dom-inspector.ts probe を実行して、現在の DOM を調査します
3. selectors.ts を新しいセレクターで更新します
4. dom-inspector.ts selectors で再テストします

セレクターの最終確認日：2026-03-13（Tools ボタン：現在は button.toolbox-drawer-button。aria-label は削除済み）

主要ファイル

ファイル	用途
scripts/research.ts	統合 CLI エントリーポイント
scripts/client.ts	GeminiDeepResearchClient クラス
scripts/selectors.ts	CSS セレクターレジストリ（フォールバック付き 13 グループ）
scripts/probes/dom-inspector.ts	DOM 調査（5 つのコマンド）
scripts/probes/research-monitor.ts	調査実行モニター
scripts/probes/share-link.ts	共有リンクの抽出

オプション一覧

オプション	デフォルト	説明
cdpUrl	http://127.0.0.1:9222	Chrome CDP エンドポイント
maxResearchTimeMs	1800000（30 分）	調査完了までの最大待機時間
pollIntervalMs	5000（5 秒）	完了状況を確認する頻度
autoConfirm	true	計画画面で「Start research」を自動クリック
enableFirecrawl	false	共有リンクを抽出し、Firecrawl でスクレイピング
firecrawlUrl	https://api.firecrawl.dev	公開 Firecrawl API のベース URL（キー不要）
--no-preflight	（事前チェックを実行）	調査前の自動ヘルスチェックをスキップ

完了の検出

調査の完了は、次の3つのシグナルで検出します。

1. マイクボタンが表示される — button[data-node-type="speech_dictation_mic_button"] が再び表示されます
2. レポートのテキストが500文字を超える — 最長の .markdown.markdown-main-panel 要素
3. テキストが安定する — テキストの長さが3回連続で同じになります（合計15秒）

完了後も、スピナーが残骸として表示され続けることがあります。主なシグナルはマイクボタンです。

実行後の振り返り

このスキルの実行後、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった指示またはエラーテーブルを修正してください。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーターテーブルを更新してください。
3. 回避策が必要でしたか？ — 別のフラグや追加手順など、その場で工夫する必要があった場合は、次回の呼び出しで同じ回避策が不要になるよう、この SKILL.md を更新してください。

実際に再現可能な問題がある場合にのみ更新してください。推測に基づく更新は避けてください。