基于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来适配。MCPModel 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字段和customConfigJSON格式字段。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的KeychainWindows的Credential Manager。在代码中通过expect/actual函数来抽象这一过程确保密钥的安全性。3.2 对话管理与上下文处理聊天功能是核心中的核心。我设计了Conversation和Message的实体关系。一个Conversation包含多条Message每条Message有角色user/assistant、内容、时间戳以及一个可选的parentMessageId用于构建树状对话结构虽然当前UI是线性展示但保留结构为未来功能预留。当用户发送消息时系统会执行以下步骤在本地数据库立即创建一条状态为“发送中”的user角色消息并显示给用户即时反馈。根据当前对话选中的ApiEndpoint构造HTTP请求。这里的关键是构建“上下文”。我会从数据库中取出当前对话最近N条消息N由模型的最大上下文长度和用户设置共同决定按照[系统提示词] [历史消息1] [历史消息2] ... [用户新消息]的顺序组装成API要求的格式通常是OpenAI的messages数组或Claude的message序列。发起网络请求。对于支持流式响应的API绝大多数我会开启一个SSEServer-Sent Events连接并逐块接收数据。每收到一个有效的文本块就更新数据库中对应assistant消息的内容并通知UI刷新。这种流式体验对用户来说是最自然的。请求结束或出错时更新消息的最终状态成功/失败并保存。注意事项不同模型的上下文格式差异很大。OpenAI和DeepSeek用messages数组每个元素有role和contentClaude用的是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:runGradle会自动处理所有依赖编译并启动一个本地运行的桌面应用程序窗口。在开发过程中修改了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会生成一个.debDebian/Ubuntu或.rpmFedora/RHEL安装包以及一个可执行的.tar.gz压缩包。在打包配置中我设置了应用图标、版本信息、JVM运行参数如内存设置等。对于macOS还需要额外配置签名和公证Notarization才能在Gatekeeper下顺利运行这涉及到Apple Developer账号开源项目发布时通常提供未签名的版本由用户自行决定是否信任运行。2. Android端打包发布到Google Play或其他应用市场需要Release版本。./gradlew :androidApp:assembleRelease生成的APK或AABAndroid 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_nameDeepCo chatChat settingsSettings # values-zh/strings.properties app_nameDeepCo 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。这是一个免费、高质量的语音合成服务支持多种语言和音色。实现原理文本处理当用户点击消息旁的“朗读”按钮时应用会获取该条消息的纯文本内容。构造请求按照Edge TTS API的格式构造一个SSE请求。请求中需要指定语音模型如zh-CN-XiaoxiaoNeural、语速、音调等参数。流式接收与播放API返回的是音频流通常是audio/ogg格式。客户端需要逐块接收这些音频数据并缓冲起来。我使用了一个跨平台的音频播放库如kotlinx-io配合平台特定的音频API来播放缓冲的音频流。对于桌面端我使用了javax.sound.sampled对于Android则使用android.media.MediaPlayer或ExoPlayer并通过expect/actual进行封装。控制与状态提供了播放、暂停、停止、调整语速等控制按钮并将播放状态正在播放、暂停、停止反馈到UI上。实操心得在线TTS的优点是音质好、选择多但缺点是需要网络且有潜在的服务稳定性问题。在实现时我加入了请求超时和重试机制。未来可以考虑集成离线的TTS引擎作为备选方案但这会显著增加应用体积。另外长时间播放或网络不稳定时音频流的缓冲管理是个技术点需要处理好数据接收、解码和播放线程之间的同步避免卡顿或内存溢出。6. 常见问题排查与性能优化6.1 网络连接与API调用问题这是用户最常遇到的问题。下面是一个快速排查清单问题现象可能原因排查步骤与解决方案连接API失败1. 网络不通。2. API密钥错误或过期。3. Base URL填写错误。4. 本地代理或防火墙阻止。1. 检查网络连接尝试访问其他网站。2. 在API提供商后台确认密钥有效且未过期注意复制时不要带空格。3. 仔细核对Base URL确保是https://开头且路径正确如OpenAI是https://api.openai.com/v1。4. 暂时关闭代理软件或防火墙试试。流式响应中断1. 网络波动。2. 服务器端超时或中断。3. 客户端解析SSE流出错。1. 检查网络稳定性。DeepCo有基本的断线重连逻辑但频繁中断需排查网络。2. 有些免费或低配API有响应时长限制。尝试缩短问题长度或更换模型。3. 查看应用日志如果开启了日志输出看是否有SSE解析错误。返回内容乱码或错误1. 请求或响应编码问题。2. API返回了非JSON格式的错误信息。3. 模型不支持某些参数。1. 确保请求头Content-Type: application/json; charsetutf-8已设置。2. 在设置中开启“显示详细错误”查看API返回的原始错误信息。3. 对照API文档检查你设置的参数如temperature,top_p是否在模型允许范围内。Ollama本地模型连不上1. Ollama服务未启动。2. 主机地址或端口错误。3. 模型未下载或加载。1. 在终端运行ollama serve确保服务在运行。2. DeepCo中Ollama的Base URL通常是http://localhost:11434/v1。3. 使用ollama list查看可用模型并用ollama pull model-name下载所需模型。一个深度排查案例有用户反馈使用某个第三方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的收集也使用collectAsStateWithLifecycleAndroid或类似的生命周期感知收集器。5. 启动速度优化应用启动时避免在主线程进行繁重的初始化操作如加载大量历史记录。我将数据库初始化、默认配置检查等任务放到了后台协程中异步执行。应用启动后先显示一个简单的骨架屏或加载界面待数据准备就绪后再进入主界面。对于桌面端还可以利用Gradle的打包插件进行资源压缩和代码混淆R8减小安装包体积间接提升加载速度。开发DeepCo的过程是一个不断在功能丰富性、跨平台一致性、用户体验和性能之间寻找平衡的过程。每一个功能从设计到落地都伴随着无数次调试和优化。开源出来也是希望更多开发者能一起参与让它变得更好用。如果你在使用的过程中有任何问题或者有很棒的想法非常欢迎到GitHub仓库提交Issue或Pull Request。