企业官网建设流程全解析

先交代一下背景。DeepSeek Harness 这个名字，最近在群里和社区里频繁出现，很多人搜的是“怎么安装”“怎么下载”“有没有插件”，但深入用一圈之后会发现，它本质上做的是同一件事：把 DeepSeek 这套模型能力的管理、调度、会话控制和运行观测，统一收口成一个可编程的工具集合。你可以把它理解成一个类似“总装车间”的东西，模型是机器，Harness 是产线，提示词、参数、历史会话、工具调用都在这个产线上流转。

问题也出在这儿。产线通常被架在服务器或桌面上，出门以后基本就断联了。我在电脑前已经习惯了用它来调试 prompt、调参数、看推理日志，但在地铁上、咖啡厅里、出差路上想快速看一眼某个任务的状态，或者临时改一个 system prompt 继续跑对话，只能干瞪眼。手机浏览器勉强能用，但那个体验一言难尽，尤其是长日志和参数配置，在移动端几乎不可用。

后来我打算专门做一个移动端壳子，把 Harness 的核心能力装进口袋。技术选型折腾了一圈，最后用了腾讯开源的 Kuikly。这篇文章就说说整个改造过程中我做了什么、为什么这么选、以及踩过的那些坑。

1. 为什么非要把 Harness 塞进手机——这个需求的起点

先别急着聊技术，得先搞清楚这个项目解决的问题到底是什么。DeepSeek Harness 在当前生态里扮演的角色，是给模型调用提供一套结构化的编排层。直接调 API 当然可以，但一旦涉及多轮对话管理、工具调用、上下文压缩、日志归档、参数实验，裸 API 就不够用了。Harness 把这些事情统一管起来，对外暴露统一的接口，对内维护状态和配置。

桌面端的使用场景很顺，因为屏幕大、键盘在手、可以同时开好几个终端窗口，随时改配置随时看效果。但我日常工作中至少有三分之一的时间不在工位上，可工作并不会因为人不在电脑前就停下来。我需要一个能放下口袋的终端，让我随时能：

• 查看当前正在跑的任务状态和结果
• 调整 DeepSeek 模型的 temperature、max_tokens、top_p 等推理参数
• 维护一组常用的 prompt 模板，并在手机上直接调用
• 查看历史会话记录，支持复制和分享
• 临时跑一小段多轮对话，验证思路是否成立

这些需求如果全走电脑远程桌面，虽然也能做，但体验割裂且依赖网络质量。如果做一个原生 App，那要同时维护 Android 和 iOS 两套 UI，成本太高。我需要的是一种“一套代码出双端、逻辑层用 Kotlin、UI 能声明式开发、对原生能力有足够桥接空间”的方案。

这时候 Kuikly 进入了视野。它是腾讯开源的跨端 UI 框架，核心思路是用 Kotlin 写声明式 UI，通过类似 Compose 的写法同时构建 Android 和 iOS 页面。和 Flutter 不一样的地方在于，Kuikly 不搞自绘引擎，而是尽量走各端原生渲染，UI 的视觉效果更接近原生，和原生模块的互操作也更直接。

我当时比较了三个方案，情况如下：

选择 Kuikly 最直接的原因，是我本来就在用 Kotlin 维护 Harness 的配套脚本和工具库，选它意味着 UI 层和逻辑层可以在同一门语言里完成，不需要引入第二套语言生态。对于一个人维护的移动端项目来说，技术栈收敛比什么都重要。

2. 服务端先立住：Harness 的接口设计决定了移动端长什么样

移动端不是凭空就能工作的，它背后需要一个稳定可访问的服务端入口。我的做法是把 DeepSeek Harness 部署在一台低配云主机上，然后专门为移动端设计一套轻量级的 HTTP + WebSocket 接口层。这部分如果不先想清楚，后面做 UI 做到一半一定会返工。

我在服务端暴露的接口分成这么几类：

• 任务查询接口：列出所有历史任务，包括任务 ID、状态、创建时间、耗时、结果摘要
• 参数配置接口：读取和修改默认推理参数，以及按任务覆盖参数
• Prompt 管理接口：维护我常用的 prompt 资产库，手机上直接选择模板发起对话
• 会话接口：创建新会话、追加消息、拉取历史消息
• 流式日志接口：通过 WebSocket 推送推理日志和状态变更

有一个设计上的取舍值得说一下：参数配置接口一开始我打算直接暴露 Harness 的原始配置结构，后来发现不行。原始配置里字段太细，很多参数是服务端专用的，比如并发线程数、缓存策略、模型路由优先级，这些在手机端根本不该暴露，暴露了只会增加混乱。最终我对移动端做了一层精简视图，只暴露温度、最大 token 数、top_p、频率惩罚、存在惩罚这五个常用项，其他全部走默认。移动端的本质是轻量化操作，不是把服务端配置中心搬到手机上。

