企业官网建设流程全解析

做 Agent 的人迟早会面对同一个问题：技能（Skills）越来越多，系统越来越乱。刚开始你可能只有两三个工具函数，觉得一切尽在掌握；后来为了应付各种场景，不停地加新技能，加到最后，光是理清"哪个技能负责什么、哪个参数该怎么传"就够叫人崩溃。我见过不少项目，功能都能做出来，但代码、配置、提示词全揉在一起，改一个地方崩三个地方，调试全靠缘分。这篇文章想聊的就是怎么系统性搞定 Agent 的 Skills 体系，从定义、设计、落地到排查，把混乱挤出去。不管你是刚接触 Agent 开发，还是已经在这坑里挣扎了一阵子，这篇实战指南应该都能帮你把思路捋顺。

1. 为什么会一团糟：Agent Skills 的混乱根源

先别急着谈最佳实践，我们得先搞清楚一件事：混乱到底是怎么产生的。很多人以为问题是"技能太多了管不过来"，但根据我实际调试过的项目来看，真正的原因往往是下面三个。

1.1 技能的定义太随意，边界模糊

最常见的做法是：今天业务方提了个需求，我就在代码里加一个函数，顺手注册成 skill。明天又提一个类似需求，再复制粘贴改一改。慢慢地，你会发现有两个技能干的其实是同一件事，只是入口参数不一样、描述文字的措辞不同。更麻烦的是，有些技能之间还有隐含的先后关系——必须先调 A 拿到某个 id，才能调 B。这种依赖关系没有任何地方写清楚，全靠开发者自己脑子里记着。

我在一个模拟项目里见过最典型的例子：有个"查询天气"的技能，和"查询城市信息"的技能，两者接收的参数都是城市名，返回结果里都包含温度字段。结果模型经常把需要查天气的请求路由到城市信息技能上去，返回一堆跟用户问题无关的数据。这就是典型的边界模糊导致的调用错乱。技能不是越多越好，而是每个技能都应该能回答清楚三个问题：我是干什么的？我需要哪些信息？我在什么场景下不该被调用？

1.2 描述文字没写明白，模型全靠猜

这是最容易忽略、但影响最大的一个因素。很多人写技能描述的时候，就写一句"查询订单状态"，完了。可模型是需要靠描述来决定调用哪个技能的，它根本看不到你的函数实现。你写得太笼统，模型就只能猜。

我习惯把技能描述当成"给一个不太聪明的实习生看的操作手册"来写。光说"查询订单状态"没用，你得说清楚：什么情况下用这个技能（比如用户询问物流、配送、订单进度时）、什么情况下不要用（比如用户要退款、要开发票，那是另外的技能）、参数是什么格式（订单号一般是纯数字还是带字母前缀）。描述写得越具体，模型的调用准确率就越高，这是实测下来最立竿见影的优化手段。

1.3 缺少统一的管理机制, 技术债越欠越多

第三个根源是工程层面的：很多项目的技能代码分散在各个模块里，有人写在业务逻辑中间，有人单独建了个 tools 目录，还有人干脆在系统提示词里用自然语言描述技能，让模型"自由发挥"。这种做法的短期成本很低，但长期维护成本极高。

一旦技能数量超过十个，你就需要统一的注册表、统一的参数校验、统一的返回格式，以及统一的调用日志。没有这套机制，你根本不知道模型在真实对话里到底调用了哪些技能、调用成功没有、参数传得对不对。排查问题时全靠用户复现描述去猜，效率极低。

2. 先把地基打好：Skill 的最小骨架与设计原则

聊完了混乱是怎么来的，接下来看怎么解决。第一步不是写代码,而是先统一对 Skill 的认识：一个合格的技能，应该由哪几部分构成。

2.1 一个 Skill 的标准结构

不管用哪套 Agent 框架，底层逻辑都大同小异。一个 Skill 本质上就是一个带说明书的函数，说明书要讲清楚什么时候能用、需要什么参数。我通常用这样的结构来定义一个技能：

