P.S. 无意间发现了一个巨牛的人工智能教程，非常通俗易懂，对AI感兴趣的朋友强烈推荐去看看，传送门https://blog.csdn.net/HHX_01

前言

很多人刚玩大模型的时候，都有过一种错觉。

模型都已经强到能写论文、捋架构了，我调个API，不就能搓出一个能干活的Agent？

现实是，你兴冲冲把API接进项目，让它改个bug。它叭叭输出几百字方法论，从定位思路讲到最佳实践，头头是道。

然后呢？没有然后了。

它知道怎么做，但它什么都做不了。读不了你的文件，跑不了你的命令，三句话之前聊的啥，下一轮就忘干净了。

同样的模型，为啥人家的产品就能自动改代码、跑测试，到你这就只剩一张嘴？

差的不是模型，是模型外面那层东西。

1. 先搞懂：裸模型到底是个啥

抛开所有花里胡哨的包装，一次大模型API调用，本质就是个纯函数。
输入一段文本，输出一段文本，就这么简单。

这个函数有三个天生的毛病，恰恰是它没法独立干活的根因。

1.1 毛病一：金鱼记忆，全靠你帮它记

它是无状态的。这次调用和上次调用，在它那半毛钱关系都没有。

所谓的多轮对话，全是你每次把历史记录全塞进去，它才“看起来”记得。你一偷懒不塞，它当场失忆，问你“咱们是谁？咱们在哪？”

合着它的记忆，全靠你当外置硬盘。

1.2 毛病二：纸上谈兵，只会说不会干

它的输出永远只有文本。它可以在回复里写“请读取src/index.ts文件”，但它没有手去真的点开那个文件。

就像驾校教练坐副驾，给你讲得明明白白，方向盘在哪、刹车怎么踩，他比谁都清楚。但你让他上手开，他根本不会。

主打一个嘴强王者，动手能力为零。

1.3 毛病三：被动上班，多一步都不走

你问一句，它答一句，答完这次调用就结束了。

它绝不会主动说“我先读个文件，看完再决定下一步”。一来它做不到读文件，二来调用一结束它就“下班”了，根本不会自己推进流程。

典型的打工人心态，不催不动，绝不主动加班。

就这三个毛病，注定了裸模型只能聊天唠嗑。真要让它干“修复bug”这种需要反复读文件、改代码、跑验证的活，它啥也干不成。

2. 把嘴替变成实干家，总共分几步

办法很朴素，缺啥补啥呗。

没记忆？我们在外面存着历史，每次调用都喂给它。

动不了手？我们给它配一套工具，它说要读文件，我们就真的去读，读完结果再塞回去。

不会自我推进？我们写个循环包住它，调一次模型，看它要干嘛，干完把结果给它，再调一次，直到它说搞定了。

2.1 核心灵魂：Agent Loop

这个循环，就是整个Agent的灵魂，业内叫Agent Loop。

它把“一次性的文本补全”，变成了“思考-行动-观察-再思考”的闭环。模型负责动脑子，循环负责让脑子的想法能落地、能继续往下走。

而把裸模型包起来、让它能持续完成任务的这一整套工程系统，就叫Harness。

2.2 打个比方：发动机和整车

我最喜欢用汽车来类比，好懂。

大模型就是发动机，提供动力和智能。Harness就是底盘、变速箱、方向盘、刹车这一整套东西。

发动机马力再大，你把它放地上，它也就只能原地轰鸣，哪也去不了。没有底盘传动，动力变不成前进的轮子；没有方向盘刹车，跑起来也只能撞墙。

模型决定了Agent的上限有多高，Harness决定了它能不能真的开上路。不然再强的模型，也就是个大型有声摆件。

2.3 十行代码看明白差别

说概念太虚，看两行代码就懂了。

这是大多数人第一次写的裸调用：

// 裸调用：一问一答，到此为止constres=awaitllm.chat({messages:[{role:"user",content:"修复 src/app.ts 里的类型错误"}],});console.log(res.content);// 输出："你可以打开 app.ts，找到第 X 行……" 然后就没了

纯纯一锤子买卖，告诉你怎么做，剩下的全靠你自己。

套了Harness之后，骨架是这样的：

// Harness：循环 + 工具，直到任务完成consthistory=[{role:"user",content:"修复 src/app.ts 里的类型错误"}];while(true){constres=awaitllm.chat({messages:history,tools:TOOLS});history.push(res.message);if(!res.toolCalls)break;// 模型说完成了，就退出循环for(constcallofres.toolCalls){constresult=awaitrunTool(call);// 真的去读文件、改代码、跑命令history.push({role:"tool",content:result});}}

差别就在那个while循环和runTool上。

多了这十来行，模型就从“嘴上谈兵”，变成了真刀真枪上手改。当然真实的Harness远不止十行，生产级的光核心循环加治理逻辑就有上千行，但内核就是这么个道理。

3. 为啥要做本地优先的设计

