企业官网建设流程全解析

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

如果你最近半年一直在折腾大模型应用，大概率会有一种强烈的割裂感：模型在对话框里上知天文下知地理，可一旦让它去实际操作系统、查数据库、发邮件、跑脚本，它就开始一本正经地胡说八道。这个现象背后其实是一个很朴素的事实——语言能力不等于执行能力。而agent-skills这个项目，本质上就是在给智能体补上“执行能力”这一课。

我先把话说直白一点：agent-skills是一套围绕智能体能力封装、注册、调度与复用展开的工程化方案。它要解决的核心问题是——当你有十几个甚至几十个不同来源、不同协议、不同权限边界的工具时，怎么让智能体知道“我现在该用哪个”“怎么用”“用错了怎么办”。这听起来像是个调度问题，但真正落地过的人都知道，它同时牵扯到能力描述规范、参数校验、上下文注入、错误恢复、权限隔离这一整条链路。

适合谁来参考这份内容？三类人。第一类是正在做智能体应用的后端或全栈开发者，你手里已经有一个能跑通 demo 的 agent，但一到真实业务场景就各种翻车；第二类是负责把内部系统接入智能体的平台工程师，你需要一套可维护、可扩展的能力注册机制；第三类是对智能体架构感兴趣、想搞清楚“工具调用”底层到底怎么运转的技术爱好者。不管你是哪一类，接下来的内容都会从设计思路一路讲到实操细节和踩坑记录。

我个人的判断是，agent-skills这类项目真正的价值不在于它封装了多少个工具，而在于它定义了一套能力契约。工具是消耗品，契约是资产。你把契约设计好了，后面接一百个工具和接十个工具，维护成本不会线性增长。这一点，是我在踩了无数次“工具描述写得太随意导致模型乱调用”的坑之后才真正想明白的。

2. 整体架构设计：为什么要把“技能”单独抽一层

2.1 核心设计思路与分层逻辑

很多人一开始做智能体，习惯把工具定义直接塞进 prompt 里，或者写一个巨大的if-else分发函数。项目小的时候没问题，一旦工具数量超过七八个，你就会发现两个致命问题：一是 prompt 越来越长，模型注意力被稀释，调用准确率断崖式下跌；二是新增一个工具就要改动核心调度代码，牵一发动全身。

agent-skills的思路是把“技能”抽象成一个独立层，夹在智能体核心和底层工具之间。这一层负责三件事：技能的声明式描述、技能的动态注册与发现、技能的调用编排与结果归一化。你可以把它理解成一个“技能中间件”——智能体不直接碰工具，而是通过技能层来间接操作。

为什么这么设计？因为智能体和工具之间的关系，本质上是一种运行时协商。智能体在每一轮推理时，需要知道“当前有哪些技能可用”“每个技能需要什么参数”“调用后会返回什么结构”。如果这些信息是硬编码的，那智能体就失去了灵活性；如果这些信息是动态查询的，那技能层就必须承担起描述和校验的职责。

我试过两种极端方案。方案 A 是把所有工具描述拼成一个超长 system prompt，实测下来在工具数量超过 12 个之后，模型选错工具的概率明显上升，而且 prompt token 消耗非常夸张。方案 B 是让模型先输出一个“意图”，再由规则引擎匹配工具，结果发现规则引擎的维护成本比 prompt 还高。agent-skills走的是中间路线：技能描述结构化存储，按需注入上下文，调用前做参数校验。这个平衡点，是我目前认为最稳的。

2.2 技能描述规范：让模型“看得懂”也“用得对”

技能描述是整个项目的基石。描述写得好，模型调用准确率能到 90% 以上；描述写得烂，再强的模型也救不了你。一个合格的技能描述至少包含五个字段：名称、功能说明、参数 schema、返回值结构、调用示例。

名称要短且唯一，最好用动词开头，比如search_docs、send_notification、query_metrics。功能说明要用自然语言写清楚“这个技能做什么”和“什么时候该用”，注意是“什么时候该用”而不是“怎么用”。参数 schema 建议直接用 JSON Schema 描述，因为主流模型对 JSON Schema 的理解已经相当成熟。返回值结构要明确告诉模型“你会拿到什么”，这样它才能决定下一步怎么处理。调用示例是最容易被忽略但最有价值的部分——给一个真实的输入输出样例，模型对参数格式的理解会准确得多。

这里有个细节值得展开：功能说明里一定要写“不适用场景”。比如一个查询订单的技能，你要明确写“本技能仅用于查询已有订单，不用于创建或修改订单”。我实测发现，加上这句否定约束后，模型误用该技能去执行写操作的概率大幅下降。这个技巧在官方文档里很少提，但实战中非常管用。