{ "name": "search_order", "description": "根据订单号查询订单的最新状态和物流信息。当用户询问‘我的订单到哪了’‘发货了没’‘物流进度’时使用。如果用户要改地址或退款，请改用其他技能。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号。平台订单号一般为12位纯数字" } }, "required": ["order_id"] } }

这里面每一样都不能省。name 是模型用来在候选列表里做匹配的标识，description 是模型判断"该不该用它"的依据，parameters 是模型提取参数的契约。这三者只要有一个写得含混，后面就一定会出问题。

2.2 设计原则：单一职责与最小参数

我把设计技能的原则总结成四句话：单一职责、最小参数、结构化返回、明确排除条件。

第一，单一职责。一个技能只做一件事。不要为了图省事把"查订单"和"查售后"合并成一个技能，共用一个函数。看似减少了注册数量，实际上却让模型的判断难度增大了：同一个技能内部还要再分逻辑，Prompt 写起来绕来绕去。

第二，最小参数。能用一个 order_id 解决的问题，就不要再加一个 user_id。参数越少，模型提取错误的概率越低。有些开发者喜欢把所有可能用到的字段都塞进参数表里，结果模型为了填全参数，反而把不存在的字段臆造出来。

第三，结构化返回。技能函数返回给模型的内容，不要用一大段自然语言，尽量返回 JSON 或简单的 Markdown 表格。模型对结构化文本的解析效率更高，也方便后续做缓存和日志分析。

第四，明确排除条件。在 description 里写清楚"什么情况不要调用这个技能"。这一点经常被忽略，但它是区分相似技能的关键。说白了，你在告诉模型边界在哪里。

3. 实战：从零搭建一套可用的 Skill 体系

原则讲完了，下面进入实操环节。我以一个典型的客服问答 Agent 为例，完整走一遍从零搭建 Skill 体系的过程。这套流程我在多个模拟项目里验证过，能直接照搬。

3.1 盘点场景，确定技能清单

动手写代码之前，先做场景盘点。把用户可能问的问题列出来，归类整理。比如客服场景可以分成五类：订单查询、物流跟踪、退换货、发票开具、优惠券使用。每一类下面再细拆成具体的原子操作。

盘点的关键不是"能想到多少技能"，而是"技能之间不重叠"。我通常会让两个技能的描述在语义上的重合度越低越好。如果发现两个候选技能都在回答"订单怎么样了"这一类问题，那就要么合并，要么把各自负责的子场景说得更清楚。这个过程有点像数据库建模里的范式设计，先分好，后面才能少改。

3.2 用注册表模式管理技能

技能清单确定后，我推荐用注册表模式来管理。核心思路是：所有技能都统一注册到一个全局字典里，由注册器负责元数据管理和函数调度的绑定，而不是散落在各处。下面是我常用的框架：

SKILL_REGISTRY = {} class SkillSpec: def __init__(self, name, description, parameters, handler): self.name = name self.description = description self.parameters = parameters self.handler = handler def register_skill(name, description, parameters=None): def decorator(func): SKILL_REGISTRY[name] = SkillSpec( name=name, description=description, parameters=parameters or {}, handler=func ) return func return decorator

定义好注册器之后，每个技能只需要用装饰器标注一下就能接入系统：

@register_skill( name="search_order", description="根据订单号查询订单的最新状态和物流信息，适用于用户询问发货、物流进度等场景。", parameters={ "type": "object", "properties": { "order_id": {"type": "string", "description": "12位纯数字订单号"} }, "required": ["order_id"] } ) def search_order(order_id: str): # 调用内部服务，返回结构化结果 return fetch_order_detail(order_id)

这样做的好处有两个：一是新技能接入成本极低，只需要新写一个函数加一行装饰器；二是后续要做清理或审计时，所有技能的元数据都在一个字典里，随时可以导出。

3.3 把技能描述交给模型"审稿"

注册表写完后，有一个很多人不愿意做但我强烈建议做的动作：把全部技能描述拼成一段话，塞给大模型，让它自己"审稿"。让模型看看两两描述之间是否有语义重叠，是否有哪些用户问题找不到合适的技能接。

