跳至主要內容

Harness 全家福:从抽象到落地 — AI Coding 工程的完整体系

Mr.Sun2026年9月20日...大约 27 分钟AI 实践HarnessAI CodingAgent上下文工程多 AgentHookAgentLoop工程治理

Harness 全家福:从抽象到落地 — AI Coding 工程的完整体系

这是 Harness 系列 3 篇整合的综述长文。
整合时间:2026-09-16(Harness 工程)/ 2026-09-17(AI Coding 工程)/ 2026-09-18(Agent Loop)。
整合日期:2026-09-20。
关键字:理论层 WHY 系统层 / 系统层 HOW / 算法层 WHAT / 治理层 OPERATE / 灵魂洞察 5 大主线。

📌 一句话核心

"AI 时代,工程师的核心能力 = 建 Harness。Harness 不是'调 LLM',是让 LLM 在 Coding 场景里'可控 / 可用 / 可信 / 可进化'的全套工程化基础设施。"

📌 为什么写这篇综述

3 天写了 3 篇:

  • 9-16 Harness 工程 —— 讲了 WHY,但没讲怎么落地
  • 9-17 AI Coding 工程 —— 讲了怎么落地,但没讲怎么跑
  • 9-18 Agent Loop 5 大模式 —— 讲了怎么跑,但没讲怎么运维

单独看都不够完整。

今天把这 3 篇整合成 1 篇综述,形成完整 Harness 体系——

理论层(WHY) → 系统层(HOW) → 算法层(WHAT) → 治理层(OPERATE)

一个完整的 AI 时代工程化思维链,4 层不可缺一。

💎 第 1 部分:理论层 — Harness 是什么(抽象 WHY)

1.1 模型的 3 个本质问题

LLM 有 3 个不可回避的本质问题。Harness 的全部存在意义,就是工程化补偿这 3 个问题。

问题 1:模型是无状态的(Stateless)

LLM 本身不"记住"任何对话。每次调用都是独立的 inference。

Session A 告诉 LLM "我叫张三",Session B 的 LLM 完全不知道。这跟数据库不一样——LLM 没有持久存储,也没有"会话句柄"。

Harness 要做的:维护 Session、把历史拼成 messages、在每次调用前把"应该让 LLM 看到的上下文"组装好送进去。

问题 2:上下文窗口受限(Window-bounded)

LLM 有最大输入长度(8K / 32K / 128K / 200K ...)。长对话塞不下,会溢出。

100 轮对话 Token 数 > 32K 时,要么压缩、要么丢、要么分多次调。这不是 LLM 的 bug,是 Transformer 的架构本质。

Harness 要做的:上下文管理——压缩、截断、摘要、Offload、按需检索。

问题 3:模型有幻觉(Hallucination)

LLM 不会"说不知道",会自信地编造。

在生产环境,LLM 的错误答案会被当成"事实"传播。比如"BBOM-001 包含 X 模块"(其实没有),工程师基于这个写用例,整个测试白做。

Harness 要做的:RAG 注入事实、Tool 调用验证、HITL 确认、BadCase 干预闭环。

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

1.2 Harness 一句话定义

Harness = 让 LLM 在生产环境"可控 / 可用 / 可信"的所有工程化基础设施

它的职责范围,是三件事:

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

1.3 抽象层:4 大核心工程支柱(WHY)

4 个支柱,是 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 → 危险。

4 大支柱之间的关系

支柱依赖关系类比(操作系统)
① 上下文工程基础内存管理
② 架构约束横切所有支柱权限管理 / 安全模块
③ 反馈回路依赖 ①②日志系统 + 文件系统
④ 人类监督依赖 ①②③用户态 / 管理员

1.4 工程层:5 大子系统(HOW)

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

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

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

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

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

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

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

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

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

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

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

模型运行的安全边界。

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

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

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

控制模型的上下文状态。

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

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

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

为什么最重要:

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

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

1.5 引导 + 检查(Harness 在软件开发中的全部)

