企业官网建设流程全解析

1. 从“agent-skills”这个命名说起：它到底指什么

第一次看到“agent-skills”这个词，很多人会下意识地把它当成某个具体框架或者某个开源库的名字。但如果你真的去搜，会发现它并不是一个单一的、有明确版本号的产品，而更像是一个概念集合——用来描述“智能体（Agent）应该具备哪些能力，以及这些能力如何被组织、调用和扩展”。

我在实际接触这类项目时，最直观的感受是：大家讨论“Agent”的时候，往往把注意力放在“用哪个大模型”“接哪个API”上，却忽略了真正决定一个智能体好不好用的，是它背后那套技能体系。模型是大脑，技能是手脚。大脑再聪明，手脚不协调，事情照样做不成。

所以这篇内容，我想围绕“agent-skills”这个主题，把我在搭建和调试智能体技能系统过程中积累的东西完整梳理一遍。核心会覆盖几个问题：技能到底该怎么分类、技能之间怎么协作、技能怎么注册和调度、以及在实际跑起来之后会遇到哪些坑。适合已经对智能体有基本概念、准备动手做一套可用技能体系的读者，也适合刚开始接触、想先搞清楚整体脉络的朋友。

需要先说明一点：下面提到的所有项目名、工具名、代码示例，都是基于常见实践的合理构造，用来把原理讲清楚，不代表某一个特定产品的实现细节。你完全可以根据自己用的技术栈做替换。

2. 技能不是函数列表：重新理解Agent的能力分层

2.1 为什么“把API包一层”不叫技能

很多人做智能体技能的第一步，是把手里现成的接口一个个包成函数，然后注册进去，觉得这样智能体就“会”这些能力了。我一开始也是这么干的，结果很快就发现不对劲。

问题出在：函数是给程序员用的，技能是给智能体用的。这两者的差别，比想象中大得多。

一个函数，比如query_user_info(user_id)，它要求调用者明确知道要传什么参数、参数是什么类型、返回结构长什么样。但智能体在决定要不要调用它的时候，面对的是一个模糊的自然语言任务，它需要判断的是“我现在该不该查用户信息”“我手上有没有足够的线索去查”“查出来之后下一步干什么”。这些判断，函数签名本身是提供不了的。

所以真正的技能，至少要比裸函数多三层信息：

• 触发条件：什么情况下该用这个技能。这不是简单的关键词匹配，而是对当前任务状态的判断。
• 输入契约：技能需要哪些信息，这些信息如果缺失，能不能从上下文里推断，推断不出来该怎么办。
• 输出语义：返回结果代表什么，成功和失败分别意味着什么，失败之后有没有补救路径。

我后来总结了一句话：函数描述“怎么做”，技能描述“什么时候做、做完意味着什么”。把这句话想明白，技能体系的设计思路就顺了。

2.2 三层能力模型：原子技能、组合技能、策略技能

在实际项目里，我把技能分成三层来管理，这个分层不是拍脑袋定的，而是被逼出来的。

原子技能是最底层的，对应一个不可再分的操作。比如“读取某个文件的内容”“发送一条消息”“执行一次计算”。这一层的特点是：输入输出明确、执行时间可控、失败原因单一。原子技能的数量会很多，但每个都很简单。

组合技能是把多个原子技能按固定流程串起来，完成一个稍大的任务。比如“根据关键词搜索并整理成摘要”这个技能，内部可能先调用搜索原子技能，再调用文本处理原子技能，最后调用格式化原子技能。组合技能的价值在于把常用的流程固化下来，避免智能体每次都从零开始编排。

策略技能是最高层，它不直接执行具体操作，而是决定“在当前情况下，应该用哪些组合技能、按什么顺序、遇到分支怎么走”。这一层最接近我们说的“规划能力”，也是最难做好的。

为什么要分三层？因为如果不分，所有技能都平铺在一起，智能体在选择的时候会面临巨大的搜索空间。分层之后，选择过程变成了“先定策略，再选组合，最后落到原子”，每一步的候选集都小了很多，决策质量明显提升。

