企业官网建设流程全解析

从 “agent-skills” 这个词能聊出不少东西。这不是一个产品名，而是我最近在折腾智能体（Agent）应用时沉淀下来的一套方法论：如何把大模型能调用的那些零散工具，整理成一个可复用、可生长、可演进的“技能库”。

如果你玩过 Agent 框架，多半会有这种体会：第一步写个search、send_email、calc之类的 function，模型调度起来还挺像回事儿。但一旦业务场景变复杂——比如要跨 5 个步骤处理用户订单、要在不同工具之间做条件分支、要让模型在几十个候选工具里准确挑出该用的那一个——零散 function 的写法就崩了：上下文塞太满、工具描述互相干扰、模型经常选错、想加一个新能力又怕影响老的链路……

“技能”就是对这一堆问题的系统性回答。它不是简单的工具列表，而是一个带有元信息、可编排、可裁剪、可观测的智能体能力单元。这篇文章我会从设计思路、核心格式、编排机制、上下文控制、实操落地到问题排查，完整拆一遍，希望能给正在做 Agent 应用的朋友提供一套可以直接抄作业的参考。

1. 方案选型：为什么是“技能库”而不是“工具列表”

1.1 从 Function Calling 到 Skill 的演进逻辑

大模型的 Function Calling 刚普及那阵，大家习惯的做法是在 system prompt 里塞一大坨 JSON Schema，告诉模型“你有这些函数可以用”。这种方式小规模没问题，可一旦函数数量超过 15 个、参数层级超过两层，问题就来了。

模型在推理时要把所有函数定义都“读”一遍才能决定调哪个，函数多了就会互相抢占注意力，导致选错或者漏选。我遇到过最离谱的一次是模型把get_user_balance当成get_user_info来调用，就因为两个函数描述里都出现了“用户”这个词，而 balance 的定义排在后面，被前面的描述干扰了。

技能库的核心改变在于：把“工具”升级为“技能”这个更高层的抽象。每个技能不仅包含可执行代码，还包含它适用什么场景、需要哪些条件、输出如何被后续使用。模型选的是“技能”，而不是“函数”。这就好比给工具箱贴了标签——你不用在满地的扳手里翻一个内六角，直接去“内六角”那格拿就行。

技能库还解决了另一个实际问题：共享与复用。通常一个 Agent 项目里会有多个不同的 Agent（客服 Agent、数据分析 Agent、售后 Agent），它们之间有很大一部分能力是重叠的。如果每个 Agent 都维护一份自己的工具列表，改一个接口就要同步改三四处，迟早出事故。拆成技能库之后，Agent 只需要声明自己“用到哪些技能”，所有实现细节都从库里拉取，真正做到了单一数据源。

1.2 三种主流实现路径的对比

在确定技能库方案之前，我评估过三种实现路径，这里直接给结论。

第一种是纯 Prompt 注入 + 单个大函数。把所有技能塞进一个大的处理函数里，用 if-else 或 switch 分发。优点是简单、快速跑通，缺点是函数内部逻辑越来越臃肿，而且模型根本没有“选择”的空间——它只知道有一个函数可用，具体调哪个子能力全靠函数内部规则。这种做法本质上还是传统的规则系统，并没有发挥大模型的调度能力。

第二种是注册表模式：一个全局技能注册表，技能用装饰器或注册函数加入，Agent 启动时拉取注册表里的所有技能定义并塞给模型。这是我最终选择的方案。它保留了 Function Calling 的灵活性，同时通过技能描述、参数校验、场景过滤让模型在“更小但更精准”的集合里做决策。

第三种是子 Agent 模式，每个技能本身是一个小 Agent。这个方案能力最强，但消耗的 token 成倍增加，且嵌套调用的稳定性很难控制——上层 Agent 等下层 Agent 的返回，超时、死锁问题层出不穷。目前只建议在确实需要多轮交互式技能（比如用户画像分析这种需要追问的）时才考虑。

对比结果见下表：

我的结论是：注册表模式是当前阶段性价比最均衡的方案，后面的实现细节全部基于这个模式展开。

