1. 项目概述与核心价值作为一名长期与浏览器和效率工具打交道的开发者我一直在寻找一种能真正理解我意图的网页收藏方式。传统的书签管理要么是手动创建文件夹、输入标题过程繁琐且容易遗忘要么是依赖一些简单的规则引擎但面对海量、结构各异的网页时往往力不从心。直到我动手实现了auto-mark这个浏览器插件它利用大语言模型LLM的语义理解能力自动将当前网页归类到你浏览器书签栏中最合适的位置才算真正解决了这个痛点。简单来说你只需要在浏览任何网页时右键点击选择“自动收藏”插件就会分析网页内容智能地将其放入你已有的书签文件夹中或者创建一个语义相符的新文件夹。它彻底告别了手动拖拽和命名的时代让知识管理变得主动而智能。这个项目的核心价值在于“理解”与“自动化”。它不仅仅是一个保存链接的工具更是一个理解网页内容、并基于你现有知识体系书签栏结构进行归档的智能助手。无论是技术文档、新闻资讯、购物商品还是灵感素材auto-mark都能尝试理解其核心主题并为其找到“家”。这对于知识工作者、研究者、开发者或任何需要大量收集和整理网络信息的人来说无疑是一个效率倍增器。接下来我将从设计思路、实现细节、实操配置到避坑经验完整地拆解这个项目你可以基于此完全复现或进行二次开发。2. 插件整体架构与设计思路拆解2.1 为什么选择浏览器插件 LLM 的方案在构思自动化书签工具时我评估过几种方案。一种是开发一个独立的桌面应用通过监听剪贴板或浏览器接口来获取URL但这样割裂了浏览上下文操作不够无缝。另一种是使用浏览器的书签API配合本地运行的分类模型但本地模型体积大、精度和泛化能力有限特别是对于多领域网页的理解。最终我选择了“浏览器插件 云端LLM API”的架构。浏览器插件方案的优势非常明显原生集成。它可以无缝嵌入浏览器的右键菜单直接获取当前活跃标签页的完整信息URL、标题、DOM内容用户操作路径最短。选择云端LLM如OpenAI的GPT系列而非本地模型主要是出于效果和成本的权衡。当前GPT等大模型在零样本Zero-shot的文本分类和摘要任务上表现出色无需针对书签分类进行专门训练就能很好地理解网页内容并输出结构化的分类建议。这避免了收集数据、训练和优化模型的巨大成本让开发者可以专注于工程实现和用户体验。当然这个选择也带来了两个明确的依赖一是需要能够访问LLM的API服务通常意味着网络要求二是会产生API调用费用。但对于一个提升核心效率的工具来说我认为这个代价是值得的而且可以通过优化提示词Prompt和缓存策略来控制成本。2.2 核心工作流程设计插件的核心逻辑是一个清晰的管道Pipeline触发与内容抓取用户右键点击页面选择“自动收藏”菜单项。插件后台脚本Background Script被触发通过Chrome API获取当前标签页的URL和页面内容。这里的内容抓取不是简单的innerHTML而是会进行清洗提取主要的文本内容剔除脚本、样式和导航栏等噪音。分析与决策将清洗后的网页文本、标题以及用户现有的书签栏树状结构通过Chrome书签API获取组合成一个精心设计的提示词Prompt发送给配置好的LLM API。Prompt的核心指令是“请根据网页内容将其归类到现有书签文件夹中或建议一个新文件夹名。”解析与执行收到LLM返回的JSON格式的响应例如{“action”: “move_to_existing”, “folderName”: “编程教程”, “bookmarkTitle”: “深入理解Python装饰器”}。插件解析这个响应然后调用Chrome书签API执行对应的操作在指定文件夹下创建书签或先创建文件夹再创建书签。用户反馈操作完成后通过浏览器通知Notification告知用户书签已成功添加到某个位置提供即时反馈。这个流程的关键在于提示词工程和错误处理。提示词必须清晰界定任务并约束LLM的输出格式为可解析的JSON。错误处理则需要涵盖网络超时、API返回异常、书签权限不足等各种边界情况。3. 核心模块实现与代码解析3.1 项目结构概览一个标准的Chrome插件通常包含以下文件auto-mark也遵循了这个结构auto-mark/ ├── manifest.json # 插件配置文件声明权限、脚本、图标等 ├── background.js # 后台服务脚本处理核心逻辑 ├── content.js # 内容脚本可注入页面本项目可能用于内容提取 ├── popup.html # 点击插件图标弹出的配置页面 ├── popup.js # 配置页面的交互逻辑 ├── icons/ # 插件图标多种尺寸 └── _locales/ # 国际化文件夹可选我们的核心逻辑主要集中在background.js和popup.js中。3.2 权限声明 (manifest.json)manifest.json是插件的“身份证”和“权限申请单”。对于auto-mark关键的声明如下{ manifest_version: 3, name: Auto Mark, version: 1.0.0, description: AI-powered automatic bookmark organizer., permissions: [ bookmarks, activeTab, contextMenus, notifications, storage ], background: { service_worker: background.js }, action: { default_popup: popup.html, default_icon: icons/icon48.png }, icons: { 48: icons/icon48.png, 128: icons/icon128.png } }permissions: 这是重点。bookmarks:必需。提供读取、创建、修改书签的权限。activeTab:必需。允许插件临时访问当前活动标签页以获取其URL和内容。contextMenus:必需。用于在浏览器右键菜单中添加“自动收藏”选项。notifications:可选但推荐。用于发送操作成功的桌面通知。storage:必需。用于安全地存储用户配置的API Key和模型参数。background.service_worker: 指定后台脚本它将在插件安装后一直运行监听事件。action.default_popup: 定义点击工具栏图标时弹出的配置窗口。注意Manifest V3 强制使用service_worker替代了V2的background page它更轻量但生命周期管理有所不同不支持DOM操作。所有与LLM API的网络通信和书签操作都应放在这里。3.3 后台服务核心 (background.js)这个文件是插件的大脑它负责初始化右键菜单在插件安装或更新时创建菜单项。监听菜单点击事件当用户点击“自动收藏”时启动整个流程。协调数据流获取页面内容、获取书签树、构造Prompt、调用API、解析结果、操作书签。发送通知。以下是关键代码段的逻辑拆解初始化与事件监听// 安装或更新时创建右键菜单 chrome.runtime.onInstalled.addListener(() { chrome.contextMenus.create({ id: auto-bookmark, title: 自动收藏, contexts: [page, selection] // 在页面和选中文本时显示 }); }); // 监听右键菜单点击事件 chrome.contextMenus.onClicked.addListener(async (info, tab) { if (info.menuItemId auto-bookmark) { // 1. 获取用户配置API Key, Endpoint, Model const config await chrome.storage.sync.get([apiKey, apiEndpoint, model]); if (!config.apiKey) { chrome.notifications.create({ type: basic, iconUrl: icons/icon48.png, title: 配置错误, message: 请先在插件设置中填写API Key。 }); return; } // 2. 获取当前页面内容简化版实际需通过content script获取更干净的内容 let pageContent 标题: ${tab.title}\nURL: ${tab.url}; // 此处理想情况下应通过chrome.tabs.sendMessage与content script通信获取清洗后的正文 // 3. 获取整个书签栏树 const bookmarkTree await chrome.bookmarks.getTree(); // 4. 构造Prompt const prompt constructPrompt(pageContent, bookmarkTree); // 5. 调用LLM API const result await callLLMAPI(prompt, config); // 6. 解析并执行书签操作 await executeBookmarkAction(result, tab.url, tab.title); // 7. 发送成功通知 chrome.notifications.create(...); } });构造提示词 (constructPrompt函数)这是项目的灵魂。一个糟糕的Prompt会导致LLM输出格式混乱或逻辑错误。我们的目标是让LLM扮演一个专业的图书管理员。function constructPrompt(pageContent, bookmarkTree) { // 将书签树扁平化提取出所有文件夹名称作为候选分类 const folderNames extractFolderNames(bookmarkTree[0]); return 你是一个专业的数字知识管理助手。请根据用户提供的网页信息将其归类到现有的书签文件夹中或者创建一个语义最相关的新文件夹。 用户现有的一级书签文件夹有[${folderNames.join(, )}] 网页信息如下 ${pageContent} 请严格按照以下JSON格式输出你的决策不要有任何其他解释 { reasoning: 简要分析网页内容与书签文件夹的关联性, action: 必须是 move_to_existing 或 create_new 中的一个, folderName: 如果action是move_to_existing则填写现有文件夹名称如果是create_new则填写你建议的新文件夹名称要求简洁、语义明确不超过4个汉字或10个英文单词, bookmarkTitle: 建议的书签标题基于网页标题优化使其更清晰易懂 } 请确保 1. “folderName”必须严格从现有文件夹列表中选取或创建逻辑高度相关的新名称。 2. 优先考虑“move_to_existing”仅在现有文件夹均不匹配时才选择“create_new”。 3. “bookmarkTitle”应简洁概括网页核心内容。; }这个Prompt明确了角色、任务、输入、输出格式和约束条件能极大提高API返回结果的稳定性和可用性。调用LLM API (callLLMAPI函数)这里以OpenAI的Chat Completion API为例。async function callLLMAPI(prompt, config) { const { apiKey, apiEndpoint https://api.openai.com/v1/chat/completions, model gpt-3.5-turbo } config; const response await fetch(apiEndpoint, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey} }, body: JSON.stringify({ model: model, messages: [{ role: user, content: prompt }], temperature: 0.2, // 低温度保证输出确定性高格式稳定 response_format: { type: json_object } // 强制要求返回JSON这是GPT-3.5-turbo-1106及更新模型支持的特性 }) }); if (!response.ok) { throw new Error(API请求失败: ${response.status}); } const data await response.json(); const content data.choices[0].message.content; try { return JSON.parse(content); } catch (e) { throw new Error(LLM返回了无效的JSON: ${content}); } }实操心得设置temperature0.2很关键它降低了输出的随机性使同类网页更容易被分到同一个文件夹。response_format参数能强制模型输出JSON但需要注意模型版本支持。对于不支持该参数的模型需要在Prompt中更加强调输出格式并在解析时做好异常捕获。3.4 配置页面与安全存储 (popup.js storage)用户需要配置API Key等敏感信息。我们使用chrome.storage.sync来存储它会在用户登录的Chrome账号间同步。!-- popup.html 片段 -- input typepassword idapiKey placeholdersk-...你的OpenAI API Key input typetext idapiEndpoint placeholderhttps://api.openai.com/v1/chat/completions select idmodel option valuegpt-3.5-turbogpt-3.5-turbo (性价比高)/option option valuegpt-4gpt-4 (效果更好更贵)/option /select button idsaveBtn保存配置/button// popup.js document.getElementById(saveBtn).addEventListener(click, async () { const apiKey document.getElementById(apiKey).value.trim(); const apiEndpoint document.getElementById(apiEndpoint).value.trim(); const model document.getElementById(model).value; if (!apiKey) { alert(API Key 不能为空); return; } await chrome.storage.sync.set({ apiKey, apiEndpoint, model }); alert(配置已保存); window.close(); // 保存后自动关闭弹窗 }); // 页面加载时从存储中读取并填充现有配置 chrome.storage.sync.get([apiKey, apiEndpoint, model], (items) { if (items.apiKey) document.getElementById(apiKey).value items.apiKey; if (items.apiEndpoint) document.getElementById(apiEndpoint).value items.apiEndpoint; if (items.model) document.getElementById(model).value items.model; });重要安全提示API Key是最高机密。chrome.storage.sync是相对安全的但理论上任何能安装到你浏览器上的恶意插件都可能尝试读取它。因此建议用户为这类工具创建并使用具有最小必要权限的API Key例如设置使用量限额并定期轮换而不是使用主账号的根Key。4. 完整实操从零安装、配置到使用4.1 获取项目代码与安装插件获取源代码你需要将项目代码克隆到本地。打开终端或命令提示符导航到你希望存放项目的目录执行git clone https://github.com/DLillard0/auto-mark.git cd auto-mark如果未安装Git也可以直接访问项目的GitHub页面点击“Code”按钮然后选择“Download ZIP”下载后解压到一个文件夹。进入Chrome扩展管理页面在Chrome浏览器的地址栏中精确输入chrome://extensions/并回车。这是管理所有扩展程序的核心页面。开启开发者模式在扩展管理页面的右上角你会看到一个开关写着“开发者模式”。将其打开。打开后页面顶部会显示“加载已解压的扩展程序”、“打包扩展程序”等新的按钮。加载插件点击“加载已解压的扩展程序”按钮。此时会弹出一个文件选择对话框。请导航到你刚才克隆或解压的auto-mark文件夹注意是选择包含manifest.json的那个文件夹本身而不是里面的某个文件。点击“选择文件夹”。确认安装成功如果一切顺利扩展程序列表中会出现一个名为“Auto Mark”的卡片并且浏览器工具栏通常地址栏右侧会出现一个拼图图标点击后也能看到“Auto Mark”的图标。这表明插件已成功安装。注意事项在开发者模式下加载的扩展在每次修改代码后都需要回到chrome://extensions/页面找到auto-mark卡片点击其下方的刷新图标才能使修改生效。4.2 关键配置步骤详解安装完成后插件还不能工作因为它不知道如何连接AI服务。获取API密钥你需要一个OpenAI API Key或其他兼容OpenAI API格式的服务商密钥。访问OpenAI平台注册/登录后在API Keys页面创建新的密钥。请妥善保管此密钥它就像你的密码。配置插件点击浏览器工具栏的拼图图标找到并固定Pin“Auto Mark”插件使其图标常驻工具栏。点击“Auto Mark”图标会弹出配置窗口。在“API Key”输入框中粘贴你刚才复制的密钥格式通常为sk-...。“API Endpoint”一般保持默认的https://api.openai.com/v1/chat/completions即可。如果你使用Azure OpenAI或第三方代理服务则需要填写对应的地址。“Model”选择对于大多数书签分类任务gpt-3.5-turbo完全够用速度快且成本低。如果你对分类准确性和标题优化有极高要求可以尝试gpt-4但每次调用成本会高很多。点击“保存配置”。通常会有一个提示框确认保存成功配置窗口会自动关闭。4.3 首次使用与效果验证配置完成后你就可以开始体验智能收藏了。打开任意一个你想收藏的网页例如一篇关于“Python异步编程”的技术博客。在网页的任意位置非输入框点击鼠标右键。在弹出的右键菜单中你应该能看到一个新的选项“自动收藏”。点击它。此时插件图标可能会显示加载状态。稍等片刻通常2-5秒取决于网络和API响应速度你会看到屏幕右下角弹出一个Chrome系统通知提示“书签已成功添加到‘编程语言’文件夹”文件夹名称是AI根据你现有书签结构判断的。现在你可以点击浏览器书签栏查看是否在对应的文件夹下找到了刚刚自动创建的书签其标题可能也被优化得更具可读性。实测场景举例场景一归类到现有文件夹你的书签栏已有“前端开发”、“后端技术”、“数据库”等文件夹。当你浏览一篇关于“Redis缓存雪崩解决方案”的文章并使用“自动收藏”时插件很可能将其归入“数据库”文件夹并将标题优化为“Redis缓存雪崩与穿透解决方案详解”。场景二创建新文件夹你的书签主要是技术类。当你浏览一篇“北海道冬季旅行攻略”时插件发现现有文件夹均不匹配可能会建议创建名为“旅行攻略”的新文件夹并将书签放入其中。5. 高级技巧、问题排查与二次开发指南5.1 提升分类准确性的技巧优化你的书签栏结构LLM是根据你现有的文件夹名称来理解你的分类体系的。保持文件夹名称语义清晰、简洁如“摄影教程”、“投资理财”、“健康科普”避免使用“杂项”、“1”、“新建文件夹”这类无意义名称能极大提升AI归类的准确性。内容获取优化基础版本只传递了网页标题和URL。更优的方案是注入一个content script提取页面的主要正文内容例如使用Readability类似的算法库剔除页眉、页脚、广告等将纯文本传递给AI。这样AI的判断依据更充分分类更准。这需要修改background.js和新增content.js通过chrome.tabs.sendMessage进行通信。定制化Prompt如果你有特殊的分类偏好可以直接修改background.js中的constructPrompt函数。例如你可以增加指令“如果网页是关于编程的优先放入‘技术’文件夹而不是更细分的子文件夹。”或者“新文件夹名称请一律使用英文。”5.2 常见问题与解决方案速查表问题现象可能原因排查与解决步骤右键菜单没有“自动收藏”选项1. 插件未成功加载。2. 插件被禁用。1. 访问chrome://extensions/确认“Auto Mark”存在且开关已启用。2. 确认安装时加载的是正确的文件夹包含manifest.json。3. 尝试重启浏览器。点击“自动收藏”后无反应1. API Key未配置或配置错误。2. 网络问题无法访问API。3. 后台脚本报错。1. 点击插件图标检查API Key等配置是否已正确保存。2. 打开浏览器开发者工具F12切换到“Console”标签页查看是否有红色报错信息。3. 检查网络连接确认能访问配置的API Endpoint。弹出“配置错误”通知storage中未找到API Key配置。确保已通过插件弹窗popup完成配置并点击了保存。配置保存在Chrome同步存储中。弹出“API请求失败”通知1. API Key无效或过期。2. 额度用尽。3. Endpoint地址错误。1. 前往OpenAI平台检查API Key状态和用量。2. 确认Endpoint地址是否正确特别是使用第三方服务时。3. 在开发者工具“Network”标签页查看请求详情和错误码。书签被创建但位置不对1. Prompt理解偏差。2. 现有书签结构混乱。3. 网页内容提取不佳。1. 参考5.1节优化书签结构和Prompt。2. 考虑在Prompt中提供更详细的指令。3. 实现更智能的正文提取功能。操作成功但无通知notifications权限可能被系统或浏览器全局禁用。检查Chrome设置chrome://settings/content/notifications确保允许网站发送通知同时检查操作系统通知设置。5.3 成本控制与性能优化建议控制成本每次调用API都会产生费用。使用gpt-3.5-turbo单次成本极低约0.001元/次但大量使用也需留意。设置预算在OpenAI平台设置使用量硬性上限。本地缓存可以对相同URL的请求结果进行缓存使用chrome.storage.local避免短时间内重复收藏同一页面时重复调用API。内容截断向API发送的网页正文文本可以截取前N个字符例如4000字符通常已足够AI判断分类。提升响应速度并行处理获取书签树和获取页面内容可以并行进行。超时设置在fetch请求中设置合理的超时时间如10秒避免因网络延迟导致用户长时间等待。使用更快的模型gpt-3.5-turbo比gpt-4响应快得多。5.4 二次开发方向拓展这个插件的基础框架已经搭建完成你可以在此基础上进行深度定制打造专属的智能助手支持多AI后端修改配置和API调用逻辑使其兼容OpenAI、Azure OpenAI、Anthropic Claude、国内大模型如DeepSeek、通义千问等多家服务商的API。添加本地模型支持集成一个能在浏览器中运行的轻量级本地模型通过WebAssembly在离线状态下提供基础的分类功能作为降级方案。自定义分类规则在插件中增加一个规则引擎允许用户设置“如果URL包含‘github.com’则自动放入‘GitHub项目’文件夹”这类硬性规则规则优先于AI判断。批量处理与历史整理开发一个管理界面可以扫描所有现有书签批量进行AI智能整理和去重。与笔记软件联动不仅收藏链接还能将网页精选内容同步到Notion、Obsidian等笔记软件中形成更完整的工作流。开发过程中最权威的参考资料永远是 Chrome Extensions官方文档 。从Manifest V3的规范到每个API的详细用法文档都非常清晰。遇到问题首先查阅文档其次可以在浏览器的开发者工具中调试你的Service Worker和Popup页面这是排查问题最直接的手段。