1. 从agent-skills这个命名说起它到底指什么第一次看到agent-skills这个词很多人会下意识地把它当成某个具体框架或库的名字。但如果你在工程实践里摸爬滚打过一段时间就会发现它更像是一个概念容器——用来描述智能体agent具备哪些可被调用的能力这件事本身。换句话说它不是一个现成的工具而是一套关于如何给智能体装配技能的设计思路和组织方式。我在实际项目里接触过不少类似命名的东西有的团队把它做成一个技能注册中心有的把它做成一套提示词模板库还有的干脆把它当成一个插件目录。命名相同落地形态却千差万别。这恰恰说明agent-skills这个词的核心不在实现而在抽象层次它站在能力这一层往上承接具体的业务任务往下对接模型调用、工具执行、状态管理等底层机制。那它到底解决什么问题简单说就是让一个智能体不再只会聊天而是能真正干活。一个只会对话的模型你问它天气它只能凭记忆瞎猜但如果你给它装配一个查询天气的技能它就能调用真实接口拿到数据。技能就是智能体从会说到会做之间的那座桥。这篇文章适合谁看如果你正在做智能体相关的应用开发或者你手头有一个需要让模型调用外部能力的场景再或者你只是好奇智能体到底怎么被组织起来干活那这篇内容都能给你一些可以直接参考的东西。我会尽量把抽象的东西讲具体把为什么这么设计讲透而不是只丢一堆名词。需要先说明一点由于原始输入里项目正文、关键词、摘要都是空的下面所有关于实现细节、目录结构、参数配置的内容都是基于我在类似项目中的常见实践做的合理补全。这些不是唯一答案但都是经过验证、能跑通的方案你可以直接拿去改。2. 技能的本质把能力从模型里剥离出来2.1 为什么不能把所有逻辑都塞进提示词很多人做智能体应用的第一反应是把所有规则、所有知识、所有操作步骤全写进系统提示词里。刚开始确实能跑但很快就会撞墙。第一个问题是上下文膨胀。你每加一个能力提示词就长一截。加到十几个能力之后光系统提示词就几千字模型每次调用都要重新读一遍token 成本飙升不说模型对每条规则的注意力还被稀释了。我实测过一个案例当系统提示词从 800 字涨到 4000 字时模型对其中某条关键约束的遵守率从 95% 掉到了 70% 左右。这不是模型变笨了是信息过载。第二个问题是无法执行真实操作。提示词再详细模型也只能描述怎么查数据库不能真的去查。它没有手只有嘴。第三个问题是不可维护。业务逻辑散落在几千字的自然语言里改一个参数要在文本里大海捞针还没法做单元测试。agent-skills这套思路的核心价值就是把这些能力从提示词里剥离出来变成一个个独立、可注册、可调用、可测试的单元。模型只负责决定调用哪个技能、传什么参数具体怎么执行交给技能本身。2.2 一个技能应该包含哪些要素一个设计良好的技能通常包含四个部分我用一个查询订单状态的技能来举例说明要素作用示例名称与描述让模型知道这个技能是干什么的query_order_status根据订单号查询当前物流与支付状态参数定义告诉模型需要提供哪些输入order_id字符串必填、detail_level枚举可选执行逻辑真正干活的代码调用内部订单服务接口解析返回结果返回结构统一输出格式方便模型理解标准化的 JSON包含状态码、消息、数据体这里最关键的是描述和参数定义。模型不是靠读你的代码来决定调不调这个技能的它是靠读描述。所以描述写得好不好直接决定技能被正确调用的概率。我见过太多人把描述写成查询订单结果模型在用户问我买的东西到哪了的时候根本想不起来调它。正确的写法应该覆盖用户可能的表达方式比如查询订单的物流进度、支付状态、预计送达时间。参数定义同样重要。每个参数的类型、是否必填、取值范围、默认值都要写清楚。模型在生成调用参数时这些信息就是它的说明书。参数定义模糊模型就会瞎填。2.3 技能与工具、插件、函数的区别这几个词经常被混用我在不同团队里见过不同的叫法。大致可以这样区分函数function最底层的代码单元纯粹的执行逻辑不包含任何给模型看的元信息。工具tool函数加上给模型看的描述和参数 schema是模型可以直接看到并调用的东西。插件plugin一组相关工具的集合通常还带有生命周期管理、配置注入等能力。技能skill语义上更强调能力这个层面一个技能可能对应一个工具也可能是一组工具的编排。在实际落地时这些概念经常是重叠的。你叫它技能也好工具也好本质都是模型可调用的能力单元。我在文章里统一用技能这个词但你要知道它和工具在多数场景下是可以互换的。理解这一层区别的意义在于当你设计系统时要清楚自己是在定义执行逻辑还是在定义给模型看的接口。这两件事应该分开混在一起就会导致技能既难测试又难被模型正确调用。3. 技能注册与发现让智能体知道自己会什么3.1 注册表是整个体系的中枢技能不会凭空被模型知道。你需要一个注册表registry把所有可用技能集中管理起来。模型在每次决策前会拿到一份当前可用技能清单然后从中选择。这个注册表最简单的形态就是一个字典或者列表每个条目包含技能的名称、描述、参数 schema 和执行入口。复杂一点的会带上权限控制、版本管理、启用开关等。我建议注册表至少支持这几个操作register(skill)注册一个技能unregister(name)注销一个技能list_available(context)根据当前上下文返回可用技能列表get(name)获取某个技能的完整定义其中list_available是精髓所在。不是所有技能在任何场景下都该暴露给模型。比如一个删除数据的技能在只读会话里就不该出现。根据用户身份、会话状态、任务阶段动态筛选可用技能能大幅降低模型选错技能的概率。3.2 技能描述怎么写才能被模型正确选中这是整个体系里最容易被低估的环节。我踩过的坑几乎都集中在这里。先说一个反直觉的结论技能描述不是写给人看的文档是写给模型看的广告。它的目标不是准确而是在正确的时机被正确选中。具体来说好的技能描述要满足三点第一覆盖同义表达。用户说查快递看物流我的包裹呢订单到哪了这些都应该能命中同一个技能。你可以在描述里把这些说法都列出来或者用更抽象的方式概括查询订单相关的物流、配送、签收信息。第二明确边界。如果一个技能只处理已支付订单描述里就要写清楚。否则模型会在用户问未支付订单时也调它然后执行失败。边界写清楚模型才知道什么时候不该用。第三避免描述重叠。如果你有两个技能描述都是查询订单信息模型就会随机选一个。这时候要么合并要么把差异写清楚比如一个查支付状态一个查物流状态。我一般会用一个简单的自测方法把技能描述单独拿出来想象用户可能说的 20 句话看这个描述能不能让人或模型判断出该不该调它。如果判断不了描述就得改。3.3 动态技能加载的两种策略技能不一定一开始就全部加载。有两种常见策略全量加载启动时把所有技能注册进去每次决策都带上完整清单。优点是简单缺点是技能多了之后光技能清单就占掉大量上下文模型选择难度也上升。适合技能数量在 20 个以内的场景。按需加载根据当前任务阶段或用户意图只加载相关技能。比如用户刚进入下单流程就只加载下单相关的技能进入售后流程再切换到售后技能。优点是上下文精简、选择准确缺点是需要一套意图识别或流程管理机制来驱动加载。我在实际项目里更倾向按需加载尤其是技能超过 30 个之后全量加载的准确率下降非常明显。一个折中方案是分组加载把技能按业务域分成若干组先让模型选组再在组内选技能。这样每层的选择空间都小准确率能稳住。4. 技能执行链路从模型决策到真实动作4.1 一次完整的技能调用经历了什么很多人以为模型调用技能是一步完成的其实中间有好几个环节。理解这条链路是排查问题的关键。一次典型的技能调用大致经过这些步骤模型根据当前对话和可用技能清单输出一个结构化的调用意图包含技能名和参数。系统解析这个意图校验技能是否存在、参数是否合法。如果校验通过执行技能逻辑如果不通过把错误信息返回给模型。技能执行结果被序列化成模型能理解的格式回填到对话上下文。模型基于结果继续生成回复或者决定调用下一个技能。这条链路里第 2 步的校验最容易被忽略但恰恰是稳定性的关键。模型生成的参数经常有各种小毛病数字传成字符串、必填项漏填、枚举值拼错。如果不校验直接执行轻则报错重则产生脏数据。我的做法是在校验层做三件事类型转换能转就转比如字符串数字转数字、必填检查、枚举白名单。校验失败时不要直接抛异常给用户而是把具体的错误信息返回给模型让它自己修正参数重试。实测下来模型在拿到明确错误提示后重试成功率很高。4.2 参数校验与错误回传的实操细节这里展开说一下错误回传的写法因为这是很多人做不好的地方。假设模型调用query_order_status时漏了order_id。如果你返回一句参数错误模型大概率会再瞎试一次。但如果你返回调用失败缺少必填参数 order_id。请从用户消息中提取订单号后重新调用。模型就能明白问题在哪并且知道下一步该干什么。错误信息里带上怎么修的提示比单纯说错了有用得多。再比如枚举值错误。模型传了detail_level: full但你的白名单只有basic和detailed。返回调用失败detail_level 的值 full 无效可选值为 basic 或 detailed。模型下次就会从白名单里选。这种带选项的错误提示能显著减少来回次数。还有一个细节错误信息不要暴露内部实现。比如不要返回堆栈信息、数据库字段名、内部服务地址。这些对模型没用还可能泄露敏感信息。错误信息应该面向如何修正调用而不是系统哪里崩了。4.3 超时、重试与幂等性技能执行是真实操作就会有超时和失败。这块处理不好整个智能体就会卡死或者产生重复操作。超时每个技能都应该有超时设置。查询类技能可以短一点比如 5 秒涉及外部服务的可以长一点比如 30 秒。超时后要返回明确的超时信息让模型知道这次没成功可以稍后重试或换方式。重试不是所有失败都该重试。网络抖动导致的失败可以重试参数错误导致的失败重试也没用。我一般只对超时和明确的临时性错误做自动重试重试次数控制在 2 次以内且要加退避间隔。幂等性这是最容易被忽视的。如果模型因为超时重试了一次创建订单的技能结果创建了两个订单那就是事故。所以对于写操作类技能必须做幂等设计。常见做法是让调用方传一个唯一请求 ID服务端根据这个 ID 去重。模型生成请求 ID 不太可靠所以通常由系统在执行层自动注入。提示写操作类技能一定要做幂等读操作类技能可以不做。判断标准是重复执行会不会产生副作用。5. 多技能编排当一件事需要好几个技能配合5.1 串行编排与并行编排的取舍现实任务很少能靠单个技能完成。帮我查一下上周的订单把没发货的挑出来然后给这些订单的客户发提醒——这一句话里至少涉及查询、筛选、通知三个技能。编排方式主要有两种串行一个技能的输出作为下一个技能的输入按顺序执行。适合有依赖关系的任务。上面那个例子就是串行先查订单再筛选再通知。并行多个技能同时执行结果汇总。适合相互独立的任务。比如同时查一下天气、汇率和股价这三个互不依赖并行能省时间。选择哪种取决于技能之间有没有数据依赖。有依赖就必须串行没依赖就尽量并行。但要注意并行执行会带来结果合并的问题多个技能同时返回模型需要能正确区分和处理。我在实际项目里的经验是默认串行确认无依赖再并行。因为串行的调试和错误定位简单得多而并行的性能收益在技能本身耗时不高时并不明显。5.2 让模型自己编排还是用固定流程这是一个架构层面的选择。模型自主编排把可用技能都给模型让它自己决定调用顺序。灵活能处理没预设过的任务组合。但不可控模型可能绕远路也可能在中间步骤出错后不知道怎么回退。固定流程编排针对特定任务预先定义好技能调用顺序模型只在每个步骤内做参数填充。可控稳定但只能处理预设过的任务。我的建议是混合对高频、关键的任务用固定流程保证稳定对长尾、探索性的任务用模型自主编排保证灵活。判断标准是这个任务出错的代价大不大。代价大的走固定流程代价小的放开让模型试。具体实现上固定流程可以用状态机或者工作流引擎来描述每个节点绑定一个技能。模型自主编排则依赖模型的规划能力通常需要配合任务分解的提示策略。5.3 中间结果的传递与状态管理多技能编排时中间结果怎么传是个实际问题。最简单的方式是全部塞回对话上下文让模型自己记住。技能少、步骤短的时候没问题但步骤一多上下文里全是中间结果模型容易被干扰。更稳妥的方式是引入一个会话状态存储。每个技能的输出除了回填给模型还存一份到状态里用键值对管理。后续技能需要前面的结果时从状态里取而不是从对话历史里翻。这样上下文保持精简状态也清晰可查。状态存储要注意生命周期。一次任务结束后相关状态应该清理掉避免污染下一次任务。我一般会给状态加上任务 ID作为命名空间任务结束就整体清除。6. 实测中踩过的坑与排查思路6.1 技能被雪藏模型总是不调用某个技能这是最常见的问题。你明明注册了一个技能描述也写了但模型就是不用它宁可自己瞎编答案。排查思路按顺序来第一步确认技能真的在可用清单里。有时候是动态加载逻辑把它过滤掉了模型根本看不到。打印一下每次决策时传给模型的技能清单一眼就能看出来。第二步检查描述是否覆盖了用户的表达。如果用户说我的包裹呢而你的技能描述是查询订单物流信息模型可能匹配不上。把用户可能的说法补进描述里。第三步看是不是被其他技能抢了。如果有个描述更宽泛的技能模型可能优先选了它。这时候要调整描述让目标技能更显眼。第四步检查系统提示词有没有压制。有时候系统提示词里写了优先使用内置知识回答模型就会倾向于不调技能。这种冲突要排查掉。我遇到过一次特别隐蔽的技能描述里有个错别字导致语义偏移模型一直匹配不上。改掉错别字就好了。所以描述写完一定要通读一遍。6.2 参数总是填错类型、格式、枚举的坑模型填参数出错通常集中在三类类型错误把数字填成字符串把布尔填成true字符串。解决办法是在参数 schema 里写清楚类型并在校验层做自动转换。能转的就转转不了的返回明确错误。格式错误日期格式、手机号格式、ID 格式。这类问题靠 schema 里的pattern约束加上校验层的正则检查。错误信息里要给出正确格式的示例。枚举错误填了不在白名单里的值。这个前面说过返回带选项的错误提示让模型重选。还有一个高频问题是参数来源错误。模型有时候会把上一轮对话里的值填到这一轮或者把用户没提到的值自己编一个。解决办法是在参数描述里强调必须从用户当前消息中提取不得编造。实测这句话能减少不少幻觉参数。6.3 执行成功但模型理解错了结果这个坑比较隐蔽技能明明执行成功了返回了正确数据但模型基于这个数据给出了错误回复。原因通常是返回结构对模型不友好。比如你返回一个嵌套很深的 JSON模型可能读错层级。或者返回字段名是缩写模型猜错含义。解决办法是把返回结果也当成给模型看的接口来设计。字段名用完整单词结构尽量扁平关键信息放在显眼位置。如果数据量大做一层摘要只把模型需要的关键字段给它细节数据放在状态里备用。我一般会在返回结构里加一个summary字段用一句自然语言概括结果比如订单 A123 已发货预计明天送达。模型读这句话比读一堆字段快得多也不容易错。6.4 技能之间的相互干扰当技能多了之后会出现一些奇怪的现象调了 A 技能之后B 技能的行为变了。这通常是共享状态被污染了。比如两个技能都读写同一个全局缓存A 写进去的数据被 B 读到了。或者两个技能用了同一个临时文件路径互相覆盖。排查这类问题关键是给每个技能的执行环境做隔离。共享状态要么加命名空间要么干脆每个技能独立。临时资源用完即清。如果确实需要共享要明确约定读写规则不能各写各的。7. 技能体系的扩展与长期维护7.1 技能版本管理怎么做技能会迭代。今天query_order_status返回三个字段明天可能要加两个。如果直接改正在依赖旧结构的流程就会崩。我的做法是给技能加版本号注册表里同一个技能名可以存在多个版本。新流程用新版本老流程继续用老版本等老流程都迁移完了再下线旧版本。版本号不一定要暴露给模型。模型看到的还是同一个技能名系统在背后根据流程配置决定用哪个版本。这样对模型透明对开发者可控。7.2 技能的可观测性日志、指标、追踪技能跑在背后出问题时如果没日志排查就是盲人摸象。我建议每个技能执行都记录这几样调用时间、技能名、参数脱敏后执行耗时执行结果状态成功/失败/超时失败时的错误类型这些数据积累起来能回答很多问题哪个技能最常失败哪个技能最慢哪个技能被调用的频率异常有了这些优化就有方向。如果技能之间有编排关系还要做链路追踪。给一次任务分配一个追踪 ID所有相关技能调用都带上这个 ID这样能把一次任务的完整执行链路串起来看。7.3 技能数量增长后的治理技能从 10 个涨到 100 个管理方式要变。分类按业务域分组注册表支持按组查询。模型决策时先选组再选技能。去重定期审查技能描述合并功能重叠的。两个技能做同一件事只会让模型困惑。下线不再使用的技能要及时注销。留着不仅占上下文还可能被误调用。权限不同技能对应不同权限级别。敏感技能只对特定角色开放注册表的list_available里做过滤。我见过一个项目技能堆到两百多个没人清理结果模型选择准确率惨不忍睹。后来做了一轮治理砍到八十个准确率立刻回升。技能不是越多越好够用且清晰才是目标。8. 我在这套体系里最看重的几个实践说了这么多最后分享几个我个人在实际操作中体会最深的点都是踩过坑之后总结出来的。第一技能描述值得花大力气打磨。很多人把描述当附属品随便写两句。但实际上描述的质量直接决定整个体系的可用性。我现在的习惯是每写一个技能描述都拿二十句真实用户可能说的话去测看能不能命中。命中率不到八成就继续改。第二错误信息要面向修正而不是报告。同样是失败返回参数错误和返回缺少 order_id请从用户消息中提取后重试效果天差地别。前者让模型卡住后者让模型自愈。这个细节能省掉大量人工干预。第三写操作技能必须幂等。这是底线不是优化项。我见过因为重试导致重复下单的真实案例修复成本远高于一开始就做好幂等。第四技能不是越多越好。每加一个技能模型的决策空间就大一分选错的概率就高一分。加技能之前先问这个能力能不能合并到已有技能里能不能用参数区分而不是新建技能能合就合。第五给技能体系留观测口子。日志和指标不是上线后才补的是一开始就要设计的。没有观测你根本不知道体系在真实环境里表现如何优化也就无从谈起。这套东西说起来不复杂但真正落地时细节决定成败。技能注册、描述打磨、参数校验、错误回传、幂等设计、可观测性每一环都有讲究。把这几环做扎实智能体才能真正从会说变成会做而且做得稳、做得可维护。
1. 从agent-skills这个命名说起它到底指什么第一次看到agent-skills这个词很多人会下意识地把它当成某个具体框架或库的名字。但如果你在工程实践里摸爬滚打过一段时间就会发现它更像是一个概念容器——用来描述智能体agent具备哪些可被调用的能力这件事本身。换句话说它不是一个现成的工具而是一套关于如何给智能体装配技能的设计思路和组织方式。我在实际项目里接触过不少类似命名的东西有的团队把它做成一个技能注册中心有的把它做成一套提示词模板库还有的干脆把它当成一个插件目录。命名相同落地形态却千差万别。这恰恰说明agent-skills这个词的核心不在实现而在抽象层次它站在能力这一层往上承接具体的业务任务往下对接模型调用、工具执行、状态管理等底层机制。那它到底解决什么问题简单说就是让一个智能体不再只会聊天而是能真正干活。一个只会对话的模型你问它天气它只能凭记忆瞎猜但如果你给它装配一个查询天气的技能它就能调用真实接口拿到数据。技能就是智能体从会说到会做之间的那座桥。这篇文章适合谁看如果你正在做智能体相关的应用开发或者你手头有一个需要让模型调用外部能力的场景再或者你只是好奇智能体到底怎么被组织起来干活那这篇内容都能给你一些可以直接参考的东西。我会尽量把抽象的东西讲具体把为什么这么设计讲透而不是只丢一堆名词。需要先说明一点由于原始输入里项目正文、关键词、摘要都是空的下面所有关于实现细节、目录结构、参数配置的内容都是基于我在类似项目中的常见实践做的合理补全。这些不是唯一答案但都是经过验证、能跑通的方案你可以直接拿去改。2. 技能的本质把能力从模型里剥离出来2.1 为什么不能把所有逻辑都塞进提示词很多人做智能体应用的第一反应是把所有规则、所有知识、所有操作步骤全写进系统提示词里。刚开始确实能跑但很快就会撞墙。第一个问题是上下文膨胀。你每加一个能力提示词就长一截。加到十几个能力之后光系统提示词就几千字模型每次调用都要重新读一遍token 成本飙升不说模型对每条规则的注意力还被稀释了。我实测过一个案例当系统提示词从 800 字涨到 4000 字时模型对其中某条关键约束的遵守率从 95% 掉到了 70% 左右。这不是模型变笨了是信息过载。第二个问题是无法执行真实操作。提示词再详细模型也只能描述怎么查数据库不能真的去查。它没有手只有嘴。第三个问题是不可维护。业务逻辑散落在几千字的自然语言里改一个参数要在文本里大海捞针还没法做单元测试。agent-skills这套思路的核心价值就是把这些能力从提示词里剥离出来变成一个个独立、可注册、可调用、可测试的单元。模型只负责决定调用哪个技能、传什么参数具体怎么执行交给技能本身。2.2 一个技能应该包含哪些要素一个设计良好的技能通常包含四个部分我用一个查询订单状态的技能来举例说明要素作用示例名称与描述让模型知道这个技能是干什么的query_order_status根据订单号查询当前物流与支付状态参数定义告诉模型需要提供哪些输入order_id字符串必填、detail_level枚举可选执行逻辑真正干活的代码调用内部订单服务接口解析返回结果返回结构统一输出格式方便模型理解标准化的 JSON包含状态码、消息、数据体这里最关键的是描述和参数定义。模型不是靠读你的代码来决定调不调这个技能的它是靠读描述。所以描述写得好不好直接决定技能被正确调用的概率。我见过太多人把描述写成查询订单结果模型在用户问我买的东西到哪了的时候根本想不起来调它。正确的写法应该覆盖用户可能的表达方式比如查询订单的物流进度、支付状态、预计送达时间。参数定义同样重要。每个参数的类型、是否必填、取值范围、默认值都要写清楚。模型在生成调用参数时这些信息就是它的说明书。参数定义模糊模型就会瞎填。2.3 技能与工具、插件、函数的区别这几个词经常被混用我在不同团队里见过不同的叫法。大致可以这样区分函数function最底层的代码单元纯粹的执行逻辑不包含任何给模型看的元信息。工具tool函数加上给模型看的描述和参数 schema是模型可以直接看到并调用的东西。插件plugin一组相关工具的集合通常还带有生命周期管理、配置注入等能力。技能skill语义上更强调能力这个层面一个技能可能对应一个工具也可能是一组工具的编排。在实际落地时这些概念经常是重叠的。你叫它技能也好工具也好本质都是模型可调用的能力单元。我在文章里统一用技能这个词但你要知道它和工具在多数场景下是可以互换的。理解这一层区别的意义在于当你设计系统时要清楚自己是在定义执行逻辑还是在定义给模型看的接口。这两件事应该分开混在一起就会导致技能既难测试又难被模型正确调用。3. 技能注册与发现让智能体知道自己会什么3.1 注册表是整个体系的中枢技能不会凭空被模型知道。你需要一个注册表registry把所有可用技能集中管理起来。模型在每次决策前会拿到一份当前可用技能清单然后从中选择。这个注册表最简单的形态就是一个字典或者列表每个条目包含技能的名称、描述、参数 schema 和执行入口。复杂一点的会带上权限控制、版本管理、启用开关等。我建议注册表至少支持这几个操作register(skill)注册一个技能unregister(name)注销一个技能list_available(context)根据当前上下文返回可用技能列表get(name)获取某个技能的完整定义其中list_available是精髓所在。不是所有技能在任何场景下都该暴露给模型。比如一个删除数据的技能在只读会话里就不该出现。根据用户身份、会话状态、任务阶段动态筛选可用技能能大幅降低模型选错技能的概率。3.2 技能描述怎么写才能被模型正确选中这是整个体系里最容易被低估的环节。我踩过的坑几乎都集中在这里。先说一个反直觉的结论技能描述不是写给人看的文档是写给模型看的广告。它的目标不是准确而是在正确的时机被正确选中。具体来说好的技能描述要满足三点第一覆盖同义表达。用户说查快递看物流我的包裹呢订单到哪了这些都应该能命中同一个技能。你可以在描述里把这些说法都列出来或者用更抽象的方式概括查询订单相关的物流、配送、签收信息。第二明确边界。如果一个技能只处理已支付订单描述里就要写清楚。否则模型会在用户问未支付订单时也调它然后执行失败。边界写清楚模型才知道什么时候不该用。第三避免描述重叠。如果你有两个技能描述都是查询订单信息模型就会随机选一个。这时候要么合并要么把差异写清楚比如一个查支付状态一个查物流状态。我一般会用一个简单的自测方法把技能描述单独拿出来想象用户可能说的 20 句话看这个描述能不能让人或模型判断出该不该调它。如果判断不了描述就得改。3.3 动态技能加载的两种策略技能不一定一开始就全部加载。有两种常见策略全量加载启动时把所有技能注册进去每次决策都带上完整清单。优点是简单缺点是技能多了之后光技能清单就占掉大量上下文模型选择难度也上升。适合技能数量在 20 个以内的场景。按需加载根据当前任务阶段或用户意图只加载相关技能。比如用户刚进入下单流程就只加载下单相关的技能进入售后流程再切换到售后技能。优点是上下文精简、选择准确缺点是需要一套意图识别或流程管理机制来驱动加载。我在实际项目里更倾向按需加载尤其是技能超过 30 个之后全量加载的准确率下降非常明显。一个折中方案是分组加载把技能按业务域分成若干组先让模型选组再在组内选技能。这样每层的选择空间都小准确率能稳住。4. 技能执行链路从模型决策到真实动作4.1 一次完整的技能调用经历了什么很多人以为模型调用技能是一步完成的其实中间有好几个环节。理解这条链路是排查问题的关键。一次典型的技能调用大致经过这些步骤模型根据当前对话和可用技能清单输出一个结构化的调用意图包含技能名和参数。系统解析这个意图校验技能是否存在、参数是否合法。如果校验通过执行技能逻辑如果不通过把错误信息返回给模型。技能执行结果被序列化成模型能理解的格式回填到对话上下文。模型基于结果继续生成回复或者决定调用下一个技能。这条链路里第 2 步的校验最容易被忽略但恰恰是稳定性的关键。模型生成的参数经常有各种小毛病数字传成字符串、必填项漏填、枚举值拼错。如果不校验直接执行轻则报错重则产生脏数据。我的做法是在校验层做三件事类型转换能转就转比如字符串数字转数字、必填检查、枚举白名单。校验失败时不要直接抛异常给用户而是把具体的错误信息返回给模型让它自己修正参数重试。实测下来模型在拿到明确错误提示后重试成功率很高。4.2 参数校验与错误回传的实操细节这里展开说一下错误回传的写法因为这是很多人做不好的地方。假设模型调用query_order_status时漏了order_id。如果你返回一句参数错误模型大概率会再瞎试一次。但如果你返回调用失败缺少必填参数 order_id。请从用户消息中提取订单号后重新调用。模型就能明白问题在哪并且知道下一步该干什么。错误信息里带上怎么修的提示比单纯说错了有用得多。再比如枚举值错误。模型传了detail_level: full但你的白名单只有basic和detailed。返回调用失败detail_level 的值 full 无效可选值为 basic 或 detailed。模型下次就会从白名单里选。这种带选项的错误提示能显著减少来回次数。还有一个细节错误信息不要暴露内部实现。比如不要返回堆栈信息、数据库字段名、内部服务地址。这些对模型没用还可能泄露敏感信息。错误信息应该面向如何修正调用而不是系统哪里崩了。4.3 超时、重试与幂等性技能执行是真实操作就会有超时和失败。这块处理不好整个智能体就会卡死或者产生重复操作。超时每个技能都应该有超时设置。查询类技能可以短一点比如 5 秒涉及外部服务的可以长一点比如 30 秒。超时后要返回明确的超时信息让模型知道这次没成功可以稍后重试或换方式。重试不是所有失败都该重试。网络抖动导致的失败可以重试参数错误导致的失败重试也没用。我一般只对超时和明确的临时性错误做自动重试重试次数控制在 2 次以内且要加退避间隔。幂等性这是最容易被忽视的。如果模型因为超时重试了一次创建订单的技能结果创建了两个订单那就是事故。所以对于写操作类技能必须做幂等设计。常见做法是让调用方传一个唯一请求 ID服务端根据这个 ID 去重。模型生成请求 ID 不太可靠所以通常由系统在执行层自动注入。提示写操作类技能一定要做幂等读操作类技能可以不做。判断标准是重复执行会不会产生副作用。5. 多技能编排当一件事需要好几个技能配合5.1 串行编排与并行编排的取舍现实任务很少能靠单个技能完成。帮我查一下上周的订单把没发货的挑出来然后给这些订单的客户发提醒——这一句话里至少涉及查询、筛选、通知三个技能。编排方式主要有两种串行一个技能的输出作为下一个技能的输入按顺序执行。适合有依赖关系的任务。上面那个例子就是串行先查订单再筛选再通知。并行多个技能同时执行结果汇总。适合相互独立的任务。比如同时查一下天气、汇率和股价这三个互不依赖并行能省时间。选择哪种取决于技能之间有没有数据依赖。有依赖就必须串行没依赖就尽量并行。但要注意并行执行会带来结果合并的问题多个技能同时返回模型需要能正确区分和处理。我在实际项目里的经验是默认串行确认无依赖再并行。因为串行的调试和错误定位简单得多而并行的性能收益在技能本身耗时不高时并不明显。5.2 让模型自己编排还是用固定流程这是一个架构层面的选择。模型自主编排把可用技能都给模型让它自己决定调用顺序。灵活能处理没预设过的任务组合。但不可控模型可能绕远路也可能在中间步骤出错后不知道怎么回退。固定流程编排针对特定任务预先定义好技能调用顺序模型只在每个步骤内做参数填充。可控稳定但只能处理预设过的任务。我的建议是混合对高频、关键的任务用固定流程保证稳定对长尾、探索性的任务用模型自主编排保证灵活。判断标准是这个任务出错的代价大不大。代价大的走固定流程代价小的放开让模型试。具体实现上固定流程可以用状态机或者工作流引擎来描述每个节点绑定一个技能。模型自主编排则依赖模型的规划能力通常需要配合任务分解的提示策略。5.3 中间结果的传递与状态管理多技能编排时中间结果怎么传是个实际问题。最简单的方式是全部塞回对话上下文让模型自己记住。技能少、步骤短的时候没问题但步骤一多上下文里全是中间结果模型容易被干扰。更稳妥的方式是引入一个会话状态存储。每个技能的输出除了回填给模型还存一份到状态里用键值对管理。后续技能需要前面的结果时从状态里取而不是从对话历史里翻。这样上下文保持精简状态也清晰可查。状态存储要注意生命周期。一次任务结束后相关状态应该清理掉避免污染下一次任务。我一般会给状态加上任务 ID作为命名空间任务结束就整体清除。6. 实测中踩过的坑与排查思路6.1 技能被雪藏模型总是不调用某个技能这是最常见的问题。你明明注册了一个技能描述也写了但模型就是不用它宁可自己瞎编答案。排查思路按顺序来第一步确认技能真的在可用清单里。有时候是动态加载逻辑把它过滤掉了模型根本看不到。打印一下每次决策时传给模型的技能清单一眼就能看出来。第二步检查描述是否覆盖了用户的表达。如果用户说我的包裹呢而你的技能描述是查询订单物流信息模型可能匹配不上。把用户可能的说法补进描述里。第三步看是不是被其他技能抢了。如果有个描述更宽泛的技能模型可能优先选了它。这时候要调整描述让目标技能更显眼。第四步检查系统提示词有没有压制。有时候系统提示词里写了优先使用内置知识回答模型就会倾向于不调技能。这种冲突要排查掉。我遇到过一次特别隐蔽的技能描述里有个错别字导致语义偏移模型一直匹配不上。改掉错别字就好了。所以描述写完一定要通读一遍。6.2 参数总是填错类型、格式、枚举的坑模型填参数出错通常集中在三类类型错误把数字填成字符串把布尔填成true字符串。解决办法是在参数 schema 里写清楚类型并在校验层做自动转换。能转的就转转不了的返回明确错误。格式错误日期格式、手机号格式、ID 格式。这类问题靠 schema 里的pattern约束加上校验层的正则检查。错误信息里要给出正确格式的示例。枚举错误填了不在白名单里的值。这个前面说过返回带选项的错误提示让模型重选。还有一个高频问题是参数来源错误。模型有时候会把上一轮对话里的值填到这一轮或者把用户没提到的值自己编一个。解决办法是在参数描述里强调必须从用户当前消息中提取不得编造。实测这句话能减少不少幻觉参数。6.3 执行成功但模型理解错了结果这个坑比较隐蔽技能明明执行成功了返回了正确数据但模型基于这个数据给出了错误回复。原因通常是返回结构对模型不友好。比如你返回一个嵌套很深的 JSON模型可能读错层级。或者返回字段名是缩写模型猜错含义。解决办法是把返回结果也当成给模型看的接口来设计。字段名用完整单词结构尽量扁平关键信息放在显眼位置。如果数据量大做一层摘要只把模型需要的关键字段给它细节数据放在状态里备用。我一般会在返回结构里加一个summary字段用一句自然语言概括结果比如订单 A123 已发货预计明天送达。模型读这句话比读一堆字段快得多也不容易错。6.4 技能之间的相互干扰当技能多了之后会出现一些奇怪的现象调了 A 技能之后B 技能的行为变了。这通常是共享状态被污染了。比如两个技能都读写同一个全局缓存A 写进去的数据被 B 读到了。或者两个技能用了同一个临时文件路径互相覆盖。排查这类问题关键是给每个技能的执行环境做隔离。共享状态要么加命名空间要么干脆每个技能独立。临时资源用完即清。如果确实需要共享要明确约定读写规则不能各写各的。7. 技能体系的扩展与长期维护7.1 技能版本管理怎么做技能会迭代。今天query_order_status返回三个字段明天可能要加两个。如果直接改正在依赖旧结构的流程就会崩。我的做法是给技能加版本号注册表里同一个技能名可以存在多个版本。新流程用新版本老流程继续用老版本等老流程都迁移完了再下线旧版本。版本号不一定要暴露给模型。模型看到的还是同一个技能名系统在背后根据流程配置决定用哪个版本。这样对模型透明对开发者可控。7.2 技能的可观测性日志、指标、追踪技能跑在背后出问题时如果没日志排查就是盲人摸象。我建议每个技能执行都记录这几样调用时间、技能名、参数脱敏后执行耗时执行结果状态成功/失败/超时失败时的错误类型这些数据积累起来能回答很多问题哪个技能最常失败哪个技能最慢哪个技能被调用的频率异常有了这些优化就有方向。如果技能之间有编排关系还要做链路追踪。给一次任务分配一个追踪 ID所有相关技能调用都带上这个 ID这样能把一次任务的完整执行链路串起来看。7.3 技能数量增长后的治理技能从 10 个涨到 100 个管理方式要变。分类按业务域分组注册表支持按组查询。模型决策时先选组再选技能。去重定期审查技能描述合并功能重叠的。两个技能做同一件事只会让模型困惑。下线不再使用的技能要及时注销。留着不仅占上下文还可能被误调用。权限不同技能对应不同权限级别。敏感技能只对特定角色开放注册表的list_available里做过滤。我见过一个项目技能堆到两百多个没人清理结果模型选择准确率惨不忍睹。后来做了一轮治理砍到八十个准确率立刻回升。技能不是越多越好够用且清晰才是目标。8. 我在这套体系里最看重的几个实践说了这么多最后分享几个我个人在实际操作中体会最深的点都是踩过坑之后总结出来的。第一技能描述值得花大力气打磨。很多人把描述当附属品随便写两句。但实际上描述的质量直接决定整个体系的可用性。我现在的习惯是每写一个技能描述都拿二十句真实用户可能说的话去测看能不能命中。命中率不到八成就继续改。第二错误信息要面向修正而不是报告。同样是失败返回参数错误和返回缺少 order_id请从用户消息中提取后重试效果天差地别。前者让模型卡住后者让模型自愈。这个细节能省掉大量人工干预。第三写操作技能必须幂等。这是底线不是优化项。我见过因为重试导致重复下单的真实案例修复成本远高于一开始就做好幂等。第四技能不是越多越好。每加一个技能模型的决策空间就大一分选错的概率就高一分。加技能之前先问这个能力能不能合并到已有技能里能不能用参数区分而不是新建技能能合就合。第五给技能体系留观测口子。日志和指标不是上线后才补的是一开始就要设计的。没有观测你根本不知道体系在真实环境里表现如何优化也就无从谈起。这套东西说起来不复杂但真正落地时细节决定成败。技能注册、描述打磨、参数校验、错误回传、幂等设计、可观测性每一环都有讲究。把这几环做扎实智能体才能真正从会说变成会做而且做得稳、做得可维护。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
