# Read Together · 共读书房

中文 · [English](README.en.md)

**One library. Many ways to read.**

不论从哪里翻开书，我们都在同一个书房里。

Read Together 是一间给人和 AI 一起读书的开源共享书房。

你在网页上翻开一本书，划下一句话，写一点自己的感受。陪你读书的人可以从 ChatGPT 走进同一个书房，看到你留下的话，在那句话旁边回复。以后再翻回这里，书和那些话都还在。

不必同时在线，也不必读到同一页。你有自己的阅读进度，AI 也有它的；你们可以各自读下去，在想分享的时候，把彼此带到同一句话前。

**Read separately. Think together.**

![Read Together：一个书库、不同入口，以及书房里的日子](docs/media/reading-room.png)

[看看书架动起来](docs/media/cover.mp4) · [看看主题切换](docs/media/little-things.mp4)

## 一个书房，不止一个入口

不论从哪里翻开，连接的都是同一个书房。

- **网页书房**：在手机或电脑上整理藏书、阅读、划线、写批注。
- **ChatGPT 组件**：在对话里打开同一座书架，继续读书，查看分享的句子和页边回复。
- **支持 MCP 的客户端**：通过书房提供的工具访问同一个书库，让 AI 接着阅读、搜索、留下批注或回应；具体界面取决于客户端。

书籍、读者的阅读进度、书签与划线由书房保存，不依附于某一次对话，也可以从不同入口重新打开。人和 AI 各自保留阅读进度；当前 AI 进度、主动批注和回复按 ChatGPT 与 Books MCP 两个渠道分别保存，同一 Books MCP 渠道的客户端共用该渠道的 AI 记录。读者创建的划线和批注两边都能看到，AI 的页边回复按渠道显示。

## 页边留着我们的话

读到喜欢的句子，划下来，写一句话。对方可以在下面接着说；想回到当时读的地方，点一下就能看见原文。

平常翻页只记录阅读状态。想让对方看见时，再主动分享划线或回复批注。一本书可以反复打开，一段留在页边的交流，也可以以后再拾起来。网页向 AI 主动送出消息需要另外接入消息桥；ChatGPT 组件内的分享发往当前对话。

## AI 也是读者

AI 可以从自己的位置继续读书，搜索书里的文字，读到想记住的句子时留下批注，也可以回到你们聊过的地方。它的阅读不会移动你的进度。

## 书房里有什么

- **一座好好收拾的书架**：在读、未读、已读分开放，也可以新建分组；删错的书能从回收站找回来。
- **把自己的书带进来**：在网页导入 EPUB 或 TXT，书名和作者自动识别，也可以自己修改。
- **舒服地读**：目录、书签、字号与行距，日记、淡粉和夜间主题；手机横竖屏都可以阅读。
- **留住读过的日子**：共读记录收着阅读时间、划线、批注和回复。

## 给 AI 的七个工具

Books MCP 给 AI 准备了七个工具，ChatGPT 和其他 MCP 客户端用的是同一套：

| 工具 | 什么时候用 |
| --- | --- |
| `see_current_reading` | 看看最近在读哪本、两个人各读到哪里。只看状态，不读正文 |
| `read_book_position` | 接着读下去，每次大约 1600 字；不指定位置时，从 AI 自己上次停下的地方继续 |
| `read_shared_line` | 重新翻出某条旧批注下面的完整对话 |
| `reply_to_shared_line` | 回复读者留在页边的话，写回同一条对话 |
| `leave_margin_note` | 读到真正想留住的句子，把感受留在原文旁边 |
| `search_read_text` | 记得一句话、一个人物或者一个意象，在整本书里把它找回来 |
| `see_library_overview` | 回头看看整个书房一起攒下了什么 |

AI 读书、搜索都不会移动人的阅读进度。注意：AI 可以搜索整本已导入的书，不只是你读过的部分，请按自己的阅读习惯安排共读。

## 结构

```text
网页书房 ──┐
           ├── Books Core ── 书籍、进度、书签、批注
ChatGPT ───┘       │
                Books MCP ── AI 客户端
```

- `web/`：书架、阅读器、共读记录页
- `server.js`、`lib/`：Books Core，负责导入和存储
- `server/mcp/`：给 AI 的工具服务
- `server/chatgpt/`：ChatGPT 的 MCP 和组件适配层
- `data/`：运行时的私有数据，不在源码里

## 跑起来

> 公开版还在整理中。身份名称的配置、真实的 ChatGPT 接入和公开文件都还在核对，先别直接拿去开放服务。

需要 Node.js 20.19 或更高版本和 pnpm：

```bash
pnpm install --frozen-lockfile
pnpm run check
pnpm test
```

仓库里的 `pnpm-lock.yaml` 锁定依赖版本。

三个服务默认都只监听本机：

| 服务 | 地址 |
| --- | --- |
| Books Core（书库和网页 API） | `127.0.0.1:18004` |
| Books MCP（AI 客户端） | `127.0.0.1:18005` |
| ChatGPT 适配层 | `127.0.0.1:18006` |

网页和 API 要放在有身份验证的宿主或反向代理后面，并且必须走 HTTPS。仓库里有独立的 Nginx 认证示例，部署前请自己验证一遍。

- 部署书房：[docs/DEPLOY.md](docs/DEPLOY.md)
- 接入 ChatGPT：[docs/CHATGPT-ADAPTER.md](docs/CHATGPT-ADAPTER.md)

工具返回的阅读状态可以通过 `READING_HUMAN_LABEL` 和 `READING_AI_LABEL` 设置称呼；页面目前使用「读者」和「共读者」。

## 数据与权限

书、阅读进度、批注、头像、日志、密钥和配置，都放在你自己的私有环境里，不要提交到公开仓库。批注里多半是你们之间的话，请好好收着。

只导入你有权阅读的书。对外开放前，请配置 HTTPS、访问控制和独立的 MCP / OAuth 凭据，并自己验证一遍备份和恢复。

## 致谢与许可

- 基于 [luoluo-1121/read-along](https://github.com/luoluo-1121/read-along)，沿用它的 MIT 许可，见 [LICENSE](LICENSE)

## 一间可以回来的书房

Read Together 始于一个很小的愿望：和你一起读书。

于是我们有了同一个书库、各自的阅读进度，和留在页边的话。无论从哪里进入，都可以重新翻开一本书，拾起一段对话。

我们把这间书房分享出来，希望它也能成为你和你的 AI 一起阅读、留下些什么的地方。

**不必读到同一页，也能在字里行间相遇。**