企业官网建设流程全解析

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

先说结论：这个项目的核心不是“再做一个网站”，而是给 AI Agent 提供一个结构化、可验证、可复用的外部能力层。你可以把它理解成给一个刚入职的聪明实习生配了一本随时能查、每页都经过校对的操作手册，而不是让他凭记忆瞎猜。

过去大半年，我一直在折腾各种 Agent 工作流。从最简单的“帮我总结这篇文章”，到稍微复杂一点的“读取本地文件、调用接口、生成报告并归档”，踩的坑几乎一模一样：模型本身很聪明，但一到具体执行环节就开始飘。它会编造一个不存在的函数名，会忽略你三句话之前刚强调过的格式要求，会在多轮对话后把关键约束忘得一干二净。你反复在提示词里写“不要虚构”“必须按这个格式”，效果时好时坏，像在跟一个记性不太好的同事反复交代同一件事。

后来我想明白了一件事：可靠性问题，很大程度上不是模型能力问题，而是信息供给方式的问题。你把所有规则、工具说明、示例、边界条件全部塞进一段越来越长的系统提示里，模型要在有限的上下文里同时做“理解任务”“回忆规则”“选择工具”“组织输出”四件事，出错概率自然高。那如果换一种思路——把 Agent 需要的能力拆成一个个独立、可检索、带示例的“技能卡片”，放在一个它随时能访问的网站上呢？

这就是这个项目的起点。我给它起的内部代号叫AgentHub，一个专门给 AI Agent 用的网站，核心包含两块：一是结构化的技能库（skills），每个技能都有明确的输入输出定义、调用示例和失败处理建议；二是一个轻量的检索与调用层，让 Agent 能通过标准化的方式找到并“学会”某个技能，而不是靠提示词里硬编码。

它解决的核心问题有三个。第一，降低提示词膨胀。你不需要把几十条规则全写进系统提示，Agent 需要什么就去技能库里查什么。第二，提高可验证性。每个技能都是独立文件，可以单独测试、单独版本管理，改一个技能不会影响其他技能。第三，增强跨会话一致性。同一个技能被不同会话、不同任务反复调用，行为是稳定的，不会因为提示词顺序变化而时灵时不灵。

适合谁来参考？如果你正在做 Agent 应用开发，不管是基于哪种框架，只要涉及到“让模型调用外部能力”这件事，这套思路都能直接借鉴。如果你只是偶尔用 AI 处理日常任务，那你可以重点看技能设计那部分，它本质上是一套“如何把模糊需求翻译成明确指令”的方法论。哪怕你完全不写代码，理解这套逻辑也能让你在跟 AI 协作时少生很多气。

2. 整体设计思路：把“提示词工程”升级成“技能工程”

2.1 从“一段大提示”到“一个技能库”的转变逻辑

最开始我也是那种把什么都往系统提示里塞的人。一个项目做下来，系统提示能写到两三千字，里面混杂着角色设定、输出格式、工具说明、禁忌事项、示例对话。每次改一个细节，都要在那一大段文字里小心翼翼地找位置，生怕改出连锁反应。更麻烦的是，当 Agent 需要同时处理多个不同类型的任务时，这段提示会变得极其臃肿，模型在长上下文里的注意力被严重稀释。

后来我参考了一个很朴素的工程原则：关注点分离。角色设定归角色设定，工具说明归工具说明，每个工具的具体用法单独成文。Agent 在运行时，先根据任务类型检索到相关技能，再把技能内容动态注入到当前上下文里。这样每次注入的都是“当前任务真正需要的信息”，而不是“所有可能用到的信息”。

这个转变带来的直接好处是，系统提示可以保持精简和稳定，技能库可以独立迭代。我实测下来，在同一个多步骤任务上，采用技能库方式后，Agent 首次调用正确工具的概率从大概六成提升到了九成以上。这个提升不是来自模型换了，而是来自信息组织方式变了。

