企业官网建设流程全解析

维护 Agent 框架三个月，我最大的感慨是：让一个 Agent 跑起来不难，让一百个 Agent 稳定地跑、且出了问题还能把现场精确还原，难度完全是另一个数量级。这篇文章想做的事，是把我在 DeepSeek Harness（下文我简称 Harness）这个项目里的两个核心工程决策拆开聊聊——全插件化设计和可回放会话日志。前者解决的是"框架越改越乱"，后者解决的是"线上出了错只能靠猜"。如果你也在写自己的 Agent 框架，或者正被 LLM 的非确定性折腾得睡不好觉，这篇的经验应该能直接平移过去用。

1. 先把问题聊透：Agent 框架是怎么变成"一坨"的

1.1 从能跑到失控，我经历的三个典型阶段

大多数 Agent 框架不是设计坏的，是长坏的。复盘我自己的实践路径，基本都逃不过三个阶段。

第一阶段是 demo 期。一个agent.py，两百行，循环里直接调模型接口，工具注册就是个字典，prompt 写在字符串里。这个阶段没有任何抽象，跑通一个 ReAct 循环就完了，根本不需要谈插件。

第二阶段是叠加期。记忆要接、工具要加、流式输出要上、重试要补。今天加一个if use_memory，明天加一个elif streaming，后天在循环里塞一个响应判空的补丁。等反应过来，核心的run()已经三百多行，里面全是分支和 Feature Flag。我见过最夸张的一个版本，核心循环里有七个布尔开关交叉组合，改一处要测八种排列。

第三阶段是协作期。不同小组要不同的模型供应商、不同的记忆策略、不同的工具集，但所有人都改同一个核心文件。每次合并都在打架，每次上线都要全量回归。到这一步，框架已经不是"难扩展"的问题，而是"根本动不了"。这个阶段最典型的表现是：你有过一些抽象，但抽象长在了错误的位置——不是沿着"变化点"切，而是沿着"上次谁着急改动"切。

1.2 全插件化的真正目标不是"扩展"，而是"隔离"

一说插件化，很多人第一反应是"抽象层太多会不会影响性能""为一个小功能搞这么重的机制值不值"。我的理解不太一样：全插件化的首要收益不是扩展性，是隔离。

隔离体现在三个层面。第一是改动的隔离——模型供应商从云厂商 API 换成内部模型网关时，只需要新增一个实现类，核心循环一行不动；第二是测试的隔离——核心逻辑可以对着一个假的模型提供者跑，不花钱、不等网络、不担心限流；第三是责任的隔离——记忆坏了查记忆插件，工具坏了查工具插件，不用在一个三百行的函数里从头断点。

想明白这个，设计目标就清晰了：Agent 框架的稳定内核应该是"流程骨架"。观察、决策、执行、再观察，这个循环永远不变；真正变化的，是每一环的具体实现。把循环写成骨架，把实现放进插件，这才是全插件化该有的样子。

1.3 我在 Harness 里划出的扩展边界

插件边界不能拍脑袋划。我的原则是：只有当一个扩展点出现了至少两次真实的替换需求，才把它正式提成接口。过早抽象出来的接口，往往连文档都写不清楚。

Harness 目前稳定下来的扩展点一共有七个，列在下面：

有两点我特意没做插件。一是 prompt 模板，它大部分时候是数据不是逻辑，用配置项表达更合适，做成插件反而让版本管理变复杂。二是事件序号分配，它是流程骨架自己的职责，交给插件容易乱序。

2. 插件接口的落地过程：继承、协议到注册表的三次迭代

2.1 第一版基类继承：改一个功能，崩一串插件

最开始 Harness 的插件机制很朴素：所有插件继承一个BaseAgentPlugin，里面预留钩子方法，比如on_user_message、on_tool_call、on_llm_response。

class BaseAgentPlugin: def on_user_message(self, message): ... def on_tool_call(self, tool): ... def on_llm_response(self, response): ... class MyPlugin(BaseAgentPlugin): def on_user_message(self, message): super().on_user_message(message) ...

