cheez-read

cheez-read

后端检测

根据读取需求选择后端，优先选择代码智能后端，而非基础工具；模型调优倾向于使用宿主的 Read/Glob，但 tilth 和 LSP 能返回结构化信息（大纲、锚点、符号表、令牌预算），而普通读取无法提供这些信息：

1. tilth MCP： 文件/范围读取、仓库感知的列表、结构大纲、令牌估算和编辑锚点（重构前使用 tilth_read、tilth_list、tilth_deps）。
2. LSP： 符号表、定义、悬停信息或类型结构化读取。
3. 原生有界读取/列表（回退方案）： 精确文件、显示范围、目录列表或快照标签读取——仅在没有代码智能后端能满足需求形态，且宿主能提供最新内容以及行/快照上下文时使用。

普通 shell 查看工具（cat、head、tail、ls、find）不是源代码后端；仅将它们用于非代码路径或数据/日志检查。

---

示例

“显示 src/auth.ts”

tilth_read(paths: ["src/auth.ts"])

小文件会返回完整内容和标题（# src/auth.ts (258 lines, ~3.4k tokens) [full]）；大文件会自动返回结构大纲。

“按符号名称读取 handleAuth 函数”

tilth_read(paths: ["src/auth.ts#handleAuth"])

#symbol_name 后缀会解析为该符号对应的行范围。当你知道名称但不知道行号时使用此方法。

“编辑前获取大型文件的精简大纲”

tilth_read(paths: ["src/auth.ts"], mode: "stripped")

mode:stripped 会返回删除普通注释和调试日志后的完整文件——适合先了解结构，再决定要完整读取哪些部分。精简读取不带编辑标签，也无法通过 tilth_write 往返写回。

“读取 src/auth.ts 第 44–89 行，以获取编辑锚点”

tilth_read(paths: ["src/auth.ts#44-89"])

[src/auth.ts#b2c4]
44:export function handleAuth(req, res, next) {
45:  const token = req.headers.authorization?.split(' ')[1];
...
89:}

[path#TAG] 标题会将编号行绑定到文件的当前内容——将 b2c4 复制到 cheez-write 的 tag 中，并在其 ops 里引用第 44–89 行。

“列出 src/handlers/ 下的所有 TypeScript 文件”

tilth_list(patterns: ["*.ts"], scope: "src/handlers/")

---

核心原则：聪明地读取，而不是读取更多

读取后端会自动调整读取方式：小文件（< ~6000 个令牌）返回完整内容，大文件返回结构大纲，二进制/生成文件会被跳过（tilth 会按需执行）。通过行范围或符号深入读取大型文件；如果后端提供精简/概览模式，在获取带锚点的内容之前先使用这些模式。

---

适用范围：何时使用代码读取后端，何时不使用

cheez-read 负责受版本控制且可解析语言中的源代码文件——即之后可能需要符号导航、编辑锚点或 cheez-write 编辑的任何文件。智能大纲、编辑模式锚点、会话去重以及遵循 .gitignore 的列表功能都属于该后端。

适用范围与内容时效性

使用限定于当前仓库且能读取磁盘最新内容的后端。Tilth 会按需遍历工作树，使用 Tree-sitter 解析文件，并遵循 .gitignore；宿主原生后端要替代它，必须提供同等的内容时效性和有界读取能力。

实际影响：

• 优先选择能读取当前保存内容而非过时索引的后端。
• 除非后端明确支持相应范围，否则不要将仓库范围的后端用于同级工作树、系统路径或依赖缓存。
• 对于多仓库读取，调用工作流技能必须在进入 cheez-read 之前按仓库进行路由。

如需了解何时其他工具比 cheez-read 更合适，请参阅 references/routing.md。

---

编辑标签

编辑模式（非精简）读取会在 N:content 编号行上方输出 [path#TAG] 标题；精简读取不带标签标题，也无法往返写入。编辑前必须先读取以获取当前标签——将 4 位十六进制 TAG 原样复制到 cheez-write 的 tag 中，该标签会将编辑绑定到你读取的内容：内容发生偏移时，写入会进行三方合并或安全拒绝，绝不会盲目应用。切勿自行编造标签。

---

目录列表

通过支持仓库感知的列表后端列出目录，而不是使用 ls、find、pwd 或 Glob。使用 tilth：

tilth_list(patterns: ["**/*.ts"], scope: "src/")

输出：

src/auth.ts  (~3.4k tokens)
src/routes.ts  (~2.1k tokens)
src/middleware.ts  (~1.8k tokens)

Token 估算有助于判断哪些内容需要完整读取，哪些只需查看大纲。若 tilth 不可用，但 harness 提供了最新的仓库感知列表，则改用原生的列表/Glob 后端。

---

tilth_deps — 影响范围检查

tilth_deps(path: "src/auth.ts")

仅在重构之前使用（重命名、更改签名、移除）。关于输出格式以及文件与符号的区别，请参阅 cheez-search 中的共享参考： ../cheez-search/references/tilth-deps.md。

---

禁止事项

• 禁止使用 cat / head / tail / less / more / bat 查看代码——请使用具备新鲜度感知能力的读取后端。哈希锚点以及大纲与完整内容之间的 Token 预算功能只能通过后端使用。
• 禁止使用 ls / tree / eza / find / fd 枚举代码文件——请使用具备仓库感知能力的列表后端。Token 估算和 .gitignore 过滤功能只能通过后端使用。
• 除非普通主机 Read 或 Glob 是 harness 的原生新鲜度感知后端，否则禁止在代码路径上使用它们——否则会绕过锚点和结构上下文。
• 禁止重新读取之前已显示的文件——请引用先前的读取结果。
• 禁止使用它来运行代码或测试——请使用项目的构建/测试技能。
• 禁止使用它来提交或发布——请使用 /plate。
• 禁止忽略 [path#TAG] 标头——编辑时必须使用该标签。