工程代号：ReadLoop
正式产品名：待定（当前候选：余思 / 页外；正式命名前不要在代码中硬编码品牌名）
产品定位：以阅读为入口的 Personal Thinking Agent / Agent-native iOS Reader
文档版本：v0.4
状态：长期主文档（Source of Truth）
首发平台：iOS / iPhone
首发内容格式：用户自导入的非 DRM EPUB
核心 AI 形态：BYOK（Bring Your Own Key）云端模型 + 本地 Agent Runtime
最后更新：2026-10-09
本 PRD 用于长期产品开发，不是一次性 brainstorm。后续任何新功能都应回答三个问题：
- 它是否强化“阅读 → 思考 → 输出 → 反馈 → 沉淀 → 再阅读”的主循环？
- 它是否让用户更愿意真正思考，而不是把思考外包给 AI？
- 它是否破坏了“阅读时少打扰、本地优先、用户拥有数据、AI 可解释且可控”的产品原则？
若一个需求与本文的“产品不变量”冲突，应先修改 PRD 并记录理由，再改代码；不要让实现细节反向定义产品。
一个让阅读真正留下来的地方。
ReadLoop 不以“读更多书”为终点，也不把自己定义成“一个带 AI 问答的 EPUB 阅读器”。
它真正要成为的是：
一个以阅读为入口、长期陪用户思考的 Personal Thinking Agent。
传统阅读产品通常结束于：
打开一本书 → 阅读 → 划线 → 读完
大量 AI Reader 则增加：
选中一段 → Ask AI → 解释 / 总结
ReadLoop 要闭合的是另一条链：
阅读 → 思考 → 表达 → Agent 反馈 → 追问 → 沉淀 → 连接过去 → 形成长期认知变化
阅读器的意义，不只是“承载 EPUB”，而是让 Agent 和用户拥有同一份第一手阅读上下文；真正长期积累的产品资产则是用户自己的 Reflection、观点、问题、连接和思想变化。
用户不是为了“AI 总结一本书”安装 ReadLoop。
用户真正需要的是：
- 我读完后不要什么都忘了；
- 我希望有人愿意认真听我说刚刚读到了什么；
- 我希望得到有知识增量、但不卖弄的反馈；
- 我希望有人在合适的时候挑战我的理解，而不是永远夸我；
- 我希望几个月后还能重新找到当时的想法；
- 我希望 AI 越陪我读越懂我；
- 我希望看到自己的观点、知识和思考方式是如何变化的；
- 我希望养成“读完以后说出来/写出来”的习惯；
- 我希望这个过程足够轻松，不像做读书作业。
截至 2026-08-24 的 iOS 市场调研显示，相关产品已经形成几个清晰类别：
| 类别 | 已被验证的需求 | 市场状态 | ReadLoop 的判断 |
|---|---|---|---|
| EPUB / PDF Reader | 好用的移动阅读体验 | 成熟、拥挤 | 必须做到合格，但不是定位 |
| Reader + AI Explain/Summary | 解释、总结、问书 | 快速同质化 | 不作为核心卖点 |
| Reading Tracker / Streak | 坚持阅读、统计阅读 | 成熟 | 学行为设计，不做数据炫耀 |
| Highlight / Notes | 留下划线与笔记 | 成熟 | 是基础数据，不是终点 |
| AI Reading Journal | 读后记录、AI 整理 | 快速升温 | 核心近邻赛道 |
| Voice Reflection | 低成本输出思考 | 很早期 | 应成为 Hero Feature |
| Long-term Reader Memory | AI 记得过去怎么想 | 很早期 | 核心护城河 |
| Reader Profile | AI 理解“我是怎样的读者” | 非常早期 | 重要长期资产 |
| Personal Intellectual Timeline | 观点如何随时间变化 | 几乎空白 | 长期差异化 |
| Reflection Habit | 让“读后输出”成为习惯 | 明显空位 | 最核心行为闭环 |
因此 ReadLoop 的竞争坐标不是：
“谁的 EPUB 阅读器支持更多格式、谁的 AI 总结更快。”
而是：
谁能最稳定地让用户在阅读后产生高质量输出，并让这些输出经过多年积累后成为一份真正有价值的个人思想档案。
近邻产品常见形态：
Kindle / Apple Books / 微信读书 → 导出 → AI App
ReadLoop：
Import → Read → Highlight → Reflect → Discuss → Remember
减少 Context Switch，并允许 Agent 准确知道用户刚刚读过什么。
大量 AI Reader 的核心问题是：
Ask your book.
ReadLoop 的核心问题是：
What did this book make you think?
Ask-your-book 是工具能力；理解用户的思考过程才是产品能力。
产品中最重要的数据优先级：
User Reflection > User Highlight/Note > Agent Commentary > AI Summary
长期要积累的是：
- 原始表达；
- Idea；
- Belief；
- Question；
- Changed Mind；
- Cross-book Connection；
- Reader Profile；
- 思想时间线。
传统产品奖励：
读了多久 / 连续多少天 / 读完多少本
ReadLoop 更关心：
今天有没有真正输出 / 有没有形成问题 / 有没有建立连接 / 有没有修正旧观点
核心连续指标是：
Thinking Streak
Agent 的价值随着用户历史增加而增加：
更多 Reflection → 更准确的 Memory → 更相关的连接 → 更好的反馈 → 用户更愿意继续 Reflection
这构成 ReadLoop 的长期复利。
以下竞品用于产品 benchmark，不意味着逐项复制：
| 产品 | 值得学习 | ReadLoop 不应复制的方向 |
|---|---|---|
| Avid | Voice conversation、长期记忆、跨书连接、Weekly/Yearly insight | 阅读与思考仍分离；ReadLoop 应拥有原生阅读上下文 |
| Canto | Reader Profile / “Reader's DNA” | 不把画像做成静态标签，应保持 evidence-based、可修改 |
| Coreader | Session 后语音输出、Reflection workflow | 避免演化成泛知识工作台 |
| EchoRead | 中国用户的知识沉淀、跨书笔记关联 | 不把产品中心变成思维导图/AI 笔记生产 |
| Quillet / ReadDeep | 原生 Reader + AI 的产品完成度、BYOK 可行路径 | 避免停留在“Ask your book” |
| Reeden | 阅读器完成度、阅读目标与统计 | 不参与格式/云盘功能军备竞赛 |
| Bookly / Bookmory | Streak、Timer、低摩擦 Habit Loop | 不用阅读时长和 XP 替代真实思考 |
| Highlighted | “让读过的东西留下来”的清晰价值 | ReadLoop 要进一步把 Capture 升级成 Think |
ReadLoop 不应该追求“功能最多”，而应该成为：
Reader + Reflection Agent + Long-term Intellectual Memory + Thinking Habit 的最佳一体化体验。
如果未来某项需求无法明显强化这四件事，应默认降级优先级。
以下原则优先级高于具体 Feature。
用户读的时候，Agent 默认安静。用户抬头的时候，Agent 在。
禁止把阅读器做成充满 AI 弹窗、自动解释、自动问答的“智能教材”。
阅读过程中，Agent 的主要入口来自用户主动行为：
- 划线；
- 批注；
- 长按“聊聊这句”；
- 主动打开讨论；
- 主动结束阅读 Session。
主动介入主要发生在 Session 结束后。
ReadLoop 不能把“用户没有思考”包装成“AI 帮用户总结了”。
默认流程应当是：
用户先说/写 → Agent 再回应
而不是：
Agent 先总结 → 用户被动阅读总结
用户的原始表达是产品最重要的数据资产之一。
Agent 应该帮助用户：
- 澄清；
- 连接；
- 追问；
- 质疑；
- 补充背景；
- 回忆旧观点；
- 发现认知变化。
Agent 不应该默认替用户：
- 写读后感；
- 给出“标准感想”；
- 把所有章节总结成模板笔记；
- 为了“有用”而不断输出大量知识。
Agent 的目标不是“显得知道很多”，而是：
在此刻，为这个用户，补充最值得补充的一点。
博学感来自关联精准，而不是引用数量。
以下数据默认保存在设备本地：
- 导入书籍；
- 阅读进度；
- Reading Session；
- Highlight；
- Note；
- Reflection；
- Agent 对话；
- Reader Profile；
- 长期 Memory；
- Retrieval Index；
- Agent Trace。
V1 不要求 ReadLoop 自有账号，也不要求 ReadLoop 后端服务器。
中国大陆是首要使用场景之一，因此产品不能把核心 AI 能力建立在 Apple Intelligence、Foundation Models 或特定 Apple Intelligence 设备能力上。
用户自行配置第三方 AI 服务商 API Key。
核心产品必须支持：
- 无 ReadLoop 服务器；
- 用户 Key 仅保存在本机安全存储；
- App 直接与用户选择的 AI Provider 通信；
- 更换 Provider 不丢失个人阅读数据和 Agent Memory。
Agent 可以在后台形成读者画像，但不能形成“不可见的秘密画像”。
用户必须能：
- 查看 Agent 记住了什么；
- 查看记忆来自哪些原始证据；
- 标记“不准确”；
- 修改；
- 删除；
- 禁止某些内容进入长期记忆；
- 一键清除 Agent Memory。
学习 Duolingo 的是：
- 极低启动成本；
- 每次打开都有清晰下一步；
- 即时反馈；
- 连续行为强化；
- 成长可见；
- 中断后容易回来。
不要机械复制：
- 过度金币；
- 宝箱；
- 诱导排行；
- 高频通知；
- 让用户为了 XP 刷无意义行为。
我们奖励“思考行为”，不只是“阅读时长”。
阅读器、AI 解释、摘要、格式支持都很容易被复制。
ReadLoop 长期真正要积累的是：
- 用户愿意持续 Reflection 的行为习惯；
- 用户多年累积的原始思想档案；
- Evidence-based Personal Intellectual Memory；
- 能正确使用这些历史的 Reader Agent Policy；
- “过去的我 ↔ 当前的我 ↔ 当前这本书”之间的高质量连接。
因此任何资源冲突时，优先级遵循：
Reflection Quality > Memory Quality > Reader Agent Quality > Habit Loop > Reader Feature Breadth
优先服务：
- 18–35 岁；
- 有稳定阅读习惯或明确想建立阅读习惯；
- 经常使用 EPUB；
- 对 AI 有一定接受度；
- 希望把阅读转化为成长，而不仅是娱乐；
- 愿意在读后花 1–5 分钟说出自己的想法；
- 能接受 BYOK 作为早期产品门槛。
典型人群：
- 大学生；
- 研究生；
- 知识工作者；
- 程序员；
- 产品经理；
- 内容创作者；
- 长期阅读非虚构/文学/社科的读者。
V1 不针对：
- 主要阅读漫画的用户；
- 需要复杂 PDF 论文标注的科研用户；
- 只需要听书的用户；
- 想购买电子书内容的用户；
- 只想让 AI 替自己总结、不愿输出的用户。
当我获得一本 EPUB 时，我希望可以直接在一个体验优秀的 iOS 阅读器里长期阅读，并且进度、划线和批注都属于我自己。
当我刚读完一段内容时，我希望能用最低成本把脑子里的想法说出来，而不是逼自己写一篇正式读书笔记。
当我说出一个尚不成熟的想法时，我希望得到像一位博学但尊重我的读者一样的回应，让我往前多想一层。
当我长期使用后，我希望 Agent 记得我以前读过什么、说过什么、在哪些主题上经常思考，而不需要每次重新解释自己。
当几个月或几年过去后，我希望看到自己的观点如何变化，而不是只看到“今年读了 37 本书”。
当我结束阅读时，我希望 App 自然推动我完成一次 1–3 分钟的输出，让“读完以后想一想”逐渐成为习惯。
当我使用几个月或几年后，我希望这里保存的不是一堆 AI 总结，而是我自己真正说过、想过、质疑过、改变过的东西，并且能够重新回到当时的原始证据。
导入一本书
↓
开始阅读
↓
Reading Session
├── 翻页
├── Highlight
├── Note
└── 主动提问（可选）
↓
结束 Session
↓
低摩擦 Reflection
├── 语音
└── 文字
↓
Agent 反馈
├── 理解
├── 点评
├── 知识补充
├── 跨书/历史连接
└── 一个值得继续想的问题
↓
用户继续对话（可选）
↓
生成 Reading Journal
↓
长期 Memory / Reader Profile 更新
↓
未来阅读时重新利用
产品是否成立，最重要的验证点不是“Agent 回答是否很长”，而是：
用户读完 20 分钟后，会不会愿意再花 2 分钟输出，并且觉得这 2 分钟值得。
V1 建议采用 3 个一级入口：
书架顶部根据状态显示一条 Next Action：
- 有未完成的 Reflection：显示“刚才读的，还没有留下想法”与补写入口；
- 没有待办动作：不额外显示卡片，书架直接呈现书籍；
- Reading / Thinking Streak 不再放在首页，移动到“我的”。
书架不是数据 Dashboard。下一步动作只服务于当前最值得做的一件事。
用户拥有的书。
包含：
- 导入 EPUB；
- 封面；
- 作者；
- 进度；
- 最近阅读；
- 阅读时长；
- Highlight 数；
- Reflection 数；
- 搜索；
- 排序。
V1 不做线上书城。
不是普通 Notes List，而是内部维护的“阅读思想档案”。
Journal 是派生数据模型，不在用户界面中单独暴露为“档案”入口。用户展开一条阅读记录后，只按需看到其中的结构化结果（“这次留下”）。
一条 Journal Entry 应展示：
- 日期；
- 书籍；
- 阅读章节/位置；
- 本次阅读时长；
- 本次用户原始输出；
- Agent 整理出的核心观点；
- 有价值的 Agent Commentary；
- Agent Question；
- 用户后续回答；
- 本次关联的 Highlight；
- 关联的旧 Reflection；
- 形成/修改的 Memory。
长期个人阅读档案与 Reader Profile。
V1/P1 包括：
- Reading Streak；
- Thinking / Reflection Streak；
- 读过的书；
- Reflection 历史；
- 主题兴趣；
- Agent 记忆；
- Agent 眼中的我；
- 可修改/删除记忆。
长期演化为：
- Idea Timeline；
- Personal Intellectual Timeline；
- Concept Graph；
- “Changed My Mind”；
- 跨书连接；
- 年度思想回顾；
- 某个主题上的观点演变；
- “哪些书真正改变过我”；
- “哪些问题我反复提出但一直没有解决”。
My Mind 的产品目标不是做另一份 Obsidian Graph，而是回答：
过去的我到底是怎么想的？今天的我哪里已经不一样了？
用户可通过：
- Files；
- iCloud Drive；
- Share Sheet；
- AirDrop 后“用 ReadLoop 打开”；
导入非 DRM EPUB。
导入时：
- 校验文件可读取；
- 计算内容指纹避免重复；
- 解析 metadata；
- 生成书籍记录；
- 保存到 App Sandbox；
- 后台建立全文索引；
- 索引未完成也应允许先阅读。
- DRM 破解；
- 在线盗版书源；
- MOBI/AZW；
- PDF；
- 漫画；
- 在线书城。
V1 阅读器至少支持：
- 分页/滚动模式二选一时优先分页；
- 字号；
- 行高；
- 页边距；
- 明/暗主题；
- 章节导航；
- 阅读进度；
- Highlight；
- Note；
- 文本选择；
- 搜索；
- 跳转到 Highlight/Agent Citation；
- 恢复上次位置。
核心要求：阅读器本身必须达到“长期愿意使用”的完成度，不能只是 Agent Demo 的容器。
一次连续阅读形成一个 Session。
记录：
- bookID；
- start/end time；
- start/end locator；
- 阅读时长；
- 新增 Highlight；
- 新增 Note；
- 用户主动与 Agent 讨论的次数。
禁止 V1 默认记录过于侵入性的精细行为，例如每个段落精确停留时长。
未来若使用“返回某段、多次查看”等弱信号，应：
- 明确说明；
- 只用于提升本地体验；
- 提供关闭能力；
- 不把弱信号直接当作确定事实。
用户主动结束阅读，或退出长时间后，再回到 App 时可以触发 Session Ending。
推荐 UI：
今天读了 24 分钟
进度 37% → 42%
留下 3 个高亮
有什么留下来了吗？
[ 按住说 ]
[ 写一点 ]
[ 今天先不了 ]
原则：
- 不制造负罪感；
- “跳过”始终清晰可见；
- 默认 Reflection 时间预期为 1–3 分钟。
用户可：
- 长按录音；
- 点击开始/结束；
- 看到实时或准实时转录；
- 编辑转录；
- 使用纯文字输入。
保存：
- 原始用户文本；
- 可选的音频文件；
- 时间；
- 当前书籍上下文；
- 当前 Session；
- 关联 Highlight。
默认建议：
- 原始音频可由用户选择“不保存”；
- Transcript 是 Reflection 的核心持久数据。
每次 Reflection 成功保存后，系统默认自动发起第一次 Agent response。用户不需要点击“请 AI 回应”，也不需要在列表中确认回应状态。
Agent 回应不是固定模板，但应符合以下内部教学策略。
用户更接近：
- 复述；
- 理解；
- 联想；
- 质疑；
- 形成观点；
- 情绪反应；
- 提问；
- 应用到现实。
候选：
- 鼓励；
- 澄清；
- 补充；
- 举例；
- 连接；
- 反驳；
- 苏格拉底式追问；
- 提醒旧观点；
- 保持安静。
默认一次回应：
- 先准确回应用户；
- 最多补充 1–2 个真正相关的知识连接；
- 最多提出 1 个值得继续思考的问题。
禁止：
- 一次列 8 个延伸知识；
- 永远“你思考得太深刻了”；
- 为了展示博学而引用大量作者；
- 频繁把简单情绪强行哲学化；
- 把用户每次表达都纠正成教科书答案。
Agent 不应默认每次都展开长讨论。
允许的高质量结果包括：
- 简短确认 + 一个精准追问；
- 指出用户仍在复述，没有形成自己的判断；
- 提供一个反例；
- 只补充一个背景事实；
- 明确表示“这里暂时不需要分析更多”；
- 对纯情绪体验给予空间，而不是强行知识化。
“少说但说得对”优先于“每次都显得很聪明”。
Agent 在讨论当前阅读内容时，应优先获得：
- 用户刚刚阅读的章节/区间；
- 本 Session Highlight；
- 本 Session Note；
- 当前 Book 的全文检索结果；
- 本书已有 Reflection。
用户不需要重复粘贴上下文。
Agent 可检索：
- 用户过去 Reflection；
- 用户旧 Highlight/Note；
- Reader Profile；
- 长期 Memory；
- 过去对相同概念的观点。
当 Agent 使用旧记忆时，UI 应允许用户点击回到证据源。
例：
“你在 6 月读《局外人》时曾经说过……”
点击可进入原 Reflection。
每次 Reflection 完成后自动生成一条 Journal。
Journal 保留为内部结构化数据，不作为用户可见的独立入口。思考页只展示阅读记录；展开记录后可显示可选的“这次留下”区域。
每次第一次 Reflection 和第一次 Agent response 保存后，系统自动生成一条不可变概要：
- 12–24 个中文字符，硬上限 36；
- 输入只使用第一次 Reflection 和第一次 Agent response；
- 生成后不因模型、Provider、追问或用户编辑而重写；
- 删除 Reflection 时级联删除概要。
推荐结构：
保留用户原始表达，不被 AI 覆盖。
Agent 可将用户表达整理成 1–3 条短观点，但必须忠于用户。
保存真正有价值的交流。
可链接：
- 当前书原文；
- 过去 Reflection；
- 其他用户导入书籍；
- 外部知识来源。
本次仍值得继续想的问题。
Memory 分为：
发生过什么。
例如：
2026-08-24 读《置身事内》时讨论了地方财政。
用户已经形成的稳定理解。
例如：
用户已理解“激励结构可以在没有恶意的情况下导致系统性结果”。
讨论偏好。
例如：
用户更喜欢具体反例而不是抽象鼓励。
尚未解决但值得长期追踪的问题。
长期模式。
例如：
用户经常能进行跨领域类比，但有时对因果证据要求不足。
Memory 必须包含：
- claim；
- confidence；
- createdAt；
- updatedAt；
- evidence IDs；
- status；
- userEdited flag。
用户可查看 Agent 当前形成的 Reader Profile。
UI 语言必须避免“心理诊断”感，定位为：
“这是我目前从我们的阅读与讨论中形成的理解。”
每条支持：
- 准确；
- 不准确；
- 修改；
- 忘记；
- 查看依据。
禁止推断或展示不必要的敏感人格/健康/政治身份标签。
V1 建议只做两个核心连续指标：
今天是否发生有效阅读。
今天是否完成一次有效 Reflection。
Thinking Streak 是核心差异化。
只奖励有意义的认知行为。
可选首批：
- First Reflection：第一次输出；
- Connector：第一次主动联系两本书；
- Questioner：第一次明确质疑作者；
- Changed My Mind：主动修改旧观点；
- Seven Days Thinking：连续 7 天 Reflection；
- Return to an Idea：重新讨论 30 天前的观点。
Achievement 不应影响 Agent 对内容质量的判断。
- Weekly Insight；
- Monthly Insight；
- “AI 眼中的我”成熟版；
- Historical Recall；
- 用户观点演变；
- 自动发现跨书连接；
- 一键回顾 30/90 天前想法；
- iCloud/CloudKit 可选同步；
- 更精细的 Reader Agent Style。
引入受控的外部知识层：
- 公版经典作品；
- 合法授权知识包；
- 作者背景；
- 思想流派；
- 历史上下文；
- 哲学/经济/文学核心概念；
- 可追溯出处。
要求：
- 外部知识不是越多越好；
- 必须优先当前书和个人历史；
- 所有事实/引用尽可能具备 provenance；
- 现代版权作品不得未经授权直接打包全文。
图谱核心实体：
- Book；
- Author；
- Highlight；
- Reflection；
- Idea；
- Concept；
- Question；
- Belief；
- Memory。
典型查询：
- 我过去一年最常思考什么？
- 我对“自由”的理解发生了什么变化？
- 哪些书真正改变了我的观点？
- 哪些问题被我重复提出但还没有答案？
- 哪些作者的观点经常被我认同/反对？
Agent 是：
一位读过大量作品、好奇、克制、尊重用户、不急于展示自己、愿意认真听人说话的长期阅读伙伴。
- 首先理解用户；
- 区分“情绪体验”和“事实判断”；
- 能承认不确定；
- 能提出反例；
- 能告诉用户“这里可能理解错了”；
- 能说“这次没有必要分析这么多”；
- 能记得过去；
- 能在引用历史时给出证据；
- 根据用户水平调整讨论深度；
- 逐渐形成稳定但可修改的个人化风格。
- 过度恭维；
- 用长文压住用户；
- 每次强行给建议；
- 把所有内容都联系到哲学；
- 把模型预训练知识冒充书中原文；
- 把推测冒充用户稳定人格；
- 擅自代表用户写正式观点；
- 通过制造焦虑提高留存。
阅读正文继续使用独立、舒适的纸张白、暖色或深色主题，不因应用壳层色彩变化而牺牲长时间阅读体验。
品牌色、交互色和状态色必须语义分离：品牌色用于识别与强调，交互色用于可操作控件，成功/警告/危险状态色只表达状态。不得用同一种绿色同时承担品牌、按钮、进度与成功反馈。
Agent 应该散布在整个体验中：
- Session Ending；
- Highlight 旁；
- Journal；
- My Mind；
- Weekly Insight；
- Historical Recall。
“聊天页”只是其中一个容器，不是产品本体。
动效重点用在：
- 阅读完成；
- Reflection 完成；
- 思想沉淀；
- Memory 更新；
- Streak 延续；
- Achievement；
- 从 Agent Citation 跳回原文；
- Idea Timeline 展开。
不要用持续动画干扰阅读正文。
建议用于：
- 长按开始录音；
- Reflection 完成；
- 新 Achievement；
- 书籍导入完成；
- 关键卡片展开。
避免每次翻页震动。
首轮 Onboarding 不应超过三个目标：
- 导入第一本 EPUB；
- 配置 AI Provider；
- 完成第一次阅读 + Reflection。
建议流程：
欢迎
↓
“把一本你正在读的书带进来”
↓
Import EPUB
↓
配置 AI
↓
Test Connection
↓
打开书
↓
阅读
↓
结束 Session
↓
第一次 60 秒 Reflection
↓
Agent 第一次反馈
第一次感受到 Agent 价值的时间必须尽量短。
用户需要提供自己的 API Key。
Settings 至少包括：
- Provider；
- Base URL（高级）；
- API Key；
- Model；
- Test Connection；
- Streaming 开关（调试/兼容）；
- 删除 Key；
- 查看本次请求使用了哪些阅读数据。
V1 推荐先支持少量 Provider，做好而不是全兼容：
- OpenAI；
- Anthropic；
- Gemini；
- DeepSeek / OpenAI-compatible。
产品中不要提供绕过 App Store 规则的外部数字服务购买流程；BYOK 的 App Store 审核路径需要在 TestFlight/首发前独立验证。
- EPUB 原文件默认仅本地；
- Reading History 默认仅本地；
- Reflection 默认仅本地；
- Agent Memory 默认仅本地；
- Provider API Key 仅本地安全存储；
- 仅为完成当前 AI 请求发送“必要上下文”到用户选择的 Provider；
- 不把整本书默认上传给模型；
- 不上传与当前请求无关的历史。
每次模型请求：
- 本地检索；
- 选择必要证据；
- 本地组装上下文；
- 仅发送选中的文本；
- 记录本地 trace；
- UI 可解释“这次使用了哪些内容”。
提供：
- Export My Data；
- Delete Book & Index；
- Delete Reflection；
- Delete Memory；
- Reset Reader Profile；
- Delete All Local Data。
没有网络或没有 API Key 时，App 仍必须是一个完整 EPUB 阅读器。
可继续：
- 导入；
- 阅读；
- Highlight；
- Note；
- 阅读进度；
- 文字 Reflection；
- 查看历史。
不能进行：
- AI Feedback；
- AI Memory 提炼；
- 云端 ASR（如果当前 Transcription Provider 是云端）；
- Semantic Retrieval（若依赖远端 embedding）。
离线产生的数据待未来联网后再处理，但不能阻塞用户阅读。
由于 V1 local-first 且无自有服务器，产品指标首先应支持本地统计和 TestFlight 用户自愿诊断导出；后续是否加入遥测应单独做隐私决策。
Weekly Meaningful Reflections per Active Reader
不是阅读时长，不是 Agent 消息数量。
- 导入第一本书成功率；
- Provider 配置成功率；
- 首次打开书率；
- 首次完成 Reflection 率；
- Time to First Valuable Feedback。
- Reading Session → Reflection 转化率；
- Reflection 平均时长；
- 用户回答 Agent 追问比例；
- 每周有效 Reflection 数；
- Reflection 7 日留存；
- Thinking Streak 形成率。
用户可轻量反馈：
- 有启发；
- 一般；
- 没理解我；
- 太啰嗦；
- 太爱夸；
- 事实有误。
长期核心指标：
- Relevant Knowledge Gain；
- Follow-up Rate；
- Memory Correction Rate；
- Citation Open Rate；
- “这个回应值得我停下来想一想”的主观评分。
为了让 Agent 真正“有智慧”，建立固定 Evaluation Harness。
每个样本包含：
- 当前书上下文；
- 用户历史；
- 当前 Reflection；
- 可用检索证据；
- 目标反馈。
评价维度：
| 维度 | 说明 |
|---|---|
| 理解用户 | 是否抓住用户真正表达的意思 |
| 理解书籍 | 是否尊重当前上下文 |
| 知识准确 | 是否出现错误事实/伪引用 |
| 知识增量 | 是否真的增加了值得知道的内容 |
| 连接质量 | 跨书/跨概念连接是否自然且相关 |
| 个性化 | 是否合理使用用户历史 |
| 追问质量 | 是否真的推动继续思考 |
| 克制 | 是否避免无意义扩写 |
| 恭维控制 | 是否避免“无脑夸” |
| 可追溯性 | 关键陈述能否指向证据 |
| 用户自主 | 是否仍然让用户自己形成观点 |
任何 Agent Prompt / Model / Retrieval 大改，都应跑回归集。
竞品调研表明，“支持更多格式 / 更多云盘 / AI 摘要 / AI 翻译 / Mind Map”非常容易把产品拖进成熟 Reader 的功能军备竞赛。
为了保证首发质量，明确不做：
- PDF；
- OCR；
- 漫画；
- 在线书城；
- 盗版书源；
- DRM 绕过；
- 社交社区；
- 排行榜；
- 好友系统；
- 复杂知识图谱 UI；
- 多 Agent；
- Browser Automation；
- MCP 大生态；
- 自建账号系统；
- ReadLoop 自有推理服务器；
- 自动替用户生成完整读后感；
- 复杂间隔重复系统；
- “百万本书全文 RAG”。
目标：成为可用 EPUB Reader。
- Import；
- Library；
- Reader；
- Progress；
- Highlight；
- Note；
- Search。
目标：验证“读完后愿意输出”。
- Reading Session；
- Session Ending；
- Text Reflection；
- Voice Reflection；
- BYOK；
- Agent Feedback；
- Journal。
目标：验证“越用越懂我”。
- Long-term Memory；
- Reader Profile；
- “AI 眼中的我”；
- Evidence；
- Memory edit/delete；
- Personal Retrieval。
目标：达到可公开 TestFlight 水准。
- Today；
- Reading Streak；
- Thinking Streak；
- Achievement；
- Advanced animation；
- Haptics；
- Empty/error states；
- Agent evaluation。
首发标准：
- 阅读器可作为独立产品使用；
- Reflection Loop 稳定；
- 至少 3 个模型 Provider 稳定；
- API Key 安全；
- App 无 ReadLoop 后端依赖；
- Memory 可查看/修改/删除；
- AI 请求数据范围透明；
- 崩溃恢复；
- 隐私政策；
- EPUB 版权边界清晰；
- 完整无障碍和动态字体基础支持；
- App Review BYOK 路径已用真实构建验证。
- Curated Knowledge Pack；
- Public Domain RAG；
- Better Cross-book Connections；
- Weekly/Monthly Insight；
- Historical Recall。
- Intellectual Timeline；
- Concept/Idea Graph；
- Changed My Mind；
- Year in Ideas；
- Cross-device optional sync。
V1 不要求在所有维度击败成熟阅读器，但必须做到：
达到“用户愿意连续读一本完整 EPUB”的水平，而不是 Demo 水平。
比“打开独立 AI App 再聊”明显少步骤；结束阅读后 3 次交互以内进入语音/文字 Reflection。
一次高质量反馈应明显区别于通用 ChatGPT：
- 知道刚才读了什么；
- 知道用户自己的表达；
- 需要时能引用旧历史；
- 不默认总结；
- 不机械恭维；
- 有明确知识增量或思考推动。
用户使用一个月后，应开始出现：
“它真的记得我以前怎么想。”
而不仅是：
“它记得我读过哪些书。”
Thinking Streak 的存在感不能弱于 Reading Streak。
如果用户只用它读书而几乎不输出，产品核心循环尚未成立。
- 用户可以导入一份合法 EPUB 并开始阅读；
- 重启 App 后准确恢复位置；
- Highlight/Note 不丢失；
- Agent Citation 能跳回对应原文位置。
- 用户可在结束 Session 后 3 次点击以内开始语音或文字输出；
- 用户原始表达永久优先展示；
- AI 出错不影响 Reflection 保存；
- 无网络时可先完成 Reflection。
- Agent 能获得本次 Session 上下文；
- Agent 可检索当前书；
- Agent 可检索个人历史；
- 默认反馈不超过合理长度；
- 关键引用可以回到证据；
- Model Provider 可替换而不影响 Memory/Journal。
- 新 Memory 有 Evidence；
- 用户可查看、修改、删除；
- 删除原 Reflection 后，其派生 Memory 应重新标记或删除；
- 重建 Index 不应改变用户原始数据。
- API Key 不以明文形式出现在数据库/日志；
- 不存在 ReadLoop 自有推理后端；
- 模型请求仅直连用户选择的 Provider；
- 用户能清除所有本地数据。
ReadLoop 最终不是要证明：
AI 可以把一本书总结得多好。
也不是要证明：
我们可以再做一个功能更多的 EPUB Reader。
而是要证明：
AI 可以让一个人在读完之后多思考两分钟，并且这两分钟随着时间累积，逐渐形成一份真正属于自己的思想档案。
产品真正的长期资产应该按这个顺序理解：
原始 Reflection → Personal Intellectual Memory → Reader Agent Relationship → Thinking Habit
阅读器、RAG、向量检索、知识库、Streak、年度回顾都是为了强化这个闭环。
如果用户愿意一直读，却不愿意在这里表达和思考，ReadLoop 只是一个 Reader。
如果用户愿意持续 Reflection，并开始因为 Agent 记得“过去的自己”而回来，产品才真正成立。
以下偏差已在实现评审中接受并豁免。按 §0 约定先记录于本节，再做对应代码改动。每条包含偏差内容与豁免理由；后续版本如推翻某条豁免，应先修订本节再改代码。
§21.1–21.11 于 v0.3 记录；§21.12–21.13 为 v0.4 补记——两者对应的代码改动已先行落地，本次为追溯补录，不构成对 §0 顺序约定的豁免先例。
- 偏差：§14 列出「云端 ASR（如果当前 Transcription Provider 是云端）」的条件分支；V1 没有云端 ASR Provider，语音输入只使用 Apple 系统 SFSpeechRecognizer。
- 豁免理由：首发闭环够用，系统转写本地优先，与 §13 隐私默认一致。云端 ASR Provider 可选化移至 v2。
- 更正（v0.4）：原文「系统转写本地优先」在写下时与实现不符 —— 代码未设
requiresOnDeviceRecognition，即允许走 Apple 服务端。该句自 §21.14 起成立：默认已改为端上识别，音频与偏置文本均不出设备。 - 识别语言（2026-10-09 定案）：V1 固定
zh-CN，不提供语言设置，与 §3.1「中文读者」的定位一致。 已实测的代价记录在docs/testing/voice/2026-10-09-transcription-measurement.md的「已接受的取舍」：夹带英文词的中文可用（§21.15 的偏置可修正，0.250 → 0.083），整句英文不可用（用中文识别器解英文语音本身失败，加偏置无效，基线 0.208 → 加词后 0.146 仍是乱码）。读英文书并以英文表达的用户，语音反思产出不可用；这是已知取舍，不是疏漏。
- 偏差：F9 的 Journal 中 What I think 当前由 Agent 结构化整理（JournalStructuredParser）派生，实现尚无用户编辑入口。
- 修订（F9 语义澄清）：What I think 由 Agent 起草、用户可改，用户编辑优先。用户编辑入口（含 userEdited 标记与防静默覆盖）在 v0.5 交付；What I said 原始表达始终不可被 Agent 覆盖。
- 偏差：§12 设置项中的「Streaming 开关（调试/兼容）」不再提供。
- 豁免理由：流式非核心循环，回应长度由系统提示词约束；保留一个模拟流式的开关只会给用户错误预期。真流式输出（SSE）移至 v2。
- 偏差：Provider 设置不拉取服务商模型列表，由用户按服务商控制台手填 Model ID。
- 豁免理由：与 §12「做好而不是全兼容」一致；手填已可用，列表拉取属于接口兼容性投入，暂无必要。
- 偏差：Reading Session 不记录 agentDiscussionCount 之外的精细行为（滚动、选中、检索触发等）。
- 豁免理由：精细行为采集暂无对应产品决策，不做无用途的数据积累。agentDiscussionCount 自 v0.5 起真实累计（用户主动发起 Agent 讨论的次数）。
- 偏差：书架级搜索仅匹配书名与作者，不做书架级全文搜索；书内全文搜索已支持。
- 豁免理由：书架级全文搜索与书内搜索能力重复且成本高，不进首发。
- 偏差：语音 Reflection 的转写润色（TranscriptPolishService）作为默认可用的增强提供；原始转写文本永久保留、优先展示，且可随时切换回原始版本。
- 豁免理由：与 P2「User output before AI output」一致——originalText 是唯一事实源，润色只是不覆盖原文的展示层。
- 偏差：§18 建议原始音频可配置为「转录成功后删除 / 永久保存 / 每次询问」三种策略；V1 在用户主动开始录音后默认保存 AAC/M4A，用户可在录音前关闭。打开 Reflection 页面不会自动启动麦克风。
- 豁免理由：转写可能失败或误识别，默认保留原始音频让用户能够核验、回放和恢复；显式关闭仍提供隐私控制。默认行为比“每次询问”更少打扰，也比转写后静默删除更可靠。
- 补充：一次用户请求的多段续录在提交时合并为一个 M4A 文件；根 Reflection 与后续追问使用同等的音频能力。播放器从 M4A 解码生成 RMS 峰值波形作为进度与 seek 轨道，不保存原始 PCM。设置中提供「默认保存录音」偏好，数据与隐私页显示录音占用并支持清理全部录音。音频与派生波形会随对应消息、Reflection、书籍或「清除所有本地数据」一并删除。
- 偏差：v0.3 原视觉目标强调“温暖、有触感”，实现采用暖白底与鼠尾草绿主色；后续 UI 版本保留低噪极简方向，但取消强制黑白约束，改为中性基底 + 语义色 + 封面衍生色。
- 豁免理由：语言审计发现主流程存在
Reflection、Agent、Provider等工程词混用；单一绿色同时承担品牌、按钮、进度与成功反馈，导致中文社区用户难以建立稳定心智模型。极简首先约束元素数量与噪音，而不是禁止颜色；颜色必须语义化、低占用并服务于识别。 - 边界：阅读器继续保留独立的纸张白、暖色与深色阅读主题；高级设置保留技术原文并提供中文解释；本次不修改 Reflection、Thought、Question、Memory 本体的字段语义；固定概要作为派生数据由 §21.10 单独记录。
- 偏差：原 F6 允许用户显式请求 Agent 回应；想法页曾提供“有回应”筛选、手动“请 AI 回应”和独立“档案”入口。现在改为每条 Reflection 保存后自动进入第一次回应流程，想法页只保留单条记录流。
- 概要：第一次 Reflection 和第一次 Agent response 保存后自动生成一句固定概要。概要只用于卡片扫读和展开态识别，不替代用户原话、不参与后续对话，也不允许重写。
- 档案：Journal 数据继续保留并供“这次留下”、我的页和导出使用，但“档案”不再作为用户可见入口或 Tab 名称。
- 下一步：原 Today 的补写入口并入书架顶部；连续阅读与连续思考迁入我的页。
- 视觉：想法卡片使用中性实色表面；玻璃材质保留给导航栏、Tab、菜单、Sheet 和浮层，避免玻璃模糊长文本。
- 删除与恢复：用户删除 Reflection 时，概要、首次回应和后续对话按既有级联语义处理；缺少回应的历史记录在 Provider 可用时后台补齐，不要求用户逐条操作。
- 偏差：书架尝试使用程序化木质桌面和共享木质承托板表达现代拟物，但真机呈现与浅色数字壳层割裂，木质面块过于突兀。
- 结论：撤回木质桌面与木质承托板，恢复低噪中性基底。
- 保留：固定桌面几何、信息槽位、同级操作、删除抽象书签、封面/书脊统一尺度与 iOS 18 zoom transition。
- 边界：后续物理感优先通过留白、固定位置、轻阴影和克制动效表达，不以完整拟物材质覆盖书架内容。
- 偏差：F10 的 Memory 五类分类学（Episodic / Semantic / Preference / Open Question / Profile Trait）与
userEdited字段退役。v26 迁移v26_retire_legacy_memories在回填后drop了memories表；BrainItemKind现仅thought/question/memory（Sources/BrainCore/BrainItem.swift:18-20）。 - 替代：单一 Memory 对象 + 三条正交轴——
origin（userExplicit / agentInferred / derivedFromThought）、state（active / needsReview / superseded / forgotten）、confidence（high / medium / low）。原五类把「记忆的内容性质」与「记忆的获得方式」压进同一维度；收敛后两者正交，获得方式由origin承担，可信度由confidence承担，生命周理由state承担。 userEdited的替代：用户编辑使origin变为userExplicit，同时写入brainItemRevisions保留改写前陈述（docs/brain.md§10），因此「用户改过」不再是独立布尔字段，而是可由 origin 与修订历史共同判定，且比原字段多保留了改写前的原文。- 连带的 F11 偏差：F11 的 Reader Profile 聚合实体（Profile Trait）随分类学一并退役，无独立画像页；「AI 眼中的我」由 memory 列表承载，实现中文案为「AI 记住的我」。F11 要求的每条操作（准确 / 不准确 / 修改 / 忘记 / 查看依据）在单条 memory 上均已实现，与 §21.9 的语言方向一致。
- 回填保真度（已知损失）：回填把所有 kind 折叠为
memory，status与confidence按确定性映射转换，但userEdited与evidenceIDsJSON未搬运，且origin统一写为agentInferred（Sources/Persistence/AppDatabase.swift:826-841）。即迁移前已被用户编辑过的旧记忆，迁移后不再携带该标记。 - 未覆盖项：P7 的「禁止某些内容进入长期记忆」仍无实现。当前缓解为 agent 推断产生的 memory 默认落在
needsReview待用户确认，且forgotten/superseded不参与检索；此项不视为已豁免，计入首发后待办。 - 豁免理由：PRD F10 写于 Brain 领域模型之前。
docs/brain.md§2–§3 给出的强类型 tagged union 能表达原分类学的全部语义，且消除了「kind 与 confidence 可矛盾」的非法状态；同一模型同时服务 UI、Agent Context 与长期记忆三处消费方，优于在旧五类上叠加修补。 - 依据：
docs/brain.md§2 Memory、§3 Domain Model、§10 Revision / Evolution。
- 偏差：实现了 PRD 未列入版本路线 §18 的整个里程碑（Phase 12–19：Brain Domain / UI / Evidence / Retriever / Agent Bridge / Projection / Revision / Observability），并在 1.0 首发之前完成。§18 的 v1.0 与 v1.x 之间无此条目；§8 中与之最接近的是 P2 的 Personal Intellectual Graph，但范围与实现方式（LLM 提议、代码执行、Evidence 为事实）均已超出其描述。
- 豁免理由：长期记忆是 P9 认定的产品护城河，而 F10 的记忆模型在首发前即已暴露语义不足（见 §21.12）；与其带着已知会重构的模型首发，不如在首发前一次收敛到位。Brain 为纯增量模块（BrainCore 不 import ReaderAgent），且维护路径异步、不阻塞 ReaderAgent，未挤占首发关键路径。
- 边界：本里程碑不改变 P1–P9 任何产品不变量；Brain 页面的「继续想想」等入口属既有 Reflection 链路的复用，不引入新的一级入口。
- 依据：
docs/brain.md§20 阶段划分；.planning/ROADMAP.mdv1.1 Personal Brain。
- 事实：语音识别请求携带
contextualStrings（当前为书名与作者），且requiresOnDeviceRecognition未设置 —— 即允许走 Apple 服务端。因此音频与偏置文本会离开设备，而 §13.1 只说「发送必要上下文到用户选择的 Provider」，Apple 不在其中；隐私政策原文也只描述 App 保留了什么，未披露识别请求本身外发。 - 连带：§21.1 的豁免理由写「系统转写本地优先，与 §13 隐私默认一致」。该句与实现不符，本次一并修正。
- 决定（依据 2026-10-09 的实机对比测量，见
docs/testing/voice/2026-10-09-transcription-measurement.md）：默认改为端上识别（requiresOnDeviceRecognition = true）。五段真人素材上，端上与服务端的均值 CER 为 0.249 与 0.244（无偏置）、0.149 与 0.149（带偏置），代价在这批素材上测不出来；且contextualStrings的收益在端上完整保留。改动后识别全程不出设备，§13 的承诺与隐私政策无需新增外发披露，§21.1 的措辞随之成立。 - 回退策略（已定案）：强制端上后，若目标 locale 的端上模型未安装，识别直接失败并给出可行动的提示，不退回服务端。理由：静默上传正是本配置要消除的行为；退回服务端会让外发路径以「仅在出错时」的形式悄悄复活，而用户恰恰不会在这时预期它。
- 端上模型由系统键盘与听写设置决定，App 无法触发下载：需要该语言+地区的键盘已安装、听写已启用、且该语言的听写包已下载。因此提示文案以「设置 → 通用 → 键盘 → 听写」为主，而不是让用户干等自动下载。
- 界面处置：模型不可用时不渲染麦克风（避免一个点了才报错的按钮），但在其原位置保留一句说明与可行动路径；模型装上后自动恢复（每次打开界面重新查询，不缓存）。明确不做静默隐藏 —— 模型缺失是用户可自行修复的一次性设置，静默会把「暂时不可用」变成「永久不存在」，且实现成本与保留一句说明完全相同。
- 识别期兜底：
supportsOnDeviceRecognition是能力检查而非已安装检查，可能返回 true 而资源仍缺失。这类失败以kAFAssistantErrorDomain1101 到达，已映射到同一条可行动文案；且仅在确实要求端上时才归因于模型，否则会把一个有服务端兜底的失败错报成模型问题。 - 实测（2026-10-09，iOS 27.0 / iPhone18,3）：zh-CN 与 en-US 有端上模型，ja-JP 与 zh-TW 没有。因此模型缺失是真实可达状态，不是理论边界。
- 已知未消除的风险：端上模型按需求下载而触发下载通常依赖一次服务端识别，硬失败可能形成死锁。zh-CN 在实测设备上已存在，目标场景不受影响；若出现真实死锁，再评估「用户显式授权后允许一次服务端识别以触发下载」—— 那需要新的披露，不得默认发生。
- 长期方向：iOS 26 的
SpeechAnalyzer用AssetInventory由 App 管理模型下载，不存在该死锁。部署目标为 iOS 18，届时需#available分支，不在本次范围内。
- 段落术语（2026-10-09 落地）：把阅读内容纳入
contextualStrings时必须先满足本条，否则会显著放大随请求外发的文本量 —— 端上默认即是该前置条件。实际实现见 §21.15。
- 动机：实测确认识别的主要失败是拉丁词被解成中文同音字（
incentive→intent、Keynesian→Kenyon），而contextualStrings能修正这类错误 —— 但只对该词已在列表内时有效。因此「词从哪来」是关键，答案只能是读者正在看的内容。 - 输入来源（经核实，非设计选择）：本次 Session 的高亮文本。
- 原本设想的「当前阅读段落」不存在：Readium 仅在选区时产生
Locator.Text，导航路径不产生，故阅读位置 locator 的textBefore/textHighlight/textAfter全为 nil。 - Readium 实际为选区提供前后各 200 字符的上下文（
selection.js的snippetLength），但 App 的rangeLocator只保留highlight，主动丢弃了上下文。因此可用文本 = 选区本身。 - 高亮文本对术语抽取反而是更好的输入：它是用户亲自认定值得记的段落，短且术语密度高。
- 原本设想的「当前阅读段落」不存在：Readium 仅在选区时产生
- 抽取规则：仅拉丁词串（长度 ≥ 3，保留词内连字符与撇号，剔除纯数字）。中文术语不抽取 —— 需要分词，而朴素的字串扫描会返回大半句话，既挤占上限又不增加价值；中文专名由书名与作者覆盖。
- 上限与顺序：总计 40 条（实测 22 条与 4 条无差异，40 留余量且不进入未测的 22–100 区间）。书名/作者固定在前，段落术语在后，保证长高亮列表无法挤出已实测有效的条目。
- 覆盖范围：阅读结束编辑器与「继续想想」的上下文反思传入高亮文本；追问输入条仍只有书名与作者 —— 它是续写而非首次表达，且为其铺管线会波及四处
SessionReflectionModel构造点。 - 依据：
docs/testing/voice/2026-10-09-transcription-measurement.md（三轮单变量对照 + 五段真人素材）。 - 明确未做：中文术语抽取、全书范围高亮、笔记正文（用户自己写的字，隐私性质与书籍文本不同，需单独评估）。
- 待办：AI 生成的高亮（若未来引入）是否纳入偏置 —— 那是派生数据，纳入等于让模型选择自己看到的上下文，需单独决策。