企业官网建设流程全解析

做过一段时间智能体（Agent）项目的人，多少都会遇到同一个尴尬时刻：模型能力明明够用，Prompt也调了不少，但一接到真实任务，整个系统就变得像一盘散沙。工具调用串不起来，流程稍微长一点就出错，调试的时候更是两眼一抹黑。我后来把大量精力从“调Prompt”挪到“搭技能体系”上，才发现问题大多出在“技能”（skills）这一层——也就是Agent到底能做什么、是怎么组织起来的。所以今天就想拿“agent-skills”这个话题，把我自己从规划到落地的一套做法摊开讲讲，包括技能怎么设计、怎么编排、怎么注册、怎么观测，希望对正在做Agent工程化的朋友有参考价值，也欢迎拍砖交流。

先给个定位：这篇文章聊的是“能给Agent用的技能工程化”，不是某个具体框架的教程，更偏底层方法和实践思路。适合三种人看——刚把Agent原型跑通、准备往工程化方向推的技术人；正在为“Agent经常用错工具”发愁的游戏/工具类产品负责人；还有单纯对智能体内部运转方式好奇、想找个切入点入门的同学。我会尽量用通俗的类比把关键原理讲清楚，同时保留可以直接复用的实操细节。

1. 先别急着写代码：技能层的本质与设计思路

很多团队上手做Agent，第一反应就是把所有功能和Prompt揉在一起，让模型“看着办”。前期确实快，但做到一定复杂度就会碰壁：同一个能力在不同场景里表现不稳定，你想单独优化某个环节又无从下手，因为所有逻辑都耦合在几大段Prompt里。把“技能层”独立出来，本质上就是为了解决这种无序膨胀的问题。

1.1 技能到底是什么：不只是“一个接口”而已

我第一次带项目时踩过一个坑：把技能想得太简单，以为封装几个API就算完事。后来发现，技能应该是一个完整的能力单元，至少包含三样东西：

• 稳定描述：一段给大模型看的说明书，说明技能在什么场景下用、什么时候不能用、有什么限制。这里的措辞直接影响模型是否选对工具。
• 结构化接口：输入、输出的类型定义和约束。不是“传两个参数进去”就够的，还要考虑超时、重试、错误码等语义。
• 评估标准：怎么判定这次调用算成功或失败。没有评估，就谈不上迭代优化。

这三样缺一个，技能就是“半个”，要么模型不会用，要么用了也没法测好不好。

你可能会问，为什么不能像传统软件开发那样，只留“接口文档”？因为传统调用方是人，能理解隐含语义；而Agent的调用方是模型，它对描述文字的敏感度远超对参数类型的敏感度。同样一个“查询天气”的接口，你写“输入城市名，返回天气数据”，模型可能风和日丽也会调用；但你写“获取空气质量指数（AQI），供健康建议模块使用”，模型就会更谨慎地判断用户是不是真的在关心健康维度。技能描述本身就是一种“面向模型的界面设计”。

1.2 技能、工具、工作流的边界在哪里

很多概念刚接触时会混在一起，我也见过同行把技能、工具、工作流当成同义词。根据我自己的实践，我会这样切分：

• 工具（Tool）：最底层的能力原子，比如“调一个API”“查一次数据库”“发一条通知”。它不问场景，只负责执行。
• 技能（Skill）：基于工具的封装，补充了适用场景、限制条件、预期效果和失败处理。技能是可被模型识别和选择的最小逻辑单元。
• 工作流（Workflow）：多个技能按固定或动态顺序的组合，用于完成更复杂的任务。工作流本身也可以作为更大的“技能”被复用。

用一个生活化的例子：刀、砧板、菜谱是“工具”，会做“切丝”“焯水”“大火爆炒”是“技能”，而“做一道鱼香肉丝”是“工作流”。模型不需要自己研究怎么握刀，它只需要决定“现在该调用‘焯水’技能”，然后技能内部去操作具体工具就好。

有了这一层拆分，后续的编排、调试、复用才谈得上“模块化”。否则你今天写的流程，明天换个领域根本搬不过去。

2. 技能的一次完整生命周期：从定义到下线

一个技能从无到有、再到退役，跟人的职业发展差不多，要经历“岗位描述—培训考核—上岗履职—退役复盘”几个阶段。这里我会把每一步的动作和为什么这么做的原因都讲清楚。按我们团队的约定，一个好的技能上线前要走过5个关卡：设计、实现、测试、评估、注册。缺一道都不行。

