Maguyva 部落格

會隨行的上下文

Mon, 07 Sep 2026 00:00:00 GMT

Cursor 的索引器在 Cursor 裡非常出色。Tab 補全、行內編輯、聊天，以及那個視窗裡的代理，都已經建立在 Cursor 為開啟的工作區維護的專案索引之上。如果 Cursor 是你唯一寫程式碼的介面，而那個索引已經能找到正確的檔案，那就留在那裡。這是誠實的「原地不動」情形，也理應是本文的第一句話。

這篇文章講的是普通一週中的另一半。同一個儲存庫也會在 Claude Code 中開啟，被 Codex CLI 詢問，在第二台機器上被審查，或者被在 CI 中執行的代理查詢。問題不是「哪個索引器更好」。問題是，代理在一個視窗裡信任的地圖，和它在下一個視窗裡信任的地圖，是不是同一張。

Maguyva 就是那張會隨行的地圖。它是一個遠端 MCP 程式碼庫上下文層。代理查詢它的方式，和查詢其他任何 MCP 工具一樣。結果會以附行號的排序路徑傳回。Cursor 仍然是編輯器。移動的是上下文。

Cursor 的索引器是做什麼用的

Cursor 內建的索引存在的目的，是讓編輯器內的聊天、代理和搜尋能夠檢索相關程式碼，而不只是依賴模型原始上下文視窗所能容納的內容。這對 IDE 來說是正確的設計。這個索引是 Cursor 原生的。它不是 MCP 伺服器，也無法從任何其他用戶端存取。

它的工作方式，按照撰寫本文時 Cursor 公開文件和 Cursor 自身說法的描述是這樣的：主要的搜尋路徑不再是雲端 embedding 索引。Cursor 團隊在其社群論壇上表示，專門的語意／基於 embedding 的搜尋正在逐步淘汰，改採基於 grep 的檢索，因為現今的模型不靠它，自己就能把即時的程式碼樹搜尋得夠好。取而代之的是 Instant Grep，一個由 n-gram、倒排串列和布隆過濾器建構的本機搜尋索引，存放在一張記憶體對應的查找表中，因此查詢是在開發者自己的機器上解析的，而不是在伺服器上。

索引本身存放在儲存庫自己的 .git/cursor/ 目錄中，錨定在某個特定的 git 提交上；自那次提交以來的編輯會疊加在其之上，而不是觸發重新掃描，只有當本機狀態與索引建置時的狀態嚴重偏離時，索引才會重建。因為它位於 .git 內部，它永遠不會被追蹤，也永遠不會被推送——刪除該資料夾，索引就消失了。.gitignore 在設計上就自動受到遵守，因為只有受 git 追蹤的內容才符合條件，.cursorignore 則在讀取路徑上被強制執行。這條路徑上已經沒有伺服器端的 embedding 步驟，也沒有遠端向量資料庫。早先的文件描述了一種雲端輔助設計——分塊加密、Merkle 樹同步、團隊成員間的索引重複使用——而 Cursor 自己的團隊後來表示這種設計正在被淘汰，所以本文不再把它描述為當前狀態。

編輯器內一個突出的亮點是 Cursor 的 Explore 子代理。它可以在自己的上下文視窗中，用一個更快的模型發起多路平行搜尋，只傳回相關的發現，這樣主對話就不會被搜尋結果撐大。這是編輯器內部一項真正的優勢。保留它。

多根工作區也受支援：每個開啟的資料夾的上下文都對 Agent 可用。一些依賴 git 的功能，比如 worktree，在多根設定中會被停用，而 Cloud Agents 完全不支援多根工作區。

這些都不是離開 Cursor 的理由。這只是對一張地圖的準確描述——它在自己所處的地方非常出色。

「隨行」到底意味著什麼

當同樣的問題在不止一個用戶端上傳回同樣類型的答案，並帶有你可以開啟檢視的引用時，一張地圖就算是會隨行的。

在 Cursor 中：「parseConfig 定義在哪裡，誰呼叫了它？」
在 Claude Code 中，同一個儲存庫：同樣的問題。
在 Codex CLI 中，一台從未開啟過 Cursor 視窗的審查機器上：同樣的問題。
在一個會說 MCP 的 CI 代理中：同樣的問題，針對同一個託管的快照。

如果每個介面都建置自己的私有索引，你擁有的就不是一張地圖，而是幾份彼此漂移的快取。編輯器索引可能對磁碟上的程式碼樹是最新的。CLI 工作階段可能落後一天。CI 任務可能看的是另一份簽出的程式碼。而代理聽起來照樣自信滿滿。

Cursor 的索引器本來就不該解決這個問題。因為它活在編輯器內部，它建立的上下文就是為那個編輯器服務的。同時還需要 CLI、CI 管線或另一個編輯器的讀者，需要一個針對這些介面的獨立工具。這是一個範圍事實，不是缺陷。Maguyva 就是那個獨立的工具。

Cursor 索引器公開的語言數量，在本文可以使用的資料中沒有說明。Maguyva 公開支援 279 種以上的語言和基於文字的技術。Cursor 的定價這裡也沒有照搬；請參考他們的定價頁面。Maguyva 按工作區計費，而不是按席位，公開的方案為 $0、$19、$49 和 $149，取決於已索引的規模和工作區大小。

一張託管地圖，每個 MCP 用戶端

Maguyva 是一個遠端 MCP 伺服器。你連接 GitHub，選擇儲存庫，雲端管線會建立符號、圖邊和一張排序後的地圖。你把一個 API 金鑰新增到你已經在用的用戶端的 MCP 設定中。Maguyva 為 24 個有文件記錄的 MCP 用戶端（包括 Cursor）提供設定指南，也可以連接其他支援標準設定的 MCP 相容用戶端。

如果你在 Cursor 中工作，Cursor 設定頁面是特定於該編輯器的路徑。同一個伺服器也服務於 Claude Code、VS Code、Windsurf、Codex CLI 等。你不需要更換編輯器。你為每個代理提供同樣的工具介面：11 個面向客戶的 MCP 工具，涵蓋搜尋、符號、依賴分析、檔案檢索、儲存庫上下文和確定性實用工作流程。語意、結構、圖和文字檢索被融合成排序結果。

這就是可移植性帶來的好處。你今天早上在 Cursor 中核實過的引用，和 Codex CLI 今晚傳回的引用形式相同。檔案路徑和行號。開啟它們。如果錯了，你會看到。如果對了，下一次編輯就有地方落腳。被認可的說法是更少的幻覺編輯，而不是承諾每一次編輯都正確。

新鮮度是公開的。快照帶有時間戳，因此代理知道自己讀到的是哪個版本的程式碼樹。重建節奏是：免費方案每天一次，付費方案每小時一次。誠實的限制是未同步的本機工作：只存在於工作樹中的編輯，還沒有進入託管地圖。無論你從哪個用戶端查詢，這個限制都是一樣的，而這正是重點所在。用戶端之間的漂移不再是第二個隱藏的限制。

文件給出了適用於每個用戶端的啟用迴圈：索引一個你已經瞭解的儲存庫，連接用戶端，問一個你能核實的問題。先在 Cursor 中做一次。再從你在審查那天真正會用的 CLI 中做一次。如果兩次回答引用的是同一個處理函式，就代表地圖確實隨行了。

兩張地圖如何並存

兩個都用。它們不是比較頁那種意義上的替代關係。

讓 Cursor 的索引器繼續為磁碟上的專案工作。讓 Explore、Instant Grep 和編輯器內的代理使用它。這個迴圈是原生且快速的。
在 Cursor 中把 Maguyva 新增為 MCP 伺服器，讓同一個工作階段也能查詢託管的工作區地圖。Cursor 是一個有文件記錄的 Maguyva 用戶端。你不是在兩個索引之間二選一、刪掉另一個。
把同一個 Maguyva 伺服器新增到 Claude Code、Codex CLI，或任何接觸該儲存庫的其他 MCP 用戶端。一種 API 金鑰形式。一個工作區。
如果某個 CI 代理相容 MCP，把它指向同一個伺服器。它會讀到和膝上型電腦一樣的、帶時間戳的快照。

編輯器索引仍然是回答「此刻這個視窗裡磁碟上有什麼」的最佳工具。託管地圖則是回答「今天要接觸這個工作區的每一個代理眼中它是什麼樣子」的最佳工具。這兩句話並不衝突。

工作區配額公布在定價頁面上：儲存庫數、已索引行數和使用者數，按工作區計費。代理和人類共享同一個使用者數。先用一個你能自己評判的儲存庫免費開始。等引用經受住了與程式碼樹接觸的考驗之後，再提升工作區規模。

本文不主張的事

本文不主張 Cursor 的索引器薄弱、不完整，或是更換編輯器的理由。本文的第一句話恰恰相反。

本文不主張 Maguyva 取代了 Instant Grep 或 Explore 子代理。那些是 Cursor 的功能。它們留在 Cursor 裡。

本文不為任何一個產品編造語言數量、延遲數字或 token 節省數字。未知的數字保持未公開。

本文不假裝未推送的本機工作已經在託管地圖裡。帶時間戳的快照讓這個限制變得可見，而不是消除它。

測試很普通。索引一個你已經瞭解的儲存庫。問一個你能核實的問題，先在 Cursor 中，再在第二個 MCP 用戶端中。會隨行的上下文，就是兩處得到同一條引用。

// same map, wherever you opened it.

先地圖，後審查

Mon, 07 Sep 2026 00:00:00 GMT

在一個提取要求的兩端，坐著兩項不同的工作。在代理動筆之前，它需要一張即將修改的程式碼樹的地圖。在代理開啟 PR 之後，應該有什麼東西對照系統的其餘部分來讀這個變更，並留下人類可以據以行動的評論。

這兩項工作從遠處看很相似，因為二者都涉及「理解程式碼庫」。但它們不是同一個產品。一個回答的是「這個改動應該落在哪裡？」。另一個回答的是「這個 diff 破壞了什麼，而逐行檢查的程式碼檢查工具會漏掉？」。把它們混為一談，只會產出更差的初稿和更嘈雜的審查。

這篇文章是一份聯合工作流程指南。Maguyva 是代理首先查詢的地圖。Greptile 是隨後為 PR 新增評論的審查代理。這個搭檔在設計上就是互補的：Maguyva 不審查提取要求，Greptile 也不會取代代理用來撰寫這些改動的上下文層。

為什麼這種分工有用

一個從訓練先驗加上幾個貼上檔案出發的編碼代理，會編造一條看似合理的路徑並編輯它。這就是錯誤檔案的失敗模式，是一個檢索問題。Maguyva 是一個遠端 MCP 程式碼庫上下文層：語意、結構（AST）、圖／依賴和文字檢索融合成排序結果，再加上符號查詢和檔案擷取。有依據的答案以 path/file.ext:line 的形式傳回，讓你能在補丁存在之前就拒絕一個錯誤的結果。這個主張保持謙遜：更少的幻覺編輯。模型仍然可能猜測。只是第一步不再是猜測。

Greptile 是一個 AI 程式碼審查代理。用他們自己的話說，它以對程式碼庫的完整理解自動審查每一個提取要求，並將這與孤立檢查檔案、而非整個系統的傳統程式碼檢查工具相對照。它的設定就是安裝 GitHub 或 GitLab 應用程式並選擇儲存庫。沒有需要你維運的本機索引。託管方式是 Greptile Cloud（他們表示符合 SOC 2 Type II，並可應要求提供報告），也為企業提供自託管選項。

他們自己的編號流程是：連接儲存庫，並為每個函式、類別和依賴建置依賴圖；在每個提取要求上，使用那張完整儲存庫圖分析變更，並在大約三分鐘內以附修復建議的 PR 評論形式發布結果；每條評論都可以把問題移交給團隊已經在用的編碼代理。他們還表示會持續閱讀先前人類留下的 PR 評論，以學習團隊的編碼標準並減少嘈雜的建議。據他們所說，這套學習系統需要 2 到 3 週來適應。

這是審查，不是起草。Greptile 的突出之處在於，針對已經落地到 PR 中的變更提供完整儲存庫圖上下文，隨後是一個閉環，把發現結果發給 Claude Code、Codex、Conductor、Cursor 或 Devin。Maguyva 的突出之處在於代理在那次變更被寫下之前查詢的排序地圖。兩者都用。不要要求任何一方去做另一方的工作。

Maguyva 與 Greptile 之間沒有宣布任何官方第一方產品整合。你也不需要。Maguyva 透過 MCP 與代理對話。Greptile 透過自己的應用程式與 GitHub 或 GitLab 對話。它們在提取要求處相遇。沒有黏合用的腳本，也沒有把一個工具接到另一個工具的排程任務。這個搭檔不需要 bash，因為每個產品都已經站在自己應有的位置上。

這不是什麼

這不是對 Greptile 的拆解。這不是一篇「換個審查工具」的文章。Greptile 於 2024 年 3 月 5 日作為 Y Combinator W24 公司在 Hacker News 上發表，那篇貼文是很多人第一次瞭解這款產品的方式。如果你也是這樣發現他們的，那就繼續用。這個頁面補上的是那個迴圈中缺失的前半段：先讓代理紮根，使 Greptile 看到的那個 PR 一開始就瞄準了正確的檔案。

Greptile 的行銷材料主打審查速度和抓 bug 能力的說法。請把這些當作 Greptile 自己的說法，而不是獨立核實過的數字。本文不會把它們當作事實重複。

語言覆蓋也是同樣的誠實問題。Greptile 把支援範圍表述為覆蓋所有程式語言，而不是一份列舉清單；沒有給出精確的數字。Maguyva 公開支援 279 種以上的語言和基於文字的技術，並在涉及技術問題時，在網站上給出技術上的細分（有解析器支援的 AST 與純文字）。這是兩個不同的產品，做出不同的聲明。不要把它們混為一談。

