AI Town
用于构建可自定义 AI 虚拟小镇的全栈起步项目。
按维度查看评分与理由
证据显示：项目使用环境变量管理API密钥，未发现硬编码凭据；但未提供用户确认机制，数据流描述有限，敏感数据处理缺乏细节，依赖安全未提及，外部效果（如网络调用）未明确说明，回滚机制仅提及数据库重置，来源归属仅通过README中的致谢。扣分原因：缺少用户确认、数据流透明度和敏感数据处理的详细说明。
证据显示：README和代码结构一致，提供了多种部署方式；但依赖可用性未验证，失败消息在故障排除部分有提供。扣分原因：依赖可用性未验证，失败消息覆盖不全面。
证据显示：面向开发者和爱好者，提供了多种部署场景和自定义选项；但触发精度（如环境变量配置）描述不够精确，环境适配（如Windows）有说明。扣分原因：触发精度不足。
证据显示：README结构清晰，安装说明详细，命名稳定，有示例和FAQ，MIT许可证明确；但缺少版本变更日志，维护责任未明确。扣分原因：缺少版本变更日志和维护责任说明。
证据显示：输出可用性高，提供了可运行的模拟世界，边际价值明显，成本效益合理（免费开源）。扣分原因：无重大扣分。
证据显示：README中的声明部分可追溯，但缺乏外部验证，事实与推断未明确区分。扣分原因：缺乏外部验证和事实推断分离。
- 项目依赖外部服务（Convex, Ollama, OpenAI等），需注意API密钥管理和数据隐私。
- 未提供用户确认机制，可能自动执行外部调用。
- 缺少版本变更日志，维护责任不明确。
这个 Agent 能做什么，适合哪些场景？
AI Town 是一个让 AI 角色在虚拟小镇中生活、聊天和社交的可部署起步项目。前端以 PixiJS 的 <Game/> 组件负责交互、渲染与背景音乐播放，后端采用 Convex 提供共享全局状态、事务、模拟引擎、数据库和向量检索。角色、故事和精灵图引用位于 data/characters.ts，地图由 convex/init.ts 加载，并可通过 Tiled 与 convertMap.js 更换。默认在本地通过 Ollama 使用 llama3 和 mxbai-embed-large，也可配置 OpenAI、Together.ai 或其他 OpenAI 兼容 API。项目可运行在 Convex 标准环境，或用 Docker Compose 自托管 Convex；前端默认访问地址为 http://localhost:5173。
启动后，npm run dev 会运行应用并将浏览器界面提供在 http://localhost:5173；也可分别执行 npm run dev:frontend 与 npm run dev:backend。Convex 后端保存模拟世界的共享状态与记忆嵌入，并通过配置的聊天模型生成角色对话；默认配置会连接 Ollama，使用 llama3 进行聊天、mxbai-embed-large 生成嵌入。它从 data/characters.ts 读取角色、故事、精灵图引用和移动参数，从 convex/init.ts 加载地图数据，并由 PixiJS 在 <Game/> 中渲染互动。可选的 convex/music.ts 会借助 Replicate 和 MusicGen 生成每日背景音乐，convex/crons.ts 负责相关定时任务。维护时可用 testing:stop、testing:resume、testing:kick、testing:archive、testing:wipeAllTables 和 init 控制或重置世界。
- 想把角色设定和剧情做成可互动像素小镇的 TypeScript 开发者，可修改 data/characters.ts 后重新初始化世界。
- 需要本地试验 AI 角色对话与记忆检索的团队，可用 Ollama、llama3 和 mxbai-embed-large 运行默认配置。
- 需要由数据库事务和共享世界状态驱动多人模拟游戏原型的开发者，可将应用部署到 Convex。
- 受限于本地基础设施、但希望运行完整前端、后端和管理面板的开发者，可使用 Docker Compose 自托管 Convex。
- 希望将现有 OpenAI 兼容模型服务接入角色对话的工程师，可配置 LLM_API_URL、LLM_API_KEY、LLM_MODEL 与 LLM_EMBEDDING_MODEL。
- 要替换小镇场景的游戏内容作者，可用 Tiled 导出两层 JSON 地图，再用 data/convertMap.js 转换。
这个 Agent 有哪些优点和局限？
- 把实时共享状态、事务、模拟引擎、数据库和向量检索集中在 Convex 后端，适合持续运行的世界模拟。
- 角色、故事、精灵图和地图替换路径均有明确文件与转换流程，便于从默认小镇改造成自己的主题。
- 默认支持完全本地的 Ollama 推理，同时记录了 OpenAI、Together.ai 与 OpenAI 兼容服务的配置路径。
- 既支持 Convex 标准部署，也提供前端、后端和仪表盘一起运行的 Docker Compose 自托管方案。
- 核心架构依赖 Convex；标准开发流程需要 Convex 账户，即使可选择自托管。
- 默认模型依赖本机 Ollama，Docker 场景还需要配置容器到 Ollama 的网络连通性。
- 切换 LLM 提供商或嵌入模型后需要删除数据并重新开始，因为向量维度必须与嵌入模型匹配。
- 修改角色数据需要执行 testing:wipeAllTables，会清除所有现有数据。
- 模拟窗口空闲五分钟后会暂停，除非加载页面、手动恢复，或修改停止非活动世界的 cron。
如何安装或部署这个 Agent？
标准安装：git clone https://github.com/a16z-infra/ai-town.git && cd ai-town && npm install，然后执行 npm run dev；该流程需要登录 Convex 账户，浏览器访问 http://localhost:5173。默认本地推理还需安装并启动 Ollama，执行 ollama pull llama3，再用 ollama run llama3 验证模型。若改用 OpenAI，在 convex/util/llm.ts 中将 EMBEDDING_DIMENSION 设为 OPENAI_EMBEDDING_DIMENSION，并执行 npx convex env set OPENAI_API_KEY 'your-key'。自托管方式可执行 docker compose up --build -d；随后执行 docker compose exec backend ./generate_admin_key.sh，配置 CONVEX_SELF_HOSTED_ADMIN_KEY 与 CONVEX_SELF_HOSTED_URL，并运行 npm run predev。
如何使用这个 Agent？
首次启动后打开 http://localhost:5173 查看并运行小镇。修改角色或故事时编辑 data/characters.ts，然后执行 npx convex run testing:wipeAllTables 和 npm run dev，使初始角色数据重新上传；该清理命令会删除现有数据。修改地图时，用 Tiled 导出含 bgtiles 和 objmap 两层的 JSON，运行 node data/convertMap.js <mapDataPath> <assetPath> <tilesetpxw> <tilesetpxh>，再使用生成的 converted-map.js。生产环境先执行 npx convex deploy，再执行 npx convex run init --prod；前端可通过 vercel --prod 部署。
这个 Agent 与同类方案有什么区别？
运行方式上，标准 Convex 配置适合本地或云端开发，并需要 Convex 账户；Docker Compose 方案可自托管前端、后端和仪表盘，适合不使用账户且可接受 Docker 的情况。仓库还提到一个面向仅运行、不修改项目的社区 Pinokio 一键安装分支。