跑了三个月，问题接踵而至。第一个问题是基类的"便捷方法"造成隐式耦合，子类悄悄覆盖某个方法，你只是改了基类里的日志格式，结果一串工具的行为全变了。第二个问题是多继承，工具插件想同时复用两个基类的行为时，Python 的 MRO 会把问题拖到运行期才爆。第三个问题是兼容性，往基类加一个新方法，等于给所有现存子类做一次全体回归，改一次伤一次。

2.2 第二版 Protocol：够灵活，但少了身份和配置

第二次迭代改用 Python 的 Protocol，结构化接口：

from typing import Protocol class ModelProvider(Protocol): async def chat( self, messages: list[dict], tools: list[dict] | None = None, ) -> ModelResponse: ...

好处是鸭子类型，测试可以传任意假实现，不再被基类绑死。真用起来短板也很明显：协议只约束了"能力长得什么样"，没有任何"身份信息"。注册表没法发现插件有哪些、吃什么样的配置、生命周期怎么管理。最后还得在入口函数里手动 import 一堆工厂再手动组装，插件化名存实亡。

2.3 第三版注册表：能力名、依赖解析、生命周期

第三版我把"描述信息"和"能力实现"绑在一起。每个插件带一份PluginMeta声明：名字、版本、提供的能力列表、依赖的能力列表、配置类。

# harness/plugin.py from dataclasses import dataclass @dataclass class PluginMeta: name: str version: str provides: tuple[str, ...] # 能力名，例如 ("llm.chat",) requires: tuple[str, ...] = () config_cls: type | None = None

注册表负责三件事：按能力名索引、按requires做拓扑排序、统一驱动生命周期。

# harness/registry.py class PluginRegistry: def __init__(self): self._factories: dict[str, type] = {} def register(self, factory: type) -> None: meta = factory.meta if meta.name in self._factories: raise PluginError(f"duplicate plugin: {meta.name}") self._factories[meta.name] = factory def provide(self, capability: str): for factory in self._factories.values(): if capability in factory.meta.provides: return factory raise CapabilityNotFound(capability)

依赖排序是这版的核心。插件声明requires=("event.sink",)，加载时先解析出完整的依赖图，再按拓扑序实例化。发现循环依赖时直接抛异常，并打印依赖图里的环，而不是在运行到一半时崩在某个调用里。这一步让我少了很多"为什么这个插件拿不到那个插件"的排查。

注意：插件间不要互相引用实例，要通过注册表按能力名拿。这样依赖方向永远是从插件指向框架声明的能力，而不是插件之间的实体纠缠。

插件生命周期我固定为五个阶段：load（实例化）、validate（配置校验）、start（打开连接）、runtime（提供服务）、stop（关闭连接）。模型提供者的 API 连接、工具插件的 HTTP 客户端，都在 start 里建立、stop 里释放，避免进程退出时一堆半开连接。

2.4 一个最小可用的工具插件长什么样

# plugins/weather_tool.py class WeatherToolPlugin: meta = PluginMeta( name="weather_tool", version="0.1.0", provides=("tool.weather",), requires=("event.sink",), config_cls=WeatherConfig, # pydantic 校验 ) def on_load(self, ctx): # ctx 是 PluginContext，只能通过它拿能力 self.sink = ctx.require("event.sink") self.api_key = ctx.config.api_key def on_stop(self): self.sink = None def execute(self, args: dict) -> dict: city = args["city"] self.sink.emit("tool.weather.request", {"city": city}) ...

核心循环里永远不会出现import weather_tool，它只调registry.provide("tool.weather")。这个习惯很关键：核心代码对具体插件的依赖降为零，替换、删掉、模拟任何插件都不碰主流程。

3. 可回放会话日志：把 Agent 的"脑回路"完整留下来

3.1 传统日志对付不了 LLM 的非确定性

传统日志的颗粒度，放在 Agent 场景里完全不够用。某个周五，运营来报：Agent 在第五步调用了一个不该调用的工具。我去翻日志，只看到一行tool_call search 返回成功。但真正要回答的问题是：模型当时看到了什么？上下文有没有被截断？工具参数是谁填的？回答不了这些，就只能复现——而 LLM 是非确定的，同一个输入第二次跑，结果可能完全不同。复现不了，就只能靠猜。

可回放日志的第一动机，就是把每一次决策的"输入-输出"完整留下来。不是记结论，而是记全过程。

