ClipMD

ClipMD · Local Markdown Clipper

选中一段，存成自己的 Markdown。

ClipMD 是一款本地优先的网页摘录扩展。在网页中选中有价值的内容，点击选区旁的按钮，即可保存为自己目录里的通用 Markdown。无需账号，不经过产品方云端；如果写入失败，摘录会留在待处理任务中，修复目录后可以继续保存。

选中片段，落到本地。品牌名称、图标和产品文案见 docs/BRAND.md。

当前状态：V1 功能开发与 Phase 7 验收已完成，正在进行发布前品牌与商店材料收尾。当前产物仍是开发者模式测试交付包，尚未经过 Chrome Web Store 或 Edge Add-ons 审核与签名。

品牌与图标

• 品牌规范：docs/BRAND.md
• 主矢量图标：public/brand/clipmd-mark.svg
• Manifest PNG 图标：public/icon/16.png、public/icon/32.png、public/icon/48.png、public/icon/128.png
• 当前图标状态：Temporary Approved

功能

• 监听普通 HTTP / HTTPS 页面的文本选区。
• 使用 Shadow DOM 显示悬浮保存按钮、Tooltip 和 Toast，不污染宿主页面。
• 保留选区 HTML，并在不可用时回退为纯文本。
• 使用 DOMPurify、URL 规范化、Turndown 和 GFM 生成通用 Markdown。
• 输出 YAML Frontmatter，包括标题、网页标题、来源、域名、摘录时间和默认标签。
• 将 FileSystemDirectoryHandle 保存到扩展 Origin 的 IndexedDB。
• 每次写入前检查目录权限，只有文件 close() 成功后才报告成功。
• 使用安全文件名和 -2、-3 冲突后缀，绝不主动覆盖已有文件。
• 保存前持久化完整任务；失败时保留正文、错误码和恢复入口。
• 提供 Popup、设置页和待处理任务页，支持重新授权、重试和删除。
• 不进行 URL 或内容去重；同一网页可以保存多条独立摘录。

技术栈

• WXT、Vue 3、TypeScript strict、Pinia
• Manifest V3、IndexedDB、File System Access API、Web Locks
• DOMPurify、Turndown、GFM、YAML
• Vitest、Playwright、ESLint、Prettier、pnpm

架构

普通网页
  → Content Script（Selection + Shadow DOM UI）
  → 类型化 Extension Messaging
  → Background Service Worker（任务持久化与流程编排）
  → Offscreen Document（Markdown 转换、目录权限查询与文件写入）
  → IndexedDB（目录句柄、任务、设置）
  → File System Access API（本地 Markdown）

目录选择和重新授权只能在可见的 Options 页面中由用户点击触发。Offscreen Document 保留当前目录句柄并执行 queryPermission()、write() 与 close()；Background 不依赖全局内存，任务和配置始终从扩展 Origin 的 IndexedDB 恢复。

本地开发

环境要求：

• Node.js 18+
• pnpm 10.32.1（以 packageManager 字段为准）
• Chrome 或 Edge

安装依赖：

corepack enable
pnpm install --frozen-lockfile

质量检查：

pnpm lint
pnpm typecheck
pnpm test
pnpm test:e2e
pnpm build
pnpm format:check

Playwright 会启动持久化 Chromium Context 并加载构建后的真实 MV3 扩展。系统目录选择器、权限恢复和原生目录写入仍必须执行手工矩阵。

构建、打包与产物审计

生成 Chrome 和 Edge 的解压构建：

pnpm build

.output/chrome-mv3
.output/edge-mv3

生成两个 ZIP 并自动审计 Manifest、权限、必要页面和远程资源：

pnpm package

.output/local-web-clipper-0.0.1-chrome.zip
.output/local-web-clipper-0.0.1-edge.zip

.output 是本地构建目录，不提交版本控制。ZIP 是可传输产物；开发者模式加载时应使用对应的解压目录。

Chrome 安装

1. 打开 chrome://extensions。
2. 启用“开发者模式”。
3. 点击“加载已解压的扩展程序”。
4. 选择 .output/chrome-mv3。
5. 确认扩展卡片没有 Manifest 或 Service Worker 错误。

Edge 安装

1. 打开 edge://extensions。
2. 启用“开发人员模式”。
3. 点击“加载解压缩的扩展”。
4. 选择 .output/edge-mv3。
5. 确认扩展卡片没有 Manifest 或 Service Worker 错误。

使用

