端侧Agent工程化实战：从架构设计到稳定性优化

1. 端侧 Agent 工程化：先想清楚边界，再谈落地

做端侧 Agent 有一个很容易踩的坑：一上来就奔着"智能"去，把大模型塞进设备里，然后就开始堆功能。结果跑起来之后发现，模型在云端表现不错，到了端上各种抽风——响应慢、内存爆、上下文乱、工具调用不稳定。然后就开始怀疑是模型的问题，其实大概率不是模型的问题，是工程化没做到位。

我接触端侧 Agent 有三四年的时间了，从最早的实验性项目，到后来在真实产品里落地，最大的感受是：端侧 Agent 和云端 Agent 的工程化难度不在一个量级。云端你有一整个机房的资源可以调度，端侧只有一块小小的芯片、有限的内存、不可控的网络环境，还有用户随时可能锁屏、切后台、杀进程。这一个"端"字，把很多在云端稀松平常的事情变成了挑战。

这篇文章是"深入理解端侧 Agent"系列的一部分，主要讲工程化的前半程：从整体设计思路、核心模块拆解，到实际编码过程中会遇到的问题和解决方案。适合两类人看：一类是把 Agent 放到真实设备上、正被性能或稳定性问题折磨的开发者；另一类是准备做端侧 Agent 但还没想清楚架构、希望少走弯路的同学。

先说结论：端侧 Agent 工程化，本质上不是"把模型跑起来"的问题，而是"把智能体系统在资源受限环境下稳定运行"的问题。模型推理只是其中一环，更麻烦的是整个系统的编排、上下文管理、工具调用、并发控制和错误恢复。

2. 端侧 Agent 的系统架构：harness 与 agent 的边界划分

2.1 从"模型封装"到"智能体系统"的转变

很多初学者对 Agent 的理解还停留在"调用模型 API"的阶段。但真正的 Agent 是一个系统，它需要感知环境、做出决策、调用工具、观察结果、迭代执行。这里面每一个环节都需要工程化的支撑。

我早期做过一个失败的项目，当时把 Agent 简单封装成了"模型调用 + 工具函数的集合"，看起来架构很清晰：模型决定调用哪个工具，工具返回结果，模型再继续推理。但实际跑起来问题层出不穷。最典型的一个场景：用户说了一句带有歧义的话，模型需要澄清，但我们的架构里没有设计"询问用户"这个能力，于是模型就在那里自说自话，最后给出一个完全错误的结果。

后来我意识到，Agent 不是一个函数，它是一个循环。这个循环里有几个关键步骤：理解输入、规划行动、调用工具、观察结果、修正计划。这个循环的每一环都有大量的边缘情况需要处理，而工程化的核心就是把边缘情况变成确定性逻辑。

2.2 harness 与 agent 的核心职责划分

关于 harness 和 agent 的区别，我见过很多不同的理解。有人觉得 harness 就是工具调用的封装层，有人觉得 harness 是 Agent 运行时的代名词。根据我的实践经验，比较清晰的定义是：

Agent是智能决策中枢，负责理解任务、拆解步骤、选择策略。它本质上是一个基于大模型的推理循环，核心能力是"思考"。

Harness是承载 Agent 运行的环境和框架，负责管理上下文窗口、调度工具执行、控制循环迭代、处理错误和中断。它解决的是"让 Agent 能稳定跑起来"的问题。

做一个类比可能更容易理解：Agent 像是司机，harness 是汽车。司机负责判断路线、决定怎么开，汽车负责提供动力、转向、刹车，以及保证行驶安全。司机再厉害，汽车本身如果刹车不灵、方向盘有虚位，也会出事。

在实际工程中，harness 和 agent 的边界经常被模糊。比如有些框架把上下文管理放进了 agent 里，让 agent 自己决定保留哪些历史消息。这在简单场景下没问题，但一旦上下文超过模型窗口，agent 的决策能力会明显下降，因为它自己也不知道该丢哪些信息。正确的做法是把上下文管理从 agent 中剥离出来，交给 harness 处理，用确定性的策略来管理，而不是让模型来做这个决定。

2.3 端侧环境对架构的特殊约束

