企业官网建设流程全解析

最近一直在琢磨怎么让Agent跳出"聊天框"，真正落地到具体任务里。

做得越深越发现，卡住很多团队的不是模型能力，而是技能——Agent 能不能稳定地完成"查天气、订机票、写报表、操控软件"这类具体动作，靠的是一套结构化的技能系统，而不是模型临场发挥。我做的这个"agent-skills"项目，说白了就是一套面向AI Agent的技能定义、注册、调度与沉淀机制，让Agent从"会聊天"变成"会干活"。

如果你正在做Agent应用，或者被"提示词越写越长但效果却越来越飘"这个问题折磨着，这篇文章里的思路和踩坑记录应该能让你少走很多弯路。文章会从头到尾拆解我是怎么设计这套技能库的，包括技能描述规范、执行器绑定、任务编排、失败反馈闭环，以及一套我自己反复调过的技能效果评估方法。

1. 为什么Agent需要一套"技能库"

先说个比较扎心的观察：很多人做Agent，第一步就是堆提示词——把各种任务约束、背景知识、示例对话全写进System Prompt里。前几个版本效果还行，一旦任务变多、变化变快，模型就开始"精神分裂"：一会儿忘记格式要求，一会儿把A任务的规则带到B任务里，同一个功能在不同对话轮次里的表现完全不一致。

问题的根源在于，用自然语言往一个上下文里塞多任务规则，本质上是在跟模型的天性较劲。模型擅长的是在明确的边界内做生成和理解，而不是在一堆互相纠缠的指令里做逻辑分流。

技能库的思路是把"规则"变成"程序化接口"。每一个技能都独立封装，包含自己的触发条件、输入参数、执行逻辑、输出规范，Agent只需要根据用户意图做一次"技能路由"，剩下的细节全部交给技能内部去处理。这和微服务架构是一个道理：高内聚、低耦合，各自的职责边界清晰了，整体系统的稳定性自然就上来了。

我设计"agent-skills"时有三个明确目标：

1. 让技能可插拔。新增一个技能就像给系统加一个插件，不碰其他任何模块，也不影响已有技能的行为。
2. 让技能可度量。每个技能有明确的评分指标和回归测试集，模型升级或者提示词调整后，能立刻知道是变好了还是变坏了。
3. 让技能可沉淀。通过观察真实使用记录，把那些成功率低、用户反复手动修正的场景自动提取为新技能，形成一套自进化的闭环。

这套思路做下来，最直观的变化是：同样一个意图识别任务，之前的准确率大概在82%左右飘着，用了技能库之后再没低于过94%，上下文越长表现越稳定。

2. 核心设计：技能是"意图、参数、执行、检查"四位一体的单元

2.1 技能描述：给Agent看的说明书，不是给人看的

技能定义的核心难点，不在于字段怎么命名，而在于让Agent在路由决策时能精准判断"这个技能适不适合当前任务"。人看技能描述靠的是常识，Agent看技能描述靠的是语义匹配，两者标准完全不一样。

我最初一版技能描述是用技术文档口吻写的，各种功能模块讲得特别详细，结果实测效果惨不忍睹——Agent把"帮我定下周三去杭州的会议室"路由到了"订机票"技能上。排查后发现，问题出在技能描述里的"行程管理"这个词，让模型误以为会议安排也属于行程范畴。

后来我重新定义了一套技能描述规范，核心就四个维度：

• 技能一句话简介：用最直白的行动句描述"这个技能帮用户完成什么"，控制在15个字以内。比如"查询指定机场的航班动态"而不是"提供航班信息检索服务"。
• 触发条件列表：列举这个技能必须满足的前置特征，每条都写成"当用户提到[关键词/意图]且满足[条件]时"。负例同样重要，明确写清楚"不处理"的场景，比如"不包含退改签操作"。
• 输入参数定义：使用JSON Schema风格描述，但每个参数都附一段"抽取要点"的自然语言说明，告诉模型遇到口语化表达时如何处理。比如"日期"这个参数就写了"支持'下周三'这类相对日期表达，自动换算为具体日期"。
• 输出效果说明：说明用户期望从这次执行里获得什么结果，方便模型在执行后做自检。比如"输出应包含航班号、起降时间、航站楼三部分"。

