第 21 章：read 的设计 — 为什么不是简单的 cat

来源：《pi 的设计艺术》第 21 章：read 的设计 — 为什么不是简单的 cat

阅读日期：2026-09-14。书中版本基线：基于 v0.66.0，书中称已对照 v0.82.1。 本条为原创阅读笔记，未独立核验 pi 源码。

设计问题与机制

读文件工具必须控制上下文规模，并保留继续探索的路径。书中以从 1 开始的行偏移和行数参数分页，另以 2000 行与 50 KiB 两个上限限制输出；结果记录截断原因与续读位置。首行已超限时给出替代读取提示，而不把残缺长行冒充完整内容。

图片按类型检测分流，可缩放后返回图像内容；失败有可见说明。底层读操作通过接口替换，文本和图片是主要支持边界。模型接收的内容限制与 TUI 的折叠显示属于两层决策。

取舍与版本边界

分页增加调用次数，图片缩放可能损失细节；资源控制换来可预测的阅读预算。后续版本分别调整了资源文件单行折叠、错误不做代码高亮等行为，不能把早期预览行为写成固定接口。PDF、Notebook 的专用解析不在这里完成。

工程应用检查（独立推导）

知识库读取可以返回正文、是否完整、下一偏移和版本号，让“完整吸收”有覆盖证据。检查空文件、超长单行、中文多字节内容、图片转换失败；需要细字时提供原图检查路径。UI 展开只改变显示，不应被当作模型已经读到更多内容。