Claude Code Tools 研究系列（五）—— Read：感知外部世界的唯一合规通道
内容提要
Read是Claude Code中感知外部世界的唯一合规通道，通过绝对路径读取文件内容，支持分页（默认2000行）、图片、PDF和Jupyter notebook等多模态输入。它建立行号坐标系，为Edit提供感知承诺，并强调按需读取、避免重复验证，是执行原语链条中承上启下的关键环节。
延伸解读
为什么 Read 是“唯一合规通道”
文章强调，Claude 对项目的理解只能来自 Read，否则只能依赖过时的训练记忆、用户粘贴的片段或幻觉。这意味着 Read 不仅是读取工具，更是防止 AI 胡编乱造的关键屏障。对用户而言，理解这一点有助于明白：当 Claude 需要修改文件时，必须先通过 Read 获取真实内容，否则后续的 Edit 可能基于错误假设，导致不可预期的改动。
分页与多模态：设计背后的考量
Read 默认只读 2000 行，并支持 offset/limit 分页，这是为了避免一次性占用过多上下文。同时，图片、PDF、Jupyter notebook 都通过 Read 统一处理，PDF 超过 10 页必须指定页码范围。这些设计体现了“按需读取”的原则，防止大文件拖垮模型性能。用户在使用时，应理解这些限制，避免要求 Claude 读取超大文件或未指定页面的 PDF，否则可能失败。
行号前缀：既是坐标也是陷阱
Read 返回的内容每行带有行号和 tab 前缀，这为 Claude 提供了精确定位的能力，但同时也为后续 Edit 埋下陷阱——前缀并非文件真实内容，Edit 时必须剥离。文章指出，这是 Read 与 Edit 协作的关键点。用户应意识到，Claude 在编辑时会处理这些前缀，但若用户手动复制内容，需注意不要包含行号，以免造成混淆。
反浪费原则：不要重复验证
官方明确要求 Claude 不要重新读取刚编辑过的文件来验证，因为 harness 已追踪状态，Edit 成功即表示改动生效。这打破了人类程序员“改完要检查”的直觉，旨在提高效率。用户应理解，Claude 的编辑操作是可靠的，无需反复确认，但若用户自己需要验证，仍可手动查看文件。
Q&A
Claude Code 中 Read 工具的主要作用是什么？
Read 是 Claude Code 中用于读取文件内容的工具，它通过绝对路径读取文件，返回文件内容，并支持分页、图片、PDF 和 Jupyter notebook 等多模态输入。它的核心作用是让 Claude 感知外部世界的真实状态，避免依赖训练记忆或幻觉，为后续的 Edit/Write 操作建立感知承诺。
Read 工具如何支持大文件读取？
Read 工具通过分页机制支持大文件读取，默认只读取前 2000 行，可以通过 offset 和 limit 参数指定读取的行范围，例如 offset: 2000, limit: 1000 可以读取第 2001 到 3000 行。这样可以避免一次性将大文件全部读入上下文，防止上下文溢出。
Read 工具支持哪些多模态输入？
Read 工具支持文本、图片（PNG/JPG/GIF/WebP）、PDF 和 Jupyter notebook。图片会以视觉方式呈现给 Claude，PDF 支持分页读取（超过 10 页必须指定 pages 参数，每次最多 20 页），Jupyter notebook 会返回所有 cell 的代码、输出和 Markdown。
为什么 Read 工具要求使用绝对路径？
因为 Claude Code 是跨会话、跨 CWD 的 agent，相对路径在不同上下文下会产生歧义。强制使用绝对路径可以消除对当前工作目录的依赖，确保每次读取都是自解释的，避免路径解析错误。
Read 工具返回的文件内容为什么带有行号前缀？
行号前缀有两个作用：一是为 Claude 提供坐标系统，使其能精确定位代码位置（如“第 4 行的 bug”）；二是为 Edit 工具制造陷阱，因为行号前缀不是文件真实内容，Edit 时必须剥离，这有助于确保 Edit 操作的准确性。
在什么情况下不应该使用 Read 工具？
不应该在以下情况使用 Read：1. 刚刚 Edit 过的文件想验证一下（因为 harness 已追踪状态，重复读取是浪费）；2. 列目录内容（应使用 Glob 或 bash ls）；3. 搜索文件中的关键词（应使用 Grep）；4. 凭幻觉验证自己上一步的输出（如果 Edit/Write 成功，无需回头怀疑）。
Read 工具与 Edit 工具是如何协作的？
Read 工具为 Edit 建立感知承诺：Read 会记录 Claude 读取过的文件，当 Claude 调用 Edit 时，runtime 会检查该记录，如果文件未被读取过，Edit 会报错。这确保了 Edit 基于真实状态进行修改，形成“感知承诺”的信任链。
