企业官网建设流程全解析

做Agent一段时间后，我最大的感触是：模型能力只是起点，真正让Agent从“能聊天”变成“能干活”的，是藏在背后那一层agent-skills。这个名字看起来简单，但它决定了你的Agent是玩具还是工具。这篇文章，我想把这一层的设计思路、落地方式和踩过的坑，原原本本整理出来。

先说清楚对象：如果你正在做Agent类应用，不管你是团队里的技术负责人、独立开发者，还是刚接触大模型应用的新人，这篇文章都会有用。它不讲模型怎么训练，也不讲Prompt的花式技巧，只讲一件很具体的事：如何把外部能力安全、稳定、可控地交给Agent，让它在真实业务里跑起来。

1. 重新理解agent-skills：为什么技能层成了Agent系统的分水岭

1.1 技能是什么，它和工具、函数有什么区别

刚接触这个概念的人，最容易把agent-skills看成“工具集合”的另一个说法。实际上，两者有本质区别。工具是给开发者用的API函数，技能是给模型用的能力描述单元——这句话值得反复看几遍。

一个工具函数，比如get_weather(city)，它的消费者是代码调用方，参数类型、返回值都写在接口文档里。但一个技能，它的消费者是大语言模型。模型没有读过你的源码，它只能通过一段描述文字来理解这个函数是干什么的、什么时候该调用、参数填什么。所以技能的本质是“面向模型的能力接口”，而不是“面向程序的能力接口”。

我见过很多失败的Agent项目，最典型的原因就是把技能层做成了工具层。开发者写了二十个API函数，往函数列表里一塞，就指望着模型自己去理解。结果模型要么乱调用，要么干脆不调用。“为什么刚才还要人教、现在要机器自己判断？”这就是没想清楚技能和函数的区别。

技能还需要回答三个问题：什么时候用、怎么用、用了以后会发生什么。函数签名回答不了这三个问题，但技能定义可以。

1.2 技能层到底解决了什么问题

站在产品视角，Agent要做的事情无非三类：获取信息、操作业务、生成内容。这三类事情都依赖外部能力，但不同能力对模型的要求完全不一样。

获取信息只需要只读接口，模型要做的是决定“需不需要查、查什么”。操作业务涉及到写操作，风险一下子高了起来，模型必须非常明确地知道操作对象、操作内容和操作限制。生成内容看起来最简单，实际上对参数约束要求最高，模型很容易把提示词直接当成业务参数传进去，制造出一堆垃圾输出。

技能层最重要的工作，是在模型和外部系统之间建立一个“翻译层”。它把庞大的API体系翻译成模型能看懂的、边界清晰的能力卡片。没有这层翻译，Agent的能力就悬在空中，每一步决策都像盲猜。

我自己的经验是，一个设计良好的技能层，能让模型在80%的普通场景下直接做出正确选择，只有在剩下的20%模糊场景里才需要额外推理。而一个设计混乱的技能层，模型永远在犯错，根本到不了工作流那一步。

1.3 一个合格的技能定义，至少包含哪些要素

很多团队的技能定义只有一个字段：描述文字。这远远不够。我在实际项目里，会把技能拆成五个维度去定义，缺一个都会在后续踩坑。

第一是技能名称。不要用编号，用动宾短语，比如“查询库存余量”“提交退款申请”。第二是功能描述。这是给模型看的，要点是场景、边界和触发条件。第三是参数Schema。包括字段名、类型、是否必填、取值范围。第四是副作用说明。这个技能会不会改数据、会不会发通知、能不能重复执行。第五是审计信息。版本号、负责人、调用权限、限流等级。

看起来繁琐，但每一块都有实际用途。名称决定召回率，描述决定准确率，Schema决定合法性，副作用决定安全性，审计信息决定可运维性。这五个维度合在一起，才是完整的技能。

2. 技能库的三种设计路线：选型不是越复杂越好

2.1 轻量路线：JSON Schema打天下的取舍

最朴素的技能定义方式，就是直接把函数声明转成JSON Schema，塞进模型请求里。这种方式上手快，很多团队半天就能跑通。