这套描述方式最关键的其实是负例清单。之前Agent乱路由，大多数情况不是不懂正例，而是不了解边界。负例写清楚了，路由的精确率直接提升了将近15个百分点。

2.2 执行器绑定：技能壳与执行体的分离

技能描述是"给Agent看的说明书"，但真正干活的是执行体。在设计的时候我把两者完全拆开：技能壳（Skill Shell）负责描述与路由，执行体（Worker）负责具体动作。这样做带来的直接好处是，同一个技能壳可以对接完全不同的执行后端。

比如"查询天气"这个技能壳，初期对接的是一个天气接口的门面封装；后来需要支持从网页兜底抓取信息了，我只新写了一个Worker挂上去，技能壳一行没改。反过来，当我把底层模型从旧版本升级到新版本时，也是只调整执行体内部的提示词策略，技能路由层完全不受影响。

执行体的内部结构我一般分成三层：

1. 参数补全层：负责把技能壳传进来的原始参数做清洗和兜底。比如用户说"帮我查一下上海的天气"，没给日期，那这层就会把日期补成今天，再把"上海"标准化为城市编码。
2. 执行策略层：真正的业务逻辑在这里。可以是函数调用、SQL查询、API请求，甚至是一次"模型推理+规则校验"的混合流程。
3. 结果校验层：对执行结果做合法性检查。我之前遇到过一个特别典型的坑：某次天气接口在极端情况下返回了全是HTML错误页的内容，状态码却是200，结果Agent直接把这个错误页当成搜索结果念给用户听了。加了一层结果校验之后，这类问题基本绝迹了。

分层设计还有一个隐藏好处：每一层都可以单独做缓存和监控。参数补全层如果频繁触发兜底逻辑，说明用户表达习惯和技能设计有偏差，需要调整描述；执行策略层如果耗时长，说明接口性能有问题；结果校验层如果经常报错，说明上游数据源不稳定。这些信号在单一实现里根本看不见，拆开之后全部变成了优化线索。

2.3 一个技能文件长什么样

直接放一个简化的技能定义示例，用的是我项目里的YAML配置格式：

skill: id: "flight_search" name: "航班动态查询" description: > 查询指定机场的航班起飞、到达信息。 触发条件：用户提及航班号/起降机场/航线，且意图为查询状态。 不处理：退改签操作、机票购买、机场交通路线。 version: "2.3.1" parameters: flight_no: type: string required: false description: "航班号，如CA1234。支持提取'国航1234'这类口语表达。" dep_airport: type: string required: false description: "出发机场三字码，如PEK。若不提供则根据用户当前位置推断。" date: type: string required: false description: "查询日期，格式YYYY-MM-DD。支持'明天'等相对日期，默认当天。" executor: module: "workers.flight_search" class: "FlightSearchWorker" params_mapping: flight_no: "flightNo" dep_airport: "departureAirport" date: "queryDate" output_spec: required_fields: ["航班号", "计划起飞", "计划到达", "状态"] style: "bullet_list"

这个配置初看可能平平无奇，用久了会发现几个容易被忽略的设计细节：

version字段绝对不能省。技能是会演化的，没有版本号就很难做灰度对比。我后来加了一套机制：同一个技能ID可以存在新旧两个版本，路由层按比例分流流量，跑一版对比数据之后才决定全量切换。

params_mapping独立出来是个小决策，但省了无数心力。技能壳里的参数名以自然语义为准，执行体里的参数名以代码库风格为准，两者通过映射关联。这样技能Shell可以面向使用场景命名，Worker可以面向技术实现命名，谁都不用迁就谁。

output_spec必须有，而且要具体。起初我写的是"输出航班信息"，结果模型有时候输出成一大段描述文字，用户根本没法一眼看到重点。后来改成明确字段列表加序号列表要求，效果立刻就正常了。

3. 技能路由：让Agent在正确的时间选到正确的技能

3.1 路由层为什么要独立于技能执行

这是我踩过最深的一个坑，值得单独拿出来说一下。

