企业官网建设流程全解析

做智能体项目这段时间，我最大的感受就是：模型越来越聪明，但真正跑起来的智能体，卡点往往不在模型，而在模型周围的“手脚”不够利索。prompt里塞满函数定义、代码里堆满if-else调用逻辑，换一个场景就改一版，接入一个新工具就要动一遍主流程，这套做法撑不过十个功能点。于是我开始把“技能”当成智能体的一等公民来设计，做了这个名为“agent-skills”的实验项目。简单说，它就是一套让Agent能力可注册、可检索、可复用、可评估的机制：管好每个技能的输入输出、执行链路、校验规则和回归测试，模型负责“想”，技能仓库负责“做”，两者边界清晰，系统才不容易烂掉。这篇笔记适合正在做Agent类应用、被工具调用和prompt维护搞到头大的开发者，内容偏实战，我把设计思路、核心抽象和踩过的坑都摊开来讲。

1. 为什么智能体不能只有大脑：技能体系解决的真实痛点

1.1 “模型+一堆函数”的理想与残酷现实

很多人第一次搭智能体的时候，脑子里都是同一幅画面：大模型负责理解意图、拆解任务，然后调用我准备好的函数，世界就自动运转了。第一版确实能跑通，做个天气查询、做个小工具调用，效果都不错。但当你开始接入数据库、第三方API、内部系统、文档库之后，画面就开始失控。

失控的表现大体有三种。第一种叫prompt膨胀，每次加一个工具，就往系统提示词里塞一长段JSON Schema或函数说明，塞到一定量级，模型开始“选择性失明”，后面的定义经常被忽略，或者干脆编造不存在的函数名。第二种叫逻辑血肉化，工具的调用条件、参数转换、结果后处理全部散落在业务代码里，一个技能逻辑被引用三次，就得写三份不同的胶水代码，后面改一个参数名，全局搜着改。第三种叫无法评估，也就是你根本说不出当前智能体哪些能力是可靠的，哪些是碰运气的，出了问题只能靠肉眼翻日志。

我自己是从第三种开始崩溃的。某次测试智能体做数据分析，同样的提问跑十次，五次调用对了数据源，三次参数拼错，两次干脆自己编了结果。模型的提示词写得再漂亮也解决不了这个问题，因为问题不在推理，而在“技能边界”没有被明确约束。

1.2 agent-skills的定位：给智能体的手脚装上标准插座

我当时的想法很简单：能不能像插件化开发一样，把每个能力封装成独立、自描述的单元？这个单元内部再复杂都没关系，对外只暴露一个干净的契约，而智能体的调度层也只和契约打交道，不关心具体实现。

agent-skills这个名字，项目里也就是这么定义的。它不是一个“工具库”，也不是一套函数集合，而是一套技能治理的框架。重点在治理这两个字：技能怎么声明、怎么检验、怎么注册、怎么被检索调用、怎么评估质量，全程可追溯。

类比一下就是：家里的电器多了，你不会把电线到处乱接，而是统一用插座来连接，然后通过空开来管理回路。每个技能就是一个电器，有额定功率、有插头标准、有使用说明书；智能体是电网调度员，它不知道电器内部怎么工作，只要按规范接上，就知道能获得什么服务。这套机制最终解决的是让能力可以被当做数据来管理：技能可以列表、可以检索、可以打分、可以下架，而不是散落在代码仓库里的孤岛。

2. 技能的核心解剖：一个技能到底包含了什么

2.1 五件套结构：从声明到回归的完整闭环

在agent-skills里，一个技能不是一个Python函数或一个API封装，而是一个包含五类内容的完整实体。我最初的设计参考了OpenAPI规范，但去掉了那些为了兼容REST而存在的东西，全部围绕“模型调用”这个场景重新定制。结构展开如下：

