Edgi：开源AI阅读追踪工具，将PDF阅读转化为可视化学习仪表盘

这次我们来看一个很有意思的开源项目：Edgi。它不是新的 AI 大模型，也不是图像视频生成工具，而是一个面向长期阅读场景的学习追踪与分析工具。作者把它比作给大脑用的 Letterboxd 或 Strava——用 Strava 记录跑步配速和运动轨迹，用 Letterboxd 记录看片清单和评分，Edgi 则用来自动记录你读过的 PDF、学习时长、阅读情绪和知识主题，再用 AI 把阅读日志整理成可以随时回顾、导出的仪表盘。

这个项目最值得关注的地方，是它把“阅读记录”这件事做成了完整闭环：PDF 导入、自动计时、AI 亮点提炼、情绪分析、主题分类、统计报表、JSON/CSV 导出，全链路打通；数据默认存在本地 SQLite，不强迫上传到云。从项目 Demo 演示看，它提供了学习日历、专注时长、AI 亮点、情绪变化、主题追踪、类别统计、PDF 时间线和 AI 建议等能力。项目在 Hacker News 发布后，收获了不少技术圈子的关注，短时间内积累了约 200 个 Star，后续计划接入 Kindle、Instapaper 和 CSV 导入。

本文会带你把 Edgi 从环境搭建跑到仪表盘出数，重点演示 PDF 导入、AI 分析、阅读追踪、数据导出和常见问题排查，最后从技术栈角度分析它适合怎样接入你的本地学习管理系统。整个过程不依赖 GPU，也不需要本地大模型，普通电脑就能跑。

1. 核心能力速览

从材料看，Edgi 的核心价值不是“多了一个 PDF 阅读器”，而是“把阅读行为量化成可复盘的指标”。传统本地阅读工具通常只解决标注和检索，Edgi 则把“你什么时候读了、读了多久、读了哪些主题、情绪如何变化”这些信息沉淀下来，再用 AI 提炼成总结。这也解释了为什么项目方把它类比成运动记录软件：它更像读书过程的管理后台，而不是单纯的阅读界面。

2. 适用场景与使用边界

先聊清楚这个工具适合谁。如果你有以下需求，Edgi 的方向值得跟进：

• 研究生、科研人员需要读大量论文，想记录每篇论文的阅读时间和核心观点；
• 产品经理、分析师长期阅读 PDF 文档，希望有一个自动化的周报/月报数据来源；
• 使用 Obsidian、Notion 做知识管理的用户，想把阅读高亮和统计结果导出到自己的笔记体系；
• 想养成深度阅读习惯的人，需要“打卡式”的反馈激励。

Edgi 能解决的问题很集中：省去手动记录学习时长，自动把 PDF 高亮和 AI 摘要整理在一起，并通过仪表盘看到学习趋势。材料中 Demo 展示的“活跃学习天数”“专注时长”“PDF 时间线”“AI 建议”等信息，本质上就是一个面向阅读的数据报表。

但也要说清楚边界。Edgi 不适合快速泛读场景——如果你只是简单扫一遍文档，不需要复盘和统计，那它就属于额外负担。另一个现实问题是扫描版 PDF：PDF.js 依赖 PDF 自带的文本层来提取文字，纯图片扫描件很可能提取不了内容，需要提前做 OCR 预处理。此外，AI 能力依赖云端服务，如果你不配置 API Key，亮点摘要、情绪分析这些功能就会不可用，项目退化为一个本地阅读统计工具。

还要注意数据合规。Edgi 的本地 SQLite 存储保证了基本隐私，但 AI 分析通常会把 PDF 文本发送到云端处理。涉及个人隐私、未公开论文、商业机密文件时，要先确认你使用的 AI 服务对数据的处理方式；后续项目如果加入学习小组、朋友追踪等社交功能，也需要更严格的授权机制，不能默认公开阅读记录。

3. 环境准备与前置条件

3.1 操作系统与运行时

Edgi 基于 Node.js 开发，部署门槛主要在 Node 运行环境，不在硬件。建议准备环境如下：

• 操作系统：Windows 10/11、macOS、主流 Linux 发行版均可；
• Node.js：需要可用的 Node.js 与 npm，材料没有标注最低版本，建议先使用 LTS 版本；
• 浏览器：Chrome、Edge、Firefox 等现代浏览器；
• 网络：安装 npm 依赖需要联网；使用 AI 摘要和情绪分析时，需要能访问对应云服务的网络环境。