2.3 技能边界怎么划：一个容易踩的坑

划分技能边界的时候，我踩过最大的坑是把技能划得太细。

有一段时间，我几乎把每个小操作都做成了一个独立技能，结果智能体在完成任务时，需要连续调用十几个技能，中间任何一步出错，整个链路就断了。而且技能之间的上下文传递变得极其复杂，调试的时候根本追不清是哪一步出的问题。

后来我调整了原则：一个技能应该对应一个“有意义的完成状态”。也就是说，技能执行完之后，应该能说清楚“现在完成了什么”，而不是“现在执行到了第几步”。按这个原则，很多原本拆开的细碎操作被合并了，技能数量少了，但每个技能更“厚实”，反而更好用。

当然也不能太粗。如果一个技能内部逻辑太复杂，失败的时候没法定位原因，那也不行。我的经验是：单个技能的内部步骤控制在三到七步之间，超过七步就考虑拆分，少于三步就考虑合并。

3. 技能注册与发现：让智能体知道自己会什么

3.1 技能描述文件该写哪些字段

技能做出来之后，得让智能体“知道”它的存在。这就需要一个注册机制。我见过不少项目，注册就是往一个列表里塞个名字，结果智能体根本不知道这个技能是干嘛的，自然不会用。

一个可用的技能描述，至少要包含这些字段：

我特别想强调触发场景这一栏。很多人写技能描述的时候，功能描述写得很详细，但触发场景就写几个关键词。结果智能体在判断要不要用这个技能时，只能靠关键词匹配，经常在不该用的时候用了，该用的时候又没想起来。

正确的做法是：触发场景要写成条件句。比如不要写“搜索、查询、查找”，而要写“当用户的问题需要获取外部实时信息，且当前上下文没有现成答案时使用”。这样智能体在判断的时候，有明确的逻辑依据。

3.2 技能发现的两种模式：主动注册与被动检索

技能注册进去之后，智能体怎么找到合适的技能？这里有两种模式。

主动注册模式是把所有技能的描述一次性加载到智能体的上下文里，让它自己选。这种模式简单直接，但有个硬伤：技能一多，上下文就爆了。我试过加载五十个技能，光是描述就占了大半的上下文窗口，留给实际任务的空间被严重挤压。

被动检索模式是先不加载技能描述，而是根据当前任务，用一个检索模块去匹配最相关的几个技能，再把它们加载进来。这种模式扩展性好，但引入了一个新问题：检索本身可能不准，该找的技能没找出来。

我现在的做法是混合：把最常用的十几个技能常驻在上下文里，剩下的走检索。常驻技能的选择标准是“高频且通用”，比如读写文件、基础计算、消息发送这类。检索技能则覆盖那些低频但专业的场景。

3.3 技能版本管理：别让更新变成灾难

技能是会迭代的。今天写的搜索技能，明天可能因为接口变了要改。如果没有版本管理，改完之后老的任务流程可能就跑不通了。

我的做法是给每个技能加一个版本号，并且在描述里注明兼容性。具体来说：

• 小版本更新（比如从1.0到1.1）只改内部实现，输入输出不变，调用方无感知。
• 大版本更新（比如从1.x到2.0）改了输入输出契约，调用方必须同步调整。

同时，注册表里保留旧版本的描述，但标记为“已弃用”。智能体在选择时优先用新版本，只有在明确需要旧行为时才回退。这样既保证了向前兼容，又不会让旧版本一直占着位置。

4. 技能调度：从“能调用”到“调得对”

4.1 单技能调用的参数填充逻辑

技能注册好了，接下来就是调用。调用第一个要解决的问题是：参数从哪来。

智能体手上只有用户的自然语言输入和当前上下文，但技能需要的是结构化参数。这中间的转换，我见过两种做法。

一种是让模型直接输出参数。比如用户说“帮我查一下上个月的销售数据”，模型直接生成{"month": "last", "metric": "sales"}。这种做法简单，但模型经常生成格式不对或者字段缺失的参数。