早期版本的架构是"模型直接调用工具"模式：Agent收到了用户请求，在上下文里看到了工具列表，自己决定调哪个工具。听起来很灵活，实际使用里问题很大——模型面对五六个工具的时候表现得还行，但工具数量一旦超过二十个，选择准确率就急剧下滑。更麻烦的是，工具的定义经常会被对话历史里的内容干扰，用户上一轮说了什么会影响这一轮的工具选择。

后来的调整是把"路由决策"和"工具执行"彻底拆成两个阶段。路由层只做一件事:从技能库里选出最匹配的技能，不输出任何业务结果。选完技能之后，再把技能壳、原始用户消息、上下文摘要打包交给执行体去处理。

这个拆分换来了两个关键收益：

一是路由上下文更干净。路由时只加载技能索引列表和用户当前意图，不受冗长对话历史干扰，也不受各种业务规则缠绕。之前那种"用户聊着聊着天气突然问股票，模型还在纠结上一个话题"的情况彻底消失了。

二是路由可以单独做优化和兜底。比如我可以针对路由结果加一个置信度阈值，低于阈值就主动追问用户确认，而不是硬着头皮执行。不确定的时候承认不确定，这种兜底机制在老架构里很难实现，因为在模型自己的决策流里插入干预逻辑是很别扭的。

3.2 用规则做预处理，用模型做语义匹配

路由阶段用了两层机制组合，不是单纯依赖模型"自由发挥"。

第一层是规则预处理。我会给高频场景配上关键词和正则规则，能命中就直接锁定技能，不走模型推理。比如用户说"帮我定个闹钟"，"闹钟"这个词直接命中提醒技能，这层的时间开销近乎为零。处理掉高频场景之后，剩下的语义模糊请求才交给模型路由，压力小了很多。

第二层是模型语义匹配。使用向量化检索做初筛，从技能库里捞回Top 5候选，再让模型根据技能描述的语义精确度做排序。这里有个细节：初筛阶段用的是描述文本的Embedding相似度，而排序阶段用的是指令遵循能力更强的模型做判别式选择，两阶段各司其职。

这套"规则兜底高频+模型解决长尾"的组合拳，让路由平均耗时从原来的1.2秒降到了300毫秒以内，同时准确率还比纯模型方案高了不少。核心原因是规则把确定性问题吃掉了一大半，模型处理的都是真正需要语义理解的请求，推理压力小了，表现自然更稳定。

3.3 路由置信度与主动澄清

路由层还做了一件特别重要的事：主动澄清。

当模型选出的最优技能置信度不高，或者技能的必要参数明显缺失时，不再硬着头皮执行，而是生成澄清问题反问用户。比如用户说"帮我看下怎么去那边"，"那边"指代不明，技能路由完全没法确定意图，这时候我会让路由层返回一个"澄清请求"标记，由对话管理模块生成问题："请问您说的'那边'具体是指哪个地点呢？"

这个机制在早期版本里是不存在的，当时的逻辑是"相信模型，强行执行"，结果就是模型经常把模糊指令脑补成具体请求，做了大量用户根本没想做的事情。有一次用户说"帮我看看周五的安排"，Agent直接定了餐厅并发了会议邀请，完全跑偏了。加上置信度机制和澄清逻辑之后，这种误操作基本清零。

置信度阈值怎么定？我实验下来，0.7到0.75是一个比较合理的区间。阈值太高会频繁追问打断用户，阈值太低又会放行太多模糊请求。每次上线新技能或者修改技能描述之后，我都会跑一轮回归测试来校准这个值。

4. 技能编排：先约束，后执行

4.1 为什么不能把编排完全交给模型

单技能执行解决的是"一个明确任务"，但真实用户请求经常是"一堆动作组合"。比如"帮我订明天去深圳的机票，到了之后找一家离机场近的酒店，再把行程发给同事小林"。这串请求里至少包含三个技能：机票预订、酒店搜索、消息发送。

处理组合任务的方式从架构演进看有两个极端：一端是写死工作流，每一步都提前编排好；另一端是让模型自由挥洒，想调哪个技能就调哪个技能。这两个极端我都不推荐。

