企业官网建设流程全解析

1. 为什么我要给 Agent 单独做一个网站

先说结论：这个网站不是给人看的，是给 Agent 看的。更准确地说，是给那些需要调用外部能力、需要稳定获取结构化信息、需要一套可复用技能库的智能体系统看的。

过去大半年，我一直在折腾各种 Agent 项目。从最简单的任务编排，到稍微复杂一点的多工具协同，再到需要长期记忆和状态管理的场景，几乎每个环节都踩过坑。踩到最后我发现，大部分问题根本不是模型不够聪明，而是 Agent 在需要外部信息或能力的时候，拿到的内容太“脏”了。网页是给人看的，HTML 里塞满了导航、广告、样式、脚本，Agent 去解析这些东西，就像让一个刚学会认字的人去读一份排版混乱的报纸，能读懂才怪。

所以我做了一个决定：给 Agent 专门建一个网站。这个网站上的每一个页面、每一个接口、每一段内容，都是为机器消费而设计的。它不追求视觉上的花哨，只追求结构上的清晰、语义上的明确、调用上的稳定。同时，我还把常用的能力封装成了 skills，让 Agent 可以直接“学会”怎么用，而不是每次都要从头教。

这个项目解决的核心问题有三个。第一，Agent 获取外部信息时，信噪比太低，导致推理不稳定。第二，不同 Agent 之间能力无法复用，每个项目都要重新造轮子。第三，缺乏一个统一的、可版本化的技能注册与发现机制。适合谁来参考？如果你正在做 Agent 相关的开发，或者你手头有一堆工具想标准化地暴露给智能体使用，又或者你单纯想了解怎么让 AI 系统更可靠，那这篇内容应该能给你一些可以直接抄作业的思路。

我先把整体设计思路讲清楚，然后再拆细节。因为如果不理解为什么这么设计，直接看代码或配置，很容易觉得“这不就是把 API 文档换了个形式吗”。实际上完全不是。

2. 整体架构设计与核心思路拆解

2.1 从“人读网页”到“机读接口”的思维转变

传统网站的设计目标是人。人有视觉系统，能快速跳过不相关的内容，能根据排版判断信息层级，能容忍一定程度的模糊和冗余。但 Agent 不行。Agent 的“阅读”本质上是文本解析和语义提取，它没有视觉注意力机制，也没有常识性的版面理解能力。你给它一个满是导航栏和侧边栏的页面，它很可能把“登录”“注册”“关于我们”当成核心内容一起塞进上下文，然后推理出一堆莫名其妙的结果。

所以这个网站的第一个设计原则就是：每个 URL 只返回一件事，而且只返回这件事的完整信息。没有全局导航，没有推荐阅读，没有“相关文章”。Agent 请求一个技能描述，返回的就是这个技能的完整 JSON Schema；Agent 请求一个数据查询，返回的就是干净的结构化数据。所有人类需要的辅助信息，全部剥离。

这个原则听起来简单，但执行起来需要克制。因为你会忍不住想加一个“首页”，想加一个“文档目录”，想加一个“搜索功能”。这些对人有用，对 Agent 全是干扰。我的做法是，所有面向人的入口统一放在一个独立的子路径下，Agent 默认访问的根路径只返回一个机器可读的能力清单。

2.2 为什么选择“网站 + Skills”而不是纯 API 网关

有人可能会问，你直接做一个 API 网关不就行了吗，为什么要叫“网站”？这里有个关键区别。API 网关通常只负责转发和鉴权，它不负责“解释”。Agent 拿到一个 API 端点，它不知道这个端点是干什么的，需要什么参数，返回什么结构，除非你额外提供文档。而文档又是给人看的，Agent 读起来依然费劲。

我做的这个网站，本质上是一个自描述的能力集合。每个技能不仅可以通过 HTTP 调用，还自带一份机器可读的说明书。这份说明书不是 Markdown 写的，而是用 JSON Schema 和自然语言混合描述的。Agent 可以先拉取技能列表，然后按需拉取某个技能的详细定义，最后再发起调用。整个过程不需要人类介入，也不需要预先在 Agent 的提示词里硬编码任何工具描述。

