# Goose 靠扩展干活。加一个懂你仓库的。

Canonical source: https://maguyva.ai/zh-hans/for-goose

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Goose 通过扩展完成工作，而每个扩展都是一个 MCP 服务器。Maguyva 就是那个索引你代码库的扩展，于是 Goose 会直接问东西在哪里，而不是一层层列目录。

> .goosehints 管怎么做事，Maguyva 管代码现在怎么写。

## 关于 Goose 需要知道的

四条 Goose 专属事实。

### config.yaml

扩展放在 `~/.config/goose/config.yaml` 的 `extensions` 下。`goose configure` → Add Extension 也会替你写入同类条目。

### 一个远程扩展

Maguyva 是一个 `streamable_http` 扩展，Goose 会自己连接端点：没有本地进程，也不需要 Node.js。URL 写在 `uri` 里，不是 `url`。

### headers

Goose 每次请求都会发送 `headers` 映射，所以密钥放在 `Authorization` 请求头里。Goose 也可以从 `env_keys` 中列出的环境变量填入它。

### available_tools

扩展可以只暴露部分工具：把想要的工具列在 `available_tools` 下，留空则全部启用。

## Goose 提示是一份工作约定，好好用它。

```text
# .goosehints
- 用 pnpm，别用 npm。
- 宣布改动完成之前，先跑集成测试。
```

Goose 默认加载 `AGENTS.md` 和 `.goosehints`：全局提示来自 `~/.config/goose/.goosehints`，项目提示来自仓库，进入子文件夹工作时还会读取嵌套的文件。提示需要启用 Developer 扩展。适合写进去的有：

- 工具选型和命令。
- Goose 应当遵守的约定。
- 文档放在哪里。

提示描述的是项目。它们回答不了“什么依赖于它？”

## 提示和 shell 不够用的地方

Goose 靠 shell 命令、一次一个文件填补的三个缺口。

### // 目录列表不是地图

面对陌生仓库，Goose 用目录列表和读文件来摸清情况。每一步都在任务开始前就消耗上下文。

### // grep 找到的是字符串，不是调用方

文本搜索分不清真正的调用、注释、mock 和同名方法。

### // 提示会跑偏

上个季度写的提示文件，描述的是上个季度的布局。Goose 照样会遵循。

## 作为 Goose 扩展的 Maguyva

一条 extensions 条目让 Goose 获得：

- **面向已索引仓库的 11 个工具**: 语义、结构（AST）、图和文本搜索，外加符号查找、依赖方和文件检索。
- **带文件路径和行号的答案**: 覆盖 285+ 种语言。
- **只读的工具**: Maguyva 的工具只查询索引，没有一个会修改你的文件。

> 提示告诉 Goose *怎么工作*。
> Maguyva 给 Goose *一张代码地图*。

## 两种工作流

先看地图，再让 Goose 跑起来。

### 01. 把缺陷追溯到源头

```text
goose> 为什么有些导出结束时是零行？

semantic_search("export job empty result")
  src/export/runner.ts:118   flushBatch()
  src/export/filters.ts:40   applyTenantFilter()

→ Goose 只读两个文件，而不是整个 export 包。
[exit 0]
```

在 Goose 打开 shell 之前，排序结果就已缩小了搜索范围。

### 02. 重构之前先查依赖方

```text
goose> 把 Notifier 类拆成邮件和短信两部分

dependency_search("Notifier", dependents)
  分布在 5 个包中的 11 处引用

→ 第一次编辑之前，规划已覆盖全部十一处。
[exit 0]
```

Goose 一次调用就拿到完整的依赖方列表，不必一连串 grep。

## 在 Goose 中配置

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

### 01. 在 maguyva.ai 索引一个代码仓库

挑一个你已经熟悉的，这样你能给答案打分。

### 02. 在 config.yaml 的 extensions 中添加 Maguyva

`~/.config/goose/config.yaml`

```yaml
extensions:
  maguyva:
    name: maguyva
    type: streamable_http
    uri: https://maguyva.tools/mcp
    enabled: true
    headers:
      Authorization: Bearer mgv_xxxx
    timeout: 300

```

### 03. 替换占位符，然后开始一个会话

把 `mgv_xxxx` 换成你的 API 密钥，运行 `goose session`，然后问一个你已经知道答案的问题。YAML 对缩进敏感：请用空格，不要用 Tab。

Goose 的 [扩展文档](https://goose-docs.ai/docs/getting-started/using-extensions/) 介绍了远程扩展、超时和工具筛选。

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

通过 MCP 连接 Goose，然后问一个你能核实的问题。