企业官网建设流程全解析

1. 从一次真实的调试困境说起

前阵子我在折腾一个自动化代码生成的小工具，需求本身不复杂：给一段自然语言描述，让它自动生成对应的函数实现，再跑一遍测试验证。听起来像是把大模型接进来就完事了，但真正动手之后才发现，坑远比想象中多。模型确实能生成代码，可它生成完就"撒手不管"了——不会自己去看编译报错，不会主动去跑测试，更不会根据失败结果回头改代码。我一开始的做法是在外面套一层循环，把报错信息拼回提示词里再喂给模型，让它重试。这个土办法能跑通，但很快就遇到了新问题：模型改着改着就开始"幻觉"，明明文件里没有的函数它硬说存在，明明测试没通过它硬说通过了。

这个经历让我意识到，一个真正能用的代码智能体，光有"生成"能力是远远不够的。它需要一套完整的运行机制：怎么循环、怎么调用工具、怎么感知环境、怎么在安全边界内操作、怎么验证结果。后来我系统性地研究了一下 Codex 这类代码智能体的架构设计，发现它把这些问题拆解成了八个核心功能模块，从最底层的 Agent Loop 一直延伸到最外层的沙盒边界。这套设计思路非常值得借鉴，不管你是想自己搭一个代码智能体，还是只是想理解这类工具背后的工作原理，把这八个功能搞清楚，基本就能看透整个系统的骨架了。

这篇文章我会按照"从内到外"的顺序，把这八大功能一个一个拆开讲。每个功能我都会说清楚三件事：它解决什么问题、它是怎么实现的、以及在实际落地时有哪些容易踩的坑。文章会涉及不少工程细节和参数选择的考量，适合有一定开发基础、想深入理解代码智能体架构的读者。如果你只是想找个工具用用，那这篇文章可能偏"重"了，但如果你想自己动手做一个，或者想搞清楚为什么有些智能体好用有些不好用，那接下来的内容应该能帮你省下不少试错时间。

2. 八大功能整体架构与设计思路

2.1 为什么是"八大功能"而不是"八大模块"

在正式拆解之前，我想先说一下这套功能划分背后的逻辑。很多人第一次接触这类系统时，会习惯性地按"模块"去理解——比如"规划模块""执行模块""记忆模块"。但 Codex 这类系统的设计思路不是按模块切的，而是按"功能职责"切的。这两者的区别在于：模块是静态的代码组织单位，而功能是动态的运行职责。一个功能可能横跨好几个代码模块，一个模块也可能同时承担多个功能职责。

举个具体的例子。"工具调用"这个功能，它既涉及到提示词层面的工具描述注入，又涉及到运行时的参数解析和函数分发，还涉及到结果回传时的格式处理。如果你按模块去理解，这些代码可能散落在四五个不同的文件里；但如果你按功能去理解，它们就是一个完整的闭环。这种"按功能划分"的思路，好处是每个功能都有明确的输入输出边界，方便单独测试和替换。比如你想把某个工具的实现换掉，只要保证输入输出格式不变，其他功能完全不受影响。

2.2 从内到外的四层结构

把这八个功能按依赖关系排一下，大致可以分成四层。最内层是Agent Loop，它是整个系统的心脏，负责驱动"思考-行动-观察"的循环。往上一层是工具调用和上下文管理，这两个功能直接服务于循环，一个负责让智能体有"手"可以操作环境，一个负责让智能体有"记忆"可以记住之前发生了什么。再往外是代码执行、文件操作和结果验证，这三个功能是智能体与外部世界交互的具体手段。最外层是沙盒边界和权限控制，它们负责约束智能体的行为范围，确保它不会闯祸。

这个分层不是随便定的，它反映了一个核心设计原则：能力越强的功能，约束就要越严格。Agent Loop 本身没有副作用，它只是驱动循环，所以不需要额外约束；但代码执行功能可以直接在系统上跑任意命令，所以必须放在沙盒里，还要配合权限控制。这个原则贯穿整个系统设计，理解了它，后面每个功能的设计取舍就都好理解了。

2.3 一个容易忽略的设计前提

