最近我在整理手头的智能体项目时发现群里聊得最多的词就是 agent-skills。说实话我第一次听到这个词觉得不过是 function calling 换了个写法但等我真的把一个技能从定义、注册、调用到排错完整走了一遍才发现里面的门道比想象中多得多。这篇文章不打算做概念科普我更想从一个开发者的视角聊聊把一个“技能体系”落地到真实业务时踩过的坑和沉淀下来的做法。如果你正准备给智能体做技能库或者正被“模型不知道该调用哪个函数”这类问题困扰那接下来的内容应该能帮你少绕几圈弯路。我会先从 Agent Skills 和工具调用的边界讲起再给出一套可以直接照抄的技能定义模板然后带你看一个从零到一落地的完整案例最后把最容易让人翻车的线上稳定性问题单独拎出来说。文章偏工程向但我会尽量用大白话把每个选择背后的理由讲清楚。1. 先别急着写代码Agent Skills和工具调用的边界到底在哪1.1 从“调函数”到“交付能力”是一次建模思维的转变早期做大模型应用时我们习惯把一堆函数直接塞给模型让模型自己选着调。函数少的时候没什么问题业务一复杂几十个函数堆在一起模型很快就“花眼”了。有的函数参数填错有的函数被用在了完全不该用的场景里更麻烦的是很多函数执行失败后模型根本不知道下一步该怎么办。Agent Skills 之所以被单独提出来不是因为它发明了什么新机制而是它改变了我们建模能力的粒度。一个技能不是“一段可以被模型调用的代码”而是一个完整的、自洽的能力单元。它至少要包含五个部分技能名称和描述、输入参数规范、执行体、成功标准、失败回退方案。这五个部分合在一起才叫技能。如果只是把一个函数连上大模型那叫工具调用不叫技能。我是后来才意识到这层差别的。当时我在做某个内部运营助手最开始把所有接口都直接注册成函数效果一言难尽。后来把每个能力按技能的标准重写了一遍给模型的信息密度、调用准确率和排障效率都明显上升了。这里面最核心的一点是技能本身携带“什么时候该用、什么时候不该用、用完怎么判断结果对不对”的上下文而普通函数只有签名。1.2 技能带来的三个实际收益可观测、可复用、可治理先说可观测。因为技能有明确的入口、出口和结构化返回所以每次调用是成功还是失败、中间走了哪些步骤、耗时多少都能埋点统计。纯函数调用当然也可以埋点但技能定义里天然包含了“预期结果”这让埋点数据可以直接用于质量评估。后来我做技能健康度报表时靠的就是这套埋点。再说可复用。业务里很多能力是通用的比如“解析文档”“查询订单状态”“生成摘要”。如果没有技能层每个智能体项目都会各自写一遍胶水代码。有了技能库之后A 团队做出来的能力B 团队在注册中心里引用一下就能用。听起来简单但真正落地后团队之间少写的重复代码量非常可观。最后是可治理。每个技能都能绑定负责人、版本、调用权限和失败率指标。出问题了可以快速灰度回滚不再需要翻代码、找日志、求着对方团队排查。这一层“治理能力”是函数调用完全给不了的。如果你还在犹豫要不要把现有工具升级成技能体系我的建议是别一步到位先挑两三个高频能力试点感受一下差异再推广。2. 给技能搭骨架我固定用的“四段式”技能定义2.1 第一段技能身份信息也就是给模型看的“脸”技能名要短描述却要足够具体。很多人写技能描述时只写“查询天气”这种描述会让模型在需要查“历史上今天的平均气温”时也把它选上。我常用的写法是第一句说清楚“什么时候用它”第二句说清楚“什么时候不要用它”。举个例子同样是天气技能我更倾向写成查询某个城市未来三天的实时天气预报用于出行前天气确认。不用于历史气候分析不用于空气质量查询不用于降雨量统计。这句话看起来啰嗦但实际效果非常好。因为很多场景下模型的语义检索是靠“技能名描述”来完成的。描述里如果没有限制句模型就会基于自己的模糊理解去匹配经常选错。限制句相当于主动帮模型划清了边界检索命中率一下子就能上来。2.2 第二段输入参数 Schema格式统一永远是稳定器技能成功与否一半在描述另一半在参数设计。我的原则是凡是能用枚举的绝不用自由文本凡是能限制长度的绝不写“任意内容”凡是需要单位的必须在参数描述里写明单位。比如时间参数如果只写start_date: string模型可能给你传2024年1月1日也可能传January 1, 2024执行体还要费力做归一化。正确做法是写清楚{ start_date: { type: string, description: 起始日期格式必须为 YYYY-MM-DD例如 2024-01-01, required: true } }这里的关键不是格式校验逻辑多厉害而是让模型在“生成参数”这一步就减少自由发挥空间。我在实践中发现模型对格式的“创意”远超出预期。有一次一个技能参数要求传省份名称模型直接传了个城市名原因是用户的问题是“杭州天气怎么样”模型觉得传杭州更直接。后来我在技能描述里加了一句“城市参数请使用用户在问题中明确提到的地名”误传率才降下来。2.3 第三段执行体可以是函数也可以是有状态的工作流执行体是整个技能真正干活的部分但它有个原则只负责把输入变成输出不负责决定“自己要不要被调用”。要不要调用是智能体决策层的事情执行体如果擅自做判断会导致行为不可预期。执行体内部需要做三件事。第一前置条件校验比如用户有没有权限、资源存不存在第二执行主逻辑可以是调一个接口也可以编排多个接口第三兜底异常把错误统一转成结构化返回。举个例子一个“查订单”技能如果订单号不存在不能直接抛一个裸异常给模型而应该返回{ status: error, error_code: ORDER_NOT_FOUND, retryable: false, message: 未找到该订单请检查订单号是否正确 }这样模型才能基于结构化信息决定是让用户改参数还是换一个技能。否则模型会凭空想象错误原因用户问“我的订单怎么样了”模型可能胡编一条物流信息。2.4 第四段成功标准与回退方案很多项目把这步省了每定义完一个技能我会强制自己回答两个问题怎样算成功失败后怎么办很多团队把技能的前三段做得很好却把成功标准省了结果模型拿到一个返回体后无法判断该不该继续。我的习惯是让技能返回一个固定结构的 JSON至少包含status、data、error_code、retryable四个字段。status只有三种取值success、error、partial。partial表示部分成功比如“周报生成了但风险数据拉取失败”这时模型可以带提示地把结果交给用户而不是假装全部完成。回退方案要写在技能文档里但不一定要模型理解。比如某个技能连续失败两次决策层就换备选技能如果备选技能也没有就直接给用户一个“当前无法完成”的答复。这套逻辑不是模型自己悟出来的而是技能定义里写死的。没有这层设计智能体就会在一个坏技能上反复重试浪费时间和算力。3. 技能注册与发现让智能体在几百个技能里“挑对东西”3.1 注册中心不是简单存一下还要管版本和权限技能数量一多就必须有个注册中心。你可以在数据库里建一张表也可以在框架里实现一个服务但不管怎么实现至少要记录这些信息技能名、中文名、版本号、入口地址、超时时间、重试策略、调用权限、所属域、标签、负责人。版本管理很容易被忽视。技能不是写一次就不变的业务接口会升级、描述文案会优化如果注册中心不支持多版本并存那每次改动都是捂着鼻子硬上。我现在的做法是每次技能变更都生成新版本旧版本保留至少一个灰度周期。这样如果新描述导致模型乱选技能可以快速回切。权限也很重要。不同角色的智能体应该看到不同的技能集合。比如内部运营助手不应该看到“删除生产环境数据”这种操作型技能。权限不在技能层做就会给模型增加额外负担——它需要自己判断能不能调而这件事模型经常判断错。权限前置到注册中心直接从源头过滤才是真正可靠的方案。3.2 技能发现策略语义召回加规则重排技能发现的核心链路是先召回候选技能再通过规则重排最终把排序结果交给模型决策。纯靠语义检索是不够的因为语义相近、功能不同的技能太多了。比如“按订单号查订单”和“按订单号查物流”两者的语义几乎一样但功能完全不同。我常用的做法是分两步。第一步用向量检索把用户问题映射到技能名的描述空间召回 Top 20 候选。第二步在重排层加规则如果用户问题里包含订单号这个实体就优先把带order_id参数且描述里包含“订单号”的技能排到最前面如果技能描述里明确写了“不用于物流查询”而用户问题里有“物流”“送达”等词就直接过滤掉。这里还有个细节重排规则不要写得太复杂。太复杂的规则自己会成为维护负担而且容易误伤。我的原则是只加三条规则——实体匹配、领域过滤、高频技能加权。其他的交给模型语义理解毕竟重排是辅助不是替代。3.3 技能冲突解决两个技能都能做一件事选哪个技能库最容易出现的问题是功能重叠。有一次我同时上了“按订单号查订单”和“按订单号查物流”两个技能模型选错率非常高因为用户问“我的快递到哪了”时两个技能都看起来相关。后来我总结出一个有效做法在技能描述里显式互斥。物流技能的描述里写清“本技能仅用于查询物流轨迹不包含订单金额、商品清单等信息如需查看订单基本信息请使用按订单号查订单技能”。订单技能同样写反向限制。除了改描述还可以在注册中心维护一组“互斥关系表”。决策引擎在给模型排序前先检查当前已经锁定的技能意图把互斥技能直接过滤掉。这属于规则上的兜底比单纯让模型自己理解更稳。我之前做过统计加了互斥声明之后这两个技能的整体选错率下降了差不多六成。4. 实战把一个“生成项目周报”的技能完整落地4.1 需求拆解这个技能不是简单调一个接口为了让你更直观理解我拿“生成项目周报”来走一遍完整流程。这个技能的需求是给定项目 ID 和时间范围自动生成一份 Markdown 周报内容包括版本控制提交记录、已完成功能、风险提示、下期计划。一开始我把它理解为“调一次接口生成文本”但真正拆解之后发现它需要连续调用好几个不同系统从项目管理平台拿项目进度从版本控制平台拉提交记录再从需求系统汇总条目。也就是说执行体本身就是一个多步骤工作流。这种技能最适合用“技能 小 Agent 工作流”的模式来做也就是技能内部可以再编排若干工具调用而不是死板地只允许一个函数。这样设计的好处是对外部来说它仍然是一个黑盒技能有输入有输出对内部来说它可以复用更多底层原子能力。4.2 技能定义与注册技能定义我用的是下面的 JSON 结构注册到技能中心后就可以被智能体发现{ name: generate_project_weekly_report, version: 1.2.0, description: 汇总指定项目在某一时间范围内的开发进度并生成周报用于项目例会汇报。需要输入项目 ID 和起止日期。不适用于单次提交记录的查询不适用于跨月汇总不可用于生成个人周报。, parameters: { project_id: { type: string, description: 项目唯一标识例如 PROJ-2024-001 }, time_range: { type: enum, enum: [this_week, last_week], description: 周报覆盖范围this_week 表示本自然周last_week 表示上一个自然周 } }, timeout_seconds: 30, retryable: true }注意这里我把时间范围做成了枚举而不是开放日期输入。这个决策是从实际教训里来的。第一版技能允许模型自己传start_date和end_date结果模型经常把用户说的“最近”理解成从当天往前推七天导致周报数据总是错位。改成枚举后模型只需要判断“本周还是上周”歧义瞬间小了很多。在注册中心里我还给这个技能打了两个标签report和project这样后续做管理筛选时方便。负责人填的是“某开发者”权限设置为“仅项目组成员可用”。4.3 执行体逻辑与联调中遇到的问题执行体我用伪代码来表示核心逻辑分成四步。第一步根据project_id校验当前调用者有没有该项目权限避免越权。第二步根据枚举折算成具体日期范围调版本控制平台接口拉提交记录。第三步把提交记录按“修复”“功能”“文档”等关键词分类。第四步把所有内容拼成 Markdown 返回。function generate_report(project_id, time_range): check_permission(project_id) date_range resolve_date_range(time_range) commits git_service.list_commits(project_id, date_range) grouped classify_commits(commits) risks risk_service.get_risks(project_id, date_range) return render_markdown(grouped, risks)联调时遇到的第一个问题不是权限也不是接口而是模型把“本自然周”理解成了“过去一周”。后来我在枚举值描述里写得更详细“this_week 代表自然周周一到周日即使今天是周三也只取周一至今的数据”。改了描述之后问题就消失了。这个案例让我深刻理解了一句话很多大模型问题不是模型能力问题而是信息表达问题。4.4 上线之后的效果观测这个技能上线后的前两周我一直盯着调用日志。第一周整体成功率在 78% 左右主要失败原因是模型把time_range传错或者明明没有project_id却调用技能。我把参数描述和技能描述又优化了一版第二周成功率就爬到了 97%无效调用降了差不多六成。这里说的“无效调用”包括模型在用户没有提供项目 ID 时就尝试用空值调用以及把“生成周报”理解成“生成日报”。这些都不是执行体代码问题而是技能定义问题。所以后来我养成了一个习惯技能上线前先用五六十条模拟用户问题做一轮“选择测试”看看模型会不会选错技能、传错参数。这种测试成本很低但效果非常好。5. 上线之后真正折磨人的是这四件事鉴权、超时、并发、上下文污染5.1 鉴权永远不要把密钥交给模型技能定义里最容易出现的安全隐患就是把 API Key、Token 直接写进技能描述或参数里。表面上看方便但模型一旦把密钥拼进日志、返回给用户或者被 Prompt 注入引导输出后果很严重。我的原则是技能执行体在运行时统一使用智能体框架提供的身份凭证技能内部如果需要调用外部服务由运行时注入短期 Token而不是让模型在参数里传。技能参数里也严禁出现token、key、secret这类字段。对于外部付费服务还要在运行时做预算控制。比如某个技能每调用一次要花一定费用就给这个技能设置每分钟调用上限、每日消耗上限。超过上限后技能直接拒绝执行不让模型在用户面前反复尝试。这些控制逻辑离模型越远越好做到执行体层甚至网关层。5.2 超时和重试宁可快速失败也不让用户无限等待智能体技能调用的最大隐性风险是超时。一个大模型对话本身可能只需要几秒如果技能里再嵌套一个外部接口外部接口响应慢整个体验就会变得不可接受。我在每个技能定义里都会写明确超时时间默认 10 秒。超过时间后执行体返回status: error、error_code: TIMEOUT、retryable: true。决策引擎看到retryable才会决定重试而且重试必须有退避策略。最简单的做法是第一次失败后等 1 秒再试第二次等 3 秒最多重试两次。我曾经吃过一次亏某个技能内部调用了外部接口外部接口超时设置是 30 秒结果整个智能体响应要两分钟。用户早就放弃了模型还在那儿傻等。后来我把所有技能的外部调用都包了一层带超时控制的客户端统一把超时压到 5 秒以内。快速失败比慢速成功更有利于智能体体验。5.3 并发技能不是单机脚本技能上线初期调用量小很多人会忽略并发问题。等接入的智能体多了同一个技能可能同时被上百个请求打进来。如果技能的底层接口不支持高并发连接池会被打爆然后就是连锁失败。注册中心里最好配置max_concurrency字段超过上限的请求先排队或者直接返回status: busy。我遇到过的最严重事故是某个“文档解析”技能同时被多个 Agent 调用底层解析服务超负荷最后连健康检查都挂了。从那以后我所有技能都做了并发上限并且把“不可并发执行”写在技能描述里让决策层看到繁忙状态时自动换其他方案。还有一种情况是技能之间有依赖。比如“先生成周报再发送到群聊”这两个技能如果都由模型独立选择中间状态很容易丢失。我的建议是有依赖关系的多个技能要包成一个工作流技能由执行体内部编排而不是让模型自己一个个调。5.4 上下文污染技能返回值会把整个对话带偏技能的返回值会注入到模型的上下文中直接影响模型后续的每一个判断。如果技能返回一个 200KB 的 JSON里面有大量无关字段模型不仅处理不过来还可能把不该看的字段当成答案输出。我的习惯是技能返回给模型的数据只保留决策必需的信息尽量控制在 2KB 以内。如果底层数据确实大比如接口返回了几百条记录那就在执行体里先做聚合摘要再把摘要返回给模型。原始数据可以单独存起来给用户提供下载链接或后续翻页技能而不是硬塞给模型。在这个问题上我用一张表格整理了常见故障和对应策略方便排查故障现象根本原因解决策略模型把技能错误信息当业务答案技能缺少结构化错误码返回statuserror_code模型重复调用同一种技能返回值太长模型没看出关键状态执行体做摘要只返回关键字段技能超时导致对话卡死外部接口超时未包裹统一 5 秒超时快速失败多个技能互相干扰返回内容混入无关数据技能层裁剪输出限制 2KB模型选错相似技能描述缺少互斥声明在描述中显式排除边界场景上下文污染是那种“平时不觉得一出事就是大事”的问题。因为它不报错只是让模型回答越来越离谱。我排查过最久的一个问题最后发现是某个技能返回了一个remark字段里面写着内部备注模型直接把这个备注当成了对用户的答复。从那以后我对技能返回字段做了一票否决式审查凡是不会参与决策的字段一律不返回。6. 技能数量多了之后怎么评估和维护一套不失控的技能库6.1 用四个指标判断技能健康度技能库和代码库一样会随着时间腐化。如果不管早晚会变成一座没人敢动的屎山。我每周都会给技能库跑一次健康度报表核心看四个指标调用准确率模型在需要某能力时是否选对了技能。执行成功率技能自身是否成功跑完包括依赖的外部接口。结果采纳率返回结果被智能体真正用于回答用户的比例。无效暴露率不该出现的场景里技能是否被模型误选和误调。这四个指标的计算需要提前埋点。每次技能被召回、被选择、被执行、被采纳都要有日志。没有埋点后面的优化就是拍脑袋。如果某个技能的调用准确率连续两周下降我会先看是不是最近新增了相似技能抢了流量如果执行成功率低再看底层接口是不是不稳定如果结果采纳率低很可能是模型执行成功但结果不是它想要的这时候要检查技能返回结构与用户需求的匹配度。无效暴露率高则说明技能的边界描述还不够清楚。6.2 版本管理和 AB 实验改描述也是改代码技能升级不一定要动代码改描述本身就是一种很常见的变更。比如把“查天气”改成“查未来三天实时天气不用于历史分析”不用改执行体但效果可能比改代码还明显。这也意味着技能描述应该像代码一样走评审和版本管理。我现在的流程是任何技能变更哪怕只改一个标点都必须生成新版本号并在变更记录里写明原因。高风险技能可以走灰度新版本只对 10% 的请求生效对比新旧版本的成功率和选择率确认没问题再全量。有一次我改了一个“周报生成”技能的描述把可选参数改成了必填枚举结果执行成功率上升但同时模型调用这个技能的次数也暴增。原因是描述里的“生成周报”太吸引模型了用户随便说一句“帮我写总结”模型就会选它。后来我在描述里加了一个下限“仅当用户明确要求生成项目周报时才使用”调用次数才回归正常。所以每次描述变更不只要看成功率还要看覆盖率。6.3 定期清理“僵尸技能”该删就删技能库最大的敌人不是质量差而是历史遗留。很多技能业务下线了但注册信息还在。语义检索时这些僵尸技能仍然会被召回轻则让模型多一次无谓筛选重则直接选错。我现在每季度做一次僵尸技能清理。标准很简单过去九十天没有任何成功调用记录或者调用成功率极低且连续三周没有好转就进入待删除清单。删除之前会走一次评审确认没有其他 Agent 还在引用然后先下线、再删除。比删除更提前一步的是“准入限制”。我给自己定了个规矩每次迭代只允许新增两三个技能同时必须删除同等数量的旧技能。这样做是逼着自己认真做技能整合而不是无限膨胀。一个健康的技能库宁可数量少一点也要每个技能边界清楚、调用可靠。6.4 团队协作里的几条硬约定当技能库变成多人维护的东西之后比技术更麻烦的是规范和沟通。我这里是这么约定的所有技能名统一用“领域_对象_动作”的格式比如project_weekly_report_generate描述第一句写适用场景第二句写不适用边界每个技能必须有明确的负责人没有负责人的技能不允许被注册。技能变更默认走评审不是直接改完就上线。评审的时候不光看执行体逻辑还要看一段“模型视角测试记录”也就是用几个典型提问先跑一遍证明新描述不会让模型误用。这个动作在很多人看来有点繁琐但它真的能拦住大多数问题。我在实际做技能库维护时最强烈的感受是所有规范最终都在回答一个问题——“三个月后一个新开发者能凭技能描述理解它为什么存在吗”如果答案是能这个技能大概率不会变成团队的心智负担如果答案是不确定那就说明技能定义还不够成熟最好先别注册。最后说点我私人的习惯。我现在每次定义新技能都会先问自己一句这个技能是让模型更省心还是让模型更困惑如果答案是后者我宁可把它拆掉或者干脆不做。技能体系的本质是给模型的决策能力做加法而不是给它的上下文做减法。希望这篇内容能帮你少踩几个坑。
最近我在整理手头的智能体项目时发现群里聊得最多的词就是 agent-skills。说实话我第一次听到这个词觉得不过是 function calling 换了个写法但等我真的把一个技能从定义、注册、调用到排错完整走了一遍才发现里面的门道比想象中多得多。这篇文章不打算做概念科普我更想从一个开发者的视角聊聊把一个“技能体系”落地到真实业务时踩过的坑和沉淀下来的做法。如果你正准备给智能体做技能库或者正被“模型不知道该调用哪个函数”这类问题困扰那接下来的内容应该能帮你少绕几圈弯路。我会先从 Agent Skills 和工具调用的边界讲起再给出一套可以直接照抄的技能定义模板然后带你看一个从零到一落地的完整案例最后把最容易让人翻车的线上稳定性问题单独拎出来说。文章偏工程向但我会尽量用大白话把每个选择背后的理由讲清楚。1. 先别急着写代码Agent Skills和工具调用的边界到底在哪1.1 从“调函数”到“交付能力”是一次建模思维的转变早期做大模型应用时我们习惯把一堆函数直接塞给模型让模型自己选着调。函数少的时候没什么问题业务一复杂几十个函数堆在一起模型很快就“花眼”了。有的函数参数填错有的函数被用在了完全不该用的场景里更麻烦的是很多函数执行失败后模型根本不知道下一步该怎么办。Agent Skills 之所以被单独提出来不是因为它发明了什么新机制而是它改变了我们建模能力的粒度。一个技能不是“一段可以被模型调用的代码”而是一个完整的、自洽的能力单元。它至少要包含五个部分技能名称和描述、输入参数规范、执行体、成功标准、失败回退方案。这五个部分合在一起才叫技能。如果只是把一个函数连上大模型那叫工具调用不叫技能。我是后来才意识到这层差别的。当时我在做某个内部运营助手最开始把所有接口都直接注册成函数效果一言难尽。后来把每个能力按技能的标准重写了一遍给模型的信息密度、调用准确率和排障效率都明显上升了。这里面最核心的一点是技能本身携带“什么时候该用、什么时候不该用、用完怎么判断结果对不对”的上下文而普通函数只有签名。1.2 技能带来的三个实际收益可观测、可复用、可治理先说可观测。因为技能有明确的入口、出口和结构化返回所以每次调用是成功还是失败、中间走了哪些步骤、耗时多少都能埋点统计。纯函数调用当然也可以埋点但技能定义里天然包含了“预期结果”这让埋点数据可以直接用于质量评估。后来我做技能健康度报表时靠的就是这套埋点。再说可复用。业务里很多能力是通用的比如“解析文档”“查询订单状态”“生成摘要”。如果没有技能层每个智能体项目都会各自写一遍胶水代码。有了技能库之后A 团队做出来的能力B 团队在注册中心里引用一下就能用。听起来简单但真正落地后团队之间少写的重复代码量非常可观。最后是可治理。每个技能都能绑定负责人、版本、调用权限和失败率指标。出问题了可以快速灰度回滚不再需要翻代码、找日志、求着对方团队排查。这一层“治理能力”是函数调用完全给不了的。如果你还在犹豫要不要把现有工具升级成技能体系我的建议是别一步到位先挑两三个高频能力试点感受一下差异再推广。2. 给技能搭骨架我固定用的“四段式”技能定义2.1 第一段技能身份信息也就是给模型看的“脸”技能名要短描述却要足够具体。很多人写技能描述时只写“查询天气”这种描述会让模型在需要查“历史上今天的平均气温”时也把它选上。我常用的写法是第一句说清楚“什么时候用它”第二句说清楚“什么时候不要用它”。举个例子同样是天气技能我更倾向写成查询某个城市未来三天的实时天气预报用于出行前天气确认。不用于历史气候分析不用于空气质量查询不用于降雨量统计。这句话看起来啰嗦但实际效果非常好。因为很多场景下模型的语义检索是靠“技能名描述”来完成的。描述里如果没有限制句模型就会基于自己的模糊理解去匹配经常选错。限制句相当于主动帮模型划清了边界检索命中率一下子就能上来。2.2 第二段输入参数 Schema格式统一永远是稳定器技能成功与否一半在描述另一半在参数设计。我的原则是凡是能用枚举的绝不用自由文本凡是能限制长度的绝不写“任意内容”凡是需要单位的必须在参数描述里写明单位。比如时间参数如果只写start_date: string模型可能给你传2024年1月1日也可能传January 1, 2024执行体还要费力做归一化。正确做法是写清楚{ start_date: { type: string, description: 起始日期格式必须为 YYYY-MM-DD例如 2024-01-01, required: true } }这里的关键不是格式校验逻辑多厉害而是让模型在“生成参数”这一步就减少自由发挥空间。我在实践中发现模型对格式的“创意”远超出预期。有一次一个技能参数要求传省份名称模型直接传了个城市名原因是用户的问题是“杭州天气怎么样”模型觉得传杭州更直接。后来我在技能描述里加了一句“城市参数请使用用户在问题中明确提到的地名”误传率才降下来。2.3 第三段执行体可以是函数也可以是有状态的工作流执行体是整个技能真正干活的部分但它有个原则只负责把输入变成输出不负责决定“自己要不要被调用”。要不要调用是智能体决策层的事情执行体如果擅自做判断会导致行为不可预期。执行体内部需要做三件事。第一前置条件校验比如用户有没有权限、资源存不存在第二执行主逻辑可以是调一个接口也可以编排多个接口第三兜底异常把错误统一转成结构化返回。举个例子一个“查订单”技能如果订单号不存在不能直接抛一个裸异常给模型而应该返回{ status: error, error_code: ORDER_NOT_FOUND, retryable: false, message: 未找到该订单请检查订单号是否正确 }这样模型才能基于结构化信息决定是让用户改参数还是换一个技能。否则模型会凭空想象错误原因用户问“我的订单怎么样了”模型可能胡编一条物流信息。2.4 第四段成功标准与回退方案很多项目把这步省了每定义完一个技能我会强制自己回答两个问题怎样算成功失败后怎么办很多团队把技能的前三段做得很好却把成功标准省了结果模型拿到一个返回体后无法判断该不该继续。我的习惯是让技能返回一个固定结构的 JSON至少包含status、data、error_code、retryable四个字段。status只有三种取值success、error、partial。partial表示部分成功比如“周报生成了但风险数据拉取失败”这时模型可以带提示地把结果交给用户而不是假装全部完成。回退方案要写在技能文档里但不一定要模型理解。比如某个技能连续失败两次决策层就换备选技能如果备选技能也没有就直接给用户一个“当前无法完成”的答复。这套逻辑不是模型自己悟出来的而是技能定义里写死的。没有这层设计智能体就会在一个坏技能上反复重试浪费时间和算力。3. 技能注册与发现让智能体在几百个技能里“挑对东西”3.1 注册中心不是简单存一下还要管版本和权限技能数量一多就必须有个注册中心。你可以在数据库里建一张表也可以在框架里实现一个服务但不管怎么实现至少要记录这些信息技能名、中文名、版本号、入口地址、超时时间、重试策略、调用权限、所属域、标签、负责人。版本管理很容易被忽视。技能不是写一次就不变的业务接口会升级、描述文案会优化如果注册中心不支持多版本并存那每次改动都是捂着鼻子硬上。我现在的做法是每次技能变更都生成新版本旧版本保留至少一个灰度周期。这样如果新描述导致模型乱选技能可以快速回切。权限也很重要。不同角色的智能体应该看到不同的技能集合。比如内部运营助手不应该看到“删除生产环境数据”这种操作型技能。权限不在技能层做就会给模型增加额外负担——它需要自己判断能不能调而这件事模型经常判断错。权限前置到注册中心直接从源头过滤才是真正可靠的方案。3.2 技能发现策略语义召回加规则重排技能发现的核心链路是先召回候选技能再通过规则重排最终把排序结果交给模型决策。纯靠语义检索是不够的因为语义相近、功能不同的技能太多了。比如“按订单号查订单”和“按订单号查物流”两者的语义几乎一样但功能完全不同。我常用的做法是分两步。第一步用向量检索把用户问题映射到技能名的描述空间召回 Top 20 候选。第二步在重排层加规则如果用户问题里包含订单号这个实体就优先把带order_id参数且描述里包含“订单号”的技能排到最前面如果技能描述里明确写了“不用于物流查询”而用户问题里有“物流”“送达”等词就直接过滤掉。这里还有个细节重排规则不要写得太复杂。太复杂的规则自己会成为维护负担而且容易误伤。我的原则是只加三条规则——实体匹配、领域过滤、高频技能加权。其他的交给模型语义理解毕竟重排是辅助不是替代。3.3 技能冲突解决两个技能都能做一件事选哪个技能库最容易出现的问题是功能重叠。有一次我同时上了“按订单号查订单”和“按订单号查物流”两个技能模型选错率非常高因为用户问“我的快递到哪了”时两个技能都看起来相关。后来我总结出一个有效做法在技能描述里显式互斥。物流技能的描述里写清“本技能仅用于查询物流轨迹不包含订单金额、商品清单等信息如需查看订单基本信息请使用按订单号查订单技能”。订单技能同样写反向限制。除了改描述还可以在注册中心维护一组“互斥关系表”。决策引擎在给模型排序前先检查当前已经锁定的技能意图把互斥技能直接过滤掉。这属于规则上的兜底比单纯让模型自己理解更稳。我之前做过统计加了互斥声明之后这两个技能的整体选错率下降了差不多六成。4. 实战把一个“生成项目周报”的技能完整落地4.1 需求拆解这个技能不是简单调一个接口为了让你更直观理解我拿“生成项目周报”来走一遍完整流程。这个技能的需求是给定项目 ID 和时间范围自动生成一份 Markdown 周报内容包括版本控制提交记录、已完成功能、风险提示、下期计划。一开始我把它理解为“调一次接口生成文本”但真正拆解之后发现它需要连续调用好几个不同系统从项目管理平台拿项目进度从版本控制平台拉提交记录再从需求系统汇总条目。也就是说执行体本身就是一个多步骤工作流。这种技能最适合用“技能 小 Agent 工作流”的模式来做也就是技能内部可以再编排若干工具调用而不是死板地只允许一个函数。这样设计的好处是对外部来说它仍然是一个黑盒技能有输入有输出对内部来说它可以复用更多底层原子能力。4.2 技能定义与注册技能定义我用的是下面的 JSON 结构注册到技能中心后就可以被智能体发现{ name: generate_project_weekly_report, version: 1.2.0, description: 汇总指定项目在某一时间范围内的开发进度并生成周报用于项目例会汇报。需要输入项目 ID 和起止日期。不适用于单次提交记录的查询不适用于跨月汇总不可用于生成个人周报。, parameters: { project_id: { type: string, description: 项目唯一标识例如 PROJ-2024-001 }, time_range: { type: enum, enum: [this_week, last_week], description: 周报覆盖范围this_week 表示本自然周last_week 表示上一个自然周 } }, timeout_seconds: 30, retryable: true }注意这里我把时间范围做成了枚举而不是开放日期输入。这个决策是从实际教训里来的。第一版技能允许模型自己传start_date和end_date结果模型经常把用户说的“最近”理解成从当天往前推七天导致周报数据总是错位。改成枚举后模型只需要判断“本周还是上周”歧义瞬间小了很多。在注册中心里我还给这个技能打了两个标签report和project这样后续做管理筛选时方便。负责人填的是“某开发者”权限设置为“仅项目组成员可用”。4.3 执行体逻辑与联调中遇到的问题执行体我用伪代码来表示核心逻辑分成四步。第一步根据project_id校验当前调用者有没有该项目权限避免越权。第二步根据枚举折算成具体日期范围调版本控制平台接口拉提交记录。第三步把提交记录按“修复”“功能”“文档”等关键词分类。第四步把所有内容拼成 Markdown 返回。function generate_report(project_id, time_range): check_permission(project_id) date_range resolve_date_range(time_range) commits git_service.list_commits(project_id, date_range) grouped classify_commits(commits) risks risk_service.get_risks(project_id, date_range) return render_markdown(grouped, risks)联调时遇到的第一个问题不是权限也不是接口而是模型把“本自然周”理解成了“过去一周”。后来我在枚举值描述里写得更详细“this_week 代表自然周周一到周日即使今天是周三也只取周一至今的数据”。改了描述之后问题就消失了。这个案例让我深刻理解了一句话很多大模型问题不是模型能力问题而是信息表达问题。4.4 上线之后的效果观测这个技能上线后的前两周我一直盯着调用日志。第一周整体成功率在 78% 左右主要失败原因是模型把time_range传错或者明明没有project_id却调用技能。我把参数描述和技能描述又优化了一版第二周成功率就爬到了 97%无效调用降了差不多六成。这里说的“无效调用”包括模型在用户没有提供项目 ID 时就尝试用空值调用以及把“生成周报”理解成“生成日报”。这些都不是执行体代码问题而是技能定义问题。所以后来我养成了一个习惯技能上线前先用五六十条模拟用户问题做一轮“选择测试”看看模型会不会选错技能、传错参数。这种测试成本很低但效果非常好。5. 上线之后真正折磨人的是这四件事鉴权、超时、并发、上下文污染5.1 鉴权永远不要把密钥交给模型技能定义里最容易出现的安全隐患就是把 API Key、Token 直接写进技能描述或参数里。表面上看方便但模型一旦把密钥拼进日志、返回给用户或者被 Prompt 注入引导输出后果很严重。我的原则是技能执行体在运行时统一使用智能体框架提供的身份凭证技能内部如果需要调用外部服务由运行时注入短期 Token而不是让模型在参数里传。技能参数里也严禁出现token、key、secret这类字段。对于外部付费服务还要在运行时做预算控制。比如某个技能每调用一次要花一定费用就给这个技能设置每分钟调用上限、每日消耗上限。超过上限后技能直接拒绝执行不让模型在用户面前反复尝试。这些控制逻辑离模型越远越好做到执行体层甚至网关层。5.2 超时和重试宁可快速失败也不让用户无限等待智能体技能调用的最大隐性风险是超时。一个大模型对话本身可能只需要几秒如果技能里再嵌套一个外部接口外部接口响应慢整个体验就会变得不可接受。我在每个技能定义里都会写明确超时时间默认 10 秒。超过时间后执行体返回status: error、error_code: TIMEOUT、retryable: true。决策引擎看到retryable才会决定重试而且重试必须有退避策略。最简单的做法是第一次失败后等 1 秒再试第二次等 3 秒最多重试两次。我曾经吃过一次亏某个技能内部调用了外部接口外部接口超时设置是 30 秒结果整个智能体响应要两分钟。用户早就放弃了模型还在那儿傻等。后来我把所有技能的外部调用都包了一层带超时控制的客户端统一把超时压到 5 秒以内。快速失败比慢速成功更有利于智能体体验。5.3 并发技能不是单机脚本技能上线初期调用量小很多人会忽略并发问题。等接入的智能体多了同一个技能可能同时被上百个请求打进来。如果技能的底层接口不支持高并发连接池会被打爆然后就是连锁失败。注册中心里最好配置max_concurrency字段超过上限的请求先排队或者直接返回status: busy。我遇到过的最严重事故是某个“文档解析”技能同时被多个 Agent 调用底层解析服务超负荷最后连健康检查都挂了。从那以后我所有技能都做了并发上限并且把“不可并发执行”写在技能描述里让决策层看到繁忙状态时自动换其他方案。还有一种情况是技能之间有依赖。比如“先生成周报再发送到群聊”这两个技能如果都由模型独立选择中间状态很容易丢失。我的建议是有依赖关系的多个技能要包成一个工作流技能由执行体内部编排而不是让模型自己一个个调。5.4 上下文污染技能返回值会把整个对话带偏技能的返回值会注入到模型的上下文中直接影响模型后续的每一个判断。如果技能返回一个 200KB 的 JSON里面有大量无关字段模型不仅处理不过来还可能把不该看的字段当成答案输出。我的习惯是技能返回给模型的数据只保留决策必需的信息尽量控制在 2KB 以内。如果底层数据确实大比如接口返回了几百条记录那就在执行体里先做聚合摘要再把摘要返回给模型。原始数据可以单独存起来给用户提供下载链接或后续翻页技能而不是硬塞给模型。在这个问题上我用一张表格整理了常见故障和对应策略方便排查故障现象根本原因解决策略模型把技能错误信息当业务答案技能缺少结构化错误码返回statuserror_code模型重复调用同一种技能返回值太长模型没看出关键状态执行体做摘要只返回关键字段技能超时导致对话卡死外部接口超时未包裹统一 5 秒超时快速失败多个技能互相干扰返回内容混入无关数据技能层裁剪输出限制 2KB模型选错相似技能描述缺少互斥声明在描述中显式排除边界场景上下文污染是那种“平时不觉得一出事就是大事”的问题。因为它不报错只是让模型回答越来越离谱。我排查过最久的一个问题最后发现是某个技能返回了一个remark字段里面写着内部备注模型直接把这个备注当成了对用户的答复。从那以后我对技能返回字段做了一票否决式审查凡是不会参与决策的字段一律不返回。6. 技能数量多了之后怎么评估和维护一套不失控的技能库6.1 用四个指标判断技能健康度技能库和代码库一样会随着时间腐化。如果不管早晚会变成一座没人敢动的屎山。我每周都会给技能库跑一次健康度报表核心看四个指标调用准确率模型在需要某能力时是否选对了技能。执行成功率技能自身是否成功跑完包括依赖的外部接口。结果采纳率返回结果被智能体真正用于回答用户的比例。无效暴露率不该出现的场景里技能是否被模型误选和误调。这四个指标的计算需要提前埋点。每次技能被召回、被选择、被执行、被采纳都要有日志。没有埋点后面的优化就是拍脑袋。如果某个技能的调用准确率连续两周下降我会先看是不是最近新增了相似技能抢了流量如果执行成功率低再看底层接口是不是不稳定如果结果采纳率低很可能是模型执行成功但结果不是它想要的这时候要检查技能返回结构与用户需求的匹配度。无效暴露率高则说明技能的边界描述还不够清楚。6.2 版本管理和 AB 实验改描述也是改代码技能升级不一定要动代码改描述本身就是一种很常见的变更。比如把“查天气”改成“查未来三天实时天气不用于历史分析”不用改执行体但效果可能比改代码还明显。这也意味着技能描述应该像代码一样走评审和版本管理。我现在的流程是任何技能变更哪怕只改一个标点都必须生成新版本号并在变更记录里写明原因。高风险技能可以走灰度新版本只对 10% 的请求生效对比新旧版本的成功率和选择率确认没问题再全量。有一次我改了一个“周报生成”技能的描述把可选参数改成了必填枚举结果执行成功率上升但同时模型调用这个技能的次数也暴增。原因是描述里的“生成周报”太吸引模型了用户随便说一句“帮我写总结”模型就会选它。后来我在描述里加了一个下限“仅当用户明确要求生成项目周报时才使用”调用次数才回归正常。所以每次描述变更不只要看成功率还要看覆盖率。6.3 定期清理“僵尸技能”该删就删技能库最大的敌人不是质量差而是历史遗留。很多技能业务下线了但注册信息还在。语义检索时这些僵尸技能仍然会被召回轻则让模型多一次无谓筛选重则直接选错。我现在每季度做一次僵尸技能清理。标准很简单过去九十天没有任何成功调用记录或者调用成功率极低且连续三周没有好转就进入待删除清单。删除之前会走一次评审确认没有其他 Agent 还在引用然后先下线、再删除。比删除更提前一步的是“准入限制”。我给自己定了个规矩每次迭代只允许新增两三个技能同时必须删除同等数量的旧技能。这样做是逼着自己认真做技能整合而不是无限膨胀。一个健康的技能库宁可数量少一点也要每个技能边界清楚、调用可靠。6.4 团队协作里的几条硬约定当技能库变成多人维护的东西之后比技术更麻烦的是规范和沟通。我这里是这么约定的所有技能名统一用“领域_对象_动作”的格式比如project_weekly_report_generate描述第一句写适用场景第二句写不适用边界每个技能必须有明确的负责人没有负责人的技能不允许被注册。技能变更默认走评审不是直接改完就上线。评审的时候不光看执行体逻辑还要看一段“模型视角测试记录”也就是用几个典型提问先跑一遍证明新描述不会让模型误用。这个动作在很多人看来有点繁琐但它真的能拦住大多数问题。我在实际做技能库维护时最强烈的感受是所有规范最终都在回答一个问题——“三个月后一个新开发者能凭技能描述理解它为什么存在吗”如果答案是能这个技能大概率不会变成团队的心智负担如果答案是不确定那就说明技能定义还不够成熟最好先别注册。最后说点我私人的习惯。我现在每次定义新技能都会先问自己一句这个技能是让模型更省心还是让模型更困惑如果答案是后者我宁可把它拆掉或者干脆不做。技能体系的本质是给模型的决策能力做加法而不是给它的上下文做减法。希望这篇内容能帮你少踩几个坑。
编程任务完整落地指南：从需求拆解到提交避坑全流程)
