1. 为什么是 Harness：核心架构与边界设计

先交代一下背景：我最近半年一直在做基于 DeepSeek 模型接口的 Agent 应用，从最早的“一个 while 循环套模型调用”的 Demo，一路演进到一个需要支撑多工具、多用户、多会话并发的小型平台系统。这个过程中踩了不少坑——最痛的不是模型本身不够聪明，而是应用层的胶水代码越堆越乱，工具互相影响，出了错没法复现。所以才有了那个被我命名为 DeepSeek Harness 的项目，而这篇文章就是对这个项目做一次工程层面的完整解剖。

1.1 Harness 在 Agent 语境里到底指什么

很多人第一次听到“Harness”这个词会愣一下，觉得不如用 Framework、Runtime 这种熟词。但实际上 Harness 在工程语境里有个很精准的指向：它是一套“把受控对象约束在可预期轨道上的框架”的意思。测试领域里叫测试夹具，把被测对象固定住；在 Agent 领域里，Harness 的核心不是替你写好业务逻辑，而是把模型推理、工具调用、上下文维护、日志记录这几件极其容易失控的事情，约束进一套统一的控制循环里。

所以这个项目从一开始就定义了两条不可妥协的原则：第一，业务能力一律外置成插件，内核不写死任何一个具体工具；第二，所有发生在循环里的关键事件必须落盘成结构化日志，而且这份日志得能支撑事后完整回放。这两条原则直接决定了整个项目的架构走向。

我见过太多 Agent 项目死在半路上，原因倒不是模型能力不够，而是工程上没法迭代——改一个工具的入参格式，要动三处代码；跑一次会话出了问题，对着终端日志根本看不出当时模型拿到的是什么上下文。Harness 这个设计就是为了把这些工程问题前置到框架层解决。

1.2 整体模块划分：内核、桥接层、会话管理层

DeepSeek Harness 的整体模块划分其实很传统，但每层职责砍得非常清晰，这也是我给你建议时最想强调的一点：不要把 Agent 框架做成一个大泥球。

• 调度内核：跑着统一控制循环，负责“取事件、派发给模型、收集插件结果、决策下一步”这个循环本身。它不关心具体模型是哪家，也不关心工具做的是什么。
• 插件桥接层：所有插件通过统一协议接入，内核只认协议，不认实现。这个桥接层解决的是“插件各自为政”的问题。
• 会话管理层：维护一次会话的上下文窗口、会话状态快照、用户身份与隔离信息。它和模型调用解耦，回放时甚至可以把模型换成 mock。
• 日志与回放引擎：所有关键事件以追加写方式落盘，并提供一套回放器把日志重新“演”一遍，支持在回放过程中用记录替换模型输出。

这个分层的好处是：替换模型不需要动插件代码，新插件不需要动内核代码，排查问题不需要翻散落各处的 print。模块之间只有接口依赖，没有实现依赖。

1.3 为什么这个设计比单体 Agent 更抗迭代

对比一下两种方案。单体 Agent 通常把“工具列表、模型选择、上下文拼装、会话历史”全部写在一个类里，demo 阶段确实爽，改什么都快。但一旦工具数量超过五个、会话持续多轮、需要接入多人使用时，单体类就开始变成维护者的噩梦：加一个工具要小心翼翼，因为工具 A 可能改了共享状态，影响工具 B 的行为；上下文拼装逻辑散落在各个回调里；日志只能用 print 凑合。

而 Harness 架构把可变点全部推向边界。内核只维护一个极稳定的状态机，插件是热插拔的，会话是独立可序列化的。我在把第一个真实工具（一个内部知识库查询插件）接入 Harness 时，全程只写了插件文件本身，内核代码一行没改。这种“框架稳定、能力外置”的取舍，就是 Harness 和其他 Agent 脚手架最大的区别。

提示：如果你现在维护的 Agent 项目已经开始出现“改一处崩两处”的征兆，尽快把业务能力往协议后面抽，别等代码到了几千行再重构。

2. 全插件化：从接口协议到注册中心的工程细节

插件化是 Agent 框架最容易被做“虚”的部分。很多框架说自己插件化，其实就是提供了一堆抽象基类，子类继承后挂到一个列表里。这种写法应付小规模没问题，但真正的工程化插件体系至少要解决三件事：插件如何声明自己的能力、插件之间如何隔离、插件如何被动态装载和卸载。