3.2 事件溯源式日志：一次决策 = 一串事件

我在 Harness 里把一次 Agent 循环拆成四类核心事件链：

再加上session_start、user_message、session_end，整条时间线就是 Agent 的完整脑回路。设计时有三个硬规则：seq单调递增，保证顺序；payload 全量保存，宁可多不可少，因为事后你无法再向模型询问"你当时看到了什么"；所有外部调用必须落事件，漏一条，回放就断一节。

3.3 格式选择、落盘策略与脱敏

格式上我选了 JSON Lines 而不是 SQLite。原因有三：追加写天然适配流式；每行独立，可以直接tail观察；可压缩性很好，能与日志平台做管道对接。SQLite 查询能力强，但回放只需要顺序读，不需要复杂查询。JSONL 唯一要防的是 schema 漂移，所以schema_version从第 0 天就加上了。

{"schema_version": 1, "session_id": "sess_ab12cd", "seq": 5, "event_type": "tool_call", "ts": "2025-06-11T10:22:31.102Z", "payload": {"call_id": "call_03", "tool": "search_web", "arguments": {"query": "..."}}}

落盘策略踩过一个坑：一开始攒批写，进程被调度平台杀掉时，最后十步事件直接蒸发，回放残了。改成每条事件写入、会话结束时统一fsync一次。多花一点 IO，换来的是任何时刻宕机，已完成的步骤都完整。

脱敏同样不能省。LLM 的 prompt 里可能混着 API key、密钥、个人数据，这些如果原样进日志，回放日志就成了泄露源。我在事件出口层加了一个 Redactor 钩子，敏感字段统一替换成[REDACTED:类型:哈希前几位]，保留长度和形状信息，方便调试时对照。

3.4 为什么回放不等于重跑

必须把两个词分开：回放是按记录重演，重跑是重新调用模型。最本质的区别是：回放是确定性的，重跑是随机的。回放引擎会"骗"过程序——模型提供者接口返回的，是记录里那一条真实响应，而不是真的去调模型。这也是为什么回放能在毫秒级跑完上千步，而且每一步的结果都与线上完全一致。

4. 回放引擎的三个核心机制

4.1 时间线重建与断点注入

回放引擎的第一步是把一个会话的所有事件按seq排序，重建时间线：

# replay/timeline.py class Timeline: def __init__(self, events: list[SessionEvent]): self._events = sorted(events, key=lambda e: e.seq) self._idx = 0 def next(self) -> SessionEvent | None: if self._idx >= len(self._events): return None event = self._events[self._idx] self._idx += 1 return event

断点是回放里最有价值的功能。我把它做成条件对象，命中即暂停：

# replay/conditions.py class StopOn: def __init__(self, event_type: str, **filters): self.event_type = event_type self.filters = filters def matches(self, event: SessionEvent) -> bool: if event.event_type != self.event_type: return False return all( event.payload.get(k) == v for k, v in self.filters.items() )

暂停后可以检查该步的完整上下文快照，也可以临时改掉某个事件再继续。这里有个实现细节：我在step_end事件里直接保存了这一步之后的上下文快照，回放加载快照比从零逐条拼回去快得多，顺带还能校验事件链是否完整——快照对不上就说明日志有缺口，直接报警。

4.2 确定性保障：现场还原的关键

回放要成立，必须消除所有非确定因素。第一是模型调用，用注入替代，这是核心。第二是时间，工具逻辑里如果有人用了time.time()，回放时对不上，我会在回放模式里注入一个 Mock 时钟，时间轴从会话ts起步。第三是内部随机数，凡是框架自己生成的随机数，种子统一从session_id派生，保证同一会话结果一致。

还有一个隐蔽问题：Python 的字符串哈希受随机种子影响，大多数场景无所谓，但当你按 dict 顺序序列化事件 payload 时，哈希随机化可能影响顺序，导致回放结果与真实现场出现细微差异。我的做法是序列化前统一按 key 排序，而不是去固定PYTHONHASHSEED——固定整个进程的哈希种子会改变哈希碰撞面，有安全顾虑。

铁律：回放引擎绝不调用真实模型，绝不执行带副作用的工具。这条约束我写进了代码注释，并在假的模型提供者实现里做了强制断言，防止后人"优化"掉确定性。

