AI 工程师都在糊"胶水代码"——2026 这篇论文,把"Agent 周边那一坨"变成了一份"可审阅的文档"

  • 关联论文:2603.25723

一句话故事

arXiv 2603.25723（Natural-Language Agent Harnesses, NLAH）是 Linyue Pan 等 2026 年 3 月发表的工作 —— 它把 AI Agent 周围那一坨"胶水代码"（怎么组织上下文、怎么路由工具、怎么校验、怎么交接状态）从耦合度极高的 Python 文件里拆出来,写成"结构化自然语言文档",再用一份统一的运行时（Intelligent Harness Runtime, IHR）解释执行。结果:任务效果与手写 controller 持平,但 harness 策略从"几千行代码"变成"几百行可读文档",可消融、可审计、可对比 —— 把 Agent Harness 从"工程师的隐性技能"升级为"可被科学实验的研究对象"。

如果你 2025–2026 年真的在搭过 LLM Agent,大概率踩过这个坑 🤦:

  • 打开 agent.py,harness 散落在 30 多个文件里
  • context 怎么组织、tool 怎么暴露、retry 几次、状态怎么持久化 —— 全靠工程师手感
  • 两个团队做同一个 task,模型一样,结果不同?—— 没人能告诉你"harness 哪个模块贡献了差异"
  • 想做 ablation（关掉某个模块看效果）?—— 改 30 个文件,跑半天,paper 还差一个表
  • 监管 / 客户问"你这个 Agent 跑了什么策略"?—— 打开源码,reviewer 一脸懵

这不是个别团队的工程债,是整个 Agent 圈 2024–2026 年的隐性结构性问题:harness 是 Agent 的"方向盘与刹车",但它一直嵌在车体里 —— 没人能拿出来单独审、单独比、单独消融。

arXiv 2603.25723（NLAH + IHR） 干了件"看似朴素但范式级"的事:

把 harness 显式化为"结构化自然语言文档（NLAH）",再用一份共享运行时（IHR）解释执行 —— 任务效果不打折,策略却"短到可以读"且"可独立消融"。

被引 26 次（paper_card 口径,2026-07-05 快照）+ 影响力被引 2 次 —— 距离首个 LLM Agent Harness 综述仅有 2 个月,NLAH 已经成为 harness 表示形式方向的事实基线工作,所有想"把 Agent 工程化"的人都该读。

0 · TL;DR（30 秒版）

  • 真问题:Agent 的实际表现由 harness（模型周围的外层执行系统）决定,但 harness 现在埋在耦合度极高的 controller 代码里 —— 不可检视、不可对比、不可迁移、不可消融。
  • 核心答案:NLAH 把 harness 表示为结构化自然语言文档,IHR 是一份统一运行时,把文档"翻译"成具体 agent 调用、handoff、validation gate、artifact 契约。
  • 关键洞察:runtime 是固定的（一份共享代码）,策略是可变的（每个任务一份 NLAH 文档） —— 把"控制流"和"策略"解耦。
  • 2026 年局限:没有可运行的开源 IHR 实现 = 当前必须自研 runtime;benchmark 覆盖未明确披露（coding / terminal-use / computer-use 三类,具体名/SOTA 数字 abstract 未给）;自然语言固有的歧义性是 IHR 解析器的工程坑。

1 · 为什么这件事和大众有关

你手机里的 AI 助手、电商客服、AI 搜索、Copilot —— 它们背后都有一个 Agent。Agent 的"聪明度"其实由两个独立部分决定:

  • 🧠 模型（引擎）—— GPT-4o、Claude、Qwen、Llama
  • 🛠️ harness（方向盘 + 刹车 + 仪表盘）—— context 怎么组织、tool 怎么调用、错了几次重试、状态怎么存

2025–2026 年的工业真相是:模型本身的天花板远没到,决定 Agent 实际表现的,80% 是 harness。

但 —— harness 现在是"工程师的隐性技能":

  • 📂 不可检视:你打开一个 agent 仓库,harness 散落在几十个 .py 里,没人一眼说清"这次跑到底跑了什么策略"
  • ⚖️ 不可对比:两个团队做同 task,harness 不同,结果不同,没人告诉你"哪个模块贡献了多少差异"
  • 🔁 不可迁移:一个 harness 验证过的策略,换个模型 / 换个场景就要重写
  • 🔬 不可消融:ablation 怎么做?把 harness 模块一个个关掉?成本极高

arXiv 2603.25723 干的不是"再发一个新 Agent" —— 它重新定义了 Agent Harness 的表示形式:用结构化自然语言写 harness 策略,让 reviewer 能审、让 ablation 能做、让跨任务复用能跑。