2.3 注册与发现机制：动态扩展的关键

技能注册机制决定了你的系统能不能“热插拔”。agent-skills采用的是注册表 + 装饰器的模式。每个技能在定义时通过装饰器自动注册到一个全局注册表，注册表负责维护技能元数据、版本信息和可用状态。

为什么不用配置文件？因为配置文件在技能数量多的时候会变得难以维护，而且无法在技能内部做参数校验和依赖注入。装饰器模式的好处是，技能的定义和注册在同一个地方完成，代码即文档，改起来不容易漏。

注册表还需要支持按标签过滤。比如你可以给技能打上readonly、write、admin这样的标签，然后在不同场景下只暴露特定标签的技能。这个设计在权限隔离场景下特别有用——面向普通用户的智能体只加载readonly技能，面向管理员的智能体才加载write和admin技能。我踩过的坑是，早期没做标签隔离，结果测试时模型调用了一个删除数据的技能，虽然是在测试环境，但也吓出一身冷汗。

3. 核心细节拆解：参数校验、上下文注入与错误处理

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

模型生成参数的能力很强，但也很“自信”。它经常会生成一些看起来合理但实际不存在的参数值，比如把日期写成2024-13-45，或者把枚举值写成近义词。如果你不做校验，这些错误会一路传到下游系统，轻则报错，重则产生脏数据。

agent-skills的参数校验分两层。第一层是结构校验，用 JSON Schema 检查参数类型、必填项、枚举范围。第二层是语义校验，针对具体技能做业务规则检查，比如日期不能晚于今天、ID 必须符合特定格式。结构校验可以自动化，语义校验需要每个技能自己实现。

这里有个实操心得：校验失败时，返回给模型的错误信息要具体且可操作。不要只说“参数错误”，而要写“参数start_date格式错误，期望格式为 YYYY-MM-DD，实际收到 2024/01/01”。模型拿到这种具体反馈后，自我修正的成功率会高很多。我做过对比测试，模糊错误信息的重试成功率大概在 40% 左右，具体错误信息能到 75% 以上。

3.2 上下文注入：给模型“刚刚好”的信息

上下文注入是个技术活。注入太少，模型不知道有哪些技能可用；注入太多，token 爆炸且干扰推理。agent-skills的策略是按需注入 + 分层摘要。

按需注入的意思是，不是所有技能都一股脑塞给模型，而是根据当前对话的意图和已加载的技能标签，动态筛选出最相关的几个技能。分层摘要的意思是，每个技能先给一个一句话摘要，模型如果对某个技能感兴趣，再展开完整描述。这个机制模拟了人类查阅手册的习惯——先看目录，再看详情。

具体实现上，我建议维护一个技能向量索引。把每个技能的功能说明做 embedding，当用户输入到来时，先做一次语义检索，召回 top-k 相关技能，再把这些技能的完整描述注入上下文。实测下来，这种方式比全量注入的调用准确率高出不少，而且 token 消耗能降低 60% 以上。

3.3 错误处理与重试：让智能体“摔倒了能爬起来”

智能体调用技能失败是常态，不是异常。网络抖动、下游服务超时、参数校验不通过、权限不足，这些都会导致调用失败。关键不在于避免失败，而在于失败后能不能优雅恢复。

agent-skills的错误处理遵循三个原则：错误分类、有限重试、降级兜底。错误分类是把错误分成“可重试”和“不可重试”两类，比如超时是可重试的，参数错误是不可重试的。有限重试是指重试次数要有上限，一般 2 到 3 次，每次重试之间加退避延迟。降级兜底是指当所有重试都失败后，要有一个备选方案，比如返回缓存数据、调用备用技能、或者明确告诉模型“这个技能暂时不可用，请尝试其他方式”。

我踩过的一个坑是：早期没做重试上限，结果一个下游服务挂了，智能体疯狂重试，直接把配额耗光了。后来加了指数退避和最大重试次数，才稳定下来。另一个坑是错误信息没有结构化，模型拿到一堆堆栈信息完全不知道该怎么办。后来统一成{error_type, error_message, suggestion}的结构，模型的处理能力明显提升。

4. 实操过程：从零搭建一个可用的技能系统

4.1 环境准备与依赖安装

假设你用的是 Python 技术栈，先把基础环境搭起来。我推荐用虚拟环境隔离依赖，避免和系统 Python 冲突。

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

pydantic用来做参数模型定义和校验，jsonschema用来做 JSON Schema 校验，openai是模型调用 SDK。如果你用的是其他模型，替换成对应的 SDK 即可。版本方面，pydantic建议用 2.x，因为 1.x 和 2.x 的 API 差异较大，网上很多示例还是 1.x 的写法，容易踩坑。