4.3 三种回放模式：重演、断点巡检、分支实验

回放引擎实际使用时有三种模式，用途完全不同：

分支实验是后期加的需求，也是最能给团队惊喜的。某次线上事故我们怀疑是工具返回里混进了一条脏数据，直接加载会话，定位到tool_result事件，把 payload 替换成清洗后的数据，再让真实模型从这一分支继续跑，一对比就确认了根因。整个过程十分钟，不用重新构线上环境。

events = load_session("sess_ab12cd") branch = Timeline(events).seek(seq=7) branch.replace(seq=7, event_type="tool_result", payload={...}) harness = Harness(live_model=True) harness.play(branch)

5. 项目落地时的六个坑，以及我的取舍

5.1 坑一：插件加载顺序与循环依赖

循环依赖初期出现过好几次，最典型的错误发生在两个插件都想"互相拿对方的配置"，结果谁先加载都不对。解法是前文说的拓扑排序加环检测，不再赘述。真正想提醒的是：插件加载阶段不要 import 任何其他插件模块，只保留能力名依赖。一旦你在 load 里直接import weather_tool，循环依赖就从"可能发生"变成"必然发生"。

5.2 坑二：日志 schema 升级，旧日志全部作废

上线第三周我往事件 payload 里加了一个字段，然后发现所有旧日志在回放引擎里解析失败。教训是：即使日志只是内部用，schema_version也要从第一天带着。现在每次 schema 变更都升版本号，回放引擎按版本分发解析器，旧日志依然可读。兼容层代码不多，但少了它，历史会话就是一堆打不开的 JSON。

5.3 坑三：回放时的副作用拦截

重演模式里我们不会真正执行工具，因为结果已经记录在案。但分支实验模式会继续调用真实工具，这时如果工具是"发邮件""写数据库"这类有副作用的，就会造成二次影响。解法是在工具注册时强制声明effectful=True，分支实验里遇到这类工具默认用记录结果替代，只有人工显式确认后才允许真实执行。宁可牺牲一点便利，也不能让调试工具变成事故放大器。

5.4 坑四：日志体积、脱敏与 IO 开销

完整 prompt 加完整响应加工具输出，一步轻松几十 KB，一百步就是一个会话几 MB。如果不控制，磁盘和回放性能都会告急。我的取舍是：不做事件采样，回放完整性优先；对超大工具结果做截断策略，保留前 N 个字符加哈希；日志按会话文件存储，按大小和时间滚动压缩。因为选了 JSONL，压缩率很可观，冷数据基本上压缩到原来的十分之一。

IO 开销方面，单条事件写盘在机械盘上确实有压力。解决思路是事件出口用异步队列写，正常路径批量刷盘，但在step_end和会话结束两个关键节点强制 flush。这样既保住了完整性，又没有把每次模型调用都变成一次磁盘等待。

5.5 坑五：不要把"热更新插件"想得太美

Python 的 import 机制决定了，模块热替换很难做干净。importlib.reload只能重载模块对象，但所有已经持有旧类引用的地方不会自动切换。我的结论是做"配置热更新 + 代码冷重启"：插件配置可以在运行期变更（换 API key、调阈值、开关按钮），插件代码变更必须走正常的发布流程。真想做到代码级热加载，那就得把插件放到独立的子进程里跑，这是另一种量级的架构，不建议从小框架起步就上。

5.6 坑六：插件化过度设计的边界

全插件化不是"把所有东西都变成插件"。我的判断标准很直接：如果只有一个实现，且未来一年内都只会有一个实现，就不做成插件。核心循环、会话 ID 生成、事件序号分配，这些永远是骨架自己的事。把它们插件化，只会得到一团互相依赖的抽象，调试时每跳一层都要骂一次。

这整套设计实际跑下来，单看任何一环都不难，难的是它们互相咬合。插件隔离让回放引擎可以作为一个特殊插件接进框架，回放日志又让每个插件的问题能快速定位到具体版本。如果让我重来一次，我会更早地把事件日志的schema_version加上，也会更早地为带副作用的工具打上effectful标记。给后来者的建议是动手顺序：先定事件格式和 schema，再切插件边界，最后做回放引擎——这个顺序能让你少走很多弯路。