tarrragon/search-tools-guide

搜尋工具指南

---

工具總覽與選擇

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

工具定位

| 工具 | 類型 | 定位 | 獨佔能力 | |------|------|------|---------| | Grep (rg) | 文字（正則） | 日常主力搜尋 | 正則搜尋、PCRE2、壓縮檔、多編碼、分頁、統計 | | WebSearch | 網頁搜尋 | 唯一網頁搜尋工具 | 技術文件查詢、API 用法、版本資訊 | | Grep+Glob+Read | 多步組合 | 多步驟研究預設方案 | 架構追蹤、程式碼路徑分析 | | Serena / LSP | 語意（符號感知） | 符號分析 | 符號定義/引用追蹤、重構、型別資訊（Dart 支援度最高） | | Dart MCP | 語意（Dart 專用） | Dart 開發工具 | analyze_files、dart_format、dart_fix | | 內建 Glob | 檔名模式 | 檔案定位 | 按名稱找檔案 | | ToolSearch | Meta-Tool | CC runtime 能力發現 | 發現 / 載入 deferred tools（TaskOutput/SendMessage/WebFetch 等） |

選擇決策樹

搜尋需求
    |
    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
        例：「我需要查背景代理人還在不在執行」「我要發送新指令給代理人」

什麼時候用什麼

| 場景 | 首選工具 | 備選 | 範例 | |------|---------|------|------| | 找某個類別定義 | Serena find_symbol | rg "class ClassName" | 找 BookRepository | | 找某個方法的所有呼叫 | Serena find_referencing_symbols | rg "\.methodName\(" | 找 fetchBooks 引用 | | 找精確字串 | Grep / rg -F | - | 找 hardcoded 值 | | 找正則模式 | Grep | rg（進階場景） | 找 import 模式 | | PCRE2 (lookaround) | rg -P | 無替代 | 進階正則 | | 搜尋壓縮檔 | rg -z | 無替代 | 搜尋 .gz | | 查看符號型別 | Dart MCP hover | Serena find_symbol | 確認回傳型別 | | 靜態分析 | Dart MCP analyze_files | 無替代 | 找 lint 問題 | | 找檔案路徑 | 內建 Glob | rg -l | 找 *.test.dart | | 技術文件查詢 | WebSearch | - | Flutter API、套件文件 | | 跨檔案架構理解 | Glob + Grep + Read | - | 追蹤完整程式碼路徑 | | 查詢背景代理人是否仍執行 | ToolSearch → TaskOutput | - | 非侵入性 status 查詢 | | 向執行中的代理人發送指令 | ToolSearch → SendMessage | - | 即時控制背景代理人 | | 派發背景任務 | ToolSearch → TaskCreate | Agent tool | 手動建立 background task | | 停止失控代理人 | ToolSearch → TaskStop | - | 安全中止任務 | | 抓取外部網頁 / 文件 | ToolSearch → WebFetch | WebSearch | 精準抓指定 URL | | 排程定期任務 | ToolSearch → CronCreate | - | 定期觸發 |

---

Code Intelligence MCP 三刀流

本專案配置三個 Code Intelligence MCP server（codebase-memory-mcp / codegraph / serena），各有不同定位與互補優勢。本章說明三者設計差異、工作流決策、以及在 JS Chrome Extension 開發中的最佳組合。

三 MCP 設計對照表

| 維度 | codebase-memory-mcp (cbm) | CodeGraph | Serena / LSP | |------|---------------------------|-----------|-------------| | 後端架構 | 語言無關向量+BM25 混合索引 | TypeScript/JavaScript AST（sqlite WAL） | LSP 協定（language server） | | 語言覆蓋 | 所有語言（向量向度） | JS/TS/Python/YAML/JSON（AST 支援度） | 編輯器已配置 LSP 的語言（Dart/JS/TS/Python 優先） | | 持久化 | ~/.cache/codebase-memory-mcp/ | .codegraph/ (local per-developer) | LSP server 進程內（session 級） | | Sync 機制 | 自動增量索引（watch mode） | 首次 init 後自動增量（2-5s lag） | LSP server 即時響應（file change event） | | Type Resolution | 無型別感知 | AST 級型別資訊（TS/JS 完整、Python partial） | 語言伺服器提供完整型別資訊 | | 跨 Service 查詢 | 單 repo 索引；支援多 project 管理 | 單 repo 初始化；可在外部 worktree 重複索引 | 單 LSP server 綁定，跨檔無額外能力 | | 概念搜尋 | 向量語意搜尋（「找相似概念」）| 精確 AST 符號定位（無模糊搜尋） | 精確符號查詢（定義/引用） | | Symbol 編輯 | 無編輯能力 | safe_delete_symbol、其他編輯工具不支援 | rename_symbol、replace_symbol_body、insert_before/after_symbol | | Diagnostics | 無 | 無 | LSP analyze_files 靜態檢查（Dart 優先） |

