DESIGN.md@docs git:20260930.4c29f21A

Immutable. This exact content never changes and is served at /api/v1/blob/35ed58b803de30c1.

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

这套工具的目标是让学生能回答三个问题：这篇论文究竟改变了什么判断；我凭什么相信它；它如何改变我下一步的研究行动。工作台负责保存和找到证据，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 类型输入显式加载打包的 SKILL.md；所需教练与记录约束同时作为开发者指令提供，其他 skill 参考资料通过受限工具读取。模型凭证留在 CLI，浏览器只连接本机工作台。

启动地址带入论文 ID，`prc coach connect` 建立论文与阅读会话的持久绑定。CLI 的 coach send 与网页发送经过同一服务；当前论文也供 prc context/resume 使用。已有本机 Codex 对话可以接入最近文字历史，形成加载当前 skill 的阅读分支；原对话不被改动，历史工具调用不重放。

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

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

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

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

## 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/)。