调整readme

.kiro/specs/multi-client-sync-fix/requirements.md

@@ -0,0 +1,92 @@
+# 需求文档
+
+## 简介
+
+本文档规定了修复 AI Town 游戏中多客户端同步问题的需求。目前，当多个 Web 客户端同时连接时，存在严重的同步问题：新角色的外观无法正确显示，新创建的角色看不到已存在的角色，角色之间无法相互交流。
+
+## 术语表
+
+- **客户端（Client）**: 运行游戏的 Web 浏览器实例
+- **角色（Character）**: 游戏世界中由玩家控制的实体
+- **服务器（Server）**: 管理游戏状态的 WebSocket 服务器
+- **世界状态（World State）**: 游戏中所有角色及其属性的完整状态
+- **角色外观（Character Appearance）**: 视觉属性，包括身体颜色、头部颜色和精灵信息
+- **角色状态消息（Character State Message）**: 包含角色信息的网络消息，包括 ID、名称、位置、在线状态和外观数据
+- **世界状态消息（World State Message）**: 包含所有角色及其状态的完整列表的网络消息
+- **广播（Broadcast）**: 向除发送者外的所有已连接客户端发送消息
+
+## 需求
+
+### 需求 1
+
+**用户故事：** 作为玩家，我希望在其他角色加入游戏时看到他们的正确外观，以便我可以在视觉上区分不同的玩家。
+
+#### 验收标准
+
+1. WHEN 创建新角色时 THEN 服务器 SHALL 向所有已连接的客户端广播包含外观数据的完整角色状态
+2. WHEN 客户端接收到角色状态消息时 THEN 客户端 SHALL 提取外观数据并应用到角色精灵上
+3. WHEN 角色在世界中生成时 THEN 客户端 SHALL 使用外观数据中的正确身体颜色和头部颜色渲染角色
+4. WHEN 角色状态消息中缺少外观数据时 THEN 客户端 SHALL 使用默认外观值
+5. WHILE 角色在世界中可见时 THEN 客户端 SHALL 始终保持角色的外观属性一致
+
+### 需求 2
+
+**用户故事：** 作为加入游戏的新玩家，我希望看到世界中所有现有的角色，以便我可以与已经在线的其他玩家互动。
+
+#### 验收标准
+
+1. WHEN 客户端成功认证时 THEN 服务器 SHALL 发送包含所有在线角色的世界状态消息
+2. WHEN 客户端接收到世界状态消息时 THEN 客户端 SHALL 生成或更新消息中列出的所有角色
+3. WHEN 从世界状态生成角色时 THEN 客户端 SHALL 包含完整的角色数据（包括外观）
+4. WHEN 角色已在本地存在时 THEN 客户端 SHALL 更新现有角色而不是创建重复角色
+5. WHILE 处理世界状态时 THEN 客户端 SHALL 从远程角色生成中排除玩家自己的角色
+
+### 需求 3
+
+**用户故事：** 作为玩家，我希望向其他玩家发送消息并接收他们的消息，以便我可以在游戏世界中进行交流和互动。
+
+#### 验收标准
+
+1. WHEN 玩家发送对话消息时 THEN 服务器 SHALL 向所有已连接的客户端广播该消息
+2. WHEN 客户端接收到对话消息时 THEN 客户端 SHALL 在适当的 UI 元素中显示该消息
+3. WHEN 显示对话消息时 THEN 客户端 SHALL 显示发送者的角色名称
+4. WHEN 消息发送给特定角色时 THEN 服务器 SHALL 仅将消息传递给该角色的客户端
+5. WHILE 对话系统处于活动状态时 THEN 客户端 SHALL 为每个对话维护消息历史记录
+
+### 需求 4
+
+**用户故事：** 作为开发者，我希望服务器在所有状态消息中包含完整的角色数据，以便客户端拥有正确渲染角色所需的所有信息。
+
+#### 验收标准
+
+1. WHEN 创建角色状态消息时 THEN 服务器 SHALL 包含 id、name、position、isOnline 和 appearance 字段
+2. WHEN 广播角色状态时 THEN 服务器 SHALL 序列化完整的角色对象（包括嵌套的外观数据）
+3. WHEN 角色外观发生变化时 THEN 服务器 SHALL 向所有客户端广播更新的外观
+4. WHEN 从磁盘加载角色时 THEN 服务器 SHALL 保留所有外观数据
+5. WHILE 维护角色状态时 THEN 服务器 SHALL 确保外观数据在保存和加载操作中的完整性
+
+### 需求 5
+
+**用户故事：** 作为玩家，我希望角色同步在多个客户端之间可靠工作，以便所有玩家的游戏状态保持一致。
+
+#### 验收标准
+
+1. WHEN 角色移动时 THEN 服务器 SHALL 向所有其他客户端广播位置更新
+2. WHEN 角色上线时 THEN 服务器 SHALL 向所有客户端广播在线状态
+3. WHEN 角色下线时 THEN 服务器 SHALL 向所有客户端广播离线状态
+4. WHEN 接收到角色状态更新时 THEN 客户端 SHALL 仅将更新应用于远程角色而不是玩家自己的角色
+5. WHILE 多个客户端连接时 THEN 服务器 SHALL 在所有客户端之间维护一致的状态
+
+### 需求 6
+
+**用户故事：** 作为开发者，我希望所有新的同步功能与现有系统逻辑完美融合，以便系统保持稳定且不引入新的错误。
+
+#### 验收标准
+
+1. WHEN 实现新的同步逻辑时 THEN 系统 SHALL 保持与现有网络管理器的兼容性
+2. WHEN 修改角色状态广播时 THEN 系统 SHALL 保持与现有 MessageProtocol 的消息格式一致性
+3. WHEN 更新世界管理器时 THEN 系统 SHALL 保持与现有角色生成和移除逻辑的兼容性
+4. WHEN 处理角色外观数据时 THEN 系统 SHALL 保持与现有 CharacterData 和 CharacterController 的数据结构一致性
+5. WHEN 添加新的消息处理逻辑时 THEN 系统 SHALL 不破坏现有的安全验证、速率限制和错误处理机制
+6. WHEN 修改客户端同步逻辑时 THEN 系统 SHALL 保持与现有游戏状态管理器的状态转换逻辑一致性
+7. WHILE 实现多客户端同步时 THEN 系统 SHALL 确保不与现有的单客户端功能（如玩家移动、对话系统）产生冲突