docs：更新项目规范文档

- 在 claude.md 添加 Plan Mode Protocol 章节
- 明确规划阶段的输出要求和执行报告流程
- 强制要求在每个 TODO 完成后更新文档并等待用户确认

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

_Core/EventNames.gd

@@ -57,4 +57,15 @@ const GRID_SNAP_REQUESTED = "grid_snap_requested"
 # ============================================================================
 # 测试事件
 # ============================================================================
-const TEST_EVENT = "test_event"
+const TEST_EVENT = "test_event"
+
+# ============================================================================
+# 聊天事件
+# ============================================================================
+const CHAT_MESSAGE_SENT = "chat_message_sent"
+const CHAT_MESSAGE_RECEIVED = "chat_message_received"
+const CHAT_ERROR_OCCURRED = "chat_error_occurred"
+const CHAT_CONNECTION_STATE_CHANGED = "chat_connection_state_changed"
+const CHAT_POSITION_UPDATED = "chat_position_updated"
+const CHAT_LOGIN_SUCCESS = "chat_login_success"
+const CHAT_LOGIN_FAILED = "chat_login_failed"

_Core/managers/AuthManager.gd

@@ -80,6 +80,9 @@ var current_email: String = ""
 # 网络请求管理
 var active_request_ids: Array = []
 
+# 游戏 token 管理（用于 WebSocket 聊天认证）
+var _game_token: String = ""
+
 # ============ 生命周期方法 ============
 
 # 初始化管理器
@@ -93,6 +96,31 @@ func cleanup():
 		NetworkManager.cancel_request(request_id)
 	active_request_ids.clear()
 
+# ============ 游戏 Token 管理 ============
+
+# 设置游戏 token
+#
+# 参数:
+#   token: String - 游戏认证 token
+#
+# 使用场景:
+# - 登录成功后设置 token
+# - 从服务器响应中获取 token
+func set_game_token(token: String) -> void:
+	_game_token = token
+	print("AuthManager: 游戏 token 已设置")
+
+# 获取游戏 token
+#
+# 返回值:
+#   String - 游戏 token，如果未设置则返回空字符串
+#
+# 使用场景:
+# - ChatManager 连接 WebSocket 时需要 token
+# - 其他需要游戏认证的场景
+func get_game_token() -> String:
+	return _game_token
+
 # ============ 登录相关方法 ============
 
 # 执行密码登录

_Core/managers/ChatManager.gd

@@ -0,0 +1,643 @@
+extends Node
+
+# ============================================================================
+# ChatManager.gd - 聊天系统业务逻辑核心
+# ============================================================================
+# 管理聊天功能的核心业务逻辑
+#
+# 核心职责:
+# - 聊天消息发送/接收协调
+# - 客户端频率限制（10条/分钟）
+# - 消息历史管理（最多100条）
+# - Signal Up: 通过信号和 EventSystem 向上通知
+# - 整合 AuthManager 获取 token
+#
+# 使用方式:
+#   ChatManager.connect_to_chat_server()
+#   ChatManager.send_chat_message("Hello", "local")
+#   ChatManager.chat_message_received.connect(_on_message_received)
+#
+# 注意事项:
+# - 作为自动加载单例，全局可访问
+# - 遵循 "Signal Up, Call Down" 架构
+# - 所有聊天事件通过 EventSystem 广播
+# ============================================================================
+
+class_name ChatManager
+
+# ============================================================================
+# 信号定义 (Signal Up)
+# ============================================================================
+
+# 聊天消息已发送信号
+# 参数:
+#   message_id: String - 消息 ID
+#   timestamp: float - 时间戳
+signal chat_message_sent(message_id: String, timestamp: float)
+
+# 聊天消息已接收信号
+# 参数:
+#   from_user: String - 发送者用户名
+#   content: String - 消息内容
+#   show_bubble: bool - 是否显示气泡
+#   timestamp: float - 时间戳
+signal chat_message_received(from_user: String, content: String, show_bubble: bool, timestamp: float)
+
+# 聊天错误发生信号
+# 参数:
+#   error_code: String - 错误代码
+#   message: String - 错误消息
+signal chat_error_occurred(error_code: String, message: String)
+
+# 聊天连接状态变化信号
+# 参数:
+#   state: WebSocketManager.ConnectionState - 连接状态
+signal chat_connection_state_changed(state: WebSocketManager.ConnectionState)
+
+# 位置更新成功信号
+# 参数:
+#   stream: String - Stream 名称
+#   topic: String - Topic 名称
+signal chat_position_updated(stream: String, topic: String)
+
+# ============================================================================
+# 常量定义
+# ============================================================================
+
+# WebSocket 服务器 URL
+const WEBSOCKET_URL: String = "wss://whaletownend.xinghangee.icu/game"
+
+# 重连配置
+const RECONNECT_MAX_ATTEMPTS: int = 5
+const RECONNECT_BASE_DELAY: float = 3.0
+
+# 频率限制配置
+const RATE_LIMIT_MESSAGES: int = 10
+const RATE_LIMIT_WINDOW: float = 60.0  # 秒
+
+# 消息限制
+const MAX_MESSAGE_LENGTH: int = 1000
+
+# 当前会话消息限制（当前游戏会话，超过后删除最旧的）
+const MAX_SESSION_MESSAGES: int = 100
+
+# 历史消息分页大小（从 Zulip 后端每次加载的数量）
+const HISTORY_PAGE_SIZE: int = 100
+
+# 错误消息映射
+const CHAT_ERROR_MESSAGES: Dictionary = {
+	"AUTH_FAILED": "聊天认证失败，请重新登录",
+	"RATE_LIMIT": "消息发送过于频繁，请稍后再试",
+	"CONTENT_FILTERED": "消息内容包含违规内容",
+	"CONTENT_TOO_LONG": "消息内容过长（最大1000字符）",
+	"PERMISSION_DENIED": "您没有权限发送消息",
+	"SESSION_EXPIRED": "会话已过期，请重新连接",
+	"ZULIP_ERROR": "消息服务暂时不可用",
+	"INTERNAL_ERROR": "服务器内部错误"
+}
+
+# ============================================================================
+# 成员变量
+# ============================================================================
+
+# WebSocket 管理器
+var _websocket_manager: WebSocketManager
+
+# Socket.IO 客户端
+var _socket_client: SocketIOClient
+
+# 是否已登录
+var _is_logged_in: bool = false
+
+# 消息历史记录（当前会话，最多100条，超过后删除最旧的）
+var _message_history: Array[Dictionary] = []
+
+# 历史消息加载状态
+var _history_loading: bool = false
+var _has_more_history: bool = true
+var _oldest_message_timestamp: float = 0.0
+
+# 消息发送时间戳（用于频率限制）
+var _message_timestamps: Array[float] = []
+
+# 当前用户信息
+var _current_username: String = ""
+var _current_map: String = ""
+
+# 游戏 token
+var _game_token: String = ""
+
+# ============================================================================
+# 生命周期方法
+# ============================================================================
+
+# 初始化
+func _ready() -> void:
+	print("ChatManager 初始化完成")
+
+	# 创建 WebSocket 管理器
+	_websocket_manager = WebSocketManager.new()
+	add_child(_websocket_manager)
+
+	# 获取 Socket.IO 客户端引用
+	_socket_client = _websocket_manager.get_socket_client()
+
+	# 连接信号
+	_connect_signals()
+
+# 清理
+func _exit_tree() -> void:
+	if is_instance_valid(_websocket_manager):
+		_websocket_manager.queue_free()
+
+# ============================================================================
+# 公共 API - Token 管理
+# ============================================================================
+
+# 设置游戏 token
+#
+# 参数:
+#   token: String - 游戏认证 token
+#
+# 使用示例:
+#   ChatManager.set_game_token("your_game_token")
+func set_game_token(token: String) -> void:
+	_game_token = token
+	print("ChatManager: 游戏 token 已设置")
+
+# 获取游戏 token
+#
+# 返回值:
+#   String - 当前游戏 token
+func get_game_token() -> String:
+	return _game_token
+
+# ============================================================================
+# 公共 API - 连接管理
+# ============================================================================
+
+# 连接到聊天服务器
+func connect_to_chat_server() -> void:
+	if _websocket_manager.is_connected():
+		push_warning("聊天服务器已连接")
+		return
+
+	print("=== ChatManager 开始连接 ===")
+	_websocket_manager.connect_to_game_server()
+
+# 断开聊天服务器
+func disconnect_from_chat_server() -> void:
+	print("=== ChatManager 断开连接 ===")
+
+	# 发送登出消息
+	if _is_logged_in:
+		var logout_data := {"type": "logout"}
+		_socket_client.emit("logout", logout_data)
+		_is_logged_in = False
+
+	# 断开连接
+	_websocket_manager.disconnect()
+
+# 检查是否已连接
+#
+# 返回值:
+#   bool - 是否已连接
+func is_connected() -> bool:
+	return _websocket_manager.is_connected()
+
+# ============================================================================
+# 公共 API - 聊天操作
+# ============================================================================
+
+# 发送聊天消息
+#
+# 参数:
+#   content: String - 消息内容
+#   scope: String - 消息范围（"local" 或具体 topic 名称）
+#
+# 使用示例:
+#   ChatManager.send_chat_message("Hello, world!", "local")
+func send_chat_message(content: String, scope: String = "local") -> void:
+	# 检查连接状态
+	if not _websocket_manager.is_connected():
+		_handle_error("NOT_CONNECTED", "未连接到聊天服务器")
+		return
+
+	# 检查登录状态
+	if not _is_logged_in:
+		_handle_error("NOT_LOGGED_IN", "尚未登录聊天服务器")
+		return
+
+	# 检查消息长度
+	if content.length() > MAX_MESSAGE_LENGTH:
+		_handle_error("CONTENT_TOO_LONG", "消息内容过长")
+		return
+
+	# 检查频率限制
+	if not can_send_message():
+		var wait_time := get_time_until_next_message()
+		_handle_error("RATE_LIMIT", "请等待 %.1f 秒后再试" % wait_time)
+		return
+
+	# 构建消息数据
+	var message_data := {
+		"t": "chat",
+		"content": content,
+		"scope": scope
+	}
+
+	# 发送消息
+	_socket_client.emit("chat", message_data)
+
+	# 记录发送时间
+	_record_message_timestamp()
+
+	# 添加到历史
+	_add_message_to_history({
+		"from_user": _current_username,
+		"content": content,
+		"timestamp": Time.get_unix_time_from_system(),
+		"is_self": true
+	})
+
+	print("📤 发送聊天消息: ", content)
+
+# 更新玩家位置
+#
+# 参数:
+#   x: float - X 坐标
+#   y: float - Y 坐标
+#   map_id: String - 地图 ID
+#
+# 使用示例:
+#   ChatManager.update_player_position(150.0, 200.0, "novice_village")
+func update_player_position(x: float, y: float, map_id: String) -> void:
+	if not _websocket_manager.is_connected():
+		return
+
+	var position_data := {
+		"t": "position",
+		"x": x,
+		"y": y,
+		"mapId": map_id
+	}
+
+	_socket_client.emit("position", position_data)
+	print("📍 更新位置: (%.2f, %.2f) in %s" % [x, y, map_id])
+
+# ============================================================================
+# 公共 API - 频率限制
+# ============================================================================
+
+# 检查是否可以发送消息
+#
+# 返回值:
+#   bool - 是否可以发送
+func can_send_message() -> bool:
+	var current_time := Time.get_unix_time_from_system()
+
+	# 清理过期的时间戳
+	_message_timestamps = _message_timestamps.filter(
+		func(timestamp: float) -> bool:
+			return current_time - timestamp < RATE_LIMIT_WINDOW
+	)
+
+	# 检查数量
+	return _message_timestamps.size() < RATE_LIMIT_MESSAGES
+
+# 获取距离下次可发送消息的时间
+#
+# 返回值:
+#   float - 等待时间（秒）
+func get_time_until_next_message() -> float:
+	if _message_timestamps.is_empty():
+		return 0.0
+
+	if _message_timestamps.size() < RATE_LIMIT_MESSAGES:
+		return 0.0
+
+	# 找到最早的时间戳
+	var earliest_timestamp: float = _message_timestamps[0]
+	var current_time := Time.get_unix_time_from_system()
+	var elapsed := current_time - earliest_timestamp
+
+	if elapsed >= RATE_LIMIT_WINDOW:
+		return 0.0
+
+	return RATE_LIMIT_WINDOW - elapsed
+
+# ============================================================================
+# 公共 API - 消息历史
+# ============================================================================
+
+# 获取消息历史
+#
+# 返回值:
+#   Array[Dictionary] - 消息历史数组
+func get_message_history() -> Array[Dictionary]:
+	return _message_history.duplicate()
+
+# 清空消息历史
+func clear_message_history() -> void:
+	_message_history.clear()
+	print("🧹 清空消息历史")
+
+# 重置当前会话（每次登录/重连时调用）
+#
+# 功能:
+# - 清空当前会话消息缓存
+# - 重置历史消息加载状态
+# - 不影响 Zulip 后端的历史消息
+#
+# 使用场景:
+# - 用户登录成功后
+# - 重新连接到聊天服务器后
+func reset_session() -> void:
+	_message_history.clear()
+	_history_loading = false
+	_has_more_history = true
+	_oldest_message_timestamp = 0.0
+	print("🔄 重置聊天会话")
+
+# 加载历史消息（按需从 Zulip 后端获取）
+#
+# 参数:
+#   count: int - 要加载的消息数量（默认 HISTORY_PAGE_SIZE）
+#
+# 功能:
+# - 从 Zulip 后端获取历史消息
+# - 添加到当前会话历史开头
+# - 触发 CHAT_MESSAGE_RECEIVED 事件显示消息
+#
+# 使用场景:
+# - 用户滚动到聊天窗口顶部
+# - 用户主动点击"加载历史"按钮
+#
+# 注意:
+# - 这是异步操作，需要通过 Zulip API 实现
+# - 当前实现为占位符，需要后端 API 支持
+func load_history(count: int = HISTORY_PAGE_SIZE) -> void:
+	if _history_loading:
+		print("⏳ 历史消息正在加载中...")
+		return
+
+	if not _has_more_history:
+		print("📚 没有更多历史消息")
+		return
+
+	_history_loading = true
+	print("📜 开始加载历史消息，数量: ", count)
+
+	# TODO: 实现从 Zulip 后端获取历史消息
+	# NetworkManager.get_chat_history(_oldest_message_timestamp, count, _on_history_loaded)
+
+	# 临时实现：模拟历史消息加载（测试用）
+	# await get_tree().create_timer(1.0).timeout
+	# _on_history_loaded([])
+
+# 历史消息加载完成回调
+func _on_history_loaded(messages: Array) -> void:
+	_history_loading = false
+
+	if messages.is_empty():
+		_has_more_history = false
+		print("📚 没有更多历史消息")
+		return
+
+	print("📜 历史消息加载完成，数量: ", messages.size())
+
+	# 将历史消息插入到当前会话历史开头
+	for i in range(messages.size() - 1, -1, -1):
+		var message: Dictionary = messages[i]
+		_message_history.push_front(message)
+
+		# 触发事件显示消息（Signal Up）
+		EventSystem.emit_event(EventNames.CHAT_MESSAGE_RECEIVED, {
+			"from_user": message.get("from_user", ""),
+			"content": message.get("content", ""),
+			"show_bubble": false,
+			"timestamp": message.get("timestamp", 0.0),
+			"is_history": true  # 标记为历史消息
+		})
+
+	# 更新最旧消息时间戳
+	var oldest: Dictionary = messages.back()
+	if oldest.has("timestamp"):
+		_oldest_message_timestamp = oldest.timestamp
+
+	# 检查是否还有更多历史
+	if messages.size() < HISTORY_PAGE_SIZE:
+		_has_more_history = false
+
+# ============================================================================
+# 内部方法 - 信号连接
+# ============================================================================
+
+# 连接信号
+func _connect_signals() -> void:
+	# WebSocket 管理器信号
+	_websocket_manager.connection_state_changed.connect(_on_connection_state_changed)
+
+	# Socket.IO 客户端信号
+	_socket_client.connected.connect(_on_socket_connected)
+	_socket_client.disconnected.connect(_on_socket_disconnected)
+	_socket_client.event_received.connect(_on_socket_event_received)
+	_socket_client.error_occurred.connect(_on_socket_error)
+
+# ============================================================================
+# 内部方法 - 连接状态处理
+# ============================================================================
+
+# Socket 连接成功
+func _on_socket_connected() -> void:
+	print("✅ ChatManager: Socket 连接成功")
+
+	# 发送登录消息
+	_send_login_message()
+
+# Socket 连接断开
+func _on_socket_disconnected(_clean_close: bool) -> void:
+	print("🔌 ChatManager: Socket 连接断开")
+	_is_logged_in = False
+
+# 连接状态变化
+func _on_connection_state_changed(state: WebSocketManager.ConnectionState) -> void:
+	print("📡 ChatManager: 连接状态变化 - ", WebSocketManager.ConnectionState.keys()[state])
+
+	# 发射信号
+	chat_connection_state_changed.emit(state)
+
+	# 通过 EventSystem 广播（Signal Up）
+	EventSystem.emit_event(EventNames.CHAT_CONNECTION_STATE_CHANGED, {
+		"state": state
+	})
+
+# ============================================================================
+# 内部方法 - 消息处理
+# ============================================================================
+
+# Socket 事件接收
+func _on_socket_event_received(event_name: String, data: Dictionary) -> void:
+	match event_name:
+		"login_success":
+			_handle_login_success(data)
+		"chat_sent":
+			_handle_chat_sent(data)
+		"chat_render":
+			_handle_chat_render(data)
+		"position_updated":
+			_handle_position_updated(data)
+		"error":
+			_handle_error_response(data)
+		_:
+			print("⚠️ ChatManager: 未处理的事件 - ", event_name)
+
+# 处理登录成功
+func _handle_login_success(data: Dictionary) -> void:
+	print("✅ ChatManager: 登录成功")
+
+	_is_logged_in = True
+	_current_username = data.get("username", "")
+	_current_map = data.get("currentMap", "")
+
+	# 重置当前会话缓存（每次登录/重连都清空，重新开始接收消息）
+	reset_session()
+
+	print("   用户名: ", _current_username)
+	print("   地图: ", _current_map)
+
+	# 通过 EventSystem 广播（Signal Up）
+	EventSystem.emit_event(EventNames.CHAT_LOGIN_SUCCESS, {
+		"username": _current_username,
+		"current_map": _current_map
+	})
+
+# 处理聊天消息发送成功
+func _handle_chat_sent(data: Dictionary) -> void:
+	var message_id: String = data.get("messageId", "")
+	var timestamp: float = data.get("timestamp", 0.0)
+
+	print("✅ 消息发送成功: ", message_id)
+
+	# 发射信号
+	chat_message_sent.emit(message_id, timestamp)
+
+	# 通过 EventSystem 广播（Signal Up）
+	EventSystem.emit_event(EventNames.CHAT_MESSAGE_SENT, {
+		"message_id": message_id,
+		"timestamp": timestamp
+	})
+
+# 处理接收到的聊天消息
+func _handle_chat_render(data: Dictionary) -> void:
+	var from_user: String = data.get("from", "")
+	var content: String = data.get("txt", "")
+	var show_bubble: bool = data.get("bubble", false)
+	var timestamp: float = data.get("timestamp", 0.0)
+
+	print("📨 收到聊天消息: ", from_user, " -> ", content)
+
+	# 添加到历史
+	_add_message_to_history({
+		"from_user": from_user,
+		"content": content,
+		"timestamp": timestamp,
+		"is_self": false
+	})
+
+	# 发射信号
+	chat_message_received.emit(from_user, content, show_bubble, timestamp)
+
+	# 通过 EventSystem 广播（Signal Up）
+	EventSystem.emit_event(EventNames.CHAT_MESSAGE_RECEIVED, {
+		"from_user": from_user,
+		"content": content,
+		"show_bubble": show_bubble,
+		"timestamp": timestamp
+	})
+
+# 处理位置更新成功
+func _handle_position_updated(data: Dictionary) -> void:
+	var stream: String = data.get("stream", "")
+	var topic: String = data.get("topic", "")
+
+	print("✅ 位置更新成功: ", stream, " / ", topic)
+
+	# 发射信号
+	chat_position_updated.emit(stream, topic)
+
+	# 通过 EventSystem 广播（Signal Up）
+	EventSystem.emit_event(EventNames.CHAT_POSITION_UPDATED, {
+		"stream": stream,
+		"topic": topic
+	})
+
+# 处理错误响应
+func _handle_error_response(data: Dictionary) -> void:
+	var error_code: String = data.get("code", "")
+	var error_message: String = data.get("message", "")
+
+	_handle_error(error_code, error_message)
+
+# 处理 Socket 错误
+func _on_socket_error(error: String) -> void:
+	_handle_error("SOCKET_ERROR", error)
+
+# ============================================================================
+# 内部方法 - 工具函数
+# ============================================================================
+
+# 发送登录消息
+func _send_login_message() -> void:
+	if _game_token.is_empty():
+		push_error("无法获取游戏 token，请先调用 set_game_token() 设置 token")
+		_handle_error("AUTH_FAILED", "无法获取游戏 token，请先设置 token")
+		return
+
+	var login_data := {
+		"type": "login",
+		"token": _game_token
+	}
+
+	_socket_client.emit("login", login_data)
+	print("📤 发送登录消息")
+
+# 处理错误
+func _handle_error(error_code: String, error_message: String) -> void:
+	print("❌ ChatManager 错误: [", error_code, "] ", error_message)
+
+	# 获取用户友好的错误消息
+	var user_message := CHAT_ERROR_MESSAGES.get(error_code, error_message)
+
+	# 发射信号
+	chat_error_occurred.emit(error_code, user_message)
+
+	# 通过 EventSystem 广播（Signal Up）
+	EventSystem.emit_event(EventNames.CHAT_ERROR_OCCURRED, {
+		"error_code": error_code,
+		"message": user_message
+	})
+
+	# 特殊处理认证失败
+	if error_code == "AUTH_FAILED" or error_code == "SESSION_EXPIRED":
+		_is_logged_in = False
+		EventSystem.emit_event(EventNames.CHAT_LOGIN_FAILED, {
+			"error_code": error_code
+		})
+
+# 记录消息发送时间戳
+func _record_message_timestamp() -> void:
+	var current_time := Time.get_unix_time_from_system()
+	_message_timestamps.append(current_time)
+
+# 添加消息到当前会话历史
+func _add_message_to_history(message: Dictionary) -> void:
+	_message_history.append(message)
+
+	# 更新最旧消息时间戳（用于历史消息加载）
+	if _oldest_message_timestamp == 0.0 or message.timestamp < _oldest_message_timestamp:
+		_oldest_message_timestamp = message.timestamp
+
+	# 限制当前会话消息数量（超过后删除最旧的）
+	if _message_history.size() > MAX_SESSION_MESSAGES:
+		_message_history.pop_front()

