Voyager 上下文同步（Context Sync）：把 Gemini 网页会话「传输」到 VS Code 的实操指南

Voyager 上下文同步（Context Sync）：把 Gemini 网页会话「传输」到 VS Code 的实操指南

【免费下载链接】voyagerEnhancement suite for Gemini, AI Studio, Claude & ChatGPT — plus a prompt manager for any websites, DeepSeek Harness included. / 面向 Gemini、AI Studio、Claude 与 ChatGPT 的增强套件；其中的提示词管理器可用于任意网站，如 DeepSeek Harness。项目地址: https://gitcode.com/gh_mirrors/ge/voyager

传输记忆：上下文同步（实验性）是 Voyager 增强套件内置的一项实验性能力。它通过本地 IDE 中的 CoBridge 扩展作为桥梁，把你在 Gemini、AI Studio 等网页端已经讨论成熟的对话上下文——包括复杂的数据表格和参考图片——一键同步到 VS Code / Trae / Cursor 等本地编辑器中，让 IDE 中的 AI 助手（Copilot、Cursor、Trae 内置助手）无需重新解释需求即可直接继承网页端的「思考过程」。读完本文，你将掌握从安装 CoBridge、端口握手到一键同步的完整流程，并能结合源码理解其底层传输机制与可配置项。

为什么需要「上下文同步」：网页是大脑，IDE 是双手

开发者最头疼的场景之一：在 Gemini 网页端与 AI 长时间讨论一套解决方案后，回到 VS Code / Trae / Cursor，却要向本地 AI 重新解释一遍需求，仿佛面对一个陌生人。由于响应配额与速度的差异，网页端往往承担「思考」（brain）的职责，而 IDE 承担「执行」（hands）的职责。Voyager 的 Context Sync 让两者共享同一份「灵魂」——不再需要反复横跳标签页。

这一功能在仓库中的定位很清晰：前端设置界面位于 ContextSyncSettings.tsx，核心传输逻辑位于 SyncService.ts，页面内采集逻辑位于 content/contextSync，整体属于实验性特性（英文文案中亦标注为 "Context Sync"）。

三步完成同步：从安装到落地

第一步：安装并启动 CoBridge

CoBridge 是连接网页端与本地 IDE 的中央桥接扩展，需要在 VS Code 中安装。安装完成后，打开任意工作目录，点击右侧图标启动本地同步服务器。

启动服务器后，它会监听一个本地 HTTP 端口（默认 3030），用于接收来自浏览器扩展的数据。从源码看，这个端口既不是写死的魔法数字，也不是用户不可见的配置：

• 在 SyncService.ts 中定义了private readonly DEFAULT_PORT = 3030；
• 端口值通过chrome.storage.sync中的contextSyncPort键读取，取不到时回退到默认值 3030（getServerUrl）。

第二步：连接与握手（端口对齐）

1. 在 Voyager 弹窗设置中启用「Context Sync」；
2. 将 Voyager 中配置的端口与 CoBridge 服务器端口对齐（默认均为 3030）；
3. 当状态指示变为「IDE Online」时，表示握手成功。

关于连接状态的检测，源码给出了非常明确的实现细节（ContextSyncSettings.tsx）：

• 前端会对http://127.0.0.1:{port}/sync发起一次GET请求，超时时间为 200ms（使用AbortController中止）；
• 启用状态时每5 秒轮询一次连接状态，绿色圆点表示在线、红色表示离线；
• 端口输入框限定在1–65535的合法端口范围（越界会自动收敛，见 handlePortChange）。

值得注意的细节是：连接检测与同步请求并非由页面直接发起，而是通过浏览器扩展的 background 以消息gv.checkSyncStatus/gv.syncToIDE转发，其注释明确写着 "bypasses page CSP"（绕过页面内容安全策略），见 background/index.ts。这是为了规避 Gemini 等站点对跨域请求的 CSP 限制，保证本地回环请求可以正常发出。

第三步：一键同步

点击「Sync to IDE」按钮，Voyager 会执行以下调用链（content/contextSync/index.ts）：

1. 弹窗向当前标签页发送{ action: 'sync_to_ide' }消息（ContextSyncSettings.tsx）；
2. 内容脚本侧的ContextCaptureService调用captureDialogue()采集当前对话——包括对话节点文本与图片；
3. SyncService.syncToIDE(data)将数据以 JSON 形式POST到本地服务器（SyncService.ts），background 侧执行真正的fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data) })（background/index.ts）。

