企业官网建设流程全解析

1. 从“会聊”到“会做”：agent-skills 到底在解决什么问题

这两年跟不少做 AI 应用的朋友聊，大家有个共同的感受：模型“能说会道”这件事早就不是瓶颈了，真正卡住落地的是“它到底能不能把一件事从头到尾干完”。你让它写一段文案，它写得挺漂亮；你让它去查一下库存、改一下订单状态、再给客户发一封确认邮件，它就开始顾左右而言他，或者干脆编一个看起来很像那么回事的假结果。agent-skills这个项目，本质上就是在补这块短板——它要解决的不是“模型聪不聪明”，而是“智能体有没有可被调用的、稳定的、可组合的技能”。

我先把话说在前头，这里的“技能”不是指模型内部的知识，而是指一套外部可执行能力的封装。你可以把它理解成给智能体配了一个工具箱：拧螺丝有螺丝刀，量长度有卷尺，切东西有刀。模型负责判断“现在该用哪把工具、怎么用”，而 agent-skills 负责保证“这把工具拿起来就能用，用完有明确结果返回”。这个分工一旦理清楚，整个系统的稳定性会有一个质的提升。

那它适合谁看？如果你正在做智能体相关的应用，比如自动化客服、流程助手、数据分析助手、内容生产流水线，或者你只是想让自己的 AI 助手别再“光说不练”，那这套思路你大概率用得上。哪怕你目前只是用现成的智能体平台搭着玩，理解 skills 的设计逻辑也能帮你少踩很多坑。接下来我会从整体设计、核心细节、实操落地、问题排查几个层面，把 agent-skills 这套东西掰开揉碎讲一遍，尽量做到你看完就能照着搭一个最小可用版本。

2. 整体设计与思路拆解：为什么是“技能”而不是“一个大提示词”

2.1 核心思路：把能力从提示词里“拆出来”

早期做智能体，很多人的做法是把所有要求都塞进一个超长的系统提示词里：你要会查天气、会算数、会总结、会发邮件……结果就是提示词越写越长，模型越来越容易顾此失彼，改一个功能还可能把另一个功能带崩。agent-skills 的核心思路恰恰相反——把每一种能力独立成一个技能单元，每个单元有自己的名字、描述、输入参数、执行逻辑和返回格式。

这么做的第一个好处是可维护。查天气的逻辑改了，我只动天气技能，不会影响发邮件技能。第二个好处是可发现。智能体在决定要不要调用某个能力时，看的是技能的描述，而不是在一大段文字里大海捞针。第三个好处是可测试。每个技能都能单独跑单元测试，输入什么、输出什么，清清楚楚，不用每次都把整个智能体拉起来验证。

我打个生活化的比方：一个大提示词就像让一个人同时背下整本菜谱、账本和通讯录，然后现场发挥；而技能化就像给他配了一排抽屉，每个抽屉上贴着标签，需要什么拉开哪个。后者显然更靠谱，也更接近人类真实的工作方式。

2.2 方案选型：技能描述为什么比技能实现更关键

这里有个很多人会忽略的点：在 agent-skills 体系里，技能描述的质量往往比技能本身的代码质量更影响最终效果。原因很简单，模型是靠描述来判断“这个技能是干什么的、什么时候该用”的。如果你的描述写得含糊，比如“处理数据”，模型根本不知道是清洗、统计还是可视化，它要么不敢调用，要么乱调用。

所以我在设计技能时，描述一般会包含三块信息：这个技能做什么、什么场景下用、输入输出大概长什么样。举个例子，与其写“查询订单”，不如写“根据订单号查询订单的当前状态和物流信息，适用于用户询问‘我的货到哪了’这类问题，输入为订单号字符串，返回状态和最新物流节点”。你看，后者几乎把调用时机都替模型想好了。

至于实现层面，选什么语言、用什么框架，其实没那么重要。Python 生态成熟、库多，适合快速验证；Node.js 在和一些前端或服务端系统对接时更顺；甚至你用无代码平台拼一个 HTTP 接口也能当技能用。关键是接口要稳定、返回要结构化，别今天返回字符串、明天返回对象，那样模型会疯掉。

2.3 边界划分：哪些该做成技能，哪些不该

不是所有东西都值得封装成技能。我的经验是，满足下面几个条件的，才适合做成独立技能：会被反复调用、逻辑相对独立、有明确的输入输出、执行结果可验证。比如“发送通知”“查询数据库”“调用某个计算服务”，这些都很适合。

反过来，那些一次性的、强依赖上下文的、结果没法验证的操作，就别硬做成技能。比如“帮我写一段有创意的开场白”，这种更适合让模型直接生成，而不是封装成一个技能去调用。硬做的话，你等于把模型的创造力又锁回了一个固定流程里，得不偿失。

