企业官网建设流程全解析

去年我们立项第二个 Agent 项目时，我直接跟老板说：这次先复用，再自己做，底层基础设施能不写就不写。第一个项目把我们坑惨了——当时整个团队追求全自研，从 Prompt 模板到工具协议、从状态机到重试策略全都要自己磨，八周过去交付物连内部试用都勉强，大量时间耗在模型偶尔输出畸形 JSON、工具调用频繁超时这类基础问题上。

第二个项目启动时我们换了一套打法：模型接口直接用现成的，Harness 拿社区成熟的来改，Skills 能挂现成技能就挂现成技能，自研只集中在业务逻辑和内部系统适配层。结果就是标题写的，九周上线，而且是灰度环境里真跑业务流量的那种上线。这篇文章是把那次复用的全过程摊开来讲，包括每一层到底复用了什么、为什么这么选、中途踩了哪些坑，以及如果你也要做第二个 Agent，哪些地方可以直接参考。

1. 为什么第二个 Agent，反而不该急着继续自研

很多人有个错觉：项目做得越多，自研比例应该越高。但至少对 Agent 项目，我的经验完全相反。第一个自研是为了摸清边界，第二个应该赶紧复用，因为你的业务壁垒根本不在那些基础设施上。这不是姿态问题，而是时间账。

1.1 第一个 Agent 留下的三笔"重复发明"的债

第一笔债是工具协议。当时我们觉得现成的工具调用方式不"优雅"，自己定义了一套类似 JSON-RPC 风格的协议，结果模型经常输出结构不规范的参数，我们硬写了三周解析器去兜底。后来才发现，现成生态里模型原生的函数调用机制已经非常成熟，对结构化参数的支持比我们自己设计得更好，根本不需要发明新协议。

第二笔债是"重写偏好"。团队遇到一个组件不顺手，第一反应不是去查社区里有没有更好用的，而是"我们自己写一个更强的"。结果新组件带来新坑，修完新坑又发现缺功能，循环往复。后来我们定了一条规矩：遇到问题，先花半小时调研生态里最活跃的替代品，而不是花半小时写第一行代码。

第三笔债是可观测性缺位。第一个项目上线后，没有 trace、没有 token 成本统计，出 bug 全靠肉眼翻日志。排查一个"某个用户的任务为什么卡住"的问题，要翻三个服务，最后发现是第三方接口静默超时。这些能力在现成的 Agent 基础设施里几乎都是标配，但我们一开始根本没考虑。

这三笔债让第一个项目至少多花了五周，而且没换来任何用户可见的价值。

1.2 先想清楚：你的壁垒到底在哪一层

复盘之后我们问了自己一个问题：这个 Agent 产品的护城河是什么？答案是业务数据、内部流程和对垂直场景的理解，绝不是"我们自己写了一套 Prompt 框架"。

所以我后来一直用三个问题来判断每一层该复用还是自研：

1. 这一层是否直接服务最终用户价值？
2. 开源或商业方案是否已经足够成熟？
3. 如果底层将来升级，替换成本高不高？

三个答案里只要有一个是"否"，就老老实实复用。尤其是第二问，很多人会高估自研方案的成熟度——自己写的东西跑通三个 case 就觉得"够用"，但上线后要面对的并发、异常、可观测性问题，开源项目早就替你踩完了。

1.3 这套打法适合谁，不适合谁

"先复用，再自作"不是普适真理。适合的场景很明确：业务价值还没验证、团队规模小、交付时限硬、成本敏感。第二个 Agent 恰好全中——我们不是要做研究型项目，而是要快速验证一个业务假设。

反过来，如果你创业卖的就是 Agent 底层引擎，或者你需要从模型行为层做深度改造，又或者数据主权有极端要求，那该花的自研时间一分都省不掉。想清楚自己属于哪类团队，比选什么框架重要得多。

2. Agent Harness：这是整辆车的底盘，别自己拿钢管焊

很多人把 LangChain、Dify 当成 Agent 开发的全部，这个理解不完整。真正撑起生产级 Agent 的是一个叫 Harness 的运行时外壳——它把 LLM、工具、记忆、安全边界绑在一起，管着 Agent 从启动到退出的整个生命周期。为什么说复用基础设施首先得选好 Harness？因为没有它，后面所有复用都没有稳定的挂载点。

2.1 Harness 到底管什么

Harness 的核心职责可以拆成四块：