接口统一返回 JSON，错误码规范成三段式格式，比如AUTH_001、TASK_404、PARAM_INVALID。为什么这样做？因为移动端要针对不同错误码给出不同的提示和恢复策略，比如 AUTH 开头跳登录页，TASK_404 提示任务不存在并刷新列表，PARAM_INVALID 回滚到上一次合法配置。如果没有规范错误码，前端就只能靠解析字符串猜，这种代码维护起来非常痛苦。

服务端还有一个必须处理的细节是鉴权。手机端不像桌面终端可以用 SSH key，我采用的最简方案是下发一个长期 token，存在手机 Keychain/Keystore 中，每次请求带上。token 有过期时间，服务端在过期前 7 天返回一个额外的续期标记，移动端在后台静默续期。这套机制不复杂，但能保证两个多月用下来不会出现“突然无法连接，必须回电脑上重新登录”的尴尬情况。

3. Kuikly 落地的关键三步：状态建模、声明式 UI、原生能力桥接

服务端接口稳定之后，移动端的工作重心就转移到了 Kuikly 本身。这个框架的资料还不算多，社区规模也比 Flutter 小一截，但核心概念上手不算难。如果你已经写过 Jetpack Compose，那看 Kuikly 会非常顺，它连状态管理和重组思想都是类似的。

3.1 状态建模：先想清楚页面上的数据从哪来、如何变

移动端的核心页面有三个：任务列表页、会话详情页、设置页。我在动手写 UI 之前，先做了状态建模，把每个页面的状态拆成了三类：

• 页面数据：任务列表项、会话消息列表、当前参数配置
• 页面状态：加载中、加载失败、空数据、有数据
• 用户操作意图：下拉刷新、点击任务、发送消息、修改参数

在 Kuikly 里我用的状态管理方式是基于其自带的 observable 状态机制。简单说，就是把页面数据声明为可观察对象，UI 组件直接读取这些对象，数据变化时框架自动重组对应组件。关键的一点是：不要把网络请求的结果直接塞进状态，必须先转成 UI 层的数据模型。比如服务端返回的任务状态字段是RUNNING、SUCCEEDED、FAILED，UI 层不能直接拿这个字符串去渲染，而是映射成TaskStatus.RUNNING这种枚举，由 UI 层根据枚举决定显示什么颜色、什么图标、什么文案。这个映射逻辑虽然多写几行代码，但后边加状态、改展示都非常方便。

3.2 声明式 UI：从“怎么画”到“怎么表达”

Kuikly 的 UI 写法接近 Compose，我挑一个典型例子说说。任务列表的每一项，我定义了一个TaskCard组件，它接收一个TaskItemUiModel对象，根据任务状态渲染不同的背景色和角标。

@Composable fun TaskCard(task: TaskItemUiModel, onClick: (String) -> Unit) { KuiklyCard( modifier = KuiklyModifier .fillMaxWidth() .clickable { onClick(task.id) } .padding(16.dp) ) { KuiklyColumn { KuiklyText( text = task.title, style = KuiklyTextStyle( fontSize = 16.sp, fontWeight = FontWeight.Bold ) ) KuiklySpacer(height = 8.dp) KuiklyRow { TaskStatusBadge(status = task.status) KuiklySpacer(width = 12.dp) KuiklyText( text = task.costTimeLabel(), style = KuiklyTextStyle(color = Color.Gray) ) } KuiklySpacer(height = 6.dp) KuiklyText( text = task.summary, maxLines = 2, style = KuiklyTextStyle( fontSize = 14.sp, color = Color.DarkGray ) ) } } }

这种声明式的写法，最直观的好处是 UI 和状态一一对应，状态变了 UI 跟着变，不会出现“数据已经更新但界面没刷新”的问题。另一个好处是列表项的复用逻辑被收敛到了组件层面，我不用像传统原生开发那样去维护 ViewHolder 和复用逻辑。

3.3 原生能力桥接：最实用但也最容易忽略的部分

移动端壳子不是纯展示，它一定要碰原生能力，至少包括本地存储和系统分享。Kuikly 对原生能力的支持方式是通过桥接接口，在 Android 端和 iOS 端分别提供实现，上层 UI 只依赖接口定义。

我封装了几个必备的桥接能力：

• SecureStorageBridge：把 token 存在系统级安全存储中
• ClipboardBridge：一键复制任务结果或对话内容
• ShareBridge：把结果分享到其他 App
• VibratorBridge：长任务完成时轻震提醒

这里有一个经验值得分享：桥接层不要做得太薄，最好在 Kotlin 侧做一次统一封装，把双端差异尽量藏在本地。比如ShareBridge在 Android 上要处理 FileProvider 授权，在 iOS 上要处理 activity view controller 的生命周期，如果把这些逻辑暴露给 UI 层，UI 层就太脏了。我封装完之后，UI 层调用就一句话：