还有一个边界要划清楚：技能负责“做”，模型负责“想”。技能里尽量不要塞太多判断逻辑，判断交给模型。技能越纯粹，复用性越高。我见过有人把一整套业务流程都写进一个技能里，结果这个技能只能在这个流程里用，换个场景就废了，这就是边界没划好。

3. 核心细节解析与实操要点：一个技能该长什么样

3.1 技能的三要素：描述、参数、执行体

一个规范的技能，我一般会把它拆成三部分来看。描述是给模型看的，决定它会不会被选中；参数是调用契约，决定模型怎么传值；执行体是真正干活的代码，决定结果对不对。

描述部分前面说过了，重点说参数。参数设计有个原则：能少则少，能明确则明确。参数太多，模型容易传错；参数类型模糊，模型容易瞎猜。比如一个“发送邮件”技能，参数至少要有收件人、主题、正文，这三个是必须的。至于抄送、附件这些，可以做成可选参数，模型用不到就不传。

执行体这块，最重要的是错误处理。技能执行失败时，不要直接抛一个原始异常给模型，那样它看不懂。你应该返回一个结构化的错误信息，比如“订单号格式不正确，应为 12 位数字”。模型看到这种信息，才有可能自己纠正或者告诉用户。这一点我在实际项目里踩过坑，早期直接把异常堆栈丢回去，模型完全懵，只能回复“抱歉出错了”，用户体验很差。

3.2 参数校验：别让模型“自由发挥”

模型传参有个特点：它很自信，但经常传错。所以参数校验必须做在技能内部，不能指望模型自觉。常见的校验包括类型校验、范围校验、格式校验。比如一个查询类技能，订单号必须是数字，那你就得在技能里判断，不是数字就直接返回错误提示。

这里有个技巧：错误提示要写成“可被模型理解并纠正”的形式。比如“日期格式应为 YYYY-MM-DD，你传入的是 2024/1/1，请转换后重试”。这种提示模型一看就知道怎么改。如果你只写“参数错误”，模型大概率会原样再传一次，然后继续错。

我还习惯给参数加默认值。比如分页查询，默认每页 10 条，模型不传就用默认值。这样能减少模型的心智负担，也能避免因为漏传参数导致调用失败。默认值的选择要合理，别设一个明显不合适的值，否则模型每次都得显式覆盖，反而更麻烦。

3.3 返回结构：让模型“看得懂”比“看得全”更重要

技能返回的数据，很多人喜欢把原始接口返回直接透传，结果是一大坨嵌套很深的 JSON。模型解析这种结构很吃力，容易漏掉关键信息。我的做法是做一层轻量转换，只保留模型决策需要的字段，并且用清晰的键名。

比如查询订单，原始返回可能有几十个字段，但我只返回订单号、状态、最新物流描述、预计到达时间这几个。键名用英文小写下划线，值尽量是字符串或数字，别搞太复杂的嵌套。如果确实需要返回列表，也控制一下长度，比如最多返回 5 条，多了就截断并提示“还有更多结果”。

提示：返回结构一旦定下来，就尽量别改。模型对字段名是有“记忆”的，你今天叫 status，明天叫 order_status，它很容易混乱。如果非要改，记得同步更新技能描述。

3.4 技能命名：好名字能省一半调试时间

命名这件事看着小，其实影响很大。我见过有人把技能命名成do_stuff、handle、process，这种名字模型根本判断不出该不该用。好的命名应该动词开头、语义明确、避免歧义。比如query_order_status、send_email_notification、calculate_shipping_fee，一看就知道干什么。

命名还要注意避免和模型已有知识冲突。比如你有一个技能叫search，模型可能会以为这是通用的网络搜索，结果你实际是查内部数据库，这就容易误调用。加个前缀或限定词，比如search_internal_knowledge_base，就能避免这种混淆。

4. 实操过程与核心环节实现：从零搭一个最小可用技能集

4.1 环境准备与目录结构

假设我们用 Python 来搭，先准备一个干净的环境。我习惯用虚拟环境，避免依赖污染：

python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install fastapi uvicorn pydantic

目录结构我一般这样组织，清晰且好扩展：

agent_skills/ ├── skills/ │ ├── __init__.py │ ├── base.py # 技能基类 │ ├── query_order.py # 查询订单技能 │ └── send_email.py # 发送邮件技能 ├── registry.py # 技能注册中心 └── main.py # 对外服务入口

这个结构的好处是，新增技能只需要在skills/下加一个文件，然后在注册中心登记一下，不用动其他代码。技能之间互相独立，谁也别依赖谁，这样测试和替换都方便。

4.2 定义技能基类：统一契约

为了让所有技能长得一样，先定义一个基类。这个基类规定每个技能必须有name、description、parameters和execute四样东西：