2. 技能格式：让大模型“读懂”每个技能的关键设计

2.1 技能描述决定了模型能不能选对

在技能库方案里，模型实际上“看”的是技能的元信息，而不是技能的实现代码。因此技能格式的核心是设计一套能让模型高效理解、准确选择的元数据结构。

我一直用的最小可行结构是五个核心字段，先看一个示例再逐条解释。

{ "name": "order_status_query", "description": "查询订单当前状态。适用于用户询问订单到哪了、是否发货、物流单号等场景。当用户问‘我的货怎么还没到’时优先使用此技能。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号，通常以字母O开头后跟10位数字" } }, "required": ["order_id"] }, "execute": "async (ctx) => { const order = await ctx.db.findOrder(ctx.params.order_id); return { status: order.status, tracking_no: order.express_no }; }", "meta": { "version": "1.2.0", "author": "team_order", "tags": ["order", "logistics"], "timeout_ms": 3000 } }

这里有两个细节容易踩坑。

第一个是description一定要写“触发条件”，不要只写“这是什么”。我见过有人写“查询订单状态”，模型在用户说“帮我看看买了啥”的时候也会去调它——因为描述范围太宽。我建议的写法是：先说功能，再说适用场景，最后给一两个示例问法。这样模型在语义匹配时的置信度会显著提升。实测下来，加了触发条件和示例之后，技能选择准确率能从 78% 涨到 93% 左右。

第二个是parameters里每个字段的description也要写清楚格式、常见取值、必填与否。不要小看这个，模型根据用户口语生成参数时，如果不知道order_id是“O 开头加 10 位数字”，它可能会生成一个纯数字字符串。我在一个项目里就因为没写格式说明，模型把用户说的“订单号 2024A12345”原样传给了接口，接口校验失败后整个链路崩溃。写了格式说明之后，模型会主动从上下文里提取匹配格式的内容，错误率下降了不止一半。

2.2 技能注册与加载：动态导入比静态清单好在哪里

技能定义是结构化的，但技能的“实现”（也就是上面示例里的execute）必须是可执行代码。为了兼顾灵活性和可维护性，我选择用动态导入的方式加载技能。

具体做法是：技能目录下每个子目录是一个技能包，包含skill.json（元信息）和index.js（实现）。Agent 启动时扫描目录，动态加载所有技能包，并把 skill.json 里的元信息收集起来，构建成模型可见的 tools 列表。

这个设计有什么好处？好处之一是热更新。生产环境不需要重启 Agent 进程，只要把新的技能目录丢进去，注册表会自动感知并加载。好处之二是隔离。每个技能包独立依赖、独立版本，不会出现一个技能引用了另一个技能的内部函数导致耦合的问题。

这里给出在我的实现里比较核心的技能加载器骨架（只保留关键逻辑）：