还有一点需要提前说明：这八大功能的设计，都建立在一个前提之上——智能体的行为必须是可观测、可中断、可回滚的。可观测意味着每一步操作都要有日志记录，出了问题能查到是哪一步出的错；可中断意味着循环不能是死循环，必须有终止条件，用户也要能随时叫停；可回滚意味着如果某一步操作造成了破坏，要有办法恢复到之前的状态。

这个前提看起来像是"正确的废话"，但在实际实现中，很多设计决策都是围绕它展开的。比如为什么 Agent Loop 要有最大迭代次数限制？就是为了保证可中断。为什么文件操作要先写临时文件再原子替换？就是为了保证可回滚。为什么工具调用的结果要结构化返回而不是直接打印？就是为了保证可观测。后面讲到具体功能时，我会反复提到这个前提。

3. Agent Loop：整个系统的心脏

3.1 循环的基本结构

Agent Loop 的核心逻辑其实很简单，用伪代码表示大概是这样：

while not done: response = model.generate(context) if response.has_tool_call(): result = execute_tool(response.tool_call) context.append(result) else: done = True

就这么几行，但它包含了三个关键决策点。第一个决策点是什么时候继续循环——只要模型还在请求调用工具，循环就继续；一旦模型不再请求工具，而是直接给出最终回答，循环就结束。第二个决策点是每次循环往上下文里放什么——不是把所有历史都塞进去，而是要有选择地保留关键信息。第三个决策点是循环什么时候强制终止——除了模型主动结束，还要有最大迭代次数、超时时间等硬性限制。

这三个决策点里，最容易出问题的是第二个。我见过不少实现，图省事把每一轮的完整对话历史都塞进上下文，结果跑不了几轮就爆了 token 限制。正确的做法是维护一个"工作记忆"，只保留与当前任务相关的信息，把已经完成的步骤压缩成摘要。这个压缩策略怎么设计，直接决定了智能体能处理多复杂的任务。

3.2 循环终止条件的工程考量

关于终止条件，我想多说几句，因为这是实际落地时最容易踩坑的地方。最直观的终止条件是"模型不再调用工具"，但这不够。你还需要至少三个兜底条件：最大迭代次数、单步超时、总超时。

最大迭代次数设多少合适？这个没有标准答案，取决于任务复杂度。我的经验是，对于代码生成类任务，20 到 30 轮通常够用；如果是复杂的重构任务，可能需要 50 轮以上。但设太大也有风险，因为轮次越多，上下文越容易膨胀，模型越容易"跑偏"。一个实用的技巧是设置"软限制"和"硬限制"：软限制到了之后，给模型发一个提示，让它尽快收尾；硬限制到了之后，直接强制终止。

单步超时和总超时是防止"卡死"的关键。有些工具调用可能会挂起，比如执行一个死循环的代码，或者等待一个永远不返回的网络请求。如果没有超时机制，整个循环就会卡在那里。单步超时建议设在 30 秒到 2 分钟之间，总超时根据任务预期时长来定，一般不超过 10 分钟。

注意：超时时间不要设得太短。我一开始把单步超时设成 10 秒，结果很多正常的代码编译都被中断了，因为冷启动编译有时候就要十几秒。后来改成 60 秒，误杀率就降下来了。

3.3 循环中的状态管理

Agent Loop 还有一个容易被低估的职责：状态管理。每一轮循环都会产生新的状态——模型说了什么、调用了什么工具、工具返回了什么、当前任务进展到哪一步了。这些状态需要有地方存，而且要存得有条理。

我的做法是把状态分成三类：对话状态、任务状态和环境状态。对话状态就是消息历史，任务状态是当前任务的进度信息（比如"已完成 3 个子任务，还剩 2 个"），环境状态是外部世界的快照（比如当前工作目录下有哪些文件、文件内容是什么）。这三类状态的生命周期不一样：对话状态每轮都在变，任务状态变化较慢，环境状态只在特定操作后更新。分开管理的好处是，上下文压缩时可以针对性地处理——对话状态可以压缩得狠一点，任务状态要保留完整，环境状态按需刷新。

