企业官网建设流程全解析

我先说明一下，目前“纯白文输出”和“真实场景内容”往往是矛盾的：越是真实自然的内容，越需要具体上下文和语气；而纯结构化输出会自带“模板感”，所以我尽量按“从业者分享帖”的口吻来写，尽量保持自然。

1. 为什么“记忆型 AI”是个伪需求：从“会聊天”到“能开工”

我实在受够了那种“记住我问过什么，然后给出一大段正确但没用废话”的AI。你问它“帮我整理一下这个目录里的文件”，它给你一份漂亮的《文件整理指南》；你说“把这几份周报汇总一下”，它告诉你“你可以用Excel”。对话记录拉了几百轮，它比谁都知道你昨天在纠结什么，但今天你还是得自己打开终端、手敲命令、逐个解决问题。

这就是我说的“记忆型AI”：它唯一的本事是记住上下文，然后用大模型的话术把问题包装成“已解决”。问题是，我们缺的从来不是答案，而是执行。一个人被琐事缠身的时候，需要的不是第三个告诉他“应该做什么”的顾问，而是一个能打开编辑器、跑脚本、写文件、发请求、最后给你一个结果的数字执行者。把个人Agent推到“可以真正开工”的阶段，本质上是把AI从“对话接口”变成“操作接口”，让它拥有手和脚，而不仅仅是嘴巴和耳朵。

这个过程其实不玄乎，也不需要一个几十人的团队。我们这次只花了几天时间，做出来的东西不是什么通用超级智能，而是一个能实际干活的个人Agent：它能读你指定的文件、能执行你允许范围内的代码、能调API、能操作浏览器、能按计划做定时任务，最关键的是，它在干完活之后会给你一份可核对的结果，而不是一句“已完成”。这篇文章就是把这几天的思路、选型、踩坑和最终方案完整记录下来，给正准备入坑Agent开发、或者已经被“只会聊天”的助手逼疯的朋友一个可参考的路线。

2. 架构怎么选：自研、框架、还是“混搭”

2.1 先想清楚你要的是“可控”还是“快”

网上Agent框架一搜一大把，LangChain、AutoGPT那种大而全的框架，看起来什么都能干，真上手的时候经常被抽象层卡住。我第一版图省事，直接套了LangChain的AgentExecutor，结果调试一个工具返回值格式花了半天，最后发现是框架内部对报错信息的封装把原始内容吃掉了。个人做Agent，尤其是要接自己本地环境和私有工具的时候，控制权比开发速度重要得多。

我们的结论是：主循环自己写，只借用少量稳定的库（比如做embedding、做浏览器自动化），不把核心逻辑绑死在某个框架上。原因不复杂，Agent的核心逻辑其实就是一个“目标—拆解—执行—观察—再执行”的循环，这个循环本身用一两百行就能写明白，一旦套进框架，反而要花大量时间去理解框架的“约定”，还要被它的版本升级牵着走。自己写主循环，每一个环节都是透明的，出问题能直接定位到代码行，改起来也快。

2.2 ReAct循环还是Plan-and-Execute：两种模式的搭配

Agent的任务编排模式，业界讨论最多的就两条路线：ReAct和Plan-and-Execute。ReAct是“边想边做”，Agent每执行一步工具调用，就把结果放回上下文，再决定下一步干什么，适合任务步骤不固定、需要随机应变的场景。Plan-and-Execute则是先把任务拆成一份完整计划，再按计划逐步执行，适合步骤明确、流程稳定的任务。

实测下来的感受是：单用ReAct，短任务很好用，任务一旦超过五步，Agent就会开始“原地转圈”——每步都产生大量推理文本，但没有实质推进。单用Plan-and-Execute也不行，现实任务往往在执行过程中出现预料之外的情况，计划做得再细也会被打破。我们最后采用的是“先Plan后ReAct”的混合模式：收到用户目标后，先让Agent生成一批步骤清单，然后进入ReAct循环执行；每完成一步，对比当前状态和计划目标的差距，如果出现偏差，就局部调整计划而不是重新规划全部。

这个取舍背后有一个很实际的理由：大模型在“长时间定位到一个目标”上的注意力衰减非常快。你让它连着做十个步骤，做到第五步它可能已经忘了最初的目标关键词。先把计划写在前面，相当于给它一个“外置便签”，让循环里的每一步都能回看目标，而不是只依赖那一刻的context窗口。