2.1 插件协议设计：协议优先于继承

我在 Harness 里做插件协议时，刻意没有用抽象基类（ABC），而是用了鸭子类型的 Protocol。这不是炫技，而是有实际考量：抽象基类要求所有插件必须继承同一个类，这在 Python 里意味着单继承限制和明显的类型耦合；而 Protocol 只约束“你实现了这几个方法就行”，插件实现者完全可以用自己的类体系，只要行为适配协议就能接入。

以模型接口的适配器为例，所有插件需要满足这样一套基础协议：

from typing import Any, AsyncIterator, Protocol, Dict, List class AgentPlugin(Protocol): """定义 Harness 插件必须实现的生命周期方法""" async def initialize(self, context: dict) -> None: """插件初始化，context 中注入配置和共享资源""" def capabilities(self) -> List[str]: """返回插件能处理的事件类型列表""" async def execute(self, event: dict, runtime: dict) -> dict: """执行插件核心逻辑，返回统一结构的结果""" async def teardown(self) -> None: """释放插件占用的资源"""

这套协议的关键心法在于capabilities方法。内核在派发事件时，不是把事件广播给所有插件，而是先读插件声明的能力标签，只把事件分发给对口的插件。这个机制避免了插件之间互相干扰，也为后续做插件级并发控制打好了基础。

2.2 注册与发现机制：三种方式谈清楚

插件不是通过 import 硬编码进系统的，Harness 支持三种注册方式，按应用场景灵活选择：

• 装饰器注册：在插件类定义处加@harness_plugin，框架在启动扫描指定包时自动收集。这是开发期最顺手的方式，代码即注册。
• 配置清单注册：通过 YAML/JSON 配置文件显式列出插件类路径和参数。生产环境推荐这种方式，因为运维可以通过配置中心动态调整插件组合，不用重新部署代码。
• 目录扫描注册：指定一个插件目录，框架扫描目录下所有符合命名约定的模块并尝试装载。适合做开放生态，但要注意模块安全校验。

我实际跑下来，开发环境用装饰器，生产环境强烈建议切到配置清单。原因很实在：装饰器声明散落在代码里，你没法一眼看清当前环境到底加载了哪些插件；配置文件则一目了然，而且方便做多环境差异化配置。

2.3 插件失败隔离与资源治理

插件一旦多了，最大的工程风险是“一颗老鼠屎坏了一锅汤”。一个插件超时阻塞，可能导致整个控制循环卡死；一个插件抛异常，可能污染会话上下文。Harness 在这块做了三道防线：

第一道是超时控制。每个插件执行外面包了一层asyncio.wait_for，超时后直接取消任务并返回超时错误事件，而不是让它无限期占用循环。第二道是并发信号量。插件可以声明自己的最大并发数，比如数据库查询插件并发上限设为 2，避免突发的多会话同时调用把数据库打崩。第三道是错误隔离。插件的异常会被捕获并转换成标准化错误事件，控制循环根据错误事件决定是重试、换策略还是终止会话。

这三道防线听着简单，但你如果自己实现过就会发现，关键是内核对“插件失败”这件事有统一的理解：失败只是事件流里的一个普通事件，而不是打断循环的例外。这个思维转换很重要，它让你能用状态机的视角去看整个 Agent 运行过程。

3. 可回放会话日志：让 LLM 应用可调试、可测试、可审计

说实话，可回放会话日志才是这个项目里我觉得价值最大、也最难做好的部分。LLM 应用有个天然痛点：模型输出是不确定的。同一个 prompt 两次调用，结果大概率不同。这就导致你很难定位“这个 bug 是模型抽风还是我代码写错了”。可回放日志要解决的就是：把一次会话的每一次关键决策记录下来，事后能精确重演当时发生了什么。

3.1 事件溯源思路：把日志当数据库写

传统日志是“打印给人看”的，而 Harness 的会话日志是“结构化成事件流”的。每条日志记录不是一个字符串，而是一个带类型、时间戳、会话 ID、载荷的 JSON 对象。一次完整会话产生的日志，本质上是一串有序事件：用户输入事件、模型请求事件、模型响应事件、插件调用事件、插件结果事件、内部状态变更事件。