特色對位：cbm 的「語言無關 + 概念搜尋」是 codegraph/serena 都無法提供的；codegraph 在「自動增量 + 跨檔 caller 追蹤」獨佔；serena 在「型別感知 + symbol edit + diagnostics」領先。

三刀流工作流決策樹

選擇工具時按以下決策樹進行。各情境的工具推薦經實測驗證：

搜尋 / 分析需求
    |
    +-- 找概念相似的程式碼 / 模糊搜尋
    |   → codebase-memory-mcp (cbm) [推薦]
    |   例：「找所有處理錯誤的地方」「找 state 相關邏輯」
    |   理由：向量語意搜尋，callstack/control flow 無法表達但 cbm 可召回
    |
    +-- 精確找某函式的所有 caller
    |   → CodeGraph + Serena（兩者都行；cgraph 更快）
    |   例：「deleteBook 被誰呼叫」「fetchBooks 的 callers」
    |   理由：AST caller/callee 追蹤，比正則搜尋精確
    |
    +-- 分析修改影響範圍 (blast radius)
    |   → Serena（最安全）或 CodeGraph（最快）
    |   例：「改 API 回傳型別會影響多少地方」
    |   理由：Serena type-aware；CodeGraph 自動 sync caller 資訊
    |
    +-- 重命名符號 / 安全重構
    |   → Serena [唯一支援]
    |   例：`BookRepository` → `BookStore`；重命名後自動更新 100+ 引用
    |   理由：LSP rename 包含檔案儲存；其他工具不支援
    |
    +-- 跨 Repo / 跨服務符號查詢（本專案單 repo 不常見）
    |   → codebase-memory-mcp [推薦]
    |   例：「這個概念在其他專案實作過嗎」
    |   理由：cbm 支援多 project 管理，向量搜尋跨 repo

JS Chrome Extension 場景：三刀流最佳組合

本專案（Chrome Extension + JS 前端 + Python hook 混合）的典型工作流：

| 工作 | 首選工具 | 理由 | 備選 | |------|---------|------|------| | 探索新需求 / 理解架構邊界 | cbm semantic search | 模糊找「event」「dispatch」「listener」等概念 | Serena find_symbol（但需精確名稱） | | 追蹤事件流（event → listener → handler） | CodeGraph call graph | 自動追蹤完整呼叫鏈（特別是 async callback） | rg + Serena（手動多步） | | 確認改動影響（改 message schema 會卡誰） | CodeGraph impact + Serena rename | cbm 找相關檔，Serena 確認精確引用 | rg 逐個驗證 | | 重構回呼函式名 / API 簽章 | Serena rename + replace_symbol_body | rename 改所有引用；replace_symbol_body 改實作 | 手動 sed + rg | | 查詢 Chrome API 使用方式 | Serena hover（JS LSP）| 顯示 TypeScript 型別簽章（chrome.runtime.sendMessage 參數） | 網路搜尋 + WebSearch |

實踐建議：cbm 為「初期探索」甜蜜點（可模糊記得概念名但不清楚確切函式名），codegraph 為「精確追蹤」甜蜜點（給定起點快速展開 caller/callee），serena 為「安全編輯」甜蜜點（批量重構無誤）。三者絕非同時用，而是按需求切換。

---

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。

使用方式

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

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

返回值會以 <function>{...}</function> 格式提供工具 schema，載入後即可如一般工具呼叫。

常見 Deferred Tools 用途對照