2.3 单Agent还是多Agent：别上来就Multi-Agent

市面上很多Demo喜欢搞“主管Agent+多个专家Agent”，看起来很有未来感，但对个人项目来说，这基本是给自己找不痛快。多Agent的协作需要解决消息协议、共享状态、任务分配、冲突消解一系列问题，调试难度是指数级上升的。我们最终选择了单Agent加工具列表的架构，原因很简单：个人Agent的日常工作流，绝大多数是串行的，一个Agent拿着工具列表按顺序执行就够了。

单Agent架构还有一个额外的好处：上下文不会因为多Agent之间的信息传递而被稀释。多Agent场景里，一个工具的执行结果要打包传给另一个Agent，中间会丢失大量细节，最后往往要回查日志才能搞清楚是谁在哪个环节搞错了。单Agent模式下，所有工具调用结果都在同一个上下文里，出了问题直接看原始输出就能定位。

3. 记忆系统：别把聊天记录当记忆

3.1 工作记忆、长期记忆与任务状态：三者要分开

这是这次项目中我体会最深的一点。很多人做“带记忆的Agent”，就是把每次聊天记录全部塞进上下文，这完全是对记忆的误解。聊天记录只是原始的对话日志，它不等于记忆。真正的记忆系统至少要分三层：

• 工作记忆：当前任务运行中产生的中间状态，比如“我正在写的这个脚本有哪几个函数”“当前处理到第几个文件”。
• 长期记忆：跨任务、跨会话稳定的信息，比如用户的习惯、偏好、常用工具路径、项目背景。
• 任务状态：这是个人Agent特有的一类记忆，它记录的是一个任务做到哪一步了、下一步要做什么，用于任务中断后的恢复。

我们一开始只做了长期记忆（其实也只是存对话摘要），结果发现Agent在同一个任务里做着做着就“失忆”了。后来才意识到，它缺的不是长期记忆，而是任务状态。解决方式也很简单：每个任务开始时初始化一个状态对象，每完成一步就更新状态对象，下次继续时把状态对象塞回上下文。相当于给Agent配了一个“进度本”，而不是让它靠回忆来记住自己干到哪了。

3.2 向量库不是万能的：该用SQLite就别硬上RAG

热词里全是向量数据库、RAG，但个人Agent的场景里，大量信息其实是结构化偏好，不是非结构化文本。喜欢在下午写代码、常用浏览器是Chrome、代码仓库在~/work/projects，这种数据用JSON或者SQLite存就行，检索又准又快，完全不需要向量化。只有当你需要根据语义检索文档片段的时候，才值得引入向量库做embedding。

举个例子，我让Agent处理“项目文档问答”这类任务时，确实是先对文档做切片、embedding、存向量库；但日常任务里，更多信息是以“键值对”形式存在的，比如“用户常用邮箱是xxx”“每周五需要生成周报”，这类信息直接放在一个结构化的profile文件里，每次任务开始前读进来就行，简单直接还不容易出错。

还有一个被忽视的问题：记忆污染。向量库里的记忆如果写入时不加筛选，时间长了什么垃圾都有。我们最后给记忆写入加了一道过滤：只有满足“与用户目标相关”“对后续决策有帮助”“信息置信度高”三条规则的内容才允许写入长期记忆，其他一律只留在当次任务的上下文里。关于记忆安全，可以参考学术圈在讨论的a-memguard那类思路，本质上是防止外部内容通过记忆通道恶意改写Agent的行为偏好——个人Agent虽然威胁面小，但养成“写入前审查”的习惯绝对不亏。

3.3 Agent要会“遗忘”：记忆的衰减与清理

长期记忆装得越多，Agent的决策反而越容易被陈旧信息干扰。我在实践中发现，一个三个月前的偏好，很可能已经过期了，但Agent会把它当成当前事实来用。所以现在我的Agent每个星期做一次记忆整理：对每条长期记忆打分，按“最近使用频率”和“是否与当前项目相关”两个维度排序，低分的直接归档，高分的保留。