2.2 为什么选择“网站”作为载体而不是本地文件

你可能会问，技能库用本地 Markdown 文件不就行了吗，为什么要做成网站？我一开始也是用本地文件，但很快遇到几个问题。

第一，多环境同步麻烦。我在不同设备、不同项目里都要用同一套技能，本地文件复制来复制去，版本很容易乱。做成网站后，所有环境访问同一个地址，天然一致。

第二，检索能力弱。本地文件靠文件名和目录结构检索，当技能数量超过几十个之后，找起来很费劲。网站可以加搜索、标签、分类，Agent 也能通过接口按关键词或语义检索。

第三，更新即时性。我改了一个技能的示例，希望所有正在运行的 Agent 立刻用上新版本。本地文件需要重新加载，网站只需要刷新缓存。

第四，可观测性。网站可以记录每个技能被调用的次数、成功率、常见失败原因，这些数据反过来指导我优化技能设计。本地文件做不到这一点。

当然，网站也带来了额外的维护成本，比如部署、域名、访问控制。但对于我这种多设备、多项目、高频迭代的使用场景来说，这些成本完全值得。如果你只是单机偶尔用，本地文件也够，但一旦技能数量上去、使用频率上去，网站的优势会非常明显。

2.3 技能（skills）的粒度怎么定

这是设计中最关键也最容易做错的地方。技能粒度太粗，一个技能里塞了十几个步骤，Agent 调用时还是要理解一大堆东西，跟写大提示没区别。粒度太细，每个技能只做一件极小的事，Agent 需要连续调用十几个技能才能完成一个任务，中间任何一步出错都会导致整体失败。

我最后采用的粒度原则是：一个技能对应一个“可独立验证的原子能力”。什么叫可独立验证？就是这个技能被调用后，你能明确判断它成功还是失败，输出是否符合预期。比如“读取指定路径的文本文件”是一个技能，“把文本按段落切分”是另一个技能，“提取段落中的关键实体”又是一个技能。每个技能都有明确的输入类型、输出类型和失败模式。

但也不是所有场景都适合拆这么细。对于高频组合操作，我会做一个“复合技能”，内部按顺序调用多个原子技能，对外暴露一个简化接口。比如“读取文件并提取关键实体”就是一个复合技能，它内部先调读取技能，再调切分技能，再调提取技能。这样既保留了原子技能的可测试性，又减少了 Agent 的调用次数。

我一般会遵循一个经验值：单个技能的说明文档控制在 200 到 500 字之间，包含功能描述、输入参数、输出格式、一个成功示例、一个失败示例、常见错误处理。超过 500 字就考虑拆分，少于 200 字就考虑合并。这个范围是我反复调整后觉得比较舒服的区间，Agent 读起来不费力，我也维护得过来。

3. 核心细节解析：一个技能文件到底长什么样

3.1 技能文件的标准化结构

每个技能在 AgentHub 上都是一个独立的 Markdown 文件，经过解析后以结构化数据的形式提供给 Agent。我定义的字段包括：技能名称、唯一标识、功能描述、输入参数表、输出格式说明、调用示例、失败处理建议、版本号、标签。下面我拿一个实际在用的“文本摘要”技能来举例说明每个字段的设计意图。

技能名称要短且语义明确，比如“text-summarize”，不要用“do-summary”这种模糊词。唯一标识用命名空间加名称，比如“nlp.text-summarize”，方便分类检索。功能描述用一句话说清楚这个技能做什么、不做什么，比如“将一段中文文本压缩为指定字数的摘要，不改变原文事实，不添加原文没有的信息”。这句话很重要，它同时定义了能力和边界，Agent 看到就知道什么时候该用、什么时候不该用。

