最近在调研 AI Agent 相关开源项目时看到不少开发者把“AI 小镇”当作入门多智能体系统的首选实验场。这类项目表面上是一群 AI 角色在虚拟小镇里生活、聊天、做计划背后却把大模型调用、记忆管理、行为规划、事件驱动和前端可视化全部串了起来。Oneiric 就是其中一个值得动手跑一遍的开源项目它的代码仓库地址是https://github.com/mewamew/my_ai_town项目同时提供了 macOS 和 Windows 版本的游戏化运行包。本文将从项目背景、核心原理、环境搭建、部署运行到常见问题完整拆解这套 AI 小镇方案的落地过程适合对 AI Agent 开发、AI 应用工程化和 AI 视频生成感兴趣的读者。1. 背景与核心概念Oneiric 到底解决了什么问题1.1 从单轮对话到 AI Agent 小镇过去几年大多数人接触 AI 的方式是聊天机器人你问一句模型答一句。这种交互虽然方便但本质上是被动的——模型不会主动想起前一天聊过什么不会自己制定明天的计划也不会因为“隔壁邻居心情不好”而改变自己的行动。AI Agent智能体的出现改变了这个模式。Agent 可以在目标驱动下自主决策调用工具记忆上下文并在一个持续运行的环境中与其他 Agent 协作。而 AI 小镇类项目就是把多个 Agent 放进同一个虚拟空间让它们像真实居民一样生活每天按计划起床、吃饭、工作、社交并且把经历形成记忆影响后续行为。Oneiric 正是这样一个开源项目。它的名字 oneiric 在英文里表示“梦境的、虚幻的”很贴切地描述了项目的体验一个由 AI 自主驱动、不断演化的虚拟小镇。项目把多个 AI Agent 组合到一个可视化的城镇场景中Agent 之间可以移动、对话、产生事件整套系统最终可以生成类似短剧或游戏实况的视频内容。1.2 Oneiric 项目定位与核心能力从技术角度看Oneiric 至少覆盖了以下几块能力多 Agent 生命周期管理每个角色都有自己的状态、位置、目标和行为循环。大模型驱动的对话与决策Agent 的言行不是脚本写死的而是通过调用大模型动态生成。记忆与状态持久化角色能记住过往事件并在后续行为中体现出来。可视化与视频输出小城镇界面实时渲染可以把 Agent 的互动过程录制成视频。开源可二次开发项目提供完整代码开发者可以修改角色、场景、模型接入方式。用一句话概括Oneiric 是一个把“AI 角色扮演 虚拟世界模拟 视频生成”结合起来的开源工程。1.3 同类项目对比Generative Agents、AI Town 与 Oneiric提到 AI 小镇很多人会想到斯坦福大学和谷歌联合发表的论文《Generative Agents: Interactive Simulacra of Human Behavior》论文里 25 个 AI 角色在小镇中自主生活表现出社交、记忆、反思等行为。后来 a16z 开源了简化版的 AI Town把架构改成了 React TypeScript 为主的前端体验。Oneiric 与这类项目的本质区别在于工程化程度和交付形态Generative Agents 偏学术研究重论文复现工程链路复杂。a16z AI Town 偏向 Web 演示适合理解 Agent 基础交互。Oneiric 更接近“可下载、可运行、可出片”的完整产品原型同时保留开源扩展能力。对开发者来说Oneiric 是一个很好的学习样本既能研究多 Agent 系统的设计又能直接拿到一套能跑起来、能录制视频的成品。2. 环境准备与版本说明2.1 系统与硬件要求Oneiric 项目提供了 macOS 和 Windows 两个平台的运行包因此本机安装版本建议按以下条件准备操作系统macOS 12 及以上或者 Windows 10/11 64 位。内存建议 16GB 及以上。多 Agent 同时运行时Node.js 进程、浏览器渲染、向量检索都会占用内存。硬盘预留 5GB 以上空间用于源码、依赖包、模型缓存和视频输出。显卡如果使用本地大模型建议 NVIDIA 显卡显存 8GB 以上如果直接调用云端 API显卡不是必须项。需要说明的是版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。具体依赖版本请以仓库 README 为准。2.2 基础依赖环境从源码运行时至少需要以下基础环境Node.js用于前端页面和后端服务建议使用 18 或 20 的 LTS 版本。Python部分 Agent 逻辑或数据处理脚本可能用到建议 Python 3.9 以上。包管理器npm 或 pnpm按项目package.json的说明选择。Git用于克隆仓库。检查本机环境可以在终端执行node -v npm -v python3 --version git --version如果某个命令提示找不到需要先安装对应环境。Node.js 建议通过官网下载安装包或者使用 nvm 管理多版本。2.3 获取源码打开终端执行git clone https://github.com/mewamew/my_ai_town.git cd my_ai_town如果你不想自己从源码构建也可以直接下载项目提供的 AI 小镇游戏安装包macOS 和 Windows 版本都内置了运行环境打开即用。不过从源码运行能更清楚地看到背后的实现逻辑也方便后续二次开发。3. 核心原理拆解AI 小镇里的 Agent 是怎么运作的3.1 感知-思考-行动循环Oneiric 里的每个 Agent 都不是被动等待输入的而是按照一个循环不断运行感知PerceiveAgent 获取当前位置、周围角色、时间、事件等信息。思考ThinkAgent 结合当前状态、目标和记忆决定下一步要做什么。行动ActAgent 执行决策比如移动到某个地点、对某个角色说话、触发事件。记录Record行动结果写回记忆影响后续判断。这个循环和大模型推理天然匹配。感知阶段把环境信息组装成提示词思考阶段调用大模型生成决策结果行动阶段解析结果并更新小镇状态。一个简化版的 Agent 决策流程如下def agent_step(agent, world_state): # 1. 感知收集当前环境信息 observation perceive(agent, world_state) # 2. 思考调用大模型生成行动 prompt build_decision_prompt( agent.identity, # 角色设定 observation, # 环境观察 agent.memory.last(), # 最近记忆 agent.goal # 当前目标 ) action llm_chat(prompt) # 返回类似 go_to_market 或 talk_to_alice # 3. 行动更新世界状态 world_state.apply(agent, action) # 4. 记录写入记忆 agent.memory.add(action, timestampworld_state.clock)实际项目中提示词会比这个复杂得多但核心结构不变。理解这个循环是看懂整个项目代码的钥匙。3.2 记忆系统短期记忆与长期记忆AI 小镇能给人“角色真的在生活”的感觉靠的不是大模型的多轮对话能力而是记忆系统。常见实现分为两层短期记忆保存最近一次行动、最近的对话记录通常直接放在上下文中。长期记忆保存角色的历史经历数量大不能全部塞给大模型需要通过检索召回相关片段。长期记忆的检索一般借助向量数据库或向量索引。每条记忆先用 embedding 模型转为向量当 Agent 需要回忆时把当前状况也转成向量用余弦相似度或内积找到最相关的历史记忆。在 Oneiric 这类项目中记忆写入时机很关键。一般会在三种节点写入重要事件发生后比如与某个角色发生冲突。定时反思时Agent 会把近期经历浓缩成“认知”。每日结束时对当天经历做一次总结。这样Agent 的行为就不是无状态的随机生成而是带有个人“人生轨迹”的连续演化。3.3 多 Agent 协作与事件驱动当多个 Agent 同时存在于小镇中如何让它们产生真实的互动是另一个关键点。Oneiric 采用事件驱动的方式。小镇本身维护一个世界状态包含当前时间、地点、角色位置、事件队列。当一个 Agent 决定“去广场和 Alice 聊天”时小镇会生成一个移动事件当两个 Agent 到达同一地点会触发对话事件。事件驱动的好处是Agent 之间不需要直接互相调用而是通过共享世界状态解耦。这样新增角色、新增场景都比较容易不会因为耦合过深导致整个系统难以维护。结合事件机制一个完整的多 Agent 互动链路可以简化为Agent A 产生意图 - 写入世界事件队列 - 世界引擎按时间推进事件 - Agent A 和 Agent B 进入同一场景 - 当前景触发对话事件 - 两个 Agent 的决策循环同时运行 - 对话结果写回双方记忆这种方式在工程上非常实用也是后面我们做二次开发时重点要维护的部分。4. 完整实战从零部署 Oneiric 并生成 AI 视频4.1 项目结构概览从源码仓库克隆后先看目录结构my_ai_town/ ├── frontend/ # 前端页面展示小镇画面 │ ├── src/ │ ├── public/ │ └── package.json ├── backend/ # 后端服务管理 Agent 与世界状态 │ ├── src/ │ ├── data/ # 小镇初始数据、角色配置 │ └── package.json ├── agents/ # Agent 定义与提示词模板 ├── scripts/ # 启动、构建、导出脚本 ├── docker-compose.yml # 可选的一键编排 └── README.md不同版本的仓库结构可能略有差异但大体会分为前端渲染、后端服务和 Agent 定义三部分。如果你的仓库结构不同不要紧重点找到package.json和配置文件即可。4.2 配置模型服务Oneiric 的 Agent 决策依赖大模型。你可以选择两类方案云端 API配置 API Key例如 OpenAI 兼容接口。本地模型通过 Ollama 或 vLLM 部署本地模型局域网内提供服务。在项目根目录找到.env.example文件复制为.envcp .env.example .env然后编辑.env按需修改# 模型服务地址 MODEL_API_BASEhttps://api.openai.com/v1 # API Key MODEL_API_KEYsk-xxxxxx # 模型名称 MODEL_NAMEgpt-4o-mini # 是否启用本地模型 USE_LOCAL_MODELfalse LOCAL_MODEL_URLhttp://localhost:11434/v1 # 小镇模拟速度数值越大Agent 行动越快 SIMULATION_SPEED1.0这里的关键点在于MODEL_API_BASE。因为 Oneiric 使用 OpenAI 兼容接口所以只要你的模型服务支持/v1/chat/completions格式都可以通过修改 base 地址接入。如果你使用本地 Ollama则可以把USE_LOCAL_MODEL设为true并把LOCAL_MODEL_URL指向本机。4.3 启动后端与前端先安装依赖。建议在项目根目录执行npm install如果项目是前后端分离的可能需要分别进入frontend和backend目录安装cd backend npm install cd ../frontend npm install然后启动后端服务cd backend npm run dev看到类似下面的输出说明后端已经启动[server] listening on http://localhost:3001 [world] AI Town initialized with 5 agents [agent] Alice: planning next action...接着另开一个终端启动前端cd frontend npm run dev浏览器访问http://localhost:5173或项目 README 中提示的地址就能看到小镇画面和角色标记。4.4 运行 Agent 小镇并导出视频小镇启动后Agent 会按照自身循环不断行动。你通常能看到角色在地图上移动。角色头顶冒出对话气泡。左下角或侧边栏显示实时行为日志。右上角有时间控制按钮可以暂停、快进。Oneiric 的项目定位包含 AI 视频生成因此一般会提供一个录制或导出机制。常见的做法有两种第一种是浏览器端录制。你可以直接使用浏览器开发者工具或者配合 OBS 等录屏软件把小镇画面录制成视频。这种方式最简单适合做演示和分享。第二种是项目内置的导出脚本。在scripts/目录下如果有类似export_video.js或render_timeline.js的脚本可以按 README 说明执行node scripts/export_video.js --duration 120 --output output.mp4这里--duration控制导出时长--output指定输出文件。具体参数以项目实际实现为准本文只给出通用思路。4.5 验证 Agent 行为是否正常启动一段时间后如何判断项目运行正常建议观察以下几点角色是否持续产生新行为而不是卡在同一个状态。对话内容是否与角色设定一致比如设定为“商店老板”的角色不会突然谈论与自己无关的话题。记忆是否生效比如角色遇到曾经互动过的角色时对话里可能提到过去的事件。日志中是否有异常报错比如 API 超时、token 超限。如果以上都正常说明核心链路已经打通。接下来就可以调整角色设定、增加 Agent 数量或修改场景进入二次开发阶段。5. 常见问题与排查思路5.1 高频问题速查表问题现象常见原因解决思路启动报错MODEL_API_KEY is not set环境变量未配置或.env未加载确认.env文件存在检查变量名拼写Agent 长时间无响应API Key 失效、余额不足或限流查看后端日志直接调用 API 测试连接前端白屏前端服务未启动或端口占用检查npm run dev输出确认端口未被占用角色行为重复单一提示词模板中上下文不足丰富角色设定增加记忆检索片段视频导出失败缺少 ffmpeg 或编码器安装 ffmpeg确认系统 PATH 中可访问内存占用过高Agent 数量过多或向量批量加载减少 Agent 数量或改为按需加载记忆本地模型响应很慢显卡显存不足、模型量化级别不够使用更小的模型或调整量化参数5.2 典型排查过程演示假设你遇到“Agent 无响应”的问题不要急着改代码按下面的顺序排查第一步确认模型服务连通。用 curl 直接调用 OpenAI 兼容接口curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:llama3,messages:[{role:user,content:hello}]}如果本地服务返回正常说明问题不在模型层。第二步查看后端日志。重点搜索error、timeout、rate limit等关键词。限流时通常会在日志里看到 429 状态码。第三步检查 Agent 的循环日志。有些项目会输出agent:step之类的调试信息如果日志停在某一步说明是提示词解析或状态更新环节出了问题。第四步检查SIMULATION_SPEED配置。如果模拟速度过快Agent 决策频率可能超过模型 API 的吞吐上限表现为“看起来没反应”。适当调低速度即可。这套排查思路不仅适用于 Oneiric也适用于大多数多 Agent 工程项目。先分清楚问题在网络层、模型层还是应用层再分别处理。6. 最佳实践与工程建议6.1 配置与密钥安全.env文件里保存着 API Key绝对不能提交到 Git 仓库。建议在项目根目录检查.gitignore确认包含如下内容.env *.local node_modules/ dist/ output/如果你使用的是 Git 仓库还可以在提交前执行git status确认没有把.env加入暂存区。更稳妥的做法是使用密钥管理工具比如在 CI 或服务器上用环境变量注入而不是把 Key 写进文件。6.2 性能、成本与可观测性AI 小镇类项目的成本主要集中在模型调用上。每个 Agent 每走一步都可能触发一次大模型请求。为了控制成本可以从三方面优化减少无效调用Agent 没有状态变化时跳过决策请求使用缓存结果。精简上下文只传当前场景相关的内容不要把全部记忆塞进提示词。使用性价比模型规划类任务用小模型对话生成用大模型按需分流。可观测性同样重要。建议给每一步 Agent 行为增加结构化日志至少包含timestamp, agent_id, action_type, model_name, prompt_tokens, completion_tokens, latency_ms有了这些日志才能判断哪个角色耗费 token 多、哪段时间延迟高从而针对性优化。6.3 二次开发与生产化扩展如果要把 Oneiric 从玩具 Demo 变成生产级应用有几个方向值得投入持久化存储把世界状态和记忆从内存挪到 PostgreSQL 或 Redis 等持久化服务。消息队列Agent 之间的事件通过消息队列异步处理避免阻塞主循环。多模型适配抽象统一的模型接口方便在 GPT、Claude、本地模型之间切换。权限与多租户如果面向多个用户提供小镇服务需要增加用户隔离和资源配额。安全审查对 Agent 生成的文本做合规过滤防止出现不当内容。其中安全审查容易被忽略。多 Agent 长时间自主运行时生成内容的不可控性会放大。建议在模型输出写回世界状态之前增加一层过滤或人工审核机制。涉及生产环境变更时务必先在测试环境验证完整流程并做好数据备份。7. 总结与下一步学习建议通过 Oneiric可以一次接触到 AI Agent 开发中最核心的几块内容感知循环、记忆检索、多智能体协作、世界状态管理以及视频输出链路。这个项目最大的价值在于它把抽象的概念变成了可运行、可观察、可录制的真实系统适合作为学习和二次开发的起点。如果接下来想继续深入建议按顺序做三件事一是先把默认小镇完整跑通记录每个角色的行为日志理解它们的决策规律二是修改角色设定和提示词模板观察行为变化三是在项目中加入自己的模块比如新的场景事件、新的记忆策略或者接入本地模型。动手实践是理解 AI 工程最好的方式。把 Oneiric 跑起来只是第一步真正有价值的是在此基础上持续迭代和扩展。如果部署过程中遇到问题建议先查看日志再对照本文的排查思路逐步定位。希望这篇教程能帮你顺利跑通自己的 AI 小镇。
AI小镇开源项目Oneiric实战：多智能体系统部署与视频生成
最近在调研 AI Agent 相关开源项目时看到不少开发者把“AI 小镇”当作入门多智能体系统的首选实验场。这类项目表面上是一群 AI 角色在虚拟小镇里生活、聊天、做计划背后却把大模型调用、记忆管理、行为规划、事件驱动和前端可视化全部串了起来。Oneiric 就是其中一个值得动手跑一遍的开源项目它的代码仓库地址是https://github.com/mewamew/my_ai_town项目同时提供了 macOS 和 Windows 版本的游戏化运行包。本文将从项目背景、核心原理、环境搭建、部署运行到常见问题完整拆解这套 AI 小镇方案的落地过程适合对 AI Agent 开发、AI 应用工程化和 AI 视频生成感兴趣的读者。1. 背景与核心概念Oneiric 到底解决了什么问题1.1 从单轮对话到 AI Agent 小镇过去几年大多数人接触 AI 的方式是聊天机器人你问一句模型答一句。这种交互虽然方便但本质上是被动的——模型不会主动想起前一天聊过什么不会自己制定明天的计划也不会因为“隔壁邻居心情不好”而改变自己的行动。AI Agent智能体的出现改变了这个模式。Agent 可以在目标驱动下自主决策调用工具记忆上下文并在一个持续运行的环境中与其他 Agent 协作。而 AI 小镇类项目就是把多个 Agent 放进同一个虚拟空间让它们像真实居民一样生活每天按计划起床、吃饭、工作、社交并且把经历形成记忆影响后续行为。Oneiric 正是这样一个开源项目。它的名字 oneiric 在英文里表示“梦境的、虚幻的”很贴切地描述了项目的体验一个由 AI 自主驱动、不断演化的虚拟小镇。项目把多个 AI Agent 组合到一个可视化的城镇场景中Agent 之间可以移动、对话、产生事件整套系统最终可以生成类似短剧或游戏实况的视频内容。1.2 Oneiric 项目定位与核心能力从技术角度看Oneiric 至少覆盖了以下几块能力多 Agent 生命周期管理每个角色都有自己的状态、位置、目标和行为循环。大模型驱动的对话与决策Agent 的言行不是脚本写死的而是通过调用大模型动态生成。记忆与状态持久化角色能记住过往事件并在后续行为中体现出来。可视化与视频输出小城镇界面实时渲染可以把 Agent 的互动过程录制成视频。开源可二次开发项目提供完整代码开发者可以修改角色、场景、模型接入方式。用一句话概括Oneiric 是一个把“AI 角色扮演 虚拟世界模拟 视频生成”结合起来的开源工程。1.3 同类项目对比Generative Agents、AI Town 与 Oneiric提到 AI 小镇很多人会想到斯坦福大学和谷歌联合发表的论文《Generative Agents: Interactive Simulacra of Human Behavior》论文里 25 个 AI 角色在小镇中自主生活表现出社交、记忆、反思等行为。后来 a16z 开源了简化版的 AI Town把架构改成了 React TypeScript 为主的前端体验。Oneiric 与这类项目的本质区别在于工程化程度和交付形态Generative Agents 偏学术研究重论文复现工程链路复杂。a16z AI Town 偏向 Web 演示适合理解 Agent 基础交互。Oneiric 更接近“可下载、可运行、可出片”的完整产品原型同时保留开源扩展能力。对开发者来说Oneiric 是一个很好的学习样本既能研究多 Agent 系统的设计又能直接拿到一套能跑起来、能录制视频的成品。2. 环境准备与版本说明2.1 系统与硬件要求Oneiric 项目提供了 macOS 和 Windows 两个平台的运行包因此本机安装版本建议按以下条件准备操作系统macOS 12 及以上或者 Windows 10/11 64 位。内存建议 16GB 及以上。多 Agent 同时运行时Node.js 进程、浏览器渲染、向量检索都会占用内存。硬盘预留 5GB 以上空间用于源码、依赖包、模型缓存和视频输出。显卡如果使用本地大模型建议 NVIDIA 显卡显存 8GB 以上如果直接调用云端 API显卡不是必须项。需要说明的是版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。具体依赖版本请以仓库 README 为准。2.2 基础依赖环境从源码运行时至少需要以下基础环境Node.js用于前端页面和后端服务建议使用 18 或 20 的 LTS 版本。Python部分 Agent 逻辑或数据处理脚本可能用到建议 Python 3.9 以上。包管理器npm 或 pnpm按项目package.json的说明选择。Git用于克隆仓库。检查本机环境可以在终端执行node -v npm -v python3 --version git --version如果某个命令提示找不到需要先安装对应环境。Node.js 建议通过官网下载安装包或者使用 nvm 管理多版本。2.3 获取源码打开终端执行git clone https://github.com/mewamew/my_ai_town.git cd my_ai_town如果你不想自己从源码构建也可以直接下载项目提供的 AI 小镇游戏安装包macOS 和 Windows 版本都内置了运行环境打开即用。不过从源码运行能更清楚地看到背后的实现逻辑也方便后续二次开发。3. 核心原理拆解AI 小镇里的 Agent 是怎么运作的3.1 感知-思考-行动循环Oneiric 里的每个 Agent 都不是被动等待输入的而是按照一个循环不断运行感知PerceiveAgent 获取当前位置、周围角色、时间、事件等信息。思考ThinkAgent 结合当前状态、目标和记忆决定下一步要做什么。行动ActAgent 执行决策比如移动到某个地点、对某个角色说话、触发事件。记录Record行动结果写回记忆影响后续判断。这个循环和大模型推理天然匹配。感知阶段把环境信息组装成提示词思考阶段调用大模型生成决策结果行动阶段解析结果并更新小镇状态。一个简化版的 Agent 决策流程如下def agent_step(agent, world_state): # 1. 感知收集当前环境信息 observation perceive(agent, world_state) # 2. 思考调用大模型生成行动 prompt build_decision_prompt( agent.identity, # 角色设定 observation, # 环境观察 agent.memory.last(), # 最近记忆 agent.goal # 当前目标 ) action llm_chat(prompt) # 返回类似 go_to_market 或 talk_to_alice # 3. 行动更新世界状态 world_state.apply(agent, action) # 4. 记录写入记忆 agent.memory.add(action, timestampworld_state.clock)实际项目中提示词会比这个复杂得多但核心结构不变。理解这个循环是看懂整个项目代码的钥匙。3.2 记忆系统短期记忆与长期记忆AI 小镇能给人“角色真的在生活”的感觉靠的不是大模型的多轮对话能力而是记忆系统。常见实现分为两层短期记忆保存最近一次行动、最近的对话记录通常直接放在上下文中。长期记忆保存角色的历史经历数量大不能全部塞给大模型需要通过检索召回相关片段。长期记忆的检索一般借助向量数据库或向量索引。每条记忆先用 embedding 模型转为向量当 Agent 需要回忆时把当前状况也转成向量用余弦相似度或内积找到最相关的历史记忆。在 Oneiric 这类项目中记忆写入时机很关键。一般会在三种节点写入重要事件发生后比如与某个角色发生冲突。定时反思时Agent 会把近期经历浓缩成“认知”。每日结束时对当天经历做一次总结。这样Agent 的行为就不是无状态的随机生成而是带有个人“人生轨迹”的连续演化。3.3 多 Agent 协作与事件驱动当多个 Agent 同时存在于小镇中如何让它们产生真实的互动是另一个关键点。Oneiric 采用事件驱动的方式。小镇本身维护一个世界状态包含当前时间、地点、角色位置、事件队列。当一个 Agent 决定“去广场和 Alice 聊天”时小镇会生成一个移动事件当两个 Agent 到达同一地点会触发对话事件。事件驱动的好处是Agent 之间不需要直接互相调用而是通过共享世界状态解耦。这样新增角色、新增场景都比较容易不会因为耦合过深导致整个系统难以维护。结合事件机制一个完整的多 Agent 互动链路可以简化为Agent A 产生意图 - 写入世界事件队列 - 世界引擎按时间推进事件 - Agent A 和 Agent B 进入同一场景 - 当前景触发对话事件 - 两个 Agent 的决策循环同时运行 - 对话结果写回双方记忆这种方式在工程上非常实用也是后面我们做二次开发时重点要维护的部分。4. 完整实战从零部署 Oneiric 并生成 AI 视频4.1 项目结构概览从源码仓库克隆后先看目录结构my_ai_town/ ├── frontend/ # 前端页面展示小镇画面 │ ├── src/ │ ├── public/ │ └── package.json ├── backend/ # 后端服务管理 Agent 与世界状态 │ ├── src/ │ ├── data/ # 小镇初始数据、角色配置 │ └── package.json ├── agents/ # Agent 定义与提示词模板 ├── scripts/ # 启动、构建、导出脚本 ├── docker-compose.yml # 可选的一键编排 └── README.md不同版本的仓库结构可能略有差异但大体会分为前端渲染、后端服务和 Agent 定义三部分。如果你的仓库结构不同不要紧重点找到package.json和配置文件即可。4.2 配置模型服务Oneiric 的 Agent 决策依赖大模型。你可以选择两类方案云端 API配置 API Key例如 OpenAI 兼容接口。本地模型通过 Ollama 或 vLLM 部署本地模型局域网内提供服务。在项目根目录找到.env.example文件复制为.envcp .env.example .env然后编辑.env按需修改# 模型服务地址 MODEL_API_BASEhttps://api.openai.com/v1 # API Key MODEL_API_KEYsk-xxxxxx # 模型名称 MODEL_NAMEgpt-4o-mini # 是否启用本地模型 USE_LOCAL_MODELfalse LOCAL_MODEL_URLhttp://localhost:11434/v1 # 小镇模拟速度数值越大Agent 行动越快 SIMULATION_SPEED1.0这里的关键点在于MODEL_API_BASE。因为 Oneiric 使用 OpenAI 兼容接口所以只要你的模型服务支持/v1/chat/completions格式都可以通过修改 base 地址接入。如果你使用本地 Ollama则可以把USE_LOCAL_MODEL设为true并把LOCAL_MODEL_URL指向本机。4.3 启动后端与前端先安装依赖。建议在项目根目录执行npm install如果项目是前后端分离的可能需要分别进入frontend和backend目录安装cd backend npm install cd ../frontend npm install然后启动后端服务cd backend npm run dev看到类似下面的输出说明后端已经启动[server] listening on http://localhost:3001 [world] AI Town initialized with 5 agents [agent] Alice: planning next action...接着另开一个终端启动前端cd frontend npm run dev浏览器访问http://localhost:5173或项目 README 中提示的地址就能看到小镇画面和角色标记。4.4 运行 Agent 小镇并导出视频小镇启动后Agent 会按照自身循环不断行动。你通常能看到角色在地图上移动。角色头顶冒出对话气泡。左下角或侧边栏显示实时行为日志。右上角有时间控制按钮可以暂停、快进。Oneiric 的项目定位包含 AI 视频生成因此一般会提供一个录制或导出机制。常见的做法有两种第一种是浏览器端录制。你可以直接使用浏览器开发者工具或者配合 OBS 等录屏软件把小镇画面录制成视频。这种方式最简单适合做演示和分享。第二种是项目内置的导出脚本。在scripts/目录下如果有类似export_video.js或render_timeline.js的脚本可以按 README 说明执行node scripts/export_video.js --duration 120 --output output.mp4这里--duration控制导出时长--output指定输出文件。具体参数以项目实际实现为准本文只给出通用思路。4.5 验证 Agent 行为是否正常启动一段时间后如何判断项目运行正常建议观察以下几点角色是否持续产生新行为而不是卡在同一个状态。对话内容是否与角色设定一致比如设定为“商店老板”的角色不会突然谈论与自己无关的话题。记忆是否生效比如角色遇到曾经互动过的角色时对话里可能提到过去的事件。日志中是否有异常报错比如 API 超时、token 超限。如果以上都正常说明核心链路已经打通。接下来就可以调整角色设定、增加 Agent 数量或修改场景进入二次开发阶段。5. 常见问题与排查思路5.1 高频问题速查表问题现象常见原因解决思路启动报错MODEL_API_KEY is not set环境变量未配置或.env未加载确认.env文件存在检查变量名拼写Agent 长时间无响应API Key 失效、余额不足或限流查看后端日志直接调用 API 测试连接前端白屏前端服务未启动或端口占用检查npm run dev输出确认端口未被占用角色行为重复单一提示词模板中上下文不足丰富角色设定增加记忆检索片段视频导出失败缺少 ffmpeg 或编码器安装 ffmpeg确认系统 PATH 中可访问内存占用过高Agent 数量过多或向量批量加载减少 Agent 数量或改为按需加载记忆本地模型响应很慢显卡显存不足、模型量化级别不够使用更小的模型或调整量化参数5.2 典型排查过程演示假设你遇到“Agent 无响应”的问题不要急着改代码按下面的顺序排查第一步确认模型服务连通。用 curl 直接调用 OpenAI 兼容接口curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:llama3,messages:[{role:user,content:hello}]}如果本地服务返回正常说明问题不在模型层。第二步查看后端日志。重点搜索error、timeout、rate limit等关键词。限流时通常会在日志里看到 429 状态码。第三步检查 Agent 的循环日志。有些项目会输出agent:step之类的调试信息如果日志停在某一步说明是提示词解析或状态更新环节出了问题。第四步检查SIMULATION_SPEED配置。如果模拟速度过快Agent 决策频率可能超过模型 API 的吞吐上限表现为“看起来没反应”。适当调低速度即可。这套排查思路不仅适用于 Oneiric也适用于大多数多 Agent 工程项目。先分清楚问题在网络层、模型层还是应用层再分别处理。6. 最佳实践与工程建议6.1 配置与密钥安全.env文件里保存着 API Key绝对不能提交到 Git 仓库。建议在项目根目录检查.gitignore确认包含如下内容.env *.local node_modules/ dist/ output/如果你使用的是 Git 仓库还可以在提交前执行git status确认没有把.env加入暂存区。更稳妥的做法是使用密钥管理工具比如在 CI 或服务器上用环境变量注入而不是把 Key 写进文件。6.2 性能、成本与可观测性AI 小镇类项目的成本主要集中在模型调用上。每个 Agent 每走一步都可能触发一次大模型请求。为了控制成本可以从三方面优化减少无效调用Agent 没有状态变化时跳过决策请求使用缓存结果。精简上下文只传当前场景相关的内容不要把全部记忆塞进提示词。使用性价比模型规划类任务用小模型对话生成用大模型按需分流。可观测性同样重要。建议给每一步 Agent 行为增加结构化日志至少包含timestamp, agent_id, action_type, model_name, prompt_tokens, completion_tokens, latency_ms有了这些日志才能判断哪个角色耗费 token 多、哪段时间延迟高从而针对性优化。6.3 二次开发与生产化扩展如果要把 Oneiric 从玩具 Demo 变成生产级应用有几个方向值得投入持久化存储把世界状态和记忆从内存挪到 PostgreSQL 或 Redis 等持久化服务。消息队列Agent 之间的事件通过消息队列异步处理避免阻塞主循环。多模型适配抽象统一的模型接口方便在 GPT、Claude、本地模型之间切换。权限与多租户如果面向多个用户提供小镇服务需要增加用户隔离和资源配额。安全审查对 Agent 生成的文本做合规过滤防止出现不当内容。其中安全审查容易被忽略。多 Agent 长时间自主运行时生成内容的不可控性会放大。建议在模型输出写回世界状态之前增加一层过滤或人工审核机制。涉及生产环境变更时务必先在测试环境验证完整流程并做好数据备份。7. 总结与下一步学习建议通过 Oneiric可以一次接触到 AI Agent 开发中最核心的几块内容感知循环、记忆检索、多智能体协作、世界状态管理以及视频输出链路。这个项目最大的价值在于它把抽象的概念变成了可运行、可观察、可录制的真实系统适合作为学习和二次开发的起点。如果接下来想继续深入建议按顺序做三件事一是先把默认小镇完整跑通记录每个角色的行为日志理解它们的决策规律二是修改角色设定和提示词模板观察行为变化三是在项目中加入自己的模块比如新的场景事件、新的记忆策略或者接入本地模型。动手实践是理解 AI 工程最好的方式。把 Oneiric 跑起来只是第一步真正有价值的是在此基础上持续迭代和扩展。如果部署过程中遇到问题建议先查看日志再对照本文的排查思路逐步定位。希望这篇教程能帮你顺利跑通自己的 AI 小镇。