企业官网建设流程全解析

在接触了大量 Agent 项目之后，我越来越确信一件事：决定一个智能体能走多远的，不是模型的聪明程度，而是它的技能层。模型再强，技能系统一团糟，落地的时候照样四处漏风。我们在生产环境遇到过很多次这种状况——Agent 在 demo 里表现得像个老员工，一上真实业务就频繁调用错误的工具、在无关技能之间反复横跳，甚至把上下文撑爆直接报错。排到最后，问题的根子几乎都出在一个地方：agent-skills 没有设计好，技能之间毫无边界和章法。这篇文章我想把这些实操中的思考和踩坑记录整理出来，给正在构建智能体技能系统的朋友做一个参考。

1. 先搞清楚一件事：Skills 不是会调用的函数，而是 Agent 的能力骨架

很多人会把 agent-skills 理解成一个简单的函数列表：给模型一些带描述的 JSON Schema，让它按需调用，完事。这种理解在玩具项目里没问题，但一旦进入真实业务场景，它就会成为最大的隐患。

1.1 为什么功能函数和技能不是一个概念

函数是代码层面的东西，形如：

def get_weather(city: str) -> str: ...

它只关心输入和输出。但技能是一个完整的能力单元，它至少包含五个维度：

• 触发条件：什么情况下模型应该使用这个技能，什么情况下绝对不该用
• 输入约束：参数的取值范围、必填项、默认值，以及模型理解模糊时的兜底策略
• 执行策略：调用外部 API 时是否需要重试和超时控制，是否需要二次确认
• 副作用说明：这个技能会不会修改数据、扣费、发消息，如果有副作用，模型决策时要不要额外谨慎
• 错误语义：失败时该怎么反馈给模型，是返回"系统错误"还是返回"查询范围过窄，请扩大时间窗口"

这五个维度真正决定了 Agent 的行为边界。一个函数只是机械地计算，而技能则参与了模型的前置决策——它可以告诉模型：什么场景该出手，什么场景该闭嘴。

我见过最典型的反面案例，是把一个"发送营销短信"的功能直接暴露给模型，没有在技能层做任何边界约束。结果模型在用户问"我这个月话费怎么这么高"的时候，居然调用营销短信技能给用户发了一堆促销消息。功能函数没有任何责任，但技能的决策权在模型手里，技能边界不清，模型的判断就会失控。

1.2 技能层是模型推理和外部世界的翻译器

再往深一层看，agent-skills 实际上承担了一个翻译角色：LLM 对世界的理解是建立在文本和语义空间里的，而外部系统需要的是精确的结构化指令。技能就是这个翻译器。

举个具体的例子。用户问"帮我看看北京明天适合穿什么"，你事件设计和提供的能力可能包括：

{ "name": "query_weather", "description": "用于查询世界主要城市的实时天气和未来三天的温度、降水、风力状况", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "城市中文名，如北京、上海、广州"}, "date": {"type": "string", "description": "查询日期，格式 YYYY-MM-DD，默认今天"}, "metric": {"type": "string", "enum": ["temperature", "precipitation", "wind"]} }, "required": ["city"] } }

模型看到的不只是几个参数，而是这段描述里隐含的一个承诺：这个技能能理解"明天"这种相对时间表达，并把它转成具体的日期值；能理解"适合穿什么"需要的是温度和降水的组合信息。所以技能描述写得越贴近真实能力边界，模型的调用成功率就越高。

如果技能系统只是机械地把函数签名翻译成 JSON 塞给模型，相当于给了一个没有操作说明的复杂机器——模型能力强还能猜一猜，弱一点的直接原地崩溃。技能层做得好的项目，通常都会花很大精力打磨 description 字段，把它当成和模型交互的接口协议来对待，而不是顺手填一句话。

1.3 技能是动态的，不是静态的折旧品

还有一个很容易被忽略的视角：Agent 的技能不应该是一成不变的。人也是这样，新任务出现时学新技能，技能过时时就要淘汰。如果你的技能系统设计成每次新增能力都要改代码重新部署，那就等于把 Agent 锁死在了开发迭代周期里。

