Kelivo 项目深度解析与技术指南

项目概述与定位

项目基本信息

Kelivo 是一个基于 Flutter 3.x 框架开发的开源大型语言模型（LLM）聊天客户端，由开发者 Chevey339 主导维护。截至 2025 年，该项目在 GitHub 上已获得超过 2000 个星标和 200 余个分支 [34]，显示出较强的社区活跃度。

项目的核心定位并非简单的聊天工具封装，而是一个企业级的多 AI 服务集成平台，通过抽象化的架构设计，实现了对多种主流 LLM 提供商的无缝接入。与市面上单一服务商的聊天应用不同，Kelivo 的最大特色在于其"多提供商自由切换"架构[135]。

多模态对话

支持文本、图片、PDF、Word 混合输入，通过文件预处理和 Vision API 实现

Markdown 富文本

代码高亮、LaTeX 公式、表格渲染，基于 flutter_markdown 扩展

语音交互

系统 TTS + 云端语音合成，支持流式接收和队列管理

MCP 工具调用

Model Context Protocol 标准支持，可扩展外部工具链[135]

支持平台矩阵

平台	支持状态	分发渠道	特殊说明
Android	✅ 完全支持	Google Play、GitHub Releases、F-Droid	Material You 动态主题（API 31+）
iOS	✅ 完全支持	App Store、TestFlight	完整审核通过，TestFlight 公测可用
Windows	✅ 完全支持	Microsoft Store、GitHub Releases	MSIX 打包，自动更新集成
macOS	✅ 完全支持	Mac App Store、GitHub Releases	Notarization 公证，DMG 分发
Linux	✅ 完全支持	Snap、Flatpak、AppImage、软件中心	多格式覆盖主流发行版
OpenHarmony	⚠️ 适配中	鸿蒙应用市场（规划中）	独立分支 kelivo-ohos，部分功能降级[154]

项目目录结构详解

核心架构分层

