1. 项目背景与核心问题：Agent 到底卡在了哪里
做了几年大模型应用开发，我最深的感受是：单论对话能力，现在的模型已经强得离谱；可一旦想让它真正“干活”，完成多步骤、跨系统、需要记忆状态的任务，立刻就露馅了。要么逻辑链条断掉，要么每一步都要人盯着喂上下文，体感跟使唤一个记性不好的实习生似的。这也是我去年立项做agent-skills的初衷。
1.1 开发 Agent 时遇到的真实现状
我见过太多团队把 Agent 做成“玩具”：模型收到指令，调一两个 API，拿到结果就结束。复杂一点的，把提示词写成长篇大论，塞进系统 Prompt，看起来规划得井井有条，实际跑起来全是幻觉——模型根本记不住那么多约束，一旦任务跨度变长，就开始自由发挥。
更深层的问题在于“技能无法沉淀”。我最早用 LangChain 那套写应用时，每个业务逻辑都散落在代码里，今天写个send_email函数，明天写个query_order函数，每次新项目都要重新复制粘贴。更糟的是，这些能力跟对话流程深度耦合，模型调用的方式、参数格式、返回结构全靠约定，没有任何标准化的注册和发现机制。时间一长，代码越来越难维护，Agent 也越来越笨——不是模型不行，是你根本没给它搭好“手脚”。
1.2 agent-skills 想解决的三个关键痛点
做 agent-skills，我不打算再糊一个演示 Demo，而是想把它做成一套真正能让 Agent“长出手脚”的可复用技能框架。拆解下来，核心要解决三件事：
第一，技能标准化。每个能力都要有清晰的名字、描述、参数 Schema、执行逻辑和返回结构，让模型看完描述就知道什么时候该用、怎么用。
第二，技能的注册与发现机制。Agent 不能靠人肉把函数写死在代码里，而是要能在运行时按需加载匹配的技能库，就像手机装应用一样，需要什么装什么。
第三，技能编排与状态管理。单个技能只是零件，真正的 Agent 需要把零件组装成流水线，过程中要传参数、记状态、做取舍、处理异常。这套东西不搞定，技能再多也是一堆散沙。
我拿一个实际场景来说明。假设你要做一个“客户工单自动处理 Agent”，它至少要会查订单、查库存、查物流、写回复、升级人工。那这五件事就是五个技能，它们各自独立，但在这个任务里要按顺序、按条件被调度起来。agent-skills 要解决的就是：怎么定义这五个技能，怎么让 Agent 知道什么时候调哪个，以及中间出现意外怎么办。下面的内容全部围绕这条主线展开。
2. 技能框架的整体设计与核心思路拆解
在设计 agent-skills 时，我给自己定了几条原则。与其一上来堆概念，不如先明确这套体系到底长什么样。
2.1 为什么选择“技能”而不是“工具”或“插件”
大模型领域里，工具（Tool）、插件（Plugin）、技能（Skill）这几个词经常混用。但我刻意选择了“技能”这个说法，背后有实际考量。
工具是函数级别的抽象，强调的是“能被调用”；插件是集成层面的概念，强调的是“能装进宿主”；而技能更接近“能力”的语义——它自带使用条件、适用场景、输入输出约束，甚至包含内部状态的转换逻辑。用我自己的话说：工具是零散的招式，技能是成套的功夫。
比如“发送邮件”是个工具，但“处理客户催单”是个技能。后者需要查上下文、判断紧急程度、决定措辞、甚至可能升级人工。一个技能内部可能串起多个工具调用，也可能自己就带了小型决策逻辑。这种粒度，Agent 才能真正理解并复用。
另一个重要原因是：技能的抽象层级更高，天然适合跨项目复用。我在项目 A 里写好的“订单状态查询技能”，只要接口不变，在项目 B、C 里都能直接挂载，不需要改 Agent 主逻辑。
2.2 技能的四层架构：注册表、描述、执行体和运行时
最初的版本我写得异常简陋——一个 Python 字典存函数引用，一个 Prompt 列功能列表。结果模型经常选错工具，参数也老传错。复盘之后我重构出四层结构，这也是 agent-skills 的骨架。
第一层是技能注册表（Registry）。这是所有技能的中枢数据库，记录每个技能的名字、版本、描述、参数 Schema、依赖关系、状态属性。Agent 在做规划时，首先查注册表，看当前任务能匹配哪些技能。
第二层是技能描述（Descriptor）。这是给大模型看的说明书。它决定模型能不能在正确时机选中正确的技能。写得好不好，直接决定整个 Agent 的智商上限。描述里一般包含：触发条件、典型用法、参数解释、返回值说明、注意事项。注意，描述要写得让模型“一看就懂”，但不是堆字数，关键是把适用边界讲清楚。
第三层是执行体（Executor）。这是真正干活的部分，接受标准化输入，调用真实 API 或业务逻辑，返回结构化结果。它可以是本地函数，可以是远程 HTTP 服务，也可以是另一个 Agent。
第四层是运行时（Runtime）。这层负责技能之间的上下文传递、状态快照、异常捕获和重试机制。它是 Agent 能力的“后勤部门”，没有它，技能再多也调度不顺。
我画了个简单的数据流：Model 发出规划意图 → Registry 检索候选技能 → Descriptor 指导选择 → Executor 执行动作 → 结果回传 Runtime → 更新上下文 → 模型继续下一步。这个循环就是整个体系运转的基础。
2.3 设计技能时的三个关键取舍
做这套框架的过程中，我反复纠结过三个问题，每个取舍都直接影响了最终效果。
第一个取舍是技能的粒度。技能定得太粗，比如“处理所有客户问题”，模型根本不知道该从哪下手；定得太细，比如“解析字符串”“获取当前时间”也算技能，注册表会膨胀到失控，模型的选择负担急剧上升。我最后的经验是：技能的粒度要让模型在一步决策内能说清“调它干嘛”。一个技能应恰好对应一个业务动作，比如“查询订单状态”是一个技能，而“执行数据库查询”就不该是技能。
第二个取舍是技能之间是否允许互调。最开始我严格禁止技能内部调用别的技能，想着逻辑越简单越安全，结果发现很多任务被迫在 Agent 主流程里写复杂编排代码。后来我改成了允许技能互调，但必须声明依赖关系，运行时通过依赖注入的方式把技能句柄传给 Executor。效果很明显——复杂任务被拆得更自然，代码重复也少了。
第三个取舍是技能状态存哪里。很多场景需要技能保存中间状态，比如“根据多轮对话内容更新工单优先级”。如果把状态全存内存，进程一重启就全丢；存外部数据库又增加复杂度。我最终采取的方案是：每个技能自带一个可选的 State Store，默认用内存快照 + 定期序列化落盘。这么做的原因是，大部分技能其实不需要持久化状态，强制做持久化反而影响性能。
3. 技能定义规范：让模型一看就懂的接口设计
讲完架构，进入最实在的部分：一个技能到底怎么定义。早期我在这方面吃过太多亏，现在这套规范是踩坑踩出来的。
3.1 技能描述文件的字段设计与写法
每个技能都有一个描述文件，可以是 JSON、YAML 或 Markdown 格式，最终都会转成模型友好的文本片段注入上下文。我强烈推荐 YAML，可读性比 JSON 好，注释也方便。
一个标准的技能描述长这样（伪代码示范）：
name: query_order_status description: > 根据订单编号查询订单的当前状态与物流进度。 当用户询问"我的订单到哪了""发货了吗""订单状态"时使用该技能。 该技能仅适用于查询，不包含修改订单操作。 version: 1.2.0 domain: ecommerce tags: [order, logistics, query] dependencies: [] state_store: optional parameters: order_id: type: string required: true description: "订单编号，通常为数字或字母组合，示例：ORD2024010142。" pattern: "^ORD\\d{10}$" include_logistics: type: boolean required: false default: false description: "是否同时返回物流轨迹，默认 false。" returns: order_status: type: string enum: [pending, paid, shipped, delivered, cancelled] logistics_tracking: type: array description: "物流轨迹列表，仅当 include_logistics 为 true 时返回。" error_cases: - code: ORDER_NOT_FOUND description: "订单不存在或无权访问。" suggestion: "请向用户确认订单编号是否正确。" - code: API_TIMEOUT description: "查询超时。" suggestion: "可以稍后重试，或为用户提供客服联系电话。"字段拆解一下：name是技能唯一标识，我用蛇形命名法，全小写；description前 200 字最关键，模型做意图匹配时主要看这部分，所以我刻意把“什么时候用”“什么时候别用”都写进去；parameters里每个字段都要有description，否则模型很容易传空值或臆造值。error_cases这块经常被忽略，但它特别重要——模型遇到错误后能不能优雅处理，全看这里有没有引导。
3.2 参数 Schema 中的类型约束与枚举提示
写参数时最容易犯的错是：只写类型，不写取值范围。你要知道，模型在生成参数时是“猜”的，你不给它边界，它就瞎猜。我的经验是，所有参数必须写明以下几项中的至少三项：type、required、default、description、pattern、enum。
举个例子，用户只说“查一下单号 20240101”，模型可能分不清这个数字是订单号还是日期。你需要在description里写清楚“订单编号通常以 ORD 开头，遇到纯数字时可先通过上下文判断，无法确定时向用户追问”。这种提示带虽然朴素，但对模型的实际表现提升是巨大的。
对于枚举类型，一定要给全所有可能值。我遇到过模型硬是把“cancelled”拼成“canceled”的，查错半天才发现在enum里漏了一个 d。这种低级错误，定义严谨了就不会发生。
3.3 灵活使用参数的 required 策略
我建议把参数分成三个档位：必须提供、可选提供、上下文自动填充。
必须提供的参数，模型没有就要追问用户；可选提供的参数，模型可以根据上下文推断；上下文自动填充的参数，则隐藏在 Agent 运行时的内部状态里，模型不需要感知。比如查询订单状态时，如果 Agent 已经在对话里确认过用户身份，user_id就不需要模型操心，运行时自动塞进去。
这套策略能明显减少模型的多余追问，让交互更顺滑。但有个前提——你自己要清楚哪些字段真的能自动拿到，不要在生产环境里想当然。测试时我曾经以为 Session 里一定有user_id，结果上线后发现三分之一请求拿不到，整个 Agent 直接降级成“查无此人”。
4. 技能注册表与动态发现机制：让 Agent 学会按需选型
技能定义好之后，要注册进系统，让 Agent 在规划阶段能“看见”它们。这里有很多细节直接关系到系统的扩展性和稳定性。
4.1 注册表的数据结构与索引策略
我用 Redis 作为注册表的存储层，原因很简单：技能描述是读多写少的典型场景，而且需要毫秒级查询延迟，Redis 的 Hash 结构天然适合存“技能名 → 描述信息”的映射。
具体存储设计：每个技能描述序列化成一个 JSON 字符串，作为 Hash 的一个 field 存进去。同时建几个索引集合，比如按domain分域索引、按tags打标索引、按version做版本链。查询时优先走索引缩小候选集，再拉出完整描述做精排。
这里要说一个我踩过的坑：切忌把全部技能的描述一次性塞进 Prompt。模型对超长上下文的注意力会衰减，技能超过十个之后就开始乱选。我的做法是两层检索：先用轻量的关键词匹配（技能名 + 标签 + 描述的摘要向量）定位候选技能，数量控制在 3~5 个；再把这几个技能的完整描述展开给模型。这样既保证了准召率，又控制了 Prompt 长度。
4.2 技能加载的时机与上下文预算管理
技能不是注册了就自动加载，加载策略直接影响模型的决策质量。我采用的是“预加载 + 按需加载”组合方案。
预加载：在会话开始阶段，把高频技能加载进上下文。比如电商客服 Agent，query_order_status、cancel_order、initiate_return这几个是必加载项，因为大多数会话都会用到。按需加载：模型在规划阶段发现某个低频技能的摘要被触发时，再展开完整描述。
上下文预算要提前规划好。假设当前模型的上下文窗口是 128K tokens，我会给“技能描述区”预留最多 30% 的预算，绝不让技能描述挤占对话历史和中间推理的空间。设计了一套简单的预算机制：预加载技能各 200~400 tokens，按需加载技能各 800~1500 tokens，超过预算就触发注册表淘汰策略，把不常用的技能先摘出去。
4.3 版本管理与灰度发布
Agent 技能是活的业务代码，肯定要迭代。我在注册表里加了一个版本字段，支持同一技能多版本共存，运行时通过?version=v1.2.0或?version=latest指定使用哪个版本。灰度发布流程是：新版本先在小流量会话中使用，跑一段时间观察调用成功率和用户反馈，再逐步放量。
这里有个非常容易出问题的点：同一技能不同版本之间必须保证参数兼容。模型是记不住你昨天刚改的参数的，如果我昨天定义了order_id，今天改成orderId，那么所有还没升级上下文的会话都会报错。我的对策是：参数名改动必须同步改版本号，并做 3.1 那种完整的参数映射兼容层。改参数名这种操作，至少要保留旧名称作为别名，再过渡两个版本再删。
5. 技能编排与运行时调度：多技能协作的实战推演
技能定义得再规范，真正测出功力的是编排层。这一步要把模型想法落地成可执行动作序列，还要处理各种中途幺蛾子。
5.1 编排引擎的两种模式：顺序执行与状态机
早期我图省事，所有任务都写成顺序调用链：step1 调技能 A，拿结果；step2 调技能 B，用 A 的结果做入参。遇到分支任务就傻眼了，比如“如果订单已发货就不能申请改地址，要推荐联系物流”，顺序链写出来像一大坨面条代码。
后来重构时引入了轻量状态机。设计了一个workflow描述文件，用states和transitions来定义步骤及跳转条件。每个步骤代表一次技能调用，跳转条件可以是“上一步结果的某个字段等于什么值”“某参数是否为空”“用户是否确认了某个选项”。这样分支、循环、重试都能自然表达。
状态机的核心是让 Agent 的每一步都有明确的“当前状态”。比如初始状态是collecting_intent，识别出用户要退换货就跳到checking_order,订单状态合法再跳到initiating_return，不合法就跳到escalate_to_human。每跳转一步，运行时都会更新状态快照，异常时能从容回滚到上一个稳定状态。
5.2 上下文传递：不要让模型猜上一轮发生了什么
编排中最容易翻车的就是上下文传递。模型在生成下一次技能调用时，需要知道上一次调用的结果，但不可能把整个历史都原样交给它，信息太多噪声也大。
我实现了一个ContextBuffer机制。每次技能返回结果后，运行时把结果按结构化摘要“注入”到上下文中——不是存原始 JSON，而是由该技能定义里预先写好的context_summary模板生成一段人类可读的文本。比如查询订单技能返回了大量物流轨迹，上下文里只留存“订单已签收，签收时间为 2024-01-15 14:20，包裹完好”这几十个字。模型看这段摘要就已经足够决策了。
这里有个细节：上下文注入位置要稳定。我固定在每次技能调用前的“最新工具结果”区域插入，并保证旧的摘要会被新摘要覆盖，不累积、不膨胀。否则模型会被越来越长的历史摘要带偏，注意力发散。
5.3 错误重试与降级策略的工程实现
技能调用不可能永远成功，网络抖动、接口限流、参数校验失败都是家常便饭。Agent 的错误处理要比普通后端服务更复杂，因为模型必须理解失败原因，并给出用户可以接受的反馈。
我实现了三级重试策略：
- 第一级，框架自动重试。针对网络超时、瞬时 5xx 这类可重试错误，自动重试最多 2 次，间隔指数退避。
- 第二级，模型感知重试。如果重试仍失败，框架把
error_cases里的提示交给模型，模型可以调整入参再次调用。比如参数格式不对，模型可以从错误信息中提取正确格式后重新生成。 - 第三级，降级或转人工。若连续三次失败，模型根据技能描述里的
suggestion字段给出兜底话术，或者调用escalate_to_human技能移交人工客服。
这套策略上线后，工单系统的技能调用成功率从 82% 提升到 97%，大部分损失都靠框架自动修正兜住了。实践心得很明确：Agent 的错误处理不能只靠模型随机应变，框架要把错误分类和决策路径先铺好。
5.4 长任务的中断恢复：状态快照的意义
有一类任务是真正折磨人的：比如“帮我对比三家供应商的报价并生成推荐报告”。这需要调用多个技能，耗时可能几分钟甚至更久。期间一旦模型进程崩溃，或用户中途切走，所有进度全丢。
我用状态快照机制解决这个问题。每个工作流的每个状态转换都会记一个checkpoint，包含当前步骤、已完成步骤、已收集的参数片段、上下文摘要等。当用户回来说“继续刚才那个任务”，运行时从最近的 checkpoint 恢复，不需要重新开始。
实现上我用 SQLite 存 checkpoint，每条记录带 session_id、workflow_id、state_name、payload、created_at。恢复时直接按 session_id 拉最新记录，重放上下文，然后让模型从断点继续编排。这里需要注意：重放时一定要告诉模型“你已经完成了什么”，否则模型会重复执行已经做过的步骤，用户体验极差。
6. 从零构建一个技能：工单自动处理全程实录
讲到这里，不如直接走一遍完整的技能构建实战。我以“客户工单自动处理 Agent”为例，把从定义技能到调试完成的全程记录下来。
6.1 需求拆分：把工单流程拆成可复用技能
客户工单处理的需求一句话：自动接收用户的售后请求，判断类型，能自助处理就自助处理，不能就转人工。但我不会直接给 Agent 写一个“智能工单处理”大技能，而是拆成五个独立技能：
categorize_query：把用户问题归类为退款、退换货、物流查询、技术咨询等。query_order_status：查订单状态，用于判断订单是否满足售后条件。initiate_refund：发起退款，需要订单号、退款金额、退款原因。escalate_to_human：转人工，附带上下文摘要和推荐处理建议。send_notification：给用户发送处理结果通知。
这五个技能相互独立，但通过工作流组合出完整的售后服务闭环。为什么拆这么细？因为退款与退货的审批逻辑不同，物流查询和订单查询的字段重叠度也不同。每个技能都能被其他场景复用（比如查询订单在售前咨询中也会用到）。
6.2 每个技能的描述、参数与返回结构规范
以initiate_refund为例，描述文件要和真实的财务系统安全接轨：
name: initiate_refund description: > 为用户的订单发起退款申请。 仅当用户明确要求退款且订单状态允许退款时使用。 发起前必须已确认订单编号且校验过订单归属权。 如果退款金额超过 1000 元或订单超过 7 天，需要升级人工处理。 version: 1.0.0 domain: ecommerce state_store: required parameters: order_id: type: string required: true description: "订单编号，以 ORD 开头，共 13 位字符。" pattern: "^ORD\\d{10}$" refund_amount: type: number required: true description: "退款金额，单位元，最多两位小数。" minimum: 0 maximum: 5000 reason_code: type: string required: true enum: [not_received, damaged, wrong_item, quality_issue, change_mind] refund_channel: type: string required: false default: original enum: [original, balance, alipay, wechat] returns: refund_id: type: string description: "退款单号，用于后续查询，例如 RFD20240115001。" estimated_arrival: type: string description: "预计原路退回时间，格式为 YYYY-MM-DD。" error_cases: - code: ORDER_NOT_REFUNDABLE description: "订单不在可退款状态。" suggestion: "检查订单状态，告知用户当前状态为何无法退款。" - code: AMOUNT_EXCEEDS_LIMIT description: "退款金额超过单笔限额。" suggestion: "升级人工客服处理。"看到description里的限定条款了吗？我把“超过 1000 元要转人工”“超过 7 天要转人工”这类业务规则直接写进技能描述，让模型在调用技能前自行判断是否合规。这比在代码里堆if要灵活得多，因为模型的判断可以结合对话上下文里更丰富的情绪和意图信息。
6.3 工作流定义：从语言指令到技能调用序列
用户说一句“我买的手机壳颜色不对，想退”，模型需要依次走这些步骤：
- 调用
categorize_query，识别出“退换货意图”。 - 调用
query_order_status，确认订单最近签收时间、状态。 - 若订单状态是“已签收”且签收时间在 7 天内，进入
initiate_refund，否则跳转escalate_to_human。 - 退款发起成功后，调用
send_notification通知用户。
这条链路对应的工作流定义节选如下：
workflow: refund_process start_state: collect_intent states: - name: collect_intent execute: categorize_query transitions: - condition: "{category} == after_sale_refund" target: check_order_status - condition: "{category} == pre_sale_consult" target: handle_consultation - name: check_order_status execute: query_order_status transitions: - condition: "{order_status} == received && {days_since_received} <= 7" target: initiate_refund - condition: "{order_status} != received || {days_since_received} > 7" target: escalate_to_human - name: initiate_refund execute: initiate_refund transitions: - condition: "{refund_result} == success" target: notify_user - condition: "{refund_result} == AMOUNT_EXCEEDS_LIMIT" target: escalate_to_human - name: escalate_to_human execute: escalate_to_human transitions: []这套定义配合运行时解释器，就能把模型“一句话指令”翻译成可执行的多技能协作流程。实际使用时，条件里那个{days_since_received}字段由query_order_status技能的context_summary模板生成，运行时自动替换成真实数值，模型不需要自己算日期差异。
6.4 调试时的 Prompt 模板与上下文组织
实现这个 Agent 时，系统 Prompt 的组织也有讲究。我不会把所有技能细节都写进系统提示，而是让系统提示只负责“定义角色 + 解释规则 + 引导调用流程”，技能信息则动态注入。
系统提示里需要强调的核心规则只有几条：
- 只使用已列出的技能完成用户请求，不要编造或猜测不存在的技能。
- 在调用技能前，先确认是否缺少必要参数，缺少时优先向用户追问。
- 技能调用失败时，阅读错误信息，按建议调整参数或转人工。
- 每次技能调用只做“当前最需要的一步”，不要试图一次调用多个技能。
最后一条尤其重要。我见过模型一个回合内连续调用四五个技能的，结果中间某步参数错了，整个链条全部作废。强制“一次一步”之后，虽然交互轮次变多了，但成功率显著上升。
7. 常见问题与排查技巧实录：那些反直觉的坑
这部分我要专门展开，把我在开发和测试过程中反复踩到的坑整理成速查。这些问题在官方文档里基本找不到答案，但每一类都足以让项目陷入停滞。
7.1 模型老是选错技能，优先级怎么调
现象：用户问“能不能帮我看看物流”，模型却调了“订单查询”技能而不是“物流查询”技能。表面看是描述写得不够清楚，实际排查后发现是技能间存在描述“语义打架”。
我见过最典型的场景：两个技能的description里都包含“订单”这个词，模型在意图匹配时出现混淆。解决思路不是把描述改得更长，而是给技能加“优先级”和“排他条件”。
在注册表里加一个priority字段，数值越小越优先被选中。同时要求每个技能的描述里声明“本技能不处理什么”——这是很多人都忽略的负向约束。比如物流查询的 description 末尾加一句“本技能仅提供物流轨迹与配送进度，不处理订单金额、退款等问题”。别小看这一句负向声明，实测能把技能选择准确率从 89% 拉到 96%。
7.2 参数传递错乱，模型把上一轮的输出当入参
这是让我最头疼的问题之一。Agent 连续调用两个技能时，模型常常把第一个技能返回里的某个字段，直接当成第二个技能的入参，但字段名对不上。
排查思路：仔细观察运行时日志里的这次调用入参。我发现很多参数错乱是因为返回结构太长，模型在上下文里“找错字段”。解决方案是精简返回结构。不相关字段不要全塞给模型，技能返回前加一个response_filter，只保留模型决策需要的字段和摘要。
另外，我强制每个技能在返回时都带一个_description字段，用一句话概括本次返回内容。比如“订单已签收，签收时间 2024-01-15”。模型读摘要比读结构化 JSON 更不容易出错，这是一个微小的改动，但收益非常可观。
7.3 上下文膨胀导致模型“遗忘”，怎么处理
长会话里，技能调用记录一多，上下文开始膨胀，模型渐渐只看最近的调用，忘了前面已经确认的信息。比如用户先说了地址信息，五个技能调用之后模型开始问用户“请问收货地址是什么”——这是极其尴尬也极其常见的问题。
这个问题不能靠加长上下文窗口解决，因为窗口越大噪声越大。我的方案是维护一个“持久化事实清单”，把对话中用户明确提供的关键信息（真实姓名、地址、订单号、期望时间）抽离到独立存储区，每次触发新技能前，把清单摘要固定注入到上下文顶部。模型在任何步骤都能看到这份摘要，自然不会再忘。
抽取事实的操作我用的是一个小提示词任务，不是正则匹配。正则只能处理“下单”“地址是”这类显式表达，面对“我那个在某某路的房子”这种隐含表达就失效了。模型抽取则能结合语义理解，准确率高得多。
7.4 技能反复失败，是重试还是彻底放弃
无脑重试是最糟糕的策略，用户感受极其煎熬。如果一个技能连续失败三次，每次耗时 10 秒，用户要等半分钟才能听到“转人工”的反馈，这个体验基本算废了。
我的策略是给不同错误码配置不同重试上限。网络超时类错误可以重试 3 次；参数校验错误重试 2 次；业务规则拒绝（比如订单不可退款）则完全不重试，直接让模型读取元信逻辑后向用户解释。另外，重试间隔不能太激进，首次失败后等 1 秒，第二次 3 秒，第三次 8 秒，指数退避。如果应用要求实时响应，那干脆第一重试直接跳过，立即降级转人工。
还有一个细节：重试时模型是否参与修正，要视错误类型而定。网络错误是环境问题，模型修正参数也没用，不该打扰模型；参数错误则必须让模型看看错误提示，调整入参后再调用。分类处理，而不是一刀切全都交给框架或全都交给模型。
7.5 技能库越来越大，选型性能下降怎么办
技能数量超过 50 个时，即使两层检索，模型偶尔还是会选错。尤其在两个技能描述相似度很高的情况下。
我的应对方案分三步：
第一步，定期对技能描述做向量化，建立 embedding 索引。查询时先把用户意图做向量检索，召回最相似的 10 个技能，再做精排。这一步能显著减少语义干扰。
第二步，对同类技能做“分组折叠”。比如“查询订单”“查询物流”“查询退款进度”三个技能折叠成一个“查询服务”技能，内部再根据业务参数分流。这样描述更集中，模型选择压力更小。注意折叠后的技能描述要清楚说明二级分流规则。
第三步，给高频场景配置“推荐技能路径”。比如工单处理这类高频场景，直接在会话开始时就预置整套工作流，不让模型从零规划。预置路径相当于给模型配了股骨，它只需要做局部决策，容错率大幅提高。
8. 聊聊后续扩展：从单机技能到组织级能力沉淀
agent-skills 这个项目目前已经跑在我自己的几个业务场景里，但我的规划远没有止步于当前的“技能注册 + 编排调度”。实际上，日常维护中我发现了几条值得继续深入的方向，这里一并分享。
8.1 技能质量评估：需要一套自动化度量指标
技能写得再好，也会在实际调用中暴露问题——调用成功率低、参数错误率高、用户反馈差。目前我的做法是给每个技能记录一份运行指标：调用次数、成功率、平均耗时、平均修正次数、降级率。每周跑来一份榜单，把明显有问题的技能捞出来重新打磨描述或修参数 Schema。
指标里我比较看重“平均修正次数”这个数字。它指每次调用中，模型第一次生成的参数有多少比例需要被框架自动修正。修正次数高，说明参数 Schema 和描述对模型不够友好，需要优化。这个指标比成功率迟钝，但更能反映设计质量。
8.2 多 Agent 协作时的技能互借
单 Agent 能承载的技能有限，但一个组织内的技能库完全可以做到共享。下一步我想在 agent-skills 上做一个“技能市场”模式，让不同业务线的 Agent 按权限互相挂载、发布技能。比如客服 Agent 可以借用售后 Agent 的“退款进度查询”技能，无需重复实现。
这需要额外解决权限控制和数据隔离问题。技能在跨 Agent 调用时，业务数据的归属、敏感字段的脱敏，都是必须想清楚的边界。我在实现时准备引入一个技能代理层，所有跨 Agent 调用都走代理，校验权限、记录审计日志、做字段级脱敏，不允许让模型直接触达对方系统的底层接口。
8.3 与我个人的真实体会
整个项目开发下来，我最深的体会有两点。一是 Agent 的智能程度并不只取决于模型选择，还取决于你给它搭建的“脚手架”。把技能定义清楚、注册表搞对、编排层做稳，即使是相对弱一些的模型，也能干出像样的活。反之，模型再强，技能描述一团糟，照样把任务做成一锅粥。
二是技能的复用收益是长期且复利的。我最早搭好的几个通用技能（查订单、查库存、发通知），现在已经在三个不同项目里重复使用。每次新项目启动，技能注册表里拖着这些存量能力，产品上线速度肉眼可见地快。这大概就是沉淀的价值——开始慢，后期越跑越快。
如果你也在做 Agent 类应用，我真心建议别把所有逻辑塞进 Prompt 里。花时间把技能层搭起来，短期看是费工夫，长期看是省下一整个团队的重复劳动。这套东西不需要一次到位，从一个最简单的高频技能开始注册，跑通流程，再逐步扩充，比憋大招稳妥得多。
