企业官网建设流程全解析

构建智能体时，"会做事"和"会稳定地做正确的事"完全是两种境界。我最近参与了代号 "agent-skills" 的模拟项目，核心思路是把智能体具备的所有能力拆成一个个独立、可复用、可测试的技能单元：一个技能只专注一件事，技能之间互不干扰，再由调度层决定什么场景下调用哪个技能、怎么调用。项目跑完一轮后，我最大的体会是：没有技能体系的智能体，就像让一个新员工"看着办"——偶尔超水平发挥，更多时候给你搞出各种匪夷所思的幺蛾子。这篇文章不聊概念，就说说我在这个项目里实际踩过的坑，以及最终沉淀下来的一套设计方法，希望帮你少走几个弯路。

1. agent-skills 到底在解决什么问题

1.1 没有技能体系的智能体是个什么状态

我最早接触智能体时，习惯把所有指令塞进一个大提示词里，让大模型自己发挥。表面看自由度很高，实际用起来问题一大堆。同样的需求，换个问法，它走的路就不同；上下文稍微偏移，它就漏掉关键步骤；明明上一步已经确认过的事实，下一步它又当作新问题重新处理。

印象最深的一次，模拟项目里让智能体做"从数据源读取文件、清洗字段、生成汇总报表"这一整条流水线。模型第一次给了完整的Python脚本，第二次却自作主张用SQL去查数，第三次干脆连输出格式都变了。结果是我花大量时间在"校对它到底做了什么"上，而不是在"让任务完成得更好"上。

这就是没有技能体系的典型症状：行为不可预期、过程不可复现、结果不可追踪。技能体系的核心价值，恰恰是把这种"随机应变"收敛成"标准化作战"。一个技能就是一套预先定义好的行为模板——包含目标、步骤、边界条件、异常处理、验收标准。智能体做决策时，不是从零推理"该怎么做"，而是从技能库里挑选"用哪套打法"。

1.2 技能与工具、工作流、提示词的边界

很多人在这个环节会绕晕：技能到底跟工具、工作流、提示词有什么区别？我最初也混淆，后来用一张表理清楚了。

注意看，技能是"工具+流程+决策"的组合体。工具是技能从外部借力的抓手，技能是工具的封装和使用说明书。比如"查询订单状态"是一个工具，而"处理售后投诉"是一个技能——它内部可能要先判断投诉类型，再决定调用哪个查询工具，然后根据结果走不同的回复模板，最后还要校验回复是否符合合规要求。

1.3 什么时候才值得引入技能体系

技能体系不是银弹，小项目硬上只会增加维护成本。我给自己定的判断标准有四个：

• 同一类行为在一个月内被触发超过十次，说明存在稳定复用需求。
• 对输出的格式、步骤、质量有硬性要求，不能接受每次都不一样。
• 智能体执行高风险操作（比如支付、发邮件、删数据）前需要强校验。
• 团队内多个人、多个项目都要复用同一套能力，需要集中管理。

如果四个条件一个都不满足，直接写提示词就行，别折腾。如果中了两个以上，那技能体系就值得认真考虑。

2. 技能体系的核心设计架构

2.1 一个技能由哪几个部分组成

我在项目中把技能定义拆成了六个组成部分，缺一个都不行。

• 技能名称：给调度模型看的机器标识，必须全局唯一、语义清晰。比如fetch_order_detail，而不是order或step1。
• 技能描述：一段自然语言文本，说明这个技能擅长什么、不擅长什么、在什么场景下使用。这是调度模型做选择的依据，写得好不好直接决定调用准确率。
• 输入参数定义：声明这个技能需要什么输入，字段名、类型、约束、是否必填。参数定义越严格，运行时解析错误越少。
• 内部流程：技能执行的具体步骤，可以是自然语言步骤清单、伪代码、或者直接绑定到一段可执行的函数/脚本。
• 终止条件与验收标准：什么情况下算执行成功，输出应该长成什么样。没有验收标准的技能一定会变成"黑盒"。
• 失败处理与回退：技能内部出错时怎么反馈、是否重试、是否切换到备用方案。这一步是很多方案里最容易漏掉的。

以项目中一个"知识库问答"技能为例，它的技能定义大概是这样的：

