PaperMind

面向学习笔记的阅读与讨论工作台。目标工作流：Codex / 外部 Agent 生成笔记，PaperMind承载阅读、标注和原文讨论，GitHub 保存内容；GitBook 可选地承载对外知识库。外部 Agent 可通过 papermind notes import 文件.md 交付文档，读取最新 revision 后继续更新；PaperMind自动接收更新。具体协议见 docs/AGENT-HANDOFF.md。

本地运行。React + Tiptap 开源编辑器，Node.js + SQLite 保存文档和讨论，Pi 模型连接与 Agent 核心驱动独立的文档 Harness。主运行路径不依赖 Codex CLI 或 App Server。

0.5.0 新增正文关系图：Markdown 中的 Mermaid flowchart / graph 导入后直接绘制，图稿折叠保存，可编辑、撤销，支持适应宽度和原始大小。图随正文与私有知识库同步保留，不需要公网图床。语法错误拒绝导入，页面绘制失败明确显示错误；导入结果中的校验通过与实际页面显示是两个状态。格式与交付约定见 交付协议。

运行

需要 Node.js 24 或以上。

npm ci
npm run build
node bin/papermind.mjs --background

默认打开 http://127.0.0.1:4317。后台模式在关闭终端或本次聊天后继续运行；用 node bin/papermind.mjs --status 查看状态，node bin/papermind.mjs --stop 停止。端口可通过 --port 4318 修改，--no-open 只启动服务。不加 --background 时以前台模式运行，按 Ctrl+C 停止。电脑重启后需要重新启动。

启动器在 macOS 上继承已启用的系统 HTTP/HTTPS 代理，用于模型联网；显式设置的代理环境变量优先。本机PaperMind请求保持直连，不改变系统网络设置。PAC 与仅 SOCKS 配置不自动转换。

需要命令行快捷入口时，在项目目录运行 npm link，以后使用 papermind 启动。

开发模式：STUDY_DEV=1 npm run dev。没有构建产物时也会启用 Vite；有构建产物时默认运行已构建版本。

从旧版升级：更新代码后运行 npm ci、npm run build，再停止并重启原服务。沿用原来的端口与 STUDY_DATA_DIR，文档留在原数据库中。仅拉取代码不会替换正在运行的旧进程；/api/health 返回运行版本。旧笔记只有表格时，需要生成并导入图稿，升级不会自动猜出关系图。

模型连接

在左下角「设置」的 AI 连接中，发起 ChatGPT 官方登录与套餐授权。接入使用 Pi 的 Sign in with ChatGPT 组件，授权页面会显示 Pi。若自动回调没有完成，界面可以提交此次登录的完整回调地址。

账号是否可调用具体模型以及额度由服务商决定。程序不会读取其他客户端的登录凭证，也不会自动使用环境变量中的付费 API Key。没有连接模型时，普通编辑和保存仍可使用；AI 功能会明确提示连接，不返回模拟答案。

相关文档与讨论在发起请求时发送给所选模型服务。凭证仅由本地服务保存，浏览器只看到连接状态。

使用

1. 从左侧文档库打开笔记，或新建空白文档；也可让外部 Agent 通过 CLI 交付笔记。文档保留原有顺序，打开或编辑不会置顶，新文档追加到末尾。
2. 直接修改标题和正文；输入停止后自动保存；未保存或保存失败时，顶部会显示状态。
3. 选中文字，打开浮动的 AI 讨论；问题与这段原文关联，支持连续追问。拖动浮窗标题可移动；关闭后从原文批注或右上角批注入口恢复同一上下文。标题也支持键盘方向键移动。
4. 点击「讨论融入正文」，模型根据本次讨论直接补充、完善选中段落并保存，无需二次确认；完成后可撤销或展开查看前后内容。
5. 如果生成期间文档已变更，写回会被拒绝，不覆盖新内容。正文写回与历史记录一起提交，失败则一并回滚。

选中文字后，浮动工具栏提供加粗、斜体、高亮、链接和「问 AI」。更多格式（标题、列表、引用、代码块、表格和编辑撤销）可从右上角「文档菜单 → 格式工具栏」展开。讨论中的 AI 写回有对应撤销入口；发生后续编辑时不会强行撤回并覆盖新内容。