4. 工具调用：给智能体装上"手"

4.1 工具描述的设计艺术

工具调用功能的核心，是让模型知道"有哪些工具可用"以及"怎么用"。这听起来简单，但工具描述怎么写，直接决定了模型能不能正确调用。我见过太多工具描述写得含糊不清，导致模型要么不用工具，要么用错参数。

一个好的工具描述应该包含四个要素：工具名、功能说明、参数列表、使用示例。工具名要见名知意，比如read_file比get_content好，run_tests比execute好。功能说明要一句话讲清楚这个工具干什么，不要写成长篇大论。参数列表要标明每个参数的类型、是否必填、取值范围。使用示例是最容易被忽略但最重要的部分，给一两个具体的调用例子，能大幅降低模型用错的概率。

这里有个反直觉的经验：工具数量不是越多越好。我一开始恨不得把所有能想到的操作都做成工具，结果模型反而不知道该用哪个了。后来我把工具精简到十几个核心操作，每个都打磨清楚，调用准确率反而上去了。原因是模型在选择工具时，候选越多，决策越容易出错。一般来说，20 个以内的工具数量是比较舒服的区间。

4.2 参数解析与校验

模型生成的工具调用参数，不能直接拿来用，必须经过解析和校验。解析是把模型输出的文本（通常是 JSON 格式）转成程序能用的数据结构，校验是检查参数是否符合预期。

解析环节最常见的坑是 JSON 格式错误。模型有时候会生成带注释的 JSON，或者用单引号代替双引号，或者漏掉闭合括号。健壮的解析器应该能容忍这些常见错误，比如先尝试标准解析，失败了再用宽松模式解析，还不行就报错让模型重试。

校验环节要检查的东西包括：必填参数是否都有、参数类型是否正确、参数值是否在合法范围内。比如文件路径参数，要检查路径是否在允许的目录内；命令参数，要检查命令是否在白名单里。校验不通过时，不要直接抛异常终止，而是把错误信息返回给模型，让它重新生成参数。这样循环几次，模型通常能自己纠正过来。

4.3 工具执行与结果回传

工具执行本身没什么好说的，就是调用对应的函数。但结果回传有讲究。回传的结果要满足三个要求：结构化、有截断、带元信息。

结构化是指结果要用统一的格式返回，比如都包成{"success": true, "data": ..., "error": null}这样的结构。这样模型处理起来不用猜格式。有截断是指结果不能无限长，比如读取一个大文件，不能把整个文件内容都塞回去，要截断到合理长度（比如前 2000 行），并注明"已截断"。带元信息是指结果里要包含一些辅助信息，比如执行耗时、返回的数据量、是否有警告等，这些信息能帮模型判断下一步该怎么做。

实操心得：工具执行结果里，错误信息要写得足够详细。我一开始只返回"执行失败"，模型完全不知道该怎么改。后来改成返回具体的错误类型、错误位置、可能的修复建议，模型的自纠能力明显提升了。

5. 上下文管理：智能体的"记忆系统"

5.1 上下文窗口的分配策略

上下文管理是八大功能里最"低调"但最影响体验的一个。模型的能力上限，很大程度上取决于上下文里放了什么。上下文窗口是有限的，怎么分配这块"内存"，是个技术活。

我的分配策略是这样的：系统提示词占 10%，工具描述占 15%，任务描述占 10%，历史对话占 40%，当前观察占 25%。这个比例不是固定的，会根据任务阶段动态调整。任务刚开始时，历史对话占比可以低一些；任务进行到中后期，历史对话占比要高一些，因为需要记住之前的决策。

系统提示词和工具描述是"固定开销"，每次都要带上，所以要尽量精简。任务描述是当前任务的说明，也要保留。历史对话和当前观察是"可变开销"，需要动态管理。当上下文快满时，优先压缩历史对话，把早期的对话压缩成摘要，保留近期的完整对话。

5.2 历史压缩的几种方法