name: knowledge_base_lookup description: > 在内部知识库中检索与用户问题最相关的文档片段并返回摘要。 适合处理含具体名词、术语、产品名称的查询； 不适合处理主观意见类问题（如"你怎么看"）和计算类问题。 parameters: query: type: string required: true description: 用户的原始问题，保留完整上下文 top_k: type: integer required: false default: 3 description: 返回的候选文档片段数量，最大不超过5 steps: 1. 对 query 做向量化处理和关键词提取； 2. 在索引库中检索 top_k 个候选片段； 3. 逐条判断片段与 query 的相关性，低于阈值的丢弃； 4. 将最终片段压缩为摘要输出。 success_criteria: - 输出结果必须包含引用来源ID - 摘要长度控制在150字以内 fallback: - 若索引服务超时，重试一次； - 若重试仍失败，返回"知识库暂不可用，请稍后再试"，并记录日志。

这套定义看起来平平无奇，但每个字段都有存在的理由。比如description里写"不适合处理主观意见类问题"，就是为了让调度模型在遇到闲聊式问题时，主动跳过这个技能，而不是强行检索一个不相关问题。

2.2 技能如何被智能体调度

技能定义好了，下一步是解决"怎么让智能体在合适的时机选对技能"。我实际测试过四种方式，各自适用场景完全不同。

规则匹配最简单，用关键词或正则直接映射。比如用户消息里含"订单号"，就调用订单查询技能。优点是快、可控，缺点是无法覆盖模糊表达。

语义检索是主流做法：把技能描述向量化，用户请求也向量化，算相似度挑最接近的。这种方式宽容度高，但需要维护向量索引，且对描述质量极其敏感。

大模型路由则是把所有技能的名称和描述塞给模型，让模型自己选。这是最灵活的，但成本高、延迟大，而且当技能数量超过几十个时，模型的选择准确率会明显下降。

混合路由是最稳的：先走规则匹配，高频、关键词明确的请求直接命中；没命中的再走语义检索或模型路由。我强烈建议排序从混合路由开始，不要一开始就迷信某个单一方案。

实际项目中我还会给调度加一道"可否认"逻辑——如果所有技能的匹配度都低于某个阈值，智能体必须明确说"我没有适合处理这个请求的技能"，而不是硬选一个最相近的。这个设计帮我避免了很多答非所问的尴尬。

2.3 关键设计决策：粒度、命名与上下文打理

技能设计里最容易翻车的，是粒度控制。

粒度太粗，一个技能内部塞了大量逻辑分支，参数复杂到调度模型看不懂，出错了也难定位。粒度太细，技能数量爆炸，调度模型选择困难，维护成本剧增。我踩过的一次教训是：把一个"销售数据分析"技能拆成了"按时间筛选"、"按地区筛选"、"生成图表"、"输出报告"四个技能，逻辑上看似清晰，实际执行时智能体要在四个技能之间来回切换，上下文和中间结果丢失得一塌糊涂。后来我把它们合并成一个"销售分析报告"技能，内部用子步骤完成筛选、制图、成稿，反而稳定得多。

我总结的粒度参考标准是：技能内部步骤控制在3到8步之间；输入参数不超过5个；一个技能完成的是一个可描述的目标，而不是一个原子动作。

命名上也要注意，技能名称要偏动词+宾语，比如generate_weekly_report、parse_invoice_pdf。避免用抽象词，如data_process、helper，这种名字调度模型根本猜不到做什么。

上下文打理是我后来补上的一课。技能执行时，不应当把用户整个对话历史全部塞进去，而是只传入技能必要的参数。否则对话长了以后，模型会把无关信息也拿来当作上下文，导致输出偏题。我对每个技能定义了严格的"输入边界"，只允许读取参数中声明过的字段。

3. 从零搭技能库的实操过程

3.1 先从使用频率最高的任务开始

动手搭技能库，别贪多。我建议先做一次简单的统计：翻出过去两三个月的日志，找出智能体被要求做的最多的十件事，按次数排序，然后从第一名开始做技能。我在模拟项目里就先挑了"信息提取"——因为几乎每个业务场景都需要把用户的自然语言请求，转成结构化参数，是所有技能的基座。