聊完基础概念，说点实际的。我自己做这个项目，出发点就是个很现实的痛点。

很多人公司有合规要求，源码不能离开本地。但市面上的AI工具，没一个能同时满足“用最强模型”和“代码不出机器”。

3.1 市面上的三类工具，都不太行

纯云端的网页助手，代码全要上传，安全部门看见直接给你红码，比防疫还严。

IDE插件类的，看起来是在本地用，实际上推理还是走云端服务器，代码该传还是传，换汤不换药。

纯本地跑小模型，代码倒是不出门了，但是模型太弱，复杂点的活根本干不了，属于是安全了但没用。

3.2 走第四条路

所以我们选了第四条路：云端模型负责推理，Agent进程跑在你本地。

你用自己的API Key直连模型服务商，但是读文件、改代码、跑命令这些动作，全在你自己电脑上发生。源码从始至终不经过任何第三方服务器。

既要最强的推理能力，又要数据安全，两头都要占。这个“本地优先”的约束，也决定了后面很多设计取舍。

4. 一套完整的Harness，都有啥部件

真要做一套能打的Harness，不是写个while循环就完事了。拆解开，其实是六大模块各司其职。

你可以把它当成一个人，有心脏、有手脚、有眼睛、有记忆，还有扛造的身板和进阶的技能。

4.1 心脏：核心循环

就是刚才说的Agent Loop，整个系统的发动机，驱动“问-做-再问”的整个流程。每一轮调度各个模块，直到任务完成。

4.2 手脚：工具系统

让模型能真的读写文件、执行命令、对接外部工具。模型说要干嘛，这套系统就真的去执行，是落地的关键。

4.3 眼睛：上下文构建

决定模型每一轮能看到什么、看多少。不是把所有东西都塞进去就完事，塞多了模型糊涂，塞少了信息不够。怎么精准投喂，是个技术活。

4.4 记忆：跨会话留存

不只是存对话历史，还要能提炼成长期记忆。上次聊过的项目背景、你的习惯偏好，下次打开它还能记得，不会每次都像第一次见面。

4.5 韧性：故障里扛住

真实环境里乱七八糟的事多了。网络超时、模型抽风、工具报错，总不能一出问题就直接崩了。这套模块负责重试、降级、故障转移，保证系统能活下去。

4.6 进阶：玩点高阶的

子代理并发干活、自我反省纠错、自动画架构图之类的高级功能，都在这一层。属于基础打牢之后的能力升级。

这套设计最核心的原则就两个字：解耦。

每个模块只对上下游负责，互相不知道对方内部细节。比如核心循环调用模型，只认统一的接口，根本不知道背后是Claude还是DeepSeek，甚至是不是已经切到备用模型了。

好处就是加新功能、换组件的时候，改动只锁在单个模块里，不会牵一发而动全身。不然加个新模型就要改半个项目，改到你怀疑人生。

5. 三个常见误会，一次性说清

聊到这，肯定有人有不同想法，挑三个最常见的澄清一下。

5.1 不是写个好prompt就叫Harness

很多人觉得Agent不就是prompt写得好吗？真不是。

prompt只是上下文的一部分，属于眼睛那一块的活。但Harness还包括循环、工具执行、错误恢复这些模型之外的逻辑。你prompt写得再天花乱坠，模型也没法靠意念读取你本地的文件。

5.2 不是用个框架就完事了

也有人说，我用LangChain之类的框架不就有了？

框架是给你提供了零件和积木，但房子怎么盖、户型怎么设计、水电怎么走，还是得你自己来。框架是材料，Harness是你用材料盖出来的房子。别以为装个依赖就等于做了Agent，跟买了袋水泥就说自己盖了楼一样离谱。

5.3 模型越强，Harness越重要

还有一种说法，等以后模型足够强了，Harness就没用了。

恰恰相反。模型越强，你越想把更复杂、周期更长、风险更高的任务交给它。任务越复杂，对循环稳定性、上下文管理、错误恢复的要求就越高。

就像发动机马力越大，越需要靠谱的底盘和刹车。不然一脚油门下去，车直接飞出去了，要动力有啥用？

最后简单总结两句。

裸大模型就是个无状态的文本补全函数，没记忆、不动手、不推进，只能聊天干不了活。

Harness就是补上这些短板的工程系统，核心是Agent Loop，把模型的智能转化成实际的行动力。

一套完整的Harness有六大模块，核心设计原则是解耦，才能一边扛生产一边持续迭代。

概念聊到这就差不多了。下一篇咱们直接上手，用几十行代码从零搓一个最小可用的Harness，亲眼看看这个循环是怎么自己跑起来的。

P.S. 无意间发现了一个巨牛的人工智能教程，非常通俗易懂，对AI感兴趣的朋友强烈推荐去看看，[传送门https://blog.csdn.net/HHX_01](https://blog.csdn.net/HHX_01/article/details/1596130