端侧和云端最大的区别是资源边界非常硬。云端 CPU 不够可以扩容，内存不够可以加节点，端侧做不到。所以端侧 Agent 的架构设计从一开始就要考虑资源预算，而不是事后优化。

我整理过一份端侧 Agent 的资源分配清单，大体是这样：

这套约束下来，端侧 Agent 的架构风格会和云端明显不同。云端 Agent 喜欢"有多少工具就用多少工具，有多少上下文就装多少上下文"，端侧 Agent 必须做减法：少即是多。

我在设计端侧 Agent 架构时，会遵循三个核心原则：确定性优先于智能性，本地优先于网络，缓存优先于计算。不确定的逻辑交给模型，确定的逻辑交给代码；能本地处理的绝不上云，能预计算缓存结果的绝不重复推理。

3. 核心模块拆解：编排、记忆、工具调用三件套

3.1 编排引擎：Agent 循环的控制中枢

编排引擎是整个 Agent 系统的心脏。它负责维护 Agent 的运行循环，决定下一步该做什么。一个完整的 Agent 循环包括：

1. 接收用户输入，追加到上下文
2. 调用模型进行推理，得到响应
3. 解析响应，判断是最终答案还是工具调用请求
4. 如果是工具调用，执行工具，将结果追加到上下文
5. 回到第 2 步，继续推理，直到得到最终答案或达到最大迭代次数

看起来简单，实际落地时每个环节都有坑。最大的坑在步骤 3：模型返回的工具调用请求是 JSON 格式，但这个 JSON 有时候会不合法。模型在生成长文本时，偶尔会在 JSON 里加一些额外的逗号、缺一个引号、或者干脆截断了。云端 Agent 遇到这种情况可以直接让模型重新生成，端侧 Agent 不行，因为重新推理的成本太高了。

我在编排引擎里加了一个轻量的 JSON 修复层，专门处理模型输出的 JSON 格式问题。比如补全缺失的引号、删除多余逗号、截断补齐等。这些听起来像是不起眼的小功能，但实际效果非常明显，能把工具调用的成功率从 80% 提升到 95% 以上。

另一个关键设计是循环控制的退出条件。云端 Agent 可以把最大迭代次数设置到 20 次甚至更多，端侧不行。每次迭代都是时间和电量的消耗，用户不会等你的 Agent 思考 20 轮。我通常会把最大迭代次数控制在 5-8 次以内，超过次数直接返回当前已获得的最佳结果，同时用文本告诉用户"由于复杂度限制，当前回答可能不是最完整的，请尝试更具体的描述"。

3.2 上下文管理：在有限窗口里做出最优取舍

上下文管理是端侧 Agent 工程化里最容易被低估的模块。很多人以为上下文管理就是"把历史消息拼起来发给模型"，但实际情况要复杂得多。

先说窗口的问题。端侧模型通常只有 4K-8K 的上下文窗口，这意味着在单轮对话中你能提供给模型的信息非常有限。一个典型的工具调用过程，工具返回的结果可能要几百到上千 token，几轮工具调用下来，上下文就满了。

解决思路是分层的：核心指令永远保留，历史对话可以压缩，工具结果只保留关键部分。我会把上下文分成三层来管理：

第一层是系统提示词和核心指令，这部分是不可压缩的，直接固定在上下文的最前面。第二层是最近几轮对话，保留完整信息，因为这通常是当前任务的焦点。第三层是更早的历史对话和工具调用记录，这类信息可以用摘要的方式压缩后保留。

摘要压缩是我踩过很多坑之后才做对的事情。早期我用模型来压缩对话（用一个小模型对历史信息做总结），效果好但消耗大。后来改成了规则 + 抽取的方式：保留用户消息中的关键词和关键实体，保留工具调用的参数和结果摘要，丢弃推理过程等噪声内容。

特别提醒一下：不要让 Agent 自己决定保留哪些历史信息。模型倾向于保留所有信息"以防万一"，结果很快就把上下文窗口占满了。上下文裁剪必须是一个确定性的策略，由 harness 来控制，不交给模型决策。

3.3 工具调用的端侧实现：从函数注册到结果过滤