好处很明显：开发速度快，模型兼容性好，大多数主流模型对JSON Schema的原生支持度都不错。而且排查问题时很直接，模型返回什么参数一目了然。

但这个路线的天花板也很低。当技能数量超过三十个以后，模型的选择准确率会明显下滑。我测试过一组对比：技能从20个增加到50个，调用准确率大概下降10到15个百分点。因为模型需要从越来越长的函数列表里去匹配意图，上下文里的干扰项变多了。

用这条路线，还需要非常重视描述文案的打磨。同样的函数，描述写成“查询数据”和写成“当用户提到订单存量问题时，调用本接口获取当前可售数量，注意区分在库与在途”，模型的表现会天差地别。我的习惯是每条描述都经过三轮修改：第一轮自己写，第二轮让同事只看描述复述功能，第三轮跑测试看模型调用准确率。

2.2 标准化路线：协议化技能描述

当技能库开始承载业务能力，就值得考虑标准化协议了。现在社区里比较成熟的方案是借鉴命名空间加能力清单的做法，把技能按域划分，每个域下挂一组原子操作。

比如订单域下面，有查询订单、修改订单备注、取消订单三个技能。库存域下面，有查询库存、锁定库存、释放库存三个技能。模型在做意图识别时，先感知到“用户在问订单的事”，再在订单域内部选具体技能。这样做的好处非常明显：模型的选择范围从全量技能缩小到一个域，准确率提升非常显著。

我做过一个实验，用标准化协议重组技能库后，相同场景的调用准确率从82%提升到了94%。代价是定义工作变重了。你需要在技能之上再维护一层分组关系，还要定期审查技能是否该归属当前域。

对于团队协作场景，协议化路线还有一个隐藏收益：不同业务线的技能可以独立演进。A组维护订单技能，B组维护库存技能，互不干扰。只要组与组之间的边界清晰，合并时只需要注册命名空间即可。

2.3 内部DSL路线：为复杂逻辑而生的硬核方案

如果技能不再只是简单函数，而是一组带流程的操作序列，光靠参数Schema就不够了。比如“生成一份库存报告并发送给管理者”，这个技能内部其实包含查询库存、生成摘要、寻找收件人、发送通知四步。

内部DSL的玩法，是用一段领域脚本把技能的内部流程固化下来，模型只需要定位到技能入口，剩下的流程由执行引擎控制。这样做的好处是，复杂逻辑不用每次都依赖模型现场推理，流程稳定且可测试。

坏处也很明确：你要维护一套脚本解释器，还要设计DSL语法，开发成本是前两种路线的几倍。如果只是一个几十个技能的轻量Agent，完全没必要上DSL。我的建议是，当技能内部涉及多步外部调用、存在条件分支和重试策略时，再考虑走这条路线。

2.4 三条路线怎么选

我的个人建议是一个递进策略：项目起步用轻量JSON Schema方案，加速产品验证；当技能数量超过30个，且出现明显的选择准确率问题时，做协议化改造；只有当具体业务技能内部确实需要复杂流程编排时，才为那一小撮技能做DSL定制。

不要一开始就上一个庞大的技能编排平台，那是大公司基础设施团队才会考虑的工程问题。中小团队把验证做好，比什么都有意义。

3. 技能从注册到调用：一条链路上最容易出问题的四个环节

3.1 技能注册：把能力暴露给Agent，不是把API列表丢给它

技能注册是第一步，也是最容易被低估的一步。很多系统就是把所有技能一股脑导进去，让模型自己去看。正确的做法，是先做一次“技能裁剪”。

每次模型请求上线时，根据当前会话所处的业务上下文，只加载可能用到的技能子集。比如用户刚进到订单售后页面，那就只把订单域和客服域的技能挂进去，完全不加载库存域、营销域的技能。这一步能直接拉高模型的调用准确率，因为干扰项少了。

我在项目里还会做一个冷启动注册阶段：新技能先以小流量方式上线，只开放给内部白名单用户，跑一周数据再看调用准确率。准确率不达标，就继续调整描述文案，不上全量。

3.2 上下文与参数绑定：约束模型的自由度

