企业官网建设流程全解析

我们这个“深入理解端侧 Agent”的系列，前两篇更多在讲端侧 Agent 是什么、为什么值得做、底层推理和调度大概怎么运转。到了第三篇，按计划该切入工程化了。我把工程化拆成“上”“下”两部分，因为一旦从概念走向落地，杂事远比想象中多——模型选型、运行时、推理进程、编排并发、记忆存储、技能系统、权限沙箱、故障兜底，随便拎出一项都能让团队排查一整天。

这篇文章基于我们团队在小尺寸模型、手机和嵌入式设备上落地 Agent 的实际经历，谈不上什么标准答案，但里面每一个选型理由和踩坑记录都是真实的。如果你正在做端侧 Agent 工程化，或者正打算把云端 Agent 往端侧搬，这篇文章应该能帮你少走几条弯路。

1. 为什么端侧 Agent 的工程化，和云端 Agent 完全是两码事

1.1 云端 Agent 的三个隐藏前提，在端侧首先不成立

很多人觉得 Agent 工程化不就是“把 LLM 包一层工具调用，再挂上记忆和 Workflow”吗？这个思路在云端能跑通，是因为云环境有三个默认前提。

第一，算力几乎无限。云端可以随时拉起一台带 H100 的实例，模型的参数规模基本不受限制，推理速度不够就加卡，内存不够就扩容。第二，网络稳定可靠。Agent 调用模型 API、调用云端技能、同步记忆，都在一个高带宽低延迟的内网环境里完成。第三，模型能力可以随时升级。大模型一更新，云端 Agent 的能力立刻水涨船高，用户感知不大。

端侧这三个前提全都不成立。端侧的算力以 NPU、CPU、GPU 的固定算力为上限，内存更是瓶颈，很多设备上能分给 Agent 的内存可能只有几百 MB 到 2GB。网络是移动网络或离线场景，今天信号好明天进电梯，Agent 不能因为网络抖动就罢工。模型一旦部署到设备上，迭代周期就变成 OTA 节奏,不可能像云端那样热更新一个大版本。

所以我在给新同学讲端侧 Agent 时通常会说：云端工程化是“往上堆资源”，端侧工程化是“在限制里打磨”，两者的思维起点完全不同。如果你把云端的 Agent 框架直接搬到端侧，会发现十个功能有七个因为资源或环境约束跑不起来，剩下三个跑起来也未必稳。

1.2 “本地跑个模型”和“本地有个 Agent”差的不是一星半点

我见过不少团队，把端侧 Agent 简单理解成“在手机里装一个能对话的大模型 App”。这个理解在 Demo 阶段没问题，但距离工程化非常远。

跑一个本地模型 App，本质是“一次请求-一次推理-一次返回”，交互是单轮的，模型不保留长期状态，App 退出就结束。Agent 则是一个长期存活的智能体，它要持续感知环境变化，比如用户说“帮我设置半小时后的提醒”“把我正在看的这篇文章存到笔记里”，它需要能读取系统状态、调用系统 API、跨应用操作，并且把之前的交互内容记下来。

这就带来了工程上完全不同的要求：

• 感知侧需要事件监听和系统钩子，而不只是一个输入框；
• 决策侧需要一个常驻的调度核心，而不是一次性的推理调用；
• 执行侧需要一套可管控的技能调用框架，而不是让模型直接拼命令；
• 记忆侧需要持久化存储和索引，而不是一段聊天记录。

拿智能家居场景举例。用户对 Agent 说“我睡觉了”，Agent 可能要同时完成关灯、锁门、调空调、设置闹钟四件事。这四件事不是靠一次模型推理就能全部完成的，它需要按照依赖关系依次调用不同设备的能力，执行过程中还可能遇到某个设备离线，需要动态调整方案。这种多步骤、有状态、可恢复的任务流程，才是 Agent 工程化的核心，而不是“把模型跑在本地”这个动作本身。

1.3 混合架构：端云协同的边界才是设计的起点

讲端侧 Agent，并不是说完全不能用云端能力。实际上大多数成熟产品走的是混合架构：核心决策和隐私敏感操作放在端侧，复杂推理和知识密集型任务放到云端。

