企业官网建设流程全解析

最近在折腾AI智能体相关的项目，发现一个被反复提起但很少被系统讲透的概念——agent-skills。说白了，它就是给AI Agent装上"手"和"工具"的那一层。很多人做了半年demo级智能体，最后卡住的地方都不是模型能力，而是不知道怎么让Agent稳定地调用外部工具、执行具体操作、完成多步任务。这篇东西我准备从一个实际落地者的角度，把agent-skills从概念、架构、代码实现到踩坑经验完整掰开讲一遍。

1.1 从"会聊"到"会做"的关键一跃

先说一个最直观的对比。没有技能系统的Agent是什么样的？你让它"帮我把今天项目周报整理好发到群里"，它只能回你一段文字："好的，我建议你打开笔记本，写下进度，然后再复制粘贴……"——这就是纯对话模型，它什么都懂，但什么事都做不了。而接入了agent-skills的Agent，面对同一个指令，会自己完成：读取今日任务列表技能、调用周报模板渲染技能、搜索群成员技能、调用IM发送技能，最后给你一句"已发送"。

这个差别，就是"会聊"和"会做"的分水岭。

我在实际项目中体会很深的一点是：模型本身的能力已经非常强了，尤其在推理和语言理解上，但它是没有任何"行动能力"的。而agent-skills要解决的核心问题，就是如何把模型的语言理解能力，翻译成真实世界中的可执行操作。这中间需要一个完整的工程体系来支撑，包括技能的注册、发现、调度、参数校验、执行回传和错误处理。这也是为什么我说，聊到Agent落地就绕不开agent-skills。

1.2 技能系统与传统插件的本质差别

很多人刚接触这个概念时，会很自然地把它和传统软件里的"插件系统"划等号——都是挂一堆功能模块嘛。实际上两者有本质区别。

传统插件体系里，调用关系是确定的。用户在界面上点一个按钮，触发对应的插件功能，或者由预先写好的业务逻辑来决定调用哪个插件。它的核心特征是"人驱动"或"规则驱动"。而agent-skills是"模型驱动"的：技能的调用决策权交给了LLM，模型根据用户输入的语义，自主判断应该调用哪个技能、传什么参数、调完一个还要不要再接着调下一个。

举一个我们项目里的真实例子。我们接了一个财务管理技能集，里面有"查账户余额""创建报销单""审批流推进"等七八个技能。用户输入"帮我看下还剩多少预算，顺便把这笔打车费报了"，传统插件只能按照内置逻辑一个个执行，或者弹窗问用户选哪个；而接了agent-skills之后，模型会先调用查询技能把余额拉出来，然后根据余额状态决定走普通报销流程还是加急审批流程，整套操作都是动态决策的。

这个动态决策能力，就是agent-skills和传统插件最根本的分水岭。技能系统实际上是在模型和真实世界之间搭了一座双向桥：模型通过技能定义理解世界有什么可用，世界通过技能执行结果反馈给模型，形成真正的闭环。

1.3 Agent技能的分类方式

在我们团队内部，习惯把agent-skills的技能池分成四类，这个分类方式对后续架构设计很有帮助：

为什么要把技能分类？因为不同类型的技能，对可靠性、权限、审计的要求完全不一样。信息获取型技能调用错了，最多返回一个错误结果；操作执行型技能调用错了，可能直接产生一笔线上支付。所以后面做权限管理和调用策略时，必须按类型分开设计。

2. 从零搭建技能系统：注册中心、调度引擎、执行沙箱三层架构

2.1 技能系统的核心组件划分

我自己在开发agent-skills时，把系统拆成了三个核心组件：注册中心、调度引擎、执行沙箱。这个划分不是从教科书抄来的，而是从实际犯错中总结出来的。最早我图省事，让Agent直接在一个大函数里调用工具，结果技能一多就乱套，根本没法维护。后来才认识到，技能系统本质上是一个"能力管线"，每层的职责必须单一清晰。

注册中心是技能的家。所有技能在上线前，都要把"技能名、技能描述、参数Schema、执行入口"四件套登记进来。它还维护技能的生命周期状态：是草稿、已上线、被禁用，还是已下线。调度引擎是大脑的二传手。它负责在模型决定了意图之后，把"用户意图"转化为"具体技能调用指令"，中间涉及参数的映射和填充。执行沙箱是手。它真正跑去调用外部API、执行代码、操作数据库，并把结构化的执行结果返回给上层。