工具调用模块在云端 Agent 里相对简单——定义函数 schema，模型返回函数名和参数，系统调用对应的函数。但端侧有一个明显的痛点：模型的工具调用格式不稳定。

云端用 GPT-4 或 Claude，工具的 JSON 输出格式基本不会出错。但端侧模型，尤其是小参数模型，经常出现格式错误、参数缺失、幻觉函数名等问题。我在早期项目里，有差不多五分之一的工具调用是失败的，原因全是格式问题，而不是模型理解错了。

后来我摸索出一套比较完整的做法：

第一，工具注册时要做充分的 schema 定义，每个参数都要写清楚类型、范围、默认值，并在描述里注明"如果该参数不确定可以省略"。这样做是为了给模型减负，提供尽量多的辅助信息。

第二，工具调用要做一层参数校验和修复。模型返回的参数可以先走一层规则逻辑：检查必填参数是否存在，检查参数类型是否匹配，检查参数范围是否合法。不合法时优先尝试自动修复（比如把字符串转成数字），修复不了再返回错误信息让模型重新生成。

第三，工具结果要做裁剪和提取。工具返回的结果往往包含大量不需要的信息，直接塞进上下文会浪费窗口。我会给每个工具定义一个"结果过滤器"，只保留任务相关的字段。比如一个查天气的工具，可能接口返回了 30 个字段，但模型只需要温度和降水概率两个，过滤器直接提取这两个字段返回。

3.4 记忆模块：短期记忆与长期记忆的互补设计

Agent 的记忆系统是"智能感"的重要来源。没有记忆的 Agent 每次对话都是从零开始，用户体验很割裂。有记忆但不会管理的 Agent，上下文很快被占满，效果反而更差。

我通常会把记忆拆成两层：短期记忆覆盖当前会话，长期记忆跨会话持久化。

短期记忆的核心是相关性管理。我维护一个滑动窗口，最新的对话永远是最优先保留的。当窗口满了，就触发一次记忆整合，把旧信息压缩成摘要存到长期记忆里。这个整合过程可以用规则做，也可以用一次小模型的推理来做，取决于你对实时性的要求。

长期记忆的存储有两种选择：向量数据库和结构化存储。向量数据库适合做语义检索，结构化存储（比如 SQLite 或 JSON 文件）适合做精确匹配。我个人的建议是：能用结构化存储解决的问题就不要上向量数据库，原因很简单——端侧资源有限，向量索引的内存占用和检索耗时会随着数据量增长，而大部分场景实际上只需要简单的键值对查找。

举一个实际场景：用户经常问"上次我说要在周末去爬山，帮我看看天气"。这种需求需要记住"上周末聊过爬山这个话题"，用结构化存储直接存一个 { 主题：爬山，时间：上周末，地点：城郊 } 的表就能覆盖，不需要向量检索。只有面对"帮我找找之前聊过的跟创意相关的所有内容"这种模糊需求时，向量检索才更有价值。

4. 并发与稳定性：端侧 Agent 如何扛住压力

4.1 端侧 Agent 的"并发"到底指什么

先要澄清一个概念：端侧 Agent 的并发和云端 Agent 的并发不是一回事。云端并发是大量用户同时请求你的服务，考验的是服务器的负载能力；端侧并发是一个用户在同一台设备上，可能同时触发多个任务，考验的是设备本地资源的调度能力。

举个具体例子：用户在手机上打开一个 Agent 应用，正在和 Agent 对话，这时候突然来了一个通知，Agent 需要在后台处理通知相关的任务。或者，用户在 Agent 应用里运行着一个长任务（比如让 Agent 帮忙整理文档），同时又发起了另一个对话。这些场景构成了端侧 Agent 的并发压力。

端侧算力有限，很难做到真正的多任务并行推理。解决办法是任务队列 + 优先级调度。我把任务分成三类：

• 高优先级：用户正在交互的任务，需要立即响应，抢占所有资源
• 中优先级：用户期待但可以稍等的任务（比如"帮我把这些图片分类"），可以后台执行
• 低优先级：系统后台任务（比如记忆整理、数据同步），只在系统空闲时执行

