# 小白入门级 Harness 工程指南 > AI Agent 不靠谱?多半不是模型变笨了,而是 Harness 没做好。一文搞懂 Harness 在 Claude Code 这类工具背后到底干了哪三件事。 - 原文链接: https://laojin.blog/blog/20260511_harness_engineering_intro - 作者: 老金 - 发布日期: 2026-05-11 - 标签: AI Agent, Harness, Claude Code, 工程实践, 入门 --- ![小白入门级 Harness 工程指南](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260511/00_cover.png) 如果你用过 Claude Code、Cursor 或任何 AI Agent,一定遇到过这些瞬间: * 让它改 **A 处**的代码,它顺手把 **B 处**也改坏了。 * 多步任务执行到一半,它突然 **"忘了"** 前面说过的关键前提。 * 同一个问题,今天和昨天的回答 **完全不同**。 * 它说 "我调用了 API",但你不知道它到底 **传了什么参数**。 这些不是模型变笨了,而是模型本身就是这样的 —— 原始大模型的输出是随机的、无状态的、没有安全边界的。它再聪明,也只是一个 **"会说话的概率引擎"**。 要让它变成你能托付生产任务的工具,中间必须有一层 **"翻译官 + 守门人"**。 这一层就叫 **Harness(驾驭工程)**。 --- ## 一张图理解 Harness ![Harness 在你与模型之间](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260511/01_architecture.png) 模型不直接和你对话,也不直接动你的电脑。所有的输入输出,都要经过 Harness 这一层加工。 **Claude Code** 本身就是一个典型的 Harness —— 它包裹着 Claude 模型,决定模型能看到什么、能做什么、出错了怎么办。 --- ## Harness 做的三件事 ![Harness 的三根支柱](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260511/02_three_pillars.png) ### 1. 决定 AI "看到"什么 —— 上下文管理 模型的 "记忆窗口" 是有限的,塞得越满,反而越容易 "迷失在中间"(重要的信息被淹没)。 Harness 像一个资深副导演,负责筛选、压缩、排序: * 哪些历史对话还有用?哪些可以丢? * 当前任务最相关的代码文件是哪几个? * 工具返回的几千行日志,能不能只保留关键的几十行? > **实例:** 在 Claude Code 中,当长对话进行到一定程度,它会自动"压缩历史" —— 这就是 Harness 在腾出空间,把位置留给真正重要的推理线索。 ### 2. 决定 AI "能做什么" —— 动作拦截 当模型说 "我要写这个文件" 或 "我要执行这条命令" 时,Harness 不会立刻照做。它会先拦下来检查: * 这个动作有权限吗? * 会不会动到危险目录? * 要不要先问一下用户? > **实例:** Claude 想运行一个新命令时弹出的 **"是否允许"** 提示 —— 这不是模型在问你,是 Harness 在问你。模型只是产生了 "意图",是否变成 "行动",由工程层决定。 ### 3. 决定 "出错了怎么办" —— 失败处理 API 超时、命令报错、返回结果格式不对 —— 这些是 Agent 运行的常态,不是异常。 ![失败重试的反馈循环](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260511/03_retry_loop.png) Harness 提供必要的兜底: * **命令失败**:把报错信息打包回传给模型,让它自己想办法修。 * **反复失败**:触发熔断,停下来报告,而不是越走越偏。 * **全程审计**:每一步谁做了什么、结果如何,都留下可追溯的记录。 > **实例:** Bash 命令超时或报错后,Claude Code 常常会自动换一种方式重试 —— 这套 **"重试 + 反馈"** 循环就是 Harness 实现的。 --- ## 一句提醒:Harness 不是免费的 工程层不是银弹。它会增加系统复杂度、推高 Token 成本、引入额外延迟。 * 做得太薄,系统不可用; * 做得太厚,系统不智能。 但对刚入门的你来说,先记住一件事就够了: **你和 AI Agent 打交道时感受到的 "靠谱" 或 "不靠谱",很大程度不是模型的问题,而是 Harness 设计的问题。** 你是否认同?或者有不同看法,欢迎评论区留下你的看法。