检查本地环境：

node -v npm -v

如果命令不存在，先去 Node.js 官网安装 LTS 版本。整个过程不需要 Python、CUDA，也不需要显卡驱动。

3.2 项目依赖

Edgi 的依赖以 npm 包为主，包含 PDF.js、Fastify、Tailwind CSS、SQLite 相关驱动，以及 Hume AI 的 SDK。数据库采用 SQLite，首次运行时自动创建，不需要单独安装 MySQL 或 PostgreSQL。

如果你计划部署到云服务器，建议准备一个至少 1 核 1G 的小型实例。项目没有复杂中间件，单个 Node 进程就能跑起来。

4. 安装部署与启动方式

4.1 获取代码与安装依赖

从项目仓库拉取代码后，在项目目录执行安装。命令是通用流程，实际仓库地址和目录名以项目主页为准。

git clone <项目仓库地址> cd <项目目录> npm install

如果npm install下载慢，可以临时换用国内镜像，但这属于网络环境问题，与项目本身无关：

npm install --registry=https://registry.npmmirror.com

4.2 配置环境变量

从材料看，情绪的 AI 推理使用 Hume AI，所以环境变量里大概率需要配置 Hume AI 的 API Key。具体变量名以仓库 README 为准。通常做法是复制环境变量模板后填写密钥：

# 在项目根目录，将 .env.example 复制为 .env 后填写 # 变量名以项目 README 为准，此处仅为示例 HUME_API_KEY=your_hume_api_key_here PORT=3000

如果你暂时没有 Hume AI 的 Key，也可以先启动项目，缺 Key 时跳过情绪模块，优先体验 PDF 阅读和统计仪表盘。

4.3 启动本地服务

安装完成后启动：

npm start # 部分项目开发模式是 npm run dev，具体看 package.json scripts 字段

启动成功后，浏览器访问http://localhost:3000（端口以启动日志为准，这里 3000 只是常见示例）。如果端口被占用，修改环境变量中的PORT后重启。此时可以看到项目主界面，说明服务已经正常拉起。

4.4 部署到云端服务器

项目方把 Web 应用托管在 Fly.io，如果你想部署到自己的服务器，思路也很直接：Node 服务 + SQLite 持久化。用 Fly.io 时需要把 SQLite 数据目录挂到持久化卷，否则每次发布都会丢失数据。通用流程参考如下：

fly launch fly volumes create edgi_data --size 1 fly deploy

这不是 Edgi 的官方一键脚本，只是云部署的通用参考。真正的部署配置需要按项目仓库中的fly.toml或 Dockerfile 做调整。如果你只要本地用，跳过部署环节直接看功能测试。

5. 功能测试与效果验证

5.1 PDF 导入测试

测试目的：验证 PDF 能否被正确解析并进入学习记录流程。

操作步骤：

1. 准备一份带文本层的 PDF，篇幅不用太长，先选一篇 10 页左右的文档。
2. 在 Web UI 中找到导入/上传入口。
3. 上传 PDF，观察页面是否自动进入阅读器视图。

预期结果：PDF 能正常打开，页面显示文档内容；阅读时间开始计时；项目里出现这份文档的学习记录。

常见失败：上传后内容空白，通常是扫描版 PDF 没有文本层。处理办法是先对 PDF 做 OCR，生成带文本层的版本，再导入。这一步不是 Edgi 的缺陷，而是多数 PDF 解析工具的通病。

5.2 自动分析与 AI 亮点测试

测试目的：确认 AI 能对 PDF 内容生成亮点摘要和主题分类。

操作步骤：

1. 导入 PDF 后，等待一段时间，观察文档详情页是否出现 AI 分析结果。
2. 如果配置了 Hume AI Key，多看一个“情绪分析”模块，检查是否能生成阅读情绪曲线。
3. 记录从上传到分析完成的时间。

预期结果：文档页出现“AI 亮点”或“重点摘要”；主要主题能被识别并归类；仪表盘中的主题追踪出现新增条目。

判断标准：AI 摘要不是简单截取段落，而是像“这篇文档提出 X 方法，用于解决 Y 问题，核心步骤是……”这样的提炼；主题类别大致符合文档内容。如果分析失败或空白，优先确认 API Key 是否配置、网络是否可用。

5.3 阅读模式与笔记测试