任务队列的调度策略也很简单：高优先级任务直接抢占，中优先级任务排队轮流执行，低优先级任务执行前先检查当前系统的负载，如果 CPU 占用超过 60% 就暂停，等系统空闲时再恢复。

4.2 推理并发与模型调用的串行化处理

端侧模型推理目前基本是串行的，尤其是在 CPU 或 NPU 上运行小模型时，并发推理很难做到。但这不代表没有办法优化。

我试过的最有效的方案是推理请求合并。当多个任务同时需要模型推理时，不立即执行，而是聚合等待一个极小的时间窗（通常 100-200 毫秒），在这段时间内到达的所有推理请求合并成一次推理。这听起来有点反直觉，但实际效果很好：模型一次推理的成本远低于多次推理的成本之和，而且 100 毫秒的延迟在用户感知上几乎无感。

另一个优化点是推理结果缓存。端侧 Agent 经常会遇到相似的请求——用户用不同的措辞问同一个问题，或者在不同的对话中触发相同的工具调用。我会对推理请求做语义级别的缓存：先计算请求的嵌入向量，然后和缓存中的历史请求做相似度匹配，相似度超过阈值（通常 0.85-0.9）就直接返回缓存的结果，不调用模型。

这个方案踩过一个坑：缓存结果如果包含工具调用指令，直接返回会导致工具被重复执行或者执行结果和当前状态不匹配。后来我在缓存设计里加了规则：含有工具调用的响应不做缓存，只缓存纯文本回答的响应。

4.3 错误恢复机制：Agent 崩溃后怎么办

端侧 Agent 的系统崩溃是必然的，不是你代码写得好就能避免。用户切换应用、系统杀后台、内存告警、电池低电量，各种情况都会导致 Agent 进程被中断。云端 Agent 挂了大不了重试，端侧 Agent 挂了你不能要求用户重新把需求说一遍。

所以错误恢复机制是端侧 Agent 工程化的必备模块。我的做法是会话持久化 + 状态重建：

在 Agent 运行的每个关键步骤结束时，把当前状态序列化存储到本地。状态信息包括：当前任务描述、执行的步骤清单、每一步的执行结果、上下文压缩摘要、未完成的计划。这样即使 Agent 进程被杀，下次启动时也可以从最近的状态点恢复。

恢复时的策略是：如果恢复点在任务开始前（用户输入刚接收，还没执行任何步骤），直接重新开始；如果恢复点在任务执行中（部分步骤已完成），不从头执行，而是基于已完成的结果继续后续步骤；如果恢复点在任务结束时（结果已经生成），直接返回缓存的结果。

这个机制有一个值得注意的细节：状态恢复后要做一次上下文一致性校验。因为 Agent 可能依赖了真实世界的信息（比如读取了某个文件的内容），恢复时如果文件已经变了，要继续执行就会出错。处理方式是给每个工具调用记录一个"输入摘要"，恢复时比对当前输入是否和摘要一致，不一致就要求用户确认或重新执行该步骤。

4.4 Agent 安全的端侧实现：权限控制与数据最小化

端侧 Agent 的安全问题经常被忽略，但实际很重要。Agent 在你的设备上运行，它能访问你的文件、通讯录、应用数据，如果被恶意利用，后果比云端泄露更严重。

我的安全策略是权限最小化 + 动态授权。Agent 启动时不持有任何敏感资源的访问权限，当它需要访问某个资源时，先向用户发出一个授权请求，说明访问目的和使用的数据范围。用户授权后，权限只在当前任务内有效，任务结束后立即收回。

工具调用层也需要做安全过滤。我给每个工具定义了安全级别：

L3 级的工具需要特别注意。Agent 可能会被 prompt injection 攻击——用户在某个网页里藏了一段恶意指令，你的 Agent 读取网页内容后，被里面的指令诱导执行了不该执行的操作。这是我很早就意识到的问题，所以端侧 Agent 执行网络操作前必须有用户的明确确认，不能静默操作。

5. 实操记录：一个端侧 Agent 的工程实现过程

5.1 项目背景与基础配置

为了不空谈理论，我用一个实际项目来展示端侧 Agent 工程化的完整过程。项目背景是做一个移动端助理应用，用户可以用自然语言让手机执行一些本地操作：查天气、定闹钟、打开应用、发短信等。模型使用的是端侧部署的 3B 参数小模型，推理框架用的是本地的 LLM 运行时，系统环境是 Android 设备。