shareBridge.shareText("任务结果", contentText)

至于双端各自的原生实现，Android 侧写一个继承桥接接口的类，iOS 侧通过 Kuikly 提供的方式在 Swift/Kotlin 混编处接上，工作量大概是 Android 半天，iOS 一天。算下来完全可控。

4. 长连接与指令协议：移动端最不能省的两块硬骨头

任务列表这种查询型场景，走 HTTP polling 完全够用，但会话详情页要实时看到推理输出，就必须上 WebSocket。我一开始图省事，用定时器每 3 秒拉一次日志，结果发现两个问题：一是推送不及时，任务都跑完了界面还卡在“思考中”；二是流量消耗大，一个长任务跑十分钟，轮询请求能发两百多次，服务端日志里全是 GET 请求，看着就烦。后来彻底改成 WebSocket 长连接。

4.1 指令协议：让“事件”和“指令”不打架

WebSocket 不只是一个消息管道，它还需要一套明确的指令协议。我定义的协议分两层。外层是信封，包含type、requestId、timestamp三个字段；内层才是具体的消息体，根据type不同有不同的结构。

常用的消息类型我规约成七种：

• session.create：请求新建会话
• session.message：上行发送用户消息
• session.event：下行推送推理过程中的事件，比如思考开始、工具调用、文本增量输出
• session.done：本轮推理完成
• session.error：推理过程出错
• health.ping/health.pong：保活心跳
• system.config：配置变更通知

实际传输中数据还是 JSON，但有了这套类型字段，客户端处理消息时就是一个干净的 when 分支，而不是不停用 if 去猜这条消息是什么。我见过很多长连接项目死在“消息格式不统一”上，所以这层设计别人可能觉得啰嗦，但对我来说它是根基。

4.2 断线重连：不加保护的自动重连是灾难

移动端网络环境实在太恶劣，地铁隧道、电梯、地下车库，随时可能断网。我一开始写的重连逻辑很简单：断线就重连，等一秒连不上再等一秒。上线第二天就出问题了：某次服务端短暂重启，客户端进入了一个“断线-重连-握手失败-再重连”的死循环，服务端压力骤增，客户端也一直转圈。

后来我把重连策略改成了经典的指数退避 + 抖动。具体逻辑是：

• 第一次断线后等 1 秒重连
• 第二次等 2 秒
• 第三次等 4 秒
• 最大不超 60 秒
• 每次在基础等待时间上加 0 到 500 毫秒的随机抖动

为什么要加抖动？如果同时有几十个客户端在断网恢复后一起重连，不带抖动的退避算法会导致它们在同一时间发起连接，服务端瞬间被打满。加一个随机抖动，可以把连接请求在时间轴上均匀铺开。

4.3 离线缓存：让用户在没网的时候也不至于什么事都干不了

移动端和桌面端一个很大的区别是：移动端用户会频繁处于弱网甚至无网状态。我不指望没网的时候还能继续跑任务，那是服务端的事，但至少要做到两点：

• 已有的会话记录可以正常翻阅
• 用户编辑的参数和 prompt 模板可以先存在本地，等网络恢复再同步

所以我在本地做了一个轻量级缓存层，核心是 KV 存储加一个简单的 JSON 文件缓存。每次服务端返回的会话列表、任务详情、参数配置都会快照到本地；读取时先读缓存，再在后台拉取最新数据刷新。这样用户在地铁上打开 App，虽然顶部会有一个“数据可能不是最新”的提示，但界面不会白屏，体验比断网就转圈圈强太多。

5. 真机调试见真章：性能、卡顿、发热与体验调优

开发期在模拟器上跑得欢，一上真机就露馅。Kuikly 走的不是自绘渲染，而是尽量映射到原生控件，理论性能上限应该不差，但前提是开发者不要写出触发频繁变形的代码。这一节说说我在真机调试阶段做的几轮调优。

5.1 列表卡顿：罪魁祸首是“过度重组”

任务列表这个页面，数据量大的时候可能一次性加载两百多条历史任务。第一版实现里，我把整个任务列表定义成一个状态对象，只要其中任何一项更新，整个列表就全部重组。真机上的表现就是滑动列表时偶发掉帧，尤其是加载新数据的那一刻，明显卡一下。

解决思路和 Compose 一样，拆分状态、缩小重组范围。我把列表拆成两个层次：

• 列表容器只依赖List<TaskItemUiModel>本身
• 每一个TaskCard组件只依赖它自己的TaskItemUiModel

另外，给列表项加 key，让框架能识别哪些项没变，跳过不必要的重组。改完之后，滑动帧率稳定很多，加载新数据也不再打断滑动。

