把 AI 阅读工具做成 local-first:页边 ThinRead 的架构、取舍与踩坑

利益相关:我是「页边 ThinRead」的作者。项目 MIT 开源,macOS 桌面端,当前版本 0.2.2。

这篇不讲怎么接大模型。它是一份已经发布的桌面产品复盘:哪些架构约束最后真的改变了产品,哪些看起来正确的做法其实走不通。

页边想解决的问题很具体:读完一章之后,能不能留下一篇可以继续改的稿子、几张有原文依据的卡片,以及一条和其他书之间的连接?

它不是一个书摘仓库,也不是问答机器人。主链路是:

text 复制代码
导入 → 阅读 → 读薄 → 卡片 → 连接 → 成书 / 分享卡 / 播客

当前版本大概能做这些事:

  • 导入 EPUB、PDF、MOBI 等 8 种文件,也能导入网页、OPDS、微信读书、Readwise 和 Kindle 划线;
  • 扫描版 PDF 用 macOS PDFKit + Vision 做 OCR,单次最多 300 页;
  • 按断言把整章改写成底稿,保留观点和原文依据;
  • 从底稿提炼卡片,每张卡片要求逐字引用;
  • 本地语义索引做跨书回声、知识地图和人物关系图;
  • 成书、Markdown / HTML / 排版 PDF、6 种分享卡、小红书 3:4 图文、千问 TTS、A/B 双人播客;
  • 19 个 AI 工作台工具,共用同一份书和笔记;
  • Electron + React + TypeScript,数据落在本地 SQLite 和文件里。0.2.2 把数据库拆成 db-books / db-notes / db-content / db-reading / db-health,db.ts 只保留兼容门面。

下面按真实的取舍来讲:为了让"本地优先"和"引用可信"不只是宣传语,代码里到底做了什么。

图 1:阅读器里的正文、本章笔记和读薄稿

两条不能妥协的约束

页边有两个不肯让步的地方。

一个是数据边界。书、章节、笔记、生成历史都在本机;AI 调用由用户显式触发;语义计算在本地完成。这不是写在隐私政策里的承诺,是架构本身。

另一个是模型输出不可信。生成结果要经过引用核对、结构校验和可回滚的写入,不能直接覆盖用户的数据。

这两句话落到工程上,会变成一串很具体的问题:

  • 哪些计算必须留在本机,哪些可以出网?
  • 流式输出到一半断了,已经写入的笔记怎么办?
  • 模型把引用改了一个字,算不算通过?
  • 本地向量模型首次下载和索引重建怎么处理?
  • 用户换模型、换服务商,流式协议、JSON 模式、缓存策略都不一样,抽象层怎么切?

下面按这些问题拆。

数据流和边界

整体结构不复杂,但边界卡得很死:

text 复制代码
┌──────────────────────────────────────────┐
│ Renderer: React + TypeScript             │
│ 书架 / 阅读器 / 笔记库 / 工作台 / 设置     │
└───────────────────┬──────────────────────┘
                    │ typed IPC(preload)
┌───────────────────▼──────────────────────┐
│ Electron main                            │
│ 导入 / 解析 / AI / 导出 / 备份 / 任务中心  │
└───────┬──────────────────┬───────────────┘
        │                  │
   SQLite + 文件       模型服务(可选)
        │
  本地 BGE-small-zh 向量索引

几个关键边界:

  • 渲染进程不能直接 import Electron 或 Node 内置模块,CI 里有 check:boundaries 拦;
  • 主进程负责文件、数据库、模型调用、导出和备份,渲染进程只通过 typed IPC 说话;
  • 书文件、数据库、导出物都在本机。主要的出网路径只有三条:用户主动触发的模型调用、网页 / OPDS 导入,以及首次下载约 23 MB 的量化向量模型;
  • API Key 存在系统钥匙串;钥匙串不可用时回退到 0600 文件,并在设置里明确告诉用户这是明文。

这个结构不新,但它让"local-first"变成了可以检查的约束,而不是一句口号。

