企业官网建设流程全解析

大模型跑通了，Agent却老在真实任务上翻车？问题多半不在模型脑力，而在你压根没给Agent建立一套像样的“技能体系”。最近在重构几个自动化场景时，我把“agent-skills”这个思路彻底捋了一遍，发现大部分人做Agent，其实是在拿 prompt 硬堆逻辑，而不是在构建技能。今天就把这套从技能拆解、元数据设计、编排到排错的经验完整盘出来。

1. 为什么Agent的实力上限，其实取决于“技能系统”而不是模型参数？

很多人在搭建Agent时有一个致命误区：以为只要换一个更强的基座模型，Agent的完成任务能力就会水涨船高。模型确实决定了推理的天花板，但在真实业务落地中，限制Agent表现得像“人工智障”的，恰恰是它手头有没有一套设计良好、可复用的“技能”。

1.1 把Agent想象成一位临聘员工

假设你请了一位高学历但没工作经验的实习生来帮你处理日常事务。他智商没问题，但你如果只跟他说“帮我搞定月度总结报告”，他大概率会一脸懵——要数据来源？要格式模板？要分析维度？要交付标准？而如果你提前给他一份《岗位SOP手册》，里面写清楚“步骤一：拉取CRM数据；步骤二：按模板填充；步骤三：调用图表库生成趋势图”，他就能稳稳地把活干完。

Agent也是同样的道理。基座模型给的是“智力”，而 agent-skills 给的是“工作经验手册”。一个Agent可以不知道具体业务数据，但它必须知道“在什么场景下、按什么顺序、使用什么工具、以什么标准完成一项任务”。这套东西，就是技能体系。

1.2 技能与提示词的本质区别

很多人说：“那我写个复杂点的 system prompt 不就行了？” 这就是最典型的弯路。

Prompt 像一张写满字的便签，它试图把所有逻辑放进一段上下文里。而技能（Skill）更像一个结构化封装的模块，它通常由这几个部分组成：

• 技能触发的条件描述（什么时候该用这个技能）
• 技能执行所需的输入参数（需要哪些外部信息）
• 技能调用工具的操作序列（先查什么、再算什么、最后做什么）
• 异常处理分支（某一步失败时怎么办）
• 成功标准的定义（怎么判断这个技能执行成功了）

这段差别在复杂任务里会放大得非常明显。Prompt方式下，模型每次执行都要从零理解任务；技能方式下，模型只需要“识别场景 → 加载技能 → 按步执行”。前者是临场发挥，后者是标准化作业。稳定性根本不在一个量级。

1.3 谁最需要这套技能设计方法

如果你正在做以下任意一类事情，这篇内容就是写给你的：

• 搭建企业内部知识问答或自动化流程助理，任务步骤固定且重复
• 开发类似“帮我写周报”“帮我整理会议纪要”“帮我分析数据”这类高频工具型Agent
• 做多Agent协作框架，需要把复杂任务拆解给不同的专业Agent
• 被Agent结果不稳定折磨，每次输出都像开盲盒

这套技能体系，能让你把“靠运气输出”变成“靠流程兜底”。

2. 技能系统设计：先拆解任务，再定义动作

技能系统不是一上来就写代码，而是先做“任务拆解”。我在实际项目中总结出一套比较成熟的设计步骤，每一步都有明确目的。

2.1 从高频业务场景倒推技能清单

最忌讳的做法是先画一个理想的技能树，然后往里填内容。正确做法是直接翻业务记录，把所有人工处理的高频任务捞出来。

我当时在某制造企业的数字化项目里，第一步就是拉取了客服部门近三个月的工单记录。结果发现，大约 40% 的工单都在重复回答类似“订单到哪一步了”“修改收货地址怎么操作”“发票多久能开”这类问题。每一类，就是一个候选技能。

筛选优先级参考三个维度：

1. 发生频率（一天几次还是一个月一次）
2. 标准化程度（是否能用明确步骤描述）
3. 可复用价值（做完这个技能能否复用到其他场景）

如果一个任务连人工处理时都没有固定流程，那暂时就别做成技能，强行做只会得到一堆脆弱的分支判断。

2.2 每个技能都有五要素设计模板

一个正经的 agent-skill 元数据，建议包含以下字段。这套模板我沿用至今，基本没大改过：

我强烈建议把 success_criteria 和 fallback_plan 单独拆出来，而不是揉在步骤描述里。原因很直接：模型在长步骤执行中会遗忘初始目标，显式的“成功标准”能给模型一个明确的终止信号，而“兜底方案”能防止模型在失败分支里反复兜圈子甚至开始编数据。

2.3 技能编排：复杂任务怎么组合多个技能

单技能解决原子问题，组合技能解决复杂业务。还是用订单场景举例：

