Search Tools Guide

搜尋工具指南

工具總覽與選擇

本專案的搜尋工具經過系列比較測試驗證，各有明確定位。

工具定位

選擇決策樹

搜尋需求
    |
    v
需要搜尋什麼？
    |
    +-- 符號定義/引用/重構 --> Serena / LSP / Dart MCP
    |
    +-- 網頁資訊（技術文件、API、版本） --> WebSearch
    |
    +-- 跨檔案架構追蹤 --> Grep + Glob + Read 組合
    |   例：追蹤 Ticket 系統從 create 到 complete 的完整路徑
    |
    +-- 精確文字/正則模式 --> Grep（優先）或 rg（進階）
    |   例：`class\s+\w+\s+extends\s+StatelessWidget`
    |
    +-- 按檔名找檔案 --> 內建 Glob
    |   例：`**/*.dart`
    |
    +-- CC runtime 能力（觀察代理人、排程、用戶提問、網頁抓取） --> ToolSearch
        例：「我需要查背景代理人還在不在執行」「我要發送新指令給代理人」

什麼時候用什麼

Code Intelligence MCP 三刀流

本專案配置三個 Code Intelligence MCP server（codebase-memory-mcp / codegraph / serena），各有不同定位：cbm 主打語言無關的概念（模糊）搜尋，codegraph 主打自動增量的呼叫圖追蹤，serena 主打型別感知的安全編輯（唯一支援 rename）。三者按需求切換，不同時使用。

完整九維度設計對照表、三刀流選擇決策樹、JS Chrome Extension 場景組合範例：references/code-intelligence-mcp-tools.md

Claude Code Meta-Tools（平台能力發現）

ToolSearch — Deferred Tools 發現機制

Claude Code runtime 將部分工具以 deferred 模式 提供。deferred tools 的 schema 不預先載入，必須透過 ToolSearch 搜尋並載入後才能呼叫。每個 session 啟動時 runtime 會在 system-reminder 中列出所有 deferred tools 名稱。

核心規則：遇到「我想做 X 但不知道怎麼做」時，在宣告「做不到」或選擇「限制性解法」（禁止、防護、規避）之前，必須先執行 ToolSearch 搜尋是否有對應的 deferred tool（完整五問窮盡檢查見 .claude/rules/core/tool-discovery.md）。

# 精確載入指定工具（最常用）
ToolSearch(query="select:TaskOutput")
ToolSearch(query="select:TaskOutput,SendMessage,TaskCreate")

# 關鍵字搜尋（探索未知能力）
ToolSearch(query="background task status")

返回值會以 <function>{...}</function> 格式提供工具 schema，載入後即可如一般工具呼叫。Session 當下可用的 deferred tools 清單以 system-reminder 為準。

常見 deferred tools 用途對照表、發現工作流程圖、反模式清單、相關規則：references/meta-tools-deferred-discovery.md

rg (ripgrep) - 日常主力搜尋

ripgrep 是基於 Rust 的高效能正則搜尋工具，是 Claude Code 內建 Grep 的底層引擎，比 GNU grep 快約 33 倍（Linux kernel 搜尋基準）且預設自動遵守 .gitignore 規則。一般搜尋用內建 Grep 即可，需要 PCRE2、壓縮檔搜尋、多編碼等進階功能時才需要以 bash 呼叫 rg。

安裝方式、rg vs 內建 Grep 完整功能對照、常用指令速查、語言框架範例、同義詞擴展的概念性搜尋技巧：references/rg-ripgrep-usage.md

Serena / LSP / Dart MCP - 符號導航與程式碼理解

Serena、LSP 和 Dart MCP 提供語意感知的程式碼導航，理解符號定義、引用關係和型別系統，是唯一能做到精確重構的工具類別。適用於有 LSP 插件的語言（Dart / JavaScript / TypeScript / Python 等）；純文字檔（.md / .txt / .yaml / .json）無 LSP 結構優勢，應改用 Edit / Grep。日常搜尋無法用 Serena 完全取代 rg。

Serena / Dart MCP 完整工具表、search_for_pattern vs Grep 詳細比較、適用場景對照：references/serena-lsp-symbol-navigation.md

三 MCP 核心能力速查表（版本無關）

為何不列具體工具動詞名：MCP server 跨版本會改名 / 增刪工具，安裝方式也決定 server 前綴（PC-173 三層漂移）。硬編碼工具動詞名必然與實機暴露漂移，讀者照抄會呼叫到不存在的工具而浪費回合。本速查表只列「server 前綴 + 能力分類」；確切工具動詞名以 ToolSearch 當下發現為準——session 啟動時 system-reminder 列出的 deferred tools 清單是唯一 ground truth。

server 前綴對照

能力 → server 對照（動詞名請 ToolSearch 發現）

使用方式：先用能力關鍵字 ToolSearch 發現當前確切工具名（或直接查 session system-reminder 的 deferred tools 清單），再以 ToolSearch(query="select:<發現到的完整工具名>") 載入 schema 後呼叫。禁止從本文件複製硬編碼工具動詞名直接呼叫——本表刻意不列動詞名以杜絕漂移。

終端 redaction 提醒（PC-173）：bash grep / rg 輸出會把實機可呼叫的 MCP 工具名替換為 n（如 mcp__codegraph__n）。驗證 MCP 工具名引用時改用 Read 工具，勿單憑 bash grep 輸出判讀。

cbm 深度參考：CLI 用法、.claude/ 不索引限制、cbm vs codegraph vs serena 分工速查 → references/codebase-memory-tool.md

WebSearch - 網頁搜尋

核心特性

WebSearch 是 Claude Code 內建的網頁搜尋工具，零配置、穩定可用。

中文查詢建議

• 搭配英文關鍵字提升搜尋精確度
• 注意搜尋結果可能混入簡體中文來源
• 重要的在地化資訊建議交叉驗證

多步驟研究方案

Grep + Glob + Read 組合

多步驟程式碼架構研究的預設方案，無需任何外部依賴。

實測結果：

• 追蹤 Ticket 系統生命週期（8 個核心檔案）：~45 秒，完整度 5/5
• 追蹤 Hook 驗證邏輯（831 行 Python）：~20 秒，完整度 5/5

標準研究流程

步驟 1: Glob 定位相關檔案
    例：Glob **/*ticket*.py

步驟 2: Grep 搜尋關鍵字
    例：Grep "ticket.*create|lifecycle"

步驟 3: Read 深度閱讀核心檔案
    例：Read ticket.py -> 理解入口和分發

步驟 4: 重複步驟 2-3 追蹤呼叫鏈
    例：Grep "TicketLifecycle" -> Read lifecycle.py

環境檢查與故障排除

安裝狀態檢查

rg --version

rg 常見問題

三 MCP 已知限制速查

比較測試結論總覽

本指南的工具定位和建議基於以下比較測試結論：

版本紀錄在同目錄的 CHANGELOG.md。