echo-agent 前身为 2025 年 11 月启动的个人助理项目 fubot，最初面向长期陪伴型个人智能体，围绕认知记忆、上下文延续、用户偏好沉淀、任务闭环与持续自我优化展开。随着真实场景迭代，项目逐步形成多入口接入、统一事件模型、消息总线、Agent Loop、多模型抽象、工具调用、MCP 接入、任务调度、权限审批、运行轨迹、长期记忆和受控自演进等能力。目前已支持微信、QQ、CLI、Gateway、Webhook、Cron 等入口，服务用户超过 20 万、累计下载超过 50 万，是面向长期运行、记忆增强和可持续成长智能体的开源 Agent Runtime。

项目地址：echo-agent

你维护过一个已经跑起来的 Agent 系统：第一版只有聊天和几个本地工具，代码不多，问题也好定位。

几个月后，系统接入了多个模型 provider、MCP、Gateway、长期记忆、调度任务、多 Agent worker 和评估集。功能变强了，但每次改动都开始让人紧张：一个工具描述调整，可能影响模型选择；一个默认策略变化，可能让旧任务跑不下去。

这就是 Agent 架构真正难的地方。写出第一版 Agent Loop 不难，难的是让系统在能力持续扩张后仍然知道边界在哪里。

本篇作为系列收官，只讲一个点：生产级 Agent 的长期维护，本质不是不断加模块，而是保护稳定契约，让变化发生在正确位置。

问题入口

如果只看传统文本型 Chatbot，它的基本形态仍然比较清楚：用户输入文本，系统返回文本。即使内部接入检索或工具，用户感知到的主流程通常还是一次问答。

Agent 不一样。它会读文件、执行命令、调用外部服务、保存记忆、恢复任务、触发调度、向其他 Agent 委派工作。它的行为不只发生在回答里，也发生在状态、工具、副作用和未来任务里。

因此，Agent 的长期维护不能只问“代码还能不能跑”。更重要的问题是：旧配置能不能加载，旧记忆是否按正确作用域召回，旧技能引用的工具是否仍可用，旧任务升级后是否能恢复，危险操作是否仍然经过审批。

Agent 升级改变的不是代码版本，而是系统的行为版本。

普通软件的兼容性主要看 API。Agent 还要看行为兼容性：模型路由、工具可见性、审批默认值、上下文压缩、记忆注入顺序，任何一个变化都可能改变用户实际感受到的 Agent。

稳定契约

模块化不等于可维护。一个项目可以有很多目录，却仍然到处共享隐式状态；也可以模块数量不多，但因为契约清晰而容易演进。

Agent 系统真正需要保护的是四类稳定契约。

契约	解决的问题	echo-agent 中的典型形态
事件契约	新通道不侵入核心循环	InboundEvent、OutboundEvent
工具契约	新能力纳入同一安全治理	Tool、ToolRegistry、执行上下文、ApprovalGate
Pipeline 契约	新能力有明确落点	ContextStage、InferenceStage、ResponseStage
状态契约	跨版本升级不丢长期资产	会话、记忆、任务、工作流、技能、调度器

为了不停留在抽象层面，下面以 echo-agent 的实现为例。

新增飞书通道，不应该直接改 AgentLoop，而应把平台消息转成 InboundEvent，再把统一输出转成平台可发送的消息。新增 MCP 工具，也不应该绕过本地工具系统，而应适配成统一 Tool，注册到 ToolRegistry，并在执行前进入风险分类、路径策略和 ApprovalGate。

新增记忆整理、技能注入、模型路由或后台 summary，也不应随手塞进主循环。看见世界的变化放在 ContextStage，推理和行动的变化放在 InferenceStage，保存和输出的变化放在 ResponseStage。

这不是为了追求抽象，而是为了降低每次改变的理解成本。

变化归位

早期 AgentLoop 往往写成一个大函数：收到事件，加载历史，构建上下文，调用模型，执行工具，保存会话，发送结果。这个写法启动快，但能力增加后会出现三个问题。

第一，新增能力不知道放在哪里。记忆、技能、RAG、工具过滤、模型 fallback、流式输出、后台整理都争夺同一段代码。

第二，测试难以定位问题。一次失败可能来自上下文构造，也可能来自模型响应解析、工具执行、会话保存或输出投递。

第三，安全边界容易出现旁路。某个新执行路径如果没有经过同一套审批逻辑，系统看起来能跑，实际已经破坏核心假设。

阶段化 Pipeline 的价值，就是让变化有位置。

async def handle_event(event: InboundEvent) -> OutboundEvent:

    context = await context_stage.build(event)

​

    result = await inference_stage.run(

        context=context,

        tools=tool_registry.ready_tools(context),

        approval_gate=approval_gate,

    )

​

    outbound = await response_stage.persist_and_emit(

        event=event,

        context=context,

        result=result,

    )

​

    return outbound

这段伪代码的重点不在函数名，而在时序：外部输入先变成上下文，工具调用必须经过统一执行路径，最终结果再统一保存和投递。

以“帮我修复测试失败”为例，意图是修复失败；状态是仓库文件、测试日志、依赖版本、历史会话和任务进度；能力是读文件、运行测试、改代码。可维护的 Agent 必须让这些信息进入明确阶段，而不是散落在 prompt、工具回调和临时变量里。

行为版本

Agent 发布不能只写“修复若干 bug”。它更像一次行为边界重新确认。

接口兼容性要看配置 schema、CLI 参数、Gateway API、工具名称、技能格式、评估数据格式是否稳定。

状态兼容性要看会话、记忆、任务、工作流、调度、技能和知识索引能不能跨版本读取，是否有迁移路径。