5.2 长文本渲染：直接 Text 会卡 UI 线程

任务结果里经常有大段大段的 JSON 输出，一个字段几万字符很常见。第一版我直接把完整文本塞给 Kuikly 的 Text 组件，真机上出现两个问题：一是首帧渲染耗时明显，二是 UI 线程在滚动时不够丝滑。

后来我采用了两个对策。第一，列表页和详情页默认只展示前 1000 个字符，末尾加“展开全文”按钮，点击后才渲染完整内容。第二，详情页完整内容改用懒加载容器，而不是直接在列表中一次性摊开。这样既保留了完整内容查看能力，又让 UI 的初始渲染量始终可控。

5.3 发热问题：WebSocket 没有自动休眠

真机测试时发现一个奇怪现象：只是挂着 App 没有操作，手机也明显发热。排查了半天，问题出在 WebSocket 没有正确的生命周期管理。App 退到后台时，我还在维持长连接并处理消息；退到后台超过一定时间，系统网络栈和 CPU 仍然在持续活动，自然发热。

修复方案是分三档：

• App 在前台：保持 WebSocket 长连接，实时接收事件
• App 退到后台 1 分钟内：关闭 WebSocket，改用后台短时任务做一次数据拉取
• App 退到后台超过 1 分钟：完全挂起，只保留本地缓存读取能力

App 回到前台时再重新建立连接并同步最新状态。这一改，发热问题基本消失。

5.4 双端细节校验：iOS 和 Android 的参数默认值不同

有一类 bug 特别坑人，就是同一个参数在两端的默认值不一样。比如分段字符串长度限制、列表最大渲染数量、键盘避让高度等。这类问题在模拟器上很难暴露，因为模拟器的键盘行为和后端设备有很大差异。

我后来立了一个规矩：所有涉及数值型的 UI 配置，一律从统一配置类读取，禁止在组件内部写死数值。配置类里区分 Android 和 iOS 的环境分支，但业务逻辑只读配置结果。这个习惯帮我在后续适配平板、折叠屏时省了很多事。

6. 这次改造里我印象最深的四个坑

最后说说这次项目里真正浪费过我时间的地方。这些坑不看日志根本查不出来，希望后面有人用 Kuikly 做类似项目时能直接绕开。

**坑一：Kuikly 的热更新在 iOS 上偶尔会失效。**开发期我用热更新来快速调 UI，Android 上一切正常，同一个改动切到 iOS 模拟器，页面经常还是旧的。一开始以为是构建缓存问题，清了 N 次缓存无果。后来去翻框架文档，注意到 Kuikly 的 iOS 热更新对工程配置有一定要求，缺少某个构建阶段脚本时热更新不会生效，但不报任何错误。解决方式是把 iOS 热更新依赖的编译脚本补上，之后才正常。这个坑我花了一个下午才定位到，如果你也是第一次在 iOS 上跑 Kuikly，遇到“改了代码没反应”的情况，先检查这一步。

**坑二：键盘弹起后的布局避让。**聊天页面里，输入框和消息列表的联动非常考验声明式框架的熟练度。第一版我只是简单地在键盘弹起时给消息列表加一个底部 padding，实测在 Android 上没问题，iOS 上偶尔会出现输入框被键盘遮挡。后来在 Kuikly 里正确接入了键盘高度监听，并在消息列表滚动到底部时做平滑滚动，问题才彻底解决。如果你要做聊天类界面，这步别省。

**坑三：WebSocket 消息顺序错乱。**有一阵子会话详情页偶尔出现“一条消息没说完就开始下一条”的错觉，排查发现不是 Kuikly 的问题，而是服务端推送消息时没有保证同一条会话消息在同一个连接上下文中的顺序，个别事件走了不同的发送通道，导致先发的后到。最终在服务端做了一层有序队列，这个现象才消失。这个经验说给搞客户端的朋友听，他们第一反应都是客户端问题，其实这种顺序错乱很多时候在服务端处理并发时更容易发生。

**坑四：发布前务必做“弱网+断网恢复”全流程测试。**别只在 WiFi 环境下测。我在小区电梯里实测过一次，走完整个“断网-重连-恢复”流程后，发现有一个边缘分支会让会话页一直停在“重连中”，必须杀掉进程才能恢复。后来加了一个 10 秒超时保护，超过 10 秒还在重连就重置连接状态并提示用户手动重试。这个保护逻辑不复杂，但没有真实弱网环境测试根本发现不了。

这次改造做下来，最大的体会是：工具链的价值在于让模型能力更顺手，而移动端壳子的价值在于把这种顺手延伸到任何场景。如果你也想在手机上跑 Harness 的管理界面，Kuikly 这套路子是走得通的，但记得把服务端接口设计、指令协议、断线策略、离线缓存这些底座先打牢，UI 只是最后一层糖衣。