企业官网建设流程全解析

1. 技能体系的整体设计思路

做Agent开发的朋友应该都有过这种体会：模型本身的能力再强，如果不知道什么时候该调用什么工具、怎么把多个操作串成一条完整的执行链路，那它本质上仍然只是一个“很会聊天的机器人”。我之前在几个项目里反复折腾过这类问题，比如让Agent去查数据库、写文件、调接口，单看每一个操作都能完成，但只要涉及到“先查A再根据A的结果去处理B，中间还要做几次判断”这种多步骤任务，就经常出现卡壳、乱调、结果对不上号的情况。后来我逐渐意识到，问题不在于模型本身，而在于我从来没有给Agent建立一套真正可管理、可复用的技能体系。

“agent-skills”这个名字听起来挺抽象，说白了就是给Agent配备一套标准化的能力工具箱，并且给这些工具定义清楚使用规则、触发条件、参数格式和组合方式。它解决的核心问题有三个：第一，让Agent知道在什么情况下该用什么技能；第二，让技能之间可以按需组合，完成复杂的多步任务；第三，让开发者对Agent的行为有迹可循，而不是黑箱式地“凭感觉调参”。

适合谁来参考？如果你正在做基于大模型的智能体应用，比如客服机器人、办公助手、数据分析助手，又或者你手上已经有一个Agent原型但总觉得它在“真实干活”的时候不够可靠，那这篇文章应该能给你一些可以抄作业的思路。我后面讲的所有内容，都是基于我自己在几个模拟项目里踩坑、重构、再踩坑之后沉淀下来的实践方案，不一定是最优解，但至少是验证过能跑通的路径。

先说一个我经常用来跟别人解释技能体系的话：如果把大模型比作一个聪明的新员工，那他入职之后最需要的东西就是一套清晰的工作手册。技能定义就是工作手册里的条款，技能编排就是告诉他“先做什么、再做什么、遇到什么情况该换一种做法”。没有这套手册，他再聪明也只会凭感觉行事，你永远不知道他下一步会干什么。

整个设计过程中，最需要想清楚的不是“我要给Agent多少技能”，而是“我要用什么样的规则让Agent在合适的时机选出合适的技能”。这里涉及几个核心模块：技能的定义规范、技能的注册与发现机制、技能的调度与编排逻辑、技能执行过程中的状态管理，以及事后怎么追踪和复盘。下面我按每个模块拆开讲。

2. 技能定义规范与参数约束

2.1 一次失败的技能定义让我学到的教训

最早我做的Agent是一个文档处理助手，需要支持总结文本、提取关键词、翻译段落这类能力。当时我偷懒，把所有功能都塞进了一个叫“process_document”的函数里，参数也只有一个含糊的“task_type”。结果Agent经常搞不清楚该填“summarize”还是“extract”，甚至有时候会传一个根本不存在的任务类型进去，然后整个流程就崩了。后来我把每个功能拆成独立的技能，给每个技能写了明确的描述、参数说明、使用场景和禁忌条件，情况才好转。

那次经历让我总结出一个原则：技能定义的目标是“消除歧义”，而不是“表达意图”。你写给模型看的每一句话都应该尽量降低它的猜测成本，如果一段描述存在两种理解方式，那在实际运行中就一定会出现错误调用。

一个标准的技能定义至少应该包含以下几块内容：技能名称（机器可读的唯一标识）、技能描述（模型能理解的用途说明）、参数声明（严格的结构化定义，标明类型、是否必需、取值范围）、执行体（实际干活的函数或脚本）、前提条件（哪些状态必须满足才能执行）、资源约束（超时时间、重试策略、并发上限等）。这六块里最容易被忽略的是前提条件和资源约束，但它们恰恰是技能能稳定运行的关键。

2.2 用JSON Schema约束参数就是给模型带上护栏

参数声明这一块，我的建议是直接用JSON Schema来写，不要手搓自定义格式。原因很简单：JSON Schema是现成的标准，很多模型对它的理解都比较稳定，而且它天然支持必填校验、类型检查、枚举限制和嵌套结构，这些正好是约束模型输出所必需的。

比如我设计一个“发送邮件”的技能，参数部分大概是这样的：

