企业官网建设流程全解析

1. 从"工具调用"到"技能体系"：为什么你的Agent需要一个像样的"技能库"

最近在深度使用和二次开发AI Agent的过程中，我越来越强烈地意识到一个问题：大部分团队的Agent项目，一开始都能跑通Demo，但一旦进入真实业务场景，就迅速变得不可控。原因五花八门，但最核心的病灶，往往出在"工具层"——大家都叫它Tool或Function，可实际上它承担的职责远超"函数"本身。

我第一次意识到这个问题，是在一个真实项目里。当时我们的Agent需要处理订单查询、退货申请、优惠券核销、客服工单流转等多组任务。最早的做法很直观：给大模型挂上五六个Function，每个Function对应一个API接口，让模型自己根据用户输入选择调用。刚上线时效果还行，但随着业务逻辑复杂化，问题开始密集爆发：模型总是选错工具、参数传得乱七八糟、新上线的工具要等很久模型才能"学会"、同一个能力在多个场景里被重复实现、还有一堆没人维护的死工具挂在列表里白白占用上下文窗口。

后来我研究了一些头部团队的实践，包括LangChain、CrewAI背后的设计思路，又自己动手重构了一版，才慢慢摸清：Agent真正需要的不是一个个孤立的工具，而是一套可描述、可发现、可组合、可评估的"技能体系"。这几乎是所有"agent-skills"类设计的底层逻辑。技能不是API的简单封装，而是把API、参数约束、使用预期、触发条件、错误处理、成本提示打包成一个结构化单元，让大模型能"看懂"并且"用得对"。

这篇文章我就把整套技能体系的构建思路、关键设计、实战代码片段以及踩过的坑，完整拆开来写一遍。无论你是刚开始接触Agent开发，还是已经在生产环境里被工具调用折磨过一阵子，这篇文章应该都能给你一套可以直接落地的参考框架。

2. 技能描述是第一生产力：让大模型"一眼看懂"每个技能

很多初学者会低估一个技能描述的重要性。大模型不像传统程序，它没有关于你的代码逻辑的"文档意识"，它对一个技能的全部理解，都来自你在技能定义里给它的那段描述、参数说明和示例。你描述得不够清楚，它就只能在"模糊理解"里瞎猜——这不叫"模型不够聪明"，这叫"你的接口文件写得不好"。

2.1 一段合格的技能描述应该包含哪些"元信息"

我见过不少项目的技能定义就两行："search_order(order_id)"，完了。这种定义几乎等于让一个新手员工直接去干活，不给背景、不给边界、不给注意事项。经过几轮重构，我把一段合格的技能描述拆成了六个固定字段，每个字段都经过真实场景验证：

关键心得：description字段里，动词、对象、场景三者缺一不可。动词告诉模型这个技能做什么（发起、查询、修改、删除、通知）；对象告诉模型作用在什么业务实体上（订单、用户、工单、优惠券）；场景告诉模型什么样的用户意图应该路由到这里（"未发货取消""收到货不满意"）。我在实测中发现，description里一旦有了典型场景，模型的工具调用准确率会提升至少20个百分点，这不是玄学，而是大模型本身就是在语义空间中做匹配，你给的语义锚点越多，匹配越准。

2.2 参数schema设计的三个"反直觉"原则

参数设计是另一个容易出问题的地方。很多人在写参数schema时，只会机械地照搬API文档，结果模型传参总是出错。我总结了三条反直觉的经验：

原则一：能枚举就枚举，不要开放字符串。比如"退款原因"，如果写成自由字符串，模型可能传"质量不好""有问题""坏了""破损"等各种说法。一旦你把字段定义为枚举，比如reason: enum["damaged", "not_as_described", "wrong_item", "other"]，模型就会强制在有限集合里选择，下游逻辑只需要做精确匹配。别指望模型聪明到帮你标准化，你在一开始就把标准化做掉，后面能省无数脏活。

原则二：数值型参数要给出单位和边界。比如"金额"字段，很多人只写amount: number。模型完全不知道这个number是"分"还是"元"，也不知道有没有上下限。正确的写法应当把单位写死在描述的默认值或字段说明里，例如amount: number, description: "退款金额，单位：分，必须大于0且不超过订单实付金额，精确到两位小数"。单位一旦出了偏差，后端的校验逻辑就会把它当成垃圾请求打回来。

原则三：每个参数都带"从哪来"的说明。我在生产环境里发现，模型经常拿用户问题里的原话直接填参数，比如用户说"帮我退掉那个蓝色的衣服"，模型就把"蓝色的衣服"当商品名传进去。这时你需要在参数描述里加"本参数应从用户上下文中提取的商品ID，若无法明确提取则向用户追问，禁止猜测"，这能明显减少参数的幻觉式填充。