关键配置参数大致如下：

• 模型：3B 参数，4-bit 量化，上下文窗口 8K
• 推理后端：本地 NPU 加速，支持流式输出
• 设备内存要求：Agent 运行时占用控制在 300MB 以内
• 最大迭代轮数：6 轮
• 工具数量：初始版本注册 12 个工具

这个配置比较保守，但保证了在老设备上也能流畅运行。如果你的目标设备较新，可以适当上调模型参数或上下文窗口。

5.2 从零搭建 Agent 运行框架的步骤

我逐步讲解搭建过程。这里不是完整的源码，而是核心逻辑的骨架和关键决策的解释。

第一步：定义工具接口和注册机制

工具在 Agent 系统里是标准化的接口，每个工具需要实现以下内容：

工具名称（唯一标识） 工具描述（给模型看的，说明这个工具能做什么、什么时候用） 参数定义（JSON Schema） 执行函数（接收参数，返回结果） 安全级别（对应权限控制） 结果过滤器（提取返回信息中的关键部分）

工具注册发生在 Agent 启动时，系统会收集所有可用工具的 schema，拼接成工具定义文本，放入系统提示词中。模型只有在工具定义文本里看到的工具才可能被调用，所以工具的"描述"写得清不清楚，直接决定了模型能不能正确选择工具。

第二步：建立上下文管理模块

我实现了一个简单的上下文管理类，负责维护完整的对话历史。它对外提供三个操作：插入用户输入、插入模型输出、插入工具结果；内部负责维护一个循环缓冲区，并实时监控 token 占用情况。

上下文管理的核心逻辑是"水位线"机制。定义一个高水位（比如 7000 token）和一个低水位（比如 4000 token）。当 token 占用超过高水位时，触发压缩流程：把最早的历史对话做摘要，删掉生存时间最长的工具结果，直到降到低水位以下。

第三步：实现编排引擎

编排引擎的代码是 Agent 系统的核心循环。关键逻辑如下：

def run_agent(user_input): # 1. 追加用户输入到上下文 context.append_user_message(user_input) # 2. 进入 Agent 循环 for iteration in range(max_iterations): # 3. 调用模型推理 response = model.generate(context.to_messages()) # 4. 解析响应，判断类型 parsed = parse_model_response(response) if parsed.is_final_answer(): # 模型给出最终答案，直接返回 context.append_assistant_message(parsed.content) return parsed.content elif parsed.is_tool_call(): # 模型请求调用工具 tool_name = parsed.tool_name tool_args = parsed.tool_args # 5. 验证工具参数，执行工具 if not tool_registry.exists(tool_name): context.append_tool_error(f"工具 {tool_name} 不存在") continue result = execute_tool(tool_name, tool_args) # 6. 结果过滤和裁剪 filtered = filter_tool_result(tool_name, result) context.append_tool_result(tool_name, filtered) else: # 解析失败，触发错误恢复流程 handle_parse_error(context, response) # 7. 超过最大迭代次数，返回当前最佳结果 return "任务执行超过最大步骤数，建议简化指令后重试。"

这段代码看似简单，实际有几个关键的工程细节需要注意。

第四步：加入错误处理与恢复机制

在实际运行中，model.generate可能会超时，execute_tool可能抛异常，parse_model_response可能返回空结果。我的处理是：

每个环节都加 try-catch，并且根据错误类型决定是重试、跳过还是终止。比如模型生成超时，重试一次；工具执行失败，把错误信息追加回上下文，给模型一个修正机会；解析失败且连续发生两次以上，终止任务并向用户报告错误。

状态恢复的持久化也在这个阶段实现。每次工具调用结束后，序列化当前状态到本地。序列化的数据量控制在几 KB 以内，读写耗时忽略不计。

5.3 工具调用成功率的优化过程

我在这个项目的开发过程中，最初工具调用的成功率只有 82% 左右，经过三轮优化后提升到了 97% 以上。这轮优化过程非常典型，我详细说一下每个阶段的改动和效果。

