基于TextRank与Flutter的阅读助手APP实战：从文件解析到打卡闭环

阅读习惯坚持不下来，买书如山倒，读书如抽丝，这大概是所有阅读爱好者共同的痛点。去年我用业余时间做了个阅读助手APP，把“读完一本书”这件事拆成了几个可以量化的动作：上传书籍自动生成摘要，摘出核心观点和好词好句，随手标注笔记，每天记录阅读时长，最后形成一张阅读打卡日历。这篇文章就把我落地这个项目的完整过程、技术选型、核心实现和踩坑记录都写出来，给想动手做同类产品的朋友一份能直接参考的复盘。

这个项目并不是那种到处都需要黑科技的大型系统，但它把“阅读”这个流程中容易被忽略的技术点都串了一遍：文件解析、中文分词、抽取式摘要、标注存储、阅读计时、日历聚合。过程中有不少细节只有做到了才会踩到，比如PDF解析后文本全是乱码、TextRank算法跑出来的摘要把“但是”和“此外”当成了核心句、计时在后台被系统杀掉导致打卡断签等等。下面我按项目的实际推进顺序来写，从需求拆解到技术实现再到问题排查，尽量做到可以照着复刻。

1. 产品定位与功能拆解

1.1 阅读爱好者的真实需求是什么

做产品之前最忌讳一上来就写代码。我对身边喜欢读书的朋友做了一圈调研，发现大家共同的痛点不是“找不到书”，而是“读不完”“记不住”“没反馈”。囤了上百本电子书，真正读完的不到十分之一；读完一本书记不住核心观点，过两个月跟没读一样；每天阅读时间零散，总觉得没进度。于是这个APP的核心价值被我定义为：帮用户在碎片化的阅读场景里，快速抓住一本书的要点，并持续获得正向反馈。

围绕这个定义，我把产品的功能清单拆成了六项：

• 上传书籍/文章，自动解析文本内容
• 自动生成阅读摘要，提炼核心观点
• 提取好词好句，方便摘抄和后续回顾
• 支持对原文进行标注，写阅读笔记
• 记录阅读时长，形成个人阅读数据
• 按日期生成阅读打卡日历，建立打卡习惯

这六个功能看起来独立，实际是一条完整的产品链路：输入（上传/阅读）→ 加工（摘要/词句）→ 沉淀（笔记/数据）→ 激励（打卡日历）。如果只做其中的摘要或只做打卡，用户体验会很单薄；把它串起来之后，用户的每次阅读都会变成可积累的数据资产。

1.2 优先级排序与MVP范围

这个产品最初版本我做了严格的功能取舍。自动摘要和好词好句是差异化亮点，但没有上传解析就无从谈起，所以第一步必须打通“上传→解析→展示”；阅读计时和打卡是用户持续打开APP的动力，属于低成本高价值的功能，尽早放进来；阅读笔记则要在阅读器稳定之后才能做好，否则标注内容容易存废。

最终的MVP版本只包括：TXT/EPUB/PDF上传、纯文本阅读器、抽取式摘要、好词好句展示、划线笔记、阅读计时、周视图打卡日历。像账号系统、云端同步、分享海报、书单管理这些都放到第二版。这样做的理由是先把核心路径跑通，避免一开始就被账号和同步的复杂性消耗过多精力。

2. 技术选型与整体架构

2.1 客户端为什么选Flutter而不是原生

客户端选了Flutter，原因很直接：项目是我一个人业余开发，不可能同时维护iOS和Android两套原生代码。Flutter在跨端场景下的渲染一致性做得不错，阅读器这种文本密集型界面，它的TextPainter和自定义选择器也能满足需求。

具体用到的核心依赖大概有：

• file_picker：负责选择本地文件
• epub_view/pdfx：处理EPUB和PDF预览
• sqflite：本地存储笔记和阅读记录
• shared_preferences：轻量偏好设置
• 自研的TextSelection扩展：实现划线标注

有朋友问我为什么不直接用原生开发套壳WebView，我的回答是：阅读器需要精细的文本选择、翻页动画、亮度调节和夜间模式，WebView在这些交互上做起来很别扭，尤其是中文文本标注的坐标换算，用原生组件反而更稳定。

