Maeiee Weekly No.11：使用 WebScrapBook 制作互联网剪报

什么是”剪报“

当我写下标题后突然意识到，会不会好多人已经不知道什么是”剪报“了……

什么是”剪报“？在我小的时候，那会儿大家还不知道什么是电脑，获取资讯主要靠看报纸。我爷爷会把好的文章用剪刀剪下来，贴到本子上。这就叫”剪报“，按现在的话来说，属于”资讯离线阅读手账“（嗯？）。

至于”剪报“长什么样，大家自行搜索这个关键词即可。

互联网时代的剪报

如今是互联网时代，已经没人看报了。连我爷爷都 iPad 玩的飞起。

互联网上的文章浩如烟海，看到好文章该怎么收藏呢？这里面存在一些现实问题：

1. 文章会消失：比如托管平台倒闭了，平台下的文章都没了
2. 大量文章如何归类：比如收藏了几万篇文章，怎么查阅都成为问题
3. 如何阅读海量资讯：这么多资讯，看不过来，怎么提高效率？

针对这些问题，诞生了一些互联网剪报产品，比如各种 Read it later 工具，以及 Internet Archive 这种保护信息的非盈利机构。

今天要介绍的 WebScrapBook 也是一种互联网剪报，适合于个人使用。

剪切页面离线保存

在我看来这是 ScrapBook 最神奇的功能，在离线剪切时，你能用一种可视化方法剪切 DOM 树，将不需要的部分剪掉（比如广告、边栏），只留下需要的部分（正文）。

进入【编辑页面】功能后，底部多出一个工具栏，里面的工具分别包括【文本高亮】、【添加备注】、【DOM剪刀】、【HTML编辑】、【保存】等。

网页中左边有一个红框，这就是【DOM剪刀】的功能，开启后将鼠标在网页中移动，光标所在的 DOM 树会自动绘制红框范围，点击后该 DOM 树会被删除。

同时【DOM剪刀】也支持反选，按下 Ctrl + 点击，会将 DOM 树之外的部分都删除掉。

通过剪来剪去，最终只留下文章正文部分，点击【保存】。一份完美的、100% 保留格式的页面，就被我们永久保留下来了。

高亮

除了【DOM剪刀】之外，还可以手动对文字添加高亮，来划重点。

后端存储

剪下来的数据该如何存储呢？WebScrapBook 提供了多种存储方式，既可以存储在浏览器中，也可以搭建后端服务器。

WebScrapBook 提供了一套后端实现，danny0838/PyWebScrapBook，基于 Flask 框架使用 Python 开发而成。

通过这种方式，数据能够得到更好的存储与保管，同时也能够支持不同的设备维护同一套 WebScrapBook 数据。

服务器启动效果如下：

归档页面管理

剪藏下来的页面，通过【打开剪贴簿】可以进行分级浏览。

下图是剪贴簿远程访问后台服务器的数据效果。

里面的文件夹都是我自己创建的，可以创建任意层级深度的目录，帮助更好地管理页面。

丰富的设置选项

现在的 App 流行“傻瓜化”，过去的 App 流行专业化。ScrapBook 提供了大量的设置项目，让适应了“傻瓜化”的我目瞪口呆。

下图展示了部分配置项：

通过这些配置项，用户可以根据自身喜好配置出不同的使用效果。比如在意 100% 排版还原的用户可以尽可能保留现场，而在意归档文件空间占用的用户可以尽可能滤除多余元素。

甚至还能通过正则名单配置自动抓取项，当我们打开某一类网址时能够自动进行离线缓存。

还有一个名为【获取助手】的模块，基于 JSON 创建了一个 DSL，允许用户针对不同站点定制抓取逻辑，以实现最佳的抓取效果。

ScrapBook

最早由 Murota Laboratory 研发，该实验室是‎‎东京工业大学‎‎决策科学研究生院人类系统科学系人力资源开发主席的成员。它目前由 Gomita 维护。也就是说，这个项目是由日本开发者研发的。

ScrapBook 赢得了火狐 2006 年的”最有用的扩展功能“奖项。原来 ScrapBook 也火过，只不过是在快 20 年前。

Gomita

Gomita 的全名是 Gomibuchi, Taiga，博客最新一篇文章更新到 18 年，专注于浏览器和浏览器插件开发。

翻看作者的博客，以下回到了 20 年前的 Web 1.0 时代。里面用到的很多技术都已经尘封为历史往事，可在当年都是最新潮的 Web 开发技术。