• meta信息：技能名称、唯一标识、版本号、领域标签、作者、描述，用于管理和检索
• 意图声明：一个偏自然语言的说明，描述“这个技能在什么情况下该被使用”，是检索系统的核心索引
• 参数契约：以JSON Schema形式声明的输入规范，严格控制模型可以填哪些参数、参数类型、必填性和约束条件
• 执行链路：实际执行逻辑，可以是同步函数、异步任务、API调用、也可以是一段工作流脚本
• 回归测试集：一组输入输出的对照样例，定期自动运行，判断技能是否仍然正常工作

这五个部分缺一不可。我见过很多团队只做前三个，执行逻辑能跑、参数规范也有，但技能就是越用越不准。原因很简单：没有回归测试，你就不知道一次prompt优化或一次底层API升级，到底让多少个技能悄悄失效了。

2.2 参数契约为什么是灵魂

我愿把参数契约称为整个技能系统的灵魂。没有契约的时候一切靠“模型自觉”，有契约之后一切靠“机制兜底”。一个典型的技能声明长这样：

skill_id: user_orders_query version: 2.1.0 name: 用户订单查询 domain: [customer_service, e_commerce] description: 根据用户ID和可选的时间范围，查询订单列表及其状态 intent: 当用户要求查询自己的订单、历史购买记录、最近交易列表时使用 parameters: type: object properties: user_id: type: string description: 用户唯一标识 start_time: type: string format: date-time description: 起止时间，ISO8601格式 end_time: type: string format: date-time description: 结束时间，ISO8601格式 required: [user_id] executor: type: http endpoint: https://internal.api.example.com/v2/user_orders security: scopes: [user_profile:read] tests: - input: {"user_id": "U123456"} expected_schema: order_list - input: {"user_id": "U123456", "start_time": "2024-01-01T00:00:00Z"} expected_action: filter_by_time

注意到我特意把intent和description分开写。description是给人看的功能介绍，intent是给检索系统用的匹配条件。后面会细讲检索的具体做法，这里先记住一个原则：技能暴露给模型的表面越简洁越好，复杂逻辑全部藏到契约和执行层背后。

2.3 执行链路的封装修饰

执行链路是技能真正干活的部分，但直接裸奔是绝对不行的。我在执行链路外至少包了三层装饰逻辑。

第一层是参数整形。模型产出的参数经常有格式问题，比如时间戳写成各种奇怪的格式，数字被传到字符串字段里。参数整形负责做宽容模式转换，转不了的才拒绝。这里有个分寸问题：太宽容会让脏数据流入下层系统，太严格会让技能频繁失败。我采取的策略是“参数分层处理”，字符串做map映射，枚举值做同义替换，时间统一parser，再不行就拒绝并返回错误信息。

第二层是结果标准化。不同后端返回的数据结构千差万别，有的包在data字段里，有的直接平铺，有的是error对象。执行链路必须把这些差异统一成内部标准结构，这样上层智能体看到的永远是同一种形状的结果。

第三层是超时与重试策略。每次执行都带超时上限，重试只对幂等操作开放，非幂等操作宁可失败返错也不自动重试。这部分细节在第五节坑位总结里我会细说，先按下不表。

3. 三层技能架构：原子技能、复合技能与编排规则的演进

3.1 原子技能：一个动作做一件事

原子技能是体系里最小的能力单元，一个技能只做一件事，且这件事通常无法在不改变业务含义的前提下再拆小。典型的原子技能包括：按ID查用户、创建工单、发送一条消息、计算两个日期间隔。

原子技能的设计原则和数据库设计里的原子性很像：不可再分。但实际操作中很容易越界，比如我曾经把一个“创建订单并发送确认通知”写成一个原子技能，结果就是发通知失败时整个订单流程回滚，白白误伤了一堆正常请求。后来我把通知动作拆出去，创建订单和发送通知彻底解耦，订单该成就是成，通知失败了单独补救和报警。

所以我的建议很直白：涉及两个不同领域动作的，永远不要做成一个原子技能。甚至干脆用代码评审时的红线来约束：一个原子技能的执行函数里，不允许出现两个不共享事务边界的副作用调用。

3.2 复合技能：把流程编排变成一个可复用技能

复合技能是原子技能的组装体。它同样具备技能的所有元数据和参数契约，但执行链路不再是直接调一个后端，而是编排多个原子技能。用代码来表达就比较清楚了：