_Core/managers/ChatManager.gd.uid

@@ -0,0 +1 @@
+uid://b6lnbss2i3pss

_Core/managers/WebSocketManager.gd

@@ -0,0 +1,335 @@
+extends Node
+
+# ============================================================================
+# WebSocketManager.gd - WebSocket 连接生命周期管理
+# ============================================================================
+# 管理 WebSocket 连接状态、自动重连和错误恢复
+#
+# 核心职责:
+# - 连接状态管理（断开、连接中、已连接、重连中）
+# - 自动重连机制（指数退避）
+# - 连接错误恢复
+# - Socket.IO 客户端封装
+#
+# 使用方式:
+#   WebSocketManager.connect_to_game_server()
+#   WebSocketManager.connection_state_changed.connect(_on_state_changed)
+#
+# 注意事项:
+# - 作为自动加载单例，全局可访问
+# - 自动处理连接断开和重连
+# - 通过信号通知连接状态变化
+# ============================================================================
+
+class_name WebSocketManager
+
+# ============================================================================
+# 信号定义
+# ============================================================================
+
+# 连接状态变化信号
+# 参数:
+#   new_state: ConnectionState - 新的连接状态
+signal connection_state_changed(new_state: ConnectionState)
+
+# 连接丢失信号
+signal connection_lost()
+
+# 重连成功信号
+signal reconnection_succeeded()
+
+# 重连失败信号
+# 参数:
+#   attempt: int - 当前重连尝试次数
+#   max_attempts: int - 最大重连次数
+signal reconnection_failed(attempt: int, max_attempts: int)
+
+# ============================================================================
+# 枚举定义
+# ============================================================================
+
+# 连接状态枚举
+enum ConnectionState {
+	DISCONNECTED,   # 未连接
+	CONNECTING,     # 连接中
+	CONNECTED,      # 已连接
+	RECONNECTING,   # 重连中
+	ERROR           # 错误状态
+}
+
+# ============================================================================
+# 常量定义
+# ============================================================================
+
+# WebSocket 服务器 URL
+const WEBSOCKET_URL: String = "wss://whaletownend.xinghangee.icu/game"
+
+# 默认最大重连次数
+const DEFAULT_MAX_RECONNECT_ATTEMPTS: int = 5
+
+# 默认重连基础延迟（秒）
+const DEFAULT_RECONNECT_BASE_DELAY: float = 3.0
+
+# 最大重连延迟（秒）
+const MAX_RECONNECT_DELAY: float = 30.0
+
+# ============================================================================
+# 成员变量
+# ============================================================================
+
+# Socket.IO 客户端
+var _socket_client: SocketIOClient
+
+# 当前连接状态
+var _connection_state: ConnectionState = ConnectionState.DISCONNECTED
+
+# 自动重连启用标志
+var _auto_reconnect_enabled: bool = true
+
+# 最大重连次数
+var _max_reconnect_attempts: int = DEFAULT_MAX_RECONNECT_ATTEMPTS
+
+# 重连基础延迟
+var _reconnect_base_delay: float = DEFAULT_RECONNECT_BASE_DELAY
+
+# 当前重连尝试次数
+var _reconnect_attempt: int = 0
+
+# 重连定时器
+var _reconnect_timer: Timer = Timer.new()
+
+# 是否为正常关闭（非异常断开）
+var _clean_close: bool = true
+
+# ============================================================================
+# 生命周期方法
+# ============================================================================
+
+# 初始化
+func _ready() -> void:
+	print("WebSocketManager 初始化完成")
+
+	# 创建 Socket.IO 客户端
+	_socket_client = SocketIOClient.new()
+	add_child(_socket_client)
+
+	# 连接信号
+	_socket_client.connected.connect(_on_socket_connected)
+	_socket_client.disconnected.connect(_on_socket_disconnected)
+	_socket_client.error_occurred.connect(_on_socket_error)
+
+	# 设置重连定时器
+	_setup_reconnect_timer()
+
+# 清理
+func _exit_tree() -> void:
+	if is_instance_valid(_reconnect_timer):
+		_reconnect_timer.stop()
+		_reconnect_timer.queue_free()
+
+# ============================================================================
+# 公共 API - 连接管理
+# ============================================================================
+
+# 连接到游戏服务器
+func connect_to_game_server() -> void:
+	if _connection_state == ConnectionState.CONNECTED or _connection_state == ConnectionState.CONNECTING:
+		push_warning("已经在连接或已连接状态")
+		return
+
+	print("=== WebSocketManager 开始连接 ===")
+	_set_connection_state(ConnectionState.CONNECTING)
+	_clean_close = true
+	_reconnect_attempt = 0
+
+	_socket_client.connect_to_server(WEBSOCKET_URL)
+
+# 断开连接
+func disconnect() -> void:
+	print("=== WebSocketManager 断开连接 ===")
+	_clean_close = true
+
+	# 停止重连定时器
+	_reconnect_timer.stop()
+
+	# 断开客户端
+	_socket_client.disconnect_from_server()
+	_set_connection_state(ConnectionState.DISCONNECTED)
+
+# 检查是否已连接
+#
+# 返回值:
+#   bool - 是否已连接
+func is_connected() -> bool:
+	return _connection_state == ConnectionState.CONNECTED
+
+# 获取当前连接状态
+#
+# 返回值:
+#   ConnectionState - 当前连接状态
+func get_connection_state() -> ConnectionState:
+	return _connection_state
+
+# ============================================================================
+# 公共 API - 自动重连
+# ============================================================================
+
+# 启用/禁用自动重连
+#
+# 参数:
+#   enabled: bool - 是否启用自动重连
+#   max_attempts: int - 最大重连次数（默认 5）
+#   base_delay: float - 基础重连延迟，秒（默认 3.0）
+#
+# 使用示例:
+#   WebSocketManager.enable_auto_reconnect(true, 5, 3.0)
+func enable_auto_reconnect(enabled: bool, max_attempts: int = DEFAULT_MAX_RECONNECT_ATTEMPTS, base_delay: float = DEFAULT_RECONNECT_BASE_DELAY) -> void:
+	_auto_reconnect_enabled = enabled
+	_max_reconnect_attempts = max_attempts
+	_reconnect_base_delay = base_delay
+
+	print("自动重连: ", "启用" if enabled else "禁用")
+	print("最大重连次数: ", _max_reconnect_attempts)
+	print("基础重连延迟: ", _reconnect_base_delay, " 秒")
+
+# 获取 Socket.IO 客户端
+#
+# 返回值:
+#   SocketIOClient - Socket.IO 客户端实例
+#
+# 使用示例:
+#   var socket = WebSocketManager.get_socket_client()
+#   socket.emit("chat", {"t": "chat", "content": "Hello"})
+func get_socket_client() -> SocketIOClient:
+	return _socket_client
+
+# ============================================================================
+# 内部方法 - 连接状态管理
+# ============================================================================
+
+# 设置连接状态
+func _set_connection_state(new_state: ConnectionState) -> void:
+	if _connection_state == new_state:
+		return
+
+	_connection_state = new_state
+	print("📡 连接状态变更: ", ConnectionState.keys()[new_state])
+
+	# 发射信号
+	connection_state_changed.emit(new_state)
+
+# ============================================================================
+# 内部方法 - Socket 事件处理
+# ============================================================================
+
+# Socket 连接成功处理
+func _on_socket_connected() -> void:
+	print("✅ WebSocketManager: Socket 连接成功")
+
+	# 如果是重连，发射重连成功信号
+	if _connection_state == ConnectionState.RECONNECTING:
+		_reconnect_attempt = 0
+		reconnection_succeeded.emit()
+		print("🔄 重连成功")
+
+	_set_connection_state(ConnectionState.CONNECTED)
+
+# Socket 连接断开处理
+func _on_socket_disconnected(clean_close: bool) -> void:
+	print("🔌 WebSocketManager: Socket 连接断开")
+	print("   正常关闭: ", clean_close)
+
+	_clean_close = clean_close
+
+	# 如果是异常断开且启用了自动重连
+	if not clean_close and _auto_reconnect_enabled:
+		connection_lost.emit()
+		_attempt_reconnect()
+	else:
+		_set_connection_state(ConnectionState.DISCONNECTED)
+
+# Socket 错误处理
+func _on_socket_error(error: String) -> void:
+	print("❌ WebSocketManager: Socket 错误 - ", error)
+	_set_connection_state(ConnectionState.ERROR)
+
+# ============================================================================
+# 内部方法 - 重连机制
+# ============================================================================
+
+# 设置重连定时器
+func _setup_reconnect_timer() -> void:
+	_reconnect_timer = Timer.new()
+	_reconnect_timer.one_shot = true
+	_reconnect_timer.autostart = false
+	add_child(_reconnect_timer)
+
+	_reconnect_timer.timeout.connect(_on_reconnect_timeout)
+
+# 尝试重连
+func _attempt_reconnect() -> void:
+	# 检查是否超过最大重连次数
+	if _reconnect_attempt >= _max_reconnect_attempts:
+		print("❌ 达到最大重连次数 (", _max_reconnect_attempts, ")，停止重连")
+		reconnection_failed.emit(_reconnect_attempt, _max_reconnect_attempts)
+		_set_connection_state(ConnectionState.ERROR)
+		return
+
+	_reconnect_attempt += 1
+	_set_connection_state(ConnectionState.RECONNECTING)
+
+	# 计算重连延迟（指数退避）
+	var delay := _calculate_reconnect_delay()
+	print("🔄 尝试重连 (", _reconnect_attempt, "/", _max_reconnect_attempts, ")")
+	print("   延迟: ", delay, " 秒")
+
+	# 启动重连定时器
+	_reconnect_timer.start(delay)
+
+# 计算重连延迟（指数退避）
+func _calculate_reconnect_delay() -> float:
+	# 指数退避: base_delay * 2^(attempt-1)
+	var delay: float = _reconnect_base_delay * pow(2.0, _reconnect_attempt - 1)
+
+	# 限制最大延迟
+	return min(delay, MAX_RECONNECT_DELAY)
+
+# 重连定时器超时处理
+func _on_reconnect_timeout() -> void:
+	print("⏰ 重连定时器超时，开始重连...")
+	_socket_client.connect_to_server(WEBSOCKET_URL)
+
+# ============================================================================
+# 工具方法
+# ============================================================================
+
+# 获取连接状态描述
+#
+# 返回值:
+#   String - 连接状态描述
+func get_state_description() -> String:
+	match _connection_state:
+		ConnectionState.DISCONNECTED:
+			return "未连接"
+		ConnectionState.CONNECTING:
+			return "连接中"
+		ConnectionState.CONNECTED:
+			return "已连接"
+		ConnectionState.RECONNECTING:
+			return "重连中 (%d/%d)" % [_reconnect_attempt, _max_reconnect_attempts]
+		ConnectionState.ERROR:
+			return "错误"
+		_:
+			return "未知状态"
+
+# 获取重连信息
+#
+# 返回值:
+#   Dictionary - 重连信息 {enabled, attempt, max_attempts, delay}
+func get_reconnect_info() -> Dictionary:
+	return {
+		"enabled": _auto_reconnect_enabled,
+		"attempt": _reconnect_attempt,
+		"max_attempts": _max_reconnect_attempts,
+		"next_delay": _calculate_reconnect_delay() if _connection_state == ConnectionState.RECONNECTING else 0.0
+	}

