1
Future<void> connect() async {
2
  // ① 防止重复连接
3
  if (_status == WsStatus.connected || _status == WsStatus.connecting) return;
4

5
  // ② 等待本地 Token 读取完成（Completer 门控，Ch7 学的）
6
  await _authInitCompleter.future;
7

8
  _setStatus(WsStatus.connecting);
9

10
  try {
11
    // ③ 建立 WebSocket 连接
12
    _channel = WebSocketChannel.connect(Uri.parse(_serverUrl));
13
    await _channel!.ready;
14
    //               ^^^^^
15
    //   等待底层 TCP 握手完成
16

17
    // ④ 开始监听 Stream（Ch8 学的）
18
    _sub = _channel!.stream.listen(
19
      _onData,          // 收到消息
20
      onError: _onError, // 连接异常
21
      onDone: _onDone,   // 连接关闭
22
    );
23

24
    _setStatus(WsStatus.connected);
25

26
    // ⑤ 发送握手 + 自动恢复登录 + 启动心跳
27
    _sendHandshake();
28
    if (_token != null) {
29
      restoreAuth();      // 有 Token → 自动恢复会话
30
    }
31
    _startPing();
32
  } catch (e) {
33
    debugPrint('[WS] 连接失败: $e');
34
    _setStatus(WsStatus.disconnected);
35
    _scheduleReconnect();  // 连接失败 → 安排重连
36
  }
37
}

1
WebSocket 收到 raw JSON
2
       │
3
       ↓ jsonDecode()
4
  Map<String, dynamic> data
5
       │
6
       ↓ switch (data['type'])
7
       │
8
       ├── 直接处理型（内部 handle 方法 → notifyListeners → UI 更新）
9
       │   ├── CHAT_RESPONSE → _handleChatResponse()
10
       │   ├── CHAT_STREAM_CHUNK → _handleChatStreamChunk()
11
       │   ├── AUTH_RESPONSE → _handleAuthResponse()
12
       │   ├── HISTORY_RESPONSE → _handleHistoryResponse()
13
       │   └── PERSONA_LIST → _handlePersonaList()
14
       │
15
       ├── Stream 广播型（放入 StreamController → UI 组件各自监听）
16
       │   ├── AUTH_REQUIRED → _authRequestController.add()
17
       │   ├── MCP_* → _mcpConfigController.add()
18
       │   └── PERSONA_* → _personaController.add()
19
       │
20
       └── Completer 唤醒型（按 message_id 找到 Completer → complete）
21
            └── FILE_UPLOAD_ACK/ERROR → _handlePendingResponse()

1
void _handleChatStreamChunk(Map<String, dynamic> data) {
2
  final payload = data['payload'] as Map<String, dynamic>? ?? {};
3
  final chunk = payload['chunk'] as String? ?? '';
4
  final finished = payload['finished'] == true;
5
  final msgId = data['message_id'] as String? ?? _genId();
6
  final assistantId = _assistantMsgId(msgId);
7

8
  // ① 结束帧：只负责状态收口
9
  if (finished) {
10
    _streamingMsgIds.add(msgId);
11
    _isGenerating = false;
12
    notifyListeners();
13
    return;
14
  }
15

16
  if (chunk.isEmpty) return;
17

18
  // ② 第一块到达：移除 "正在输入..." 占位
19
  _streamingMsgIds.add(msgId);
20
  _messages.removeWhere((m) => m.isTyping);
21

22
  // ③ 查找已有消息
23
  final existingIndex = _messages.indexWhere(
24
    (m) => m.id == assistantId && m.sender == MessageSender.ai,
25
  );
26

27
  if (existingIndex == -1) {
28
    // ④ 第一块：创建新消息
29
    _messages.add(ChatMessage(
30
      id: assistantId,
31
      content: chunk,
32
      sender: MessageSender.ai,
33
      time: DateTime.now(),
34
    ));
35
  } else {
36
    // ⑤ 后续块：追加内容（使用 copyWith，Ch4 学的）
37
    final existing = _messages[existingIndex];
38
    _messages[existingIndex] = existing.copyWith(
39
      content: _mergeAssistantContent(existing.content, chunk),
40
      isTyping: false,
41
    );
42
  }
43

44
  notifyListeners();   // ← 每个 chunk 都通知 UI 更新
45
}

