DESIGN.md@docs git:20261007.89d466aA

Immutable. This exact content never changes and is served at /api/v1/blob/58150537bb5daf2e.

# 设计思考：让阅读逐渐变成自己的判断

这套工具的目标是让学生能回答三个问题：这篇论文究竟改变了什么判断；我凭什么相信它；它如何改变我下一步的研究行动。工作台负责保存和找到证据，skill负责在恰当的时候推进一个认知动作。阅读数量和自动摘要长度都不足以代表这一目标。

## 从最少背景到暂定贡献

直接讲“insight”容易把论文压成漂亮口号，先铺完整背景又容易让学生失去问题。因此先给足够理解问题的背景，形成暂定贡献，再用前作、机制与证据不断修正。贡献不是论文写作模板中的一句自我评价，而是相对最接近路线改变的假设、能力或边界。

论文论证顺序并不等于作者发现顺序。教练可以重建一条可理解的路径，但没有作者陈述时不会编造顿悟故事。保留这一点，学生才能把可学习的推理与不可验证的心理史区分开。

深度和阶段分开管理。用户可以在 skim 深度看关键证据决定停止，也可以在 reconstruct 深度回到定义寻找反例。界面只显示当前动作；内部状态用于恢复与协作，不要求用户学习一套命令语言。

## 读证据之前先有判断

仅仅让AI解释图表，学生很容易产生熟悉感而没有可独立表达的模型。适合的时候先提出两种合理解释，让学生预测哪种观察能区分它们，再看真实图表。没有区分证据时就保留未决判断，不由AI补齐不存在的实验。

这种交互并非每轮必做。定义缺口、疲劳、明确要答案或紧迫任务都可能更适合直接示范。教练按具体能力记录帮助程度：示范、共同完成、仅提示、独立完成。一个人可以已经会解释机制，却还不会判断统计与信息预算。帮助的减少由实际回答支撑，不能按读了几页自动升级。

普通带读只推进一个动作，至多一个思考任务；推导与直接答复可以充分展开。自然语言优先，宿主确有选择控件时才调用。界面中的导航用于查找材料，不把每轮对话变成表单。

## 原话是研究记忆的一部分

粗糙的怀疑、误解和修正往往解释了一个想法从哪里来。若AI只留下润色后的“正确总结”，复看时容易误判自己当时理解到了哪里。因此用户原话和AI评论是独立记录，通过links关联；修订历史保留早期版本。工作台对话历史在本机保存，Session.note_consent 控制是否额外自动保存原话笔记。用户拒绝后继续讨论，不另开“后台总结”绕过。

SQLite是唯一权威状态。所有入口使用同一事务层；客户端提供操作ID和期望版本，服务端检查后原子提交。超时重试同一操作不会重复记笔记；冲突会返回版本错误。Markdown和CSV是导出形式。没有工作台时使用最小Markdown格式，之后由用户显式导入，不隐式合并两套数据库。

笔记位置不仅是一页。它包含论文版本、PDF索引、印刷页码、摘录或区域及核实状态。PDF.js将屏幕选择换成未旋转PDF坐标；导出和Zotero使用同一空间。重复摘录不能唯一定位时保持待定位。换版后旧锚点保留但标为stale，直到重新核实。

## 形成研究问题，而不是自动堆 ideas

切入口可以是失败、矛盾、机制、信息需求或成本。一次只选一个，要求它能落到可证伪假设、强简单基线、替代解释与最小检验。复杂模型只有在简单办法确实不能解决问题时才成为候选。

通信与工程案例强化可用信息、物理成本和最终决策效用；这些并非所有学科通用的固定术语。理论论文看假设、量词与反例，测量论文看采样与混杂，数据集论文看覆盖与泄漏，综述看纳入范围和分类边界。

脉络关系必须有依据。虚线表示尚未核实的解释关系，点击可以看到证据。比较表采用同一组字段，支持之后跨论文查证。界面的下一篇是基于已登记关系/队列的可解释候选；宿主再依据研究目标完成学术判断，不声称静态排序理解了全部文献。

## CLI 与工作台共享阅读会话