from abc import ABC, abstractmethod from pydantic import BaseModel class SkillBase(ABC): name: str description: str parameters: dict @abstractmethod def execute(self, **kwargs) -> dict: pass def to_spec(self) -> dict: return { "name": self.name, "description": self.description, "parameters": self.parameters, }

to_spec这个方法很关键，它把技能转成模型能读的规格说明。模型拿到的就是这一份份规格，而不是你的源码。这样设计还有个好处：技能实现可以随便换语言、换服务，只要规格不变，模型侧完全无感。

4.3 实现一个查询订单技能

下面是一个具体的技能实现，我加了参数校验和结构化返回：

from .base import SkillBase class QueryOrderSkill(SkillBase): name = "query_order_status" description = ( "根据订单号查询订单当前状态和最新物流信息。" "适用于用户询问订单进度、物流位置等场景。" "输入为订单号字符串，返回状态和最新物流节点。" ) parameters = { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号，12 位数字字符串" } }, "required": ["order_id"] } def execute(self, order_id: str) -> dict: if not order_id or not order_id.isdigit() or len(order_id) != 12: return { "success": False, "error": "订单号格式不正确，应为 12 位数字，请检查后重试" } # 这里替换成真实的查询逻辑 mock_data = { "order_id": order_id, "status": "运输中", "latest_event": "已到达某分拨中心", "estimated_arrival": "2024-06-20" } return {"success": True, "data": mock_data}

注意看错误返回，我特意写成了模型能理解的自然语言，而不是抛异常。这样模型收到后，可以自己判断是让用户重新提供订单号，还是直接告知格式要求。这个细节直接决定了智能体的“情商”。

4.4 技能注册与规格导出

所有技能写完后，用一个注册中心统一管理：

from skills.query_order import QueryOrderSkill from skills.send_email import SendEmailSkill class SkillRegistry: def __init__(self): self._skills = {} def register(self, skill): self._skills[skill.name] = skill def get_specs(self): return [s.to_spec() for s in self._skills.values()] def invoke(self, name, **kwargs): skill = self._skills.get(name) if not skill: return {"success": False, "error": f"未找到技能 {name}"} return skill.execute(**kwargs) registry = SkillRegistry() registry.register(QueryOrderSkill()) registry.register(SendEmailSkill())

get_specs返回的列表，就是你要塞给模型的那份“技能清单”。模型看到这份清单，就知道自己有哪些能力可用。invoke则是模型决定调用后，你实际执行的地方。注册中心是模型和技能之间的唯一桥梁，所有调用都走这里，方便加日志、加权限、加限流。

4.5 把技能清单接入模型调用

接入这一步，不同平台做法不一样，但核心逻辑是一样的：把技能规格转成模型能识别的格式，然后在模型返回调用意图时，解析出技能名和参数，交给注册中心执行。下面是一个简化的处理流程：

def handle_user_input(user_input, model_client, registry): specs = registry.get_specs() response = model_client.chat( messages=[{"role": "user", "content": user_input}], tools=specs ) if response.get("tool_call"): call = response["tool_call"] result = registry.invoke(call["name"], **call["arguments"]) # 把结果回传给模型，让它组织最终回复 final = model_client.chat( messages=[ {"role": "user", "content": user_input}, {"role": "assistant", "content": None, "tool_call": call}, {"role": "tool", "content": str(result)} ] ) return final["content"] return response["content"]

这段代码里有个关键点：技能执行结果要回传给模型，而不是直接返回给用户。因为模型需要根据结果组织语言，比如把“status: 运输中”翻译成“您的包裹正在运输途中”。如果你直接把原始结果丢给用户，体验会很生硬。

注意：回传结果时，如果结果很长，记得做截断或摘要，否则会占用大量上下文，影响后续对话质量。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 模型不调用技能怎么办

这是最常见的问题。模型明明有能力可用，却选择直接回答。原因通常有三个：技能描述不够明确、技能太多导致选择困难、提示词里没有引导。

排查顺序我一般是这样的：先看描述，把描述改得更具体，加上“适用于……场景”这样的引导语；如果技能超过 10 个，考虑做分组或分层，别一次性全塞给模型；最后在系统提示词里加一句“当用户问题涉及订单、物流时，优先调用 query_order_status 技能”。实测下来，这三招基本能解决八成的不调用问题。

5.2 模型传参错误怎么破

传参错误的表现五花八门：参数名拼错、类型传错、该传的没传。根子上还是参数描述不够清楚。我的做法是在参数描述里把格式要求写死，比如“订单号，12 位数字字符串，不要带空格”。另外，在技能内部做严格校验，错误提示写清楚期望格式，模型收到后往往能自己纠正。

如果某个参数经常传错，可以考虑降低它的复杂度。比如原本要求传一个 JSON 对象，改成传几个简单字符串参数，模型出错率会明显下降。能用简单类型就别用复杂类型，这是血泪教训。

5.3 技能执行超时或失败

外部服务不稳定是常态，技能执行超时很常见。我的处理原则是：设置合理超时、失败要有降级、错误要可读。超时时间一般设 5 到 10 秒，太长会拖垮整个对话。失败时返回一个明确的错误信息，比如“查询服务暂时不可用，请稍后重试”，而不是让模型干等。

如果某个技能特别容易失败，可以考虑加重试机制，但重试次数别太多，两次就够了。重试还失败，就老老实实返回错误，让模型告诉用户。千万别在技能里无限重试，那样会把整个系统拖死。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑是技能描述写得太技术化。早期我写“调用订单服务 API 获取数据”，模型完全不知道什么时候该用。后来改成“查询订单状态和物流信息，适用于用户问‘我的货到哪了’”，调用率立刻上来了。描述要站在模型的角度写，而不是站在开发者的角度写。

第二个坑是返回结果里带了敏感字段。有一次查询用户信息，我把整个用户对象都返回了，包括一些不该给模型看的字段。虽然模型不一定乱用，但这属于安全隐患。后来我强制要求所有技能返回前做字段白名单过滤，只返回必要信息。技能返回的数据，默认都是要进模型上下文的，该脱敏的一定要脱敏。

第三个坑是技能之间互相调用。一开始我觉得技能 A 调技能 B 挺方便，后来发现调试极其痛苦，一个出错另一个也跟着挂。后来我定了个规矩：技能之间不互相调用，需要组合就在模型层组合。模型先调 A，拿到结果再调 B，这样每一步都清晰可查。

6. 技能组合与扩展：从单点能力到完整工作流

6.1 让模型自己编排技能顺序

单个技能只能解决单点问题，真正的价值在于组合。比如用户说“帮我查一下订单，如果还没发货就取消掉”，这就涉及查询和取消两个技能。你不需要写一个“查询并取消”的复合技能，而是让模型先调查询，根据返回状态决定要不要调取消。编排逻辑交给模型，技能只管执行，这样灵活性最高。

当然，模型编排偶尔会出错，比如该取消的时候没取消。这时候可以在系统提示词里加一些编排规则，比如“取消订单前必须先查询状态，只有状态为‘待发货’时才能取消”。这种规则相当于给模型一个决策框架，能显著降低出错率。

6.2 技能版本管理与灰度

技能上线后难免要改。直接改线上技能风险很大，万一改坏了，所有依赖它的流程都受影响。我的做法是给技能加版本号，比如query_order_status_v2，新版本先小范围灰度，观察一段时间没问题再全量。旧版本保留一段时间，确保没有遗漏的调用方。

版本管理还有个好处是方便回滚。一旦新版本出问题，把模型侧的技能清单切回旧版本就行，不用改代码重新部署。这个机制在紧急情况下能救命，我强烈建议你从一开始就加上。

6.3 技能的可观测性

技能跑在后台，出了问题如果没日志，排查起来就是盲人摸象。我一般会在注册中心的invoke方法里统一加日志，记录谁调的、传了什么参数、执行了多久、返回了什么。这些日志不仅能排查问题，还能分析哪些技能常用、哪些没人用，为后续优化提供依据。

日志里要注意别记录敏感信息，比如用户密码、完整身份证号。可以在记录前做一层脱敏，只保留必要字段。另外，日志量大的话记得做采样或分级，别把磁盘写爆了。

7. 我个人的一些实操体会

搭 agent-skills 这套东西，最大的感受是**“慢就是快”**。一开始你可能觉得每个技能都要写描述、定参数、做校验，很繁琐，不如直接写个大提示词来得快。但等到技能数量上去、业务逻辑变复杂，你会发现前期这些“繁琐”的工作全都在帮你省时间。改一个技能不影响其他技能，加一个技能不用动老代码，这种清爽感是大提示词给不了的。

另一个体会是描述的重要性怎么强调都不过分。我现在的习惯是，技能代码可能十分钟写完，但描述要反复改好几轮，甚至拿真实用户问题去测试模型能不能正确选中。描述写好了，后面几乎不用怎么调；描述写不好，天天都在救火。

最后分享一个小技巧：给技能加一个“使用示例”字段。在描述里附上一两个典型的调用例子，比如“用户问‘我的订单 123456789012 到哪了’，应调用本技能，参数 order_id 为 123456789012”。实测下来，加了示例的技能，模型调用准确率能提升不少。这个字段不是必须的，但性价比极高，值得一试。

这套东西后续还能往很多方向扩展，比如给技能加权限控制、加计费统计、加异步执行。但那是后面的事了，先把最小可用版本跑起来，比什么都重要。