快速启动
给开发者的启动指南。Clone 仓库后读此文件，了解项目全貌。
项目架构
4 个仓库，共用一个 Cloudflare 账户：
songdaochuanshu/
├── ai-world-sim # 后端 — Cloudflare Workers + Hono + D1
├── ai-world-sim-web # 前端 — Vue 3 + PixiJS 8 像素地图
├── ai-world-sim-docs # 文档 — VitePress（本仓库）
└── cloudflare-assets # 资产中心 — R2 图片 + AI 博客 + 邮件通知后端 (ai-world-sim)
技术栈
| 层 | 选择 |
|---|---|
| 运行时 | Cloudflare Workers |
| 框架 | Hono |
| 数据库 | Cloudflare D1 (SQLite) |
| 向量库 | Cloudflare Vectorize |
| 外部记忆 | MemOS |
| LLM | Agnes / GLM / OpenAI 兼容 |
| 部署 | GitHub Actions → Cloudflare Workers |
本地开发
bash
cd ai-world-sim
npm install
cp .dev.vars.example .dev.vars # 填入你的 secrets
npm run dev # wrangler dev (localhost:8787)数据库初始化
bash
# 本地
npm run db:init:local
# 远程
npm run db:init:remote环境变量
非密钥变量在 wrangler.toml 的 [vars] 中。密钥通过 wrangler secret put 设置：
bash
wrangler secret put AGNES_API_KEY
wrangler secret put MEMOS_API_KEY
wrangler secret put JWT_SECRETAPI 端点
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /v1/auth/register | 注册 |
| POST | /v1/auth/login | 登录 |
| GET | /v1/me | 当前用户 |
| GET | /v1/world/list | 世界列表 |
| GET | /v1/world/state | 世界状态 |
| POST | /v1/character/create | 创建角色 |
| GET | /v1/character/:id | 角色详情 |
| POST | /v1/character/:id/chat | 与角色对话 |
| POST | /v1/character/:id/command | 下达指令 |
| GET | /v1/events/stream | SSE 实时事件 |
| GET | /v1/events/recent | 最近事件 |
| POST | /v1/admin/tick | 手动 tick |
前端 (ai-world-sim-web)
技术栈
| 层 | 选择 |
|---|---|
| 框架 | Vue 3 + TypeScript |
| 构建 | Vite 8 |
| 渲染 | PixiJS 8 |
| 状态 | Pinia |
| 路由 | Vue Router 4 |
| 部署 | GitHub Actions → Cloudflare Pages |
本地开发
bash
cd ai-world-sim-web
npm install
npm run dev # localhost:5173确保后端在 localhost:8787 运行。Vite 已配置代理。
构建
bash
npm run build # vue-tsc 类型检查 + vite build文档 (ai-world-sim-docs)
bash
cd ai-world-sim-docs
npm install
npm run docs:dev # localhost:5173
npm run docs:build # 构建到 docs/.vitepress/dist系统设计
季节系统
- 一年 365 天，每季 91 天
- 春: Day 0-90 / 夏: Day 91-181 / 秋: Day 182-272 / 冬: Day 273-364
- 季节末尾 10 天为过渡期，色调渐变
- 影响地形 tile、树木状态、天气概率、环境粒子
天气系统
- 9 种天气类型：晴/多云/阴/小雨/暴雨/小雪/暴风雪/雾/雷阵雨
- 天气受季节影响概率（春多雨、冬多雪）
- 每种天气有粒子效果、色调偏移、能见度变化
记忆系统
- 短期记忆：D1 存储，最近 N 条交互
- 长期记忆：D1 + Vectorize 向量检索
- MemOS 集成：外部记忆服务
部署
CI/CD
- 后端：push 到 main → GitHub Actions →
wrangler deploy - 前端：push 到 main → GitHub Actions → Cloudflare Pages
- 文档：push 到 main → GitHub Actions → Cloudflare Pages
所需 GitHub Secrets
| Secret | 说明 |
|---|---|
CLOUDFLARE_API_TOKEN | Cloudflare API Token |
CLOUDFLARE_ACCOUNT_ID | Cloudflare Account ID |
AGNES_API_KEY | Agnes AI API Key |
MEMOS_API_KEY | MemOS API Key |
CROSS_REPO_TOKEN | GitHub PAT (跨仓库触发) |
常见问题
- API 请求失败：检查后端是否启动，
ai-world-sim-web的 vite 代理配置 - 素材加载失败：检查
public/assets目录和 R2 配置 - PixiJS 渲染异常：参考渲染器设计文档，检查素材尺寸、锚点和层级
- 类型错误：运行
npx tsc --noEmit（后端）或npx vue-tsc -b（前端）
作者：songdaochuanshu 更新：2026-07-12