{ "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "description": "收件人地址列表，至少一个" }, "subject": { "type": "string", "maxLength": 200, "description": "邮件标题" }, "content": { "type": "string", "minLength": 1, "description": "邮件正文" }, "priority": { "type": "string", "enum": ["low", "normal", "high"], "default": "normal" } }, "required": ["to", "subject", "content"] }

关键的细节在几个容易被忽视的地方：to字段限制成数组并且至少一个元素，就避免了模型传空数组或者传单个字符串时程序还要做类型兼容处理；priority用枚举而不是自由字符串，目的就是让模型没有发挥空间；maxLength和minLength这种文本长度约束，在防止模型生成超长内容时非常有用。

不过光有Schema还不够，实际运行中模型不一定会严格按Schema输出，所以我通常会在执行技能之前加一道校验：如果参数不合法，不直接报错，而是把校验失败的原因拼成一段提示回传给模型，让它可以自动修正参数之后再试一次。这个“校验-反馈-重试”的闭环，能把大多数参数错误在真正执行之前就拦截下来。

2.3 技能评估的关键是先定义清楚能力边界

技能设计里还有一个隐藏工作，就是给每个技能写清楚适用边界。比如一个“查询天气”的技能，需要说明支持哪些城市、数据覆盖的时间范围、无法处理什么情况（比如查历史气温）。这些边界信息看起来是给开发者看的，其实模型在调度技能时同样依赖它，否则Agent很可能拿着一个过期的技能去处理一个完全不属于它能力范围的问题，浪费大量轮次后还是拿不到结果。

3. 技能注册机制与动态发现

3.1 静态技能清单是起步，动态发现才是真正实用的形态

第一版技能系统我用的是静态清单，也就是把几十个技能写在一个文件里，每次构造提示词的时候全部塞进去。技能少的时候没问题，但等到技能数量超过二十个之后，问题就开始出现了：模型在长上下文里定位相关技能的能力急剧下降，经常忽略掉一些明明相关的技能，反而去调用一个名字看起来沾边但功能完全不对的技能。

这个现象让我意识到，把全部技能一股脑塞给模型，本质上是在增加它的选择负担。人找工作看招聘网站，也是先筛城市、筛岗位，再细看职位描述，而不是把全站所有职位一条条读完再决定投哪个。Agent选技能也是一样的逻辑，工程师要做的是建一个“招聘网站”，而不是直接做一本“岗位大全”。

所以后来我把技能系统改成了三层结构：技能库、技能索引、技能选择器。技能库存放全部技能的具体实现；技能索引保存每个技能的轻量元信息，包括技能名称、一句话摘要、适用场景关键词、调用频率统计；技能选择器负责根据当前用户请求和Agent的中间状态，从索引中快速过滤出候选技能，再通过排序选出最终备选列表。

3.2 用向量检索和关键词过滤做第一轮筛选

具体实现上，我推荐的做法是“漏斗式筛选”。第一层是硬性关键词过滤，比如用户请求里明显提到了“邮件”，那就把跟邮件无关的技能直接剔除；第二层是向量相似度召回，把用户请求和每个技能的摘要描述分别转成向量，算出相似度，取TopK；第三层再根据上下文做一次轻量的相关性排序。三层筛完，最后只把可能用到的5-8个技能写进模型上下文。

这里有一个经常被忽略的细节：筛选用的技能描述和最终展示给模型看的技能描述可以不完全一样。筛选用摘要，展示用完整描述，既能保证召回效率，又不丢失必要的信息。我见过一些项目在这个环节偷懒，用同一份长描述又做检索又做展示，向量检索时噪音太大，召回质量很差。

动态发现的收益也很明显：技能库从二十个扩大到了上百个之后，模型在单次任务里的判断准确率反而更高了，因为每次只需要在真正相关的几个技能里做选择，干扰项变少了。当然，动态发现也有代价，那就是需要额外维护索引、设计适合的召回策略，初次搭建的成本会比静态方案高一些。

3.3 技能冲突检测：取个名字很简单，但要让名字不打架却很难

技能多起来之后，另一个需要处理的问题是命名空间冲突。如果两个技能都叫“search”，A技能是搜数据库，B技能是搜网页，模型在调时只能靠描述去猜。我建议在设计阶段就用前缀来区分技能归属，比如“db_search”和“web_search”，一眼就能看清楚用途。同时，同义词技能之间最好通过描述里的使用场景来拉开区分度，比如一个搜索引擎的技能描述里明确写“适用场景：查询互联网公开信息”，另一个就写“适用场景：查询企业内部数据库记录”，这样模型在做向量匹配时就不会走错路。

4. 编排调度引擎的设计与实现

4.1 从单技能调用到多技能编排的思维转换

一个Agent如果只是做一个“调用技能→返回结果”的单轮操作，那其实不复杂，复杂的是多技能、多步骤的场景。比如让Agent完成一个“生成本季度销售报告”的任务，它可能需要先查询销售数据库，清洗数据，做统计分析，再生成图表，最后套用公司模板产出文档。这里的每一步都是一个独立技能，而真正的难点在于如何编排它们之间的顺序、传递中间数据、处理失败和重试。

在这个问题上，我尝试过两种路线。第一种是把流程完全写死在代码里，用工作流引擎定义节点和连线，Agent只能按固定路径执行。优点是稳定可控，缺点是不够灵活，稍微偏离预期场景就处理不了。第二种是完全让模型自由发挥，由它自己决定调用哪些技能、按什么顺序调用。优点是灵活，缺点是真的会失控，尤其是任务步骤比较多的时候，经常出现重复调用、遗漏关键步骤、中间结果丢失这些问题。

最后我采用的是折中方案：把编排动作分成“计划层”和“执行层”。执行层由引擎控制，负责按顺序调用技能并把结果写进共享状态；计划层由模型负责，根据用户目标和当前状态生成具体的技能调用序列，但计划生成后需要经过一些校验规则确认，发现明显不合理的地方会打回让模型重新生成。

4.2 几种实用的编排模式

在编排结构上，我个人常用下面几种模式，它们可以组合使用：

• 顺序执行：A完成后才能开始B，适合有明确先后依赖的场景。比如“先定位文档再编辑”。
• 并行执行：多个相互独立的步骤同时进行，可以显著提升执行效率。比如“同时收集三份不同的公开信息再汇总”。
• 条件分支：根据中间步骤的结果决定后续路径。比如“如果数据量超过阈值就走聚合方案，否则走明细展示”。
• 循环重试：某个技能执行失败时按规则重试，但要设定最大重试次数，避免死循环。
• 回退补偿：当连锁任务中某步彻底失败时，回滚之前已经完成的操作或做对冲处理。

比如在一个跨系统数据同步的场景里，我会先跑一个预检查技能确认两边数据的版本兼容性，再执行同步技能，同步完成后调用校验技能抽查数据一致性。如果校验技能发现不一致，触发补偿流程，把增量更新重放一遍。这个流程看起来简单，但直接用纯代码写死每一步会非常僵硬，用上面的编排模式组合实现，就灵活很多。

4.3 编排引擎如何避免“对话式跑题”

说到编排引擎的具体实现，我觉得最核心的机制是“状态机加约束提升”。状态机负责保证技能调用的顺序不被模型随意打乱，约束提升则是在模型生成下一步动作时，只给它看当前状态允许执行的那部分技能列表，其他技能不出现。

我举个具体的例子：在一个“会议纪要自动归档”的技能里，编排顺序是“解析会议录音→生成文字稿→提取行动项→写入文档库”。当Agent还在解析录音阶段时，引擎只会把“生成文字稿”和“提取行动项”这两个后续技能展示给模型，根本不给它展示“写入文档库”这类跟当前阶段无关的技能。这样做之后，模型的决策空间被收紧到了当前步骤真正需要的范围内，跑题的概率大大降低。

5. 上下文管理、状态传递与内存机制

5.1 状态管理不做好，技能编排就是空中楼阁

技能编排跑起来之后，紧接着要面对的就是状态管理。多步骤任务里，每个技能执行完毕都会产生输出，这些输出可能是下一步的输入，也可能是最终答案的一部分。如果状态管理混乱，常见的问题有两个：一是中间结果覆盖，A技能的产出被B技能的产出冲掉；二是上下文爆炸，每一步都把历史结果全部塞进模型提示词，几轮下来上下文就超限了。

我的做法是为Agent引入一个工作内存区，本质上是一个结构化的键值存储，专门用来保存技能执行过程中的中间产物。每次技能执行前，引擎把所需的输入从工作内存中取出来组装好；技能执行完，把输出写回内存并挂上对应的步骤编号。这样做带来的好处是：上下文里的信息只保留“当前步骤相关的部分”，历史中间结果全部放在内存区，需要时才取用。

比如在“定时更新客户周报”的场景里，Agent从邮件中提取客户反馈后，会先把客户反馈记到一个独立的键下面，等汇总数据技能跑完后再从内存里读取反馈内容，合并到周报模板里。两个技能之间不直接传参，而是都通过内存区中转，这样哪怕后续又要增加一个“情感分析”步骤，也只需要新增一个技能去读同一个内存键，完全不需要动之前的步骤代码。

5.2 运行时上下文只说该说的

还有一个经验是：提示词里的上下文要按需装配，不要有求必应。我看过不少项目，为了让“上下文更丰富”，把用户的历史聊天记录、桌面环境信息、十几个技能的全部文档一股脑儿都塞进去。这种堆积确实能解决一部分“模型不懂用户背景”的问题，但代价是决策噪音和Token消耗都直线上升。

我更推荐的做法是分层管理上下文。全局上下文放最基础的信息，比如用户身份、时间、当前任务目标；局部上下文放跟当前技能相关的信息；临时上下文用来装一次技能调用之间的过渡数据。三个层级按优先级覆盖，低层级的字段如果跟高层级冲突，以高层级为准。这样模型每次看到的上下文总量可能只有原来的三分之一，但信息密度反而更高了。

5.3 小心长任务执行过程中的“状态漂移”

长任务执行时还有一个很容易踩的坑，就是模型的“状态漂移”。比如一个任务有十步，模型在执行到第五步时，对前面四步已做操作记忆模糊，可能会重复执行某个步骤或者跳过某个步骤。为了应对这个，我习惯把“已完成的操作步骤”实时写入内存区，并且在每一步执行前明确提示模型当前进度。你可以把这个想象成施工工地上挂在墙上的进度表，每一个工序做完就打个勾，工人下一道工序开始前先看一眼进度表，而不是凭记忆判断做到哪了。

6. 可观测性建设与调试复盘方法

6.1 没有可观测性的Agent，出了问题只能干瞪眼

Agent应用跟传统程序最大的不同在于它的行为是动态生成的。传统程序出错时，看堆栈日志基本能定位；Agent出问题时，你面对的可能是一整段对话记录加N次工具调用，出错原因可能是模型理解偏了，可能是技能选择错了，也可能是编排顺序不对。如果没有一套可观测体系，排查问题完全靠运气。

我建议从以下几个维度来建设可观测性：

• 调用轨迹：记录每一次技能调用的时间、输入参数、输出结果、耗时；
• 决策过程：记录模型当时选择了哪些候选技能、最终选了哪个、筛选依据是什么；
• 状态变化：记录工作内存区的每一次写入和读取，方便复现中间状态；
• 成本统计：统计每个任务消耗的Token数、调用的技能数，用于优化开销。

这些数据不一定要实时展示，但必须完整落盘。我习惯的做法是“先全量记录，再按需筛选”，因为事后复盘你最需要的是完整的原始数据，而不是预先加工过的摘要。

6.2 调试时的经典手法：把一次任务完整回放

调试Agent技能编排时，最有用的一个方法是离线回放。把线上产生的一条完整任务轨迹保存下来，然后在本地用相同的模型、相同的技能库、相同的状态初始化条件重新跑一遍，逐步对比哪一步的行为和预期不一致。我经常拿“单元测试”来类比这个过程：传统的单测验证的是代码逻辑，这里的回放验证的是“模型加上技能系统”组合起来的整体行为。

做回放之后我养成的一个习惯是：每次新增一个技能或者调整编排规则，都会用历史任务集跑一遍回归验证，重点看两个指标——技能选择准确率有没有下降、任务完成率有没有变化。这个做法让我在重构技能库的过程中没有出现过大面积的隐性回退。

6.3 技能评估不只是看“完成率”

很多人习惯用“任务完成率”来评估Agent效果，但做完几个项目之后我发现，这个指标太粗了，根本发现不了问题在哪。我更推荐把评估拆细一点：

平时我会定期跑一批带人工标注的评测集，分别统计这几个维度的数据。任何一个维度出现明显下降，都能很快定位是技能描述出了问题、参数约束太松还是编排逻辑有缺陷。

7. 技能运行时的异常处理与容错对策

7.1 技能执行失败的几种典型场景

技能编排做得再精细，运行时也不可能完全不出错。根据我的观察，技能执行失败集中在以下几类场景：

• 外部服务超时或不可用
• 参数校验不通过，模型传了非法值
• 前置状态缺失，比如某个依赖键在内存区里不存在
• 大模型的输出没按照预期结构返回，导致技能解析失败
• 长时间运行的任务中途被中断，内存状态丢失

应对这些异常，我的核心原则是“分级处理”。超时类的异常，按配置重试，重试间隔递增；参数非法，先尝试让模型修正，而不是直接放弃；前置状态缺失，则检查任务是不是跳过了某一步，或者恢复历史状态重新执行；模型输出结构异常，则做一次结构修复再重试。

7.2 重试机制要设计成幂等的

做重试设计的时候，有一个很重要的原则是：要保证技能本身是幂等的。尤其在写操作、数据变更这类场景里，同一次操作重复执行，结果必须保持一致。我踩过最典型的坑是“发送通知”这个技能没有做幂等保护，重试一次之后就出现重复通知。

解决办法是每次调用技能时生成一个全局唯一的调用ID，技能内部通过这个ID做去重判断，如果发现已经处理过相同ID的请求就直接返回之前的结果。这个机制成本很低，但对系统的稳定性提升非常明显。

7.3 用补偿机制处理“做了一半”的任务

还有一类情况更棘手：编排任务执行到一半，某个步骤彻底失败了，并且无法重试。例如一个任务链是先扣预算、再生成服务凭证、最后发送确认通知，如果生成凭证成功但通知发送失败，就会出现“用户已经扣款但没收到确认”的中间状态。

这种情况下，我会在编排层配置一条补偿链路，规定哪些步骤需要有“逆向操作”或“补发操作”。还拿这个例子说，通知发送失败后，补偿机制会先尝试再次发送；如果重试也失败，就把失败等级升级，同时生成一条待人工处理的事项记录。整套逻辑走下来，虽然不能让每一步都百发百中，但至少每次失败都有明确的对应处理策略，不会再出现“任务失败但不知道该怎么办”的尴尬。

8. 常见问题与排查技巧实录

8.1 技能老是选不对，先别急着骂模型

技能选错，八成问题出在技能描述上。我这里有个快速诊断流程：

1. 把一个失败请求的输入和最终选技能的对话记录完整导出；
2. 人工模拟一遍，看在这个输入条件下，你希望Agent选哪个技能；
3. 对比一下模型最终选的技能，把它们描述都打印出来；
4. 看看两个描述之间的语义距离是不是太近了——如果太近，说明你要么合并它们，要么把差异写得更明显。

遇到过最典型的案例是“提交请假申请”和“查看请假余额”两个技能。从人的角度来说这两件事区别很明显，但模型的向量表征里它们的语义距离非常近，经常选混。后来我在两个描述里强行加了使用场景的区分：一个写“员工发起申请流程并需要审批人批复”，另一个写“只读查询，不发起任何流程”，选错现象立刻少了很多。

8.2 模型编造不存在的技能或参数怎么处理

模型编造参数的情况太常见了，比如把一个技能根本定义的字段给填进来，或者拼接出超过Schema约束的内容。应对这种问题，我一般做三层防护：

• 第一层，参数Schema校验，拦截掉所有不符合声明的调用；
• 第二层，当校验不通过时，把校验错误信息转成自然语言，送回给模型让它自己修正；
• 第三层，如果修正两次仍失败，就中断这个技能的调用，转人工重新描述需求。

因为模型在“看得到校验反馈但无法真正执行”的情况下，它会倾向于重新生成符合要求的参数，这本质上是一个自我纠错的过程。实测下来，经过两轮反馈修正，参数通过率能从70%提升到95%以上。

8.3 长对话场景下技能执行结果被遗忘

多轮对话里，用户前几轮让Agent做了一件事，后面又追问细节，结果Agent完全忘掉了前面技能的执行状态。这个问题的根源在于：多轮对话的上下文只保存了聊天文本，没有保存技能执行的真实结果。建议在工作内存区单独开一块“持久记忆区域”，把用户关心的关键执行结果，提炼成结构化摘要存下来。在后续对话中，如果用户的问题命中相关摘要，就可以直接从内存区取内容做回答，不需要重新执行一次技能。

8.4 一些效率优化上的细节补充

技能编排跑通之后，接下来值得优化的方向大概有三个：并行加载候选技能、压缩技能描述在提示词里的占用、以及把高频技能链做成“复合技能”。我试过把经常一起执行的“查询-统计-生成报表”三步流程封装成一个复合技能，虽然内部的三个动作还是分开执行，但对外暴露的接口变成了一步，模型的决策负担会明显减轻。这类优化，属于把整个系统从“能跑”推向“跑得顺”的关键一步。

另外，如果你准备在自己的项目里动手实践这套体系，我的建议是从小处入手，先定义五个核心技能，手动管理一个静态清单，跑通之后再加动态发现、编排引擎。一上来就想构建一个一百技能的动态体系，大概率会因为排查成本过高而半途放弃。先让整个链路跑起来，再逐步做复杂化，反而更符合真实项目迭代的节奏。