2.1 技能的接口设计：好看的边界是成功的一半

设计技能接口时，我最看重一点：输入要让模型“容易给对”，输出要让上层“容易判断”。模型不像人，它不会看到“所在城市”就自动补一个默认值，如果你不给默认，它可能凭空编一个城市名出来。所以接口设计有几个朴素的规矩：

• 参数能省则省：能自动推断的就不让模型填。比如从用户IP或上下文可以推断地理位置，就不该把地址设为必填参数，减少模型“胡说”的机会。
• 必填参数给枚举和示例：如果参数值是个有限集，把合法值列出来；如果是自由文本，给一个典型示例。模型在Few-shot下对示例的遵从度远高于纯描述。
• 输出尽量结构化：哪怕是返回一段自然语言，也建议附上一个带状态码的结构体。因为上层不管是人看还是模型继续处理，状态码都是最直接的判断依据。
• 明确超时和幂等语义：技能里如果涉及外部服务，一定要定义超时后返回什么；能设计成幂等的操作尽量幂等，否则重试会产生脏数据。

这些规矩听着琐碎，但它们决定了Agent在“边界情况”下是优雅降级还是胡乱猜测。就拿超时来说，很多线上事故的根因不是模型笨，而是技能自身没有设定好“失败阈值”，导致Agent在等待中反复重试，白白耗尽上下文窗口。

2.2 注册与描述：这一步决定模型“会不会用”

技能写好了，还只是完成一半，另一半在于“让模型知道它存在、知道什么时候该用”。我们团队内部把注册描述当成一种“文案工程”来对待。基本写法有几点心得：

• 开头写明触发条件，比如“当用户需要修改收货地址时使用”，这比长篇大论介绍功能更直接。
• 写明不适用场景，防止误调用。例如“仅用于已登录用户；游客查询请先引导登录”，这能显著降低误用率。
• 描述中不要写具体数据，比如“统计近7天数据”这种话应该放到参数说明里，而不是技能描述里，否则模型可能为了满足描述而忽略用户的不同意图。
• 做一组排列测试：把不同版本的描述给模型看，让它做选择题来验证理解是否正确。这比主观感觉“这版写得不错”靠谱多了。

注册完之后，还要定期看调用日志。如果一个技能长期没被调用，大概率不是没用，而是描述写得让模型“看不懂”。我就碰到过一个“导出报表”的技能，功能完全正常，但模型从来不用，改了两版描述才被高频激活。所以“注册”不是终点，得持续用数据反馈来修正描述。

2.3 质量关卡怎么设：评测集不是摆设

我以前也觉得评测很麻烦，总想“先跑起来再说”。但后来发现，没有评测集，技能迭代基本靠玄学：你改了一版Prompt，感觉好像好了一点，但又说不清好在哪，回归测试更是无从谈起。现在我们的做法很简单——每个核心技能都配一组“验收用例”，数量不多，但覆盖典型场景和边界场景。

评测集分三层：

• 静态层：检查技能结构，比如参数是否都有类型声明、有没有默认值、描述里有没有禁用词。
• 案例层：运行20到50组人工标注的输入，看调用成功率、参数正确率、结果可用率。
• 场景层：把技能放进完整的Agent流程里端到端跑一遍，观察会不会出现技能之间的冲突或上下文污染。

每当要改技能，先把三层评测跑一遍，绿了才允许上。这个习惯帮我们在一次“给全部技能统一升级参数格式”的工程中，提前抓出了十多个影响线上场景的隐藏问题。没有评测集，这些可能就线上炸了才被发现。

3. 编排与组合：多技能协同正确工作的关键

单个技能做得再漂亮，最终还是要放进流程里用。Agent实际干活时，往往需要若干个技能配合，比如先查询订单状态，再根据状态决定是否创建售后单、是否通知仓库。技能怎么编排，直接决定了系统是“简单、可解释”的胶水逻辑，还是“不可预测”的暗黑森林。

3.1 三类编排模式：顺序、并行、分支

我习惯把编排归纳成三种基础模式，复杂流程都是它们的组合：

• 顺序模式：A完成后才能做B，强调的是依赖关系。比如“先扣库存，再生成订单”，顺序反了会出大问题。
• 并行模式：多个技能互不依赖，可同时执行，追求的是效率。比如同时查询天气和路况，合并结果后统一回复用户。
• 分支模式：根据某次输出决定下一跳，是动态决策的体现。比如“查询余额，如果余额不足就走充值引导，否则直接下单”。