| 需求 | Deferred Tool | 典型場景 | 注意事項 | |------|---------------|---------|---------| | 查背景代理人 runtime 狀態 | TaskOutput | PC-050 模式 D 補救；失敗判斷前置步驟 Step 0.5 | 只讀 <status> 標籤，禁讀 <output> body（PC-050） | | 派發背景代理人 | TaskCreate | 需要 run_in_background 長任務 | 搭配 Agent tool 更常用 | | 停止失控代理人 | TaskStop | 代理人 loop、超時、錯誤方向 | 先 TaskOutput 確認狀態再停 | | 向代理人發送指令 | SendMessage | 代理人執行中需要補充資訊 | 非同步發送，代理人下次 tool call 收 | | 列出所有任務 | TaskList | 總覽 CC 任務（非 TodoList） | 注意：不是 TodoList 系統 | | 用戶做決策 | AskUserQuestion | 路由 / 多選 / 二元確認 | 詳見 askuserquestion-rules.md | | 抓取指定網頁 | WebFetch | 精準讀取 URL 內容 | 網頁搜尋用 WebSearch | | 網頁搜尋 | WebSearch | 技術文件 / API 查詢 | 詳見本文件 WebSearch 章節 | | 排程定期任務 | CronCreate / CronList / CronDelete | 週期性自動執行 | | | 建立 / 管理多代理人團隊 | TeamCreate / TeamDelete | 代理人間即時協商 | 詳見 agent-team skill | | 進入 / 離開計畫模式 | EnterPlanMode / ExitPlanMode | 提出計畫給用戶核准 | | | 進入 / 離開 worktree | EnterWorktree / ExitWorktree | 分支隔離 | | | 監控背景 process stdout | Monitor | 追蹤 log 流 | | | 修改 Jupyter Notebook | NotebookEdit | 專案少用 | | | MCP resources 查詢 | ListMcpResourcesTool / ReadMcpResourceTool | 跨 MCP server 資源 | |

Session 當下可用的 deferred tools 清單以 system-reminder 為準，實際載入請以 ToolSearch 返回為依據。

工作流程

情境：「我想做 X 但不知道有什麼工具」
    |
    v
Step 1：對照本章「用途對照表」是否有直接匹配
    |
    +-- 有 --> ToolSearch(query="select:<tool_name>") 載入 → 呼叫
    |
    +-- 無 --> Step 2
    |
    v
Step 2：用關鍵字 ToolSearch 探索
    ToolSearch(query="keyword1 keyword2", max_results=5)
    |
    +-- 找到 --> 載入 → 呼叫
    |
    +-- 找不到 --> Step 3
    |
    v
Step 3：五問窮盡檢查
    (1) Hook 能推送嗎？
    (2) 檔案系統能追蹤嗎？
    (3) 流程能繞過嗎？
    (4) 既有模組有 API 但沒接線嗎？
    (5) CC runtime 有 deferred tool 嗎？（已在 Step 1-2 執行）
    |
    v
五問皆否才能結論「做不到」

反模式（必須避免）

| 反模式 | 症狀 | 正確做法 | |-------|------|---------| | 框架為「XX 專用前置步驟」 | 把 ToolSearch 當成特定工具的鑰匙，不當成通用發現機制 | 理解為「發現 CC runtime deferred tools 的通用入口」 | | 忽略 session system-reminder | 把 deferred tools 清單當背景資訊 | 每 session 首次遇到「找工具」需求時掃一次 | | 採限制性解法（禁止 / 防護） | 問題框架為「如何防止 X」 | 改框架為「如何正確做 X」再問五問 | | 跳過第五問 | 只檢查 Hook/檔案/流程/既有 API，未問 CC runtime 能力 | 必須執行 ToolSearch 搜尋 deferred tool | | 宣告「平台不支援」未窮盡 | 代理人或 PM 直接下結論 | 先完成五問（規則 1），最後才下結論 | | 讀 transcript 推論代理人狀態 | 違反 PC-050 模式 D | 用 TaskOutput 讀 <status> 標籤 |

相關規則與錯誤模式

• .claude/pm-rules/askuserquestion-rules.md — AskUserQuestion 的具體用例
• .claude/references/pm-agent-observability.md — TaskOutput 安全使用範本
• .claude/error-patterns/process-compliance/PC-050-premature-agent-completion-judgment.md — 模式 D 禁讀 output body
• Memory feedback_exhaust_indirect_before_impossible.md — 五問檢查清單