右上角 AI 打开当前文章的讨论，选中文字则开启该段落的讨论；两者各自保留上下文。浮层只提供放大和关闭，关闭后完全隐藏，通过原入口继续讨论。整篇文章的讨论自动携带当前正文，按文章分别保存在本机，无需新建对话或附带文档。文档库、文章目录、文章批注各自独立；文章目录以左侧短线呈现，悬停展开。右上角批注入口支持搜索、原文定位、最近讨论预览和写回状态。导入和同步位于文档的「…」菜单。点击正文中带下划线的批注文字，也可直接继续讨论。

GitHub 同步包含正文、段落批注与整篇文章 AI 问答。旧版独立聊天保留在数据库中，不再混入文章讨论界面。

数据与恢复

默认数据目录为 ~/.local/share/study-workbench/，可用 STUDY_DATA_DIR 指定。正文、注释、高亮、讨论、提案和历史在 notes.sqlite；模型授权在权限为 0600 的独立设置文件中。数据目录不属于源码，不上传 Git。

关闭浏览器不会删除数据。再次启动后恢复本地文档。备份前停止服务，再复制整个数据目录；其中含授权信息，只应保存在自己信任的位置。

这是一份浏览器文档应用，不依赖 Word / DOCX。设置中支持浅色、深色、跟随系统，四组默认配色（雾蓝、纸页、松绿、鸢紫），以及折叠的自定义颜色选项；外观偏好保存在当前浏览器。

导入与 GitHub

「文档菜单 → 导入网页」可预览公开 GitBook 单篇文章，再保存为自己的可编辑副本，保留来源链接。视频和图片保留链接，不自动读取视频内容，也不跟随原网站更新。

「文档菜单 → 同步到 GitHub」默认只导出当前文档，先预览正文、结构和讨论文件，再确认上传到自己的已有仓库。需要本机 GitHub CLI 登录；冲突时拒绝覆盖。同一窗口可切换「从 GitHub 拉取」，在另一台电脑恢复正文、格式、高亮和讨论。两边都改过时，明确预览后保留完整本机副本，再载入远端版本；不自动合并句子，也不删除其他笔记。两台电脑仍需分别运行PaperMind，这不是云端托管服务。自动同步使用独享私有知识库，详细配置见下方工作流。详见 docs/INTEGRATIONS.md。

GitBook 的位置

GitBook 与PaperMind在组织、阅读、编辑和评论上有重合。建议PaperMind作为个人学习工作台，GitBook 作为可选的知识库展示和团队协作端，避免同时维护两个主要编辑入口。GitBook 官方 Git Sync 可双向同步 GitHub 仓库中的 Markdown；PaperMind自定义的批注、对话与锚点不属于 GitBook 原生评论，不能直接互通。

PaperMind现支持上传和拉取自己导出的笔记包。如果在 GitBook 或 GitHub 编辑了包内的 README.md，拉取时会采用该 Markdown 正文，并尝试重新定位原有讨论；Markdown 未表示的部分排版可能变化。GitBook 原生评论仍不互通。没有接 GitBook 也能保存到 GitHub，GitHub 仓库不会自动成为在线运行的PaperMind。

官方参考：https://gitbook.com/docs/docs-as-code/git-sync ，https://gitbook.com/docs/collaborate/comments 。

验证

npm run check
npm test
npm run build

自动测试使用临时数据目录。文档测试不调用模型；OAuth 测试只验证登录准备与取消，不完成授权，不发送推理请求。不要在用户正使用登录回调端口 1455 时运行 OAuth 测试。

验收范围见 docs/RELEASE.md，模型接入说明见 docs/AI.md。自动测试、浏览器验收、真实模型端到端验收分别记录，互不替代。

升级兼容

品牌与主命令已改为 PaperMind / papermind，旧 yejian 命令继续可用。沿用本机数据目录、浏览器偏好键及 yejian-*-v1 交换格式，已有笔记、授权和同步记录继续使用，不自动迁移或复制私人数据。

私有知识库工作流

支持后台双向同步，以及整篇 AI 对话随笔记恢复。安装、Agent 交付、浏览器阅读和换电脑操作见 完整工作流。