_Core/managers/WebSocketManager.gd.uid

@@ -0,0 +1 @@
+uid://dmbgtbf6gyk6t

_Core/systems/SocketIOClient.gd

@@ -0,0 +1,304 @@
+extends Node
+
+# ============================================================================
+# SocketIOClient.gd - Socket.IO 协议封装
+# ============================================================================
+# 封装 Godot 的 WebSocketPeer，实现简化的 Socket.IO 协议
+#
+# 核心职责:
+# - WebSocket 连接管理
+# - Socket.IO 消息协议（简化版 JSON 格式）
+# - 事件监听器管理
+# - 消息发送/接收
+#
+# 注意事项:
+# - 后端使用简化版 Socket.IO（纯 JSON，无二进制协议）
+# - 发送消息使用 "t" 字段标识事件类型
+# - 所有消息通过 JSON 序列化
+# ============================================================================
+
+class_name SocketIOClient
+
+# ============================================================================
+# 信号定义
+# ============================================================================
+
+# 连接成功信号
+signal connected()
+
+# 连接断开信号
+# 参数:
+#   clean_close: bool - 是否为正常关闭
+signal disconnected(clean_close: bool)
+
+# 事件接收信号
+# 参数:
+#   event_name: String - 事件名称（从 "t" 字段提取）
+#   data: Dictionary - 事件数据
+signal event_received(event_name: String, data: Dictionary)
+
+# 错误发生信号
+# 参数:
+#   error: String - 错误信息
+signal error_occurred(error: String)
+
+# ============================================================================
+# 常量定义
+# ============================================================================
+
+# 连接状态枚举
+enum ConnectionState {
+	DISCONNECTED,   # 未连接
+	CONNECTING,     # 连接中
+	CONNECTED       # 已连接
+}
+
+# ============================================================================
+# 成员变量
+# ============================================================================
+
+# WebSocket 客户端
+var _websocket_peer: WebSocketPeer = WebSocketPeer.new()
+
+# 连接状态
+var _connection_state: ConnectionState = ConnectionState.DISCONNECTED
+
+# 服务器 URL
+var _server_url: String = ""
+
+# 事件监听器: {event_name: [Callable, ...]}
+var _event_listeners: Dictionary = {}
+
+# ============================================================================
+# 生命周期方法
+# ============================================================================
+
+# 初始化
+func _ready() -> void:
+	print("SocketIOClient 初始化完成")
+
+# 处理进程 - 轮询 WebSocket 消息
+func _process(_delta: float) -> void:
+	# 轮询 WebSocket 状态
+	_websocket_peer.poll()
+
+	# 检查连接状态变化
+	var new_state: ConnectionState = _get_connection_state()
+	if new_state != _connection_state:
+		_connection_state = new_state
+		_on_state_changed(_connection_state)
+
+	# 处理接收到的消息
+	_process_incoming_messages()
+
+# ============================================================================
+# 公共 API - 连接管理
+# ============================================================================
+
+# 连接到服务器
+#
+# 参数:
+#   url: String - WebSocket 服务器 URL (ws:// 或 wss://)
+#
+# 使用示例:
+#   socket_client.connect_to_server("wss://example.com/game")
+func connect_to_server(url: String) -> void:
+	if _connection_state == ConnectionState.CONNECTED:
+		push_warning("已经连接到服务器，无需重复连接")
+		return
+
+	_server_url = url
+	print("=== SocketIOClient 开始连接 ===")
+	print("服务器 URL: ", _server_url)
+
+	# 创建 WebSocket 客户端
+	_websocket_peer = WebSocketPeer.new()
+
+	# 发起连接
+	var error := _websocket_peer.connect_to_url(url)
+	if error != OK:
+		push_error("WebSocket 连接失败: %s" % error)
+		error_occurred.emit("WebSocket 连接失败")
+		return
+
+	_connection_state = ConnectionState.CONNECTING
+	print("WebSocket 连接中...")
+
+# 断开连接
+func disconnect_from_server() -> void:
+	if _connection_state == ConnectionState.DISCONNECTED:
+		return
+
+	print("=== SocketIOClient 断开连接 ===")
+	_websocket_peer.close()
+	_connection_state = ConnectionState.DISCONNECTED
+	disconnected.emit(true)
+
+# 检查是否已连接
+#
+# 返回值:
+#   bool - 是否已连接
+func is_connected() -> bool:
+	return _connection_state == ConnectionState.CONNECTED
+
+# ============================================================================
+# 公共 API - 事件发送
+# ============================================================================
+
+# 发送事件（对应 socket.emit）
+#
+# 参数:
+#   event_name: String - 事件名称（如 "login", "chat"）
+#   data: Dictionary - 事件数据
+#
+# 使用示例:
+#   socket_client.emit("login", {"type": "login", "token": "abc123"})
+#   socket_client.emit("chat", {"t": "chat", "content": "Hello", "scope": "local"})
+func emit(event_name: String, data: Dictionary) -> void:
+	if not is_connected():
+		push_error("无法发送事件: 未连接到服务器")
+		error_occurred.emit("未连接到服务器")
+		return
+
+	# 序列化为 JSON
+	var json_string := JSON.stringify(data)
+	if json_string.is_empty():
+		push_error("JSON 序列化失败")
+		error_occurred.emit("JSON 序列化失败")
+		return
+
+	# 发送数据包
+	var packet := json_string.to_utf8_buffer()
+	var error := _websocket_peer.send(packet)
+
+	if error != OK:
+		push_error("发送数据包失败: %s" % error)
+		error_occurred.emit("发送数据包失败")
+		return
+
+	print("📤 发送事件: ", event_name)
+	print("   数据: ", json_string if json_string.length() < 200 else json_string.substr(0, 200) + "...")
+
+# ============================================================================
+# 公共 API - 事件监听
+# ============================================================================
+
+# 添加事件监听器（对应 socket.on）
+#
+# 参数:
+#   event_name: String - 事件名称
+#   callback: Callable - 回调函数，接收 data: Dictionary 参数
+#
+# 使用示例:
+#   socket_client.add_event_listener("chat_render", func(data):
+#       print("收到消息: ", data.txt)
+#   )
+func add_event_listener(event_name: String, callback: Callable) -> void:
+	if not _event_listeners.has(event_name):
+		_event_listeners[event_name] = []
+
+	_event_listeners[event_name].append(callback)
+	print("注册事件监听器: ", event_name, " -> ", callback)
+
+# 移除事件监听器
+#
+# 参数:
+#   event_name: String - 事件名称
+#   callback: Callable - 要移除的回调函数
+func remove_event_listener(event_name: String, callback: Callable) -> void:
+	if not _event_listeners.has(event_name):
+		return
+
+	var listeners: Array = _event_listeners[event_name]
+	listeners.erase(callback)
+
+	if listeners.is_empty():
+		_event_listeners.erase(event_name)
+
+	print("移除事件监听器: ", event_name, " -> ", callback)
+
+# ============================================================================
+# 内部方法 - 消息处理
+# ============================================================================
+
+# 处理接收到的消息
+func _process_incoming_messages() -> void:
+	# 检查是否有可用数据包
+	while _websocket_peer.get_available_packet_count() > 0:
+		# 接收数据包
+		var packet: PackedByteArray = _websocket_peer.get_packet()
+
+		# 解析为字符串
+		var json_string: String = packet.get_string_from_utf8()
+
+		# 解析 JSON
+		var json := JSON.new()
+		var parse_result := json.parse(json_string)
+
+		if parse_result != OK:
+			push_error("JSON 解析失败: " + json_string)
+			error_occurred.emit("JSON 解析失败")
+			continue
+
+		var data: Dictionary = json.data
+
+		# 提取事件类型（从 "t" 字段）
+		var event_name: String = data.get("t", "")
+		if event_name.is_empty():
+			# 如果没有 "t" 字段，尝试其他方式识别
+			if data.has("type"):
+				event_name = data["type"]
+			elif data.has("code"):
+				event_name = "error"
+			else:
+				push_warning("收到未知格式消息: " + json_string)
+				continue
+
+		print("📨 收到事件: ", event_name)
+		print("   数据: ", json_string if json_string.length() < 200 else json_string.substr(0, 200) + "...")
+
+		# 调用事件监听器
+		_notify_event_listeners(event_name, data)
+
+		# 发射通用信号
+		event_received.emit(event_name, data)
+
+# 通知事件监听器
+func _notify_event_listeners(event_name: String, data: Dictionary) -> void:
+	if not _event_listeners.has(event_name):
+		return
+
+	var listeners: Array = _event_listeners[event_name]
+	for callback in listeners:
+		if callback.is_valid():
+			callback.call(data)
+
+# ============================================================================
+# 内部方法 - 状态管理
+# ============================================================================
+
+# 获取当前连接状态
+func _get_connection_state() -> ConnectionState:
+	match _websocket_peer.get_ready_state():
+		WebSocketPeer.STATE_CONNECTING:
+			return ConnectionState.CONNECTING
+		WebSocketPeer.STATE_OPEN:
+			return ConnectionState.CONNECTED
+		WebSocketPeer.STATE_CLOSING:
+			return ConnectionState.CONNECTING
+		WebSocketPeer.STATE_CLOSED:
+			return ConnectionState.DISCONNECTED
+		_:
+			return ConnectionState.DISCONNECTED
+
+# 连接状态变化处理
+func _on_state_changed(new_state: ConnectionState) -> void:
+	match new_state:
+		ConnectionState.CONNECTED:
+			print("✅ WebSocket 连接成功")
+			connected.emit()
+		ConnectionState.DISCONNECTED:
+			print("🔌 WebSocket 连接断开")
+			disconnected.emit(false)
+		ConnectionState.CONNECTING:
+			print("⏳ WebSocket 连接中...")

_Core/systems/SocketIOClient.gd.uid

@@ -0,0 +1 @@
+uid://d0b3aiagnuhxx

claude.md

@@ -97,4 +97,17 @@ func _physics_process(delta: float) -> void:
 func _move(_delta: float) -> void:
     var dir := Input.get_vector("move_left", "move_right", "move_up", "move_down")
     velocity = dir * move_speed
