cheez-search

cheez-search

后端约定：使用语义代码搜索后端，而非盲目文本搜索。选择能回答问题的最精简工具。

后端检测

根据问题类型选择后端：

1. **类型相关问题优先使用 LSP：**跨导入的定义、处理遮蔽和重新导出的引用、悬停／类型信息、实现、重命名规划，以及服务器已知的代码操作。
2. **语法形态优先使用 AST 搜索／sg：**带有元变量的结构化模式，以及重复的、符合语法形态的代码转换。
3. **广泛的源码搜索优先使用 tilth MCP：**在一次全新的仓库扫描中查找符号、调用方、导入、内容、限定范围的正则表达式，以及依赖关系／影响范围上下文。

**注意：**每个 tilth 工具都需要 cwd——也就是你的绝对检出目录（服务器自身的 cwd 在启动时即固定）。在 Claude Code 中，钩子会自动注入 cwd；不要设置它。在没有钩子的运行环境中，请显式传入 cwd，以便正确解析相对路径和范围。没有 root 参数。

---

示例

“handleAuth 定义在哪里？”

tilth_search(queries: [{query: "handleAuth"}], scope: "src/")

# Search: "handleAuth" in src/ — 6 matches (2 definitions, 4 usages)

## src/auth.ts:44-89 [definition]
→ [44-89]  export fn handleAuth(req, res, next)
## src/routes/api.ts:34 [usage]
→ [34]   router.use('/api/protected/*', handleAuth);

[definition] 标签即可回答问题；同时也会免费附带用法。

“哪些地方调用了 validateToken？”

tilth_search(queries: [{query: "validateToken", kind: "callers"}])

# Callers: "validateToken" — 3 call sites

## src/auth.ts:62 [usage] in handleAuth
→ [62]   const claims = validateToken(token);

## src/middleware/admin.ts:18 [usage] in requireAdmin
→ [18]   if (!validateToken(req.headers.authorization)) return next(403);

kind: "callers" 会过滤掉注释和字符串——只保留真实的调用点。

“查找任何提到重试的 TODO”

tilth_search(queries: [{query: "TODO.*retry", kind: "regex"}], scope: "src/")

跨内容进行模式匹配时使用 kind: "regex"；限制搜索范围以 降低成本。

---

范围：何时使用代码搜索后端，何时不使用

cheez-search 负责已跟踪、可解析源文件中的代码（Rust、TypeScript/TSX/JS、Python、Go、Java、Scala、C/C++、Ruby、PHP、C#、Swift）。符号类查询、调用方、内容、限定范围的正则表达式、AST 形态模式和类型相关查询应使用 AST/LSP 后端。

范围与新鲜度

使用限定在当前仓库范围内、且基于磁盘最新状态的后端。tilth MCP 会按需遍历工作树并遵循 .gitignore；当原生 sg 和 LSP 能看到当前检出内容，并能回答所需的语义形态问题时，也可以使用。

实际影响：

• 不要使用过时索引：如果后端需要刷新才能看到当前文件，请先刷新，或选择更新鲜的后端。
• 除非后端明确支持相应范围，否则不要对同级工作树、系统路径或依赖缓存使用仓库范围的后端。
• 跨仓库问题应在进入 cheez-search 之前分流。

何时不应调用 /cheez-search

这些问题不在范围内——遇到时不要进入 cheez-search；请参照表格，将问题分流到对应的调用工作流技能。

问题（不要使用 cheez-search）	分流到	原因
含元变量的模式（JSON.parse(JSON.stringify($X))）	sg（ast-grep）——允许的例外，可通过 Bash 从 cheez-search 调用	AST 形态无法用名称／文本搜索表达
外部库文档（“React 的 useEffect 如何工作？”）	/briesearch（Context7）	不是你的代码；需要查询供应商的实时文档
大量普通非代码文本（日志、构建输出、大型 CSV）	在调用工作流技能中使用宿主的 Bash，搭配 rg、jq、awk、head／tail	Tree-sitter 解析在此会浪费令牌；应使用适合特定格式的工具
仓库外的文件（系统路径、~/Library、/etc）	在调用工作流技能中使用宿主的 Grep／Bash	cheez-search 限定在仓库范围内（见上文）
提交、推送、普通 PR 或堆叠 PR 变更	/plate	发布不属于代码搜索

在进入前分流（类型相关问题）

名称类查询应留在本次运行选定的语义搜索后端中（tilth、原生 AST 搜索，或同类的索引源码搜索路径）。对于类型相关问题，应在进入 cheez-search 前分流——LSP 和 Serena 的分流表请参阅 references/routing.md。

选择搜索类型

进行代码导航（X 在哪里／Y 调用了什么／影响范围）时：先用 kind:symbol 查找定义，再用 kind:callers 查找调用位置。只有在不知道符号名称时，才退而使用 content／regex。

目标	示例后端	示例
查找符号的定义位置／使用位置	tilth_search 的 symbol 类型、原生 AST 符号搜索，或基于类型的 LSP 定义查询	参见 示例 —“handleAuth 定义在哪里？”
查找函数的所有调用位置	tilth_search 的 callers 类型、原生 AST 调用者搜索，或基于类型的 LSP 引用查询	参见 示例 —“什么调用了 validateToken？”
查找字面字符串、TODO、错误消息	在语义后端中进行内容搜索	tilth_search(queries: [{query: "error message", kind: "content"}])
查找匹配正则表达式的行	在语义后端中进行范围受限的正则搜索	tilth_search(queries: [{query: "rate.?limit", kind: "regex"}])
匹配 AST 形状（带元变量的模板）	sg（ast-grep，通过 Bash 调用）	sg --lang typescript -p 'JSON.parse(JSON.stringify($X))' --json src/
模块导入／影响范围图	tilth_deps、LSP 引用／导入图，或等效的依赖上下文	tilth_deps(path: "src/auth.ts")

经验法则： 对名称形式或文本形式的查询，使用语义源代码搜索后端。 只有当模式需要所选后端无法表达的结构化元变量（$X、 $$$BODY）时，才改用 sg。

---

MCP 工具参考

完整的调用格式、参数选项和各类型的示例见 references/tilth-search-reference.md。

AST 形状模式 -- ast-grep 备选方案

对于带元变量的形状（$X、$$$BODY），通过 Bash 改用 sg ——这是唯一获准的 Shell 例外，可通过 sg --rewrite 执行结构化代码改写。有关语法、语言矩阵、安全调用规则、易错点和代码改写试运行协议，请参阅 references/sg-patterns.md。

---

禁止事项和范围限制

• 代码搜索使用语义后端。 sg 用于 AST 形状元变量模式和代码改写；LSP 用于基于类型的定义和引用查询（重命名和代码操作属于编辑，应交由 cheez-write 处理）；对于代码工作以外的非名称条件（大小、修改时间、权限），可以使用 find。不要使用 grep、rg、ripgrep、ag、ack、find 或 fd 搜索代码。
• 已显示展开的结果。 不要重新读取。
• 从默认展开数量开始。 仅在必要时增加；不要过度展开。
• 通过 cheez-read 读取完整文件。 不要在此处读取。
• 通过 cheez-write 编辑代码。 不要在此处编辑。
• 通过项目的测试／构建技能运行测试。 不要在此处运行。
• 通过 git/gh 技能处理 Git 操作。 不要在此处处理。