共读 · PDF 与资料阅读器

在聊天里保留原文阅读空间，让读者和 AI 对着同一段内容学习。

共读提供本地书库、PDF 阅读、扫描页 OCR，以及 arXiv 和 GitHub 资料入口。你可以翻页、选字、写下自己的问题，再把原文、版本和位置一起交给当前聊天中的 AI；回答后继续回到原文阅读。

基于 PDF.js 和 MCP Apps，派生自 MCP 官方 PDF Server 示例。阅读器本身不调用模型 API，也不需要模型密钥；回答由承载它的聊天客户端生成。

当前状态：个人学习原型。 主要在 Windows 本地环境开发，已完成浏览器、MCP、SQLite 和 Windows OCR 的定向验证。最新版在 Codex 原生侧栏中的完整使用及真实模型回答仍待验证，详见验证范围。

主要功能

Related MCP server: MokuPDF

快速开始

本机安装

需要 Node.js 24+、npm，以及用于注册连接的 Codex CLI。Bun 随开发依赖安装。宿主需要支持 MCP Apps；扫描页 OCR 另需 Windows 10/11 和对应 OCR 语言组件。

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

已有本地维护目录时直接使用原目录。安装脚本注册“共读 · 本机插件”来源，并安装、启用 共读。在客户端「插件」页面可以查看共读；支持浏览本地来源的客户端也可在目录中选择此来源。页面仍显示旧列表时先重新进入页面，必要时保存工作后正常退出并重开客户端。

插件通过 stdio 启动现有项目的 dist/index.js，无须另开服务窗口。默认只授权仓库中的示例 PDF，不扫描整个磁盘。请保留本项目及其依赖、构建结果；这是本机包装，不是独立部署的云插件。机器路径只写入被 Git 忽略的 .local-plugin/，安装缓存由 Codex 管理。

如果只需要独立 MCP 连接，仍可使用 scripts/install-mcp.ps1；它显示在「MCP」标签，名称为 pdf_reader。完整插件附带的连接名为 gongdu。从旧方式迁移时，先验证插件，再移除旧注册，见 CONNECT.md。

客户端加载连接后，在当前聊天中说“打开共读书库”，助手会调用本地阅读器并显示书库。选择或拖入 PDF，再点击“开始阅读”。支持任务入口的客户端也可能在 右侧＋ → PDF 阅读器 中显示入口；菜单没有该项时可直接通过聊天打开。连接不可用或仍显示旧界面时，按 CONNECT.md 检查和刷新。

上传到 GitHub 只提供代码分发，不会自动部署成网页服务。

连接已有 PDF 文件夹

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

书库可以扫描并批量入库，原目录只读，入库使用独立副本。重新注册时需传入全部需要保留的文件夹；不自动监控原目录或同步原文件删除。

也可只授权指定文件：

.\scripts\install-plugin.ps1 -PdfPath 'D:\Learning\paper.pdf'

GitHub 授权

公共仓库可以直接检索；收藏、我的仓库和私有资料需要本机 GitHub CLI（gh）授权：

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

完成授权后，在“从 GitHub 找资料”里刷新账号，输入 owner/repo 或仓库首页链接并打开仓库。令牌无需粘贴到聊天或阅读器。文件导入固定到具体提交，不克隆整个仓库。

阅读与 AI 共读

阅读、找页与高亮

• 选中文字后右键，点击“向 GPT 提问”，即可把选中原文与出处直接发送到当前聊天。PDF、OCR 文字及 GitHub Markdown／代码都支持；聊天中可继续追问。未选择原文、输入框和阅读区外保留原有右键菜单。

• 左右方向键和翻页按钮直接换页。PageUp／PageDown、空格／Shift＋空格先移动当前页；向上跨页时落在上一页底部。输入框保留自身键盘操作。

• “导航 → 页面”展示缩略图，每组 12 页。切换预览分组不会翻正文，点击某页才跳转；收起后停止未完成的预览。

• “旋转”每次将当前页顺时针转 90°，用于调整阅读方向。角度属于当前窗口，保存 PDF 保留原文件方向。

• 选字后点击“高亮选区”，只标记本次选择的位置，重复段落不会全部被高亮；也支持 OCR 文字。

• Ctrl/Cmd＋Z 撤销。高亮和其他批注的本机缓存与 PDF 导出是两步：下载／保存后才生成带批注的 PDF。缓存写入失败时会提示下载留存。

• “专注阅读”收起学习区、OCR 和缩放工具，保留阅读导航和选区操作。可在阅读设置中调整配色与组件。

扫描页选字

1. 展开“文字识别”或“扫描页识字”，点击“识别本页文字”。

2. 需要时在识别设置中选择系统已安装语言和文字方向。

3. 完成后直接划选，或展开“核对识别文字”对照原页。

4. 点击解释或针对选区提问，识别文字以纯文本及出处交给聊天模型。

识别使用本机 Windows WinRT OCR，不调用聊天模型视觉识别或第三方 OCR 服务。页面图像仍经过宿主的 MCP 工具通道；这一实现不能被视为任意远程部署下的网络隔离保证。

OCR 结果始终标注“未经人工核对”。错字、公式、表格和多栏阅读顺序需要对照原页确认；“使用原文字层”可以撤回 OCR 覆盖层。识别完成不会自动发送整页 OCR 全文，显式提问或读取才会提供相应文字。

当前按页按需识别，窗口最多缓存最近 8 页。搜索包含文字层和仍在缓存中的已识别页，不自动识别整书，也不将扫描 PDF 改写成带文字层的文件。

写问题与学习笔记