二元结构:引导(前馈)+ 检查(反馈)

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

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

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

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

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

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

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

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

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

引导 + 检查 的最佳实践

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

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

💎 第 2 部分:系统层 — Harness 在 Coding 怎么落地(执行 HOW)

2.1 4 大核心组件(微观 — 单项目内)

AI Coding 工程的最小可行 Harness = 4 个文件 + 1 个目录:

my-project/
├── Agents.md          ← 指令系统
├── init.sh            ← 环境初始化
├── work_orders/       ← 状态机
├── progress.md        ← 进度日志
└── src/
组件对应 Harness 子系统一句话
Agents.md① 指令子系统告诉 AI "怎么工作"
init.sh③ 环境子系统强制环境一致性
状态机④ 状态子系统追踪每个功能"做到哪了"
progress.md④ 状态子系统跨会话的进度文件

Agents.md——指令系统

关键 3 个字:短、准、根。

  • 短:不能写成长篇小说——LLM 看完要 1 秒内,人看完要 30 秒内
  • 准:每个规则都要"可执行",不要模糊描述
  • 根:放在仓库根目录,所有 Coding Agent 第一时间读到

Agents.md 必须包含的 5 个部分:

部分内容为什么
核心规则不能违反的硬规则(全局)防止幻觉 / 防止越权
工作流程任务从开始到结束的标准步骤防止漏步 / 防止乱序
工作规则软规则(可违反但有代价)风格 / 命名 / 注释
任务完成标准"什么算做完"的可判定标准防止 LLM 假装做完
失败案例反向规则(不要做 X,因为 Y)从错误中学习

init.sh——环境初始化

关键词:复杂配置 + 强制一致性

问题没有 init.sh有 init.sh
开发者本地"我电脑上能跑"跑 init.sh 就一样
CI 服务器"CI 跑挂了,本地能跑"跟本地一致
新成员加入配环境配半天跑 init.sh 5 分钟
生产部署"生产挂了,排查环境"init.sh 是"环境基线"

init.sh 的 5 个最佳实践:

  1. 幂等:跑 10 遍和跑 1 遍效果一样
  2. 可观测:每一步都有 echo "✅ xxx done"
  3. 可回滚:失败了能 undo
  4. 可并行:能并行的步骤并发
  5. 可配置:超时时间 / 镜像源可配

状态机——功能清单

为什么是"状态机"而不是"清单":

维度简单 Checklist状态机
状态☐ / ☑P0 / P1 / WIP / Done / Failed / Blocked
依赖无显式显式定义"X 必须先于 Y"
转换无有明规则"X 完成后才能进 Y"
错误恢复难易(知道卡在哪一步)

状态机的 3 个关键属性:

  • 有限状态:5-10 个足够
  • 明确转换条件:每一步都要可判定
  • 可逆性:支持 rollback

progress.md——进度日志

核心定位:

  • 跨会话:会话 1 跑 30 分钟 → 会话 2 接手 → 读 progress.md 继续
  • 任务状态:每个任务"做到哪了"
  • 决策记录:为什么这么做

进度文件 vs 对话历史:

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

2.2 3 级成熟度等级(中观 — 个人/团队/组织)

  ┌────────────────────────────────────────────────────────┐
  │ 组织级:沙盒 + 成本监控(全公司视角)                      │
  ├────────────────────────────────────────────────────────┤
  │ 团队级:共享规则 + CI + 共识变脚本(团队视角)              │
  ├────────────────────────────────────────────────────────┤
  │ 个人级:四件套 + 反馈循环(个人视角)                       │
  └────────────────────────────────────────────────────────┘

三级对比

维度个人级团队级组织级
视角我能用我们能用全公司能用
共享方式本地仓库(根目录)平台 / 服务
规则来源我自己定团队共识组织标准
反馈闭环个人 BadCase团队 BadCase 库全公司 BadCase + 评测
CI无 / 简单必须有 CI全流程 CI + 监控
成本不计(自己的 token)不计(团队预算)必须计(部门成本)
沙盒本地环境容器化环境隔离沙盒(生产级别)