跟遗忘配套的是记忆的“摘要化”：每次任务结束后，Agent会生成一段结构化的任务摘要，包含任务目标、执行路径、结果、遗留事项，然后只存摘要，不存完整对话。这样长期记忆的体积可控，检索时也不容易被无关信息干扰。说实话，这一步才是让Agent真正“越用越聪明”的关键，比多接十个工具都管用。

4. 工具能力的封装：Agent的“手”长什么样

4.1 Tool Schema：写给模型看的“使用说明书”

Agent能不能“开工”，九成取决于工具封装的质量。我见过太多人把工具描述写得跟API文档一样工整，结果模型根本不知道怎么调用。核心问题在于：工具描述是写给大模型看的，不是写给程序员看的。大模型的思维模式是“意图匹配”，如果工具描述里没有“什么时候该用这个工具”的触发条件，它就不会用。

我总结了一套好用的Tool Schema写法，大家可以抄作业：

• 名称：动词+名词，一眼能看出是干什么的，比如list_files、execute_python、search_web。
• 描述：包含三部分——功能说明、适用场景、不适用场景。不用写太多技术细节，但要写清楚“什么情况选我”。
• 参数：给每个参数写一个真实示例值，比写类型注解有用得多。模型看到“path: /Users/me/projects”这样的示例，比看到“path: string”更容易理解。
• 返回值：说明返回格式，尤其是失败时会返回什么。

还有一个容易被忽略的点：工具要能“解释自己”。我给每个工具加了help字段，Agent在犹豫的时候可以调用help来查看该工具的详细用法，就像人在用命令行之前敲一下--help。这个设计让新工具的接入成本降低了很多，不用每次都改prompt来告诉Agent新工具怎么用。

4.2 浏览器操作与API调用：两只最重要的“手”

个人Agent最常见的两类工具，一个是操作浏览器，一个是调API。浏览器这块我们用的是Playwright，它对现代网页的兼容性比老牌的Puppeteer稳得多，而且支持持久化上下文，Agent能保持登录态。实际操作中踩过最大的坑是页面加载时机：直接用page.click()经常因为元素还没渲染出来就报错，后来统一在点击前加了wait_for_selector和wait_for_load_state双重等待，问题基本消失。还有一点，用浏览器自动化抓数据时，如果目标网站有验证码，建议直接放弃自动化，转用API，别在这种事上跟风控死磕。

API调用这块的核心是权限最小化。我的Agent配置文件里维护了一个白名单，只有在白名单里的域名和接口才能被调。每个API Key都单独设置最小scope，比如只能读不能写、只能调用某个特定服务的接口。这样即使Agent被prompt注入诱导着去乱调接口，也翻不出什么大浪来。至于网上讨论的“Agent能不能替你发邮件、发消息”这类操作，我的建议是：凡是会产生真实世界影响的操作，一律加一道人工确认，成本也就一个弹窗，但能避免很多灾难性后果。

4.3 本地环境的安全边界：Agent能跑代码，但不能乱跑

个人Agent不可避免地要执行代码、读写文件，这是它“能干活”的基础，也是最大的风险点。我们在设计时做了三层防护：

第一层，文件系统的虚拟目录映射。Agent只能访问一个配置好的项目根目录，这个目录之外的路径一概拒绝。即使Agent被诱导去读/etc/passwd或者用户目录下的私密文件，也会被这层拦截挡住。

第二层，危险操作的确认机制。删除文件、批量修改、向外部发送数据，这些操作在执行前必须输出一条确认请求，由用户在终端里输y才能继续。刚开始觉得繁琐，但实际用下来发现，Agent每天遇到的“危险操作”其实很少，偶尔弹一两次确认完全不影响使用体验。

第三层，操作日志与回滚。Agent做出的每一个文件改动，都会自动生成一份diff记录，存在日志目录下。如果哪次改动出了问题，可以直接用这份diff回滚。这个机制救了我好几次，尤其是Agent批量重命名文件的时候，有一次正则写错了，差点把一批配置文件改成乱码，靠diff记录一秒救了回来。

5. 实操记录：四天把一个个人Agent推到可开工状态

5.1 第一天：定义场景和工具清单

我踩过最大的一次坑，就是没想清楚“让Agent干什么”就直接开写代码。结果Agent什么都能干一点，但没一件事做得利索。这次我学乖了，第一天全部用来定义场景，一张纸一支笔，写下三个最高频的痛点任务：

