1
client/lib/
2
├── main.dart                        # 应用入口、Provider 注册、窗口/托盘管理
3
├── models/
4
│   └── message.dart                 # 数据模型（ChatMessage + copyWith）
5
├── screens/
6
│   ├── auth_screen.dart             # 登录/注册页面
7
│   ├── bootstrap_screen.dart        # 启动引导页面
8
│   ├── chat_screen.dart             # 聊天主界面（3000+ 行，最大文件）
9
│   ├── mcp_settings_screen.dart     # MCP 扩展设置页面
10
│   └── components/
11
│       └── approval_dialog.dart     # 审批对话框组件
12
├── services/
13
│   ├── app_settings.dart            # 应用设置（字体、关闭行为、连接模式）
14
│   ├── bootstrap_service.dart       # 启动流程编排（进程管理、环境检测）
15
│   └── ws_service.dart              # WebSocket 通信（认证、消息、文件上传）
16
└── theme/
17
    └── app_theme.dart               # 主题系统（明暗主题 + LumiColors 扩展）

1
┌──────────────────────────────────────────────────────┐
2
│                    表现层 (Screens)                    │
3
│  auth_screen │ bootstrap_screen │ chat_screen │ mcp  │
4
│                                                      │
5
│  StatefulWidget + State + build()                     │
6
│  context.watch / context.read                        │
7
│  Navigator.push / pop / showDialog                   │
8
├──────────────────────────────────────────────────────┤
9
│                    状态层 (Services)                   │
10
│  AppSettings    │ WsService    │ BootstrapService     │
11
│                                                      │
12
│  extends ChangeNotifier                              │
13
│  notifyListeners() → UI 自动重建                      │
14
│  Stream / Completer → 异步通信管道                    │
15
├──────────────────────────────────────────────────────┤
16
│                    数据层 (Models)                     │
17
│  ChatMessage │ WsStatus │ BootstrapStage │ Enums     │
18
│                                                      │
19
│  不可变数据类 + copyWith                              │
20
│  enum + switch exhaustive                            │
21
├──────────────────────────────────────────────────────┤
22
│                    基础设施层                          │
23
│  dart:io (File/Process/Platform)                     │
24
│  WebSocketChannel │ SharedPreferences                │
25
│  window_manager │ tray_manager                       │
26
└──────────────────────────────────────────────────────┘

1
用户在输入框打字 → TextEditingController
2
     │
3
     ↓ 按下发送
4
_ChatScreenState._submit()
5
     │
6
     ↓ context.read<WsService>()
7
WsService.sendMessage(text)
8
     │
9
     ├──→ ① _messages.add(我的消息)         [乐观 UI]
10
     ├──→ ② _messages.add(typing 占位)      [打字指示器]
11
     ├──→ ③ notifyListeners()               [UI 立即更新]
12
     └──→ ④ _send({type: CHAT_REQUEST})     [WebSocket 发送]
13
              │
14
              ↓ (网络)
15
         Host 处理中...
16
              │
17
              ↓ CHAT_STREAM_CHUNK
18
         WsService._onData()
19
              │
20
              ↓ _handleChatStreamChunk()
21
     ├──→ 移除 typing 占位
22
     ├──→ 拼接 chunk 到消息
23
     └──→ notifyListeners()                 [UI 逐字更新]
24
              │
25
              ↓ CHAT_RESPONSE（最终完整内容）
26
         _handleChatResponse()
27
              │
28
              ↓ notifyListeners()
29
         ChatScreen.build() 重新执行
30
              │
31
              ↓ context.watch<WsService>()
32
         ws.messages → ListView.builder
33
              │
34
              ↓
35
         用户看到完整的 AI 回复 ✨

1
                 ┌──────────────┐
2
                 │  AppSettings  │
3
                 │ (设置持久化)   │
4
                 └──────┬───────┘
5
                        │
6
            ┌───────────┼───────────┐
7
            ↓                       ↓
8
   ┌────────────────┐     ┌─────────────────┐
9
   │   WsService     │     │ BootstrapService │
10
   │ (WebSocket 通信) │────→│  (启动编排)      │
11
   └────────┬───────┘     └────────┬────────┘
12
            │                      │
13
            │    依赖 WsService    │
14
            │    依赖 AppSettings  │
15
            │                      │
16
   ┌────────┴──────────────────────┴──────┐
17
   │             Provider 层              │
18
   │  MultiProvider 在 main.dart 注册     │
19
   │  ChangeNotifierProxyProvider2 处理   │
20
   │  服务间依赖                          │
21
   └──────────────────────────────────────┘
22
            │
23
            ↓ context.watch / context.read
24
   ┌──────────────────────────────────────┐
25
   │             Screen 层                │
26
   │  AuthWrapper → AuthScreen            │
27
   │              → BootstrapScreen       │
28
   │              → ChatScreen            │
29
   │                 └→ McpSettingsScreen  │