另一个原因是版本管理。纯 API 网关很难做细粒度的版本控制，而网站形式天然支持路径版本化。比如/skills/v1/weather和/skills/v2/weather可以共存，Agent 可以根据自己的能力选择调用哪个版本。这对于长期维护的 Agent 系统来说非常重要，因为你不希望升级一个技能导致所有老 Agent 全部失效。

2.3 核心模块划分与数据流

整个系统我分成了四个核心模块。第一个是技能注册中心，负责管理所有技能的元数据、版本、依赖关系和调用统计。第二个是技能执行引擎，负责实际执行技能逻辑，处理输入校验、错误捕获和结果格式化。第三个是机器可读文档生成器，它从技能定义中自动生成 Agent 可消费的描述文件。第四个是调用日志与反馈回路，记录每次调用的上下文和结果，用于后续优化技能描述和排查问题。

数据流是这样的：Agent 首先请求/skills获取可用技能列表，这个列表里包含每个技能的 ID、简要描述和版本号。然后 Agent 根据任务需要，请求/skills/{id}获取该技能的完整定义，包括输入参数 Schema、输出格式、调用示例和注意事项。接着 Agent 构造请求，调用/skills/{id}/invoke执行技能。执行引擎会校验输入，调用底层实现，把结果按照预定义格式返回。同时，调用日志会记录这次交互的完整链路，包括 Agent 的原始请求、校验结果、执行耗时和返回内容。

这个数据流的关键在于，Agent 不需要任何先验知识就能发现和使用技能。它只需要知道根路径，剩下的全部可以通过自描述文件推导出来。这大大降低了 Agent 系统的耦合度。

3. 核心细节解析与实操要点

3.1 技能描述文件到底该怎么写

这是整个项目里最花心思的部分。技能描述文件是 Agent 理解技能的唯一入口，写得好不好直接决定了 Agent 能不能用对。我试过很多种格式，最后稳定下来的结构包含以下几个字段。

首先是name和description。name是机器标识，用蛇形命名，比如get_weather_forecast。description是一段自然语言，但这段自然语言不是写给人看的，是写给模型看的。所以它必须包含三个要素：这个技能做什么、什么时候该用、什么时候不该用。比如“获取指定城市未来三天的天气预报。当用户询问天气、气温、降水概率时使用。不适用于历史天气查询或气候趋势分析。”这样模型在规划任务时，就能准确判断是否该调用这个技能。

然后是input_schema。我用的是 JSON Schema 的一个子集，但做了一些针对 Agent 的优化。比如每个参数除了类型和描述，还必须包含examples字段，给出至少一个典型值。这是因为模型在生成参数时，示例比描述更有指导性。另外，对于枚举类型的参数，我会把每个可选值的含义也写清楚，而不是只给一个值列表。

还有一个容易被忽略的字段是side_effects。这个字段用来声明技能是否有副作用，比如是否会写入数据、是否会发送通知、是否会消耗外部配额。Agent 在规划多步任务时，需要知道哪些步骤是不可逆的，这样才能合理安排执行顺序。我见过太多 Agent 因为不知道某个操作有副作用，导致重复执行或者顺序错乱。

最后是error_codes。每个技能定义里都有一张错误码表，列出可能出现的错误、错误含义和建议的处理方式。Agent 拿到错误码后，可以根据建议决定是重试、换参数还是放弃。这比让模型去猜“500 是什么意思”要可靠得多。

3.2 输入校验的边界与容错策略

Agent 生成的参数经常是“差不多对”的。比如它可能把日期写成“明天”而不是“2025-06-15”，可能把城市名写成“北京市”而不是“北京”，可能把数字写成字符串。如果校验太严格，Agent 会频繁失败；如果太宽松，底层实现又会出错。我的策略是分层校验。

