写代码这事儿最怕的不是逻辑复杂而是什么都从零开始。前阵子给一个智能体项目做功能扩展核心模块本身不复杂真正耗时的是那些围绕主流程的周边能力查天气、算时间、调API、处理文件格式。每加一个新需求都要在主流程里堆代码很快就乱成一锅粥。后来我把这些能力全部重构成独立的技能模块整个项目才变得清爽起来。这篇就聊聊我整理agent-skills这套技能层的心得从设计原则到落地实现再到测试维护全是实操经验。1. 技能层设计的核心思路为什么非拆不可1.1 先理解技能到底是什么在智能体项目里技能不是一个抽象概念它就是一段可以被动态加载、按需调用的代码单元。你可以把它理解为手机的App——主系统是操作系统技能就是装在里面的应用。想看天气就打开天气App想算账就打开计算器App操作系统本身不需要关心这些应用怎么实现只需要提供统一的调用入口。我最早犯的错就是把技能直接写成主流程里的函数。需求少的时候还好一旦技能数量上到二三十个问题就全冒出来了代码互相引用改一个功能牵连一片想加新功能得读懂整个主流程测试的时候只能整体跑根本定位不了具体是哪个环节出的问题。重构之后我才真正体会到技能层最重要的价值不是把代码拆开而是把变化隔离。主流程只关心技能能不能用不关心技能怎么实现。这样主流程就稳定了新技能的加入和旧技能的替换都不会影响核心逻辑。1.2 拆技能的几个判断标准我一般按三个标准来划分技能边界。第一是调用来源如果一段功能会被多个不同的上层逻辑调用那它大概率应该独立成技能。第二是变更频率经常变动的功能比如第三方API的策略调整应该独立成技能这样改的时候不用动主流程。第三是故障隔离会出问题的功能比如网络请求、文件解析独立成技能后就算它挂了主流程还有机会兜底而不是跟着一起崩。一个经常被忽略的点是技能的粒度控制。拆太细技能之间要频繁传数据调用开销大管理也烦拆太粗每个技能都干一堆事复用性又差。我现在的经验是一个技能应该像一个功能完整的服务对外暴露尽量少的接口内部可以复杂但外部要简单。比如处理文档是一个技能内部可以包含读取、解析、格式化多个步骤但对外就一个方法。1.3 技能层的整体架构这套架构的核心是把技能当成插件来管理。每个技能都是独立的文件或目录有自己的实现和元数据。主系统维护一个注册表记录所有可用技能的名称、路径、依赖关系和版本信息。当主流程需要某个能力时它不直接写技能代码而是通过一个标准接口去调用。这样做的好处是技能层的边界非常清晰。主流程、技能调度器、技能实现三者各司其职依赖关系和通信方式都有严格约束。后面对接新能力、替换旧实现甚至把技能扩展成其他语言都是在不影响整体框架的前提下进行的。2. 核心细节拆解一个标准技能是怎么做出来的2.1 技能描述文件的结构一个标准的技能不管内部用什么语言实现我都建议先有一个描述文件。这个文件记录了技能的核心信息名字、版本、描述、作者、依赖。我用的是JSON格式因为解析简单也方便后续接入各种工具链。{ name: skill-weather, version: 1.2.0, description: 查询实时天气支持国内主要城市, author: dev-ops-team, entry: weather.js, parameters: { city: { type: string, required: true, description: 城市名称如 北京 }, days: { type: integer, required: false, default: 1, description: 预报天数 } } }这个文件最核心的部分是parameters。它声明了技能需要哪些入参、参数类型、是否必填、默认值。为什么这个部分这么重要因为技能调用方不用去读技能的实现代码只看这个描述文件就知道应该传什么参数、会得到什么结果。这就让技能和调用方之间形成了一种松耦合的关系——双方只需要对这个描述文件达成一致。2.2 技能的代码实现模板每个技能内部我统一用同一个模板来写。这个模板对格式的要求比对内容更严格这样后面做统一测试、统一日志、统一错误处理都会很方便。// weather.js import { SkillBase } from agent/skill-core; export default class WeatherSkill extends SkillBase { constructor(context) { super(context); this.name skill-weather; this.version 1.2.0; } async validate(params) { if (!params.city || typeof params.city ! string) { throw new Error(参数 city 必须为非空字符串); } return true; } async execute(params) { const city params.city; const days params.days || 1; const data await this.context.httpClient.get(/api/v1/weather, { params: { city, days } }); return { code: 0, data: data.data, }; } async cleanup() { // 释放资源、断开连接等 } }这套实现有几个关键细节。validate方法是第一道防线参数不对就直接抛出异常不进业务逻辑。execute是技能的主干所有业务逻辑都放这里。cleanup是兜底的清理方法比如技能内部开了数据库连接或者占用了临时文件执行完之后必须释放。我见过太多项目只写execute结果技能一多内存和连接句柄就开始泄漏排查起来极其痛苦。2.3 技能接口设计的几个坑接口设计是技能层最容易出问题的地方这里我有几个亲身的教训。第一个坑是返回值格式不统一。有的技能返回数组有的返回对象有的返回字符串调用方就得写一堆判断逻辑。我现在的做法是统一返回一个结构业务数据放在 data 字段里错误信息放在 error 字段里status 标记成功或失败。这样就算某个技能内部出了错调用方也能在解析结果的第一时间拿到错误信息不用去猜。第二个坑是错误码的随意定义。每个技能都自己定义一套错误码排查问题的时候同样的错误在不同技能里有不同编号非常痛苦。我最后统一了一套错误码规范权限类错误、参数类错误、外部服务异常、未知错误都有固定编号段新技能接入时必须按这套规范来。第三个坑是同步和异步的混乱。有些技能是同步函数有些技能是异步的调用方还要自己判断。包括 JS 这类异步友好的语言也建议统一用 Promise 包装所有技能都按异步方式调用。这样主流程里可以统一使用 await 或 then不需要关心底层技能是同步还是异步。3. 技能的注册、加载与调用打通整条链路3.1 技能注册表的设计技能装好了得有地方记录它们。注册表就是这套机制的管理中心。我设计注册表的核心数据结构时关注三块信息技能的基本元数据、技能的加载状态未加载/加载中/已就绪/异常、以及技能之间的依赖顺序。{ skills: { skill-weather: { version: 1.2.0, status: ready, dependencies: [], lastLoadedAt: 2024-06-18T10:00:00Z }, skill-doc-processor: { version: 0.9.0, status: ready, dependencies: [skill-file-parser], lastLoadedAt: 2024-06-18T10:00:00Z } } }依赖关系的处理是注册表里最需要注意的部分。比如文档处理技能依赖文件解析技能如果文件解析技能没加载成功文档处理技能就不能被标记为就绪。我在加载阶段会做依赖拓扑排序保证父依赖先加载。如果有循环依赖直接报错不让系统进入运行状态。3.2 技能的动态加载机制技能的加载有两种方式启动时全量和运行时按需。全量加载的好处是简单坏处是启动慢、内存占用高按需加载的好处是资源利用效率高坏处是第一次调用有延迟而且加载失败的场景需要更精细的错误处理。我的做法是折中方案核心技能启动时全量加载非核心技能按需加载。每个技能加载后会被缓存再次调用时不用重复加载性能损耗只在第一次。加载技能本质上就是把代码文件读进来注册到运行时环境。如果是 JS/TS 技术栈我推荐用原生的动态导入机制加载路径必须白名单化禁止用拼接路径去加载任意文件。我在白名单里只放了技能标准目录下的文件路径这样即使有人传入恶意路径也找不到目标文件。3.3 标准调用流程从入参到结果技能加载完毕后调用一个技能的整体流程是这样的调用方拿到技能名和参数调度器去注册表查这个技能是否存在存在就检查参数是否合法然后执行技能逻辑。这个过程有几个环节是必须要做好的。入参校验是第一步如果参数不符合描述文件的声明直接抛错根本不用进入技能内部。这一步能拦截大量低级错误比如少传参数、类型不匹配。校验通过后技能进入执行阶段执行期间所有日志会被打上这个技能专属的标识方便后续检索。执行完成后无论是成功还是失败返回值必须是统一格式而且失败也要有明确的错误码和错误信息。3.4 技能间通信与数据传递的约定技能不是完全隔离的孤岛它们之间有时候也需要协作。比如文档处理技能可能让文件解析技能帮它提取原始数据。技能间的通信我规定只能用调度器来中转禁止技能之间直接互相调用模块。这样做的目的是保持依赖关系的可视化出了问题时可以理清楚数据是从哪里流向哪里。技能间的数据传递格式也有强制约定用 JSON 序列化字段名统一用驼峰命名复杂对象不要直接传引用传序列化后的字符串。这个约定的好处是就算两个技能后续用不同语言重写它们之间的通信方式也不会受影响。4. 技能测试与评估质量保障怎么做才靠谱4.1 单技能测试每个技能都要有体检报告每个技能在开发阶段就要有一套基本的测试用例。单技能测试我分三层单元测试、集成测试、模拟演练。单元测试聚焦技能内部的纯逻辑部分比如参数校验、数据处理输入输出都是模拟数据不依赖真实环境。集成测试则是把技能接到模拟的外部服务上比如用脚手架模拟天气 API 返回固定数据验证技能正确解析和使用返回值。模拟演练是更高一层的验证用真实的调用流程去跑但外部依赖全部用可重复的 mock目的是测试整个调用链路的稳定性。测试要过的指标我一般看这几个维度参数校验覆盖率、异常分支覆盖率、超时处理的正确性、返回格式的一致性。这些指标会存在每个技能的存档里后续改代码时用来判断有没有引入回归问题。4.2 多技能联动测试局部对不代表整体对单技能测试过了不代表整个系统跑得通。多技能联动测试关注的是技能间的协作是否正常。最典型的场景是 A 技能调用 B 技能B 返回格式变了或者两个技能同时去争同一个外部服务导致资源竞争。联动测试里我踩过最多的坑是超时传导。主流程调技能 A技能 A 调技能 BB 因为外部服务故障卡住了结果 A 也没设置自己的超时时间整个调用链被一个底层故障拖垮。后来我给每个技能都设了独立的超时上限并且强制要求技能在调用其他技能时要把子调用的超时时间压缩到父调用超时时间的一半以内。这样就算最底层出了问题错误也能逐层向上传播并快速中止。4.3 技能评估的核心维度准确率、耗时、稳定性技能的评估不光是看测没测过还要看好不好用。我这套评估体系有四个核心指标。第一个是准确率。这个最直接返回的结果和预期结果对比完全一致才算对。第二个是耗时。技能的平均耗时、P95 耗时得有个基线超过阈值就要排查是不是有性能瓶颈。第三个是稳定性。跑一百次有多少次是成功的这个成功率低于 99% 的技能我都不会让它进入生产环境。第四个是资源消耗。内存占用、CPU 占用如果一个技能跑一次就吃掉大量内存哪怕功能正确也不合格。这几个指标会定期统计形成趋势图。我发现很多性能问题不是突然出现的而是一点点累积的比如第三方 API 响应越来越慢、本地缓存命中率下降。定期评估能提前发现这类问题。5. 常见问题与排查技巧实录5.1 技能加载失败的原因往往不在技能本身有一次某个新技能在注册表里始终显示异常状态单测跑也没问题日志也没报错。排查了半天才发现技能目录下有个翻译文件编码是 GBK加载器解析它时直接抛异常而这个异常被外层代码吞掉了所以表现成技能加载失败但日志里什么都没记录。后来我给加载器加了一个铁规任何加载异常必须如实记录包括异常类型、异常信息、堆栈、是哪个文件导致的。并且加载失败时不能只标记状态要同步把失败原因存下来方便后面直接查看。5.2 调用技能时心累的参数格式地狱多个技能联调时最常遇到的问题是我觉得我传对了但技能觉得我传错了。比如文档处理技能要求filePath是绝对路径调用方传了相对路径天气查询技能要求city是中文名调用方传了拼音。这类问题靠人肉排查效率极低。我的解决办法是在技能描述文件里增加一个examples字段把常用调用示例直接写在描述里。然后在技能代码的validate方法里对每个参数不光做类型校验还做格式预检。比如city参数一旦传入先过一个城市名称库检查不在库里就抛出带提示的错误信息直接告诉调用方支持的格式是什么样的。5.3 技能执行时的隐形炸弹外部服务故障技能依赖第三方服务时外部服务一挂技能也跟着挂。有一段时间我频繁收到某个技能超时的告警查日志发现是第三方天气接口的某个节点响应特别慢。后来我做了三件事第一第三方接口的调用统一走一个带超时控制的 HTTP 客户端超时时间默认 3 秒内部服务之间的调用最长不超过 5 秒。第二加了失败缓存即外部服务偶发失败时直接返回上一次成功的数据用短暂的数据滞后换取稳定性。第三实现了熔断机制某个第三方接口连续失败超过五次就自动停止调用五分钟而不是每次都去尝试连一个明显有问题的服务白白浪费等待时间。这三招配合起来技能的超时率下降了非常多。特别是熔断机制它在尖峰故障时保护了整个系统的稳定性不拖累其他技能和主流程。5.4 技能性能问题的排查思路如果你发现某个技能越来越慢先别急着加机器有几个方向值得查。第一步是看外部依赖。第三方 API 响应时间有没有变化是不是对方加了新的限流策略这些用日志就能看到。第二步是看数据量。技能处理的数据是不是越来越多如果入参的文件变大了处理逻辑没优化慢是必然的。第三步是看缓存。缓存命中率降低了没有如果缓存策略设计不合理每次都回源那慢就是正常的。定位到瓶颈后再做针对性优化。我遇到过一个文件解析技能特别慢怎么查都找不到原因最后发现是它内部用了递归解析文件层级一深就把调用栈给打爆了改成迭代之后性能立刻恢复正常。6. 部署与监控上了生产之后的这些坑6.1 技能包版本管理的玩法技能是独立迭代的每个技能都有自己的版本号。版本号的规则我采用的是语义化版本主版本号不兼容改动时加一次版本号加了新功能且向后兼容时加一补丁版本号修 bug 时加一。升级技能时最怕的是隐式升级——某个技能从 1.0 升到 1.1描述文件里改了某个参数的行为但调用方完全不知道。为了解决这个问题我在技能描述文件里加了一个breakingChanges字段每次不兼容变更都必须写明影响范围。这样的话调用方升级技能前可以明确知道哪些地方可能需要调整而不是等上了生产才发现接口行为变了已经开始报错了。6.2 生产环境的日志规范与追踪方案技能的运行日志如果格式不统一出了问题根本没法查。我给所有技能定了一套标准日志格式技能名、版本、请求ID、执行时间、执行状态、耗时、错误码。每个字段都有固定位置日志系统可以按这些字段来做统计和检索。日志里最容易被忽略的信息是上下文关联。一次用户请求可能会触发多个技能调用如果每个技能的日志里没有共同的请求ID排查时候就得靠时间戳去猜哪几行日志是同一批请求产生的。所以我在调用链路的入口处生成一个请求ID后续所有技能调用都带上这个ID日志检索时直接按请求ID过滤效率高很多。6.3 给技能加监控指标时需要重点关注的核心项上了生产环境后我给每个技能都加了几个核心监控指标调用量、成功率、平均耗时、P95耗时、错误分布、资源占用。这些数据通过生产环境的监控系统采集后直接画成趋势图。其中我建议重点关注 P95 耗时而不是平均耗时。平均耗时容易被极端值掩盖P95 能真实反映大多数用户遇到的情况。有一次某个技能平均耗时看着很正常但 P95 已经明显超标查下来发现是有少量请求走到了一个很慢的外部服务节点平均耗时被那些正常请求给稀释了。要是只看了平均值就会错过这个隐患。监控告警的阈值设置也要合理。告警太灵敏会被频繁误报最后大家都麻木了太迟钝又起不到作用。我的经验是先收集一周的基线数据按基线的两倍设置告警阈值等系统稳定后逐步收紧。7. 技能扩展与生态化的进阶玩法7.1 怎么让技能可以被别人使用技能体系成熟后你就有了一个可以对外扩展的能力库。这时候要考虑的不是怎么再写一个技能而是怎么让其他人也能贡献技能。我会提供一个技能开发的脚手架新技能可以直接基于这个模板生成自动包含描述文件、代码模板、测试用例、日志格式。同时提供一套校验工具提交技能前先自动检查格式是否符合规范、参数是否完备、测试是否通过。这样就算不熟悉整套体系的人也能快速写出符合标准的技能。7.2 技能组合的高阶玩法把技能当积木搭技能体系的终极目标是搭积木。一个技能本身解决一个问题很多业务场景其实需要多个技能协同完成。比如我做过一个自动生成日报的场景它实际上是数据查询、文本生成、格式转换和消息推送这几个技能的组合。主流程不用关心每个技能的细节只需要定义好调用顺序和前后数据的传递关系。这种组合能力有一个前提技能之间的接口必须足够稳定。我一直都说接口设计是技能体系中最关键的部分比实现本身更重要。因为单独一个技能可以通过内部代码保证正确性但组合起来的正确性完全取决于接口能否在变化中保持契约的稳定。接口一旦不稳定上层组合逻辑就得跟着改积木就搭不起来了。7.3 踩过这些坑之后的几点感悟整个技能体系从设计到落地我最大的感受就是约定比代码更重要。代码只是把约定固化下来真正让体系跑通的是大家共同遵守的那些规则返回值统一、错误码一致、日志格式规范、依赖关系清晰。有了这些约定哪怕你换一套编程语言来写某个技能整个体系照样能运转。第二点是渐进式重构。如果你现在有一个跑着的项目别想着一次重构成技能体系那太冒险了。我的建议是先把新功能按技能方式去设计然后逐个把旧功能迁移成技能。每次迁移都有测试兜底风险可控体系也能随着业务的发展逐步完善。还有一个经验是技能不是越多越好。技能库膨胀比代码库膨胀更可怕。每个技能都要维护、测试、监控都是有成本的。我定期清理技能库把使用率极低、功能重复的技能合并或下线。保留核心常用的几个技能比堆一大堆半死不活的脚本有用得多。