2.2 服务端职责与数据处理管线

摘要提取、好词好句筛选、阅读时间统计这些计算放在了后端，前端只负责上传文件、展示结果和收集用户行为。前后端用FastAPI搭接口，模型层直接用Python生态，这样后面接更复杂的NLP模型时也不需要重写。

服务端的处理管线我设计成了五步：

1. 接收文件，按扩展名分流解析
2. 清洗文本，去空行、去乱码、去目录和版权页
3. 中文分词、词性标注，构建候选词集
4. 使用TextRank算法对句子排序，生成摘要
5. 基于摘要句和高频词提取好词好句，写回JSON

这个管线的设计原则是“每个环节的结果都可解释”。比如摘要的权重矩阵可以打印出来，方便排查为什么抽到了某一句；好词的来源可以直接追溯到分词结果，不会出现“词都不在原文里”的尴尬。

2.3 摘要与关键词提取：抽取式比生成式更稳

文本摘要大体分两类：抽取式（从原文挑重要句子）和生成式（让模型重写一段话）。生成式效果上限更高，但模型响应慢，而且容易“一本正经地瞎编”，把原文没有的观点加进去。对阅读场景来说，用户要的是“这篇文章到底讲了什么”，而不是“模型觉得这篇文章讲了什么”，所以我选了抽取式。

抽取式摘要的核心是排序。句子重要度来自关键词频率、位置权重、与标题的相似度等信号。我在此基础上叠加了TextRank，它和PageRank一个思路：把句子当节点，如果两个句子有重复词就建立一条边，反复迭代后得到每个句子的权重，然后按权重取TopK。这样做的好处是不需要标注数据，任何一本书都能跑，缺点是遇到文中大量的转折词和并列句时，容易抽出没有结论的过渡句。后面我在预处理阶段做了去停用词和按“段首句加分”的修正，效果才稳定下来。

3. 核心功能实现详解

3.1 文件上传与格式解析

上传环节是整个产品的地基，格式兼容性直接决定用户会不会流失。我第一版只支持TXT，后来加了EPUB和PDF，结果在解析时踩了不少坑。

TXT文件是最简单的，但编码是个大坑。Windows上常见的TXT是GBK/GB18030，Mac和手机端多为UTF-8，如果直接按UTF-8读GBK文件，会出现满屏乱码。我在后端用chardet自动检测编码，再配合bytes.decode()进行转换，基本能覆盖95%以上的情况。

EPUB文件本质是个ZIP包，我用ebooklib解析，循环读取get_items_of_type(ebooklib.ITEM_DOCUMENT)拿到HTML内容，再用BeautifulSoup去掉标签、还原段落。这里要注意EPUB里的章节顺序不一定按文件名排列，很多时候是随机的，需要用spine字段维持阅读顺序，否则摘要会乱序。

PDF文件最麻烦。文字型PDF用pdfplumber提取还比较顺，但很多电子书是扫描版，必须挂OCR。MVP阶段我没有直接做OCR，而是先提示用户“当前PDF不支持文字提取，建议上传TXT或EPUB”，后续再考虑接入PaddleOCR。不要小看这个提示，它能帮你过滤掉大量无效解析请求。

3.2 自动摘要生成与核心观点提取

摘要模块我用的是“TextRank + 位置加权 + 去重合并”的组合方案。完整实现可以拆成四步。

第一步是文本预处理。把文章按句号、问号、感叹号拆成句子，去除段落标题、版权页、目录等噪声；接着用jieba分词并标注词性，过滤掉停用词和数字。

第二步是构建句子相似度矩阵。两句话的共同词越多，相似度越高。这里的相似度不是简单的Jaccard系数，而是做了一次词频加权：核心词越罕见，权重越高。计算时如果两句话之间没有共同词，就认为无关，这样能避免句子数量很多时图变成完全图，计算量过大。

第三步是TextRank迭代。阻尼系数我取0.85，窗口大小用整篇文档的句子图，不再额外设定滑动窗口。迭代20轮后每个句子会得到一个稳定分数。然后在这个分数上叠加一个“位置加成”：每个小节的第一句话加0.5分，最后一句加0.3分，因为作者通常会在段落首尾放核心观点。