• 生命周期管理：Agent 从接收到任务，到规划、调用工具、等待用户确认、完成、异常退出，这个状态机如果自己写，要处理的边界情况远比你想象的多——并发任务、超时恢复、幂等重入。
• 循环控制：模型在复杂任务里偶尔会陷入死循环，Harness 要用最大步数、最大 token、单步超时这些硬护栏兜底。
• 工具注入与 Schema 校验：所有工具统一注册，模型返回的调用参数先过一层校验再真正执行，避免脏参数直接打到业务接口上。
• 可观测性：每个环节的 trace、token 消耗、工具调用记录，都应该是开箱即用的能力。

用个生活化类比：编排框架像导航软件，告诉你路线怎么走；Harness 更像发动机管理系统，管的是每一个动作能不能稳定发生。你可以换路线，但发动机一定不能熄火。

2.2 Harness 和编排框架，是两回事

这是最容易混淆的地方。编排框架关心任务如何拆解和流转——哪个子任务先做、依赖关系是什么、怎么并行；Harness 关心的是 Agent 这个进程本身如何被启动、被监控、被安全地暂停和恢复。

第一个项目我们就是栽在这——把编排当成了全部，忽略了运行壳，结果一上线就发现超时没有统一处理、工具调用没有熔断、并发一高就乱。后来看业界关于 Agent Harness 的深度拆解文章，才意识到生产级 Agent 真正难的部分，全在那些"看起来不起眼"的运行时细节里。

2.3 落地选型时，我们只盯四个指标

当时我们挑 Harness 时列了一张清单，只看四个维度：

• 社区活跃度：最近一个月有没有持续提交，有多少公司在生产环境里用。
• 生命周期状态机是否完整：是不是覆盖了中断、恢复、失败转移这类非理想路径。
• 扩展点是否够：能否接入内部系统认证、能否把自有 trace 接到统一监控。
• 开源协议和文档质量：协议是否友好、文档能不能让新人在两天内跑通。

选型这件事我建议不要拍脑袋。我们第一周没急着写代码，花了两天把选型文档写出来，把候选方案的优缺点列清楚再动手。这看似"浪费"的两天，后来省掉了至少两周返工——因为方案一旦定下来，后面所有适配工作都沿着这个边界走。

3. Skills 机制：把能力做成"即插即用"的模块

如果说 Harness 是底盘，那 Skills 约等于给 Agent 装上了一排即插即用的功能模组。第二个 Agent 能九周上线，Skills 的功劳至少占三成。它解决的问题是：不再需要把每个能力硬编码进主流程，而是以"说明书 + 工具 + 验收用例"的形式注册给模型，模型读懂了说明，自己就能决定什么时候调用。

3.1 一个 Skill 的四个组成部分

我理解 Skill 的方式是把它想成新员工工位抽屉里的工具说明书。Agent 需要一个技能时，会先看到一张描述卡，上面写着：这个技能解决什么问题、什么条件下该用、参数长什么样、大概会产生多少开销。

具体拆开，一个 Skill 就是四样东西的组合：

• 触发说明：用自然语言写清楚"什么时候该用这个技能"，这是模型做决策的主要依据。
• 参数 Schema：一段 JSON Schema，约束输入的字段、类型和取值范围。
• 执行函数：真正去调用某个工具或 API 的那段代码。
• 验收用例：一组输入输出样例，用来做回归测试，防止后面改动破坏了原有能力。

关于 Agent Skills，行业里有一篇讲得很透的原理解析，核心观点是 Skill 的形态应该以自然语言描述为主、以代码为辅。我们实践下来完全赞同——模型是靠"阅读理解"来触发技能的，说明文字的质量直接决定调用准确率。

3.2 我们直接复用了三套现成技能

第一个是网页保存成 Markdown。以前我们得自己写爬虫加 HTML 解析器，现在社区里成熟的 Skill 直接挂载，适配了一下内部存储就上线了。第二个是表格解析，Excel、CSV 这类文件的读取和结构化处理，现成工具包直接接入。第三个是本地文件检索，在指定目录里按语义找文件，还自带了权限边界检查。

这三套技能如果全部从零开始，每套至少一周，加起来三周打底。但因为我们选了有现成 Skills 生态的 Harness，这三块基本是"适配 + 测试"的活，一周内全部搞定。这让我深刻意识到：能力模块层也是基础设施，而且是最容易被低估的一类。

3.3 写新 Skill 时，也别从零开始

团队里第一次写自家 Skill 的同事，上来就想把执行函数设计得"无比通用"。我直接把他按住，让他从仓库里复制一份结构最接近的现成 Skill，只改三样东西：触发说明、参数 Schema、内部调用逻辑。结果他一天半就把新 Skill 合入了主干，而通用方案讨论了三天还没定稿。