这里我借用了事件溯源（Event Sourcing）的思想：会话的当前状态不是直接保存的，而是可以通过重放事件流还原出来的。这有一个特别大的好处——你不必在日志里保存一份容易过期的“当前状态快照”，只要事件流完整，任何时刻的状态都能重建。

设计上，每一轮循环产生的事件组是这样一串结构（缩略示例）：

{ "session_id": "6f3c9a1e", "event_seq": 42, "event_type": "plugin_exec", "ts": "2024-12-08T15:04:05.123Z", "plugin_name": "search_kb", "input": {"query": "harness 插件协议", "top_k": 5}, "output": {"items": ["Plugin protocol ..."]}, "duration_ms": 231, "status": "ok" }

3.2 录制什么：不止是模型输入输出

刚开始做时我只记模型请求和响应，日志量小了，但回放时发现根本不够——工具的中间输出、上下文窗口的截断行为、重试策略的触发条件，全都没有记录。后来我重新梳理了一份“必须录制”清单：

• 模型请求快照：完整 prompt、参数（temperature、max_tokens 等）、模型名与版本。
• 模型响应快照：完整输出、token 用量、延迟。
• 插件调用快照：入参、出参、异常堆栈、耗时。
• 上下文生命周期：每轮上下文追加了什么、因为超长被裁剪了什么。
• 决策轨迹：路由逻辑选了哪个插件、重试策略怎么触发的。

这份清单听着条目多，但实现起来并不复杂。核心就是内核提供了两个埋点：一个在模型调用前后，一个在插件调用前后。所有事件走同一套序列化管线，统一落盘。

3.3 回放引擎：用记录替代模型输出实现确定性复现

录制只是存储问题，回放才是技术难点。Harness 的回放引擎有两种模式：

第一种是模拟回放模式。回放器截断真实的模型调用，把日志里记录的模型响应直接塞给控制循环，插件仍然真实执行。这种模式的用途是调试工具逻辑：如果上次会话里模型说“调用 search_kb 搜 XX”，回放时就真的再调用一次 search_kb，通过对比两次插件执行结果，定位到底是不是插件代码改出了回归问题。

第二种是验证回放模式。保持模型真实调用，但把插件结果替换成日志里的旧值。这种模式用来做模型回归评测——在插件输出固定的条件下，看当前模型版本是否还会做出和以前一样的决策，用来验证 prompt 修改或模型切换是否破坏了原有能力。

这两种模式加在一起，让“跑一次真实会话”变成“可以在不同约束条件下反复演练的实验”。我现在每次改插件代码，第一件事不是跑新的 demo 对话，而是把历史会话日志回放一遍，确认没有破坏任何旧场景。这已经变成了我的工程习惯。

4. 最小可运行框架的实现路径

理论讲再多，不如直接看代码。这一节我带你从零搭一个最小可运行的 Harness 雏形。我刻意把代码量控制在两百行以内，但麻雀虽小五脏俱全。

4.1 控制循环：Agent 的心脏

控制循环是 Harness 的最小可运行心脏。它的职责非常清晰：消费会话中的事件队列，调用模型获取决策，根据决策派发插件执行，把结果写回上下文，然后循环往复，直到模型产出终止信号。

import asyncio from datetime import datetime, timezone class MiniHarness: def __init__(self, model, registry, recorder): self.model = model self.registry = registry self.recorder = recorder async def run(self, user_input: str, session: dict): context = session.get("context", []) context.append({"role": "user", "content": user_input}) for _ in range(session.get("max_steps", 20)): events = [] # 1. 模型决策，录制模型请求响应 self.recorder.record("model_request", {"prompt": context}) decision = await self.model.decide(context) self.recorder.record("model_response", {"decision": decision}) # 2. 模型认为可以结束，退出循环 if decision.get("action") == "finish": context.append({"role": "assistant", "content": decision.get("output", "")}) break # 3. 根据决策派发插件执行 plugin = self.registry.get(decision["action"]) if plugin is None: self.recorder.record("unknown_action", {"action": decision["action"]}) break self.recorder.record("plugin_start", {"action": decision["action"]}) result = await plugin.execute(context, decision.get("args", {})) self.recorder.record("plugin_end", {"result": result}) # 4. 把工具结果注入上下文 context.append({"role": "tool", "name": decision["action"], "content": str(result)}) return context[-1]["content"]