graph TD A["Presentation Layer
UI Widgets"] --> B["Business Logic Layer
Providers"] B --> C["Data Access Layer
Repositories"] C --> D["Infrastructure Layer
Network/Storage"] E["Features/"] --> F["Chat/
Models/Providers/Services"] E --> G["Settings/
Configuration"] E --> H["Models/
AI Service Integration"] I["Core/"] --> J["Network/
Dio Configuration"] I --> K["Storage/
Hive/SharedPreferences"] I --> L["Logger/
Logging System"] style A fill:#dbeafe,stroke:#1e40af,stroke-width:2px,color:#1f2937 style B fill:#dcfce7,stroke:#166534,stroke-width:2px,color:#1f2937 style C fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#1f2937 style D fill:#fce7f3,stroke:#be185d,stroke-width:2px,color:#1f2937 style E fill:#f0f9ff,stroke:#0284c7,stroke-width:2px,color:#1f2937 style F fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#1f2937 style G fill:#fefce8,stroke:#ca8a04,stroke-width:2px,color:#1f2937 style H fill:#fdf2f8,stroke:#be185d,stroke-width:2px,color:#1f2937 style I fill:#faf5ff,stroke:#9333ea,stroke-width:2px,color:#1f2937 style J fill:#f0f9ff,stroke:#0284c7,stroke-width:2px,color:#1f2937 style K fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#1f2937 style L fill:#fefce8,stroke:#ca8a04,stroke-width:2px,color:#1f2937

聊天模块结构

lib/features/chat/

├── models/

│ ├── message.dart # 消息数据模型

│ ├── conversation.dart # 会话模型

│ └── attachment.dart # 附件模型

├── providers/

│ ├── chat_provider.dart # 核心状态管理

│ └── conversation_provider.dart # 会话管理

├── services/

│ ├── llm_service.dart # 抽象接口

│ ├── streaming_handler.dart # SSE 流处理

│ └── context_compressor.dart # 上下文压缩

├── widgets/

│ ├── chat_message_list.dart # 消息列表

│ ├── chat_input_bar.dart # 输入栏

│ ├── message_bubble.dart # 消息气泡

│ ├── code_block.dart # 代码块渲染

│ ├── markdown_body.dart # Markdown 渲染

│ └── thinking_indicator.dart # 思考指示器

└── screens/

├── chat_screen.dart # 主聊天页面

└── conversation_list_screen.dart # 会话列表

构建与编译指南

环境准备

Flutter SDK 要求

✓ Flutter 3.8.1+

✓ Dart 3.0.0+

验证安装： flutter doctor

平台工具链

• Android: Android Studio, SDK API 33+
• iOS: Xcode 15+, CocoaPods
• Windows: Visual Studio 2022
• macOS: Xcode 15+
• Linux: Clang, CMake, Ninja

依赖预加载

cd kelivo
flutter pub get

中国大陆开发者建议配置镜像： export PUB_HOSTED_URL=https://pub.flutter-io.cn

发布构建命令

Android

# 调试 APK

flutter build apk --debug

# 发布 AAB

flutter build appbundle --release

iOS

# 构建 release

flutter build ios --release

# 后续 Xcode Archive

Windows

# MSIX 打包

flutter build windows --release

# 自动更新集成

OpenHarmony

# 鸿蒙适配分支

git clone kelivo-ohos

flutter build app --release

Flutter 核心概念与特性

一切皆 Widget

UI 组件化与组合式构建，从简单的 Text 到复杂的 ListView 都是 Widget

声明式编程

状态驱动 UI 自动更新，框架负责状态变化时的自动同步

自绘引擎

Skia/Impeller 跨平台渲染一致性，像素级相同的视觉效果

热重载（Hot Reload）

工作原理

• JIT 编译：开发模式 Dart VM 执行字节码
• 状态保持：重建 Widget 树，保留 State 对象
• 毫秒级反馈：增量编译 + 增量传输

Kelivo 应用场景

• 调整消息气泡圆角 → 保存 → 立即查看效果
• 修改主题色值 → 实时预览
• 优化动画曲线 → 反复微调至满意

开发环境搭建

IDE 选择与配置

VS Code

轻量快速、插件丰富

• Flutter 插件
• Awesome Flutter Snippets
• Error Lens

Android Studio

官方支持、重构强大

• Flutter/Dart 插件
• 布局编辑器
• .env 文件支持

IntelliJ IDEA

企业级功能、多语言支持

• 同 Android Studio
• 企业级特性

SDK 版本管理

fvm 推荐配置

# 安装 fvm
dart pub global activate fvm

# 项目级版本锁定
cd kelivo
fvm install 3.8.1
fvm use 3.8.1

创建 .fvm/fvm_config.json 纳入版本控制，确保团队环境一致

常用组件与布局系统

核心布局组件

基础布局

Row / Column

线性排列，用于工具栏按钮横向排列

Stack

层叠布局，消息气泡上的引用标记

Expanded / Flexible

空间分配，输入框与发送按钮比例

响应式布局

LayoutBuilder

断点系统实现

final width = MediaQuery.size.width;
return switch (width) {
< 600 => MobileLayout(),
< 900 => TabletLayout(),
_ => DesktopLayout(),
};

聊天界面专项实现

消息气泡渲染

CustomPainter + ShapeDecoration 实现带"尾巴"的不规则气泡

实现方案对比：

• BorderRadius: 仅圆角矩形
• ShapeDecoration: 自定义路径（主要方案）
• CustomPainter: 完全自由（特殊效果）

代码高亮

flutter_highlight 集成，支持 180+ 编程语言

自定义功能：

• 行号显示
• 复制按钮
• 语言标签
• 多主题支持

Markdown 渲染

flutter_markdown + 自定义元素构建器

扩展支持：

• 代码块（code）
• 数学公式（latex）
• 流程图（mermaid）

图片与文件预览

Hero 动画 + photo_view 实现流畅预览

交互特性：

• 点击放大
• 双指缩放
• 左右滑动切换
• 文件类型识别

路由与导航管理

路由方案选型

方案	特点	适用场景	Kelivo 选择
MaterialApp.routes	静态配置、简单直观	页面少、无复杂参数	基础配置
Navigator 1.0	动态灵活、栈操作	需要手动控制返回栈	部分使用
go_router	深层链接、路径参数	需要 URL 路由、Web 支持	未采用
auto_route	代码生成、类型安全	大型项目、复杂导航	未采用

页面层级结构

/

├── /chat/:conversationId # 主聊天页

├── /settings # 设置主页

│ ├── /settings/appearance # 外观设置

│ ├── /settings/language # 语言设置

│ └── /settings/providers # 模型提供商配置

└── /onboarding # 首次启动引导

路由守卫

MaterialApp(

initialRoute: hasAnyProvider() ? '/' : '/onboarding',

)

无 API 密钥配置时，强制跳转引导页面

插件生态系统与关键依赖

核心功能插件

网络通信

dio ^5.4.0

web_socket_channel ^2.4.0

本地存储

shared_preferences ^2.2.2

hive ^2.2.3

hive_flutter ^1.1.0

文件处理

image_picker ^1.0.7

file_picker ^6.1.1

path_provider ^2.1.1

桌面端专属插件

插件	版本	功能	平台
window_manager	^0.3.7	窗口管理、尺寸、位置、置顶	全桌面平台
tray_manager	^0.2.2	系统托盘图标、右键菜单	全桌面平台
desktop_drop	^0.4.4	文件拖放进入应用窗口	全桌面平台
hotkey_manager	^0.1.7	全局快捷键注册	全桌面平台
screen_retriever	^0.1.9	多显示器信息获取	全桌面平台

状态管理架构

Provider 架构分层

graph TD A["UI Layer
Widgets"] --> B["ChangeNotifier
Provider"] B --> C["Service Layer
Business Logic"] C --> D["Repository Layer
Data Abstraction"] D --> E["Data Source
API / Local DB / Cache"] style A fill:#dbeafe,stroke:#1e40af,stroke-width:2px,color:#1f2937 style B fill:#dcfce7,stroke:#166534,stroke-width:2px,color:#1f2937 style C fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#1f2937 style D fill:#fce7f3,stroke:#be185d,stroke-width:2px,color:#1f2937 style E fill:#f1f5f9,stroke:#475569,stroke-width:2px,color:#1f2937

聊天状态管理：ChatProvider

流式响应处理核心逻辑：

1. 添加用户消息，设置加载状态

2. 调用 LLM 服务获取流

3. 创建 AI 消息占位符

4. 监听流更新，实时追加内容

5. 错误处理和状态清理

性能优化

Selector 优化

使用 Selector 替代 Consumer，避免整树重建

ValueNotifier

局部更新优化，消息列表流畅滚动

API 交互与网络层设计

多服务商抽象架构

抽象接口定义：

abstract class LLMService {

Future<Stream<String>> streamMessage(...);

Future<List<AIModel>> getModels();

Future<int> countTokens(String text);

Future<bool> validateConfig();

}

OpenAI 实现

• HTTP + SSE 协议
• Bearer Token 认证
• 组织 ID 可选
• 函数调用支持

Claude 实现

• x-api-key 头认证
• 系统提示词单独字段
• thinking 块处理
• API 版本管理

流式响应处理

SSE 解析

自定义解析器处理标准 SSE 格式

data: {"choices":[{"delta":{"content":"Hello"}}]}

UI 实时更新

StreamBuilder + AnimatedText 实现打字机效果

逐字动画 + 智能滚动 + 光标闪烁

错误处理

网络异常分类 + 指数退避重试

自动重连 + 用户友好提示

核心功能模块实现

对话系统

消息模型设计

@HiveType(typeId: 1)

class Message {

@HiveField(0)

final String id;

@HiveField(1)

final MessageRole role;

@HiveField(2)

final String content;

@HiveField(3)

final DateTime timestamp;

}

上下文压缩策略

滑动窗口

保留最近 K 条，简单有效

摘要生成

轻量模型生成摘要，保留语义

关键提取

提取用户明确引用的消息

多模态输入

图片理解

• Vision API 集成
• 本地压缩优化
• Base64 编码
• 多模态消息格式

语音输入

• speech_to_text 插件
• 权限申请处理
• 实时语音识别
• 标点优化

文件解析

• PDF 文本提取
• Word 文档解析
• 代码文件处理
• 大文件分批处理

本地模型支持

Ollama 对接

配置界面

端点 URL、模型选择、高级参数

模型管理

动态拉取、流式进度、版本控制

离线检测

ConnectivityService

检测本地模型可用性

checkOllamaAvailable() → bool

UI 适配：显示提示条，提供重试或切换选项

出行/配送类应用最佳实践

技术迁移说明

虽然 Kelivo 是 LLM 聊天应用，但其技术架构与出行/配送类应用有诸多共通之处。以下基于 Kelivo 的实践经验，推导可迁移的最佳实践。

地图与定位集成

地图插件选型

国内应用

amap_flutter_map 高德地图

国际应用

google_maps_flutter

开源方案

flutter_map + openstreetmap

实时定位

• geolocator 插件
• 前台高精度定位
• 后台位置更新
• 电量优化策略

轨迹绘制

• Polyline 动态更新
• 平滑动画效果
• 轨迹回放功能
• 性能优化处理

Kelivo 架构迁移启示

多服务商抽象架构可直接迁移——定义 MapService 接口，实现 AmapService、 GoogleMapService，运行时根据区域切换

订单状态机设计

graph TD A["待支付"] --> B["待接单"] B --> C["取货中"] C --> D["配送中"] D --> E["待确认"] E --> F["已完成"] A --> G["已取消"] B --> G C --> H["异常上报"] D --> H E --> I["申诉中"] H --> J["客服处理"] I --> J J --> F J --> G style A fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#1f2937 style B fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1f2937 style C fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#1f2937 style D fill:#ddd6fe,stroke:#7c3aed,stroke-width:2px,color:#1f2937 style E fill:#f0f9ff,stroke:#0284c7,stroke-width:2px,color:#1f2937 style F fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#1f2937 style G fill:#fef2f2,stroke:#dc2626,stroke-width:2px,color:#1f2937 style H fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#1f2937 style I fill:#fce7f3,stroke:#be185d,stroke-width:2px,color:#1f2937 style J fill:#f1f5f9,stroke:#64748b,stroke-width:2px,color:#1f2937

推送通知方案

firebase_messaging

国际应用，生态成熟

极光推送

国内应用，通道稳定

自建 WebSocket

高实时性，完全可控

实时同步架构

客户端 ←→ 负载均衡

←→ WebSocket 集群

←→ 订单服务 ←→ 数据库

↓ 状态广播（发布订阅）

性能优化模式

列表优化

• ListView.builder 按需构建
• 图片懒加载
• 内存缓存管理
• 分页加载机制

Kelivo 消息列表 → 订单列表迁移

地图优化

• Marker 聚合算法
• 瓦片缓存策略
• 层级动态控制
• 内存管理优化

电量优化

• 定位精度动态调整
• 后台任务限制
• 地理围栏替代
• 批量上传策略

特定技术实现细节

国际化（i18n）完整方案

ARB 文件管理

l10n.yaml 配置：

arb-dir: lib/l10n

template-arb-file: app_en.arb

output-class: AppLocalizations

app_en.arb 示例：

{

"@@locale": "en",

"appTitle": "Kelivo",

"sendMessage": "Send",

}

动态语言切换

LocaleProvider

setLocale(Locale locale)

notifyListeners()

RTL 语言适配

阿拉伯语、希伯来语等从右到左语言

Directionality(

textDirection: TextDirection.rtl

)

主题系统深度定制

Material 3 适配

• 动态配色提取
• 系统主题跟随
• 组件主题覆盖
• 自定义主题扩展

自定义组件主题

ChatBubbleTheme

extends ThemeExtension

聊天专属样式主题化

系统主题监听

onPlatformBrightnessChanged

动态响应系统主题变化

安全与隐私合规

证书固定（SSL Pinning）

CertificatePinning

allowedSHAFingerprints: [

'sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAA='

]

防止中间人攻击

隐私协议

首次启动流程

隐私协议弹窗 → 用户同意

GDPR 合规

数据透明、删除权、导出功能

数据脱敏

class SensitiveDataFilter

_containsSensitivePattern(message)

// 过滤 API 密钥、手机号等