代理程式的程式碼搜尋有 Token 預算

Semble 在 2026 年 5 月 17 日突破 900 顆 GitHub 星標，靠的是一句直白主張：程式碼代理在 grep、開啟整個檔案，並讀取遠超任務所需的程式碼時，會浪費大部分脈絡預算。¹

這個主張之所以有力，是因為它把程式碼搜尋重新定義為預算問題。人類可以快速掃過雜訊很多的 rg 結果，忽略無用內容；代理卻要為每一行無關內容付出脈絡、注意力與工具迴圈時間。

TL;DR

Semble 是給代理使用的程式碼搜尋函式庫。它提供 MCP 伺服器、透過 AGENTS.md 或 CLAUDE.md 進行的 Shell 整合、CLI，以及 Python API。¹在底層，Semble 會切分程式碼，用 BM25 加上靜態 Model2Vec 程式碼嵌入進行搜尋，再用 Reciprocal Rank Fusion 融合排序清單，接著以符號權重、定義加成、識別字詞幹、檔案一致性與雜訊懲罰等程式碼感知訊號重新排序。¹它的基準測試回報，在 19 種語言、63 個儲存庫、約 1,250 個查詢上，NDCG@10 為 0.854，接近 CodeRankEmbed 混合分數 0.862，同時在基準表中的索引速度快得多。²真正重要的產品教訓不是「取代 grep」。教訓更尖銳：代理搜尋工具應該回傳最小的證據包，讓模型能正確採取行動。

重點摘要

• 給程式碼代理使用者：精確字串仍使用 rg；當任務問的是行為，而不是字面 Token 時，改用片段排序搜尋。
• 給工具建構者：最佳化取回的脈絡，而不只是檢索準確率。有用的單位是每個 Token 能帶來多少證據。
• 給 Codex 與 Claude Code 使用者：子代理最好有 Shell 可存取的路徑，因為頂層 MCP 工具不一定能以相同方式觸及委派代理。¹
• 給基準測試讀者：要把供應商的基準宣稱與本地執行環境行為分開看。我的冷啟動 uvx 執行遠慢於 Semble 的基準表，因為套件、模型與索引啟動成本占了主因。
• 給公開寫作者：檢索工具不會免除引用工作，只是讓檢查證據路徑的成本更低。

為什麼 Grep 仍然好用，但仍然不夠

rg 仍是精確字串的第一選擇。如果我需要 visible_label_residue、憑證變數名稱或函式名稱，詞彙搜尋在速度與確定性上都應該勝出。在我的本地測試中，針對翻譯殘留字詞的字面 rg 查詢大約 0.1 秒就回傳。⁵

問題從代理不知道精確字串時開始。

代理常常按意圖搜尋：「部落格 i18n 關口在哪裡檢查可見標籤殘留？」或「翻譯發布驗證怎麼運作？」字面搜尋仍可能找到有用的行，但代理必須選字、檢查數十個命中、讀檔、重寫查詢，再判斷哪一行承載答案。每一步都消耗脈絡，也都增加太早停下來的風險。

Semble 處理的正是這種失敗模式。它讓代理用自然語言查詢，然後回傳排序過的程式碼片段，而不是整個檔案。¹這不會讓 rg 過時，而是把預設互動從「列出所有符合這個詞的行」改成「給我最小但有用的程式碼切片」。

這個差異很重要，因為代理不像人類那樣閱讀。人類可以掃過 80 行搜尋輸出，只把有趣的 3 行留在腦中；模型收到的是完整輸出的 Token。雜訊搜尋結果會變成任務環境的一部分。

Semble 實際做了什麼

Semble 公開 README 描述了 4 種整合路徑：MCP 伺服器、Bash / AGENTS.md、CLI，以及 Python API。¹Codex 設定是在 ~/.codex/config.toml 加入本地 MCP 伺服器項目；Shell 路徑則是在 AGENTS.md 或 CLAUDE.md 加入程式碼搜尋區塊。¹

Shell 路徑的重要性比乍看更高。README 指出，Claude Code 與 Codex CLI 子代理應使用 Bash 整合，而不是只用 MCP，或至少要與 MCP 並用，因為在那種設定下，子代理無法直接呼叫 MCP 工具。¹這是很實際的代理介面問題：搜尋工具必須存在於工作真正發生的位置，而不只是頂層會話開始的位置。

它的檢索堆疊也很像代理搜尋正在前進的方向：

這個設計符合我在本地檢索系統中看到的情況：純向量搜尋會漏掉識別字，純關鍵字搜尋會漏掉意圖，而混合排序讓代理更容易第一眼讀對。⁴

基準宣稱談的是脈絡，不是魔法

Semble 的基準 README 回報了兩類結果。