这段经历给我的经验是：Skill 的迭代重点应该放在说明文字上，而不是代码结构。我们后来每次发版，改得最多的都是触发说明——比如最初写"当用户要求整理网页时使用"，后来发现模型也会在用户只是问网页里某句话时触发，于是补了一条反面约束："当用户只是询问网页内容时不要使用，直接回答即可"。正面例子加反面例子，模型的理解一下就准了。

4. 模型层和记忆层：我们到底复用了什么

模型层我们干了一件让不少人意外的事——除了砍掉领域微调的计划，其余几乎全部走"现成 API + 配置"路线。不做微调的理由很直白：九周交付的项目，既没有时间也没有足够数据做一次靠谱的微调；而现成模型的能力已经足够覆盖我们的业务场景，差的那点领域感，用提示词和 Skill 说明就补上了。

4.1 函数调用：复用平台自带的"手"

第一层复用是模型平台自带的函数调用（Function Calling）机制。模型在需要调用工具时，会直接输出规范化的工具调用参数，我们再把这些参数转发给对应 Skill 的执行函数。这套机制比当年自己解析自然语言输出不知道高到哪里去了——省掉了解析器、兜底对话逻辑、错配处理这些所有脏活。

实际体验下来，函数调用最舒服的一点是参数校验前置。模型输出的工具调用参数本身就是结构化 JSON，我们在 Harness 层做一层 Schema 校验，不合法就直接让模型重新生成，而不是像以前那样等执行阶段才发现参数错了。这让工具调用成功率肉眼可见地上升，至少稳定在百分之九十八以上。

4.2 记忆三层方案，全用成熟存储

记忆是 Agent 体验的关键，但我们没有发明任何新东西，直接按三层模型搭：

• 短期记忆：放在上下文窗口里，靠提示词压缩和摘要控制 token 增长。
• 工作记忆：用 Redis 存会话中间状态，比如当前执行到哪一步、哪些结果还没写入。
• 长期记忆：向量数据库存历史事实和用户偏好。

特别说一下长期记忆的选型。我们量化数据量后发现，历史事实大概几十万条量级，完全不需要独立部署一套大规模向量引擎。最后选了 PostgreSQL 加 PGVector 插件，直接复用团队已经在运维的数据库实例，省掉了一个全新组件的部署、监控和备份成本。这条建议送给大多数中小团队——别一听 RAG 就上一个新数据库，先看看你现有的存储能不能顶上。

4.3 记忆和上下文相关的三个坑

有些坑是跑起来之后才显形的。第一个是不该把记忆全量塞进上下文——不是钱的问题，是效果问题。上下文超过一定长度，模型的注意力会被稀释，反而忽略当前用户真正想要的东西。所以我们做了两级摘要：用户离开对话超过一段时间，就把中期细节压缩成长线记忆。

第二个坑是向量召回不加阈值。刚开始召回时，旧记忆里一些无关片段会经常蹦出来干扰回答，后来加了相关度阈值和时间衰减权重，情况立刻好转。第三个坑是换模型要跑回归——提示词和 Skill 说明在不同模型上的理解能力不太一样，换基座模型不能只看离线指标，一定得拿真实用例集过一遍再切换。

5. 编排框架四选一：AI 助手开发到底该站哪个队

写到这里，肯定有人会问：现在不是有 LangChain、Dify、CrewAI 这些现成框架吗，为什么还要自己盘一套 Harness？答案是：这些框架本身就是一种"基础设施复用"，我们当然用了，只是把每个工具放在最合适的位置上。毕竟框架不是万能药，重点是拿它解什么题。

5.1 四个方向的复用价值对照

我把当时认真考虑过的路线列了一张表，方便后面的团队直接参考：

5.2 我们的判断标准：能力密度与逃逸成本

挑框架不能只看 Star 数，我们当时给自己定了两个判断标准。

第一个叫"基础设施能力密度"：这个组件能帮我少写多少代码？它是否默认提供了重试、缓存、可观测性、批量调度这些生产必需的东西？密度越高，复用价值越大。

第二个叫"逃逸成本"：如果它将来不合适，抽离方案的代价高不高？有些框架深度绑定，你所有业务代码都长在它的抽象上，一旦版本大升级就是二次开发；有些框架只做薄薄一层，抽离时基本无痛。我们的倾向是宁可自己多写一百行胶水代码，也不要被一个巨型抽象绑死。

5.3 我们的最终组装方式

验证环境我们用了 Dify——它可以让业务方在一周内就看到交互效果，可视化流程和调试面板极大降低了沟通成本，需求对齐阶段特别管用。但生产环境我们没把 Dify 直接搬上去，而是用自选 Harness 加轻量胶水代码，内部工具适配器直接注入，LangChain 只是作为设计参考，借鉴了少数几个模式。

