企业官网建设流程全解析

1. 为什么拿 Android 登录模块来搭 Agent 开发环境

第一次听到“用 Android 登录模块搭 Agent 开发环境”这个组合，很多人会觉得这俩东西八竿子打不着。一个是移动端 UI 层的账号体系，一个是当下最热的大模型智能体工程。但真在一线写过 Agent 项目的人会明白，登录模块恰好是一个天然的、边界清晰的、带状态流转的“微型 Agent 场景”：它有输入（账号密码/验证码）、有决策分支（本地校验、远程校验、风控拦截）、有工具调用（网络请求、本地存储、生物识别）、有失败重试、有超时兜底、有状态机。你把这套东西跑通，Agent 开发里 80% 的工程问题——状态管理、异步编排、错误恢复、可观测性——都能在同一个代码库里练一遍。

我这次选的是Harness作为 Agent 编排层，Kotlin + Jetpack Compose作为 Android 侧的实现语言和 UI 框架。Harness 这个词在 Agent 圈子里最近被讨论得很多，核心思路是把 Agent 的“执行骨架”和“业务逻辑”解耦：骨架负责调度、重试、上下文传递、工具注册，业务逻辑只关心“这一步该干什么”。这跟 Android 里把 UI 和 ViewModel 拆开是一个道理。用登录模块来练手的好处是，业务逻辑足够简单，你能把注意力全放在 Harness 的编排机制上，而不是被复杂的业务规则带偏。

这篇文章适合三类人看：一是写过 Android 但没碰过 Agent 的，想找个熟悉的场景切入；二是搞过 Agent 但工程化经验不足的，想知道怎么把 Agent 塞进一个真实 App 里；三是纯粹想学 Kotlin 协程和 Compose 状态管理的，登录模块本身就是个绝佳练习场。全文我会按“设计思路 → 核心细节 → 实操落地 → 踩坑排查”的顺序展开，每一步都给出可复现的代码和参数，你照着抄就能跑起来。

提示：本文所有代码基于 Kotlin 1.9+、Compose BOM 2024 以上版本、Harness 编排层采用通用 Agent 骨架思路实现，不依赖任何特定厂商 SDK，你可以自由替换成自己团队的技术栈。

2. 整体架构设计与技术选型拆解

2.1 为什么是 Harness 而不是裸写协程

很多人第一反应是：登录逻辑我用viewModelScope.launch加几个suspend函数不就搞定了，为什么要引入 Harness 这一层？我一开始也是这么想的，直到登录流程里出现了这些需求：验证码发送失败要退避重试、密码错误三次要触发风控、网络超时要降级到离线缓存校验、生物识别失败要回退到密码登录。这些分支如果全写在 ViewModel 里，很快就会变成一坨if-else嵌套地狱，而且每个分支的重试逻辑都要重写一遍。

Harness 的价值就在于把这些“横切关注点”抽出来。它的核心抽象是Step（步骤）和Runner（执行器）。一个 Step 定义“做什么”和“失败了怎么办”，Runner 负责按顺序执行、处理重试、传递上下文。这跟 Android 里的 WorkManager 思路很像，但更轻量，而且天然支持挂起函数。

选 Harness 的另一个理由是可测试性。登录流程里最烦的就是“验证码发送失败”这种分支，裸写的话你得 mock 网络层、mock 计时器。用 Harness 之后，每个 Step 都是独立的类，你可以单独测它的execute和onFailure，Runner 的调度逻辑也能用假 Step 来验证。

2.2 Kotlin 协程与 Compose 的配合方式

Android 侧我用的是Kotlin 协程 + StateFlow + Jetpack Compose这套组合。协程负责异步，StateFlow 负责状态暴露，Compose 负责根据状态渲染 UI。这三者的关系可以这样理解：Harness 的 Runner 跑在viewModelScope里，每完成一个 Step 就更新一次 StateFlow，Compose 监听到变化就重组界面。

这里有个关键决策：登录状态到底放在 ViewModel 还是放在 Harness 的 Context 里。我的做法是两者都放，但职责不同。Harness Context 里放的是“流程内部状态”，比如当前重试次数、上次错误码、验证码倒计时；ViewModel 的 StateFlow 里放的是“UI 可见状态”，比如按钮是否可点、进度条是否显示、错误文案是什么。这样做的原因是，流程内部状态变化频率高，全部暴露给 UI 会导致过度重组；而 UI 状态需要稳定，不能因为一次内部重试就闪一下。

2.3 模块划分与依赖关系

整个项目我拆成四个模块，依赖关系是单向的，避免循环引用：