2.3 示例（few-shot）怎么放入技能描述

大模型对工具调用的理解很容易被示例左右。我在技能里固定加了两到三个输入输出pair，但有个细节：示例不要只放成功路径，一定要放一个"边界示例"。

比如退款技能，我给的示例大概长这样：

{ "user_input": "我昨天买的订单88888还没发货，想退掉", "selected_skill": "refund_order", "parameters": { "order_id": "88888", "reason": "not_as_described", "request_source": "user_self_service" } }, { "user_input": "帮我取消一个订单", "selected_skill": "clarify_required", "parameters": {}, "reason": "缺少订单号，无法确定退款对象，需要追问用户" }

第一个示例教会模型"看到什么输入该调用什么"，第二个示例教模型"信息不足时不能乱调"。实测中，边界示例能显著减少"模型在信息不全时强行调用技能"的问题。这个细节常常被忽略，但它是让技能调用更"懂分寸"的关键。

3. 技能注册、路由与执行：把一个技能库真正"跑"起来

有了规范的技能定义，下一步就是把技能组织成Agent能够调用的运行时体系。这里涉及技能注册中心、路由策略、执行沙箱、上下文追踪四块内容。我按模块展开，每个模块都会给出我在实测中验证过的方案。

3.1 技能注册中心：从"硬编码挂载"到"统一注册"

最早我写Agent工具时，是直接在系统提示词里把所有工具的JSON Schema拼好塞进去。技能少的时候没问题，技能涨到三四十个以后，整个提示词膨胀到爆炸，模型开始在长上下文里"迷路"——它忘了后面还有哪些技能可用，或者把两个相似技能搞混。

后来我改成了统一注册中心：所有技能以注册表形式存在，Agent启动时按需加载。注册中心保存的不只是技能定义，还包括技能的启用状态、版本号、所属业务域、授权角色、发布状态等信息。注册表的结构类似：

@dataclass class SkillMeta: name: str domain: str version: str enabled: bool description: str parameters_schema: dict required_skills: list[str] cost_hint: dict auth_roles: list[str] handler: Callable

信息都注册好之后，技能才能真正被系统统一管理。这里有一个很重要的设计选择：技能被加载进模型上下文的方式，应该由"技能选择器"决定，而不是把所有技能一次性全部塞给模型。这就是所谓"动态技能装配"。

3.2 技能选择器：如何在几十个技能里让模型不迷路

技能多起来之后，路由选择是最大难题。总不能让大模型从40个技能里挑一个。我的方案是两层筛选：

第一层：基于意图的粗筛。这层可以用一个轻量模型或者分类器，先把用户输入分到几个大领域（订单、售后、营销、账户……），每个领域挂对应的一批技能。粗筛后，候选技能被压缩到5个以内。

第二层：技能描述语义精排。在粗筛后的技能集合里，让主模型根据技能描述、用户输入、整体对话上下文选择最终要调用的技能。这一步与我在2.1节讲的"技能描述质量"强相关：描述写得越精确，精排准确率越高。

有人可能会问，为什么要分两层，不能直接让一个模型在同一轮里既分类又选技能吗？理论上可以，但实测下来，分类和选择耦合在一起时，模型在边界场景下经常被两个子任务互相干扰。先粗筛再精排，相当于把"选数据库"和"写SQL"分成两个步骤，错误率会明显下降。

3.3 执行沙箱与上下文控制

技能执行要进沙箱，这个原则我已经强调给团队很多次：不要拿生产主数据库和核心API直接作为无防线的执行后端。技能的权限模型至少要分三级：

在代码实现里，每个技能handler在执行前会先走一道权限校验，校验通过后才能访问外部资源。不要把这个权限校验放在大模型的"自觉"上——你管不住它的，只能靠后端的强制护栏。

上下文追踪方面，每一轮技能调用我都会记录：模型选了什么技能、传入参数是什么、技能返回了什么、用户后续反馈是什么。这些日志是后续做技能评估和优化的原始数据来源。没有日志的技能体系，基本等于闭着眼睛开车。

4. 技能编排与复用：把"原子技能"组合成"复杂任务"

单技能能解决单点问题，但真实的业务任务往往是多步骤的。比如"帮用户改收货地址的同时重算运费并发送通知"，就要涉及身份验证、订单查询、地址修改、运费计算、消息通知五个原子技能。如果不做编排，这五个技能会由模型在多次上下文循环里逐个调用，中间任何一步出错，后面全乱。