用户问“帮我查一下我上个月买了什么，顺便算一下总共花了多少钱”。如果拆解成技能链：

1. order_history_query（获取用户历史订单列表）
2. order_amount_calculate（执行金额汇总）
3. response_formatter（按用户偏好组织回复结构）

这里最关键的是“技能间数据传递协议”。上一个技能输出的结构，直接决定下一个技能能否正确读取。我统一使用 JSON 作为技能间数据交换格式，每个技能的输出必须包含status（成功与否）、data（结构化结果）、message（自然语言摘要）三个字段。别小看这个约定，它能省掉后面 80% 的调试时间。

3. 核心细节拆解：描述怎么写、参数怎么校验、动作怎么编排

这一节是真正决定技能好用与否的地方。很多人的技能文件写得像天书，或者像流水账，模型根本没法正确触发。

3.1 技能描述是给模型看的“流量入口”

技能系统的第一步是让模型知道“当前用户问题该用哪个技能”。这个匹配过程通常靠 embedding 相似度，也会参考 description 的关键词。所以 description 的写法极其讲究。

用一个反例和一个正例来对比。反例写法：“用于处理用户订单状态相关的问题。” 正例写法：“当用户想要查询订单的当前状态、物流进度、预计送达时间，或者在订单长时间未更新时询问原因时，使用本技能。使用时需要用户提供订单号；若用户未提供，调用订单列表接口反查最近一笔订单。”

正例描述的核心优势有两个：

• 把触发场景枚举得更具体，减少模型误判
• 把参数缺失的处理策略直接写进描述，引导模型主动完成参数收集，而不是直接报错

还有一个小技巧：描述里可以写明“不要用于”的场景。比如“本技能不适用于退换货申请，退换货请调用 return_order_skill”。这种负向约束对模型纠偏效果极佳。

3.2 参数定义与运行时校验

很多Agent翻车，就是因为技能执行时参数不齐全，模型又不会主动追问。参数设计上要注意以下三类属性：

第一类是业务必要参数。比如查询订单必须要订单号，这类参数要标记为required。模型在进入技能执行流程前，应主动向用户追问缺失的必要参数，而不是拿一个空值跑下去。

第二类是可推断参数。比如用户没给订单号但给了手机号，技能内部要有“通过手机号反查订单”的逻辑。这类参数在触发阶段可以表现为可选，进入执行阶段后再通过内部动作补齐。

第三类是上下文参数。比如当前用户ID、当前租户ID、语言偏好等，一般从会话上下文中自动获取，不需要大模型额外理解。

运行时校验有个实用原则：凡是模型生成的参数，在高风险动作（比如扣款、删除、发送消息）执行前，必须返回给用户做二次确认。确认后生成一个短时有效的执行令牌（token），技能内部凭令牌完成后续动作。这个机制在不改动模型能力的前提下，硬生生把误操作率降了一个数量级。

3.3 动作序列的编排粒度

工具序列的设计是技能设计中最考验经验的部分。我总结出一个“三步法”来判断动作编排的粒度：

• 每一个动作必须对应一次外部工具调用或一次确定性计算
• 两个动作之间只传结构化数据，不传上下文废话
• 每一步动作都要考虑失败分支

举个例子，设计一个“生成周报”技能，工具序列可以拆成：

1. 调用工时系统接口获取当周任务记录
2. 调用文档数据库获取上周周报模板
3. 调用大模型按模板结构生成初稿
4. 调用评审规则引擎检查字数与格式合规性
5. 输出定稿并归档

注意第 4 步的规则引擎检查，这一步能把 LLM 输出的“幻觉”用确定性规则卡一道。哪怕只是简单的“必须包含本周数据亮点”“字数不得少于300字”“不能出现TODO占位符”，也能显著提升交付质量。技能设计里最容易被忽略的，就是“检查”这个动作，但恰恰是它决定了交付物是半成品还是成品。

3.4 上下文窗口与技能加载策略

当技能数量变多，不可能把所有技能描述一股脑塞进上下文。token 有限，塞多了反而干扰模型判断。主流方案是做一个检索层：预先对所有技能描述做 embedding，实时根据用户问题召回最相关的 Top-K 个技能。这个召回策略能保证在技能数量达到上百个时，触发准确率依然稳定。

另外，技能文件本身的详细内容不需要整体加载。详情内容只在技能确定被触发后才注入上下文。这个“两段式加载”（先匹配描述，再加载步骤）几乎成了Agent框架的标准做法，能省下大量上下文开销，同时提升长任务执行稳定性。

4. 实操过程：从零实现一个可用的订单查询技能

理论知识说完了，下面完整走一遍实操。以一个最简单的“订单物流查询”技能为例，从定义元数据，到注册到执行引擎，最后测试通过。这个过程是我在实际项目里反复跑的路径。

4.1 第一步：定义技能元数据文件

