跳转到内容

面向 Windsurf 用户

Windsurf 编辑文件。
Maguyva 看见整个代码库。

Windsurf 是编辑器，Cascade 是智能体。在 monorepo 里，智能体依然需要一张“哪个文件重要”的地图。Maguyva 索引你的代码库，并通过 MCP（语义、AST、图谱和文本）提供回来，于是“鉴权发生在哪里”返回的是真实的鉴权流程，而不是七个测试桩。

免费开始查看 Windsurf 配置说明

Free 层级：3 个代码仓库, 最多 5 万行索引代码，无需信用卡。

Windsurf 编辑你指向的内容。Maguyva 告诉 Cascade 该指向哪个文件。

每一层各自的作用

四个部件，各司其职。

// 编辑器

Windsurf

你和 Cascade 实际工作的地方。

// 手动上下文

@ 提及 + .windsurfrules

手动维护上下文很管用，直到代码库变大为止。

// 代码库

Maguyva

通过 MCP 自动提供代码库真实情况。

// 谁付钱

按工作区计费，而非按坐席

智能体不需要付坐席费。查看价格

Windsurf 是编辑器，好好用它。

IDE 本身不是问题。Cascade、Tab 补全、多文件编辑，以及 .windsurfrules 都非常出色，你已经在用它们做这些事：

  • 在当前打开的文件里做内联建议和 Cascade 编辑。
  • 当改动是局部的时候做多文件编辑。
  • 用 .windsurfrules 定义代码仓库规范和风格护栏。
  • 用 @ 提及把某个特定文件拉进上下文。

继续这样用，这些都不会消失。

但在真实的 monorepo 里（有工作区依赖的 TypeScript、Python 服务、混合包结构），一旦相关文件还没进入 Cascade 的视野，智能体的上下文就会崩掉。

你已经试过的手动办法，以及它们失效的地方

四种手动方法及其失效模式。左边 = 你今天在做的事。右边 = 它失效的地方。

// the fix

// 提及文件

你 @ 提及你认为重要的三个文件。Cascade 能在里面干净利落地编辑。

// where it breaks

// 提及本质上是猜测

只有当你已经知道涉及哪些文件时，提及才管用。上下文工具存在的意义，恰恰是把你根本不知道该提及的文件找出来。

// the fix

// 粘贴代码片段

你把另一个包里的 200 行代码粘贴给 Cascade，好让它获得足够的上下文。

// where it breaks

// 粘贴的代码会过期

你早上 9 点粘贴的代码片段，反映不出队友 11 点 rebase 之后的样子。Cascade 正在对着一个幽灵版本的包做编辑。

// the fix

// 写一份上下文文档

你写了一个 .windsurfrules 文件或一篇架构 markdown。今天看它是对的。

// where it breaks

// 文档漂移的速度比代码快

任何手写的东西都会漂移。代码才是唯一的真相来源。一篇解释队列层的文档能正确一周，然后就永远错下去了。

// the fix

// 保留规则文件

你添加 .windsurfrules 来定义命名、lint 和构建命令。对约束行为很好用。

// where it breaks

// 规则 ≠ 索引

.windsurfrules 正适合写“提交前必须运行 pnpm tsc -b”这类规则。但它不是你 monorepo 里每一个符号、文件和调用点的可查询索引。

Maguyva 是底下的那一层

不是要取代 Windsurf，而是挂在 Cascade 的 MCP 支持之下的那层代码库上下文。

  • 语义 + AST + 图谱 + 文本 按含义、结构、依赖关系或字面文本搜索。每个命中结果都会返回文件路径和行号。
  • 默认跨包 覆盖 monorepo 中每一个包的调用点和引用方，而不只是 Cascade 当前打开的那个包。
  • 分支感知 Maguyva 看到的是 Cascade 正在编辑的那个版本的代码。
  • 互补而非竞争 .windsurfrules 继续做它该做的事，@ 提及继续做它该做的事。Maguyva 填补的是它们都填补不了的空白。

Cascade 编辑你指向的文件。

Maguyva 告诉智能体该指向哪个文件。

三种 monorepo 工作流

跨包、跨语言，基于真实的调用图谱，而不是 Cascade 的 grep。

// workflow 01

在不提及任何文件的情况下，跨包找到鉴权流程

cascade> 这个 monorepo 里，身份验证发生在哪里？

graph::query("authentication flow")
  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  权限门禁

→ 4 个包中的 4 个入口点，按调用点密度排序。
[exit 0]

你没有提及任何文件，也没有粘贴任何代码片段。Cascade 拿到的是真正重要的四个文件，排序也是对的，可以据此做出有根据的编辑。

// workflow 02

找到真正的实现，而不是测试桩

cascade> normalizePhoneNumber 是怎么处理 E.164 格式的？

semantic::query("normalize phone E.164")
  packages/shared/util/phone.ts:88     normalizePhoneNumber()  ← 真实实现
  packages/api/test/phone.spec.ts:14   jest.mock(...)          ← 测试桩
[exit 0]

名字会骗人，mock 会遮住真实代码。Maguyva 会在所有包范围内，把真实实现排在测试 mock 之上。

// workflow 03

重构前先看清影响范围

cascade> 整个 monorepo 里，谁调用了 QueueDispatcher.publish？

graph::callers(QueueDispatcher.publish)
  3 处在 packages/billing/*
  1 处在 packages/audit/*
  1 处在 packages/notifications/*
  1 处在 services/python-worker/*  ← 通过 gRPC 桩跨语言调用
[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？”

自助注册已开放。

索引一个你已经熟悉的代码仓库。

测试一个你能自行验证答案的问题。

索引你的第一个仓库查看兼容性文档

免费方案：3 个代码仓库, 最多 5 万行索引代码，无需信用卡。