这个边界怎么划，是工程化第一笔要画的线。我的建议是遵循三个原则。

第一，凡是涉及用户隐私的操作路径，尽量端侧闭环。比如读取本地文件、分析相册、处理健康数据，这些数据不出设备是最好的设计。

第二，凡是需要低延迟响应的动作，必须端侧兜底。比如语音助手的唤醒词识别、快捷指令的触发，不能每次都在云端走一圈再回来，那样用户的体感会非常差。

第三，凡是重推理任务，允许云端增强，但必须明确降级路径。比如复杂文档总结可以走云端，但云端不可用时，Agent 要做到不减功能地降低回答质量，而不是直接“抱歉我当前无法处理”。

举个我们实际遇到的例子。车载场景下，用户在地下车库或隧道里没有信号，此时 Agent 需要能继续处理导航、音乐、车辆控制等本地任务。我们把导航目的地解析、音乐检索这类依赖知识库的请求设计成“端侧意图识别 + 云端结果增强”，当云端不可用时，端侧用本地缓存的历史数据和简化模型完成基本服务。这套降级逻辑如果不在设计初期定下来，后期补会非常痛苦，因为涉及数据流、模型选择、UI 状态多个层次的改动。

所以我把混合架构的边界问题放在工程化第一章节，它决定了后续所有模块的资源和约束条件，先想清楚再动手，比什么都重要。

2. 端侧模型量化与推理引擎：第一道工程门槛

2.1 量化选型：内存账先算清楚再谈效果

模型是 Agent 的“大脑”，但端侧能装下多大的大脑，先得算内存账。

以 7B 参数的模型为例，FP16 精度下，权重大小就是 14GB，绝大多数端侧设备根本装不下。INT8 量化后权重变成约 7GB，仍然偏大。INT4 量化后约 3.5GB，加上运行时所需的 KV Cache 和激活值，总内存占用大概在 4.5GB 到 5GB 左右，这才勉强进入高端手机和平板能承受的范围。

我们实际使用中，落地优先级一般是：1.5B 到 3B 模型跑 INT4/INT8，用于车载、智能家居和轻量设备；7B 模型跑 INT4，用于旗舰手机和专业设备；13B 以上模型基本不走端侧纯本地推理，除非是特殊定制硬件。

但这不代表量化就是“压一下就完事”。量化一定会带来精度损失，尤其对函数调用、JSON 输出、工具参数生成这类结构化任务，低精度模型经常出现参数名拼错、数值类型错误的问题。我们的做法是为每个目标模型建立一份“量化评测集”，里面包含 Agent 典型场景的工具调用用例，量化后逐条跑一遍，对比成功率。有一次我们在一个 4bit 量化模型上发现工具调用参数的字段错误率高达 12%，怎么调提示词都没用，最后切换到 6bit 量化才恢复正常。所以别只看内存降低，要用任务指标决定精度档位。

2.2 推理引擎选型：别追求“一个库跑所有硬件”

端侧推理引擎的选型，很容易进一个误区：希望找一个万能引擎，一套代码在所有设备上跑。现实是没有这种东西。

我列个我们评估过的推理引擎对比，你可以参考：

那个“真香”方案其实是组合：同一个模型导出多份格式，运行时根据设备类型加载。Android 旗舰机走 NPU 加速的格式，老设备走 CPU 优化版本，嵌入式 Linux 走 llama.cpp。听起来运维复杂，实际上用一个统一的模型管理模块就能封装，换来的是各设备的稳定性和性能。

工程上另一个重要建议是先把流程跑通再优化。不要一开始就扎进 NPU 算子适配里，先用 CPU 跑通整套 Agent 流程，确认效果和功能没问题，再把性能瓶颈用 NPU 加速。我们有个教训：第一次做端侧 Agent，直接上手调 NPU，结果算子对齐花了两周，最后发现整体流程里记忆检索的耗时占比比推理还高，NPU 优化完全没打在点上。

2.3 进程架构：不要让模型推理拖死主服务