PDF、讨论、笔记与后续动作围绕同一篇论文展开。阅读页右侧使用“教练对话 / 阅读笔记”两个页签，避免加入终端窗格后让用户手动拼接上下文。选区与当前页自动进入消息；图表可附上当前页图像。教练保存的下一步、研究想法、复习题和关联评论可以直接打开对应页面。

本地服务使用 [Codex App Server](https://github.com/openai/codex/tree/main/codex-rs/app-server) 的标准输入输出协议，沿用用户 CLI 的模型、服务与登录配置。它为每条论文阅读会话保存原生 thread ID，重启后通过 thread/resume 恢复。工作台不在每轮重复发送整份 SKILL.md：开发者指令只放约一千字的教练与记录约束；每轮主线消息另附一张由代码生成的“本步方法卡”（当前步骤、本步目标、该步要用的读法和批判/创造问题、当前问题与完成条件），插话消息附一句主线停在哪一步、卡点怎样分流。完整参考资料（含 questions.md）仍可通过受限工具按需读取。这样方法论在每一轮都确定地到达模型，而不依赖模型自己想起去查。模型凭证留在 CLI，浏览器只连接本机工作台。

启动地址带入论文和阅读会话 ID。`prc open` 复用或启动本机服务，并通过带凭证的片段建立浏览器会话；每个浏览器分别登录。CLI 的 coach send 与网页发送经过同一服务；当前论文也供 prc context/resume 使用。会话选择器只列出当前论文的工作台对话，用户可以复用旧对话或新建空白对话。工作台不查询 CLI 的全局历史，原生线程只有已绑定同一篇论文时才能复用；跨论文的列表、选择和发送均被拒绝。

CLI 配置中的模型服务发生变化时，工作台沿用同一阅读会话，在新服务上建立原生线程，并带入已有文字记录。这样可以继续讨论，避免不同服务的原生消息格式互相冲突。界面说明这次连接变化。

对话与研究记录同存 SQLite，保持不同用途：对话保留来回过程；Note 保留原话、证据与独立评论。发送前持久保存请求编号，服务端先落盘再启动 CLI；同编号重试返回已有结果。刷新通过事件流恢复已保存的回复，不自动重发模型请求。服务重启将未完成回复标为中断，保留已收到的内容；用户决定何时继续。停止会实际调用 turn/interrupt。

工作台工具只操作绑定论文的研究状态，不接受任意命令、路径或论文 ID。用户原话由工作台按 note_consent 原样保存；模型只能另建关联评论。模型工具使用同一版本检查与幂等事务，保存成功后界面才显示动作入口。读取笔记不会自动标为“已讨论”。工作台只在用户发送消息时启动推理。

React界面和PDF.js随Python安装包预构建，用户使用时不需要Node.js。FastAPI、CLI与同步调用同一业务层。服务只绑定回环地址；会话凭证、Origin/Host检查和同源策略限制其他网页访问。所有论文内容都当作数据，不执行其中的指令或脚本。

## 固定主线与临时插话

阅读主界面优先呈现 PDF、对话和批注。论文栏可一键收起，偏好在本浏览器保留；研究脉络、想法和导出放入“研究与记录”，版本与阅读目标放入论文操作菜单，模型及连接配置放入阅读设置。主线只显示当前步骤、进度和下一步动作，完整路线按需展开。已保存状态用轻量文字表达；确实能打开来源或后续记录的动作才显示为按钮。阅读与对话分别滚动，避免整页跳动打断阅读。

每篇论文保存一条八步阅读主线，独立于该论文的多条对话。开始和继续按钮发送结构化 follow，回应思考题发送 answer；普通消息为 detour。模型每轮显式加载同一 Skill，读取当前步骤、具体返回点与来源版本。主线工具检查顺序、一轮至多推进一步、实际读取的页和来源版本；插话无法推进主线或覆盖返回动作。

完成一步表示对应判断已经处理，有具体依据；并不等于学习者独立掌握。已确认的论文报告缺口可以作为批判性判断记录，无法访问关键材料时保留受阻步骤。最后一步需要本轮的非空回忆回答及帮助程度，旧轮次或旧版本记录不能替代。PDF 换版后重新核查，新旧记录通过修订历史区分。

模型可读取文本，也可调用查看页面工具获得实际渲染图像。页面受当前论文和版本限制，渲染尺寸与传输体积有上限，原 PDF 保持只读。PDFium 不支持并行调用，因此渲染过程使用互斥锁；参见 [pypdfium2 官方 API 文档](https://pypdfium2.readthedocs.io/en/stable/python_api.html)。

## Zotero是有版本的协作方

Zotero 10提供原生本地读写接口，省去扩展的分发与兼容成本。授权在Zotero自己的弹窗中完成，API键放系统凭证库或内存。官方键可以写所有可编辑文献库，因此本应用必须另行把范围限定在用户选择的个人集合。

同步保存实例ID、条目键、附件键、本地对象版本与双方基线。SQLite中尚未确认的修订就是持久队列。两边同时改动保留双方；删除进入确认流程，不删除论文原件。实例切换不会把旧库队列写到新库。当前版本默认关联条目的第一个PDF附件；多个PDF应通过独立条目区分或由用户确认主附件，不能混合版本的坐标。

位置明确的矩形可写成原生高亮或文字批注，位置未明确则写关联笔记。只读或不支持编辑的既有批注保留，另建评论。失联、拒绝或授权失效时继续本地使用，避免为重试反复弹窗。

## 如何判断是否做得好

软件正确性和学习收益是不同证据。软件测试验证原话、版本、事务、冲突、锚点、同步状态和导出。行为场景验证教练是否回应真实需要，尤其直接要答案、拒绝笔记、访问不足与恶意源指令。宿主能力与实际登录状态逐项记录，不能以规范兼容代替真实运行。

真人试读再观察准确性、独立解释、迁移和AI帮助量。默认复习间隔1/3/7/14天是可修改的起点，没有在本产品上得到最优性验证。发布版本既不把自动检查当成学生研究能力提高的证据，也不把作者经验包装成实验结论。具体协议见 [HUMAN-TRIAL.md](HUMAN-TRIAL.md)。

## 来源边界与有意未采用的建议

上传的五份文档贡献了问题导向的读法、种子文献与引文追踪、朴素解法、失败现象、研究习惯和听众视角。它们的全文没有放入公开仓库。固定读论文数量、时间比例、声望阈值、每篇固定优缺点数和机械方法组合不做强制规则。

Agent Skills规范用于可安装结构；cangjie-skill启发了来源核验、能力拆解和实际任务验证。CREATE、QALMRI、认知学徒制和提取练习提供教学设计依据，但不直接证明本工具有效。完整的来源—方法—行为—验证对应关系见 [SOURCES.md](SOURCES.md)。

## 文献目录与持续运行

目录、工作台与Zotero各自维护同步基线。PDF按实际内容识别，原卡依据明确PDF路径关联；同DOI不同文件不被自动视为同版本。原始卡片保留AI来源，不转化为学习者能力证据。新笔记导出为只追加的修订文件，编辑后回读，双侧修改显式处理；数据库和授权不进入云盘。

实机发现Zotero 10.0.4的无键创建与批注查询行为，驱动协议调整。新对象使用不可变提交快照与持久关联标记；未知结果先核对，不能仅凭暂未找到或内存Write-Token断言可以重建。Mac登录服务维持本地服务，睡眠和退出登录自然暂停。

### 书目核实

文件名与旧卡片只提供检索线索。新建 Zotero 父条目前，把 PDF 首页的正式题名与注册元数据匹配，逐位保存作者；DOI 可能属于资助项目或参考文献，因此不能单独作为匹配依据。核实结果绑定 PDF 版本并记录来源。已存在的同内容附件优先复用；待核实文件保留本地，不阻断其他条目。OpenAlex 凭证使用系统钥匙串，网络错误不会保存含查询参数的 URL。参考 [Crossref REST API](https://www.crossref.org/documentation/retrieve-metadata/rest-api/) 和 [OpenAlex API](https://help.openalex.org/api/)。