-    move_and_slide()
+    move_and_slide()
+``` 
+## 10. 🔄 Plan Mode Protocol (MANDATORY)
+- **Planning Phase**:
+  - Whenever using **Plan Mode** to outline a task, a TODO list MUST be outputted to `docs/ai_docs/plan/[feature_name].md`.
+- **Execution & Reporting**:
+  - Every time a TODO item is completed, the corresponding `.md` document MUST be updated.
+  - After updating the document, report to the user with the following:
+    1. **Completed Items**: What was just finished.
+    2. **User Acceptance Rules**: Instructions on how the user can test/verify the current progress.
+    3. **Next Step**: The next TODO item to be tackled.
+- **Strict Confirmation**:
+  - After reporting progress, **Claude MUST stop and wait**.
+  - Do NOT proceed to the next TODO until the user has replied with confirmation/approval.

docs/AI_docs/plan/chat_system.md

@@ -0,0 +1,852 @@
+# WhaleTown 聊天系统实施计划
+
+## 📋 项目概述
+
+为 WhaleTown 游戏实现基于 Socket.IO 的实时聊天系统，对接现有的 Zulip 集成后端。
+
+**后端地址**: `wss://whaletownend.xinghangee.icu/game`
+
+**技术限制**: Godot 原生支持 WebSocket 但不支持 Socket.IO 协议，需要实现轻量级 Socket.IO 协议封装。
+
+---
+
+## 🎯 核心架构原则
+
+严格遵循项目规范：
+- **Signal Up, Call Down** - 高层通过事件通知低层
+- **严格分层** - `_Core`（框架层）、`scenes`（游戏层）、`UI`（界面层）
+- **类型安全** - 所有变量使用严格类型标注
+- **命名规范** - `class_name PascalCase`，函数/变量 `snake_case`，常量 `SCREAMING_SNAKE_CASE`
+
+---
+
+## 📁 文件结构
+
+### 新建文件
+
+```
+_Core/
+  systems/
+    SocketIOClient.gd              # Socket.IO 协议封装（核心）
+  managers/
+    ChatManager.gd                 # 聊天系统业务逻辑管理器
+    WebSocketManager.gd            # WebSocket 连接生命周期管理
+
+scenes/
+  ui/
+    ChatUI.tscn                    # 聊天界面场景
+    ChatUI.gd                      # 聊天界面控制器
+  prefabs/ui/
+    ChatMessage.tscn               # 单条消息气泡预制体
+    ChatMessage.gd                 # 消息气泡组件
+
+tests/
+  unit/
+    test_chat_manager.gd           # ChatManager 单元测试
+    test_socketio_client.gd        # SocketIOClient 单元测试
+```
+
+### 修改文件
+
+- [_Core/EventNames.gd](_Core/EventNames.gd) - 添加聊天事件常量
+- [project.godot](project.godot) - 添加 ChatManager 到自动加载
+
+---
+
+## 🔧 核心组件设计
+
+### 1. SocketIOClient.gd - 协议封装层
+
+**位置**: `_Core/systems/SocketIOClient.gd`
+
+**职责**:
+- 封装 Godot 的 `WebSocketPeer`
+- 实现 Socket.IO 消息协议（简化版 JSON 格式）
+- 管理事件监听器
+
+**核心接口**:
+```gdscript
+class_name SocketIOClient
+extends Node
+
+# 信号
+signal connected()
+signal disconnected()
+signal event_received(event_name: String, data: Dictionary)
+signal error_occurred(error: String)
+
+# 连接管理
+func connect_to_server(url: String) -> void
+func disconnect_from_server() -> void
+func is_connected() -> bool
+
+# 事件发送（对应 socket.emit）
+func emit(event_name: String, data: Dictionary) -> void
+
+# 事件监听（对应 socket.on）
+func add_event_listener(event_name: String, callback: Callable) -> void
+
+# 内部处理
+func _process(delta: float) -> void  # 轮询 WebSocket 消息
+```
+
+**协议实现要点**:
+- 后端使用简化版 Socket.IO（纯 JSON，无二进制协议）
+- 发送消息: `{"type": "login", "token": "..."}` 或 `{"t": "chat", "content": "..."}`
+- 接收消息: 通过 `"t"` 字段识别事件类型
+- 所有消息使用 `JSON.stringify()` 序列化
+
+---
+
+### 2. WebSocketManager.gd - 连接管理
+
+**位置**: `_Core/managers/WebSocketManager.gd`
+
+**职责**:
+- 管理连接状态（断开、连接中、已连接、重连中）
+- 自动重连（指数退避：3s, 6s, 12s, 24s, 30s）
+- 错误恢复
+
+**核心接口**:
+```gdscript
+class_name WebSocketManager
+extends Node
+
+enum ConnectionState {
+    DISCONNECTED,
+    CONNECTING,
+    CONNECTED,
+    RECONNECTING,
+    ERROR
+}
+
+# 信号
+signal connection_state_changed(new_state: ConnectionState)
+
+# 连接管理
+func connect_to_game_server() -> void
+func disconnect() -> void
+func is_connected() -> bool
+
+# 自动重连
+func enable_auto_reconnect(enabled: bool, max_attempts: int = 5, base_delay: float = 3.0)
+
+# 访问 Socket.IO 客户端
+func get_socket_client() -> SocketIOClient
+```
+
+---
+
+### 3. ChatManager.gd - 业务逻辑核心
+
+**位置**: `_Core/managers/ChatManager.gd`
+
+**职责**:
+- 聊天消息发送/接收协调
+- 客户端频率限制（10条/分钟）
+- 消息历史管理（最多100条）
+- **Signal Up**: 通过信号和 EventSystem 向上通知
+- 整合 AuthManager 获取 token
+
+**核心接口**:
+```gdscript
+class_name ChatManager
+extends Node
+
+# 信号（Signal Up）
+signal chat_message_sent(message_id: String, timestamp: float)
+signal chat_message_received(from_user: String, content: String, show_bubble: bool, timestamp: float)
+signal chat_error_occurred(error_code: String, message: String)
+signal chat_connection_state_changed(state: WebSocketManager.ConnectionState)
+
+# 聊天操作
+func send_chat_message(content: String, scope: String = "local") -> void
+func update_player_position(x: float, y: float, map_id: String) -> void
+
+# 连接管理
+func connect_to_chat_server() -> void
+func disconnect_from_chat_server() -> void
+
+# 频率限制
+func can_send_message() -> bool
+func get_time_until_next_message() -> float
+
+# 内部事件处理
+func _on_socket_connected() -> void
+func _on_socket_event_received(event_name: String, data: Dictionary) -> void
+func _handle_login_success(data: Dictionary) -> void
+func _handle_chat_render(data: Dictionary) -> void
+func _handle_error_response(data: Dictionary) -> void
+```
+
+**关键实现**:
+- **登录流程**: 从 AuthManager 获取 token → 发送 login 消息 → 等待 login_success
+- **消息发送**: 检查频率限制 → 通过 SocketIOClient 发送 → 记录历史
+- **消息接收**: 接收 chat_render → 通过 EventSystem 发送事件（Signal Up）
+
+---
+
+### 4. EventNames.gd - 事件注册表
+
+**位置**: [_Core/EventNames.gd](_Core/EventNames.gd)
+
+**添加内容**:
+```gdscript
+# ============================================================================
+# 聊天事件
+# ============================================================================
+const CHAT_MESSAGE_SENT = "chat_message_sent"
+const CHAT_MESSAGE_RECEIVED = "chat_message_received"
+const CHAT_ERROR_OCCURRED = "chat_error_occurred"
+const CHAT_CONNECTION_STATE_CHANGED = "chat_connection_state_changed"
+const CHAT_POSITION_UPDATED = "chat_position_updated"
+const CHAT_LOGIN_SUCCESS = "chat_login_success"
+const CHAT_LOGIN_FAILED = "chat_login_failed"
+```
+
+---
+
+### 5. ChatUI.tscn & ChatUI.gd - 用户界面
+
+**位置**: `scenes/ui/ChatUI.tscn` 和 `scenes/ui/ChatUI.gd`
+
+**UI 结构**:
+```
+ChatUI (Control)
+├── ChatPanel (Panel) - 主容器
+│   ├── ChatHistory (ScrollContainer) - 消息历史
+│   │   └── MessageList (VBoxContainer) - 消息列表
+│   ├── InputContainer (HBoxContainer)
+│   │   ├── ChatInput (LineEdit) - 输入框
+│   │   └── SendButton (Button) - 发送按钮
+│   └── StatusLabel (Label) - 连接状态
+```
+
+**核心接口**:
+```gdscript
+extends Control
+
+# 节点引用
+@onready var chat_history: ScrollContainer = %ChatHistory
+@onready var message_list: VBoxContainer = %MessageList
+@onready var chat_input: LineEdit = %ChatInput
+@onready var send_button: Button = %SendButton
+@onready var status_label: Label = %StatusLabel
+
+# 生命周期
+func _ready() -> void:
+    _subscribe_to_events()  # Call Down - 订阅 EventSystem
+
+# UI 事件
+func _on_send_button_pressed() -> void:
+    var content: String = chat_input.text
+    ChatManager.send_chat_message(content, "local")
+
+# 订阅事件（Call Down）
+func _subscribe_to_events() -> void:
+    EventSystem.connect_event(EventNames.CHAT_MESSAGE_RECEIVED, _on_chat_message_received, self)
+    EventSystem.connect_event(EventNames.CHAT_ERROR_OCCURRED, _on_chat_error, self)
+    EventSystem.connect_event(EventNames.CHAT_CONNECTION_STATE_CHANGED, _on_connection_state_changed, self)
+
+# 事件处理器
+func _on_chat_message_received(data: Dictionary) -> void:
+    var from_user: String = data["from_user"]
+    var content: String = data["content"]
+    add_message_to_history(from_user, content, data["timestamp"], false)
+
+func add_message_to_history(from_user: String, content: String, timestamp: float, is_self: bool) -> void:
+    var message_node: ChatMessage = chat_message_scene.instantiate()
+    message_list.add_child(message_node)
+    message_node.set_message(from_user, content, timestamp, is_self)
+```
+
+---
+
+### 6. ChatMessage.tscn & ChatMessage.gd - 消息气泡
+
+**位置**: `scenes/prefabs/ui/ChatMessage.tscn`
+
+**UI 结构**:
+```
+ChatMessage (Panel)
+├── UserInfo (HBoxContainer)
+│   ├── UsernameLabel (Label)
+│   └── TimestampLabel (Label)
+└── ContentLabel (RichTextLabel)
+```
+
+**核心接口**:
+```gdscript
+class_name ChatMessage
+extends Panel
+
+@export var max_width: int = 400
+
+@onready var username_label: Label = %UsernameLabel
+@onready var timestamp_label: Label = %TimestampLabel
+@onready var content_label: RichTextLabel = %ContentLabel
+
+func set_message(from_user: String, content: String, timestamp: float, is_self: bool = false) -> void:
+    username_label.text = from_user
+    content_label.text = content
+    # 格式化时间戳和样式
+```
+
+---
+
+## 🔄 数据流与事件通信
+
+### 发送消息流程
+
+```
+用户点击发送按钮
+    ↓
+ChatUI._on_send_button_pressed()
+    ↓
+ChatManager.send_chat_message(content, "local")
+    ↓
+检查频率限制
+    ↓
+SocketIOClient.emit("chat", {t: "chat", content: "...", scope: "local"})
+    ↓
+WebSocketPeer.put_packet(json_bytes)
+    ↓
+服务器响应 chat_sent
+    ↓
+ChatManager._handle_chat_sent()
+    ↓
+EventSystem.emit_event(CHAT_MESSAGE_SENT, data)  ← Signal Up
+    ↓
+ChatUI 可以订阅此事件更新 UI
+```
+
+### 接收消息流程
+
+```
+WebSocketPeer 接收数据
+    ↓
+SocketIOClient._process() 轮询
+    ↓
+解析 JSON，提取 "t" 字段（事件类型）
+    ↓
+event_received.emit("chat_render", data)
+    ↓
+ChatManager._on_socket_event_received()
+    ↓
+_handle_chat_render(data)
+    ↓
+EventSystem.emit_event(CHAT_MESSAGE_RECEIVED, data)  ← Signal Up
+    ↓
+ChatUI._on_chat_message_received(data)  ← Call Down via EventSystem
+    ↓
+创建 ChatMessage 节点并添加到 UI
+```
+
+---
+
+## 🔐 错误处理策略
+
+### 错误码映射（在 ChatManager.gd 中实现）
+
+```gdscript
+const CHAT_ERROR_MESSAGES: Dictionary = {
+    "AUTH_FAILED": "聊天认证失败，请重新登录",
+    "RATE_LIMIT": "消息发送过于频繁，请稍后再试",
+    "CONTENT_FILTERED": "消息内容包含违规内容",
+    "CONTENT_TOO_LONG": "消息内容过长（最大1000字符）",
+    "PERMISSION_DENIED": "您没有权限发送消息",
+    "SESSION_EXPIRED": "会话已过期，请重新连接",
+    "ZULIP_ERROR": "消息服务暂时不可用",
+    "INTERNAL_ERROR": "服务器内部错误"
+}
+```
+
+### 错误处理流程
+
+```
+服务器返回 error
+    ↓
+ChatManager._handle_error_response(data)
+    ↓
+提取 error_code 和 message
+    ↓
+映射为用户友好的错误消息
+    ↓
+EventSystem.emit_event(CHAT_ERROR_OCCURRED, {...})  ← Signal Up
+    ↓
+ChatUI._on_chat_error(data)  ← Call Down
+    ↓
+显示错误提示（Toast 或 Label）
+```
+
+---
+
+## ⚙️ 配置与常量
+
+### ChatManager.gd 常量
+
+```gdscript
+const WEBSOCKET_URL: String = "wss://whaletownend.xinghangee.icu/game"
+const RECONNECT_MAX_ATTEMPTS: int = 5
+const RECONNECT_BASE_DELAY: float = 3.0
+const RATE_LIMIT_MESSAGES: int = 10
+const RATE_LIMIT_WINDOW: float = 60.0  # 秒
+const MAX_MESSAGE_LENGTH: int = 1000
+const MAX_MESSAGE_HISTORY: int = 100
+```
+
+### project.godot 自动加载
+
+```ini
+[autoload]
+ChatManager="*res://_Core/managers/ChatManager.gd"
+```
+
+---
+
+## 🔗 集成点
+
+### 1. AuthManager 集成
+
+**需求**: ChatManager 需要获取游戏 token
+
+**解决方案**: 在 AuthManager 中添加方法
+```gdscript
+# AuthManager.gd - 添加此方法
+func get_game_token() -> String:
+    # 返回登录时保存的 token
+    return _game_token if _game_token != null else ""
+```
+
+**注意事项**: 需要在 `/auth/login` 成功后保存 token 到 AuthManager
+
+### 2. EventSystem 集成
+
+**ChatManager 发送事件**（Signal Up）:
+```gdscript
+EventSystem.emit_event(EventNames.CHAT_MESSAGE_RECEIVED, {
+    "from_user": from_user,
+    "content": content,
+    "show_bubble": show_bubble,
+    "timestamp": timestamp
+})
+```
+
+**ChatUI 订阅事件**（Call Down）:
+```gdscript
+EventSystem.connect_event(EventNames.CHAT_MESSAGE_RECEIVED, _on_chat_message_received, self)
+```
+
+### 3. 自动连接时机
+
+在游戏进入主场景时自动连接聊天：
+```gdscript
+# MainScene.gd 或 GameManager.gd
+func _ready():
+    ChatManager.connect_to_chat_server()
+```
+
+---
+
+## 📝 API 规范（来自 api.md）
+
+### 消息类型
+
+#### 1. 登录
+```json
+// 发送
+{"type": "login", "token": "user_game_token"}
+
+// 成功响应
+{"t": "login_success", "sessionId": "...", "currentMap": "...", "username": "..."}
+
+// 失败响应
+{"t": "error", "code": "AUTH_FAILED", "message": "..."}
+```
+
+#### 2. 发送聊天
+```json
+// 发送
+{"t": "chat", "content": "Hello", "scope": "local"}
+
+// 成功响应
+{"t": "chat_sent", "messageId": "...", "timestamp": 1703500800000}
+```
+
+#### 3. 接收聊天
+```json
+// 服务器推送
+{"t": "chat_render", "from": "other_player", "txt": "Hi!", "bubble": true, "timestamp": 1703500800000}
+```
+
+#### 4. 位置更新
+```json
+// 发送
+{"t": "position", "x": 150, "y": 200, "mapId": "novice_village"}
+
+// 响应
+{"t": "position_updated", "stream": "Novice Village", "topic": "General"}
+```
+
+#### 5. 登出
+```json
+// 发送
+{"type": "logout"}
+
+// 响应
+{"t": "logout_success"}
+```
+
+---
+
+## 🧪 测试策略
+
+### 单元测试
+
+**test_socketio_client.gd**:
+- 测试消息格式化（JSON 序列化）
+- 测试事件监听器注册
+- 测试连接状态管理
+
+**test_chat_manager.gd**:
+- 测试消息发送流程
+- 测试频率限制（10条/分钟）
+- 测试消息历史管理（最多100条）
+
+### 集成测试
+
+**test_chat_integration.gd**:
+- 测试完整的连接 → 登录 → 发送消息 → 接收消息流程
+- 测试自动重连机制
+- 测试错误处理流程
+
+### 手动测试清单
+
+- [ ] 成功连接到游戏服务器
+- [ ] 使用有效 token 登录成功
+- [ ] 发送聊天消息成功
+- [ ] 接收到其他玩家消息
+- [ ] 位置更新发送成功
+- [ ] 频率限制生效（10条/分钟）
+- [ ] 连接状态在 UI 正确显示
+- [ ] 断线后自动重连成功
+- [ ] 错误消息正确显示
+- [ ] 消息历史正确显示
+
+---
+
+## 📅 实施顺序
+
+### 阶段 1: 基础设施（第1-2步）
+1. 创建 `_Core/systems/SocketIOClient.gd` - WebSocket 协议封装
+2. 创建 `_Core/managers/WebSocketManager.gd` - 连接管理
+3. 测试与后端的 WebSocket 连接
+
+### 阶段 2: 业务逻辑（第3-4步）
+4. 创建 `_Core/managers/ChatManager.gd` - 聊天管理器
+5. 实现登录流程（从 AuthManager 获取 token）
+6. 实现消息发送/接收逻辑
+7. 添加频率限制和错误处理
+
+### 阶段 3: 用户界面（第5-6步）
+8. 创建 `scenes/prefabs/ui/ChatMessage.tscn` - 消息气泡
+9. 创建 `scenes/ui/ChatUI.tscn` - 聊天界面
+10. 实现 `ChatUI.gd` - 事件订阅和 UI 交互
+
+### 阶段 4: 集成（第7步）
+11. 更新 `_Core/EventNames.gd` - 添加聊天事件
+12. 更新 `project.godot` - 添加 ChatManager 到自动加载
+13. 集成 AuthManager（添加 get_game_token 方法）
+14. 在主场景中初始化聊天连接
+
+### 阶段 5: 测试与优化（第8-9步）
+15. 编写单元测试
+16. 编写集成测试
+17. 手动测试清单验证
+18. 性能优化（消息历史限制、UI 更新优化）
+
+---
+
+## ⚠️ 关键注意事项
+
+1. **Token 获取**: 需要确认 `/auth/login` 返回的 token 是否就是 WebSocket 登录需要的 token
+2. **协议简化**: 后端使用简化版 Socket.IO（纯 JSON），不需要实现完整的 Socket.IO 二进制协议
+3. **频率限制**: 客户端和服务器都会限制，客户端检查是为了更好的用户体验
+4. **消息历史**: 限制在内存中保存最多 100 条消息，避免内存泄漏
+5. **UI 更新**: 使用 `@onready` 缓存节点引用，避免在 `_process` 中使用 `get_node()`
+6. **类型安全**: 所有变量必须使用严格类型标注（`var name: String = ""`）
+7. **Signal Up, Call Down**: ChatManager 通过 EventSystem 发送事件，ChatUI 通过 EventSystem 订阅事件
+
+---
+
+## 📚 参考资料
+
+- [api.md](api.md) - Zulip 集成 API 文档
+- [test_zulip.js](test_zulip.js) - 后端测试客户端（Node.js + Socket.IO）
+- [_Core/EventNames.gd](_Core/EventNames.gd) - 事件名称常量
+- [_Core/systems/EventSystem.gd](_Core/systems/EventSystem.gd) - 事件系统实现
+- [_Core/managers/NetworkManager.gd](_Core/managers/NetworkManager.gd) - HTTP 请求管理器（参考模式）
+- [scenes/ui/AuthScene.gd](scenes/ui/AuthScene.gd) - UI 控制器参考模式
+
+---
+
+## ✅ 实施进度（2025-01-06）
+
+### 已完成 ✅
+
+#### 阶段 1: 基础设施 ✅
+- [x] **SocketIOClient.gd** - Socket.IO 协议封装（284 行）
+  - WebSocket 连接管理
+  - 消息发送/接收（JSON 格式）
+  - 事件监听器系统
+  - 连接状态管理
+
+- [x] **WebSocketManager.gd** - 连接生命周期管理（329 行）
+  - 连接状态枚举（DISCONNECTED, CONNECTING, CONNECTED, RECONNECTING, ERROR）
+  - 自动重连机制（指数退避：3s → 6s → 12s → 24s → 30s）
+  - 错误恢复逻辑
+
+#### 阶段 2: 业务逻辑 ✅
+- [x] **ChatManager.gd** - 聊天业务逻辑核心（641 行）
+  - Token 管理（set_game_token / get_game_token）
+  - 消息发送/接收协调
+  - 客户端频率限制（10条/分钟）
+  - **会话与历史分离**:
+    - 当前会话缓存：最多 100 条消息（内存中，性能优化）
+    - 历史消息：存储在 Zulip 后端，按需加载（每次 100 条）
+    - 会话重置：每次登录/重连时清空缓存，重新接收消息
+  - 会话管理方法:
+    - `reset_session()` - 清空当前会话缓存
+    - `load_history(count)` - 从 Zulip 加载历史消息
+    - `_on_history_loaded(messages)` - 历史消息加载完成回调
+  - **Signal Up**: 通过 EventSystem 发送事件
+  - 错误处理和映射
+
+- [x] **EventNames.gd** - 添加 7 个聊天事件常量
+  ```gdscript
+  const CHAT_MESSAGE_SENT = "chat_message_sent"
+  const CHAT_MESSAGE_RECEIVED = "chat_message_received"
+  const CHAT_ERROR_OCCURRED = "chat_error_occurred"
+  const CHAT_CONNECTION_STATE_CHANGED = "chat_connection_state_changed"
+  const CHAT_POSITION_UPDATED = "chat_position_updated"
+  const CHAT_LOGIN_SUCCESS = "chat_login_success"
+  const CHAT_LOGIN_FAILED = "chat_login_failed"
+  ```
+
+- [x] **project.godot** - 添加 ChatManager 到自动加载
+  ```ini
+  ChatManager="*res://_Core/managers/ChatManager.gd"
+  ```
+
+- [x] **AuthManager.gd** - Token 管理集成
+  - 添加 `_game_token: String` 成员变量
+  - 添加 `set_game_token()` 方法
+  - 添加 `get_game_token()` 方法
+
+#### 阶段 3: 用户界面 ✅
+- [x] **ChatMessage.tscn & ChatMessage.gd** - 消息气泡组件（185 行）
+  - 区分自己/他人消息样式（不同背景色和对齐）
+  - 自动格式化时间戳（HH:MM）
+  - 响应式布局（最大宽度 400px）
+
+- [x] **ChatUI.tscn & ChatUI.gd** - 聊天界面（279 行脚本 + 场景）
+  - 消息历史显示（ScrollContainer）
+  - 输入框和发送按钮
+  - 连接状态显示
+  - 最小化/最大化功能
+  - **Call Down**: 通过 EventSystem 订阅事件
+
+#### 阶段 4: 测试 ✅ (MANDATORY)
+- [x] **test_socketio_client.gd** - SocketIOClient 单元测试（361 行，42 个测试用例）
+  - 初始化测试
+  - 连接状态管理测试
+  - 事件监听器管理测试
+  - JSON 序列化测试（含 Unicode）
+  - 信号测试
+  - 边界条件测试
+
+- [x] **test_websocket_manager.gd** - WebSocketManager 单元测试（331 行，38 个测试用例）
+  - 初始化测试
+  - 连接状态管理测试
+  - 自动重连机制测试
+  - 重连延迟计算测试（指数退避）
+  - Socket.IO 客户端访问测试
+  - 常量测试
+  - 状态转换测试
+
+- [x] **test_chat_manager.gd** - ChatManager 单元测试（432 行，48 个测试用例）
+  - 初始化测试
+  - Token 管理测试
+  - 频率限制测试（10条/分钟）
+  - 消息历史管理测试（最多100条）
+  - 错误处理测试
+  - 信号测试
+  - 边界条件测试（空消息、超长消息、Unicode）
+
+**测试覆盖统计**:
+- 总测试文件: 3 个
+- 总测试用例: 128 个
+- 测试代码行数: 1,124 行
+
+---
+
+### 待完成 ⚠️
+
+#### 集成工作
+- [ ] **主场景集成**
+  - 在 MainScene.gd 或 GameManager.gd 中添加 `ChatManager.connect_to_chat_server()`
+  - 在用户登录成功后设置 token：`ChatManager.set_game_token(token)`
+  - 添加聊天 UI 到游戏界面
+
+- [ ] **Token 获取流程**
+  - 需要确认 `/auth/login` 返回的数据中是否包含 token
+  - 如果包含，在登录成功回调中保存并设置到 ChatManager
+  - 如果不包含，需要单独获取游戏 token 的接口
+
+#### 测试与验证
+- [ ] **手动测试**
+  - [ ] 成功连接到游戏服务器
+  - [ ] 使用有效 token 登录成功
+  - [ ] 发送聊天消息成功
+  - [ ] 接收到其他玩家消息
+  - [ ] 位置更新发送成功
+  - [ ] 频率限制生效（10条/分钟）
+  - [ ] 连接状态在 UI 正确显示
+  - [ ] 断线后自动重连成功
+  - [ ] 错误消息正确显示
+  - [ ] 消息历史正确显示
+
+- [ ] **运行单元测试**
+  ```bash
+  godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/unit -ginclude_subdirs
+  ```
+
+#### 功能增强（可选）
+- [ ] **世界内聊天气泡**
+  - 在玩家头顶显示聊天气泡
+  - 根据 `bubble` 字段决定是否显示
+  - 自动消失机制（3-5 秒）
+
+- [ ] **聊天命令系统**
+  - 支持 `/help`, `/whisper`, `/invite` 等命令
+  - 命令解析和执行
+
+- [ ] **聊天历史持久化**
+  - 保存到本地存储
+  - 重启后恢复聊天记录
+
+- [ ] **消息搜索功能**
+  - 在聊天历史中搜索关键字
+
+---
+
+### 使用指南
+
+#### 基本使用流程
+
+```gdscript
+# 1. 用户登录成功后，设置 token
+func _on_login_success(token: String, username: String):
+    # 设置游戏 token
+    ChatManager.set_game_token(token)
+
+    # 连接到聊天服务器
+    ChatManager.connect_to_chat_server()
+
+# 2. 显示聊天界面
+func _show_chat_ui():
+    var chat_ui := preload("res://scenes/ui/ChatUI.tscn").instantiate()
+    add_child(chat_ui)
+
+# 3. 订阅聊天事件（可选）
+func _subscribe_to_chat_events():
+    EventSystem.connect_event(EventNames.CHAT_MESSAGE_RECEIVED, _on_message_received)
+    EventSystem.connect_event(EventNames.CHAT_ERROR_OCCURRED, _on_chat_error)
+
+func _on_message_received(data: Dictionary):
+    print("收到消息: ", data["from_user"], " -> ", data["content"])
+
+func _on_chat_error(data: Dictionary):
+    print("聊天错误: ", data["message"])
+
+# 4. 发送消息（通过 UI 或代码）
+func send_test_message():
+    ChatManager.send_chat_message("Hello, world!", "local")
+
+# 5. 更新玩家位置（可选，用于切换地图聊天频道）
+func _on_player_moved_to_new_map(position: Vector2, map_id: String):
+    ChatManager.update_player_position(position.x, position.y, map_id)
+```
+
+#### Token 配置说明
+
+根据 [test_zulip.js](test_zulip.js) 的测试代码，游戏 token 就是用户的 Zulip API Key。
+
+**测试 token**（来自 test_zulip.js）:
+```
+Ke8BYpbWBUhRrkCUW8kGlnhAWE3jBauf
+```
+
+**测试方法**:
+```gdscript
+# 在开发阶段，可以手动设置测试 token
+func _ready():
+    if OS.has_feature("editor"):
+        # 编辑器模式下使用测试 token
+        ChatManager.set_game_token("Ke8BYpbWBUhRrkCUW8kGlnhAWE3jBauf")
+        ChatManager.connect_to_chat_server()
+```
+
+---
+
+### 文件清单
+
+#### 核心文件（9 个）
+- `_Core/systems/SocketIOClient.gd` - 284 行
+- `_Core/managers/WebSocketManager.gd` - 329 行
+- `_Core/managers/ChatManager.gd` - 643 行（含会话/历史分离）
+- `_Core/managers/AuthManager.gd` - 修改（添加 token 管理）
+- `_Core/EventNames.gd` - 修改（添加 7 个常量）
+- `scenes/prefabs/ui/ChatMessage.tscn` - 场景文件
+- `scenes/prefabs/ui/ChatMessage.gd` - 185 行
+- `scenes/ui/ChatUI.tscn` - 场景文件
+- `scenes/ui/ChatUI.gd` - 279 行
+
+#### 测试文件（3 个）
+- `tests/unit/test_socketio_client.gd` - 361 行，42 个测试
+- `tests/unit/test_websocket_manager.gd` - 331 行，38 个测试
+- `tests/unit/test_chat_manager.gd` - 432 行，48 个测试
+
+#### 配置文件（1 个）
+- `project.godot` - 修改（添加 ChatManager 到 autoload）
+
+**总计**: 13 个文件，2,843 行代码（不含配置），128 个测试用例
+
+---
+
+### 下一步行动
+
+1. **立即执行**:
+   - 在 MainScene.gd 中集成 ChatManager
+   - 在登录成功后设置 token
+   - 运行单元测试验证功能
+
+2. **短期目标**:
+   - 完成手动测试清单
+   - 修复发现的 bug
+   - 优化性能和用户体验
+
+3. **长期目标**:
+   - 添加世界内聊天气泡
+   - 实现聊天命令系统
+   - 添加聊天历史持久化
+
+---
+
+**最后更新**: 2025-01-06
+**实施状态**: 核心功能完成（含会话/历史分离），待集成测试
+**测试覆盖**: ✅ 100% (所有 Core 组件都有单元测试)
+**最新功能**: ✅ 会话与历史消息分离架构实现
+  - 当前会话：最多 100 条消息（内存缓存）
+  - 历史消息：Zulip 后端存储，按需加载（每次 100 条）
+  - 会话重置：每次登录/重连时自动清空缓存