采集到的数据结构可以从 types.ts 中看到：每个DialogNode包含页面 URL、CSS 类名、文本内容、图片数组（images?: string[]）、AI/用户归属判断（is_ai_likely/is_user_likely）以及元素位置矩形。也就是说，复杂的数据表格、参考图片都会作为对话节点一并采集并同步，与官方文档中「无论是数据表格还是参考图片，都能即时同步到 IDE」的描述完全一致。

在 IDE 中落地：.cobridge 目录结构

同步完成后，IDE 工作目录会出现.cobridge/AI_CONTEXT.md文件，以及用于存放同步图片的images/子目录。Trae、Cursor、Copilot 会通过各自的规则文件（Rule files）自动读取这份「记忆」：

your-project/ ├── .cobridge/ │ ├── images/ │ │ ├── context_img_1_1.png │ │ └── context_img_1_2.png │ └── AI_CONTEXT.md ├── .github/ │ └── copilot-instructions.md ├── .gitignore ├── .traerules └── .cursorrules

这份AI_CONTEXT.md是完整的 Markdown 格式，对 IDE 中的 AI 而言，阅读它就像阅读一份操作手册一样顺畅——这正是该功能「适配 AI」（AI-friendly）设计目标的体现。

页面适配原理：从选择器到通用回退

网页结构千差万别，Voyager 如何判断哪些 DOM 节点属于对话内容？答案是「适配器」机制，定义在 adapters/index.ts：

• 对gemini.google.com，使用精确选择器：用户消息取div.user-query-container，AI 回复取.response-content；
• 对其他站点（default适配器），采用更通用的策略：遍历div、p等通用容器，再通过ai/assistant（AI 侧）与user/human（用户侧）等标记词判断归属；
• 匹配规则为「主机名包含即命中」：getMatchedAdapter(host)逐个比对站点键，未命中时回退到默认适配器（getMatchedAdapter）。

这种「精确适配 + 通用回退」的双层设计，使得功能在核心站点上可以获得高质量的结构化采集，同时保持对其他网页的基本可用性。弹窗对非内置支持页面（如非 gemini.google.com / chatgpt.com / claude.ai）会给出提示但仍尝试同步（ContextSyncSettings.tsx）。

设计原则与使用建议

• 零污染（Zéro pollution）：CoBridge 会自动维护工作目录的.gitignore，确保私人对话内容永远不会被提交到 Git 仓库——同步产出的.cobridge/目录默认处于忽略状态。
• 适配 AI：AI_CONTEXT.md采用完整 Markdown 格式，便于 IDE 内 AI 像读操作手册一样高效读取。
• 建议：如果对话时间较久，建议先用 Voyager 的 时间线（Timeline） 功能回滚网页端上下文，让网页端「回忆」起相关语境，以获得更好的同步效果。

常见问题排查

• 一直显示「IDE Offline」：确认 CoBridge 服务器已启动、端口与 Voyager 设置中的端口一致（默认 3030），并确认弹窗端口输入在 1–65535 合法范围内；
• 同步失败提示服务器无响应：检查本地127.0.0.1:{port}/sync是否可访问，background 中的错误会以HTTP {status}或网络异常消息形式回传（background/index.ts）；
• 找不到.cobridge/AI_CONTEXT.md：确认同步按钮已点击且显示「Synced successfully!」，并检查当前 VS Code 窗口打开的是否为期望的工作目录。

小结

Voyager 的上下文同步通过「浏览器扩展采集对话 → background 转发本地请求 → CoBridge 服务器写入.cobridge/」这条链路，实现了网页端与 IDE 之间的记忆传输。理解其端口配置、握手检测和选择器适配机制后，你不仅能顺畅完成三步骤同步，也能在遇到问题时快速定位原因。网页端负责思考，IDE 负责落地——「大模型不再失忆，即可立即行动」。

【免费下载链接】voyagerEnhancement suite for Gemini, AI Studio, Claude & ChatGPT — plus a prompt manager for any websites, DeepSeek Harness included. / 面向 Gemini、AI Studio、Claude 与 ChatGPT 的增强套件；其中的提示词管理器可用于任意网站，如 DeepSeek Harness。项目地址: https://gitcode.com/gh_mirrors/ge/voyager