写死工作流的问题在于无法应对变化。用户随口一句"如果有早班机就订早班机"，一个静态工作流根本没法表达这种条件分支。让模型自由发挥的问题则在于不可控，模型可能跳过关键步骤，也可能在两个技能之间反复横跳。

我采用的是中间路线：用轻量级编排描述约束执行框架，把复杂的决策权留给模型，但把顺序约束和依赖关系用结构化方式表达出来。具体来说，就是定义一张简单的"技能依赖图"，每个技能节点声明自己的前置条件和后置产出，执行引擎自动做拓扑排序。

4.2 技能依赖与数据传递

技能依赖图的设计思路，有点像任务管理器里的依赖关系视图。每个技能在注册时声明：

• 执行条件：运行这个技能之前，哪些条件必须满足。比如"发送消息"技能要求"收件人列表"参数非空。
• 产出物：技能执行完之后，会向全局上下文写入哪些结构化数据。比如"酒店搜索"技能的产出物是"酒店候选列表（含价格、距离、评分）"。

有了这两份声明，执行引擎就可以在运行时自动推导:

1. 阅读用户的原始请求，由编排模型把它拆解为"意图草图"（一连串待执行技能节点）。
2. 对草图做合法性检查，补上缺失的中间步骤。用户说"订机票并通知同事"，但没说查航班，引擎会自动在"订票"前插入"航班查询"节点。
3. 按依赖关系做拓扑排序，顺序执行，上一个技能的产出物自动成为下一个技能的输入。

这套机制最大的好处是，模型只需负责设计意图，不需要操心流程细节。就算模型漏了某个步骤，依赖图检查也会把它拉回来。

4.3 编排失败时的降级策略

不受控的编排一定会出现失败情况，处理失败才是系统工程里真正见功夫的地方。我记录一下实测中遇到过的高频失败形态，以及对应的降级策略：

• 技能参数缺失，但可以通过上下文推断。用户说"帮我订个酒店，上次住的那家就行"，'上次住的'这个数据在历史记录里，但当前技能参数列表不包含。这种不直接报错，而是触发一次"上下文参数回填"，从历史会话里检索补充。
• 多个技能存在执行顺序冲突。比如"先查询再预订，如果价格没变化就直接下单"，'价格没变化'本身是一个逻辑判断，不是技能调用。这种场景我单独提供"条件判断"节点，把它嵌在技能依赖图里当分支节点用。
• 串联技能中某一个失败了。默认策略是中止整条链路并如实告知用户，不自动伪装成"部分完成"。"已发送"就是已发送，"预订成功"就是预订成功，Agent绝不能替用户脑补结果。

这些降级策略并不是一次性设计出来的，都是在真实请求的高压测试下反复打磨出来的。最开始总想着"让系统看起来聪明一点"，后来发现让系统诚实地承认自己做不到什么，用户体验反而好得多。

5. 技能评估与回归测试

5.1 单技能评分卡

技能定义完了、路由也跑通了，接下来最头疼的问题是：怎么量化一个技能"好不好"。如果只用"效果还行"这种标准，根本没法驱动持续优化。

我设计了单技能评分卡体系，从五个维度打分，每个维度0到100分：

每个版本迭代前，我会构造一个覆盖典型场景、边界场景和干扰场景的测试集，大概每个技能50到100条标注样本，跑一遍评分卡。版本上线后再对比新旧版本分数差异，来验证改动方向对不对。

这套评分体系救了我很多次。有次我优化技能描述时，自以为写得更清楚了，结果路由准确率降了8个点。回看评分卡才发现，问题出在描述里的表述过于正式，反而偏离了用户的日常表达方式，测试集的自然口语样本全部翻车了。没有量化数据的话，这种隐蔽回退根本发现不了。

5.2 回归测试集的构建原则

构造测试集是这套系统里性价比最高的工作，分享几个实践原则：

• 真实用户语料优先，而不是凭想象写假样本。从日志里采集那些实际出现过的句式、同义表达、口误和省略，标注好正确意图和参数。
• 刻意加入干扰项。比如用户同时提到了"天气"和"机票"，测试一下系统会不会正确路由到"航班查询"而不是"天气查询"。这种边界样本最能暴露问题。
• 保持测试集版本可追溯。每次评估都要记录用了哪个版本的测试集。测试集本身如果一直在变，前后数据就没法对比了。