• 自动整理下载目录：按文件类型/项目分类，重命名，移动到对应文件夹，生成一份整理报告。
• 每日信息汇总：定时从几个指定源抓取更新，用大模型做摘要，生成一份简报发到指定邮箱。
• 代码仓库维护：检查当前分支状态、跑测试、按规范做commit，偶尔清理过期的分支。

定好场景之后，再把每个场景拆解成“工具调用序列”。比如“整理下载目录”需要：列出目录文件 → 读取文件元信息（类型、时间）→ 判断目标分类 → 执行移动 → 生成报告。这一步做完，工具清单自然就出来了：文件操作工具、元数据读取工具、代码执行工具、HTTP请求工具、浏览器操作工具、定时调度工具。第一版就六个工具，贪多嚼不烂。

5.2 第二天：主循环与上下文管理

第二天开始写Agent的主循环，框架代码如下：

def agent_loop(user_goal, available_tools): context = load_context(user_goal) plan = planner.generate(user_goal) for _ in range(max_steps): action = model.decide(plan, context, available_tools) if action.type == "finish": return action.result result = execute_tool(action.tool_name, action.params) context.add_observation(action, result) if result.type == "error": model.revise_plan(plan, result.error) return "max_steps exceeded"

这个循环的核心在两个点：decide和revise_plan。decide是决定下一步动作，revise_plan是出错后的修正逻辑。我在第一天只写了主循环，没写修正逻辑，结果运行起来遇到工具报错就卡死，因为模型会机械地反复调同一个工具，直到步数上限。

上下文管理这块，重要的原则是“不把工具返回的原始内容全塞给模型”。比如execute_python工具执行一个有大量输出的脚本时，原始输出可能有几千行，直接塞进上下文不仅浪费token，还会干扰模型判断。我们的处理是：工具返回结果先做摘要（取前100行和后100行，加上统计信息如“共输出3000行，前100行内容为...”），再放进上下文。这样模型既保留了“发生了什么”的大局观，又不会被细节淹没。

提示：主循环里的max_steps建议设置在8到12之间。太低任务完不成，太高模型会在错误的路上越走越远，浪费大量token。

第二天结束时，我的Agent已经能跑通“文件整理”和“仓库维护”两个场景了，虽然还很粗糙，但已经是一个能“开工”的雏形。

5.3 第三天：Evals与端到端测试

很多人在Agent开发中不做测试，理由是Agent的产出是开放式的，没法断言对错。这句话对了一半。开放式的确没法做“完全正确”的断言，但你可以做“关键行为”的断言。我把第三天全部用在写Evals，就是热词里那个“agent evals”。

具体做法：准备10条端到端测试用例，每条包含输入指令、预期行为序列、预期产出关键字段。比如“整理下载目录”的预期行为是“调用list_files→调用read_metadata→调用move_files→输出报告”，预期产出的关键字段是“移动了X个文件，剩余Y个未处理”。每次改完代码，把这10条用例跑一遍，看行为序列是否匹配、关键字段是否出现。

团队里另一个伙伴觉得这样太费时间，不如直接跑真实任务。但这个测试流程在第三天晚上就发挥了关键作用：我们改了一个工具参数的命名方式，结果没跑Evals直接上真实任务，Agent连续三次用旧参数名调用工具，每次都报错重试。跑了Evals后，这种“改了工具名但忘记同步Agent调用格式”的蠢问题被瞬间抓了出来。

注意一个坑：用大模型判断Agent行为是否正确时，别全信它的“看起来不错”。我吃过一次亏，大模型在eval里给出“完全正确”的评分，但实际产出文件是错的。后来我给每条case加了一个“可验证条件”，必须从文件系统或API返回值里抽取实际结果进行判断，不让模型空口评价。

5.4 第四天：记忆系统完善与权限细化

第四天做的两件事，一件是把前一天的记忆代码升级成三层结构，另一件是权限安全加固。记忆这块花了最多时间的是“摘要生成策略”。一开始我让Agent每轮对话都生成摘要，结果发现摘要里垃圾信息太多，原因是大模型在“没必要总结”的时候也会强行凑内容。