4.1 从"模型自由调用"到"DAG化流程编排"

自由调用模式是让模型自己决定调用顺序，这在步骤少、依赖弱的情况下还行，一旦步骤超过三步，模型极容易遗漏。我的实践是：把稳定的业务流程抽成DAG（有向无环图），节点是技能，边是依赖关系。

举个具体例子，"售后退款"流程可以抽成这样：

1. verify_user_identity（验证用户身份）必须先执行；
2. 身份通过后并行执行query_order_detail和query_refund_policy；
3. 两个查询结果汇总后执行validate_refund_eligibility；
4. 校验通过后执行refund_order，并做操作确认；
5. 退款成功后执行notify_user。

在这个DAG设计里，模型不需要自己编排步骤，它要做的是在流程的"选择点"做决策，比如判断退款原因走"仅退款"还是"退货退款"。固定流程和模型决策分离，是提升任务成功率的有效方式。

用代码表达一个节点时，我通常会有一个简单的flow配置：

refund_flow = { "steps": [ {"skill": "verify_user_identity", "next_on_success": "query_parallel"}, {"skill": "query_order_detail", "parallel_group": "query_parallel"}, {"skill": "query_refund_policy", "parallel_group": "query_parallel"}, {"skill": "validate_refund_eligibility", "next_on_success": "confirm_refund"}, {"skill": "refund_order", "requires_approval": True, "next_on_success": "notify_user"}, {"skill": "notify_user"} ] }

这种声明式编排的好处是，运营和工程可以分离，技术同事调技能，业务同事调流程，互不阻塞。

4.2 状态传递：不要让每个技能都去"裸读"业务数据

多个技能组合执行时，一个很常见的问题是参数传递。A技能的结果是B技能的输入，如果直接让B技能重新查一遍数据，既慢又可能取到不同的值。我的做法是给每个技能增加一个"上下文访问协议"：技能的输入参数可以显式引用上一节点的输出字段。比如refund_order.order_id可以直接引用query_order_detail.order_id，这样技能在执行时不需要重新解析用户原话。

这个设计有个好处：业务流程里的中间状态是显式的，每次调用都有迹可循；坏处是实现时对框架要求更高，没有统一规则就会变成"贴满补丁的传参"。所以我的建议是，一开始就要制定"技能上下文只能通过参数传递，禁止共享全局变量"的团队约定。虽然听起来古板，但在多技能协作场景下，它是最不容易出错的。

4.3 降级与重试：编排后的容错策略

技能编排后，容错策略也要升级。单技能失败和流程中途失败，处理方式完全不同。

我把容错分成三层：

• 参数级容错：技能发现参数缺失，可以进入主动澄清模式，反问用户补齐信息，而不是失败退出。
• 执行级容错：基础服务超时或网络抖动时，使用带指数退避的重试，最多重试2次；重试仍失败则切换降级技能。比如主用query_inventory失败，可以降级为query_cached_inventory。
• 业务级容错：当流程中某个环节出现不可逆异常（如退款接口返回失败），要回滚已经执行过的前置操作，比如取消通知、恢复状态标记。这类回滚操作也应该抽象成技能，放在DAG的反向链路上。

实测下来，加入三层容错后，Agent处理复杂任务的完成率从61%提升到了84%，这个提升主要来自"不再因为一个环节的小错误导致整个任务报废"。

5. 技能评估与治理：别让技能库变成一个"谁都不敢删的垃圾场"

技能体系的长期维护，远比技能开发更考验人。随着业务迭代，技能会越来越多，有些已经废弃，有些重复实现，有些质量堪忧。如果不做评估和治理，几个月后技能库就会变成一个"谁都不敢删的垃圾场"。

5.1 先给每个技能建立"健康档案"

我建议为每个技能建立一份轻量级健康档案，核心指标包括：

我第一次给已有技能库建健康档案时，发现居然有18%的技能在一个月里从未被调用过，另外有12%的技能错误率高得吓人但我们一直没察觉，因为它们被埋在了日志里无人问津。如果这个档案早点建，很多代价本可以避免。

5.2 技能评估集：用"黄金对话集"做回归测试

技能改动频繁时，最怕的是"改一个技能，炸掉十个流程"。我引入了"黄金对话集"作为回归测试集：从历史真实对话里挑出几百条覆盖典型场景的对话，每一条都标注了期望的技能调用序列和参数。每当技能或编排逻辑更新，就跑一遍回归测试，看技能选择的正确率、参数填充正确率、流程完成率有没有下降。