第一层是类型校验，这个必须严格。字符串就是字符串，数字就是数字，布尔就是布尔。类型不对直接返回错误，并附上正确的类型示例。第二层是格式校验，这个可以适度宽松。比如日期字段，我接受 ISO 格式、常见中文日期格式和相对日期表达，然后在执行引擎里统一转换成标准格式。第三层是语义校验，这个放在技能实现内部。比如城市名，我先用模糊匹配找到最可能的城市，如果匹配度低于阈值再返回错误。

这里有个实操心得：永远不要相信 Agent 会按照你期望的格式传参。我在早期版本里要求日期必须是YYYY-MM-DD，结果 Agent 经常传2025/6/15或者June 15, 2025。后来我干脆在描述文件里把examples写成多种格式，并在校验层做归一化，失败率立刻降下来了。

另一个技巧是给参数设置合理的默认值。Agent 在不确定的时候，倾向于省略参数而不是瞎猜。如果你给一个合理的默认值，Agent 的调用成功率会高很多。但默认值不能乱给，必须是那种“即使 Agent 不提供，结果也基本可用”的值。

3.3 技能执行引擎的隔离与超时控制

技能执行引擎是整个系统里最需要稳定的部分。因为 Agent 可能会在短时间内发起大量调用，也可能调用一些耗时较长的技能。如果引擎本身不稳定，整个 Agent 系统就会跟着崩。

我的做法是每个技能运行在独立的执行上下文中，有独立的内存限制和超时设置。超时时间不是拍脑袋定的，而是根据技能的历史执行时间分布来动态调整。具体来说，我会记录每个技能最近 1000 次调用的耗时，取 P95 作为基准超时时间，再乘以一个安全系数。这样既能避免个别慢请求拖垮系统，又不会因为超时太短导致正常请求被误杀。

隔离方面，我用的是进程级别的隔离，而不是线程。因为很多技能会调用外部服务或者执行计算密集型任务，线程隔离不够彻底。进程隔离虽然开销大一点，但稳定性好很多。每个技能进程启动时会加载自己的依赖，执行完就销毁，不会互相影响。

还有一个细节是并发控制。有些技能有外部配额限制，比如每天只能调用 1000 次。如果 Agent 并发调用，很容易超限。我在执行引擎里加了一个令牌桶算法，每个技能可以配置自己的速率限制。当 Agent 调用超过限制时，返回一个明确的“配额不足”错误，并附带建议的重试时间。这样 Agent 就知道该等待而不是疯狂重试。

4. 实操过程与核心环节实现

4.1 从零搭建技能注册中心的完整步骤

第一步是定义技能的数据模型。我用的是关系型数据库，因为技能之间的依赖关系和版本管理用关系模型表达最自然。核心表有三张：skills表存技能的基本信息，skill_versions表存每个版本的详细定义，skill_dependencies表存技能之间的依赖关系。

skills表的关键字段包括id、name、current_version、status和created_at。status用来控制技能是否对 Agent 可见，比如有些技能还在测试阶段，可以设为beta，只对特定 Agent 开放。

skill_versions表存的是每个版本的完整 JSON 定义，包括输入输出 Schema、描述、示例和错误码。每次修改技能定义，不是直接更新，而是插入一条新版本记录，然后把skills表的current_version指向新版本。这样历史版本永远可查，Agent 也可以指定调用某个历史版本。

skill_dependencies表用来记录技能之间的依赖。比如技能 A 在执行过程中需要调用技能 B，那就在这张表里记一条 A 依赖 B 的记录。这样在技能 B 升级或下线时，系统可以自动通知所有依赖它的技能负责人。

第二步是实现技能注册接口。这个接口不是给 Agent 用的，是给开发者用的。开发者提交一个技能定义 JSON，系统校验格式、检查依赖、生成版本号，然后写入数据库。校验环节会检查很多细节，比如input_schema是否符合规范、examples是否覆盖所有必填参数、error_codes是否完整。我甚至加了一个检查，确保每个技能的description里都包含了“什么时候不该用”的说明，因为这是 Agent 最容易出错的地方。