1
String _mergeAssistantContent(String existing, String incoming) {
2
  if (incoming.isEmpty) return existing;
3
  if (existing.isEmpty) return incoming;
4
  if (existing.endsWith(incoming)) return existing;  // ← 完全重复，跳过
5

6
  // 找到最大重叠部分（避免重复拼接）
7
  final maxOverlap = min(existing.length, incoming.length);
8
  for (var overlap = maxOverlap; overlap > 0; overlap--) {
9
    if (existing.endsWith(incoming.substring(0, overlap))) {
10
      return existing + incoming.substring(overlap);
11
      //                         ^^^^^^^^^^^^^^^^
12
      //              只拼接不重叠的部分
13
    }
14
  }
15
  return existing + incoming;   // ← 没有重叠，直接拼接
16
}

1
// 存储等待中的请求
2
final Map<String, Completer<Map<String, dynamic>>> _pendingResponses = {};
3

4
Future<Map<String, dynamic>> _sendAndAwaitResponse(
5
  String type,
6
  Map<String, dynamic> payload, {
7
  Duration timeout = const Duration(seconds: 30),
8
}) async {
9
  if (_status != WsStatus.connected) {
10
    throw Exception('WebSocket 未连接');
11
  }
12

13
  // ① 生成唯一 ID
14
  final msgId = '${_genId()}_${DateTime.now().microsecondsSinceEpoch}';
15

16
  // ② 创建 Completer 并存入 Map
17
  final completer = Completer<Map<String, dynamic>>();
18
  _pendingResponses[msgId] = completer;
19

20
  // ③ 发送请求
21
  _send({
22
    'message_id': msgId,
23
    'type': type,
24
    'source': 'client',
25
    'target': 'host',
26
    'timestamp': DateTime.now().millisecondsSinceEpoch,
27
    'payload': payload,
28
  });
29

30
  // ④ 等待响应（带超时）
31
  try {
32
    return await completer.future.timeout(timeout);
33
  } on TimeoutException {
34
    _pendingResponses.remove(msgId);   // ← 超时清理
35
    throw Exception('$type 请求超时');
36
  }
37
}

1
调用端                         WsService 内部                Host
2
  │                                │                          │
3
  │ _sendAndAwaitResponse()        │                          │
4
  │──→ 创建 Completer              │                          │
5
  │    _pendingResponses[id]=c    │                          │
6
  │──→ _send({id, type, ...})     │──→ WebSocket ──→         │
7
  │                               │                          │
8
  │    await completer.future     │    (等待中...)            │
9
  │    ┊                          │                          │
10
  │    ┊                          │←── WebSocket ←──         │
11
  │    ┊                          │  _onData()               │
12
  │    ┊                          │  → _handlePendingResponse│
13
  │    ┊                          │  → completer.complete()  │
14
  │    ┊                          │                          │
15
  │←── 返回 data                  │                          │

1
Future<Map<String, dynamic>> uploadFile(
2
  String filePath, {
3
  void Function(double progress)? onProgress,
4
}) async {
5
  final file = File(filePath);
6
  if (!await file.exists()) throw Exception('文件不存在');
7

8
  final bytes = await file.readAsBytes();
9
  final sha256Hex = sha256.convert(bytes).toString();  // ← SHA256 校验
10

11
  // ① 初始化上传（拿到 upload_id）
12
  final initResp = await _sendAndAwaitResponse('FILE_UPLOAD_INIT', {
13
    'file_name': fileName,
14
    'mime_type': mimeType,
15
    'size_bytes': bytes.length,
16
    'sha256': sha256Hex,
17
  });
18

19
  final uploadId = initResp['payload']['upload_id'] as String;
20

21
  // ② 分片上传
22
  final totalChunks = (bytes.length / _uploadChunkSize).ceil();
23
  onProgress?.call(0);
24

25
  for (var index = 0; index < totalChunks; index++) {
26
    final start = index * _uploadChunkSize;
27
    final end = min(bytes.length, start + _uploadChunkSize);
28
    final chunk = bytes.sublist(start, end);
29

30
    await _sendAndAwaitResponse('FILE_UPLOAD_CHUNK', {
31
      'upload_id': uploadId,
32
      'chunk_index': index,
33
      'total_chunks': totalChunks,
34
      'chunk_base64': base64Encode(chunk),    // ← Base64 编码二进制
35
    }, timeout: const Duration(seconds: 60));
36

37
    onProgress?.call((index + 1) / totalChunks);
38
    //               ^^^^^^^^^^^^^^^^^^^^^^^^
39
    //         进度回调：0.0 → 1.0
40
  }
41
}

