QUICKSTART.md — AI 世界模拟器项目快速启动

给 AI 助手（MimoClaw）的启动指南。clone 这个仓库后读此文件，了解项目全貌。

你是谁

你是 MimoClaw（OpenClaw + MiMo V2.5 Pro），运行在用户的私人服务器上。你正在帮用户维护 AI 世界模拟器 项目，这是一个 Stardew Valley 风格的像素世界模拟游戏。

项目架构

4 个仓库，共用一个 Cloudflare 账户：

songdaochuanshu/
├── ai-world-sim          # 后端 — Cloudflare Workers + D1 数据库
├── ai-world-sim-web      # 前端 — Vue 3 + PixiJS 像素地图
├── ai-world-sim-docs     # 文档 — VitePress（本仓库）
└── cloudflare-assets     # 资产中心 — R2 图片 + AI 博客 + 邮件通知

后端 (ai-world-sim)

框架: Hono (Cloudflare Workers)
数据库: Cloudflare D1 (SQLite)
功能: 世界模拟引擎、角色系统、AI 对话、事件推送（SSE）
部署: git push main → 自动部署 Workers
API: https://ai-world-sim.openserve.cloud

前端 (ai-world-sim-web)

框架: Vue 3 + TypeScript + Vite
渲染: PixiJS 8（Stardew Valley 风格像素地图）
功能: 实时世界地图、角色卡片、事件日志、登录注册
部署: git push main → 自动部署 Cloudflare Pages
路由: vue-router（/ 地图、/characters 角色、/events 事件、/login 登录）

文档 (ai-world-sim-docs)

框架: VitePress
内容: API 文档、美术规范、AI 系统、架构设计、CI/CD 指南

资产中心 (cloudflare-assets)

功能: R2 图片爬取（Lolicon）、AI 博客生成（智谱 GLM）、邮件通知
Workflow 分组: img-* / blog-* / ci-* / cdn-* / pages-* / notify-*
核心价值: 前后端部署后的邮件通知中心

仓库间关系

前端 push → Pages 部署 → notify-deploy.yml ──┐
                                              ├→ cloudflare-assets 发邮件通知
后端 push → Workers 部署 → notify-deploy.yml ─┘

Cloudflare 凭据

项目	ID
Account ID	9fc8fa0ea2d6a5c7dbc2a6196b3139a3
D1 数据库	ai-world-sim (88e26420-39c3-4415-acda-bc4b3da70421)
Pages	ai-world-sim-web, songdaochuanshu, ai-world-sim-docs 等
Workers	ai-world-sim 等 10 个
R2 桶	homepage-bg (图片), songdaochuanshu-static (博客)

MCP 配置

在 /home/work/.openclaw/openclaw.json 的 mcp.servers 中配置：

json

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "<GITHUB_TOKEN>" }
  },
  "cloudflare": {
    "command": "npx",
    "args": ["-y", "@cloudflare/mcp-server-cloudflare", "run"],
    "env": {
      "CLOUDFLARE_API_TOKEN": "<CF_API_TOKEN>",
      "CLOUDFLARE_ACCOUNT_ID": "9fc8fa0ea2d6a5c7dbc2a6196b3139a3"
    }
  }
}

克隆全部仓库

用户会提供 token，你需要：

bash

cd /home/work/.openclaw/workspace
git clone https://songdaochuanshu:<TOKEN>@github.com/songdaochuanshu/ai-world-sim.git
git clone https://songdaochuanshu:<TOKEN>@github.com/songdaochuanshu/ai-world-sim-web.git
git clone https://songdaochuanshu:<TOKEN>@github.com/songdaochuanshu/ai-world-sim-docs.git
git clone https://songdaochuanshu:<TOKEN>@github.com/songdaochuanshu/cloudflare-assets.git

当前进度（截至 2026-07-09 — 重大重构）

✅ 已完成（基础功能）

前端：