第三步是实现技能发现接口。Agent 访问/skills时，系统返回所有status为active的技能列表，每个技能只返回id、name、description和current_version。这个列表要尽量精简，因为 Agent 可能会一次性拉取全部技能，如果每个技能都返回完整定义，上下文会爆炸。Agent 需要详细信息时，再单独请求/skills/{id}。

4.2 机器可读文档的自动生成与缓存策略

机器可读文档不是手写的，是从技能定义自动生成的。生成过程分两步：第一步是把数据库里的 JSON 定义转换成 Agent 友好的格式，第二步是加上一些运行时信息，比如当前可用性、平均响应时间、最近错误率。

转换过程中有几个关键处理。一是把 JSON Schema 里的技术术语翻译成自然语言。比如type: "string"会变成“这是一个字符串参数”，enum: ["a", "b"]会变成“可选值为 a 或 b”。这样模型读起来更顺畅。二是把examples展开成完整的调用示例，包括请求体和预期响应。模型对示例的模仿能力很强，给一个完整的例子比给一堆描述更有效。

缓存策略上，我用的是两级缓存。第一级是内存缓存，存最近生成的文档，有效期 5 分钟。第二级是 CDN 缓存，因为文档内容不经常变，可以缓存更长时间。但有个细节：当技能定义更新时，必须主动清除缓存，否则 Agent 会拿到旧文档。我在技能注册接口里加了一个缓存失效的钩子，每次更新技能定义都会触发。

还有一个优化是按需生成。不是所有技能都需要完整的机器可读文档。有些技能非常简单，参数就一两个，Agent 看个简要描述就能用。对于这类技能，我只生成精简版文档，减少上下文占用。判断标准是参数数量和错误码数量，超过阈值的才生成完整版。

4.3 调用日志与反馈回路的落地细节

调用日志不是简单记个流水账，而是要能回答三个问题：Agent 为什么调用这个技能、调用结果是否符合预期、如果不符合预期问题出在哪。

为了回答第一个问题，我在日志里记录了 Agent 的原始请求上下文，包括它当时正在执行的任务描述和已经完成的步骤。这样当出现异常调用时，我可以回溯 Agent 的决策链路，判断是技能描述有歧义，还是 Agent 的规划逻辑有问题。

为了回答第二个问题，我在日志里记录了执行结果的摘要和 Agent 的后续行为。如果 Agent 拿到结果后立刻重试同一个技能，说明结果可能不符合预期。如果 Agent 拿到结果后继续执行下一步，说明结果基本可用。这个信号虽然粗糙，但非常有效。

为了回答第三个问题，我把错误日志和技能定义关联起来。如果某个技能频繁出现同一种错误，我会去检查它的描述文件是不是有歧义，或者输入校验是不是太严格。我甚至做了一个简单的聚类分析，把相似的错误请求聚在一起，看看是不是某类参数组合特别容易出错。

反馈回路的闭环是这样的：日志分析发现某个技能的问题，我修改技能定义或实现，发布新版本，然后观察新版本的错误率是否下降。如果下降，说明修复有效；如果没下降，继续分析。这个循环我跑了大概两个月，把主要技能的错误率从最初的 15% 降到了 3% 以下。

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

5.1 Agent 调用技能时参数格式错误的排查思路

这是最常见的问题，没有之一。表现是 Agent 生成的参数不符合 Schema 定义，导致校验失败。排查的时候不要只看错误信息，要往前看 Agent 的原始请求和它当时看到的技能描述。

我遇到过一个典型案例：一个日期参数，Schema 里写的是format: "date"，示例给的是2025-06-15。但 Agent 经常传2025-6-15或者2025/06/15。一开始我以为是模型能力问题，后来发现是描述文件里没有明确说“必须补零”。我在description里加了一句“月份和日期必须两位数字，不足补零”，错误率立刻降了八成。

另一个常见问题是枚举值不匹配。Agent 可能传一个语义相近但不在枚举列表里的值。比如枚举是["high", "medium", "low"]，Agent 传了"normal"。我的处理方式是在校验失败时，返回一个“最接近的合法值”建议。Agent 拿到建议后，通常会在下一次调用中修正。

