gavindiazandClaude Code
0ca4fcce65
- README.md：补充原生分页 / 连续选取 / 摘录高亮说明；阅读位置改为 服务端跨设备同步（不再是「当前浏览器保存」）；补「第二大脑」助手 与模型管理入口；验证命令改为 venv 内 python - deploy/README.md：修正 git clone 后的实际目录结构；新增第 8 节 「历史遗留数据清理」（clean_orphans 脚本 + 启动迁移自动清理）， 并在常见问题里补跨设备位置 / 删书不彻底 / 脚本 ModuleNotFound 等 - frontend/README.md：整体重写，去掉 create-next-app 模板残留 （Vercel / Geist），改为项目真实结构 / 模块说明 / 本地开发 / 构建 - 删除 backend/AGENTS.md：Next.js 自动生成的残留块，backend 目录为 FastAPI 项目、无 node_modules/next，删除避免误导（frontend 那份保留） Co-Authored-By: Claude Code <noreply@anthropic.com>
63 lines
2.6 KiB
Markdown
63 lines
2.6 KiB
Markdown
# BookMate
|
||
|
||
基于 FastAPI 和 Next.js 的 AI 读书助手。支持 EPUB 导入、围绕书籍内容对话、原文引用、完整 EPUB 网页阅读（原生分页）、摘录与高亮，以及跨书籍跨对话的全局「第二大脑」AI 助手。
|
||
|
||
## 本地启动
|
||
|
||
后端（Python 3.12，Windows PowerShell）：
|
||
|
||
```powershell
|
||
cd backend
|
||
python -m venv .venv
|
||
.venv/Scripts/python.exe -m pip install -r requirements.txt
|
||
Copy-Item .env.example .env
|
||
.venv/Scripts/python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
||
```
|
||
|
||
macOS / Linux 同理，把 `.venv/Scripts/python.exe` 换成 `.venv/bin/python`。
|
||
|
||
在 `.env` 配置模型 API，或启动后在网页的「管理模型」中添加模型。数据库和上传目录会自动创建。未配置向量服务时自动降级为关键词检索。
|
||
|
||
另开终端启动前端（Node.js 20.9+）：
|
||
|
||
```powershell
|
||
cd frontend
|
||
npm ci
|
||
npm run dev
|
||
```
|
||
|
||
访问 http://localhost:3000。前端默认连接 http://localhost:8000/api。
|
||
|
||
## 阅读与对话
|
||
|
||
导入 EPUB 后，在书架或聊天页面点击「阅读全书」。阅读器支持：
|
||
|
||
- 目录跳转、原生分页翻页、字号调整（14–28）
|
||
- **阅读位置跨设备同步**：`relocated` 驱动的 CFI 位置存在服务端（`reading_progress` 表），换浏览器 / 换设备继续读；loses localStorage 仅作离线兜底
|
||
- **连续选取**：切换为 scrolled 流以便跨页选中文字，选完自动回到分页
|
||
- 选中文字后「保存摘录 / 添加高亮」，或直接「交给 AI 解读」把原文带入 AI 聊天
|
||
- 摘录与笔记侧栏支持导出 Markdown
|
||
|
||
顶部导航的「AI 助手」进入全局「第二大脑」模式：不绑定单本书，可跨书籍跨对话使用内置 `bm_*` 工具检索你的书库。
|
||
|
||
## MCP 外部工具
|
||
|
||
侧栏底部「MCP 服务」可添加远程 MCP 服务器（Streamable HTTP / 老式 SSE），配置 URL 与请求头（如 `Authorization`）。启用后，对话 AI 可调用其暴露的外部工具（如 Firecrawl 的搜索 / 抓取）获取书中没有的信息，回答时注明外部信息来源。工具调用过程会在流式回答中显示。配置会保存在 `mcp_servers` 表；模型需原生支持 function calling（OpenAI 兼容协议）才会启用工具循环。
|
||
|
||
## 验证
|
||
|
||
```powershell
|
||
cd backend
|
||
.venv/Scripts/python.exe -B -m unittest test_book_file
|
||
```
|
||
|
||
```powershell
|
||
cd frontend
|
||
npm run build
|
||
```
|
||
|
||
本地 `.env`、模型凭据、数据库、上传书籍和构建产物不纳入版本控制。
|
||
|
||
## 云服务器部署
|
||
|
||
见 `deploy/README.md`（Docker + nginx-proxy-manager，含数据迁移、`.env` 配置、NPM 反代、日常运维与历史数据清理）。 |