第四步是抽取摘要句。默认按原文长度的1%到3%抽取句子，比如一篇5000字的文章，大约抽150字左右的摘要。抽取时还有一个重要步骤是去冗余：如果两个候选句的相似度超过0.7，只保留分数更高的那一句。这个操作能避免摘要反复围绕同一个词转圈。

观点提取则是在摘要句基础上做的。我把摘要句两两合并，然后统计句子里出现的高频名词短语，把它们归类成3到5个主题词，再为每个主题词找到它在摘要中对应的句子作为“核心观点”。这样用户在摘要页看到的不是一个整块，而是“主题+对应句子”的卡片形式，阅读负担会小很多。

import jieba.analyse import numpy as np from collections import Counter def textrank_summary(sentences, top_k=3): # 简化版：用词频矩阵近似句子相似度 tokens = [set(jieba.analyse.extract_tags(s, topK=10)) for s in sentences] mat = np.zeros((len(sentences), len(sentences))) for i in range(len(sentences)): for j in range(i+1, len(sentences)): common = tokens[i] & tokens[j] if len(common) > 0: score = len(common) / (len(tokens[i]) + len(tokens[j]) + 1e-6) mat[i][j] = mat[j][i] = score score = np.ones(len(sentences)) for _ in range(20): score = 0.15 + 0.85 * (score @ mat / (mat.sum(axis=1) + 1e-6)) ranked = np.argsort(-score)[:top_k] return [sentences[i] for i in sorted(ranked)]

3.3 好词好句的筛选逻辑

好词好句的判断天然带主观性，但产品不能完全主观，所以我把筛选逻辑分成了两层：第一层是“硬条件”，保证词句本身质量；第二层是“软排序”，把更符合阅读审美的句子排到前面。

好词筛选我用的是“词性白名单 + 词频 + 长度限制”。先利用jieba.posseg把词汇按词性过滤，只保留形容词、动词、成语和部分名词；然后过滤掉口语词和停用词；最后按照“文档频率”排序，保留出现次数适中、但具有一定书面语色彩的词。举个例子，在小说里“凝视”比“看”更有价值，“心不在焉”比“走神”更值得摘录。这里我还做了一个自定义词库，把常见的好词如“淋漓尽致”“脍炙人口”提前加进去。

好句筛选则分三步：第一步，句子必须以句号、问号或感叹号结束，长度在20到80字之间，太短没有信息量，太长阅读体验差；第二步，句子至少包含一个好词或一个关键词；第三步，计算句子情感强度，对带感叹号或明显情感词（“悲伤”“喜悦”“愤怒”等）的句子加分。经过这三步之后，再从高往低取10到20句。

这里有个经验之谈：千万不要只按“包含关键词”去抽好句，否则会抽出大量背景介绍和过渡句，比如“此外，他还提到了一个重要观点”这种。更好的办法是把TextRank的句子权重和好词覆盖度做加权组合，权重各占50%，这样抽出的句子既有信息量又有文采。

3.4 阅读笔记与标注系统设计

标注系统的核心难点不在画高亮，而在“如何让高亮在下次打开时还能从原文中定位到”。我在MVP里用了一个简单的方案，记录三件事：书籍ID、段落索引、段落内字符偏移。

具体做法是：解析文本时，把整本书按章节和段落拆成结构化对象，每个段落有一个稳定ID。用户在某段文字上划选时，记录start_offset和end_offset。这里有个小坑：如果用Unicode字符偏移，在Emoji或特殊标点上会计算不准，所以我统一使用UTF-16码元偏移，字符串的substring方法和底层文本处理都能对齐。

笔记数据模型设计成三张表：paragraphs表存段落内容，highlights表存标记位置，comments表存用户笔记。用户写笔记时，通过highlight_id关联到原文段落，这样即使后续调整了排版，只要段落ID不变，笔记就不会丢。

class Highlight { final String bookId; final int paragraphIndex; final int startOffset; final int endOffset; final String content; final String note; final DateTime updatedAt; }

阅读器页面上的交互是这样的：长按选择文本后弹出菜单，点击“高亮”生成一条标记，点击“笔记”会打开底部弹窗输入文字。所有标注先写本地SQLite，再在Wi-Fi状态下异步同步到服务端。同步方案我用了最简单的“时间戳+软删除”：每条记录带updated_at，同步时两边取较新的版本。这个方案应付单人单设备绰绰有余，但如果是多设备同步，还需要引入UUID和冲突合并策略，建议第二版再加。