• core-harness：Agent 编排骨架，包含 Step、Runner、Context、RetryPolicy，纯 Kotlin 模块，不依赖 Android。
• feature-login：登录业务逻辑，包含各个 Step 的实现、LoginViewModel、Compose 界面。
• >interface Step<I, O> { val name: String suspend fun execute(input: I, context: AgentContext): O fun onFailure(error: Throwable, context: AgentContext): FailureStrategy }

  execute是核心逻辑，onFailure决定失败后怎么办。FailureStrategy是个密封类，有三个分支：Retry（重试）、Fallback（降级到备用逻辑）、Abort（终止流程）。这样设计的原因是，不同 Step 的失败处理策略完全不同。比如“发送验证码”失败应该重试，“校验密码”失败应该直接 Abort 并提示用户，“读取本地缓存”失败应该 Fallback 到空值。

  AgentContext是个可变的上下文对象，内部用ConcurrentHashMap存数据，因为多个 Step 可能并发执行。它提供get、put、getOrPut等方法，还内置了一个traceId用于全链路追踪。

  注意：AgentContext不要存大对象，比如 Bitmap 或者大 List。它应该只存轻量的状态数据，大对象走专门的 Repository。我踩过的坑是把用户头像的 ByteArray 塞进 Context，结果内存抖动明显。

  3.2 登录流程的 Step 拆解

  登录流程我拆成六个 Step，顺序执行，但中间有分支：

  1. ValidateInputStep：校验账号密码格式，本地完成，不涉及网络。
  2. CheckLocalCacheStep：查本地是否有有效 token，有则跳过后续直接成功。
  3. SendVerifyCodeStep：如果需要验证码，发送验证码，带重试。
  4. VerifyCodeStep：校验用户输入的验证码。
  5. RemoteLoginStep：调用登录接口，带重试和超时。
  6. PersistTokenStep：把 token 加密存储到本地。

  每个 Step 的输入输出类型要明确。比如SendVerifyCodeStep输入是手机号，输出是SendResult（包含是否成功、倒计时秒数）。这样类型安全，编译期就能发现参数传错的问题。

  3.3 重试策略的参数计算

  重试不是简单粗暴地循环。我用的是指数退避 + 抖动策略。基础延迟 1 秒，每次翻倍，最大 8 秒，再加 0~500ms 的随机抖动。为什么要加抖动？因为如果多个用户同时失败重试，没有抖动的话会在同一时刻集中请求，给服务端造成脉冲压力。

  计算公式是：delay = min(baseDelay * 2^attempt, maxDelay) + random(0, jitter)。以 attempt 从 0 开始算：

  重试次数	基础延迟	加抖动后范围
  第 1 次	1s	1.0s ~ 1.5s
  第 2 次	2s	2.0s ~ 2.5s
  第 3 次	4s	4.0s ~ 4.5s
  第 4 次	8s	8.0s ~ 8.5s

  超过 4 次就 Abort，提示用户“网络异常，请稍后重试”。这个参数不是拍脑袋定的，我实测下来，移动网络下 4 次重试覆盖了 95% 的临时故障，再多重试用户等待时间就太长了。

  3.4 Compose 状态管理与重组优化

  Compose 这边最容易踩的坑是过度重组。登录界面有个倒计时按钮，如果倒计时状态和输入框状态放在同一个 StateFlow 里，每秒倒计时都会导致整个界面重组。我的做法是拆成多个独立的 StateFlow：

  val inputState: StateFlow<InputState> val countdownState: StateFlow<Int> val loadingState: StateFlow<Boolean> val errorState: StateFlow<String?>

  然后在 Compose 里用collectAsStateWithLifecycle分别订阅。这样倒计时变化只重组按钮，不影响输入框。另外，InputState用data class并重写equals，避免内容没变也触发重组。

  提示：collectAsStateWithLifecycle比collectAsState更适合 Android，因为它会在界面不可见时自动停止收集，省电省内存。

  4. 完整实操流程与关键环节实现

  4.1 环境准备与依赖配置

  先把项目骨架搭起来。Android Studio 新建项目选 Empty Compose Activity，包名随意。然后在gradle/libs.versions.toml里加依赖：

  [versions] kotlin = "1.9.22" composeBom = "2024.02.00" coroutines = "1.8.0" lifecycle = "2.7.0" [libraries] coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" } coroutines-android = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-android", version.ref = "coroutines" } lifecycle-viewmodel-compose = { module = "androidx.lifecycle:lifecycle-viewmodel-compose", version.ref = "lifecycle" } lifecycle-runtime-compose = { module = "androidx.lifecycle:lifecycle-runtime-compose", version.ref = "lifecycle" }

  lifecycle-runtime-compose是必须的，它提供collectAsStateWithLifecycle。协程版本别用太老的，1.7 以下在 Compose 里有些挂起函数的行为不一致。

  4.2 Harness Runner 的核心实现

  Runner 的职责是按顺序执行 Step，处理失败策略。核心代码如下：

  class AgentRunner(private val steps: List<Step<Any, Any>>) { suspend fun run(context: AgentContext): RunResult { for (step in steps) { var attempt = 0 while (true) { try { val input = context.get<Any>(step.name + "_input") ?: Unit val output = step.execute(input, context) context.put(step.name + "_output", output) break } catch (e: Throwable) { when (val strategy = step.onFailure(e, context)) { is FailureStrategy.Retry -> { if (attempt >= strategy.maxAttempt) return RunResult.Failed(e) val delay = calculateDelay(attempt, strategy) delay(delay) attempt++ } is FailureStrategy.Fallback -> { context.put(step.name + "_output", strategy.fallbackValue) break } is FailureStrategy.Abort -> return RunResult.Failed(e) } } } } return RunResult.Success(context) } }

  这里有个细节：context.get<Any>(step.name + "_input")用 Step 名字做 key 前缀，避免不同 Step 的输入输出互相覆盖。实际项目里我会用更严格的类型化 Context，但为了演示清晰，这里用字符串 key。

  4.3 登录 ViewModel 的组装

  ViewModel 负责把 Runner 和 UI 状态连起来：

  class LoginViewModel( private val runner: AgentRunner, private val context: AgentContext ) : ViewModel() { private val _loadingState = MutableStateFlow(false) val loadingState: StateFlow<Boolean> = _loadingState.asStateFlow() private val _errorState = MutableStateFlow<String?>(null) val errorState: StateFlow<String?> = _errorState.asStateFlow() fun login(account: String, password: String) { viewModelScope.launch { _loadingState.value = true _errorState.value = null context.put("account", account) context.put("password", password) when (val result = runner.run(context)) { is RunResult.Success -> { /* 导航到主页 */ } is RunResult.Failed -> { _errorState.value = mapErrorToMessage(result.error) } } _loadingState.value = false } } }

  mapErrorToMessage把异常类型映射成用户能看懂的文案。比如TimeoutException映射成“网络超时，请检查网络”，AuthException映射成“账号或密码错误”。这个映射表要维护好，别直接把异常堆栈丢给用户看。

  4.4 Compose 登录界面的实现

  界面部分用 Compose 写，重点是状态订阅和输入处理：

  @Composable fun LoginScreen(viewModel: LoginViewModel) { val loading by viewModel.loadingState.collectAsStateWithLifecycle() val error by viewModel.errorState.collectAsStateWithLifecycle() var account by remember { mutableStateOf("") } var password by remember { mutableStateOf("") } Column(modifier = Modifier.fillMaxSize().padding(24.dp)) { OutlinedTextField( value = account, onValueChange = { account = it }, label = { Text("账号") }, singleLine = true ) Spacer(Modifier.height(16.dp)) OutlinedTextField( value = password, onValueChange = { password = it }, label = { Text("密码") }, visualTransformation = PasswordVisualTransformation(), singleLine = true ) Spacer(Modifier.height(24.dp)) Button( onClick = { viewModel.login(account, password) }, enabled = !loading && account.isNotBlank() && password.isNotBlank() ) { if (loading) CircularProgressIndicator(modifier = Modifier.size(20.dp)) else Text("登录") } error?.let { Spacer(Modifier.height(12.dp)) Text(it, color = MaterialTheme.colorScheme.error) } } }

  remember { mutableStateOf("") }是 Compose 里管理输入框状态的标准做法。注意enabled条件里加了!loading，防止用户重复点击。进度条用CircularProgressIndicator，尺寸设成 20dp 放在按钮里，比整页 loading 体验好。

  4.5 本地 Token 加密存储

  登录成功后 token 要存本地，但不能明文存。我用的是 Android Keystore + AES-GCM 加密：

  object TokenStore { private const val KEY_ALIAS = "login_token_key" private const val PREF_NAME = "auth_prefs" private const val TOKEN_KEY = "encrypted_token" fun save(context: Context, token: String) { val key = getOrCreateKey() val cipher = Cipher.getInstance("AES/GCM/NoPadding") cipher.init(Cipher.ENCRYPT_MODE, key) val iv = cipher.iv val encrypted = cipher.doFinal(token.toByteArray()) val combined = iv + encrypted context.getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE) .edit() .putString(TOKEN_KEY, Base64.encodeToString(combined, Base64.NO_WRAP)) .apply() } }

  IV 要跟密文一起存，解密时先取前 12 字节作为 IV。AES-GCM 的 IV 长度固定 12 字节，这是规范。别用 ECB 模式，那个不安全。

  5. 常见问题与排查技巧实录

  5.1 Harness 插件加载失败的排查

  热词里有个“harness failed to load plugins”，这个我实际遇到过。表现是启动时日志报2 entries did not activate，插件没生效。排查思路分三步：先看插件描述文件里的activation条件是否满足，比如依赖的类是否存在；再看类加载器是否隔离，插件和主程序用了不同的 ClassLoader 会导致类找不到；最后看版本兼容性，插件编译时的 API 版本和运行时不一致也会静默失败。

  我的解决办法是在 Runner 初始化时加一个PluginValidator，启动时主动检查每个插件的isActive状态，不满足就打印具体原因。别等到运行时才发现插件没加载。

  5.2 协程回调转挂起的常见坑

  Android 里很多老 API 是回调式的，比如BluetoothGattCallback。转成挂起函数时最容易踩的坑是回调可能被调用多次。比如连接失败回调可能触发两次，如果你用suspendCancellableCoroutine没做保护，第二次resume会抛IllegalStateException。

  正确做法是用AtomicBoolean标记是否已经 resume：

  suspend fun connect(): Boolean = suspendCancellableCoroutine { cont -> val resumed = AtomicBoolean(false) callback = object : Callback { override fun onSuccess() { if (resumed.compareAndSet(false, true)) cont.resume(true) } override fun onFailure(e: Throwable) { if (resumed.compareAndSet(false, true)) cont.resumeWithException(e) } } }

  这个模式我封装成了一个工具类，所有回调转挂起的地方都用它，省得每次重写。

  5.3 Compose 重组导致的倒计时闪烁

  倒计时按钮如果直接在 Composable 里用LaunchedEffect加delay循环，界面旋转或者后台切回来时倒计时会重置。原因是LaunchedEffect的 key 变了会重启协程。解决办法是把倒计时状态提到 ViewModel 里，用StateFlow<Int>暴露，Composable 只负责显示。ViewModel 的生命周期比 Composable 长，旋转屏幕不会丢状态。

  5.4 常见问题速查表

  问题现象	可能原因	排查方法	解决方案
  登录按钮点击无反应	loading 状态未重置	检查 finally 块	用 try-finally 确保重置
  验证码倒计时重置	LaunchedEffect key 变化	看 key 是否含可变值	状态提到 ViewModel
  Token 解密失败	IV 长度不对	打印 IV 字节数	固定取前 12 字节
  重试次数超预期	多个 Step 共享 attempt	检查 attempt 作用域	attempt 放在 while 内
  Compose 界面卡顿	过度重组	用 Layout Inspector	拆分 StateFlow

  注意：Layout Inspector是排查重组问题的利器，能看到每个 Composable 的重组次数。重组次数异常高的地方就是优化点。

  6. 从登录模块扩展到通用 Agent 场景

  登录模块跑通之后，这套 Harness 骨架可以直接复用到其他场景。比如注册流程，无非是把 Step 换成“校验手机号 → 发送验证码 → 校验验证码 → 设置密码 → 创建账号”，Runner 和 Context 完全不用改。再比如实名认证流程，Step 换成“上传身份证 → OCR 识别 → 人脸比对 → 提交审核”，也是一样的套路。

  我实际项目里还用它做过“订单提交”流程，Step 包括“校验库存 → 计算优惠 → 创建订单 → 发起支付 → 更新状态”。每个 Step 独立测试，失败策略单独配置，比原来写在一个方法里清晰太多。关键是要把 Step 的粒度控制好，太粗了复用性差，太细了调度开销大。我的经验是一个 Step 对应一个明确的业务动作，执行时间在 100ms 到 3 秒之间比较合适。

  另外，Harness 的 Context 可以扩展成支持持久化，这样流程中断后能恢复。比如用户登录到一半接了个电话，回来还能继续。这个功能在长流程场景里很有用，实现思路是把 Context 序列化到本地，恢复时反序列化回来。不过要注意 Context 里不能存不可序列化的对象。

  最后分享一个我踩过的坑：别在 Step 里直接操作 UI。Step 应该只返回数据，UI 更新交给 ViewModel 的 StateFlow。我一开始图省事在 Step 里弹 Toast，结果测试时根本没法断言，而且 Step 和 Android 框架耦合了，没法在纯 JVM 环境跑单元测试。解耦之后，所有 Step 都能用runTest快速验证，测试速度从分钟级降到秒级。