gemini-deep-research

Gemini Deep Research

通过浏览器自动化（Playwright CDP）运行 Google Gemini Deep Research 长篇研究查询。生成包含来源引用、字符数超过 40k 的 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 插件中的共享端口脚本（浏览器路由的 SSoT）。该脚本会固定使用单独的配置文件，这是 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 min)	等待研究完成的最长时间
pollIntervalMs	5000 (5s)	检查是否完成的频率
autoConfirm	true	自动点击计划中的 "Start research"
enableFirecrawl	false	提取分享链接并通过 Firecrawl 抓取
firecrawlUrl	https://api.firecrawl.dev	公开的 Firecrawl API 基础 URL（无需密钥）
--no-preflight	（运行预检）	跳过研究开始前的自动健康检查

完成检测

通过以下三个信号检测研究是否完成：

1. 麦克风按钮可见 — button[data-node-type="speech_dictation_mic_button"] 重新出现
2. 报告文本超过 500 个字符 — 最长的 .markdown.markdown-main-panel 元素
3. 文本稳定 — 连续 3 次文本长度相同（总计 15 秒）

完成后，加载动画可能仍会作为过时的残留元素显示 — 麦克风按钮是主要信号。

执行后反思

此技能完成后，在关闭前检查：

1. 命令是否成功？ — 如果没有，修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生变化，请更新 Usage 示例和 Parameters 表，使其保持一致。
3. 是否需要变通处理？ — 如果你不得不临时变通（使用不同的标志、增加额外步骤），请更新此 SKILL.md，避免下次调用时再次需要相同的变通处理。

仅当问题真实存在且可复现时才更新 — 不要针对推测性问题进行更新。