还有一个坑是嵌套对象的参数。Agent 对扁平结构的参数处理得很好，但遇到嵌套对象就容易漏字段或者搞错层级。我的经验是，尽量把技能参数设计成扁平的。如果实在需要嵌套，就在描述文件里给一个完整的嵌套示例，并且把每个子字段的说明写清楚。

5.2 技能执行超时与重试策略的平衡

超时和重试是一对矛盾。超时太短，正常请求被误杀；超时太长，慢请求拖垮系统。重试太少，偶发失败导致任务中断；重试太多，可能引发雪崩。

我的策略是分级超时 + 有限重试。每个技能定义里可以配置三个超时时间：软超时、硬超时和绝对超时。软超时是预期的最长执行时间，超过软超时但未到硬超时，系统会记录警告但不中断。硬超时是必须中断的时间点，超过就返回超时错误。绝对超时是包括重试在内的总时间上限，超过就彻底放弃。

重试策略上，我只对幂等操作开启自动重试。非幂等操作，比如“发送消息”或“创建订单”，绝不自动重试，而是返回错误让 Agent 决定。重试次数最多两次，且每次重试的间隔指数递增。这样既能处理偶发的网络抖动，又不会在系统真正故障时疯狂重试。

这里有个实操心得：超时时间不要设成整数。比如不要设 5000ms，而是设 4700ms 或 5300ms。因为很多系统的超时机制是整秒对齐的，设成整数容易和系统超时撞在一起，导致难以排查的边界问题。这个技巧是我从一个老运维那里学来的，实测确实能减少一些诡异的超时现象。

5.3 技能版本升级导致 Agent 行为异常的兼容处理

技能升级是不可避免的，但升级不能让老 Agent 突然失效。我的做法是向后兼容优先，破坏性变更走新版本。

具体来说，如果只是修改描述文字或者增加可选参数，直接在当前版本上更新，不改变版本号。因为这类变更不影响 Agent 的调用方式。如果增加了必填参数或者改变了参数含义，那就发布一个新的大版本，老版本继续保留至少三个月。Agent 在调用时可以指定版本，不指定则默认用最新版。

但这里有个问题：Agent 通常不知道技能升级了。它可能一直调用老版本，直到老版本下线才发现问题。为了解决这个，我在技能发现接口里加了一个deprecated标记。当某个版本被标记为废弃时，Agent 拉取技能列表会看到这个标记，然后可以选择升级或继续使用。同时，调用废弃版本时，返回结果里会附带一个警告信息，提醒 Agent 该版本即将下线。

还有一个细节是依赖技能的版本联动。如果技能 A 依赖技能 B，B 升级了，A 可能需要跟着升级。我在依赖表里记录了版本约束，当 B 发布新版本时，系统会自动检查所有依赖它的技能，如果版本约束不满足，就通知相关负责人。这样避免了“B 升级导致 A 崩溃”的连锁反应。

5.4 常见问题速查表

6. 技能库的扩展与长期维护经验

6.1 技能粒度的把握：太细还是太粗

技能粒度是个很微妙的问题。太细了，Agent 需要调用很多次才能完成一个任务，上下文切换成本高。太粗了，技能内部逻辑复杂，参数多，Agent 容易用错。

我的经验是按“原子操作”来划分，但允许组合。原子操作是指那些不可再分的最小功能单元，比如“查询天气”“发送邮件”“计算汇率”。这些操作参数少、语义清晰、容易测试。然后我再提供一层“组合技能”，把常用的原子操作序列封装起来，比如“预订行程”可能包含查天气、查航班、发确认邮件。组合技能对 Agent 更友好，因为它只需要一次调用就能完成多步操作。

但组合技能不能太多，否则技能库会变得臃肿。我的标准是：如果一个组合被三个以上不同 Agent 使用，就把它固化成组合技能；否则就让 Agent 自己编排原子技能。

6.2 技能文档的持续迭代与 A/B 测试

技能文档不是写完就完了，需要持续迭代。我每个月会做一次文档审查，重点看三个指标：调用成功率、平均调用次数和错误分布。如果某个技能的成功率下降，或者平均调用次数上升，就说明文档可能有问题。

