最近 8 周深读 AgentScope 2.0 源码,提了 4 个 PR(#2166 提的、#2167 推的合并、#2217 合并、#2343 待 review)。真正花时间的不是 LLM 本身,是它周围的会话管理 / Memory 分层 / Tool 路由 / HITL 机制 —— 这些全是 Harness。

💎 观点 2:模型有 3 个不可回避的本质问题

"Harness 存在的全部理由,就是工程化补偿模型的 3 个局限。"

问题	本质	Harness 要做的
无状态性	LLM 不"记住"任何对话	维护 Session、拼 messages、组装上下文
窗口受限	32K / 128K / 200K 不是无限	压缩、摘要、Offload、按需检索
幻觉	LLM 不会"说不知道"	RAG 注入事实、Tool 验证、HITL 确认、BadCase 闭环

关键洞察:这 3 个问题都不是"Bug",是 LLM 的架构本质。Harness 不是"修 Bug",是"工程化补偿"。

我的连接:

测试场景里,幻觉最危险的不是"答错",是"自信地答错"。比如 LLM 说"BBOM-001 包含 X 模块"(其实没有),工程师基于这个写用例,整个测试白做。我们现在的 Harness 在 Tool 调用层加了强制 HITL + 结果回写 L2 + BadCase 干预 —— 这就是"用工程手段管住幻觉"。

💎 观点 3:Harness = 上下文 + 工具 + 运行环境

"Harness 的三件事:让 LLM 看到对的信息、能动手做、在受控空间里运行。"

职责范围三件事:

上下文:让 LLM 看到"对的信息"(解决无状态 + 窗口受限)
工具:让 LLM 能"动手做"(解决幻觉 + 无行动力)
运行环境:让 LLM 在"受控空间"里运行(解决安全 + 可靠性)

一句话定义:Harness = 让 LLM 在生产环境"可控 / 可用 / 可信"的所有工程化基础设施。

今天我会从 4 个层次拆开 Harness:

抽象层(WHY):四大核心工程支柱
工程层(HOW):五大核心子系统
治理层:Harness 也是代码,会腐化
战略层:未来 Harness 工程师的护城河

💎 观点 4:抽象层 —— 四大核心工程支柱(WHY)

"Harness 必须解决的 4 类问题。"

        ┌──────────────────────────────────┐
        │         Harness = 控制外围        │
        └────────────┬─────────────────────┘
                     │
     ┌───────────────┼───────────────┬───────────────┐
     ▼               ▼               ▼               ▼
┌─────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ ① 上下文 │    │ ② 架构约束 │    │ ③ 反馈回路 │    │ ④ 人类监督 │
│  工程   │    │  物理强制  │    │  熵管理   │    │  HITL   │
└─────────┘    └──────────┘    └──────────┘    └──────────┘

支柱 1:上下文工程(Context Engineering)

把"应该让 LLM 看到的信息"工程化组装。

核心手段:System Prompt 分层 / Per-Request Context 注入 / Memory L1-L4 / RAG / 压缩 / Offload / 检索增强。

关键挑战:不是"塞进去",是"塞对的、塞最少的、塞最新的"。

支柱 2:架构约束(物理手段强制)

不是"提醒 LLM 不要做 X",而是"系统不允许做 X"。

写 Tool 必须走 HITL 确认;Tool 调用前 sandbox 验证;权限校验在 Tool 层而非 Prompt 层。

关键洞察:架构约束的本质,是把"规则"从 Prompt 文字 → 架构代码。

支柱 3:反馈回路与熵管理

让 Harness 有"记忆",让用户有"反馈回路",让整个系统"越用越聪明"。

两个核心手段:

循环执行的沙箱:让 Agent 在受控环境里反复试
经验积累:每次执行的结果沉淀到知识库

熵的来源:Token 累积、状态污染、错误累积、上下文污染。

支柱 4:人类监督(HITL)

人从"软件开发"变成"审核员" —— 这是 AI 时代最大的角色转变。

写 TMSS / 提缺陷 / 删数据 → 必须 HITL;读文档 / 查知识库 → 不需要 HITL。

关键挑战:太多 HITL → 慢;太少 HITL → 危险。

💎 观点 5:工程层 —— 五大核心子系统(HOW)

"5 个子系统是 4 大支柱的'工程化实例'。这是 Harness 的'主视图'。"

子系统 1:指令子系统(地图 + 红线 + 教训)

让模型知道"要做什么 / 不要做什么 / 别人犯过什么错"。

组件	类比
地图	导航:项目背景、当前任务、目标
不要做什么	交通规则:红线、约束、反模式
犯过的错误	事故黑点:BadCase、踩坑记录、经验

关键三件套缺一不可。地图过期 / 红线缺失 / BadCase 不沉淀,任一都会让模型"翻车"。

子系统 2:工具子系统(不是越多越好,是匹配任务的工具)

核心观点:工具不是越多越好,是匹配任务的工具。

把所有 MCP Tool 都暴露给它 → 模型选错率高 + Token 浪费。正确做法是按 Skill / 按状态 / 按角色动态路由。

类比:工人的工具箱,不是越大越好,是对应工作的工具。

子系统 3:环境子系统(权限、沙箱、文件隔离等安全边界)

模型运行的安全边界。

组件	作用
权限	谁(用户 / 角色)能做什么(读 / 写 / 删)
沙箱	模型在哪运行(本地 / 测试 / 生产)
文件隔离	能访问哪些目录 / 资源 / 数据库

类比:工厂车间 + 安全门禁。

子系统 4:状态子系统(信息干净、精确、同步)

控制模型的上下文状态。

组件	含义
信息干净	无过期、无重复、无矛盾
信息精确	每个字段有明确含义和来源
信息同步	跨 session / 跨用户 / 跨组件一致

类比:数据库的 ACID —— 干净的、精确的、同步的。

子系统 5:反馈子系统(最重要的部分,AI 的传感器)

为什么最重要:

AI 的传感器 —— 没有反馈,AI 不知道自己错在哪
用测试验证 —— 跟写代码一样,需要单元 / 集成 / E2E 测试
ROI 最高 —— 投入产出比最高的子系统

"没有反馈子系统的 Harness,就是个聪明的复读机。"

5 大子系统的关系

           ┌─────────────────┐
           │ 反馈子系统(⑤)    │ ← 最重要,驱动整个系统进化
           │   AI 的传感器    │
           └────────▲────────┘
                    │ 驱动
     ┌──────────────┼──────────────┐
     │              │              │
┌────▼────┐   ┌────▼────┐   ┌────▼────┐
│指令(①)│   │工具(②)│   │状态(④)│
└────┬────┘   └────┬────┘   └────┬────┘
     │              │              │
     └──────────────┼──────────────┘
                    │ 被保护
           ┌────────▼────────┐
           │ 环境子系统(③)   │ ← 横切所有,提供安全边界
           └─────────────────┘

反馈子系统(⑤):引擎,驱动整个系统进化
指令 / 工具 / 状态(①②④):三个"内容型"子系统
环境子系统(③):横切所有,提供安全边界

我的连接:

在无线测试平台里,这5 个子系统都有对应:

指令:System Prompt 分三层(Agent / 项目 / Skill)
工具:20 Skill × 21 MCP Tool 的路由表
环境:Tool 层权限检查 + 容器化隔离
状态:Memory L1-L4 + State Machine S0-S6
反馈:BadCase 闭环 + 单元测试套件 + 5 个生产在跑

Harness 不是"概念",是"已经在我系统里跑的代码"。

💎 观点 6:引导(前馈) + 检查(反馈) = Harness 在软件开发中的全部

"Harness 在软件开发中,只有两件事:引导(前馈)和检查(反馈)。"

引导(Feed-forward):让模型"尽可能做对"

在 LLM 干活前,把"应该知道的一切"塞给它。

载体	作用
上下文加载	Memory / RAG / 项目公共信息
Agents.md	项目级 Agent 配置(类似 README 但给 Agent 看)
Skill / Tool 预选	按场景路由到对的工具
System Prompt 分层	Agent / 项目 / Skill 三层

"Agents.md 是给 Agent 看的 README。"

关键原则:引导越多 = 模型第一次做对率越高 = 反馈成本越低。

检查(Feed-back):让模型"做错了能拦住"

LLM 干完活后,强制走一遍"门禁",不通过就回滚 / 重试 / 报警。

载体	作用
强制 Hooks	Tool 调用前后必须经过的钩子
单元测试	Agent 写的代码也要跑测试
门禁检查	Code Lint / 类型检查 / 安全扫描
CI/CD	每次提交都跑全流程
人工 Review	关键变更必须人看一眼

"没 Hooks 的 Harness,就是个裸跑的 LLM。"

引导 + 检查的最佳实践

引导 + 检查同时重,但引导 70% + 检查 30% 是大多数场景的最佳比例。

5 大子系统	引导角色	检查角色
① 指令子系统	★★★(主战场)	★
② 工具子系统	★★	★★★(主战场:Hooks)
③ 环境子系统	★	★★★(主战场:权限拦截)
④ 状态子系统	★★	★★
⑤ 反馈子系统	—	★★★(主战场:测试 + CI)

💎 观点 7:长任务交接 —— 结构化进度文件

"对话历史是'日志',进度文件是'快照'。两者并存,各司其职。"

多轮 Agent 必然带来"长任务"问题 —— 跨多轮、跨多 session、可能跨天。

会话断了怎么办?靠结构化进度文件。

进度文件 vs 对话历史

维度	对话历史	进度文件
形式	滚动消息流	结构化 YAML/JSON
跨 session	难(散落各 session)	易(中央仓库)
LLM 友好	一般(噪声大)	优(直接读字段)
人类友好	一般	优(看 done/in_progress 就懂)

进度文件的标准结构(YAML 片段)

# progress.md
work_order: WO-2026-0810-001
title: BBOM-001 测试用例生成
state: S1
owner: zhangsan

done:
  - { id: 1, skill: test_strategy, output: artifacts/strategy.md }

in_progress:
  - { id: 3, skill: case_generation, progress: 60% }

todo:
  - { id: 4, skill: case_optimize }

decisions:
  - { decision: 用 test_design_generate, reason: 复用团队 Skill }

context_snapshot:
  bbom_modules: [BBOM-001, BBOM-002, BBOM-003]
  user_preferences: [用 Markdown 表格输出, 简洁]

next_action: 继续 case_generation,完成剩余 8 条用例

进度文件的 5 个关键属性

结构化(YAML / JSON)
可追溯(时间戳 + 操作人 + 输出链接)
上下文完整(下次直接读就能继续)
决策记录("为什么这么做",避免重复纠结)
Git 可版本化(变更可回滚)

"进度文件让长任务可交接,对话历史只能回放。"

💎 观点 8:Harness 治理 —— 防止腐化

"Harness 也是代码,会随时间腐化。"

Harness 腐化的 5 大来源

腐化类型	表现	后果
Prompt 漂移	System Prompt 越加越长,旧规则和新规则冲突	模型行为不稳定
Tool 废弃	老 Tool 没清理,新 Tool 又加进来	选错率高
BadCase 沉淀但不更新	错误知识塞满了,新错误没放进去	失去反馈价值
Memory 漂移	用户偏好被错误地长期记忆	误导模型
Skill 失效	上游 Skill 改了,但 Harness 没跟上	调用失败

"Prompt 漂移,是 Harness 腐化的头号杀手。"

Harness 治理的 5 大手段(对标代码治理)

手段	类比代码治理
版本管理	Prompt 版本 / Tool 版本 / Skill 版本
定期清理	坏 BadCase 移除 / 老 Tool 废弃
回归测试	每次 Harness 变更都跑测试套件
监控告警	关键指标(成功率 / 反馈数 / BadCase 数)
Code Review	Harness 变更也要 review

元规则:Harness 治理的 ROI,远高于 Harness 功能开发。

我的连接:

我们每周会有一次"Skill 失效清单 review",把调不通的 Skill / 拼写错参数的 Tool / 引用失效文档的 RAG 全清一遍。这就是 Harness 的"定期清理"。

💎 观点 9:Harness 的未来,外层被吸收,核心持久

"Harness 的不同部分,半衰期不同。"

核心论点

Harness 的不同部分,半衰期不同:
  - 外层(通用规范、防御)→ 短半衰期 → 被模型吸收
  - 内核(私有上下文、领域知识、反馈层)→ 长半衰期 → 持久存在

外层补丁:会被模型吸收的部分(1-2 年)

类别	吸收方式
通用编程规范(PEP 8 / 命名规范)	模型训练时学习
通用提示词防御("请一步步思考")	模型微调时学
通用工具使用规范(Tool 失败重试)	RLHF 学
通用安全约束(不要输出 PII)	对齐时固化

核心:持久存在的部分(5+ 年)

类别	为什么持久
项目特定上下文	模型不会知道你们公司的项目
私有领域知识	模型没你们的领域数据
反馈层系统(单元测试 + CI)	业务相关,模型训练不到
团队私有 Skill	团队方法论不可复制
HITL 流程	业务决策权在公司

战略启示

启示 1:Harness 工程师的护城河 = 私有资产 + 反馈飞轮。

启示 2:投入产出重分配:

现在:  写 Prompt / 调 LLM = 50%  ← 这部分未来会被吸收
       维护 Tool / Skill   = 30%
       维护反馈系统 + 测试 = 20%

未来:  维护反馈系统 + 测试 + 私有资产 = 80%  ← 护城河
       配置通用 Prompt / Tool        = 20%

启示 3:Harness 的"资产化":

资产类型	价值	半衰期
私有 Skill 库	高	5+ 年
BadCase 知识库	高	5+ 年
反馈系统	高	5+ 年
通用 Prompt 模板	低	1-2 年

职业演化路径

过去(2023-2024):Prompt 工程师 —— 写 Prompt / 调 LLM
现在(2025-2026):Harness 工程师 —— 写 Harness / 建子系统 / 治理腐化
未来(2027+):Agent 资产管理者 —— 维护私有资产 / 运营反馈飞轮

"从 Prompt Boy 到 Harness Engineer,再到 Agent 资产管理者。"

📌 总结:Harness 是 AI 时代的基础设施思维

一句话总结

"Harness 不是'调 LLM',而是'让模型在系统里活下来,并越用越强'。"

4 层次心法

本质:Agent = Harness + Model。Harness 是可改造的全部空间。
抽象:四大支柱 —— 上下文工程 / 架构约束 / 反馈回路 / 人类监督。
工程:五大子系统 —— 指令 / 工具 / 环境 / 状态 / 反馈。
战略:外层被吸收,内核持久 —— 护城河 = 私有资产 + 反馈飞轮。

给工程师的行动建议

如果你正在做 Agent 项目:

本周:对照"5 大子系统"自检,你的项目少了哪个?
本月:写一份 AGENTS.md,给项目"装上导航仪"
本季度:建一套"反馈闭环",BadCase 闭环 + 单元测试 + CI
半年内:把"通用 Prompt"沉淀下来,逐步变成"私有资产 + 反馈飞轮"

如果你正在选职业方向:

❌ 别再当 Prompt Boy(会被模型学走)
✅ 当 Harness Engineer(短期护城河)
✨ 成为 Agent 资产管理者(长期护城河)

💬 最后一句话

"Harness 工程师的真正价值,不是'让 LLM 干活',而是'让 LLM 干完活之后,系统变得更强'。"

这跟传统软件工程"代码资产化"完全一致 —— 你写的代码不是给自己用的,是给团队和未来用的。

Harness 的私有资产 + 反馈系统,就是 AI 时代的"代码资产"。

🛡️ 隐私 + 致良知说明

项	内容
写作动机	2026-09-16 上午重新学习 Harness 工程,把核心思考沉淀
隐私处理	所有工作单位 / 职级 / 团队规模等敏感信息已脱敏
个人经历	"我的连接"段引用的是公开实践(AgentScope 4 PR 等),非内部信息
致良知	本文所有洞察都来自公开学习材料 + 个人工程实践,无任何夸大

作者注:本文是 Harness 工程学习的完整复盘,所有观点归个人所有,仅供参考。如果你也在做 Agent 项目,欢迎交流。

贡献者

sunrong1