用 Manifest V3 撸了一个 Notion 剪藏插件，彻底解决了保存丢失的痛点

很多用 Notion 做知识库的朋友应该深有体会，官方的 Web Clipper 体验其实相当糟糕。在 Chrome 商店里它的评分只有 3.4，最让人崩溃的是那种毫无预兆的“请联网后保存”提示，或者在登录界面陷入死循环。对于一个追求效率的工具来说，这种不稳定性是致命的。因为官方迟迟没有彻底修复，我决定用 Manifest V3 自己写一个替代方案，起名叫 ClipMark。

在开发这个插件之前，我分析了官方插件失效的核心原因：它采用了同步请求模式，一旦网络波动或 API 响应超时，数据直接在内存中丢失。为了解决这个问题，我在 ClipMark 中实现了一套“先本地持久化，后异步同步”的逻辑。

具体到技术实现上，我设计了一套防丢队列机制。当用户点击保存按钮时，插件不会直接调用 Notion API，而是第一时间将提取的内容写入 chrome.storage.local。只有在本地存储确认成功后，Service Worker 才会发起异步请求。如果此时网络波动导致接口报错，插件会通过 chrome.alarm 触发指数退避重试机制，最高尝试 6 次。这种设计确保了即使在极差的网络环境下，用户的剪藏内容也绝不会凭空消失，且用户可以通过弹窗实时监控队列的同步状态。

为了让这个插件不仅仅是一个简单的搬运工，我将其实操流程分成了三档，覆盖了不同的知识管理场景。第一档是“纯净 Markdown”，我集成了 Readability.js 来过滤掉网页上的垃圾菜单和 Cookie 弹窗，将干净的 Markdown 内容直接复制到剪贴板，这在把素材喂给 Claude 或 ChatGPT 做分析时非常高效。第二档是“本地存档”，插件会自动生成带有 YAML frontmatter 的 .md 文件，方便直接丢进 Obsidian 这种本地笔记软件。第三档才是真正的“Notion 同步”，通过 OAuth 2.0 协议走官方 API，将内容转换为原生 Block 存入指定的数据库。

最让我满意的是在后台接入 gpt-4o-mini 实现的 AI 增强功能。在内容正式推送到 Notion 之前，AI 会自动分析页面内容，生成 3-5 个精准的标签以及一行摘要。用户在最终点击保存前可以手动微调这些信息，这样存入 Notion 的页面自带结构化标签，极大方便了后期的检索。

在技术栈的选择上，前端采用了 Manifest V3 + Vanilla JS，并使用 Turndown 库完成 HTML 到 Markdown 的转换。后端则使用 Express 部署在 VPS 上，主要负责处理 OAuth 令牌交换和 AI 增强接口的转发。

整体的架构逻辑如下：
Content Script (负责提取) ──▶ Popup UI ──▶ Service Worker (管理队列与 OAuth) ──▶ Notion API。同时，Service Worker 会与 VPS Backend 交互以完成 AI 增强。

虽然 Readability.js 在处理某些极其复杂的动态页面时仍有局限，但整体的稳定性比官方剪藏高出很多。对于构建个人知识库的人来说，这种“本地优先”的同步逻辑才是最稳妥的方案。