AI编程系列之3：从聊天框到 Agent——Claude Code 的 Harness 与 LLM Loop 拆解

1. 聊天框和 Agent 到底差在哪一次真实的困惑刚接触 Claude Code 的时候我把它当成命令行版的 ChatGPT用了整整一周。问它怎么写正则、让它解释一段报错、让它帮我改个函数——用起来确实顺手但总觉得哪里不对这不就是把网页聊天搬到了终端里吗凭什么大家都在说它是 Agent直到有一次我丢给它一句帮我把项目里的 moment.js 全部换成 dayjs顺便把相关测试跑通然后去泡了杯咖啡。回来的时候它已经改完了 11 个文件、更新了 package.json、跑了一遍测试、发现两个用例挂了、自己读了报错、又改了一轮最后给我列了一份变更清单。那一刻我才意识到我面对的不是一个答题机器而是一个会自己拆任务、自己动手、自己验证的执行体。这个差异不是产品包装出来的背后是两套完全不同的工程机制在支撑。普通聊天框的工作流是你问一句、它答一句主动权永远在你手里Claude Code 的工作流是你给一个目标、它自己循环执行到完成主动权交给了它。支撑这个转变的核心就是本文要拆解的三件事LLM Loop大模型循环、Harness脚手架体系、Agentic Search智能体式检索。如果你正在用 Claude Code 但还停留在高级聊天框的用法或者想搞清楚 Agent 到底是怎么跑起来的这篇会给你一套可复制、可验证的认知框架。我会先讲清楚机制再给出一份能直接用的settings.json骨架最后带你做一次本地验证亲眼看到循环是怎么转起来的。2. 普通聊天 vs Agent四个维度的本质差异先把概念对齐。很多人把AI 聊天和AI 智能体混着说但它们在四个维度上有质的区别。维度普通 AI 聊天Agent如 Claude Code行为你问一句它答一句你说一个目标它自己规划并执行多步能力只能生成文字能读写文件、运行命令、搜索代码、调用工具主动性被动回答你不问它不动主动规划、主动发现问题、主动纠错记忆仅限当前对话可有长期记忆CLAUDE.md、Skills 等最关键的是能力和主动性两栏。普通聊天只能给你文字回复你得自己把代码复制进项目、自己跑命令、自己看报错Agent 能在你授权下直接操作文件系统、执行命令、安装依赖——它有手而聊天框只有嘴。主动性同样关键。聊天框是你问什么它答什么你不说它就沉默Agent 拿到目标后会自己拆成子任务、自己找要改的文件、自己写代码、跑测试、发现 bug、改 bug一直循环到任务完成。打个比方ChatGPT 像你问路人怎么去某个地方路人告诉你路线但路得你自己走Claude Code 像你叫了个代驾你只说目的地它自己把车开到。这个比喻的精髓在于主动权的转移——在聊天框里主动权永远在你手里在 Agent 里你交出的是目标它拿走的是过程。3. LLM LoopClaude Code 自主读代码、改代码、跑命令的引擎Claude Code 之所以是 Agent 而不是聊天框核心在于一套叫LLM Loop的机制。3.1 对话式 AI 的单步工作流在 ChatGPT / Claude.ai 这类对话式产品里工作流是单步的你问一句 → AI 答一句 → 结束。答案不满意你再问一次。AI 只是个高级回答机器主动权始终在你手里。3.2 Claude Code 的循环工作流Claude Code 的工作流是循环的你下达一个目标 → 它自己拆解步骤 → 调用工具 → 看结果 → 决定下一步 → 再调用工具 → ……一直循环到任务完成。这个不断思考-行动-观察-再思考的循环就是 LLM Loop。用伪代码表示大概是这样你给一个目标 ↓ 思考制定下一步计划 ↓ 行动调用工具 / 执行命令 ↓ 观察读取执行结果 ↓ 任务完成 ── 否 ──→ 回到思考 ↓ 是 交付结果3.3 LLM Loop 带来的三个能力跃迁第一处理模糊目标。你可以给它帮我做一个番茄钟这种高层目标它会自己拆成创建项目、装依赖、写组件、加样式、接计时器 API、写测试。第二自我纠错。执行过程中它会自己读错误信息——某条命令报错了它读报错、调整方案、再试。这和聊天框你把报错贴给它、它给你建议是完全不同的闭环。第三不一定每步都问你。它会自主决策不会每个动作都打断你。这是它高效的原因也是它偶尔跑偏的原因——所以开跑前你要给足上下文CLAUDE.md、Skills、计划。这里有个容易被忽略的点Claude Code 是程序 模型的组合底层模型其实可以替换。这也是为什么可以用统一的 Key/API 通道接入不同模型来驱动它。真正让它比聊天框强大的是这套 Loop 机制加上 Harness 工程。4. Agentic Search它怎么读懂整个代码库很多人对 Claude Code 有个误解以为它像其他 AI 工具一样需要先把项目代码上传到服务器建索引。事实是它不需要任何预先的代码库索引。官方把这种机制叫做 Agentic Search智能体式检索。4.1 Agentic Search 的工作方式它的工作方式和一个新人工程师冷启动项目完全一样你的需求 ↓ 浏览目录结构ls / find ↓ 读取关键文件cat / read ↓ 用 grep 搜索代码 ↓ 跟进引用 / 调用关系 ↓ 在本地理解代码 ↓ 执行任务它不会一次性把整个代码库塞进脑子——而是按需读取像经验丰富的工程师那样先看目录、找关键文件、读相关代码、跟引用关系、按需深入。4.2 与传统 RAG 检索的本质区别维度传统 RAG 检索Agentic Search工作方式预先嵌入整个代码库为向量查询时按相似度拼凑现场读文件、grep、追引用需要服务器索引需要且需持续维护不需要代码变动处理索引过期可能返回已删除或重命名的代码始终读取实时代码代码上传通常需要预先上传或建索引不需要预先上传/索引整个代码库适合场景老项目、不变代码库活跃开发中的项目、大型 monorepo这意味着它天生适合活跃代码库——不依赖可能过期的预建索引也不需要部署向量数据库。但要注意被读取进上下文的代码片段仍会发送给模型服务处理敏感代码时依然要遵守公司的安全规范。5. Harness 体系脚手架比模型更重要如果你问Claude Code 为什么这么强答案不只是背后的模型还有围绕模型搭建的脚手架——Harness。5.1 什么是 HarnessHarness 指模型之外的所有工程化能力上下文管理、工具调用、规则约束、子任务分发等等。一个粗略的公式是实际能力 模型能力 × Harness 质量模型能力是地板Harness 质量才是天花板。模型决定下限项目上下文、工具权限、规则文件和工作流决定上限。5.2 Harness 的 7 层扩展点官方把 Claude Code 的工程化能力抽象成 7 个扩展点建议按从底到顶的顺序理解——先打好上下文和规则基础再接入更复杂的外部工具层组件作用加载时机①CLAUDE.md项目上下文背景、约定、禁区每次会话自动加载②Hooks会话生命周期钩子启动/结束/文件写入等事件触发③Skills可复用的任务方法论如代码审查部署按需加载④Plugins打包一整套 Skills Hooks MCP 配置装上后始终生效⑤LSP给 AI 装上跳到定义/查找引用等 IDE 级导航始终生效⑥MCP 服务器打通与外部工具数据库、文档、票务系统始终生效⑦Subagents独立上下文窗口的实例只返回结论任务发出时创建前 3 层是纪律——项目上下文、规则钩子、专业知识后 4 层是武器——包分发、IDE 能力、外部工具、子代理。5.3 一个提醒顺序很重要初学者不要在基础没搭好时就急着上 MCP 或 Subagents。先把 CLAUDE.md、Hooks、Skills 这三层基本功做扎实。这和软件工程里先写单元测试再做微服务是同一个道理。6. 可复制的 settings.json 骨架与统一 Key 接入理解了机制接下来是能直接用的部分。Claude Code 的配置分两层项目级的CLAUDE.md上下文和用户级的settings.json行为与权限。下面这份骨架你可以直接抄。6.1 settings.json 骨架{ permissions: { allow: [ Read, Glob, Grep, Bash(npm run test:*), Bash(git status), Bash(git diff:*) ], deny: [ Bash(rm -rf:*), Bash(git push:*), Read(./.env), Read(./secrets/**) ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的统一Key }, hooks: { PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: npx prettier --write $CLAUDE_FILE_PATHS } ] } ] } }几个关键点解释一下permissions.allow是白名单只放你信任的操作。Bash(npm run test:*)这种写法表示允许所有以npm run test开头的命令冒号后面的*是通配。permissions.deny是黑名单优先级高于 allow。把rm -rf、git push、.env这类危险操作挡在外面是 Harness 里最实用的一层纪律。env里配置的是统一 Key/API 通道。把ANTHROPIC_BASE_URL指向https://taotoken.net/api再用ANTHROPIC_AUTH_TOKEN填上你的 Key就能让 Claude Code 通过统一通道接入模型不用在多个供应商之间来回切换配置。hooks.PostToolUse是文件写入后的自动动作。上面这个例子是每次写完文件自动跑 prettier 格式化——这就是 Harness 里用钩子管住行为的典型用法。6.2 项目级 CLAUDE.md 骨架settings.json管行为CLAUDE.md管上下文。放在项目根目录每次会话自动加载# 项目约定 ## 技术栈 - 前端React 18 TypeScript Vite - 状态管理Zustand - 测试Vitest Testing Library ## 代码规范 - 组件用函数式禁止 class 组件 - 所有异步操作必须有错误处理 - 提交前必须跑 npm run test 和 npm run lint ## 禁区 - 不要修改 src/legacy/ 下的文件 - 不要动 package.json 里的依赖版本 - 不要提交任何 .env 相关文件这份文件的价值在于它把你脑子里的项目常识变成了它每次都能读到的上下文。没有它Claude Code 每次都要重新摸索有了它第一轮就能站在正确的起点上。7. 本地验证亲眼看到 LLM Loop 转起来配置好了怎么确认循环真的在工作做一次最小验证。7.1 准备一个带 bug 的小项目mkdir loop-demo cd loop-demo npm init -y npm install --save-dev vitest创建src/calc.jsexport function add(a, b) { return a - b; // 故意写错 } export function multiply(a, b) { return a * b; }创建src/calc.test.jsimport { describe, it, expect } from vitest; import { add, multiply } from ./calc.js; describe(calc, () { it(add 应该做加法, () { expect(add(2, 3)).toBe(5); }); it(multiply 应该做乘法, () { expect(multiply(2, 3)).toBe(6); }); });7.2 下达一个目标而不是问题在项目目录里启动 Claude Code输入跑一下测试如果有失败的用例找出原因并修复修完再跑一遍确认全绿。注意这句话的措辞——它不是这个测试为什么失败而是一个目标。这正是触发 LLM Loop 的关键。7.3 观察循环的四个阶段你会看到它依次做这些事思考先跑测试看看情况 行动Bash(npm run test) 观察add 用例失败期望 5 实际 -1 思考看 calc.js 里 add 的实现 行动Read(src/calc.js) 观察return a - b应该是 a b 思考改这一行 行动Edit(src/calc.js) 观察文件已修改 思考再跑一遍确认 行动Bash(npm run test) 观察全部通过 交付修复完成add 函数由减法改为加法整个过程你只说了一句话它自己完成了跑测试 → 读代码 → 定位 → 修改 → 复验的完整闭环。这就是 LLM Loop 在真实场景里的样子。7.4 验证统一 Key 通道是否生效如果你想确认请求确实走了统一通道可以在settings.json里临时加一个环境变量打印或者直接看 Claude Code 启动时的连接信息。正常情况下配置了ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN后所有模型请求都会经过你指定的通道不需要额外设置。8. 本篇常见错排查实际配置和使用中下面这几个坑最容易踩。报错一Invalid API key或401 Unauthorized先检查settings.json里的ANTHROPIC_AUTH_TOKEN有没有多余空格或换行。JSON 里字符串不能带尾随空格。另外确认ANTHROPIC_BASE_URL写的是https://taotoken.net/api不要漏掉/api路径。报错二Permission denied或工具调用被拦截这是permissions.deny生效了。如果你确认某个操作是安全的把它从 deny 移到 allow。注意 deny 优先级高于 allow同一个操作不能既在 allow 又在 deny 里。报错三Hook 不执行检查hooks里的matcher是否匹配到了正确的工具名。Write|Edit是正则表示匹配 Write 或 Edit。如果写成了write小写就匹配不上。另外确认 hook 命令本身能在终端里独立跑通。报错四循环卡住不动通常是某个命令在等待输入。比如npm run test进了 watch 模式或者某个交互式命令在等确认。解决办法是在 CLAUDE.md 里明确写测试命令用npm run test -- --run不要进 watch 模式或者把这类命令加进 deny。报错五改了不该改的文件这是没有配好 CLAUDE.md 的禁区部分。把不该动的目录和文件明确写进 CLAUDE.md 的禁区同时在settings.json的 deny 里加上对应的路径规则双保险。9. 把 Claude Code 当需要管理的实习生而不是无所不能的神回到开头那个困惑为什么 Claude Code 不只是命令行版聊天框现在答案清楚了——普通聊天是问答机器它是远程工程师普通聊天看代码靠塞上下文它靠现场读取 引用追踪普通聊天靠模型能力它靠模型 × Harness 的乘积。理解了这些你在用它的时候就不会再犯以为它什么都懂的错误。你会主动写 CLAUDE.md 给它上下文主动用 Skills 沉淀经验主动用 Hooks 管住它的行为主动用 permissions 划清边界。把它当成一个能力很强但需要被管理的实习生而不是一个许愿池。如果你还没配好统一 Key 通道可以从这里开始先拿到 API Key再按第 6 节的settings.json骨架填进去然后跑一遍第 7 节的验证。看到循环转起来的那一刻你对 Agent 的理解会从概念变成体感。接入配置与 Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_harness_loop接入文档与参数说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_harness_loop想先验证模型对话效果https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_harness_loop长期编码与 Agent 场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_harness_loop