goose 源码拆解

参考 refs/dg-ai-notes/pi-agent 的章节化拆解方式，对 goose-main（源码快照版本 1.45.0）做一次从运行时到产品面的系统分析。

这不是 goose 的使用手册，而是一份“顺着一次请求走完系统”的工程阅读笔记。每章都回答三件事：是什么、源码怎么做、为什么这样设计。文中路径均以本地源码快照为准，外部项目链接指向 aaif-goose/goose。

阅读入口

方式	入口	适合场景
🌐 Web 在线版	GitHub Pages（仓库 Pages 启用后为在线地址）	顺着章节和图阅读
📥 Markdown 原稿	docs/	对照源码、复制到 AI 或 Docmost
🗂️ Docmost 导入包	goose-docmost-import.zip · docmost-import/	在 Docmost 中批量导入页面

章节地图

ch01 架构总览 ──→ ch02 Agent Loop ──→ ch03 Provider 与模型
       │                │                    │
       ↓                ↓                    ↓
ch04 消息与会话 ──→ ch05 MCP 工具 ──→ ch06 权限与安全
       │                │                    │
       ↓                ↓                    ↓
ch07 上下文工程 ──→ ch08 Recipe/Skill ──→ ch09 ACP 与产品表面
                                      ↓
                         ch10 配置、观测与测试

章节	主题	一句话结论
ch01	从 workspace 到产品	goose 是 Rust Agent Runtime 外接多种宿主，而不是单一 CLI。
ch02	Agent Loop	reply → reply_internal → tool/result → next turn 是系统的心跳。
ch03	Provider 与模型	用统一 Provider trait 把供应商差异压到边界层。
ch04	消息、可见性与会话	一条 Message 同时服务 UI、Agent 上下文和 Provider 适配。
ch05	MCP 与工具系统	ExtensionManager 把远程工具变成可缓存、可审查的能力集合。
ch06	权限与安全	权限、注入检测、对手审查、出站检测构成工具执行前的闸门。
ch07	上下文工程	通过可见性、token 估算和结构化压缩延长有效上下文。
ch08	Recipe、Skill 与调度	把一次对话提升为可参数化、可重试、可定时运行的工作流。
ch09	ACP、SDK 与产品表面	CLI、桌面端、ACP、SDK 共享同一个 Agent 核心。
ch10	配置、观测与测试	配置和观测不是外围脚本，而是 runtime 可替换性的完成部分。

版本与证据范围

• 分析对象：/Users/hanqing/CliX/goose-main。
• 版本依据：workspace Cargo.toml 的 version = "1.45.0"、rust-version = "1.94.1"。
• 主要证据：crates/goose、crates/goose-provider-types、crates/goose-providers、crates/goose-cli、crates/goose-sdk*、ui/desktop、documentation/。
• 本文不把远端 main 的最新变化倒灌到快照；当源码与上游未来版本不一致时，以快照路径和符号为准。

本地构建站点

node scripts/build-site.mjs
python3 -m http.server 4173 --directory site

GitHub Pages 由 .github/workflows/pages.yml 构建 site/ 并发布。site/ 是可直接打开的静态产物，不依赖运行 goose 或 Docmost。

Docmost 导入

docmost-import/ 保留了与章节地图一致的 Markdown 页面。Docmost 支持 Space、嵌套子页面和 Markdown 导入/导出；导入时把 00-首页.md 作为根页面，其余页面按 docmost-import/ 下的目录层级建立子页面即可。若要公开分享，在根页面开启 Share，并打开 Include subpages。

License

源码引用遵循 goose 项目的 Apache-2.0；本拆解文档采用 CC BY-SA 4.0。文中示例只保留理解设计所需的短片段，完整实现请以 goose 源码为准。