企业官网建设流程全解析

早在 Agent 这个概念刚火起来的时候，我就在折腾各种框架。那时候大家普遍关注的是模型选型、Prompt 设计、记忆机制这些大方向，但实际跑下来，我发现真正决定一个 Agent 能不能从“演示品”变成“生产力工具”的，往往是技能（Skills）体系的设计。标题里这个 agent-skills，说白了就是一套让 Agent 学会“做事”的工程化方法——从按剧本执行，到真正拥有可复用、可组合、可观测的“手艺”，中间隔着好几层实践经验。

这篇内容不是科普什么是 Agent，也不是讲某个具体的开发框架，而是从我实际项目里摸爬滚打出来的技能体系搭建思路。包括技能如何定义、怎么拆解、怎么写描述才不会被模型误调用、多技能怎么编排协作，还有一堆调试时踩过的坑。适合已经在做 Agent 开发、或者正准备把智能体落地到业务里的读者参考。

1. 技能体系的核心设计思路

1.1 技能不是工具列表，而是一个完整的抽象层

很多人一开始会把技能理解成“给 Agent 接的几个 API 调用”。比如接入搜索、接入计算器、接入数据库查询，然后在系统提示词里写一句“你可以使用以下工具”，就以为技能做完了。我最初也这么干过，但后来发现问题很快就暴露了。

技能的本质应该是一个完整的抽象层。它既不是简单的函数枚举，也不是纯自然语言描述的行为建议，而是处于两者之间的工程产物。一个合格的技能单元，要包含触发条件、输入输出协议、执行逻辑、约束边界、错误处理，以及与其他技能协作的方式。这几乎相当于给 Agent “手写岗位说明书”，而不只是给它递工具。

举一个真实场景。我做过一个团队协作助手类 Agent，一开始把“创建任务”“查询日程”“发送消息”都做成独立的工具函数。结果模型经常在应该查日程的时候去发起会议创建，或者明明用户已经说完需求了，Agent 还在反复确认“您确定要创建这个任务吗”。Review 日志的时候发现，问题就出在技能定义太薄了：只有函数名和参数，缺少上下文触发的判断标准。

后来我重新设计了技能层的结构。每个技能会有一个明确的“适用场景”描述和一个“不适用场景”说明。比如创建任务的技能，它的适用场景是“用户表达出明确的待办事项、任务指派、截止时间诉求”；不适用场景则是“用户只是在询问任务列表、提醒已有安排、讨论优先级”。这听起来像是在写更长的提示词，但区别在于这些信息被我结构化地放进了技能的元信息里，而不是塞进系统 Prompt 里让模型自己领会。

改动之后效果差别很明显。Agent 在决策时的选择准确率高了很多，日志里也很少看到“误调用”了。这里面的核心逻辑是：模型本身并不知道你的业务流程边界在哪里，技能层必须充当“行为护栏”，让 Agent 的动作在一个受控范围内展开。

1.2 技能分类要用“决策维度”来分，而不是用功能维度

我见过很多团队把技能分类做成功能标签：搜索类、计算类、数据类、消息类。这种分类方式对用户讲解挺友好，但对模型决策几乎没有帮助。模型在底层判断该用哪个技能时，更多依赖的是当前对话的意图方向、上下文信息的完整度、以及技能输出结果的可预期性。

所以我自己在做技能拆解时，会从三个决策维度来分成三类。

第一是确定性技能。这类技能输入输出边界清晰，比如数学计算、日期转换、格式整理、文本截断。模型调用这类技能时几乎不需要做任何权衡，只要触发条件满足，就必须调用。这类技能写起来最简单，但在整个体系里的价值更像“基础设施”。

第二类是判断型技能。这类技能需要模型根据上下文做一定的推理和取舍，比如意图识别后的路由分发、检索增强时的查询重写、多源信息冲突时的取舍策略。这类技能不能做成“只要触发就执行”的逻辑，因为它会产生多样的后续连锁影响。

第三类是流程型技能。这类技能往往是多步骤的，或者会调用其他技能完成一个业务目标。比如“安排一场会议”这个技能，内部可能涉及查询参会者空闲时间、创建日程邀请、发起会议室资源分配、给参会者发提醒。它是一个编排层技能，而不是单点能力。