导入链路里,脏数据是常态

阅读工具的第一道坎不是 AI,是导入。EPUB 的目录结构千奇百怪,PDF 有扫描版、双栏、页眉页脚、代码块,网页正文里混着导航和广告,微信读书、Readwise、Kindle 的划线格式又各不相同。

处理顺序是:先判断来源和格式,再做正文抽取或 OCR,然后分章,最后才进阅读器。扫描版 PDF 用 PDFKit 渲染页面、Vision 逐页 OCR;Docling 深度解析用来恢复代码换行和缩进;目录页、版权页和广告页会被识别并隐藏。

这块没有"一次做完"的捷径。每多支持一种输入,就多一堆边界情况。但它决定了后面的读薄和卡片是不是建立在干净文本上。

引用核对:让模型过不了这一关

AI 笔记最危险的地方,是它看起来很对,引用却是编的。

页边的规则很简单:每张生成的卡片必须带一段原文引用,引用必须能在章节正文里逐字找到;找不到就标成"待核对"或"无引用",不允许冒充作者原话。

简化后的逻辑大概是这样:

ts 复制代码
// 简化示意:normalize 的具体实现省略
declare function normalize(value: string): string

function verifyQuote(quote: string, chapter: string) {
  const q = normalize(quote)
  const c = normalize(chapter)

  if (!q) return { status: 'missing' as const }
  return c.includes(q)
    ? { status: 'verified' as const }
    : { status: 'pending' as const }
}

// normalize 会处理空白、换行、全半角标点和 OCR 噪声;
// 实际实现还会保留原文位置,方便点击回到章节。

代价是有的:

  • 模型偶尔改一个词、合并两句话,引用就会失败;
  • OCR 噪声会让一些本来正确的引用变成"待核对";
  • 用户会看到更多"不完美"的状态,而不是一个干净漂亮的摘要。

但它换来了一个更重要的东西:用户敢引用。对阅读笔记来说,可信度比覆盖率重要。宁可少一张卡片,也不要多一条假引用。

引用状态要进入 UI

"核对"不能只停在数据库里。页边把每条引用标成已核对 / 待核对 / 无引用,笔记库可以按这个筛,章节有覆盖度,读薄稿、成稿和报告可以做版本 diff。

这带来一个反直觉的体验:用户第一眼看到的不是"完美笔记",而是"哪些地方还需要看"。但这正是阅读工具该有的样子。AI 负责起草,人负责确认。

流式输出,但不能写半成品

模型输出是流式的,但数据库写入不能是流式的。

页边的做法:

  1. 宽松解析流式片段。模型可能在 JSON 前后加说明文字,也可能在流式过程中输出不完整结构,先用宽松解析拿到候选对象;
  2. 字段和类型归一化。把常见的枚举、空值、数组和字符串混用修到可校验的形态;
  3. zod 校验。通过后才允许写库;
  4. 纯文本 JSON 兜底。结构化解析失败时,再尝试从纯文本里提取 JSON;
  5. 失败不覆盖。无效 payload 直接拒绝,不会把原来好的笔记冲掉。

还有一个容易忽略的点:格式化和改写要可回滚。页边把格式化结果单独存在 formatted_html 里,原始 HTML 不销毁;成稿历史保留多个版本,最多 40 个,可恢复。

这套东西的工程成本不低,但它避免了一类很恶心的问题:用户看到一半结果,刷新之后笔记变成半截,或者原始内容被一次失败的重写覆盖。

本地向量:不把笔记传上去

跨书连接是页边和普通笔记工具差别最大的地方,也是最容易做成"云端黑盒"的地方。

页边的选择是:用本地 BGE-small-zh 计算笔记向量,索引和缓存都留在本机。

具体做法:

  • 对笔记标题、标签和正文做 embedding;
  • 向量缓存到本地,按内容哈希更新;
  • 跨书回声、知识地图、人物关系图共用这份索引;
  • 笔记内容不出网。只有用户主动调用在线模型时,才发送必要的章节正文。