行为兼容性更难。即使接口和状态都兼容，默认模型变化、工具描述变化、审批策略变化、上下文压缩变化，也可能让同一个任务走出不同路径。

改动	表面看	真正风险
改工具描述	文案优化	模型选择工具的概率变化
改默认模型	提升质量	工具调用格式和稳定性变化
改审批级别	更安全	旧自动化任务被中断
改记忆召回	更相关	旧会话目标被遗漏或污染
改 Gateway 鉴权	更严格	外部系统无法投递任务

生产发布时，还要承认 Agent 是持续运行系统。调度任务可能正在等待触发，Gateway 可能有未完成请求，后台记忆整理可能正在写入。直接重启可能造成重复任务、丢失输出或状态半写入。

更稳妥的流程是：停止外部入口，等待关键任务收束，暂停后台执行，完成状态迁移，启动新版本，观察健康信号和关键 trace，再逐步恢复入口。

会调用工具只说明有行动接口；能否长期维护，要看工具调用是否进入闭环，是否受权限约束，是否能被追踪和复盘。

状态迁移

Agent 的长期状态比代码更难升级。代码可以重新部署，状态不能随意丢弃。

会话历史通常是 append-heavy 数据，迁移时应读取旧字段、写入新字段，让升级渐进发生。记忆数据涉及检索质量，embedding 模型、索引版本、chunk 策略都要记录，必要时提供重建索引命令。

技能是用户资产。echo-agent 的技能目录兼容 agentskills.io 布局，迁移不能随意改路径。新增元数据更适合放在 SKILL.md front matter 或可选文件中。

任务和工作流是状态机。迁移必须保证 running、suspended、cancelled 这类中间状态能映射到新状态。调度任务还涉及时间，CRON 规则、时区、下一次运行时间和投递目标都必须保留。

这里有一个判断标准：每次改变持久化结构，都应增加“旧数据可读、新数据可写、读后不破坏”的测试。没有这类测试，状态迁移只是开发者的口头信心。

扩展治理

Agent 架构要允许扩展，但扩展点不能同权。

只读知识源、输出格式模板、通道渲染器通常是低风险扩展。技能、RAG parser、MCP 只读工具会影响模型行为，属于中风险。写工具、执行器、审批策略、模型路由、远程 Agent 委派会产生副作用或改变安全边界，应按高风险治理。

扩展点分级可以避免两个极端：全部封闭导致生态无法发展，全部开放导致安全失控。

生产级标准要落到可检验项上。一个能力进入系统前，至少要回答：是否有严格 schema，是否标注 risk level 和 readiness，是否区分只读、低风险写和高风险写，是否进入审批节点，是否有 tool call trace，是否支持失败重试和取消，是否有回归测试。

对于平台化 Agent，未来会走向策略中心化与执行分布化。身份、权限、审批、模型路由、工具治理、评估和审计由统一控制面管理；具体执行发生在本地、容器、远程执行器、浏览器或其他 Agent 中。即使当前只是单用户部署，会话、记忆、任务和权限也最好保留 owner、scope 或可扩展字段。

可校准性

长期维护的目标不是让系统永远不复杂，而是让每次改变的影响范围可理解。

这需要一套闭环：观察行为，解释原因，调整策略，验证效果，安全发布。

环节	需要留下的证据
观察	模型调用、工具调用、审批决策、检索结果、输出投递
解释	prompt 版本、技能来源、记忆证据、模型版本、工具 schema
调整	配置、策略、工具描述、模型路由、记忆规则
验证	结构化 case、执行轨迹评估、场景评估、安全评估
发布	迁移记录、行为变更说明、健康信号、回滚路径

行为债务往往比代码债务更隐蔽。提示词临时加一句规则，工具描述为某次失败做特殊措辞，记忆 reviewer 放宽写入门槛，审批策略为某个项目开例外，单独看都合理，长期累积后 Agent 行为会变得难以预测。

偿还行为债务不是一味重写，而是建立归因：某个行为来自系统提示、技能、记忆、模型版本、工具 schema，还是用户当前指令？只有能回答，团队才能安全调整。

这也是文档为什么属于架构治理。文档不是源码注释集合，而是系统行为契约。它应说明默认安全姿态、配置含义、工具风险、部署模式、数据保留、评估方法和扩展接口。落后或超前，都会降低信任。

小结

Agent 架构的长期演进，是在能力扩张和边界稳定之间取得平衡。

echo-agent 当前最重要的架构资产，不是某个具体类或目录，而是统一事件模型、统一工具接口、阶段化 Pipeline、安全审批边界、模型 provider 抽象、长期状态分层和可测试的模块结构。只要这些契约保持清晰，新增通道、工具、模型和协作方式，就更可能成为能力增长，而不是复杂度失控。

本系列从 Chatbot 与 Agent 的边界讲到上下文、工具、权限、记忆、RAG、任务、多 Agent、MCP、Gateway、可观测性、评估、测试，最终落回同一个工程判断：AI Agent 不是神秘智能体，而是把大模型推理放进工程化行动系统后的结果。

真正值得信任的 Agent，不是永远给出漂亮回答的 Agent，而是能在长期复杂工作中保持目标、尊重约束、解释限制、恢复失败并持续改进的 Agent。架构维护做的，就是让这种能力可以一年一年地生长，而不是在一次次新增功能后被复杂度吞没。

（全篇完）

---

本文为 echo-agent 设计笔记系列第 31 篇。项目源码已开源至 GitHub。如果你对工业级 Agent 的工程落地感兴趣，欢迎加入技术交流群参与日常讨论。