# ai- reader

**Repository Path**: ketty9527/ai-reader

## Basic Information

- **Project Name**: ai- reader
- **Description**: 个人看书app开发尝试  
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-16
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ai-reader · 百胜书房

**Legado 私人阅读助手服务端** — 与 [Legado](https://github.com/gedoor/legado)（开源阅读）集成的
"小说 + 私人助手"后端，Docker 一键部署。

> **职责边界**：阅读的一切（书源/书架/正文/TTS/备份）都在 Legado App 内；ai-reader 是
> **完整 agent 平台**：私人助手（陪读/找书/回忆）+ 阅读记忆 + AI 校对（错别字/标点）+
> 更新聚合 + 换源巡检 + 联网搜索/网页读取/长时记忆/文件/视觉工具（高权限工具带设备审批）。
> 详见 [`PRD.md`](PRD.md)（v2.2）。

## 快速开始（Docker）

```bash
cp .env.example .env        # 填 DEEPSEEK_API_KEY（或其他模型 Key）
docker compose up -d --build
docker compose exec ai-reader cat /data/admin_token.txt   # 首次自动生成的管理令牌
```

- 服务端口 `9119`；健康检查 `GET /health/ready`；API 文档 `GET /docs`。
- 局域网直连：手机 Legado 填 `http://<服务器IP>:9119` + 设备 API Key。
- 公网暴露：前置 Caddy/Nginx 反代启用 TLS（见 docker-compose.yml 注释）。

### Caddy 反代示例

```
reader.example.com {
    reverse_proxy 127.0.0.1:9119
    # SSE 流式对话必需: 关闭缓冲
    flush_interval -1
}
```

Nginx 等价配置要点：`proxy_pass http://127.0.0.1:9119;`
`proxy_http_version 1.1; proxy_set_header Connection "";`
`proxy_buffering off;`（SSE 必须关闭缓冲，否则对话无逐字输出）。

## 本地开发

```bash
uv sync                     # 安装依赖（Python 3.11+）
uv run ai-reader-api        # 启动（默认 0.0.0.0:9119）
uv run pytest tests/ -q     # 回归 + novel 验收测试
```

开发时可用 `BSN_AUTH_ENABLED=0` 临时关闭鉴权（仅限本机）。

## API 一览

| 端点 | 说明 |
|---|---|
| `GET /health` `/health/ready` | 存活 / 就绪（DB + 数据目录） |
| `POST /v1/chat` | 助手对话（HTTP/SSE），支持 `meta` 场景注入（陪读/找书/回忆/梗概） |
| `GET/POST /v1/sessions` `GET/DELETE /v1/sessions/{id}` | 会话管理（基座） |
| `GET/DELETE /api/v1/sessions/book/{book_id}` | 按书列出/删除会话 |
| `POST /api/v1/auth/devices` | 签发设备 API Key（管理令牌） |
| `GET/DELETE /api/v1/auth/devices[...]` | 设备列表 / 吊销 |
| `PUT/DELETE /api/v1/books/{book_id}` | 书架镜像 upsert / 撤书 |
| `PUT /api/v1/books/{book_id}/progress` | 阅读轨迹推送 |
| `GET /api/v1/books` `GET /api/v1/memory/summary` | 记忆查询 |
| `DELETE /api/v1/memory` | 清空阅读记忆（不动会话历史） |
| `POST /api/v1/proofread` | **AI 校对**（离线规则 + LLM 双通道，同章去重不重复扣费） |
| `GET/POST/DELETE /api/v1/memory/long-term` | **长时记忆**（偏好/事实/笔记，FTS 检索） |

> 当前完成 **M1 + M2**：鉴权、阅读记忆、陪读/找书/回忆/梗概场景、AI 校对、长时记忆、按书会话管理。
> M3+（更新聚合/换源巡检/书摘/Agent 工具）见 [`PLANS.md`](PLANS.md)（任务级实施计划），进度总览见 [`STATUS.md`](STATUS.md)。

### 对话示例（陪读）

```bash
curl -X POST http://127.0.0.1:9119/v1/chat \
  -H "Content-Type: application/json" -H "X-API-Key: air_xxx" \
  -d '{
    "messages": [{"role":"user","content":"这章讲了什么？"}],
    "session_id": "device-1-book-toc123",
    "meta": {
      "scenario": "read_companion",
      "book": {"id": "toc123", "name": "诡秘之主"},
      "chapter": {"index": 120, "title": "第120章"},
      "chapter_text": "……章节正文（≤8000字符）"
    }
  }'
```

## 目录结构

```
api/                # [vendored] HTTP/SSE 层（集成点：meta 注入、鉴权、ready）
agent/ core/ gateway/ hermes_cli/ providers/ tools/   # [vendored] 对话基座，见 VENDORED.md
novel/              # [自研] 鉴权 / 记忆 / 校对 / 场景编排
├── api/            #   /api/v1（auth、books、memory、proofread、sessions）
├── assistant/      #   meta → 场景上下文组装（陪读/找书/回忆/梗概）
├── proofread/      #   AI 校对：rules（离线规则）+ ai（LLM 通道）
├── auth_gate.py    #   统一鉴权中间件（纯 ASGI）
├── fts.py          #   FTS5 trigram 幂等 DDL（create_all 补建）
├── models.py db.py config.py security.py migrate.py
migrations/         # Alembic（0001/0002/0003，启动自动 upgrade head）
android/            # [客户端] Legado 开源阅读 Android 代码（Kotlin + Gradle）
Dockerfile docker-compose.yml
PRD.md README.md STATUS.md PLANS.md AGENTS.md VENDORED.md SOUL.md
```

## 配置

- **行为开关**：`config.yaml`（`novel:` 节：auth_enabled 等）。
- **密钥**：`.env` 只放密钥（`BSN_ADMIN_TOKEN`、模型 Key），不进 config.yaml。
- **数据目录**：`BSN_DATA_DIR`（默认 `./data`；Docker 为 `/data` 卷）——含 `novel.db`（记忆）、
  `state.db`（会话）、`admin_token.txt`（管理令牌）。打包即备份。

## 维护

- vendored 基座来源与升级流程见 [`VENDORED.md`](VENDORED.md)。
- 新能力优先落 `novel/`；基座文件改动需 `baisheng(ai-reader) 定制:` 注释标记并最小侵入。