---

rg (ripgrep) - 日常主力搜尋

核心概念

ripgrep 是基於 Rust 的高效能正則搜尋工具，是 Claude Code 內建 Grep 的底層引擎。

效能特性：使用有限自動機和 SIMD 最佳化、lock-free 並行目錄遍歷，比 GNU grep 快約 33 倍（Linux kernel 搜尋基準）。預設自動遵守 .gitignore 規則。

安裝

# macOS
brew install ripgrep

# Linux (Debian/Ubuntu)
sudo apt-get install ripgrep

# 通用（需要 Rust）
cargo install ripgrep

rg vs 內建 Grep

| 功能 | 內建 Grep | rg (Bash) | |------|----------|-----------| | 基本正則搜尋 | 支援 | 支援 | | 檔案類型過濾 | glob 參數 | -t / -T 參數 | | 上下文顯示 | -A / -B / -C | -A / -B / -C | | PCRE2 正則 | 不支援 | -P 支援 | | 壓縮檔搜尋 | 不支援 | -z 支援（brotli, bzip2, gzip, lz4, xz, zstd） | | 替換預覽 | 不支援 | -r 支援 | | JSON 輸出 | 不支援 | --json 支援 | | 排序控制 | 不支援 | --sort 支援 | | 多編碼 | 不支援 | -E 支援（UTF-16, Latin-1, GBK, EUC-JP, Shift_JIS） | | Preprocessor | 不支援 | --pre 支援（可搜尋 PDF 等） | | 混合正則引擎 | 不支援 | --auto-hybrid-regex 自動切換 |

結論：一般搜尋用內建 Grep 即可，需要進階功能時用 rg。

常用指令速查

# 基本搜尋
rg "pattern" lib/              # 搜尋特定目錄
rg -i "pattern"                # 大小寫不敏感
rg -w "className"              # 全字匹配
rg -F "exact.string"           # 固定字串（非正則）

# 輸出控制
rg -l "pattern"                # 僅顯示檔案名稱
rg -c "pattern"                # 僅顯示計數
rg -C 3 "pattern"              # 前後各 3 行上下文
rg -m 5 "pattern"              # 限制最大匹配數

# 檔案類型過濾
rg -t dart "pattern"           # 僅搜尋 Dart
rg -t py "pattern"             # 僅搜尋 Python
rg -g "*.dart" "pattern"       # glob 過濾
rg -g "!*.test.dart" "pattern" # 排除模式

# 正則表達式
rg "class\s+\w+\s+extends"     # 基本正則
rg -P "(?<=class\s)\w+"        # PCRE2 (lookaround)
rg -U "class.*\{[\s\S]*?\}"    # 多行匹配

# 進階功能（rg 獨佔）
rg -z "pattern" archive.gz     # 搜尋壓縮檔
rg -E utf-16 "pattern"         # 搜尋非 UTF-8 編碼檔案
rg --pre cat "pattern"         # 使用 preprocessor（可搜尋 PDF 等）
rg --hidden "pattern"          # 搜尋隱藏檔案
rg --no-ignore "pattern"       # 搜尋 gitignore 忽略的檔案

# 替換預覽
rg "oldName" -r "newName"      # 不修改檔案，僅預覽

語言/框架專案範例（以 Flutter/Dart 為例，其他語言類似）

# Widget 定義（Flutter）
rg -t dart "class\s+\w+\s+extends\s+(Stateless|Stateful)Widget"

# Provider 使用（Flutter）
rg -t dart "Provider\.(of|watch|read)" lib/

# 測試案例（Dart）
rg -t dart "test(Widgets)?\(" test/

# TODO 和 FIXME（Dart，可替換為其他語言的 type filter 如 -t js/py/go）
rg -t dart "(TODO|FIXME|HACK)" lib/

# Ticket 狀態（與語言無關）
rg "status:\s*(pending|in_progress)" docs/work-logs/

概念性搜尋技巧

rg 的主要弱點是同義詞覆蓋（召回率 ~79-87%），可透過多 Pattern 組合改善：

# 錯誤處理（基本 + 同義詞擴展）
rg "catch|try|error|exception|throw" lib/           # 基本
rg "failure|recover|fallback|retry|graceful" lib/    # 同義詞擴展