这三个组件必须解耦。我们的第一次架构设计就是因为把调度和执行的逻辑耦合在一起，导致每次给技能加一个重试策略，都要去改调度代码，把所有技能都牵连进来。拆开之后，调度引擎只关心"调哪个、按什么顺序调"，执行沙箱只关心"怎么调、调失败了怎么退"，注册中心只关心"有哪些技能、它们是否健康"。各干各的，场景再复杂也不乱。

2.2 一次完整的技能调用数据流

理解了组件之后，直接看一次完整的技能调用链路，会清楚得多。当用户输入"帮我查一下杭州明天适合跑步吗"时，系统里发生的事是这样的：

用户原文进入LLM，模型先判断意图，确定这是一个天气查询需求。LLM读取agent-skills的技能清单，从数十个技能描述中匹配到"查询天气"技能。模型根据用户输入和技能参数Schema，生成结构化的调用参数，比如城市="杭州"，日期="明天"，此时并不直接执行任何代码。调度引擎拿到这些参数后，走校验逻辑，确认参数完整合法，再根据技能的注册信息找到执行入口。执行沙箱真正调用后端天气API，取回温度、降水概率、空气质量等原始数据。执行结果返回给LLM，模型把结构化数据组织成自然语言，补充一句"明天空气质量良好，适合晨跑"，最终回复给用户。

这个过程看起来简单，但每一步都有工程化的设计在里面。最关键的一点是：LLM在整个链路中扮演的是"决策者"而不是"执行者"。它负责理解用户意图、选择合适的技能、生成正确的参数，但绝不直接操作外部系统。实际操作全部落在执行沙箱里。这么做的原因很实际：模型生成的内容天然存在随机性和不确定性，你不可能指望一个概率模型去完成对精确度要求极高的API调用；只有在执行层用确定的代码去兜底，系统整体才会稳定。

2.3 为什么技能描述必须"声明式"

我在给团队做培训时常说一句话：技能描述是写给模型看，不是写给用户看的。很多开发者刚接触agent-skills时，习惯把技能描述写成给人类看的文档，比如"天气查询功能，用于获取中国各城市未来7天的天气预报数据"。这种描述太笼统了。

模型选择技能时，靠的是语义匹配和逻辑推理。你的描述越具体、越结构化，模型就能越精准地做路由。我们内部现在对技能描述有一套统一规范：第一句点明技能的适用场景，第二句说明它接收的核心参数，第三句讲清楚执行后的返回值形态，最后补充哪些场景不应该调用它。

举个例子。同样是查询天气的技能，我们现在的描述长这样：用于查询指定城市未来1-10天的天气信息。适用场景：用户询问天气、温度、降水概率、空气质量、出行穿衣建议。参数：city_code（城市编码，必填）、forecast_days（预报天数，默认7）。返回字段：date、weather、temp_high、temp_low、precipitation、air_quality。注意：用户问过去天气或用天气做销售分析时，不调用此技能，返回空结果。

这么写的好处是，模型在面对模糊输入时，有足够的信息做判断。之前我们遇到过用户问"上海和北京哪个适合本周去旅游"，模型一开始调了两次天气查询分别查两个城市的天气，后又调了交通查询技能。正是因为描述写清楚了适用场景和参数，模型才能做出这种组合调用的决策。这叫声明式技能描述——你声明什么，模型才能调度什么。

3. 技能注册与调用实战：一段代码把Agent接入真实世界

3.1 技能的声明结构与JSON Schema

聊完架构，进入实战环节。一个技能在代码层面上到底长什么样？这是我目前项目里一个标准技能的定义结构：

{ "name": "send_email", "description": "向指定收件人发送邮件。适用场景：用户要求写邮件、发邮件、回复邮件。", "parameters": { "type": "object", "properties": { "to": { "type": "string", "description": "收件人邮箱地址，多个地址用逗号分隔" }, "subject": { "type": "string", "description": "邮件主题" }, "body": { "type": "string", "description": "邮件正文内容" }, "cc": { "type": "string", "description": "抄送人邮箱地址，可选" } }, "required": ["to", "subject", "body"] }, "handler": "email_service.send_email", "tags": ["communication", "mail"], "timeout_ms": 10000, "execution_mode": "sync" }