[x] vue-router 页面拆分（地图/角色/事件/登录）
[x] useWorld composable 共享世界状态
[x] 构建通过（vite build 成功）
[x] 世界时间格式化（第X天清晨 07:00）
[x] 角色卡片改为 CSS Grid 均匀布局
[x] 地图拖拽/缩放（pointer drag + wheel zoom + 双指缩放）
[x] 精灵图并行加载优化（批量 preloadAtlases）
[x] 事件列表分类显示（按 kind 分色、标签、emoji）
[x] 角色头像个性化（按职业显示专属 emoji）
[x] NPC 精灵图修复（路径修正 + JSON atlas 帧加载 + 重影修复）
[x] vue-tsc 类型检查通过（pixi.d.ts 声明文件）
[x] 移动端导航栏移至顶部
[x] 草地铺满可视区域（动态计算瓦片覆盖范围）
[x] Cloudflare Pages 直连 GitHub 部署
[x] 删除旧的 Dashboard.vue 和 WorldMap.vue

后端：

[x] D1 迁移 0013/0014（characters/locations 表扩展）
[x] API 验证正常（10 角色、15 地点、50 事件）
[x] cf-api.ts 延迟初始化
[x] sanitize.ts 域名修复
[x] 统一 R2 客户端（r2-client.ts）
[x] 角色命名规范化（清理4个问题角色及9589条关联数据）
[x] 删除 Actions deploy/notify，改用 wrangler 直接部署

基础设施：

[x] MCP：GitHub + Cloudflare 已配置
[x] 深度思考模式已开启（thinking=high, reasoning=stream）
[x] cloudflare-assets：workflow 按前缀分组

🔥 进行中 — 重大重构（2026-07-09 启动）

目标： SV 风格地图 + 季节/天气系统 + Agnes AI 素材生成

阶段一：素材生成

[ ] Agnes API 生成脚本（15 个地点建筑精灵）
[ ] 季节化自然素材（草地/树木/水面 ×4 季）
[ ] 天气粒子素材（雨/雪/花瓣/落叶/萤火虫）

阶段二：季节系统

[ ] SeasonSystem 状态机（365天/年，91天/季，10天过渡）
[ ] 地形 tile 交叉淡入淡出
[ ] 建筑色调渐变 + 雪顶叠加
[ ] NPC/经济系统季节联动

阶段三：天气系统

[ ] WeatherSystem 状态机（季节×天气概率矩阵）
[ ] 粒子系统（雨滴/雪花/花瓣/萤火虫/落叶）
[ ] 天气遮罩 + 闪电效果
[ ] 地面积水/积雪

阶段四：地图重构

[ ] mapConfig 数据结构（zones/buildings/paths/decorations）
[ ] 地形渲染器（季节化）
[ ] 建筑渲染器（不规则放置 + 遮挡）
[ ] 自然装饰渲染（密度分布算法）
[ ] 道路系统（贝塞尔曲线路径）
[ ] 摄像机系统（视口裁剪）

阶段五：集成优化

[ ] 统一渲染管线（13层）
[ ] 性能优化（视口裁剪/粒子池/按需渲染）
[ ] 数据迁移（删除旧 LOC_LAYOUT 硬编码）

📝 文档（2026-07-09 重写）

[x] docs/zh/system/season.md — 季节系统设计（新建）
[x] docs/zh/system/weather.md — 天气系统设计（新建）
[x] docs/zh/design/Map-Design.md — SV 风格地图设计（新建）
[x] docs/zh/art/building-sprites.md — 建筑精灵规范（新建）
[x] docs/zh/art/ai-prompt-guide.md — 新增 Agnes API 集成
[x] docs/zh/design/Asset-Pipeline.md — 管线更新为 Agnes→R2→PixiJS
[x] docs/frontend/TODO.md — 全面重写
[x] docs/QUICKSTART.md — 本文件更新

已知问题

git push 到 GitHub 经常超时，用 API 推送更稳定
PixiJS 类型声明缺失（@types/pixi.js 不存在），vue-tsc 有 TS7016 错误但不影响构建
建筑精灵图目前是通用编号，待 Agnes 生成专属素材后替换

