企业官网建设流程全解析

1. agent-skills到底在解决什么问题

最近大半年，我一直在折腾基于LLM的Agent项目，陆陆续续接手过几套不同团队留下的代码基座，发现一个非常普遍的现象：大家在初期Demo阶段跑得飞快，各种花哨的Agent能力都能演示出来，但只要一进入真实业务场景，立刻被一堆细节问题卡死。比如同样的一个查询天气的能力，A项目写死在Prompt里，B项目做成了函数调用，C项目又封装成了独立的微服务，换个人接手根本不知道该怎么复用。更麻烦的是，只要你敢让Agent多干几件事，它的行为就开始飘，有时候调用错工具，有时候干脆自己编一个结果出来。

这些问题归根到底，都指向同一个痛点——Agent缺少一套结构化的技能体系。光有模型能力不够，你得把模型的推理能力跟外部工具、内部流程、业务约束系统地组合起来，让Agent知道自己有什么技能、什么时候该用、怎么用、用完之后怎么收尾。这就是我理解的"agent-skills"，一个关于如何设计、实现、维护Agent技能集合的完整方法论。

这篇文章不是讲某个具体框架的API怎么调用，而是想把我自己在实际项目里踩过的坑、验证过的方案、沉淀下来的设计套路整理出来。适合谁看？适合那些已经跑通了一个简单的Agent Demo，但正在发愁怎么把它做成一个真正能扛住业务压力的人。也适合刚接触Agent开发、想避开一些常识性坑的初学者。我会尽量用大白话讲清楚，也会给出可以直接复制的代码结构和配置方案。

2. 先把技能这件事想清楚

2.1 技能不只是"调一个API"

很多人一提到给Agent加技能，第一反应就是"多接几个API"。这种思路不能说错，但很容易把一个本该稳健的系统做成四处漏风的脚手架。我见过一个团队接入了十几个第三方接口，结果Agent经常搞混参数，把给CRM系统的数据发到了监控系统里，排查了半天才发现是技能描述写得含糊，模型压根分不清两个工具的边界。

真正的技能设计，应该把"工具调用"这个概念再往上抽象一层。一个技能应该是一个完整的、自包含的能力单元，它要回答清楚四件事：这个技能在什么场景下触发，它需要哪些输入信息，它内部如何执行，它返回什么结果以及结果如何被上层使用。你甚至可以把它理解成一个微服务——有明确的接口契约、有内部实现、有错误处理、有版本管理。唯一的不同是，它的调用方不是另一个程序，而是一个语言模型。

我在设计技能时，最早犯的错误就是把技能定义得太"功能化"。比如我封装了一个"查订单"的技能，但实际上业务方要的是"用户问订单到哪了"这个意图的完整处理链路。这两者的差别在于：功能化的技能只拿到订单号去查物流状态，意图化的技能要先判断用户是想查物流、想改地址还是想催发货，然后才决定调用哪个底层函数。如果只做前者，你会发现Agent在面对稍微复杂一点的用户问题时，依然会手足无措。

2.2 技能拆分的粒度怎么把握

技能的粒度是个典型的"看着简单、做起来要命"的问题。拆得太细，Agent要在几十个技能里做选择，决策成本高，还容易选错；拆得太粗，每个技能内部塞了一堆逻辑，难以复用，也不好维护。我自己的经验是：以"一个完整的用户意图闭环"为粒度基准，而不是以"一个底层操作"为基准。

拿电商客服场景举例。"查询订单状态"和"修改收货地址"是两个独立的技能，因为它们的触发意图明确、边界清晰、内部逻辑互不交叉。但如果把"查订单"拆成"查订单基本信息""查物流轨迹""查售后进度"三个技能，就明显过度了，因为用户通常不会刻意区分这三者的边界，Agent判断起来也费劲。这时候不如合并成一个"查询订单全貌"的技能，内部透出结构化结果，让模型自己决定怎么回答用户。

另一个维度是考虑复用性。如果一段逻辑将来大概率会被其他Agent场景复用，那就值得单独拆成技能；如果只是当前场景一次性用掉，那放在工作流里就好。比如"从用户历史消息中提取手机号"这种技能，大概率所有客服场景都会用到，值得独立；而"根据商品ID生成推荐话术"这种强业务绑定的逻辑，就不必急着抽出来。

2.3 技能的描述是给模型看的"说明书"