先说字段设计的逻辑。name是技能的唯一标识，必须简短明确，不能带空格或特殊字符。description是给模型看的，写得好不好直接决定模型会不会在关键时刻想起你这个技能。parameters部分强烈建议用JSON Schema这样的标准格式，不要自定义一套。

为什么必须用JSON Schema？因为模型侧的function calling能力原生支持标准JSON Schema。你定义好这个结构后，可以直接把整个参数结构传给LLM，模型就能生成符合要求的参数对象。如果你自己搞一套参数格式，意味着你得自己写转换逻辑，还得考虑模型忘记遵守格式怎么办。用标准格式最大的好处是完全兼容模型的tool-calling接口，几乎零成本接入。

handler字段指向技能的真实执行函数。我特意用字符串而不是直接放函数引用，是为了支持技能的热更新和多人协作——配置与代码分离，改配置不需要重新发布服务。这也是我在做架构升级时的一个重要决定。

3.2 核心实现：注册器、加载器与执行器

下面给一段Python代码，展示注册中心的简化实现。这段代码虽然不长，但在我们项目里，它支撑了几十个技能的声明、校验和执行：

import json import importlib import inspect from typing import Dict, Any, Callable class SkillRegistry: def __init__(self): self._skills: Dict[str, Dict[str, Any]] = {} def register(self, skill_def: dict): name = skill_def["name"] if name in self._skills: raise ValueError(f"技能重复注册: {name}") # 解析handler字符串，加载真实函数 module_path, func_name = skill_def["handler"].rsplit(".", 1) module = importlib.import_module(module_path) handler_func = getattr(module, func_name) # 执行参数校验：确保handler是异步函数（防止阻塞事件循环） if not inspect.iscoroutinefunction(handler_func): raise TypeError(f"技能 {name} 的handler必须是异步函数") self._skills[name] = { "definition": skill_def, "handler": handler_func, } def list_skills(self) -> list: """给LLM用的技能清单，只保留描述和参数结构""" return [ { "name": item["definition"]["name"], "description": item["definition"]["description"], "parameters": item["definition"]["parameters"], } for item in self._skills.values() ] async def execute(self, name: str, arguments: Dict[str, Any]) -> str: if name not in self._skills: return json.dumps({"error": f"unknown skill: {name}"}) item = self._skills[name] skill_def = item["definition"] handler = item["handler"] # 执行超时控制 timeout = skill_def.get("timeout_ms", 5000) / 1000 result = await asyncio.wait_for( handler(**arguments), timeout=timeout ) return json.dumps(result, ensure_ascii=False)

这段代码有几个地方值得细说。第一，handler必须是异步函数，这在整个系统并发能力上是非常关键的设计。Agent调用技能时，很可能需要同时发起多个并行调用（比如查三个城市的天气），用同步函数会阻塞整个事件循环。第二，给LLM的技能清单（list_skills方法）和内部完整注册信息是分开的。模型只需要看到名称、描述和参数结构，不必知道handler怎么实现。这既减少了传递给模型的token数量，也避免暴露内部实现细节。

执行器还做了超时控制。我遇到过的真实情况是，某个第三方API偶尔会响应极慢，拖慢整个Agent的回复。哪个技能慢就暴露哪个技能的超时问题，执行器这边把timeout_ms调小，等到真需要扩容或者做降级策略时再单独处理。

3.3 执行结果的回传与多轮处理

技能执行完，结果怎么回到模型手里？很多Agent新手在这里栽过跟头。有个常见误区是把结果拼一段字符串直接返回给LLM就完了。实际线上调用时，模型返回的结果可能是JSON，也可能是错误堆栈，还可能是个超时异常，这些情况要分门别类。

我习惯的做法是：无论技能内部发生了什么，执行层统一返回一个规范的JSON字符串。正常执行时返回数据和字段；异常时返回独立的错误码与可读信息。所有返回都会在传给LLM前做一次统一包装。格式如下：

{ "ok": true, "data": { "weather": "晴", "temp_high": 28 }, "meta": { "skill": "query_weather", "latency_ms": 342 } }

失败时的格式：

{ "ok": false, "error": { "code": "VENDOR_API_ERROR", "message": "天气服务商接口返回500，请稍后重试" } }