模型推理非常吃资源，如果你把推理直接跑在 Agent 主进程里，Agent 所在的应用会频繁卡顿甚至被系统杀掉。

我们的做法是把推理独立成一个常驻服务进程，主进程通过 IPC 和它通信。进程模型设计如下：

• Agent 主进程：负责感知、决策、技能调用、记忆管理，保持轻量；
• 模型推理进程：负责加载模型并处理推理请求，占资源大户；
• 通信层：Android 上走 Binder/AIDL，Linux 上走 Unix Socket 或共享内存队列。

这样做的好处有三个。第一，模型加载和卸载不会影响主进程的响应速度；第二，推理进程崩溃后主进程可以自动拉起，Agent 不退出；第三，主进程可以同时对接多个推理后端，比如一个轻量模型做意图识别，一个稍大的模型做深度推理，互相独立。

关于通信层，我要提醒一个细节：不要用 HTTP 做端侧本机通信。虽然开发最顺手，但 HTTP 的序列化开销和端口管理在低功耗场景很吃亏。我们用 Unix Domain Socket 加 protobuf 或者 MessagePack，延迟低、占用小、并且天然支持本机多进程通信。

3. 编排层工程化：并发、任务队列与生命周期

3.1 端侧同样有并发压力，只是换了一种形式

“AI Agent 怎么抗并发”这个问题，我之前总觉得云端才需要考虑。后来在手机上做实际产品，发现端侧照样有并发，只是“并发”的来源不太一样。

想象一个真实场景：用户戴着耳机说“帮我放一首周杰伦的歌”，同时车载系统正在播报路况，后台还有一个定时任务在等待触发。这三个事件几乎同时到达 Agent,如果 Agent 只有一个执行通道，就必须排队处理，还可能互相打断。

我们设计的并发模型分三层：

1. 请求接入层用异步队列接收所有事件，避免阻塞系统回调；
2. 调度层根据任务优先级决定下一个执行哪个任务，比如系统安全相关任务优先于娱乐任务；
3. 执行层使用线程池或协程池跑具体任务，但模型推理部分仍然是串行的，需要在调度层做合并。

这里容易犯的错是让每个请求都独立占用一次模型推理。我们后来做了一个“请求合并”机制：如果多个请求在短时间窗口内到达，且判断它们可能属于同一个会话意图，就合并成一次推理输入交给模型，大幅降低推理开销。比如用户连续说“设个八点的闹钟”“明天早上”“顺便提醒我带文件”，这三条如果分开推理，模型可能无法连贯理解，合在一条上下文里反而效果更好。

3.2 Agent 任务的生命周期，必须用状态机管理

Agent 的任务不是一次原子操作，它通常要经历多个阶段：理解意图、生成计划、逐步执行、中途验证、最终交付。在工程上，这种多阶段任务必须用状态机管理，否则任何一步异常都找不到责任方。

我们定义的核心状态包括：

• Idle：等待新任务；
• Planning：正在生成执行计划；
• Executing：正在调用技能工具；
• WaitingForInput：需要用户确认或补充信息；
• Degraded：云端不可用或推理质量下降；
• Error：任务执行失败；
• Settled：任务完成，结果已归档。

每个状态都绑定超时和重试策略。比如 Planning 阶段超过 5 秒没有产出，直接降级为简化规则执行；Executing 阶段某个技能调用连续失败两次，不再死磕，而是进入 Error 并给用户反馈替代方案。

状态机的价值在于“资源紧张时可管控”。端侧的内存和算力有限，我们设定当系统内存水位超过 80% 时，冻结所有低优先级任务状态，不是杀死任务，而是让它们暂停在 Executing 阶段，等资源恢复后从断点继续。如果没有状态机，这种暂停/恢复根本做不到，你只能硬着头皮跑然后等系统杀进程。

3.3 多 Agent 协作与事件总线

我之前聊过端侧也可以有多 Agent 协作的场景，主 Agent 负责统筹，专门 Agent 负责各领域。工程化之后，协作方案的取舍会很明显。