每个级别的"关键增量"

级别上一级 → 这一级,新增什么
个人级(0→1)从零到有——4 大组件 + 反馈循环
团队级(1→10)从独享到共享——规则入仓 + CI 卡门 + 共识变脚本
组织级(10→100)从用到治——沙盒隔离 + 成本监控 + 可观测

团队级的核心:共识变脚本

"共识变脚本" 是团队级 Harness 的核心。

含义:团队里"大家都这么做"的隐性共识,要显式写成脚本。

5 个具体例子:

共识脚本化
大家都用 Python 3.11init.sh 强制锁版本
大家都用 black 格式化CI 黑名单自动加
大家都用 conventional commitscommit-msg hook 校验
大家都跑测试再 commitpre-commit hook 强制
大家都用某个 LLM 模型CI 校验配置文件

关键洞察:共识是"软资产",脚本是"硬资产"。共识走的人会忘,脚本永远在。

"共识变脚本——团队级 Harness 的核心。"

演进路径

个人级 (Month 0-3)
   ↓ 跑通 + 反馈循环产生价值
团队级 (Month 3-12)
   ↓ CI 卡门生效 + 团队共识沉淀
组织级 (Month 12+)

关键:不能跳级。直接做"组织级"是空中楼阁。

2.3 多 Agent 系统架构(宏观 — 1 → N)

SubAgent 的定义

属性含义
调用关系被父 Agent 调用(不是独立启动)
生命周期受父 Agent 管控(父死,子死)
任务范围受限(只能做父 Agent 分配的子任务)
对外暴露不对外(对外只有父 Agent)

关键洞察:SubAgent 不是"独立的 Agent",是"父 Agent 的延伸"。

多 Agent 系统的两种模式

维度层级架构(Hierarchical)对等协作(Agent Team)
结构树形网状
控制点单一(Orchestrator)多个(每个 Agent)
鲁棒性⭐⭐(顶层挂 = 全挂)⭐⭐⭐⭐⭐(群体智慧)
可调试⭐⭐⭐⭐⭐(调用链清晰)⭐⭐(不可预测)
涌现性⭐⭐(中心化抑制涌现)⭐⭐⭐⭐⭐(群体激发涌现)
适用任务明确 / 流程化 / 工程探索 / 创意 / 复杂
真实案例Claude Code / Cursor算法大赛 4 Agent / AutoGen

关键洞察:同一个系统里,两种模式可以共存——顶层层级架构 + 局部对等协作。

反直觉洞察

  • 多 Agent ≠ 1 Agent × N——不是简单复制,会产生涌现
  • 父子 Agent 不是"上下级",是"调用关系"——没有"权威"
  • Agent Team 不一定更好——协调成本可能超过收益
  • SubAgent 的"任务受限"是优势不是缺陷——防止 LLM 跑偏

"父子 Agent 不是上下级,是调用关系。"

2.4 Agent Hook 系统(实现层 — 从建议到强制)

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

Hook 的定义

属性含义
形式用户定义的 shell 命令(或脚本)
触发在 Agent 生命周期特定点自动执行
本质从"建议指导"升级到"强制的执行"
本质确定性的控制
本质自动化的工作流

本质:从建议到强制

维度建议指导(Prompt)Hook 强制执行
形式"请运行测试"pre-commit hook 强制跑测试
阻挡LLM 可忽略系统拦截
可靠性⭐⭐⭐⭐⭐⭐⭐⭐
可绕过容易难

退出码语义(关键)

退出码含义LLM 行为系统行为
exit 0成功继续下一步静默
exit 2阻断必须修复(错误注入)中断当前操作
exit 1系统错误标记异常报警,但不阻断

关键洞察:exit 2 是 Hook 的"灵魂"——只有"阻断"才能让 LLM 真的"听进去"。

Hook 生命周期(3 阶段)

阶段 1:会话启动阶段(SessionStart)
  - 加载项目配置 / 注入初始 Prompt

