一个让我困惑了很久的反差

我第一次用 Claude Code 改代码的时候，是有点震撼的。

我说「把这个组件的状态管理从 useState 迁移到 useReducer」，它真的去读了文件、理解了现有结构、改了代码、还顺手把引用它的地方一起更新了。整个过程它自己读、自己写、自己验证，连续干了七八轮。

接下来我回到自己的项目里用同一家的模型、同一个 API Key，想复刻这个体验。结果呢，我调一次 API，它回我一大段「你可以这样做…，」的文字。我把它的回答贴回去，它又回一段。它知道该怎么做。但它什么都做不了——它读不了我的文件，跑不了我的命令，记不住三句话之前我们聊到哪了。

一样的模型，差别怎么这么大？从答案是来看，Claude Code 不只是「调了一下模型」。说起来，模型外面包了一层东西，正是这层东西。把一个「会聊天的模型」变成了「会干活的智能体」。这层东西，业界叫它 Harness。

你调的 LLM API，本质是个无状态的文本补全函数

抛开所有包装。一次 LLM API 调用本质上就是一个纯函数: 输出文本 = LLM. 你给它一段文本，它吐出最可能下一段文本。就这么简单，这个函数有三个“天生残疾”，恰恰是它没法独立干活的根因：

• 残疾一：没有记忆. 这个函数是无状态的。你这次调用和上次之间，它没有任何“记得”。简单讲多轮对话全是假象——其实是你每次都把之前所有对话重新塞进输入里它才“看起来”记得。一旦你不塞，它就是个失忆的人。
• 残疾二：动不了手. 它只能输出文本。可以在文本里说“我要读取 src/index.ts”，但没有手去真的读那个文件。能描述动作，却不能执行动作。
• 残疾三：不会自我推进. 你问一句。它答一句，接下来这次调用就结束了。不会主动说“我先读个文件，看完再决定接下来”——因为读文件动作它做不到。而一次调用结束后又“死”掉。

A真正编程任务长什么样？“帮我修复这个 bug”——需要：先看报错 → 读相关文件 → 定位问题 → 改代码 → 跑测试 → 看结果 → 再改。这是需要反复行动、观察、再决策的过程。按理说，而裸 LLM 只能做其中“决策”那一步，其余行动与观察全做不了。

从“补全一段话”到“完成一件事”

*使用者痛点*: 只得到建议，却无法落地执行；无法在本地环境中操作，缺乏持续反馈循环*

• No memory: 我们在外面存住历史,每次调用时喂给它；
• No hands: 我们给它一套工具集。它在文本里说“我要调用 read_file”,我们真的去读，再把结果喂回去； 按理说，
• No self‑drive: 用一个`while` 循环包住**LLM**: 调一次看想干嘛 → 执行 → 再调。一直直到说 “搞定”，

主要概念: Agent Loop

一句代码看清差别

// 裸调用：一问一答，到此为止
const res = await llm.chat({
messages:
});按理说，console.log;// → "你可以打开 app.ts，找到第 X 行…，"
// Harness：循环 + 工具，直到任务完成
const history =;while {
const res = await llm.chat;history.push;if break，// 模型说 “完成”
for {
const result = await runTool;// ⭐ 真正执行
history.push;}
}

说到案例项目。catbuddy 的 “代码不出本地” 的 Harness 实践

*使用者痛点*: 云端 AI 工具被安全禁用，但仍想使用 AI 辅助编程；源代码必须留在本地，不可上传云端*

• 原始需求： AI 推理强大，但源码完全离线处理；方法： 
• 设计取舍： 

从全景地图来看，Harness 的六大器官

设计原则 & 解耦思想

每个器官只负责自己的上下游接口，不知道内部细节。例如 AgentRunner: 接收统一 LLMProvider。无需关心具体是 Claude 或 DeepSeek，也不需要了解故障转移逻辑。添加新 provider，只需更新对应模块，无需改动 Runner 本身。这正是 Harness 能兼容多场景、多版本且易 的大理由之一。

常见误解 · 快速澄清

• *误解 一*：“Harness 就是写个好 Prompt。” 答：Prompt 是输入的一部分，而 Harness 包含循环、工具执行还有错误恢复等完整程序。老实说，如果仅靠 Prompt，即使提示再好。也无法让模型真正读写文件或继续进行任务。
• *误解 二*：“LangChain 或其他框架已经足够。” 答：框架提供的是材料与封装，但你的 Agent 在何种场景下如何管理上下文、降级策略及工具选择仍需自行决定。框架是砖块，而 Harness 是建筑师，让砖块搭建起完整房子。
• *误解 三*：“模型越强壮，Harness 就不关键。” 答：相反，更强大的模型代表着更高风险、更复杂任务。对稳定性与可靠性的要求更高。Harness 的关键性随之提高，并承担更多责任与挑战。

要点这方面。

1.  裸 LLM 是无状态文本补全函数，有三大缺陷—没记忆、动不了手、不自驱动，所以无法独立完成任务;
2.  Harness 用存历史补记忆。用工具补手脚，用循环补自驱动，实现 Agent Loop；其内核即为 Agent Loop.
3.  catbuddy 的 Harness 拥有六大器官—心脏/手脚/眼睛/记忆/韧性/进阶—并以接口解耦为主要设计理念.

 


\t\t\t\t\t\t\t
"
/>
">"
#>
">"
#>

'