我习惯用 YAML 格式写技能元数据。相比 JSON，YAML 支持注释，可读性高得多，非开发角色的运营也能维护。

以订单查询为例，一个精简版元数据是这个样子：

name: order_status_query description: > 当用户查询订单状态、物流进度、预计送达时间时使用。 若用户未提供订单号，主动询问或调用 order_list_recent 反查最近一笔订单。 不适用于退货退款，退货请调用 return_request_skill。 version: 1.2.0 author: agent-platform-team params: order_id: type: string required: false description: 订单号，格式如 ORD20250120001 user_id: type: string required: true description: 用户唯一标识 tools: - order_query_api - order_list_recent - logistics_tracking_api steps: - action: resolve_order_id description: 若order_id为空，调用order_list_recent获取最近一笔订单 - action: call_order_query description: 调用order_query_api获取订单基础状态 - action: call_logistics description: 调用logistics_tracking_api获取物流轨迹 - action: format_response description: 按统一模板组织标准回复 success_criteria: - 返回内容包含订单状态、最新物流节点、预计送达时间 - 若订单已签收，额外返回签收时间 fallback_plan: - 未找到订单：返回错误话术并附最近三笔订单供选择 - 物流接口超时：降级返回订单状态，并说明物流信息暂不可用

这套元数据已经可以直接进入执行引擎运行了。字段不算多，但覆盖了触发、执行、检验、回退四个关键阶段。

4.2 第二步：注册技能到执行引擎

注册过程就是把元数据文件丢给技能仓库，并同步触发模型的 embedding 服务，让该技能的描述进入检索库。这个环节需要注意一个细节：每改一次元数据，必须同步更新 embedding 向量，否则模型匹配到的还是旧的描述内容，明明是查物流，结果命中的却是查发票的接口。

同步之后，还需要在测试环境跑一轮技能触发准确率测试。我一般准备一个模拟问题集，至少涵盖三种情况：

• 正常触发：用户问题包含技能关键词
• 模糊触发：用户问题绕着弯说，但语义应该命中
• 负向测试：用户问题不该触发，看模型是否会误触发

实测中，负向测试是最容易暴露描述问题的环节。如果你的描述里缺少“不适用于”约束，技能误触发的概率会显著增加。

4.3 第三步：执行链路数据流追踪

执行引擎跑起来之后，最该盯的就是技能内部的数据流。技能步骤 book 里每一步的输入输出是什么，中途哪一步用了模型生成的结果，哪一步是纯代码调用，这些都要能追踪。

以我们这个技能为例，完整的执行链路是：

用户提问 ↓ Agent 识别意图，命中 order_status_query ↓ 参数解析：user_id 从上下文拿，order_id 缺失 ↓ 步骤 resolve_order_id：调用 order_list_recent，拿到最近订单的 order_id ↓ 步骤 call_order_query：调用订单查询 API，返回订单状态、商品概要、收件地址 ↓ 步骤 call_logistics：调用物流 API，返回轨迹节点列表 ↓ 步骤 format_response：组装最终话术 ↓ 返回给用户

每一跳结束后，我都建议在日志里打一个结构化的中间结果，包括当前步骤名、输入参数、输出摘要、耗时。排查问题时就靠这个数据流日志，往前往后都能快速定位是哪一步出了偏差，而不是瞎猜。

4.4 第四步：成功标准与回归测试

技能上线前，必须有一个自动化的回归测试集。每次改动技能元数据，都要把整个回归测试集跑一遍。测试样例至少应该覆盖用户表达方式上的变体，比如“我的快递到哪了”和“订单号ORD20250120001现在什么状态”，这两句话语义相同但结构差异很大，模型能不能都稳定触发，就是测试的关键输出。

我在实际项目中维护了一个约 200 条的标准回归集，覆盖大约 15 个核心技能。每次有更新，跑完回归大概需要十几分钟。这十几分钟的投入，换回来的是线上问题数量断崖式下降。

5. 踩坑实录：技能执行最常见的高危问题与排查对策

最后一部分，整理那些真实线上环境才会遇到的问题。我在多个Agent项目的建设和运维中，几乎每个坑都踩过一遍，提前看到就等于提前避雷。

5.1 技能明明设计好了，模型就是不触发

这是出现频率最高的问题。排查顺序如下：

• 先查检索召回：把用户问题拿去跟技能描述做相似度匹配，看目标技能有没有进入 Top-K 候选。如果没进去，说明描述写得和用户实际说法差距太大，需要补充更多触发说法，尤其是口语化的。比如“我的快递到哪了”这种自然表达，远程比“查询订单物流状态”更容易被真实用户说出来。
• 再查排序策略：如果目标技能进了候选但仍没触发，可能是排序阶段被其他技能挤掉了。这时需要检查是不是某个技能的 description 写得过于宽泛，成了“万能吸铁石”，把大量相关或无关的问题都吸走了。
• 最后查上下文注入：模型选择技能时，如果上下文里塞了过多无关任务记录或历史对话，可能干扰意图判断。把上下文精简到只保留最近两轮对话，通常有奇效。

