1. 为什么我要折腾一个 Agent 的 Harness 层先说个场景。某天凌晨两点我负责的 Agent 任务又跑挂了。爬起来打开日志看到的是一堆散落在不同文件里的记录模型调用的请求响应、工具执行的入参出参、状态机的迁移记录……彼此之间没有关联时间戳对得上但因果链全断。我花了三个小时才拼出事情经过原来是工具 A 返回了一个异常格式Agent 错误地选择了重试重试时又把同一个脏数据传给了工具 B最后在工具 B 那边炸了。问题不在 Agent 本身而在运行环境。模型的推理能力再强没有一套能把每一步发生了什么、为什么这么做、做完之后世界变成什么样完整记录下来的底座调试就是灾难。那一刻我下定决心不能再用拼凑的脚本把 Agent 串起来了必须给 Agent 套一个真正的Harness——一个可控、可观测、可扩展的运行时外壳。这个项目后来被我叫作 DeepSeek Harness。核心就两件事一是把 Agent 的所有能力工具、记忆、策略全部插件化主流程不写死任何具体实现二是把会话过程完整落盘成可回放的事件日志任何一次运行都能像倒带一样重看。这篇文章就把这两块工程化设计从头到尾拆一遍包括我踩过的坑和最终的取舍方案适合已经在用各类 Agent 框架、但想更进一步掌控运行时的开发者参考。很多人问市面上框架那么多为什么还要自己造我的回答是框架解决的是怎么把 Agent 跑起来Harness 解决的是跑起来之后怎么控制它。两者是不同层面的东西。用过一段时间之后你会发现模型能力的天花板往往不是模型本身而是你手上那套运维工具的粒度——日志够不够细、能不能回放、插件能不能热插拔、出了故障能不能快速定位。这些才是一个 Agent 系统从 Demo 走向工程化的分水岭。2. 从 Demo 到工程化中间差了一整个可观测层2.1 裸跑 Agent 时你根本没意识到的问题大多数人在本地跑一个 Agent Demo 时流程是写一个 while 循环调模型拿结果判断要不要调工具再调模型……跑通了就觉得很顺。但一旦进入真实业务你会发现几个藏得很深的问题。第一个问题是黑盒。模型返回了一大段 JSON里面有 thoughts、tool_calls、final_answer。你看到了结果但看不到模型内部的决策依据——它为什么选择先查数据库而不是先调搜索这个不可问的状态在单轮 Demo 里无所谓但在多轮复杂任务里你会被迫接受模型说什么就是什么根本没办法干预和校准。第二个问题是状态散落。为了把任务做完你会维护一堆上下文变量当前计划、已完成步骤、待执行队列、工具间传递的临时数据。这些变量散落在代码各处一旦流程中断超时、报错、模型输出格式异常恢复现场基本靠运气。第三个问题是无法重放。线上跑出一个诡异结果你想让模型再跑一遍但上下文变了、工具返回变了、模型采样也有随机性——同样输入、同样代码结果对不上。于是你没法定位到底是哪一步引入的问题。这三个问题归到底都是同一个根因Agent 运行时缺少一个统一的数据面和控制面。模型调用是数据面的一部分工具执行是数据面的一部分状态迁移也是数据面的一部分但它们没有一个统一的采集通道和统一的控制入口。2.2 Harness 层到底管什么所以 Harness 层管的东西不是Agent 的业务逻辑而是 Agent 运行时的六大横切关注点关注点裸跑时的状态Harness 的目标模型调用直接调 SDK参数散落统一入口记录每次请求与响应工具执行函数指针到处传插件化注册带鉴权和限流会话状态全局变量或 context 对象结构化状态包可持久化日志记录print 或 logger 随手打结构化事件流可回放错误处理try-except 层层包统一错误边界故障可诊断配置管理环境变量 硬编码分级配置插件独立配置块你可能会说这些用现成的框架也有啊。没错很多 Agent 框架都有 session、trace、tool 列表这些东西。但深度用下来你会发现框架给的是默认能跑的最小实现而工程化需要的是任何一环出问题你都能把它抠出来查清楚的深度控制。具体到我这个项目Harness 的定位是不取代任何 Agent 框架它是在框架下面的一层运行时基础设施。你可以把它理解成Agent 是发动机Harness 是底盘。发动机决定车能跑多快底盘决定你能不能安全可控地让它跑。2.3 我选择的两个核心抽象在动手写代码之前我先定了两个核心抽象后面的所有设计都围绕它们展开。第一个抽象是Step。一次 Agent 运行被拆成若干 Step每个 Step 要么是一次模型调用要么是一次工具执行要么是一次状态迁移。每个 Step 都有全局唯一的序列号、入参、出参、耗时、状态。所有 Step 串起来就是一次完整的会话事件流。第二个抽象是ReplayableSession。一次会话是一个持久化对象里面装了三样东西会话头模型配置、插件版本、全局参数、事件索引Step 序列、状态快照关键节点上的完整上下文。有了这三个东西回放就变成了纯粹的确定性计算。这两个抽象看起来简单但它们把前面提到的三大问题全解决了Step 解决黑盒问题每一步都可见ReplayableSession 解决状态散落问题上下文可恢复事件流 快照解决无法重放问题。后面两节就详细展开这两块是怎么落地的。3. 全插件化设计把 Agent 的每项能力变成可插拔零件3.1 插件协议随便写个函数不叫插件化先说一个很多人理解上的偏差。插件化不是写个函数注册进来就行而是运行时与实现之间有一条稳定的协议边界。这条边界决定了哪些事情由框架管、哪些事情由插件管双方如何通信出了问题谁负责。我在 DeepSeek Harness 里定义的插件协议包含四个部分元信息声明插件名称、版本、依赖的框架版本、作者描述、权限声明需要访问哪些资源、调哪些外部系统。生命周期钩子on_load加载时初始化、on_ready就绪检查、on_shutdown卸载时清理。这三个钩子让框架能管理插件的完整生命周期而不是加载了就听天由命。执行入口一个统一的invoke(payload, context) - result接口。所有工具类插件都实现这个接口框架用同一个签名调度不区分你是查数据库、调 HTTP API 还是跑一段本地代码。输出约束插件必须返回结构化结果我定义了一套统一的 Result 包装包含 code、data、error、trace_id不允许丢一个裸字符串或裸对象出来。这个协议一旦定下来主流程就可以非常干净。伪代码大概长这样class PluginBase: name: str version: str permissions: list[str] async def on_load(self, config: dict) - None: ... async def on_ready(self) - bool: ... async def invoke(self, payload: dict, ctx: StepContext) - PluginResult: ... async def on_shutdown(self) - None: ...看到没有框架完全不关心插件内部是怎么实现的。你爱用同步还是异步内部调 SQLAlchemy 还是 requests都是插件自己的事。框架只认这个接口。这就是插拔能力的根基——协议稳定实现自由。3.2 注册中心你总得有个户口本只有协议还不够还得有一个所有插件都能被找到、被校验、被依赖解析的地方。这就是插件注册中心。我实现了一个三层结构的注册中心静态声明层启动时从配置目录扫描所有插件的 manifest 文件我用的 YAML建立全局插件清单。动态加载层按照依赖关系排序后逐个执行on_load实例化插件对象注入共享的上下文日志句柄、配置对象、外部客户端。健康检查层定期调用on_ready如果返回 False 或抛异常把插件标记为不可用路由时自动跳过。这个注册中心解决了一个很实际的问题插件之间的依赖关系。举个真实例子我写了一个数据库查询插件又写了一个数据脱敏插件脱敏插件依赖查询插件返回的元信息。如果注册中心不做依赖解析加载顺序错了脱敏插件初始化时拿不到查询插件直接跑崩。我的做法是在 manifest 里声明depends_on注册中心做一次拓扑排序。这个思路直接移植自微服务里的依赖治理在 Agent 插件系统里同样适用# manifest.yaml name:>