这一步在开发阶段做特别划算。因为等到上线后模型调错技能，你再回头查是哪个描述写得有歧义，成本就高了。我自己会在每次新增技能后跑一遍这个自查流程，把模型标记为"易混淆"的描述拿出来改，很多潜在的调用混乱在上线前就消掉了。

3.4 让模型正确调用技能的几个技巧

框架搭好之后，接下来是最考验细节的部分：让模型稳定地、正确地调用技能。这里有几个我实测过很有用的技巧。

第一，给关键技能提供示例。有些框架支持在技能定义里附加 usage 示例。比如"用户问：我的快递到哪了。输出：调用 search_order，参数 order_id=202403120001"。有了示例，模型照着例子走的准确率会明显提升。

第二，控制每次提供给模型的技能数量。如果系统里有三十个技能，不要一次性全塞给模型。模型在大量候选里做选择时，注意力会被稀释。比较好的做法是分两层：先用一个粗粒度的路由器技能判断用户意图属于哪个域，再只把该域下的几个技能作为候选取出。

第三，定义兜底技能。无论你设计得多好，总有模型拿不准的时候。一定要有一个 fallback 技能，专门处理"没有其他技能匹配"的情况。它通常返回一个默认回复，或者把问题转给人工客服。别让模型在没匹配时硬编一个技能名出来，那是最难排查的 bug 之一。

3.5 执行流程与上下文回填

技能被调用后，返回的结果怎么回到对话里，也需要统一约定。我的习惯是：技能返回的原始 JSON 先经过一层格式化，转成人类可读的自然语言摘要，再拼接进上下文，最终由模型生成面向用户的回答。直接拿着 JSON 去给模型，模型虽然也能理解，但组织出来的语言往往生硬。中间加一层摘要，回答质量会稳定不少。

这一步还有一个容易踩的坑：上下文长度。技能返回结果如果很大（比如一份长文档），全部塞进上下文会挤占模型有限的窗口。我通常会对返回做截断或摘要，只保留最关键的那几个字段。实测下来，不仅 token 用量降了，回答反而更干脆，因为干扰信息少了。

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

技能体系跑起来之后，真正的考验在线上。我在多个项目里反复踩过一些坑，下面挑几个最常见的问题，以及对应的排查思路，整理成速查表。这些内容常规文档里不会写，但实战价值极高。

4.1 模型死活不调技能，或者调了错的技能

这是新人最常遇到的问题。模型不调技能，大概率是描述不够具体，或者候选技能太多导致选择困难。你可以在日志里记下模型在每一步的完整输出，看它到底是没识别出技能需求，还是压根没把描述当成候选。然后针对性做两件事：要么把描述里的触发词写得更明确，要么减少每轮候选技能的数量。

至于调了错的技能，绝大多数是描述之间存在语义重叠。排查方式是最小化重现：构造两个语义相近的测试问题，跑一遍，如果走错路由，就把两个技能的描述都拿出来逐句对比，找到重叠部分，用排除条件划清界限。

4.2 参数解析错误频发

模型提取参数时偶尔会抽取错误，比如把用户 ID 当成订单号传进去。这个问题我用两个手段压制：一是在参数描述里写清格式和校验规则，二是函数入口做严格校验，校验失败时返回明确错误信息，而不是直接抛异常。

我在实际项目中写过一个通用的参数校验装饰器：

def validate_required_params(func): def wrapper(*args, **kwargs): # 校验必填参数是否存在且类型正确 for name, value in kwargs.items(): if value is None or value == "": return {"error": f"参数 {name} 缺失", "need_retry": True} return func(*args, **kwargs) return wrapper

特别提醒：返回的错误信息里最好带上 need_retry 标记，让模型知道自己该重新询问用户还是换个参数再试。否则模型会把参数错误当成业务失败，回一句"查询失败"就完了，体验很糟糕。

4.3 技能执行抛异常，整个对话崩了

线上最致命的不是技能本身出错，而是一个技能出错把整个 Agent 对话流程带崩。无论技能内部是什么逻辑，暴露给调用方的一定得是"成功的返回值或失败的结构化错误"，绝对不能是裸奔的 exception。