历史压缩有几种常见方法，各有优劣。最简单的是滑动窗口，只保留最近 N 轮对话，更早的直接丢掉。这种方法实现简单，但会丢失早期的重要信息。稍微好一点的是摘要压缩，把早期对话让模型总结成一段话，保留摘要丢掉原文。这种方法能保留关键信息，但摘要本身也可能丢失细节。

更精细的是分层压缩，把对话按重要性分层，重要的完整保留，次要的压缩成要点，不重要的直接丢弃。判断重要性的依据可以是：是否包含关键决策、是否包含错误信息、是否包含用户明确要求记住的内容。这种方法效果最好，但实现也最复杂。

我实际用的是"摘要压缩 + 关键信息提取"的组合。具体做法是：当对话轮次超过阈值时，把最早的几轮对话让模型总结成摘要，同时提取出其中的关键信息（比如文件路径、函数名、错误信息）单独存起来。摘要和关键信息一起放回上下文，这样既压缩了体积，又保留了要点。

5.3 上下文污染的防治

上下文污染是个隐蔽但危害很大的问题。所谓污染，是指上下文里混入了错误、过时或无关的信息，导致模型判断失误。常见的污染源有三个：工具返回的错误信息、模型的幻觉内容、过时的环境状态。

工具返回的错误信息如果处理不当，会一直留在上下文里，让模型误以为问题还没解决。防治方法是，当问题解决后，主动清理相关的错误信息，或者用一条"问题已解决"的标记覆盖掉。模型的幻觉内容更麻烦，因为模型自己可能意识不到那是幻觉。防治方法是，对模型声称的事实性内容做校验，校验不通过的标记为"待确认"，不要让它影响后续决策。过时的环境状态，比如文件已经被修改了但上下文里还是旧内容，防治方法是每次操作前刷新环境状态，或者给状态加上时间戳，让模型知道哪些是新的哪些是旧的。

6. 代码执行：在沙盒里跑代码

6.1 为什么必须要有沙盒

代码执行功能让智能体可以真正跑代码、看结果，这是它区别于"纯文本生成"的关键。但跑代码意味着风险，一段恶意或有 bug 的代码可能删文件、改系统配置、发起网络请求。所以代码执行必须放在沙盒里。

沙盒的核心作用是隔离：隔离文件系统，让代码只能访问指定目录；隔离网络，让代码不能随意发起请求；隔离资源，让代码不能吃光 CPU 和内存。隔离的强度可以分级，从轻到重依次是：进程级隔离、容器级隔离、虚拟机级隔离。进程级隔离最轻量，用独立的子进程跑代码，限制它的权限；容器级隔离更彻底，用容器技术把代码关在一个独立的环境里；虚拟机级隔离最重，但隔离最彻底。

选择哪种隔离级别，取决于你的安全需求和性能要求。如果只是跑一些可信的代码片段，进程级隔离就够了；如果要跑用户提交的任意代码，那至少得用容器级隔离。我自己的工具用的是容器级隔离，启动一个轻量容器跑代码，跑完就销毁，兼顾了安全和性能。

6.2 执行环境的准备

沙盒里的执行环境需要提前准备好。最基本的是运行时环境，比如 Python 解释器、Node.js 运行时、编译器等。这些要预装在沙盒镜像里，不能等代码要跑了才去装，那样太慢。

除了运行时，还要准备依赖库。代码可能用到各种第三方库，这些库要么预装，要么允许代码自己装。预装的问题是镜像会很大，允许自装的问题是可能装到恶意库。折中方案是预装常用库，同时允许从可信源装其他库。

还有一个容易忽略的是工作目录。代码执行时需要一个工作目录，这个目录要预先创建好，并且要限制代码只能在这个目录及其子目录里操作。工作目录的初始内容也要准备好，比如把需要处理的文件先放进去。

6.3 执行结果的捕获与处理

代码执行的结果包括三部分：标准输出、标准错误、退出码。这三部分都要捕获，并且要结构化返回给模型。标准输出是代码正常打印的内容，标准错误是报错信息，退出码表示执行是否成功（0 表示成功，非 0 表示失败）。

