AAIF goose 詳細教學

對應 repo: https://github.com/aaif-goose/goose（45.6k stars / 4.7k forks / v1.34.1 stable / Apache-2.0，截至 2026-05-22）

1. 專案定位

1.1 它是什麼

goose 是 AAIF (Agentic AI Foundation, Linux Foundation) 治理的 Rust 原生通用 AI agent。三種形態：

1. Desktop app：macOS / Linux / Windows native（Electron 包 Rust 後端 goosed）
2. CLI：terminal-native（最快上手）
3. Server / API：可嵌入任何系統

原本是 Block (Square 母公司) 內部工具 → 2024-08 開源 → 2026-05 轉移到 AAIF 治理（README 第一段：「goose has moved! From block/goose to AAIF」）。

1.2 它解決什麼問題

• 「想在本機跑 agent，但又不想被綁定特定 IDE」：Cursor / Claude Code 都是 IDE 內 agent；goose 是 OS-level agent，跨 IDE 都能用
• 「每家 LLM 各裝一個工具」：goose 一個 binary 連接 30+ provider
• 「想用既有訂閱不另外 API key」：ACP 讓你接 ChatGPT / Claude / Gemini 訂閱
• 「企業要自家 AI agent 但不想從零做」：Custom Distros 讓你 fork + brand 自己的 goose
• 「需要進 Linux Foundation 級別治理 / 安全」：AAIF 有正規 SECURITY.md + 51 個 CI workflow + 中立法律框架

1.3 與其他 agent 工具差異

goose 獨特：跨形態 + 訂閱接入 + Linux Foundation 治理。

1.4 適合誰用

• 本機跑 agent 的 power user：日常 dev + research + 自動化全包
• 想用既有 LLM 訂閱：透過 ACP 不另花錢
• 企業 DevX 團隊：想推「全公司統一 agent」用 Custom Distros 出企業版
• 基金會 / 開源中立性敏感者：相對於 Anthropic / OpenAI 商業產品，goose 在 Linux Foundation 中立法律框架下
• MCP / ACP 生態開發者：goose 是 reference implementation

2. 安裝指南

2.1 CLI 一鍵裝

1# macOS / Linux
2curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash
3
4# Windows (PowerShell)
5iex (irm "https://github.com/aaif-goose/goose/releases/download/stable/download_cli.ps1")
6
7# 驗證
8goose --version
9goose --help

2.2 Desktop app

下載對應平台 binary：https://goose-docs.ai/docs/getting-started/installation

• macOS: .dmg
• Linux: .deb / .rpm / Flatpak
• Windows: .msi / .exe

2.3 從 source build（contributor）

 1git clone https://github.com/aaif-goose/goose && cd goose
 2
 3# Hermit 是 dev env 管理工具（rust-toolchain / cargo / pnpm 自動處理）
 4source bin/activate-hermit
 5
 6# CLI build
 7cargo build --release           # → target/release/goose
 8
 9# UI build（desktop app）
10cd ui/desktop && pnpm install && pnpm run build
11
12# 全部用 Justfile 跑
13just release-binary
14just generate-openapi
15just run-ui
16
17# 跨平台 Nix
18nix develop                     # flake.nix 包好整個 dev env

2.4 Docker

1docker build -t goose .
2# 看 BUILDING_DOCKER.md 詳細

2.5 環境需求