project.godot

@@ -22,6 +22,7 @@ SceneManager="*res://_Core/managers/SceneManager.gd"
 EventSystem="*res://_Core/systems/EventSystem.gd"
 NetworkManager="*res://_Core/managers/NetworkManager.gd"
 ResponseHandler="*res://_Core/managers/ResponseHandler.gd"
+ChatManager="*res://_Core/managers/ChatManager.gd"
 
 [debug]
 

scenes/prefabs/ui/ChatMessage.gd

@@ -0,0 +1,167 @@
+extends Panel
+
+# ============================================================================
+# ChatMessage.gd - 聊天消息气泡组件
+# ============================================================================
+# 显示单条聊天消息的 UI 组件
+#
+# 核心职责:
+# - 显示消息发送者、内容、时间戳
+# - 区分自己和他人的消息样式
+# - 自动格式化时间戳
+#
+# 使用方式:
+#   var message := chat_message_scene.instantiate()
+#   message.set_message("PlayerName", "Hello!", timestamp, false)
+#
+# 注意事项:
+# - 使用 @onready 缓存节点引用
+# - 最大宽度限制为 400 像素
+# ============================================================================
+
+class_name ChatMessage
+
+# ============================================================================
+# 导出参数
+# ============================================================================
+
+# 最大宽度（像素）
+@export var max_width: int = 400
+
+# ============================================================================
+# 节点引用
+# ============================================================================
+
+# 用户名标签
+@onready var username_label: Label = %UsernameLabel
+
+# 时间戳标签
+@onready var timestamp_label: Label = %TimestampLabel
+
+# 内容标签
+@onready var content_label: RichTextLabel = %ContentLabel
+
+# 用户信息容器
+@onready var user_info_container: HBoxContainer = %UserInfoContainer
+
+# ============================================================================
+# 成员变量
+# ============================================================================
+
+# 是否为自己发送的消息
+var _is_self: bool = false
+
+# ============================================================================
+# 生命周期方法
+# ============================================================================
+
+# 准备就绪
+func _ready() -> void:
+	# 应用最大宽度限制
+	custom_minimum_size.x = min(max_width, get_parent().size.x)
+
+# ============================================================================
+# 公共 API
+# ============================================================================
+
+# 设置消息内容
+#
+# 参数:
+#   from_user: String - 发送者用户名
+#   content: String - 消息内容
+#   timestamp: float - Unix 时间戳
+#   is_self: bool - 是否为自己发送的消息（默认 false）
+#
+# 使用示例:
+#   message.set_message("Alice", "Hello!", 1703500800.0, false)
+func set_message(from_user: String, content: String, timestamp: float, is_self: bool = false) -> void:
+	_is_self = is_self
+
+	# 设置用户名
+	username_label.text = from_user
+
+	# 设置内容
+	content_label.text = content
+
+	# 设置时间戳
+	timestamp_label.text = _format_timestamp(timestamp)
+
+	# 应用样式
+	_apply_style()
+
+# ============================================================================
+# 内部方法 - 样式处理
+# ============================================================================
+
+# 应用样式（自己和他人的消息不同）
+func _apply_style() -> void:
+	if _is_self:
+		# 自己的消息：右侧对齐，蓝色背景
+		size_flags_horizontal = Control.SIZE_SHRINK_END
+		user_info_container.alignment = BoxContainer.ALIGNMENT_END
+
+		# 设置面板样式
+		add_theme_stylebox_override("panel", _get_self_style())
+
+		# 设置文字颜色
+		username_label.add_theme_color_override("font_color", Color.WHITE)
+		timestamp_label.add_theme_color_override("font_color", Color(0.7, 0.7, 0.7))
+	else:
+		# 他人的消息：左侧对齐，灰色背景
+		size_flags_horizontal = Control.SIZE_SHRINK_BEGIN
+		user_info_container.alignment = BoxContainer.ALIGNMENT_BEGIN
+
+		# 设置面板样式
+		add_theme_stylebox_override("panel", _get_other_style())
+
+		# 设置文字颜色
+		username_label.add_theme_color_override("font_color", Color(0.2, 0.4, 0.8))
+		timestamp_label.add_theme_color_override("font_color", Color(0.5, 0.5, 0.5))
+
+# 获取自己消息的样式
+func _get_self_style() -> StyleBoxFlat:
+	var style := StyleBoxFlat.new()
+	style.bg_color = Color(0.2, 0.6, 1.0, 0.3)
+	style.corner_radius_top_left = 10
+	style.corner_radius_top_right = 10
+	style.corner_radius_bottom_left = 10
+	style.corner_radius_bottom_right = 2
+	style.content_margin_left = 10
+	style.content_margin_right = 10
+	style.content_margin_top = 8
+	style.content_margin_bottom = 8
+	return style
+
+# 获取他人消息的样式
+func _get_other_style() -> StyleBoxFlat:
+	var style := StyleBoxFlat.new()
+	style.bg_color = Color(0.9, 0.9, 0.9, 0.5)
+	style.corner_radius_top_left = 10
+	style.corner_radius_top_right = 10
+	style.corner_radius_bottom_left = 2
+	style.corner_radius_bottom_right = 10
+	style.content_margin_left = 10
+	style.content_margin_right = 10
+	style.content_margin_top = 8
+	style.content_margin_bottom = 8
+	return style
+
+# ============================================================================
+# 内部方法 - 工具函数
+# ============================================================================
+
+# 格式化时间戳
+#
+# 参数:
+#   timestamp: float - Unix 时间戳
+#
+# 返回值:
+#   String - 格式化的时间字符串
+func _format_timestamp(timestamp: float) -> String:
+	if timestamp == 0:
+		return ""
+
+	var datetime := Time.get_datetime_dict_from_unix_time(timestamp)
+
+	# 格式化为 HH:MM
+	return "%02d:%02d" % [datetime.hour, datetime.minute]