4.2 定义第一个技能：从描述到注册

先定义一个最简单的技能，比如查询天气。技能定义包含三部分：元数据、参数模型、执行函数。

from pydantic import BaseModel, Field from agent_skills import skill, SkillRegistry class WeatherParams(BaseModel): city: str = Field(..., description="城市名称，如北京、上海") date: str = Field(..., description="日期，格式 YYYY-MM-DD") @skill( name="query_weather", description="查询指定城市指定日期的天气情况。仅用于查询天气，不用于其他用途。", tags=["readonly"], params_model=WeatherParams ) def query_weather(params: WeatherParams) -> dict: # 实际实现中调用天气 API return {"city": params.city, "date": params.date, "weather": "晴", "temp": "25C"}

这段代码里，@skill装饰器做了几件事：把技能注册到全局注册表、从params_model自动生成 JSON Schema、把函数和元数据绑定。description里我特意加了“仅用于查询天气，不用于其他用途”，这就是前面提到的否定约束。

4.3 技能调度器的实现要点

调度器是技能系统的“大脑”。它接收模型输出的技能调用请求，找到对应技能，校验参数，执行，然后归一化结果。核心逻辑大概长这样：

class SkillDispatcher: def __init__(self, registry: SkillRegistry): self.registry = registry def dispatch(self, skill_name: str, raw_params: dict) -> dict: skill = self.registry.get(skill_name) if not skill: return {"error_type": "not_found", "error_message": f"技能 {skill_name} 不存在", "suggestion": "请检查技能名称或尝试其他技能"} try: params = skill.params_model(**raw_params) except ValidationError as e: return {"error_type": "invalid_params", "error_message": str(e), "suggestion": "请根据错误信息修正参数后重试"} for attempt in range(3): try: result = skill.func(params) return {"error_type": None, "data": result} except TimeoutError: if attempt == 2: return {"error_type": "timeout", "error_message": "调用超时", "suggestion": "请稍后重试或使用备用技能"} time.sleep(2 ** attempt) except Exception as e: return {"error_type": "execution_error", "error_message": str(e), "suggestion": "请检查输入或联系管理员"}

这段代码里有几个关键点。第一，参数校验失败直接返回，不进入重试逻辑，因为参数错误重试多少次都一样。第二，只有超时才重试，其他异常直接返回，避免无意义的重试。第三，所有返回都是结构化字典，包含error_type、error_message、suggestion三个字段，方便模型理解。

4.4 与模型对接：把技能描述注入对话

最后一步是把技能描述注入到模型的对话上下文中。我通常会在 system prompt 里加一段技能清单，格式如下：

你可以使用以下技能来完成任务： 1. query_weather 功能：查询指定城市指定日期的天气情况。仅用于查询天气，不用于其他用途。 参数：city (string, 必填), date (string, 必填, 格式 YYYY-MM-DD) 返回：包含 city, date, weather, temp 的 JSON 对象 调用技能时，请输出 JSON 格式：{"skill": "技能名", "params": {...}}

这个格式的好处是结构清晰，模型容易解析。我试过用 XML 格式和 YAML 格式，实测下来 JSON 的调用准确率最高。另外，技能清单不要一次性全量注入，按前面说的向量检索召回 top-k 即可。

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

5.1 模型选错技能怎么办

这是最高频的问题。排查思路分三步。第一步，检查技能描述是否有重叠。如果两个技能的功能说明语义相近，模型很容易混淆，解决办法是在描述里明确区分边界，比如“技能 A 用于查询，技能 B 用于修改”。第二步，检查是否有否定约束。前面说过，加上“不用于 XX”能显著降低误用。第三步，检查召回逻辑。如果召回阶段就把正确技能漏掉了，后面再优化描述也没用。

我遇到过一个典型案例：一个系统里有get_user_info和get_user_profile两个技能，功能说明都写得很模糊，模型经常混用。后来把前者改成“根据用户 ID 查询账号基础信息（用户名、注册时间）”，后者改成“根据用户 ID 查询个人资料（头像、签名、偏好设置）”，调用准确率立刻上来了。

5.2 参数格式错误怎么破

参数格式错误通常有三种原因：模型对格式理解不到位、技能描述里没写清楚格式、模型“自作聪明”做了转换。解决办法是在参数描述里给出明确示例，比如date: string, 格式 YYYY-MM-DD, 例如 2024-01-15。另外，可以在校验失败时返回具体的格式要求，让模型自我修正。

如果模型频繁把数字写成字符串，或者把字符串写成数字，可以在 JSON Schema 里用oneOf或者自定义校验器做兼容处理。我一般建议在校验层做宽松处理，在执行层做严格处理，这样既能提高成功率，又能保证数据质量。