回归测试集不用追求数量巨大，但样本质量一定要顶上去。我现在维护的测试集一共就两千多条，已经足够支撑常态化的版本评估了。

5.3 线上效果追踪的回流闭环

离线评分是"实验室数据"，上线之后的表现可能完全不同，核心原因在于真实用户的语言风格复杂得多。所以我又加了一套线上效果追踪机制。

具体做法是给每个技能节点注入埋点，记录四种事件：命中事件（技能被选中）、成功事件（执行完成）、修正事件（用户对结果表示不满或手动修改）、失败事件（执行报错）。通过计算这几种事件的比例，形成"线上健康分"。

举个例子，某个控温技能代码逻辑没什么变化，但最近一周的"修正事件"比例突然翻倍了。排查发现是一栋建筑的传感器数据源变更了单位，导致技能执行结果全部失真。如果没有线上事件追踪，这种问题大概率要等用户正式投诉之后才会发现。

更让我惊喜的是，这些事件数据经过分析，还能反向挖出新的技能需求。我统计"修正事件"时发现，用户经常在"查询会议室"之后追问"那有没有投影仪"，这个追问触发的技能命中率很低。后来我把"查询会议室设备"从"查询会议室"技能里拆出来独立成一个技能，加上专用参数，健康分直接涨到了95分以上。这就是技能沉淀的正向循环。

6. 踩坑实录与迭代心法

6.1 五个核心踩坑复盘

整理一下开发过程中印象最深、坑最深的问题，按照"现象—原因—解法"的格式分享。都是真金白银攒出来的教训。

坑一：技能描述炫技导致路由漂移

现象是给某个技能写了一份文采斐然的描述，上线后路由准确率反而下降了。原因是描述里用了很多同义词和专业化表述，把模型的语义重心带偏了。后来改成朴素、确定性的语言，把动作动词和时间副词作为重心，效果立刻回升。

这个经验总结下来就是：技能描述不是写作文，别追求辞藻，要追求确定性。每个词都往"这个技能到底是干什么的"这个核心语义上靠。

坑二：参数抽取过度依赖模型"聪明"

早期所有参数抽取都靠模型从用户原话里提取，模型一换版本或上下文一长就崩。后来加了规则抽取与模型抽取的混合管线，凡是能用规则解决的（日期换算、城市编码、电话号码脱敏）全部先让规则做，模型只处理剩余模糊部分。稳定性好了不止一个量级。

坑三：执行结果不校验，前端直接愣住

某次技能对接的数据源返回了空数组，但状态码是200，执行体以为成功，直接给模型返回了一个"查询成功，结果为空"的假象。模型对着空结果一本正经地编了一段FAQ告诉用户"该区域没有商铺"，给用户造成极大困惑。

后来所有执行体强制增加结果校验层，空数组、异常结构、引用缺失一律视为执行失败。宁可承认失败，也不能用编造的结果去误导用户。

坑四：编排上下文无隔离，技能之间互相污染

早期编排时把所有技能的中间结果全部塞进同一个上下文，导致技能B的输入里混着技能A的过程性信息，模型经常把无关数据当成输入参数。后来引入了"编排上下文隔离"机制，每个技能只能看到依赖图里声明过的前置产出物，其他数据一律不可见。这次改动之后，编排链路的成功率涨了近10个点。

坑五：没有灰度机制，一次优化毁掉全局

有一次改了一个底层技能的执行策略，离线评分看着全线飘红，上线后却发现某个边缘场景直接废掉。原因是我测试集里没有覆盖那类边缘请求，等用户报障才意识到问题。后来所有技能上线都强制走灰度流程：先切5%流量试跑24小时，比对健康分，再逐渐放量。这个流程看起来繁琐，但救回来的场景远比多花的功夫值钱。

6.2 技能更新的灰度发布流程

说到灰度，展开讲一下完整的更新流程，照着抄基本不会出错：