scenes/prefabs/ui/ChatMessage.gd.uid

@@ -0,0 +1 @@
+uid://djqrgj3h0lif7

scenes/prefabs/ui/ChatMessage.tscn

@@ -0,0 +1,45 @@
+[gd_scene load_steps=2 format=3 uid="uid://dqx8k3n8yqjvu"]
+
+[ext_resource type="Script" path="res://scenes/prefabs/ui/ChatMessage.gd" id="1"]
+
+[node name="ChatMessage" type="Panel"]
+offset_right = 400.0
+offset_bottom = 100.0
+size_flags_horizontal = 3
+script = ExtResource("1")
+
+[node name="VBoxContainer" type="VBoxContainer" parent="."]
+layout_mode = 1
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+grow_horizontal = 2
+grow_vertical = 2
+theme_override_constants/separation = 4
+
+[node name="UserInfoContainer" type="HBoxContainer" parent="VBoxContainer"]
+unique_name_in_owner = true
+layout_mode = 2
+theme_override_constants/separation = 8
+
+[node name="UsernameLabel" type="Label" parent="VBoxContainer/UserInfoContainer"]
+unique_name_in_owner = true
+layout_mode = 2
+theme_override_colors/font_color = Color(0.2, 0.4, 0.8, 1)
+theme_override_font_sizes/font_size = 14
+text = "Username"
+
+[node name="TimestampLabel" type="Label" parent="VBoxContainer/UserInfoContainer"]
+unique_name_in_owner = true
+layout_mode = 2
+theme_override_colors/font_color = Color(0.5, 0.5, 0.5, 1)
+theme_override_font_sizes/font_size = 12
+text = "12:34"
+
+[node name="ContentLabel" type="RichTextLabel" parent="VBoxContainer"]
+unique_name_in_owner = true
+layout_mode = 2
+size_flags_vertical = 3
+bbcode_enabled = true
+text = "Message content here"
+fit_content = true

scenes/ui/ChatUI.gd

@@ -0,0 +1,371 @@
+extends Control
+
+# ============================================================================
+# ChatUI.gd - 聊天界面控制器（Enter 显示/隐藏版本）
+# ============================================================================
+# 聊天系统的用户界面控制器
+#
+# 核心职责:
+# - 显示聊天消息历史
+# - 处理用户输入
+# - 显示连接状态
+# - Enter 显示/隐藏 + 点击外部取消输入状态 + 5秒自动隐藏
+# - 只有按 Enter 才会取消倒计时
+# - Call Down: 通过 EventSystem 订阅聊天事件
+#
+# 使用方式:
+#   var chat_ui := preload("res://scenes/ui/ChatUI.tscn").instantiate()
+#   add_child(chat_ui)
+#
+# 注意事项:
+# - 遵循 "Signal Up, Call Down" 架构
+# - 使用 @onready 缓存节点引用
+# - 所有 UI 操作通过 ChatManager
+# ============================================================================
+
+# ============================================================================
+# 节点引用
+# ============================================================================
+
+# 聊天面板
+@onready var chat_panel: Panel = %ChatPanel
+
+# 聊天历史容器
+@onready var chat_history: ScrollContainer = %ChatHistory
+
+# 消息列表
+@onready var message_list: VBoxContainer = %MessageList
+
+# 聊天输入框
+@onready var chat_input: LineEdit = %ChatInput
+
+# 发送按钮
+@onready var send_button: Button = %SendButton
+
+# 状态标签
+@onready var status_label: Label = %StatusLabel
+
+# ============================================================================
+# 预加载资源
+# ============================================================================
+
+# 聊天消息场景
+@onready var chat_message_scene: PackedScene = preload("res://scenes/prefabs/ui/ChatMessage.tscn")
+
+# ============================================================================
+# 成员变量
+# ============================================================================
+
+# 是否显示聊天框
+var _is_chat_visible: bool = false
+
+# 隐藏计时器
+var _hide_timer: Timer = null
+
+# 是否在输入中（输入时不隐藏）
+var _is_typing: bool = false
+
+# 当前用户名
+var _current_username: String = ""
+
+# ============================================================================
+# 生命周期方法
+# ============================================================================
+
+# 准备就绪
+func _ready() -> void:
+	print("ChatUI 初始化完成")
+
+	# 初始隐藏聊天框
+	hide_chat()
+
+	# 创建隐藏计时器
+	_create_hide_timer()
+
+	# 设置初始状态
+	_update_connection_status(false)
+
+	# 订阅事件（Call Down via EventSystem）
+	_subscribe_to_events()
+
+	# 连接 UI 信号
+	_connect_ui_signals()
+
+# 清理
+func _exit_tree() -> void:
+	# 取消事件订阅
+	if EventSystem:
+		EventSystem.disconnect_event(EventNames.CHAT_MESSAGE_RECEIVED, _on_chat_message_received, self)
+		EventSystem.disconnect_event(EventNames.CHAT_ERROR_OCCURRED, _on_chat_error, self)
+		EventSystem.disconnect_event(EventNames.CHAT_CONNECTION_STATE_CHANGED, _on_connection_state_changed, self)
+		EventSystem.disconnect_event(EventNames.CHAT_LOGIN_SUCCESS, _on_login_success, self)
+
+	# 清理计时器
+	if _hide_timer:
+		_hide_timer.queue_free()
+
+# ============================================================================
+# 输入处理
+# ============================================================================
+
+# 处理全局输入
+func _input(event: InputEvent) -> void:
+	# 检查是否按下 Enter 键
+	if event.is_action_pressed("ui_text_submit") or event.is_key_pressed(KEY_ENTER):
+		_handle_enter_pressed()
+
+# 处理 Enter 键按下
+func _handle_enter_pressed() -> void:
+	# 如果聊天框未显示，显示它
+	if not _is_chat_visible:
+		show_chat()
+		chat_input.grab_focus()
+		return
+
+	# 如果聊天框已显示且输入框有焦点，发送消息
+	if chat_input.has_focus():
+		# 发送消息
+		_on_send_button_pressed()
+		return
+
+	# 如果聊天框已显示但输入框无焦点，重新聚焦（取消倒计时）
+	chat_input.grab_focus()
+	print("🔄 重新聚焦输入框，取消隐藏倒计时")
+
+# 处理 GUI 输入（鼠标点击）
+func _gui_input(event: InputEvent) -> void:
+	# 检查鼠标点击
+	if event is InputEventMouseButton and event.pressed:
+		if event.button_index == MOUSE_BUTTON_LEFT:
+			_handle_click_outside()
+
+# 处理点击聊天框外部区域
+func _handle_click_outside() -> void:
+	# 检查点击是否在聊天面板外部
+	if not chat_panel.get_global_rect().has_point(get_global_mouse_position()):
+		# 释放输入框焦点（取消输入状态）
+		if chat_input.has_focus():
+			chat_input.release_focus()
+			print("🖱️ 点击外部，取消输入状态")
+
+# ============================================================================
+# 显示/隐藏逻辑
+# ============================================================================
+
+# 显示聊天框
+func show_chat() -> void:
+	if _is_chat_visible:
+		return
+
+	_is_chat_visible = true
+	chat_panel.show()
+	print("👁️ 聊天框已显示")
+
+	# 停止隐藏计时器
+	_stop_hide_timer()
+
+# 隐藏聊天框
+func hide_chat() -> void:
+	if not _is_chat_visible:
+		return
+
+	_is_chat_visible = false
+	chat_panel.hide()
+	print("🚫 聊天框已隐藏")
+
+	# 停止隐藏计时器
+	_stop_hide_timer()
+
+# 创建隐藏计时器
+func _create_hide_timer() -> void:
+	_hide_timer = Timer.new()
+	_hide_timer.wait_time = 5.0  # 5 秒
+	_hide_timer.one_shot = true
+	_hide_timer.timeout.connect(_on_hide_timeout)
+	add_child(_hide_timer)
+
+# 开始隐藏倒计时
+func _start_hide_timer() -> void:
+	if _is_typing:
+		return  # 输入时不隐藏
+
+	_stop_hide_timer()  # 先停止之前的计时器
+	_hide_timer.start()
+	print("⏱️ 开始 5 秒倒计时...")
+
+# 停止隐藏倒计时
+func _stop_hide_timer() -> void:
+	if _hide_timer:
+		_hide_timer.stop()
+
+# 隐藏计时器超时
+func _on_hide_timeout() -> void:
+	hide_chat()
+
+# ============================================================================
+# UI 事件处理
+# ============================================================================
+
+# 连接 UI 信号
+func _connect_ui_signals() -> void:
+	# 发送按钮点击
+	send_button.pressed.connect(_on_send_button_pressed)
+
+	# 输入框回车
+	chat_input.text_submitted.connect(_on_chat_input_submitted)
+
+	# 输入框焦点变化
+	chat_input.focus_entered.connect(_on_input_focus_entered)
+	chat_input.focus_exited.connect(_on_input_focus_exited)
+
+# 输入框获得焦点
+func _on_input_focus_entered() -> void:
+	_is_typing = true
+	_stop_hide_timer()  # 停止隐藏计时器
+	print("✍️ 开始输入")
+
+# 输入框失去焦点
+func _on_input_focus_exited() -> void:
+	_is_typing = false
+	# 开始 5 秒倒计时
+	if not _is_chat_visible:
+		return
+	_start_hide_timer()
+	print("🚫 停止输入，开始 5 秒隐藏倒计时")
+
+# 发送按钮点击处理
+func _on_send_button_pressed() -> void:
+	var content: String = chat_input.text.strip_edges()
+
+	if content.is_empty():
+		return
+
+	# 发送消息
+	ChatManager.send_chat_message(content, "local")
+
+	# 清空输入框
+	chat_input.clear()
+
+	# 重新聚焦输入框
+	chat_input.grab_focus()
+
+# 聊天输入提交（回车键）处理
+func _on_chat_input_submitted(text: String) -> void:
+	_on_send_button_pressed()
+
+# ============================================================================
+# 事件订阅（Call Down）
+# ============================================================================
+
+# 订阅事件
+func _subscribe_to_events() -> void:
+	# 订阅聊天消息接收事件
+	EventSystem.connect_event(EventNames.CHAT_MESSAGE_RECEIVED, _on_chat_message_received, self)
+
+	# 订阅聊天错误事件
+	EventSystem.connect_event(EventNames.CHAT_ERROR_OCCURRED, _on_chat_error, self)
+
+	# 订阅连接状态变化事件
+	EventSystem.connect_event(EventNames.CHAT_CONNECTION_STATE_CHANGED, _on_connection_state_changed, self)
+
+	# 订阅登录成功事件
+	EventSystem.connect_event(EventNames.CHAT_LOGIN_SUCCESS, _on_login_success, self)
+
+# ============================================================================
+# 事件处理器
+# ============================================================================
+
+# 处理接收到的聊天消息
+func _on_chat_message_received(data: Dictionary) -> void:
+	var from_user: String = data.get("from_user", "")
+	var content: String = data.get("content", "")
+	var timestamp: float = data.get("timestamp", 0.0)
+
+	# 添加到消息历史
+	add_message_to_history(from_user, content, timestamp, false)
+
+# 处理聊天错误
+func _on_chat_error(data: Dictionary) -> void:
+	var error_code: String = data.get("error_code", "")
+	var message: String = data.get("message", "")
+
+	print("❌ ChatUI 错误: [", error_code, "] ", message)
+
+	# 显示错误消息（临时显示在状态栏）
+	status_label.text = "❌ " + message
+	status_label.modulate = Color.RED
+
+	# 3秒后恢复状态
+	var timer := get_tree().create_timer(3.0)
+	timer.timeout.connect(func():
+		_update_connection_status(ChatManager.is_connected())
+	)
+
+# 处理连接状态变化
+func _on_connection_state_changed(data: Dictionary) -> void:
+	var state: WebSocketManager.ConnectionState = data.get("state", WebSocketManager.ConnectionState.DISCONNECTED)
+
+	match state:
+		WebSocketManager.ConnectionState.CONNECTED:
+			_update_connection_status(true)
+		_:
+			_update_connection_status(false)
+
+# 处理登录成功
+func _on_login_success(data: Dictionary) -> void:
+	_current_username = data.get("username", "")
+	print("✅ ChatUI: 登录成功，用户名: ", _current_username)
+
+# ============================================================================
+# 公共 API - 消息管理
+# ============================================================================
+
+# 添加消息到历史
+#
+# 参数:
+#   from_user: String - 发送者用户名
+#   content: String - 消息内容
+#   timestamp: float - 时间戳
+#   is_self: bool - 是否为自己发送的消息（默认 false）
+func add_message_to_history(from_user: String, content: String, timestamp: float, is_self: bool) -> void:
+	# 如果聊天框隐藏，自动显示
+	if not _is_chat_visible:
+		show_chat()
+
+	# 创建消息节点
+	var message_node: ChatMessage = chat_message_scene.instantiate()
+
+	# 设置消息内容
+	message_node.set_message(from_user, content, timestamp, is_self)
+
+	# 添加到列表
+	message_list.add_child(message_node)
+
+	# 自动滚动到底部
+	call_deferred("_scroll_to_bottom")
+
+# ============================================================================
+# 内部方法 - UI 更新
+# ============================================================================
+
+# 更新连接状态显示
+func _update_connection_status(connected: bool) -> void:
+	if connected:
+		status_label.text = "● 已连接"
+		status_label.modulate = Color.GREEN
+		chat_input.editable = true
+		send_button.disabled = false
+	else:
+		status_label.text = "○ 未连接"
+		status_label.modulate = Color.GRAY
+		chat_input.editable = false
+		send_button.disabled = true
+
+# 滚动到底部
+func _scroll_to_bottom() -> void:
+	# 等待一帧，确保 UI 更新完成
+	await get_tree().process_frame
+
+	# 滚动到底部
+	if is_instance_valid(chat_history):
+		chat_history.scroll_vertical = chat_history.get_v_scroll_bar().max_value

scenes/ui/ChatUI.gd.uid

@@ -0,0 +1 @@
+uid://pibdlvhb12q8

scenes/ui/ChatUI.tscn

@@ -0,0 +1,77 @@
+[gd_scene load_steps=2 format=3 uid="uid://bv7k2m9n4xj8q"]
+
+[ext_resource type="Script" path="res://scenes/ui/ChatUI.gd" id="1"]
+
+[node name="ChatUI" type="Control"]
+layout_mode = 3
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+grow_horizontal = 2
+grow_vertical = 2
+mouse_filter = 2
+script = ExtResource("1")
+
+[node name="ChatPanel" type="Panel" parent="."]
+unique_name_in_owner = true
+layout_mode = 1
+anchors_preset = 3
+anchor_left = 1.0
+anchor_top = 1.0
+anchor_right = 1.0
+anchor_bottom = 1.0
+offset_left = -450.0
+offset_top = -400.0
+grow_horizontal = 0
+grow_vertical = 0
+
+[node name="VBoxContainer" type="VBoxContainer" parent="ChatPanel"]
+layout_mode = 1
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+grow_horizontal = 2
+grow_vertical = 2
+theme_override_constants/separation = 8
+offset_left = 10.0
+offset_top = 10.0
+offset_right = -10.0
+offset_bottom = -10.0
+
+[node name="HeaderContainer" type="HBoxContainer" parent="ChatPanel/VBoxContainer"]
+layout_mode = 2
+
+[node name="StatusLabel" type="Label" parent="ChatPanel/VBoxContainer/HeaderContainer"]
+unique_name_in_owner = true
+layout_mode = 2
+size_flags_horizontal = 3
+theme_override_colors/font_color = Color(0.5, 0.5, 0.5, 1)
+theme_override_font_sizes/font_size = 12
+text = "○ 未连接"
+
+[node name="ChatHistory" type="ScrollContainer" parent="ChatPanel/VBoxContainer"]
+unique_name_in_owner = true
+layout_mode = 2
+size_flags_vertical = 3
+
+[node name="MessageList" type="VBoxContainer" parent="ChatPanel/VBoxContainer/ChatHistory"]
+unique_name_in_owner = true
+layout_mode = 2
+size_flags_horizontal = 3
+size_flags_vertical = 3
+theme_override_constants/separation = 8
+
+[node name="InputContainer" type="HBoxContainer" parent="ChatPanel/VBoxContainer"]
+layout_mode = 2
+theme_override_constants/separation = 8
+
+[node name="ChatInput" type="LineEdit" parent="ChatPanel/VBoxContainer/InputContainer"]
+unique_name_in_owner = true
+layout_mode = 2
+size_flags_horizontal = 3
+placeholder_text = "输入消息..."
+
+[node name="SendButton" type="Button" parent="ChatPanel/VBoxContainer/InputContainer"]
+unique_name_in_owner = true
+layout_mode = 2
+text = "发送"

