企业官网建设流程全解析

我一直有个习惯：新项目开工前，先老老实实盘一遍手头能直接拿来复用的基础设施，而不是打开 IDE 就新建目录。这个习惯在第二个 Agent 项目里被验证得特别彻底——从立项到上线用了九个星期，没有通宵赶工，也没有推倒重来，靠的就是一句话：先复用，再自己做。

第一个 Agent 我是反着来的，什么都想亲手写，结果被交付日期追着跑。第二个 Agent 我彻底换了思路：框架、模型接入、记忆、向量库这些通用能力全部交给现成的基础设施，自己只碰业务逻辑和差异化部分。这篇文章就把这套实践完整拆开，讲清楚我当时怎么选型、九周里每周在忙什么、踩了哪些坑，以及哪些地方最后不得不自己重写。如果你正在做 Agent 开发，或者准备把业务链路 Agent 化，这套思路可以直接抄作业。

1. 为什么第二个 Agent 我决定先复用，再自己做

1.1 第一个 Agent 的教训：从零造轮子到底有多痛

第一个 Agent 前身是个内部小工具，目标让人用自然语言查运维指标。当时我脑子一热，觉得用大模型 API 拼个对话轮次很简单，就从模型封装开始写了。结果真实项目根本不是“拼起来”那么简单。

第一关是模型接入。第一版同时接了不同厂商的两套 API，消息格式、参数名、流式返回长得都不一样，我写了两个适配器，可一上线就发现超时重试、限流处理完全没覆盖。第二关是工具调用。模型吐出来的 JSON 经常不合规范，需要额外纠错逻辑；工具那边的返回又五花八门，文本、表格、报错堆在一起，Agent 根本没法稳定解析。第三关是记忆。我把历史对话直接塞进上下文，到第七八轮 token 就爆了，只能粗暴截断，一截断它就忘了前面交代的事情。

四个月下来，功能是跑通了，但上线不是解脱，而是另一个坑的开始：上下文经常断、工具返回格式不统一、日志看半天不知道是哪一步出的问题。所以第二个 Agent 立项时，我给自己定了一条红线——凡是能找到现成基础设施的场景，一律先复用，等真正跑出瓶颈了，再决定要不要自己做。后来证明，这个决定至少帮我省掉了六周时间。

1.2 先复用的判断标准：一条“通用/专用”分界线

很多人问我，复用到底怎么划边界？我当时给自己画了一条线：一个能力如果换家公司、换个行业还是同样的玩法，那就是通用基础设施，直接复用；一旦跟公司业务、行业知识、内部流程绑死，那就是专用层，必须自己搭。这条线听起来简单，但做起来很招人反复琢磨，因为很多能力是“看起来通用、用起来专用”。

举几个例子。向量库本身是通用的，但你的索引结构、分段策略、元数据过滤规则完全取决于业务文档长什么样，所以我会把向量库选型当复用，把分段与索引设计当自研。模型调用是通用的，但你的异常重试、提示词模板版本、可观测性标记必须自己规范。用装修做类比：复用的是水电管线、大楼结构这些基础工程，而墙面颜色、家具布置、动线设计必须自己做，否则每个项目都长得一模一样，那就不叫业务了。

1.3 复用不是偷懒，而是给关键问题留时间

复用最大的价值不是省钱，而是随时把“未知”变成“已知”。框架有多少 bug、社区有多少解法，这些是确定的；而业务路线选错了、评测集漏了关键场景，这些才是真正让项目报废的风险。基础设施复用掉，省出来的时间全部投给业务不确定性的消解。

项目进入第四周的时候，我们第一天就发现工具调用链路上，一个老的审批接口返回格式和预期完全不符，于是花了大半天改接口适配。假如同时还要维护自研的编排框架，这种业务适配可能要排到下周，进度表直接崩。所以“先复用”表面上是选择题，本质上是给自己留出容错时间。九周能上线，不是因为运气好，而是因为前几周把最不确定的业务问题提前暴露了。

2. Agent 基础设施选型：框架、模型与存储怎么搭

2.1 Agent 框架怎么选：LangChain、Dify、CrewAI 的取舍

一提到框架，社区马上会分成几派：有人嫌 LangChain 太重，有人说 Dify 太玩具。我的态度是别被框架的名字绑架，先看你的 Agent 要跑多长时间、要接多复杂的业务。我们第二个 Agent 要做的事是：根据内部需求描述，自动去多个系统查资料、填表单、生成结论，还要支持多轮确认。这种场景需要强可控的编排，低代码平台的插件化模型满足不了接内部系统的一系列定制，纯自研又太慢。