Greptile 的定價沒有出現在本文可以使用的資料中。付費方案是存在的；請參考他們的定價頁面。Maguyva 按工作區計費，而不是按席位。方案從免費開始。如果你需要工作區數字，定價頁面上列出了公開的方案。

工作流程

三個有名字的階段。按這個順序執行。第一次嘗試這個搭檔時，一個都不要跳過。

1. Maguyva 上下文

索引一個你已經瞭解的儲存庫。連接你已經在用來寫程式碼的 MCP 用戶端——Claude Code、Cursor、Codex CLI、VS Code、Windsurf，或者其他 MCP 相容用戶端。Maguyva 為 24 個有文件記錄的 MCP 用戶端提供設定指南，也能連接支援標準 MCP 設定的其他用戶端。

在任何人寫下一行程式碼之前，先問一個你能評判的問題。「工作階段過期在哪裡處理，什麼在呼叫它？」比「修一下認證」是更好的第一步。要求引用。開啟 file.ext:line 結果。跟著符號走。確認你即將觸碰的依賴關係。

Maguyva 提供 11 個面向客戶的 MCP 工具，涵蓋搜尋、符號、依賴分析、檔案檢索、儲存庫上下文和確定性實用工作流程。四種檢索模式融合成排序結果；當你已經知道名字時，find_symbol 是一個獨立的工具。文件描述了最短路徑：先免費開始，索引一個你已經瞭解的儲存庫，連接用戶端，然後問一個你能核實的問題。

快照帶有時間戳，因此代理能判斷自己讀到的是哪個版本的程式碼樹。誠實的限制是未同步的本機工作。如果編輯只存在於工作樹中，還沒有被推送，託管地圖就還不包含它。指令檔案（CLAUDE.md、AGENTS.md）在這裡依然有它們的位置，用來記錄慣例和不該觸碰的東西。它們不是一張活的地圖。用它們來規範行為。用 Maguyva 來核實事實。

在引用經受住與儲存庫接觸的考驗之前，不要讓代理開啟 PR。這道關卡就是這個階段的全部意義所在。

2. 代理 PR

同一個代理現在會在你已經付費使用的用戶端裡寫下這個改動。Maguyva 既不是編輯器，也不是審查者。代理仍然負責生成 diff。你仍然像以前一樣，在 GitHub 或 GitLab 上開啟提取要求。

應該不同的是第一個檔案。這個 PR 應該點明實際實作該行為的處理函式、將會被破壞的呼叫端，以及在改動出錯時會失敗的測試。如果第一階段被跳過了，第三階段就會把評論花在一個落在錯誤套件裡的改動上。Greptile 依然能發現系統性的問題。但它不應該還要從一條幻覺出來的路徑中恢復過來。

把 PR 的範圍控制好。一個有依據的第一個檔案，不是重寫整個模組的許可證。這個互補的搭檔之所以有效，是因為代理先帶著地圖完成了一項工作，然後請審查者在一個有邊界的 diff 上完成另一項工作。

3. Greptile 審查

Greptile 已經透過 GitHub 或 GitLab 應用程式連接到儲存庫。在新的提取要求上，它使用自己建置的完整儲存庫圖分析改動，並以附修復建議的評論形式發布結果。他們自己的材料把這個過程的時長定在大約三分鐘。

像讀一位仔細的隊友那樣讀這些評論：開啟被引用的位置，判斷這個發現是否真實，然後再行動。當 Greptile 提供「Fix with your Agent」時，它會把問題——檔案路徑、行號、建議程式碼——傳送給 Claude Code、Codex、Conductor、Cursor 或 Devin。「Fix All」會一次性傳送審查中的所有問題。他們還為這次移交提供了 Greptile MCP 和一個 Claude Code 外掛。Maguyva 不在那份具名的目標清單上；這種缺席不是問題。Maguyva 已經在第一階段完成了自己的工作。寫下這個 PR 的編碼代理，才是應該接收修復負載的那一方。

在最初的 2 到 3 週裡，預期會有一些噪音，因為 Greptile 的學習系統正在適應你團隊實際留下的評論。這是他們公布的時間表，不是這個搭檔的缺陷。人類審查依然在這個迴圈裡。Greptile 是自動化的第一道關卡，不是合併按鈕。

如果一條 Greptile 評論指向了代理在第一階段從未查詢過的檔案，這是一個有用的訊號。要麼是地圖漏掉了一個呼叫端，要麼是代理跳過了一次引用。針對這條評論修正草稿。不要關掉審查者。

如何保持這種互補關係的誠實

Maguyva 永遠在先。對一個錯誤檔案的 PR 進行審查，依然是在審查錯誤的檔案。
Greptile 永遠在後。一份引用充分的草稿，依然需要一次系統層面的 diff 通讀。
不要要求 Maguyva 發布 PR 評論。它不會這麼做。
不要要求 Greptile 在代理還在選擇路徑時，充當它的第一層檢索工具。這不是他們的 GitHub 或 GitLab 應用程式被設計來做的事。
不要編造一個「同步」兩者的 bash 管線。PR 就是介面。
獨立地驗證兩端。索引一個你已經瞭解的儲存庫。問一個你能核實的問題。然後開啟一個小的 PR，看看 Greptile 實際上評論了什麼。

一旦被命名，這個迴圈就很普通了。先地圖。再代理 PR。再審查。每個產品都留在自己擅長的那一側提取要求上。

// map first. review second. in that order.

在沒有本地索引器的情況下，給 AI 代理大型儲存庫的上下文

Fri, 14 Aug 2026 00:00:00 GMT

一個大型儲存庫放不進上下文視窗，而如果你曾經把膝上型電腦上的索引器指向一個真正的 monorepo，你就知道它在那裡也放不舒服——記憶體飆升，第一次索引要花一個小時，而你的代理在下一個工作階段開始時，依然在猜哪些檔案重要。

通常的答案是在編輯器旁邊執行一個索引器，對於能舒服放進一台機器的儲存庫來說，這是個不錯的答案。如果你的 monorepo 在 Cursor 中已經索引得很快，而那也是你唯一需要這張地圖的地方，那麼這篇文章沒有什麼可以補充的——跳過它就好。

這篇文章講的是另一種情況——當一個代理需要一張大型儲存庫的可查詢地圖，而你又不想為此執行本地索引器時。

什麼時候本地索引器是錯誤的工具

本地索引假定程式碼存在於查詢它的那台機器上，而在真正的 monorepo 規模下，即便在單個編輯器內部，這個假設也會變得吃緊。這個儲存庫單純就是大到你不想一直在膝上型電腦上保持熱索引：你在一個套件裡工作，而影響範圍卻在三個目錄之外，一次針對兩百萬行程式碼樹的冷啟動首次索引，不是你想經歷兩次的事——無論是在你自己的機器上，還是在一個從未複製過這棵程式碼樹的 CI 執行器上。或者，某個同事應該能查詢你在用的同一張地圖，而不必等自己的機器吃力地跑完同一個索引。

這些都不是丟棄一個好的編輯器索引器的理由。這是一個理由，說明你還應該擁有一張任何代理都能透過 MCP 查詢的託管地圖。

而規模問題比「檔案太多沒法貼上」要深得多。在一棵大程式碼樹上，有意思的問題幾乎從來不是「給我看這個檔案」——而是哪個檔案、哪個符號、哪些呼叫端、哪些測試。一個從列出 src/ 並讀取前三個結果開始的代理，會心安理得地漏掉 apps/api 裡的處理函式和 packages/sdk 裡生成的用戶端。你需要的是從整棵程式碼樹建置、再排序、並附上引用的檢索。

「大型儲存庫的上下文」到底意味著什麼

把檔案一股腦塞進提示詞不是上下文——那只是程式碼樹更小、更差的一份副本。你的代理真正需要的是提出問題，並得到帶引用的答案：這個符號定義在哪裡、誰在呼叫它，我即將修改的模組有什麼依賴它，哪個測試檔案覆蓋了這個行為，以及程式碼樹現在是什麼樣子，而不是上個季度的樣子。

這些答案必須來自一個根據你的儲存庫建置的索引，而不是模型對別人儲存庫的記憶，而且這個索引必須存在於代理上下文視窗之外的某個地方。對這個問題來說，它也應該存在於你膝上型電腦之外的某個地方。

還有一件事，指令檔案替你做不到：CLAUDE.md 和 AGENTS.md 是放置慣例和行為規範的正確地方，但它們不是一張兩百萬行程式碼樹的、活的、經過排序的、可查詢的地圖。行為用規則，事實用儲存庫智慧。

在雲端建置地圖，從任何用戶端查詢它

Maguyva 是一個遠端 MCP 程式碼庫上下文層。你連接 GitHub，選擇你的儲存庫，然後就可以放手，讓雲端管線解析程式碼樹、建立符號和圖邊、維護一張排序後的地圖——永遠不需要本地索引器。

當你推送程式碼時，變更的檔案會被增量解析，圖和排序層會按排程重建：免費方案每天一次，付費方案每小時一次。每份快照都帶有時間戳，讓你的代理能分辨自己讀到的是哪個版本的程式碼樹。這裡誠實的限制是未同步的本機工作——只存在於你工作樹中、從未推送過的編輯，還不在託管地圖裡。

然後，你把 API 金鑰新增到你已經在用的用戶端的 MCP 設定中，就完成串接。這裡有 24 個有文件記錄的 MCP 用戶端的設定指南，任何支援標準設定的其他 MCP 相容用戶端也都能連接。如果 Cursor 是你的主場，Cursor 頁面會帶你走完那條路；同一個伺服器也服務於 Claude Code、VS Code、Windsurf、Codex CLI 等等。

你不需要更換編輯器。你給代理的是一整套工具介面——11 個 MCP 工具，涵蓋搜尋、符號、依賴分析、檔案檢索和儲存庫上下文——覆蓋 279 種以上的語言和基於文字的技術，這在一個早已不再是單一語言的 monorepo 上，比你想像的更重要。

答案會附上依據傳回，以帶行號的檔案路徑形式呈現。語意、結構、圖和文字檢索被融合成排序結果，所以像「什麼依賴 parseConfig」這樣的問題，得到的既不是一大堆 grep 輸出，也不是單一的語意片段，而是真正重要的那一小撮位置。

一份具體的操作指南

不要一上來就索引整個公司。以下是行之有效的路徑：

選一個你已經很熟悉的儲存庫——一個你能手動評判的套件，勝過你手頭最大的程式碼樹。
免費開始：3 個儲存庫，5 萬行索引額度，全部 11 個工具，沒有每月查詢配額。如果你的代表性儲存庫比這更大，定價頁面按已索引規模——而不是按席位數——列出了工作區方案（$0、$19、$49、$149）。
連接 GitHub，等待首次索引完成。你沒有在本機編譯任何東西。
接上 MCP 用戶端——幾行設定。Maguyva 是一個遠端 MCP 伺服器，所以沒有外掛、沒有擴充套件，也不需要採用第二個編輯器。
問一個你能核實的問題。「什麼依賴 parseConfig？」或者「登入工作階段過期在哪裡處理？」然後開啟被引用的 file.ext:line 結果，對照眼前的程式碼樹核對。
只有在引用經受住那次核對之後，才讓代理去編輯。

如果第一個儲存庫合適，而你的程式碼樹很大，就按你的已索引行數和重建節奏提升工作區規模。人類和代理共享同一個使用者數——Maguyva 按工作區計費，而不是按席位——所以往這個迴圈裡再加一個代理不會多花你一分錢。

啟用測試和文件為任何首次執行推薦的一樣：索引一個你已經瞭解的儲存庫，問一個你能核實的問題。大型儲存庫不會改變這個測試，只會讓第一個選錯的檔案代價更高。

串接之後要留意什麼

留意三件事。新鮮度：付費方案每小時重建，免費方案每天重建，未推送的本機工作不會出現在地圖裡——這是你接受的權衡。範圍：索引一組有代表性的儲存庫，而不是每一個被歸檔的分叉儲存庫；免費方案是刻意設計成這個規模，讓你先弄清楚這些答案值不值得留下。以及驗證：一張無法引用路徑和行號的大型儲存庫地圖，只是一台更慢的猜測機器，所以在代理交付補丁之前，讓它先展示位置。

然後執行你在小儲存庫上會執行的同一個測試。索引一個你已經瞭解的儲存庫。問一個你能核實的問題。如果這張地圖是真實的，你的代理就不會再從一棵冷程式碼樹開始。

// no laptop got hot building this map.

為什麼你的 AI 編碼代理會產生檔案路徑幻覺

Fri, 14 Aug 2026 00:00:00 GMT

破綻不是一個寫錯的函式體。而是一次自信滿滿的編輯，針對一個不存在的檔案，或者一個存在但並非實作該行為的檔案。

你要求修復工作階段過期問題。代理開啟了 src/auth/session.ts。這條路徑看起來合理。但它也是錯的。真正的處理函式在 apps/api/src/middleware/expiry.ts 裡，兩次重構之前被重新命名過。代理沒有對你撒謊。它是用訓練先驗加上上下文視窗裡已經有的內容，補全了一個路徑形狀的字串。

這是真實儲存庫中常見的失敗模式。模型會寫程式碼。失誤在於選錯了寫程式碼的地方。

為什麼代理會編造路徑

編碼代理是一個帶工具的下一個 token 預測模型。當你說「修一下工作階段過期」時，它必須先指定一個檔案，才能讀取或修補任何東西。如果它還沒有一張有依據的地圖，它就會從以下來源拼湊出一條路徑：