我们试过两种多 Agent 通信方式。一种是通过共享内存直接读写公共状态，实现简单，但多个 Agent 并发写同一个状态时，排查问题简直灾难。另一种是引入事件总线，所有 Agent 只向总线发消息，也只从总线订阅自己关心的事件，模块之间彻底解耦。我们最终选了第二种。

在端侧落地事件总线，不需要上什么重量级中间件。Linux 设备上我们用本地 Unix Socket 配一个轻量消息分发器，移动端直接用系统提供的本地广播机制。重点是消息格式一定要提前定好 Schema，比如任务完成事件必须包含 task_id、状态、耗时、结果摘要字段，这样后续无论是做日志还是做并发控制都有依据。

多 Agent 编排还有个工程细节是执行顺序的拓扑关系。我们用 DAG 来描述任务依赖，主 Agent 根据用户意图动态生成一张子任务图，然后按拓扑序执行。某个子任务失败时，只重跑它的依赖链，而不是整个任务重新来。比如“查找文件并总结摘要”这个任务，“查找文件”成功但“总结”失败，就只重跑“总结”节点，不需要重新找文件。

4. 记忆系统：存储选型与遗忘策略

4.1 短期记忆、长期记忆、向量检索，分别怎么落

记忆是 Agent 区别于普通聊天机器人的关键，但工程上的记忆设计经常被做成“全塞进向量数据库”，这是个误区。

我们把记忆分成三种，分别用不同的存储方案：

为什么要区分这么细？因为端侧存储空间有限，向量索引最占空间。一段 1000 字的对话嵌入成向量后，光向量就要占用几 KB 到几十 KB，还不算原始文本。如果所有记忆都向量化，一个用户用三个月，存储可能膨胀到几百 MB。所以我们只在需要语义检索的内容上做向量化，其他记忆用结构化字段存储，比如“用户偏好：喜欢早上八点听新闻”直接存成键值对，不需要向量化。

我们选 SQLite 作为长期记忆的底座，理由很简单：事务可靠、崩溃恢复机制成熟、单文件易备份。向量检索用 sqlite-vec 这样的扩展，直接在同一个库里管理向量和结构化数据，省去了维护两套存储的麻烦。

4.2 记忆压缩和遗忘不是可选项，是容量工序

记忆系统的最大工程挑战不是写入，而是容量管理。一个长期使用的 Agent，如果只存不删，任何设备都会被撑爆。

我们的遗忘策略是分层的。会话结束后，短期记忆先尝试用模型做摘要，把细节压缩成几十字的结论存入长期记忆，原始对话保留在本地日志里，超过保留期后清理。当长期记忆库达到容量水位线的 80%，触发“深度压缩”任务：对旧记忆做二次归纳，把多条相关的条目合并成一条。达到 95% 时启动“强制裁剪”，优先删除低价值记忆条目。

这个过程中最容易出现的坑是 Agent 自己触发记忆迁移时把时间顺序搞乱。比如整理“上周去杭州出差”的记忆，模型可能在总结时输出“下周五有杭州行程”，时间错位。我们的解法是：任何模型生成的记忆都必须经过“时间字段校验”，只允许模型改写内容正文，时间戳和实体关系必须从原记录继承。这种机械校验看起来粗暴，但非常有效，能挡住大部分记忆污染。

另外建议给记忆操作设计一个统一接口，不管是写入、查询、压缩还是删除，都通过同一个模块走。这样后续做权限控制、日志审计和同步上云都会方便很多。如果各模块各自操作数据库，后面维护就是一场噩梦。

5. 技能系统设计：Harness 与 Agent 的边界怎么切

5.1 Harness 和 Agent 的区别，对工程化意味着什么

“harness 和 agent 区别”这个问题被很多人搜过，它同时也是工程化的关键议题。Harness 翻译成“工具链”或“脚手架”更准确，它规定了 Agent 能在一个什么样的环境里执行动作：能调用哪些工具、用什么协议、超时多久、有哪些约束。Agent 则是那个“决定调用哪个工具、怎么调用、调用后怎么办”的决策主体。

把这两个概念分开，工程上的意义非常直接：决策和执行力必须解耦。