改进方法是定义一个“总结触发条件”：只有当任务阶段切换（比如从“调研”进入“实施”）、或者已经进行了超过10轮对话时，才生成阶段性摘要。其他时间不生成摘要，只更新任务状态对象。这个改动让长期记忆的质量提升非常明显，摘要里不再是流水账，而是真正有决策价值的信息。

权限细化这块前面已经说过，文件系统虚拟目录、危险操作确认、操作日志三条防线一个不少。第四天结束时，我们的Agent已经能稳定跑完三个核心场景，并且能在一周的使用中不出现“灾难性失误”——但小错还是会犯，比如偶尔会弄错文件分类规则，这是正常的，只需要在提示词里增加一条“如果不确定分类规则，先询问用户”。

6. 避坑实录：这几天踩过的坑

6.1 Agent死循环：工具失败后不断重试

这个坑几乎每个Agent开发者都会遇到。Agent调用一个工具失败，于是很“努力”地换个参数再试，连续失败八次，最后步数耗尽，任务失败。根因是：大模型缺少“放弃”的元认知，它不会判断“这个工具是不是不适用于这个场景”。

解决方式：在工具返回的错误信息里，加一个结构化字段retryable。retryable: true表示参数问题可以重试，retryable: false表示这个工具本身不适用当前任务，Agent应该换工具或者换策略，而不是继续重试。这个小小的字段目前是我用过最有效的防死循环手段之一。

6.2 上下文爆炸：工具返回几十KB塞进prompt

上面说过用摘要截断来解决，这里再补充一个细节：不只是“长度截断”，还要做“结构梳理”。比如工具返回的是JSON，不要直接把原始JSON扔进去，转成人类可读的摘要文本效果更好：

用户列表（共3人）： - alice，管理员，创建于2024-01-01 - bob，普通用户，创建于2024-06-15 - carol，编辑，创建于2024-09-30

模型对这种结构化文本的理解效率远高于原始JSON，而且上下文占用直接减少一个数量级。说白了，工具返回给模型的格式，要以“模型容易理解”为准，而不是以“程序效率”为准。

6.3 记忆混乱：昨天的偏好影响今天的判断

一次把Agent部署到真实环境后，我发现它在处理一个与上周相似但又不完全相同的任务时，错误地沿用了上周的偏好设定。排查发现是长期记忆里的旧偏好没有被更新，Agent把“用户喜欢A方案”当成当前事实用了。从那以后我加了一条规则：每次任务开始前，Agent会先回顾与本次任务相关的长期记忆，并显式标注“该信息最后更新时间”，超过时间阈值的信息必须向用户确认是否仍然有效。

6.4 权限失控：Agent悄悄改了我没让它改的文件

有一次我让Agent整理一个项目目录，它的行为序列里多出了一个“修改package.json”的操作。查日志发现，它在读取文件元数据时注意到package.json的版本号可能是旧的，于是“自作聪明”地更新了。这个问题暴露出一个设计缺陷：Agent在默认情况下，对文件系统的所有已有文件都有“读改”权限。修复方式：给每个文件按目录设置权限级别，比如“只读目录”“可写目录”，Agent只有在可写目录下才能做修改操作，其他目录一律只读。这套权限配置放到了配置文件里，每次任务前加载，简单有效。

7. 常见问题速查表

8. 结尾：一些个人体会

做完这几天，最大的体会是：Agent开发的难点从来不在模型，而在“把现实世界的工作流压缩成工具接口”。模型越来越聪明，但你给它六个精心设计的工具，它就能干六种活；给它三个设计糟糕的工具，它就只能原地打转。工具接口的设计，才是Agent能否“开工”的分水岭。

另外想对准备入坑的朋友说一句：别一上来就追什么炫酷的Multi-Agent框架、复杂的知识图谱记忆，先把一个单Agent带着三五个工具跑通一个真实场景。只要那个场景是能给你省时间、省力气的，Agent就值得做下去；如果连一个场景都跑不通，堆再多框架和概念都是空中楼阁。我自己的下一步是把这个Agent接进更多日常工作流，顺便把记忆清理策略做得更细一些——毕竟“会遗忘”这件事，可能才是Agent从“玩具”变成“工具”的最后那块拼图。