5.2 参数缺失导致技能执行到一半就卡死

这类问题多发生在技能设计时没想清楚“参数缺失怎么处理”。排查时看执行日志，确认卡点在哪一步。如果卡在参数解析之后、第一步工具调用之前，基本就是缺参没有兜底。解决方式有两个方向：

• 一种是把该参数标记为必填，并在技能 description 里写明“参数缺失时必须先向用户追问”，让模型主动生成澄清式回复。
• 另一种是增加一个前置动作，负责通过其他接口反推该参数（就是我们前面用的 order_list_recent 思路）。

5.3 模型执行步骤时跳过关键校验

不少技能在测试时一切正常，一上生产就频繁出现“跳过校验直接输出结果”的情况。举个例子，技能要求调取 A 接口拿到数据后再计算，模型却直接根据对话历史里的旧数据生成了结论。

这场景我遇到太多次了。根源在于步骤描述写得过于宽松，让模型有了“自由发挥”的空间。对策是加强步骤定义中的约束性，明确加上“禁止使用上下文中的历史数据，必须使用本步骤接口返回的实时数据”。说白了，这类问题不是模型能力不够，而是你的技能边界没有表达清楚。

5.4 工具调用结果格式不符合预期

外部接口返回的 JSON 结构和技能步骤里预期的不一致，导致后续动作解析失败。这类问题的隐蔽性很高，因为大多数时候接口返回是正常的，只有边界情况下（比如订单被取消、物流单未生成）才会出现结构变异。

对策是在工具调用外再包一个“适配层”，把外部返回统一清洗成技能内部约定的数据协议。哪怕外部接口变更了字段名，适配层改一小处，技能主体完全不受影响。这个抽象隔离层在长期维护中带来的收益远超最初的编写成本。

5.5 长流程任务执行到一半上下文溢出

技能步骤多、工具调用结果又臃肿时，上下文很容易爆掉。很多平台遇到这个问题会直接报错，有的模型则开始丢弃早期信息，导致最终结果缺少关键上下文。

我的做法是引入“记忆蒸馏”机制：每完成一个步骤，只保留该步骤的结构化摘要，丢弃原始工具返回的完整报文。这个操作能将上下文占用降到原来的五分之一左右，同时保证必要信息不丢失。凡是涉及长链路任务，我建议都采用这个策略，越早引入越省心。

6. 技能维护的正确姿势：版本管理与持续迭代

最后一个常见误区是技能做完就一劳永逸了。实际线上业务会不断变化，技能必须跟着迭代。建议至少从三个维度持续维护。

第一是描述与触发词迭代。每个月拉一次用户侧的失败会话，把那些没有触发成功的问题归拢起来，汇总高频表达，补充到技能 description 中。做这件事以后，我的技能触发率从 78% 提升到了 96% 左右。

第二是步骤动作演进。关注执行日志里那些报错最多和耗时最长的步骤。比如某个接口经常超时，就可以在技能里加一个“超时切换备用数据源”的分支。这类优化通常优先作用于线上痛点，收益是即时可见的。

第三是成功标准的收紧。初期定义的成功标准可以宽松一些，保证能跑通；等到跑稳定之后，逐步收紧标准，让输出质量持续往上走。比如早期允许格式基本符合就算过，后期可以增加“必须包含更新时间字段，必须引用最新的数据来源”这类严格约束。

还有一点务必注意：任何技能变更都要核对该技能被哪些上层流程依赖。改了一个步骤的数据协议，整个引用链可能都要同步更新。版本管理建议直接用代码仓库的思路来管，每次变更走提交、评审、发布流程，而不是直接在线上配置里热改。

我在实际项目中体会到，技能体系设计得好不好，直接决定了Agent项目能在“Demo可用”和“业务可用”之间走多远。很多项目卡在 85 分上不去，往往不是模型不够强，而是技能该拆的没拆干净，该定义的边界没有定义清楚。

另外分享一个有价值的细节：遇到过多个技能执行结果相互矛盾的情况时，可以在技能返回结构中增加一个confidence字段。凡是置信度低于阈值的输出，让上层协调Agent自动发起二次确认，而不是直接硬着头皮下发。这个机制极大程度减少了后续的纠错成本，尤其是在面向外部客户自动回复的场景中，效果尤其明显。

建立一套适合自己的技能体系，初期肯定会有些枯燥，但一旦形成规范，后续新增任何技能都会非常顺手。少走弯路的最好方式，就是把前面这些坑一次性避过去。