TouchGrass：基于开源大模型的户外游戏手机裁判助手

这是 Hacktoberfest 开源 AI 挑战赛第 1 周：TouchGrass 的参赛作品。

我构建了什么

TouchGrass 是一款运行在手机上的户外游戏裁判，这样就不必有人留下来计分。

理念很简单：每个人都应该能专注于玩耍，而不是争论规则、计分或看时间。TouchGrass 旨在处理这些任务，让朋友、家人和青年团体能有更多时间在户外玩耍。

该项目包含一个游戏引擎、一个多人服务器、持久化的游戏会话，以及由开源权重模型驱动的 AI 游戏主持人（Game Master）。

游戏主持人可以为每一轮提出一个变体：例如安全区规则、额外挑战或增加一点时间。但有一个重要的区别：AI 仅提出建议；游戏引擎负责决定。

模型永远不会直接更改游戏状态。其提议必须通过普通代码中实现的三个检查，才能被应用：

Gemma 提出建议
      ↓
模式验证
      ↓
游戏合法性检查
      ↓
确定性安全验证
      ↓
游戏引擎应用事件
      ↓
玩家收到更新

如果模型响应缓慢、产生格式错误的输出、提议了非法事件或被关闭，游戏可以在没有该 AI 事件的情况下继续进行。

该项目旨在为那些希望有理由去公园的朋友、家人和青年团体服务，也为所有曾经争论过“是否被抓到”的人而设计。

当前可用功能：Tag（抓人）和 Hide & Seek（捉迷藏）支持 2–4 名玩家游玩，包含三轮比赛并决出获胜者。另外三款游戏 Ice & Fire（冰与火）、Treasure Hunt（寻宝）和 Nature Challenge（自然挑战）已定义规则，但尚不可玩。网站将它们标记为“即将推出”，而非假装已完成。

基于浏览器的游戏客户端尚未实现。游戏流程已通过本地游戏服务器进行了测试。

演示

在线网站：https://touchgrass-game-master.vercel.app/

在线网站展示了项目、游戏、规则和设计理念。它目前尚不支持直接在浏览器中进行完整的游戏对局。

本地演示：游戏服务器已在本地环境中使用多名玩家和真实的游戏主持人回合进行了测试。下面的录像展示了会话创建、玩家加入、一轮开始，以及在验证后应用游戏主持人事件的流程。

代码

GitHub 仓库：https://github.com/SHWETANK-SAURABH/touchgrass_game_master

本项目采用 MIT 许可证。README 文件中包含了安装依赖项、运行验证、启动服务器以及尝试本地演示所需的命令。

我是如何构建它的

核心的开源 AI

游戏主持人使用了三个关键组件：

• Gemma 3 (4B)：一个开源权重模型，通过 Ollama 在本地提供服务。
• Mastra：一个开源智能体框架，用于构建游戏主持人智能体的结构。
• 可替换的模型提供商：应用程序可以使用 Ollama 或通过配置选择的兼容模型端点。

在我的本地设置中，Gemma 运行在我自己的机器上。在这种配置下，进行游戏主持人回合不需要托管 AI API。

一条规则塑造了整个架构：

AI 提出建议。安全层进行验证。游戏引擎执行操作。

语言模型可能会出错、响应缓慢，或以不适合户外游戏的方式发挥创意。它不应负责判断某个动作是否合法或游戏状态是否有效。

相反，TouchGrass 使用确定性的游戏引擎。游戏事件会与规则进行检查，相同的有效事件序列会产生相同的游戏状态转换。这使得核心机制可以独立于模型进行测试。

模型被视为不可信的建议来源，而非游戏的权威决策者。

在游戏主持人回合期间会发生什么？

每个回合都遵循受控的流程管道：

1. 智能体接收游戏上下文。它看到的是经过裁剪的当前游戏视图，而非不受限制的内部状态。
2. 它可以使用两个只读工具。game_history 用于检索历史游戏记录，而 game_rules 提供有关规则和约束的信息。
3. 它返回结构化的提议。响应必须符合预期的模式，并通过 Zod 进行验证。
4. 引擎检查合法性。对于当前游戏状态无效的事件将被拒绝。
5. 确定性安全层检查提议。它会拒绝已识别的不安全事件类型和选项。
6. 引擎应用被接受的事件。只有经过验证的事件才能改变游戏状态，随后更新会被广播并持久化。

工具调用不能直接改变游戏状态。未知的工具会被拒绝，且工具的输入和输出受到限制。

如果模型产生格式错误的输出或提议未能通过验证，游戏将不应用该无效事件。

这种设计让 AI 能够贡献创意，同时又不赋予其控制规则的权力。

其余技术栈