第一類衡量檢索品質與速度。表格回報 Semble 的 NDCG@10 為 0.854、CodeRankEmbed Hybrid 為 0.862、BM25 為 0.673、ripgrep 為 0.126。基準涵蓋 19 種語言、63 個儲存庫、約 1,250 個查詢，並且只使用 CPU 執行。²

第二類衡量 Token 效率。該基準模擬常見的程式碼代理工作流程：把查詢拆成關鍵字，執行 rg --fixed-strings --ignore-case，依不同關鍵字命中數排序檔案，再完整讀取命中的檔案。相較於這個基準線，報告指出 ripgrep 加完整讀檔平均使用 45,692 個 Token，而 Semble 使用 566 個 Token，減少 98%。²

這才是有意思的主張。不是「語意搜尋在所有情境都勝過 grep」，也不是「代理應停止使用精確搜尋」。主張是：當任務只需要幾個片段時，grep 加讀檔會把太多無關程式碼送進模型。

基準方法也說明了這個主張適用與不適用的範圍。Semble 比較的是完整讀取命中檔案。²如果您的工作流程已經使用 rg -n、sed 與精準行範圍，基準線可能比它的 grep 加讀檔模型更緊。如果您的代理經常在廣泛搜尋後開啟整個檔案，那這個基準就更接近真實失敗模式。

我的本地測試

我在網站儲存庫中透過 uvx --from semble semble 執行 Semble，然後和字面 rg 搜尋比較。

我先用發布流程查詢開始：

semble search "blog translation quality gate release verifier D1" . --top-k 5 --include-text-files

Semble 回傳 5 個片段。第一個結果在遷移文章表格中摘要了部落格翻譯發布迴圈。另一個結果直接指向 scripts/i18n-automation/README.md，裡面包含品質關口、發布驗證器、母語審閱、commit、push、Railway、Cloudflare 與正式環境 smoke 步驟。⁵

可比較的 rg 指令回傳很快，但它也回傳了一大串字面命中，包含憑證變數、blog_release_verify，以及散落在 scripts、tests 與 docs 中的相關名稱。⁵人類可以過濾這些內容；代理要做同一件事，就必須花費脈絡。

接著我詢問關口實作：

semble search "where does the blog i18n gate check visible label residue" . --top-k 5 --include-text-files

Semble 的第一個結果指向精確的本地關口區塊，也就是 visible_label_residue 被指定、轉成錯誤並影響 finding 狀態的位置。輸出包含相關函式本體行，而不是整個檔案。⁵

可比較的 rg 查詢同樣完成得更快，但回傳了測試、翻譯提示、修復腳本、README 與關口實作中的許多命中。⁵

這個測試不能證明 Semble 的基準。我使用 uvx，下載了套件與模型資產，索引大型混合儲存庫，包含 Markdown 與 JSON 檔案，而且是冷路徑執行。第一個 Semble 查詢約 54 秒，第二個約 31 秒。⁵這些數字不符合專案的基準表，我也不會把它們當作 Semble 效能資料引用。

但這個測試證明了產品形態。Semble 回傳的是更小、更像答案的證據包。兩次搜尋後，semble savings --verbose 依照它自己的檔案對片段節省方法，回報約節省 38,100 個估計 Token，比例為 94%。⁵這應視為工具回報的估計，而不是獨立測量；但方向和可見輸出一致。

正確心智模型：證據包

代理搜尋應該產出證據包。

證據包有 4 個特性：

原始 rg 提供位置與速度。完整讀檔提供脈絡，但通常過量。向量搜尋提供意圖，但可能漏掉精確名稱。好的代理搜尋工作流程會把它們結合起來：

1. 當任務點名符號、錯誤、設定鍵、檔案或字面字串時，使用精確搜尋。
2. 當任務描述行為時，使用片段排序的語意或混合搜尋。
3. 只有在片段證明相關後，才開啟完整檔案。
4. 在最終答案引用檔案與行範圍。
5. 當片段指出具體識別字時，再用精確搜尋重試。

Semble 把這套工作流程的許多部分編碼成工具。代理仍然需要判斷，而證據關口仍然需要可檢查的追蹤。

Semble 如何改變 Codex 與 Claude Code 工作流程

實務問題不是要不要安裝每個新的搜尋工具，而是程式碼搜尋在代理操作契約中應該放在哪裡。

對頂層會話來說，MCP 可以很好用，因為代理看得到工具 schema，並直接呼叫伺服器。Semble 的 README 包含 Claude Code、Codex、OpenCode、Cursor 與其他相容 MCP 用戶端的 MCP 設定範例。¹

對委派工作來說，Shell 存取可能更重要。Semble 的 README 明確點出，Claude Code 與 Codex CLI 子代理應使用 Bash 整合。¹無法觸及頂層 MCP 工具的子代理，若工作流程教它何時以及如何使用，仍可執行 Shell 指令。

