跳至主要內容

給 Windsurf 使用者

Windsurf 編輯檔案。
Maguyva 看懂整個程式碼庫。

Windsurf 是編輯器，Cascade 是代理。在 monorepo 中，代理仍然需要一張地圖，才知道哪個檔案才是重點。Maguyva 會為你的程式碼庫建立索引，並透過 MCP 回傳（語意、AST、圖譜與文字），所以「驗證邏輯在哪裡發生」這個問題，得到的會是真正的驗證流程，而不是七個測試 mock。

免費開始閱讀 Windsurf 設定說明

Free 方案：3 個儲存庫, 最多 5 萬行索引儲存庫行數，免信用卡。

Windsurf 編輯你指向的目標。Maguyva 告訴 Cascade 該指向哪個檔案。

每一層各自負責什麼

四個部分，各司其職。

// 編輯器

Windsurf

你和 Cascade 實際工作的地方。

// 手動脈絡

@ mentions + .windsurfrules

手動提供脈絡在程式碼庫夠小時很好用，直到規模變大。

// 程式碼庫

Maguyva

透過 MCP 自動提供程式碼庫事實。

// 誰付費

以工作區計費，而非席位

代理不需要付席位費。查看價格

Windsurf 是編輯器，儘管用。

IDE 本身不是問題。Cascade、Tab 自動完成、多檔案修改，以及 .windsurfrules 都非常出色，你也已經在用它們來做：

  • 在目前開啟的檔案中使用即時建議與 Cascade 編輯。
  • 當變更範圍侷限於單一區域時，進行多檔案修改。
  • 用 .windsurfrules 定義程式碼庫慣例與風格規範。
  • 用 @-mentions 把特定檔案拉進脈絡中。

繼續這樣做，這些都不會消失。

但在真正的 monorepo（有工作區依賴的 TypeScript、Python 服務、混合套件）中，只要相關檔案還沒進入 Cascade 的視野，代理的脈絡就會出問題。

你已經試過的手動解法，以及它們會在哪裡失靈

四種手動解法，各自搭配對應的失效模式。左邊＝你現在的做法。右邊＝它會在哪裡出問題。

// the fix

// 提及檔案

你用 @-mention 標出你認為重要的三個檔案。Cascade 能在裡面乾淨地修改。

// where it breaks

// 提及只是猜測

這只有在你已經知道涉及哪些檔案時才有用。脈絡工具真正的價值，就是找出那些你根本不知道該提及的檔案。

// the fix

// 貼上程式碼片段

你把另一個套件裡的 200 行程式碼貼進 Cascade，好讓它有足夠的脈絡。

// where it breaks

// 貼上的程式碼會過時

你早上 9 點貼上的片段，反映不出隊友在 11 點完成的 rebase。Cascade 正在對著這個套件的幻影版本進行修改。

// the fix

// 寫一份脈絡文件

你寫了一份 .windsurfrules 檔案或架構說明文件。今天它是對的。

// where it breaks

// 文件過時的速度比程式碼快

任何手寫的東西都會過時。程式碼才是真相來源。一份說明佇列架構的文件，可能只對了一週，之後就永遠錯了。

// the fix

// 保留規則檔案

你新增 .windsurfrules 來規範命名、lint 與建置指令，對於行為規範很有效。

// where it breaks

// 規則 ≠ 索引

.windsurfrules 很適合放 “commit 前務必先執行 pnpm tsc -b” 這類規則。但它並不是一份可查詢的索引，涵蓋不了你 monorepo 裡每一個符號、檔案與呼叫點。

Maguyva 是底層的那一層

它不是要取代 Windsurf，而是掛載在 Cascade 的 MCP 支援上、負責程式碼庫脈絡的那一層。

  • 語意 + AST + 圖譜 + 文字 依意義、結構、依賴關係或字面搜尋。每一筆結果都會回傳檔案路徑與行號。
  • 預設跨套件 涵蓋 monorepo 中每個套件的呼叫點與匯入者，不只是 Cascade 目前開啟的那一個。
  • 感知分支 Maguyva 看得到 Cascade 正在編輯的那個程式碼版本。
  • 互補而非競爭 .windsurfrules 繼續做它該做的事。@-mentions 也繼續做它該做的事。Maguyva 補上它們補不到的空缺。

Cascade 編輯你指向的檔案。

Maguyva 告訴代理該指向哪個檔案。

三種 monorepo 工作流程

跨套件、跨語言，紮根於真實的呼叫圖，而不是 Cascade 的 grep。

// workflow 01

在不提及任何檔案的情況下，找出跨套件的驗證流程

cascade> 這個 monorepo 裡，驗證邏輯發生在哪裡？

graph::query("驗證流程")
  packages/web/src/auth/session.ts:42       中介層
  packages/api/src/auth/jwt.ts:88           權杖驗證
  packages/shared/src/auth/types.ts:12      AuthContext
  packages/admin/src/auth/admin-only.ts:31  RBAC 閘門

→ 4 個進入點，橫跨 4 個套件，依呼叫點密度排序。
[exit 0]

你沒有提及檔案，也沒有貼上程式碼片段。Cascade 已經拿到那四個真正重要的檔案，排序正確，可以做出紮根的修改。

// workflow 02

找出真正的實作，而不是測試 mock

cascade> normalizePhoneNumber 是怎麼處理 E.164 格式的？

semantic::query("正規化電話號碼 E.164")
  packages/shared/util/phone.ts:88     normalizePhoneNumber()  ← 真正的實作
  packages/api/test/phone.spec.ts:14   jest.mock(...)          ← mock
[exit 0]

名字會騙人，mock 會掩蓋真正的程式碼。Maguyva 會在每個套件中，把真正的實作排在測試 mock 之前。

// workflow 03

重構前先確認影響範圍

cascade> 這個 monorepo 裡，誰呼叫了 QueueDispatcher.publish？

graph::callers(QueueDispatcher.publish)
  packages/billing/* 中有 3 筆
  packages/audit/* 中有 1 筆
  packages/notifications/* 中有 1 筆
  services/python-worker/* 中有 1 筆  ← 跨語言，透過 gRPC stub
[exit 0]

跨套件，遇到多語言程式碼庫時也跨語言，呼叫點會直接顯示在結果中。這份差異紮根於真實的匯入者，而不是 Cascade 的 grep。

在 Windsurf 中設定

三個步驟。Free 方案：3 個儲存庫, 最多 5 萬行索引儲存庫行數，免信用卡。

  1. // step 01

    在 maguyva.ai 索引一個程式碼庫

    挑一個讓你最深刻感受到脈絡痛點的 monorepo。

  2. // step 02

    在 Windsurf 中把 Maguyva 加為 MCP 伺服器

    // ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "maguyva": {
      "serverUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer <your-key>"
      }
    }
  }
}

  3. // step 03

    問一個你已經知道答案的問題

    不要一開始就丟出整間公司的規模。從一個程式碼庫、一個可驗證的問題開始，例如「跨套件有誰呼叫了 formatInvoice？」

自助註冊，隨時開放。

索引一個你已經熟悉的程式碼庫。

測試一個你能自行驗證答案的問題。

索引您的第一個儲存庫查看相容性文件

Free 方案：3 個儲存庫, 最多 5 萬行索引儲存庫行數，免信用卡。