它在其他儲存庫裡見過的命名慣例。src/auth/session.ts 是一種常見形態。
已經出現在對話裡的檔案，那可能是你上週貼上過的檔案，而不是現在真正重要的檔案。
它碰巧執行過的目錄清單，在大型程式碼樹上是不完整的。
指令檔案。CLAUDE.md 和 AGENTS.md 告訴代理該如何表現。它們不是符號、呼叫端或當前路徑的活索引。

這些來源沒有一個是今天這個儲存庫的地圖。模型填補空白的方式，和它填補任何空白的方式一樣：用一個高機率的延續。這個延續常常看起來像一條真實的路徑。有時那個檔案確實存在，而且就在正確檔案旁邊。有時它曾經存在於上個月已合併的一個分支上。有時它從來就不存在。

如果代理從未搜尋過正確的字串，grep 在這裡救不了你。代理猜了一條路徑，然後讀了那條路徑傳回的內容，然後編輯了它。第一個錯誤的步驟是路徑，不是補丁。

讀檔案也不等於找到正確的檔案。Claude Code、Cursor、Codex 以及類似的工具，可以開啟你指向的任何東西。問題在於，它們能否在編輯之前，可靠地找到正確的檔案、重要的符號、依賴關係、測試，以及影響範圍。沒有地圖的檔案存取，依然是從猜測開始的。

錯誤檔案的編輯是一個檢索問題

把編造出來的路徑當作一次檢索失敗來處理，而不是當作性格缺陷。

如果代理在被允許編輯之前必須傳回 path/file.ext:line，會發生兩件事。第一，你可以開啟這條引用，在十秒內拒絕這次工作。第二，代理必須去查詢某個真正瞭解這棵程式碼樹的東西。

這就是程式碼庫上下文層的工作。僅靠語意搜尋是不夠的。一個「聽起來像工作階段過期」的片段，依然可能落在一個已廢棄的套件裡。當你知道字串時，你還需要精確文字；當你知道名字時，你需要符號查詢；當你知道形狀時，你需要結構化搜尋；當你需要呼叫端和影響範圍時，你需要依賴圖。

Maguyva 就是為相容 MCP 的編碼代理提供的這一層。它不是編輯器。Claude Code、Cursor、Codex CLI、VS Code、Windsurf 以及其他 MCP 用戶端，都留在它們原本的位置。代理在觸碰任何一行程式碼之前，先查詢一張排序過的地圖。

這個主張刻意保持謙遜：更少的幻覺編輯。Maguyva 並不會剝奪模型猜測的能力。它改變的是預設的第一步，從「編造一條看似合理的路徑」變成「請求排序過、帶引用的位置」。

一份有依據的答案是什麼樣子

對「工作階段過期在哪裡處理」這個問題，一個有用的答案不是一段話。而是一份簡短的位置清單：

apps/api/src/middleware/expiry.ts:48 - 處理函式
apps/web/src/lib/auth-client.ts:112 - 呼叫端
apps/api/tests/expiry.test.ts:20 - 如果這次改動出錯就會失敗的測試

你可以開啟這些行。如果錯了，你就停下。如果對了，代理就可以編輯。重點在於驗證，而不是一句口號。

Maguyva 提供 11 個面向客戶的 MCP 工具，涵蓋搜尋、符號、依賴分析、檔案檢索、儲存庫上下文和確定性實用工作流程。四種檢索模式（語意、結構、圖／依賴和文字）融合成排序結果；符號查詢是一個獨立的 MCP 工具（find_symbol）。有依據的答案會附上檔案路徑和行號傳回，方便你對照眼前的程式碼樹來評判。

文件描述了最短路徑：先免費開始，索引一個你已經瞭解的儲存庫，連接用戶端，然後問一個你能核實的問題。

一個改變第一次編輯的迴圈

你不需要一套新的工作流程信條。你需要的是在第一次落筆之前多加一步。

問一個你已經能評判的問題。「哪段程式碼處理登入和工作階段過期」比「修一下認證」更好。
要求引用。檔案路徑和行號，而不是「認證模組」的一段摘要。
開啟被引用的檔案。跟著符號走。確認你即將觸碰的依賴關係。
只有到那時，才讓代理去打補丁。

如果第二步沒有傳回任何有用的東西，代理就沒有資格臨時編造一條路徑。它要麼再搜尋一次，要麼由你來指路。正是這一道關卡，產生了更少的幻覺編輯。模型還是同一個模型。變了的是地圖。

指令檔案依然重要。保留它們。用它們來記錄慣例、審查規則，以及不該觸碰的東西。不要要求它們充當索引。一個列出三個重要目錄的 CLAUDE.md，在一次套件拆分之後的那一週就會過時。而一張可查詢的地圖，會隨著儲存庫的更新而更新。

一個相關的失敗是「幾乎對」的檔案：當行為其實在 auth-client.ts 裡時，代理卻開啟了 auth.ts；或者補丁打在了一個生成的檔案上，而不是原始檔；或者因為名字匹配，編輯了 packages/legacy 裡的那份複製。引用不會讓這些錯誤變得不可能發生。它們只是讓這些錯誤在 diff 落地之前變得可見。

一張地圖不會為你修復的東西

對自己得到的東西保持清醒。一張有依據的地圖不會讓每一次編輯都變得正確——你的代理依然可能在完全正確的檔案裡寫出一個糟糕的補丁。如果你的程式碼庫依賴動態派發、反射或猴子補丁，一些符號查詢傳回的結果會比你希望的更單薄，因為執行時的間接性對任何靜態索引都會造成這種效果。而如果你在期待一個百分比——「幻覺路徑減少了 X%」——你在這裡找不到，因為除了你自己，沒有人能為你的儲存庫誠實地測出這個數字。

你可以期待的東西範圍更窄，也更有用：代理不再用一條猜測出來的路徑來開始它的編輯。這第一步會紮根於一張真實的地圖，而更少的幻覺編輯正是由此而來。引用之後的一切——閱讀 diff、判斷補丁——依然是你的工作，和以往一樣。

這個測試幾乎不花你什麼成本：索引一個你已經瞭解的儲存庫，問一個你能核實的問題。從一條曾經讓你吃過虧的路徑開始。如果引用錯了，你會立刻看出來。如果對了，你代理的下一次編輯就有了一個更好的落腳點。

// it doesn't know the file. it knows how to find it.

我們為何將程式碼搜尋升級至 voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

本文中的基準測試數字，反映發布當下（2026 年 6 月）的 RTEB 排行榜狀態。排行榜會變動，請將這些排名視為某一時間點的快照，而非永久不變的事實。

語意搜尋的品質，取決於其底層嵌入模型的品質。

當代理向 Maguyva 提問「我們在哪裡處理重試機制」時，它並不是在用 grep 搜尋「retry」這個字，而是在尋求意義 — 退避迴圈、斷路器，或是任何包裹了不穩定呼叫的機制。這個問題，是由一個向量模型負責回答的：它會把程式碼轉化為空間中的一個點，再找出相鄰的點。換一個更好的模型，產品中每一次語意查詢都會悄悄變得更精準。

因此我們換了模型。自 2026 年 6 月起，Maguyva 的程式碼嵌入運行於 voyage-4-large，取代了 voyage-code-3。

基準測試

我們做這個決定不是憑感覺。公開的檢索嵌入基準測試（RTEB）會依真實檢索任務為嵌入模型排名，而在其 Code 排行榜上，voyage-4-large 高居 總排名第一（90.86 分），領先 gemini-embedding-2-preview（90.26 分），也值得一提的是，領先了我們原本使用的模型 voyage-code-3（89.73 分，第 3 名）。

這是一個很小的絕對差距，但它是朝正確方向的差距，出現在一份公開的基準測試上，而且正是在我們最在乎的任務上：依意義檢索程式碼。

我們接受的取捨：二元量化

以下是多數「我們升級了模型」這類文章不會提到的部分。

Maguyva 並不儲存全精度向量，我們儲存的是二元量化後的嵌入：每個 2048 維的向量，會被壓縮成一個 2048 位元的簽章 — 每個向量僅 256 位元組。這些簽章會以漢明距離進行搜尋，並依租戶分別索引與分割。

這是一項刻意做出的取捨。二元量化犧牲了部分檢索精確度，換來大幅縮小的儲存空間，以及快速、低成本的距離運算，且不需要另外操作獨立的向量資料庫。對於一款每個工作區都要索引整個程式碼庫的產品來說，這樣的經濟效益，比在基準測試上多擠出最後一絲分數更重要。

voyage-4-large 完全契合這套設計，不需要強行遷移儲存層：它產生的輸出同樣是 2048 維，與 voyage-code-3 相同，因此我們的 bit(2048) 欄位與漢明距離搜尋路徑都不需要更動。模型變好了，結構描述則原封不動。

程式碼只是起點

Maguyva 是一款程式碼智慧工具，但我們自己同時也是「零號客戶」，並把它指向了另一種內容：與程式碼並存於我們儲存庫中的 Markdown 文件。架構決策紀錄、操作手冊、合約、財務與政策文件 — 全都以 Git 進行版本控管，全都藏在同一個 MCP 伺服器背後，是一份針對文件本身、而不只是原始碼的語意索引。

這正是為何 voyage-4-large 的廣度如此重要。在同一個 RTEB 系列排行榜上，它在金融領域排名第一、醫療保健領域排名第一，整體文字檢索也排名第一 — 領先 Google 的 Gemini Embedding、Cohere 的 Embed v4，以及 OpenAI 的 text-embedding-3-large。（Voyage 是 RTEB 的共同創建者之一，因此我們將這視為一項有力的公開訊號，而非完全中立的裁判結果 — 但它確實是在私有的保留測試集上，與每個主要商業模型正面較量得出的結果。）能為代理找到正確函式的那套索引，同樣也能找到合約中正確的條款、或政策中正確的那一行 — 而在這些領域，voyage-4-large 並非退而求其次的選擇，而是當之無愧的領先者。

我們為何願意為高階嵌入模型付費

搜尋還有更便宜的做法，而且很多都是免費的。詞彙搜尋 — BM25 及其同類方法 — 靠關鍵字比對，可在本機執行，完全不花錢。像 BGE、Nomic、embeddinggemma 這類開源嵌入模型，能提供貨真價實、還算不錯的語意檢索能力，你甚至可以只花一張 GPU 的錢就自行架設。Maguyva 也同樣運用這免費的一面：每一次查詢都會融合文字、AST、圖形與語意搜尋。我們唯一不肯省的，是語意這一層。

我們選擇按 token 計費、為高階嵌入模型 — voyage-4-large — 付費，而不是自架一個免費模型，原因有二。第一，當程式碼寫的是 backoff 和 circuit breaker、卻從未出現「retry」這個字時，單靠關鍵字搜尋根本回答不了「我們在哪裡處理重試機制」這個問題 — 掌握語意正是嵌入模型的核心價值，而在我們服務的這些領域中，開源模型確實落後於高階模型：在一般文字上落後個幾分，在程式碼、合約、金融這類利基領域則落後得更多。第二，就我們的經驗而言，檢索品質對最終答案的影響，遠大於另一端所使用的模型本身 — 一個強大的代理，若拿到錯誤的情境資訊，依然會答錯；而它從未被交付的文件，它也永遠看不見。

因此，高階嵌入模型是一筆隨著我們索引的每個儲存庫與每份文件而持續增加的按 token 計費帳單 — 而我們是刻意選擇支付這筆費用的。為了讓使用者得到正確的函式、或正確的條款這樣的結果，我們認為這筆取捨值得。

誠實的部分

Voyage 自家的文件，目前仍將 voyage-code-3 標示為程式碼最佳化模型。那我們為什麼還要換？

因為我們參考的是公開的基準測試，而不只是廠商自己的模型比較表，而基準測試顯示，在程式碼檢索上排名第一的是 voyage-4-large。這是一個前瞻性的決定：採用更新、整體表現更強的模型，並依公開排行榜、針對真正重要的任務加以驗證。我們之所以敢下這個賭注，是因為證據相當充分 — voyage-4-large 不只在程式碼上獲勝，在金融、醫療保健與整體檢索表現上也同樣領先。

那個默默支撐一切的基礎

我們對外提供的每一項工具 — 語意搜尋、任務情境蒐集、有憑有據的問答 — 最終都仰賴檢索作為基礎。當檢索器變得更好，另一端的代理就能得到更好的佐證、少走幾步冤枉路，並將答案扎根於正確的程式碼 — 或是正確的條款，或是正確的政策。更精準的嵌入模型並不是一項華麗的功能，它是支撐其他一切的基礎，而我們剛剛把它墊高了一些。你不會注意到這件事，而這正是重點所在。

語言遞迴自我改進：在近 280 種語言中打磨程式碼智慧

Tue, 26 May 2026 00:00:00 GMT

本文中的數字反映發布當下（2026 年 5 月）的系統狀態。目前最新數字請參見我們的團隊頁面。

Maguyva 會從大約 280 種語言的原始碼中擷取符號、參照關係與依賴關係圖。每種語言都對應一套自訂的 tree-sitter 處理器 — 查詢、啟發式規則、邊界案例 — 而每個處理器都可能以自己獨特的方式微妙地出錯：方法呼叫被誤判為讀取、函式被歸屬到錯誤的外層作用域、或是一段根本不存在的關係。

這種問題無法靠人力逐一稽核。沒有任何團隊能讀完橫跨 280 種文法的擷取輸出，並揪出其中的錯誤邊。因此，真正有意思的問題不是「我們的擷取結果正確嗎」，而是「在這樣的規模下，你要如何發現它出錯了，同時不必讓人力介入每一個迴圈」。我們的答案是語言遞迴自我改進：一套由語言代理驅動的品質迴圈，搭配擔任評審的 LLM，以及一條我們不斷重新學到的規則 — 綠燈不等於正確。