1
// 登录
2
void login(String username, String password) {
3
  _send({
4
    'type': 'AUTH_REQUEST',
5
    'payload': {
6
      'action': 'login',
7
      'username': username,
8
      'password': password,
9
    },
10
  });
11
}
12

13
// 自动恢复会话
14
void restoreAuth() {
15
  isRestoringAuth = true;
16
  notifyListeners();
17
  _send({
18
    'type': 'AUTH_RESTORE',
19
    'payload': {'token': _token},
20
  });
21
}

1
Future<void> _handleAuthResponse(Map<String, dynamic> data) async {
2
  final payload = data['payload'] as Map<String, dynamic>? ?? {};
3
  final status = payload['status'] as String?;
4
  final wasRestoring = isRestoringAuth;
5
  isRestoringAuth = false;
6

7
  if (status == 'success') {
8
    // ① 保存 Token
9
    _token = payload['token'] as String?;
10
    _user = payload['user'] as Map<String, dynamic>?;
11
    if (_token != null) {
12
      final prefs = await SharedPreferences.getInstance();
13
      await prefs.setString('auth_token', _token!);
14
    }
15

16
    // ② 恢复登录时延迟，避免 UI 闪烁
17
    if (wasRestoring) {
18
      await Future.delayed(const Duration(milliseconds: 1000));
19
    }
20

21
    // ③ 设置认证状态，触发页面切换
22
    _isAuthenticated = true;
23
    _pendingInitialHistoryAfterPersonaList = true;
24
    requestPersonaList();      // ← 先拿人格列表
25
    notifyListeners();         // ← AuthWrapper watch 到变化 → 切换到 ChatScreen
26
  } else {
27
    await logout();            // ← 失败就清除 Token
28
  }
29
}

1
void _scheduleReconnect() {
2
  _reconnectTimer?.cancel();
3
  _reconnectTimer = Timer(_reconnectDelay, () {
4
    //                      ^^^^^^^^^^^^^^
5
    //                   3 秒后重连
6
    if (_status == WsStatus.disconnected && !_disposed) {
7
      unawaited(connect());
8
    }
9
  });
10
}
11

12
void _onError(dynamic error) {
13
  debugPrint('[WS] 连接异常: $error');
14
  _setStatus(WsStatus.disconnected);
15
  _scheduleReconnect();             // ← 出错就重连
16
}
17

18
void _onDone() {
19
  debugPrint('[WS] 连接关闭');
20
  _setStatus(WsStatus.disconnected);
21
  _scheduleReconnect();             // ← 关闭也重连
22
}

1
void sendMessage(String text, {List<Map<String, dynamic>> attachments = const []}) {
2
  final normalized = text.trim();
3
  if (_status != WsStatus.connected) return;        // ← 未连接，忽略
4
  if (normalized.isEmpty && attachments.isEmpty) return;  // ← 空消息，忽略
5

6
  final requestId = _genId();
7
  final now = DateTime.now();
8

9
  // ① 创建本地消息（乐观 UI）
10
  if (normalized.isNotEmpty) {
11
    _messages.add(ChatMessage(
12
      id: requestId,
13
      content: normalized,
14
      sender: MessageSender.me,
15
      time: now,
16
    ));
17
  }
18

19
  // ② 添加"正在输入"占位
20
  _messages.add(ChatMessage(
21
    id: '${requestId}_typing',
22
    content: '',
23
    sender: MessageSender.ai,
24
    time: now,
25
    isTyping: true,            // ← 特殊标记
26
  ));
27
  _isGenerating = true;
28
  notifyListeners();            // ← 立刻更新 UI
29

30
  // ③ 发送到 Host
31
  _send({
32
    'message_id': requestId,
33
    'type': 'CHAT_REQUEST',
34
    'source': 'client',
35
    'target': 'host',
36
    'timestamp': DateTime.now().millisecondsSinceEpoch,
37
    'payload': {
38
      'content': normalized,
39
      'context_id': 'default',
40
      'persona_id': _activePersonaId,
41
      'attachments': attachments,
42
    },
43
  });
44
}