阅读器重构优化：统一评论模型，数据全部改走宿主回调（TB-199）

.github/workflows/pages.yml

@@ -0,0 +1,47 @@
+# 把介绍页与纯内存演示页（make dist 生成的 dist/index.html、dist/demo.html）发布到 GitHub Pages。
+# 演示页不连后端，评论数据只存在访问者浏览器内存里。
+# 首次使用需在仓库 Settings → Pages 把 Source 设为「GitHub Actions」。
+name: Pages
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - run: make dist
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

AGENTS.md

@@ -2,6 +2,84 @@
 
 面向 AI agent 的项目约定。与 `CLAUDE.md`（通用编码行为准则）配合使用。
 
+## 笔记功能设计约定
+
+以下是用户确认的目标设计，后续实现、接口对接和 UI 文案应遵循。阅读器一侧已按此实现；数据由宿主 talebook 通过 `annotation_callbacks` 提供，阅读器不直接调用 BRS 或任何评论、账号接口（契约见 `README.md`）。
+
+### 统一模型
+
+- 划线、文字笔记和整书评论统一属于「笔记」，不能再作为相互独立的数据和产品体系设计。
+- 每条笔记至少包含：类型、笔记内容、公开范围，以及必要的作者、书籍和位置关联信息。
+- 类型包括「划线」「文字」「整书评论」。「段落评论」「章节评论」「本书评论」是查看范围，不是额外的笔记类型；「整书评论」类型表示针对整本书撰写的笔记。
+- 公开范围区分私密与公开。私密笔记仅作者可查看；公开笔记可以被其他读者查看。
+- 新建文字笔记和整书评论在没有已保存偏好时默认公开。用户可以修改公开范围，并持久记忆最近一次选择，后续新建时沿用，刷新页面或重新打开阅读器后仍应保留。
+- 公开范围偏好只影响后续新建笔记，不修改已有记录；创建私密划线不能覆盖文字笔记和整书评论的公开范围偏好。
+- 划线固定为私密笔记，不提供公开划线选项。划线记录应保存所选原文和准确选区，不能要求用户填写文字内容。
+- 文字笔记有用户填写的内容和公开范围；公开的章段文字笔记必须出现在对应的段落、章节和本书查看范围中。保存时标记为公开、却无法从评论面板读到，不符合设计。
+- 宿主回调、评论 API 或本地存储是实现细节，界面中的创建、查询和展示必须遵循同一个笔记模型。仅保存在当前浏览器的数据不能被视为已经向其他读者公开。
+
+### 选区与评论归属
+
+- 单段文字笔记关联所在段落。
+- 允许多段选择后创建文字笔记，不能因跨段选择直接禁用文字笔记功能。
+- 多段文字笔记在章段评论查询、展示时，归属到选区最后一个段落的 CFI；本段评论入口也应使用同一归属规则。
+- 评论归属 CFI 与原始选区范围应分开保存或表达：归属最后一段不意味着丢弃前面选中的文字，也不能改变划线的真实范围。
+- 同一条公开笔记可以出现在多个查看范围中，但仍是同一条记录，不得为段落、章节、全书分别保存副本。
+
+### 入口与功能面板
+
+- 界面中原「笔记」文案统一改为「评论」，总入口为「评论」，创建按钮为「写评论」；划线、文字和整书评论仍使用同一统一模型。
+- 从总入口打开的笔记弹窗默认展示当前章节的所有评论。弹窗顶部提供「查看更多评论」入口，右侧带箭头，点击进入完整评论页面。
+- 评论弹窗采用底部抽屉模式，顶部不显示独立标题栏或 × 关闭按钮，内容顶部直接展示「本章评论」小标题与「查看更多评论 ›」入口；「写评论」按钮放在抽屉底部。
+- 笔记抽屉不额外展示「当前段落」引用区；从段尾气泡进入本段评论时也不展示该区域。编辑笔记时所需的原文引用仍由编辑框承载。
+- 抽屉与完整评论页面都不提供搜索功能。
+- 评论列表采用分页加载，滚动到底部时自动加载下一页；展示加载中、加载失败可重试和没有更多的状态。切换范围或筛选条件时重置分页，加载期间不能重复请求；过期请求不能混入新范围。自己评论优先的排序必须覆盖整个结果集，不能仅对每一页分别排序。
+- 移动端笔记抽屉占底部菜单上方可用阅读区域高度的 90%，贴底部菜单上沿展开，顶部保留 10% 的外部区域用于展示阅读上下文和点击收起。
+- 桌面端采用侧边栏：目录从左侧打开，笔记和设置从右侧打开；侧边栏覆盖在阅读区域上，不将正文改为双栏或压缩正文宽度。不同功能面板互斥，点击侧边栏外收起。原型暂用 850px 作为桌面断点，宽度值不是已确认的产品约定。
+- 阅读中的侧边栏、抽屉以及外部遮罩都必须避开底部菜单；这些面板展开时底部菜单可见、可点击，仍可直接切换目录、评论和设置。独立的完整评论页不保留阅读菜单。
+- 抽屉支持向下拖拽收起，也支持点击抽屉外区域收起。完整评论页面的返回导航与抽屉的收起操作是不同动作。
+- 完整评论页面支持「本章评论」与「全书评论」范围切换，并提供返回笔记弹窗的入口；弹窗承担阅读中的快速查看，完整页面承担更多评论的浏览。
+- 「查看更多评论」进入独立的完整评论页面，不是在抽屉或侧边栏内扩大列表；完整页占满整个内容区域，不保留阅读正文、底部阅读菜单或其他阅读界面元素，支持页面返回导航及浏览器返回。
+- 完整评论页从右侧进入，是独立页面容器和导航状态，不能通过改变原抽屉尺寸模拟新页面；返回时恢复原抽屉查看范围、筛选和滚动位置。
+- 完整评论页不显示独立 titlebar，顶部直接是「本章评论／全书评论」Tab 导航；返回入口融入同一导航行，不另占标题栏。「写评论」与抽屉保持一致，固定放在页面底部。
+- 选区工具栏的「划线」创建私密划线笔记；文字笔记入口打开文字笔记编辑框，编辑框应明确笔记内容和公开范围。
+- 面板支持三个查看范围：「本段评论」「当前章节的所有评论」「本书评论」。范围必须明确显示在面板标题或筛选状态中。
+- 「本段评论」查询归属当前段落的公开笔记；选区工具栏与正文段落评论气泡应进入相同的段落范围。
+- 正文段尾保留评论数量气泡，显示归属本段的公开笔记数量（不计私密划线或私密文字笔记），点击进入该段评论；调整抽屉或桌面侧边栏时不能丢失这个入口。
+- 「当前章节的所有评论」汇总本章的公开笔记，包含本章各段的公开文字笔记，不能仅查询旧接口中 `segment_id=0` 的章节级记录。
+- 本章评论列表直接展示每个人的作者信息和评论内容，不逐条展示所关联的正文引用；笔记编辑框中的原文引用不受影响。
+- 评论列表先列当前用户自己的评论，再列其他人的评论。其他人的条目仅展示名字、时间和评论内容；自己的条目额外提供「修改」按钮，打开该记录的编辑框，不得为其他人的评论提供修改入口。
+- 自己评论的「修改」入口使用文字按钮，紧跟评论正文末尾，与正文自然行内排版，不单独占据底部操作行。
+- 「本书评论」查看这本书的公开笔记，包含各章段的公开笔记和整书评论类型；不能被理解为仅查看「整书评论」类型。
+- 公开笔记的创建入口和查看入口必须互通，不能出现「看本段评论」实际只打开另一套本段笔记数据的情况。
+- 完整评论页的 Tab 为「本章评论／全书评论／我的」。「我的」列出当前用户在本书的全部记录，包含私密划线、私密文字和自己的公开评论；私密记录只在「我的」中出现，不混入「本章评论」「全书评论」等公开范围。游客进入「我的」时引导登录。
+- 整书评论关联到全书最开头的位置（首章起始处），不留空位置；它与其他记录使用同一套位置字段。
+
+- 设置里只有两个相互独立的评论开关：「显示全部划线和评论」（正文划线标记与段尾评论气泡）和「选中文字后显示工具栏」。不再设「启用划线和笔记功能」总开关；关闭任一开关都不删除数据，评论入口始终可用。
+
+### 互动：赞、踩、回复
+
+以下为用户确认的规则。
+
+- 公开评论及其回复都支持赞、踩、回复；阅读器中的单条记录直接展示「赞 N／踩 N／回复 N」操作行，其中赞和踩用图标加数字表示，不显示「赞」「踩」文字（保留无障碍标签）；已投的一项用实心图标和主色区分。游客可浏览，点击操作时引导登录。私密记录不开放他人互动。
+- 赞与踩互斥：重复点击取消，点另一项则替换；每个用户对每个目标只有一个投票。允许给自己的评论投票，也允许回复自己的评论。请求失败时界面恢复到操作前状态。
+- 自己评论的「修改」入口仍紧跟正文末尾，不并入操作行。
+- 详情页中，直接回复主评论的第一层回复不缩进，与主评论左对齐；第二层及之后的回复（回复的回复）统一只缩进一级，归在所属的第一层回复下面，彼此同级排列并显示回复对象。不得出现更深的层级缩进。
+- 回复挂在主评论下，不单独出现在段落、章节、全书的顶层列表中。段尾气泡只统计公开顶层评论，不计投票和回复。
+- 查看回复时进入独立的评论详情页面，评论列表内不展开回复。点击列表中的单条评论（按钮以外的区域）或其「回复 N」都进入详情页；赞、踩、修改、删除等按钮在列表中原地生效，不跳转。详情页结构：顶部是返回入口，正文是主评论及其操作行，下面是回复列表（缩进规则见上），回复输入固定在页面底部。详情页与完整评论页一样占满整个内容区域、从右侧进入，支持页面返回和浏览器返回；返回后恢复原列表（抽屉或完整评论页）的范围、已加载数量和滚动位置，计数与列表保持同步。
+- 删除是真删除，不做软删除，不保留「已删除」占位。删除主评论时，其下全部回复以及相关投票一并删除。
+- 作者可以修改自己的评论和回复；修改后不显示「已编辑」标记。
+- 回复没有独立的公开范围，跟随主评论。公开评论改为私密后，其下已有回复只有该评论作者自己能看到，其他人（包括回复的作者）不可见，也不能再对其投票或回复。
+- 整书评论虽然关联到全书开头，但不出现在首章的「本章评论」中，只出现在「全书评论」和作者的「我的」里。
+- 不迁移旧 BRS 评论数据，升级时直接清空。
+
+尚未确认，实现前需先问用户，不要把临时选择当成已确认的设计：
+
+- 评论详情页中回复的排序与分页方式。当前实现：时间正序，每页 20 条，滚动到底继续加载。
+- 抽屉和完整评论页底部的「写评论」在没有选区时写什么。当前实现：本段范围写该段的文字评论，本章／全书／我的范围写整书评论。
+- 删除第一层回复时，其下第二层及之后的回复是否一并删除。
+- 私密评论重新改回公开后，原有回复和投票是否恢复可见。
+
 ## 提交 PR 前必须跑 e2e 测试
 
 **任何改动在提交 / 推送 PR 之前，必须本地跑通 Playwright e2e 测试。** CI 会跑同一套用例，本地先验证可避免红 CI 来回。
@@ -18,5 +96,5 @@ npm run test:e2e
   E2E_PORT=5009 npm run test:e2e               # 让 Playwright 复用它
   ```
 
-- 全量套件应全部通过（当前 33 passed）。失败用例的现场快照在 `test-results/<用例名>/error-context.md`。
-- 改了底部导航 / 登录 / 评论面板等 UI 时，重点核对 `tests/e2e/{auth,user-center,reader-ui,comments-login}.spec.js`：这些用例按文案（如「评论」「点击登录，发表评论」）定位元素，改文案会连带改测试。
+- 全量套件应全部通过（当前 61 passed）。失败用例的现场快照在 `test-results/<用例名>/error-context.md`。
+- 改了底部导航 / 评论面板等 UI 时，重点核对 `tests/e2e/{comments,annotations,panel-focus,reader-ui}.spec.js`：这些用例按文案（如「评论」「查看更多评论」「写评论」）定位元素，改文案会连带改测试。