输入参数表用表格形式列出每个参数的名字、类型、是否必填、默认值、说明。比如文本内容、目标字数、摘要风格。输出格式说明要明确是纯文本、JSON 还是 Markdown，如果是 JSON 要给出字段结构。调用示例给一个完整的输入输出对，让 Agent 能直接模仿。失败处理建议列出常见失败情况，比如输入为空、文本过长、目标字数不合理，以及每种情况应该怎么应对。

版本号用语义化版本，每次修改都递增，方便追踪。标签用于检索，比如“nlp”“文本处理”“摘要”。这些字段看起来多，但写顺了之后一个技能文件十分钟就能搞定，而且后续维护非常清晰。

3.2 输入输出定义中的“防幻觉”设计

Agent 不可靠的一个典型表现是“幻觉调用”——它编造一个不存在的参数，或者把参数类型搞错。为了减少这种情况，我在输入输出定义上做了几层约束。

第一，参数类型严格化。每个参数都标明类型，字符串就是字符串，数字就是数字，布尔就是布尔。Agent 在生成调用时，如果类型对不上，解析层会直接拒绝并返回错误信息，而不是硬着头皮执行。这比让模型自己“理解”要可靠得多。

第二，必填与可选分离。必填参数缺失时直接报错，可选参数缺失时用默认值。这样 Agent 不需要记住哪些参数可以省略，只需要按定义填就行。

第三，输出结构固定。如果一个技能返回 JSON，我会在文档里给出完整的字段结构，包括每个字段的类型和含义。Agent 拿到输出后，可以按固定路径解析，不需要猜。如果返回纯文本，我会说明文本的格式约定，比如“第一行是标题，第二行开始是正文”。

第四，示例即契约。调用示例不只是给人看的，也是给 Agent 看的。我会确保示例中的输入输出完全符合定义，Agent 模仿示例的格式来生成调用，出错概率会低很多。我试过把示例写得很随意，结果 Agent 也跟着随意，输出格式五花八门。后来把示例写严谨了，输出一致性明显提升。

3.3 技能检索机制：让 Agent 自己找到需要的技能

AgentHub 的检索层支持两种方式：关键词检索和语义检索。关键词检索就是传统的全文匹配，适合技能名称和标签比较规范的情况。语义检索用嵌入向量做相似度匹配，适合 Agent 用自然语言描述需求时找到相关技能。

我实际用下来，两种方式结合效果最好。Agent 先用自己的话描述当前需要什么能力，检索层返回最相关的三到五个技能，Agent 再从中选择最合适的一个。这个过程不需要人工干预，也不需要把所有技能都塞进上下文。

这里有个细节值得注意：检索结果要带摘要。如果只返回技能名称，Agent 可能选错。我会在检索结果里附带每个技能的一句话描述和输入参数概览，让 Agent 在选之前就能判断是否匹配。这个摘要控制在 50 字以内，太长会占用上下文，太短又不够判断。

另外，我会给每个技能设置一个“适用场景”字段，用自然语言描述什么情况下该用这个技能。比如“当你需要把长文本压缩但保留关键信息时使用”。这个字段在语义检索时权重很高，能显著提升匹配准确率。

4. 实操过程：从零搭建一个 Agent 技能网站

4.1 技术选型与基础环境搭建

先说技术栈。我选的是静态站点生成 + 轻量 API 层的组合。静态部分用 Markdown 文件生成技能页面，方便人浏览和编辑。API 层负责给 Agent 提供检索和获取技能内容的接口。数据库我用的是轻量级的键值存储，因为技能数据量不大，不需要复杂的关系型数据库。

为什么不用重型框架？因为我的核心需求是“快”和“稳”。Agent 调用技能时，响应时间直接影响整体任务耗时。静态生成的内容可以直接走缓存，API 层只做检索和组装，逻辑简单，出错面小。我试过用更复杂的方案，结果调试成本高，收益不明显，最后又退回来了。