真正可用的技能系统，应该把技能的注册、更新、启停做成运行时能力。也就是说，运营一个 Agent 更像在管理一支团队：技能库是团队的作战手册，而不仅仅是几段代码的集合。你随时要能加技能、改技能描述、下架有问题的技能，而这些操作不能影响整体的稳定性。

这些思考，直接决定了我在搭建技能系统时选什么样的架构。接下来详细说说落地过程。

2. 技能系统怎么设计才稳：注册中心、路由策略和上下文隔离

2.1 零散技能就是一场灾难，先建一个注册中心

无论你是用 LangChain、OpenAI Function Calling，还是自研的 Agent 框架，第一步永远是统一管理技能清单。我在项目里称之为技能注册中心（Skill Registry），它是一个拥有完整元数据的能力目录，而不是一堆散落各处的 Python 函数。

注册中心的核心数据结构，我一般推荐这样设计：

这个注册表解决了三个痛点：

• 技能可见：每添加一个技能，都必须经过注册流程，任何人不能绕过注册直接拼一个 function 进去。这样整个系统的能力边界是一目了然的。
• 描述一致：同一个技能不会出现在多个地方，避免不同插件模块里各写一份割裂的描述。
• 权责清晰：每次修改都有记录可查，生产环境出问题了能快速定位是哪个技能在哪个时间段变过。

我见过太多没有注册中心的项目：技能散落在不同模块里，有的写在 prompt 里，有的写进工具列表，有的干脆塞在业务代码的 if-else 里。这种项目前期跑得快，后期维护就是噩梦。模型行为稍微一变，你都说不清楚它是被哪份技能描述影响的。

2.2 路由策略：给模型一份精简但完整的技能候选集

解决了技能管理问题之后，下一个挑战是把技能送到模型面前的方式。很多人一开始会把全部技能一股脑塞进每条请求里，这在技能数量超过 20 个之后就会出问题：

• 入参 token 消耗巨大，每条请求都要背负所有技能的描述
• 技能之间相互干扰，模型在太长的候选列表里更容易产生幻觉调用

所以我最终的方案是动态路由。具体拆分两层：

• 粗选层（Retriever）：用 embedding + 关键词匹配，从技能注册中心里筛出与用户意图最相关的 Top 5~8 个技能作为候选集。
• 精排层（模型决策）：把候选集的全量描述交给模型，模型基于完整描述精准选择要调用的技能和参数。

粗选层其实可以直接用文本相似度实现。核心代码逻辑大致是：

from sentence_transformers import SentenceTransformer import numpy as np model = SentenceTransformer('paraphrase-multilingual-MiniLM-L12-v2') def retrieve_skills(query, skill_docs, top_k=5): query_embedding = model.encode([query]) skill_embeddings = model.encode(skill_docs) scores = cosine_similarity(query_embedding, skill_embeddings) top_indices = np.argsort(scores[0])[::-1][:top_k] return [skill_docs[i] for i in top_indices]

这里有个容易被忽视的细节：技能描述文档（skill_docs）的生成方式。我建议不只把 description 字段做 embedding，而是把名字、描述、输入参数说明、典型使用场景拼接成一份连续的文本再编码。这样，语义匹配的空间更加丰富，模型"知道"技能的真实使用边界，而不是每次都在一个干燥的字段里捞信息。

动态路由的效果非常明显。在我们的实测里，技能数量从 15 个扩展到 60 个之后，每条请求的 token 消耗几乎没变，而模型的选择准确率反而因为干扰减少而上升了几个点。这就是典型的"少即是多"。

2.3 上下文隔离：技能信息不能污染对话记忆

技能系统的另一个大坑，是技能执行结果和对话记忆搅在一起。很多初学者会直接把 function_call 的结果当作普通消息 append 到 messages 里，下一次对话又把这些内容全部发给模型。这会导致两个问题：

• token 浪费严重：一次技能返回的长文本会被反复携带，哪怕下一次对话根本用不上
• 语义干扰：模型会把技能返回的过程细节当成用户意图的一部分，严重影响后续推理

后来我把上下文做了严格隔离。技能调用的上下文分成三层：