5.3 技能执行超时怎么处理

超时是分布式系统的常态。处理策略分三层：超时设置、重试策略、降级方案。超时设置要根据技能的实际耗时来定，查询类技能一般 5 到 10 秒，写入类技能可以放宽到 30 秒。重试策略用指数退避，第一次等 1 秒，第二次等 2 秒，第三次等 4 秒。降级方案要提前准备好，比如返回缓存数据、调用备用接口、或者明确告诉模型“该技能暂时不可用”。

我踩过的一个坑是：超时时间设得太短，导致很多正常请求被误判为超时。后来统计了实际耗时分布，把超时时间设在了 P99 耗时之上，误判率就降下来了。这个数据一定要自己统计，不要拍脑袋定。

5.4 技能版本管理怎么做

技能是会迭代的。今天query_weather返回temp字段，明天可能改成temperature。如果模型还在用旧字段名，就会出错。解决办法是在技能描述里标注版本，并且保持向后兼容。比如新增字段而不是重命名字段，如果必须重命名，就同时保留旧字段一段时间，并在描述里标注“已废弃”。

注册表要支持多版本共存。调用时可以指定版本，不指定就用最新版。这个机制在灰度发布时特别有用——先让一部分流量走新版本，观察没问题再全量。

6. 技能系统的扩展方向与个人经验

6.1 从单智能体到多智能体协作

当技能数量继续增长，单个智能体可能管不过来。这时候可以考虑多智能体架构：每个智能体负责一个领域的技能，智能体之间通过消息传递协作。agent-skills的技能注册表可以升级成分布式的，每个智能体只加载自己领域的技能，通过一个协调者来路由跨领域的请求。

这个方向我还在探索中，目前遇到的主要挑战是智能体之间的通信开销和状态同步。一个可行的思路是用共享内存或者消息队列来做技能调用结果的缓存，避免重复调用。

6.2 技能的组合与编排

单个技能能做的事有限，真正有价值的是技能组合。比如“查询天气 + 推荐穿搭 + 发送提醒”可以组合成一个“出门助手”技能。agent-skills支持技能编排，你可以用声明式的方式定义技能之间的依赖关系和数据流转。

编排的难点在于错误传播。如果组合技能中的某一个失败了，是整体失败还是部分成功？我的建议是定义清楚每个组合的失败策略，是“全有或全无”还是“尽力而为”。这个决策要在设计阶段就定下来，不要等到出问题了再补。

6.3 技能的可观测性建设

技能系统上线后，可观测性是运维的生命线。你需要知道每个技能的调用次数、成功率、平均耗时、错误分布。这些数据不仅能帮你排查问题，还能指导优化方向——比如某个技能调用成功率低，可能是描述写得不好，也可能是下游服务不稳定。

我一般会在调度器里埋点，把每次调用的元数据（技能名、参数摘要、耗时、结果状态）写到日志或者时序数据库。参数摘要要注意脱敏，不要把敏感信息写进去。这个细节很容易被忽略，但一旦出事就是大事。

6.4 我踩过的三个印象最深的坑

第一个坑是技能描述写得太“技术化”。早期我直接把 API 文档复制过来当技能描述，结果模型完全看不懂，调用准确率极低。后来改成用自然语言写“这个技能能帮你做什么”，准确率才上来。模型不是程序员，它需要的是业务语言，不是技术语言。

第二个坑是没有做技能隔离。测试环境和生产环境的技能混在一起，有一次测试时误调了生产环境的写入技能，虽然没造成实际损失，但吓出一身冷汗。后来严格做了环境隔离和标签隔离，才安心。

第三个坑是忽略了 token 成本。技能描述全量注入的时候，一次对话的 token 消耗是现在的三倍多。后来做了向量检索召回，成本降下来了，响应速度也快了。这个优化在技能数量少的时候不明显，一旦超过 20 个技能，差距就非常大了。

6.5 给后来者的几条实用建议

如果你正准备上手agent-skills这类项目，我有几条建议。第一，从三个技能开始，不要一上来就接几十个，先把描述规范、校验机制、错误处理跑通。第二，技能描述要当成产品文案来写，站在模型的角度想“它需要什么信息才能正确调用”。第三，错误信息要具体，这是提升模型自我修正能力的关键。第四，做好可观测性，没有数据你就是在盲人摸象。第五，版本管理要趁早，等到技能多了再补，成本会高很多。

最后分享一个小技巧：定期用一批典型用户输入做回归测试，统计技能调用的准确率和成功率。这个测试集不用很大，几十条就够，但要坚持跑。我自己的经验是，每次修改技能描述后跑一遍回归，能提前发现大部分问题，比等到线上出问题再排查高效得多。