阶段 2:Agentic Loop 执行过程
  - UserPromptSubmit / PreToolUse / PostToolUse / Stop

阶段 3:SubAgent 执行中
  - SubagentStart / SubagentStop

Hook 解析 5 步流程

事件触发 → 匹配器检查 → 处理器执行 → 并行执行 → 退出码检查

Hook 实战示例:Pre-commit(代码检查)

#!/bin/bash
# .git/hooks/pre-commit

set -e
echo "🔍 Running pre-commit checks..."

black --check src/ 2>&1
flake8 src/ 2>&1
pytest tests/ -q 2>&1 || {
    echo "❌ Tests failed. Fix before committing."
    exit 2  # 阻断 commit
}
exit 0

Hook 的反直觉洞察

  • Hook 不是"功能",是"约束"——限制 LLM 行为的工具
  • 成功静默 ≠ 无用——好的 Hook 是"看不见的"
  • Hook 可以替代 Prompt——把"软规则"从 Prompt 移到 Hook,更可靠
  • Hook 是 Harness 的"边界"——LLM 不能跨越的边界

💎 第 3 部分:算法层 — Agent 怎么跑(实现 WHAT)

3.1 Agent Loop 的 4 阶段循环

[感知] → [思考] → [行动] → [反馈]
   ↑                          │
   └──────────────────────────┘
        (反馈作为下一轮感知)
阶段输入输出实现
感知用户指令 / 环境状态当前上下文读取消息 / RAG 检索 / Tool 结果
思考感知结果决策(下一步 / 结束)LLM 推理
行动思考结果调用结果外部 API / Tool / 数据库
反馈行动结果新感知信息结果解析 / 异常处理 / 日志

"Agent Loop = 人类认知的工程化实现。"

3.2 5 大核心组件

#组件作用关键挑战失败会怎样
①状态管理器维护对话 / 任务 / 流程状态状态一致性 / 序列化状态错乱
②决策引擎(核心)决定下一步动作上下文完整 / 推理正确跑偏 / 卡死
③工具执行器调用外部 API / 数据库 / 文件参数正确 / 异常处理Tool 调用失败
④记忆模块短期 + 长期记忆短期压缩 / 长异步持久失忆 / 重复问
⑤终止校验器判断"该结束了"成功条件 / 最大轮次无限循环

3.3 5 大主流 AgentLoop

#模式复杂度轮次核心思想
1基础工具调用⭐1-3LLM 直接调函数
2ReAct⭐⭐中迭代规划调整(想一步做一步)
3Plan-and-Execute⭐⭐⭐长全局规划(先设计再写)
4反思迭代⭐⭐⭐长执行 → 反思 → 修正 闭环
5多智能体协作⭐⭐⭐⭐⭐长跨领域涌现(慎用)

关键原则:不选最复杂的,选最适合的(跟 9-17 "Harness 是迭代出来的"呼应)。

模式 1:基础工具调用

维度简述
轮次1-3 轮
复杂度⭐(最低)
本质LLM 直接调函数,简单查询 / 操作
适用简单查询 / 操作 / 大部分场景
典型应用ChatGPT Function Calling / 简单助手

模式 2:ReAct(迭代规划调整)

ReAct = Reasoning + Acting(思考 + 行动交替)

[思考] → [行动] → [观察] → [思考] → ...

核心机制:上下文拼接实现记忆延续——所有历史堆到 context 里。

优缺点:

优点缺点
动态性好——每步根据最新结果调整长任务目标容易漂移
通用性好——适用各种任务缺全局视野(只看眼前)
实现简单——上下文堆就行Token 消耗增加较快

类比:下棋——想一步走一步。

模式 3:Plan-and-Execute(全局规划)

先计划,再执行——默认人的思维模式。

[Plan] 规划整体任务
   ↓
[Execute] 逐步执行
   ↓
[Re-Plan] 必要时调整计划
   ↓
[Execute] 继续执行