部署方面，我放在一个低配的云主机上，配合对象存储做静态资源分发。技能文件用 Git 管理，每次推送自动触发构建和部署。这样我本地改完技能，推上去几分钟内所有环境都能用上新版本。访问控制用简单的令牌机制，只有持有有效令牌的 Agent 才能调用 API，避免技能库被随意访问。

4.2 技能文件的编写与入库流程

写一个技能文件，我一般按这个顺序来。先想清楚这个技能解决什么问题，用一句话写下来，这就是功能描述。然后列出输入参数，每个参数问自己三个问题：这个参数是必须的吗？它的类型是什么？如果用户不提供，默认值应该是什么？接着定义输出格式，如果是结构化数据，把字段结构写出来；如果是文本，把格式约定写清楚。

然后写调用示例。我会实际跑一遍，把真实的输入和输出贴进去，确保示例是可复现的。这一步很关键，因为很多设计问题在写示例的时候才会暴露出来。比如你发现某个参数其实没法从上游获取，或者输出格式在实际解析时会有歧义，这些都要在写示例时修正。

最后写失败处理建议。我会故意制造几种失败情况，比如输入为空、输入超长、参数类型错误，看看系统实际返回什么，然后把应对建议写进去。这些建议会直接指导 Agent 在遇到错误时怎么重试或降级。

写完的文件放到 Git 仓库的指定目录，推送到远程，自动构建流程会解析文件、提取结构化数据、更新检索索引。整个过程不需要手动操作数据库，降低了出错概率。

4.3 Agent 端的接入与调用示例

Agent 端接入很简单，核心就是两个接口：一个检索接口，一个获取技能详情接口。检索接口接收一个查询字符串，返回匹配的技能列表，每个技能带名称、描述、标签和唯一标识。获取详情接口接收技能标识，返回完整的技能定义，包括参数表、输出格式、示例和失败处理。

我在 Agent 的系统提示里只写一段很短的说明：“当你需要外部能力时，先调用技能检索接口，根据返回结果选择最合适的技能，再获取详情并按定义调用。” 就这一段，替代了以前几百字的工具说明。Agent 在运行时，会根据当前任务自动检索和调用，不需要我预先告诉它有哪些工具。

实际调用时，Agent 生成的调用请求会经过一个校验层，检查参数类型、必填项、格式是否符合技能定义。校验不通过就返回明确错误，Agent 根据错误信息修正后重试。这个校验层是可靠性的重要保障，它把很多低级错误挡在了执行之前。

我实测下来，接入技能库后，Agent 在多步骤任务中的工具调用准确率明显提升，而且因为技能定义清晰，即使调用失败，Agent 也能根据失败建议做出合理应对，而不是直接卡死或胡编一个结果。

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

5.1 技能检索不准怎么办

这是最常见的问题。Agent 描述需求时用的词和技能标签对不上，导致检索不到或者检索到不相关的技能。我的排查思路是分三步。

第一步，看 Agent 的查询语句。如果它描述得太笼统，比如“帮我处理一下这个”，那检索不准是正常的。我会在系统提示里引导它用更具体的动词和名词描述需求，比如“我需要把一段中文文本压缩成摘要”。

第二步，看技能标签和描述是否覆盖了常见表达。我会定期查看检索日志，把 Agent 常用的查询词和实际匹配到的技能对比，如果发现某些查询词经常匹配失败，就在相关技能里补充这些词作为标签或描述关键词。

第三步，调整语义检索的阈值。如果阈值太高，相关技能会被过滤掉；太低又会引入不相关结果。我一般会把阈值设在中等偏上的位置，然后对 top 3 结果做人工抽查，根据抽查结果微调。

5.2 技能调用参数出错怎么防

参数出错主要有几种：类型错误、必填缺失、格式不对、值超出范围。我的防护策略是“定义严格 + 校验前置 + 错误友好”。