如果它们耦合，Agent 代码里直接写死各种系统操作，比如 shell 命令、文件删除、权限修改，那这个 Agent 的安全性和可维护性都会迅速失控。而如果 Harness 独立承担“执行沙箱”职责，Agent 的每一次动作都要经过 Harness 的校验和授权，风险面就能被大幅度收住。

我见过一个反面案例：某个端侧 Agent 的“打开应用”技能直接由 Agent 主进程 fork 一个 shell 去执行 am start 命令，结果一次模型输出格式异常，把命令参数拼接错了，差点拉起错误的 Activity。后来我们把所有系统技能收编进 Harness，由 Harness 做参数白名单校验，同样的异常事件再也没出现过。

5.2 技能注册、加载与调用协议

技能系统要支持“接入标准化、加载按需化、调用可管控”。我们实践下来的标准流程是：

1. 每个技能是一个独立插件目录，包含 manifest 文件和实现代码；
2. manifest 里用 JSON Schema 描述技能名称、参数列表、返回结构、权限需求；
3. Agent 通过技能注册中心发现可用技能，加载时只加载 manifest，不加载实现；
4. 真正调用时才按需冷加载实现代码，调用结束后释放资源。

这个设计的好处是设备资源占用低，而且技能可以独立升级。如果某个技能版本有 bug，只需要禁掉该插件的 manifest entry，不需要重启 Agent 主进程。

调用协议方面，不要自己发明一套格式，直接用 OpenAPI 或 JSON-RPC 这类成熟规范。我们用 OpenAPI 描述每个技能的 HTTP 映射，或者用 JSON-RPC 描述本地进程间调用。模型端通过函数调用（Function Calling）生成结构化参数，Harness 负责把参数映射到具体技能实现。

这里有个经验：技能的参数定义一定要严格，最好每个参数都声明类型、范围、枚举值。因为模型的输出天生“自由奔放”，如果技能定义模棱两可，模型就会生成千奇百怪的调用。我们甚至要求每个技能必须定义“失败时的替代建议”字段，这样技能调用失败时 Agent 可以直接把建议话术回复给用户，而不是愣在原地。

5.3 权限控制：最小权限和人类审批

端侧 Agent 直接面对操作系统，权限控制做得不好，等于把家门钥匙交给一个陌生人。

我们的权限模型分三层强制措施。

第一，进程权限最小化。Agent 相关进程用独立 UID 运行，只授予它操作必需的文件夹和设备的权限。Linux 上不要给它 root，Android 上只申请用户实际授予的权限，不要“为了以后方便”提前申请所有权限。

第二，敏感技能有人审。凡是涉及支付、短信、删除文件、修改系统设置这类高风险动作，Agent 不能自行执行，必须通过 UI 弹窗让用户确认。这里“人机共审”不只是产品体验问题，从工程上看它也是防止模型误操作的最后一道大坝。

第三，技能沙箱隔离。如果平台支持，把技能实现放在单独的容器或子进程中执行，就算技能代码有漏洞，也不会影响 Agent 主进程。我们在嵌入式 Linux 上直接给每个技能套了 Linux 权限隔离组，效果很好。

6. 故障兜底与安全护栏：把端侧 Agent 当“真正的服务”来做

6.1 崩溃恢复与看门狗模式

端侧 Agent 面临一个云上没有的麻烦：它寄宿在操作系统里，随时可能被系统杀掉。可能是内存不足被 LMK 收走，可能是后台任务被系统冻结，也可能是设备重启。云端 Agent 崩溃了自动扩容重启就是，端侧 Agent 崩溃了用户感知是“这个助理偶尔失灵”。

我们做的第一道防线是看门狗机制。独立的监控进程定期检查 Agent 主进程的心跳，心跳超时就拉起一个新的主进程。同时主进程在进入关键状态前会持久化一份“任务快照”到本地，里面包含当前状态机状态、正在执行的技能 ID、关键上下文摘要。重启后先恢复快照，再决定继续执行还是告知用户任务中断。

