基于Compose Multiplatform的跨平台AI对话客户端DeepCo开发实践

1. 项目概述：一个跨平台的AI对话客户端

最近在折腾AI应用开发，发现市面上的AI对话工具要么是Web端，要么就是平台绑定太死。作为一个喜欢把工具握在自己手里的开发者，我决定自己动手，用Compose Multiplatform技术栈搞一个真正跨平台的AI对话客户端。这就是DeepCo的由来——一个能让你在Windows、macOS、Linux桌面端，以及未来的Android、iOS上，用同一套代码、同一种体验，去对话各种主流大语言模型的开源项目。

简单来说，DeepCo就是一个聚合了OpenAI、Anthropic Claude、Google Gemini、DeepSeek、Coze、Dify、Grok等多家AI服务API的本地客户端。它最大的特点就是“不挑食”，你既可以用它连接在线的官方API，也能对接任何兼容OpenAI格式的自定义接口，甚至通过LM Studio或Ollama来调用本地部署的模型。对于我这种经常需要在不同模型间横跳做对比测试，或者有些敏感数据不想走云端的人来说，这种灵活性太重要了。如果你也是个AI爱好者、开发者，或者单纯想找一个界面清爽、功能集中、且完全由自己掌控的AI聊天工具，那DeepCo的设计思路或许能给你一些启发。

2. 核心架构与技术选型解析

2.1 为什么选择Compose Multiplatform？

决定做这个项目时，第一个要面对的问题就是技术栈。我的目标是覆盖桌面和移动端五大平台，如果每个平台都原生开发一遍，那工作量简直是个噩梦。React Native、Flutter这些跨端方案我也考虑过，但在桌面端的原生体验和性能上，总觉得差那么点意思。直到我看到了JetBrains推出的Compose Multiplatform。

Compose Multiplatform的核心魅力在于“共享UI逻辑”。它允许你用Kotlin和声明式的Compose UI框架来编写界面，然后这套代码可以分别编译运行在Android、iOS、Windows、macOS和Linux上。对于DeepCo这样一个以信息展示和交互为主的工具类应用来说，UI逻辑的复用率可以做到非常高。这意味着我只需要维护一套主要的业务逻辑和UI代码，就能生成多个平台的客户端，开发效率的提升是指数级的。

当然，选择它也有挑战。首先，Compose Multiplatform，尤其是其Desktop和iOS的支持，在当时（甚至现在）仍处于比较活跃的发展期，一些高级控件和平台特定功能的集成需要自己多踩些坑。其次，社区生态相比Flutter等更成熟的方案，第三方库会少一些，有些轮子得自己造。但权衡下来，用一套现代、声明式的Kotlin代码统一多端的长期收益，远远大于初期的适配成本。从实际开发体验来看，JetBrains的工具链支持非常给力，与IDE的集成度极高，调试和热重载都很顺畅。

2.2 功能模块设计与数据流

确定了技术底座，接下来就是设计应用的核心架构。DeepCo不是一个简单的API调用包装器，它需要管理用户、管理对话、管理复杂的提示词，还要支持像MCP这样的扩展协议。我采用了比较清晰的分层架构：

1. 数据层 (Data Layer)这是应用的基石，负责所有数据的持久化。我使用了SQLDelight作为本地数据库，它能够根据Kotlin代码自动生成类型安全的SQL查询，完美契合Compose Multiplatform项目。在这里，我定义了User、Conversation、Message、PromptTemplate、ApiEndpoint等核心数据表。所有聊天记录、用户配置、自定义的API密钥和提示词模板，都安全地存储在这里。

2. 领域层 (Domain Layer)这一层包含核心的业务逻辑和用例。例如，有一个SendMessageUseCase用例，它并不关心消息是通过哪个API发送的，它只负责协调：从仓库获取当前对话和API配置，调用网络层发送请求，处理流式或非流式响应，最后将消息实体保存回数据库并通知UI更新。这种设计让业务逻辑高度内聚且可测试。