class BookingFlowSkill(CompositeSkill): def __init__(self): super().__init__( skill_id="hotel_booking_flow", version="1.3.0", parameters=self._build_parameters() ) self.tasks_define = [ "check_hotel_availability", "create_reservation", "send_confirmation" ]

这个编排器的内部逻辑本质上很简单：按顺序调用三个原子技能，中途任何一步失败都进入补偿流程。补偿流程的设计比主流程更考功夫，比如create_reservation成功但send_confirmation失败时，到底要不要自动取消预订？不能笼统回答，要看业务规则：某些场景下确认消息不是必要件，可以只标记“待确认”；某些场景下用户必须立即得到凭据，那就要自动反转预订。

我把这类判断做成了显式的决策表，而不是散落在代码里的一大堆if-else。决策读起来清楚，改起来也安全得多。

3.3 编排规则：谁来决定技能的执行顺序

到这里会出现一个关键问题：复合技能内部的步骤顺序是写死的，但上层智能体调用哪个复合技能、按什么顺序组合复合技能，应该由谁决定？

我的答案是：人定框架、模型填参数。复杂任务链的模板（剧本）由工程师预设，模板里留下参数槽位，模型要做的是根据用户意图选择合适的模板，然后填充参数。这比让模型自由编排技能要稳妥得多。自由编排在演示环境很酷，一旦上了生产，模型会想出你从来没见过的奇怪组合，出的错也千奇百怪。

举个例子，一个标准的售后处理剧本是这样预设的：

playbook: after_sale_refund steps: - skill: verify_order input_template: {order_id: "$order_id"} - skill: fetch_refund_policy input_template: {product_id: "$product_id"} - skill: estimate_refund_amount input_template: {order_id: "$order_id", policy_id: "$policy_id"} - skill: request_refund_approval input_template: {order_id: "$order_id", amount: "$amount", reason: "$user_reason"} - condition: approval_status == "approved" then: - skill: trigger_refund

每个playbook都有条件分支，分支条件只依据上一技能的标准化输出，不允许模型自己创造新分支。这样既保留了灵活性，又把不可控范围压缩到最小的可接受区间。

4. 技能仓库从0到1的搭建过程：注册、评估、上架、退役

4.1 技能登记表：先有数据，才能谈管理

动手写第一行代码之前，我先建了一张技能登记表。听起来很土，但这是整个项目里性价比最高的决策。登记表里每行对应一个技能，字段包括技能ID、版本、负责人、所属领域、调用频率、最近一次回归时间、当前状态、依赖后端系统。

这张表有几个直接作用。一是面试“这个智能体现在到底上了多少个技能”的时候不用再翻代码库；二是做容量评估时，能按领域聚合出调用热点；三是退役评审时，你能一眼看到哪些技能半年都没人调用。技能长期不被调用且没有特殊保留理由，我会直接标记为draft状态，禁止被检索命中，避免“僵尸技能”混进线上。

4.2 技能的注册与索引流程

注册环节本质上工作有三步：语法校验、意图索引、沙盒验证。

语法校验靠的是我在前文提到的那套标准化schema，写一个lint脚本在注册时自动跑，检测参数契约是否符合规范、必填项是否齐全、executor字段是否指向可访问的端点或函数。这一步拦截了一大批“手滑提交”的问题，比如参数名拼写错误、版本号冲突、JSON Schema格式非法。

意图索引是把每个技能的intent字段做语义向量化，存入向量检索库。检索调用时，智能体框架先把用户问题向量化，在技能库里做top-k召回，再把召回的技能精简描述拼进局部上下文。这里有个非常重要的细节：正常情况不要把所有技能描述全塞进prompt，只塞召回的top-k个个。我做实验时发现，技能总量超过20个以后，全量塞和检索塞的效果差距不是一星半点。全量塞会导致模型在多个候选技能之间犹豫，错误路由概率显著上升；检索塞则让模型专注在当前意图相关的2-3个技能上，命中率大幅提高。