1. 离线评估：在新版本技能上跑全量回归测试集，评分卡分数必须不低于当前线上版本，否则退回优化。
2. 影子模式：把新版本技能的决策结果与线上版本并排运行，但执行结果不透出给真实用户，只记录日志做对照分析。这一阶段要重点看路由差异，那些新版本选错而旧版本选对的样本就是优化线索。
3. 小流量灰度：切5%的真实请求给新版本技能，运行24到48小时，观察线上健康分和用户修正事件比例。要注意不同时间段流量特征差异，至少覆盖一个完整工作日。
4. 逐步放量：健康分达标后按25%、50%、100%分阶段放量，每阶段观察12小时以上。放量期间不能只盯着平均值，还要拆维度看分时段、分渠道的数据。
5. 版本钉住与回滚：灰度通过后，把新版本钉住为线上默认版本，旧版本保留回滚通道。一旦发现极端情况，可以一键切回旧版本。

这套流程看起来步骤多，实际执行起来都是自动化脚本在跑，人工只需要在每个放量节点看一眼健康分仪表盘。但它带来的确定性收益，远超我投入的时间成本。

6.3 给新技能"起名字"的技术细节

最后分享一个容易被轻视但实际非常重要的小细节：技能ID和名称的定义。

ID尽量用领域约定俗成的缩写，别用太泛的单词。比如"booking"这种名字一定要避免，它会涵盖机票、酒店、餐厅、会议室各种预订，后续技能拆分的时候光改名字就是一场灾难。

我建议技能ID遵循"领域_动作"的命名规范，比如"hotel_search"、"flight_booking"、"meeting_room_reserve"。这样既保证了唯一性，又能在路由索引阶段做前缀分组查找，提高检索效率。

技能名称则是"用户视角"的说法，要用目标用户说话的方式命名，而不是系统开发者的术语。用户说"查航班"，不说"航班动态技术查询"，技能名称就按用户的说法来。名称和描述走两个体系，名称追求口语贴切，描述追求结构严谨，两者并存在同一个技能定义里，各司其职。

7. 技能沉淀：让Agent从真实使用中长出新的能力

这套系统里我最喜欢的一部分，是技能的自动沉淀机制。

思路并不复杂：持续分析线上"修正事件"与"失败事件"的聚类结果。当一个场景反复出现"用户请求→技能执行→结果被修正"的循环时，说明当前技能库没有覆盖好这类需求，值得生成一个新技能或者调整现有技能的边界。

举例来说，我在分析中发现，用户经常先说"帮我评估下这个项目方案"，然后追问一句"有几个关键风险点"。现有技能库只有一个"文档总结"技能，它把项目方案的风险点部分折叠进了总结里，用户根本没法按风险维度追问。于是我把"项目风险分析"从"文档总结"中拆出来，设了"风险类型""严重程度""缓解建议"三个参数，加了一个风险分类的执行策略。这个新技能上线后，命中率一直稳定在90%以上。

自动沉淀的本质，是把用户行为和系统失败当成免费的标注数据。每个修正事件都是一条标注样本："用户不认可这个结果，他想要的东西是那样的"。把这些样本批量喂给分析管线，人只需要在最后做一次审核和技能设计确认，不需要从零开始构造需求。

不过这个机制有一个需要注意的地方：不要过度拆分。如果用户问"这个方案的项目风险"就拆一个"项目风险分析"技能，问"方案里的预算"又拆一个"预算分析"技能，技能库很快就会被碎片化，路由压力反而增大。我的经验是，只有当修正事件在14天窗口内达到一定阈值（比如30次以上），且技能语义在向量空间里确实与现有技能有足够区分度时，才考虑新增或者拆分。

从结果来看，这套"使用—失败—沉淀—再使用"的循环，让系统在下线后的几个月里持续变强。每次去查看统计报表，都能看到新增技能从设想到上线的完整轨迹，那种"系统在自我进化"的感觉，是其他工程任务很难替代的。

如果你也被Agent应用"效果不可控、需求大爆炸"的问题困扰着，我觉得可以参考这套"技能库"思路，从最小闭环开始搭建：先给现有Agent梳理技能边界，再逐步加上路由、编排、评估和沉淀机制。不用一次到位，但"让每一个技能都可度量、可回滚、可独立优化"这件事，值得尽早做起来。