数据流

AI 世界模拟器项目的数据流设计旨在确保数据的一致性、实时性和高效传输。整个系统围绕后端服务 (ai-world-sim) 作为核心数据源，前端 (ai-world-sim-web) 负责数据的消费和可视化。

1. 核心数据实体

项目中的主要数据实体包括：

• World (世界)：全局世界状态，如时间、季节、天气、情绪等。
• Character (角色)：NPC 和玩家角色的详细信息，包括属性、位置、职业、状态等。
• Location (地点)：世界中的具体地点，如房屋、商店、广场等，包含其类型、名称和在地图上的坐标。
• GameEvent (游戏事件)：世界中发生的各种事件，如角色行动、对话、环境变化等。
• Memory (记忆)：角色长期和短期记忆，用于 AI 决策和行为生成。

2. 数据流概览

3. 详细数据流

3.1 前端到后端 (请求-响应)

1. 用户操作：用户在前端界面进行操作（如登录、创建角色、查看详情）。
2. API 客户端：前端的 api.ts 模块封装了对后端 API 的请求。
3. API 端点：后端 Hono 框架定义的 RESTful API 接收请求，进行身份验证、数据校验。
4. 业务逻辑：后端根据请求调用相应的业务逻辑，可能涉及 D1 数据库查询、AI 模块决策等。
5. 数据返回：后端将处理结果以 JSON 格式返回给前端。

3.2 后端到前端 (实时事件推送)

1. 世界 Tick 引擎：后端的核心 Tick 引擎以固定频率运行，驱动世界状态的演进和 AI 行为的生成。
2. AI 决策模块：在每个 Tick 中，AI 模块根据角色需求、记忆和环境进行决策，生成新的游戏事件和角色状态。
3. D1/Vectorize 数据库：新的世界状态、角色状态和记忆被持久化到 D1 和 Vectorize 数据库。
4. SSE 网关：后端通过 Server-Sent Events (SSE) 机制，将最新的游戏事件和世界状态实时推送到所有连接的前端客户端。
5. 前端状态管理：前端 useWorld Composables 接收 SSE 事件，更新本地状态，并触发 PixiJS 渲染器重新绘制。

3.3 素材管线

1. AI 图像生成：通过调用 Agnes AI API，根据 Prompt 生成原始像素风格图像。
2. 素材处理脚本：Python 脚本对原始图像进行自动化处理，包括：
   • 背景移除：将图像背景变为透明。
   • 裁剪与缩放：将图像裁剪到目标尺寸，并进行等比缩放。
   • 图集打包：使用 TexturePacker 等工具将多张图片打包成 PixiJS 兼容的精灵图集（一张 PNG 大图和一份 JSON 描述文件）。
3. R2 对象存储：生成的精灵图集上传到 Cloudflare R2 进行存储和 CDN 分发。
4. 前端加载：前端 PixiJS 渲染器通过 textureAtlas.ts 模块从 R2 加载精灵图集，并根据 JSON 描述文件获取单个精灵的纹理。

4. 数据持久化

• D1 数据库：用于存储结构化数据，如世界状态、角色属性、地点信息、游戏事件日志等。D1 是基于 SQLite 的边缘数据库，提供低延迟访问。
• Vectorize 向量数据库：用于存储角色的长期记忆和语义信息。AI 模块在决策时会查询 Vectorize，以获取相关的历史记忆，实现更复杂的行为。

---

作者：Manus AI 日期：2026年7月10日