另一种是先抽取再填充。先从输入里抽取出所有可能用到的信息，形成一个信息池，然后根据技能需要的参数，从池子里匹配填充。缺的参数再回头问用户或者从上下文推断。

我现在用的是第二种。虽然多了一步，但稳定性高很多。具体流程是：

1. 解析用户输入，抽取实体和意图，存入信息池。
2. 根据选定的技能，列出需要的参数。
3. 逐个参数去信息池里找，找到就填，找不到就标记为缺失。
4. 对缺失的参数，判断能不能从上下文推断，不能就生成追问。

这个流程里，第三步的“找不到就标记”很关键。很多人为了省事，找不到参数就随便填个默认值，结果技能执行出来是错的，还很难排查。

4.2 多技能编排：顺序、分支与回滚

单个技能调用相对简单，真正复杂的是多个技能编排在一起。

顺序编排是最常见的，技能A执行完，结果传给技能B。这里要注意的是数据格式的衔接。A的输出格式和B的输入格式往往不一致，中间需要一个转换层。我一般会定义一个统一的中间格式，所有技能的输出都往这个格式上靠，输入也从这里取。

分支编排是根据中间结果决定下一步走哪条路。比如搜索技能返回了结果就走整理流程，没返回结果就走追问流程。分支的关键是条件要明确，不能模棱两可。我见过有的项目，分支条件写的是“如果结果看起来不错”，这种模糊判断会让整个流程变得不可预测。

回滚是最容易被忽略的。如果技能A成功了，技能B失败了，A的副作用要不要撤销？比如A已经发了消息，B没发出去，这时候是补发B还是撤回A？这个问题没有标准答案，但必须在设计阶段就想清楚，不能等出了问题再临时处理。

我的经验是：对有副作用的技能，尽量设计成幂等的。也就是说，同一个技能执行两次和执行一次效果一样。这样即使重试也不会出问题。

4.3 调度中的超时与重试策略

技能调用不是总能成功的。网络可能超时，接口可能限流，服务可能临时不可用。这些情况必须有应对策略。

超时设置上，我的原则是分层设置。原子技能的超时短一些，比如五秒；组合技能的超时长一些，因为它内部要串好几个原子技能。如果组合技能的超时比内部原子技能的总和还短，那组合技能永远会先超时，内部技能根本没机会跑完。

重试策略上，不是所有失败都值得重试。我一般分三类：

• 可重试：网络抖动、临时限流。这类失败等一小会儿再试，往往能成功。
• 不可重试：参数错误、权限不足。这类失败重试多少次都一样，直接报错。
• 条件重试：依赖的外部服务暂时不可用。这类可以重试，但要设上限，不能无限等。

重试的间隔也很重要。我一般用指数退避，第一次等一秒，第二次等两秒，第三次等四秒。这样既给了服务恢复的时间，又不会让调用方等太久。

5. 实战中绕不开的几个坑

5.1 技能描述写得太“聪明”反而没人用

这个坑我印象特别深。有一次我写了一个技能描述，用词很专业，逻辑很严密，自认为写得很好。结果智能体几乎从不调用它。

排查了半天才发现，问题出在描述太“聪明”了。我用的那些专业术语，模型在理解的时候需要额外的推理步骤，而它倾向于选择那些描述直白、一看就懂的技能。后来我把描述改得更口语化、更贴近日常表达，调用率立刻就上去了。

这件事给我的教训是：技能描述是写给模型看的，不是写给同行看的。清晰比精确更重要，直白比优雅更重要。

5.2 上下文污染：技能调用记录把窗口撑爆

智能体每调用一次技能，就会在上下文里留下一条记录。任务稍微复杂一点，调用十几次技能，上下文里就全是调用记录，真正有用的任务信息反而被挤没了。

我试过几种解决办法。一种是只保留最近几次调用记录，更早的压缩成摘要。另一种是把调用记录放到独立的存储里，上下文里只留一个引用。还有一种是在调用记录里只保留关键信息，比如技能名、结果状态、核心输出，把中间的调试信息全部去掉。