这段代码虽然简化到极致，但已经能看出来 Harness 的核心约束：循环、录制、路由三件事被隔离得很清楚。你往里面加日志、加重试、加超时，都是在固定位置做加法，而不是到处乱插。

4.2 日志录制器：把事件流稳定落盘

录制器不能只写文本，必须写成结构化事件。我在最小实现里用了一个非常简单的 JSONL 写入器：

import json, os class JsonlRecorder: def __init__(self, path, session_id): self.session_id = session_id self.seq = 0 self.buffer = [] self.fh = open(path, "a", encoding="utf-8") def record(self, etype, payload): self.seq += 1 event = { "session_id": self.session_id, "event_seq": self.seq, "event_type": etype, "ts": datetime.now(timezone.utc).isoformat(), "payload": payload, } self.buffer.append(json.dumps(event, ensure_ascii=False)) if len(self.buffer) >= 10: self.flush() def flush(self): if self.buffer: self.fh.write("\n".join(self.buffer) + "\n") self.buffer.clear() def close(self): self.flush() self.fh.close()

注意这里的缓冲批量写。在实际生产里，每秒可能会产生几十条事件，如果每条事件都直接write加flush，磁盘 IO 会拖慢整个循环。批量化之后，IO 压力小很多，而且进程崩溃时最多丢一个批次（通常也就十条事件），对调试影响很小。

4.3 回放入口：最简可用的重放器

回放器的最小实现也只需要做一件事：逐行读取 JSONL，把model_response事件里的 decision 塞回给一个替身模型。替身模型不真正访问模型接口，只是根据事件序列“照着演”。

class ReplayModel: def __init__(self, log_path): self.recorded = {} idx = 0 with open(log_path, encoding="utf-8") as f: for line in f: evt = json.loads(line) if evt["event_type"] == "model_response": self.recorded[idx] = evt["payload"]["decision"] idx += 1 self.cursor = 0 async def decide(self, context): if self.cursor not in self.recorded: raise RuntimeError("回放数据不足，日志不完整") decision = self.recorded[self.cursor] self.cursor += 1 return decision

把ReplayModel传给MiniHarness，跑出来的轨迹就和原会话完全一致——前提是插件逻辑没有改变。如果插件逻辑变了，回放会在某一步产生不同的插件输出，这时你就能在对比中精确看到：是哪一次插件行为变化导致了后续决策链的连锁反应。

注意：回放模式最常用的一个场景，是把旧会话里出现过的“坏决策”拿出来，配上修复后的插件代码重跑一遍，验证它现在是否能被正确纠正。这类回归测试比人工对话验证高效太多。

5. 常见问题与排查技巧实录

任何框架在真实使用中都会遇到一堆文档里没有的怪问题，Harness 也不例外。这一节我把实际踩过并且值得分享的坑整理出来，按问题现象、原因、解决路径的格式列一下。

5.1 回放结果与原始会话不一致

这个问题在我前几次回放时几乎必现。明明用的是同一份日志，回放出来的决策轨迹和原始会话却对不上。排查下来原因很典型：插件是不确定的，或者模型请求日志没有记录全。

具体来说，如果你的插件里有一个读时间的操作、一个读环境变量的操作，或者一个访问外部接口获取“当前值”的操作，那么回放时即便决策相同，插件输出也会不同，进而影响后续上下文。这类问题不能靠“让插件完全确定”解决——真实业务里插件就是会读外部状态。

我的解决方案是：回放时把插件结果也分成两类，一类是“关键结果”强制回归（用旧值回放），一类是“实时结果”允许变化（真实执行）。这样在断言决策链时就不会被外部状态波动干扰。这个思路对应到模式就是上面说的验证回放和模拟回放之别。

5.2 插件热更新后旧日志回放报错

插件版本升级后，老日志里记录的插件入参格式可能已经不兼容了。比如旧版插件入参是query，新版改成了search_text，回放旧日志就会 KeyError。

这个问题没有银弹，只能在插件侧做兼容层。我在插件基类里约定了一个adapt_legacy_args钩子，每个插件可以声明老版本参数如何映射到新版本。回放器加载日志时，如果发现版本号不匹配就自动调用这个钩子。这个机制让我的回放测试用例可以跨多个版本长期保存，不会因为升级就全部作废。