其中《designMode》一篇介绍道：设计模式是一个简单的 HTML 编辑功能，安装在许多 Web 浏览器中，主要用作博客文章和 Web 邮件创建的富文本编辑器。

ScrapBook X

ScrapBook 从 2012 年开始研发速度变慢了，很多问题没有及时修复。这段时间出现了大量 Fork，比如：ScrapBook Plus、ScrapBook Plus 2、ScrapBook Lite。但是这也也都没有维护下去。

Danny Lin 创建了 ScrapBook X，GitHub 首页。ScrapBook X 对 ScrapBook 做了很多修复和新功能添加，还扩展了一些新的插件：

• ScrapBook X MAF Creator：将 ScrapBook 数据转换为 MAFF 格式（一种单文件网页归档格式）
• ScrapBook X CopyPageInfo：复制 ScrapBook 的引用信息，比如 BibTeX。
• ScrapBook X AutoSave：在浏览过程中自动归档网页
• ScrapBook X File Converter：其他格式的文件与 ScrapBook 相互导入导出

本文要介绍的 WebScrapBook 也是 Danny Lin 创建的。

Danny Lin

Danny Lin 是一个台湾的开发者，GitHub。创建了以下软件：

• danny0838/content-farm-terminator：屏蔽内容农厂的浏览器插件
• danny0838/webscrapbook：本文的主角
• danny0838/firefox-scrapbook：webscrapbook 的前身
• danny0838/PyWebScrapBook： webscrapbook 的后端服务
• danny0838/SingleFile：Fork 项目，一个将文件保存问单文件 HTML 的浏览器插件
• danny0838/mark.js：Fork 项目，一种对网页进行标注的 JS 插件

WebScrapBook

WebScrapBook 也是由 Danny Lin，作为 ScrapBook X 的后继，基于 WebExtension 规范。目前仍然在活跃维护当中。两者由什么不同呢？

ScrapBook X 只能在老版的 Firefox 下运行，WebScrapBook 在最新的 Chrome、Firefox 下都能运行。同时 WebScrapBook 提供 Server，支持远程访问。并且可自定义的项目更多。

该项目的 Wiki 价值非常高，比如 FAQ。

ScrapBee

插件首页，也是 ScrapBook 的一种 Fork，GitHub。他的后端是用 Golang 写的。

ScrapYard

插件首页，另一个 ScrapBook Fork。支持通过云服务同步页面。该项目是对 ScrapBee 的 Fork，GitHub。目前处于活跃开发中。

作者是 GChristensen，个人主页。这个作者的文章都很有意思，值得认真学习。比如这一篇《Creating a personal knowledge base》

右键菜单

代码中该文案【获取页面（原样）】位于 src/_locales/zh_CN/messages.json，key 名称是 CapturePageSource。

沿着 key 值继续寻找，找到右键菜单创建代码，位于 src/core/background.js，对应代码如下：

browser.contextMenus.create({
  title: scrapbook.lang("CapturePageSource"),
  contexts: ["page"],
  documentUrlPatterns: urlMatch,
  onclick: (info, tab) => {
    return scrapbook.invokeCapture([{
      tabId: tab.id,
      mode: "source",
    }]);
  },
});

可以看到，点击回调对应的是 scrapbook.invokeCapture 方法，该方法位于 src/core/extension.js，提供了一个工具列 scrapbook，通过它作为插件功能的入口。invokeCapture 方法最终会调用 scrapbook.invokeCaptureEx。

scrapbook.invokeCaptureEx

Advanced API to invoke a capture.（发起一次抓取的高级 API）。

该方法的大致逻辑是：

1. 开一个新窗口（Tab）打开页面
2. 等待页面加载完成
3. 页面完成后通过 scrapbook.invokeExtensionScript，在页面 Context 下执行脚本 capturer.getMissionResult

capturePromise

来到 capture.js 的 capturePromise。

添加 document 的 DOMContentLoaded 事件回调，待页面加载完成后，继续执行逻辑。

在 capture.html 中专门有一个 iframe，是用来执行网络请求的。这个页面是弹出来的用于显示抓取日志的那个对话框的页面。

执行 capturer.runTasks(taskInfo) 进行实际抓取工作。

captureGeneral + capturer.captureRemote

再往后的逻辑，如调用栈所示：

capturer.js:1091 console.trace
capturer.captureRemote @ capturer.js:1091
await in capturer.captureRemote(异步)
capturer.captureGeneral @ capturer.js:889
await in capturer.captureGeneral(异步)
capturer.runTasks @ capturer.js:817
(匿名) @ capturer.js:4191