选中原文后展开“学习与笔记”，点击“针对选区提问”。输入框打开时固定书名、位置和引用；后续翻页、切书或重新选字不会替换这一引用，折叠和专注模式保留当前草稿。

问题发送前先保存原文记录，再交给当前聊天。记录分别保留“我的问题”和“我的理解”，可以搜索与导出。发送失败时先检查聊天，再决定是否手动重试；同一问题重试复用记录，修改问题后另建记录。仅回执保存失败时，“保存笔记”只重试本机写入，不再次发送模型请求。未发送的输入草稿仅保留在当前窗口。

• 记笔记： 有选区时保留引文，也可以直接记本页笔记；写完点击“保存笔记”。

• 返回原文： 核对资料版本后恢复位置和页面方向，滚到保存的引文并作临时标示。同书内返回保留 OCR 缓存；没有有效引文坐标时只返回页码。

• 导出笔记： 导出当前显示记录为 Markdown，包含出处、版本、问题、理解、OCR 标记及可见未保存草稿；导出不会替代本机保存。

• 删除记录： 行内确认／取消，未保存草稿会明确提示一并丢弃。只删除本机学习记录，不影响原文或聊天消息。

• 检验理解： “提问检验”要求模型先问一个问题并等你回答；“检验我的理解”将你的笔记与原文一起发送，要求区分你的判断、AI 纠正和证据不足。

多窗口新增记录会合并。同一条记录发生编辑、删除或回执保存冲突时，保留本窗口草稿并拒绝静默覆盖。消息送达只说明请求已交给宿主，模型回答和实验结果仍需在聊天中查看；阅读页数、计时和 AI 生成内容不作为掌握知识的证明。

数据与当前边界

• 当前是本机单用户服务，没有云端账号系统或跨设备同步。数据目录应与代码仓库、Obsidian 知识库及云盘实时同步目录分开。

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

• PDF 仍按单页渲染。Markdown／代码暂没有文本批注、书签界面或全文搜索，Markdown 图片不加载。

• OCR 当前仅支持 Windows 本机引擎及已安装语言；复杂书籍的准确率没有保证。

• 界面配色不改变 PDF 原稿颜色。文本字号用于 Markdown／代码，PDF 使用缩放。

• EPUB、数据库笔记同步和 Z-Library 在线连接尚未实现。

• 个人书籍、下载资料、数据库、凭据、日志、依赖和构建输出不纳入代码仓库；代码仓库仅保留源码、配置、说明和小型测试夹具。

开发与验证

npm ci
npm run build

按改动选择现有检查，不要求每次执行全部测试：

浏览器检查可运行 npx playwright install chromium，或通过 PLAYWRIGHT_EXECUTABLE_PATH 指向已有 Chrome／Edge。其他定向命令见 package.json，包括本地目录、arXiv 界面和可选联网检查。

验证范围

截至 2026-10-09，最新构建与现有 17 项阅读器回归已通过。近期定向检查使用真实 Chrome、PDF.js、MCP AppBridge、SQLite 和 Windows WinRT OCR，覆盖：

• 合成扫描页识别、重复文字的实际鼠标选择、纯文本发送、来源信息、取消及换页失效；清晰简体中文样例已用本机引擎识别。

• 原稿旋转、CropBox、UserUnit 和阅读角度下的选区／批注位置，以及导出后重新读取的真实 PDF 高亮。

• 缩略图分组、目录、书签、多文件导入、失败与取消。

• 自由问题的固定引用、先存后发、失败重试、问题／理解分离、导出重开及双窗口删除和迟到回执。

• Web Lock 等待期间的新笔记草稿保留、存储失败提示、笔记准确返回原文；桌面／390px、触控按钮、键盘和五种主题。

• 本地插件安装、名称与技能发现、Codex 新宿主加载 gongdu 工具、打开书库、读取互动界面资源和未授权文件拒绝；可用 npm run test:plugin 重现（先安装插件，需要本机 Codex CLI）。

这些检查采用合成材料和测试宿主；部分 GitHub API／OCR 返回值使用固定样例检验边界，不代表真实私有仓库或复杂书籍已完整验证。

最新版在 Codex 原生侧栏里的完整操作，以及真实模型回答的内容和质量，仍待单独验证。 测试宿主收到消息不能证明模型已经回答或读者已掌握知识。详细证据和阶段边界见 docs/IMPLEMENTATION.md。

项目结构

当前聊天模型 ← 原文、出处、问题 → MCP Apps 阅读界面
                                    ├─ PDF.js：页面、目录、批注、表单
                                    └─ Markdown／代码：正文、源文件行号
                                                ↕ MCP 工具
                                    本机 Node.js 服务
                                    ├─ SQLite 与书库原件
                                    ├─ Windows WinRT OCR
                                    ├─ arXiv API
                                    └─ GitHub API + 本机 CLI 授权

连接方式见 CONNECT.md，界面约定见 DESIGN.md，数据模型和实现边界见 docs/IMPLEMENTATION.md。

开发历程

开发中形成的几个判断：功能接通需要进一步验证阅读是否顺畅；宿主回执与真实回答要分开；资料版本必须固定；已有客户端／插件能力应先检查，再确定共读界面需要自行实现的部分。后续优先补足原生客户端体验和真实资料验证，再根据实际需要推进新格式与同步能力。

来源与许可

派生自 modelcontextprotocol/ext-apps 的 PDF Server 示例，固定来源提交为 6d9bdc7babf275b759225aa722cbf5510c4c6021。详见 UPSTREAM.md。

仓库保留原始 LICENSE，包含上游许可过渡说明及 Apache-2.0、MIT、CC-BY-4.0 文本／说明。继承内容不能简单概括为单一 MIT 许可。