企业官网建设流程全解析

大概半年前，我第一次在项目里大规模引入 agent-skills 这套思路时，团队的反馈是“这玩意儿听着玄，拆开看其实就是给模型配了一套工具箱”。等到真正落地完一套完整的技能库，我才意识到，这个说法既对也不对。对的部分在于，agent-skills 确实是在解决“模型怎么调用外部能力”的问题；不对的部分在于，如果只是把它理解成注册一堆函数，那后面遇到的所有坑——调用不命中、参数传错、上下文被塞爆——你一个都躲不掉。

所以这篇文章，我想从自己的实践出发，把这套技能系统的设计思路、实现细节、踩坑记录完整梳理一遍。它不是一份官方文档的复述，而是一个真实跑过、真实被坑过、又真实修好的项目记录。无论你是在做个人 AI 助手、企业内部的知识库机器人，还是复杂的多智能体系统，这套方法论应该都能给你一个不错的起点。

1. 整体设计拆解：agent-skills 到底在解决什么问题

1.1 没有技能库的 Agent 是什么样的

先说个基本场景。你让一个纯大模型 Agent 去“帮我把桌面上的图片压缩成 webp 格式”，它如果没有任何外部工具，会怎么做？大多数情况下，它会给你生成一段 Python 代码，告诉你“你自己去跑一下”。这已经是表现比较好的模型了，更差的情况是它直接口述一遍操作步骤，然后问你“还有什么可以帮忙的吗”。

这在真实业务场景里完全不可用。我见过不少团队的第一版 Agent 原型就死在这：模型很聪明，对话很流畅，但一涉及实际操作——读写文件、调用接口、操作数据库——就立刻抓瞎。根本原因在于，模型本身是一个“没有手的头脑”，它只能基于训练数据里的知识进行推理和生成，无法主动对真实世界施加影响。

所以就有人想了个办法：既然模型不能直接动手，那我们就给它提供一堆“手”。每个技能函数就是一根手指，技能库就是整只手。模型要做某件事时，先从技能库里挑一个合适的技能，然后按技能的规范填好参数调用，剩下的脏活累活由代码去完成。这就是 agent-skills 要解决的核心问题：把模型的推理能力和真实世界的执行能力桥接起来。

1.2 技能库的设计目标不是“能用”而是“好用”

我在设计第一版技能库的时候，犯过一个很典型的错误：只想着把功能堆上去，结果一个技能库塞了上百个函数，看起来啥都能干，实际上模型根本不知道该在什么场景下调用哪个。后来经过好几轮重构，我才总结出技能库设计的几个核心目标。

第一是调用准确率要高。模型收到用户指令后，能否在技能列表里挑中正确的那个，这直接决定了整个流程的成败。第二是参数理解要稳。用户说得口语化一点、含糊一点，模型也能把参数填对。第三是系统开销要小。每次调用都要把技能列表拼进 prompt，技能多了，token 消耗是个不小的数目。最后是排错要容易。技能执行失败时，错误信息要能清晰地反馈给模型，让它能自己尝试补救，而不是直接把失败甩给用户。

从这几个目标出发，你会发现技能库的设计完全不是“写几个 Python 函数”那么简单。它涉及技能描述怎么写、参数 schema 怎么定义、技能之间怎么组织、错误怎么反馈、上下文怎么管理，每一个环节都值得认真对待。

1.3 常见的技能实现方案对比

在具体实现上，现在业内主要有三种做法。

第一种是纯函数调用，也就是把技能定义为普通的编程函数，通过 JSON Schema 描述参数结构，让模型输出结构化的调用请求，代码端解析后执行并返回结果。几乎所有主流 Agent 框架，比如 LangChain、LlamaIndex、OpenAI Function Calling，都采用这种模式。它的优点是简单直接，生态成熟，缺点是技能之间基本是孤岛，无法互相调用，复杂任务需要编排。