这三层的分工非常明确：模型做决策时看到的，永远是压缩后的摘要和长期记忆，而不是一次技能调用产生的原始海量输出。这就要求技能返回结果的设计也和普通函数不同——技能不仅要返回原始数据，还要生成一段适合沉淀进记忆的摘要文本。

我在技能开发规范里定了一条规则：每个返回结构化数据的技能，必须额外提供一个memory_summary字段。这个字段是给模型看的、经过提炼的自然语言结论，其他原始数据只用于本次展示和短时赋值。

这样设计之后，长会话中的模型表现稳定了很多。之前那种"聊了二十轮之后，模型开始胡言乱语"的情况，大量减少。原因很简单：模型的上下文窗口终于有了清晰的结构，技能产生的噪音没有在对话空间里无限累积。

3. 我踩过的三个坑：幻觉调用、命名冲突、上下文膨胀

搞技术的人都清楚，文档里写出的架构和真实运行的效果永远是两回事。技能系统真正上线、被各种真实流量打过之后，那些隐蔽的问题才会暴露出来。这一节把这三个印象很深的坑还原一下，也许能帮你少走几个月弯路。

3.1 幻觉调用：模型调用了根本不存在的技能

第一次遇到这个问题时的场景我记得很清楚。生产环境日志里突然出现了大量 404 报错，排查后发现，模型在某几轮对话中调用了一个叫query_refund_status的技能，但我们注册中心里根本没有这个技能，只有一个外形相似度极高的query_order_detail。

当时的第一反应是怀疑 embedding 路由出了问题，但回查发现路由是正常的——候选集里根本没有query_refund_status。问题出在模型自身：它在生成 function_call 的时候，根据用户描述"我退款到哪一步了"，自己脑补了一个技能名，而不是从候选技能列表里做选择。

这个坑的根子在于，技能信息进入模型的方式不够闭环。当你把技能用 Function Calling 格式传给模型时，模型理论上只能在给定列表里选名字，但如果你用的是 Prompt + JSON 输出或者某些宽松的 Agent 框架，模型就有机会发挥创造性。

解决方案分成三层，层层加固：

• 第一层：路由结果不仅要给模型看，还要在系统层做一次硬校验。模型返回的function_name必须存在于当前请求路出的候选技能集合中，否则视为无效调用，强制进入纠错流程。
• 第二层：纠错流程里，把候选技能的名称列表和简短说明再给模型看一次，明确告诉它只能选这些。通常第二轮的准确率就回到正常水平了。
• 第三层：给模型明确加一条系统提示："如果没有任何技能能解决用户的问题，直接告诉用户做不到，不要尝试编造一个不存在的能力。"

最终的效果立竿见影。这也让我意识到，agent-skills 系统必须有两个层面的保障：一个是模型决策层的智能，另一个是执行层的硬校验。两者缺一不可，绝不能把所有信任都放在模型的判断上。

3.2 命名冲突：两个技能语义重叠，谁该被调用

第二次大规模踩坑，发生在技能数量增长到 40 个左右的时候。当时我们有两个技能，一个叫get_warehouse_stock，另一个叫query_supplier_inventory。产品经理的角度它们是有明显区别的，前者查自家仓的实时库存，后者查上游供应商的可供量。但对一个语言模型来说，这两个描述几乎是一样的东西——"库存查询"。

结果就是模型的选择概率几乎随机。有些对话里它选了前者，有些对话里它选了后者，客户看着明明是同一个问题，两次得到的数据却完全对不上。更麻烦的是，由于两个技能的返回结构不完全一致，下游解析逻辑经常报错。

排查到最后，我并不想直接删掉其中一个技能，因为它们的业务逻辑确实不同。于是我换了个思路：重构两个技能的描述，让它们的边界彻底互斥。

新的描述写法是这样的：

• 第一个技能重点强调"查询自有仓库的实时库存水位，数据源为 WMS 系统，单位为箱"
• 第二个技能重点强调"查询外部供应商未来 30 天的承诺供货量，数据源为供应商协同平台，单位为件"