A/B 测试在技能文档优化上非常有用。我会同时维护两个版本的描述文件，随机分配给不同的 Agent 调用，然后对比成功率。比如一个版本用简洁描述，另一个版本用详细描述，看哪个效果更好。测试周期一般是一周，样本量至少一千次调用。这个做法帮我发现了很多反直觉的结论，比如有时候更长的描述反而降低了成功率，因为模型被无关信息干扰了。

还有一个技巧是让 Agent 自己反馈。我在技能调用接口里加了一个可选的feedback字段，Agent 可以在调用后提交对结果的评价。虽然大部分 Agent 不会主动填，但那些填了的反馈非常有价值，尤其是负面反馈，往往能直接指出文档的盲区。

6.3 安全边界与权限控制的最小化实践

Agent 调用技能时，权限控制不能马虎。我的原则是最小权限 + 显式授权。每个技能定义里都声明了它需要的权限，比如“读取用户位置”“写入日志”“访问外部网络”。Agent 在调用前，必须先获得这些权限的授权。授权不是永久的，而是有有效期的，过期需要重新授权。

权限的粒度要细。比如“访问外部网络”太宽泛了，我会拆成“访问天气服务”“访问地图服务”“访问邮件服务”。这样即使某个 Agent 被恶意利用，它能造成的破坏也有限。

还有一个实践是输入输出审计。所有技能的输入和输出都会记录在审计日志里，但敏感字段会被脱敏。比如用户 ID 只记录哈希值，位置信息只记录城市级别。这样既能追溯问题，又不会泄露隐私。

6.4 从单机到分布式的演进路径

一开始我的技能库是单机部署的，所有技能跑在同一台机器上。随着技能数量增加和调用量上升，单机扛不住了。演进到分布式是必然的，但怎么演进有讲究。

我的路径是先垂直拆分，再水平扩展。垂直拆分是指按技能类型拆成不同的服务，比如“数据查询类”一个服务，“消息通知类”一个服务，“计算类”一个服务。每个服务独立部署、独立扩缩容。这样即使某个服务出问题，也不会影响其他技能。

水平扩展是指同一个服务部署多个实例，通过负载均衡分发请求。但这里有个坑：有些技能是有状态的，比如需要维护会话或缓存。对于这类技能，我用一致性哈希把相同会话的请求路由到同一个实例。无状态技能则随便分发。

演进过程中最大的挑战是服务发现和配置管理。技能数量多了之后，Agent 怎么知道某个技能在哪个服务上？我的做法是维护一个中心化的路由表，Agent 只需要知道技能 ID，路由表负责找到对应的服务地址。路由表本身也是高可用的，多个副本同步。

7. 我个人在实际操作中的几点体会

这个项目做了大概四个月，从最初的一个简单想法，到现在支撑着几个内部 Agent 系统的日常运行。踩过的坑不少，但收获更大。

最大的体会是：给 Agent 做基础设施，和给人做基础设施，思路完全不同。人容忍模糊，Agent 需要精确；人擅长联想，Agent 需要显式；人可以从错误中学习，Agent 需要你提前把错误路径堵死。所以做这个网站的过程中，我花在“防错”上的时间，远多于花在“功能”上的时间。

另一个体会是文档即接口。在 Agent 系统里，技能描述文件的重要性不亚于技能实现本身。一份好的描述文件能让平庸的实现变得可用，一份差的描述文件能让优秀的实现变得不可用。我现在的习惯是，写技能实现之前先写描述文件，写完描述文件让模型试着调用几次，根据调用结果调整描述，最后再写实现。这个顺序看起来反直觉，但实际效果很好。

最后分享一个小技巧：给技能起名的时候，用动词开头，并且尽量具体。比如get_weather比weather好，send_email比email好，calculate_exchange_rate比exchange好。因为 Agent 在规划任务时，是根据动作来匹配技能的。动词开头的名字能让匹配更准确。这个细节很小，但实测下来对调用成功率的提升是肉眼可见的。