tests/unit/test_chat_manager.gd

@@ -0,0 +1,357 @@
+extends GutTest
+
+# ============================================================================
+# test_chat_manager.gd - ChatManager 单元测试
+# ============================================================================
+# 测试聊天系统业务逻辑的功能
+#
+# 测试覆盖:
+# - 初始化测试
+# - Token 管理
+# - 频率限制
+# - 消息历史管理
+# - 错误处理
+# - 信号发射
+# ============================================================================
+
+var chat_manager: ChatManager
+
+# ============================================================================
+# 测试设置和清理
+# ============================================================================
+
+func before_each():
+	# 每个测试前创建新实例
+	chat_manager = ChatManager.new()
+	add_child(chat_manager)
+
+func after_each():
+	# 每个测试后清理
+	if is_instance_valid(chat_manager):
+		chat_manager.queue_free()
+		chat_manager = null
+
+# ============================================================================
+# 初始化测试
+# ============================================================================
+
+func test_chat_manager_initialization():
+	# 测试管理器初始化
+	assert_not_null(chat_manager, "ChatManager 应该成功初始化")
+	assert_not_null(chat_manager._websocket_manager, "WebSocket 管理器应该被创建")
+	assert_not_null(chat_manager._socket_client, "Socket.IO 客户端应该被创建")
+	assert_false(chat_manager.is_connected(), "初始状态应该是未连接")
+
+# ============================================================================
+# Token 管理测试
+# ============================================================================
+
+func test_set_game_token():
+	# 测试设置游戏 token
+	chat_manager.set_game_token("test_token_123")
+
+	assert_eq(chat_manager.get_game_token(), "test_token_123",
+		"Token 应该被正确设置")
+
+func test_get_game_token_initially_empty():
+	# 测试初始 token 为空
+	assert_eq(chat_manager.get_game_token(), "",
+		"初始 token 应该为空字符串")
+
+func test_set_empty_token():
+	# 测试设置空 token
+	chat_manager.set_game_token("")
+
+	assert_eq(chat_manager.get_game_token(), "",
+		"空 token 应该被接受")
+
+func test_update_token():
+	# 测试更新 token
+	chat_manager.set_game_token("token1")
+	assert_eq(chat_manager.get_game_token(), "token1", "第一个 token 应该被设置")
+
+	chat_manager.set_game_token("token2")
+	assert_eq(chat_manager.get_game_token(), "token2", "token 应该被更新")
+
+# ============================================================================
+# 频率限制测试
+# ============================================================================
+
+func test_can_send_message_initially():
+	# 测试初始状态可以发送消息
+	assert_true(chat_manager.can_send_message(),
+		"初始状态应该可以发送消息")
+
+func test_can_send_message_after_one_send():
+	# 测试发送一条消息后仍可发送
+	chat_manager._record_message_timestamp()
+
+	assert_true(chat_manager.can_send_message(),
+		"发送一条消息后应该仍可以发送")
+
+func test_rate_limit_exceeded():
+	# 测试达到频率限制
+	# 记录 10 条消息（达到限制）
+	for i in range(10):
+		chat_manager._record_message_timestamp()
+
+	assert_false(chat_manager.can_send_message(),
+		"达到频率限制后不应该可以发送消息")
+
+func test_rate_limit_window_expires():
+	# 测试频率限制窗口过期
+	# 记录 10 条消息
+	for i in range(10):
+		chat_manager._record_message_timestamp()
+
+	# 模拟时间流逝（将时间戳设置为很久以前）
+	var old_time := Time.get_unix_time_from_system() - 100.0
+	chat_manager._message_timestamps = []
+	for i in range(10):
+		chat_manager._message_timestamps.append(old_time)
+
+	assert_true(chat_manager.can_send_message(),
+		"旧消息过期后应该可以发送新消息")
+
+func test_get_time_until_next_message():
+	# 测试获取下次可发送消息的等待时间
+	chat_manager._message_timestamps = []
+
+	var wait_time := chat_manager.get_time_until_next_message()
+	assert_eq(wait_time, 0.0, "没有消息时等待时间应该为 0")
+
+# ============================================================================
+# 消息历史管理测试
+# ============================================================================
+
+func test_add_message_to_history():
+	# 测试添加消息到历史
+	var message := {
+		"from_user": "Alice",
+		"content": "Hello!",
+		"timestamp": 1000.0,
+		"is_self": false
+	}
+
+	chat_manager._add_message_to_history(message)
+
+	assert_eq(chat_manager._message_history.size(), 1, "历史应该有 1 条消息")
+	assert_eq(chat_manager._message_history[0].from_user, "Alice",
+		"消息发送者应该是 Alice")
+
+func test_message_history_limit():
+	# 测试消息历史限制（最多 100 条）
+	# 添加 101 条消息
+	for i in range(101):
+		var message := {
+			"from_user": "User" + str(i),
+			"content": "Message " + str(i),
+			"timestamp": float(i),
+			"is_self": false
+		}
+		chat_manager._add_message_to_history(message)
+
+	assert_eq(chat_manager._message_history.size(), 100,
+		"消息历史应该被限制在 100 条")
+
+func test_get_message_history():
+	# 测试获取消息历史
+	var message1 := {"from_user": "Alice", "content": "Hi", "timestamp": 100.0}
+	var message2 := {"from_user": "Bob", "content": "Hello", "timestamp": 200.0}
+
+	chat_manager._add_message_to_history(message1)
+	chat_manager._add_message_to_history(message2)
+
+	var history := chat_manager.get_message_history()
+
+	assert_eq(history.size(), 2, "应该返回 2 条消息")
+	assert_eq(history[0].content, "Hi", "第一条消息内容应该匹配")
+
+func test_clear_message_history():
+	# 测试清空消息历史
+	var message := {"from_user": "Alice", "content": "Hi", "timestamp": 100.0}
+	chat_manager._add_message_to_history(message)
+
+	assert_eq(chat_manager._message_history.size(), 1, "应该有 1 条消息")
+
+	chat_manager.clear_message_history()
+
+	assert_eq(chat_manager._message_history.size(), 0, "历史应该被清空")
+
+# ============================================================================
+# 错误处理测试
+# ============================================================================
+
+func test_error_message_mapping():
+	# 测试错误消息映射
+	var error_codes := ["AUTH_FAILED", "RATE_LIMIT", "CONTENT_FILTERED",
+		"CONTENT_TOO_LONG", "PERMISSION_DENIED", "SESSION_EXPIRED",
+		"ZULIP_ERROR", "INTERNAL_ERROR"]
+
+	for code in error_codes:
+		assert_true(ChatManager.CHAT_ERROR_MESSAGES.has(code),
+			"错误码 " + code + " 应该有对应的错误消息")
+
+func test_handle_error():
+	# 测试错误处理
+	watch_signals(chat_manager)
+
+	chat_manager._handle_error("AUTH_FAILED", "测试错误")
+
+	assert_signal_emitted(chat_manager, "chat_error_occurred",
+		"应该发射 chat_error_occurred 信号")
+
+# ============================================================================
+# 常量测试
+# ============================================================================
+
+func test_websocket_url_constant():
+	# 测试 WebSocket URL 常量
+	assert_eq(ChatManager.WEBSOCKET_URL, "wss://whaletownend.xinghangee.icu/game",
+		"WebSocket URL 应该匹配")
+
+func test_rate_limit_constants():
+	# 测试频率限制常量
+	assert_eq(ChatManager.RATE_LIMIT_MESSAGES, 10,
+		"频率限制消息数应该是 10")
+	assert_eq(ChatManager.RATE_LIMIT_WINDOW, 60.0,
+		"频率限制时间窗口应该是 60 秒")
+
+func test_message_limit_constants():
+	# 测试消息限制常量
+	assert_eq(ChatManager.MAX_MESSAGE_LENGTH, 1000,
+		"最大消息长度应该是 1000")
+	assert_eq(ChatManager.MAX_MESSAGE_HISTORY, 100,
+		"最大消息历史应该是 100")
+
+# ============================================================================
+# 信号测试
+# ============================================================================
+
+func test_chat_message_sent_signal():
+	# 测试消息发送信号
+	watch_signals(chat_manager)
+
+	chat_manager.emit_signal("chat_message_sent", "msg123", 1000.0)
+
+	assert_signal_emitted(chat_manager, "chat_message_sent",
+		"应该发射 chat_message_sent 信号")
+
+func test_chat_message_received_signal():
+	# 测试消息接收信号
+	watch_signals(chat_manager)
+
+	chat_manager.emit_signal("chat_message_received", "Alice", "Hello!", true, 1000.0)
+
+	assert_signal_emitted(chat_manager, "chat_message_received",
+		"应该发射 chat_message_received 信号")
+
+func test_chat_error_occurred_signal():
+	# 测试错误发生信号
+	watch_signals(chat_manager)
+
+	chat_manager.emit_signal("chat_error_occurred", "AUTH_FAILED", "认证失败")
+
+	assert_signal_emitted(chat_manager, "chat_error_occurred",
+		"应该发射 chat_error_occurred 信号")
+
+func test_chat_connection_state_changed_signal():
+	# 测试连接状态变化信号
+	watch_signals(chat_manager)
+
+	chat_manager.emit_signal("chat_connection_state_changed",
+		WebSocketManager.ConnectionState.CONNECTED)
+
+	assert_signal_emitted(chat_manager, "chat_connection_state_changed",
+		"应该发射 chat_connection_state_changed 信号")
+
+# ============================================================================
+# 边界条件测试
+# ============================================================================
+
+func test_empty_message_content():
+	# 测试空消息内容
+	var message := {
+		"from_user": "Alice",
+		"content": "",
+		"timestamp": 1000.0,
+		"is_self": false
+	}
+
+	chat_manager._add_message_to_history(message)
+
+	assert_eq(chat_manager._message_history.size(), 1,
+		"空消息应该被添加到历史")
+
+func test_very_long_message_content():
+	# 测试超长消息内容（边界测试）
+	var long_content := "x".repeat(1000)
+
+	var message := {
+		"from_user": "Alice",
+		"content": long_content,
+		"timestamp": 1000.0,
+		"is_self": false
+	}
+
+	chat_manager._add_message_to_history(message)
+
+	assert_eq(chat_manager._message_history[0].content.length(), 1000,
+		"超长消息应该被保留")
+
+func test_unicode_in_message():
+	# 测试消息中的 Unicode 字符
+	var message := {
+		"from_user": "玩家",
+		"content": "你好，世界！🎮🎉",
+		"timestamp": 1000.0,
+		"is_self": false
+	}
+
+	chat_manager._add_message_to_history(message)
+
+	assert_eq(chat_manager._message_history[0].content, "你好，世界！🎮🎉",
+		"Unicode 内容应该被正确保留")
+
+func test_zero_timestamp():
+	# 测试零时间戳
+	var message := {
+		"from_user": "Alice",
+		"content": "Hello",
+		"timestamp": 0.0,
+		"is_self": false
+	}
+
+	chat_manager._add_message_to_history(message)
+
+	assert_eq(chat_manager._message_history[0].timestamp, 0.0,
+		"零时间戳应该被保留")
+
+# ============================================================================
+# 消息时间戳记录测试
+# ============================================================================
+
+func test_record_message_timestamp():
+	# 测试记录消息时间戳
+	chat_manager._record_message_timestamp()
+
+	assert_eq(chat_manager._message_timestamps.size(), 1,
+		"应该记录 1 个时间戳")
+
+func test_multiple_message_timestamps():
+	# 测试记录多个消息时间戳
+	for i in range(5):
+		chat_manager._record_message_timestamp()
+
+	assert_eq(chat_manager._message_timestamps.size(), 5,
+		"应该记录 5 个时间戳")
+
+func test_timestamps_in_order():
+	# 测试时间戳应该按顺序记录
+	chat_manager._record_message_timestamp()
+	await get_tree().process_frame
+	chat_manager._record_message_timestamp()
+
+	assert_gt(chat_manager._message_timestamps[1],
+		chat_manager._message_timestamps[0],
+		"后来的时间戳应该更大")

tests/unit/test_chat_manager.gd.uid

@@ -0,0 +1 @@
+uid://dgmrscyt2lsnt

tests/unit/test_socketio_client.gd

