Harness as a Language：JAZ 如何把 Agent 执行环境工程化

1. 从 JAZ 这个标题说起：Harness 为什么值得被当成一门语言来对待

第一次看到“Harness as a Language”这个说法，我的反应是：终于有人把这件事挑明了。过去两年，大家聊 Agent、聊 LLM 应用，注意力几乎都压在模型本身——参数多大、上下文多长、榜单排第几。但真正在一线把 Agent 跑起来的人心里都清楚，模型只是发动机，决定这台车能不能上路、能不能跑长途的，是外面那层壳：工具怎么挂、状态怎么存、失败怎么重试、权限怎么收口。这层壳，英文里常被叫做 Harness。

JAZ 这个研究最抓人的地方，不是又提出了一个 Agent 框架，而是换了个视角：把 Harness 从“一堆胶水代码”提升到“一门语言”的高度来设计。这个视角的转变，直接决定了后面所有的工程取舍。你把它当胶水，它就是一堆 if-else 和 try-catch；你把它当语言，它就得有语法、有语义、有作用域、有组合规则、有错误模型。这两种心态写出来的东西，维护成本差着一个数量级。

我先把结论摆在前面，方便你对号入座：如果你只是想让模型调一两个 API 做个 demo，那 Harness 是不是语言无所谓，怎么写都能跑。但只要你开始面对多工具、多轮次、多 Agent 协作、需要回退和审计的真实场景，Harness 的设计质量就会变成整个系统的天花板。JAZ 想解决的，正是这个天花板问题。

这篇文章我会按一线落地的顺序来拆：先讲清楚 Harness 和 Agent 到底怎么分工，再讲 JAZ 把 Harness 语言化背后的设计逻辑，然后是核心机制怎么落地、实操里怎么搭、踩坑怎么排。全程按“能抄作业”的标准写，参数和步骤我都会给到能直接用的程度。

1.1 先把概念钉死：Harness、Agent、LLM 三者到底谁管什么

很多人一上来就混着用这三个词，结果架构图画出来自己都说不清边界。我用一个生活化的类比把它钉死：LLM 是那个脑子很好使但只会动嘴的顾问，Agent 是带着这个顾问去干活的项目经理，Harness 是项目经理手里的那套流程手册加工具箱。

具体到职责：

• LLM：负责理解和生成。你给它一段上下文，它吐出下一步该干嘛的意图。它本身没有记忆、没有手脚、不能真的去调接口。它的输出是“文本形式的决策”。
• Agent：负责把 LLM 的文本决策翻译成真实动作，并维护“我是谁、我在找什么、我能提供什么”这套状态。它决定什么时候该问 LLM、什么时候该直接执行、什么时候该停。
• Harness：负责提供 Agent 执行动作所需的一切基础设施——工具的注册与调用、参数的校验、执行结果的规范化、错误的分类与重试、上下文的拼装与裁剪、权限与沙盒的边界。

热词里有个说法特别形象：LLM 的 token 三个点是 key“我是谁”、query“我在找什么”、value“我能提供什么”。这其实是在说注意力机制，但借到 Agent 语境里也成立——Agent 每一轮都在回答这三个问题，而 Harness 就是保证这三个问题能被稳定、可复现地回答的那层机制。

注意：把 Harness 和 Agent 混为一谈，是新手最容易犯的架构错误。Agent 是决策者，Harness 是执行环境。决策逻辑可以换模型、换 prompt，但 Harness 一旦定下来，整个系统的行为边界就定了。

1.2 为什么“语言化”不是玩概念，而是被逼出来的

我踩过的坑很典型：早期做 Agent，工具调用就是手写函数，模型返回个 JSON，我json.loads一下，然后if tool_name == "search": ...。三个工具的时候还行，十个工具就开始乱，三十个工具的时候，光参数校验和错误处理就能写出一千行，而且每加一个工具都要动核心逻辑，测试根本覆盖不过来。

这就是“胶水心态”的必然结局：耦合度随工具数量线性上升，维护成本指数上升。JAZ 提出 Harness as a Language，本质是要把这层耦合切断。语言化的核心收益有三个：

第一，声明与执行分离。工具用声明式的方式注册，长什么样、要什么参数、返回什么结构，全部描述清楚；执行引擎统一处理调用、校验、重试。加工具不再动核心代码。

第二，组合有语法。多个工具、多个步骤之间怎么串，用一套明确的组合规则表达，而不是靠散落各处的回调。这让“先查再算再写”这种流程可以被静态分析、被复用、被测试。

第三，错误有语义。语言化之后，错误不再是随便抛的异常，而是有类型、有层级、有恢复策略的一等公民。哪些错该重试、哪些该回退、哪些该直接终止，全部可以在 Harness 层统一决策。

这三条加起来，才是“语言”这个词真正的分量。它不是让你写起来更花哨，而是让系统在规模上去之后还能被理解、被测试、被演进。

2. JAZ 的核心设计逻辑：把 Harness 拆成语法、语义和运行时