核心思想:任务拆解 = 任务降维。

优缺点:

优点缺点
稳定性强——有全局计划,不会跑偏计划错了后面全错
适合长任务——任务明确时好分解初期规划成本高
目标清晰——用户能看清楚整个计划不灵活

类比:写代码——先设计再写。

模式 4:反思迭代(执行 → 反思 → 修正)

[执行] → [反思] → [修正] → [执行] → ...

三层反思(关键结构):

层次反思什么谁来做
结果校验层这次执行的结果对吗?自动(代码 / 测试)
过程复盘层这次的执行过程合理吗?LLM
策略优化层整体策略要调整吗?LLM + 人类(关键决策)

优缺点:

优点缺点
幻觉少(多层校验)Token 消耗量很大
鲁棒性强(自我纠错)响应慢(多轮反思)
质量稳定可能反思错误(LLM 也可能错)

适用场景:代码审查、法律文书、医疗诊断、金融决策。

类比:写论文——写完反复改。

模式 5:多智能体协作(慎用)

子模式结构协调方式适用场景
主从模式Orchestrator + SubAgentOrchestrator 调度任务明确、需要问责
对等协商平级 Agent投票 / 协商 / 互相 review探索性、需要涌现
维度评价
优点跨领域 + 高复杂度 / 涌现 / 鲁棒
缺点稳定性较低 / Token 消耗极高 / 速度很慢

适用场景:开发全流程、头脑风暴、跨领域极高复杂度任务。

"多智能体协作是 5 大循环中成本最高的——慎用。"

3.4 5 大循环对比

维度基础工具调用ReActPlan-and-Execute反思迭代多智能体协作
响应速度⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
稳定性⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
Token 消耗低中低极高极高
容错能力⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
可解释性⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
适用复杂度单步中高高极高

3.5 ReAct vs Plan-and-Execute 核心区分

维度ReActPlan-and-Execute
本质迭代规划调整全局规划
稳定⭐⭐⭐⭐⭐⭐
灵活⭐⭐⭐⭐⭐⭐
类比下棋写代码

最佳实践:ReAct + Plan 混合 = 防漂移的标准组合。

💎 第 4 部分:治理层 — Harness 怎么活下去(运维 OPERATE)

4.1 AgentLoop 核心原理

"AgentLoop 的本质 = 上下文驱动的状态延续。"

含义:

  • Agent 没有"自身状态",只有"context + tool"
  • 每一轮的状态 = 之前的 context + tool 调用历史
  • "延续"靠 context 拼接(ReAct)或显式状态存储(Plan/反思)

4.2 4 大子组件

子组件作用关键设计
状态机维护基础信息 / 进度 / 记忆状态转换规则 + 持久化
终止条件双重保险① 任务完成 ② 异常状态强制终止
工具调用跟外部交互参数校验 + 异常处理 + Hook
记忆分层短期 + 长期短期 = context,长期 = 持久化

4.3 双重终止保险(鲁棒性核心)

维度任务完成异常状态
触发条件LLM 判断"做完了"超时 / 错误 / 异常
动作优雅退出强制停止 + 错误返回
关键作用正常完成防止无限循环 / 资源耗尽

关键洞察:"双重保险"是 AgentLoop 鲁棒性的核心——没有它,Agent 跑飞了都不知道。

4.4 AgentLoop 4 大痛点 + 防御

痛点 1:无限循环

检测信号:同一个 tool 被调 N 次没进展 / context 不再变 / 思考结果重复

防御措施:

措施作用配置
最大迭代次数硬性终止max_iters = 10-20
超时时间时间维度硬性终止timeout = 60s
进度检测没进展就停"同一状态重复 N 次"
异常终止出错就停Tool 失败率 > 50%

"无限循环 = AgentLoop 的'心脏病';双重保险是'心脏起搏器'。"

痛点 2:目标漂移

检测信号:Agent 跑偏了 / 任务结果跟用户原始需求不一致

防御措施:

措施作用
Plan-and-Execute提前固化目标(ReAct + 规划)
定期 Re-Plan每 N 轮回顾"我现在还在主线吗?"
用户 Confirm关键节点用户确认
目标向量检查每步跟"原始目标"做相似度计算

"目标漂移 = AgentLoop 的'阿尔茨海默';规划是'指南针'。"

痛点 3:上下文溢出

检测信号:context token 数 > 模型上限的 80%

防御措施:

措施作用实现
关键信息压缩提取核心,丢掉细节LLM 做摘要
下沉长期记忆老的对话存到 PG / Mem0context 只放摘要
滑动窗口只保留最近 N 轮早期对话压缩 / offload
结构化状态不存对话,存结构化数据状态机 + 进度文件

"上下文溢出 = AgentLoop 的'记忆饱和';压缩 + 下沉是'大脑'。"

痛点 4:性能瓶颈

检测信号:响应时间 > 5s / Token 消耗 > 预期 / 并发能力弱

优化措施:

优化作用收益
Prompt 缓存同样 prompt 不重复算50%+ 加速
Tool 调用缓存同样 tool 不重复调30%+ 加速
并行执行不依赖的 tool 并发调2-5x 加速
结果 Offload大结果存外部context 减小
模型分层简单任务用小模型成本 80%+

"性能瓶颈 = AgentLoop 的'动脉硬化';缓存是'血管支架'。"

痛点的元规则

"AgentLoop 的所有痛点,本质都是'无限资源约束下做有限任务'。"
"防御不是'避免',是'提前知道怎么停'。"

4.5 成熟度等级演进路径

个人级 (Month 0-3) → 团队级 (Month 3-12) → 组织级 (Month 12+)

关键:不能跳级。直接做组织级是空中楼阁。

4.6 Harness 治理:防止腐化

5 大腐化来源:

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

5 大治理手段(类比代码治理):

手段类比代码治理
版本管理Git tag
定期清理删 dead code
回归测试单元测试
监控告警APM
Code ReviewPR review

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

💎 第 5 部分:灵魂洞察 — 5 大主线

这是 blog 的灵魂,适合作为开场/结尾的金句区。

洞察 1:Agent = Harness + Model

"Model 是推理引擎,Harness 是工程控制。Model 不可变,Harness 才是可工程化改造的全部空间。"

这是 AI 时代工程师的"原点公式"。所有 AI 项目的失败,99% 都可以追溯到 Harness 没做对。

洞察 2:不是"调 LLM",是"建 Harness"

"AI 时代,工程师的核心能力 = 建 Harness。Prompt 是'和模型说话',Harness 是'让模型在系统里活下来'。"

短期工程师写 Prompt,长期工程师建 Harness。Prompt 是消费品,Harness 是资产。

洞察 3:Harness 是迭代出来的,不是设计出来的

"一个 BadCase 抵 10 个设计假设。v0.1 比'完美设计'重要 100 倍。没有'完美的 Harness',只有'一直在迭代的 Harness'。"

这跟传统软件工程完全相反——传统追求"一次设计完美",Harness 追求"边跑边改"。

为什么 Harness 不能"设计":

  1. LLM 不可预测——你设计得再完美,LLM 行为也跟设计不一样
  2. 真实场景比想象的复杂——没跑过就不知道坑在哪
  3. 用户需求会变——Harness 是为用户服务的,用户变 Harness 就得变
  4. 反馈比设计重要——一个 BadCase 抵 10 个设计假设

洞察 4:外层被吸收,内核持久

"Harness 的不同部分半衰期不同。通用规范 1-2 年被模型吸收;私有上下文 + 领域知识 + 反馈系统 5+ 年持久。未来 Harness 工程师的护城河 = 私有资产 + 反馈飞轮。"

部分半衰期命运
通用编程规范1-2 年被模型吸收
通用提示词防御1-2 年被模型吸收
项目特定上下文5+ 年持久存在
私有领域知识5+ 年持久存在
反馈层系统(测试 + CI)5+ 年持久存在