第二种是技能组合链。一个技能内部可以调用另一个技能，形成一个技能依赖图。比如说“生成季度销售报告”这个高层技能，内部会依次调用“查询数据库”“生成图表”“汇总成文档”三个底层技能。这种方式适合业务流程固定的场景，缺点是灵活性差，逻辑写死了，模型没法根据实际对话动态调整链路。

第三种是动态技能生成，模型根据任务描述现场生成执行代码。这种方式最灵活，但风险也最大——生成出来的代码可能有漏洞、行为不可控，生产环境基本不敢用。

我的建议是，在大部分真实场景里，第一种方案就足够用了，撑不住的时候再用第二种把高频链路固化下来。至于第三种，可以在沙箱环境里做研究，但别一上来就往生产放。

2. 技能库的结构设计：从扁平列表到分层体系

2.1 扁平技能列表的致命伤

如果你只给 Agent 配了十来个技能，那扁平列表完全没问题。但一旦技能数量超过二十个，问题就来了。

我用一个很直观的现象来举例。技能列表里同时存在“获取天气信息”和“获取空气质量信息”这两个技能，它们的描述非常接近。模型在解析“明天出门要不要带口罩”这句话时，可能在两个技能之间犹豫很久，甚至直接选错。当你把技能数量扩大到五十个以上时，这种混淆会成倍增加，模型需要比对的选择空间太大，准确率会明显下降。

还有一个更隐蔽的问题：技能列表越长，prompt 里塞的 token 就越多。我在一次压力测试里发现，光是把一百个技能的描述和参数 schema 拼进上下文，就要消耗大约五千个 token。这不仅是钱的问题，更重要的是，过长的上下文会稀释模型对用户指令的注意力。

所以当技能库膨胀到一定规模时，第一步就是做分层。

2.2 我现在采用的三层技能组织

经过几轮迭代，我目前使用的技能库分成了三层：核心技能、领域技能、临时技能。

核心技能是系统的基础能力，任何时候都在技能列表里，数量控制在十个以内。比如文件读写、HTTP 请求、时间查询这类通用能力。领域技能则按业务模块分组，比如“数据分析类技能”“文档处理类技能”“消息通知类技能”。这一层是数量的大头，但它们不会同时全部加载，而是根据对话主题动态注入。临时技能是某个特定会话里临时注册的，用完即弃，一般是一次性任务里临时创建的小工具。

这个设计和模块化编程是同一个思路。你不可能把整个项目的全部代码一次性读入内存，而是要用到哪个模块就加载哪个模块。技能库同理，把好钢花在刀刃上。

2.3 技能分组的动态加载策略

分组容易，关键是“怎么决定这次对话加载哪一组”。我这里提供一个简单可落地的做法：关键词路由。

先给每个技能组定义一组触发关键词，比如“数据分析”组对应“统计、图表、趋势、均值”等词。每次收到用户消息时，先用 embedding 或简单的关键词匹配判断对话属于哪个主题，再只加载对应技能组加上核心技能。这种方式在工程上实现简单，效果也不错。

更进阶一点的做法是用一个轻量级分类模型做意图识别，判断结果再决定加载哪些技能。但说实话，在大多数场景下关键词路由够了，没必要一上来就上模型，成本和延迟都划不来。

这里要特别提醒一个坑：技能分组不是越细越好。如果你把一个业务录成了二十个小组，光路由本身的准确性就成了新瓶颈。我实测下来，五到八个组比较合理，既能减少 token 消耗，又不至于路由自身出错。

3. 核心实现：技能定义格式与注册机制

3.1 技能描述是给模型看的，得说人话

技能定义最关键的部分不是函数实现，而是描述文本。函数实现是给代码看的，写不好最多报个错；描述文本是给模型看的，写不好就直接导致模型不调用或调错。

很多人在这一步踩坑，就是因为把技能描述写成了开发文档的风格。比如：

获取用户信息：从数据库中根据用户ID查询用户详细信息，返回用户基础资料。

这种描述太笼统了。模型看到“用户详细信息”这几个字，并不知道这个技能到底能返回哪些字段，自然也就无法判断“我想知道这个人的手机号”该不该调用它。更好的写法是：