沙盒验证则是在隔离环境里跑一遍冒烟测试。冒烟测试的样例我直接从回归集中抽一小批，确保每个注册进仓库的技能至少有一个成功的执行记录，防止“能用但没见过成功案例”的技能进入线上检索范围。

4.3 灰度上架与退役机制

技能上架不搞一刀切。新技能进仓库后，默认状态是beta，只有5%的流量会检索到它，且命中后会在trace里打上beta标记。跑满一段时间没有异常才能提升为active。这么做的好处是，模型一旦选到了beta技能并且表现不佳，影响面是可控的，我们也有足够日志去判断是技能本身不成熟还是检索逻辑的问题。

退役的触发条件我设了三个：持续零调用超过90天、连续多轮回归测试失败、或底层依赖系统下线。退役动作也不是直接删，而是先置为deprecated，排除出检索范围，保留存档。整个流程跑下来，就像在运营一个小型应用商店，技能的整个生命周期都是可见、可信、可控的。

5. 实测翻车清单：技能系统最常见的五个大坑与对策

5.1 参数幻觉：模型编造了不存在的参数

这是把技能开放给模型调用以后遇到的第一个普遍问题。模型在生成参数时，偶尔会输出契约里根本不存在的字段，比如契约只定义了start_time，模型擅自加了timezone字段；更隐蔽的是，模型把另一个相似技能的参数混进来，造成下游系统解析失败。

纯靠prompt警告没用，必须在框架层做硬校验。我在入口处写了一个校验器，收到模型产出的参数后，先和当前技能的JSON Schema做diff，只要发现未声明字段就直接拒绝并返回一个标准错误信息。这里不能静默丢弃，必须把“被拒绝的字段名”回传给模型，否则模型完全不知道自己的错误在哪。实测下来，这样处理后模型在下一次生成时通常会修改参数，自纠错效果明显。

5.2 技能路由冲突：两个技能都想管同一件事

如果两个技能的intent描述过于相似，检索层可能召回两个不相关的技能，模型选哪个都像“有道理”。这个问题在历史会话里尤其明显，比如“查询订单状态”和“查询物流进度”两个技能，用户问“我的订单到哪了”，模型既可能理解成订单状态，也可能理解成物流更新。

我用了两个对策。第一是在索引阶段强制技能间做意图距离检查，相似度超过阈值的技能会被标记为conflict，并要求负责人改写intent以拉开差异。第二是在检索层引入“判别头”，也就是一个轻量级分类器，专门负责在两个高相似技能之间做最终路由。这个分类器不复杂，本质是few-shot的二分类，效果却比单纯靠主模型判断稳定得多。

5.3 上下文污染：执行结果把会话窗口撑爆

技能执行返回的结果如果原封不动拼进上下文，很快就会把对话窗口消耗完。我见过最夸张的情况，一次查询返回了200行用户历史订单，几千个token瞬间被吃掉，导致后续对话质量明显下降。

解决办法是结果摘要层。每个技能可以声明自己的result_summary策略，包括：保留字段白名单、默认取top-n条、长文本用LLM一键摘要。我试验过三种策略的排序：优先用规则摘取（速度最快成本最低），规则无法处理再用模型摘要，加一层优先级控制。更关键的一点是，摘要要在技能内部完成不可见回调给智能体中间层，不要让模型在后续对话里还对着未摘要的原始结果“遐想”。

5.4 失败重试的“雪崩效应”

技能执行超时后，第一版的做法是自动重试两次。听起来合理，但在高并发场景下，一个下游服务已经过载，所有技能都在疯狂重试，等于给故障服务火上浇油，整体响应时间被拖垮。

后来我把重试策略改成了三层分级：第一层，一个请求同一个技能最多自动重试一次；第二层，重试仅限幂等技能，且加上指数退避；第三层，任何技能连续失败超过一定次数，立即打开展示开关（熔断），后续一定时间内请求直接走失败快速返回。通过这种方式，故障被限制在小范围，不再逐步放大。这个方法在支付回调那个故障场景里帮了大忙，没有出现全网雪崩。

5.5 回归测试的“记忆偏差”