同时，我在描述里主动加入"该技能不适用于..."的负向边界条件。这一点被太多人忽视了——正向描述管用，但负向排除同样关键。当一个技能和其他技能语义相近时，明确写上"这个技能不会做什么"能显著降低模型的混淆概率。

这个优化上线后，我们把两个技能的混淆错误率从接近 30% 降到了 5% 以下。从那以后，每新增一个技能，我都会先做一件事：把新技能和所有存量技能的 embedding 两两计算相似度，凡是相似度超过阈值的，必须给出充分的差异理由，否则不允许注册。这个机制成了技能注册中心的准入必备流程。

3.3 上下文膨胀：技能说明书太长，把思路都堵住了

第三个坑比较隐蔽，是随着技能描述精修一起出现的。前面说描述写得越详细越好，这是对的，但它有一个隐藏代价：token 消耗。

我们曾经把一个技能的描述写到接近 500 字，因为它太重要了，我们想尽办法让模型理解它。结果每条路由后的候选技能集是 6 个技能，光技能说明书就占了快 3000 token。加上历史对话和系统提示，一次请求动辄 6000 到 8000 token。这在本地调试时完全看不出来，但到了线上、并发量一上来，成本和延迟全炸了。

做了一番优化之后，我的原则变成了：描述信息分层投放。

• 路由匹配阶段：使用详细的技能全描述，保证检索准确
• 模型决策阶段：使用精简版描述，只保留能力边界和关键约束，控制在 80 到 150 字之间
• 模型调用的 schema 参数详解：通过参数本身的 description 字段承载，不再额外堆在技能总描述里

这样一来，模型看到的信息密度反而更高了，token 消耗也降回到每次请求 3000 token 以内。最关键的经验是：给模型看的技能描述，不是一个越详细越好的文档，而是一份在一定字数限制内的精准情报。信息浓缩度是设计出来的，不是写出来的。

4. 一个可落地的轻量技能编排参考实现

理论说了不少，这里给一份我在项目中反复用过的最小可运行实现。它不依赖任何重型框架，用纯 Python 就能跑通，适合中小型项目直接套用，也适合作为理解 agent-skills 内部机制的起点。

4.1 技能注册与 Schema 生成

核心思路是用装饰器把普通函数变成可注册的技能，并且自动生成 OpenAPI 风格的 Schema。

from typing import Callable, Dict, Any import inspect import json class SkillRegistry: def __init__(self): self._skills = {} def register(self, name=None, description="", permission_level=0): def decorator(func): skill_name = name or func.__name__ schema = self._generate_schema(func) self._skills[skill_name] = { "name": skill_name, "description": description, "function": func, "input_schema": schema, "permission_level": permission_level, "status": "active" } return func return decorator def _generate_schema(self, func: Callable) -> Dict[str, Any]: sig = inspect.signature(func) properties = {} required = [] for name, param in sig.parameters.items(): if param.annotation is not inspect.Parameter.empty: properties[name] = {"type": self._map_type(param.annotation)} else: properties[name] = {"type": "string"} if param.default is inspect.Parameter.empty: required.append(name) return { "type": "object", "properties": properties, "required": required } def get_skill(self, name): skill = self._skills.get(name) if not skill or skill["status"] != "active": return None return skill def all_skills(self): return [ {"name": s["name"], "description": s["description"], "input_schema": s["input_schema"], "permission_level": s["permission_level"]} for s in self._skills.values() if s["status"] == "active" ] registry = SkillRegistry() @registry.register(description="查询指定城市的当前温度和天气状况，城市名使用中文") def get_weather(city: str, unit: str = "celsius"): """模拟天气服务""" return {"city": city, "temperature": 25, "unit": unit} @registry.register(description="计算两个数字之间的数学运算，支持加、减、乘、除") def calculator(expression: str): """模拟计算器""" return {"result": eval(expression)}

这段代码很简略，但已经把注册中心最核心的骨架搭出来了。想直接当生产用还差很多东西，比如参数校验、鉴权、监控、链路追踪，但作为理解技术原理的起点足够了。

4.2 动态候选路由的实现思路