代价也很明确:

  • 首次要下载约 23 MB 的量化模型;
  • 索引重建需要时间,书多的时候更明显;
  • 中文语义效果优先,其他语言的跨书召回会弱一些;
  • 本地模型的能力上限不如最大的云端模型。

但这是我认为值得的取舍。阅读笔记是很私人的数据,如果为了"更准一点"把所有笔记上传到云端,产品的信任基础就变了。

模型层:AI 是可选件

页边没有把产品绑死在一家模型上。当前内置 13 套预设(12 家服务商加演示模式),包括 DeepSeek、智谱 GLM、Anthropic、OpenAI、Moonshot、阿里云百炼、OpenRouter、OpenCode Zen / Console、OpenCode Go、OpenDesign Cloud,以及本地 Ollama 和 LM Studio。任意 OpenAI 兼容端点也可以填。

抽象层不是换一个 baseURL 就结束了。实际要处理的差异包括:

  • 流式响应的分片格式;
  • JSON 模式、结构化输出的支持程度;
  • Anthropic 的 cache_control 和 OpenAI 兼容端的自动前缀缓存;
  • 千问 TTS 的原生协议;
  • 不同服务商的限流、错误码和重试策略;
  • 本地 Ollama / LM Studio 没有 Key、模型名不固定的情况。

主流程统一走 OpenAI 兼容层,Anthropic 和 TTS 用原生适配器;失败只对 429、5xx、超时这类可恢复错误做指数退避重试。

差异点 处理方式
流式分片 统一适配成增量文本
JSON 输出 优先结构化解析,失败走纯文本兜底
前缀缓存 Anthropic 显式 cache_control,OpenAI 兼容端依赖自动缓存
本地模型 Ollama / LM Studio 免 Key、模型名不固定
TTS 千问原生协议单独适配

还有一个产品判断:AI 是可选件。没有 API Key 时,演示模式可以走完整条链路;本地 Ollama 也能免 Key 使用。用户可以先看清楚"读薄、卡片、核对、导出"到底长什么样,再决定要不要接真实模型。

数据完整性:本地产品没有服务端兜底

阅读工具的数据是长期资产。功能少一点可以补,数据坏了很难救。

页边在数据层做了这些事:

  • SQLite 迁移按 PRAGMA user_version 顺序执行,事务内失败回滚;
  • settings.json 用临时文件加 rename 原子替换;损坏文件保留为 .corrupt-<timestamp>,在界面里提示,而不是静默重置;
  • 笔记读取时也做校验:非法枚举降级为安全值,坏 JSON 跳过并计数,计数进入诊断包;
  • 书、章节、笔记、生成物都有 30 天回收站;
  • 合并、拆分、重解析、删除前自动备份;自动备份保留 8 份;
  • 书文件按内容哈希去重,备份不会因为重复文件膨胀。

这些工作用户平时看不见,但它们是"本地优先"能成立的前提。云端产品可以靠服务端兜底,本地产品只能靠自己的写入路径足够克制。

跨设备也一样:没做实时同步,只做手动快照。可以推整库,也可以只推一份不含书文件的精简笔记快照;快照可选 AES-256-GCM 加密成 .thinsync,口令不落盘。合并时按时间戳只取较新的笔记、PDF 标注、书签、阅读位置、统计和周复盘,不删除本地内容;本地没有的书会连同章节和书文件一起导入。恢复前会先备份当前状态,还可以先"比较"本地和远端的记录数量,再决定合并还是整库恢复。

这个方案不性感,但它承认了一个事实:本地优先的同步,难点不在把文件传上去,而在两边都改过之后,怎么不悄悄丢数据。

成本和速度