# 狀態管理（基本 + 生命週期概念）
rg "status|state|pending|in_progress|completed" lib/ # 基本
rg "lifecycle|transition|workflow|progress|phase" lib/ # 擴展

# 資料流向（基本 + 資料操作概念）
rg "parse|validate|save|store|write" lib/            # 基本
rg "transform|convert|persist|repository|serialize" lib/ # 擴展

降噪技巧：排除 l10n 和 import 噪音

rg "error" lib/ --glob '!lib/l10n/' --glob '!*.g.dart'

---

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

核心概念

Serena、LSP 和 Dart MCP 提供語意感知的程式碼導航，理解符號定義、引用關係和型別系統。這是唯一能做到精確重構的工具類別。

重要限制

Serena 的 LSP 符號分析適用於有 LSP 插件的語言：Dart / JavaScript（typescript-language-server）/ TypeScript / Python（pyright）等皆有效；對純文字檔（.md / .txt / .yaml / .json）無 LSP 結構優勢，應改用 Edit / Grep。

Why 此處原誤紀錄為「僅對 Dart 有效」：此紀錄源自早期 Python 環境未配置 pyright 的觀察，已不適用當前環境。W17-091 ANA 實證 serena 對本專案 JavaScript 程式碼完整有效（Class / Methods / 行號邊界皆能解析）。

Serena 工具

| 工具 | 用途 | 使用場景 | |------|------|---------| | find_symbol | 搜尋符號定義 | 找類別、方法、變數定義（僅 Dart） | | find_referencing_symbols | 搜尋引用 | 找某個符號的所有使用處 | | get_symbols_overview | 檔案符號總覽 | 瞭解檔案結構（不需讀全檔） | | rename_symbol | 重命名符號 | 安全重構（自動更新所有引用） | | replace_symbol_body | 替換符號定義 | 精確修改函式/類別實作 | | insert_before/after_symbol | 插入程式碼 | 在符號前後新增內容 | | search_for_pattern | 模式搜尋 | 靈活的正則搜尋（類似 rg） |

Dart MCP 工具

| 工具 | 用途 | 使用場景 | |------|------|---------| | hover | 型別和文件資訊 | 查看符號的完整型別簽章 | | resolve_workspace_symbol | 跨檔案符號搜尋 | 在整個工作區找符號 | | signature_help | 函式簽章提示 | 查看參數定義和說明 | | analyze_files | 靜態分析 | 找 lint 問題、型別錯誤 | | dart_format | 格式化程式碼 | 自動排版 | | dart_fix | 自動修復 | 套用 lint 建議的修正 |

Serena search_for_pattern vs Grep

日常搜尋無法用 Serena 完全取代 rg。 差異如下：

| 維度 | Grep (rg) | Serena search_for_pattern | |------|-----------|--------------------------| | 速度 | 即時（< 1 秒） | 1-5 秒，大範圍可能溢出 | | 輸出格式 | 簡潔行格式，三種模式 | JSON，較冗長 | | 大小寫處理 | 原生 -i flag | 需 regex (?i) | | 分頁 | head_limit + offset | 無（溢出時需縮小範圍） | | 計數 | output_mode: count | 無 | | 跨行搜尋 | 需 multiline: true | 預設支援 | | 程式碼過濾 | --type dart | restrict_search_to_code_files |

Serena search_for_pattern 僅在以下場景使用：

• 搜尋後接續語意操作（find_symbol、replace_symbol_body）
• 需要嚴格只搜尋程式碼檔案
• 需要跨行匹配

適用場景

| 適合（獨佔優勢） | 不適合 | |-----------------|-------| | 重構前找所有引用（精確） | 搜尋註解或字串內容 | | 理解類別繼承和實作關係 | 搜尋非 Dart 程式碼檔案 | | 安全重命名（自動更新引用） | 模糊概念搜尋 | | 查看符號完整型別資訊 | 跨專案搜尋 | | 靜態分析和自動修復 | 效能分析 |

---

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

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

server 前綴對照