模型在调用技能时，最大的风险是参数乱填。比如一个查询接口只接收订单号，但模型可能在没有任何订单号的情况下，编造一个“客户提到过的编号”。

解决这个问题，需要双管齐下。第一是在技能描述里强调前置条件，明确写“只有用户明确提供订单号时才可调用，否则先反问用户”。第二是在执行层做参数校验，模型返回的参数如果不符合Schema约束，直接返回错误信息，让模型重新生成。

我在实践里发现，参数校验这步绝对不能省。省了，你就要处理各种诡异的脏数据进入业务系统。一个校验函数，可能每小时帮你挡掉几十次非法调用。

3.3 执行引擎与调度策略：技能调用的生命周期管理

技能调用不是发一个HTTP请求就完事，它是一个完整的生命周期：解析模型输出、校验参数、执行内置逻辑、处理返回结果、把结果格式化成模型能理解的文本。

生命周期里最关键的环节，是返回结果的处理。模型不是直接读接口返回的JSON，它读的是经过格式化的文本。如果格式化做得不好，信息密度太低，模型就会在多个调用之间来回折腾，浪费上下文窗口。

调度策略方面，我想特别提一个点：技能调用是有代价的，不是免费的。一次技能调用要消耗模型上下文、等待外部系统响应、占用执行时间。所以我的经验是设置一个调用次数的软上限。如果一个任务类型平均需要三次技能调用才能完成，但某次会话已经调用了十次还在继续，大概率是模型走进了循环，这时候应该主动终止并询问用户。

3.4 技能编排：从单技能调用到多技能协作

真实的业务场景很少是单个技能能搞定的。大多数情况下，Agent需要在一次任务里组合调用多个技能，这就要用到技能编排。

编排这件事，我的核心建议是：能用流程固定的编排，就不要依赖模型自由发挥。比如“生成库存报告并发送给管理者”这个流程里，先查询库存，再取收件人，再发通知。这三步是完全确定的，就应该做成固定流程，模型只能选择要不要执行，而不能决定中间步骤。

反过来，如果问题是开放式的，比如“帮我分析一下为什么最近订单量下降了”，这时候应该让模型自由选择查询订单量、查看客单价、检索近期活动三个技能的组合方式。固定编排处理确定流程，自由组合处理开放问题。两者配合，才是健康的技能编排体系。

4. 把agent-skills落到真实项目：一个模拟项目的完整拆解

4.1 项目背景与目标

为了把前面的思路落到实践，我设计了一个模拟项目，就叫它“某客服工作台智能助手”。目标很简单：让一个对话式Agent处理客服日常工作中最常见的三类任务——查订单、处理售后、汇总交接班记录。

这个项目设计了5个技能，不贪多，但每一个都完整走了一遍注册、描述、校验、执行、格式化整个过程。这样做的意义是，用一个小而完整的案例，把前面几章讲的设计理念串起来。

4.2 技能清单与定义策略

5个技能的定义如下：

查询订单状态。描述里强调需要用户提供订单号，如果没有就反问。支持模糊搜索，但必须经过用户二次确认。

修改订单备注。这个技能涉及写操作，描述里强调只能在用户明确要求修改时才调用，且修改前必须回显修改内容给用户确认。

提交售后申请。限制更强，每次会话只能调用一次，参数校验要求必须有申请原因。

查询库存余量。只读技能，描述里区分了精确查询和区间查询两种触发场景。

生成交接班报告。多步编排技能，内部固定流程为：拉取当前会话未处理事项、汇总本班次已完成操作、生成文本报告。

每个技能在注册时，都带了版本号、适用会话场景标签和白名单权限标记。

4.3 核心代码片段与运行效果

我先给出一段技能注册表的伪代码，用来演示结构设计：

这个设计里，eligibility_checker的角色很关键。它会在技能执行前检查当前会话是否满足触发条件。比如create_refund技能，同一个会话如果已经调用过一次，这里就会直接拦截，返回错误提示让模型向用户解释原因。