• Rust 1.91.1（rust-toolchain.toml 鎖定）
• pnpm（UI）
• macOS / Linux / Windows (x86_64 / arm64)
• 對 desktop：需 Vulkan packages (Linux)，最新 commit (#9323) 已加入

flowchart TB
    U[使用者] --> C1[CLI binary]
    U --> C2[Desktop app
Electron + goosed]
    U --> C3[Server API
goosed standalone]
    C1 & C2 & C3 --> G[goose core
Rust crates/goose]
    G --> P[Provider Registry
30+ LLM]
    G --> M[MCP Client]
    G --> A[ACP Bridge]
    P --> LLM1[Anthropic / OpenAI / Google]
    P --> LLM2[Databricks / Bedrock / Azure]
    P --> LLM3[Ollama / OpenRouter / litellm]
    P --> LLM4[xAI / Kimi / Snowflake]
    A --> SUB[Claude/ChatGPT/Gemini
既有訂閱]
    M --> MCP1[5 內建 MCP server]
    M --> MCP2[70+ 第三方 MCP]
    MCP1 --> D[developer / computercontroller / memory / peekaboo / tutorial]

3. 核心架構解析

3.1 三層架構

graph TB
    subgraph "Interface Layer"
        CLI[goose CLI
terminal-native]
        UI[Desktop App
Electron + React]
        API[Server / API
goosed]
    end
    subgraph "Core (Rust crates/goose)"
        AG[Agent runtime
conversation + execution + permission]
        PR[Provider abstraction
30+ LLM]
        MC[MCP Client
+ ACP bridge]
        HOOK[Hooks + Plugins + Subagents]
        REC[Recipes engine]
    end
    subgraph "Extensions / MCP"
        BUILT[5 內建 MCP
developer / computercontroller / memory / peekaboo / tutorial]
        THIRD[70+ 第三方 MCP
via MCP marketplace]
        ACP[ACP providers
Claude / ChatGPT / Gemini 訂閱]
    end
    subgraph "LLM"
        LLMS[Anthropic / OpenAI / Google / Databricks / Bedrock / xAI / Ollama / OpenRouter / Azure / Databricks / Snowflake / Kimi / ...]
    end
    CLI & UI & API --> AG
    AG --> PR
    AG --> MC
    AG --> HOOK
    AG --> REC
    PR --> LLMS
    MC --> BUILT & THIRD
    MC --> ACP
    ACP --> LLMS

3.2 8 個 Crate 職責

3.3 一個 goose session 的生命週期

sequenceDiagram
    participant U as 使用者
    participant CLI as goose CLI
    participant A as Agent Core
    participant P as Provider
    participant LLM as Anthropic / etc.
    participant M as MCP Client
    participant EXT as MCP Extension

    U->>CLI: goose session
    CLI->>A: 啟動 agent
    A->>A: 載入 config（providers + extensions）
    A->>M: 啟動各 MCP server (subprocess)
    M->>EXT: spawn extension processes
    U->>CLI: 「幫我整理 ~/Downloads 」
    CLI->>A: forward prompt
    A->>P: 組 prompt + tool definitions
    P->>LLM: API call
    LLM-->>P: 回應 + tool calls
    P-->>A: 解析
    A->>A: permission check
    A->>M: 執行 tool（如 developer.shell("ls ~/Downloads")）
    M->>EXT: 跑 tool
    EXT-->>M: 結果
    M-->>A: 結果
    A->>P: 把 tool result 餵回
    P->>LLM: 下一輪
    Note over A,U: 反覆執行直到 task 完成
    A-->>CLI: 最終回應
    CLI-->>U: 印出

3.4 Provider Registry 設計（30+ LLM）

crates/goose/src/providers/ 列了所有 provider 實作。每個 provider 是一個 .rs，實作共同 trait（在 base.rs）。provider_registry.rs 註冊所有；init.rs 處理啟動。

ACP 系列（用使用者既有訂閱）：

• claude_acp.rs — Claude.ai 訂閱
• chatgpt_codex.rs — ChatGPT 訂閱
• codex_acp.rs — OpenAI Codex 系列
• copilot_acp.rs — GitHub Copilot
• pi_acp.rs — Inflection Pi
• amp_acp.rs — Amp

OAuth 認證流程：

• oauth_device_flow.rs — device code flow
• azureauth.rs / gcpauth.rs — 雲端認證
• gemini_oauth.rs — Gemini OAuth

3.5 MCP server 自家 5 個

3.6 Recipe / Subagent / Hook / Plugin 抽象

4. Helper Scripts 詳細用法

4.1 goose CLI 命令樹

4.2 Justfile 主要 target

1just --list                         # 看全部
2just check-everything               # 跑 cargo fmt + clippy + UI lint + OpenAPI 校驗
3just release-binary                 # 釋出 build + 自動 generate OpenAPI
4just generate-openapi               # 重生 OpenAPI schema（server 改了就要跑）
5just run-ui                         # 啟動 desktop app
6just record-mcp-tests               # 重錄 MCP integration test 快照

4.3 scripts/ 17 個 helper

4.4 download_cli.sh（一鍵裝 CLI）

從 GitHub Releases 抓對應 OS/arch binary。支援環境變數：

1GOOSE_VERSION=v1.34.0 bash download_cli.sh         # 裝特定版本
2INSTALL_DIR=$HOME/bin bash download_cli.sh         # 改安裝路徑

4.5 goose-self-test.yaml（17KB）

goose 自己對自己跑的 smoke test recipe。是學寫 recipe 的最好範例。

4.6 goosed server 直接跑

1cargo run -p goose-server         # 起 HTTP server :3000（預設）
2curl http://localhost:3000/openapi.json  # 看 schema

可嵌入第三方 app；OpenAPI 自動 generate → ui/desktop/openapi.json 與 src/api/ TypeScript 客戶端同步。

5. 應用場景

6. 資安掃描報告

掃描範圍：crates/、scripts/、download_cli.sh、SECURITY.md、provider 實作（spot check）、MCP servers。

綜合燈號：🟢 / 🟡（無紅燈；風險主要來自「本機 agent 本質」，文件已明確告知 + 多重防護）

重點建議：

• 個人 dev：用 goose 沒問題，但敏感 task 建議用 VM/container
• 企業：建 Custom Distro + 限制 MCP whitelist + permission policy
• 永遠不要讓 goose 跑 untrusted 內容（包括 prompt-injection 的網頁）— 用 sandbox
• 啟用 OpenTelemetry (otel/) 把 audit log 集中化

7. FAQ

Q1：跟 Claude Code / Cursor 差別？ A：

• Claude Code：Anthropic 專屬產品，深度整合 Claude；商業 / 部分免費
• Cursor：IDE-centric agent；商業
• goose：OS-level，跨 LLM 跨 IDE，OSS，可自家 fork 做 Custom Distro

Q2：為什麼要從 block/goose 移到 aaif-goose？ A：原來是 Block (Square) 內部工具，但社群投入大、希望中立治理 → 進 Linux Foundation 的 Agentic AI Foundation (AAIF)。Block 工程師（jh-block / Bradley Axen 等）仍是主要 contributor。

Q3：ACP 是什麼？跟 MCP 有什麼關係？ A：

• MCP (Model Context Protocol)：Anthropic 推的「agent ↔ tool / data source」標準
• ACP (Agent Client Protocol)：goose 推的「agent ↔ existing LLM subscription」橋接協議 — 讓 goose 用使用者 ChatGPT / Claude / Gemini 訂閱
• 兩者互補：MCP 接 tools，ACP 接 subscriptions

Q4：MCP extension 怎麼裝？ A：兩條路：

1. goose configure → 加入「extensions」（從 MCP marketplace 選）
2. 手動編 config 加 stdio / SSE / HTTP-type MCP server

Q5：Custom Distros 是什麼？ A：CUSTOM_DISTROS.md (28KB) 文件描述：企業可建立帶 preconfigured providers + extensions + branding 的自家 goose 變體。例如「Acme Goose」可預載 Acme 的 internal MCP / 內部 LLM proxy。

Q6：本機跑 LLM (Ollama) 行不行？ A：行。provider = ollama；要先 ollama pull <model> 把模型下下來。但目前 ollama 對長 context / tool use 仍不如 cloud LLM。

Q7：dictation（語音輸入）支援？ A：crates/goose/src/dictation/ 有實作；目前是實驗功能。

Q8：能跟既有 IDE（Vim / Emacs / VSCode）整合嗎？ A：可。goosed server 暴露 HTTP API → 任何 IDE 寫 plugin 接。目前社群有 vscode-goose 等。

Q9：跟 OpenCode / OpenClaw / Aider 等比較？ A：

• OpenCode / OpenClaw：較小型 OSS CLI agent
• Aider：focus on code editing；CLI only
• goose：規模 / 治理 / provider 數遠超這些 — 是 OSS agent 的重量級選手

Q10：本知識庫怎麼用 goose？ A：建議：

1. 在 inbox/ 跑 goose session 對 markdown 做問答
2. 寫 recipe 自動化 ai-save / gh-tutorial-qd 等工作流
3. 用 ACP 接 Claude.ai 訂閱省 API key 錢
4. 把本知識庫的 SKILL.md 部份 import 成 goose 的 hint / extension

8. 進階技巧

8.1 寫一個 Recipe

 1# my-recipe.yaml
 2name: research-summarizer
 3description: 給定 URL，summarize 並存到 inbox
 4parameters:
 5  - name: url
 6    type: string
 7prompt: |
 8  Read {{url}} and write a 5-paragraph summary to inbox/<date>-<slug>.md.
 9extensions:
10  - developer       # 需要 file write

1goose run --recipe my-recipe.yaml --param url="https://..."

8.2 寫 .goosehints（專案層）

本 repo 的 .goosehints 是好範例：明確說明結構 / build 命令 / lint 規則 → agent 進專案會自動讀，省去每次重講。

8.3 用 ACP 接 Claude.ai 訂閱

1goose configure
2# → 選 provider → claude_acp
3# → 跑 OAuth device flow 認你的 Claude.ai 帳號
4# → 之後 chat 就用訂閱額度，不用 API key 計費

8.4 寫自家 MCP server

1// 看 crates/goose-mcp/src/tutorial/ 抄結構
2// 然後 cargo build 加進 goose-mcp/Cargo.toml

8.5 在本知識庫跑 goose

1cd "/config/workspace/.../260416 AI-knowledge_template v1"
2goose configure
3# 加 developer MCP（read/write inbox/）
4# 加 .goosehints：說明 inbox / projects / .claude/skills 結構
5
6goose session
7# 「幫我把 inbox/ 內 2026-05 開頭的所有 .md 摘要成 summary.md」

8.6 Subagent 拆任務

recent commit #9238 「slash commands (built-in, skill, recipe) in acp server」表明 ACP server 支援 slash commands；意味著你可以在 ACP session 內喚醒 sub-agent / skill / recipe。

8.7 用 Harbor eval runner（PR #9138）

1# evals/harbor/ 內
2cd evals/harbor
3# 看 README，跑 goose 對自己的 benchmark

9. 整合進其他工作流

10. 重點摘要 Checklist

• 45.6k stars / 4.7k forks / Apache-2.0 / 1.7 年生命週期（2024-08-23）
• AAIF Linux Foundation 治理（前 block/goose）
• Rust workspace 8 個 crate + Electron UI + 3001 個檔
• v1.34.1 stable / v1.35.0 在 flight / v2.0.0-rc 開發中
• 3 種形態：CLI / Desktop app / Server (goosed)
• 30+ LLM provider（含 ACP 系列用既有訂閱）
• 70+ MCP extension + 自家 5 個（developer 為主力）
• Recipe + Subagent + Hook + Plugin 完整 agentic 抽象
• Custom Distros 文件 28KB — 企業可建自家變體
• Prompt injection 專責防禦（dorien-koelemeijer 為主）
• 51 個 CI workflow + Cargo deny + cargo machete + clippy strict
• OpenAPI 自動 generation（goose-server → ui/desktop/openapi.json）
• 完整 Linux Foundation 治理（GOVERNANCE / MAINTAINERS / SECURITY / I18N / RELEASE_CHECKLIST）
• 資安綜合燈號：🟢 / 🟡（無紅燈；本機 agent 本質風險 + 文件全揭露）

11. 進一步閱讀

• 官方 docs：https://goose-docs.ai
• Quickstart：https://goose-docs.ai/docs/quickstart
• AAIF (Agentic AI Foundation)：https://aaif.io
• Linux Foundation Insights：https://insights.linuxfoundation.org/project/goose
• Discord：https://discord.gg/goose-oss
• ACP providers guide：https://goose-docs.ai/docs/guides/acp-providers
• Custom Distros：本 repo CUSTOM_DISTROS.md
• Governance：本 repo GOVERNANCE.md
• 對應姊妹專案：
  • rohitg00/agentmemory（持久記憶）— inbox/2026-05-21-github-rohitg00-agentmemory.md
  • 1weiho/open-slide（簡報）— inbox/2026-05-22-github-1weiho-open-slide.md
• 本知識庫先前 tutorial：inbox/2026-05-22-tutorial-open-slide.md