3. 网络与基础设施层 (Network/Infra Layer)这是与外部世界打交道的部分。针对每个支持的AI服务提供商（如OpenAI、Claude、Gemini），我都实现了一个对应的ApiClient。这些Client都遵循一个统一的接口，内部处理各自特有的API格式、认证方式和参数。对于OpenAI兼容的API和Ollama，则使用一个通用的客户端，通过配置不同的Base URL来适配。MCP（Model Context Protocol）客户端的实现也放在这一层，它负责与MCP服务器建立连接并执行工具调用。

4. UI层 (UI Layer)基于Compose构建。我大量使用了ViewModel来持有UI状态，并通过StateFlow或MutableState将数据状态的变化自动反映到界面上。例如，主聊天界面有一个ChatViewModel，它持有当前对话的消息列表、输入框状态、连接状态等。当用户发送消息时，UI层调用ViewModel的方法，ViewModel再调用领域层的用例，整个过程是单向数据流，非常清晰，也利于状态恢复和预览。

注意：在Compose Multiplatform中处理平台差异时，我采用了expect/actual机制。比如，文件选择对话框，在桌面端我expect一个函数，然后在androidMain和desktopMain源集中分别用Android的ActivityResultLauncher和Compose for Desktop的FileDialog去actual实现。这样，公共的UI代码只需要调用这个expect函数，具体实现由各平台负责。

3. 核心功能实现与实操要点

3.1 多模型API的统一接入与管理

DeepCo支持十几种API，如果每个都写死配置，那维护起来将是灾难。我的解决方案是设计一个灵活可扩展的ApiEndpoint配置系统。在数据库里，ApiEndpoint表不仅存储了name、baseUrl、apiKey，还有一个关键的providerType字段和customConfig（JSON格式）字段。

providerType是一个枚举，告诉应用该使用哪个特定的ApiClient（如ProviderType.OPENAI,ProviderType.DEEPSEEK）。对于这些官方明确支持的提供商，应用内置了其API规范。而对于其他兼容OpenAI格式的服务，或者用户自建的接口，则使用ProviderType.OPENAI_COMPATIBLE类型。此时，customConfig字段就派上用场了，它可以存储一些非标准的请求头、特殊的路径后缀或者模型列表映射关系。