获取用户信息：当用户询问用户的手机号、邮箱、注册时间、会员等级或个人简介时，使用此技能。 输入参数：用户ID或用户姓名。

看出来区别了吗？第二段描述里包含了触发场景和一个关键参数说明，模型不需要靠猜，就能知道什么时候该调、参数该怎么填。

3.2 一个完整的技能定义长什么样

我现在一般用一个统一的字典结构来定义技能，方便注册和后续处理。下面是一个参考示例，语言用 Python 写，但思路是通用的：

skills = [ { "name": "get_user_info", "description": "当用户询问手机号、邮箱、VIP等级、注册时间等个人资料时使用，参数为用户ID或用户姓名", "parameters": { "type": "object", "properties": { "user_id": { "type": "string", "description": "用户的唯一ID，可以从对话上下文中提取" }, "user_name": { "type": "string", "description": "用户的姓名，用于模糊查询" } }, "minProperties": 1, "required": [] }, "handler": get_user_info_handler } ]

注意这里的关键地方。description是给模型看的，必须写明触发场景、参数含义和返回值概要。parameters是给模型当填表指南用的，每个字段都要解释清楚含义，最好能带一个候选值范围，比如“值只能为 'asc' 或 'desc'”。handler是真正干活的函数。

3.3 注册机制的设计

技能注册其实就是把上面这个字典挂到一个全局注册表里，方便后续检索和调用。但有一点要特别提醒：注册表的 id 必须稳定。如果你修改了技能名称或参数结构，所有依赖它的历史对话和缓存都可能会受影响。

我的做法是在注册表里加一个版本字段，每次有破坏性修改就升级版本号。调用记录里存的是技能名称加版本号的组合，这样即使技能有更新，也能查得出来是哪一代的行为。这在生产环境排错时能省下不少口舌。

4. 实操落地：从零搭一个带技能库的 Agent

4.1 环境准备与框架选型

动手之前，先把环境列一下。以下是我本地测试环境的标准配置：

• Python 3.10 以上，建议 3.11，性能更好
• 一个开源 Agent 框架，用 LangChain 或直接裸调 OpenAI SDK 都可以
• 一个本地 LLM 或远程 API，支持工具调用（Function Calling）的模型优先
• 用于测试的本地文件目录或一个简单的 SQLite 数据库

如果你对框架不熟，我的建议是第一次先用裸 SDK 手写一遍调用流程。虽然多写几行代码，但你会对技能调用的完整链路有直观理解。直接从框架入手的话，很多细节会被框架藏起来，出了问题反而不知道怎么排。

4.2 第一步：定义三个实用的基础技能

我以一套最简单的实用技能为例，带大家走通全流程。选择这三个技能是因为它们覆盖了文件读取、数据处理和网络请求三种最常见的 Agent 能力。

# skill_1.py import json def read_file_handler(file_path: str) -> str: try: with open(file_path, "r", encoding="utf-8") as f: content = f.read() return content except Exception as e: return f"读取文件失败: {str(e)}"

第二个技能是计算文本统计信息，比如字符数、行数、词频，这很实用，模型自己算不了这个。

# skill_2.py import collections import re def analyze_text_handler(text: str) -> dict: words = re.findall(r"\b\w+\b", text.lower()) counter = collections.Counter(words) return { "char_count": len(text), "word_count": len(words), "line_count": len(text.splitlines()), "top_words": counter.most_common(5) }

第三个技能是抓取网页标题，用于“看看这个链接是什么内容”这一类需求。

# skill_3.py import requests from bs4 import BeautifulSoup def fetch_page_title_handler(url: str) -> str: try: resp = requests.get(url, timeout=10) resp.raise_for_status() soup = BeautifulSoup(resp.text, "html.parser") return soup.title.string.strip() if soup.title else "未找到标题" except Exception as e: return f"页面获取失败: {str(e)}"

这三个函数不难，重点在于它们对应的技能定义怎么写。我在下一节给出完整注册代码。

4.3 第二步：技能注册表与调用核心

接下来是注册表构建和调用核心。注意我这里在_dispatch函数里加了一个循环保护，防止模型陷入“拿到错误结果后反复重试同一操作”的死循环。

