goose Tutorial 扩展 first-game 教程详解：让 AI Agent 带你从零做一个 Flappy Bird

本文围绕 goose 内置 Tutorial 扩展中随仓库分发的教程脚本 first-game.md 展开。该文档是 goose 内置教程服务器（TutorialServer）通过 load_tutorial 工具动态加载的"第一课"，指导用户用 Python + Pygame 做出第一个可运行的游戏。读完本文，你将理解：这份教程文档在 goose 源码中是如何被打包、索引并注入给 Agent 的；教程本身覆盖的完整学习路径（从环境搭建到核心游戏循环、机制开发与迭代打磨）；以及如何启用 tutorial 扩展并按脚本完成"第一只会飞的鸭子"。

一、first-game 在 goose 中的定位：一个被编译进二进制的教程脚本

先说清楚这份文档不是给人直接阅读的普通文档，而是 Agent 的教学大纲——它写给 goose 内部的 LLM 看，用来指导 Agent 以交互式方式陪用户一步步完成开发。

从源码结构看，集成机制非常清晰：

• 教程文件被编译进二进制：tutorial/mod.rs 第 14 行通过 include_dir!("$CARGO_MANIFEST_DIR/src/tutorial/tutorials") 把整个 tutorials/ 目录嵌入 crate，因此 first-game.md 随 goose 一起分发，无需用户额外下载；
• 服务器启动时自动索引可用教程：get_available_tutorials() 遍历内嵌目录，用每个文件第一行内容作为简介生成清单（- {文件名}: {首行}），并拼入服务器 instructions。也就是说 first-game.md 第一行的 # Building Your First Game 会被 Agent 在"可用教程列表"中直接看到；
• Agent 通过 MCP 工具按需拉取全文：load_tutorial 工具（第 84-107 行）根据 name 参数拼出 {name}.md 并在内嵌目录中查找，命中后以 ContentBlock::Text 返回，并打上 audience: [Assistant] 注解——表示内容主要供模型消费，而非原样展示给用户。找不到时返回 Could not locate tutorial '{name}' 错误；
• 服务器 instructions 中还写死了一条与游戏教程直接相关的行为约束（第 42-58 行）：执行教程时先给说明再执行命令——"在运行启动游戏的命令之前，先让用户知道将会发生什么"，并且一次不要连发太多工具调用，要保持互动。

TutorialServer 是四个内置扩展之一，与 autovisualiser、computercontroller、memory 一起注册在 goose-mcp/src/lib.rs 的 BUILTIN_EXTENSIONS 表中；CLI 侧在 cli.rs 中由 McpCommand::Tutorial 分支启动：serve(TutorialServer::new())。官方文档 tutorial-mcp.md 确认了 first-game 是内置的两个可用教程之一（另一个是 build-mcp-extension）。

测试用例（mod.rs 的 #[cfg(test)] 部分）验证了上述行为的边界：可用清单非空、load_tutorial 成功时内容带 Assistant 受众注解、不存在时错误信息包含 Could not locate tutorial。

启用方式（来自 tutorial-mcp.md）：在 goose CLI 中运行 goose configure，选择 Toggle Extensions，勾选 tutorial；桌面端则在扩展安装入口启用 Tutorial 扩展。启用后可以直接对 goose 说 "Can you walk me through the first-game tutorial?"，Agent 便会调用 load_tutorial 拉取这份脚本并进入教学流程。

二、初始讨论：先定游戏与栈，再动手写代码

教程脚本的第一步不是写代码，而是摸清用户背景，共三层问题：

1. 编程经验

• 是否完全零基础？
• 是否熟悉某种特定语言？
• 是否做过游戏开发？

2. 游戏偏好：默认推荐 Flappy Bird，同时给出三个替代方案，各自侧重的技术点不同：

游戏	核心技术点
Flappy Bird（默认）	物理模拟与碰撞检测
Snake	网格移动与"生长"机制
Pong	双人交互与球的物理
Breakout	碰撞与计分机制

如果用户已有明确想法，教程要求尊重其选择，并帮助用户理解所选游戏的复杂度，必要时降级调整。

3. 技术栈选择：默认 Python + Pygame（对新手友好、跨平台），备选：

• JavaScript + Canvas：Web 端运行、便于分享；
• Lua + LÖVE：轻量、适合学习；
• C# + MonoGame：适合 Windows 用户或想过渡到 Unity 的人。

选栈时要权衡四个因素：目标系统上的安装复杂度、学习曲线、可获得的资料数量、用户未来的编程方向。

三、环境搭建：venv 隔离依赖 + git 版本控制

教程脚本给出的环境搭建顺序是：版本控制 → 语言 → 依赖管理 → 游戏框架，四步走完才算就绪。