为什么非要做这个包装？因为模型从错误中学习的能力很强。当它看到错误码和清晰错误信息时，下一次决策里就会避开同样的错误，比如自动换一个参数再调用。之前我们没做统一包装，技能的报错信息随手拼一段，模型根本不知道自己错在哪里，经常在原地重试，白白浪费了好几轮对话。包装之后，模型能理解"参数格式不对"和"服务商挂了"的区别，推理质量提升非常明显。

多轮处理时，把技能执行结果作为系统消息追加到对话上下文中，让模型参考这些信息生成最终回复。这里的顺序很重要：先给用户原话，再给技能结果，再让模型生成自然语言。这样模型既知道用户想要什么，也知道工具实际上给到了什么，就能自然地做信息整合，而不是机械复述结果。

4. 让模型"正确选技能"的关键工程手段：意图路由与提示词编排

4.1 技能列表是给模型看的"菜单"

有人会想，让LLM自动选技能不就行了？选错了选对了都靠模型发挥。大模型确实能处理意图识别，但是直接让它在一堆技能描述里挑一个，就像让一个刚来餐厅的客人从几百道菜的菜单里选一道最适合赶时间、又便宜、又健康的菜。它的选择可能偶有灵感，但不够稳定。实际Agent场景里，需要给模型铺一条高效的"决策路径"。

这里我先说一个基本的配置——技能菜单怎么传递给模型。在主提示词或者系统提示词里，把技能列表作为结构化文本放进去。现在主流做法是直接使用function calling机制，把技能Schema传给模型，但如果你用的框架不支持，也可以在自己的提示词里嵌入。

我们内部演进了三个版本的写法。第一版很简单，纯粹罗列技能名和一句话描述。效果很差，模型经常分不清A技能和B技能的边界。第二版加了场景描述，效果好了不少。第三版我们在每个技能下加了"不适用场景"，这个做法在准确率上带来了一次明显的提升，模型误调用的比例大约下降了40%。

现在我们的提示词片段大概是这样的：

可用技能清单如下，格式为：技能名 - 描述 - 参数 - 不适用场景。 query_weather - 查询城市实时天气和预报 - city_code, forecast_days - 不适用：过去天气、气候统计、数据分析 send_email - 发送邮件给收件人 - to, subject, body, cc - 不适用：读取收件箱、搜索邮件、删除邮件 search_files - 在指定的根目录下搜索文件 - root_path, keyword, file_type - 不适用：打开文件内容、编辑文件 create_jira_ticket - 创建JIRA工单 - project_key, summary, description, priority - 不适用：查询工单状态、修改工单 ...

这个"不适用场景"的思路，有点类似给模型画了一个"安全边界"。模型在做语义匹配时，不仅要判断"该不该用"，还要判断"现在是不是不该用这个"。边界画清楚了，模型的误判率会大幅降低。尤其是在技能数量变多之后（超过20个），这个边界信息价值极大。

4.2 路由策略：语义相似度优先、规则兜底

虽然LLM本身就是很好的意图识别器，但我还是建议在工程上加一层"路由策略"，而不是完全把选技能这件事交给模型。

具体做法分两个层面。第一层是规则兜底：一部分意图非常明确的指令，直接用传统NLP规则或者小模型做初筛。比如用户输入包含"天气*城"这类结构化表述，直接路由到天气技能，根本不需要动大模型。这样做有两个好处：省token、降低响应延迟。第二层才是LLM决策：遇到规则无法覆盖的开放语义，才让模型在技能之间做选择。

这种"规则优先、模型兜底"的策略在我们项目里叫"宽进严出"。技能数量少的时候，全走LLM也可以；技能多了之后，你会发现大量高频指令其实是规则化的，没必要每次都让大模型为这点简单事支付推理成本。比如"查余额""看天气""搜文件"这类明确指令，规则策略几乎不会出错，让模型参与纯属浪费。

4.3 技能冲突与误调用的兜底设计

无论提示词编排得多巧妙，模型总有走神的时候。技能系统必须做攻击面防御。这里说三个我实战中验证过的兜底方案。