第一轮优化：增加 JSON 修复层（成功率 82% → 88%）

原始实现是直接把模型的输出交给json.loads解析，失败就报错。增加修复层之后，做了几件事：

• 提取字符串中最外层的大括号或方括号里的内容，忽略前后噪声
• 对不完整的字符串，尝试补全引号和大括号
• 删除多余的关键字（部分模型会输出这里的回复请直接使用 json之类的废话）

这一轮改完之后，格式错误类的失败大幅降低，但参数错误类的失败还是很多。

第二轮优化：加强参数校验与自动修复（成功率 88% → 93%）

这一轮的难点在参数校验。模型的回复里经常会出现参数和 schema 定义不一致的情况，比如 schema 里定义的是一个整数类型的时间，模型返回了"十分钟后"；schema 里定义了一个必填的location字段，模型遗漏了，但在描述里提到了。

我的做法是：工具执行前先做一轮参数清洗，针对常见的模型错误模式做专门处理：

• 类型转换：字符串转数字、字符串转布尔值等，根据 schema 的字段类型自动转换
• 枚举归一化：模型可能返回同义词（比如工具定义接收mobile，模型返回了phone），通过别名表做映射
• 补全缺失字段：某些工具可以在参数缺失时使用默认值，在 schema 里注明default: "auto"的字段，缺失时不报错，直接使用默认值

第三轮优化：prompt 层面的工具描述精炼（成功率 93% → 97%）

轮优化没有改代码，只改了 prompt。我发现模型调用工具失败，很多原因是工具的"描述"写得太抽象。比如最初某个工具的说明是"使用本地应用打开对应链接，注意需要防止外部攻击，小心点击"，模型看了之后理解的是"这个工具有安全风险，可能不能随便用"，于是就不调用了。

我把所有工具描述重写了一遍，原则是：描述要直接告诉模型"这个工具在什么情况下必用，应该传哪些参数"，不要写任何警示性、防御性的废话。改完之后，模型工具的调用准确率有了一次明显跃升。

5.4 端侧 Agent 的内存与性能实测

项目开发完成后，我在一台中端 Android 设备上做了详细的性能测试。设备配置：8 核 CPU，集成 NPU，内存 8GB（系统实际可用约 4GB），系统 Android 14。

测试场景是用户连续发出 5 个不同的任务指令，每个任务都涉及至少一次工具调用，然后检查整体表现：

从数据来看，这个配置在多数真实场景下是可以接受的。用户发出一个指令到收到回复大概需要 3 秒左右，配合流式输出（模型是边生成边输出的），体感上不会觉得太慢。

内存这块，286MB 的峰值占用在移动设备上确实偏高，但考虑到是在用户主动使用 Agent 的情况下才会触及这个峰值，可以接受。后续我会考虑进一步优化：降低模型量化位宽（从 4-bit 降到 3-bit 可以再省约 20% 内存，但推理质量会轻微下降）、对工具结果做更激进的裁剪等。

6. 常见问题排查手册：踩过的坑和解决方案

6.1 工具调用格式频繁出错

现象：模型有时返回无法解析的工具调用格式。

排查思路：先区分是格式问题还是内容问题。在日志中记录每一次模型输出的完整原文，观察出错的模式。常见的格式错误有：JSON 被截断、缺少闭合括号、参数值里出现了未转义的特殊字符、模型把多个工具调用混在一个响应里返回。

解决方案：优先加 JSON 修复层；修复不了就重试，用出错信息引导模型重新输出（比如追加一句"上次的工具调用格式有误，请严格按照定义输出"）；重试两次仍然失败时，终止调用并返回默认兜底答案。另外，在 prompt 层面控制：明确告诉模型每次只能调用一个工具，多个工具调用必须拆分到不同轮次，这能大幅降低格式错误的概率。

6.2 上下文窗口被历史工具结果占满

现象：Agent 运行几轮之后，上下文窗口耗尽，模型开始"失忆"——回复的内容和之前的对话逻辑对不上。

排查思路：检查上下文管理模块的输入输出。在调试模式中打印每次上下文更新后的 token 占用情况，找到占用最多的内容类型。根据我排查的经验，工具完整返回结果是最主要的内存消耗源。