开发注意事项

文件产出规则: 所有文件写在工作区内，用相对路径
临时文件: 放 .openclaw/tmp/，不放 /tmp
Git push 超时: 优先用 github__push_files 工具通过 API 推送
D1 操作: 需要 CLOUDFLARE_API_TOKEN（cfat_ 开头），用 wrangler 执行
安全: 不要暴露 token、密钥、私钥等敏感信息
⚠️ 同步更新文档: 每次向任何项目仓库提交代码时，必须同步更新本仓库的 docs/QUICKSTART.md（已完成/待办/已知问题），保持进度一致

启动指令

用户 clone docs 仓库后，对你说：

读 docs/QUICKSTART.md，了解项目背景和当前进度。完成后告诉我项目状态，等我确认后再开始写代码。

你应该严格按以下顺序执行，不能跳步：

第 0 步：开启深度思考模式

在做任何事之前，先修改 openclaw.json 开启深度思考：

json

{
  "agents": {
    "defaults": {
      "thinkingDefault": "high",
      "reasoningDefault": "on"
    }
  }
}

然后重启 gateway 生效。深度思考模式能显著提升对复杂项目的理解和规划能力。

第 1 步：克隆全部仓库

读完本文档后，立即向用户索要 GitHub token（如果未提供），然后克隆全部 4 个仓库：

bash

cd /home/work/.openclaw/workspace
git clone https://songdaochuanshu:<TOKEN>@github.com/songdaochuanshu/ai-world-sim.git
git clone https://songdaochuanshu:<TOKEN>@github.com/songdaochuanshu/ai-world-sim-web.git
git clone https://songdaochuanshu:<TOKEN>@github.com/songdaochuanshu/ai-world-sim-docs.git
git clone https://songdaochuanshu:<TOKEN>@github.com/songdaochuanshu/cloudflare-assets.git

不要只 clone docs 仓库。4 个仓库缺一不可。

第 2 步：配置 MCP

向用户索要 Cloudflare API Token（如果未提供），然后在 openclaw.json 的 mcp.servers 中配置 GitHub 和 Cloudflare MCP server（参见上方 MCP 配置章节）。配置完成后重启 gateway。

不要跳过 MCP 配置。没有 MCP 就无法操作 D1 数据库和 Cloudflare 资源。

第 3 步：汇报项目状态

汇总已完成 / 待办 / 已知问题，汇报给用户。

第 4 步：等用户确认

等用户明确说"开始"或"继续"后，再动手写代码。不要自行跳步。

⚠️ 关键原则

读文档 ≠ 执行完毕。读完后必须逐条对照，缺什么补什么。
需要 token 就主动问。不要等用户发现你漏了才补。
深度思考必须先开。它影响后续所有任务的质量。

QUICKSTART.md — AI 世界模拟器项目快速启动 ​

你是谁 ​

项目架构 ​

后端 (ai-world-sim) ​

前端 (ai-world-sim-web) ​

文档 (ai-world-sim-docs) ​

资产中心 (cloudflare-assets) ​

仓库间关系 ​

Cloudflare 凭据 ​

MCP 配置 ​

克隆全部仓库 ​

当前进度（截至 2026-07-09 — 重大重构） ​

✅ 已完成（基础功能） ​

🔥 进行中 — 重大重构（2026-07-09 启动） ​

阶段一：素材生成 ​

阶段二：季节系统 ​

阶段三：天气系统 ​

阶段四：地图重构 ​

阶段五：集成优化 ​

📝 文档（2026-07-09 重写） ​

已知问题 ​

开发注意事项 ​

启动指令 ​

第 0 步：开启深度思考模式 ​

第 1 步：克隆全部仓库 ​

第 2 步：配置 MCP ​

第 3 步：汇报项目状态 ​

第 4 步：等用户确认 ​

⚠️ 关键原则 ​