第一个是冷却与频控。如果某个技能在短时间内被反复调用，可能不是用户真的有这么多次需求，而是模型陷入死循环了。我们给高频技能加了一个简单的频控策略，比如同一会话中某个技能调用超过5次就返回提示，让模型检查是否陷入循环。这招救回过好多次"Agent卡死"事故。

第二个是敏感技能二次确认。操作执行类技能（发邮件、下单、删除文件）都走一次二次确认。确认的方式可以是在对话里问用户，也可以做成前端UI的确认按钮。技术实现上，给技能打一个confirm: true的标签，调度引擎遇到这个标签就先返回一个pending状态，等用户确认再真正执行。

第三个是技能回滚机制。在执行沙箱里，一旦操作类技能产生了副作用，我们会把原始状态记录下来，以便在必要的时候回滚。比如"修改配置文件"技能，在执行前先备份原文件，执行后发现问题立刻恢复。这个东西做完之后，线上出问题时的恢复时间从小时级降到了分钟级。

5. 技能编排进阶：组合调用、工作流与多Agent分工

5.1 技能编排与编排器的设计思路

单个技能能做的事终究有限，Agent的价值更多体现在"组合调用"上。我自己最早做多技能协作时，是在主提示词里写"如果需要，你可以依次调用多个技能来完成用户需求"，然后让模型自己编排顺序。结果也是时好时坏，成功率高的时候运行令人惊喜，失败的时候会让用户怀疑系统不可用。

后来我意识到，简单的多步调用可以交给模型自由发挥；复杂的多步链路（超过5步、强先后依赖）必须用工作流来编排，减少模型的自由决策空间。

举个例子，"生成周报并发送给部门群"这个任务，拆解出来的步骤是：读取本周完成任务列表→按模板生成周报→搜索部门群聊对象→发送周报。前两步之间有确定的逻辑关系，我不想让模型每次重新推理这一步。于是我们把这些步骤封装成一个"周报工作流"技能，内部编排好每个子步骤的调用顺序，模型只需要执行一次这个工作流即可。

这个设计在工程上被称为技能编排。它带来了两个明显好处的：稳定性和效率都提升了。不用每次让模型从零推理链路，发生中间错乱的可能性大大降低；对外暴露为一个技能之后，提示词里只需要保留很短的一个描述，token消耗还变少了。

5.2 多Agent协作下的技能分配

如果单个Agent的技能池越装越多，提示词里要传的技能清单也会越来越长，整体的上下文会被挤占。这是agent-skills规模化落地时一定会撞上的天花板。我们的解法是多Agent架构：不同职责的Agent各管一摊技能。

我们系统的实际配置是，一个主调度Agent，它不执行具体业务技能，只负责理解用户意图，然后按职责边界把请求转发给子Agent。每个子Agent维护自己的技能池。比如工作Agent维护和文档、报表、日历相关的技能；沟通Agent维护邮件、IM、会议相关的技能；数据Agent维护SQL查询、BI图表相关的技能。

这么做的好处一眼就能看出来：每个Agent的技能清单都短，模型做路由时干扰项少了很多。我们实测一个技能池数量从60个降到15个之后，路由准确率从81%提升到了93%以上。这就是技能收敛带来的显著收益。

另外，多Agent结构还天然做了权限隔离。不同职责Agent可以绑定不同的权限账号，数据Agent只能读数据库，沟通Agent可以发消息但不能删消息。权限边界清晰，审计链路也更简单。

5.3 技能复用与灰度发布

最后聊一下技能体系的迭代管理。agent-skills系统上线之后，必然会持续新增、修改技能，这个迭代过程如果处理不好，很容易翻车。

我们做了几件事：所有技能上线前均有测试用例，覆盖边界条件；技能版本管理，每次改动保留历史版本以便回滚；新版本技能先在单Agent环境灰度，确认运行稳定后推全量。

灰度发布的设计有意思。我们把技能执行器的配置抽成一个独立的配置中心，线上环境、灰度环境、测试环境的技能参数完全隔离。把一个技能从测试提升到灰度，只在配置中心里改一行配置，不用改任何代码。这个机制让运营人员和算法同学都能自己操作，不用每次来麻烦我们开发。

6. 落地agent-skills的真实踩坑记录与最终建议

6.1 描述冗余带来的路由混乱