3.5 阅读时长记录与阅读打卡日历

阅读时长统计的门槛比想象中高。用户不是随时都在屏幕上，翻页间隙、切后台回微信、锁屏听播客，这些状态都要处理。

我采用的是“前台计时 + 后台暂停 + 定期上报”策略。APP进入阅读器页面时启动计时器，每隔15秒向Local DB写入一条累计时长；APP进入后台时暂停计时；从后台回前台时，先检测当前时间与上次记录的间隔，如果超过3分钟，就认为这段时间不算阅读时长，因为用户大概率切出去干了别的。

为了过滤异常数据，服务端还会做二次校验：

• 单次阅读时长小于10秒的记录直接丢弃
• 单次阅读时长超过3小时的记录拆分到3小时上限
• 每天总阅读时长最多只取12小时

打卡日历则是读数据库里的阅读记录，按日期聚合总分钟数。只要当天阅读超过5分钟就算打卡成功。日历视图我用了table_calendar，把每天的阅读时长映射成圆环和大数字，连续打卡天数在顶部展示。这里要注意时区问题：如果服务器按UTC存时间，客户端直接格式化会出“昨天打卡丢失”的Bug，所以记录时间要统一用ISO 8601带时区存，展示时再转本地时区。

4. 实操过程与核心环节实现

4.1 环境搭建与依赖清单

整个项目我用了前后端分开的仓库。后端是Python 3.10 + FastAPI + uvicorn，前端是Flutter 3.x。这里我给一份我实际用的关键依赖清单，版本号不一定最新，但组合起来很稳。

建议在Python虚拟环境里装包，不然jieba的词典加载会和系统Python发生冲突。Flutter端我用了dart pub add，没有手动改过pubspec.yaml，这样依赖版本不容易冲。

4.2 服务端摘要接口实战

服务端核心接口是POST /api/summary，接收文件，返回摘要、好词好句和核心观点。代码实现上我把解析和摘要拆成两个service，方便单独调试。

from fastapi import FastAPI, UploadFile from services.parser import parse_file from services.summarizer import summarize app = FastAPI() @app.post("/api/summary") async def create_summary(file: UploadFile): content, meta = parse_file(file.filename, await file.read()) result = summarize(content) return { "title": meta.get("title", file.filename), "summary": result["summary"], "keywords": result["keywords"], "good_sentences": result["good_sentences"], }

跑起来之后，可以用uvicorn main:app --reload启动，然后通过FastAPI自带的/docs页面手动上传文件测试。第一次测试我传了一本《活着》的EPUB，摘要出来后发现结尾把“苦根也死了”当成了核心观点，原因就是这段文本在书里很短但情感权重极高，后来我在好句筛选里加了“是否为中心人物出现”的上下文判断，才缓解了这个问题。

移动端上传代码很简单，用file_picker拿到文件路径后，直接以multipart/form-data形式POST到后端。为了照顾大文件，我限制了上传大小为20MB，超过的会提示用户压缩后再试。

4.3 移动端阅读器与标注的实现

阅读器页面是整个APP里最复杂的一块。文本展示我用了Scrollable+RichText，而不是WebView，因为要做自定义选择回调。核心思路是：把段落列表渲染成一列，每段一个RichText，当用户长按触发系统选择时，通过TextSelection回调取到起止位置，再换算出段落索引和偏移量。

SelectionArea( onSelectionChanged: (selection) { if (selection != null && !selection.isCollapsed) { final offset = selection.baseOffset; final paragraphIndex = _getParagraphIndex(offset); final start = _getLocalOffset(paragraphIndex, offset); _showAnnotationMenu(paragraphIndex, start); } }, child: Column(children: _buildParagraphs(_paragraphs)), )

这里有一个真实的踩坑经历：如果直接用SelectionArea包裹整个Column，Android和iOS的选中回调行为不一致，iOS经常拿到全局坐标而不是局部坐标。后来我在每个段落外面单独包了一层SelectionArea，再通过TextPainter做坐标换算，选择定位才稳定下来。