这个组合的好处是：验证阶段享受了 Dify 的开箱即用，生产阶段避开了平台绑定，真正把"现成的东西"和"自己的差异化"之间划出了一条清晰边界。说白了，Dify 帮我们把业务方喂饱，Harness 帮我们把服务器扛住，两者各司其职。

6. 九周上线时间线：我们每周具体在干嘛

这一章把时间线完全摊开。九周听着玄，拆开其实就是：两周收口、两周搭壳、两周接能力、两周调质量、一周交付。每一步都有具体的交付物，而不是泛泛的"推进中"。

6.1 第 1-2 周：接口与边界，只做四件事

第一周我们没有写任何业务代码，全部精力花在四件事上：定义工具调用的 JSON Schema、确定模型适配层的接口、建好数据库表结构、画清楚生命周期状态机。这段看起来"不写代码"的工作，其实最省后面时间——因为所有复用组件都要挂在这些边界上，边界不稳，后面全得返工。

踩过一个坑：一开始想做一套"万能工具协议"，想支持未来所有可能的工具，被同事一盆冷水泼醒——我们连未来有哪些工具都不知道，怎么定义通用协议？最后老老实实先只支持三个高频工具，其他工具等需求明确了再加。这个"砍边界"的决定，让第一周顺利收口。

6.2 第 3-4 周：Harness 骨架搭起来

这两周把选好的 Harness 跑通，接入内部系统认证和第一批工具适配器。因为 Harness 是现成的，我们主要工作是配置和适配，而不是从零写状态机。第三周结束时就跑通了一个最简单的"问答 + 单工具调用"链路。

这里的教训是别贪全。我们一开始想让所有内部工具一次性接入，结果集成测试直接炸锅——十几个工具各有各的鉴权方式、返回格式、超时时间，根本不是一个星期能磨完的。后来改成按业务优先级分批接入，每批一个小迭代，节奏立刻顺了。

6.3 第 5-6 周：Skills 与工具，接通主干能力

这两周是复制模板写 Skill、做端到端调试的高峰期。我们复用了三套现成 Skill，又自己写了两个内部专用的，前面说的"复制最近结构再改"的方法就是这时候定下来的。每个 Skill 合入前都要跑验收用例，保证改动不会破坏已有能力。

这个阶段最大的坑是工具返回结果太大。有一次某个内部接口返回了几百行 JSON，直接吃掉了上万 token，一次任务还没开始就把上下文预算耗完了。后来我们统一给工具输出加了字段裁剪、分页返回和摘要处理三道工序，token 消耗立刻降下来，模型也能更精准地找到自己需要的信息。

6.4 第 7-8 周：记忆与评测，把质量焊死

向量库接入是在第七周完成的，毕竟选了 PGVector，部署和配置都很轻。真正花时间的是搭建评测体系。我们整理了一批业务场景用例，把"任务完成率"当成唯一指标的毛病也改了，增加到四个维度：工具调用成功率、平均步数、token 成本、幻觉率。

评测集要特别说一句：70% 以上的用例设计成怪问题、反问题、模糊需求。正常的 happy path 谁都跑得通，真正的质量差异全在边界场景里。比如用户中途反悔、用户给了互相矛盾的要求、用户要求调用一个权限外的工具，这些才是评测的重点。

6.5 第 9 周：灰度上线，以及一点反思

第九周做的事比较收敛：小范围灰度、可回滚方案、盯着 trace 看真实用户的行为模式。灰度期间果然发现一个场景化问题——真实用户并不会像测试集那样规规矩矩说话，口语化表达和少字段的诉求比预想得多，但因为 Skill 触发说明写得足够清楚，模型大多数时候都能正确引导用户补充信息。

回头看这九周，如果要我总结一个最大的教训，那就是：第一周如果不坚持砍掉"自研工具协议"的执念，后面根本不用这么顺。很多时间看起来是省在了 Skills、省在了 Harness，其实最根本的是省在了"想清楚哪里该踩在别人的肩膀上"。

两个 Agent 项目走完，我最大的感受是：决定一个 Agent 项目多少周能交付的，往往不是模型效果本身，而是你愿意在多大程度上复用现成基础设施。第一次我们年轻气盛，什么都想自己造，输得很惨；第二次我们学会了站在巨人肩膀上，赢得很踏实。

最后分享一个内部小原则：每次想自己造轮子之前，先问一句——如果这个组件是开源的，作为维护者我会不会在评审时拒绝它？如果答案是会，那就老实复用吧。把省下来的精力，留给真正只属于你产品的那个差异点。