共读 · 统一 PDF 与资料阅读器

让人和 AI 对着同一份原文学习：你在侧栏阅读、翻页、选择内容，当前聊天里的 AI 根据明确的来源和位置继续解释。

项目从内嵌 PDF 阅读器起步，逐步扩展为本地书库、arXiv 论文和 GitHub 文档／代码的统一共读入口。基于 MCP 官方 PDF 示例，使用 PDF.js 和 MCP Apps。阅读器本身不调用模型 API，回答由所在聊天的模型生成。

当前阶段：可用的个人学习原型，仍在改善阅读体验。 已实现的功能、验证范围与未来设想在下文分别说明。主要在 Windows 本地 Codex 桌面环境开发；其他客户端需要单独验证。

为什么做这个项目

学习 AI 时，材料分散在 PDF 书籍、论文、GitHub README 和源代码里。阅读与提问往往是两件脱节的事：在一个窗口里看原文，在另一个窗口里复制、粘贴，再告诉 AI 自己读到哪一页、哪段话。

项目希望把这个过程变成：

打开资料 → 保留原文阅读界面 → 选中不理解的内容 → 直接在当前聊天中提问 → 回到原文继续读。

这带来了几个具体要求：

• 人始终能看见原文。 目录、缩放、搜索和阅读位置都是基本阅读能力，不能只留下一个问答框。

• 问题有明确出处。 AI 应知道文档、版本、页码或代码行号，以及实际选中的文字；翻页、切书不能改写已经发出的问题。

• 不同来源共用阅读记录。 本地文件、论文和仓库资料可以放进同一个书库，但各自的定位方式要准确保留。

• 继续使用当前聊天。 不为阅读器另建一个需要模型密钥的问答服务，也不把“模型能检索资料”直接当成“人和模型正在共读”。

“统一”指统一资料入口、身份、阅读记录和提问方式。PDF 仍按页面阅读，Markdown 和代码使用各自的显示方式。

Related MCP server: MokuPDF

目前能做什么

书库内 PDF 的阅读位置与书签保存在本机 SQLite；文本阅读位置按源文件行保存。PDF 未导出的批注仍在浏览器存储中。所有这些都不代表跨设备同步。

项目如何发展到现在

以下日期和提交对应本仓库的实际开发历史。

到这一阶段，我们学到了什么

1. 功能接通不等于阅读顺畅。 GitHub 接入虽然跑通了，但账号、搜索、结果、目录和书库堆在同一个纵向区域里，文件打开后又失去目录导航，使用户难以判断“打开后显示在哪里”。这是当前明确的体验问题。

2. 嵌入式应用必须验证宿主行为。 普通浏览器中可用的表单提交，在受限 iframe 中可能不触发。前端等待、工具调用超时和旧页面刷新也会影响用户感知，不能只依赖后端测试。

3. 资料身份和版本要先明确。 同一论文或文件更新后，旧问题与书签仍应指向当时读到的版本，而不是静默跳到最新内容。

4. 应先检查已有产品能力。 Codex 已有 GitHub 插件，可承担仓库读取与分析。此前应先说明已有插件与自建共读界面的分工，再确定需要自建多少功能。自建服务目前使用 GitHub CLI 授权，尚未打通官方插件调用或凭据共用。

下一步方向

以下是待评估／待实现的方向，不是已交付能力或固定排期：

• 优先改善布局： 仓库导航与正文同时可见，账号和搜索放到入口或设置中，减少切文件时反复返回书库。

• 厘清 GitHub 分工： 仓库分析优先考虑现有插件；自建部分聚焦原文浏览、位置记录与选区共读，验证可行后再决定整合方式。

• 补足使用验证： 继续检查真实客户端里的完整操作，以及真实授权仓库和较大文件场景。

• 后续格式与记录能力： EPUB、批注持久化等按实际需求推进。Z-Library 在线连接仍需独立验证，尚未实现。

本机安装与使用

需要 Node.js 24+、npm；本机安装脚本还需要 Codex CLI。Bun 已作为开发依赖包含。GitHub 登录使用 GitHub CLI（gh）。

git clone https://github.com/yuanj8699/gongdu-pdf-reader.git
cd gongdu-pdf-reader
npm ci
npm run build
.\scripts\install-mcp.ps1

本仓库现已公开，可直接查看和克隆。已有本地维护目录的开发者直接使用原目录，不必另建一份副本。