最后我的选择是：用 LangGraph 做状态机级别的编排，但只当它是“状态管理基础设施”，不把它当万能库。工具调用、模型接入、向量检索、记忆这些组件各自独立，通过统一接口接入。选择 LangGraph 的具体原因是它把 Agent 变成了一个有向状态图：每个工具调用是一个节点，模型决策是节点间的跳转条件。这一点很直白，出问题时可以直接看路径。复用现成框架不是把整个黑盒子拿过来，而是把它当一块积木，拼进我们自己定的流程里。

顺带说一句 Agent harness。所谓 harness，通俗讲就是“驾驭 Agent 的运行时环境”，包括上下文组装、工具注册、生命周期管理这些外围能力。这部分跟业务弱相关，是最适合复用的地方。我们直接用框架自带的 harness 机制，省去了从零管理 Agent 会话的麻烦。

2.2 模型接入层与缓存复用：别自己写 SDK 封装

模型接入层是最容易让人手痒自己写的部分，因为写一个“调用大模型”的函数半小时就搞定。但这个认知是错的。真实环境里你要处理的不是“怎么调模型”，而是“怎么稳定地、可控地调模型”：超时策略、流式返回、重试退避、限流排队、预算控制、多模型切换、请求日志、敏感信息脱敏。这一整套写下来，熟练工程师也要一周起步，而且稳定性大概率不如现成方案。

我们当时直接复用了团队内部已有的模型网关，上面已经接好兼容接口和几个国产模型，切模型只需改一个配置。缓存层面做了两层：第一层是请求级的完全匹配缓存，相同请求直接返回；第二层是向量语义缓存，类似问题不再调模型。这里一个关键教训是缓存 key 里千万不能带动态时间戳，我见过有人把当前日期拼进提示词，结果缓存命中率直接跌破 10%，成本一点没省。

说人话就是：别自己写 SDK 封装。如果公司里没有现成网关，也可以优先选开源方案做统一接入，而不是从零造一个。复用之后，你才有时间做真正重要的事情——把工具返回的内容规整成 Agent 能稳定消化的结构化数据。

2.3 记忆与向量库：RAG 这块的复用收益最大

记忆是我在第一个 Agent 上被坑得最惨的地方，所以第二个项目里我专门把“短期上下文管理”和“长期记忆检索”分开。短期上下文直接复用框架的消息窗口机制；长期记忆则做成一个记忆服务：每次对话结束后，把关键信息提取成结构化条目，写入向量库；下次对话开始时，根据当前问题做一次检索，只把相关片段放回上下文。这个机制能稳定记住用户偏好、项目背景和之前的结论。

向量库选型我们没折腾，直接复用了团队已有的 PostgreSQL，再加 pgvector 插件。为什么不是专门的向量数据库？因为我们当时的文档量大概几十万条切片，单机 PostgreSQL 完全扛得住，而运维一个新组件的时间成本，在当时根本不是九周能覆盖的。等数据量真到千万条级别，再考虑迁移也不迟。这条经验套到类似项目里同样适用：基础设施复用的第一原则，是别轻易引入一个需要专人运维的新组件。

需要提醒的是，RAG 的检索效果不完全取决于向量库。分段策略、嵌入模型、是否做重排序，这些和业务文档强相关，必须自己调。我们第二周就在这个部分反复试：把内部文档按章节分段，加了元数据过滤之后，召回准确率才拉到了能用的水平。这就是典型的“复用基础设施 + 自研策略”组合。

3. 九周实操复盘：从搭骨架到上线的关键动作

3.1 前三周：搭一个最小可运行骨架

第一周基本不怎么写业务代码。我先把仓库、CI、开发环境全部跑在现成模板上——公司内部有现成的 Python 服务脚手架，带好了日志、配置、健康检查、服务发现。这里也说一句：复用的范围不仅仅是 Agent 框架，还包括工程脚手架。很多团队觉得开发 Agent 需要从零搭工程，其实完全没必要。

第二周的核心目标是让整条链路转起来。我们在 LangGraph 里定义了一个很粗的三节点图：入口节点接收用户输入，中间节点做大模型推理和工具调度，末尾节点把结果回给用户。模型接入直接用了网关的兼容接口，工具则先接了三个只读接口。这时候系统已经能跑，但效果很糙，离可用差得远。

第三周开始加记忆和 RAG。上下文策略先做成每轮对话结束把关键信息抽成 JSON 存入记忆库；知识库则先把文档导入，测试不同分段策略。这一周结束的时候，我们实际上已经有一个能演示的最小可用版本。前三周的关键动作，是让整个链路在简单场景下先跑通，而不是追求效果。