路由层的实现可以严格按照前面说的方法来。先把所有已注册技能的描述文档提前生成并编码，每次请求进来后，对用户 query 做 embedding 和余弦相似度排序，取 Top-K。

import numpy as np def build_skill_docs(registry): docs = {} for skill in registry.all_skills(): doc = f"{skill['name']}: {skill['description']}, params: {json.dumps(skill['input_schema'], ensure_ascii=False)}" docs[skill['name']] = doc return docs # ... 假设 emb_model 是一个加载好的 SentenceTransformer 模型 # skill_embeddings 是提前算好的 {skill_name: np.ndarray} def route_skills(query, docs, embeddings, top_k=5): q_emb = emb_model.encode([query])[0] scored = [] for name, doc in docs.items(): score = cosine_similarity(q_emb, embeddings[name]) scored.append((name, score)) scored.sort(key=lambda x: x[1], reverse=True) return [name for name, _ in scored[:top_k]]

这一步其实很便宜，单条查询的 embedding 时间大约几十毫秒，完全扛得住常见并发。如果你想更快，还可以用向量数据库做 ANN 检索，但项目早期没必要整这些花活，内存计算完全够用。

4.3 执行链路里的硬校验

模型返回的 function_call 里带着一个技能名和入参。我这里做的第一件事不是马上去执行函数，而是做三重检查：

def execute_skill_call(registry, skill_name, arguments, allowed_skills): # 第一重：技能是否存在于全量注册表 skill = registry.get_skill(skill_name) if not skill: return {"error": "skill_not_found", "message": f"技能 {skill_name} 不存在或已停用"} # 第二重：技能是否在当前请求允许的候选集合内 if skill_name not in allowed_skills: return {"error": "skill_not_allowed", "message": f"技能 {skill_name} 不在本次调用允许列表中"} # 第三重：权限检查 if skill["permission_level"] >= 2: need_confirmation = True # 参数校验 try: validated_args = validate_args(skill["input_schema"], arguments) except SchemaValidationError as e: return {"error": "schema_validation_failed", "message": str(e)} return skill["function"](**validated_args)

这套写法最大的收益不是功能，而是把"错误返回"当成一等公民。模型调用失败、校验不过、参数不对，都能返回一个结构化的错误对象。这个对象会被交给语料摘要层，最终变成给模型的一句话反馈，比如："查询失败，原因是参数缺失：缺少城市名。请向用户确认后再试。"这比直接抛一个 TypeError 出去让模型原地发懵强太多了。

4.4 如何给模型构造最终输入

模型最终看到的，是一个精简过的技能候选集。我一般把格式拼成下面这样的消息块：

{ "role": "system", "content": "你是一个智能助理。以下是你当前可以调用的工具列表。只能调用列表中的工具，如果你认为没有任何工具可以解决问题，直接告知用户。\n\n" "工具1: get_weather\n描述: 查询指定城市的当前温度和天气状况，城市名使用中文\n参数: {\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"]}\n\n" "工具2: calculator\n描述: 计算两个数字之间的数学运算，支持加、减、乘、除\n参数: {\"type\":\"object\",\"properties\":{\"expression\":{\"type\":\"string\"}},\"required\":[\"expression\"]}" }

注意这里的描述长度已经被我压缩过了。精简版描述是一个单独维护的字段，不是从注册中心的长描述里直接截断。截断会产生语义残缺，单独维护才能保证信息完整但密度高。这一步很琐碎，但对生产效果影响极大。

5. 想让技能系统能用三年，这几个进阶方向得考虑

如果只是跑 demo，前面四章的内容已经够了。但真实世界的 Agent 是要长期演进、不断叠加新能力的，所以技能系统在设计之初就要预留几个进阶方向。

5.1 组合技能：让 Agent 学会编排而不是每次现跑

我的观察是，单一技能能解决的问题是有限的，真正的价值在于让 Agent 有能力把多个技能组合成一条完整的工作流。比如"用户想查一下上个月的订单里有没有出口的订单"，这个需求本身可能需要三个技能：query_orders、query_region_filter、format_report。

组合技能不是硬编码工作流，而是把组合链路也抽象成一个新的技能。我倾向于用"计划-执行-总结"三层来组织：