启示:未来 Harness 工程师 80% 精力 = 维护私有资产 + 反馈系统(护城河)。

洞察 5:人从"软件开发"变成"审核员"

"AI 时代最大的角色转变:人从写代码的变成审代码的。这是 AI 给工程师的礼物,也是挑战。"

工程师的核心技能从"能写"变成"能审"。会看"懂能写"重要 100 倍——你能审,意味着你能定义"什么算对"。

5 大洞察的相互关系

洞察 1 (本质) → 洞察 2 (行动) → 洞察 3 (方法)
                 ↓
洞察 5 (角色) → 洞察 4 (护城河)

📌 总结:完整 Harness 体系 4 层结构

一张表说清楚

层次视角解决关键产出
理论层WHY模型 3 个局限4 支柱 + 5 子系统
系统层HOWHarness 怎么落地4 组件 + 3 等级 + 多 Agent + Hook
算法层WHATAgent 怎么跑4 阶段 + 5 组件 + 5 模式
治理层OPERATEHarness 怎么活双重保险 + 4 痛点 + 5 治理
灵魂层WHY AGAIN工程师的认知升级5 大洞察

跟昨天 3 篇 blog 的关系

维度9-16 Harness 工程9-17 AI Coding 工程9-18 Agent Loop综述(本文)
定位抽象层(WHY)系统层(HOW)算法层(WHAT)全景
视角4 支柱 + 5 子系统4 组件 + 3 等级 + 多 Agent + Hook4 阶段 + 5 组件 + 5 模式完整 Harness 体系
字数~3500 中文字~5100 中文字~5500 中文字~10000 中文字
读者工程师思考层工程师执行层工程师实现层任何做 AI 项目的工程师

关系:综述是 3 篇短文的"目录",3 篇短文是综述的"详情"。

给工程师的行动建议

如果你正在做 AI Coding 项目:

时间行动
本周写一份 AGENTS.md(哪怕 20 行)
本月写 init.sh,跑通环境一致性
本季度建状态机 + progress.md,任务可追踪
半年内团队共用 Agents.md + 共识变脚本
一年内上多 Agent 架构 + Agent Loop 5 模式选型
持续加 Hook + 治理 + 防漂移

如果你正在选职业方向:

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

💬 最后一句话

"AI Coding 的真正护城河,不是 LLM 用得多熟,是 Harness 建得多深。"

"4 组件是骨架,3 等级是节奏,多 Agent 是规模,Hook 是牙齿,5 大 Loop 是神经,治理是血液。"

"6 个加起来 = 一个能在 Coding 场景活下去的 AI 团队。"

Harness 不是"调 LLM",也不是"写 Prompt",它是 AI 时代的基础设施思维。

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

Harness 的私有资产 + 反馈系统 + Hook 强制 = AI 时代的"代码资产 + 治理框架"。

🛡️ 致良知 + 参考

项内容
写作动机整合 9-16 / 9-17 / 9-18 三天的 Harness 学习,形成完整体系
致良知所有洞察都来自公开学习材料 + 个人工程实践,无任何夸大
隐私所有工作单位 / 职级 / 团队规模 等敏感信息已脱敏
个人经历"我的连接"段引用的是公开实践(AgentScope 4 PR / 8 周 commit),非内部信息

参考与延伸

  • Anthropic:Building Effective Agents(2024)
  • LangChain:LangGraph 多 Agent 框架
  • 阿里:AgentScope 2.0(笔者贡献过 4 个 PR)
  • Claude Code Hook 文档
  • DeepMind:Sparks of AGI 论文

关联 blog

作者注:本文是 Harness 体系 3 篇 blog 的综述长文,前后写了 4 天。如果你是 AI Coding 项目负责人,这篇应该读 3 遍;如果你是 AI 时代的工程师,这篇应该抄一份贴墙上。

本文首发于 sunrong.site,Mr.Sun,2026-09-20。

贡献者

sunrong1
MIT Licensed
Copyright © 2026 Mr.Sun