3.2 中间三周：接入业务数据与工具能力

中间三周是九周里最“累但成就感最强”的阶段。查询类工具接入相对简单，无非是把内部 API 封装成 function calling 能理解的 schema，映射到 Agent 工具注册表。这里有一个特别多人忽略的细节：工具描述一定要写人话，把边界条件和返回值样例写进去。模型不是人，你得告诉它这个工具什么时候能用、返回结构长什么样。我们第一个版本工具描述写得潦草，模型经常在不需要查询的时候乱调用，还拿返回结果一顿硬编。后来把每条工具描述重写了一遍，调用准确率立刻看着涨。

权限设计这一块，我的立场很明确：任何对系统有副作用的能力，都不能指望大模型自律。不管提示词里怎么写“未经确认不得执行”，模型总有被诱导绕过的概率。所以我们在工具网关层做了硬控制：读接口统一走只读凭证，写接口一律触发审批流，Agent 只能提交“申请意图”，由后端确认后才真正执行。这套做法没有用任何专属技术，就是借用了公司已有的审批基础设施和统一权限模型。

第五周到第六周做端到端联调。我们用真实业务场景一条条过，发现了很多前置条件没满足的情况，比如某个查询接口要求先初始化项目上下文。于是我们在工具层加了一个“先调用初始化接口再查询”的前置约束，在编排里体现为条件节点。这些模式，框架原生图结构支持得很好，全程没有改源码。

3.3 最后三周：评测、打磨、灰度和上线

最后三周没有新功能，核心只有两件事：让问题尽量变少、让问题能早被发现。

先说评测。我们建了一个约 120 条场景的评测集，来源不是凭空编的，而是从历史工单和需求文档里扒出来的：包含多轮追问、模糊表达、工具异常等典型情况。每个评测样本都配了期望结论和关键证据。自动化评测时，我们把 Agent 的回复和期望结论分别交给模型打分，并要求给出得分依据；每周冲刺完再人工抽 20 条确认，防止“机器骗机器”。打磨方向完全从评测结果里来：发现大量回答缺少关键数据，就去查是检索没召回还是工具没调到；发现幻觉，就去收紧系统提示词和工具描述。整个优化都是小步快跑，没有重构任何模块。

灰度上线按部门放量：第一周内部员工，第二周试点团队，通过后再全面切流。这里复用的是公司现有的灰度发布平台和统一监控看板。我们自己只额外补了两块 Agent 特有的监控指标：一是工具调用链路的成功率，二是单轮对话的 token 成本。这两块数据能直接告诉我们，Agent 被卡在哪儿了，以及模型是不是在无效绕圈。上线当天并非万事大吉，群里开始有人反馈回答慢，但因为有链路追踪，我们二十分钟内就定位到了是知识库检索阶段没有加并发限制，把数据库连接池调大之后恢复。

4. 复用过程中的深坑与排查实录

4.1 框架版本大坑：依赖冲突与 API 变动

第二个项目进行到第五周时，一天早上，我们的对话突然开始报错，整个 Agent 无法调用任何工具。排查后发现不是我们代码改了，而是某个依赖的小版本被自动升级脚本动了，新版把函数签名改掉了。这类问题在 Agent 项目里特别常见，因为框架生态迭代速度极快，今天能跑的代码，三个月后可能就跑不起来了。

处置策略是三条：第一，依赖全部锁版本，不要在自动化流程里用 latest；第二，框架升级必须单独排期，升级后跑一遍完整评测集再进行灰度；第三，如果某个上游库改动过于激进，在它外面封装一层薄薄的接口，把不稳定部分隔离起来。

这里多说一句：薄封装是复用基础设施最重要的护栏。当你决定复用一个库时，不要在业务代码里直接到处引用，而是先定义好项目需要的接口，再用适配器去接。底层框架换掉，业务代码不会爆炸。这是我在第一个项目里没做、第二个项目里做得最到位的一件事。

4.2 上下文管理与记忆过期：模型为什么会“精神分裂”

多轮对话超过十轮以后，模型突然不记得用户十分钟前说的要求，这是测试中遇到最多的情况。排查后通常有两个原因：一是上下文窗口被打满，早期关键信息被滚动截掉了；二是记忆条目写入了，但检索时没有考虑时效，把已经失效的信息当成事实。

