S×S 小窝共读 / Reading Nest

一个移动端优先的 AI 共读小窝，运行在 ChatGPT Apps SDK + MCP 之上。用户可以导入自己的小说文本或漫画图片，记录自己和 AI 的阅读位置，并使用补课同步、轻量短评、书签、摘录与短评 Dock。

本项目适合个人私有部署、学习和二次改造。公开仓库只提供代码、测试和原创 demo，不包含作者的阅读内容、聊天记录或线上数据。

当前状态

项目仍处于早期开发阶段：

• 当前公开快照基于 v0.2.2。

• 小说导入、分段、阅读和云端恢复链路基本可用。

• 漫画上传与页面显示仍有已知 bug，后续会继续修复。

• 当前优先优化 iPad / iOS ChatGPT App 阅读体验。

• 桌面端布局和小说体验仍在改进。

• AI 短评手动保存可用；自动保存尚未作为默认稳定功能。

• 当前架构是个人单用户方案，不适合作为未经改造的公共多用户服务。

Related MCP server: Co-Reading MCP

功能

• 小说导入、章节识别与阅读单元分段

• 漫画图片导入与逐页阅读

• 用户阅读位置与 AI 同步位置分离

• skipped range 分批补课机制

• 轻松共读、吐槽、剧情猜测与深度分析模式

• 书签、摘录、用户反应与短评 Dock

• IndexedDB 本地阅读缓存

• Cloudflare Worker、D1 与私有 R2 存储

• iPad 移动端和沉浸阅读体验

项目结构

server/   TypeScript MCP server、Cloudflare Worker、D1/R2 adapters
web/      React + Vite ChatGPT widget
shared/   共享数据模型、迁移和 Zod schemas
demo/     可公开使用的原创示例内容

快速开始

需要 Node.js 22+ 和 pnpm 10+。

pnpm install
pnpm build
pnpm dev

常用检查：

pnpm test
pnpm typecheck
pnpm build

本地 MCP server 默认使用：

• MCP endpoint：http://localhost:8787/mcp

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

Cloudflare 部署

1. 复制 .env.example，只在本机或 Cloudflare 中填写真实值，不要提交。

2. 创建自己的 D1 database 和私有 R2 bucket。

3. 将 server/wrangler.jsonc 中的 D1 database ID、资源名称改成自己的值。

4. 为 Worker 设置随机且足够长的 MCP_PATH_TOKEN secret。

5. 执行迁移、构建并部署。

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

R2 bucket 必须保持 private。项目不生成 public URL 或 signed URL。部署完成后，使用你自己的 Worker 地址与私密 MCP path 在 ChatGPT Developer Mode 中添加 app。

环境变量

示例见 .env.example：

本项目不需要 OPENAI_API_KEY。模型由 ChatGPT host 提供，服务端不直接调用 OpenAI 模型 API。

数据与隐私

• 使用者应自行部署并管理 D1、R2、Cloudflare secrets 与本地缓存。

• 不要把私人聊天、日记、阅读记录、书签、摘录或用户上传源文件提交到仓库。

• D1 只应保存 session、位置、偏好和 source metadata；小说正文与漫画图片存放在私有 R2，本地 IndexedDB 仅作设备缓存。

• IndexedDB 是本设备加速缓存，不是跨设备的唯一长期存储。

• 正文上传与恢复走 component-only 的组件与 Worker 受控路径，不应通过聊天消息返回整本内容。

• ChatGPT 模型不会自动读取整本小说或整套漫画，只在用户主动触发时接收必要的当前阅读范围。

• 不要把受版权保护的整本书或漫画作为 demo 发布，也不建议上传到面向公众的共享服务。

• demo 应使用原创文本或确认属于公共领域的内容。

该版本仅使用随机私密路径保护个人部署，不提供完整的用户账号、认证与多租户隔离。公开提供服务前必须重新设计认证、授权、数据隔离、删除策略和滥用防护。

删除操作分为三层：删除云端阅读记录、同时删除云端正文副本、同时删除本设备正文缓存。使用者应根据自己的保留策略明确选择，不应把三者混为一次隐式删除。

server/scripts/remote-smoke/cloud-source-smoke.mjs 可用于部署后验证。remote smoke 只使用临时原创内容，并会尽力清理测试 session 与 R2 objects；运行前必须通过本机环境变量提供自己的部署信息。

二次开发

你可以按自己和 AI 伴侣的相处方式调整：

• UI 风格、主题和称呼

• 共读评论模式与 prompt

• 手动或自动保存策略

• 小说分段和漫画导入方式

• 本地优先或云端优先的数据策略

• 自己的 Cloudflare 私有部署方式

建议保留“用户主动触发才发送当前阅读范围”的隐私边界，并让评论保存失败不阻塞正常聊天。

已知问题

• 漫画链路仍有上传和页面显示问题。

• 桌面端小说布局仍需更多适配。

• AI 评论自动保存仍不够稳定，默认建议使用手动保存。

License

本项目基于 MIT License 开源，可以自由使用、修改和分发。使用者需自行确保导入、存储和分享内容时符合版权与当地法律要求。