# AI Native 阅读设计

## 目标

AI 阅读不是一份脱离原文的报告，也不是一个新页面。它是覆盖在 EPUB 原文之上、
可定位、可验证、可恢复的共享学习层。

## 三个界面

### 阅读页：语义画布

阅读页依照阅读动作分为四层，而不是把所有 AI 内容都当作标注：

1. **章前导读**：置于正文之前，说明本章解决的问题、阅读路线与关键提醒。
2. **句子标注**：只解释精确的原文句子；点击高亮后在下方弹出 Markdown 透视卡。
3. **段落便利贴**：总结一段内容在整章中的作用，而不重复解释其中某句话。
4. **章末深入思考**：在正文结束之后，用少量问题邀请读者整合本章，而非在阅读中
   打断理解。

段落便利贴不常驻成卡片：它精确锚定在对应段落旁，以一个彩色 `!` 作为轻量提示；
点击才展开该段的 Markdown 说明，并可通过关闭按钮收起。Mermaid 思维导图收在章前导读的
“查看思维导图”触发器中，点击才展示；在触控设备上同样可用。图以本章主题为中心、向外展开
主线与支撑概念，而非把段落顺序画成流程。这样正文始终优先，AI 内容只在
读者需要时出现。无法精确引用的综合观点不会伪装为句子标注。

## 共享与剧透

共享键包括书籍、范围、语言、书籍策略、模板版本和模型配置版本。`读至第 N
章` 是一个显式边界，绝不自动展示给读到更早位置的用户。全书层始终带有剧透
标识。旧结果可用，只有管理员显式重生成才成为当前版本。

## 结果契约

模型返回严格 JSON；文本字段使用受限 Markdown，绝不直接返回 HTML。章节学习
层包含 `quick`、`structure`、`deep.questions[]`、`annotations[]` 与
`paragraph_notes[]`。每个
句子标注至少包含：

```json
{
  "kind": "concept|claim|evidence|turn|question",
  "quote": "原文精确子串",
  "title": "简短标题",
  "body_markdown": "解释，可含公式或图形",
  "chapter_index": 3
}
```

服务端验证字符串长度、类型和精确引用；模型若把书内印刷章节号误作页面索引，
服务端会在锚点确属当前章节时归一为当前页面索引。无效锚点不会进入阅读画布。

## 后台任务

学习层生成与私人追问都先写入 SQLite 队列，HTTP 接口只返回任务或对话 ID。服务
进程内的 worker 以原子领取方式消费队列，SSE 仅订阅这份持久状态。因此关闭页面
不会取消生成，进程重启时运行中的任务会重新排队；同一共享学习层仍由缓存键保证
只有一个生成请求，私人追问则独立排队。

## 富文本安全

Markdown 由本地渲染器生成 DOM，模型 HTML 作为纯文本。仅接受 fenced
`mermaid` 和 `math` 区块：Mermaid 使用严格安全模式，禁止脚本、外部 URL 和
HTML；KaTeX 禁用 HTML 宏。失败时保留代码文本与复制入口。

## 模板治理

提示词位于 `epub_browser/prompt_templates/`，按策略和任务组织，并包含模板 ID、
版本、输出契约、证据要求、标注预算和 Mermaid/KaTeX 规则。结果保存模板和
模型配置版本，确保缓存与历史可解释。思维导图使用 Mermaid `mindmap` 语法：中心
主题、3–6 条主分支、最多一层子分支；新模板不会复用旧版流程图结果。

## 交付顺序

1. 模板文件、共享学习层元数据、锚点校验与 API。
2. 阅读页的共享语义画布：章前导读、句子透视和段落旁注。
3. 本地 Markdown、KaTeX、Mermaid 渲染与安全降级。