解决方案是给记忆条目加元数据：时间戳、来源、置信度、有效期。检索时除了向量相似度，还做时间过滤和权重衰减。用户最近说过相反的偏好，就应当优先采纳新信息，并在记忆里标记旧条目为过期。这套逻辑一开始准备自己写，后来发现开源记忆方案已有元数据过滤能力，直接复用即可。复用的前提是你要清楚自己需要什么字段，否则很容易被现成方案的默认行为带偏。

4.3 工具调用的安全与成本失控：权限必须拦截在 Agent 之外

有一次灰度测试里，一个用户用自然语言连续让 Agent 查询大批量数据，结果因为没有提前加追踪，事后看成本涨得惊人。这不是模型问题，而是我们没有给工具调用设置速率和成本预算。后来我们在工具网关加了三层控制：第一层，按用户身份限制调用频率和最大返回条数；第二层，按会话限制总 token 预算，超过就强制结束并要求用户开启新会话；第三层，所有写操作必须走审批流。这个过程中没有改 Agent 编排代码，完全是在基础设施层做拦截。安全控制确实应该独立于 Agent 逻辑之外，不能依赖模型的自我约束。

4.4 常见问题速查表

排查 Agent 问题最有效的手段，是把 Agent 每一步写成事件日志：用户输入、模型决策、工具调用参数、工具返回摘要、记忆读写、最终回复。我当时直接在系统里开了 debug 模式，任何问题场景点开都能看到整条链路，而不是靠猜。这条经验比任何框架技巧都管用。

5. 哪些地方我后来还是自己写了：复用与自研的边界

5.1 评测集与回归测试：业务相关的没法复用

在整个项目里，最不能复用、也最值得投入自制力的，就是评测集。外部框架不会懂你所在行业的业务口径，更不知道什么样的回答算“正确”。建评测集的过程，就是跟业务方反复对齐需求的过程。我们当时从历史工单里抽了最具代表性的问题，人工标注期望回答和关键证据点，一共攒了 120 多条。

自动化评测时把两种方式结合：一部分场景用精确匹配，比如工具是否返回了正确的数值；一部分场景用模型给模型打分，并附带理由。这套评测脚本完全是自己写的，但它并不复杂——脚本加一份用例清单，就足够支撑九周迭代。不要一开始就想着做成平台化工具，先把最基础的跑起来。

5.2 领域提示词与业务知识沉淀

系统提示词、工具描述、知识库索引规则这些，直接决定 Agent 业务能力的天花板，天然属于专用资产。我们做了两件事：把所有提示词语料化、版本化，放在代码仓库里，每次修改都记录变更理由；同时把常用业务口径解释单独写成知识文档，让检索去取，而不是把知识硬塞进系统提示词。

提示词不是写一次就完，要持续迭代。每周开一小时的“提示词复盘会”，把线上问题样本拿出来逐条讨论，看是提示词问题、工具问题还是检索问题。这是项目质量能持续走高的原因。这些内容外部给不了你模板，必须从自己团队的业务里长出来。

5.3 日志、追踪与可观测性：复用得看得见才敢复用

复用基础设施的前提是可观测。如果不知道 Agent 每一步在干嘛，就很难判断是框架问题、模型问题、还是工具问题。我们直接复用了团队已有的日志采集和链路追踪系统，同时把模型的思考过程和工具调用输出作为结构化日志打点。

另外单独做了一张 token 成本统计表，按会话维度、用户维度聚合。这张表是运营和业务方最关心的数据。Agent 本质上是一个会持续消耗模型资源的系统，成本口径和传统接口完全不同，如果第一版没埋好这个指标，上线后会给运维和财务管理带来不少麻烦。可观测性做得越早，后期排查问题越省力。

6. 先复用这件事，我还会继续做下去

项目上线到现在，再回头看这九周，我最庆幸的不是用了多新的框架，而是把大量不确定性挡在了项目早期。做 Agent 最怕的不是框架不好用，而是你花三个月搭了一套自认很牛的地基，最后发现产品需求根本不是那样。先复用现成基础设施，等于把地基快速铺好，把时间留给业务验证。等业务验证成立、瓶颈真的出现在框架或基础设施层面，再动手自研，那一刻的投入性价比，远比一开始就造轮子要高。

最后再分享一个小建议：如果你正在启动一个 Agent 项目，不用先纠结具体框架，先把现成的基础设施列成一张清单，标清楚哪些直接复用、哪些必须自己做。这半小时，可能是整个项目里回报率最高的一步。第二个 Agent 能九周上线，靠的不是技术奇迹，而是把“先复用，再自己做”这句话真正落到了每一步决策里。