针对顺序依赖，我会在技能定义里增加“前置条件”和“后置条件”。比如“创建工单”技能的前置是“已完成用户身份核验”，模型在编排时会优先检查这些前置，而不是凭感觉乱来。针对并行，我会在流程层限制并行数量，避免资源争抢，尤其是当多个技能都依赖同一个限流API的时候。分支则是所有Prompt里最像“逻辑代码”的部分，需要反复打磨判断条件的准确性。

3.2 一次典型的任务分解：从用户请求到调用链

拿我们做过的一个“订单助理”来说。用户说“我上周买的那个鼠标垫什么时候送到”，这句话看着简单，背后至少涉及四个技能：用户意图识别（这是一个查询物流的请求）、获取订单信息（先找到对应订单）、获取物流轨迹（再查具体物流状态）、生成友好回答（把轨迹数据转成口语化的话术返回给用户）。在工程实现上，这四个技能就是一条顺序链，但中间有两个分支点：订单存在与否、物流轨迹是否获取成功。

真正有价值的设计是“兜底”和“中断”也被当成技能来编排。我们规定每个流程都必须有一个“无法处理”的路由，例如查不到订单，就直接调用“转人工”技能，而不是让模型在上下文里硬编一个客服电话。这样用户体验会稳定很多。你仔细想想，很多Agent“翻车”，不是主流程有问题，而是异常分支没人管。

3.3 编排是固定写死还是靠模型自己“想”

这是团队里经常争论的话题。我的倾向是：能写死的尽量写死，不能写死的才留给模型。固定工作流的好处是稳定、可观测、容易排查；模型自由发挥的好处是灵活、能应对新场景。两者不矛盾，可以叠起来用——主链路固定，次级分支路由交给模型，同时限定模型只能在“技能库里选”，不能自己发明工具。

这就像开自动挡的车：挡位逻辑是写死的，但去哪里是驾驶员（模型）决定。如果让驾驶员每次开车都重新发明一遍换挡逻辑，那基本开不出小区。Agent的编排层也一样，先给稳定骨架，再给有限发挥空间。

4. 实战剖析：做一个“客服质检Agent”的技能表

前面讲了一堆方法论，来个具体例子大家感受会比较深。我们曾经要在客服系统里加一个“质检Agent”，目标是自动检查客服对话记录，判断接待质量是否合规。刚开始团队想把所有质检规则都写进一个Prompt，结果效果一塌糊涂，规则一多模型就“顾此失彼”。后来按要求拆技能，效果立刻不一样。

4.1 拆解质检需求，变成若干技能

客服质检大类下有好多子任务：检查开头是否有标准问候语、检查是否询问了用户联系方式、检查是否按时回复、检查是否出现违禁词等等。我们把这些都拆成独立技能：

• greet_check（问候语检测）
• contact_check（联系方式收集检测）
• response_time_check（响应时长检测）
• banned_word_check（违禁词检测）
• emotion_check（情绪安抚检测）

每个技能接收对话片段，返回结构化结果：是否合规、违规类型、证据文本片段。主流程是顺序执行这5个技能，最后汇总成一份质检报告。这里巧妙的地方在于，每个技能都很简单，单独拿出来都能跑得很准，合并起来覆盖了完整的质检需求，而且任何一个技能出问题，可以只改那一个，不影响其它。

4.2 技能描述里怎么写“判定规则”

有了技能清单，还得让模型正确使用。我们的技能描述类似这样：

技能名称：greet_check 功能：检查客服对话首句是否为标准问候语。 适用场景：会话的第一条客户消息之后，客服的第一条回复。 判定标准：必须包含“您好”或“你好”，否则标记违规。 输出：JSON，含字段 status（pass/fail）和 evidence（违规原句）。

一个关键细节：判定标准写得越客观越好。如果写“问候语要热情友好”，模型就很容易自由裁量，结果飘忽不定。改成“必须包含特定关键词”，模型就会稳定很多。这个设计原则在质检类技能上特别重要，因为质检讲究“可复核”。

4.3 出问题怎么调：从误报到定位的排查故事

这个Agent上线后遇到过一个经典问题：频繁把客服的“你好亲”判为合规，但“您好，很高兴为您服务”反而有时被判定为不合规。我们第一步是看调用日志，发现模型在“happy”这个关键词上打了个问号，怀疑“高兴”算不算标准问候语。于是调整技能描述，把“您好、你好、您好亲”等词直接列成白名单，并明确“不要做语义泛化”。改完后误报率立刻下降了四成。

