你给 AI 一个任务“帮我分析一下这个项目的风险。”十秒后它打了一行字我先查一下项目背景。然后你看到它调了搜索找到了 README 和架构文档读完才开始回答。输出之前还补了一句信息来源是这些。整个过程半分钟不到。你感觉这个 AI 很靠谱——它没有直接给答案而是先确认自己有没有足够的信息。你再给它一个任务“把这段代码从 Vue 2 升级到 Vue 3。”这次更复杂。你看到它先读了一遍当前代码列了一份改动清单然后逐个文件修改。改完一个跑一遍测试测试过了才改下一个。中间有一个文件改完后测试没过它停下来分析了错误信息调整了方案重改了一遍才过。最后还列了一份变更记录告诉你哪些地方改了、为什么改、还有哪些风险点需要你确认。整个过程中你没有插手一次。你可能觉得这个 AI “太聪明了”。但仔细想想它做的不就是把一个复杂任务拆成小步骤按顺序执行遇到问题做调整搞不定的告诉你——这不就是一个人做事的流程吗AI 能做复杂任务不是因为模型突破了什么极限而是因为有人给它设计了一套做事的方法。这个方法有一个专门的名字ReAct 循环Reasoning Acting推理 行动。这篇文章就讲一件事这套做事的方法到底是怎么运作的以及你理解了它之后能获得什么启发。一、它没在想是在跑循环AI 收到帮我分析项目风险之后不是靠灵光一闪出答案的。它内部先走了一圈看看自己知道什么、还缺什么信息决定先干一件事比如查个文件然后看结果再决定下一步。一圈不够跑两圈两圈不够跑三圈。这个过程用术语说就是 ReAct 循环——推理Reasoning和行动Acting交替进行。每一轮循环包含四个步骤感知AI 看当前上下文里有什么——你的指令、之前查到的资料、刚刚跑出来的结果。它只能看到放在它桌面上的东西。推理结合当前信息判断该做什么——是继续收集信息还是可以做决定了还是需要问你。这一步不是玄学是模型根据上下文做的概率预测。行动执行一个具体操作——查文件、写代码、跑命令、或者直接输出一段文字。每一步行动都有明确的结果。观察看行动的结果——代码有没有报错、命令有没有跑通、查到的资料够不够。观察的结果进入下一轮推理形成闭环。这个循环不断重复直到满足两个条件之一任务完成了或者遇到搞不定的情况需要问你。从外面看你只看到 AI “想了想然后开始干活”。从里面看是在跑一个又一个循环每次循环都以前一轮的结果为起点。二、复杂任务不是一次搞定的是一步步拆开的单轮循环只能做一件简单的事。真正的复杂任务——比如把代码从 Vue 2 升到 Vue 3——需要很多轮循环才能完成。关键在第一步任务拆解。AI 接到升级 Vue这类复杂任务时不会直接动手改代码。它会先生成一个计划。这个计划通常是一个步骤清单先评估当前代码结构然后逐个迁移组件最后做兼容性检查。有了计划之后AI 才按步骤执行。每一步可能又包含多轮 ReAct 循环——改一个文件可能需要读代码→理解逻辑→修改→跑测试→看结果→如果没过就分析错误→再改→再跑。这样一层一层拆下去一个大任务就变成了一棵由小任务组成的树。每一片叶子都是一轮可以执行的 ReAct 循环。拆解质量直接决定了执行质量。一个好的拆解会让每一步都清晰可执行一个粗糙的拆解会导致 AI 在中间迷失方向不知道该做什么或者做了一堆无关紧要的事。这里有一个重要的启发不是所有任务都需要复杂拆解。简单任务应该走简单路径。AI 的一个关键能力是判断当前任务的复杂度选择匹配的拆解深度。给一个简单问题做过度拆解反而浪费时间。这个判断能力需要你在系统设计时提供——通过设定规则告诉它在什么情况下应该详细规划什么情况下可以直接做。三、它需要工具才能干活说完循环和拆解再来看看行动这一步里到底发生了什么。一个只会生成文字的 AI做不了复杂任务。它需要工具才能干实事——查文件、写代码、跑命令、读数据库。每一次行动就是调一个工具。AI 决定调什么工具、传什么参数系统拿到结果后交给 AI 观察然后进入下一轮推理。这里有一个很微妙但很重要的设计AI 用什么工具、怎么用不是随心所欲的。首先工具清单是提前注册好的。AI 只知道你给它列出来的那些工具。你给它注册了查文件它就能查文件。你没给它注册写数据库它就写不了——哪怕它的训练数据里知道数据库怎么用也是白搭。其次每个工具的参数是固定的。AI 不能自己发明参数——它只能在你定义的接口范围内调用。比如查文件这个工具参数是文件路径 行号范围AI 不能传帮我查一下那个重要的文件——参数不合法工具不执行。这听起来像约束实际上是解放。因为参数固定AI 不需要猜测该怎么用工具因为清单透明系统可以精确审核 AI 每一步操作是否合规。对使用 AI 的人来说这意味着你可以放心给它工具——不是因为它天生可靠而是因为你可以精确控制它能干什么、不能干什么。给读文件的权限不给写文件的权限它就只读不改。切到只看不碰的模式它就真的只看不碰。四、出错不可怕可怕的是不会停循环再完整、拆解再精细、工具再齐全AI 还是会犯错。文件查不到、代码编译不过、测试不通过、参数传递错误——这些都是 Agent 执行过程中的常态。关键不是 AI 会不会出错而是出错了之后怎么办。好的执行系统在错误发生时做这三件事第一有限重试。出错了先试一次。可能是网络抖动导致超时可能是状态还没就绪。但重试必须有上限——连续失败几次就停下来。停下来不是认输是为了不浪费更多时间和 Token 在一个注定走不通的路上。第二调整方案。一条路走不通换一条路走。比如文件找不到可能是路径错了可以换个方式定位。方案调整是 ReAct 循环的精华——你不是在走一条死记硬背的路线而是在执行中持续校正方向。第三问人。如果试了两条路都走不通或者进入了一个完全没见过的状态——停下来问你。一个好的 Agent 敢于承认我搞不定而不是瞎编一个答案混过去。这三件事做得好不好是区分靠谱 Agent 和玩具 Agent 的分界线。这里有一个值得记住的启发如果你在让 AI 做一件高风险的决策——改生产代码、操作数据库、发正式消息——开始之前告诉它拿不准就问我。这句话写在规则里AI 会在每一步不确定的时候停下来问你而不是自作主张。五、如果你自己搭 Agent先想清楚这几件事前面讲的都是 Agent 执行系统的基本机制。但如果你真的要去搭一个有几个设计决策必须在写第一行代码之前想清楚。循环不能无限跑ReAct 循环每跑一轮就消耗一轮的 Token 和时间。没有上限的话一个简单的任务可能跑到你回来发现它还在跑。你需要定两个参数最大循环次数。一个代码审查 10-20 轮够了一个多文件重构可能需要 50 轮以上。根据任务复杂度设一个上限到了就停——不是失败是告诉你我尽力了还需要更多指令。终止条件。Agent 怎么判断自己做完了三个常见模式任务目标明确达成比如测试全部通过、没有更多有用的操作可以做了比如所有文件都改完了、或者用户说了停。三种条件都满足才停防止做到一半自己收工。工具设计的单一职责原则工具是 Agent 执行任务的手脚工具设计直接决定了 AI 能不能用对它们。最重要的原则是一个工具只做一件事。读文件和写文件分开而不是一个文件操作工具带两个参数。前者让 AI 清晰知道该调哪个后者让 AI 在调用时可能选错模式。参数的边界也要清楚。路径就用字符串不要用帮我找一下那个文件这种自然语言参数——AI 不会猜你要的是哪个文件但它会试着传各种东西然后期待你帮它兜底。返回值尽量结构化。JSON 比纯文本好纯文本比二进制好。结构化返回值让 AI 能直接读到关键信息不需要再花一轮推理去解析。工具出错时错误信息要告诉 AI 为什么失败、能不能重试——这样它才能决定下一步是重试还是换方案。Token 预算是硬约束每轮 ReAct 循环都在消耗上下文。查文件占 Token返回结果占 TokenAI 的推理过程也占 Token。跑着跑着桌面就满了。这意味着两件事第一拆解不能太细。每一步都拆成最小单位看起来精确但每多一轮循环就多消耗一轮的 Token。第二你得有一个上下文管理策略——不能在每轮循环中把所有的历史都原样保留。这就是第 7 篇讲的三层记忆体系要解决的问题工作记忆只放当前循环需要的东西短期记忆保留会话内的上下文长期记忆跨越会话。你不需要从零实现这些——成熟的 Agent 框架都有内置的上下文管理。但你需要理解它的存在否则当你的 Agent 跑了 30 轮之后开始失忆你会以为是模型的问题。错误处理的三级策略Agent 执行过程中错误是常态。设计阶段就要明确三级策略第一级重试。临时性错误——网络超时、服务未就绪、速率限制——重试 2-3 次。为什么是 3 次一次可能是运气不好两次也可能是巧合三次大概率真有别的问题。第二级换方案。永久性错误——文件不存在、参数不合法、权限不足——不重试直接换方案。比如文件路径不对换个方式找API 调不通换个接口。换方案是 ReAct 循环的精华说明 AI 不是在机械执行而是在动态调整。第三级问人。如果所有方案都试过了还是不行或者进入了一个完全没见过的状态——停下来问用户。问人的时候给上下文、给选项、让用户选。不要让用户猜你的状态。六、OpenCode 是怎么落地这些设计的前面讲的这些设计决策OpenCode 全都有对应的实现。拿它当参考系你可以看到这些概念在真实产品里怎么落地。指令层 AGENTS.md。你在 AGENTS.md 里写的每一行规则都是 AI 执行循环的一部分。写先确认资料够不够不够先查AI 就会在拆解任务时先做这一步。改一行文本行为就变了——不需要修改代码不需要重新部署。这就是指令即架构的落地。工具系统 注册制。OpenCode 的工具在 opencode.json 里注册。每个工具有明确的名称、参数、返回值。加一个工具AI 就多一种执行能力删一个工具AI 就不能再调它。工具的注册清单就是 AI 的能力边界这是你控制 Agent 最直接的入口。权限分层 Plan/Build 模式。切到 Plan 模式AI 只能看不能碰——能做方案、分析代码但不能改任何一个文件。切回 Build 模式AI 才能执行写操作。同一个模型、同一套工具换一个权限配置行为完全不一样。这就是前面讲的事件与决策分离——AI 决定做什么系统决定能不能做。上下文管理 自动的。OpenCode 自动管理上下文窗口。每轮调模型之前检查用了多少空间接近 80% 就开始整理最新内容完整保留旧的内容压缩成摘要。整个过程后台自动完成你在操作中完全感觉不到。从业者不需要重新实现这套机制但需要理解它的存在——它决定了你的 Agent 能在一次会话里跑多远。错误处理 3 次上限 问人。工具调用连续失败 3 次系统就停下来问用户“要不要换个方式” 这就是前面讲的三级策略的具体实现有限重试 人工接管。七、写在最后回到开头。AI 能做复杂任务不是因为它变聪明了。是因为有人给它设计了一套做事的方法接到任务先拆解拆完了按步骤跑循环每一步拿工具干实事出错了调整搞不定了问人。这套方法不是灵丹妙药但把不确定性控制在了可管理的范围内。你不需要预测 AI 会怎么走每一步你只需要确保它的运作框架是对的。这也是看懂 AI的最终目的不是学会怎么跟 AI 聊天而是知道什么场景可以放心交给它、什么场景需要你盯一下、什么场景根本不该让它碰。下一篇聊一个很多人都在问的问题我的资料、文档、知识那么多AI 怎么才能找到需要的信息这件事有一个词叫 RAG——但它的核心可能跟你以为的不太一样。关于 ArchAIHarness这篇文章是「看懂 AI 与智能体」专栏的一部分由ArchAIHarness持续输出。ArchAIHarness 是一套面向 AI 时代软件工程的人机协同架构哲学与公开工程资产主张架构师定义秩序AI 在秩序中生长。人立法AI 执行体系审计。如果你也希望 AI 在明确的架构边界内协作而不是在混沌中碰运气欢迎到 GitHub 上看看我们在做什么组织主页github.com/ArchAIHarness — 了解完整理念与资产全景本专栏zhuanlan-ai-and-agents— 所有文章的源码与发布记录实践指南docs— 架构哲学、工程方法和落地指南开源工具agent-workflows— 可复用的 AI 协作 Agents、Skills 与 Tools工程样例framework— DDD AI 协作的工程底座展示如何在开发中融合 AIEngineered by Architects · Empowered by AI · Audited by Discipline