# registry.py import json SKILL_REGISTRY = {} def register_skill(name, description, parameters, handler): SKILL_REGISTRY[name] = { "description": description, "parameters": parameters, "handler": handler } def get_skill_definitions(): tool_list = [] for name, info in SKILL_REGISTRY.items(): tool_list.append({ "type": "function", "function": { "name": name, "description": info["description"], "parameters": info["parameters"] } }) return tool_list def call_skill(name, arguments: dict): if name not in SKILL_REGISTRY: raise ValueError(f"未注册的技能: {name}") handler = SKILL_REGISTRY[name]["handler"] return handler(**arguments)

调用主逻辑这里是最关键的部分，我用的是模型先返回结构化调用请求，代码解析后执行再反馈给模型。这个循环可以直接理解为：模型出方案，代码去执行，执行结果再喂回给模型做进一步判断。

# agent_core.py import json from registry import get_skill_definitions, call_skill def run_agent(user_message: str, max_turns: int = 5): messages = [{"role": "user", "content": user_message}] for turn in range(max_turns): response = client.chat.completions.create( model="your-model-name", messages=messages, tools=get_skill_definitions(), tool_choice="auto" ) msg = response.choices[0].message if msg.tool_calls: messages.append(msg) for tool_call in msg.tool_calls: result = call_skill( tool_call.function.name, json.loads(tool_call.function.arguments) ) messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": json.dumps(result, ensure_ascii=False) }) else: return msg.content return "执行轮数过多，已自动中止"

这段代码有几点我后来觉得特别值得改进的，但不影响先把它当骨架用：第一是max_turns的循环保护必须有，没有的话模型可能在同一个错误技能上反复重试。第二是 tool 消息里我把结果转成了 JSON 字符串，模型对结构化文本的理解比自由文本好得多，这点很重要。

4.4 第三步：测试与效果观察

用一段最简单的用户指令来跑一下：“读取 data.txt 文件，并告诉我里面出现最多的五个词。”

整个流程会是这样：模型收到指令，从技能列表里挑选read_file_handler对应的技能，参数填data.txt，代码端执行并返回文件内容。然后模型看到文件内容后，又判断需要调用analyze_text_handler，把文件内容作为参数传入，代码端返回词频统计结果。最后模型整合答案，给出自然语言回复。

我建议第一次跑通时，把tools参数里传入的技能定义和每个 turn 的返回内容全部 print 出来看一眼。这一步能帮你直观理解模型是怎么在多个技能之间做决策的，对后面调优极有帮助。

5. 加餐调优：让技能调用准确率再上一个台阶

5.1 prompt 里直接告诉模型“你有这些工具”

我见过不少人的技能调用率上不去，就是因为在系统提示词里压根没有对“技能”这件事做任何说明。虽然模型技术上看到了工具列表，但它不知道应该在什么时机用。

所以我习惯在 system prompt 里专门加一段提示：你是一个可以通过工具执行任务的助手。当用户的要求涉及读取文件、查询数据、访问网络等操作时，请调用对应工具来完成任务，不要假装自己会。如果你不知道应该调用哪个工具，可以直接询问用户以获取更完整的信息。

这段话的调优效果非常显著。它给模型建立了一个行为预期，告诉它遇到哪类问题时必须走工具通道。

5.2 参数描述里的隐藏技巧

参数描述写得好不好，直接影响大模型填参数的准确率。这类小细节，官方文档不会告诉你，但实践中影响很大。

第一个技巧是给枚举值加上明确限定。比如某个参数只接受“晴天”“雨天”“多云”三种取值，你必须在描述里写清楚“只允许传以下值之一”，否则模型自由发挥的概率相当高。第二个技巧是给容易混淆的概念做区分。我见过最坑的例子是有个技能同时有start_date和end_date，描述里都写的是“日期”，模型经常把两个值填反。后来我把描述改成start_date是“开始日期，早于结束日期”和end_date是“结束日期，晚于开始日期”，出错率明显下降。第三个技巧是模糊场景要求补参。如果某个参数没有默认值且难以从上下文推断，就在描述里写明“如果用户未提供此参数且无法推断，请向用户询问确认”。