2 · NLAH + IHR 到底干了什么

2.1 NLAH:不是 prompt,不是代码,是"可读可执行"的策略文档

NLAH 是一个结构化的、可编辑的、人类可读的自然语言文档。它描述"一次任务跑起来,harness 该怎么组织"。

伪代码示意:

Harness: code_agent
Goal: Solve {task} using repository tools.

Modules:
  - context_builder:
      role: Read repo files relevant to {task} using ripgrep
      fallback: ls + cat full tree (depth <= 3)
  - tool_router:
      interface: [shell, edit_file, run_tests]
      policy: Prefer edit_file over shell for in-repo changes
  - validator:
      must_pass: [run_tests, ruff_check]
      on_fail: Send diff to model for self-repair (max 2 retries)
  - handoff:
      next_state: tests_pass → mark_done
                    tests_fail → loop(validator)

Artifact contracts:
  - patch.diff: unified diff, must apply cleanly
  - test.log: full pytest output

Validation gates:
  - Pre-commit: lint_pass
  - Post-commit: tests_pass

要点:

  • 每个模块都是独立段落,可以单独打开 / 关闭 / 修改
  • 用自然语言,但保留结构化标签（role / interface / policy / must_pass）—— 机器可解析
  • 静态可读,运行时由 IHR 解释执行

2.2 IHR:把 NLAH 文档"翻译"成可执行动作

IHR 是 NLAH 的解释器 + 执行器。它接收 NLAH 文档,逐模块实例化为:

  • 🤖 agent calls（具体调用哪个 agent / 模型）
  • 🔀 handoffs（状态转移）
  • 💾 state updates（写入 / 读取持久化状态）
  • 🚧 validation gates（gate 判定 + 失败回滚）
  • 📜 artifact contracts（产物契约的校验）

设计哲学一句话:runtime 是固定的,策略是可变的 —— 传统 "hard-coded controller" 里控制流与策略耦合的部分,NLAH + IHR 直接解耦开了。

2.3 关键一招:显式模块化

NLAH 强制把 harness 拆成 5 类可命名模块:

模块 职责 例子
context_builder 上下文怎么组织 ripgrep 找相关文件,失败就 ls+cat 整树
tool_router 工具接口怎么暴露 [shell, edit_file, run_tests],偏好 edit_file
validator 输出怎么校验 必跑 [run_tests, ruff_check],失败回弹
handoff 任务怎么交接 tests_pass → mark_done;tests_fail → 重试
artifact_contracts 产物契约 patch.diff 必须干净应用,test.log 全量输出

每个模块都是:

  • 静态可分析 —— 可以直接读出策略意图
  • 运行时可独立关停 —— ablation 时关掉某个模块,看任务表现变化
  • 跨任务可复用 —— 一个验证过的 validator 模块可以从 task A 搬到 task B

这一设计把 harness 从"耦合代码"升级为"可被科学实验的对象"。

3 · 关键实验与数据

论文在三类典型 Agent benchmark 上做了评估（abstract 明确陈述,具体数字需查 PDF 实验表）:

维度 IHR + NLAH 代码实现 harness 纯 prompt harness
任务达成率 comparable baseline baseline
静态 harness 策略长度 明显更短 长 —
模块可分析性 可独立消融 难 难
benchmark 覆盖 coding / terminal-use / computer-use 同 同

abstract 的核心论断:

「Across coding, terminal-use, and computer-use benchmarks, IHR-executed NLAHs achieve comparable task outcomes to code and prompted realizations, while exposing much shorter static harness policies.」

「Module ablations further show that explicit harness modules are analyzable.」

注意:核心是"持平 + 显著更可分析",不是"NLAH 比手写 controller 跑分更高" —— 论文的"赢法"是范式级,不是榜单级。

4 · 对工程落地的启发（不读 PDF 也用得上）

  1. 别再 hard-code harness —— 把所有 harness 策略显式写成 NLAH 文档,让 reviewer 能审、让 ablation 能做
  2. runtime 与策略解耦 —— 一份 IHR 跑所有 NLAH,策略变更只改文档不改 runtime
  3. harness 应该是可对比的研究对象 —— A 团队和 B 团队谁 harness 更好?把 NLAH 公开出来,benchmark 才能跑
  4. 把 ablation 当作基本工程纪律 —— 任何 harness 模块上线前都做关停实验,看任务表现下降多少
  5. 自然语言 ≠ 模糊 —— 结构化标签让 NLAH 在"人可读"与"机器可解析"之间取得平衡
  6. 审计 / 合规有抓手 —— 监管或客户问"你这个 agent 跑了什么策略",NLAH 文档就是现成答案