处理结果时有几个细节要注意。第一，输出可能很长，要截断，但截断时要保留头尾，因为开头通常是关键信息，结尾通常是错误信息。第二，输出可能包含特殊字符，要转义处理，避免破坏上下文格式。第三，执行可能超时，超时要能中断并返回超时信息，而不是一直等下去。

注意：标准错误里经常包含大量警告信息，这些信息对模型判断问题帮助不大，反而会干扰。我的做法是过滤掉常见的警告，只保留真正的错误信息。

7. 文件操作：读写改查的完整闭环

7.1 文件读取的边界控制

文件操作看起来简单，但要做好并不容易。先说读取。读取文件时，最大的风险是读到不该读的文件，比如系统配置文件、其他用户的隐私文件。所以读取必须有边界控制，只能读指定目录下的文件。

边界控制的实现方式，是在读取前做路径校验。校验的逻辑是：把请求的路径转成绝对路径，然后检查这个绝对路径是否在允许的根目录之下。这里有个坑，路径里可能包含..这样的相对路径符号，如果不处理，就可能绕过校验。正确的做法是先规范化路径（解析掉所有..和.），再做前缀匹配。

读取大文件时还要注意内存问题。不能一次性把整个文件读进内存，要分块读或者限制读取长度。我的做法是默认只读前 2000 行，如果模型需要更多，再让它显式请求。

7.2 文件写入的原子性

写入文件比读取更危险，因为写错了可能覆盖掉重要内容。所以写入要保证原子性：要么完全成功，要么完全不动，不能出现写了一半的情况。

实现原子性的标准做法是"临时文件 + 原子替换"。具体步骤是：先把内容写到同目录下的一个临时文件，写完后调用操作系统的原子替换操作（比如rename），把临时文件替换成目标文件。这样即使写入过程中出错，目标文件也不会被破坏。

写入前还要做备份。如果目标文件已存在，先把它备份一份，万一新内容有问题，还能恢复。备份文件可以加个时间戳后缀，避免覆盖。

7.3 文件修改的精确性

修改文件是最复杂的操作，因为要精确地改对地方。常见的修改方式有两种：整体重写和局部替换。整体重写是把整个文件内容替换掉，简单但风险大，容易误删内容。局部替换是只改指定的部分，精确但实现复杂。

局部替换的关键是定位。定位方式可以是行号、可以是字符串匹配、可以是正则表达式。行号定位最简单，但行号容易因为前面的修改而失效。字符串匹配更稳，但要保证匹配的字符串唯一。正则表达式最灵活，但写不好容易匹配错。

我的经验是，优先用字符串匹配，匹配的字符串要包含足够的上下文，确保唯一性。如果匹配到多处，就报错让模型重新指定。修改完成后，要重新读取文件验证修改结果，确认改对了。

8. 结果验证：让智能体自己检查作业

8.1 验证的层次

结果验证是保证输出质量的关键环节。验证可以分几个层次：语法验证、逻辑验证、测试验证。

语法验证是最基础的，检查生成的代码能不能通过语法解析。比如 Python 代码可以用ast.parse检查，JavaScript 代码可以用解析器检查。语法不过关的代码，后面都不用看了。

逻辑验证更进一步，检查代码的逻辑是否合理。比如函数有没有返回值、变量有没有定义、类型是否匹配。逻辑验证通常需要静态分析工具，或者让模型自己审查。

测试验证是最强的验证，实际跑一遍测试，看结果对不对。测试可以是预先写好的单元测试，也可以是模型自己生成的测试用例。测试通过，基本就能确认代码是对的。

8.2 验证失败的反馈循环

验证失败不是终点，而是反馈循环的起点。验证失败后，要把失败信息整理清楚，返回给模型，让它修正。失败信息要包含：失败类型、失败位置、失败原因、可能的修复方向。

这里有个技巧：失败信息不要一次性全给，而是按重要性排序，先给最关键的。因为模型一次能处理的信息有限，给太多反而抓不住重点。我的做法是，先给第一条失败信息，让模型修，修完再验证，通过了再看下一条。这样虽然慢一点，但准确率高。

8.3 验证通过的确认

