企业官网建设流程全解析

我先说明一下这次的处理思路。你给的输入很简单，只有一个项目名字“agent-skills”和相关热搜词，没有具体的项目正文和场景描述。这种情况下，我就按最常见的理解来处理——这是一个围绕AI Agent技能体系设计、技能库搭建、工具调用调优的项目。下面的内容从“为什么Agent需要技能库”讲起，把技能定义、描述编写、参数设计、路由调度、踩坑排查这些环节完整展开，尽量做成一份能直接参考的实战材料。如果你手里有更具体的技术选型或场景细节，可以再补充，我再调整内容方向。

1. 先想清楚：Agent缺的从来不只是“聪明”

这两年做大模型应用的人应该都有同感——光有会聊天的模型不够，真正能落地的Agent，拼的反而是那些看起来“笨”的部分：怎么把模型和外部工具接起来，怎么让模型知道什么场景该调什么服务，怎么保证它在复杂任务里不会自己跑偏。

我把大量时间花在研究这个环节上，最终围绕一个叫“agent-skills”的项目做了比较系统的梳理与实践。说白了，它的核心是做一件事：给Agent配置一套结构清晰的技能库，让模型像工具箱里的镊子一样，需要哪样抽哪样，而不是把所有东西混在一起乱拿。这个思路在真实项目里非常实用，尤其是当你要把Agent放进客服、运维、数据查询这类生产环境时，没有技能库管理，模型几乎必然会在工具选择上犯迷糊。

这篇文章就是来拆解这套技能库怎么搭、技能描述怎么写、调用链路怎么调的。适用于正在搞Agent落地、做工具调用接入、或想把手头Prompt工程升级成技能体系的开发者。如果你只是刚接触大模型想了解Agent大概能做什么，这篇内容也可以帮你建立对“Agent技能设计”的整体认知，让你知道真正需要花力气的地方到底在哪。

很多团队的误区是：模型不够聪明就换更大的模型，效果不理想就无限调Prompt。但就我自己的经验，Agent干活拉胯，七成以上的问题出在“技能体系”上——要么技能边界模糊，要么描述写得模棱两可，要么参数定义太随意。这些问题，靠换模型解决不了，只有把技能层做扎实，Agent的稳定性和可控性才能真正提上来。

2. 技能体系的设计与拆解

2.1 技能的最小单元：一个“可被模型理解”的接口

在agent-skills的思路里，技能不是一个函数、也不是一段Prompt，而是一套完整的“接口契约”。这个契约最少包含五样东西：技能名称、触发场景描述、输入参数定义、输出结构定义、典型调用示例。这五个元素缺一不可。

为什么说缺一不可？你可以把技能理解成给模型看的一张“使用说明书”。模型并不知道你的代码里有什么函数，它只能通过你给它的文本和结构去判断“当前这个情况该不该用这个工具”。如果你的技能说明里只写“查询订单状态”，那模型遇到“用户问快递到哪了”时可能会调用，遇到“用户说帮我看看货发了没”时也可能调用，但遇到“用户说客服怎么一直不发货”时就不确定该不该调了。

所以，技能的最小单元是一套能让模型“一眼看懂”的接口描述。名称要短且无歧义，场景描述要覆盖该用和不该用的情况，参数要按JSON Schema严格定义，输出要规定好结构。实际项目里，我给每个技能都单独建一个文件或字典，统一管理，避免散落各处。