| MCP server | 本專案 server 前綴 | 安裝方式註記 | |-----------|------------------|-------------| | CodeGraph | mcp__codegraph__* | 專案層級 .mcp.json | | codebase-memory-mcp (cbm) | mcp__codebase-memory-mcp__* | 專案層級 .mcp.json（注意前綴含連字號，非底線） | | Serena | user-level 安裝為 mcp__serena__*；plugin marketplace 安裝為 mcp__plugin_serena_serena__* | 前綴依安裝方式而定，兩者工具子集不完全相同（部分工具僅 plugin 版有） |

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

| 能力 | 首選 server | 發現方式（取代硬編碼名） | |------|-----------|----------------------| | 索引就緒確認 / 重建 | CodeGraph | ToolSearch(query="codegraph status index") 取當前名 | | 符號定義搜尋（跨語言精確） | CodeGraph / Serena | ToolSearch(query="codegraph search") / ToolSearch(query="serena find symbol") | | 呼叫者 / 被呼叫者追蹤 | CodeGraph | ToolSearch(query="codegraph callers callees") | | 影響分析（blast radius） | CodeGraph / Serena | ToolSearch(query="codegraph impact") | | 語義 / 概念搜尋（模糊召回） | cbm | ToolSearch(query="codebase memory search graph") | | 索引狀態 / 建立 | cbm | ToolSearch(query="codebase memory index") | | 安全重命名 / symbol 編輯 | Serena [唯一] | ToolSearch(query="serena rename replace symbol") | | 檔案符號總覽 | Serena | ToolSearch(query="serena symbols overview") |

使用方式：先用能力關鍵字 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 內建的網頁搜尋工具，零配置、穩定可用。

| 特性 | 說明 | |------|------| | 回應速度 | ~3 秒 | | 英文查詢品質 | 4-5/5（API 用法、技術文件表現優秀） | | 中文在地化品質 | 2-3/5（可能混入簡體中文或英文結果） | | 整合度 | 原生整合到對話，自動提供結構化摘要和來源連結 |

中文查詢建議

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

---

多步驟研究方案

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 常見問題

| 問題 | 原因 | 解決 | |------|------|------| | command not found | 未安裝 | brew install ripgrep | | 搜尋結果不完整 | .gitignore 排除 | rg --no-ignore "pattern" | | PCRE2 不可用 | 編譯時未啟用 | cargo install ripgrep --features pcre2 |

三 MCP 已知限制速查

| 限制 | 影響 | Workaround | |------|------|----------| | cbm MCP namespace 在某些版本未於 ToolSearch deferred 曝光 | ToolSearch(query="codebase memory") 找不到時 | 改用 CLI：codebase-memory-mcp cli <tool> '<json>'（詳見 references/codebase-memory-tool.md §1）。前綴以實機 deferred 清單為準（正確形含連字號 mcp__codebase-memory-mcp__，非底線） | | cbm 對 .claude/ 不索引（v0.6.1 hardcoded） | .claude/ 範圍搜尋 cbm 結果為空 | .claude/ 範圍改用 rg + 必要時 serena（詳見 references/codebase-memory-tool.md §2） | | codegraph 冷啟動需載 embedding model | fresh subprocess 30-60s 不可用 | 用 CC runtime 內已暖機的 mcp__codegraph__* deferred tools |

---

比較測試結論總覽

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

| 比較項目 | 核心結論 | |---------|---------| | WebSearch 網頁搜尋效果 | WebSearch 是唯一推薦的網頁搜尋工具 | | 多步驟研究效果 | Grep+Glob+Read 組合是預設選擇 | | 語意搜尋 vs 文字搜尋 | rg 精確度 ~90-94%，同義詞弱點可用多 Pattern 改善 | | Serena 結構化導航 | Serena LSP 對配置 LSP 的語言（Dart / JS / TS / Python via pyright）皆有效；非符號級操作（如純文字搜尋）Grep 步驟數更少 | | rg vs Serena search_for_pattern | 日常搜尋無法用 Serena 取代 rg |

---

Last Updated: 2026-06-04 Version: 5.1.0 - 三 MCP 核心命令速查表改為版本無關形式（server 前綴對照 + 能力分類 + ToolSearch 發現指引），消除 codegraph/cbm 硬編碼工具動詞名漂移源（PC-173 / W1-035 收斂方案落地）。歷史 5.0 版見 git log。