AI 阅读工具很容易变成"每点一次都在烧 token"。页边做了几层缓存和并发控制:

  • 读薄按段落并发,标准 / 快速模式最多 6 路,深度模式 4 路;
  • 断言审计和卡片提取并行;
  • 结果按"章节内容 + 模型 + 质量档位"的内容哈希缓存 14 天,命中时 0 token;
  • 深度模式复用 24k token 的源文前缀,Anthropic 用显式 cache_control,OpenAI 兼容端依赖自动前缀缓存;
  • 短章节、低压缩比、小卡片集会自动跳过不划算的阶段;
  • 全文索引缓存成 search-index.json.gz,签名不变时直接加载;
  • 生成快照按"工具 + 范围"只保留最近 30 个,收藏和当前版本不剪。

这些优化不改变产品形态,但会直接影响用户愿不愿意长期用。一个每次读一章都要重新算全书的工具,很难成为日常工具。

视觉 PDF 的跨平台渲染

视觉 PDF 是导入链路里最贵的一步:把每一页渲染成图片,再交给视觉模型转成 Markdown。它适合扫描版、教材、跨页表格和图表很多的 PDF,但也最容易把平台限制暴露出来。

最早的实现只支持 macOS:主进程调用一个 Swift 脚本,用 PDFKit 把页面导成 JPEG。Windows / Linux 上点下去只会得到一句"暂不支持"。这不算错,但对一个 local-first 工具来说,渲染层被一个平台写死,后面的跨平台就无从谈起。

0.2.2 的做法是加一条跨平台兜底,而不是重写整条链路:

ts 复制代码
// 先试 macOS 的 Swift 渲染
let rendered = await renderPdfPages(sourcePath, imageDir, batch)

// 失败或平台不支持时,用 pdfjs + @napi-rs/canvas 栅格化
if (rendered.length === 0) {
  rendered = await renderPdfPagesWithCanvas(doc, imageDir, batch, signal)
}

两个渲染器输出同样的 page-<n>.jpg,后面的读图、缓存、失败页兜底完全不用改。每批 120 页,批内并发 2;页面按 1.5 倍渲染,JPEG 质量 72,既保证模型能看清表格,又不至于把图片体积翻几倍。

真正花时间的是一个很隐蔽的坑:pdfjs 在 Node 里默认 disableFontFace: true,会用自带的 Path2D 描字;而 @napi-rs/canvas 的 Path2D 不是同一个实现,ctx.fill(path) 会直接抛 CanvasFillRule 枚举错误。关掉 disableFontFace,让它走正常的 fillText,图片才稳定出来。

缓存也按页做:键是"模型 + 上一页末尾 + 图片哈希",重跑同一页不会重复烧 token;跨页表格和公式会保留上一页的上下文,避免每页都从零开始。识别出的块还会整理成「表格与公式索引」,导入后生成可编辑的卡片,而不是只在正文里留一段 Markdown。

需要说清楚的是:这只是渲染层跨平台,当前发布的安装包仍然只有 macOS。Windows / Linux 还需要实机验证、OCR 引擎和安装包适配。但至少,视觉 PDF 不再是一个从架构上就锁死单平台的功能。

没走通的路

复盘里更有价值的部分,往往是"没做什么"。

页级摘要。 早期很容易做成"每页生成一段摘要",看起来功能很全,但输出仍然是一堆碎片。用户不会因为摘要更多而更容易写作。后来改成"按断言重写整章",产物才立得住。

云端优先。 云端做向量、存储和协作会简单很多,但会改变隐私边界和迁移成本。选择本地优先,就要接受同步、备份、跨设备这些事更难做。

全自动替用户读书。 "导入一本书,直接给你一篇成稿"听起来很吸引人,但它会把引用核对和人工判断挤掉。我的底线是:AI 可以起草,引用必须能回到原文。

一开始就做全平台。 macOS 的 PDFKit、Vision OCR、钥匙串让本地链路更快落地;Windows 和 Linux 需要新的 OCR 引擎和实机验证。现在只发 macOS Apple Silicon,未签名构建。这不是不想做,是不想用一个没验证过的版本消耗信任。

怎么验证它不是演示壳

截至 0.2.2,仓库里有近 300 个回归测试,覆盖划线解析、OCR 分章、发布包、分类、关系图、全文索引、备份恢复、schema 校验和迁移。

