1. 项目概述CtxPort一个为AI对话而生的结构化剪贴板如果你和我一样每天的工作流里充斥着与ChatGPT、Claude、Gemini等AI助手的深度对话那你一定也经历过这种痛苦花了半小时讨论出一个绝妙的架构设计或者调试出一段完美的代码想把这段对话分享给同事或者导入到另一个AI工具里继续深化却发现复制粘贴出来的内容一团糟。HTML标签乱飞、代码块格式丢失、对话结构荡然无存最后只能无奈地截图或者更糟——手动重打一遍。这就是CtxPort要解决的痛点。它不是一个复杂的AI工具而是一个极其简单、纯粹的浏览器扩展一键将任何AI对话或GitHub Issue/PR转换为结构清晰、元数据完整的Markdown文档。这个“文档”我称之为“上下文包”Context Bundle它包含了完整的对话历史、发言者标识、代码块语言标签甚至来源URL和时间戳。你可以把它粘贴到任何地方——另一个AI聊天窗口、你的笔记软件、团队协作工具或者直接保存为.md文件归档。整个过程完全在本地浏览器中完成无需登录不上传任何数据对隐私的坚持到了偏执的程度。我最初开发CtxPort就是因为受够了在工具间迁移上下文时的手动劳动。AI对话已经成为知识工作的新单元但搬运它们的体验却还停留在“传真时代”。CtxPort的目标就是让“上下文移植”变得像复制一段文本一样简单自然。2. 核心设计思路为什么是“结构化剪贴板”在深入代码之前我想先聊聊CtxPort背后的核心设计哲学。市面上已经有一些“对话导出”工具但它们大多要么功能臃肿要么处理结果粗糙。CtxPort选择了一条不同的路做最专业的“剪贴板”。这个定位决定了它的所有特性。2.1 定位解析专注“搬运”而非“管理”很多工具试图成为你的“AI对话管理中心”提供复杂的归档、搜索、分析功能。这当然有价值但也带来了更高的使用成本和隐私顾虑。CtxPort反其道而行之它只做一件事把对话从A点原汁原味地搬到B点。它不存储你的对话不分析你的内容甚至没有后台服务器。它的价值在于“瞬间完成一次高质量的格式转换”然后功成身退。这种极简定位带来了几个优势零信任模型用户无需担心数据泄露因为数据压根不会离开你的浏览器。极低的使用门槛没有账户没有配置安装即用。无与伦比的可靠性功能越单一出错的概率就越低维护也越简单。2.2 技术选型现代Web扩展技术栈为了实现这个目标我选择了一套兼顾性能、开发体验和未来扩展性的技术栈构建工具WXT。这是替代原生chrome.*API和复杂Webpack配置的现代选择。它基于Vite为Chrome、Firefox、Safari等浏览器扩展开发提供了统一、高效的开发体验内置了HMR热模块替换让调试扩展像开发普通Web应用一样流畅。前端框架React 19 TypeScript。React的组件化模型非常适合构建扩展的UI部分如弹出的复制按钮、选项页。TypeScript则提供了严格的类型安全这对于需要与各种不同结构的网页ChatGPT、Claude等打交道的项目至关重要能极大减少因DOM结构变化导致的运行时错误。样式Tailwind CSS 4。实用优先的CSS框架能让我们快速构建出一致、美观的UI同时保持极小的样式体积。这对于一个追求轻量、快速的扩展来说很重要。包管理与构建pnpm Turborepo。项目采用Monorepo结构将核心逻辑、平台适配插件、共享UI组件等拆分为独立的包。pnpm的磁盘效率和严格依赖管理配合Turborepo的智能缓存和任务调度使得多包项目的开发和构建速度极快。这个技术栈的核心思想是开发者体验驱动。一个愉快的开发环境能鼓励更高质量的代码和更持续的维护这对于开源项目尤其重要。2.3 架构设计插件化与核心分离CtxPort的架构清晰地区分了“核心能力”和“平台适配”。packages/ ├── core-schema/ # 定义“上下文包”的数据结构使用Zod ├── core-plugins/ # 平台适配插件ChatGPTPlugin, ClaudePlugin... ├── core-markdown/ # 将结构化数据序列化为Markdown └── shared-ui/ # 按钮、图标等共享React组件 apps/ └── browser-extension/ # 扩展主入口集成所有插件和UIcore-schema这是项目的“宪法”。它使用Zod库定义了一个ContextBundle对象应该长什么样必须包含哪些元数据如来源、URL、时间消息数组的结构如何。所有插件产出的数据都必须通过这个模式的校验确保了输出格式的绝对一致性。core-plugins这是项目的“适配器层”。每个支持的平台如chatgpt.com,claude.ai都有一个独立的插件。插件的工作很简单监听页面变化当检测到对话页面时从DOM中提取出结构化对话数据并将其转换成符合core-schema定义的对象。这种设计使得添加对新平台的支持变得非常模块化几乎不会影响现有代码。core-markdown这是项目的“翻译官”。它接收一个通过校验的ContextBundle对象然后按照精心设计的规则将其转换为易读的Markdown字符串。这里处理了所有细节如何用##标题区分用户和助手如何在代码块上添加正确的语言标识符如javascript如何优雅地处理长消息换行等。这种“核心-插件”的架构让CtxPort既保持了核心功能的稳定和纯净又拥有了轻松扩展支持范围的能力。3. 核心功能深度解析与实现要点3.1 魔法之源内容脚本与页面通信浏览器扩展的核心能力来自于内容脚本Content Scripts。CtxPort的内容脚本被注入到所有它支持的网站中。它的工作流程可以概括为“侦察、提取、上报”侦察MutationObserver脚本使用MutationObserver监听目标页面的DOM变化。这不是一个简单的setInterval轮询而是高效的、事件驱动的监听。当检测到聊天容器、消息列表或侧边栏列表出现更新时它就会触发下一步。提取Platform Plugin根据当前页面的URL激活对应的平台插件。每个插件都封装了针对该平台页面结构的特定CSS选择器和数据提取逻辑。例如ChatGPT插件知道如何找到.text-base开头的元素来区分消息并从中提取出角色用户/助手和纯文本内容。上报Message Passing提取出的结构化数据通过Chrome扩展的chrome.runtime.sendMessageAPI从内容脚本运行在网页上下文中发送到后台服务工作线程Service Worker。注意这里有一个关键的隐私设计。所有复杂的DOM解析和数据提取逻辑都运行在内容脚本中即你的浏览器标签页内部。只有最终生成的、纯净的文本和元数据不包含任何个人身份信息或原始HTML会被发送到扩展的后台部分进行格式化和复制到剪贴板。原始网页数据从未离开过当前标签页的进程。3.2 侧边栏列表复制一个被忽略的效率杀手“侧边栏列表复制”是CtxPort我最引以为傲的功能也是它区别于其他工具的关键。大多数工具要求你必须点开一个对话才能复制它。想象一下你需要整理上周与AI讨论的5个不同想法的对话这意味着你要进行5次“点击加载 - 等待渲染 - 点击复制 - 点击返回”的循环。CtxPort的解决方案优雅得多当你将鼠标悬停在侧边栏的对话列表项上时内容脚本会检测到这个li或div元素。插件会从这个列表项元素中直接提取出对话的标题和关键的对话ID通常藏在>--- ctxport: v2 source: chatgpt url: https://chatgpt.com/c/abc123def456 title: REST API设计认证与速率限制讨论 date: 2026-02-07T14:30:00Z nodes: 24 format: full lang: zh-CN ---source和url允许任何接收此文档的工具知道内容的原始出处甚至可以设计一个“导入”功能尝试重新打开这个链接。date和nodes提供了对话的时空维度信息便于归档和检索。format记录了导出时的模式完整、仅用户、仅代码等避免后续混淆。lang标记了对话的主要语言对于后续处理或搜索有潜在价值。消息体部分则严格遵守可读性与结构性的平衡角色用二级标题##标识## User,## Assistant。这比简单的加粗或前缀更清晰在大多数Markdown渲染器中会非常醒目。代码块保留语言标识从平台原始数据中尽可能提取编程语言如python,javascript,bash确保粘贴到支持语法高亮的编辑器时能正确显示。处理富媒体占位符对于AI对话中可能出现的“图片已生成”或“文件已上传”等占位文本CtxPort会将其转换为明确的Markdown注释或描述性文本如!-- [Image generated by AI] --而不是直接丢弃或保留无意义的HTML。3.4 四种复制模式的应用场景提供多种模式不是为了炫技而是为了覆盖真实工作中不同的使用场景完整模式Full默认且最常用的模式。导出全部对话。适用于将整个讨论上下文迁移到另一个AI如从ChatGPT搬到Claude继续或作为项目文档的一部分完整存档。仅用户模式User Only只导出你用户发送的所有消息。这本质上是一个高质量的提示词Prompt集合导出工具。当你积累了一批有效的提问模板想在新项目中复用或分享给团队成员时这个模式极其有用。仅代码模式Code Only过滤掉所有叙述性文字只提取对话中出现的代码块并按顺序排列。想象一下你和AI调试了十轮生成了多个版本的函数片段。这个模式能一键给你一个纯净的代码草稿文件直接用于后续开发。紧凑模式Compact将每个消息无论多长压缩成一个段落。牺牲了一些可读性但极大减少了令牌Token数量。当你需要将很长的对话摘要粘贴到有令牌限制的AI上下文窗口或者分享到即时通讯软件时这个模式能派上大用场。4. 开发与构建实操指南4.1 从零开始环境搭建与首次运行假设你是一个开发者想从源码构建CtxPort或者有意为其贡献代码以下是详细的步骤# 1. 克隆仓库 git clone https://github.com/nicepkg/ctxport.git cd ctxport # 2. 安装依赖 (确保你已安装 Node.js 18 和 pnpm) pnpm install # 3. 构建所有核心包 pnpm build # 4. 启动扩展开发模式 pnpm dev:ext执行pnpm dev:ext后WXT会启动开发服务器并在项目根目录下的apps/browser-extension/dist/文件夹中生成开发版本的扩展。通常你会看到一个类似chrome-mv3-dev的文件夹。在Chrome中加载扩展打开Chrome访问chrome://extensions/。开启右上角的“开发者模式”。点击“加载已解压的扩展程序”。选择上一步生成的chrome-mv3-dev文件夹。现在你的扩展栏应该会出现CtxPort的图标。打开chatgpt.com或claude.ai你应该能在对话界面看到CtxPort的复制按钮了。实操心得开发中的热重载。WXT的一个巨大优势是支持热重载。当你修改了内容脚本、弹出页或后台脚本的代码并保存后WXT会自动重新构建并通知浏览器扩展更新。大多数时候你只需要在对应的网页上刷新一下页面就能看到修改生效无需手动在chrome://extensions/页面重复点击“刷新”图标。这显著提升了开发效率。4.2 添加一个新平台插件以“通义千问”为例CtxPort的插件化架构使得支持新平台变得相对直接。假设我们要添加对阿里云“通义千问”的支持。第一步创建插件文件在packages/core-plugins/src目录下创建一个新文件例如tongyi.plugin.ts。每个插件都需要实现一个统一的PlatformPlugin接口。// packages/core-plugins/src/tongyi.plugin.ts import type { PlatformPlugin, Conversation, Message } from ctxport/core-schema; const TongyiPlugin: PlatformPlugin { // 唯一标识符 id: tongyi, // 匹配的网站域名 matchDomains: [tongyi.aliyun.com, qianwen.aliyun.com], // 插件名称 name: 通义千问, // 图标可选 icon: , // 核心方法检查当前页面是否是该平台的对话页 isConversationPage(): boolean { // 通过URL路径或页面特定元素判断 return window.location.pathname.includes(/chat/); }, // 核心方法从当前页面提取对话数据 async extractConversation(): PromiseConversation | null { // 1. 获取对话标题可能从页面标题或特定元素 const title document.title.replace( - 通义千问, ) || 未命名对话; // 2. 定位消息容器元素 const messageContainer document.querySelector([data-testidmessage-list]) || document.querySelector(.chat-container); if (!messageContainer) return null; // 3. 遍历消息元素提取每条消息 const messageElements messageContainer.querySelectorAll(.message, [class*message-]); const messages: Message[] []; messageElements.forEach((el) { // 判断角色通常通过CSS类名、特定属性或元素位置区分用户和AI const isUser el.classList.contains(user-message) || el.querySelector(.avatar-user); const role isUser ? user : assistant; // 提取纯文本内容需要移除按钮、操作图标等无关元素 const contentEl el.querySelector(.content, .text-part); let text contentEl?.textContent?.trim() || ; // 处理代码块通义千问的代码块可能有特定结构 const codeBlocks el.querySelectorAll(pre code); codeBlocks.forEach((codeEl, index) { const lang codeEl.className.match(/language-(\w)/)?.[1] || text; const code codeEl.textContent || ; // 将代码块替换为Markdown代码块占位符后续由core-markdown统一处理 text text.replace(code, \\\${lang}\n${code}\n\\\); }); messages.push({ role, content: text }); }); // 4. 返回符合core-schema定义的Conversation对象 return { title, messages, sourceUrl: window.location.href, }; }, // 可选实现侧边栏列表项的数据提取用于悬停复制 extractFromListItem(element: HTMLElement): { title: string; conversationId?: string } | null { const titleEl element.querySelector(.conversation-title); const linkEl element.querySelector(a); const title titleEl?.textContent?.trim() || linkEl?.textContent?.trim() || 未命名; const href linkEl?.href || ; const idMatch href.match(/\/chat\/([a-zA-Z0-9_-])/); return { title, conversationId: idMatch?.[1], }; }, }; export default TongyiPlugin;第二步注册插件在packages/core-plugins/src/index.ts中导入并注册这个新插件。import TongyiPlugin from ./tongyi.plugin; // ... 其他导入 export const platformPlugins: PlatformPlugin[] [ // ... 其他已注册插件 TongyiPlugin, ];第三步更新扩展清单在apps/browser-extension/wxt.config.ts中确保内容脚本会注入到新平台的域名。export default defineConfig({ // ... manifest: { content_scripts: [ { matches: [ // ... 其他匹配规则 *://tongyi.aliyun.com/*, *://qianwen.aliyun.com/*, ], js: [content-scripts/main.ts], run_at: document_end, }, ], }, });第四步测试运行pnpm dev:ext在Chrome中加载开发版扩展然后访问通义千问的聊天页面。如果一切正常你应该能看到CtxPort的复制按钮出现并且点击后能生成正确的Markdown。注意事项网页结构的易变性。这是开发AI平台插件最大的挑战。像ChatGPT、Claude这样的网站其前端DOM结构可能会随着产品更新而改变。这意味着插件中的CSS选择器可能会突然失效。一个健壮的插件应该使用相对宽松、层级较多的选择器而不是依赖绝对精准但脆弱的路径。对关键元素如消息容器进行多重备选查询。在extractConversation方法中添加足够的空值判断和错误处理当无法提取有效数据时优雅地返回null而不是让扩展崩溃。4.3 核心Markdown序列化引擎的工作逻辑core-markdown包的工作是将一个标准的Conversation对象转换成字符串。这个过程需要考虑很多细节// packages/core-markdown/src/serializer.ts 简化示例 export function serializeToMarkdown(conversation: Conversation, format: CopyFormat full): string { // 1. 生成Frontmatter const frontmatter ---\nctxport: v2\nsource: ${conversation.platform}\nurl: ${conversation.sourceUrl}\n...\n---\n\n; // 2. 根据选择的格式过滤消息 let messagesToProcess conversation.messages; if (format user-only) { messagesToProcess messagesToProcess.filter(m m.role user); } else if (format code-only) { // 更复杂的逻辑需要从消息内容中提取代码块 messagesToProcess extractCodeBlocksFromMessages(messagesToProcess); } else if (format compact) { // 压缩逻辑将每条消息内容合并为一段 messagesToProcess compactMessages(messagesToProcess); } // 3. 遍历消息构建Markdown主体 let markdownBody ; for (const message of messagesToProcess) { // 角色转为二级标题 const roleHeader ## ${message.role user ? User : Assistant}; markdownBody ${roleHeader}\n\n; // 处理消息内容识别内联代码、代码块、链接等 const processedContent processMessageContent(message.content); markdownBody ${processedContent}\n\n; } // 4. 返回最终结果 return frontmatter markdownBody.trim(); } function processMessageContent(content: string): string { // 这里需要处理各种情况 // - 已经由插件标记的代码块lang\n...\n保持不变。 // - 未标记的代码段可能用code标签或反引号包裹需要统一转换。 // - 过长的行可能需要智能换行避免在窄视图中出现水平滚动条。 // - 处理图片、文件等附件的占位符表示。 // 这是一个需要精心打磨的函数决定了最终Markdown的观感。 return content; }5. 常见问题、排查技巧与未来展望5.1 使用中常见问题速查即使设计再精良在实际使用中也可能遇到问题。以下是一些常见情况及其解决方法问题现象可能原因解决方案在某个网站看不到复制按钮1. 该网站尚未被CtxPort支持。2. 网站DOM结构已更新插件选择器失效。3. 扩展未在该网站获得权限罕见。1. 检查CtxPort官网的支持列表。2. 刷新页面重试。若普遍存在可能是插件需要更新。3. 在chrome://extensions/中检查CtxPort的“网站访问”权限是否为“在所有网站上”。点击复制按钮无反应1. 页面未完全加载。2. 内容脚本注入失败。3. 与其他浏览器扩展冲突。1. 等待页面完全加载消息列表出现后再试。2. 尝试刷新页面。3. 尝试在无痕模式下禁用其他扩展后测试。复制出来的格式错乱1. 插件提取逻辑对当前页面结构不匹配。2. 消息中包含极其特殊的富媒体格式。1. 尝试切换到“紧凑模式”或“仅用户模式”看是否有所改善。2. 最可靠的方式使用“仅代码模式”提取核心代码或手动微调生成的Markdown。侧边栏悬停不显示图标1. 该平台的侧边栏列表结构特殊未被插件识别。2. 页面使用了虚拟滚动等技术列表项非静态DOM。目前此功能对某些动态加载的列表支持不佳。可以尝试点开对话使用页面内的复制按钮。快捷键(AltShiftC)无效1. 快捷键被其他扩展或系统占用。2. 焦点不在网页内容上可能在地址栏或开发者工具。1. 访问chrome://extensions/shortcuts查看并重新设置CtxPort的快捷键。2. 确保鼠标点击一下网页内容区域再按快捷键。5.2 开发者调试技巧如果你是贡献者或正在自行构建遇到问题时可以这样排查检查控制台日志在目标网站如chatgpt.com按F12打开开发者工具切换到Console标签页。CtxPort的内容脚本会将重要的运行日志如插件匹配成功、数据提取结果打印到这里。这是诊断“为什么按钮不出现”或“为什么数据提取为空”的第一步。检查后台页日志在扩展管理页面 (chrome://extensions/)找到CtxPort点击“详细信息”然后点击“服务工作者”旁边的链接打开Service Worker的控制台。这里可以看到后台脚本处理消息、与剪贴板交互的日志。手动测试插件提取逻辑在目标网站的Console中你可以手动执行插件代码来测试。首先在Sources标签页中找到CtxPort的内容脚本通常位于chrome-extension://[扩展ID]/path/to/content-script.js然后在Console中尝试调用window.__CTXPORT_PLUGIN?.extractConversation()如果暴露了的话或检查相关的全局变量来查看插件是否能正确识别页面和提取数据。审查网络请求针对侧边栏复制如果侧边栏复制失败打开Network标签页筛选Fetch/XHR请求。点击侧边栏的复制按钮观察是否有新的网络请求发出。这能帮助你判断是对话ID提取失败还是后台请求被阻止。5.3 未来演进方向CtxPort目前已经解决了核心的“复制”问题但围绕“上下文移植”这个主题还有更多值得探索的方向上下文包导入当前的流程是单向的“导出”。一个自然的延伸是“导入”——允许用户将之前导出的.md文件或一段Markdown文本“喂”给CtxPort让它自动在目标AI聊天中恢复对话结构例如将历史消息逐条发送出去作为新对话的上下文。这能实现真正的双向上下文迁移。批量导出用户可能想一次性导出某个项目的所有相关对话。一个批量选择界面允许用户勾选侧边栏的多个对话然后打包下载为一个包含多个上下文包的ZIP文件或一个整合的文档会非常实用。自定义模板高级用户可能希望对输出的Markdown格式有更精细的控制比如自定义Frontmatter字段、消息前缀样式、是否包含时间戳等。提供一个简单的模板引擎如Handlebars可以满足这种需求。更多平台支持除了主流AI聊天工具许多知识管理工具如Notion、Obsidian、代码仓库GitLab、Bitbucket和协作软件Slack、Discord中与AI机器人的对话也是上下文产生和需要移植的地方。插件生态可以持续扩大。本地AI集成随着Ollama、LM Studio等本地大模型客户端的普及CtxPort可以探索与这些桌面应用集成实现从Web AI到本地AI的无缝上下文切换。开发CtxPort的过程让我深刻体会到一个好的工具未必需要功能繁多而是要在单一痛点上下足功夫做到极致。它就像一把精心打磨的“瑞士军刀”中的那个最常用、最锋利的刀片虽然小巧但每次使用都能切中要害让你几乎感觉不到它的存在却又离不开它。如果你也厌倦了在AI工具间手动搬运思想的碎片不妨试试CtxPort它或许能让你更流畅地捕捉和连接那些闪烁的灵感。