一个特别容易被忽略的点是：技能的description字段，某种意义上比技能本身的实现还要重要。因为模型就是靠这段描述来判断"我现在该不该调用这个技能"的。描述写得太泛，模型会在不该用的时候乱用；描述写得太细，模型抓不住重点；描述里用了跟其他技能重复的关键词，模型就会懵。

我在一个项目里吃过亏：给两个技能分别写了"查询用户会员等级"和"查询用户积分余额"，description都很简短，结果模型经常把查积分的请求打到会员等级接口上，返回的数据驴唇不对马嘴。后来我把两个描述改成了带触发条件、输入要求和业务场景的完整版本，错误率立刻降了很多。现在我对description的要求是：包含触发条件、输入字段说明、输出结果说明、使用限制或禁忌。写完之后反复读几遍，想象自己是一个啥都不知道的模型，看到这段描述能不能准确判断"该不该调用"。

3. 技能体系的核心设计：从数据结构到调度逻辑

3.1 技能注册表：给每个技能建立"户口"

当你手里的技能超过五个之后，就必须引入一个统一的注册管理机制。我这里推荐一个很实用的做法——技能注册表（Skill Registry）。每个技能在注册表里都有唯一标识、名称、版本号、依赖关系、描述信息、执行入口和参数Schema。这样一来，Agent的调度层只需要跟注册表打交道，而不是跟几十个散落的函数打交道。

下面是我常用的技能注册表的Schema示例，参考价值比较高：

{ "skill_id": "order_query_v3", "name": "查询订单全貌", "version": "3.2.0", "description": "当用户查询订单状态、物流进展、售后进度时使用。输入需要order_id或用户手机号。返回订单基本信息、物流轨迹及售后状态。注意：本技能不处理改地址、退款等操作。", "input_schema": { "type": "object", "properties": { "order_id": {"type": "string", "description": "订单号，长度通常为18位"}, "phone": {"type": "string", "description": "下单手机号，与order_id二选一"} }, "required": [] }, "output_schema": { "type": "object", "properties": { "order_status": {"type": "string"}, "logistics": {"type": "array"}, "after_sale": {"type": "object"} } }, "dependencies": ["user_auth", "order_api_adapter"], "tags": ["order", "customer_service"], "timeout_ms": 3000 }

这段JSON看起来简单，但几个字段的取舍值得展开说。version字段不只是给自己看的，更要紧的是，模型在理解技能变更历史时能拿它做参照。tags字段用来做粗粒度的初始筛选，避免模型每次都把所有技能描述塞进上下文里，省token也省决策时间。timeout_ms则是对技能执行的最长等待时间，超时了必须有兜底逻辑，否则Agent会一直傻等。

3.2 技能调用协议：让模型和技能之间"讲规矩"

技能注册表解决的是"有什么技能"的问题，但模型跟技能之间怎么协作，还需要一套明确的调用协议。我的做法是定义一个统一的函数调用规范，把所有技能都包装成同一个模式的函数，对外暴露统一的入口。这样做的好处非常明显：调度层不需要针对每个技能单独写适配逻辑，新增技能的成本降到最低。

我推荐一个三段式协议：意图识别、参数提取、执行确认。意图识别由模型完成，它根据用户输入和技能描述判断该调用哪个技能；参数提取要求模型从对话上下文中抽取出调用技能所需的参数，抽取失败时要主动向用户追问补齐；执行确认则是在调用前把解析出来的参数展示给用户或上层系统确认一遍，避免误操作。这个协议看起来多了一步"确认"，但它能拦下大量因为模型参数幻觉导致的错误调用。

我自己在实现参数提取时，会额外要求模型输出一个confidence字段，表示它对参数匹配的把握程度。当这个值低于阈值时，系统自动转人工或发起澄清式追问，而不是闭眼执行。这个设计救过我很多次，尤其是处理那种用户语焉不详的请求时，效果立竿见影。

3.3 技能编排：多个技能如何协同作战

单技能调用只是基本功，真正的复杂度来自多个技能的编排组合。比如用户问"我昨天买的东西怎么还没到，能不能帮我把收货地址改成公司？"，这个请求同时涉及查订单、查物流、改地址三个技能，而且它们之间有明确的先后依赖关系：先查订单拿到订单号，再查物流确认状态，最后才能改地址。