綠燈不等於正確

每種語言都有一套固定測試集，發布關卡會依五個面向為其評分 — 準確度、結構完整性、涵蓋度、品質與效能。唯有在固定測試集上精確率 ≥ 0.95、召回率 ≥ 0.99、F1 ≥ 0.97，且預期關係邊數至少達 20 筆以取得統計信心，該語言才會判為綠燈。低於此標準即為黃燈或紅燈，不予發布。

這道關卡是必要條件，卻不是充分條件。固定測試集是拿我們自己寫的測試案例來驗證，只涵蓋我們已經想到的情境。一個處理器可能在固定測試集上完美無瑕，卻在只出現於真實程式碼中的模式上出包 — 一個巨集慣用法、一個帶有泛型型別限制的方法、一個沒人為它寫過測試案例的語言特性。綠燈只代表固定測試集通過，不代表真實程式碼庫能乾淨地被擷取。所以這套迴圈必須跳脫固定測試集，正視真實世界的狀況。

內層迴圈：抽查、評審、修正、驗證

核心迴圈一次處理一種語言：

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

有幾個關鍵設計，讓這套機制真正發揮作用，而不是原地打轉。

評審者是代理本身，不是一次 API 呼叫。 我們所謂的「LLM 擔任評審」，指的是語言代理親自對照真實原始碼，逐一檢視每筆取樣的關係邊，並依固定的五類量規進行分類：這條邊是正確的、是誤判、關係正確但類型錯誤、歸屬到錯誤的作用域，還是攜帶了錯誤的中繼資料？這套量規正是整套機制的關鍵所在 — 在你知道「23% 錯誤率」究竟是真實缺陷還是評審誤判之前，這個數字毫無意義。

一次只修正一件事，然後證明它有效。 每次迭代只變更一項可編輯的資產，接著針對固定的測試機制重新執行，唯有 F1 分數提升、且重新分類結果變好時才保留這項變更；若沒有，就回復原狀。不做批次的臆測性修改，也不接受「應該會變好」這種說法。一項變更必須靠實績留下，否則就出局。而一旦修正真正站穩腳步，就會被納入固定測試集 — 讓它修正的錯誤再也無法悄悄重現。這一步「納入測試集」的動作，正是讓這套迴圈成為遞迴、而不只是重複的關鍵：每一輪都會強化下一輪據以驗證的基準。

我們不斷重新學到的教訓：指標會誇大問題

這裡有個陷阱，而我們就曾一頭栽進去。次要的語料庫指標 — 例如擷取出的目標有多少比例找不到可解析的符號、有多少符號看起來「孤立」等等 — 會大幅誇大問題的嚴重程度。這些多半是語言典範本身的產物，而不是真正的錯誤。

最清楚的例子是：llvm 曾一度顯示 73% 的「有來源卻無符號」比例，並因此被貼上「災難性」的標籤。我們深入追查後發現，真實準確度其實是 98.5%。那些「缺少的符號」幾乎全是合理的外部參照 — 呼叫標準函式庫、呼叫框架、或呼叫存在於程式碼庫之外的程式碼。這項指標量測的其實是該語言本身的特性，而不是處理器的缺陷。像 Zig、COBOL、Odin 這類語言都出現 65% 到 70% 的「孤立」比例，卻完全正確無誤 — COBOL 甚至沒有任何真實錯誤。

如果我們當初任由這些數字主導工作方向，恐怕會花上好幾週去「修正」原本就沒問題的處理器，同時忽略那些真正暗藏錯誤的語言。結論很直白：彙總指標充其量只是粗略的分診訊號。真正的品質訊號來自搭配關係邊分類的抽查 — 逐一檢視真實程式碼庫中的實際關係邊並加以判斷。用資料取代直覺沒錯，但前提是你得先知道哪些資料才是真話。

外層迴圈：靠艦隊，而不是靠一場馬拉松

若一次只處理一種語言，280 種語言跑下來將遙遙無期，因此內層迴圈外面還包了一層外層迴圈，讓多個語言得以平行處理。

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

每個代理都在一個用完即丟的工作樹中作業，彼此互不干擾。協調器會逐一整合各代理的修正，每一項都要通過完整清單的迴歸檢查：如果一項變更改善了自己的語言，卻悄悄弄壞了另外三種語言，就不會被採納。整合會先經過關卡把關、確認無誤，才會推送出去 — 迴歸關卡決定什麼是安全的，但要不要正式發布，仍由人來決定。之後，代理池會輪替到下一批語言，整套流程再跑一輪。

仍不完美之處

評審者也可能出錯，而且出錯是有方向性的：脈絡資訊不足的代理往往會誇大回報問題。曾有一批任務中，8 種語言被標記為 5% 到 20% 的錯誤率；深入檢視後，真正屬於該語言本身的錯誤只有一項 — 其餘都是評審者因未掌握該語言自身語意而產生的誤判（例如一行原始碼合理地產生多條關係邊、參數繫結被建模成賦值、以每個識別碼為單位建立參照關係的語言）。這正是我們以兩組不同種子取樣並交叉核對的原因，也是為什麼評審者與固定測試集之間出現分歧時，我們會將其視為最值得關注的訊號，而不是定論 — 有時候，出錯的其實是固定測試集本身。

我們對目標也很誠實。目標是零真實錯誤，一點都不打折 — 但「零」是我們一種語言接著一種語言持續打磨、朝其邁進的方向，而不是打勾了事的檢查項目。永遠會有下一個程式碼庫、帶著下一種慣用寫法。

靠實績贏得，而非憑空宣稱

Maguyva 為代理所做的每一件事 — 找出一個符號、追蹤一項依賴關係、以附上程式碼佐證的方式回答問題 — 都仰賴底層擷取結果的正確性。橫跨 280 種語言，「正確」無法憑空宣稱，必須不斷對照真實程式碼贏得。這套迴圈正是我們贏得正確性的方式：一個自主的抽查與修正循環，對自己產出的指標抱持懷疑，證明每一項變更確實有效，並讓每一次修正都成為抵禦下一次迴歸的守衛。這件事並不光鮮亮麗，卻是讓我們能夠說出「我們支援你的語言」、而且說到做到的那份工夫。綠燈很容易，正確得靠實績贏得。

多模態融合搜尋：為每個查詢挑選正確的檢索方式

Wed, 15 Apr 2026 00:00:00 GMT

歷史設計說明：這篇 2026 年 4 月的文章描述的是當時的路由設計，並非目前的預設行為。下方 9 月的更正僅針對一項測量聲明。關於目前的路由、預設組態與明確的檢索模態控制，請參閱運作原理。

搜尋查詢從來不是單一種東西。

「parseConfig 定義在哪裡」想要的是精確的符號 — 一個精準的位置，而且要快。「authentication 是如何運作的」想要的是意義 — 是能解釋一個概念的相關程式碼分佈全貌。「如果我修改這個函式會壞掉什麼」想要的是依賴關係圖。「找出字串 ECONNREFUSED」想要的是字面比對，不需要耍任何花招。

Grep 在字面比對上表現優異，對某些參照搜尋也很有用，但它不是依賴關係圖，也不理解意義。嵌入模型涵蓋了語意層面，但對精確字串比對與影響分析來說，卻是用錯了工具。多數程式碼搜尋工具只會選定一種引擎，讓每個查詢都得將就這個選擇。Maguyva 不做這種取捨，而是先判斷你提出的是哪一類問題，再依該問題應得的比例，混合四種檢索方式。

四種模式

在底層，有四種各自獨立的方式可以找到程式碼：

語意（semantic） — 對 Voyage 二元嵌入向量進行向量搜尋，依意義找出程式碼。
文字（text） — 三字元片段（trigram）比對，找出字面值、錯誤字串、精確識別碼。
結構（structural） — AST 查詢，找出定義、簽章與語言結構。
圖形（graph） — 依賴關係圖，找出呼叫端、被呼叫端與影響範圍。

每一種模式各擅長不同類型的問題，關鍵在於：針對眼前這個查詢，該給予每一種多少信任。

意圖分類

在任何檢索執行之前，一個輕量分類器會先將查詢歸入六種意圖之一，並附上信心分數。這個分類器刻意做得很精簡 — 依序套用啟發式規則，第一個命中者勝出 — 因為它運作在關鍵路徑上，只能增加一兩毫秒的延遲：

以 def 、class 、func 、import ⋯⋯ 開頭 → find_definition（信心 0.95）
「who calls」「usages of」「references to」→ find_references（0.90）
「impact」「blast radius」「what depends on」→ impact_analysis（0.90）
加了引號的 "string" 或像 traceback 這樣的錯誤相關詞彙 → exact_match（0.85–0.90）
一個 CamelCase 或 snake_case 形式的識別碼 → find_definition（0.60–0.80）
「how」「why」「explain」「architecture」→ understand_code（0.75）
都不符合 → understand_code，低信心（0.40）

每種意圖在四種模式上都有各自的權重設定，以下是實際數值：

意圖	語意	文字	結構（AST）	圖形
find_definition	0.2	0.1	0.6	0.1
find_references	0.1	0.2	0.2	0.5
understand_code	0.5	0.2	0.2	0.1
find_similar	0.4	0.3	0.2	0.1
impact_analysis	0.1	0.1	0.1	0.7
exact_match	0.0	0.9	0.1	0.0

因此「parseConfig 定義在哪裡」會大幅偏重 AST（0.6）；「auth 是如何運作的」會偏重語意向量（0.5）；「什麼依賴這個」幾乎完全倚重圖形（0.7）；「找出 ECONNREFUSED」則幾乎完全倚重三字元片段比對（0.9），並完全關閉嵌入模型 — 因為對精確字串來說，語意相似度正是用錯了工具。

快速路徑，以及融合路徑

當分類器信心足夠 — 分數 ≥ 0.85 — 且查詢屬於一般情形時，Maguyva 會完全跳過融合，直接路由到單一主導模式。「X 定義在哪裡」不需要四種檢索器，它現在就需要的是 AST 索引。這條直達路徑會回報為 fusion_strategy: "direct"。

其餘一切模糊不清的查詢，都會經過融合程序。四種（或在預設集下為三種）模式會並行執行，各自回傳自己的排名清單，再由我們加以整合。

加權版 Reciprocal Rank Fusion

融合異質的檢索器，比聽起來還要困難：0.82 的餘弦相似度、137 的三字元片段分數，以及 0.004 的圖形中心性，彼此並不在同一個量尺上，因此不能直接相加。Reciprocal Rank Fusion（倒數排名融合）繞過了這個問題 — 捨棄原始分數，只保留每個引擎所給出的排名。某項結果來自某一種模式的貢獻值為：

contribution = weight × 1 / (k + rank + 1)

其中 rank 是它在該模式清單中的位置，k 則是一個平滑常數。若某項結果被一種以上的引擎找到，各模式的貢獻值就會加總 — 檢索器之間的共識，自然會浮上頂端。我們在預設集中使用 k = 40，在 thorough 中則使用 60（quick 僅執行語意搜尋，因此融合機制在那裡從不啟動）。RRF 原始研究對一般用途檢索採用 k = 60；我們的預設值更偏重前列結果，讓多種模式都排在前列的結果獲得稍高的權重 — 而我們不建議手動調整這個數值。

除此之外，結果還會帶有一項圖形重要性加成。一個樞紐節點 — 整個程式碼庫都仰賴的函式 — 即使在相同的文字相關性下，也應該排在不起眼的葉節點之前，因此我們會將每項貢獻值乘以：

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

中心性數值來自管線預先計算好的 PageRank／度數指標，且此加成上限鎖定在 1.5 倍，避免一個熱門函式完全蓋過另一個相關性更高、卻較不起眼的函式。最後，我們會將來自 vendor、build 與 archive 路徑的結果降權，並針對每個檔案去除重複，只保留最佳片段。

仍不完美之處

意圖分類器是一組正規表示式，而不是經過訓練的模型。它以啟發式方法處理常見的查詢形式，遇到模糊的查詢時，會退回 understand_code 與偏重語意的混合檢索。本文的早期版本曾將無結果查詢比例從約 15% 降至低於 5% 描述為已實現的改善。實際上，2025 年 12 月的提案列出的是估計基準與目標，並未提供支持此結果的查詢集或測量紀錄。我們撤回這項已實現改善的聲明；參見來源證據與更正（英文）。我們尚未以訓練過的模型取代這個分類器，因為低成本版本對於預定的路由用途而言夠快、也夠好，而且一個自信卻錯誤的分類器，比一個坦誠的備援方案更糟。這些權重是手動選定的先驗值，並非從我們沒有收集的點擊資料中學習而來。

問問題，而不是選工具

代理不該需要自己判斷該用 grep、嵌入模型還是呼叫圖 — 它應該用直白的方式提出問題，並得到正確的答案。多模態融合，正是讓 find_symbol、語意搜尋與依賴分析，能共同藏身於單一查詢介面之後的原因：系統會讀懂問題的形狀，靜靜地為它組出正確的檢索方式。負責為嵌入向量評分的模型固然重要，但知道何時不該使用它們同樣重要。為每個查詢挑選正確的工具，本身就是一種品質，而這正是我們寧可自己扛下、也不願丟給呼叫端處理的事。

// you bring the question. it brings the tools.

代理可觀測性：Hooks、Alloy 與 Grafana

Tue, 24 Mar 2026 00:00:00 GMT

代理系統會以各種奇怪的方式失敗。