• monorepo 中的 TypeScript
• 用于网站的 Next.js 16
• 用于多人会话的 WebSocket 游戏服务器
• 用于持久化游戏会话的 MongoDB
• 用于 Game Master 智能体的 Mastra
• 通过 Ollama 进行本地推理的 Gemma 3 (4B)
• 用于结构化输出验证的 Zod
• Sentry 集成及应用级可观测性
• 用于 Game Master 行为的自动化评估套件

该仓库包含超过 2,000 个自动化测试，其中包括 35 个脚本化的 Game Master 评估场景。目标是使变更可衡量，而不是仅依赖提示词听起来是否更好。

生产服务器目前使用单进程多人架构。它并非为多个独立的游戏服务器实例共享同一数据库而设计。

我诚实学到的教训

1. 模型看到了它不该看到的东西。

在开发过程中，一个游戏加入代码通过历史游戏记录泄露到了模型的视图中。模型并不需要这些信息。我将问题追溯至历史视图并修正了脱敏处理。

那次经历强化了一个重要的教训：限制模型的权限是不够的。它所接收的信息也必须仅限于其所需的内容。

1. 小模型可以很谨慎。

在我对 Gemma 3 (4B) 的测试中，Game Master 经常选择延长回合。这是一个合法且安全的选项，但反复使用会使游戏变得缺乏变化。

较小的模型可用于受控任务，但其行为仍需评估。下一个挑战是在不削弱验证规则的情况下鼓励更多的多样性。

1. 安全规则有其局限性。

安全验证器是一组确定性规则。它可以拒绝它识别出的危险，但它不知道玩家所在的公园、附近的交通状况或他们周围的实际环境。

它并不能使户外游戏自动变得安全。玩家仍需要运用判断力并遵守当地的安全规则。

1. 成功的模型响应并不等同于成功的游戏事件。

模型可以返回有效的 JSON，但仍可能建议在当前游戏中非法的操作。结构化输出仅解决了问题的一部分。

将模式验证、引擎合法性检查和安全性验证分开，使得这些失败案例更易于测试和推理。

为什么开放创新很重要？

因为我可以运行和检查开源权重的模型，有三件事变得更容易了。

我可以检查模型的输入和输出

由于在我的开发设置中，Gemma 通过 Ollama 在本地运行，我可以检查进入模型的内容以及返回的内容。

这帮助我发现并纠正了加入代码泄露的问题。

开源权重并不能自动保证隐私或安全，但它们让开发者对推理环境拥有更多控制权，并使调查模型行为变得更加容易。

评估套件为我提供了可重复的基线

游戏主持人（Game Master）评估套件包含 35 个预设场景，涵盖了预期结果和失败阶段。

针对固定模型版本运行这些测试，使我在更改提示词、工具描述或安全规则时进行的比较更具意义。这并不能消除模型的变异性，但为我提供了一个可重复的基线。

本地推理避免了按次调用的托管 AI 费用

在我的本地配置中，游戏主持人通过 Ollama 运行，无需向托管 AI 提供商发起按次调用。

这使得那些不希望产生基于使用量的 AI 账单的开发人员、家庭和社区团体能够更便捷地进行实验。

需要区分的是，本地推理并不等同于完全离线的应用程序：必须先安装依赖项和模型权重，且其他服务可能仍需要网络访问权限。

更广泛的好处在于实验的自由度。任何人都可以添加新游戏、替换模型、改进评估套件或翻译安全规则，而无需获得封闭 API 提供商的许可。

奖项类别

最佳 Gemma 应用

Gemma 3 (4B) 担任游戏主持人。通过 Ollama，它接收游戏上下文，可以查阅只读工具，并以结构化 JSON 形式提出单一的游戏转折建议。

该架构围绕小型开源权重模型所能贡献的想法构建，同时将合法性判定和执行留给确定性代码处理。

最佳 Mastra 应用

游戏主持人智能体是使用 Mastra 构建的。其两个只读工具 game_history 和 game_rules 在智能体提出事件前提供额外的上下文信息。

该应用程序并未赋予智能体对游戏的无限制控制权。在任何变更生效之前，其输出必须通过现有的模式验证、引擎合法性检查和安全审查。

下一步是什么？

当前的优先任务是构建基于浏览器的游戏玩法客户端，使剩余三款游戏可玩，并在不损害安全边界的前提下提升游戏主持人事件的多样性。

我还希望让开源贡献者更容易地扩展该项目，方法包括完善游戏定义、增加更多评估场景、提升无障碍功能以及进行本地化适配。

我借助 AI 编程助手构建了 TouchGrass，包括在实现和本文撰写方面的协助。架构决策、测试以及关于项目能诚实宣称的内容等决定，均由我负责。

核心理念很简单：利用开源权重 AI 让游戏变得更有趣，但绝不让模型成为裁判。

让模型提出建议。让代码进行检查。让大家都能尽情游玩。