SxS Reading Nest / 小窝共读

一个运行在 ChatGPT 中的移动端优先私人阅读器。它把多书书架、阅读进度、划线想法、书签和“与 AI 共读当前页”连接在同一个 MCP App 中。

公开仓库只包含源代码、测试和原创 demo，不包含维护者的线上地址、Cloudflare 资源标识、连接令牌、书籍正文、批注、聊天或阅读记录。

当前冻结版本：0.3.34 公开发布标签：v0.3.34

设计目标

• 在 ChatGPT Web、iPhone 和 iPad 宿主中使用同一份 React 组件。
• 支持粘贴文本和导入 TXT、Markdown、EPUB。
• 支持多本书，而不是为单本样书写特殊逻辑。
• 让正文保持私密，同时允许用户主动分享当前页与想法进行共读。
• 允许设备缓存丢失后从私人云端恢复正文和阅读状态。

核心功能

• 多书书架、筛选、详情页和阅读记录
• 当前阅读位置与 AI 已同步位置分离
• 划线、想法、清思、纪要、书签及删除管理
• 水蓝、粉桃、米白、浅绿和柔墨绿主题
• IndexedDB 本地缓存
• D1 元数据与私人 R2 正文存储
• 当前页上下文的只读共读工具
• ChatGPT Web、iPhone、iPad 响应式界面

架构概览

flowchart LR
    U["用户"] --> H["ChatGPT Web / iPhone / iPad"]
    H -->|"MCP tools/call"| W["Cloudflare Worker"]
    W --> T["MCP 工具层"]
    W --> R["内联 React UI resource"]
    T --> S["ReadingService"]
    S --> D[("D1 元数据")]
    T --> C["CloudSourceService"]
    C --> O[("私有 R2 正文")]
    R --> I[("IndexedDB 缓存")]
    R -->|"组件专用工具"| T

关键点：工具执行成功、数据返回成功、UI resource 可读取、宿主完成挂载、用户可以交互，是五个不同的状态。浏览器成功也不能替代 iPhone 或 iPad 真机验收。

详细说明见 架构与设计思路。

项目结构

shared/  共享数据模型、Zod schema、数据库迁移与小说分段
server/  MCP 工具、UI resource、Worker、D1/R2 服务与隐私边界
web/     React 阅读器、ChatGPT host bridge、IndexedDB 与主题样式
demo/    可公开使用的原创示例文本
docs/    架构、部署、维护与学习资料

本地开发

要求：Node.js 22+、Corepack、pnpm 10.15.1。

git clone https://github.com/ice-star-blue/ss-reading-nest.git
cd ss-reading-nest
corepack pnpm@10.15.1 install
corepack pnpm@10.15.1 test
corepack pnpm@10.15.1 typecheck
corepack pnpm@10.15.1 build

本地开发：

corepack pnpm@10.15.1 dev

默认本地端点：

• MCP：http://localhost:8787/mcp
• 健康检查：http://localhost:8787/health

部署到自己的 Cloudflare

该项目默认是个人单用户部署。不要把维护者或其他人的 MCP 地址作为自己的后端。

1. 创建 D1 数据库和私有 R2 bucket。
2. 把 server/wrangler.jsonc 中的占位数据库 ID 改成自己的值。
3. 创建随机 MCP_PATH_TOKEN，仅通过 Wrangler secret 保存。
4. 应用迁移并部署 Worker。

corepack pnpm@10.15.1 --filter @ss/server exec wrangler login
corepack pnpm@10.15.1 --filter @ss/server exec wrangler d1 create ss-reading-nest-db
corepack pnpm@10.15.1 --filter @ss/server exec wrangler r2 bucket create ss-reading-nest-sources
corepack pnpm@10.15.1 --filter @ss/server exec wrangler secret put MCP_PATH_TOKEN
corepack pnpm@10.15.1 --filter @ss/server exec wrangler d1 migrations apply ss-reading-nest-db --remote
corepack pnpm@10.15.1 deploy:cloudflare

连接地址由你自己的 Worker origin 和私密 token 组成：

https://<your-worker>.<your-subdomain>.workers.dev/mcp/<your-random-token>

原生客户端兼容入口使用当前后缀：

https://<your-worker>.<your-subdomain>.workers.dev/mcp/<your-random-token>/ios-v4

不要把实际地址发到 issue、日志或截图里。完整步骤见 开源部署指南。ChatGPT App/MCP 的官方概念可参考 OpenAI MCP server 指南 与 ChatGPT UI 指南。

数据与隐私

位置	保存内容	性质
D1	session、进度、偏好、批注、书签、阅读记录、source metadata	私有结构化数据
R2	导入的小说正文和 manifest	必须保持 private
IndexedDB	当前设备的正文与分段缓存	可重建缓存
ChatGPT 上下文	用户主动共读时所需的当前页与想法	最小必要范围

服务端会在书架数据离开内部存储边界前移除 R2 objectKey 和 manifestObjectKey。项目不需要 OPENAI_API_KEY，模型由 ChatGPT 宿主提供。

IndexedDB 只承担加速缓存，不是唯一数据源。正文上传和恢复使用 component-only 的组件通道；ChatGPT 模型不会自动读取整本小说。R2 保持私有，本项目不生成 public URL 或 signed URL。

删除操作分为三个明确层次：删除云端阅读记录、同时删除云端正文副本、同时删除本设备正文缓存。使用者应根据自己的保留需求确认范围。

部署后的 remote smoke 只应使用临时原创文本，并在完成后清理测试 session 与对象。

随机路径 token 不是完整的多用户认证。公开提供托管服务前，必须增加真正的身份认证、授权、用户隔离、限流、删除和滥用防护。详见 安全策略。

共读为什么不把整页塞进聊天

组件只发送一句简短的共读意图。模型随后调用无 UI 绑定的只读工具 read_shared_page_context，从 R2 恢复当前页、从 D1 获取该页想法，再直接回应用户观点。这样模型获得必要上下文，但聊天界面不会变成正文和批注的复读机。

测试基线

公开前在冻结源码上验证：

• shared：34 项通过
• server：87 项通过
• web：173 项通过，1 项按设计跳过
• TypeScript 类型检查通过
• 生产构建通过
• iPhone ChatGPT App 由维护者完成真实设备挂载验收

iPad 和未来版本仍应独立验收，不能继承其他宿主的结论。

文档

• 架构与设计思路
• 开源部署指南
• 项目学习讲义
• 维护与排错手册
• 贡献指南
• 安全策略

License

MIT。导入、存储或分享文本时，使用者仍需自行确认版权和当地法律要求。仓库 demo 为原创短文本。