⚠️ 三个边界坑（落地前必看）

  1. 没有可运行的开源 IHR —— arXiv 原文 + GitHub 均未检索到 IHR/NLAH 实现仓库,当前必须自研 runtime,不能直接拿来用
  2. benchmark 对应未披露 —— abstract 只说 "coding / terminal-use / computer-use",SWE-Bench / TerminalBench / OSWorld 这些具体 benchmark 与具体达成率数字 abstract 未给,选型时需补 PDF 实验表
  3. runtime 开销未量化 —— "comparable"结论是在什么硬件配置 / 什么模型规模下成立的?自研 IHR 在生产环境是否带来不可接受的延迟增量,需实际 profiling

🎯 你能立即做的事

  • agent 平台架构师:把现有 controller 重构为"一份 NLAH 模板 + IHR 适配",策略改文档,代码不动
  • agent 框架作者:评估是否要把 NLAH 作为更高层的抽象（替代 / 补充 LangChain / AutoGen / CrewAI）
  • agent 安全 / 合规团队:用 NLAH 写"当前所有 agent 的 harness 策略文档",让审计有文本依据
  • agent benchmark 作者:用 NLAH 写"标准 harness 策略",让不同模型在同一 harness 下对比
  • 做 agent ablation 研究的研究生:NLAH 直接降低 ablation 实验的工程门槛,paper 缺表时这就是你的切入点
  • CTO / VP Engineering:当团队纠结"为什么 A agent 比 B agent 跑得好"时,让两边都把 harness 写成 NLAH,直接对比策略差异

📌 一句话总结:NLAH 把 Agent Harness 从"嵌在车体里的胶水代码"升级为"可拿出来单独审阅、对比、消融的工程图" —— 任务效果不打折,但 harness 第一次具备"作为研究对象"的资格;这是 2026 年 Agent 走向"可工程化、可审计、可对比"的关键一步。

🔔 评论区聊聊:你搭过的 Agent 里,harness 哪一部分最难复盘?context_builder、tool_router、validator、handoff 哪个模块最值得"显式化"?

AI #Agent #LLM #harness #NLAH #可观测性 #ablation #工程化 #arXiv #论文解读

三个标题变体

  1. 类比版:Agent 界的"把方向盘从车体里拆出来"——arXiv 2603.25723 用一份可读文档重写 harness
  2. 数字钩子版:被引 26 次 + 影响力被引 2 次——arXiv 2603.25723 是 Agent Harness 走向"可科学实验"的事实基线
  3. 反直觉版:task 效果不打折,harness 策略却从几千行变几百行——arXiv 2603.25723 把"代码即策略"打成"文档即策略"

📱 小红书风格卡片文案（直接可用）

做 AI Agent 的姐妹听我说 🫶

你打开一个 Agent 仓库 —— harness 散落在 30 多个 .py 文件里,context 怎么组织、tool 怎么暴露、retry 几次,全靠工程师手感 🤦

两个团队做同一个 task,模型一样,结果不同 —— 没人能告诉你"harness 哪个模块贡献了差异"。想做 ablation（关掉某个模块看效果）?改 30 个文件,跑半天,paper 还差一个表 ✋

arXiv 2603.25723（NLAH） 干了件看似朴素但范式级的事 🪄:

❌ 错法:harness 嵌在 controller 代码里,不可检视、不可对比、不可迁移、不可消融 ✅ 真法:把 harness 显式化为"结构化自然语言文档（NLAH）",再用一份统一运行时（IHR）解释执行

结果: - 任务效果不打折 - 静态策略从"几千行代码"变成"几百行可读文档" - 5 类模块（context / tool / validator / handoff / artifact）可独立消融 - harness 第一次成为"可被科学实验的研究对象"

3 个落地抓手: 1️⃣ 别再 hard-code harness —— 显式写成 NLAH 文档,reviewer 能审、ablation 能做 2️⃣ runtime 与策略解耦 —— 一份 IHR 跑所有 NLAH,策略改文档不改代码 3️⃣ 审计 / 合规有现成答案 —— 监管问"agent 跑了什么策略",文档就是答案

⚠️ 诚实交代: - ⚠️ 没有可运行的开源 IHR = 当前必须自研 runtime - ⚠️ benchmark 对应未明确披露（coding / terminal / computer 三类,具体名/SOTA 数字 abstract 未给） - ⚠️ runtime 开销未量化,需实际 profiling

📌 一句话:把方向盘从车体里拆出来单独审、单独比、单独消融 —— 这就是 NLAH + IHR 干的活。

AI #Agent #LLM #harness #NLAH #工程化 #可观测性 #arXiv #论文解读 #AI产品 #技术分享 #AI工程师