30
   └──────────────────────────────────────┘

1
enum MessageSender { me, ai }
2

3
class ChatMessage {
4
  final String id;
5
  final String content;
6
  final MessageSender sender;
7
  final DateTime time;
8
  final bool isTyping;
9
  final bool isSelected;
10
  final Map<String, dynamic>? extra;
11

12
  ChatMessage({
13
    required this.id,
14
    required this.content,
15
    required this.sender,
16
    required this.time,
17
    this.isTyping = false,
18
    this.isSelected = false,
19
    this.extra,
20
  });
21

22
  ChatMessage copyWith({
23
    String? content,
24
    bool? isTyping,
25
    bool? isSelected,
26
    Map<String, dynamic>? extra,
27
  }) {
28
    return ChatMessage(
29
      id: id,                             // ← 不变的字段
30
      content: content ?? this.content,   // ← 可选覆盖
31
      sender: sender,
32
      time: time,
33
      isTyping: isTyping ?? this.isTyping,
34
      isSelected: isSelected ?? this.isSelected,
35
      extra: extra ?? this.extra,
36
    );
37
  }
38
}

1
  第一部分：Dart 语言基础 ─────────────────────────────
2
  ┌──────┐ ┌──────────┐ ┌──────┐ ┌─────┐ ┌──────┐ ┌──────┐
3
  │Ch 1  │→│ Ch 2     │→│Ch 3  │→│Ch 4 │→│Ch 5  │→│Ch 6  │
4
  │入门  │ │集合&控制 │ │函数  │ │OOP  │ │枚举  │ │错误  │
5
  │null  │ │Map/List  │ │闭包  │ │Mixin│ │模式  │ │处理  │
6
  │安全  │ │函数式   │ │级联  │ │copy │ │匹配  │ │策略  │
7
  └──────┘ └──────────┘ └──────┘ └─────┘ └──────┘ └──────┘
8

9
  第二部分：Dart 进阶特性 ─────────────────────────────
10
  ┌──────┐ ┌──────┐ ┌──────────┐
11
  │Ch 7  │→│Ch 8  │→│ Ch 9     │
12
  │异步  │ │Stream│ │ 泛型     │
13
  │await │ │广播流│ │ Extension│
14
  │Comp- │ │订阅  │ │ Theme-   │
15
  │leter │ │关闭  │ │ Extension│
16
  └──────┘ └──────┘ └──────────┘
17

18
  第三部分：Flutter 框架 ──────────────────────────────
19
  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
20
  │Ch 10 │→│Ch 11 │→│Ch 12 │→│Ch 13 │
21
  │Widget│ │布局  │ │状态  │ │导航  │
22
  │State │ │Row   │ │管理  │ │主题  │
23
  │生命  │ │Column│ │Provi │ │Theme │
24
  │周期  │ │响应式│ │der   │ │Data  │
25
  └──────┘ └──────┘ └──────┘ └──────┘
26

27
  第四部分：工程实战 ──────────────────────────────────
28
  ┌──────┐ ┌──────┐ ┌──────┐
29
  │Ch 14 │→│Ch 15 │→│Ch 16 │  ← 你在这里 🎯
30
  │平台  │ │Web-  │ │架构  │
31
  │集成  │ │Socket│ │总览  │
32
  │窗口  │ │协议  │ │知识  │
33
  │进程  │ │流式  │ │地图  │
34
  └──────┘ └──────┘ └──────┘

1
                    你学了什么
2
                    ──────────
3

4
   ✅ Dart 语言核心
5
      变量、空安全、集合、函数、闭包、级联
6
      类、构造函数、Mixin、copyWith
7
      枚举、模式匹配、Sealed Classes、Records
8
      异常处理、五种防御策略
9

10
   ✅ Dart 异步体系
11
      事件循环、async/await、Future
12
      Completer（请求-响应/门控）
13
      Stream、StreamController（广播/订阅）
14
      Timer、Stopwatch
15

16
   ✅ 泛型与扩展
17
      泛型类/函数/约束/CRTP
18
      Extension methods
19
      ThemeExtension
20

21
   ✅ Flutter 框架
22
      Widget 树、三棵树架构
23
      StatelessWidget / StatefulWidget
24
      State 生命周期（initState → dispose）
25
      布局系统（Row/Column/Expanded/Scaffold）
26
      状态管理（Provider + ChangeNotifier）
27
      导航（Navigator + 状态驱动）
28
      主题（ThemeData + ColorScheme + ThemeExtension）
29

30
   ✅ 工程实战
31
      窗口管理（window_manager）
32
      系统托盘（tray_manager）
33
      进程管理（Process.run / Process.start）
34
      文件 I/O（File / Directory）
35
      WebSocket 全双工通信
36
      JSON 协议设计
37
      流式消息处理（打字机效果）
38
      分片文件上传
39
      心跳保活 + 自动重连