在客户端重新连接 MCP 后，打开 右侧＋ → PDF 阅读器 → 我的书库。选择 PDF 导入，点击“开始阅读”，选中原文后点击“解释选中内容”。默认安装只注册项目自带的示例 PDF，不自动授权整个磁盘。

连接本地 PDF 文件夹：

.\scripts\install-mcp.ps1 -LibraryPath 'D:\Learning\Books'

刷新连接后，在书库里扫描并批量入库；原文件只读。每次重新注册时，请传入全部需要保留的文件夹。

GitHub 收藏／私有仓库授权：

gh auth login --hostname github.com --web --git-protocol https

完成浏览器授权后，在“从 GitHub 找资料”中点击“刷新账号”。输入 owner/repo 或仓库首页链接，点击“打开仓库”，然后点文件阅读。令牌不需要粘贴到聊天或阅读器页面。

更完整的注册、客户端刷新、侧栏和远程连接说明见 CONNECT.md。ChatGPT 网页部署是另一条连接路径，本仓库上传到 GitHub 不会自动使其上线。

架构与代码入口

当前聊天模型 ← 选区、上下文、问题 → MCP Apps 阅读界面
                                    ├─ PDF.js：PDF、目录、批注
                                    └─ Markdown／代码：正文、源文件行号
                                                ↕ MCP 工具
                                    本机 Node.js 服务
                                    ├─ SQLite：资料身份、阅读记录、下载任务
                                    ├─ 本机文件：不可覆盖的书库原件
                                    ├─ arXiv API
                                    └─ GitHub API + 本机 CLI 授权

数据模型、各阶段的行为约束和详细验证范围见 实现说明。

数据存放与已知限制

• 默认书库在 %LOCALAPPDATA%\GongduReader，包含 SQLite、原件、导入暂存和导出文件；可用 PDF_READER_DATA_DIR 指定其他独立目录。

• 代码仓库只保存源码、配置、说明和小型测试夹具。个人书籍、下载资料、数据库、令牌、日志、依赖及构建输出不上传。

• 本地 PDF 导入上限为 512 MB；GitHub PDF 为 100 MB，UTF-8 文本为 1 MB／10000 行；不读取 GitHub 符号链接、子模块和 Git LFS 实体。

• 目前按本机单用户服务设计，没有云端账号系统或跨设备同步。数据目录不应放入知识笔记仓库或云盘实时同步目录。

• 自动上下文同步、显式选区提问、后端读取状态是不同链路；宿主收到上下文更新不代表模型一定使用，发送失败也不能显示为成功。

• 现有 GitHub 布局仍需调整；30 秒超时提示用于恢复交互，并不能替代对具体宿主故障的诊断。

开发与验证

npm run build
npm test
npm run test:library
npm run test:library-ui
npm run test:github-ui

浏览器检查需先运行 npx playwright install chromium，或通过 PLAYWRIGHT_EXECUTABLE_PATH 指向已有 Chromium／Edge。更多定向检查包括 test:stdio、test:reader、test:local-library、test:arxiv-ui 和可选的 test:arxiv-live；按改动选择即可。

截至 2026-09-28，已有构建、后端单测、真实 Node/SQLite 书库检查，以及使用 MCP AppBridge 的浏览器交互回归。GitHub 浏览器回归使用固定 API 样例，包含按钮／回车、无表单权限的沙箱、错误、超时及迟到结果；不把测试宿主收到消息当作真实模型已经回答。

真实联网记录包括 arXiv 指定版本下载与重启恢复，以及 GitHub 已登录账号、earendil-works/pi 提交解析和目录读取。实际阅读上下文也已回传该仓库的 README。真实私有仓库下载、跨设备及不同宿主的完整体验尚不能据此认定已验证。上游仍有两项既有跳过：macOS kqueue 专用检查、未知窗口的长轮询检查。

来源与许可说明

项目派生自 modelcontextprotocol/ext-apps 的 PDF Server 示例，固定来源提交为 6d9bdc7babf275b759225aa722cbf5510c4c6021。初始 Git 提交保留引入基线，后续提交记录本项目的扩展。详见 UPSTREAM.md。

仓库保留原始 LICENSE，其中含上游许可过渡说明及 Apache-2.0、MIT、CC-BY-4.0 文本／说明；不能将整个继承内容简单概括为单一 MIT 许可。本次文档整理不改写上游许可。