先说一个我们踩得很冤的坑。项目初期，为了让技能定义更"详尽"，团队里一位同学在技能描述里写了一整段带示例的说明文字，从背景到用途写了200多字。结果上线之后，这个技能经常被模型误调用，凡是模糊字段的描述都容易触发它。

排查过程是，打印出每次技能调用日志，把入参和用户原始输入做了对照，发现模型只要看到"数据""分析""统计"这些词，就倾向于调用这个描述里提到的技能。原因正是描述文本过长、关键词分布太密集，把模型注意力带偏了。后面把每段描述精简到50字左右，加上"不适用场景"说明，误调率立刻降下去。

我最终的总结是：技能描述要"结构清晰、范围明确、示例克制"。描述不是文档，它给模型做决策用，不是给人类阅读用。给人类的说明可以放到系统文档里，不要塞进技能描述。

6.2 参数与返回值的类型隐患

这个坑几乎必踩。有一次，用户让Agent"帮我查一下最近七天的销售数据"，模型把forecast_days参数生成为字符串类型的"7"，而不是整数7。我们的JSON Schema定义里写的是整数，但模型生成时把引号带上了。执行层校验通过不了，技能报错返回，模型不知道错在哪，又用同样的参数重试一次，反复两三次，最后直接崩溃给用户一段异常信息。

处理办法：在调度引擎里加一层参数归一化。数字类型参数可以接受数字或数字字符串；字符串参数尽量做trim和编码修正；布尔参数兼容多种表达方式。归一化之后，模型生成的参数即使不那么精确，也能被系统稳稳接住。这层逻辑像是一个容错的"翻译官"，让模型的输出和执行器的输入之间有一个缓冲垫。

返回值类型同样要注意。有些第三方API返回XML，有些返回超大JSON，如果不做预处理直接丢给模型，轻则上下文占用严重，重则模型被无关字段干扰。我们在执行沙箱里加了一个返回裁剪逻辑，把无关字段去掉，只保留模型生成回复所需的核心字段。

6.3 超时、并发与上下文膨胀

Agent场景里，技能调用的超时问题是个隐形杀手。早期我们所有技能都设置统一的5秒超时，结果查询类技能跑得好好的，操作类技能因为下游系统慢频繁超时。后来把超时改成按技能单独配置：查询类3秒，操作类10秒，复杂的报表生成类30秒。然后再把超时重试策略加进去：查询类技能允许重试2次，操作类技能不重试，避免重复提交。

并发控制也是个大坑。多个Agent实例同时跑，共享同一技能服务，如果技能背后对接的API有频控限制，你的Agent再聪明也白搭。我们给技能层加了一层简单的信号量限流。特别火的技能最多支持20个并发执行，超出的请求排队等待。实际运行中，这个排队机制有效保护了下游API不被我们打爆。

上下文膨胀问题是所有Agent系统都会遇到的。每执行一个技能，就要把技能结果塞进上下文；多个技能执行完，上下文可能膨胀到几千token。解决办法有二：一是对大块技能结果只保留摘要，而不是全文；二是做完多步操作后，用一个小模型对历史工具调用结果做压缩，只保留关键结论。

6.4 我的最后建议

做了这么多集成和优化，我对agent-skills的看法是：它是Agent从实验品走向生产力工具的必经之路。越早把技能层当成一个独立工程体系来对待，后期越省心。架构上做好注册、调度、执行三分，数据流上做到技能描述结构清晰、执行结果统一包装、上下文及时压缩，运营上做好灰度与回滚机制，这套体系就能稳定地跑起来。

如果你现在正在开发自己的Agent，建议不要先急着堆技能数量，而是先打磨三个技能的调用链路，跑通一个完整的"用户请求→模型路由→技能执行→结果返回→模型总结"闭环。这个闭环稳定之后，再慢慢加技能、加场景。技能系统这东西，开始的姿势对了，后面就是坦途；多了再重构，痛苦指数会直线上升。

我个人在实际操作中的体会是，agent-skills最迷人的地方在于，它是模型智能和工程现实之间的粘合剂。没有它，模型再聪明也只能纸上谈兵；有了它，模型才真正开始"动手做事"。顺着这个方向继续往深做，下一步还能优化技能间依赖关系的自动编排、技能效果AB测试、甚至让Agent自己学会创造新技能组合。这条路还很长，但方向一定是往"更多自动决策、更少人工干预"上走的。