5.3 结果返回的格式化也很重要

技能函数执行完返回什么，这直接决定模型下一步决策的质量。我现在有一个硬性要求：尽量结构化返回，不要返回自由文本。

比如错误处理，直接抛异常不行，要在结果里带上错误码和错误描述，比如{"status": "error", "code": "FILE_NOT_FOUND", "message": "文件不存在，请检查路径"}。这样模型看到结构化错误信息后，能自己做出合理的后续决策，比如提醒用户检查路径，或者换一个文件重试。

另外，如果返回的数据太大了，记得截断。我曾经有一个查询日志的技能，一次返回了上万行日志，导致模型的上下文窗口直接被打爆。现在我会在技能内部加一个max_results参数强制限制返回条数，超出部分提示模型“结果过多，已截断，可以传更多筛选条件后再查询”。

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

6.1 模型“假装调用”却不传参数

这是我见过最奇葩的一个问题。模型在回复里写了“我将调用 get_user_info 工具来获取用户信息”，但返回的tool_calls是空的，也就是它只是嘴上说说，没有实际发出调用请求。

排查下来的原因是模型对“工具调用”和“文本生成”两种模式的边界理解不够。解决办法有三个方向：一是检查 system prompt 里是否明确写了调用规范；二是检查是不是在回复的开头就被打断了；三是在parse阶段做兜底，检测到模型文本里包含“调用某某工具”字样但没有实际结构化调用时，自动转成一次强制提示。

6.2 技能参数传参类型错误

模型在填参数的时候，偶尔会把数字型参数传成字符串，比如"user_id": "12345"而不是12345。这在大多数语言里不是问题，但在严格类型检查的场景下会直接报错。

我现在的做法是调用技能前做一个轻量的类型校验和数据清洗。如果 schema 里写着 integer，就把字符串类型的数字自动转成 int；如果转不过去就返回参数错误提示，并附上正确的格式要求。这层防御性代码很薄，但能省掉大量低级故障。

6.3 一次调用出错后，模型陷入死循环

这是最折磨人的问题。模型第一次调用技能返回失败，它不甘心，换个参数再试，又失败，再换再试……直到把max_turns全部用完，用户看到的是机器人在那自言自语好几轮。

我的解决办法有两层。第一层是代码层的重试保护，我已经在上面的示例里写过了。第二层是在工具返回的错误信息里加上“建议动作”，比如{"error": "API_KEY过期", "action": "请用户去控制台重新生成API密钥"}。模型看到这种带建议的错误提示，通常会顺着建议走，而不是自己瞎猜。

6.4 常见问题速查表

7. 个人经验总结与下一步扩展

回头再看，agent-skills 这套体系最核心的价值，不是让 Agent “多几个按钮”，而是把模型从一个“什么都懂但什么都做不了”的顾问，变成了一个“边想边干”的执行者。从这个角度说，它其实是所有 Agent 从 Demo 走向生产级的必经之路。

有几个经验我想特别强调。技能描述这件事值得你反复打磨，它的重要性不亚于模型本身的选择，措辞不同，效果差距很大。另外，不要一上来就追求技能数量多，先把十个核心技能调稳定，再逐步扩展。至于下一步的优化方向，我会优先做两件事：一是给技能调用加监控，记录每个技能的调用次数、成功率、平均延迟，用数据驱动的方式调整技能描述；二是给常用技能组合固化出编排模板，让“查数据-做分析-出报告”这种固定链路变成一次调用，进一步降低延迟和 token 消耗。

最后分享一个小技巧：每次更新技能库之后，建议跑一遍回归测试集。我手里有一份几十条标准问答的测试清单，从“压缩文件”“读取表格”“查询天气”到“调用 API”，每次改完描述或参数就全量跑一遍，对比前后准确率，看是升了还是降了。靠感觉判断技能调优效果是不可靠的，量化数字才靠谱。