后续执行捕获的方法进入 capturer.captureUrl。在该方法中将进行页面和资源的 fetach 拉取操作。

capturer.captureTab

【获取页面】最终进入的是 capturer.captureTab，这与【获取页面（原样）】是不同的。

captureGeneral：

• 【获取页面】模式下是：
  • tabId = 1014441721
  • url = undefined
• 【获取页面（原样）】模式下是：
  • tabId = 1014441721
  • url = undefined

原来两个模式下都走了 capturer.captureTab，但在 capturer.captureTab 内部逻辑出现了不同。

在 capturer.captureTab 中，对于 "source mode"，直接走 capturer.captureRemote。而【获取页面】则走了 capturer.invoke("captureDocumentOrFile" 逻辑。

capturer.captureDocumentOrFile

TBD。

handle_action_token 注解

添加标签系统

目前 Scrapbook 没有支持标签系统，我准备手动加入这个系统。

具体来说，用户可以手动给资讯添加标签。并且支持对标签进行不断缩小范围式的检索。

注：未来可以扩充，支持根据规则自动给资讯添加标签。

基于域名的自动目录创建

我打算将目录层级采用固定规则：每个域名一个目录。

采用 SQLite 数据

由于支持 Tag 系统，我打算引入 SQLite 数据库，与已有的 Flask 相打通。

开发新的管理前端

目前 Scrapbook 的管理端做在了浏览器插件中，开发技术比较繁琐。

我打算利用现代化的前端技术重新开发一个管理端。

目前打算使用 Flutter for Windows 来开发。有几个原因：

1. Web 前端开发我已经忘得差不多了……否则的话我会考虑 Electron，因为毕竟都是 Web 技术栈，操纵起 DOM 来更加方便
2. Flutter 是我比较擅长的，最近两年一直在搞 Flutter
3. Flutter for Windows 下有 WebView，Flutter 是没有官方 Desktop 下的 WebView 的，目前只有 Windows 和 macOS 有非官方的实现。其中 Windows 的版本，目前看起来足够使用了。
4. 移动化迁移。这套系统我希望能像移动端迁移，把整个 Scrapbook Server 服务跑在手机上。如果能先把管理端迁过去，Flask 的部分可以通过 Android 嵌 Python 的技术快速落地（已有开源框架），形成 MVP 产品，之后再慢慢将 Flask 的部分使用 Flutter 或移动端原生语言重写。

如何调试插件

参见《Debugging extensions》。进入插件管理页，选择检查视图，进入一个 Devtools 调试窗口，能够看到 background 脚本的日志。

在弹出的 Devtools 中，进入【源代码】Tab 可以下断点，调试效率大幅提升。

插件基础知识

WebScrapBook 是一个浏览器插件，首先需要补充浏览器插件相关的基础知识。

这一节主要参阅了以下文章：

1. 《【干货】Chrome插件(扩展)开发全攻略》
2. 《10分钟入门chrome(谷歌)浏览器插件开发》
3. 《从零深入Chrome插件开发》

核心概念：

1. Manifest：清单文件
2. Background Script：后台脚本
3. UI 元素
4. Content Script：内容脚本
5. Options Page：设置页面

manifest.json

是一个 JSON 配置清单。内容元素：

• name：插件名称
• description：插件描述
• version：插件版本
• manifest_version：第几代插件格式，2是主流，最新为3
• browser_action：右上角插件按钮
  • default_popup：弹出页面的 HTML
  • default_icon：图标
• commands：定义插件命令，可指定快捷键

manifest 相当于 App 的入口，透过它能够快速了解全貌。WebScrapBook 的 manifest：

name 和 description：

"name": "__MSG_ExtensionName__",
"description": "__MSG_ExtensionDescription__",

为什么是 __MSG_ 的常量定义？查阅到《使用 jQuery 进行前端多语言化的方法》，这是一种基于 jQuery 的多语言展示方案。 permissions

"permissions": [
  "contextMenus",           // 右键菜单
  "downloads",              // 下载
  "storage",                // 数据存储
  "tabs",                   // 标签访问能力
  "unlimitedStorage",       // 默认只有 5MB 存储配额，该权限扩展到无上限
  "webNavigation",          // 导航状态
  "webRequest",             // 发请求
  "webRequestBlocking",     // 屏蔽请求
  "http://*/*",             // 插件匹配所有 http
  "https://*/*",            // 插件匹配所有 https
  "file://*"                // 插件匹配所有本地文件
],

参阅《“https：// * / *”和“＜ all_urls＞”在Chrome扩展程序的权限区分》、《Chrome 应用和扩展程序权限》、《谷歌浏览器插件permissions权限列表大全以及权限字段描述》。

background

background 指常驻页面，生命周期与浏览器一样长，用于处理耗时操作。从中可见，关键逻辑都在这里面。

"background": {
  "persistent": true,
  "scripts": [
    "lib/browser-polyfill.js",
    "core/common.js",
    "core/optionsAuto.js",
    "core/extension.js",
    "core/background.js",
    "scrapbook/server.js",
    "capturer/background.js",
    "editor/background.js",
    "viewer/background.js"
  ]
},

browser_action 点击浏览器图标弹出的菜单：

"browser_action": {
  "default_icon": {
    "32": "core/scrapbook_32.png",
    "128": "core/scrapbook_128.png"
  },
  "default_title": "__MSG_ExtensionName__",
  "default_popup": "core/browserAction.html"
},

web_accessible_resources 插件携带的资源文件：

"web_accessible_resources": [
  "resources/*",
  "scrapbook/sitemap.html",
  "viewer/load.html"
],

options_ui 设置页面：

"options_ui": {
  "chrome_style": true,
  "open_in_tab": true,
  "page": "core/options.html"
},

commands

声明插件的命令：

使用方式，只要出发 Command，浏览器就会向 background 发送一个 command。

对应于 src/core/background.js 的 background：

const background = {
  commands: {
    // ……

    async captureTab() {
      return await scrapbook.invokeCapture(
        (await scrapbook.getHighlightedTabs()).map(tab => ({
          tabId: tab.id,
        }))
      );
    },

    async captureTabSource() {
      return await scrapbook.invokeCapture(
        (await scrapbook.getHighlightedTabs()).map(tab => ({
          tabId: tab.id,
          mode: "source",
        }))
      );
    },

    async captureTabBookmark() {
      return await scrapbook.invokeCapture(
        (await scrapbook.getHighlightedTabs()).map(tab => ({
          tabId: tab.id,
          mode: "bookmark",
        }))
      );
    },

    // ……
  },
};

可以看到，具体操作都是转到了 scrapbook.invokeCapture 中进行。并且传入的参数有两个，一个是 tabId，一个是类型。

capturer.captureGeneral

页面捕捉方法。

根据 capture.saveTo 有多种缓存模式：server 服务器、storage 本地存储、memory 内存缓存。

支持两种页面捕捉方式：

1. Tab 捕捉：通过 capturer.captureTab
2. URL 捕捉：通过 capturer.captureRemote

captureTab

捕获一个 Tab 内的网页信息。

const response = await capturer.invoke(
    "captureDocumentOrFile", 
    message, 
    {tabId, frameId});

来到 src/capturer/common.js：capturer.captureDocumentOrFile，调用 capturer.captureDocument。

capturer.captureDocument

该方法是页面离线化的最核心方法，该方法代码长达 2k 多行。

整体流程如下。首先，cloneDocument 开始搞事情：

// create a new document to replicate nodes via import
const newDoc = scrapbook.cloneDocument(doc, {origNodeMap, clonedNodeMap});

有两种页面捕捉方式：全页面（fullPage）和 Selection 局部选择。

let selection = settings.fullPage ? null : doc.getSelection();

简单起见，这里只看 fullPage 的处理分支。

将老文档的所有子节点拷贝到新文档中，并指定跟节点（rootNode）：

// not capture selection: clone all nodes
for (const node of doc.childNodes) {
  newDoc.appendChild(cloneNodeMapping(node, true));
}
rootNode = newDoc.documentElement;

注：DOM JavaScript API：Element.removeAttribute()：从指定的元素中删除一个属性。

通过以下代码删除页面中的 ScrapBook Toolbar：

// remove webscrapbook toolbar related
rootNode.removeAttribute('data-scrapbook-toolbar-active');
for (const elem of rootNode.querySelectorAll(`[data-scrapbook-elem|="toolbar"]`)) {
  elem.remove();
}

capturer.captureDocument.rewriteNode

capturer.captureDocument 中会对所有节点进行遍历，并对每个节点进行改造。其中，用于对节点进行改造的方法就是 rewriteNode。

capturer.CaptureHelperHandler

capturer.captureDocument 中会调用该方法。会对 options 做一些修改。