有時問題出在模型本身，有時出在工具，有時你的 MCP 伺服器一切正常，但代理選錯了專家、或是把半個工作階段都花在你意料之外的殼層操作上、又或是在一個表面上看起來很有生產力的迴圈中悄悄燒掉預算。

如果你看不出這些差異，你就不是真的在「操作」一套代理系統，你只是在瞎猜。

因此我們為自己的工作流程打造了一套可觀測性技術堆疊：Claude Code、Codex、Claude 的 hook 事件、Codex 的 notify 事件、原生 OpenTelemetry、Grafana Alloy，以及另一端的 Grafana Cloud。

真正有趣的地方，不是「我們做了一個儀表板」，而是我們必須把遙測資料拆成兩條不同的串流，因為沒有任何單一資料來源能給我們完整的全貌。

問題所在：代理遙測資料是零散的

現代程式開發代理已經會發出一些遙測資料，這有幫助，但還不夠。

原生 OTEL 很擅長回答這類問題：

我們發出了多少次請求？
一個工作階段花費多少成本？
span 與 trace 分布在哪裡？
延遲是否飆高？

但它在回答這類問題時就弱得多：

代理倚重了哪個 MCP 伺服器？
這次失敗是出在 Bash、某個內建檔案工具，還是某次 MCP 呼叫？
實際觸發的是哪個技能？
被派出去的是哪一類子代理？
這個工作階段究竟是在做有用的工作，還是原地空轉？

第二類問題，比較貼近 hook，而不是 trace。

但反過來說也成立：一些最重要的效能問題，反而更貼近 trace，而不是 hook。

如果你想知道延遲究竟累積在哪裡、哪些 span 拖慢了速度、或工作階段的時間究竟花在模型呼叫還是工具執行上，你同樣需要 trace 資料，而不只是語意事件。

我們最終採用的架構

我們並行運作兩條遙測路徑。

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

這樣的拆分是刻意設計的。

它同時也是不對稱的。Claude Code 提供了豐富得多的生命週期 hook 介面；Codex 提供的則是原生 OTEL 加上一個 notify 介面，因此我們會將較單薄的回合完成事件正規化進同一套日誌結構描述，而不是假裝兩個執行環境提供了相同的控制能力。

原生 OTEL 提供了基準串流：來自執行環境本身的日誌與 trace，以及該環境確實會發出的指標。

Hook 與 notify 事件 提供了語意層：像是 PreToolUse、PostToolUse、PostToolUseFailure、UserPromptSubmit、SubagentStop、SkillActivated，以及我們在除錯代理行為時真正在乎的分類後中繼資料。這部分較豐富的事件串流由 Claude Code 提供，Codex 則提供較單薄、但仍然有用的正規化串流。

Hook 存在的理由

我們的 hook 管線會在事件抵達 Loki 之前先加以擴充。

我們不會只說「有一個工具執行了」，而是會將事件分類到以下這些欄位：

tool_type：builtin、mcp、skill、agent、bash
mcp_server：由哪個 MCP 後端處理這次呼叫
bash_cli：殼層指令的類型
subagent_type：派出的是哪一類專家
agent_tool：來源是 Claude Code 還是 Codex

這代表我們能提出真正具有營運意義的問題：

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

這些都不是花俏的欄位，它們正是「這個代理感覺變慢了」與「這個代理過去十分鐘都花在殼層密集的 git 操作上，而且工具失敗率偏高」之間的差別。

有一個看起來比實際情況更奇怪的實作細節：即使事件來自 Codex，共用的 Loki 串流仍會使用 service_name="claude-code-hooks" 作為標籤。執行環境之間真正的區分，發生在 agent_tool 上。

為何 Alloy 位居中樞

在這套系統中，Grafana Alloy 不只是一個轉發器，而是套用遙測處理規則的關卡。

我們將來自 Claude Code 與 Codex 的原生 OTEL 串流，指向 localhost:4318 上的一個本機 Alloy 代理，讓 Alloy 先清理過酬載內容，才轉發給 Grafana Cloud。

這一點很重要，因為原始的代理遙測資料，充斥著對分析有用、卻極不適合當作已索引標籤的高基數欄位：

session_id
prompt_id
token 數量
耗時
工具參數區塊

如果你把每樣東西都索引起來，就會遇上標籤爆炸，然後迎來悲慘的一天。

所以 Alloy 為我們做了三件事：

只讓一小組低基數標籤維持索引狀態。
把雜訊多、但仍有用的欄位移進結構化中繼資料。
徹底捨棄純粹的雜訊。

背後的核心理念很簡單：觀察得更多，索引得更少。

為何 Hook 串流會繞過 Alloy

Hook 串流本身早已針對 Loki 塑形完成。

在 send_event.py 推送一筆事件之前，我們早已決定好哪些欄位值得當作標籤處理、哪些該歸入結構化的 JSON 內容主體。這條串流會直接送往 Grafana Cloud 的 OTLP 閘道，不會再經過 Alloy。

因此整套系統的分工非常清楚：

Alloy 馴服原始的原生 OTEL 串流。
Hook 擴充 讓語意事件變得可查詢。

這讓整體架構，比起硬要把所有東西塞進同一條路徑，簡單得多。

儀表板實際呈現了什麼

下方的截圖，取自支撐我們代理工作流程的其中一個可觀測性儀表板。它不是一次基準測試，這些數字也只是某個時間點的切片。重點在於資料的樣貌：活動動態、工具呼叫、失敗紀錄、提示內容，以及依代理、內建工具、MCP 使用情形、殼層指令與技能所做的細分。

真正有用的地方，在於這個儀表板與其餘代理遙測資料，共用同一套 Grafana 技術堆疊。我們可以依來源代理與工具類別篩選，橫跨不同執行環境查看，而不必為每套系統另外發明一套可觀測性敘事。

支撐我們代理工作流程的其中一個即時儀表板。這張截圖只是共用 Grafana 技術堆疊中的一個切片，這套技術堆疊同時也接收來自我們其他代理執行環境與系統的遙測資料。點選圖片可查看完整解析度版本。

為何 Trace 比表面上看起來更重要

日誌告訴我們發生了哪一類工作，Trace 則告訴我們這項工作是如何隨時間展開的。

這個區別在代理系統中格外重要，因為「慢」這個詞太籠統，派不上什麼用場。

一筆 trace 能告訴我們，痛點究竟來自：

模型延遲
工具執行時間
重複重試
某一次特別昂貴的 MCP 互動
一長串個別看起來無害、加總起來卻拖慢速度的小型操作

實務上，我們會同時運用 hook 串流與 Tempo trace。

Hook 日誌 回答：發生了什麼類型的事？
Trace 回答：時間都花到哪裡去了？

正是這樣的組合，讓可觀測性從一個儀表板，變成一份真正的解釋。

Codex 適合放在哪裡

Codex 是同一套技術堆疊的一部分，但它與 Claude Code 並不完全相同。

針對 Codex，我們接入了兩個部分：

來自 Codex 的原生 OTEL 資料，接入 Alloy
一個 notify webhook，接入 codex_notify.py，將回合完成事件對應到我們用於 hook 事件的同一套 Loki 結構描述

這讓我們能在同一條日誌串流中，使用像 agent_tool="codex-cli" 這樣的統一篩選條件。

誠實地說，Codex 目前的 notify 酬載，內容仍比 Claude Code 的 hook 酬載單薄，因為它並非同一種整合介面。以我們目前的設定來說，Codex 的回合完成事件可以被正規化進共用的結構描述，但逐一工具層級的豐富擷取，目前仍然是原生 OTEL 串流做得比 notify 橋接更好。

這並不是要迴避這篇文章要談的重點，反而正是重點所在：真正的可觀測性系統，是由不完美的訊號拼組而成的。

透過 MCP 使用 Grafana，改變了整個局面

更大的轉變在於，Grafana 不再只是人類用瀏覽器造訪的地方。

在這個儲存庫中，我們同時透過 MCP 提供 Grafana 的存取介面。這代表代理可以直接查詢 Loki、Prometheus 與 Tempo，而不必等人類先手動檢視儀表板。

這讓可觀測性從被動的回報介面，變成了工作流程的主動輸入。

代理可以提出這樣的問題：

過去一小時裡，哪些工具類別失敗最多？
哪個 MCP 伺服器主導了某個工作階段？
近期的變更究竟減少了工具失敗，還是只是把同樣的錯誤，搬到了更依賴殼層的路徑上？
哪些 trace 顯示出最高的延遲，或反覆重試？

一旦擁有這些能力，你就已經非常接近一套自我改進迴圈了。

從儀表板到回饋迴圈

這是我們認為最有意思的部分。

一旦可觀測性技術堆疊可以從代理層級被查詢，遙測資料就不再只是被動的回報介面，而會變成一種控制訊號。

這個迴圈的樣貌如下：

代理活動產生 trace、指標，以及擴充後的 hook 日誌。
Grafana 將這些證據儲存在 Loki、Tempo，以及有指標存在的 Prometheus 中。
代理透過 Grafana MCP 查詢這些證據。
系統辨識出不良的工具組合、脆弱的技能、薄弱的路由，或不斷產生可避免錯誤的殼層密集工作流程。
代理或操作者調整提示、代理的設定、技能說明、路由規則，或工具存取權限。
下一個工作階段會產生新的遙測樣貌，循環繼續進行。

這正是從「有趣的儀表板」邁向「可衡量的改進系統」的方式。

目標並不是把某一類工具的使用量最大化，而是為實際進行的工作，找出 CLI、內建工具、MCP 呼叫與技能之間正確的比例組合。

這讓我們能回答哪些問題

一旦兩種執行環境都落在同一套 Grafana 技術堆疊中，我們就能更快回答營運面的問題：

失敗是否集中在某一個工具類別？
依賴殼層的工作流程，是否正在造成本可避免的錯誤，而其實該有更高階的工具存在？
哪些 MCP 伺服器承擔了大部分工作量？
我們是否正在為沒有產生實質進展的代理活動付費？
一個工作階段不健康，究竟是因為模型、工具，還是協調層本身？

這在多代理工作流程中格外有用，因為「代理很忙」這句話幾乎什麼都沒說明。

如果某一位專家不斷被派出去、卻不斷產生高失敗率，那就是路由或提示設計上的問題。

如果某個 MCP 伺服器主導了所有呼叫，這可能代表架構良好，也可能代表其他部分全是多餘的負擔。

如果工具失敗率飆升、成本卻居高不下，那就是營運面的問題，而不是品質問題。

如果殼層工作持續以可預期、本可避免的方式失敗，而其實該有更高階的工具存在，那就是一個產品訊號。

如果某個技能不斷被觸發、卻沒有改善結果，那就是提示或路由訊號。

真正的教訓

這裡更深層的教訓在於：代理可觀測性同時需要執行環境遙測與工作流程遙測。

執行環境遙測告訴你系統做了什麼。

工作流程遙測告訴你代理「以為」自己在做什麼。

兩者我們都需要。

如果你只保留 trace 與計數器，你就會錯過語意層；如果你只保留 hook 事件，你就會錯過延遲、span，以及更完整的執行環境全貌。

而如果你兩者都保留，卻從未將其回饋給代理層，你得到的只是監控，而不是調適。

正是這樣的組合，讓整套系統既足夠可解釋以供操作，也足夠可調整以持續改進。

仍不完美之處

仍有一些粗糙的邊角。

並非每個 hook 事件都包含我們希望有的耗時與 token 資料。
有些最好的時間分析視角，仍來自 Tempo trace，而不是 hook 日誌。
在擴充後的事件串流中，Codex 目前在語意豐富度上仍不及 Claude Code。
這張儀表板截圖，是一個真實的營運介面，而不是一件精心打磨的行銷素材。

最後這一點是刻意為之的。我們寧可展示真實的儀表面板，也不願假裝代理系統會神奇地自我解釋一切。

這對 Maguyva 為何重要

Maguyva 的核心，是要為代理提供更好的程式碼智慧。但一旦代理真正開始做有用的工作，一項新的需求會立刻浮現：你需要看見它們的行為表現。

搜尋品質、路由品質、工具選擇，以及情境使用效率，全都會變成可觀測的問題。

這正是我們認為值得寫下這篇文章的原因。未來的代理技術堆疊，不會只是提示與工具，而是提示、工具，再加上告訴你這整套機制是否真正運作正常的監測層。

如果你正在認真打造代理工作流程，可觀測性就不是可有可無的基礎設施，它就是產品本身的一部分。

挖掘迴圈：變更如何化為組織記憶

Tue, 03 Feb 2026 00:00:00 GMT

本文中的數字反映發布當下（2026 年 2 月）的系統狀態。目前最新數字請參見我們的團隊頁面。

每個工程團隊都面臨同樣的難題：變更不斷發生，但這些變更背後的原因卻不斷流失。六個月後，有人問「我們當初為什麼在 pipeline 各階段採用 DuckDB？」而答案只存在於當初做出這個決定的人腦中 — 前提是那個人還在團隊裡。

我們打造了一套挖掘工作流程，補上了這個缺口。變更透過 git 提交流動，經我們的挖掘管線處理後，化為結構化的變更日誌條目與架構決策紀錄，再透過 CLI 查詢回饋給我們的 AI 代理。結果就是：人類與 AI 都能存取的組織記憶。

問題所在：決策會蒸發

想想一個典型情境。某位開發者提交了：

feat(canonical): add DuckDB runtime for pipeline stages

這筆提交代表了一項重大的架構抉擇。團隊評估了多個選項、權衡了各種取捨，最終基於特定原因選擇了 DuckDB。但這些脈絡全都存在於：