• 计划层：模型先拆解用户任务，判断需要哪些原子技能
• 执行层：路由系统根据拆解结果逐一调用原子技能，每一步都返回结构化结果
• 总结层：把多技能的中间结果汇聚成面向用户的最终答案

做了组合技能之后，我体会到最大的区别在于：Agent 的行为开始变得有层次感。用户的问题不再直接映射到单个函数，而是先被理解成业务目标，再被翻译成形如"先查订单、再过滤地区、再统计金额"的执行计划。这种"可能会让远离业务的模型更稳定，因为它不需要从用户话语凭空跳到一个函数，而是通过中间规划缓冲了一层。

5.2 技能加缓存：高频技能不能每次都不计代价地执行

有一个很容易被忽视的事实：Agent 技能的调用成本往往不在模型 API 上，而在技能本身调用的下游服务上。比如查一个报表，底层可能关联数据库查询、数据仓库调度、甚至第三方接口扣费。如果用户问了同一个问题两遍，Agent 老老实实把完整链路再走一遍，那就是纯浪费。

我给高频技能设计了一个轻量缓存方案，缓存键由技能名、入参 JSON 的规范化排序、以及上下文指纹三部分组成。TTL 按技能类型不同而不同——查天气可以缓存 10 分钟，查用户账户余额最多缓存 30 秒。

from functools import lru_cache import hashlib import json def build_cache_key(skill_name, args, ttl_signature=""): raw = json.dumps(args, sort_keys=True, ensure_ascii=False) payload = f"{skill_name}|{raw}|{ttl_signature}".encode() return hashlib.md5(payload).hexdigest()

这里的关键不是缓存库怎么选，而是缓存的内容形态。缓存的应该是技能的最终结构化结果，附带记录缓存命中时的上下文摘要，这样即使缓存过期了，也能追溯它曾经产生的对话影响。让技能系统有可观测性，比给技能增加更多功能更重要。

5.3 技能自省：让 Agent 动态认识自己的能力边界

目前大多数技能系统是"外挂式"的——注册中心有什么，Agent 就会什么。但更理想的状态是技能系统能主动感知自身的能力盲区，并在合适的时机给出反馈。我把它称作技能自省（Skill Introspection）。

实现方式不复杂，就是给模型一个特殊的list_my_skills技能，它允许模型在对话中途检索当前可用的技能列表，甚至能查询某个技能的详细描述。当用户提出一个不在现有候选集里的需求时，模型可以通过自省确认："我的技能库里没有查汇率的能力"，然后主动告知用户。这比模型基于不完整信息硬猜一个技能去调用要强得多。

这个设计也大大减轻了路由的负担。因为有些用户意图本身就是模糊的，可能牵扯多个技能，与其靠 embedding 一次猜准，不如让模型自己通过自省技能做二次确认。实测下来，自省机制在处理长尾需求、跨领域问题时的准确率提升非常明显。代价是多了 1 到 2 轮系统内部的交互延迟，但换来的是更可靠的决策质量，这个买卖划算。

5.4 可观测性：没有 trace，就别谈调优

最后一条，也是我个人的血泪教训：技能系统必须从第一天就埋好可观测性点，而不是等功能跑挂了再去补。我通常要求每一个技能的调用生命周期都记录四类数据：

有了这些数据，调优就变成了查数据、看分布、下结论的过程，而不是拍脑袋。我们经常在 trace 里发现，某类业务场景下模型反复选了错误技能，从而倒逼出技能描述的重写方向——这比凭空猜模型"怎么了"靠谱得多。

这条实践贯穿始终：技能系统的每一次优化，都必须有数据支撑。没有 trace 的 Agent 项目，就像不带仪表盘的飞行器，看着在飞，其实随时可能失速。

关于 agent-skills，我目前的思考和实践大体就是这些。回头再看，所有踩过的坑其实都指向同一个核心认知：技能系统不是模型的附属品，而是决定 Agent 行为质量的骨架工程。把技能注册、路由、隔离、校验和可观测性这五件事想透了，Agent 的稳定性和可扩展性自然就上来了。