测试目的：验证阅读器在真实阅读场景下的可用性。

操作步骤：

1. 从仪表盘打开任意已导入 PDF，进入阅读模式；
2. 测试高亮工具，在关键段落上做标记；
3. 查看自动生成的文档目录，用缩略图翻页；
4. 打开笔记面板，写下一条阅读笔记。

预期结果：高亮能保存并回显；目录能根据 PDF 标题层级自动生成；缩略图加载正常；笔记能关联到对应文档。

这个环节最影响日常使用体验。从材料看，Edgi 的阅读器包含高亮、自动目录、缩略图和笔记面板，已经是完整阅读器形态。实际体验时，建议同时打开多份 PDF 来回切换，观察阅读器卡不卡。大型 PDF 的渲染和目录提取都会消耗内存，这是需要重点观察的点。

5.4 仪表盘核心数据测试

测试目的：验证学习统计是否准确，能否形成可视化的回顾面板。

操作步骤：

1. 连续几天或多次在阅读器中打开 PDF，制造多条学习记录；
2. 回到仪表盘，检查活跃学习天数、专注时长是否有更新；
3. 查看类别统计和主题追踪，确认比重分布合理；
4. 查看情绪分析结果，看阅读过程中情绪是否出现明显变化；
5. 查看 AI 建议是否针对你的阅读习惯给出反馈。

预期结果：日历上有活跃标记；专注时长等于多次阅读时间的累加；主题和类别能大致反映阅读内容分布；PDF 时间线按时间展示阅读活动。

判断标准：数据不是静态写死的，而是随着阅读行为实时变化。如果你连续阅读却不更新，说明计时逻辑失效，可从浏览器控制台和 Node 服务日志查找问题。

5.5 数据导出与备份测试

测试目的：验证 JSON/CSV 导出能否用于外部数据处理。

操作步骤：

1. 在仪表盘或导出页面找到“导出 JSON/CSV”入口；
2. 导出文件并打开，检查是否包含阅读会话、时长、高亮、AI 摘要等字段；
3. 用一个脚本简单验证导出 JSON 的结构是否完整。

这里给一个 Python 检查示例，字段名以实际导出结果为准：

import json with open("export.json", "r", encoding="utf-8") as f: data = json.load(f) print("顶层字段:", list(data.keys())) # 示例：如果是 dict，且存在 sessions 列表，就打印长度 if isinstance(data, dict) and "sessions" in data: print("学习会话数:", len(data["sessions"]))

预期结果：导出文件能正常打开，数据结构和界面展示内容一致。这一步很重要，它决定了你能不能把 Edgi 的数据接进自己的 Obsidian、Notion 或数据分析平台。

6. 技术实现与数据接口

6.1 整体技术栈拆解

从材料给出的信息看，Edgi 的技术选型非常轻量，适合做技术复盘：

• PDF.js：浏览器端解析 PDF，负责文本提取、渲染和高亮。这个方案的优势是不需要后端额外调用重型的文档解析服务，部署简单。
• SQLite：保存阅读记录、高亮、时间统计和 AI 分析结果。单文件数据库，备份和迁移成本低，很适合个人工具。
• Fastify：提供 Web 服务和轻量 API，性能比 Express 更好，插件生态也够用。
• Tailwind CSS：快速完成 UI 开发，仪表盘视觉风格统一。
• Hume AI：将阅读过程中可能隐含的情绪变化做估计，用于生成情绪曲线。

这套组合说明项目方很在意“个人工具”的轻量属性。如果换用 Electron 客户端，体积和复杂度会明显上升；如果换用 PostgreSQL，部署门槛也更高。SQLite + 浏览器 UI 的方案是目前最简单能在本地跑起来的组合。

6.2 本地 SQLite 数据读取

由于项目没有公开第三方 API，想拿到结构化数据最直接的方式就是读 SQLite 文件。在项目所在目录找到数据库文件，可以用 Python 连接：

import sqlite3 conn = sqlite3.connect("edgi.sqlite") cur = conn.cursor() # 列出所有表，表名以实际数据库为准 cur.execute("SELECT name FROM sqlite_master WHERE type='table'") print(cur.fetchall()) conn.close()

建议先看表结构，再针对阅读会话表、高亮表做查询。这个方式适合做定时备份，也适合把阅读记录同步到其他系统。

6.3 批量任务与扩展方向