5.3 日志文件膨胀得太快

一次完整的长会话可能产生数千条事件，如果每条都带完整 payload，单个会话日志能到几 MB。多个用户、多个会话累积下来，磁盘压力很大。

我的做法是分级存储：近期日志用高保真格式存在热目录，便于调试；超过七天的日志做一次缩略处理，把插件 payload 裁剪成摘要字段，只保留事件轮廓。回放器碰到缩略日志时，会自动从详细度更高的备份中补全。

这里也可以分享一个小技巧：录制器落盘时把字符串字段统一做一次json.dumps去空白，能显著降低日志体积；代价仅是日志不再适合人肉阅读，但对机器回放毫无影响。

5.4 排查流程沉淀成清单

经过几个月的使用，我把排查流程固定成了下面这一套操作顺序。无论问题是模型决策错误还是插件异常，我都按这个流程走：

先看事件时间线（把所有事件的event_type和时间戳列出来，确认问题发生在哪个环节）；然后看模型决策序列（决策是顺序记录在事件流里的，对照业务预期逐条检查，能快速圈定是第几步出的问题）；再看插件调用详情（明确决策正确但工具执行失败，还是工具结果正常但决策逻辑有问题）；最后做差分回放（修复后重新回放同一份日志，对比修复前后的分叉点）。

这套流程最大的价值是省掉了肉眼盯打印日志的时间。以前出了 bug 要看半天终端输出，现在直接对着事件结构做查询，效率和准确率完全不是一个量级。

6. 从工程实践到下一步扩展

Harness 这个形态做得越久，我越觉得 Agent 框架的趋势是从“模型为中心的套壳”走向“可观测、可回放、可评测的工程底座”。全插件化解决的是组织与扩展问题，可回放日志解决的是信任与迭代问题——这两个问题恰恰是 LLM 应用从实验品走向产品的两道大坎。

6.1 比较：Harness 与常见替代方案的取舍

如果你也在评估要不要搭建类似的东西，我帮你理清一下 Harness 方案和其他常见做法的边界。市面上现成的 Agent 编排框架很多，功能往往更丰富，但引进大而全的框架通常意味着你要接受它的协议约束、数据格式和部署方式。Harness 这种自研轻量方案则相反——它只强制你遵守“协议”和“日志”这两件事，其余全部开放。

这个取舍在团队小、场景独特时尤其值得。我的真实体会是，与其花大量时间学习一个大框架的各种高级特性，不如用 20% 的精力把 Harness 的最小骨架搭好，剩下 80% 的精力放在业务插件的打磨上。毕竟 Agent 项目最终的竞争力来自业务能力质量，而不是框架多炫。

6.2 可扩展方向：可视化时间线、会话差分、自动回测

Harness 目前的回放还停留在命令行对比层面，但这套事件流的延伸空间其实很大。

我下一步准备做的是可视化时间线：把一次会话渲染成一张按时间展开的泳道图，左边是模型决策，右边是插件调用，中间用箭头画出上下文流动。调试者一眼就能看到“模型在这里决定调用工具，但工具结果让模型改变主意”的完整链路。另一个方向是自动化回测——把历史会话整理成回归语料库，每次修改框架或插件就跑一遍全量回放，把回放分叉点汇总成报告。我已经验证了这个流程的可行性，效果非常理想，唯一要花功夫的是积累足够多的高质量会话样本。

6.3 最后分享一点个人体会

这套框架从最初的八百行实验代码，演进到现在的稳定形态，中间推倒重来了两次。第一次重来是发现插件之间互相污染状态，第二次是发现日志记录不够细导致回放残缺。现在回头看，这两个问题其实在设计阶段就能规避——只要把“能力外置”和“事件溯源”这两条主线从一开始就焊死在架构里。

如果你正在做类似的 Agent 项目，我的核心建议是：内核代码一定要极度克制，宁可把功能放在插件里让它们“野蛮生长”，也不要让内核变成什么都干的管家；日志事件一定要从第一天就结构化，千万不要觉得“等上线后再补日志”来得及——等到你需要回放一个三天前的会话去定位线上问题时，基本就晚了。

文章写到这里，我不打算再做多余的总结。用一句话收束吧：Agent 的智能可以交给模型，但 Agent 的可靠性必须由工程来兜底，Harness 的设计哲学就是为此服务的。