验证通过后，还要做最后的确认。确认的内容包括：所有验证项都通过了吗、有没有跳过的验证项、验证覆盖了所有关键路径吗。有时候验证通过只是因为测试用例没覆盖到出问题的地方，这种情况要特别警惕。

我的做法是，验证通过后，让模型自己再审查一遍，看有没有遗漏。同时，我会保留验证的完整日志，万一后面发现问题，可以回溯是哪一步验证没做到位。

9. 沙盒边界：安全与能力的平衡

9.1 边界的划定原则

沙盒边界是八大功能里最"外围"但最不能少的一个。它划定了智能体能操作的范围，超出范围的操作一律拒绝。边界的划定遵循一个原则：最小权限。也就是说，智能体只应该拥有完成任务所必需的最小权限，多余的权限一律不给。

具体来说，文件系统方面，只开放工作目录，系统目录一律不开放。网络方面，默认不开放，如果任务确实需要联网，再按需开放特定域名。进程方面，只允许启动白名单里的命令，其他命令一律拒绝。资源方面，限制 CPU、内存、磁盘的使用量，防止资源耗尽。

9.2 边界的动态调整

边界不是一成不变的，可以根据任务阶段动态调整。任务刚开始时，边界可以紧一点，只开放最基本的权限；随着任务推进，如果确实需要更多权限，再逐步放开。这种"渐进式授权"的思路，能在保证安全的同时，避免一开始就限制太死导致任务做不下去。

动态调整的实现方式是，把权限配置做成可变的，每次调整都记录日志。调整的触发条件可以是模型的显式请求，也可以是任务阶段的自动切换。比如进入"测试阶段"时，自动开放测试相关的权限。

9.3 边界突破的检测与响应

再严密的边界也可能被突破，所以要有检测和响应机制。检测的方式包括：监控系统调用、监控网络连接、监控资源使用。一旦发现异常，比如试图访问未授权目录、试图连接未授权地址，立即中断操作并记录。

响应机制要分级。轻微异常，比如一次未授权的读取尝试，可以只记录警告，继续任务。严重异常，比如试图执行危险命令，要立即终止整个任务，并通知用户。响应的分级标准要提前定好，不能临时判断。

10. 权限控制：谁能做什么

10.1 权限模型的设计

权限控制是沙盒边界的"软件层"实现，它定义了"谁能做什么"。权限模型的设计有两种常见思路：基于角色的访问控制和基于能力的访问控制。

基于角色的访问控制，是先定义角色（比如"只读角色""读写角色""管理员角色"），再给角色分配权限，最后把角色赋给具体的操作。这种模型直观易懂，适合权限种类不多的场景。

基于能力的访问控制，是直接给每个操作发放"能力令牌"，令牌里写明了这个操作能做什么。这种模型更灵活，适合权限粒度很细的场景。

我自己的工具用的是基于角色的模型，定义了三个角色：观察者（只能读）、操作者（能读能写能执行）、管理员（能改配置）。大部分任务用操作者角色就够了，只有需要改系统配置时才用管理员角色。

10.2 权限检查的时机

权限检查要在操作执行前做，而不是执行后。执行前检查，不通过就直接拒绝，不会造成任何副作用。执行后检查，操作已经发生了，再拒绝也晚了。

检查的粒度要细。不能只检查"能不能执行代码"，还要检查"能执行哪些代码"；不能只检查"能不能写文件"，还要检查"能写哪些文件"。粒度越细，安全性越高，但实现也越复杂。要在安全和复杂度之间找平衡。

10.3 权限提升的流程

有时候任务确实需要更高权限，这时候要有一个权限提升的流程。流程的设计要保证：提升是显式的、提升是临时的、提升是可审计的。

显式是指，权限提升必须由模型明确请求，不能自动发生。临时是指，提升的权限只在一段时间内有效，用完就收回。可审计是指，每次提升都要记录：谁提升的、提升了什么、为什么提升、用了多久。

实操心得：权限提升的请求里，要让模型说明"为什么需要这个权限"。这个说明不只是走形式，它能帮模型自己想清楚是不是真的需要，也能帮用户判断该不该批准。