某個 Slack 討論串中（大概已經被刪掉了）
某人的記憶裡（肯定正在淡去）
程式碼中的一則註解（也許有，如果你夠幸運的話）

三個月後，一位新加入的團隊成員問道：「這個新階段該用 DuckDB 還是 SQLite？」若沒有組織記憶，他們要嘛重新發明輪子，要嘛做出不一致的選擇。

這個迴圈：從提交到情境

我們的挖掘工作流程，會將 git 歷史轉化為可查詢的知識：

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

關鍵洞察在於：變更日誌與架構決策都源自同一份 git 歷史，經由統一的管線處理。這確保了不會有任何內容遺漏。

挖掘機制如何運作

步驟一：同步索引

uv run orkestra mine sync

此指令會掃描 git 歷史，為所有提交建立索引，並從每筆提交中擷取結構化訊號：

Conventional Commits 提交類型（feat、fix、chore、docs）
範圍（屬於哪個套件或領域）
不相容變更標記
異動檔案與複雜度指標

步驟二：檢查涵蓋率狀態

uv run orkestra mine status

我們目前的狀態如下：

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

已處理 15,637 筆提交，其中 476 筆成為架構決策，6,799 筆成為變更日誌條目，每一筆提交都已完成分類。

步驟三：取得待審核候選項目

uv run orkestra mine candidates --limit 50 --full

這會列出尚未處理的提交，並附上供分類使用的完整脈絡：

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

這些訊號有助於引導分類：is_releasable_type: true 顯示這應該出現在變更日誌中；較大的新增行數與基礎架構檔案，則顯示它也可能是一項架構決策。

步驟四：為提交分類

從這裡開始分成兩條路徑：變更日誌條目，以及架構決策。

針對變更日誌條目：

uv run orkestra mine classify abc123 --changelog added

這會記錄提交 abc123 應出現在變更日誌的「新增」類別下。

針對架構決策：

首先，取得一個真實的決策編號：

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

接著使用該決策編號進行分類：

uv run orkestra mine classify abc123 --decision DEC-PL-143

這會將該提交連結到一份即將建立或更新的決策紀錄。

針對批次處理（我們實際採用的方式）：

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

JSONL 格式讓兩種領域能一次處理完成：

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

步驟五：渲染輸出

uv run orkestra registry changelog render --package <pkg>

這會依帳本內容產生各套件專屬的 CHANGELOG.md 檔案。變更日誌屬於衍生產物 — 就算刪除它們，也能從來源帳本完美重新生成。

決策紀錄的結構

擷取出的決策會化為附帶豐富中繼資料的 YAML 檔案：

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

每項決策都會回連其來源提交，每項決策都會指明其影響的檔案，決策彼此之間的關係也都明確標示。

CLI 整合：查詢組織記憶

這正是迴圈閉合之處。代理可以透過 CLI 查詢決策：

# Search by topic
uv run orkestra registry decisions search --query "retry"

回傳與重試邏輯、錯誤處理、復原模式相關的決策。

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

回傳包含情境、理由與影響的完整決策紀錄。

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

顯示近期做出了哪些架構抉擇。

代理如何運用這套機制

我們協調器的基準指令中包含：

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

當代理被要求實作與 DuckDB 相關的內容時，它可以先檢查：

uv run orkestra registry decisions search --query "DuckDB"

並發現 DEC-PL-142，從中了解：

我們為何選擇 DuckDB（脈絡）
該如何正確使用它（代理指引）
該查看哪些檔案（檔案）
有哪些相關決策（相關項目）

代理不必重新發明輪子，而是能在既有模式的基礎上繼續建構。

三問測試

並非每筆提交都值得建立決策紀錄，我們以「三問測試」來篩選：

這個決定當初難做嗎？ 是否需要大量分析、取捨評估或討論？
改變它的代價高嗎？ 若要推翻這項決策，是否需要大幅重做？
它是否具有全系統層級的影響？ 是否影響多個套件，或建立了其他人將遵循的模式？

只要一筆提交對這三個問題中至少一項回答「是」，就是決策擷取的候選對象。我們的一般比例是：每 100 筆提交約產生 1 到 4 項決策（約 1% 到 4%）。

至於變更日誌條目，門檻較低：任何面向使用者的變更（功能、修正、改善）都會被記錄下來；內部雜務、文件更新與重構通常會被略過。我們的一般比例是：每 100 筆提交約產生 30 到 50 則變更日誌條目。

資料儲存：僅可附加的帳本

挖掘系統採用僅可附加（append-only）的 JSONL 帳本，以支援無衝突的多代理作業：

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

這種採用 merge=union 合併設定（記錄於 .gitattributes）的 JSONL 格式，代表多個代理可以同時為提交分類，而不會產生合併衝突 — 每一行都是獨立的。

驗證關卡

在任何一次挖掘作業開始前，我們都會執行驗證：

uv run orkestra mine validate --quick

此驗證會檢查：

SHA 格式是否有效
決策編號格式是否符合規範
同一個 SHA 是否有重複項目
所參照的決策是否確實存在

分類完成後，我們會在提交變更前再次驗證。

為什麼這很重要

我們建構的這個回饋迴圈，解決了幾項問題：

對新進團隊成員而言： 他們不必再問「我們當初為什麼這麼做？」，而是可以直接搜尋決策登錄檔，脈絡都被完整保留。

對 AI 代理而言： 它們不必在真空中運作，可以在提出建議前先查詢組織知識。當被要求新增一個 pipeline 階段時，它們能發現 DuckDB 這項模式，並依循它。

對架構一致性而言： 決策是明確且可搜尋的。當有人提出與既有決策相牴觸的做法時，系統能夠揭露這項衝突。

對變更日誌生成而言： 發布說明不再是最後一刻的臨時拼湊，而是開發過程中持續分類所產生的副產品。

對新人上手而言： 新進代理會繼承程式碼庫的完整脈絡。它們看到的不只是程式碼本身，還有塑造出這些程式碼的種種決策。

目前狀態

截至目前為止：

已透過此管線處理 15,637 筆提交
已擷取並記錄 476 項架構決策
已記錄 6,799 則變更日誌條目
兩個領域的涵蓋率皆為 100%

自我們開始執行以來，每一筆提交都已完成分類，組織記憶完整且可查詢。

開始使用

若你想實作類似的機制：

從 Conventional Commits 格式開始。 當提交具備結構化前綴（feat:、fix:、chore:）時，挖掘管線的效果最好。
定義你的領域。 我們使用像 pipeline、agent-design、observability、data-modeling 這樣的領域，用以依區塊整理決策。
養成分類的習慣。 當團隊定期為提交分類時，挖掘機制才會奏效；搭配 LLM 協助的批次處理，有助於擴大規模。
讓決策可被查詢。 當代理能透過 CLI 搜尋決策時，其價值會不斷複利累積；請將輸出結構化，以利機器讀取。
閉合這個迴圈。 決策應該影響未來的工作，請在代理指令與程式碼審查檢查清單中納入決策參照。

目標並非追求完美的文件，而是讓變更背後的原因，無論是今天還是六個月後，都能讓人類與 AI 同樣觸手可及。當變更化為組織記憶，團隊便能在既有模式的基礎上持續建構，而不必一再重新發明。

這套挖掘工作流程是我們協調引擎的一部分，具體來說，屬於我們協調套件中的情境引擎模組。

技能挖掘：從 3,500 個候選項目到 466 項能力

Tue, 27 Jan 2026 00:00:00 GMT

本文中的數字反映發布當下（2026 年 1 月）的系統狀態。目前最新數字請參見我們的團隊頁面。

3,500 項技能的難題

當我們開始打造代理協調系統時，遇到了一個有趣的挑戰：整個 AI 生態系中散落著成千上萬個潛在技能。GitHub 儲存庫、廠商文件、社群專案、內部經驗模式 — 技能無所不在。但哪些才真正重要？哪些真的有效？又該如何維護一套代理真正能派上用場的一致技能庫？

我們的答案是：一套系統化的挖掘與導入迴圈。

今天的數字

在 Anthropic 於 2025 年 10 月 16 日推出 Agent Skills 剛滿三個多月後，本文於 2026 年 1 月 27 日發布時，我們的現況如下：

指標	數量
已識別候選項目	3,500+
已採納技能	466
廠商技能	373
內部技能	93
活躍廠商	25+
每項技能平均 token 數	2,834
參照工具數	89
不重複標籤數	635

我們審核了超過 3,500 個技能候選項目，最終採納了 466 項，採納率為 13% — 這樣的高度篩選是刻意設計的結果。

知識分層系統

並非所有技能生而平等，我們將它們組織成五個知識層級（K0 至 K4），各自代表不同的適用範圍：

K0：基礎（通用）

每個代理都應具備的技能，代表能在任何地方都適用的「優秀思考者」能力。

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

K0 技能可移植到任何專案、任何領域、任何技術堆疊，它們編碼的是通用的認知模式。

K1：身份（專業領域）

「優秀工程師」或「優秀研究者」等，適用於某一學科內各個專案的技能。

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2：領域（專業知識）

「優秀的資料庫專家」或「優秀的安全工程師」等，可在某一領域內移植的技能。

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3：技術堆疊（技術）

「優秀的 Supabase 使用者」或「優秀的 Cloudflare 開發者」等，針對特定技術堆疊的技能。

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4：專案（組織）

專屬於我們組織與工作流程的技能。

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

挖掘迴圈

第一階段：發現

技能來自四面八方：

廠商儲存庫：AWS、Anthropic、Cloudflare、Supabase 以及社群貢獻者，都會發布技能集合，我們追蹤超過 25 個廠商根目錄。

社群專案：GitHub 上充滿了 Claude Code 範本、代理模式與工作流程定義。

內部經驗模式：隨著我們團隊解決問題，各種模式會逐漸浮現，並被正式化為技能。

文件挖掘：技術文件中經常隱含著技能 — 程序、檢查清單、決策樹。

發現過程持續不斷，我們會用一份技能待辦清單，在正式評估之前追蹤候選項目。

第二階段：評估

每個候選項目都會經過同一套量規：

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

五項產品標準必須全數通過，這正是 87% 的候選項目遭到否決的原因。

接著，每個候選項目還會經過一次獨立的信任審查。我們不會把官方廠商儲存庫、知名的社群維護者，以及隨機的 GitHub 儲存庫，視為同等可信的來源。

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

受信任的廠商能獲得較輕量的來源審查，但這不代表可以免審通過。不受信任或來源不明的技能，則會經過更深入的人工稽核，而且在腳本被讀過、確認範圍、並歸類為安全之前，我們絕不會執行隨附的腳本。

缺口分析：在採納之前，我們會先搜尋自己的登錄檔：

uv run orkestra skills search "<capability>"

如果我們已經有了，就不需要再採納；如果我們有相近的東西，我們可能會選擇合併，而非直接採納。

深度與規範評分：我們也會為候選項目對代理技能模型的運用完整度評分。單一的 SKILL.md 依然可能有用，但若能依照 agentskills.io 所鼓勵的方式，將指令與參考資料、腳本、素材分開，技能就會更有價值、更深入。

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

GitHub 星數可以稍微提升可信度分數，但永遠救不回一個膚淺或不安全的技能。一個星數很高、卻只有一份內容含糊的 SKILL.md 和不透明腳本的儲存庫，其分數會低於一個規模較小、卻擁有精確說明、精心整理的 references/、以及真正充分運用技能完整能力的原子化輔助工具的儲存庫。

結構分析：我們會檢查技能的品質：

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

若候選項目包含腳本，審查就會更加嚴格。一項好的技能不只要有用，還必須清晰易讀、範圍受限，且能安全地交給代理使用。光是這道安全篩選，就足以刷掉相當一部分原本看起來頗有意思的候選項目。

第三階段：導入

當一項技能通過評估後，就會進入登錄檔。但技能從不會原封不動地被採納，而是會經過調整以符合我們的系統。

採納時的調整：

中繼資料正規化：每項技能都會套用我們的前置資料結構描述
K 層級指派：技能會被歸入適當的知識層級
標籤擴充：加入標籤以利於被發現
工具宣告：明確宣告允許使用的工具
章節對齊：內容會被重新組織，以符合我們的範本

導入後典型的技能 YAML 範例如下：

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

第四階段：範圍指派

技能會被指派到「範圍」— 決定哪些代理會載入哪些技能的分類：

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

代理會宣告自己的範圍，技能則會自動被指派：

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

第五階段：實體化

技能在正式環境中並非以 YAML 形式存在，而是會被渲染為 Claude Code 能夠載入的 SKILL.md 檔案：

uv run orkestra sync

這個指令會：

讀取所有技能的 YAML 定義
透過 Jinja 範本進行渲染
將 SKILL.md 檔案寫入 .claude/skills/
依 K 層級組織（foundations/、identities/、domains/、stacks/、project/）

最終的輸出結構如下：

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

休眠範圍模式

我們最強大的模式之一，是「已採納但未載入」的技能，我們稱之為休眠範圍。

以來自 k-dense-scientific 儲存庫的科學運算技能為例：我們已採納超過 120 項技能，涵蓋生物資訊學、化學、量子運算與臨床資訊學。但我們大多數代理並不需要分子對接或基因表現分析。

我們並不會把全部 120 項技能都載入每一個代理（那會撐爆情境視窗），而是：

以特定範圍（例如 bioinformatics）採納這些技能
讓它們保持休眠 — 已登錄但未載入
只在代理宣告該範圍時才啟用它們

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

這個模式讓我們的登錄檔中能容納 466 項技能，而一般代理卻只會載入其中 40 到 60 項相關的技能。

技能類型

技能有三種認知模式：

工作流程