先做高频任务的好处是反馈循环短，你今天写的技能明天就被反复调用，问题暴露得又快又集中。等你用这套方法跑顺了，再回头去补低频技能，质量和速度都会好很多。

3.2 技能描述到底怎么写才有效

技能描述我写了足有六版才满意，前面几版全被调度准确率按在地上摩擦。踩坑踩出来几条经验：

描述里必须写清楚"输入是什么、输出是什么、边界在哪里"。尤其是"边界"，很多人只写正面能力，不写负面限制。实际上，"不擅长什么"对调度的帮助有时比"擅长什么"还大。比如一个天气查询技能，描述里加一句"本技能仅支持国内城市查询，不支持海外城市，不支持历史天气查询"，调度准确率能提升好几个点。

还要注意描述的长度。太短则信息量不足，太长则淹没关键词。我发现300字左右是一个比较合适的安全区间。描述结构固定为：这个技能做什么、输入是什么、输出是什么、典型场景示例、明确不做什么。

3.3 参数校验是一个小成本大收益的环节

很多技能跑挂，不是流程逻辑错，而是参数没对上。用户说"我想看看上个月的销售数据"，调度模型把参数解析成start_date: 上个月, end_date: 上个月，这显然不对。

我在每个技能入口加了一层参数预处理，把常见的口语化表达规范化：

def preprocess_date_param(value): # 处理"上个月""最近七天""今年"等相对时间表达 # 处理"2024年1月""1月5日"等非标准化格式 # 统一输出为 YYYY-MM-DD pass

这一步看起来技术含量不高，但直接决定了技能执行能否顺利启动。我见过太多项目把时间都花在调模型上，忽略了这些"笨功夫"，结果参数解析错误成了出错率第一的环节。

3.4 技能测试不能只测"正常路径"

我刚开始写技能时，测试用例清一色是标准场景。比如测"订单查询"，输入一个合法订单号，期待正确返回。后来上线两天就翻车，因为真实用户输入的是"帮我查一下昨天那单"，根本没有订单号。

后来我把测试分成三类：正向用例、边界用例、对抗用例。正向用例验证技能正常路径正确；边界用例验证临界输入，比如空值、超长文本、正则特例；对抗用例验证你不期望它处理的内容，比如让订单查询技能去翻译一句话，它应该拒绝而不是硬答。每个技能上线前，至少要有9到12条测试用例，三类各占三分之一。

我把这套测试做成了自动化回归，每次技能定义或实现有改动，跑一遍全部用例。效果立竿见影，技能行为稳定性上了一个台阶。

4. 技能跑通后我踩过的那些坑

4.1 技能调对了，输出仍然"不像话"？

项目进行到一半，有个技能测试全部通过，但内部评审时大家一致觉得输出"差口气"。仔细排查后发现，问题不在技能流程，而在输出的表达方式：技能把结构化数据直接格式化成文本，读起来干巴巴的。

这个问题的根源，是我把技能的"逻辑层"和"表达层"混在了一起。技能内部负责产生正确的结构化结果，但最终呈现给用户的话术，应该交给表达层根据场景自由组织。于是我把技能输出改成返回结构化数据，再定义一段"话术生成"的提示词，把数据包装成自然语言。改完之后，同一个技能可以既用于终端用户对话，又用于生成日报摘要，输出质量都好了不少。

这是一条很重要的经验：技能不要接管"表达"职责，只负责"决策"和"执行"。

4.2 技能之间互相干扰，共享状态是万恶之源

有一次我上线了五个技能，发现其中一个技能的执行结果会被另一个技能意外篡改。排查了两天才定位到问题：这两个技能共用了一个全局缓存变量，第一个技能往缓存里写入了中间结果，第二个技能在初始化时错误地读取了这个残留值。

从那以后我立了一条规矩：技能之间不共享任何可变状态。所有数据交换只通过技能的输入输出参数完成。如果确实有需要跨技能传递的数据，必须显式地作为参数传入，且变量名要带有技能前缀，避免冲突。

这个改动让技能从"互相耦合的组件"变成了"完全独立的功能单元"。后面凡是遇到诡异的跨技能问题，我先去查有没有违反这条规矩，排查效率提高了很多。

4.3 日志不完整，出了问题只能干瞪眼