除此之外还有:

  • Headless Electron smoke tests,覆盖书架、搜索、划词操作、TTS、笔记编辑、地图、导入和分页;
  • Storybook 像素基线,CI 里做 diff,布局漂移会让构建失败;
  • axe-core 注入 UI smoke test,扫描 WCAG 2A/2AA 的 critical / serious 问题;
  • CI 不需要 API Key:真实模型响应录制一次,之后回放;
  • check:boundaries 阻止渲染进程直接依赖 Electron / Node,架构边界由 CI 守。

这些测试不能证明产品一定好用,但至少能证明它不是只有几张截图的 demo。

适合谁,不适合谁

适合:

  • 主要读非虚构,读完之后确实要写点东西的人;
  • 愿意花时间核对引用,而不是只要一个"看起来很美"的摘要的人;
  • 在意书和笔记留在本机的人;
  • 用 macOS,能接受未签名构建和手动安装的人。

不适合:

  • 想要"AI 替你读书"、直接看结论的人;
  • 需要书源、盗版下载或全网书库的人;
  • 需要记忆卡、考试队列、间隔重复的人;
  • 需要多人协作、云端账号、实时同步的人;
  • 现在就要 Windows / Linux / 移动端的人。

如果重来一次

我会更早把"引用核对"做成 UI 的一等状态,而不是先做漂亮的摘要。会更早接受本地产品没有服务端兜底,把备份、迁移、损坏恢复放进第一版。也会更早把模型层抽象出来,而不是先绑一家服务商再拆。

还有一点:会更早承认产品有边界。页边不替用户读书、不提供书源、不做记忆卡、不做云端协作。这些"不做"省下来的时间,最后都变成了把读薄、卡片、核对做扎实。

图 2:知识地图

怎么试

当前版本 0.2.2,macOS Apple Silicon,MIT 开源,构建未签名。第一次打开如果提示"无法验证开发者",在 Finder 里右键应用,选择"打开",或者到"系统设置 → 隐私与安全性"里允许本次打开。

如果你只想看效果,可以先不配 Key,用内置演示书走一遍读薄、卡片、核对、导出。觉得这条链路成立,再考虑接自己的模型。

Local-first 不是"永远不上云",而是每一条出网路径都能解释清楚,每一份本地数据都有可恢复的写入路径。

页边离"完美"还很远:同步、数据库加密、跨平台 OCR、移动端都还在路上。但它至少在两个地方没有妥协:书和笔记先属于用户;模型可以起草,引用必须回到原文。

如果这两条也是你在意的,欢迎试试。点个 star、提 issue,或者去公开留言板写你卡在哪一步,都是支持;也欢迎在评论区聊聊你的读书笔记流程。

相关推荐
双鱼大猫1 小时前
opencode 吃掉 100G 空间:Agent 会话数据要分级清理
人工智能·agent·ai编程
ZzT2 小时前
约 90% 代码由 Claude 写和审,Claude Code 团队如何做验证
ai编程·claude
一切皆有可能!!2 小时前
【SoduWork测评】本机跑源码,找到并修了7个Bug
windows·开源·bug·ai编程·soduwork
jianqiang.xue2 小时前
把Agent塞进MCU:工具次数和上下文长度怎么卡
java·前端·网络·单片机·esp32·ai编程
莪_幻尘2 小时前
AI 编程的下一场战争,不在模型,在协议
agent·ai编程·mcp
oil欧哟3 小时前
AI Agent Skill 入门指南:文件夹本质、渐进式加载与挑选方法
人工智能·ai编程
挖掘狂人4 小时前
AI 三分钟写完的代码,你凭什么敢直接上线?
人工智能·程序员·ai编程
codigger4 小时前
AI 三分钟写完的代码,你凭什么敢直接上线?
ai·程序员·编程·ai编程·#人工智能
回家路上绕了弯4 小时前
让错误活不过 N 步
ai编程