有序的程序性步驟：「1. 做 X，2. 接著做 Y，3. 最後做 Z」

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

紀律

行為護欄：「務必做 X」「絕不做 Y」「優先選擇 Z」

type: discipline
# Examples: test-first-discipline, evidence-based-completion

檢查清單

驗證標準：「確認 X」「驗證 Y」「檢查 Z」

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

品質關卡

每項技能在發布前都必須通過驗證：

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

說明文字必須介於 50 到 400 字元之間，並包含觸發語句（例如「Use when…」「When you need…」），讓 Claude Code 知道何時該建議使用它。

我們會持續進行驗證：

uv run orkestra validate --show-warnings

廠商生態系

我們的 373 項廠商技能，來源如下：

廠商	技能數	領域
AWS Agent	19	雲端服務
Anthropic	12	文件生成
Cloudflare	8	邊緣運算
Supabase	5	資料庫
k-dense	100+	科學運算
silvainfm	4	資料科學
Java Developer Kit	45+	Spring／Java
Vercel	1	瀏覽器自動化

每個廠商根目錄都會在 metadata.yaml 中宣告：

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

當 orkestra sync 執行時，廠商技能會依各自的廠商命名空間，以符號連結方式連進 .claude/skills/vendor/。

我們學到的事

高度篩選有其回報。 把每個看起來有用的東西都採納進來，是很誘人的做法，但每項技能都要耗費 token。以平均每項技能 2,834 個 token 來說，膨脹的代價很快就會浮現。我們 13% 的採納率，讓代理保持精簡。

結構能促進發現。 K 層級系統不只是為了分類，更關乎可移植性。K0 技能可以在任何地方重複使用；K4 技能則刻意侷限於特定專案。這樣的清晰度，讓人類與代理都能更容易找到自己需要的東西。

休眠範圍具備擴展性。 你可以採納數百項技能，卻不必全部載入。範圍機制讓你能建立一套涵蓋全面的登錄檔，同時讓每個代理各自的情境視窗維持在可管理的範圍內。

採納時的調整不可或缺。 未經處理的原始廠商技能，很少能直接契合你的系統。導入流程 — 加入中繼資料、指派層級、擴充標籤 — 讓外部技能得以在內部順利運作。

挖掘是持續進行的。 3,500 這個數字仍在持續成長：新的廠商儲存庫不斷出現，社群模式不斷浮現，內部工作流程也不斷成形。這個迴圈永不停止。

接下來的計畫

我們正在推進幾項改進：

自動化缺口偵測：當常見的代理失誤本可透過某項尚未採納的技能解決時，發出警示
技能淘汰流程：為已被取代或不再使用的技能，建立正式的退役程序
跨技能依賴關係：明確宣告技能之間的前置需求
使用分析：追蹤代理實際呼叫了哪些技能，而不只是載入了哪些

技能挖掘迴圈是一種基礎建設，並不光鮮亮麗，但正是它，讓 41 個代理能在情境限制內，與 466 項能力協調一致地運作。

這就是 3,500 如何變成 466 的故事：不是靠忽略其中的 3,000 個，而是靠系統化地逐一評估、只採納真正有效的那些。

想親眼看看這套技能系統實際運作嗎？歡迎查看 uv run orkestra skills list，探索我們目前的登錄檔。

漸進式揭露：透過 CLI 窺探代理系統

Tue, 20 Jan 2026 00:00:00 GMT

本文中的數字反映發布當下（2026 年 1 月）的系統狀態。目前最新數字請參見我們的團隊頁面。

代理系統在設計上本就不透明。它們會做決策、呼叫工具，並協調數十位專家之間的工作。但當出了問題 — 或你單純只是想了解目前發生了什麼事 — 該從哪裡著手查看？

答案是漸進式揭露：一種分層介面，恰好在你需要的時候、揭露恰好足夠的複雜度。

不透明的問題

一套現代的代理協調系統，可能包含：

超過 40 位各具能力的專家代理
超過 700 項技能，涵蓋內部自動化與第三方整合
超過 470 項塑造行為的架構決策
數十個提供外部能力的 MCP 工具伺服器

這樣的複雜度是刻意設計的：代理需要取用豐富的情境資訊 — 領域知識、程式碼智慧、資料庫結構描述 — 才能做出好的決策。但這份豐富度，同時也帶來了能見度的問題。

你怎麼知道哪個代理負責處理資料庫遷移？哪些決策塑造了搜尋系統的排名行為？架構顧問代理又能取用哪些工具？

若沒有結構化的存取方式，你就只能翻讀原始碼，或是祈禱文件仍是最新的。

將漸進式揭露視為一種架構

漸進式揭露不只是一種 UI 模式，而是一項架構原則：將資訊分層組織，一層比一層深入，讓使用者能在剛好回答出自己問題的那一層停下來。

對代理系統而言，這化為深度遞增的一系列 CLI 指令：

層級	指令	回答的問題
1	`orkestra system status`	一切是否健康？
2	`orkestra agents list`	有哪些代理存在？
3	`orkestra agents info <name>`	這個代理做什麼？
4	`orkestra decisions search`	為什麼它是這樣運作的？
5	Maguyva MCP 工具	讓我看看程式碼。

每一層都回答了一個自然而然的後續問題，你很少需要直接跳到第五層。

第一層：系統健康狀態

第一個問題永遠是：一切都在正常運作嗎？

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

一個指令、四個數字，就足以知道系統設定完成、各登錄檔也都已經填入資料。

若代理數量意外下降、或技能載入失敗，你會在這裡第一時間看到，不需要翻找日誌。

第二層：代理清單

一旦確認系統健康，下一個問題是：有哪些可用？

$ orkestra agents list

這會回傳結構化資料 — 代理名稱、說明、模型偏好、涵蓋領域。輸出預設為 JSON 格式，可輕鬆透過管線送入 jq 進行篩選：

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

想找出負責資料庫工作的代理？搜尋指令可以幫你縮小範圍：

$ orkestra agents search "database"

它會掃描名稱、說明與能力，讓你不必讀完 40 份代理定義，就能找到對的專家。

第三層：代理深度檢視

找到一個看起來相關的代理了？info 指令會揭露所有細節：

$ orkestra agents info architecture-advisor

輸出內容包括：

中繼資料：名稱、類別、模型偏好、說明
領域：這個代理涵蓋哪些知識領域
身份：性格特質（架構師、策略家、知識架構師）
工具指南：哪些工具文件會被注入情境
工具：這個代理可用的完整 MCP 工具清單

以下是你會看到的內容範例：

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

這會準確告訴你這個代理能做什麼，完全不需要查看原始碼。

第四層：決策考古

代理會依照已記錄的決策行事。當你需要理解某件事為什麼是這樣運作時，決策登錄檔就是最終真實來源。

$ orkestra decisions search "agent"

這會回傳相符的架構決策：

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

每項決策都具備完整的溯源資訊 — 何時做出、為何做出、考量過哪些取捨、由哪些提交實作：

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

這是一份能持續保持最新的架構文件，因為它是從提交中挖掘出來的，而非人工手動維護。

第五層：直接的程式碼智慧

當你需要看到實際的實作內容 — 而不只是關於它的中繼資料 — Maguyva 的 MCP 工具能提供直接存取。

在代理工作階段中：

mcp__maguyva__intelligent_search
  query: "agent context loading"

這會自動橫跨語意、文字與 AST 搜尋，找出相關程式碼。若要查詢特定符號：

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

若要進行依賴分析：

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

這些工具不只是 grep 的替代品，而是具備圖形感知能力、經過語意索引，並與驅動代理自身運作的那套程式碼智慧完全整合。

跨登錄檔的統一搜尋

有時候你根本不知道答案藏在哪個登錄檔裡，統一搜尋能一次橫跨所有登錄檔：

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

在五個登錄檔中共找到 254 筆相符結果。摘要會告訴你該往哪裡深入查看。移除 --summary 可取得詳細結果，或加上 --limit 5 讓輸出量維持在可掌控範圍內。

為什麼這很重要

漸進式揭露不只是為了方便，它改變了你與複雜系統互動的方式。

除錯變得可掌控。 當代理做出意外決策時，你不必翻遍日誌，而是先檢查它能取用哪些工具（agents info）、哪些決策塑造了它的行為（decisions search），必要時再追蹤實作內容（intelligent_search）。

新人上手更快。 新進團隊成員不必讀完整個程式碼庫，而是從 system status 開始，透過 agents list 探索，只有在遇到自己不理解的地方時，才需要深入研究。

文件保持最新。 因為 CLI 讀取的，正是設定代理所用的那些登錄檔本身，輸出內容永遠準確，文件所說的與系統實際運作的內容之間，不會出現落差。

以 CLI 作為介面

我們原本可以打造一個網頁儀表板，也可以寫出大量文件。但我們選擇打造一套直接讀取最終真實來源的 CLI。

CLI 具備以下優勢：

可組合：可透過管線將輸出送入 jq，並與腳本整合
可腳本化：可自動化檢查、產生報告
快速：不需要頁面載入，也不需要身分驗證流程
準確：讀取的是真實設定，而非快取後的呈現版本

對於正確性比美觀更重要的系統來說，CLI 才是贏家。

打造你自己的漸進式揭露

如果你正在打造代理系統，請思考使用者將如何檢視它：

從健康檢查開始。 一個指令，就能告訴你一切是否運作正常。
提供清單檢視。 先列出有什麼存在，再解釋它做什麼。
支援針對性查詢。 在大規模情境下，搜尋勝過瀏覽。
揭露溯源資訊。 讓使用者能追蹤決策回到其源頭。
連接到程式碼智慧。 最終，使用者需要看到實作內容本身。

每一層都回答一個後續問題，請依使用頻率順序建構它們 — 多數使用者會停在第二層或第三層，只有進階使用者才會抵達第五層。

目標並不是揭露一切，而是恰好揭露需要的東西、在恰好需要的時候。這正是漸進式揭露應用於代理架構的方式。

根基真相：讓 AI 代理扎根於現實

Tue, 13 Jan 2026 00:00:00 GMT

本文中的數字反映發布當下（2026 年 1 月）的系統狀態。目前最新數字請參見我們的團隊頁面。

AI 代理的能力令人驚豔，能夠推理、統整、生成內容。但它們有一個根本弱點：會憑空捏造。不是出於惡意，而是自信滿滿地捏造。代理可能會發明根本不存在的 API 參數、引用從未定義過的設定，或是套用訓練資料中與你實際架構相牴觸的模式。

常見的緩解方式是「給代理更多情境資訊」。但情境資訊本身可能自相矛盾：文件會與實作脫節，註解可能說謊，就連程式碼本身，若不理解其意圖，讀起來也可能誤導人。

我們需要更明確的東西 — 一種無法被忽略、也難以被誤解的東西，能讓代理扎根於可驗證的現實。

我們稱之為根基真相（Ground Truths）。

什麼是根基真相？

根基真相是一項明確、經過版本控管的事實陳述，代理必須予以尊重。它不是文件，也不是註解，而是系統中的一級實體，具備：

唯一識別碼（例如 GT-MAG-015 或 GT-MAG-036）
生命週期狀態（現行、暫定或已淘汰）
範圍（平台全域、特定套件或特定領域）
佐證（能證明該陳述的檔案路徑、網址或參照）
代理指引（明確的「該做」與「該避免」指示）

以下是我們 Maguyva 程式碼智慧平台中的一個範例：

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

這不是散文，而是一份契約。當代理遇到這條根基真相時，它會知道：

預設行為是確定性的（回傳空結果，而不是模糊猜測）
有特定參數（find_similar、exact_match）具備明確定義的行為
佐證存在於可驗證的特定檔案中
該陳述已在特定日期完成驗證

根基真相登錄檔的結構

根基真相存放於 ai_assets/reference/ground_truths.yaml 底下的 YAML 登錄檔中。每個套件或領域都可以擁有自己的登錄檔。其結構如下：

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

登錄檔包含關於整份集合本身的中繼資料、供文件生成使用的渲染設定，以及陳述本身。每則陳述都遵循由 Pydantic 模型驗證的嚴格結構描述：

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

代理如何取用根基真相

根基真相透過多種管道提供給代理存取：

1. 渲染後的文件

orkestra sync 指令會將 YAML 登錄檔轉換為可讀的 Markdown：

uv run orkestra sync

此指令會產生納入代理情境的 GROUND_TRUTHS.md 檔案。渲染後的輸出會依狀態與類別將陳述分組：

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. CLI 搜尋

具備殼層存取權的代理可以透過程式化方式搜尋根基真相：

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

搜尋函式會依加權相關性，對多個欄位進行比對評分：

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. 情境組成

當代理是由 YAML 定義渲染而成時，其情境可以參照根基真相登錄檔：

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

這確保了相關的根基真相會在代理開始作業前先行載入。

根基真相的類別

檢視我們的各個登錄檔，根基真相大致可歸納為幾種模式：

產品原則

界定產品「是什麼」與「不是什麼」的限制：

「Maguyva 對使用者的程式碼庫僅有唯讀權限；唯一無法重建的資產是付費的嵌入快取。」（GT-MAG-001）

架構邊界

界定職責歸屬何處、以及原因：

「pipeline 與 Maguyva 之間的邊界是刻意設計的：pipeline 可重複使用，Maguyva 掌管程式碼專屬邏輯，而 CQRS 則將管線各階段的寫入與伺服器端的讀取分離。」（GT-MAG-006）

反幻覺規則

確保工具契約維持確定性、而非仰賴推測的明確規範：

「模糊符號比對須透過 find_similar=true 主動啟用。預設行為會對不存在的符號回傳空結果；exact_match=true 會強制嚴格比對，並停用所有模糊備援機制。」（GT-MAG-015）