我处理这个问题的思路是：在注册器这一层做统一异常捕获。这样即便某个技能内部代码写得不严谨，错误也会被拦截在调用边界上，不会影响整个 Agent 的状态机。同时把异常信息记录到日志里，并返回给模型一个可理解的提示，让模型可以优雅地告诉用户"这部分暂时不可用，请稍后再试"或者转人工。

4.4 线上问题排查实录

分享一个具体的排查案例。有段时间线上反馈说 Agent 经常答非所问，我拉出调用日志后发现，某个查询类技能在一天内被调用了几千次，但其中四成调用的参数都是同一个错误值。进一步追查才发现，是新版本上线时，参数 schema 里的字段名改了，但旧对话里模型仍然按照旧字段名提取参数，导致校验失败。

这个问题的根因在于没有字段名兼容层。后面我专门加了一块参数归一化逻辑：在真正的技能函数执行之前，把历史用过的同义字段映射到新字段上。所以从那时候起，我给自己立了个规矩：技能参数名一旦对外公布，就不要轻易变更，实在要改，必须在注册层做迁移映射，而不是直接删字段。这个教训很值钱，帮我在后来的项目里省了一堆麻烦。

5. 版本管理与持续迭代：让技能体系长期不乱

很多人以为把技能跑通就算完事了，但其实真正让体系保持不乱的，是后续的维护节奏。最后一节聊一聊上线之后的版本管理和迭代策略。

5.1 给技能加版本号和变更日志

技能也是代码，同样应该享受版本管理的待遇。我建议每个技能在注册表里带上 version 字段，并在元数据里记录最近一次变更的原因。这样当线上行为异常时，你可以快速看出是不是某个技能的最近一次变更引起的。

这里有一个很实用的做法：把技能的"变更日志"也作为一段元数据暴露在开发环境里，方便同事 review 和回滚。比如你改了一个技能的描述，从"支持查询订单状态"改成"支持查询订单状态和预约取件",结果某些本应调用其他技能的问题被它抢走了。有了变更日志，你就能把改动还原到上一个版本，或者重构描述来避免边界侵占。

5.2 灰度发布与线上监控

技能变更不像后端接口那样可以直接灰度，因为模型是概率性的，同一套定义在不同对话里表现可能不稳定。所以更稳妥的办法是：新旧两版技能同时注册，用一定比例流量走新版、大部分流量走旧版，对比调用成功率和用户满意度后再逐步切流量。

监控指标方面，我只关注三个核心指标：技能调用成功率、参数解析通过率、以及技能被模型选中后返回结果被采纳的比率。前两个指标反映工程层面是否健康，最后一个指标间接反映描述是否匹配用户意图。任何一个指标的异常波动，都应该触发告警而不是等用户投诉。

5.3 从混乱到规范的三个习惯

文章写到最后，我想分享三个让我自己受用很久的小习惯。

第一个习惯：每次新增技能，先写描述，再写函数。很多人倒着来，函数写完了随手补一行描述。先写描述的好处是，你会被迫先把"这个技能到底该管什么"想清楚，函数只是把描述翻译成代码。

第二个习惯：定期整理淘汰技能。我每两个月会跑一遍调用统计，找出一个月内调用量为零或极低的技能，评估它是不是该被下线了。很多技能当初是拍脑袋加的，实际场景里根本没人触发。技能太多本身就是混乱的来源，删掉不需要的，系统立即清爽很多。

第三个习惯：把技能体系的审查纳入代码评审流程。任何技能变更，不只是看代码逻辑，还要让其他开发者看看描述是否准确、参数是否合理。一个人写的描述总有盲区，多一个人看，就多一层纠错机会。

这些是我在不同项目里反复试错后沉淀下来的方法。Agent 技术本身迭代很快，但"如何把系统组织得井井有条"这件事，永远不会过时。希望这份实战指南能帮你少踩一些坑，也欢迎你在实践后回来交流你自己的技巧。