BookNotes

在 VS Code 中阅读 PDF / EPUB，将书中重点整理成卡片和脑图，并通过 AI 问答回到原文核实。

系统要求

• macOS 14 或更新版本，Apple Silicon（arm64）。
• VS Code 1.141.0 或更新版本，使用原生 arm64 版本。
• 不支持 Windows、Linux、Intel Mac、Rosetta x64 扩展宿主或浏览器版 VS Code。

扩展自带本地阅读服务，无需安装 Node.js、Python 或额外运行时。

开始阅读

1. 安装后点击左侧活动栏的 BookNotes。
2. 选择“导入 PDF / EPUB”，或执行命令“BookNotes: 导入 PDF / EPUB”。
3. 也可在文件右键菜单中选择“打开方式 → BookNotes 阅读器”。
4. 左侧查看书籍、文档目录和手动书签；中间阅读正文；右侧通过脑图、卡片、AI 页签整理内容。

导入会将文档复制到扩展自己的本地书库，不改写原始文件。扫描版 PDF 需要原有文本层才能进行文字摘录和检索；当前不提供 OCR。

PDF 与 EPUB

PDF 支持连续滚动、纵向或横向阅读、单页或双页、缩放与方向键翻页。正文右上角“⋯”可调整阅读模式、适合宽度以及白色、棕褐色、灰色、暗黑、绿色书页主题；书页主题独立于 VS Code 深浅色主题。

拖选 PDF 文字后可复制、添加注释、选择黄/绿/蓝/红划线、插入脑图或创建卡片。点击已有划线可编辑或删除；正文右键可切换文字、手绘线和矩形框工具。文字摘录限制在同一物理页。

EPUB 按书籍章节顺序呈现 HTML、样式和本地图片，支持选文制卡、标记与来源跳转。作者脚本和远程资源被阻止；加密/DRM、部分复杂排版、SVG/数学内容和跨章节超链接存在限制，可使用左侧章节列表导航。

卡片与脑图

卡片可编辑标题、评论、标签和颜色，支持搜索、加入脑图和回到原文。草稿按书籍保留，点击保存才写入。

使用“BookNotes: 生成章节脑图”按 PDF 内嵌目录组织章节；没有目录时按页分组。该操作建立目录结构，不调用 AI 生成摘要。PDF 选段入图会按正文所属章节归类。

脑图支持缩放、平移、分支折叠、节点“＋”添加子节点、双击编辑文字和调整父节点。点击有来源的节点只定位原文，不新增定位高亮。删除节点及子节点会先确认，关联卡片与文档仍保留。

导出脑图

脑图页签右侧“⋯ → 导出脑图（FreeMind）…”或命令“BookNotes: 导出脑图（FreeMind）”可保存.mm文件，在MindNode、XMind、iThoughtsX中导入。导出整张已保存脑图，包含折叠的子节点、完整标题/摘录、卡片备注/标签、正文注释和来源起始页或章节。未保存草稿不自动提交。取消或保存前切书不写文件。

目标软件可能重新布局或忽略部分样式；来源页码写入备注，不能保证BookNotes内部回跳可用。导出只写用户选择的本机.mm，不修改书库或发送网络请求；64MiB容量上限及不支持的XML文字会报错，不会截断导出。更新包含新本地服务，请保存并完全退出所有VSCode窗口，等待数秒后重开。

AI 问答

打开右侧 AI 页签，通过页签栏“⋯ → AI 设置”配置 OpenAI 兼容的 Chat Completions 服务地址、模型和 API 密钥。可以在常驻表单中编辑多个字段，使用“测试连接”验证合成请求，再保存设置。

密钥支持直接填写或环境变量引用，例如 $OPENCODE_API_KEY、${OPENCODE_API_KEY}。环境变量必须存在于启动 VS Code 的进程环境中；应用不会运行 shell 或读取 shell 配置文件。保存的密钥或引用由 VS Code SecretStorage 管理，不在页面回显。

输入问题后按 Enter 发送，Shift+Enter 换行，也可点击停止。应用检索当前书籍中最多 8 个匹配片段并发给你配置的服务；回答保存到当前书籍，点击引用链接只跳转到来源，不新增正文高亮。没有匹配文本时会明确提示。

OpenCode 用户可在 AI 页签“⋯ → 本书 AI 会话 ID…”中设置单书会话 ID，留空保存恢复自动。不同书籍不能共用同一个自定义 ID。测试连接使用独立的合成会话，测试成功不保证其他请求持续可用。

当前使用非流式问答。服务错误不会自动重试；如果中断发生在本地保存已提交之后，请刷新核对结果。

数据与网络

• 书籍副本、卡片、脑图、阅读位置和已保存回答存放在本机的扩展存储中。
• 本地阅读、摘录和脑图整理不需要网络，不提供 iCloud 或账号同步。
• 显式提问会向配置的 AI 服务发送问题和检索到的书籍片段；测试连接只发送固定合成材料。API 密钥随服务请求用于认证。
• 本地服务仅通过同机 Unix socket 与扩展通信；同一 VS Code profile 的多个窗口共享书库服务。所有连接关闭后服务自动退出。
• 卸载前请保留需要的书库数据；当前没有内置的完整书库备份/恢复或跨身份迁移向导。

升级与故障排查

本次正式包的扩展 ID 为 jaredqu.booknotes。早期本地版本 local-rea.booknotes 使用不同的存储身份；安装新 ID 不会自动带入旧书库或密钥。已有早期数据的用户应先保留旧安装和完整书库，再安排迁移；避免同时启用两个身份的 BookNotes。

遇到连接错误，可执行“BookNotes: 重新连接本地服务”。前端更新后可重载窗口；若更新包含本地服务版本变化，请保存工作、完全退出所有 VS Code 窗口，等待几秒后重新打开。不要通过删除书库锁文件处理连接问题。

文档目录读取不完整、资源受限或脑图部分显示时会明确提示。复杂 PDF、EPUB 与真实触控板体验可能因文档和设备而异。

版本与许可

版本：0.1.27。发布者 ID：jaredqu。作者：jared.qu。

许可元数据保持 UNLICENSED；本包未声明 MIT、Apache 等开源授权。书籍内容和所使用的 AI 服务适用各自的条件。