开始做回归测试时，我只把测试样例固化在登记表里，结果模型或者底层接口升级以后，旧样例的期望值已经不再正确，回归测试跑出来的失败全是“假阳性”，负责人都麻木了，最终连真失败也懒得看。

我调整了回归集的治理方式：每轮测试结束后，自动把已确认失效的样例状态改为“待更新”，由技能负责人判断是修代码还是更新期望输出。同时把回归集与线上trace关联，定期从真实成功样本里抽一部分回填到测试集，让测试集始终贴近真实分布，而不是永远停留在发布那一刻。

6. 技能的质量度量：让“好用”变成可量化的指标

6.1 Echo技能：衡量技能本身最简单的方式

为了彻底搞清楚“技能好不好用”，我引入了Echo技能的概念。所谓Echo技能，就是理论上完全不该出错的最简单技能，比如输入一个字符串，原样返回这个字符串。

这个看似无用的技能，实际上是整套评估体系的地基。它在每个版本更新后会跑一遍完整链路：意图检索、参数校验、执行、结果返回、异常处理。如果Echo技能都失败了，那问题肯定出在框架层，而不是具体技能上，可以直接定位系统级Bug。它不是用来完成业务任务的，而是当作系统的“基准血压”来监测的。

6.2 从Trace到评分：一个技能的得分是怎么算出来的

我给每个技能维护了基础质量分，综合五项指标得出：检索命中率、执行成功率、参数零修正率、结果满意率、平均耗时。参数零修正率这个指标可能不太好理解，它的含义是：模型产生的参数在要不要经过默认值填充或格式纠偏的情况下，直接通过校验的比例越高，说明技能和模型之间的契约越清晰。如果经常需要大量修正参数，我会去审视intent和description是否与真实调用场景存在偏差。

每一项指标都从线上trace中提取，汇总到技能画像面板。另外，所有告警也会和技能维度绑定：新增技能上线后，如果它前三天的成功率低于60%，自动生成风险预警。这样就避免了“出了问题才想起来追踪”的被动局面。

6.3 评估结果怎么反哺技能仓库

评估不是结束，而是迭代的输入。当某项指标连续下滑，我不建议马上改代码，因为大概率是外部依赖变了，或者用户提问方式演变导致召回变化。我会先跑一遍最近一周的失败样本，看它们集中在哪类输入上，再据此决定：改参数契约、改intent描述、还是根据错误类型去修改执行链路。

技能仓库每周出一份“活跃技能健康报告”，按状态分成三类——健康、观察、异常。健康状态继续正常检索；观察状态降低召回权重；异常状态暂时下架，等修复验证后再重新上架。整个循环走下来，技能库就不只是静态代码库，而是会呼吸的、持续进化的能力体系。

7. 项目状态与几个我特别想强调的工程心得

agent-skills这个项目目前已经跑通了技能注册、语义索引、运行时校验、回归评估这套主链路，并且在两个不同业务场景的小规模智能体上稳定运行了一个多月。直接暴露出来的收益有两个：一个是prompt体量大幅下降，不需要再把所有工具绑进去；另一个是技能失败时可以快速定位是哪个环节出了问题，而且可以精确到具体技能版本，修起来边界很清晰。

如果让我给准备参考这套思路的同学列几个明确的告诫，第一是高估模型能力，尤其不要指望模型从零自学各种技能参数，参数契约必须显式表达；第二是低估下线比上线难，没有退役机制，技能库会越来越肿，检索准确率随之下降；第三是远离“全能技能”，一个技能做太多事情，最终结果是每个场景都表现平庸，还不如拆细了各自优化。

按照我目前的经验，技能系统的复杂度会滞后于业务复杂度爆发两到三周，也就是说刚上线一个月内可能非常安静，但之后会突然遇到集中爆发的问题。提前把监控埋点、回归测试和熔断机制设好，不要等到爆发了才去补，否则那两周你会过得比较煎熬。agent-skills对很多人来说可能只是一个玩具项目，但对我来说，它是把那些大模型在纸面能力与实际产出之间最后一段路补完整的关键拼图。