这里有个重要的取舍：不是所有任务都值得恢复。如果任务快照显示已经执行了 20 分钟、涉及 15 步操作，而且是一个“查询天气”这类轻任务，那直接放弃并重新开始反而更合理。我们给每个任务类型定义“可恢复价值评分”，只有评分高于阈值的重型任务才做完整恢复，轻任务直接清理快照进入 Idle。这能避免恢复机制本身带来新的复杂度。

6.2 模型不可靠时的护栏工程

模型是概率系统，必然有输出格式错误、幻觉、参数越界、死循环这些问题。工程上的态度就是“用护栏层兜住模型的不可靠性”。

我们会在推理输出之后和技能执行之前插入一道硬校验：

• Shell 校验输出是否符合 JSON Schema？不符合就自动重试一次，采用更低温度参数；
• 参数校验工具参数是否在合法范围？比如音量调成 200% 这种显然越界的情况直接拒绝；
• 超时控制在每个技能调用都设置超时，防止某个本地操作卡死整个 Agent；
• 执行上限给 Agent 的单次任务设定执行步数上限，默认 8 步，超过就停止并给出阶段性总结，而不是无限循环。

有人担心这些护栏会限制 Agent 的“智能”。但我的观点是：先把确定性管住了，再谈智能。用户不会因为 Agent 偶尔更“自由”而原谅它经常出错，端侧产品尤其如此。

6.3 本地日志与可审计性

端侧隐私要求高，但日志不是不能做，关键是不能像云端那样把所有数据传到服务器。我们的做法是“本地详细日志 + 用户同意后选择性上传”。

本地日志记录尽量全：每次事件触发的原始输入、Agent 选中的意图、生成的计划、每次技能调用的技能 ID、参数摘要、返回结果摘要、耗时、状态迁移。这些日志存成环形文件，最多保留最近几天的量，存储超限就滚动覆盖。

这样做的好处是，排查问题时不用靠“猜”，可以直接回放当时的完整决策链路。有一次用户反馈 Agent “乱操作”，我们通过日志发现是模型把“关闭蓝牙”识别成了“关闭网络”，立刻定位到意图分类模型的问题并做了针对性微调。如果当时没有审计日志这个决策链信息，这个 bug 可能好几天都查不出来。

日志字段里我会特别强调一个点：必须区分“用户原始输入”和“Agent 的中间解释结果”。这不仅是排查方便，也是责任界定的依据，如果 Agent 做错了，能明确看到是理解错了还是执行错了，而不是把责任混在一起。

7. 落地优先级：三条路线图建议与“下篇”预告

工程化讲了一大堆，如果团队刚起步，我建议按下面的优先级推进，先把地基打好再盖楼。

第一条，先做单机闭环，再谈多 Agent 协作。不管最终架构多复杂，先把“模型加载 -> 意图识别 -> 一次技能调用 -> 记忆写入 -> 状态返回”这条链路完整跑通。这个过程会暴露出大量真实问题：模型量化精度够不够、IPC 性能行不行、技能调用稳不稳定。把这些基础问题解决了，再上多 Agent、再谈云端协同，才不至于一团乱麻。

第二条，把“结果可预期”放在“能力丰富”之前。端侧 Agent 的第一版能力可以少，但每个能力都得稳定。我们内部有个原则：功能上线前先在低端设备上做压力测试，如果某个功能在两年前的设备上表现不合格，宁可推迟发布也不带病上线。用户对端侧 Agent 的容忍度比云产品低很多，一次失败就可能卸载。

第三条，从第一天就预留观测接口。端侧 Agent 的可观测性比云端难做，但又是排查问题的命脉。最少要在核心模块加日志埋点、结构化事件上报通道、状态快照持久化。这些观测能力早期可能用不上，一旦上线出问题，它们就是唯一的救命稻草。

下篇我计划重点展开三块：一是记忆和技能系统的完整接口设计细节，包括消息 Schema 和存储模型；二是多设备间的 Agent 状态同步与冲突处理；三是在嵌入式设备上做 Agent 的资源调度与功耗优化。这些内容更偏实现层面，等我们跑完新一批设备验证，再回来填坑。

先到这，继续干活去了。