这三类的处理方式是完全不同的。确定性技能只要保证参数校验和结果稳定性；判断型技能要注意给模型留出足够的推理空间，并在输出结构上提供可操作的选项；流程型技能则要做成独立的状态机，不能被模型中途随意打断或跳步。如果把三类混在一起用一套管理模式，Agent 很容易在生产环境里表现出非常“神经质”的行为。

1.3 技能描述怎么写，直接影响调用命中率

这个我特别想说，因为太多人在这上面吃亏了。技能描述，也就是我们常说的 skill description，不同于函数注释。函数注释是给开发人员看的，可以写很多技术细节；技能描述是给模型看的，它的目标是让模型在正确的时机以正确的参数调用正确的技能。

我最早写技能描述的时候，照着 OpenAPI 文档风格写，每个技能都附带详细的参数数据类型、默认值、返回值说明。后来看调用日志发现，模型经常把技能 A 的参数按照技能 B 的逻辑传给技能 A，例如给字符串字段传一个 JSON 对象。排查了很久才发现，是描述里关于参数格式的说明太抽象，模型在低概率采样时产生了错误联想。

现在我写技能描述会遵循三个原则。

第一个原则是“场景优先于功能”。开头第一句话先用自然语言描述这个技能会在什么情境下被用户需要，而不是先写这个技能的输入输出。例如“当用户试图安排多人的线下会议，且给出了会议主题和时间范围时，这是一个需要调用 meeting-scheduler 技能的情境”。这样模型在做动作决策时，匹配的是意图语义，而不是字面函数名。

第二个原则是“给出反例”。我会在每个描述里加一小段“不要调用该技能的场景”。比如分诊路由技能，要明确说明“当用户只是想了解某个部门的上班时间时，不要调用分诊路由，直接回答即可”。反例信息对模型纠正边界很有帮助。

第三个原则是参数示例用真实值。描述里的 JSON Example 不能写占位符，比如 name: string，要写成 name: "张三"。模型对具体值的理解远好于对类型标注的理解。这一点我是在观察多次调用失败后总结出来的。

2. 从零搭建一套技能集的关键步骤

2.1 先做技能盘点，再谈技术实现

如果你的 Agent 已经跑了一些基础流程，或者你准备给 Agent 设计技能体系，第一步不是写代码，而是做技能盘点。拿一张白板，把所有可能用到的能力域列出来，再针对每个能力域去拆解“用户的话术长什么样”“这个能力内部会经过哪些环节”“成功和失败分别以什么状态返回”。

我会按五个维度做盘点：能力名称、触发的用户意图、前置依赖条件、执行步骤清单、输出产物。这五个维度确定清楚了，后面写技能描述和实现逻辑都会顺畅很多。如果这一步偷懒，后面每加一个技能都要返工，非常折腾。

举个例子，如果我要给一个客服型 Agent 做“退款进度查询”技能。触发意图是用户询问退款到哪一步了，前置依赖条件包括用户身份已识别、退款单号已提取。执行步骤则拆成：调用订单系统查询退款单状态、判断退款单所属阶段、拼接最新的进度话术。输出产物是一个包含状态文本和一个可选解释字段的消息结构。这些信息比“入参 orderId，出参 status”要丰富得多，对模型判断有实质帮助。

盘点结束后，你手里就有了一张技能的“全局地图”。接下来才进入具体实现。

2.2 因子化拆技能：不要每个动作都做成独立技能

有些开发者喜欢把一切拆成粒度极细的技能，比如“发送验证码”技能、“校验验证码”技能、“刷新验证码”技能。粒度太细的问题在于模型需要在众多语义相近的技能里做选择，出现误选的概率会成倍上升，调用链也会越来越深。

我在实践中的经验是，技能粒度应该按照“业务可理解的子目标”来定。也就是说，一个技能对应一个用户能感知到的结果。比如“完成验证码校验”可以作为“用户登录”这个业务子目标的一个技能，而不是把“发送验证码”单独拆出来。发送验证码只是过程中的某一步，可以放在技能内部的执行逻辑里处理，没必要暴露给模型做决策。

这样做的好处有两个。一是模型决策面变小了，技能数量精简之后，选择的准确率自然提高。二是技能内部的可扩展空间变大了，以后如果要在发送验证码之前加一个风控检测，直接在这个技能内部加逻辑就行，模型不需要知道这些子步骤的存在。

