CaralHsi
diff --git a/‎demos/AOTAI_Hike/INTRODUCTION_EN.md‎
Lines changed: 448 additions & 0 deletions b/‎demos/AOTAI_Hike/INTRODUCTION_EN.md‎
Lines changed: 448 additions & 0 deletions
diff --git a/‎demos/AOTAI_Hike/INTRODUCTION_ZH.md‎
Lines changed: 454 additions & 0 deletions b/‎demos/AOTAI_Hike/INTRODUCTION_ZH.md‎
Lines changed: 454 additions & 0 deletions
diff --git a/‎demos/AOTAI_Hike/README.md‎
Lines changed: 97 additions & 0 deletions b/‎demos/AOTAI_Hike/README.md‎
Lines changed: 97 additions & 0 deletions
diff --git a/‎demos/AOTAI_Hike/backend/MEMORY_INTEGRATION.md‎
Lines changed: 113 additions & 0 deletions b/‎demos/AOTAI_Hike/backend/MEMORY_INTEGRATION.md‎
Lines changed: 113 additions & 0 deletions
diff --git a/‎demos/AOTAI_Hike/backend/aotai_hike/__init__.py‎
Lines changed: 1 addition & 0 deletions b/‎demos/AOTAI_Hike/backend/aotai_hike/__init__.py‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎demos/AOTAI_Hike/backend/aotai_hike/adapters/background.py‎
Lines changed: 144 additions & 0 deletions b/‎demos/AOTAI_Hike/backend/aotai_hike/adapters/background.py‎
Lines changed: 144 additions & 0 deletions
@@ -0,0 +1,97 @@
+# 鳌太线徒步模拟器（AoTai Hike）Demo
+
+> A pixel-art interactive narrative game demo based on the MemOS multi-view memory system
+
+<div align="center">
+  <img src="./banner.png" alt="AoTai Hike × MemOS - Poly-View Memory" width="100%">
+</div>
+
+## 📖 Overview
+
+**鳌太线徒步模拟器（AoTai Hike）** is a Web game demo showcasing MemOS's multi-view memory capabilities. Players can create multiple roles, lead a team across the dangerous AoTai route, and experience memory-based intelligent NPC dialogues and dynamic storytelling.
+
+### Key Highlights
+
+- 🎮 **Multi-role roleplay**: Create and switch between multiple roles, each with an independent memory space
+- 🧠 **Multi-view memory**: Fully integrated MemOS multi-view memory system
+- 💬 **Intelligent NPC dialogue**: Generate personality-consistent dialogue based on role memory
+- 🗺️ **Fixed route exploration**: Follow the real AoTai route and experience the full journey
+- 🎨 **Pixel-art UI**: Use Phaser 3 to render pixel-art maps and role animations
+
+**📚 For detailed documentation, see: [INTRODUCTION_ZH.md](./INTRODUCTION_ZH.md) | [INTRODUCTION_EN.md](./INTRODUCTION_EN.md)**
+
+## 🚀 Quick Start
+
+### Requirements
+
+- Python 3.8+
+- MemOS service (local or remote)
+
+### Installation Steps
+
+1. **Install backend dependencies**
+```bash
+cd backend
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+2. **Configure MemOS service address (optional)**
+```bash
+export MEMOS_API_BASE_URL=http://localhost:8002
+```
+
+3. **Start the service**
+```bash
+uvicorn app:app --host 0.0.0.0 --port 8010 --reload
+```
+
+4. **Access the game**
+Open your browser and visit: `http://localhost:8010/demo/ao-tai/`
+
+## 📡 Core API
+
+- `GET /api/demo/ao-tai/map` - Get map information
+- `POST /api/demo/ao-tai/session/new` - Create a new session
+- `POST /api/demo/ao-tai/roles/upsert` - Create/Update a role
+- `POST /api/demo/ao-tai/roles/quickstart` - Quick-create default roles
+- `PUT /api/demo/ao-tai/session/active_role` - Switch active role
+- `POST /api/demo/ao-tai/act` - Perform an action (core endpoint)
+
+For detailed API documentation, see [INTRODUCTION_EN.md](./INTRODUCTION_EN.md#-api-documentation)
+
+## 🏗️ Project Structure
+
+```
+demos/AOTAI_Hike/
+├── backend/              # FastAPI backend
+│   ├── aotai_hike/      # Game core code
+│   │   ├── router.py    # API routes
+│   │   ├── services/    # Game services
+│   │   ├── adapters/    # Adapters (memory/dialogue/background)
+│   │   └── world/       # Map data
+│   └── app.py           # Application entry
+├── frontend/            # Frontend (Phaser 3 + DOM UI)
+│   ├── src/            # Source code
+│   └── assets/          # Asset files
+└── README.md           # This file
+```
+
+## 🔧 Extensible Interfaces
+
+The game is designed to be "lightweight but extensible"; all intelligence-related features are isolated via adapters:
+
+- `adapters/memory.py` - **MemoryAdapter**: Interface with MemOS memory system
+- `adapters/companion.py` - **CompanionBrain**: NPC dialogue generation (based on MemOS chat_complete)
+- `adapters/background.py` - **BackgroundProvider**: Background asset provider
+
+## 📚 Related Documents
+
+- [INTRODUCTION_ZH.md](./INTRODUCTION_ZH.md) - **Complete project introduction (中文)**
+- [INTRODUCTION_EN.md](./INTRODUCTION_EN.md) - **Complete project introduction (English)**
+- [backend/MEMORY_INTEGRATION.md](./backend/MEMORY_INTEGRATION.md) - Memory system interaction guide
+- [PRD.md](./PRD.md) - Product requirements document
+
+---
+
+**Enjoy your AoTai hike!** 🏔️
@@ -0,0 +1,113 @@
+# 游戏系统与记忆系统交互说明（AoTai Hike）
+
+本文说明 AoTai Hike 中游戏系统与记忆系统的交互方式，并给出关键代码位置。
+
+## 总体流程概览
+
+一次 `act` 的主链路如下：
+
+1. 游戏处理阶段门控与动作执行（更新世界状态）。
+2. 写入世界事件记忆（world cube）。
+3. 检索世界记忆，作为 NPC 对话上下文。
+4. 若触发 NPC 对话：
+   - 每个 NPC 检索自身记忆（role cube）
+   - 调用 chat 生成回复
+   - 将对话写回角色记忆
+5. 写入 `chat_history` 供后续对话使用。
+
+## 关键交互点与代码位置
+
+### 1) 游戏事件写入（world 记忆）
+
+- 位置：`GameService.act`
+- 作用：把本轮事件结构化写入记忆系统（world cube）
+
+代码位置：
+- `demos/AOTAI_Hike/backend/aotai_hike/services/game_service.py`
+  - `GameService.act()` 内：
+    - `mem_event = self._format_memory_event(...)`
+    - `self._memory.add_event(...)`
+
+### 2) 世界记忆检索（world 记忆）
+
+- 位置：`GameService.act`
+- 作用：为 NPC 对话提供全局上下文
+
+代码位置：
+- `demos/AOTAI_Hike/backend/aotai_hike/services/game_service.py`
+  - `mem_res = self._memory.search(...)`
+
+### 3) NPC 对话（角色记忆检索 + chat + 回写）
+
+- 位置：`MemoryCompanionBrain._generate_role_reply`
+- 作用：每个 NPC 走完整记忆链路生成发言
+
+代码位置：
+- `demos/AOTAI_Hike/backend/aotai_hike/adapters/companion.py`
+  - `self._memory.search_memory(...)` 角色记忆检索
+  - `self._memory.chat_complete(...)` 调用算法 chat
+  - `self._memory.add_memory(...)` 写回角色记忆
+
+### 4) 记忆命名空间（cube_id）
+
+- 位置：`MemoryNamespace`
+- 规则：
+  - 角色记忆：`cube_{user_id}_{role_id}`
+  - 世界记忆：`cube_{user_id}_world`
+
+代码位置：
+- `demos/AOTAI_Hike/backend/aotai_hike/adapters/memory.py`
+
+### 5) 记忆适配与客户端
+
+- 位置：`MemOSMemoryClient` / `MemOSMemoryAdapter`
+- 作用：封装 MemOS `/product/add`、`/product/search`、`/product/chat/complete`
+
+代码位置：
+- `demos/AOTAI_Hike/backend/aotai_hike/adapters/memory.py`
+
+### 6) 对话历史记录
+
+- 位置：`GameService._append_chat_history`
+- 作用：将系统/发言消息转为 `chat_history`，供后续对话使用
+
+代码位置：
+- `demos/AOTAI_Hike/backend/aotai_hike/services/game_service.py`
+
+## 算法回放脚本（调试用）
+
+脚本 `algorithm_tuning.py` 以 1:1 的方式调用 `GameService.act`，并打印记忆/对话日志：
+
+- `demos/AOTAI_Hike/backend/aotai_hike/scripts/algorithm_tuning.py`
+
+常用参数：
+- `--user-id`：指定用户
+- `--base-url`：MemOS 服务地址
+- `--log-world-search`：打印 world 搜索
+- `--log-full-prompt`：打印完整 prompt
+
+## 简要链路图
+
+```
+GameService.act
+  ├─ add_event (world add)
+  ├─ search (world search)
+  └─ MemoryCompanionBrain.generate
+        ├─ search_memory (role search)
+        ├─ chat_complete (LLM)
+        └─ add_memory (role add)
+```
+
+## 多视角记忆集成
+
+本游戏完整集成了 MemOS 的多视角记忆系统，实现了每个角色拥有独立记忆空间、从角色视角提取记忆的功能。
+
+**详细文档**：
+- [多视角记忆集成 PR 文档](../PR_MULTI_VIEW_MEMORY_INTEGRATION.md) - 完整的技术实现说明
+- [PR 摘要](../PR_SUMMARY.md) - 快速概览
+
+**核心特性**：
+- ✅ 自动多视角模式检测（通过 `role_id` 和 `role_name` 字段）
+- ✅ 角色记忆隔离（每个角色独立的记忆空间）
+- ✅ 第一人称视角记忆提取
+- ✅ 基于记忆的智能 NPC 对话生成
@@ -0,0 +1 @@
+"""AoTai line pixel-hiking demo (single-player, multi-role)."""
@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import os
+import zlib
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import ClassVar
+from urllib.parse import quote
+
+from aotai_hike.schemas import BackgroundAsset
+
+
+@dataclass
+class BackgroundRequest:
+    scene_id: str
+    style: str = "pixel"
+    animate: bool = False
+
+
+class BackgroundProvider:
+    def get_background(self, req: BackgroundRequest) -> BackgroundAsset:
+        raise NotImplementedError
+
+
+class StaticBackgroundProvider(BackgroundProvider):
+    """Pick a background from the user's local pixel asset library.
+
+    Rules (demo-friendly):
+    - Prefer user-provided raster assets under `frontend/assets/` (png/jpg/webp/gif).
+    - Exclude avatars and legacy `bg_*.svg`.
+    - Deterministically map `scene_id` -> one asset, so the same scene is stable.
+
+    You can refine selection by setting env vars:
+      - AOTAI_BG_INCLUDE: substring that must appear in filename (case-insensitive)
+      - AOTAI_BG_EXCLUDE: substring that must NOT appear in filename (case-insensitive)
+    """
+
+    _IMG_EXTS: ClassVar[frozenset[str]] = frozenset(
+        {".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg"}
+    )
+
+    def __init__(
+        self,
+        *,
+        base_url: str = "/demo/ao-tai/assets",
+        assets_dir: Path | None = None,
+    ):
+        self._base_url = base_url.rstrip("/")
+
+        if assets_dir is None:
+            # .../AOTAI_Hike/backend/aotai_hike/adapters/background.py -> parents[3] is demo root
+            assets_dir = Path(__file__).resolve().parents[3] / "frontend" / "assets"
+        self._assets_dir = assets_dir
+
+        inc = os.getenv("AOTAI_BG_INCLUDE", "")
+        exc = os.getenv("AOTAI_BG_EXCLUDE", "tilemap")
+        self._include = inc.strip().lower() if inc else ""
+        self._exclude = exc.strip().lower() if exc else ""
+
+        self._candidates = self._discover_candidates()
+
+    def _discover_candidates(self) -> list[str]:
+        if not self._assets_dir.exists():
+            return []
+
+        out: list[str] = []
+        for p in sorted(self._assets_dir.rglob("*")):
+            if not p.is_file():
+                continue
+            if p.suffix.lower() not in self._IMG_EXTS:
+                continue
+
+            rel = p.relative_to(self._assets_dir).as_posix()
+            low = rel.lower()
+
+            # Skip avatars
+            if low.startswith("avatars/"):
+                continue
+
+            # Skip legacy demo backgrounds
+            if low.startswith("bg_") and low.endswith(".svg"):
+                continue
+
+            # Optional include/exclude substrings
+            if self._include and (self._include not in low):
+                continue
+            if self._exclude and (self._exclude in low):
+                continue
+
+            # Skip mock-up style sheets by default
+            if "mock up" in low or "mock_up" in low:
+                continue
+
+            out.append(rel)
+
+        # If filtering is too strict and yields nothing, fall back to all non-avatar images except legacy bg_*.svg
+        if not out:
+            for p in sorted(self._assets_dir.rglob("*")):
+                if not p.is_file():
+                    continue
+                if p.suffix.lower() not in self._IMG_EXTS:
+                    continue
+                rel = p.relative_to(self._assets_dir).as_posix()
+                low = rel.lower()
+                if low.startswith("avatars/"):
+                    continue
+                if low.startswith("bg_") and low.endswith(".svg"):
+                    continue
+                out.append(rel)
+
+        return out
+
+    def _pick(self, scene_id: str) -> str | None:
+        if not self._candidates:
+            return None
+        h = zlib.crc32(scene_id.encode("utf-8"))
+        return self._candidates[h % len(self._candidates)]
+
+    def get_background(self, req: BackgroundRequest) -> BackgroundAsset:
+        chosen = self._pick(req.scene_id)
+        if not chosen:
+            # last resort: legacy
+            return BackgroundAsset(
+                scene_id=req.scene_id,
+                asset_url=f"{self._base_url}/bg_{req.scene_id}.svg",
+                type="svg",
+                meta={"style": req.style, "animate": req.animate, "fallback": True},
+            )
+
+        ext = Path(chosen).suffix.lower().lstrip(".")
+        # URL encode each segment (handles spaces)
+        encoded = "/".join(quote(seg) for seg in chosen.split("/"))
+        return BackgroundAsset(
+            scene_id=req.scene_id,
+            asset_url=f"{self._base_url}/{encoded}",
+            type=ext if ext in {"png", "jpg", "jpeg", "webp", "gif", "svg"} else "none",
+            meta={
+                "style": req.style,
+                "animate": req.animate,
+                "picked": chosen,
+                "candidates": len(self._candidates),
+            },
+        )
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+"""AoTai line pixel-hiking demo (single-player, multi-role)."""`