我对多技能编排的处理思路是：优先让模型自己生成编排计划（Plan），但必须用结构化的方式表达。具体来说，就是要求模型输出一个包含多个步骤的执行计划，每个步骤绑定一个技能和预期输出，系统按计划逐步执行，每步结果回填给模型再决定下一步怎么走。这种做法比让模型一口气调完所有技能稳妥得多，因为中间任何一步出错了，都能及时纠偏。

def execute_plan(plan: list[dict], registry: SkillRegistry): context = {} for step in plan: skill = registry.get(step["skill_id"]) result = skill.execute( inputs=resolve(step["params"], context) ) context[step["name"]] = result if not result.is_success: # 中间步骤失败，触发兜底逻辑 return fallback_handler(step, result) return context

这段伪代码展示的是一个最简执行引擎，实际项目里你还会加上日志、审计、超时控制、重试策略等。但核心思想是一致的：让模型当指挥官，让技能当执行者，中间加一层程序化的调度保障。

4. 实操记录：从零到一搭建一套Agent技能框架

4.1 第一步：先盘点业务场景，再决定技能清单

很多人的第一步是先去选模型、搭框架、写代码，但我强烈建议反过来——先做业务场景盘点。找业务方聊一聊，把用户最常问的50个问题拉出来，分类整理，看看到底需要哪些技能支撑。这个过程看起来很笨，但能把后面的返工成本降到最低。

我最近帮一个本地生活类项目梳理技能清单时，就是从客服聊天记录里筛出一批高频问题，然后逐个标注：这个问题需要哪些数据才能回答，需要调用什么系统，回答的正确形式是什么。整理完发现，真正核心的技能其实只有七个：门店查询、菜单查询、排队取号、优惠券核销、投诉建议、会员查询、订单查询。其他一堆听着高大上的需求，全是低频场景，根本不需要初期就做成技能。

4.2 第二步：搭一个最小可用的技能执行器

技能清单确定后，下一步就是搭执行器。我用的架构很轻：一个FastAPI服务做技能执行入口，一个SQLite表存技能注册信息，一个Redis做会话状态缓存，再加上一个LLM调度层。整个架子两百行代码就能跑起来。

执行器的核心是一个路由函数，它接收模型输出的结构化调用请求，然后根据skill_id匹配到对应的处理函数，执行完把结果包装成统一格式返回给模型。这个过程中，我最看重的是错误边界。每个技能执行都必须包一层try-except，返回的错误信息要带上错误码、可读的错误描述和可恢复的提示。为什么要这么做？因为模型在拿到错误信息后，会尝试自己修复——比如换个参数重新调用，或者向用户解释情况。如果你返回的是赤裸裸的堆栈信息，模型大概率会用一段废话来掩盖它的无能。

def execute_skill(skill_id: str, params: dict, session: Session): try: skill = registry.get(skill_id) if not skill: return SkillResult(err_code="SKILL_NOT_FOUND", err_msg="技能不存在") result = skill.run(params, session) return SkillResult(data=result) except TimeoutError: return SkillResult(err_code="TIMEOUT", err_msg="技能执行超时，请稍后重试") except BizException as e: return SkillResult(err_code=e.code, err_msg=e.message) except Exception: logger.exception("unexpected error in skill execution") return SkillResult(err_code="UNKNOWN", err_msg="系统开小差了，请稍后再试")

4.3 第三步：让技能执行效果"可观测"

技能上线后，最忌讳的就是"黑盒运行"——光知道它在跑，不知道它跑得好不好。我的做法是给每个技能加三件套：全链路日志、执行结果评估、调用频次统计。

全链路日志记录的是一次完整请求从用户输入到最终响应的全过程，包括模型调用了哪些技能、每步花了多少时间、中途有没有出错。执行结果评估更复杂一点，我会抽出一部分线上请求，人工标注"这次调用是否合理、结果是否正确"，然后把标注结果作为评测集，定期跑回归测试，防止模型升级或技能改动后出现行为退化。调用频次统计则用来判断哪些技能是高频刚需、哪些技能基本没人用，指导后续的优化投入。

这个环节还有一个务实的用途：它是你跟业务方之间最好的沟通语言。当业务方质疑Agent能力时，你甩出一份"本周技能调用分布报表"，比空口解释一百倍都有效。

4.4 第四步：技能测试与上线流程

技能的测试不能只靠联调冒烟，要建立一套针对性的评测用例。我自己的做法是给每个技能准备三类测试数据：正常输入、边界输入、恶意输入。正常输入好理解；边界输入包括参数缺失、参数类型错误、参数值超范围等；恶意输入则是故意构造的、容易诱导模型误判的请求，比如用户说"我没下单但你要给我查订单"或者"帮我查一下别人的订单"。