当然，使用一个复合技能时也要注意，技能内部执行的步骤越多，出问题的可能性就越大。我会为每个复合技能单独写一个状态机，记录它执行到哪一步了，哪一步失败了，失败后是重试还是终止。这样即便出了故障，也能从日志里快速定位。

2.3 技能注册表与动态发现机制

当一个项目的技能数量超过十个，静态的“把所有技能都塞给上下文”的设计就成了明显的性能瓶颈。一方面模型每轮对话都要处理大量与当前场景无关的技能描述，注意力被稀释；另一方面 token 成本也扛不住。

这时候就需要技能注册表和动态发现机制。简单说，就是先有一个记录了所有技能元信息的注册表，然后在每轮对话开始时，基于当前对话状态做一次技能召回，只把相关技能注入到上下文中。

我做动态召回时的做法是先给技能打上领域标签和状态标签。领域标签像是财务、日程、审批；状态标签像是需要用户确认、后台静默执行、结果可展示。然后写一个轻量级的召回器，基于用户当前 message 的向量相似度，加一些规则约束，筛出 top-N 个候选技能。规则约束很关键，比如财务领域的技能召回，如果当前会话没有完成身份核验，那相关技能就会被直接排除掉。

这些机制的实现并不复杂，但它让技能体系具备了规模化的能力。不然技能越多，效果越差，会很打击团队信心。

3. 技能编排协作的实操路线

3.1 从串行调用到状态感知的任务编排

Agent 通常不会只调用一个技能就能完成任务。多数业务流程需要多个技能按某种顺序协作。最简单的编排方式是让模型自行决定技能调用顺序，这就是大家常说的“Agent 自主规划”。这个方法在简单场景下可行，但在复杂业务流程里会经常出问题。模型会在中间步骤缺乏判断依据时就开始“自由发挥”，把不该调用的技能串联起来。

我采用的方案是做一层轻量的状态感知编排器。它不去替模型做所有的决策，只维护一个当前任务的上下文状态表。这张表里记录了当前流程的阶段、已经完成的步骤、各步骤产出的数据依赖。当模型想调用某个技能时，编排器先检查前置条件是否满足。例如未完成身份核验时，任何涉及用户敏感数据的技能都不能被调用。

这套机制在工程上的实现并不难，但收益非常明显。Agent 的自主性依然存在，但它的自由度被约束在业务流程的安全边界内。这就是技能体系从“能用”走到“可控”的关键分水岭。

3.2 技能切换的上下文交接设计

多个技能协作时，最容易被忽略的问题是上下文交接。比如一个技能输出了中间结果，到下一个技能执行时，模型可能记不住前一个技能返回里的细节。这是很多 Agent 项目表现不稳定的主要原因之一。

我的做法是使用结构化的上下文槽位来显式传递关键数据。举个例子，在一个“客户投诉处理”的流程中，第一个技能负责从用户陈述里提取结构化信息，包括订单号、问题类型、客户情绪等级，输出一个结构化槽位。第二个技能在执行解决方案推荐时，并不是从聊天历史里自己找数据，而是从槽位中读取。

这样做的优势在于，即使中间经历了较长对话，槽位数据依然稳定可靠，不会因为对话轮次增加而丢失或模糊。而且后续如果要做多轮修正，只需要更新槽位里的字段即可，模型不用重新从头理解整段历史。实际排障时也非常好用，看一个技能的输入输出就能定位上下文数据到底正不正确。

3.3 并行与回退：进阶编排的必要功课

有些技能的调用没有前后依赖关系，比如在分析用户问题时，需要同时检索内部知识库、查询历史工单、拉取产品文档。如果串行执行，既浪费时间又增加多次调用的延迟。把这些无依赖的技能并行触发，在各结果就绪后再做汇总，是性能优化很直接的手段。

但并行也有坑。如果并行调用的多个技能访问了同一个共享资源，或者其中一个技能的结果会改变其他技能的输入条件，就不能简单并行。我遇到过并行调用后，检索型技能拿到的知识快照和判断型技能所基于的数据版本不一致，导致输出自相矛盾的情况。现在我的做法是在设计技能时明确标注“可并行”和“不可并行”两类属性，并由编排器控制调度策略。