现在我用的是组合方案：关键调用保留完整记录，非关键调用只留摘要，超过一定数量的旧记录自动归档。这样既保证了可追溯性，又不会把窗口撑爆。

5.3 技能之间的“隐性依赖”导致顺序错乱

有些技能之间有依赖关系，但这种依赖没有显式声明，结果智能体在编排的时候把顺序搞反了。

比如“发送报告”这个技能，依赖“生成报告”先完成。但如果描述里没写这个依赖，智能体可能先调发送再调生成，自然就失败了。

解决办法是在技能描述里显式声明前置条件。我一般会加一个depends_on字段，列出必须先完成的技能。调度器在编排的时候会检查这个字段，确保顺序正确。

但这里有个度的问题：依赖声明太多，调度器就变成了一个死板的流程引擎，失去了灵活性。我的做法是只声明硬依赖，也就是“没有它一定失败”的依赖。软依赖，也就是“有它更好但没有也能跑”的，不声明，留给智能体自己判断。

5.4 技能执行结果的结构化与可读性平衡

技能返回的结果，既要让智能体能解析，又要让人能看懂。这两个需求经常打架。

纯结构化的结果，比如JSON，机器好处理，但人看起来费劲。纯自然语言的结果，人好读，但机器解析起来容易出错。

我现在的做法是双轨返回：一个结构化的数据字段，给机器用；一个自然语言的描述字段，给人看。智能体在后续处理时用结构化字段，在向用户展示时用描述字段。这样两边都照顾到了。

当然，这要求技能开发者多写一点东西，但这点额外工作量换来的是整个链路的顺畅，非常值得。

6. 技能体系的评估与迭代

6.1 怎么判断一套技能体系好不好用

技能体系做出来之后，得有个评估标准。我一般看三个指标。

任务完成率是最直接的。给智能体一批任务，看它能独立完成多少。这个指标反映的是技能体系的整体覆盖度。

平均调用次数反映的是效率。完成同一个任务，调用次数越少，说明技能划分越合理，组合越紧凑。如果调用次数很多，往往意味着技能划得太细，或者编排逻辑有问题。

失败恢复率反映的是健壮性。技能失败之后，智能体能自己恢复的比例。这个指标高，说明错误处理和重试策略做得好。

这三个指标要一起看。只看完成率，可能会忽略效率问题；只看调用次数，可能会为了少调用而牺牲完成率。

6.2 从调用日志里挖出改进点

技能体系的迭代，最怕拍脑袋。我觉得最有价值的改进线索，藏在调用日志里。

我一般会重点看这几类日志：

• 高频失败：某个技能经常失败，要么是技能本身有问题，要么是触发条件写得太宽，在不该用的时候被调用了。
• 长链路：某个任务需要调用很多技能才能完成，说明缺少一个组合技能来固化这个流程。
• 零调用：某个技能注册了但从来没被调用过，要么是描述有问题，要么是这个技能根本不需要。

定期分析这些日志，比坐在那里空想怎么优化要有效得多。

6.3 技能体系的扩展节奏

最后说一个容易被忽略的问题：扩展节奏。

技能不是越多越好。每增加一个技能，智能体的选择空间就大一分，决策难度也大一分。我见过有的项目，技能列表长到几百个，结果智能体反而不知道该用哪个了。

我的建议是按需扩展。先做最核心的十几个技能，把主流程跑通，然后根据实际任务中暴露的缺口，一个一个补。每补一个，都要验证它确实解决了问题，而不是增加了复杂度。

扩展的时候还要注意合并同类项。如果两个技能的功能有重叠，优先考虑合并，而不是保留两个让智能体去选。选择越少，决策越准。

这套东西我断断续续打磨了挺长时间，中间推翻重来过好几次。最大的体会是：技能体系的设计，本质上是在灵活性和可控性之间找平衡。太灵活了，智能体乱来；太可控了，又失去了智能体该有的适应能力。这个平衡点没有标准答案，只能根据自己的任务场景慢慢调。但只要你把技能的分层、注册、调度、评估这几个环节都想清楚了，调起来就有方向，不会像无头苍蝇一样乱撞。