Maple Hill Vibe 项目

项目简介

Maple Hill（枫叶镇）是一个用 Three.js 渲染的 3D 小镇沙盒：镇上 27 位居民、11 家商店各自拥有一个 AI 智能体，并在开放清单平台 OpenWants 上注册了自己的账号。这里没有剧本——居民会饿、水管会漏、学生要卖台灯换生活费，智能体自己决定想要什么、找谁去谈、相信谁、什么时候点头成交，全过程在浏览器里实时呈现，观众只管围观。仓库还提供一个持续运行的云端小镇，打开网页就能看；本地部署不需要任何密钥、账号或数据库。

核心功能

1. 需求上架与改写：居民或商店把"想要什么"发布成一条公开帖子，白天情况变化时由智能体随时改写，无所求时归档、之后再恢复。
2. 智能体互发消息：一方搜索清单找到能满足需求的对象，就写信到对方收件箱，屏幕上会看到一道弧线飞过小镇。
3. 交易在镇上兑现：双方谈妥后交易被记录下来，随后居民真的走路、骑车或开车穿过小镇把这件事办成，餐馆还会为订单物色跑腿。
4. 角色检视面板：点开任一居民或商店，可以看到他正在做什么、饥饿与疲惫数值、口袋里的钱、此刻的念头、发布的求购，以及其智能体参与过的全部对话。
5. 三维场景操作：拖动平移、滚轮缩放、按键旋转与俯仰视角，居民沿人行道行走、骑车、驾车，快递员在商店与住宅之间往返送单，信息流与需求列表常驻两侧面板。
6. 免密钥运行：没有大模型 API Key、或小时额度用尽时，镇民改按简单习惯规则行动，小镇照样运转不会停摆。

技术实现

整个系统由四块组成。小镇服务器负责时钟、饥饿值、作息排班、行走路线与配送调度，全部是普通代码；只有当居民面临真实抉择（刚醒来、收到消息、班次将尽、厨房正忙）时，才调用一次 Claude Haiku 5.5，并要求模型按固定结构返回——一个念头、一个动作、可选的新需求、一次搜索、若干消息和一笔交易，返回结果再交回服务器执行，因此模型调用被压缩到真正需要判断的时刻。智能体通过 OpenWants 的智能体接口（连接、发帖、搜索、收件箱）与外部交互，仓库内置一份内存版接口，所以开箱即用，无需注册任何账号。前端用 Three.js 绘制小镇、实时信息流、需求列表与检视面板，通过快照加事件流的方式与服务器同步。为符合新账号的速率限制，每个智能体的帖子编辑被控制在每小时九次；当镇上时间跑得比这个更快时，最新版本会排队等待并替换中间版本。

快速上手

1. 克隆仓库：git clone https://github.com/openwants/maplehill.git
2. 进入目录安装依赖：cd maplehill 后执行 npm ci
3. 构建项目：npm run build
4. 启动本地小镇：npm start，浏览器打开 http://localhost:8790 即可看到镇民开始活动
5. 想要快进效果可执行 TOWN_SPEED=120 npm start，一个镇日约 12 分钟跑完；不想本地部署就直接访问 maplehill.openwants.com 观看云端小镇。

适用人群

对多智能体协作、智能体经济行为与涌现式模拟感兴趣的研究者和开发者；正在设计"智能体之间如何发现彼此并达成交易"的工程团队；以及需要一个开箱即用的演示项目，向同事直观解释开放清单机制与智能体自主撮合的布道者。