1. 版本控制：安装并配置 git，对新手解释基本概念，创建初始仓库。

2. 编程语言：按所选语言走安装流程，验证安装是否成功（报错时协助排查），并演示如何在环境中运行代码。

3. 依赖管理：解释"为什么需要依赖隔离"后给出 Python 的标准做法（教程原文命令）：

python -m venv env
source env/bin/activate  # or env\Scripts\activate on Windows

其他语言的等价隔离手段：Node 用 package.json，Rust 用 Cargo.toml，以此类推。

4. 游戏框架：安装并验证所选框架（Pygame），先写一个最小测试程序并确认能成功运行——这一步是后续一切工作的前置验证，跑不通就停在这里排查，避免在坏环境上堆业务代码。

四、项目结构与游戏主循环：教程脚本中的两个工程骨架

项目结构部分要求先讨论再动手：文件结构、代码组织、素材（asset）管理方式；随后创建初始文件——主游戏文件、配置（如需要）、素材目录（如需要）；最后为所选技术栈配置 .gitignore，完成首次提交并向用户解释提交策略。

核心游戏循环部分是整个教程的技术内核，拆成两块：

1. 窗口搭建

• 创建游戏窗口；
• 搭起游戏循环（典型的"事件处理 → 更新状态 → 渲染"主循环）；
• 处理基础事件：退出、重新开始。

2. 游戏状态

• 定义核心游戏对象（如玩家、管道/障碍物、分数）；
• 建立状态管理；
• 区分 update 与 draw——逻辑更新和画面绘制分离，这是后续所有机制开发能保持可维护性的关键约束。

到这一步，屏幕上应该已经有一个能跑起来、能退出的空窗体，教程意义上的"最小可运行版本"达成。

五、机制开发、测试迭代与后续扩展

教程把剩余实现切成三块渐进式推进：

1. 玩家交互：输入处理 → 基础移动 → 实际玩一遍并调"手感"（flappy 的跳跃高度、响应延迟这类参数）。

2. 核心机制（随游戏类型变化）：主游戏元素、基础碰撞检测、分数记录。

3. 渐进增强：额外功能、打磨与精修、修 bug。

测试与打磨从两个维度做：

• 可玩性：测试核心机制、调整难度、精调操作手感；
• 代码质量：找出重复代码、提出改进建议、向用户解释改进的收益。

扩展与学习给出两条后续路径：

• 功能增强：画面改进、音效、新玩法、菜单系统；
• 学习机会：代码结构优化、性能优化、进阶特性、相关主题延伸阅读。

六、Default Implementation 与 Agent 行为规范

教程脚本末尾固化了默认实现路径：当用户没有强烈偏好时，Agent 直接引导走 Python + Pygame + Flappy Bird 复刻 + virtualenv 管依赖 + git 管版本的组合。脚本给出的理由是这套组合做到"四个少/快"：安装复杂度最低、进度反馈快（很快能看到东西在屏幕上动）、下一步清晰、范围可控。

同时，脚本对 Agent 本身定了一组教学行为准则，这也解释了为什么 tutorial 扩展的 instructions 要求保持互动：

• 根据用户理解程度调整节奏，需要时给更详细的解释；
• 在合适的节点建议休息；
• 为小胜利和进展喝彩；
• 随时准备排查四类常见问题：安装问题、框架特定报错、游戏逻辑 bug、性能问题；
• 频繁确认用户是否理解，把新概念挂到用户已有知识上，耐心 debug，鼓励试验，维持正向的学习氛围。

七、把 first-game 跑起来的完整路径

综合源码与文档，完整流程是：

1. 通过 goose configure → Toggle Extensions 启用 tutorial 扩展（或桌面端启用 Tutorial）；
2. 对 goose 提出学习意图，例如 "walk me through the first-game tutorial"；
3. goose 调用 load_tutorial（参数 name: first-game），拿到这份 178 行教学脚本后，按脚本与用户交互：先聊经验与游戏偏好，再按"环境 → 结构 → 主循环 → 机制 → 迭代"的顺序推进，执行任何命令前都会先说明将要发生什么；
4. 走默认路径时，用户最终得到的是一个本地虚拟环境 + git 仓库 + 可运行的 Pygame Flappy Bird。

值得强调的是这份教程的设计取向：它不预设用户水平（初始讨论负责校准难度），不一次性倾倒代码（按 update/draw 分离、碰撞、计分逐块递进），并且把"教 Agent 怎么教人"写进了脚本本身（Notes for Agent 一节）。这正是 Tutorial 扩展与静态文档的区别——教程内容的消费方是模型，执行方是交互式会话，而 first-game.md 与 tutorial/mod.rs 的组合保证了脚本、索引、加载、行为约束四者在同一 crate 内闭环可测。