11. 常见问题与排查技巧实录

11.1 循环卡死或无限重试

这是最常见的问题。表现是 Agent Loop 一直转，但任务没有进展。原因通常是模型反复调用同一个工具，或者反复生成同样的错误代码。

排查思路：先看日志，确认是卡在哪一步。如果是反复调用同一个工具，检查工具返回的结果是不是有问题，导致模型误以为没成功。如果是反复生成同样的错误代码，检查错误信息是不是没传回给模型，或者传回了但模型没理解。

解决方法：设置最大重试次数，同一个工具连续失败 N 次就强制换策略。同时，在错误信息里加入"你已经试过 X 次了，请换个方法"这样的提示，引导模型改变策略。

11.2 上下文溢出

表现是跑到一半突然报 token 超限。原因是上下文管理没做好，历史信息堆积太多。

排查思路：统计每一轮上下文的 token 数，看是哪一轮开始暴涨的。通常是某次工具返回了超大结果，或者某轮对话特别长。

解决方法：给工具返回结果加长度限制，超长就截断。给历史对话加压缩机制，超过阈值就摘要。同时，预留一定的 token 余量，不要等到满了才处理。

11.3 工具调用参数错误

表现是模型生成的参数格式不对，或者参数值不合法。原因是工具描述不清楚，或者模型理解有偏差。

排查思路：看模型生成的原始参数，对比工具描述，看是哪里的理解出了偏差。常见的是参数类型搞错（比如该传字符串传了数字）、参数名搞错（比如file_path写成filepath）。

解决方法：在工具描述里加更多示例，特别是边界情况的示例。在参数校验失败时，返回详细的错误信息，指明哪个参数错了、错在哪、应该是什么格式。

11.4 沙盒权限拒绝

表现是操作被沙盒拒绝，任务做不下去。原因是权限配置太严，或者操作确实越界了。

排查思路：看拒绝日志，确认是哪个操作被拒了、为什么被拒。如果操作是合理的，说明权限配置需要调整；如果操作确实越界，说明模型需要改变策略。

解决方法：对于合理的操作，动态调整权限配置，放开必要的权限。对于越界的操作，把拒绝原因返回给模型，引导它用合规的方式完成任务。

11.5 验证误报

表现是验证说失败了，但实际上代码是对的。原因是验证逻辑太严，或者验证环境有问题。

排查思路：手动跑一遍验证，看是不是真的失败。如果手动跑通过，说明是验证逻辑的问题；如果手动跑也失败，说明是代码的问题。

解决方法：调整验证逻辑，放宽不必要的限制。同时，确保验证环境和实际运行环境一致，避免因为环境差异导致误报。

12. 我在实际搭建中的几点体会

把这八个功能都实现一遍之后，我最大的体会是：这套系统的难点不在单个功能，而在功能之间的配合。每个功能单独看都不复杂，但要让它们协同工作，需要仔细设计接口和状态流转。比如 Agent Loop 和上下文管理的配合，循环每转一轮，上下文就要更新一次，更新的时机和内容都要精确控制，早了晚了都会出问题。

另一个体会是，日志和可观测性怎么强调都不过分。我一开始图省事，日志记得很粗，结果出了问题根本查不到原因。后来我把每一步操作、每一次工具调用、每一次上下文更新都记了详细日志，排查效率一下子提升了好几倍。如果你也在搭类似的系统，我强烈建议在日志上多花点时间，这个投入绝对值得。

还有一点是关于参数调优的。最大迭代次数、超时时间、上下文压缩阈值这些参数，没有一组"万能值"，都要根据实际任务调。我的做法是先设一组保守值，跑一批测试任务，看哪些参数经常触发限制，然后针对性调整。调参是个迭代过程，不要指望一次调好。

最后分享一个小技巧：给智能体加一个"自我反思"的环节。在任务结束前，让它回顾一下整个过程，总结哪些做得好、哪些可以改进。这个反思内容不用返回给用户，但可以存起来，作为后续优化的参考。我加了这个小环节之后，发现模型在类似任务上的表现确实有提升，因为它"记住"了之前的经验教训。