这类问题不在模型能力，而在于技能描述里的规则不够“硬”。让模型做判断题时，与其给它模糊的指南，不如给它一张明确的“正负样本表”。这也是我建议每个技能带一组“示例输入”的原因。

5. 技能调试的硬核手段：全链路观测与问题定位

技能多了以后，最怕的不是“某个技能不好用”，而是“你不知道它为什么不好用”。这时候就需要从观测入手，建立一套让问题自然现形的机制。我经常跟团队说：“无法观测的技能就是定时炸弹。”

5.1 最小观测埋点：日志里至少要有这几项

我给技能执行链路做的统一埋点，至少要包含以下字段：

• 技能名、技能版本号、调用来源（哪个流程/哪个模型路由触发）
• 输入参数的JSON快照
• 输出结果的JSON快照
• 执行耗时、调用次数、重试次数
• 错误码或异常信息

有了这些字段，才能回答“这个技能最近用得怎么样”“今天为什么突然失败了”“影响范围有多大”之类的问题。我们团队会用看板把各技能的成功率、调用量、平均耗时画出来，每周巡检一次。有一次巡检发现“账单查询”技能调用量暴增，但成功率骤降，一查日志才发现是上游改了接口字段名，技能里的参数名没跟上。如果没有埋点，这种问题很可能要等用户投诉了才知道。

5.2 查询调用链与回放：像修复Bug一样修复“模型行为”

定位问题时，我几乎都会依赖“回放”——把当时输入到模型的完整上下文、选中的技能、输出的原始内容都拉出来，逐步排查。这跟排查传统软件Bug的思维一致，区别在于我们还要考虑“模型本身可能在哪个环节产生了幻觉”或“上下文哪里的信息误导了模型”。

我常用的一种排查顺序是：

1. 看输入是否被正确抽取：用户原话和结构化参数之间是否信息丢失。
2. 看技能选择是否合理：模型为什么选了这个技能而不是另一个，是描述不清还是上下文干扰。
3. 看技能执行本身是否失败：外部依赖是否正常、超时设置是否合理。
4. 看结果渲染是否失真：技能输出到“最终答案”这一步，模型是否乱改事实。

这四步走下来，大多数问题都能被定位到具体环节。许多Agent事故最后都落在第一步和第二步，也就是“参数抽取失误”和“技能选择失误”，真正外部接口挂掉的情况反而不多。

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

整理了最近半年在Agent技能工程中遇到最多的8个问题，做成速查表，方便大家直接对照排查。

这只是常见清单，实际遇见的奇技淫巧更多。有一个经验值得分享：很多“模型不听话”的问题，最后都是“技能描述写得太像人话，不像机器指令”。大模型不是不懂，而是你的描述里有太多可自由解释的空间。把话说死、把规则量化，通常是最快的解法。

7. 让技能库活下来：长期维护的核心心得

技能库不是做完一次就一劳永逸的静态资产，它像代码库一样需要持续维护和演进。我们团队维护技能库一年，总结下来有三个习惯最值钱：版本管理、变更评审和定期复盘。

版本管理是老生常谈，但真正执行得好的人不多。每个技能都独立版本，尤其是改描述、改参数、改判定标准时，一定保留历史版本日志。这样一旦新版本有问题，可以秒级回滚，不会牵连其它技能。

变更评审则是“人肉质检”环节。哪怕只是加一句话，也要过一遍“会不会导致模型在某些边缘场景误用”。评审会通常很短，因为大家已经把技能描述当重要资产对待，一眼就能看出哪里容易产生歧义。

至于定期复盘，我们固定每月做一次“技能体检”，从调用量、成功率、故障次数三个维度给技能排名，把排名垫底的技能找出来升级或下线。这个习惯听起来简单，但坚持下来，技能库会越来越精简、越来越顺手。有一次体检发现一个“查询物流”技能和“查询订单”技能有七成调用重叠，干脆合并成一个，整体准确率反而提升了。

维护技能库还有一个心态上的建议：把它当成养花园，而不是盖大楼。盖大楼是一锤子买卖，养花园则要不断修剪、浇水、除虫。技能库本身就是活的，它会随着业务、数据、模型能力的更新而生长。愿意持续打理它的人，最后都会发现Agent的稳定性肉眼可见地提升。