{ "name": "query_order_status", "description": "查询用户订单的当前状态。当用户询问订单配送进度、物流信息、发货时间、包裹状态时，可以使用此技能。当用户询问退款申请或售后问题时，请勿使用此技能，应转交售后处理。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "用户的订单编号，格式为字母O开头加8位数字，如O20250001" }, "user_id": { "type": "string", "description": "用户账号的唯一标识" } }, "required": ["order_id", "user_id"] }, "output": { "type": "object", "properties": { "status": { "type": "string", "enum": ["pending", "shipped", "delivered", "cancelled"] }, "tracking_info": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "location": { "type": "string" }, "event": { "type": "string" } } } } } }, "examples": [ { "user_input": "我的订单O20250001发货了吗", "parsed_params": { "order_id": "O20250001" } } ] }

这样一个结构化的技能定义，才是能被Agent稳定解析和调用的最小单元。如果你只是写一段自然语言告诉模型调用某个函数，那本质上是Prompt工程，不是技能库。

2.2 技能描述：这是模型的“眼睛”，不是写给人看的

技能描述是整个技能体系中最被低估的部分。很多人在描述里写“本技能用于处理订单相关事宜”，或者干脆写“调用这个工具可以帮助用户查询订单”，这种描述基本等于没写。模型面对这种描述，只能靠猜——猜对了皆大欢喜，猜错了就疯狂触发误调用。

正确的写法是：用动作触发条件覆盖该用场景，用排除规则划定不该用场景。比如天气查询技能，你要写清楚“当用户询问今日、明日、未来一周的天气情况、温度、降水概率、风力时，可以使用此技能。当用户询问气候特征或季节温度趋势时，请勿使用此技能，应转由数据分析技能处理。”这样模型在遇到问题时，才能像查字典一样准确匹配。

我专门踩过这个坑。早期设计的技能描述里没有做“不该用”的约束，结果一个订单查询技能，在面对“我想申请退款”时，模型会强行把用户的话往“查询订单状态”里套，返回一个“订单已送达”的上下文无关回复，用户体验极差。后来补上排除规则，模型才真正学会“知道什么不该做”。

除了覆盖正反场景，还有一个细节容易被忽略：描述里要写清楚输入约束。比如订单编号有特定格式，你在描述里写“格式为O开头的8位数字”，模型在解析用户输入时就会自动过滤掉不符合条件的内容，减少后续参数校验的负担。我在实际项目里深切体会到这个写法的价值——不做输入约束的Agent，解析出五花八门的数据，最后兜底的全是代码。

2.3 参数与输出结构：把不确定性关在笼子里

Agent调用技能，最怕的就是参数解析不固定。今天模型给你返回字符串，明天它可能就返回数组，后天又给你带上单位符号。如果不界定清楚参数，你的下游代码只能不停写兼容逻辑，时间全花在处理模型的不稳定输出上。

JSON Schema是目前最靠谱的参数定义方案。它的好处是结构精确，支持必填校验、类型约束、枚举限定。更关键的是，现在主流的模型都对JSON Schema有很好的理解和生成能力，你只要把Schema嵌入技能定义，模型输出的参数结构基本不会乱。

需要注意的是：不要把所有参数都设计成必填。就我在agent-skills里的实践来看，技能参数应遵循“核心必填、扩展可选”原则。比如查询订单技能，order_id可以必填，但返回物流轨迹的时间范围就是可选。这样设计的原因是模型在信息不完整时需要有能力“继续追问用户”而不是硬着头皮填一个假值。如果你把所有参数都设为必填，模型会编造数据以满足格式要求，这种错误更难排查。

输出结构同样要严格定义。我们允许模型用自然语言回复用户，但技能调用本身返回的数据结构必须是规范化的。status字段用枚举值，时间字段统一ISO格式，金额字段统一用数字类型。这些约束在技能定义阶段写清楚，后面做数据可视化、做统计分析、做前端展示时才会省心。

2.4 技能路由：模型自动决策 + 规则干预的混合模式

技能库搭建好之后，下一个问题就是：模型面对多个技能时，怎么知道该选哪一个？这就涉及路由机制。

agent-skills里默认的路线是用决策引擎，把当前用户消息和已定义的技能描述一起交给模型，让它自己判断应该调用哪个技能。这种方式灵活度高，适合技能数量少、边界清晰的场景。但技能数量一旦超过15到20个，模型的选择准确率就开始下降，会出现在两个相似技能之间犹豫不决，甚至选错技能的情况。

我的做法是在纯模型决策之上加一层规则干预。两种约束比较常见：一是针对带明显特征的输入，直接做关键词或正则预匹配，比如用户消息里包含“订单”“快递”“物流”，直接映射到订单查询技能，不走模型决策；二是技能优先级加权，给一些核心技能更高的默认权重，同时在用户消息里出现特定意图时，对所有技能描述进行排序后截断，只让模型在Top3到Top5的技能里选。

结合这两层，Agent的技能选择准确率会明显提升。我在自己的测试集里实测过——纯模型决策的准确率在83%左右，加上预匹配和权重干预后能提升到95%以上。这个提升不是模型变聪明了，而是你帮模型排除了大量干扰项，让它在有限的选择里做出更准确的决定。这就像你问一个人“午饭吃什么”，他可能纠结一小时；但你把菜单帮他减到三样，他几秒钟就能定。

3. 手把手搭建一个可用的技能库

3.1 明确场景边界：先盘点，再动手

搭建技能库不能上来就写代码。我习惯先做一个动作：梳理场景清单。把业务方提供的所有用户诉求列成一张表，然后逐条判断哪些是“单一技能可以解决的”，哪些是“需要多技能配合的”，哪些是“根本不需要技能的”。

这一步的价值在于避免技能数量的无脑膨胀。很多团队会把每个用户意图都变成一个技能，结果技能列表越来越长，模型每次决策的负担越来越重，准确率反而下降。合理的技能粒度是“一个技能覆盖一类场景”，而不是“一个技能覆盖一句话”。比如“查订单” “查物流” “查退款进度”，这三件事在系统层面是不同的接口，但在用户预期里高度相似，如果你把它们拆成三个独立技能，模型很容易混淆。更好的做法是合并成一个“order_query”技能，用参数里的query_type字段区分具体查询类型。

以下是我在一套客服Agent里做的技能盘点示例：

按这种思路盘下来，一个中等规模的客服Agent，首批技能控制在8到12个范围内就是很合理的量。有了场景清单，后续的技能定义、测试、迭代才有依据。

3.2 完整案例走通：从技能定义到调用全流程

这里用一个“查天气”的完整案例来演示。你可能觉得天气查询太简单，但恰恰是这种简单技能，能把整个链路讲清楚，而且这个技能里的经验可以直接平移到任何复杂技能上。

第一步，确定服务接口。我们的天气服务接收city和date两个参数，返回temperature、condition、wind等信息。接口本身很简单，但要让Agent稳定调用它，技能的描述和参数设计才是关键。

第二步，写技能描述。我经过多次打磨，最终用的版本是：“当用户询问某个城市在某个日期的天气情况、气温、降水概率、风力等级时，可以使用此技能。用户可能使用表述如‘明天上海冷不冷’‘杭州会下雨吗’。当用户询问平均气温、历史天气或气候宜适度时，请勿使用此技能。”这个描述在前半段给出了触发条件，在后半段排除了边界场景，模型选择准确率明显高于“天气查询工具”这种写法。

第三步，定义参数。city用字符串加枚举约束，可取值限定在中国主要城市。date用字符串类型，但描述里写清楚格式要求——尽量精确到日期，若用户未提供日期则默认当天。

第四步，实现调用。以下是一段调用逻辑示例：

import json import requests def call_weather_api(city: str, date: str) -> dict: """统一封装天气服务调用，降低上游变更影响""" base_url = "https://api.example.com/weather" params = { "city": city, "date": date, "fields": "temperature,condition,wind,humidity" } response = requests.get(base_url, params=params, timeout=10) response.raise_for_status() data = response.json() return { "city": data["city"], "date": data["date"], "temperature": data["weather"]["temp"], "condition": data["weather"]["text"], "wind": data["wind"]["dir"] + " " + str(data["wind"]["scale"]) + "级", "humidity": data["weather"]["humidity"] } def handle_weather_intent(params: dict) -> str: """技能执行入口：解析参数、调用服务、拼装回复""" city = params.get("city") date = params.get("date", "today") try: data = call_weather_api(city, date) return ( f"{data['city']} {data['date']}天气：{data['condition']}，" f"气温{data['temperature']}℃，风力{data['wind']}，" f"湿度{data['humidity']}%" ) except requests.RequestException: return "抱歉，天气服务暂时不可用，请稍后再试。"

第五步，写示例。给模型提供一到两个完整的“用户输入 → 解析结果”配对示例。比如“明天北京适合穿什么”应该被解析为city=北京、date=明天，而不是当成穿搭咨询去触发其他技能。这个示例不仅在决策时给模型做了示范，还在解析阶段约束了模型的思路。

完成这五步，一个技能就算落地了。回看整个流程你会发现，代码实现的比例其实很小，大部分工作量是花在定义清楚“技能边界”和“参数约束”上。这个比例是合理的，Agent的开发重心本来就该放在接口契约的设计上，而不是业务逻辑的堆砌。

3.3 技能注册与清单维护：把技能库当成产品来经营

技能库跟代码库一样，需要版本管理、灰度发布和回归测试。在agent-skills项目里，我专门给每个技能加了一个version字段，技能定义有任何变动，版本号必须递增。

我把技能清单放在一个JSON或YAML文件里，供决策引擎加载。当一个技能处于灰度期时，它的权重会被调低，让模型优先使用旧技能。等新技能在一批测试样本上稳定通过，再逐步放量。别轻视这个流程——我试过把新技能权重拉满，结果模型行为立刻变化，连老场景的准确率都被拖累。

技能清单的维护节奏也要固定。我在两周周期内做的例行动作是：挑出决策错误的样本，逐条分析是模型理解问题还是技能描述问题。大部分是描述问题，修改描述后重新跑测试集验证，验证通过再上线。这个节奏看起来慢，但对整个系统的稳定性非常值得。

3.4 从单技能到多技能协同：复杂任务怎么调度

单个技能跑通之后，紧接着就是多技能协作的问题。一个真实任务经常需要按顺序调用多个技能。比如“帮我查查昨天买的手机今天能不能到，顺便把发票开了”，这句话背后涉及订单查询和发票开具两个技能。

实现多技能协同的方案主要有两种。一种是把“多个技能串行调用”的逻辑显式写进代码里，即Agent先调用订单查询技能，拿到订单状态后再判断是否需要触发发票技能。另一种是让模型自己规划调用顺序，代码层只提供技能列表，模型输出技能调用序列，由执行引擎逐个执行并汇总结果。

两种方案各有利弊。显式串行调用可控性强，但适用面窄，每新增一种组合场景就要写一份编排逻辑。模型自主规划灵活，能应对未知组合，但结果不稳定，偶尔会跳过必调用技能。我的建议是：核心链路用显式编排，长尾场景让模型自由发挥。比如售后流程这种每个环节都敏感的场景，直接用代码把订单查询、物流更新、退款申请串成固定链路；而像“帮我查一下明天上海天气，顺便订个闹钟明早7点叫醒我”这种跨域组合，就交给模型自主规划。

实际项目中，我见过把多技能协同做得很复杂却依然毛病的案例。比如某类场景需要模型做多个工具的串行调用，但工具返回的结果格式不统一，导致下一步的参数拼接出问题。这时候的解法不是让模型更努力，而是把工具输出统一成标准中间格式，让模型不需要理解不同系统的差异。

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

4.1 模型反复选错技能，问题往往出在描述太宽泛

这是整个技能库搭建中出现频率最高的问题。具体表现是：用户说了一句与技能沾边但意图不同的话，模型仍然触发了错误技能。典型的案例是用户说“我想退货”，模型却触发了“查订单状态”——因为它看到了“订单”这个词。

排查思路不是换更大参数的模型，而是回头看技能的description有没有写排除规则。我在实操中总结出来的排查步骤大致是：把所有决策错误的样本收集起来，按错误类型分组，看是“错误触发”还是“漏触发”。错误触发就是不该用的时候用了，漏触发就是该用的时候没反应。前者继续看描述里的排除规则，后者就看示例数量和质量够不够。

优化的时候，把正例和反例以“if...else...”的句式写进描述里，效果通常比我预期的要好。比如“当用户询问订单状态时使用；当用户要求退货或退款时，请勿使用，应调用after_sale_service技能”。这样模型就能形成清晰的识别边界。

4.2 参数解析五花八门：欠约束比过约束更可怕

模型把参数解析出各种古怪结构，是高频故障点。我见过模型把“用户说今天下午”解析成“2025-01-28 14:00:00”，也见过把“上海”直接当成城市传进去，但系统里根本没有这个城市的枚举值。

核心解法是在参数定义里加强约束、弱化灵活性。在agent-skills的参数Schema里，能枚举的字段不要用自由字符串，能用正则约束的字段就写正则。但同时也注意不要过度约束——系统里没有的地区，即使硬填也是白搭，模型如果解析不出来的场景，宁可让它保持“unknown”并触发追问流程。

处理这类问题，我的原则是：参数定义越具体，模型输出越可靠。与其让下游代码包容各种奇怪的参数格式，不如让模型在源头就按标准格式输出。这条原则我是在吃了大量亏之后才真正内化的。

4.3 多技能上下文互相干扰，Agent干着干着就“失忆”了

另一个常见问题出现在长对话场景中。用户先聊了订单问题，又转去问商品库存，再回来问订单时，Agent可能已经开始混乱——它不确定现在该调用哪个技能，甚至会在回答库存问题时误带出订单状态的信息。

根源在于模型的全量对话上下文权重排序问题，历史消息对当前决策的影响不总是可控的。我的解法是：每个技能执行完，把该技能的关键输出写成一份“当前会话状态摘要”，在下一轮决策时优先读取摘要，而不是让模型整个对话历史里自己找信息。这相当于给Agent加了一层短期记忆管理。

你可以想象成办公场景：桌面堆了一堆文件，与其让新人把所有文件都翻一遍找资料，不如提前在便利贴上写好“第3份文件里有你需要的信息”。摘要就是这个便利贴。

4.4 技能数量膨胀后准确率下降，需要定期精简合并

技能库运营一段时间后，大概率会出现“技能越加越多，准确率越来越差”的局面。原因不难理解：技能数量增长，决策空间变大，模型选择的难度也随之上升。更麻烦的是，很多新技能和旧技能在描述上高度重叠——比如“查物流”和“查配送进度”本质上是一回事。

我对技能库的维护不搞一刀切，而是每个季度做一次系统性的“技能收敛”检查。把所有技能按描述相似度做聚类，找到相似度高于85%的技能组，逐组判断是否可以合并。合并的方法就是把这些技能统一成一个，使用子字段区分具体场景。这个动作很有效，能让技能数量降低20%到35%，但决策准确率反而是上升的。

技能清单本质上是给模型看的“目录”。目录章节越少，条目越清晰，检索效率越高。

5. 实测下来更推荐的一些做法与源码级建议

项目做到这个阶段，我对agent-skills最有价值的不是那些华丽的路由策略，反而是一些“脏活累活”的细节。这里挑几个我强烈推荐的做法分享。

关于输出格式的稳定性，我强烈建议在你的技能定义里再加一个meta字段，用system指令约束模型的输出语言。很多Agent莫名其妙输出JSON格式或者是插了Markdown标记，都是因为少了这个约束。比如你可以在技能执行前加一句：“请直接返回自然语言结果，不要附带JSON标记或Markdown格式。不要在回复前添加任何说明文字。”这对后续展示层做渲染能省掉大量清洗代码。

调试技能库时我给多数技能都写了一个--debug参数。当Agent决策异常时，可以通过在用户消息里附加标志打开调试，看到当前模型认为要调用的技能列表、每个技能的打分、最终选中的技能。这个手段极其实用——光靠肉眼观察Agent的输出，你会完全搞不清它为什么选错。

还有一个心得是：技能描述对于“冷启动”非常敏感。新技能的初始版本，我会把描述写得比最终版详细50%左右，给模型足够的信息量去试错，等测试样本稳定了再逐步精简。过早把描述写得太精简，模型发挥的空间反而更大，错误也更隐蔽。

最后说一个我反复提到的方法论：技能库的设计不是一次性的。Agent上线后，技能描述、参数定义、路由策略都应该是可迭代的。我一般以两周为一个周期，收集真实场景的调用日志，抽样分析决策质量，把每一条失误案例都改回技能描述和示例里。坚持做下来，整体准确率才会有肉眼可见的提升。