Edgi 当前没有现成的批量任务队列，但单个 PDF 的导入流程已经打通，批量处理完全可以基于本地目录改造。常见的做法是准备一个导入目录，用脚本把多个 PDF 文件复制过去，再写一个定时触发任务，让项目自动处理：

# 示例：把论文目录下的 PDF 复制到项目导入目录 for f in ~/Downloads/papers/*.pdf; do cp "$f" ./import/ done

最终能否自动全量解析，取决于项目是否监听导入目录。如果当前版本没有监听机制，就需要二次开发，在服务启动时扫描导入目录并批量入库。

从材料的路线图看，后续会支持 Kindle、Instapaper、CSV 导入。这意味着作者想把“外部阅读记录”也纳入统计体系，而不是只停留在 PDF。到那个阶段，Edgi 会从一个单点工具变成真正的“阅读数据聚合器”。

6.4 开发者可以改什么

如果你打算基于 Edgi 做改造，建议从三个方向入手：

• 接入自己的大模型 API：把 AI 摘要、主题分类替换成你的模型，可以降低对 Hume AI 或云端服务的依赖；
• 增加定时导出任务：每天自动导出 JSON/CSV，形成阅读周报；
• 增加多用户或群组功能：SQLite 单文件数据库不适合直接做多用户并发，如果要支持学习小组，需要把存储层换成 PostgreSQL。

7. 资源占用与性能观察

Edgi 不需要 GPU，所以观察的重点是 CPU、内存和网络，不再去看显存。

本地运行时，Node.js 进程会同时承担 Web 服务和 PDF 交互逻辑。阅读器本身在浏览器端渲染 PDF，服务端内存压力集中在 PDF 元数据读取、AI 分析结果落库等任务上。导入大 PDF 时，PDF.js 在浏览器端做解析，网页标签页的内存会明显上涨，这是所有浏览器 PDF 阅读器都存在的现象，不属于异常。

要特别强调的是，AI 云端服务的响应时间会直接决定“分析 PDF”环节的体验。如果你发现某个 PDF 一直处于分析中，不一定是逻辑卡死，可能是网络到云端服务的延迟。可以先检查网络连通性，再决定是否调整超时配置。

8. 常见问题与排查方法

这里多数问题都能通过日志定位。启动服务时保持终端日志可见，导入 PDF 和分析 PDF 的过程会在后端输出关键信息。遇到异常，第一条排查原则是看后端有没有报错，第二条才是看前端界面。

9. 最佳实践与使用建议

如果你决定试用 Edgi，我建议按下面的顺序来，能少踩很多坑。

第一次先找小文件。选一篇 10 页以内、带文本层的 PDF 测试完整流程，确认导入、计时、分析、导出都能跑通，再往里丢几百页的书籍或论文。这样可以快速分辨是配置问题还是文件问题。

目录管理要提前规划。把论文、书籍、报告分目录放，导入前统一命名。后续统计分析时，清晰的来源字段能让你知道时间都花在哪些类目上。

定期备份。Edgi 的数据都在 SQLite 文件里，把这个文件连同导出 JSON 一起备份即可。建议每周导出一份 JSON/CSV，既可以防止数据库损坏造成数据丢失，也能满足你自己做数据分析的需求。

注意云服务的数据边界。凡是用到 AI 摘要和情绪分析的 PDF，内容会发送到云端。隐私敏感的文档不要导入需要云分析的环境；如果一定要处理，优先用本地模型替代或加密处理后再操作。

理性看待 AI 建议。情绪分析本质是对文本的估计，不能作为严肃心理指标；AI 亮点适合辅助复盘，但关键论文的理解判断仍然要回到原文。

前几个版本功能迭代会很快，部署在云服务器的用户要关注数据库结构和备份格式变化。参与开源项目时，尽量不要长期停留在旧版本，否则后续升级会面临数据迁移问题。

这套技术栈对于做知识管理类工具很有参考价值。PDF.js 加 SQLite 加轻量 Node 服务的组合，在个人项目和内部工具场景下足够稳定；如果你想自建一个“阅读数据管理后台”，Edgi 的思路和路线图可以直接复用。从本地跑通，到批量导入，再到数据导出，整条链路都验证过之后，再考虑二次开发和功能扩展。选一份最近在读的 PDF，导入 Edgi，跑完一轮再看仪表盘，你会立刻理解这个项目想解决的问题。