阅读指南与项目全貌
本章先建立地图：这个项目解决什么问题、代码有多大、应按什么顺序读，以及本文档如何验证每个结论。
一、为什么 Web Clipper 值得拆
表面上，Web Clipper 只是“把网页存进 Obsidian”。源码里的真实问题要复杂得多：网页不是干净的文章，浏览器扩展不是单进程应用，Markdown 不是 HTML 的等价序列化，用户模板也不是简单的字符串替换。
一次剪藏至少跨越七类边界：
- 浏览器边界：popup、content script、background、扩展页分别运行在不同上下文。
- 文档边界：任意网页 DOM 要变成稳定、可读、链接正确的正文。
- 语言边界：用户模板要经过词法分析、语法分析、表达式求值和异步变量解析。
- 持久化边界：临时页面信息要落成有类型的 YAML frontmatter 与 Markdown。
- 定位边界：高亮必须在页面刷新、DOM 轻微变化后仍尽量找回原文。
- 平台边界：Chrome、Firefox、Safari 的后台模型、权限和网络限制并不相同。
- 产品边界：同一核心能力还要服务扩展 UI、独立阅读页、npm API 与 CLI。
这正是项目最值得学习的地方：它不是单一算法，而是一套围绕“内容耐久性”做出的工程取舍。
二、分析快照
| 指标 | 快照值 | 说明 |
|---|---|---|
| 包版本 | 1.7.1 | 来自 package.json 与三份 manifest |
src 文件数 | 294 | 包含 36 份 locale 与测试 fixture |
src 总行数 | 81,025 | JSON、HTML、SCSS、测试均计入 |
| 核心 TS/JS | 约 28,203 行 | 排除 *.test.ts 后统计 |
| 测试代码 | 约 4,696 行 | 以 *.test.ts 统计 |
| 模板过滤器 | 50+ 名称 | 含 stripmd 兼容别名 |
| 浏览器目标 | Chrome / Firefox / Safari | webpack 同一入口组构建三套产物 |
| 站点分析日期 | 2026-08-01 | 源码文件快照时间为 2026-07-28 |
最大的核心文件也暴露了复杂度中心：
| 文件 | 行数 | 承担职责 |
|---|---|---|
src/utils/reader.ts | 2,805 | 阅读模式 DOM 重建、主题、导航、媒体体验 |
src/utils/parser.ts | 1,902 | 模板 AST、表达式优先级、静态校验 |
src/utils/highlighter.ts | 1,438 | 高亮建模、合并、历史、持久化与导出 |
src/core/popup.ts | 1,412 | 剪藏 UI 编排与主要用户流程 |
src/core/highlights.ts | 1,369 | 高亮库浏览、搜索、增量渲染与导出 |
src/background.ts | 1,109 | 生命周期、消息路由、快捷键和浏览器能力 |
src/utils/tokenizer.ts | 1,015 | 模板 DSL 词法分析 |
src/utils/renderer.ts | 994 | AST 求值、作用域、异步变量和过滤器 |
三、不要按目录顺序读
如果从 src/api.ts 一路按字母读到 src/utils，会很快陷进工具函数。更有效的办法是按调用链分五轮。
第一轮：只看骨架
按以下顺序建立运行时心智模型：
manifest.*.json
→ webpack.config.js
→ background.ts
→ content.ts
→ core/popup.ts这一轮只回答三个问题：入口有哪些？代码分别运行在哪里？消息由谁转发？
第二轮：追踪一次剪藏
popup.initializeExtension()
→ content: getPageContent
→ Defuddle.parseAsync()
→ initializePageContent()
→ buildVariables()
→ compileTemplate()
→ generateFrontmatter()
→ saveToObsidian()这条链把产品的主价值串起来。读完后再看设置 UI，很多字段才有意义。
第三轮：拆模板语言
template-compiler.ts
→ tokenizer.ts
→ parser.ts
→ renderer.ts
→ variables/*
→ filters.ts + filters/*重点不是记住 50 个过滤器，而是理解两阶段解析：AST 渲染负责结构和普通变量，后处理负责 selector/prompt 等特殊异步能力。
第四轮：读两个状态型子系统
高亮和阅读模式都有大量可变状态与 DOM 副作用，必须单独读：
highlighter.ts ↔ highlighter-overlays.ts ↔ content-extractor.ts
reader.ts ↔ reader-view.ts ↔ reader-script.ts第五轮：看可复用边界
最后读 api.ts、cli.ts 与构建脚本。它们展示项目如何把浏览器专属能力剥离，沉淀成环境无关核心。
四、本文档采用的拆解方法
每个核心章节尽量保持同一结构：
- 先提出该模块真正解决的问题；
- 给出组件图或时序图，说明它在系统中的位置；
- 标出源码入口、核心类型和关键状态；
- 顺着数据流解释正常路径；
- 单列失败、兼容和降级路径；
- 提炼设计取舍，而不是只复述代码；
- 用检查清单告诉读者读完后应能回答什么。
文中的 文件:行号 是导航提示，不是稳定 API。上游文件继续演进后，函数名通常比行号更可靠。
五、全站知识地图
第一篇 架构地基
01 全景：四个运行域、三条主链路
02 运行时：background 如何成为消息总线
03 构建：同一代码如何产出三种扩展
第二篇 剪藏主链路
04 抽取：DOM → DefuddleResult → variables
05 DSL：文本 → token → AST → output
06 变量与过滤器：同步、异步、选择器、schema
07 保存：properties → YAML → Obsidian URI/文件/剪贴板
第三篇 核心体验
08 高亮：Range → 双锚点 → 恢复 → 导出
09 阅读：原网页/独立页两种运行形态
10 Interpreter：多供应商请求与脏 JSON 防御
第四篇 平台能力
11 storage.sync / storage.local 与管理器层
12 Manifest、权限、CORS、Safari native fetch
第五篇 对外与工程化
13 clip() API 与 Node CLI
14 测试矩阵、fixture 与维护策略
15 按任务反查源码的索引六、源码中的三条主线
主线 A：剪藏
目标是把网页变成一份 Obsidian 笔记。它关注抽取质量、模板可编程性和保存可靠性。
主线 B：高亮
目标是在原网页或阅读模式里保留“我看过哪里”。它关注 Range 建模、锚点恢复、视觉覆盖和本地持久化。
主线 C：阅读
目标是把网页重排成干净的阅读界面。它关注正文提取、样式隔离、链接导航、媒体与高亮复用。
三条线并非互不相干：阅读模式调用高亮，高亮可以被剪藏进模板，剪藏 UI 又能切换阅读模式。理解共享状态在哪里，是阅读源码的关键。
七、读完你应该获得什么
这套文档不是为了让你背实现，而是让你能回答：
- 为什么扩展必须有 background 路由，而 popup 不能直接完成所有工作？
- 为什么模板编译不是一个正则表达式？
- 高亮怎样同时使用 XPath 和 Text Quote Anchor 抵抗 DOM 漂移？
- 为什么
content.js与reader-script.js之间需要显式共享高亮实例？ storage.sync与storage.local各自存了什么，为什么不能互换？- 浏览器版、API 和 CLI 如何复用同一套模板语义？
- 新增一个过滤器、变量或浏览器目标时，应该改哪些层？
下一章从最高层的系统全景开始。