跑完测试不代表就完事，还要做灰度。我常用的策略是切一小部分流量到新技能版本，观察错误率和用户反馈，确认没问题再全量放开。灰度期间的监控指标至少要覆盖：技能调用成功率、平均响应时长、参数解析失败率、用户投诉率。任何一个指标出现异常，立刻回滚。

5. 典型问题与排障实录

5.1 模型选错了技能，怎么办

这是所有Agent项目里最常遇到的问题。模型明明有"查物流"的技能，它偏偏去调了"查订单"，返回了一堆无关信息。排查的第一步不是去改Prompt，而是去看日志——看看模型在决策时到底看到了什么。很多时候问题是出在技能描述上：两个技能的description有重叠关键词，或者其中一个写得太泛，模型分不清。

我整理过一个技能描述对照表，把容易混淆的技能放在一起改。比如"查订单"和"查物流"是重灾区，我会刻意在描述里强调边界："查订单用于获取订单的基本状态、商品明细、金额信息；物流轨迹查询请使用另一个技能，本技能不返回物流过程信息。"这种"我不管什么，你去找别人"的写法，能很有效地帮助模型做区分。

5.2 模型参数解析经常出错

参数提取是另一个高发问题。用户的表达千奇百怪，模型很容易提取出错别字、缺字段、张冠李戴。我最常用的一道防线是声明式校验：给每个参数都配上类型、格式、可选值和校验规则，在技能执行前先跑一遍校验，校验不过就返回需要补充信息。这套机制能拦住大约60%的参数错误。

剩下的40%，要靠追问机制兜底。校验失败时，系统返回一条"缺少必要参数：order_id"之类的信息，模型会据此向用户发起追问，而不是硬着头皮瞎猜。这里有一个细节：追问信息里最好给出示例或者期望的格式，比如"订单号一般是18位数字，可以在订单列表页找到"，用户配合度会高很多。

5.3 技能内部报错，怎么回退

技能内部依赖的第三方接口不可能永远稳定。我的兜底策略分三层：超时重试、备选路径、优雅降级。超时重试最好理解，对时效性要求不高的技能可以试着再调一次。备选路径是指同一个技能内部可以有多条实现路线，比如主接口挂了就切备用接口，甚至切到人工处理。优雅降级则是直接给用户一个说得过去的替代结果，比如查不到实时物流时，回复"目前物流信息更新有延迟，建议1小时后再查询"。

设计兜底策略时有一条铁律：宁可给用户一个明确的不完美答复，也不能让Agent假装自己完成了操作。我见过一些项目，技能内部抛了异常，模型为了表现得"有用"，硬是编造了一个成功的假象，那才是真正的事故现场。

5.4 上下文超长导致的技能调用失败

当对话轮次变多，上下文塞满了历史消息，模型的理解能力会明显下降，技能调用的准确率跟着掉。我的解决办法是引入上下文治理机制：每次模型决策前，先对上下文做一轮精简，把已经完成的信息摘要化，只保留当前决策真正需要的字段。这个操作能让长对话场景下的技能调用成功率提高不少。

另一个补充手段是给关键参数设立"会话级缓存"。比如用户在前面已经确认过手机号，后续的技能调用就不需要模型再去上下文里找，直接走缓存。这既降低了参数解析的错误率，也省了模型的推理时间。

6. 关于agent-skills的一些个人体会

这些内容写下来，其实就是一句话：Agent的能力上限，很大程度上取决于你给它配了哪些技能，以及这些技能被设计得有多靠谱。模型本身决定了Agent的天花板，但技能体系决定了Agent离这个天花板有多近。我踩过那么多坑之后，最大的体会是：不要迷恋花哨的模型调优技巧，踏踏实实把技能的定义、注册、执行、观测、兜底这一套基本功做扎实，你的Agent才能真正在业务里站住脚。

分享一个小技巧作为收尾：每个技能上线后，记得定期翻看真实的调用日志，尤其是那些"模型犹豫不决乱调技能"的case。每一次这类case，都是你优化技能描述和调用策略的绝佳素材。你不需要一口气做得完美，只要保持每个迭代都让技能的决策准确率往上涨一点，三个月后再回头看，你自己的Agent和最初那版Demo，已经是完全不同的两个东西了。