回退机制同样不可忽视。当一个流程型技能执行失败时，究竟是重试当前步骤、跳过它，还是换一个替代路径，需要提前定义。一套好用的回退机制，不是让模型临场判断，而是在编排器里配置好回退策略。比如检索类技能连续失败两次后，自动切换为“仅回答通用建议”的降级模式。这种提前设计好的降级路径，比让模型面对报错时硬着头皮胡编要可靠得多。

4. 常见问题与调试实录

4.1 技能被频繁误调用，怎么定位和修正

这是我在支持其他开发者时最常被问到的问题。技能误调用的典型表现是，用户明明在闲聊，Agent 却调了一堆技能；或者用户咨询 A 类型问题时，Agent 优先调用了 B 类型的技能。

排查这类问题，我一般从三个角度走查。首先看技能描述是否足够有区分度。打开所有技能的 embedding 或者语义相似度看看，如果 A 技能和 B 技能的描述相似度过高，模型当然会在两者之间摇摆不定，那就需要重写描述，把各自的应用场景讲得更鲜明。其次看上下文中有没有让模型混淆的表述。比如系统提示词里把“查询”这个词既用于搜索技能场景，又用于数据库查询技能场景，就容易诱导误判。第三看召回器。如果做的是动态召回，要检查是不是召回候选集里同时混入了多个高度相似的技能，把决策难度放大了。

一个很具体的修正案例是，我曾有一个“日程查询”技能和一个“待办事项查询”技能。它们的描述几乎都是“获取用户的日程或待办事项列表”，只是参数不同。导致模型经常把“查询待办”识别成“查询日程”。修正之后我强调了一个关键差异，日程技能需要绑定具体日期和时间点，待办事项技能则没有时间段概念，只关心完成状态，误调用率就明显降下来了。

4.2 技能内部报错，模型“假装成功”怎么破

技能调用失败后，Agent 可能没有把错误信息透传给用户，而是顺着上下文一本正经地编造一个结果。这个问题在生产环境里非常致命，因为用户会把假结果当成真结果去执行。

解决这个问题的核心是“失败必须显式化”。我在技能的输出协议里规定，凡是执行失败的技能，必须返回一个结构化错误对象，包含错误码、可读错误信息、以及降级建议。同时要提供一个“无法验证”的置信度标记。如果技能没有返回但是模型还在往下走，那我就会在编排器里拦一道：连续多次调用无有效结果的任务必须被标记为失败，并引导用户补全信息或转人工。

这个机制看着简单，但很多项目就是忽略了它在工程上的强制性。技能层的核心任务是消除不确定性，假设模型总能正确处理异常状态。是错误的设计取向。

4.3 回归验证：技能改完别忘旧场景

技能的迭代频率通常很高。改一个参数的描述，调整某个步骤的执行逻辑，或者替换内部的第三方服务，都可能无意中影响已有正常运行的技能链路。我也经历过这样的情况：改了一个底层检索技能的超时时间，结果导致两个高层编排技能的执行节奏全乱了，之前能跑通的流程全部异常。

后来我建立了一个技能回归数据集。每个技能至少配三组典型场景、三组边界场景、三组错误场景。每次改动技能，就把这些数据集跑一遍，看输出是否符合预期。虽然没法做到全靠自动化，但至少能拦住很大比例的回归问题。尤其在技能数量增多之后，这可以说是最省力的避坑方案了。

如果团队人少，哪怕用手工方式做回归记录，也比不做要强得多。我见过太多项目在推进新功能的过程中，悄悄丢掉了旧功能，到了演示给业务方的时候才被发现已经不能用了。

4.4 调试技能时最推荐的信息采集思路

调试 Agent 技能比调试普通后端接口难得多，因为输出的不确定性来自模型本身。我的经验是，在设计阶段就要把可观测性想进去。每个技能调用时，都要记录入参快照、出参快照、执行耗时、调用链上下文、以及模型决策的理由草稿。

有了这些数据后，复现问题时不需要用户再重新描述一遍，直接查看调用链就能还原当时的决策过程。我从自身经验出发，结论是：可观测性越早做，后续调试返工的次数就越少。不要等到几十个技能都上线后再补充日志，到那时候你会发现自己陷入了一团理不清的纠缠中。

我在实际使用中还有一个心得：技能设计这件事，不存在一次性做到完美这个选项。模型在升级，框架在变化，业务流程在调整，技能体系必须跟着迭代。维护一套技能集，本质上是在维护一份活着的操作手册。这既是工程能力的体现，也是 Agent 效果长期稳定下来的根基。