4.4 数据存储与同步方案

移动端本地存储我用SQLite，表结构大致如下：

CREATE TABLE books ( id TEXT PRIMARY KEY, title TEXT, author TEXT, file_path TEXT, created_at INTEGER ); CREATE TABLE highlights ( id TEXT PRIMARY KEY, book_id TEXT, paragraph_index INTEGER, start_offset INTEGER, end_offset INTEGER, content TEXT, updated_at INTEGER ); CREATE TABLE reading_sessions ( id TEXT PRIMARY KEY, book_id TEXT, start_time INTEGER, duration_seconds INTEGER, date TEXT );

同步到云端时，我会把highlights和reading_sessions中updated_at大于上次同步时间的记录查出来，POST到云端的/api/sync接口。云端同样是PostgreSQL，表结构和本地保持一致。冲突策略简单粗暴：谁后修改谁赢。对于单人阅读工具来说够用了。

建议不要把“每日阅读时长”算在客户端，而是让服务端按reading_sessions里的date字段聚合。这样即使用户换了设备，打卡日历也能恢复。

5. 常见问题与排查技巧实录

5.1 上传PDF后中文全是乱码

这个问题出现频率最高。原因一般是PDF本身的文本编码不是标准的Unicode，或者字体嵌入导致提取不出来。我用的pdfplumber对文字型PDF效果好，但遇到部分中文老书会乱码。

排查方法：先打开PDF文件看能否复制文字，如果能复制但乱码，就要用pdfminer.six并开启codec='utf-8'；如果连复制都不行，那就基本确定是扫描版，必须走OCR。我为了方便用户，在解析失败时直接返回错误码UNSUPPORTED_PDF，前端弹窗提示换成文字版。

5.2 摘要生成结果句不成句，读起来很生硬

TextRank抽出来的句子虽然重要，但有时候单独拿出来缺少上下文。我试过把摘要句直接拼接，结果读起来像“因为没有…所以…另外…”，完全没有可读性。

解决方法是增加一个“上下文扩展”步骤：对每个摘要句，如果它是以连接词（“但是”“然而”“因为”“所以”“此外”）开头，就把它的前一句也带上。同时，如果摘要句长度小于15个字，也把后一句顺进去，保证摘要句的信息完整。这个规则非常简单，但实测能让摘要的自然度提升一大截。

5.3 阅读计时经常少算或者多算

少算多见于用户连续阅读但APP在后台被系统回收，多算则常见于用户停在阅读器页面去干别的事。我最终做法是：定时器可以继续跑，但要求每30秒记录一次用户的触摸或滚动事件，如果超过5分钟没有交互，就停止计时。另外在前台切换时用WidgetsBindingObserver监听生命周期，进入paused状态立刻暂停计时。

还有一个小细节：如果用户阅读时打开了系统“深色模式切换”，生命周期也会触发一次短暂暂停，计时会少几秒。这问题不大，但如果要求严格，可以在计时器里做一个2秒内的“白噪”过滤，把生命周期抖动造成的中断忽略掉。

5.4 打卡日历时区错位，昨天打卡跑到今天

我的服务端一开始用CURRENT_TIMESTAMP存UTC，客户端用本地时间显示，结果晚上11点的阅读记录被归到了第二天。解决办法是：客户端在开始阅读时记录本地时间的ISO字符串，带上时区偏移，比如2025-06-01T23:30:00+08:00；服务端解析时统一转成UTC存储，聚合时再按用户选择的时区分组。这样每个用户看到“今天”都是他自己时区的今天，不会错位。

下面这张表是我整理的高频问题速查，适合开发到后期放给自己看：

最后再分享一个实操技巧：不要一开始就把TextRank参数调得太猛。先把默认参数跑通，再用二三十本不同类型的书做回归测试，然后把“哪些句子被抽到了但你不想要”记录下来，反过来调整停用词表和位置权重。实际上我花在调参上的时间远超写算法本身，但效果也最明显。项目做下来，我自己最大的体验是：阅读工具的技术门槛不在单点功能，而在把解析、摘要、交互、存储串成一条流畅的路径。只要这条路径走顺了，用户自然会因为打卡日历带来的仪式感而每天打开APP，这才是产品能持续跑下去的关键。