品質關卡

必須維持的標準：

「對共用基礎架構（post_filters.py、關係擷取器、共用處理器）的變更，提交前必須透過完整清單生成，針對『所有』支援語言進行驗證。僅驗證單一語言，對共用程式碼而言並不足夠。」（GT-MAG-036）

程式碼模式

實作上的要求：

「在非同步情境中處理 CPU 密集型工作時請使用 asyncio.to_thread()；已淘汰的 loop.run_in_executor() 模式不應用於新程式碼。」（GT-MAG-018）

根基真相的生命週期

根基真相並非一成不變，而是會經歷明確定義的生命週期：

暫定

一項尚在評估中的擬議真相，陳述已被記錄，但仍可能變動：

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

現行

一項代理必須遵守的已驗證真相，佐證已通過驗證：

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

已淘汰

一項已不再適用的真相，出於歷史紀錄目的而保留，並附上指向其後繼者的指引：

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

為什麼不能只靠文件？

文件服務於不同的目的：它負責解釋、負責教學，可以模糊一點，也可以使用「通常」或「一般而言」之類的限定語。

根基真相不能模糊。它們是斷言，要嘛適用，要嘛不適用。

想想這個差異：

文件寫法：「當找不到符號時，API 通常會回傳空結果，不過在某些設定下可能會啟用模糊比對。」

根基真相寫法：「預設行為會對不存在的符號回傳空結果；exact_match=true 會強制嚴格比對，並停用所有模糊備援機制。」

前者對正在學習系統的人類很有幫助；後者則能讓代理據以直接採取行動、做出決策。

代理指引：該做與該避免

部分根基真相包含明確的代理指引：

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

這消除了模糊地帶。閱讀這段內容的代理不僅知道什麼是真的，也知道這項真相意味著該採取什麼行動。

驗證與維護

根基真相需要持續維護。我們追蹤以下資訊：

last_verified：上次有人確認該陳述仍然成立的時間
evidence：能證明該陳述的檔案（可檢查其是否存在）
source：該真相的來源（CLI 檢視、架構審查、事後檢討所得的經驗）

若一項根基真相的驗證日期過於陳舊、或佐證連結已失效，就是需要調查的訊號：要嘛這項真相依然成立、只是需要重新驗證，要嘛現實已經改變、這項真相需要更新。

來自正式環境的真實案例

安全邊界

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

這條根基真相能防止一類會破壞產品的、方向錯誤的「安全性改善」。

擷取階段的準確度

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

這條規則來自一段痛苦的經驗：代理曾透過只在驗證器層級加入篩選條件，讓測試機制看起來更綠，來「修補」失敗的語言套件，但正式環境中的 Maguyva 擷取器實際上仍會產生錯誤的關係邊。這條規則強制將修正導回真正的路徑：YAML 設定、查詢，或處理器本身。

多層篩選

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

這能防止代理把篩選條件加在錯誤的位置 — 這是常見的失誤，過去曾因此造成準確度倒退。

與協調系統的整合

根基真相是更廣泛情境系統中的一層：

架構決策（ADR） — 記錄我們為何選擇方案 A 而非方案 B
根基真相 — 陳述當下確切為真的事實
領域模式 — 描述如何正確完成某件事
反模式 — 描述該避免什麼、以及原因

在此系統中作業的代理可以取用以上全部四種資訊。根基真相提供事實錨點，決策說明歷史脈絡，模式引導實作，反模式則提醒陷阱所在。

衡量成效

自導入根基真相以來，我們觀察到：

「修正幻覺出的修正」這種循環變少了
事實明確時，代理做決策更有信心
PR 審查品質更好，因為期望被明確寫出
新進代理（以及新進人類）的上手時間縮短

維護根基真相所投入的成本，換來了更少的除錯時間與更清晰的系統邊界，物有所值。

開始使用

要在你的系統中加入一條根基真相：

建立一個 ground_truths.yaml，置於你套件的 ai_assets/reference/ 目錄下
定義中繼資料與渲染設定
依照結構描述加入陳述
執行 uv run orkestra sync 以產生文件
將該登錄檔納入代理情境組成中

從最容易引發混淆的事實、或最常被違反的限制開始著手，這些正是你價值最高的根基真相。

結語

AI 代理終究會產生幻覺，這是它們的本性。但我們可以打造一種環境，讓幻覺受到約束、讓某些事實不容妥協、讓代理能夠對照已驗證的現實來檢查自己的假設。

根基真相並非萬靈丹，它需要維護、可能會過時，也會為開發流程增加額外負擔。

但它提供了一項寶貴的東西：一套人類與代理都能信任的共同事實詞彙。在一個代理日益深度參與軟體開發的世界裡，這樣的共同基礎變得不可或缺。

另一種選擇，是代理不斷自信地犯錯、人類不斷收拾善後的無盡循環。根基真相打破了這個循環，讓修正變得明確而持久。

你的代理值得知道什麼是真的。告訴它們。

Orkestra：大規模協調 AI 代理

Tue, 06 Jan 2026 00:00:00 GMT

本文中的數字反映發布當下（2026 年 1 月）的系統狀態。目前最新數字請參見我們的團隊頁面。

當我們開始使用 Claude Code 進行開發時，遇到了每個使用 AI 程式設計助理的團隊終究都會碰上的問題：單一代理無法把每件事都做好。

你可以提示一個代理扮演資料庫專家，或是安全稽核員，或是前端工程師。但只要你同時要求它身兼這三種角色，品質就會下滑：情境被稀釋，指令彼此矛盾，代理變成一個什麼都懂一點、卻什麼都做得平庸的通才。

於是我們打造了 Orkestra。

什麼是 Orkestra？

Orkestra 是專為 Claude Code 及類似 AI 程式設計工具打造的代理協調系統。它會在單一協調器之下，統籌多個各具專長的專家代理，並將工作分派給最適合的專家。

可以把它想像成一間專為 AI 代理服務的人力仲介公司：協調器接下任務，判斷該由哪位專家處理，再附上正確的情境資訊進行委派。工作完成後，結果會回流到協調器手上進行整合。

這些數字說明了一切：

組成	數量
專家代理	46
可重複使用的技能	466
身份原型	27
思維模式	11
溝通風格	10
知識領域	21

角色系統：代理的 D&D

Orkestra 背後的核心洞察，是代理的行為源自三個可組合的基本元素：

身份（Identity） 定義代理「是什麼」。架構師（architect）設計系統結構；除錯者（debugger）追蹤失敗的根本原因；守護者（guardian）落實合規與安全邊界。我們共有 27 種可自由組合的身份原型。

思維模式（Mindset） 定義代理「如何思考」。分析型思維會將主張建立在證據之上，並量化不確定性；懷疑型思維會質疑假設、尋找反證；探索型思維則擁抱模糊性，嘗試多種做法。

風格（Style） 定義代理「如何溝通」。技術型風格會納入精確數值、引用具體檔案；精簡型風格會去除贅詞、先給出答案；圓融型風格則在誠實與得體之間取得平衡。

一個代理會組合這些基本元素：

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

這樣的組合，會產生一個能設計系統（architect）、跨領域串連知識（knowledge-architect）、設定策略方向（strategist）、以證據與資料思考（analytical）、且溝通不帶贅詞（concise）的代理。

真正的威力來自組合爆炸：27 種身份 × 11 種思維模式 × 10 種風格，可產生近 3,000 種可能的代理人格。但你只需要定義對你的工作真正有意義的那些組合。

技能：可重複使用的能力模組

技能是代理可以呼叫的知識與工作流程，依範圍分為分層系統：

層級	名稱	範圍	範例
K0	基礎	通用方法論	測試優先原則、以證據為本的完成標準
K1	身份	依角色劃分的工作流程	CLI 介面標準、效能作戰手冊
K2	領域	領域專屬知識	資料庫遷移模式、身份驗證機制驗證
K3	技術堆疊	特定技術專屬	Cloudflare 部署、Supabase 操作
K4	專案	僅限本程式碼庫	專案專屬的工作流程與慣例

技能採懶載入方式：代理在啟動時只會看到技能名稱與說明，完整內容只有在被觸發時才會載入。這讓情境保持精簡，同時使數百項技能都能被發現與運用。

每項技能都包含：

明確的觸發條件（例如「遷移資料庫結構描述時使用」）
逐步操作指引
該工作流程允許使用的工具
成功標準與失敗復原路徑

我們登錄檔中的 466 項技能，涵蓋範圍從 git 工作樹隔離、網路研究工作流程，到部署健康驗證，無所不包。

為何協調很重要

單一代理架構很快就會撞牆：

情境稀釋。 20 萬 token 的情境視窗聽起來很大，但一旦載入資料庫結構描述、API 文件、測試案例與資料，以及領域知識，很快就會吃緊。專家代理則可以只使用目標明確的情境。

指令衝突。 同時要求代理「徹底但要快」與「什麼都要驗證但別過度工程」，會產生內在張力。專家代理則因為範圍明確而能化解這類矛盾。

專業深度。 通才型代理對每件事都略知一二；而由正確的身份與技能組成的專家代理，則能對自己的領域有深入理解。

Orkestra 採用扁平化協調：一個協調器統籌多個專家代理，專家代理不能再衍生出子專家。這能避免複雜度失控，同時仍支援平行作業。

協調器可運用的有效容量高達 220 萬個 token：自身 20 萬 token 的視窗，加上最多 10 個並行子代理、各自擁有 20 萬 token。足以耗盡單一代理情境容量的工作量，在整支艦隊中卻能從容完成。

渲染管線

代理定義存放於 YAML 中，而 Claude Code 讀取的是 Markdown。Orkestra 以一套確定性的渲染管線，銜接這道落差：

YAML Registries → Jinja Templates → .claude/agents/*.md

操作者編輯 YAML 原始檔，執行 orkestra sync，渲染後的 Markdown 就會出現在 .claude/agents/ 中，Claude Code 隨即讀取到這些變更。

這樣的區分服務於不同對象：

YAML 原始檔 包含生命週期中繼資料、標籤、驗證規則，以及供工具使用的淘汰通知
渲染後的 Markdown 只包含模型真正需要的內容：描述、工具、技能與行為指引

這套管線會將身份、思維模式、風格與技能，組合成單一且連貫一致的提示。即使共享部分底層技能，architect-analytical-concise 型代理所得到的系統提示，也會與 debugger-skeptical-technical 型代理截然不同。

領域知識：四檔案模式

每個知識領域都遵循一致的結構：

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

這種結構是為了服務代理的情境載入：處理身份驗證相關工作的代理，會載入 authentication/patterns.md 取得指引，並載入 authentication/anti-patterns.md 以避開已知陷阱。這些檔案的大小經過調整，以利高效載入 — 夠聚焦、才有用；夠全面，才具權威性。

我們維護 21 個頂層領域，涵蓋分析、身份驗證、資料科學、基礎架構、機器學習、效能、安全等等。每個領域都可以再細分出子領域，以取得更細緻的粒度。

價值觀：作業系統

所有代理都共用一套定義其運作方式的基礎價值觀：

簡潔優先。 使用有效的最簡方案，只有在有正當理由時才增加複雜度。

修正根本原因。 絕不繞過失敗打補丁。若管線失敗，就除錯管線；若測試失敗，就修正程式碼或測試本身。

以證據為本。 將主張標示為「已驗證」（附上基準測試）或「估計」（附上假設）。偵測到模式，不等於問題已獲確認。

情境經濟學。 MCP 工具僅耗用 0.1% 的情境，每次讀取檔案則耗用 2%。在探索程式碼之前，先運用領域專業知識。

這些價值觀會透過渲染管線傳遞給每一位專家代理，任何代理都無法透過組合方式繞過它們。

CLI：控制平面

Orkestra 隨附一套用於管理代理生態系的 CLI：

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

這套 CLI 是「有哪些代理存在」「它們擁有哪些技能」「系統是否健康」等資訊的唯一真實來源，並會在同步前執行驗證，及早揪出問題。

開源方面的考量

我們打造 Orkestra，是為了解決自己的問題：在複雜的程式碼庫中大規模協調 AI 代理。但我們發現的這些模式，並不侷限於我們自己的領域。

角色組合系統（身份 + 思維模式 + 風格）適用於任何需要定義代理人格的團隊。

技能分層系統（K0 至 K4）提供了一套按範圍組織可重複使用能力的心智模型。

渲染管線模式（YAML 原始檔 + 範本 + 生成產物）將工具面的關注點與供模型讀取內容的關注點區分開來。

扁平化協調模型（一個協調者、多個專家）在支援平行作業的同時避免了複雜度爆炸。

Orkestra 是否會走向開源，取決於這些模式對其他使用 Claude Code 開發的人是否有價值。如果你也正撞上我們所描述的那些牆，這套架構或許能幫上忙。

我們學到的事

打造 Orkestra 讓我們明白，協調的重點不在於讓代理變得更聰明，而在於讓它們變得更專注。

即使指令再完美，單一代理終究會耗盡情境；即使擁有所有技能，單一代理依然會搞不清楚該套用哪一項；一個試圖包辦一切的單一代理，只會在每件事上都做得平庸。

四十位各自在自己領域表現出色的專家，由一個懂得何時該委派的協調器統籌 — 這正是我們得以持續交付的方式。

數字本身沒有架構重要。你可能需要五個代理，也可能需要五十個。原則始終如一：組合勝過單一能力，專精勝過通才，協調勝過單打獨鬥的英雄主義。

Orkestra 驅動著 Maguyva（我們的程式碼智慧平台）背後的代理生態系。想進一步了解嗎？歡迎聯絡我們的團隊。