另一个让我头大的问题是：技能跑完之后，日志里只有"开始执行""执行成功"两条记录，出了错完全不知道中间哪一步出的问题。后来我在技能框架里强制加了三个埋点位置：技能入口参数快照、每一步关键执行结果摘要、最终输出全量记录。

这三个埋点的价值在排障时体现得淋漓尽致。有人反馈一个技能结果不对，我直接把参数快照和步骤摘要拉出来对比，很快就能定位是输入参数本身就解析错了，还是中间某一步的处理逻辑有问题，而不需要盲猜。

我还做了一个小工具，把每轮执行的日志折叠成一个"回放链路"，可以重看该技能当时是如何决策的。这跟代码调试里的断点一样好用，强烈建议你也试试。

4.4 出现频率最高的问题与排查速查表

这个表看起来简单，可每一条背后都有真实事件支撑。尤其是"技能描述模糊"这一条，我前前后后改了不知道多少遍才意识到，问题不在模型，在描述文本本身。

5. 技能库需要当成产品去经营

5.1 技能仓库的目录结构与管理规范

当技能数量超过二十个以后，零散存放会变成灾难。我在项目里建立了一套统一的仓库结构：

skills/ common/ 信息提取/ 技能定义.yaml 实现逻辑.py 测试用例.json 变更记录.md 日期解析/ ... 业务域A/ 售后处理/ ... 业务域B/ 销售分析/ ...

每个技能一个目录，目录内固定包含四类文件：定义、实现、测试、变更记录。变更记录是后来加的，因为每次改完技能，过两周就忘了为什么这么改。这个文件里会写：改了什么、为什么改、影响范围、谁来review的。后面排查回归问题全靠它。

5.2 技能质量要靠数据说话

主观判断一个"技能好不好"容易吵架，我用四个客观指标来衡量：

• 调用成功率：技能执行完成且通过验收标准的比例。
• 调度准确率：用户请求被路由到正确技能的比例。
• 平均执行耗时：从触发到返回结果的时长。
• 单次执行成本：token消耗或资源开销。

每个指标按周统计，周会上一摆出来，哪个技能质量有问题一目了然。我印象很深的是，一个技能调度准确率只有62%，谁都说不清为什么。后来把错误案例拉出来聚类，发现超过一半的误调度都发生在用户表达含"某个含糊代词"的场景。于是我在描述里补充了"当用户指代不明时不要调用本技能"，准确率直接拉到了88%。

这种"数据发现问题、调整描述、数据验证效果"的闭环，是技能库持续变好的核心机制。

5.3 团队协作里最容易被忽视的环节

技能库一旦多人协作，最怕的就是"偷偷改技能"。有一次我负责的技能被别人改了参数含义，我不知情，调用方全部出了偏差。后来我加了技能变更的评审机制：任何修改必须发起变更说明，至少一个人review，改动上线后跑一遍自动化回归测试。

另外一个容易被忽视的点是技能文档的语言风格。团队里有人写描述喜欢用"聪明"的长句，有人的描述像代码注释。最后我们统一成"面向调度模型的说明文档"风格：短句、主动语态、避免修辞。描述的质量直接决定调度质量，这一点怎么强调都不过分。

6. 亲身试验后的一些心得体会

整个项目跑下来，我对"技能"这件事最大的感受是：它解决的不是"智能体聪明不聪明"的问题，而是"智能体靠谱不靠谱"的问题。模型底座决定它有多聪明，技能体系决定它能多稳定地完成任务。前者是上限，后者是地板。没有地板，上限再高也落不了地。

如果你现在正准备给自己的智能体搭建技能库，我的建议是先忍住"什么都要支持"的冲动。从三个高频任务开始，把每个技能当成一个小产品去打磨：描述改到位、参数校验做扎实、测试用例写充分。跑顺了再逐步扩展。技能库这个东西，广度是慢慢长出来的，深度是一开始就要夯实的。

最后再分享一个让我少走了不少弯路的方法：每次技能出问题，先写一份"事故记录"，描述问题现象、排查过程、根因、修复动作、预防措施。把它放在技能目录的变更记录里。三个月后回头看，你会发现很多曾经让你熬夜的问题，都是相似的几个根因在反复出现。把这些根因提前防住，技能体系自然就稳了。