也就是說，最佳整合可能看起來很樸素：

## Code Search

Use `semble search` when looking for behavior or related implementation.
Use `rg` when looking for an exact string, symbol, file name, or config key.
Open full files only after the search result proves relevance.
Report file path and line range when citing evidence.

這類指令比籠統的「使用語意搜尋」更有用，因為它說清楚了路由決策。代理會學到哪種工具適合哪種問題。

我不會做的事

我不會取代 rg。

本地測試已經說明得很清楚。rg 大約 0.1 秒就能回答字面查詢。Semble 對行為型查詢回傳更好的證據包，但我的冷 Shell 呼叫確實有啟動與索引成本。⁵

我也不會把 Semble 的 98% Token 主張視為放諸四海皆準。基準比較的是 grep 加完整讀檔。當這個基準線接近代理實際行為時，主張是公平的；若原本已有紀律地只讀窄行範圍，這個收益就會被高估。

我不會把路由選擇藏在黑盒子裡。代理必須知道自己正在做精確查找、語意探索、相關程式碼探索，還是證據確認。沒有路由規則的工具使用，會變成另一種看似合理的失敗來源，也就是聊天驅動代理工作背後同樣的介面問題。

為什麼 Semble 應該放在 Grep 論文旁邊

近期的「Is Grep All You Need?」論文在長記憶對話式 QA 上，測試了 Chronos、Claude Code、Codex CLI 與 Gemini CLI 中的 grep 與向量檢索。在該情境中，內嵌 grep 勝過內嵌向量，但論文更深層的教訓更重要：執行環境對結果的影響，和檢索方法本身一樣大。³

Semble 則從程式碼側指向同一個操作層。搜尋品質不只存在於檢索器本身，也存在於：

• 查詢如何形成；
• 精確與語意路徑是否同時存在；
• 工具回傳多少脈絡；
• 片段是否帶有檔案與行證據；
• 代理是否只在必要時開啟完整檔案；
• 委派代理是否觸及得到工具；
• 最終答案是否引用搜尋真正找到的內容。

包裝器仍然是產品。只有當執行環境把檢索轉成證據時，搜尋才會真正有用。這也是為什麼代理式設計控制面和檢索演算法同等重要。

我想要的標準

代理搜尋工具不應只回報命中。

它應該回報：

• 它執行的查詢；
• 它使用的檢索路徑；
• 檔案與行範圍；
• 片段；
• 回傳 Token 的估計值；
• 結果來自精確、語意或混合檢索；
• 代理何時從片段升級到完整讀檔。

這樣的輸出能讓程式碼搜尋接受稽核。審閱者可以看出代理是否找到正確程式碼、讀了足夠脈絡，並避免讓自己淹沒在無關檔案中。同一個原則也驅動代理執行追蹤：證明存在於路徑，不只存在於答案。

Semble 已經朝這個方向前進，因為它把片段大小與 Token 節省視為一級產品關切。代理執行環境的下一步，是讓這條證據路徑出現在審閱包與最終答案中。

目標不是更漂亮的搜尋，而是讓每個 Token 產生更少無根據的主張。

FAQ

Semble 會取代 grep 嗎？

不會。精確字串、符號、設定鍵、檔名與快速確認仍使用 rg。當任務描述的是行為或相關實作，而代理不知道精確識別字時，再使用 Semble 式片段檢索。

你的本地測試確認了 Semble 的速度宣稱嗎？

沒有。我的本地 uvx 呼叫第一個查詢約 54 秒，第二個約 31 秒，主要是因為套件、模型啟動與索引主導了這次臨時執行。Semble 基準表回報的受控測量快得多，但我的本地執行應視為工作流程證據，而不是效能基準。²⁵

你的本地測試確認了 Token 節省方向嗎？

有，在工作流程層級上是如此。Semble 回傳的片段遠小於廣泛字面 rg 輸出，而它的 savings 指令在兩次搜尋後回報約節省 38,100 個估計 Token。這個節省數字來自 Semble 自己的計算方法，所以應視為工具遙測，而不是獨立證明。⁵

為什麼代理程式碼搜尋對 Codex 與 Claude Code 很重要？

當搜尋傾倒太多脈絡，或隱藏太多證據時，代理品質就會下降。好的工作流程會教代理何時使用精確搜尋、何時使用片段排序檢索、何時開啟完整檔案，以及如何引用結果。

團隊應該把 Semble 加入 AGENTS.md 嗎？

只有在自己的程式碼庫上測試後才應加入。先從一條指令開始：行為型問題使用片段排序搜尋，精確字串使用 rg。衡量代理是否更快找到正確檔案，並讀取更少無關行。

參考資料