先说清楚它是什么
水鱼文集(Waterfish Anthology)是一个自托管的个人文集应用,跑在你自己的 NAS 上。 你把书和文章放进去,它给你一个安静的书架:封面、作者、读到哪儿了,一屏看完。
它不联网同步、不做推荐、不统计你读了几分钟。数据就在自己机器的目录里, 备份就是拷一个文件夹,换机器就是搬过去。界面用什么字体、纸是什么颜色, 也由你决定——内置五套,不够就自己写一套。
主页在 waterfish.ren, 外观系统怎么写,作者在 这篇说明 里讲得很细。
- 书架卡片式陈列,封面、作者、进度一眼看到
- 阅读正文排版,衬线或圆体、字号大小都能调
- 标签按标签翻,不用记文件名
- 深浅色跟随系统或手动切,每套外观自带两套配色
- 外观五套内置加自定义
.js,就是下面这些 - 数据存在自己的 NAS 上,一个账号一份配置
三步,二十秒
不需要命令行,不需要改配置文件。
挑一套
每套都有独立页面,能当场切浅色深色、看它在卡片和列表上的样子。别看缩略图,看真的。
下载 .js
点「下载」,或者把代码复制走自己存成文件。文件名就是主题名,所以叫 湖心纸.js 比叫 theme1.js 好。
上传
设置 → 外观 → 自定义主题 → 选择文件。卡片出现就生效了,立即保存,不用确认。最多存 20 个。
想换回来?在抽屉里点「纸墨」就是内置外观。不想要了就悬停卡片,点右下角的 ✕,它带来的样式和图标会一起清干净。
它为什么不是一个配色表
一开始我也想只让人填几个颜色。但很快就不够了:有人希望卡片悬浮时抬起来一点, 有人想把图标换成自己画的那套,有人觉得标题字距太挤、正文行高太松。这些都不是「颜色」, 是样式和动效,用 JSON 填不出来。
所以主题就是一个 JS 文件。你可以只写三行键值对(主色: #1F6C9F),
也可以写一个 function theme(api),拿到 api 之后调 CSS 变量、注入样式、换图标。
两种写法在同一个文件里,客户端自己判断。
每次应用主题前,客户端会先把上一次的东西全部清掉——变量回退、样式移除、图标还原。 所以复杂主题每次都是从干净状态开始跑,不会越叠越乱;写错了也只是控制台报个错,界面退回内置外观,不会白屏。
主题只在你自己的浏览器里运行,跟着外观配置存在你的账号下。这点很重要, 下一页会说我们怎么保证没人借这个入口干别的。
- api.setVar()改根元素上的 CSS 变量,比如
--accent、--r - api.css()注入一段 style,动效、字距、阴影都写在这里
- api.icon()用 SVG path 覆盖内置图标,颜色跟随
currentColor - api.dark当前是不是深色,可以写两套配色
- api.el根节点,想查哪个元素都行——也是风险所在
怎么防止有人动手脚
说难听点:主题代码在你浏览器里的权限,和页面本身一样大。
它跑在页面主世界(main world),能读 DOM、能发请求。所以这个库不能「谁都能直接 push」。 投稿走 GitHub issue,收进来之前过三道:
-
静态规则。一段代码里出现
eval、new Function、 网络请求、读写 cookie 或 localStorage、动态插 script、改 location、监听键盘—— 任意一条,直接拒,不看别的。 - 模型读一遍。规则只看关键词,看不出「把正文里的链接批量改掉」这种事。 所以再让一个语言模型把代码读一遍,判断它到底想干什么。模型也会看错,所以它只给建议。
- 我自己点。最后一步是人。我点「approved」再关 issue, 机器人这时才会把文件写进仓库、生成页面。
已经收录的也可能变坏——比如它引用了别人域名下的一张图,哪天那张图换成了别的东西。 发现了就下架,不会因为「已经收了」就留着。
- 会拒eval / new Function / 动态 import / 任何网络请求
- 会拒读写 cookie、localStorage、sessionStorage
- 会拒改 location、开新窗口、postMessage、伪造表单
- 会拒外链脚本、长期轮询、键盘监听
- 会看非字体 CDN 的远程资源、超长 base64、不认识的键
完整规则在仓库的 scripts/lib/rules.mjs, 改了什么都能看到。
常被问到的
会不会拖慢打开速度?
一个主题最多 64 KB,绝大多数只有几十行 CSS 变量。真正让页面变慢的是背景图——如果你挂了一张 2 MB 的图,慢的是那张图,不是主题。
能改布局吗?
技术上能。api.el 给你根节点,你可以在里面查任何元素、加类名。但类名会随版本变,写得越深越容易坏。库里大部分主题只动变量和表面样式,就是为了少坏。
主题存在哪?换设备还在吗?
存在你账号下的外观配置里,跟着账号走,换设备登录还在。卸载应用会一起清掉,所以删之前记得把 .js 留一份。
为什么「推荐」不能投稿?
那几套是我自己天天在用的,颜色改了几十遍才定下来。开放投稿它就会变成投票榜,我不想那样。看到合适的,我会主动去要。
收录之后还能撤吗?
能。你开个 issue 说一声,或者我发现行为不对,直接下架。下架不会删历史——文件还在 git 里,只是不再出现在列表。
我能直接提 PR 吗?
可以,但目录名必须是内容哈希,手算容易错。建议还是走 issue,机器人会算好。PR 走的校验和 issue 是同一套。