1. 打开扩展设置页，选择一个本地保存文件夹。
2. 在普通网页中选中一段非空正文。
3. 点击选区附近的保存按钮。
4. 等待页面右上角显示最终 Markdown 文件名。
5. 写入失败时，从 Toast、Popup 或设置页进入待处理任务页重试。

默认文件名格式：

YYYY-MM-DD-{slug}-{HHmmss}.md

目录授权

• 扩展保存的是浏览器目录句柄，不是操作系统绝对路径字符串。
• 浏览器重启后句柄仍可从 IndexedDB 恢复，但读写权限可能恢复为 prompt。
• 已验证 Chrome 在同一浏览器会话内可跨 Service Worker 休眠继续写入，无需重复授权。
• 已验证 Edge 可能在空闲后把权限恢复为 prompt，即使 Offscreen Document 仍然存在；此行为由浏览器控制。
• 此时只需在设置页点击“重新授权”，通常不需要重新选择目录。
• 浏览器不允许 Content Script 或 Service Worker 静默请求目录权限。
• 取消目录选择或授权不会删除原目录配置、待处理任务或已经保存的文件。

隐私与权限

生产 Manifest 仅申请：

offscreen

offscreen 只用于在扩展文档中执行 DOMPurify 和 Turndown，不访问用户目录、不持久化正文，也不联网。

Content Script 只匹配 http://*/* 和 https://*/*，用于读取用户主动选择的内容和显示 Shadow DOM UI。它不会注入 chrome://、edge://、浏览器商店或内置 PDF 等受限页面。

扩展不包含：

• 产品方服务器或远程 API
• 遥测、统计或第三方分析 SDK
• 远程执行代码或远程字体
• 摘录、URL、标签或浏览历史上传
• chrome.storage.sync 中的正文或目录句柄

数据安全与失败恢复

点击保存
→ 持久化 pending 任务
→ 检查目录权限
→ 生成 Markdown
→ 创建、write、close
→ 删除任务
→ 报告成功

• 任务持久化失败时不会创建文件。
• close() 失败时不会报告成功，任务会保留。
• Manifest V3 Service Worker 重启后，遗留 pending 任务会转为 failed/INTERRUPTED，不会自动重复写入。
• 最多保留 100 条 pending/failed 任务；达到上限后阻止新保存，不静默淘汰旧任务。
• 成功摘录的最终数据是本地 Markdown，不继续保存为扩展正文数据库。

手工验证

完整 Chrome / Edge 文件系统矩阵见 tests/manual/README.md。

启动本地测试网页：

pnpm test:manual:serve

打开 http://127.0.0.1:43127。测试输出目录应放在仓库外，避免把真实摘录或本地路径提交到版本控制。

已知限制

• Chrome / Edge 可能在重启后要求再次授予目录读写权限；Edge 还可能在浏览器空闲后要求重新授权。
• 系统目录选择器和 requestPermission() 必须由可见设置页中的直接点击触发。
• 浏览器内置页面、扩展商店、内置 PDF 和跨域 iframe 不能运行 Content Script。
• 远程图片只保留 URL，不下载到本地。
• File System Access API 没有可移植的排他创建原语。Web Locks 可阻止扩展自身并发覆盖，但外部程序仍存在极小的文件名竞态窗口。
• 当前产物是开发者模式/测试交付包，尚未经过 Chrome Web Store 或 Edge Add-ons 审核与签名。

V1 不包含

完整网页保存、Readability、截图、离线归档、图片下载、PDF/字幕解析、AI、全文搜索、云同步、账号、服务器、WebDAV、Git、S3、URL/内容去重、自动合并或保存前编辑表单。

仓库结构

entrypoints/          WXT Content、Background、Offscreen、Popup、Options、Tasks
src/application/      保存与恢复用例
src/domain/           领域类型、错误和消息协议
src/repositories/     IndexedDB Repository
src/services/         Markdown、文件名和文件系统服务
src/ui/               Design Tokens 与共享组件
tests/unit/           纯逻辑单元测试
tests/integration/    IndexedDB 集成测试
tests/e2e/            构建后扩展 Playwright 测试
tests/manual/         真实浏览器与文件系统矩阵
scripts/              发布产物审计

贡献

V1 产品范围和技术方向已经冻结。贡献应保持聚焦、可测试且不扩大范围。不要在 Issue、日志、截图、测试夹具或提交中包含真实摘录、本地目录路径、浏览器 Profile、密钥或其他个人信息。

License

本项目使用 MIT License。