解决方案：这需要执行两个方向的优化。第一，重写各类工具的结果过滤器，让返回内容只保留关键字段；第二，上下文压缩时优先压缩工具结果（毕竟它们往往已经执行完毕，不太相关了）。如果在压缩后发现 Agent 还是"失忆"，可以尝试把系统提示词里补充"你是运行在用户手机上的代理助理，请始终基于当前对话最新消息回答，如果你没有找到相关信息，请直接说明不知道"，利用宽松约束来提升模型对现有上下文的利用。

6.3 Agent 响应太慢，用户体验差

现象：用户发出指令后，Agent 偶尔会卡住几秒甚至更久才给出响应。

排查思路：先把耗时拆解成几个环节：模型推理耗时、工具执行耗时、上下文管理耗时、进程切换耗时。分别做埋点统计，找到瓶颈。

解决方案：根据耗时定位结果，通常是模型推理耗时占大头。优化手段有：调整量化位宽（4-bit 效果基本够用）、启用 NPU 加速（部分设备上相比 CPU 能降低 40% 以上的推理时间）、减少上下文占用来降低 attention 计算量、对常见的用户指令做 pattern matching 直接跳过模型推理（比如"设置一个五分钟后的闹钟"这种固定句式不太需要模型推理，规则匹配可以直接执行）。如果这些手段都用上了还是慢，建议降低模型参数规模，从 3B 降到 1.5B，推理延迟能减半，代价是复杂任务的理解能力变差。

6.4 Agent 进程被杀后的会话恢复异常

现象：用户中途切出应用，再回来时发现 Agent 完全忘记了之前的任务；或者更糟——提醒用户"上次任务进行到一半，是否继续"时，用户点继续，Agent 执行出错。

排查思路：检查状态恢复校验逻辑。我遇到过一次这样的问题：状态恢复后，工具执行继续使用之前的参数，但执行环境已经变了。

解决方案：恢复时的关键校验不能省。每个工具调用的执行结果要带上时间戳和输入摘要，恢复时先比较当前的输入参数和摘要是否一致，不一致就触发重新执行该步骤。注意恢复状态时不要把用户的对话历史丢掉——短期记忆的恢复优先于长期记忆，"上次聊了什么"远比"上个任务做到哪一步"更影响用户体验。

6.5 不同设备上模型输出质量差异大

现象：同一套代码，同一份模型权重，在 A 手机上表现很好，在 B 手机上经常出现输出格式错误或语言不流畅。

排查思路：不同设备的芯片不同，算子支持程度不同，相同的推理代码可能实际上跑在不同精度的计算上。在 NPU 上，某些小算子会被调度到 CPU 执行，中间结果精度不同，最终输出就会出现细微差异。

解决方案：对端侧推理做一次算子级验证。在目标设备上跑一遍模型自带的验证用例，检查输出是否和参考值一致。如果发现差异过大，考虑在同一设备上禁用 NPU 加速，改用 CPU 运行（推理时间会增加，但输出质量更可预期）。在很多场景里，稳定比快更重要。

7. 回到工程化本质：端侧 Agent 的下一步怎么走

写了这么多，都围绕一个核心问题：如何把 Agent 从"能跑"变成"好用"。端侧环境的资源约束逼着你把工程化做到极致，这反而是好事——在云端，你可以用堆资源的方式掩盖工程上的粗糙；在端侧，每一个设计失误都会直接暴露成用户体验问题。

根据我个人的实践体会，端侧 Agent 工程化的优先级排序应该是：稳定性 > 响应速度 > 智能程度。这个顺序很重要，很多团队做反了。一上来就追求模型的推理能力，把一个 7B 模型塞进设备，结果经常出 bug，用户用两次就卸载了。先把有限的资源投入到稳定性和容错机制上，让 Agent 能够稳定地完成简单任务，再逐步提升智能程度，这个路径更可行。

后续这个系列还会继续往下讲。下一部分我会重点分享 Agent 工程化的后半程：数据回流与迭代优化、多设备适配实践、以及端侧 Agent 的可观测性设计。如果你正在或准备做端侧 Agent，欢迎在评论区交流你们遇到的问题。