基于论文中提出的设计方案,项目作者开发了一个模拟游戏以进行验证。此前的文章已对代码编译的相关细节进行了介绍。今天我们将进一步深入探讨该实现的具体代码层面。
技术栈
- 主要代码基于 Python 实现
- 前端技术: HTML/CSS/JavaScript (Django模板,服务器端渲染)
- 集成 openAI 大语言模型集成
- 涉及到地图部分可能会用到: Tiled
代码架构分析
1. 分层架构设计
plain
表现层 (Frontend)
├── Django模板系统
├── JavaScript前端逻辑
└── CSS样式控制
业务逻辑层 (Backend)
├── 仿真控制器 (ReverieServer)
├── 代理行为系统 (GenerativeAgent)
└── 认知模块 (Cognitive Modules)
数据层 (Storage)
├── 文件系统存储
├── 内存缓存
└── 状态序列化
2. 关键设计模式
- 观察者模式
- 策略模式
- 状态模式
3. 数据流向分析
仿真主循环
plain
1. 感知阶段:收集环境信息
2. 检索阶段:查询相关记忆
3. 规划阶段:制定行动计划
4. 执行阶段:执行具体行动
5. 反思阶段:更新认知状态
6. 存储阶段:持久化数据
前后端通信
plain
前端 → 后端:用户命令和控制指令
后端 → 前端:状态更新和可视化数据
存储 ← 后端:仿真数据持久化
存储 → 后端:历史数据加载
后端核心文件解析
仿真服务器核心 (reverie/backend_server/
)
reverie.py
- 主仿真控制器
python
"""
核心功能:
- ReverieServer类:管理整个仿真状态
- 仿真循环控制:时间步进和状态更新
- 代理调度:协调多个AI代理的行为
- 状态持久化:保存和恢复仿真状态
"""
class ReverieServer:
def __init__(self, fork_sim_code, sim_code):
# 初始化仿真环境
# 加载地图、代理、环境配置
def start_simulation(self):
# 启动仿真主循环
# 处理代理决策和环境更新
def save_simulation(self):
# 保存当前仿真状态
# 支持增量保存和完整快照
主要功能模块:
- 仿真状态管理
- 代理生命周期控制
- 环境交互处理
- 命令行界面控制
- 数据持久化管理
utils.py
- 配置和工具函数
python
# 配置参数
openai_api_key = "<Your OpenAI API>"
key_owner = "<Your Name>"
maze_assets_loc = "../../environment/frontend_server/static_dirs/assets"
env_matrix = f"{maze_assets_loc}/the_ville/matrix"
env_visuals = f"{maze_assets_loc}/the_ville/visuals"
fs_storage = "../../environment/frontend_server/storage"
fs_temp_storage = "../../environment/frontend_server/temp_storage"
collision_block_id = "32125"
debug = True
功能职责:
- 系统配置管理
- 路径和资源定位
- 调试参数控制
- API密钥管理
代理行为模块 (reverie/backend_server/persona/
)
persona.py
- 代理人格和行为核心
python
class GenerativeAgent:
def __init__(self, name, first_name, last_name, age, innate, learned,
currently, lifestyle, living_area, daily_plan_req, f_daily_schedule):
# 初始化代理基本属性
self.name = name
self.memory = AssociativeMemory() # 记忆系统
self.scratch = Scratch() # 临时状态
def perceive(self, maze):
# 感知环境变化
# 更新记忆流
def retrieve(self, query):
# 检索相关记忆
# 基于重要性和相关性排序
def plan(self, maze, personas, new_day, retrieved):
# 制定行动计划
# 基于当前状态和目标
def execute(self, maze, personas, plan):
# 执行具体行动
# 与环境和其他代理交互
核心能力:
- 记忆流管理
- 环境感知
- 行为规划
- 社交互动
memory_structures/
- 记忆系统
associative_memory.py
: 联想记忆实现scratch.py
: 临时状态管理spatial_memory.py
: 空间记忆系统
认知架构模块 (reverie/backend_server/persona/cognitive_modules/
)
converse.py
- 对话系统
python
def generate_agent_chat(maze, init_persona, target_persona, retrieved,
curr_context, init_summ_idea, target_summ_idea):
"""
生成代理间对话
- 基于GPT生成自然对话
- 考虑人格特征和当前情境
- 维护对话连贯性
"""
plan.py
- 规划模块
python
def revise_identity(persona):
"""修订代理身份认知"""
def daily_plan(persona, wake_up_hour):
"""生成每日计划"""
def hourly_plan(persona, curr_hour_str, p_f_ds_hourly_org, hour_str,
intermittent_chatting, maze):
"""生成每小时计划"""
perceive.py
- 感知模块
python
def perceive(persona, maze, address_tiles, curr_tile):
"""
感知环境变化
- 检测周围实体
- 更新空间记忆
- 触发记忆存储
"""
retrieve.py
- 检索模块
python
def retrieve(persona, focal_pt, n_count=30):
"""
检索相关记忆
- 基于焦点查询
- 计算相关性分数
- 返回排序结果
"""
reflect.py
- 反思模块
python
def reflect(persona, focal_pt):
"""
生成反思和洞察
- 分析记忆模式
- 生成高级认知
- 更新信念系统
"""
工具和实用程序
compress_sim_storage.py
- 仿真数据压缩
python
def compress(sim_code):
"""
压缩仿真数据
- 移除冗余信息
- 优化文件大小
- 生成演示版本
"""
前端核心文件解析
环境服务器 (environment/frontend_server/
)
manage.py
- Django管理入口
python
#!/usr/bin/env python
"""Django's command-line utility for administrative tasks."""
import os
import sys
if __name__ == '__main__':
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'frontend_server.settings')
# Django应用启动逻辑
frontend_server/
- Django应用配置
settings.py
: Django配置文件urls.py
: URL路由配置views.py
: 视图函数定义models.py
: 数据模型定义
simulator/
- 仿真器应用
views.py
: 仿真相关视图models.py
: 仿真数据模型templates/
: HTML模板文件
静态资源 (environment/frontend_server/static_dirs/
)
assets/the_ville/
- 游戏资源
matrix/
: 地图矩阵数据visuals/
: 可视化资源meta.json
: 环境元数据
css/
- 样式文件
style.css
: 主样式表simulator.css
: 仿真器样式
js/
- JavaScript文件
simulator.js
: 仿真器前端逻辑utils.js
: 工具函数
数据存储 (environment/frontend_server/storage/
)
仿真数据结构
plain
storage/
├── base_the_ville_n25/ # 25代理基础仿真
├── base_the_ville_isabella_maria_klaus/ # 3代理基础仿真
└── [simulation_name]/ # 自定义仿真
├── personas/ # 代理状态
├── environment/ # 环境状态
├── movements/ # 移动记录
└── meta.json # 元数据
bash
environment/frontend_server/storage/base_the_ville_isabella_maria_klaus
├── environment
│ └── 0.json
├── personas
│ ├── Isabella\ Rodriguez
│ │ └── bootstrap_memory
│ │ ├── associative_memory
│ │ │ ├── embeddings.json
│ │ │ ├── kw_strength.json
│ │ │ └── nodes.json
│ │ ├── scratch.json
│ │ └── spatial_memory.json
│ ├── Klaus\ Mueller
│ │ └── bootstrap_memory
│ │ ├── associative_memory
│ │ │ ├── embeddings.json
│ │ │ ├── kw_strength.json
│ │ │ └── nodes.json
│ │ ├── scratch.json
│ │ └── spatial_memory.json
│ └── Maria\ Lopez
│ └── bootstrap_memory
│ ├── associative_memory
│ │ ├── embeddings.json
│ │ ├── kw_strength.json
│ │ └── nodes.json
│ ├── scratch.json
│ └── spatial_memory.json
└── reverie
└── meta.json