端侧 Agent 这三年的热度肉眼可见地从概念走向了工程。前两篇我们聊了端侧的算力底座和系统架构属于“想清楚”的阶段这篇开始聊“做出来”的部分——Agent 工程化。所谓工程化说白了就是在跑通 Demo 之后怎么把它变成一台记得住上下文、调得对工具、出得了活、出错了还能自己爬起来的机器。这个“上篇”先聚焦最核心的骨架Harness 怎么搭、上下文怎么管、Skill 和 Tool 怎么设计、并发和安全怎么兜底。我会把实际部署端侧 AI 硬件、做 Agent 落地时踩过的坑和验证过的方法直接摆出来适合那些已经跑过模型 Demo、正准备把智能体真正嵌进 App、车机或智能硬件的工程师。如果你还没跑过任何端侧 Agent也不慌这篇会给你一张完整的工程地图按图索骥就行。1. 端侧 Agent 工程化到底在解决什么问题1.1 端侧和云端的工程分水岭很多同学是从云端 Agent 开始入门的习惯了“请求一下模型、拿到 JSON、再调一下工具”的节奏一到端侧就发现处处不对劲。端侧 Agent 面对的不是“性能弱一点的云端”而是一整套完全不同的约束条件。云端你有几十 GB 内存、有 GPU 矩阵、有稳定带宽上下文窗口动不动就是 64K 甚至 1M端侧则是几百 MB 内存、算力有限的 NPU、时有时无的网络、4K 到 32K 的上下文窗口还得考虑功耗和发热。我把两者在工程上的差异拉了一个表方便大家直接对照维度云端 Agent端侧 Agent推理算力高可弹性扩容受限通常跑量化后的 1B~8B 模型内存GB 级起步几十 MB 到 1GB 左右和 App 共享网络稳定、低延迟弱网、离线常态上下文64K~1M Token4K~32K Token更新方式服务端热更新OTA 包、增量模块版本碎片化严重可观测性日志全量上云本地环形存储回传受限并发模型多实例、水平扩展单实例、串行推理为主这里最关键的一点是端侧工程化不是“把云端方案压一压就能用”而是要为一个资源极度受限、环境不可控的运行时空设计一套自洽机制。你做的每一个决策——上下文保留多少轮、工具调用超时设几秒、状态写在哪——都是在为毫秒和兆字节负责。这不是悲观而是端侧开发的基本素养把硬约束作为设计输入而不是事后补救。1.2 从“会写 Python 脚本”到“Agent 产品”的差距先泼一盆冷水跑通一个 while True 循环套模型调工具真的只是入门。我见过太多项目卡在 Demo 阶段模型能回答、能调用写好的几个函数但一进真机就崩进程被杀后对话全丢模型偶尔返回非 JSON 格式就 panic工具超时没人管用户点了一下取消结果后台还在跑。工程化要解决的核心矛盾是把“大模型输出的不确定性”变成“系统行为可预期的确定性”。读起来很绕但落地就三件事状态、日志、自愈。状态是说Agent 运行到哪一步必须能随时落盘App 退到后台、系统回收进程、用户切换任务回来都能接着跑。日志是说模型输出、工具调用、异常、耗时这些关键事件必须留痕出了鬼问题你能回放。自愈是说模型不按格式回答、工具报错、超时、死循环系统得有兜底策略不能直接白屏。所以端侧 Agent 的工程化框架里最该被认真对待的不是某一个炫酷工具而是这个稳定的三角可追踪的状态机、可观测的执行轨迹、可控的故障恢复。后面所有章节讲的 Harness、上下文管理、Skill 设计本质上都是为了撑起这个三角。2. 跑通一条 Agent 循环Harness 的骨架与关键字节2.1 先搞清楚 Harness 和 Agent 的区别“Harness 和 Agent 到底什么关系”是后台留言里高频问题这里单独拆开说。Agent 是大脑负责理解任务、决定下一步做什么Harness 是躯体负责让大脑的想法真正变成动作——它调度模型、管理上下文、执行工具调用、保存状态。换句话说Agent 是模型和提示词组成的那一坨“智能”Harness 是围绕这坨智能搭建的“运行时 操作系统”。没有 Harness 的时候你写的是硬编码循环每一步逻辑都缠在一起。有了 Harness循环变成框架能力模型吐出一个意图Harness 负责校验、执行、记录、再喂回给模型。系统提示词不是模型自己写的是 Harness 在每次推理前注入的工具清单不是模型随便翻的是 Harness 按权限动态塞进去的状态不是散落在全局变量里的是 Harness 统一持久化的。务实的类比Harness 好比一个项目的脚手架加 CI 流水线Agent 是业务代码。没有脚手架也能写业务但当业务复杂到一定规模你真正需要的是流水线帮你保证每次构建可重复、可回滚、可观察。2.2 一个最小 Harness 的组成我在端侧落地时习惯把 Harness 拆成五个模块状态管理、上下文组装、模型调度、工具执行、回溯日志。下面是一个极简的伪代码框架结构上可以直接映射到 TypeScript、Python 或 Rustclass Harness: def __init__(self, model, tools, storage): self.model model # 端侧推理引擎封装 self.tools tools # 已注册的工具白名单 self.storage storage # 本地 KV 存储sqlite/MMKV self.state State() # 智能体状态机 async def run(self, user_request): # 1. 先从持久化存储恢复上次状态 self.state.load(self.storage) while not self.state.is_finished(): # 2. 按状态组装 prompt注入系统指令、历史、工具 schema prompt self.context_builder.render(self.state) # 3. 模型推理拿到期望动作带超时保护 raw_output await self.model.generate(prompt, toolsself.tools.schemas(), timeout10) # 4. 解析动作。不信任模型输出做宽松解析 action self.action_parser.parse(raw_output) if action.is_finish(): break # 5. 执行工具带超时、幂等控制 result await self.tools.execute(action, timeout5, idempotency_keyself.state.gen_key()) # 6. 更新状态、写日志、落盘 self.state.apply(action, result) self.state.save(self.storage) self.tracer.record(action, result, cost_msself.last_cost()) return self.state.final_answer()这段代码看起来简单但每个循环环节都藏着工程细节。第 3 步模型推理必须有超时因为端侧模型偶发卡死第 4 步不能直接json.loads因为端侧小模型经常输出残缺 JSON第 6 步必须先落盘再返回否则进程一杀就丢状态。这个循环本身就是“边跑边存快照”的模式保证任意一步挂掉重启后都能恢复到最近的稳定点。实践中有个经验状态机至少要有RUNNING、WAITING_TOOL、FINISHED、ABORTED四个状态不要省。WAITING_TOOL尤其有用工具是外部调用可能长时间无响应这个状态可以撑起“取消任务”“超时重试”这些能力。2.3 选择框架还是自研端侧 Agent 要不要用现成框架是很多人纠结的点。我的态度很明确看看思路别直接搬。云端用得多的编排框架在端侧碰到的坑主要有三个——依赖体积大动不动就几 MB 到几十 MB对 App 包体不友好运行模型偏“在线服务思维”动态注册、反射调用这些机制在端侧受限并发模型不适合单实例串行推理很多框架默认异步并发在端侧反而增加复杂度。做一个快速选型对比供大家参考方案优势端侧落地问题LangChain / LangGraph编排抽象多、生态全依赖树深、体积大、抽象偏重难定制状态机Dify可视化、服务端成熟本质是服务架构端侧离线跑不起来CrewAI多角色编排直观多 Agent 调度开销大端侧成本敏感自研轻量 Harness可控性强、体积小、可深度定制需要自己踩坑没有社区共享排错我现在的默认路线是自研一个轻量 Harness只实现事件循环、上下文、工具、状态、日志这五件套整个核心代码控制在 1000 行左右复杂场景里借鉴 LangGraph 的状态图思想但不用它的代码。你一旦自己写过 Harness再回头看框架源码会清楚很多——因为你知道每一步是为了解决什么真实问题。端侧的另一个优势是“Agent anywhere”的形态非常灵活同一个 Harness 可以跑在 App 主线程的 worker、车内娱乐系统的服务进程、甚至智能音箱的嵌入式 Linux 里。自研方案天然能适配这种多形态分发框架反而绑手绑脚。3. 上下文管理端侧 Agent 的“内存条”3.1 端侧模型上下文窗口的现实上下文窗口决定了 Agent 能“同时看见多少东西”端侧这块非常拮据。你看着包装盒上写的“8K 上下文”觉得很宽裕真跑起来就傻眼系统提示词占掉 1.5K工具 JSON Schema 占掉 2K历史对话占掉 2K剩下给当前请求的可能只有 2.5K一个稍长的用户指令加文件内容就爆。更隐蔽的是 KV cache 对内存的占用。上下文开得越长推理时需要缓存的 K/V 张量越大端侧内存很容易被拖垮。量化模型虽然饱受推崇但 KV cache 往往是浮点不跟着量化缩。我实测过一些 4B 量化模型4K 窗口下 KV cache 能吃掉 200~400MB 内存这对很多设备是灾难。所以上下文管理的核心任务不是“尽量塞满窗口”而是“在预算内只保留对当前决策最有用的信息”。这句话就是端侧 Agent 上下文工程的总纲。3.2 上下文裁剪与压缩策略我在项目里会把上下文分成三个层级按优先级塞入窗口第一优先级系统指令 当前用户请求 最近 2~3 轮对话。这是决策的直接依据不可缺失。第二优先级本轮相关的工具调用结果摘要。工具返回的原始 JSON 往往会很大只保留结构化的结论和关键字段。第三优先级更早的对话历史。用摘要代替全文只保留任务目标、已确认的约束条件、尚未闭环的待办。裁剪策略上我推荐“滑动窗口 关键帧保留”。滑动窗口只留最近 N 轮关键帧则是那些标记为重要的节点——比如用户改变需求、工具确认某个操作、任务阶段完成。这些关键帧无论相隔多远都要保留它们决定了 Agent 会不会“失忆”。压缩策略里最有价值的是“摘要重写”。每完成一个阶段让模型把已经走过的对话压缩成 100~200 字的进度摘要写回状态存储作为下一轮的“长期记忆”。这比粗暴截断效果好得多因为摘要保留了因果逻辑而不是只剩碎片。这个方案端侧尤其合适摘要本身也是模型干活正好复用推理引擎不引入额外组件。实操里踩过最大的坑工具返回的 JSON 整包塞进上下文。一次数据库查询返回 50 行记录直接把窗口撑爆。后来所有工具结果都过一层“精简器”只返回“查询到 50 条其中关键字段: xxx”窗口压力瞬间小了一个量级。想让 Agent 干活给它的不是原料是结论。3.3 端侧 Memory可持久化的上下文有人把 Memory 和上下文窗口混为一谈其实两者是两类东西上下文窗口是“工作记忆”Memory 是“长期记忆”。长期记忆必须持久化不然退出 App 一切归零。端侧 Memory 我推荐从 SQLite 起步不要一上来就上向量库。大部分场景的长期记忆其实是结构化数据用户的偏好、任务清单、历史摘要、实体关系。这些用表存就行查询快、体积小、事务可靠。只有在做“语义召回历史片段”时才需要引入向量检索端侧可以选 sqlite-vec 这类轻量扩展或者干脆在服务端算好向量端侧只存浮点数组做暴力检索几百条数据量暴力检索反而更简单。写入策略上有个细节不要每轮对话都写全量历史IO 频繁且浪费。我的做法是“按阶段落盘”——一个任务阶段结束后把该阶段的摘要和关键状态写入 MemoryApp 进入后台或 Harness 即将休眠时强制刷一次盘。这样既保证可靠性又不会把闪存写穿。Memory 的数据要设计成“可读给模型听的格式”。存储是给人看的表结构但喂给模型时得组装成一段自然语言或结构化片段比如“用户偏好速览”“任务进度摘要”。很多 Agent 的长期记忆失效不是存得不够而是读出来时不会组装。4. Skill 与 Tool 层端侧 Agent 的执行器设计4.1 Skill 和 Tool 的区别Skill 和 Tool 是近两年高频词很多人以为只是换了个说法。我的理解是Tool 是原子操作一次调用做一件确定的事比如“打开文件”“发送通知”“查询天气”Skill 是把多个 Tool 按工作流组织起来的复合能力里面还带着前置条件、校验逻辑和异常回退。给你一个生活化例子“把当前网页保存为 Markdown”是一个 Skill它内部要依次调用“读取 DOM”“清洗噪音内容”“HTML 转 Markdown”“保存文件”四个 Tool还要处理页面无法访问时降级为“保存正文纯文本”。如果让模型自己一步步编排这四个 Tool不仅贵还容易中途跑偏把整条流程封装成一个 Skill模型只需要决策“要不要执行这个 Skill”内部逻辑直接确定。端侧场景下 Skill 的价值更大模型要省 token、省延迟能一次编排完成的绝不来回猜。所以我会把高频的复合任务都沉淀成 Skill模型只需要做选择题而不是做组合题。实操中我把 Tool 形容成“扳手”Skill 是“一套完整的检修流程”。扳手谁都会用但检修流程才是老师傅的价值。Agent 也是一样底层工具人人都能注册真正拉开体验差距的是把工具编排成高质量工作流。4.2 工具注册与参数校验端侧 Harness 在注册工具时一定要为每个工具提供 JSON Schema 描述这是模型“知道有什么工具可用”的前提。但端侧小模型不像云端大模型那样老实经常输出残缺的 JSON、把参数类型写错、或者干脆吐一段 Markdown 包住 JSON。我的标准做法是解析层做三级容错——先标准 JSON 解析失败后剥掉 Markdown 代码块再解析再失败就用正则捞关键字段做参数补全。参数校验也不能省。模型认为“删除文件”的 path 参数是相对路径但你的工具在等绝对路径直接执行就会删错文件。所以 Harness 里要有一个参数校验层对path做路径归一化和目录白名单检查对url做域名白名单校验对数值参数做边界钳制。宁可校验失败让模型重新调整也不要带着脏参数执行。工具的执行层还有两个必须处理的点超时和幂等。工具调用要包超时你不可能让模型等一个网络请求十秒钟幂等是为了应对重试Agent 循环里模型可能会重复调用同一个工具比如“发送短信”这种有副作用的工具必须用幂等键保证同一逻辑请求只执行一次。我习惯在执行前生成idempotency_key hash(agent_session_id, tool_name, args)执行器检查这个键是否处理过处理过就直接返回上次结果。4.3 多 Agent 与技能编排端侧要不要搞多 Agent这是后台留言里的高频问题。我的答案能单 Agent 就别多 Agent。端侧跑多 Agent 的成本是实打实的——每个 Agent 都是一次模型推理会话内存占用线性增加通信协调复杂度也上来了而收益往往只是“分工明确”这种心理安慰。云端多 Agent 有价值是因为它在并行环境里能用多个模型实例分头处理端侧没有这个资源底气。如果业务确实需要角色拆分比如“一个规划者 一个执行者”我推荐用“单 Agent Skill 编排”模拟而不是真的跑多个 Agent 实例。也就是说让同一个 Agent 在不同阶段加载不同的 Skill 和系统提示词主观上扮演不同角色。效果近似多 Agent资源开销只是单份。真要上多 Agent也建议控制在一个进程内、走共享状态存储而不是跨进程搞 IPC。Agent 之间通信用“读同一份状态 结构化消息”消息体要短不要互相传大文本。实践告诉我多 Agent 的通信链条长一步出错概率就翻一倍优先压复杂度别追求架构上的“高级”。5. 并发、安全与观测工程化的“护栏”5.1 端侧能扛多少并发“AI Agent 怎么扛并发”是个好问题但前提要分场景。端侧 Agent 的推理引擎通常只有一个实例模型推理是长耗时操作一次生成往往要几百毫秒到几秒期间硬件的 CPU/NPU 占用非常高。所以端侧的基本并发模型是单实例 队列 串行推理类似于一台机器只跑一个主循环。具体做法外部请求全部进任务队列Harness 主循环从队列里拿任务一次只处理一个。任务之间按优先级排序比如用户主动交互优先级高于后台预取任务。队列要带背压机制——队列满了就拒绝新任务并提示“请稍后再试”而不是无限堆积把内存拖垮。另外提一下“AI Agent 怎么扛并发”在端侧的答案和云端完全不一样云端靠水平扩展堆实例端侧靠调度降级保体验。比如用户连续提问时如果模型还在跑上一条可以把新请求先合并等当前任务结束后跳过去重后的最新问题。这种降级策略比硬并发优雅得多。5.2 安全边界与权限控制Agent 能调工具等于给模型发了一把“能动系统的手”安全设计必须同步跟上。端侧 Harness 里我坚持三条护栏工具白名单、路径白名单、审计日志。工具白名单说的是Harness 只暴露当前业务真的需要的工具其余一概不注册。这不是性能问题是攻击面问题。模型一旦被注入恶意指令它只能调用白名单内的工具影响就收敛了。路径白名单是文件类工具必须校验目录范围只能读写指定的工作目录不能满盘乱跑。审计日志则是把每次工具调用记录下来谁调的、传了什么参数、结果如何出事后可以回放溯源。还有个容易被忽略的安全点是“外部内容隔离”。当 Agent 从网页、文件、API 响应里读到内容时这些内容是可能夹带恶意指令的。我的工程经验是凡是模型需要“读外部内容再决策”的场景都要把外部内容放在一个明确的“数据区”并在提示词里强调这是待处理数据而非系统指令。同时对于“修改系统配置、发送消息、删除文件”这类高敏感工具不因外部内容自动触发至少加一次用户确认。这类防护无法做到百分百但工程上认真做与不做的差距是量级的。端侧设备的用户资料更敏感权限设计宁可保守也不要激进。5.3 可观测性日志、追踪、评估很多端侧 Agent 项目只做了日志没做追踪。日志的粒度是“文本”追踪的粒度是“一次完整任务的执行链”。我建议 Harness 从第一版就内置一个本地 trace 系统把一次任务的每一步记成一个结构化事件模型输入摘要、模型输出原始内容、解析结果、工具调用名与参数、工具结果摘要、每步耗时和 token 数。全部追加写入本地环形文件保留最近 100 条任务。这套 trace 的价值在调试和评估两件事上体现得最明显。模型为什么在某一步做出了错误决策回放 trace 看看上下文组装是否有遗漏、工具返回是否有误导、系统提示词是否冲突一目了然。线上出现问题后你可以把 trace 文件导出来离线重放再造相同输入验证修复效果。评估工作也别动不动就上大工具。先把 trace 里沉淀的原始数据拿来做“成功率的粗糙统计”——任务完成率、平均步骤数、平均耗时、工具失败占比。这些指标能帮你快速定位瓶颈如果工具失败占比高问题大概率在工具层如果步骤数膨胀大概率是上下文裁剪策略没做好。工程化不是上线就结束而是从 trace 里持续获得反馈、持续优化。6. 常见问题与故障排查实录6.1 上下文被截断Agent 突然“失忆”症状是对话到一半模型开始忽略早期指令或者完全忘记用户最开始的需求。排查思路先看 trace 里模型输入的实际 token 数如果已经顶到窗口上限那就是上下文溢出了。处理办法是把裁剪策略调激进一些摘要重写的触发阈值设低一点并且确认关键状态是否被摘要覆盖。曾遇到一次案例模型把“用户禁用了某个功能”这件事放在很早期的对话被滑动窗口挤掉了后来我设置了“所有用户明确禁止项强制保留”的关键帧规则问题才根治。6.2 模型不按 JSON 格式返回这是端侧小模型的“通病”严重程度跟模型量级相关。症状表现是输出缺括号、多注释、参数名被改写。我的经验是用两层方案兜底解析层三级容错 提示词层少让模型“自由发挥”。提示词里给出严格的输出模板明确每个字段的类型和取值范围比说一百遍“must be valid JSON”都管用。如果模型还是经常性不守格式可以在 Harness 侧增加“输出后校验失败自动重试一次”的机制重试时的提示词补齐上次的输出作为反面示例成功率会显著提升。6.3 Agent 陷入死循环症状是模型反复调用同一个工具或者一直追问同一个问题。排查步骤先看 trace 里是不是所有步骤都一样是一样就基本确定进入了循环。处理措施分三路最大迭代次数硬限制超过就强制结束并返回中间结果工具调用次数上限单个工具被调超过 N 次就临时禁用轮次去重如果连续 N 步的输出哈希相同判定为循环并中断。有一种特殊情况是模型在“确认性追问”这不是死循环是它没理解指令可以针对性地在系统提示词里强调“没有新信息时不要重复提问”。6.4 端侧内存占用持续上涨症状是 App 常驻内存逐渐增加使用越久越卡。优先级排查顺序先看 KV cache 是不是没有释放有些推理引擎在长会话后会累积缓存再看 trace 文件是不是无界增长环形日志有没有正确覆盖最后看工具执行是否泄漏资源比如每次调用都新开句柄。我的经验是端侧 Agent 的内存治理核心是“一切都要有上限”上下文窗口有预算、trace 文件有大小限制、并发队列有长度上限。把这些上限显性化内存异常往往立刻现形。6.5 状态丢失、对话错乱症状是任务执行到一半被杀进程重启后状态对不上甚至历史消息重复出现。排查思路围绕“落盘时机”展开。我踩过的坑是在工具执行完才落盘结果工具执行到一半进程被杀状态停在工具调用前重启后模型又把工具调了一遍产生了重复副作用。后来改成“工具执行前先记录意图执行后再更新结果”两步都落盘重启后可以根据中途状态决定是继续等待还是重试。这个改动很小但对可靠性提升极大。这类问题的共性规律是能恢复的状态一定先落盘不能恢复的执行一定带幂等。拿这两条原则去走查代码大部分状态类 Bug 都能提前化解。我个人在实际操作中最深的体会是端侧 Agent 工程化半年跑下来不用怕真正要命的是“没有约束机制”。模型天生自由奔放Harness 就是给它画跑道上下文窗口天生不够用压缩策略就是帮它做减法工具天生有副作用权限和幂等就是帮它踩刹车。把这些骨架搭稳Agent 才能在端上变成可靠产品。这个系列的下篇我会继续聊评估、OTA 部署和长期维护到时候再说。