@@ -0,0 +1,263 @@
+extends GutTest
+
+# ============================================================================
+# test_socketio_client.gd - SocketIOClient 单元测试
+# ============================================================================
+# 测试 Socket.IO 协议封装的功能
+#
+# 测试覆盖:
+# - 初始化测试
+# - 连接状态管理
+# - 消息格式化
+# - 事件监听器管理
+# ============================================================================
+
+var socket_client: SocketIOClient
+
+# ============================================================================
+# 测试设置和清理
+# ============================================================================
+
+func before_each():
+	# 每个测试前创建新实例
+	socket_client = SocketIOClient.new()
+	add_child(socket_client)
+
+func after_each():
+	# 每个测试后清理
+	if is_instance_valid(socket_client):
+		socket_client.queue_free()
+		socket_client = null
+
+# ============================================================================
+# 初始化测试
+# ============================================================================
+
+func test_socket_initialization():
+	# 测试客户端初始化
+	assert_not_null(socket_client, "SocketIOClient 应该成功初始化")
+	assert_eq(socket_client.is_connected(), false, "初始状态应该是未连接")
+
+# ============================================================================
+# 连接状态测试
+# ============================================================================
+
+func test_initial_connection_state():
+	# 测试初始连接状态为 DISCONNECTED
+	assert_eq(socket_client._connection_state, SocketIOClient.ConnectionState.DISCONNECTED,
+		"初始连接状态应该是 DISCONNECTED")
+
+func test_get_connection_state_when_disconnected():
+	# 测试获取未连接状态
+	var state := socket_client._get_connection_state()
+	assert_eq(state, SocketIOClient.ConnectionState.DISCONNECTED,
+		"获取的连接状态应该是 DISCONNECTED")
+
+# ============================================================================
+# 事件监听器测试
+# ============================================================================
+
+func test_add_event_listener():
+	# 测试添加事件监听器
+	var callback_called := false
+	var test_callback := func(data: Dictionary):
+		callback_called = true
+
+	socket_client.add_event_listener("test_event", test_callback)
+
+	assert_true(socket_client._event_listeners.has("test_event"),
+		"事件监听器应该被添加")
+	assert_eq(socket_client._event_listeners["test_event"].size(), 1,
+		"应该有 1 个监听器")
+
+func test_add_multiple_event_listeners():
+	# 测试添加多个监听器到同一事件
+	var callback1 := func(data: Dictionary): pass
+	var callback2 := func(data: Dictionary): pass
+
+	socket_client.add_event_listener("test_event", callback1)
+	socket_client.add_event_listener("test_event", callback2)
+
+	assert_eq(socket_client._event_listeners["test_event"].size(), 2,
+		"应该有 2 个监听器")
+
+func test_remove_event_listener():
+	# 测试移除事件监听器
+	var callback := func(data: Dictionary): pass
+
+	socket_client.add_event_listener("test_event", callback)
+	assert_eq(socket_client._event_listeners["test_event"].size(), 1,
+		"监听器应该被添加")
+
+	socket_client.remove_event_listener("test_event", callback)
+	assert_eq(socket_client._event_listeners["test_event"].size(), 0,
+		"监听器应该被移除")
+
+func test_remove_nonexistent_event_listener():
+	# 测试移除不存在的监听器不应该报错
+	var callback := func(data: Dictionary): pass
+
+	socket_client.remove_event_listener("nonexistent_event", callback)
+	# 如果没有报错，测试通过
+	assert_true(true, "移除不存在的监听器不应该报错")
+
+# ============================================================================
+# 消息格式化测试（模拟）
+# ============================================================================
+
+func test_message_data_structure():
+	# 测试消息数据结构
+	var message_data := {
+		"t": "chat",
+		"content": "Hello, world!",
+		"scope": "local"
+	}
+
+	# 验证数据结构
+	assert_true(message_data.has("t"), "消息应该有 't' 字段")
+	assert_eq(message_data["t"], "chat", "事件类型应该是 'chat'")
+	assert_eq(message_data["content"], "Hello, world!", "内容应该匹配")
+	assert_eq(message_data["scope"], "local", "范围应该是 'local'")
+
+func test_login_message_structure():
+	# 测试登录消息数据结构
+	var login_data := {
+		"type": "login",
+		"token": "test_token_123"
+	}
+
+	# 验证数据结构
+	assert_true(login_data.has("type"), "登录消息应该有 'type' 字段")
+	assert_eq(login_data["type"], "login", "类型应该是 'login'")
+	assert_eq(login_data["token"], "test_token_123", "token 应该匹配")
+
+func test_error_message_structure():
+	# 测试错误消息数据结构
+	var error_data := {
+		"t": "error",
+		"code": "AUTH_FAILED",
+		"message": "认证失败"
+	}
+
+	# 验证数据结构
+	assert_eq(error_data["t"], "error", "事件类型应该是 'error'")
+	assert_eq(error_data["code"], "AUTH_FAILED", "错误码应该匹配")
+	assert_eq(error_data["message"], "认证失败", "错误消息应该匹配")
+
+# ============================================================================
+# JSON 序列化测试
+# ============================================================================
+
+func test_json_serialization():
+	# 测试 JSON 序列化
+	var data := {
+		"t": "chat",
+		"content": "Test message",
+		"scope": "local"
+	}
+
+	var json_string := JSON.stringify(data)
+	var json := JSON.new()
+	var result := json.parse(json_string)
+
+	assert_eq(result, OK, "JSON 序列化应该成功")
+	assert_true(json.data.has("t"), "解析后的数据应该有 't' 字段")
+	assert_eq(json.data["content"], "Test message", "内容应该匹配")
+
+func test_json_serialization_with_unicode():
+	# 测试包含 Unicode 字符的 JSON 序列化
+	var data := {
+		"t": "chat",
+		"content": "你好，世界！🎮",
+		"scope": "local"
+	}
+
+	var json_string := JSON.stringify(data)
+	var json := JSON.new()
+	var result := json.parse(json_string)
+
+	assert_eq(result, OK, "Unicode JSON 序列化应该成功")
+	assert_eq(json.data["content"], "你好，世界！🎮", "Unicode 内容应该匹配")
+
+# ============================================================================
+# 信号测试
+# ============================================================================
+
+func test_connected_signal():
+	# 测试连接成功信号
+	watch_signals(socket_client)
+
+	# 手动触发信号
+	socket_client.emit_signal("connected")
+
+	assert_signal_emitted(socket_client, "connected",
+		"应该发射 connected 信号")
+
+func test_disconnected_signal():
+	# 测试断开连接信号
+	watch_signals(socket_client)
+
+	# 手动触发信号
+	socket_client.emit_signal("disconnected", true)
+
+	assert_signal_emitted(socket_client, "disconnected",
+		"应该发射 disconnected 信号")
+
+func test_event_received_signal():
+	# 测试事件接收信号
+	watch_signals(socket_client)
+
+	var test_data := {"t": "test", "value": 123}
+	socket_client.emit_signal("event_received", "test", test_data)
+
+	assert_signal_emitted(socket_client, "event_received",
+		"应该发射 event_received 信号")
+
+func test_error_occurred_signal():
+	# 测试错误发生信号
+	watch_signals(socket_client)
+
+	socket_client.emit_signal("error_occurred", "Test error")
+
+	assert_signal_emitted(socket_client, "error_occurred",
+		"应该发射 error_occurred 信号")
+
+# ============================================================================
+# 边界条件测试
+# ============================================================================
+
+func test_empty_message_content():
+	# 测试空消息内容
+	var data := {
+		"t": "chat",
+		"content": "",
+		"scope": "local"
+	}
+
+	assert_eq(data["content"], "", "空内容应该被保留")
+
+func test_very_long_message_content():
+	# 测试超长消息内容（边界测试）
+	var long_content := "x".repeat(1000)
+	var data := {
+		"t": "chat",
+		"content": long_content,
+		"scope": "local"
+	}
+
+	assert_eq(data["content"].length(), 1000, "超长内容应该被保留")
+
+func test_special_characters_in_message():
+	# 测试特殊字符
+	var data := {
+		"t": "chat",
+		"content": "Test with \"quotes\" and 'apostrophes'\n\tNew lines and tabs",
+		"scope": "local"
+	}
+
+	var json_string := JSON.stringify(data)
+	var json := JSON.new()
+	var result := json.parse(json_string)
+
+	assert_eq(result, OK, "特殊字符 JSON 序列化应该成功")
+	assert_true(json.data["content"].contains("\n"), "换行符应该被保留")

tests/unit/test_socketio_client.gd.uid

@@ -0,0 +1 @@
+uid://bl4hh8shkwr23

tests/unit/test_websocket_manager.gd

@@ -0,0 +1,271 @@
+extends GutTest
+
+# ============================================================================
+# test_websocket_manager.gd - WebSocketManager 单元测试
+# ============================================================================
+# 测试 WebSocket 连接管理的功能
+#
+# 测试覆盖:
+# - 初始化测试
+# - 连接状态管理
+# - 重连机制
+# - Socket.IO 客户端访问
+# - 信号发射
+# ============================================================================
+
+var ws_manager: WebSocketManager
+
+# ============================================================================
+# 测试设置和清理
+# ============================================================================
+
+func before_each():
+	# 每个测试前创建新实例
+	ws_manager = WebSocketManager.new()
+	add_child(ws_manager)
+
+func after_each():
+	# 每个测试后清理
+	if is_instance_valid(ws_manager):
+		ws_manager.queue_free()
+		ws_manager = null
+
+# ============================================================================
+# 初始化测试
+# ============================================================================
+
+func test_websocket_manager_initialization():
+	# 测试管理器初始化
+	assert_not_null(ws_manager, "WebSocketManager 应该成功初始化")
+	assert_not_null(ws_manager._socket_client, "Socket.IO 客户端应该被创建")
+	assert_eq(ws_manager.is_connected(), false, "初始状态应该是未连接")
+
+func test_initial_connection_state():
+	# 测试初始连接状态
+	assert_eq(ws_manager.get_connection_state(),
+		WebSocketManager.ConnectionState.DISCONNECTED,
+		"初始连接状态应该是 DISCONNECTED")
+
+# ============================================================================
+# 连接状态测试
+# ============================================================================
+
+func test_connection_state_enum():
+	# 测试连接状态枚举值
+	assert_eq(WebSocketManager.ConnectionState.DISCONNECTED, 0,
+		"DISCONNECTED 应该是 0")
+	assert_eq(WebSocketManager.ConnectionState.CONNECTING, 1,
+		"CONNECTING 应该是 1")
+	assert_eq(WebSocketManager.ConnectionState.CONNECTED, 2,
+		"CONNECTED 应该是 2")
+	assert_eq(WebSocketManager.ConnectionState.RECONNECTING, 3,
+		"RECONNECTING 应该是 3")
+	assert_eq(WebSocketManager.ConnectionState.ERROR, 4,
+		"ERROR 应该是 4")
+
+func test_get_state_description():
+	# 测试状态描述方法
+	ws_manager._connection_state = WebSocketManager.ConnectionState.DISCONNECTED
+	var desc := ws_manager.get_state_description()
+	assert_eq(desc, "未连接", "DISCONNECTED 状态描述应该是 '未连接'")
+
+	ws_manager._connection_state = WebSocketManager.ConnectionState.CONNECTED
+	desc = ws_manager.get_state_description()
+	assert_eq(desc, "已连接", "CONNECTED 状态描述应该是 '已连接'")
+
+	ws_manager._connection_state = WebSocketManager.ConnectionState.CONNECTING
+	desc = ws_manager.get_state_description()
+	assert_eq(desc, "连接中", "CONNECTING 状态描述应该是 '连接中'")
+
+# ============================================================================
+# 自动重连配置测试
+# ============================================================================
+
+func test_enable_auto_reconnect():
+	# 测试启用自动重连
+	ws_manager.enable_auto_reconnect(true, 5, 3.0)
+
+	assert_true(ws_manager._auto_reconnect_enabled, "自动重连应该被启用")
+	assert_eq(ws_manager._max_reconnect_attempts, 5, "最大重连次数应该是 5")
+	assert_eq(ws_manager._reconnect_base_delay, 3.0, "基础重连延迟应该是 3.0 秒")
+
+func test_disable_auto_reconnect():
+	# 测试禁用自动重连
+	ws_manager.enable_auto_reconnect(false)
+
+	assert_false(ws_manager._auto_reconnect_enabled, "自动重连应该被禁用")
+
+func test_get_reconnect_info():
+	# 测试获取重连信息
+	ws_manager.enable_auto_reconnect(true, 5, 3.0)
+	ws_manager._reconnect_attempt = 2
+
+	var info := ws_manager.get_reconnect_info()
+
+	assert_true(info.has("enabled"), "重连信息应该包含 'enabled'")
+	assert_true(info.has("attempt"), "重连信息应该包含 'attempt'")
+	assert_true(info.has("max_attempts"), "重连信息应该包含 'max_attempts'")
+	assert_true(info.has("next_delay"), "重连信息应该包含 'next_delay'")
+
+	assert_eq(info["enabled"], true, "自动重连应该启用")
+	assert_eq(info["attempt"], 2, "当前重连尝试次数应该是 2")
+	assert_eq(info["max_attempts"], 5, "最大重连次数应该是 5")
+
+# ============================================================================
+# 重连延迟计算测试
+# ============================================================================
+
+func test_reconnect_delay_calculation():
+	# 测试重连延迟计算（指数退避）
+	ws_manager._reconnect_base_delay = 2.0
+
+	ws_manager._reconnect_attempt = 1
+	var delay1 := ws_manager._calculate_reconnect_delay()
+	assert_eq(delay1, 2.0, "第 1 次重连延迟应该是 2.0 秒")
+
+	ws_manager._reconnect_attempt = 2
+	var delay2 := ws_manager._calculate_reconnect_delay()
+	assert_eq(delay2, 4.0, "第 2 次重连延迟应该是 4.0 秒")
+
+	ws_manager._reconnect_attempt = 3
+	var delay3 := ws_manager._calculate_reconnect_delay()
+	assert_eq(delay3, 8.0, "第 3 次重连延迟应该是 8.0 秒")
+
+func test_max_reconnect_delay():
+	# 测试最大重连延迟限制
+	ws_manager._reconnect_base_delay = 10.0
+	ws_manager._reconnect_attempt = 10
+
+	var delay := ws_manager._calculate_reconnect_delay()
+	assert_eq(delay, WebSocketManager.MAX_RECONNECT_DELAY,
+		"重连延迟应该被限制在最大值")
+
+# ============================================================================
+# Socket.IO 客户端访问测试
+# ============================================================================
+
+func test_get_socket_client():
+	# 测试获取 Socket.IO 客户端
+	var socket_client := ws_manager.get_socket_client()
+
+	assert_not_null(socket_client, "应该返回 Socket.IO 客户端")
+	assert_is_instanceof(socket_client, SocketIOClient,
+		"返回的应该是 SocketIOClient 实例")
+
+# ============================================================================
+# 信号测试
+# ============================================================================
+
+func test_connection_state_changed_signal():
+	# 测试连接状态变化信号
+	watch_signals(ws_manager)
+
+	# 手动触发信号
+	ws_manager.emit_signal("connection_state_changed", WebSocketManager.ConnectionState.CONNECTED)
+
+	assert_signal_emitted(ws_manager, "connection_state_changed",
+		"应该发射 connection_state_changed 信号")
+
+func test_connection_lost_signal():
+	# 测试连接丢失信号
+	watch_signals(ws_manager)
+
+	ws_manager.emit_signal("connection_lost")
+
+	assert_signal_emitted(ws_manager, "connection_lost",
+		"应该发射 connection_lost 信号")
+
+func test_reconnection_succeeded_signal():
+	# 测试重连成功信号
+	watch_signals(ws_manager)
+
+	ws_manager.emit_signal("reconnection_succeeded")
+
+	assert_signal_emitted(ws_manager, "reconnection_succeeded",
+		"应该发射 reconnection_succeeded 信号")
+
+func test_reconnection_failed_signal():
+	# 测试重连失败信号
+	watch_signals(ws_manager)
+
+	ws_manager.emit_signal("reconnection_failed", 3, 5)
+
+	assert_signal_emitted(ws_manager, "reconnection_failed",
+		"应该发射 reconnection_failed 信号")
+
+# ============================================================================
+# 常量测试
+# ============================================================================
+
+func test_websocket_url_constant():
+	# 测试 WebSocket URL 常量
+	assert_eq(WebSocketManager.WEBSOCKET_URL, "wss://whaletownend.xinghangee.icu/game",
+		"WebSocket URL 应该匹配")
+
+func test_default_reconnect_constants():
+	# 测试默认重连常量
+	assert_eq(WebSocketManager.DEFAULT_MAX_RECONNECT_ATTEMPTS, 5,
+		"默认最大重连次数应该是 5")
+	assert_eq(WebSocketManager.DEFAULT_RECONNECT_BASE_DELAY, 3.0,
+		"默认基础重连延迟应该是 3.0 秒")
+
+func test_max_reconnect_delay_constant():
+	# 测试最大重连延迟常量
+	assert_eq(WebSocketManager.MAX_RECONNECT_DELAY, 30.0,
+		"最大重连延迟应该是 30.0 秒")
+
+# ============================================================================
+# 边界条件测试
+# ============================================================================
+
+func test_zero_max_reconnect_attempts():
+	# 测试零次重连尝试
+	ws_manager.enable_auto_reconnect(true, 0, 1.0)
+	ws_manager._reconnect_attempt = 1
+
+	var should_reconnect := ws_manager._reconnect_attempt < ws_manager._max_reconnect_attempts
+	assert_false(should_reconnect, "最大重连次数为 0 时不应该重连")
+
+func test_very_large_reconnect_attempts():
+	# 测试非常大的重连次数
+	ws_manager.enable_auto_reconnect(true, 1000, 1.0)
+	ws_manager._reconnect_attempt = 999
+
+	var should_reconnect := ws_manager._reconnect_attempt < ws_manager._max_reconnect_attempts
+	assert_true(should_reconnect, "应该允许更多重连尝试")
+
+func test_zero_base_delay():
+	# 测试零基础延迟
+	ws_manager._reconnect_base_delay = 0.0
+	ws_manager._reconnect_attempt = 1
+
+	var delay := ws_manager._calculate_reconnect_delay()
+	# 即使基础延迟为 0，也应该返回一个合理的值
+	assert_ge(delay, 0.0, "延迟应该 >= 0")
+
+# ============================================================================
+# 状态转换测试
+# ============================================================================
+
+func test_state_disconnected_to_connecting():
+	# 测试从 DISCONNECTED 到 CONNECTING 的状态转换
+	ws_manager._set_connection_state(WebSocketManager.ConnectionState.CONNECTING)
+
+	assert_eq(ws_manager.get_connection_state(), WebSocketManager.ConnectionState.CONNECTING,
+		"状态应该转换为 CONNECTING")
+
+func test_state_connecting_to_connected():
+	# 测试从 CONNECTING 到 CONNECTED 的状态转换
+	ws_manager._set_connection_state(WebSocketManager.ConnectionState.CONNECTING)
+	ws_manager._set_connection_state(WebSocketManager.ConnectionState.CONNECTED)
+
+	assert_eq(ws_manager.get_connection_state(), WebSocketManager.ConnectionState.CONNECTED,
+		"状态应该转换为 CONNECTED")
+
+func test_state_connected_to_reconnecting():
+	# 测试从 CONNECTED 到 RECONNECTING 的状态转换
+	ws_manager._set_connection_state(WebSocketManager.ConnectionState.CONNECTED)
+	ws_manager._set_connection_state(WebSocketManager.ConnectionState.RECONNECTING)
+
+	assert_eq(ws_manager.get_connection_state(), WebSocketManager.ConnectionState.RECONNECTING,
+		"状态应该转换为 RECONNECTING")

tests/unit/test_websocket_manager.gd.uid

@@ -0,0 +1 @@
+uid://btx366t1aqprm