const fs = require('fs'); const path = require('path'); class SkillRegistry { constructor(skillDir) { this.skillDir = skillDir; this.skills = new Map(); this.watchers = []; } async loadAll() { const entries = fs.readdirSync(this.skillDir, { withFileTypes: true }); for (const entry of entries) { if (!entry.isDirectory()) continue; const skillPath = path.join(this.skillDir, entry.name); const meta = JSON.parse(fs.readFileSync(path.join(skillPath, 'skill.json'), 'utf-8')); const impl = require(path.join(skillPath, 'index.js')); this.skills.set(meta.name, { meta, impl }); } } getAllToolDefs() { return Array.from(this.skills.values()).map(({ meta }) => ({ type: 'function', function: { name: meta.name, description: meta.description, parameters: meta.parameters, } })); } async execute(name, params, ctx) { const skill = this.skills.get(name); if (!skill) throw new Error(`Skill not found: ${name}`); // 这里可以插入统一的鉴权、限流、日志逻辑 return await skill.impl.execute(ctx, params); } }

一个容易忽略的点是技能名（name）的规范。模型靠 name 来调用技能，所以 name 必须满足大模型 API 对函数名的约束（通常要求^[a-zA-Z0-9_-]+$），而且要有一定的语义可读性。我见过有人用skill_001这种命名，模型偶尔会把两个相邻的技能搞混。用order_status_query、user_profile_analysis这种“领域_实体_动作”的命名方式，模型调用的准确性会高不少。

2.3 版本管理：技能不是写完就完事的

技能是会演进的。你要修 bug、要加参数、要调整返回结构。如果只有一个 “latest” 版本，一旦新版有问题想回退，就非常被动。

我的做法是在skill.json里加入meta.version，并保留历史版本的技能包文件（目录名带版本号，比如order_status_query@1.2.0）。Agent 启动时默认加载 latest，但如果配置指定了某个版本，就加载指定版本。这相当于给每个技能加了一个旁路开关，出问题时可以快速定位到“是这个技能的问题还是 Agent 编排的问题”，而不是把所有代码都翻一遍。

版本管理的另一个作用是缓存兼容。技能返回的数据结构如果有变化，下游的 Agent 决策逻辑可能完全懵掉。所以我的团队定了一条规矩：技能返回的数据结构只增不改，真要删字段，必须先加 v2 版本的技能，老版本保留一段过渡时间。这条规矩看起来保守，但它避免了大量“技能升级后 Agent 行为突变”的诡异问题。

注意：技能包不要跟代码仓库的其他模块共用一套依赖树。技能应该声明自己的依赖并独立安装，否则升级一个公共依赖库可能同时影响几十个技能的行为，排查的时候会非常痛苦。

3. 编排与上下文控制：技能库能不能真正落地的胜负手

3.1 技能链：把一个复杂请求拆成多个技能协作

单一技能往往只能完成一步操作。真实业务里，一个请求常常要串起多个技能。比如用户问“我那个 998 的订单什么时候能到？”，理想的执行路径是：先用order_search根据金额和模糊描述找到订单号，再用order_status_query查物流状态，最后也许还要调logistics_tracking拿详细的物流轨迹。

技能链就是用来描述这种多步协作关系的。我在技能库里内置了几种编排方式，最简单的就是顺序链。

const chain = [ { skill: 'order_search', output_var: 'order_id' }, { skill: 'order_status_query', input_from: 'order_id' }, { skill: 'logistics_tracking', input_from: 'order_id', optional: true } ];

链的语义是：下一步的执行可以使用上一步的输出作为参数。这个设计很简单，但它把“模型一次想清楚所有步骤”的负担，转移给了我们自己在代码里定义好的执行路径。换句话说，在“用户请求复杂但流程相对固定”的场景下，我们先用规则圈定步骤，再利用模型在每一步做参数提取和修正，而不是让模型一步不差地生成整条链路。实测下来，这种方法比完全让模型自由发挥的稳定性高出不少。

条件分支也很有用。比如“如果订单状态是已签收，就调评价引导技能；如果是运输中，就调客服人工介入”。这种分支不需要模型做决策，我们在编排配置里写清楚条件即可。

3.2 上下文裁剪：别让技能定义吃掉你的全部 context

我前面提到技能多了之后模型会看不过来。有人会说，那把技能全部塞进 system prompt 里交给大模型处理不就行了吗？问题是：你 50 个技能的定义加起来可能有 10000 个 token，用户消息和对话历史再占一些 token，一个很小的任务可能就要用掉 8000 token 的上下文——不是在跑推理，是在给模型递小抄。

上下文裁剪是我在这个项目里花时间最多的地方，目前用了三个策略，组合起来效果不错。

第一个策略是“技能粗筛 + 精排”。Agent 收到用户请求后，先用一个轻量级模型（或者基于关键词/BERT 向量的检索器）从技能库里找出最相关的 5 个技能，只有这 5 个技能的定义会进入大模型的上下文。粗筛环节判断标准可以放宽一些，“宁可多召也不要漏”，精排时再通过语义相似度把最相关的排到最前面。这其实就是搜索里经典的 recall 和 precision 权衡，在 Agent 场景下同样适用。

第二个策略是“技能描述压缩”。把 description 里的“示例问法、适用场景、预期输出”这些字段梗概成一句话。切换前记得在离线评测集上对比一下压缩前后的技能选择准确率，压缩太多会影响模型判断，得不偿失。

第三个策略是“技能参数精简”。有些技能定义的 parameters 里包含一堆 optional 字段，这些字段写进去既占 token 又容易让模型困惑。我给技能元信息加了一层“运行时参数视图”——只暴露当前链路需要的最小参数集合。比如order_status_query完整定义有 7 个可选字段，但在“订单物流查询”这条技能链里，它只需要order_id一个参数。模型看到的定义跟实际操作的是同一个技能，但上下文中呈现的参数列表完全不同，轻量了很多。

这两种操作思路的本质没有冲突：技术优化照做，加缓存降低重复推理单价；模型无关的技能调度逻辑优先放本地，减少对远端模型的依赖。这样在量化受限的团队里，也能支撑起中高频的 Agent 业务。

3.3 工具绑定与模式控制：什么时候允许模型自己选，什么时候不许

技能库里不是所有技能都适合让模型自主决定是否调用。支付相关的、删除数据类的、发外部通知类的，这些操作最好加一道人工确认；而查天气、算金额、翻译这种低风险技能，模型可以自主调用。

我给技能元信息里加了permission_mode字段，三种取值：auto（模型自主调用）、manual（模型可以提调用意图，但需要用户确认）、disabled（模型不可见，只能由内部编排链触发）。这样做不仅是为了安全，也是为了减少误调用。用户问“能不能退款”，模型如果看到有refund_create技能且有权限，可能直接就尝试退款了——这也是为什么高影响的技能最好都设为 manual，等用户确认再说。

内部编排触发时要格外注意一个问题：编排链上需要调disabled技能，但模型看不到它，怎么办？我的方案是把这类技能的调用封装在一个“内部工具”里，这个内部工具对模型可见、但 description 写得比较含糊（比如“执行退款相关操作”），真正的退款逻辑在内部工具实现里再分发到具体技能。这样模型知道“能退款”，但它不知道也不需要知道具体的退款技能长什么样，更不会直接跨过编排去调它。

注意：上下文裁剪不能只发生在模型输入之前，也要关注模型输出的 token 预算。如果技能返回的数据很大（比如一页 100 条物流轨迹），模型可能为了节省输出就丢弃关键信息。更合理的做法是技能返回结构化摘要，并做好截断，把决策所需的信号压缩到足够小的体积。

4. 实操过程：从 0 到 1 搭建一个本地技能库 Demo

4.1 项目结构与依赖准备

理论说了不少，直接上一份可以跑的 Demo。我本地的项目结构大致如下：

agent-skills/ ├── skills/ │ ├── order_search/ │ │ ├── skill.json │ │ └── index.js │ ├── order_status_query/ │ │ ├── skill.json │ │ └── index.js │ └── logistics_tracking/ │ ├── skill.json │ └── index.js ├── registry.js ├── orchestrator.js ├── index.js └── package.json

依赖方面我用的是 Node.js 18+，一个轻量的本地 HTTP 服务框架，外加一个 OpenAI 兼容的模型接口（可以是本地模型服务也可以是云端 API）。技能实现里如果涉及数据库，我用的是一个简单的内存对象模拟，方便演示。如果你想跑得更快，直接用node index.js就能起服务。

这个 Demo 场景是“查订单物流”，包含 3 个技能。我把技能定义拆成两个文件，就是为了让元信息和实现天然分离——这是技能库方案跟“把所有逻辑堆在一个文件里”最大的区别。

4.2 三步实现核心链路

第一步，写技能定义。以order_search为例：

{ "name": "order_search", "description": "根据用户描述查找订单号。适用于用户不确定订单号、只记得商品名/金额/下单日期等场景。示例问题：‘我那个998的订单’、‘上周买的那本书’。", "parameters": { "type": "object", "properties": { "keyword": { "type": "string", "description": "用户提供的订单描述关键词" }, "amount": { "type": "number", "description": "用户提到的订单金额，没有则为空" } }, "required": ["keyword"] }, "meta": { "version": "1.0.0", "tags": ["order"], "permission_mode": "auto" } }

配套实现文件index.js：

const mockOrders = [ { id: 'O20240501001', item: '技术书', amount: 998, status: 'shipped' }, { id: 'O20240501002', item: '蓝牙耳机', amount: 299, status: 'delivered' } ]; exports.execute = async (ctx, params) => { const { keyword, amount } = params; const match = mockOrders.filter(o => { const kwOk = !keyword || o.item.includes(keyword); const amtOk = !amount || o.amount === amount; return kwOk && amtOk; }); if (match.length === 0) return { found: false }; return { found: true, orders: match.map(o => ({ id: o.id, status: o.status })) }; };

第二步，写技能注册和编排。注册表我参考了 2.2 节的骨架代码，这里直接给出orchestrator.js里支持技能链的片段：

class Orchestrator { constructor(registry) { this.registry = registry; } async runChain(chain, ctx) { const local = {}; for (const step of chain) { const args = {}; for (const [paramKey, sourceKey] of Object.entries(step.input_from || {})) { args[paramKey] = local[sourceKey]; } if (step.optional && !args[Object.keys(step.input_from || {})[0]]) { continue; } const result = await this.registry.execute(step.skill, args, ctx); if (step.output_var) { local[step.output_var] = result; } } return { final: local, full_history: chainSteps.map(s => s.result) }; } }

第三步，起服务并做端到端测试。主题入口index.js里做的事不外乎：加载注册表 → 构建编排器 → 根据用户输入先做技能粗筛，再决定是直接调模型走自由调度，还是按配置的技能链跑一遍。为了快速验证，我会在启动时同时打印出当前已加载的所有技能名，以及它们的permission_mode。

node index.js # 输出：Loaded skills: order_search, order_status_query, logistics_tracking

然后模拟一个用户请求：“我那个998的订单发货了没？”，期望的链路是：order_search找到订单号 →order_status_query查状态 → 返回结果。真正调模型之前，先手动验证技能链路跑通与否非常关键。我是用了一段临时的 mock 脚本绕过大模型，直接给链条喂参数，看每个技能是否拿到了正确输入。这段脚本虽然简单，但帮我节省了大量排查模型请求的时间。

4.3 关键决策记录：我为什么这样设计

有几个设计点是走查了几次才定下来的，记录一下当时的思考过程。

第一，技能注册表为什么用目录扫描而不是显式 import？因为目录扫描更适合“一个技能一个维护者”的团队协作模式。每个人在自己的目录里改代码，互不干扰，CI 构建时自动检查 skill.json 合法性，比在一个大文件里找 import 语句要清晰得多。

第二，编排链里的optional字段为什么要显式标注？因为在真实请求里，不是每个技能都能成功拿到前置参数。比如order_search没搜到订单，后续的查询和物流就都跳过了。如果不标注 optional，链在执行到第二步时会因为参数缺失直接报错。显式标注之后，链条对“没有找到结果”的场景就有了容错机制。

第三，为什么技能实现里不直接写死返回数据的展示模板？因为技能库是给 Agent 用的，不是给用户页面用的。技能只负责返回结构化数据，怎么把数据组织成自然语言，是模型的工作。如果技能把这一层也做了，等于把模板塞进了技能逻辑，复用价值大打折扣。

5. 避坑指南与排查技巧：那些文档里不会写的事

5.1 高频问题速查表

这六个问题是我在实际项目里真实遇到过的，不是从报告里抄来的，每一条都对应着一次白天黑夜连轴的排查。

5.2 排查技能选择问题的有效手段

排查模型“选错技能”这类问题，最笨但最有效的手段是加日志。我在注册表的execute入口加了一行结构化日志，记录：用户原始请求、模型传入的参数、选中的技能名、执行结果、耗时时长。这样在复盘时可以清晰看到模型到底是怎么决策的。

有一次我查一个很诡异的问题：同一个用户请求，上午模型调order_status_query是对的，下午突然改调了order_status_query_v2（新加的技能）。日志显示 v2 的技能描述里多了一句“优先使用”，模型就真的优先了——哪怕它实际并不更合适。这提醒我一个细节：技能描述里千万不要写“优先使用”“建议使用”这类带强烈倾向的词，除非你是真的想让模型优先选它。模型对措辞的敏感程度远超想象。

另外，当怀疑是技能定义太多导致模型犯错时，可以把“候选技能列表”直接打印出来，人工模拟模型视角看一遍。如果人眼都觉得 20 个技能里好几个长得很像，那模型大概率也会搞混。这时候要做的不是优化描述，而是把技能合并或增加更明确的边界条件。

举一个真实的调试例子。某个查询天气的技能和查询空气质量的技能都包含“PM2.5”这个词，模型经常搞混。我把两个技能的 description 做了区分：天气查询开头写“气象信息，包括温度、湿度、风速、天气现象”，空气质量查询开头写“空气污染指标，包括 PM2.5、PM10、AQI 指数”。加了领域前缀后，错误率基本归零。这说明一个问题：描述里的“首词”权重比后面内容高得多，重要的区分词要放在开头。

5.3 两个容易被忽视的工程细节

第一个是技能实现的超时和重试。大模型调技能时，如果技能执行超过 3 秒，模型那边可能已经不耐烦甚至断开了，所以技能实现里最好统一套一层超时控制。我目前的默认策略是：一般技能 3 秒超时，重试 1 次；涉及外部 API 的技能 8 秒超时，不重试（避免重复扣费或产生副作用）。这个超时阈值不是拍脑袋定的，是压测了 500 次请求之后求出的 P95 值。

第二个是技能返回内容的“幂等性”。也就是说同一个技能、同样的参数，连续调用两次，结果最好完全一致（或者至少业务上一致）。模型为了补全缺失信息，可能会在同一轮对话里多次调用同一个技能。如果技能实现里写的是“调用外部接口并写入数据库”，第二次调用的结果和第一次就会不一样，这会扰乱模型的规划。对于这类技能，要么在编排层缓存同一轮对话内的执行结果，要么在返回结构里明确标注“操作已完成”，尽量让副作用最小化。

插一句编排层的细微设计：同一轮对话中，如果同一个技能被多次请求且参数相同，默认返回缓存结果而不重新执行。这个逻辑让我少花了很多冤枉钱，也少踩了很多重复扣费或重复发消息的事故。

5.4 构建可观测性的三个核心指标

技能库上线后，一定要盯三个指标，否则属于“裸奔”。

第一个是技能选择准确率。这个指标需要人工抽检或者用离线评测集来算——把用户请求和期望技能配对，跑一遍模型调度，看选对的占比。低于 85% 就说明技能描述存在严重歧义，需要回到 2.1 节的方案里优化描述。

第二个是技能执行成功率。包括超时率、报错率、参数缺失率。如果某个技能连续报错，多半是实现里有 bug，也可能是参数从模型那边就是错的——两者排查路径完全不同，日志里要把参数原样打出来再判断。

第三个是技能调用链路的命中分布。也就是最常被模型调用的 top10 技能是哪些、哪些技能从来没被调过。从来没被调用的技能基本等于白写，要么是场景不存在，要么是描述跟模型认知对不上，需要重点检查。我会定期拉这个分布，用来决定下一个迭代周期优化哪个技能。

这三个指标真正落地之后，技能库就不再是一个“看得见摸不着”的设计了，它是可以被度量和优化的系统。这种数据驱动的改进方式，可能比任何大模型调参技巧都更实用。

结语

我最早接触 agent-skills 这个概念时，以为它只是给工具列表换了个名。真正动手实现并跑过几个真实项目之后才意识到，技能库真正改变的是 Agent 的开发方式——从“给模型一堆函数”变成“给模型一套有组织的、可裁剪的、可复用的能力体系”。这个转变带来的稳定性提升和上下文节省是肉眼可见的。

如果你正在做 Agent 相关项目，我的建议很简单：不要急着冲上来就写一堆 function。先把你的能力域拆成技能，设计好定义格式、注册机制、编排链路和观测指标，再让模型跑在这样一套结构化基础上。“先结构，后智能”，看起来走了一段弯路，实际是走得最快的那条路。