这个环节要做好，刚开始会很繁琐，因为你需要人工标注大量历史数据。但一旦积累到一定规模，它的价值会非常大。很多团队不做这个，是因为懒或侥幸，但实际上，没有回归保护，技能迭代到后期几乎寸步难行。

5.3 技能下线机制与版本管理

技能不是越多越好。技能过多不仅增加选择器的负担，还稀释模型的注意力。对于已经沉寂的技能，该下线就下线。

我的下线机制是：

1. 连续30天调用频率为0，自动进入"废弃候选"状态；
2. 废弃候选技能保留7天，期间仍可以被路由选择，但日志中打上"deprecated"标记；
3. 7天后无人访问，移入归档区，不再进入任何技能的候选列表；
4. 归档技能在注册中心里仍保留定义，仅作为历史追溯，不参与运行时。

版本管理方面，每个技能都带语义化版本号，技能升级时保留旧版本至少两个迭代周期，确保编排流程可以平滑切换。因为线上环境说不定某个流程还在调用旧版本技能，直接覆盖新版本可能导致不可预知的参数不兼容。

6. 实测复盘：我踩过的五个"技能设计"深坑

最后这部分，我整理了在构建agent-skills体系时踩过的一些比较典型的坑，有些是架构层面的，有些是细节层面的，但都值得拿出来单独说。

6.1 坑一：技能命名太抽象，模型根本猜不到

早期我给技能命名时用过process_refund、handle_order、update_record这类名字。你以为很清晰，但模型在语义匹配时更依赖真实业务词。把它改成refund_order、cancel_order、update_shipping_address这种"动词+对象"的命名后，选择准确率立刻涨了一截。命名不是一个纯工程问题，它会直接影响模型的理解质量。

6.2 坑二：底层API变更，技能定义却没同步修改

有过一次印象深刻的故障：底层库存接口把字段从stock改成了available_quantity，但技能定义里的参数说明还写着stock。结果模型看着旧说明传了stock，后端解析失败报错，用户面前显示的文案却是"系统繁忙"。从那以后，我制定了一条规则：技能定义的变更和底层API的变更必须同步上线，且变更前必须跑一次黄金回归集。

6.3 坑三：技能说明里的"多余细节"过多

技能描述并不是写得越多越好。描述如果塞满了内部代码结构、历史包袱、边缘行为清单，模型反而会被噪声干扰，抓不住核心。我后来遵循一个原则：描述里只写"模型做选择时需要知道的信息"和"参数正确填充需要的信息"，其他全部放到技能内部文档里，不让模型看到。

6.4 坑四：把权限校验做成"可选的"

最开始时，我在退款技能里加了一个approval_required参数，让模型判断是不是需要人工审批。结果模型在多数场景下都判断为"不需要"，导致一些高金额退款被直接放行。后来我彻底把这套逻辑从模型判断里移除，改为后端硬编码：凡金额超过阈值或命中风控规则，强制进入人工审批状态。这里我的教训是：凡是涉及钱、隐私、对外影响的决策，绝对不要交给大模型自由发挥，后端必须要有一道铁的规则。

6.5 坑五：没有考虑技能调用的"冷启动"问题

新上线的技能往往没有足够的调用数据，选择器会倾向于选择老技能，导致新技能长期不被使用。我在评测时发现过一个新技能上线一个月只被调用过三次的尴尬情况。解决思路是给新技能一个"曝光期"：新技能上线后的前一段时间，强制在候选列表里排前，甚至通过路由策略偏向选择它，加速数据积累。有了数据之后，再回到基于效果的选择机制。

7. 写在最后：技能体系的本质是"用工程手段驯服不确定性"

做agent-skills这一整套东西，我最大的体会是：它本质上不是在写工具，而是在用工程手段驯服LLM调用的不确定性。大模型天生是概率性的，但业务系统需要确定性。技能体系，就是在这两者之间搭一个缓冲层——用规范的描述、强约束的参数、DAG流程、后端权限护栏和持续评估，把模型的自由度限制在可控范围内，同时保留它在"选择"和"生成"上的灵活优势。

如果你正准备给自己项目的Agent搭建技能层，我的建议是：不要一上来就追求复杂框架，先去梳理清楚你的业务里到底有哪些"原子动作"，每个动作的边界和约束是什么，然后按这套方法来定义、注册、编排、评估。等跑通一条最小闭环，再逐步扩展技能数量。技能体系做得好的团队，Agent的稳定性、可解释性、可维护性都会有质的提升；做得不好，Agent就永远只能在Demo里表演。希望这篇文章能帮你少走一些我已经走弯路，让你的Agent真正成为一个"有技能"的稳定执行者。