理解了动机，接下来拆 JAZ 的设计。我把它归纳成三层：语法层管“能写什么”，语义层管“写了是什么意思”，运行时层管“跑起来怎么执行”。这三层对应到工程上，就是接口定义、类型系统和执行引擎。

2.1 语法层：工具与流程的声明式描述

语法层要解决的是“怎么把一个工具讲清楚”。一个工具至少要说清四件事：名字、输入、输出、副作用。JAZ 的思路是用结构化描述替代散落的函数签名，让工具本身成为可被引擎读取的数据，而不是只能被程序员读懂的代码。

我实际落地时用的描述结构大概是这样，你可以直接参考：

{ "name": "search_docs", "description": "在内部文档库中检索相关片段", "input_schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "top_k": { "type": "integer", "default": 5, "minimum": 1, "maximum": 20 } }, "required": ["query"] }, "output_schema": { "type": "object", "properties": { "items": { "type": "array" } } }, "side_effect": "read_only", "timeout_ms": 8000 }

这份描述里，input_schema和output_schema是关键。它们让引擎可以在调用前校验参数、在返回后校验结构，把大量“模型瞎编参数”的问题挡在执行之前。side_effect字段则决定了这个工具能不能在沙盒里跑、要不要额外授权。timeout_ms是硬性保护，防止某个工具卡死拖垮整个流程。

提示：side_effect这个字段看着不起眼，但它是后面做权限收口和审计的基础。读操作和写操作必须分开标记，否则你没法在 Harness 层做“写操作二次确认”这种策略。

2.2 语义层：类型、作用域与组合规则

语法层只是让工具“可读”，语义层才让它“可推理”。JAZ 在语义层做了两件我认为最关键的事：类型约束和组合规则。

类型约束的意思是，工具之间的数据流是有类型的。A 工具输出的结构，能不能直接喂给 B 工具，引擎要能判断。这听起来像类型系统，实际落地时不需要做到那么严格，但至少要能识别“结构不匹配”这种低级错误。我见过太多线上事故，根源就是上游返回的字段名变了，下游还在按老字段取，结果静默失败。

组合规则是语义层的重头戏。多个工具怎么串，JAZ 用一套显式的组合表达，而不是靠 Agent 自由发挥。举个实际例子，一个“先检索、再总结、再落库”的流程，用组合规则写出来大概是这样：

pipeline summarize_and_store: step retrieve = search_docs(query=user_input, top_k=8) step summary = llm_summarize(items=retrieve.items) step persist = write_record(content=summary.text, tag="auto") on_error retrieve -> fallback: return_empty on_error persist -> retry(3, backoff=exponential)

这段伪代码里，on_error是语义层的核心。它把“出错怎么办”从散落的 try-catch 提升成了流程定义的一部分。retrieve失败就返回空，persist失败就重试三次指数退避。这种策略一旦写进流程，就可以被复用、被审计、被统一修改。

2.3 运行时层：执行引擎、状态机与沙盒

运行时层是真正干活的地方。它要维护一个状态机，记录当前流程走到哪一步、每步的输入输出是什么、有没有失败、失败了几次。这个状态机是 Harness 的心脏，也是“代码回退”能力的基础。

热词里有人问“deepseek harness 代码回退”怎么搞，答案就在这一层。回退不是简单地重新跑一遍，而是基于状态机里记录的快照，把系统恢复到某个已知良好的状态。这就要求运行时在每一步都保存足够的上下文：输入、输出、时间戳、工具版本。没有这些，回退就是空谈。

沙盒是运行时层的另一块。Agent 执行工具时，尤其是执行代码类工具，必须在隔离环境里跑。JAZ 的设计里，沙盒的边界由工具的side_effect和权限策略共同决定。只读工具可以在轻量沙盒里跑，写操作必须走更严格的授权链路。

注意：沙盒不是万能的。我见过有人以为套了沙盒就安全了，结果工具本身有网络访问权限，照样能捅娄子。沙盒要和权限策略配合用，单靠一层防护是不够的。

3. 核心机制落地：从工具注册到并发扛压的完整链路

设计讲完了，接下来是最实在的部分：怎么把这套东西搭起来。我按实际搭建顺序走一遍，每一步都给到能直接用的配置和参数。

3.1 工具注册与参数校验的实操细节

工具注册是第一步。我的做法是建一个注册中心，所有工具通过声明文件注册，引擎启动时统一加载。这样加工具只需要加一个声明文件，不用动核心代码。

参数校验我强烈建议用 JSON Schema，因为模型返回的参数本质就是 JSON，用同一套 schema 校验最自然。校验分两道：第一道在调用前，检查必填项、类型、范围；第二道在返回后，检查输出结构是否符合预期。两道校验都失败时，不要直接把原始错误抛给模型，而是转成模型能理解的提示，让它重新生成参数。

这里有个实操心得：top_k这类数值参数一定要设上下限。我吃过亏，模型有时候会返回top_k: 1000，直接把检索服务打爆。加上maximum: 20之后，这类问题基本绝迹。同理，字符串参数要设maxLength，防止模型生成超长输入。

3.2 上下文拼装与 token 预算的分配策略

上下文拼装是 Harness 里最容易被低估的环节。Agent 每一轮都要把历史、工具描述、当前任务拼成 prompt 喂给 LLM，拼得好不好直接决定效果和成本。

我的分配策略是这样的：先给系统提示和工具描述留固定预算，再给当前任务留一块，剩下的才分给历史。历史部分用滑动窗口加摘要，最近几轮保留原文，更早的压缩成摘要。具体比例我一般按 2:3:5 来分——系统提示占两成，当前任务占三成，历史占五成。这个比例不是死的，任务越复杂，当前任务那块要越大。

token 预算一定要显式管理。我见过太多项目，上下文无限增长，跑到十几轮之后要么超限报错，要么成本失控。显式预算的意思是，每次拼装前先算一下还剩多少额度，超了就主动裁剪，而不是等模型报错。

3.3 并发场景下 Agent 怎么扛住压力

热词里“ai agent 怎么扛并发”是个高频问题，我单独拎出来讲。Agent 扛并发和普通服务扛并发不一样，因为每个请求背后可能挂着多次 LLM 调用和工具调用，链路长、耗时不可控。

我的做法分三层。第一层是请求级限流，用令牌桶控制入口 QPS，防止瞬间打满。第二层是 LLM 调用级并发控制，因为 LLM 接口通常有并发上限，超了会被拒。第三层是工具调用级的隔离，不同工具用不同的线程池或连接池，防止一个慢工具拖垮所有请求。

具体参数上，LLM 调用并发我一般设成接口上限的 80%，留 20% 余量应对突发。工具调用超时统一设 8 到 10 秒，超过就降级。降级策略要提前定义好，比如检索失败就返回空结果，而不是让整个流程挂掉。

提示：并发问题里最隐蔽的是“重试风暴”。一个工具超时，如果所有请求同时重试，会把下游瞬间打爆。重试一定要加抖动，比如backoff = base * 2^n + random(0, base)，避免重试同步。

3.4 错误分类与恢复策略的对照表

错误处理是 Harness 语言化之后收益最明显的地方。我把常见错误整理成一张表，直接对应恢复策略：

这张表的价值在于，它把“出错怎么办”从个人经验变成了团队共识。新人接手时不用猜，照着表来就行。

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

这一节是我踩坑踩出来的，都是文档里不会写的。

4.1 模型返回的 JSON 解析失败怎么办

这是最高频的问题。模型有时候会在 JSON 外面包一层解释文字，或者用单引号，或者少个括号。我的处理是三步：先尝试直接解析，失败就用正则提取第一个完整 JSON 块，再失败就回传错误让模型重新生成。

但更根本的解法是在 prompt 里明确要求“只输出 JSON，不要任何解释”，并且用 schema 约束输出。如果模型支持结构化输出，一定要开。开了之后解析失败率能从百分之几降到千分之几。

4.2 工具调用陷入死循环怎么破

Agent 有时候会反复调同一个工具，因为模型觉得上次结果不满意。我的做法是给每个工具设调用次数上限，比如同一个工具在同一任务里最多调 5 次，超了就强制进入下一步或终止。

另一个技巧是在上下文里显式记录“你已经调过这个工具了，结果是……”，让模型看到历史，减少重复调用。这个改动很小，但效果很明显。

4.3 上下文超限的排查思路

上下文超限通常不是突然发生的，而是慢慢涨上来的。我的排查顺序是：先看历史是不是没裁剪，再看工具返回是不是太大，最后看是不是有工具把整个文档塞进了上下文。

工具返回一定要做截断。检索类工具返回的片段，单条不要超过 500 字，总数不要超过 3000 字。超出的部分要么丢弃，要么摘要。这一步不做，上下文迟早爆。

4.4 沙盒里工具跑不通的常见原因

沙盒环境干净，很多依赖没有。常见原因有三个：缺依赖库、缺环境变量、网络不通。排查时先在沙盒里跑一个最小复现脚本，确认基础环境没问题，再逐步加依赖。

环境变量要显式注入，不要指望沙盒继承宿主环境。网络访问要按需开放，只读工具通常不需要网络，写工具才需要，而且要走白名单。

5. 我对 Harness 工程化的一点个人体会

搭了几套 Agent 系统之后，我最大的体会是：Harness 的质量不取决于你用了多花哨的框架，而取决于你有没有把它当成一门需要设计的语言来对待。语法清晰、语义明确、运行时可靠，这三条做到了，用什么框架都能跑得稳；做不到，换再多框架也是换个地方踩坑。

JAZ 把 Harness 语言化这个提法，真正的价值是给了我们一个判断标准：当你加一个新工具、改一个新流程时，需不需要动核心代码？如果需要，说明你的 Harness 还没语言化到位。这个标准很朴素，但特别管用。

最后分享一个小技巧：把每次工具调用的输入输出都落盘，按任务 ID 归档。出问题时，这份日志比任何调试工具都好使。我靠这个习惯定位过好几次“模型看起来在胡说”的问题，最后发现都是上游工具返回了脏数据。日志不骗人，模型会。