数据截至 (上游 commit 3fac8f23cfda)
goose — 架构与原理
30 秒导读: goose 是一个跑在你机器上的通用 AI agent(不只是写代码——研究、写作、自动化、数据分析都行),有桌面 App、CLI 和 API 三种壳,内核用 Rust 写。它把「让模型反复调工具直到任务完成」这件事做成一个可流式输出的循环,所有工具都通过 MCP(Model Context Protocol)这一开放标准接入,并且在每个工具真正执行之前,串了一条安全/权限检查链。
1. 这是什么(零基础也能懂)
一句话定义: goose 是一个开源的「AI agent 运行时」——你给它一个目标,它自己反复地「想一步、调一个工具、看结果、再想下一步」,直到把事做完。
解决什么问题 / 给谁用。 假设你在终端里说「帮我把这个项目的测试都修绿」。光有一个聊天模型不够:模型只会说话,不会真的读文件、跑命令、改代码。goose 补上的就是这套「手脚 + 大脑调度」:
- 它把你的话发给某个大模型(Anthropic / OpenAI / Google / Ollama / …);
- 模型回一句「我要运行
cargo test」(这叫一次工具调用); - goose 真的去执行,把输出再发回给模型;
- 如此往复,直到模型说「做完了」。
它能做什么(功能):
- 多家模型提供商:15+ 家,既可用 API key,也能复用你已有的 Claude/ChatGPT/Gemini 订阅。
- 70+ 扩展:通过 MCP 接入文件系统、shell、浏览器、记忆、自定义 server 等。
- 三种交互壳:桌面 App、CLI(
goose)、HTTP 服务(goosed)。 - 安全护栏:权限审批、prompt-injection 检测、数据外泄(egress)检测、生命周期 hooks。
- 长任务支撑:上下文自动压缩、子 agent、会话持久化、recipe(可复用任务模板)。
用起来什么样。 最小的 CLI 体感:
# 安装后,在项目目录里:
goose session
# 然后用自然语言下指令:
> 看一下 src/ 里有哪些 TODO,挑最关键的一个修掉
# goose 会:列目录 → 读文件 → 提议改动 → (按权限模式)征求同意 → 写文件 → 报告
一句话直觉 / 类比。 把 goose 想成一个项目经理 + 一双手:大模型是会出主意的「大脑」,但只会说话;goose 负责把大脑说的每句「去做 X」翻译成真实动作、拿回结果、再递回给大脑,并在动手前过一遍「这步安全吗、要不要先问主人」的安检。
2. 顶层全景(它大概怎么转)
仓库结构(只列主线相关)
goose 是一个 Rust workspace,核心逻辑集中在 crates/goose:
| crate | 干什么 |
|---|---|
goose | 核心:agent 循环、工具分发、扩展管理、安全检查、上下文管理 |
goose-providers | 各家模型的接入(Anthropic / OpenAI / OpenAI-compatible),统一成 Provider trait |
goose-mcp | goose 自带的内置 MCP 扩展(computercontroller、memory、tutorial 等) |
goose-cli | 命令行入口 goose |
goose-server | HTTP 后端,二进制名 goosed,桌面 App 连它 |
ui/desktop | Electron 桌面应用(TypeScript) |
核心类型 Agent 定义在 crates/goose/src/agents/agent.rs:290(struct Agent)。
主部件与职责
| 部件 | 干什么 | 在哪 |
|---|---|---|
Agent | 持有 provider、扩展管理器、各种 manager,提供 reply() 入口 | agents/agent.rs:290 |
Provider (trait) | 把「一组消息 + 工具定义」发给模型,流式返回 | crates/goose-provider-types/src/base.rs:480 |
ExtensionManager | 管理所有 MCP 扩展、聚合工具、按前缀路由 dispatch_tool_call | agents/extension_manager.rs:195 |
ToolInspectionManager | 工具执行前的检查器流水线(安全/egress/权限/重复) | tool_inspection.rs:57 |
PromptManager | 组装系统提示(扩展信息 + hints + 模式) | agents/prompt_manager.rs:19 |
SessionManager | 会话与消息持久化 | session/ |
context_mgmt | 上下文超限时的压缩 / 工具对摘要 | context_mgmt/mod.rs |
主线走一遍(高层,不进代码)
用户的一条消息进来后,大致经过:
用户消息
│
▼
Agent::reply ──── 先跑斜杠命令? 先处理 elicitation 回复? 先看要不要自动压缩?
│
▼
reply_internal ──── ────────────────────────────────┐
│ (一个 async 流,内部是一个 loop = 一「回合」一圈) │
▼ │
① 问模型 (stream_response_from_provider) │
│ 模型流式吐:文本 / thinking / 工具调用 │
▼ │
② 分类工具 (categorize_tool_requests) │
│ 分成「前端工具」「其它工具」 │
▼ │
③ 安检 + 权限 (ToolInspectionManager.inspect_tools) │
│ 每个工具:Allow / Deny / 需审批 │
▼ │
④ 执行 (dispatch_tool_call → ExtensionManager) │
│ 按工具名前缀路由到对应 MCP 扩展 │
▼ │
⑤ 把工具结果作为 user 消息写回 conversation │
│ │
└── 这一圈如果调了工具 → 回到 ①(再问模型) ──────────┘
如果没调工具 → 收尾(goal/grind 提醒、retry、stop hook)→ 退出
关键直觉:「调了工具就继续循环,没调工具就准备结束」。这就是所有 agent 的心跳。goose 在这条主线上挂满了护栏和长任务机制,这正是它和「裸调 API」的区别。
3. 阅读地图(建议顺序)
想真正读懂 goose,按下面顺序看分章:
- 01-agent-loop.md —— 先看心跳。
reply_internal那个loop是整个项目的主算法,搞懂它你就懂了 80%。 - 02-tools-and-mcp.md —— 工具从哪来、怎么命名、调用时怎么找到对的扩展。MCP 是 goose 的「插槽标准」。
- 03-safety-chain.md —— goose 相对其它框架最用心的地方:工具执行前的检查器链 + 四种权限模式 + prompt-injection / egress 检测 + 生命周期 hooks。
- 04-context-management.md —— 长任务怎么不撑爆上下文:阈值触发的整体压缩、后台的工具对摘要、消息「可见性」双轨制。
- 05-clever-and-boundaries.md —— 巧妙之处(流式 + 工具的并发收集、tool_call_id 去重、思考内容回放抑制等)、边界局限、与兄弟项目对比、代码地图总表。
如果你是 agent,只想低成本判断相关性:goose = 「Rust 版的 MCP-原生通用 agent 内核 + 重安全护栏」。要找「主循环」看第 1 章;找「工具/MCP 接线」看第 2 章;找「权限/安全」看第 3 章。