为了跑通实操流程，我选了一个中等体量的模型来做测试。测试任务是：“帮我查一下订单12345的物流信息，顺便给这个订单加个备注，说一周后再发货。”

模型在技能层的引导下，先检索到query_order_status技能，但在执行时发现该技能返回的信息里没有物流轨迹字段。这里体现出的设计细节是：技能返回结果里主动暴露了“缺少信息”的标记，模型意识到需要调用另一个快递查询技能，于是补充了一次调用。

整个会话最终走了一次技能选择、两次技能调用、一次参数修正。在我看来，这个效果已经达到了可用的标准。如果把技能数量扩展到20到30个，配合分组加载，同样可以保持稳定。

这个案例最值得参考的，不是代码本身，而是它在技能定义里埋的约束逻辑。每一处“如果用户没有提供某参数，则先反问”的规则，都在帮模型降低犯错概率，而这恰好是技能层设计的核心价值。

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

5.1 模型开始乱填参数了怎么办

最典型的场景是：模型明明没有获取到订单号，却编造了一个“看起来合理”的编号传入查询接口。遇到这种问题，先别急着换模型，优先级最高的是检查技能描述里是否写清楚了前置条件。

我的常用改法是在技能描述开头加上“必须满足以下条件才可调用：...”，然后用列举句式把条件写全。改完之后跑一遍回归测试，如果还出现乱填的情况，再考虑在参数校验层增加强制反问逻辑：检测到关键参数缺失时，让执行引擎直接不发起外部调用，返回“缺少订单号，请先向用户索要”。

实际排查的过程里，七成问题都是描述不清造成的，模型本身没有那么大罪过。

5.2 技能调用超时，答案迟迟不返回

技能调用超时的原因往往不在模型，而在外部依赖。比如技能内部要调用一个第三方查询接口，这个接口偶尔要三秒钟才响应，模型等待期间上下文状态还在继续消耗，最终结果要么超时要么截断。

我的做法是给每个技能配置独立的超时时间，时长取决于外部接口的P95响应时间。与此同时，在技能描述的显眼位置标注预期耗时：“本技能通常需要1到2秒完成查询”。这样模型会提前知道该技能偏慢，不会在慢技能上反复重试。

如果外部接口实在不稳定，我会直接把技能从模型可调用列表里摘掉，放到固定流程里由程序自动兜底调用，避免模型一次次地去撞同一堵墙。

5.3 多技能组合时上下文爆炸

当模型需要连续调用多个技能时，每个技能的返回结果都会留在对话历史里。技能数量一多，上下文里堆积了半屏的工具返回JSON，真正有用的业务信息反而被冲淡了。

我解决这个问题的方式，是给技能返回信息加上严格的摘要层。每个技能执行完以后，不是把完整结果返回给模型，而是只返回一个摘要，最多两句话加三个关键值。比如仓库查询返回的是“余量充足，建议配件库存提交补货申请”，而不是一张25行的库存流水表。

这样调整后，同一个任务的模型输入长度能压缩40%以上，而且模型做后续判断时更聚焦。摘要层的实现也很简单，给每个技能配置一个提炼函数即可，不需要复杂模型参与。

5.4 安全边界：不能让模型什么都做

最后说一个容易被忽视的问题：技能层不能只考虑效果，还要考虑安全边界。这里不只是指权限控制，还包括业务风险的边界设定。

再举一个例子：某次测试里，用户对模型说“把最近一周所有订单都打八折”。这个请求触碰了价格操作技能，但这个技能并没用对应的权限标记。由于权限校验在技能执行前就拦截了这次调用，模型被迫向用户解释“当前账号没有价格修改权限”。

这就是技能层安全边界的价值：让模型犯错，但不能让系统承担风险。我在每个技能定义里，都会加一个权限位配置。凡是涉及资金、价格、批量操作的技能，权限校验绝不可跳过，而且要有审计日志。

做技能层时间越久，我越觉得这个系统的核心不是技术挑战，而是工程取舍。每一次技能边界的确定、每一句描述的打磨、每一个约束条件的添加，都在真实地影响Agent的能力上限。希望这篇文章能帮你少走一些弯路，把agent-skills真正做扎实。