定义严格就是前面说的，每个参数的类型、必填性、取值范围都写清楚。校验前置是在 Agent 生成调用后、实际执行前，先过一遍校验层，不符合定义直接拒绝。错误友好是指返回的错误信息要具体，告诉 Agent 哪个参数错了、错在哪里、应该怎么改，而不是只返回一个“参数错误”。

我踩过的一个坑是，早期错误信息写得太模糊，Agent 收到后不知道该怎么修正，就反复重试同样的错误调用，浪费了很多轮次。后来把错误信息写具体了，Agent 一次就能改对，效率提升很明显。

5.3 技能版本更新后 Agent 行为不一致

这个问题通常是因为缓存没刷新，或者 Agent 上下文里还留着旧版本的技能定义。我的处理方式是：每次技能更新后，版本号递增，检索接口返回的详情里带版本号。Agent 在调用时如果发现版本号和它上下文里的不一致，就重新获取最新定义。

另外，我会在技能文件里维护一个变更日志，记录每次改了什么、为什么改。这样当行为出现异常时，我能快速定位是不是某次更新引起的。变更日志不需要很长，一两句话说明即可，但坚持记录对排查问题帮助很大。

5.4 常见问题速查表

5.5 几个我踩过的坑和独家建议

第一个坑是技能描述写得太技术化。我一开始用很多专业术语写描述，结果 Agent 理解不了，检索匹配率很低。后来改成用大白话写，比如“把长文章缩短但保留重点”，匹配率立刻上去了。Agent 不是领域专家，它需要的是清晰直白的说明。

第二个坑是示例写得太理想化。我早期只写成功示例，结果 Agent 遇到边界情况时不知道怎么办。后来每个技能都补了一个失败示例和对应的处理建议，Agent 的鲁棒性明显提升。

第三个坑是技能数量增长后缺乏治理。技能多了之后，有些技能功能重叠，有些技能很久没用但还留在库里，检索时互相干扰。我现在的做法是定期清理，合并重叠技能，归档长期不用的技能。保持技能库精简，比不断往里加东西更重要。

第四个建议是给技能加使用统计。我记录了每个技能的调用次数、成功率、平均耗时、常见错误。这些数据帮我判断哪些技能设计得好、哪些需要优化。比如某个技能成功率一直偏低，我就去看它的失败原因，往往是定义不够清晰或者示例不够典型。

第五个建议是不要追求一次设计完美。我最早的技能定义和现在差别很大，都是在使用中逐步调整的。先跑起来，收集反馈，再迭代。技能库是一个活的东西，不是一次写完就固定的文档。

6. 这套方案还能怎么扩展

技能库跑顺之后，我开始想一些延伸用法。一个是技能组合编排，让 Agent 能根据任务自动把多个技能串起来，形成一个工作流。比如“读取文件 → 提取实体 → 生成摘要 → 写入结果”，Agent 只需要描述最终目标，中间步骤由编排层自动完成。这个方向我还在试验，目前的做法是预定义几个常用组合，后续再考虑动态编排。

另一个是技能质量评分。根据调用成功率、耗时、输出稳定性等指标，给每个技能算一个质量分。Agent 在检索到多个相似技能时，优先选择质量分高的。这个机制能自动淘汰低质量技能，让技能库保持健康。

还有一个是跨项目技能共享。我现在有几个不同的 Agent 项目，它们各自有一些通用技能，比如文本处理、格式转换、数据校验。我把这些通用技能抽出来放在共享层，各项目按需引用。这样改一处，所有项目都受益，避免了重复维护。

最后分享一个小技巧：如果你也在做类似的东西，建议从三到五个最常用的技能开始，不要一上来就建大库。先把这几个技能的定义、示例、失败处理打磨好，让 Agent 实际用起来，收集真实反馈，再逐步扩展。技能库的价值不在于数量，而在于每个技能都足够可靠、足够清晰。我见过太多人一开始热情很高，建了几十个技能，结果大部分都没经过实际验证，用起来反而添乱。少而精，持续迭代，才是这条路走得稳的关键。