在UI上，我提供了一个通用的API配置界面。用户选择提供商类型后，界面会动态变化。例如，选择DeepSeek，它会自动填充其官方的Base URL (https://api.deepseek.com)，并提示输入正确的API密钥格式。选择“OpenAI兼容”，则允许用户自由输入任意Base URL，并可以展开高级选项，配置自定义的HTTP头。

实操心得：处理API密钥等敏感信息时，绝对不能明文存储在数据库或代码里。我在本地使用了操作系统提供的安全存储机制。在Android上，使用EncryptedSharedPreferences；在桌面端，则使用平台相关的密钥链（如macOS的Keychain，Windows的Credential Manager）。在代码中，通过expect/actual函数来抽象这一过程，确保密钥的安全性。

3.2 对话管理与上下文处理

聊天功能是核心中的核心。我设计了Conversation和Message的实体关系。一个Conversation包含多条Message，每条Message有角色（user/assistant）、内容、时间戳以及一个可选的parentMessageId用于构建树状对话结构（虽然当前UI是线性展示，但保留结构为未来功能预留）。

当用户发送消息时，系统会执行以下步骤：

1. 在本地数据库立即创建一条状态为“发送中”的user角色消息并显示，给用户即时反馈。
2. 根据当前对话选中的ApiEndpoint，构造HTTP请求。这里的关键是构建“上下文”。我会从数据库中取出当前对话最近N条消息（N由模型的最大上下文长度和用户设置共同决定），按照[系统提示词] + [历史消息1] + [历史消息2] + ... + [用户新消息]的顺序组装成API要求的格式（通常是OpenAI的messages数组或Claude的message序列）。
3. 发起网络请求。对于支持流式响应的API（绝大多数），我会开启一个SSE（Server-Sent Events）连接，并逐块接收数据。每收到一个有效的文本块，就更新数据库中对应assistant消息的内容，并通知UI刷新。这种流式体验对用户来说是最自然的。
4. 请求结束或出错时，更新消息的最终状态（成功/失败）并保存。

注意事项：不同模型的上下文格式差异很大。OpenAI和DeepSeek用messages数组，每个元素有role和content；Claude用的是messages数组但结构略有不同，且系统提示词是通过单独的system字段传递；Gemini的API更是自成一派。在ApiClient的实现中，需要为每个提供商编写专门的请求体组装和响应解析逻辑，这是工作量最大但也最需要细致处理的部分，任何格式错误都会导致API调用失败。

3.3 提示词模板与SillyTavern角色卡适配

对于高级用户，反复输入复杂的系统指令很麻烦。DeepCo的提示词模板功能就是为了解决这个。用户可以创建模板，定义name、content，还可以设置一些变量，比如{{date}}、{{user}}。在聊天时，选择某个模板，{{date}}会被自动替换为当前日期，{{user}}会被替换为当前用户名，非常方便。

更有趣的是对SillyTavern角色卡的支持。SillyTavern是一个流行的AI角色扮演前端，它的角色卡可以导出为PNG（图片中嵌入了JSON元数据）或直接的JSON文件。DeepCo实现了对这两种格式的解析。

• PNG解析：读取PNG文件，查找其tEXt或zTXt数据块中关键字为chara或character的内容，这部分内容通常是经过Base64编码的JSON字符串，解码后即可得到角色信息。
• JSON解析：直接读取JSON文件，按照SillyTavern的格式解析name、description、personality、scenario、first_mes等字段。

解析成功后，DeepCo会将这些信息转换为自己内部的PromptTemplate格式。其中，角色的description、personality等会合并成系统提示词，而first_mes（角色的第一句话）则会作为一条助手消息插入到新对话的开头，营造出角色“主动开口”的沉浸感。这个功能让DeepCo不仅能作为通用聊天工具，也能轻松用于角色扮演场景。

3.4 MCP（模型上下文协议）集成实战

MCP是去年让我非常兴奋的一个协议。它让大模型能够安全、可控地访问外部工具和数据源，比如读取本地文件、查询数据库、执行代码。DeepCo集成MCP，意味着你的对话助手不再只是“空谈”，它可以真正为你“做事”。

集成MCP主要分为客户端和服务器两部分。在DeepCo中，我实现了MCP客户端。

1. 配置MCP服务器：用户需要在设置中配置MCP服务器。这通常是一个本地启动的进程。配置项包括服务器名称、可执行文件路径（或命令）、启动参数以及工作目录。例如，配置一个文件系统访问服务器，可能命令是npx，参数是@modelcontextprotocol/server-filesystem，工作目录是/home/user。

2. 建立连接与工具发现：DeepCo的MCP客户端会根据配置，在后台启动这个服务器进程，并通过stdio（标准输入输出）与其建立连接。连接成功后，客户端会向服务器发送initialize请求，协商协议版本。紧接着发送tools/list请求，获取该服务器提供的所有工具列表。每个工具都有名称、描述和输入参数模式（JSON Schema）。

3. 在聊天中使用工具：当用户在聊天中输入指令，比如“总结一下我桌面上的report.txt文件”，DeepCo的底层逻辑（或未来结合模型自身能力）会判断是否需要调用MCP工具。如果需要，客户端会构造一个tools/call请求发送给服务器，指定工具名和参数（如{"path": "~/Desktop/report.txt"}）。服务器执行操作（读取文件）后，将结果返回。客户端再将这个结果作为上下文信息，或直接格式化后插入对话，供用户或模型参考。

实操心得：MCP通信是异步的，且需要处理可能长时间运行的工具调用。我在实现时使用了协程和通道（Channel）来管理这些后台任务，确保不会阻塞UI主线程。同时，必须做好错误处理，比如服务器进程崩溃、通信超时等，要给用户清晰的错误反馈。目前这个功能还在完善中，但已经为DeepCo打开了连接外部世界的一扇大门。

4. 桌面端部署与打包详解

4.1 开发环境搭建与运行

如果你想从源码运行或贡献DeepCo，环境搭建很简单。项目主要使用Kotlin和Gradle，这是JVM生态的标准工具。

1. 环境准备：

• JDK 17+：必须安装。建议使用JetBrains官方发行的JDK，兼容性最好。
• Android Studio（推荐）：虽然它是Android开发IDE，但其最新的版本对Compose Multiplatform项目支持非常完善，内置了Gradle管理、设备模拟器和UI预览功能。直接使用它打开项目根目录即可。

2. 运行桌面端：这是最快捷的体验方式。在Android Studio中，找到desktopApp模块下的run任务，直接执行即可。或者，在终端中进入项目根目录，执行：

./gradlew :desktopApp:run

Gradle会自动处理所有依赖编译，并启动一个本地运行的桌面应用程序窗口。在开发过程中，修改了Compose UI代码后，Compose支持热重载（不是热更新，是重绘），可以快速看到效果。

3. 运行Android端：确保已安装Android SDK并配置好模拟器或连接了真机。在Android Studio中，选择androidApp模块和对应的设备，点击运行。或者使用命令行：

./gradlew :androidApp:installDebug

这会将调试版APK安装到你的设备上。

4.2 构建可分发的应用程序包

开发调试完成后，下一步就是打包成用户可以独立安装的程序。

1. 桌面端打包：Compose Multiplatform的桌面插件提供了强大的打包能力。执行以下命令，Gradle会为当前操作系统生成对应的安装包：

./gradlew :desktopApp:packageDistributionForCurrentOS

打包完成后，你可以在desktopApp/build/compose/binaries目录下找到生成物。不同平台格式不同：

• Windows：会生成一个.exe安装程序和一个包含所有依赖的可执行文件目录。
• macOS：会生成一个.dmg磁盘映像文件或.pkg安装包，以及一个.app应用程序包。
• Linux：会生成一个.deb（Debian/Ubuntu）或.rpm（Fedora/RHEL）安装包，以及一个可执行的.tar.gz压缩包。

在打包配置中，我设置了应用图标、版本信息、JVM运行参数（如内存设置）等。对于macOS，还需要额外配置签名和公证（Notarization）才能在Gatekeeper下顺利运行，这涉及到Apple Developer账号，开源项目发布时通常提供未签名的版本，由用户自行决定是否信任运行。

2. Android端打包：发布到Google Play或其他应用市场需要Release版本。

./gradlew :androidApp:assembleRelease

生成的APK或AAB（Android App Bundle）文件位于androidApp/build/outputs/apk/release/或.../bundle/release/目录下。Release版本会启用代码压缩（R8）、资源优化，并使用你的发布密钥进行签名。务必保管好你的签名密钥文件（.jks）和密码，丢失后将无法更新应用。

3. iOS端打包：iOS的支持仍在进行中。当功能完备后，打包需要一台macOS设备和安装Xcode。过程大致是：Gradle任务会编译出iOS框架，然后需要打开Xcode项目（位于iosApp目录），配置开发者团队和证书，最后通过Xcode进行归档（Archive）并上传到App Store Connect。

踩坑记录：在早期打包桌面应用时，我忽略了JVM依赖的打包方式。默认的“嵌入JVM”方式会让安装包体积巨大（超过200MB）。后来我切换到了“使用系统JRE”的方式，并提供了清晰的文档告诉用户需要预先安装JRE 17+，这显著减小了安装包体积。但代价是增加了用户的前置依赖。这是一个典型的权衡，需要根据目标用户群体来决定。

5. 国际化、主题与辅助功能

5.1 多语言支持实现

作为一个开源项目，我希望DeepCo能被更多地区的用户使用。国际化是必不可少的。Compose Multiplatform本身对i18n有很好的支持。我的实现步骤如下：

1. 定义字符串资源：我创建了一个strings.xml文件（实际上是一个Kotlin对象或属性文件），但为了结构化，我使用了strings.kt，里面用object Strings来定义所有需要翻译的文本键值对。例如：

object Strings { val appName = stringResource("app_name") val chat = stringResource("chat") val settings = stringResource("settings") // ... 更多键 }

这里的stringResource是一个自定义的扩展函数，它会根据当前的语言环境去查找对应的翻译。

2. 创建翻译文件：在resources目录下，为每种语言创建对应的目录，如values/（默认，英文）、values-zh/（中文）。在每个目录下放置一个strings.properties文件，里面是键值对：

# values/strings.properties app_name=DeepCo chat=Chat settings=Settings # values-zh/strings.properties app_name=DeepCo chat=聊天 settings=设置

3. 动态切换语言：应用内部维护一个AppSettings数据类，其中包含language字段。当用户在设置界面切换语言时，我更新这个设置并持久化到数据库。然后，我使用CompositionLocalProvider在应用的根布局处，提供一个基于当前AppSettings.language构建的LocalConfiguration环境。这样，所有子Composable中通过stringResource获取的文本都会自动更新。

注意事项：语言切换后，部分Composable可能需要重组才能显示新文字。对于像日期、数字等格式，也需要使用LocalConfiguration提供的本地化上下文来处理，以确保格式符合当地习惯。

5.2 深色模式与动态主题

现代应用没有深色模式是说不过去的。Compose的主题系统让这一切变得简单。我定义了两套颜色调色板：LightColorPalette和DarkColorPalette。它们都实现了同一个ColorPalette接口，确保了类型安全。

在AppSettings中，同样有一个theme字段，可以是Light、Dark或System。应用启动时，会读取这个设置。如果是System，则会使用Platform相关的代码（同样是expect/actual）去查询操作系统当前的主题模式。

在UI层，我创建了一个AppThemeComposable函数：

@Composable fun AppTheme( settings: AppSettings, content: @Composable () -> Unit ) { val colors = when (settings.theme) { Theme.Light -> LightColorPalette Theme.Dark -> DarkColorPalette Theme.System -> { val isSystemInDarkTheme = isSystemInDarkTheme() // 平台查询 if (isSystemInDarkTheme) DarkColorPalette else LightColorPalette } } MaterialTheme( colors = colors.materialColors, typography = Typography, shapes = Shapes, content = content ) }

这样，只需要用AppTheme包裹整个应用，所有使用MaterialTheme.colors或MaterialTheme.typography的组件都会自动适应主题变化。切换主题时，更新AppSettings并触发UI重组即可。

5.3 文本转语音功能集成

为了让对话体验更生动，我集成了TTS功能。考虑到跨平台和易用性，我选择了微软Edge浏览器的在线TTS API。这是一个免费、高质量的语音合成服务，支持多种语言和音色。

实现原理：

1. 文本处理：当用户点击消息旁的“朗读”按钮时，应用会获取该条消息的纯文本内容。
2. 构造请求：按照Edge TTS API的格式，构造一个SSE请求。请求中需要指定语音模型（如zh-CN-XiaoxiaoNeural）、语速、音调等参数。
3. 流式接收与播放：API返回的是音频流（通常是audio/ogg格式）。客户端需要逐块接收这些音频数据，并缓冲起来。我使用了一个跨平台的音频播放库（如kotlinx-io配合平台特定的音频API）来播放缓冲的音频流。对于桌面端，我使用了javax.sound.sampled；对于Android，则使用android.media.MediaPlayer或ExoPlayer，并通过expect/actual进行封装。
4. 控制与状态：提供了播放、暂停、停止、调整语速等控制按钮，并将播放状态（正在播放、暂停、停止）反馈到UI上。

实操心得：在线TTS的优点是音质好、选择多，但缺点是需要网络，且有潜在的服务稳定性问题。在实现时，我加入了请求超时和重试机制。未来可以考虑集成离线的TTS引擎作为备选方案，但这会显著增加应用体积。另外，长时间播放或网络不稳定时，音频流的缓冲管理是个技术点，需要处理好数据接收、解码和播放线程之间的同步，避免卡顿或内存溢出。

6. 常见问题排查与性能优化

6.1 网络连接与API调用问题

这是用户最常遇到的问题。下面是一个快速排查清单：

一个深度排查案例：有用户反馈使用某个第三方OpenAI兼容API时，总是超时。我让他开启了调试日志，发现请求成功发送了，但一直收不到响应。最后发现是那个API服务端默认的响应超时时间很短，而DeepCo在等待流式响应时没有设置一个合理的客户端超时。我在代码中为SSE连接增加了可配置的读写超时时间，并在高级设置中暴露给用户，解决了这类特定API的兼容性问题。

6.2 应用性能与资源占用优化

作为一个桌面端应用，流畅度和资源友好性很重要。以下是我在开发中做的几点关键优化：

1. 聊天列表的惰性加载与状态保持：聊天记录可能很长，如果一次性加载所有消息到内存并全部渲染，会非常卡顿。我使用了LazyColumn来渲染消息列表，它只会渲染可视区域及附近区域的消息项。对于每条消息，尤其是包含长文本或代码块的消息，我使用了DerivedState来避免在滚动时因内容未变而导致的无效重组。同时，在ViewModel中妥善管理对话状态，确保在切换对话时能快速恢复。

2. 图片与资源的缓存：对于从网络加载的角色卡头像、或未来可能支持的图片消息，我引入了Coil或Kamel这样的图片加载库（通过expect/actual实现多平台支持）。它们自带内存和磁盘缓存，能有效避免重复下载和内存泄漏。对于应用自身的图标等资源，则使用Compose的painterResource，它会由框架进行高效管理。

3. 数据库操作的优化：所有数据库的读写操作都放在IO调度器上执行，绝不阻塞UI线程。对于批量插入消息（如导入历史记录）等操作，使用事务来提高效率。定期清理过期的缓存数据或临时文件。在Android上，还需要注意在后台时或应用生命周期变化时，妥善关闭数据库连接。

4. 内存泄漏预防：在Compose中，最常见的泄漏是忘记了在DisposableEffect或LaunchedEffect中取消协程或监听器。我养成了习惯，对于每个在Composable中启动的协程，都会确保其作用域与Composable的生命周期绑定（使用rememberCoroutineScope），并在onDispose中取消。对于Flow的收集，也使用collectAsStateWithLifecycle（Android）或类似的生命周期感知收集器。

5. 启动速度优化：应用启动时，避免在主线程进行繁重的初始化操作（如加载大量历史记录）。我将数据库初始化、默认配置检查等任务放到了后台协程中异步执行。应用启动后先显示一个简单的骨架屏或加载界面，待数据准备就绪后再进入主界面。对于桌面端，还可以利用Gradle的打包插件进行资源压缩和代码混淆（R8），减小安装包体积，间接提升加载速度。

开发DeepCo的过程，是一个不断在功能丰富性、跨平台一致性、用户体验和性能之间寻找平衡的过程。每一个功能从设计到落地，都伴随着无数次调试和优化。开源出来，也是希望更多开发者能一起参与，让它变得更好用。如果你在使用的过程中有任何问题，或者有很棒的想法，非常欢迎到GitHub仓库提交Issue或Pull Request。