做 AI 应用的朋友应该都有过这种经历Demo 阶段什么都好说模型选好、Prompt 写顺功能就能跑起来。真往生产环境一搬最先出问题的往往不是模型本身而是模型周围那一堆越来越失控的能力模块。HagiCode Skill 系统要解决的正是这一团乱麻里最容易被低估的部分——AI 技能管理。所谓 Skill你可以理解为 Agent 能调用的能力单元它比单纯的 function/tool 多了一层描述、约束和生命周期管理。HagiCode Skill 系统的核心目标是让团队在技能数量从个位数涨到上百个时依然能清楚地知道每个技能能干什么、该什么时候被调用、被谁调用、出了事怎么回滚。这篇文章不打算讲概念直接拆这套系统背后的数据模型、注册链路、装载机制以及我实际搭建和运维中踩过的五类坑。不管你是打算自研 Agent 平台还是想把手头的技能调用过程规范化这些设计思路都能直接抄作业。1. 为什么 Agent 需要一套独立的技能管理抽象层1.1 能力一多系统就开始脏起来大多数 Agent 项目的演化路径惊人地相似第一版内置三五个工具函数代码里一个 dispatch 搞定模型按参数调用清晰得很。等业务方开始提需求加个查库存的加个根据用户画像推荐的加个自动生成报表的工具函数很快从 5 个涨到 50 个。于是你开始面临几个非常现实的问题。第一提示词里塞不下那么多工具描述了。按常见模型 API 的设计每个工具定义平均消耗几百 token50 个工具就是上万 token光工具列表就把上下文窗口占掉一大半留给真实对话和推理的空间寥寥无几。第二工具之间的边界开始模糊。查库存和查订单详情可能都要订单号推荐算法和用户画像查询可能都要调同一个数据接口命名和描述稍不一致模型就会在多个候选工具之间犹豫甚至产生误调用。第三发布和回滚变成了噩梦。某个工具改了内部逻辑影响面波及所有调用它的场景你根本说不清到底有多少 Prompt 间接依赖它。这些问题的根源在于工具被当作函数看待而不是当作产品来管理。函数只需要参数和返回值而一个可扩展、可运营的能力单元需要身份信息、调用约束、依赖关系、版本记录和权限边界。这正是 HagiCode Skill 系统引入独立抽象层的直接原因——把能力本身变成一等公民。1.2 技能和工具不是一回事我得先把概念掰清楚因为日常沟通里这两个词经常被混用这会导致后续设计时思路跑偏。工具Tool/Function是一条机械的调用通道输入固定参数执行固定逻辑返回结构化结果。它适合在代码层面被精确引用但在模型驱动的场景里光有通道是不够的模型并不知道什么时候该走这条通道。技能Skill则是一个完整的、带自我描述的能力封装它除了包含可执行的逻辑还必须包含触发条件、适用场景、受用边界、依赖资源和版本信息。用生活里的例子来说工具像一把螺丝刀技能则是一整套使用说明 适用场景 维护记录 保修政策的作业包。这个差异决定了系统设计的走向。如果你只是把工具列表塞给模型那工作落到写清 description就结束了但如果你意识到 Agent 的能力是围绕技能来组织的就会进一步思考技能描述如何被检索、技能执行时能接触哪些数据、技能升级后旧行为如何兼容、一个技能能否依赖另一个技能。HagiCode 的架构里所有模块都围绕技能生命周期来设计代码库里的工具函数反而是最末端的执行细节。1.3 独立抽象层带来的四个直接收益把技能管理抽象出来不是多了一层复杂度而是用这一层复杂度换取了四个实打实的收益。第一模型侧的上下文可控。有了技能仓库和动态装载机制系统不再需要把全部技能定义塞进 Prompt而是根据当前会话意图先检索候选技能再按预算注入上下文占用可以压缩到原来的几分之一。第二工程侧的可独立发布。每个技能都有独立版本号可以单独测试、灰度、上线或回滚工作流互相不阻塞这对多团队协作尤其重要。第三治理侧的权限收敛。技能执行时会声明自己需要的数据和操作范围平台统一做授权校验而不是让每个 Prompt 都去拼访问控制逻辑。第四运营侧的行为可观测。每个技能都有调用埋点、耗时统计和成功率记录这些数据反过来又能用于优化技能描述和调度策略。换句话说独立抽象层不是为了炫技而是让系统在复杂度上升时依然保持可解释、可管控。接下来我按一条主链路来拆解这套系统的具体实现从技能仓库的数据模型开始到注册中心与加载链路再到执行沙箱和运维观测。2. 技能仓库的数据模型从 manifest 到运行时上下文2.1 manifest 是技能的身份证一个技能进入系统首先要提交一份 manifest 文件——它是技能的静态描述相当于身份证。HagiCode Skill 系统的 manifest 最早只设计了四五个字段后来在实践中逐步补到了十几项。下面这份是从真实使用里沉淀出的精简版结构我用 YAML 呈现name: order_query version: 1.3.0 title: 订单查询 description: | 仅用于查询订单状态和物流信息。 当用户询问我的订单到哪了发货没有物流进度时使用。 不适用于修改订单、退款、申请发票。 entry: type: http endpoint: https://internal-api.example/agent/order/query method: POST parameters: order_id: type: string required: true description: 订单编号通常为 18 位数字 permissions: scope: order:read allow_network: true env_vars: [ORDER_SERVICE_TOKEN] dependencies: skills: [user_identity_resolve] tags: [commerce, order, logistics] maintainer: team-commerce这里每个字段都有它的存在理由。name是全局唯一标识所有注册、调用、审计都以它为准version是语义化版本号兼容性判断全靠它description是给模型看的调用说明书它的质量直接决定调度准确率下一节我会单独展开entry声明技能的执行入口HagiCode 支持 HTTP 端点、本地函数和容器镜像三类入口方便不同技术栈的团队接入permissions是安全边界技能不能自己声明能访问什么它只能提出需求真正授权由平台管理员审批dependencies声明技能之间的依赖关系比如查询订单前需要先解析用户身份这个字段会被注册中心用来构建调用依赖图。2.2 description 的质量直接影响模型会不会调用在 Skill 系统里description不是给人看的注释而是模型做路由决策时的核心依据。它的质量高低直接决定了技能会不会被正确调用。我踩过最典型的一个例子某个技能描述写的是处理用户相关操作结果模型在用户问天气时也调用了它白白浪费一次请求还返回了无用信息。后来我们把描述改成了仅当用户已登录且请求涉及个人订单、收藏、优惠券时使用天气、新闻等公共信息请勿调用误调用率立刻降了一大截。经过几轮调优我总结出高质量技能描述的三个要点。一是明确触发条件正面说清楚什么情况下调用最好给出典型用户问法的示例。二是明确不适用场景反面列举禁止调用的情况这能有效抑制模型的好奇心。三是控制长度单条描述控制在 150 字以内因为描述越长检索和解析的成本越高而且模型对长描述的注意力集中在开头部分关键信息要前置。值得强调的是技能描述必须版本化。每次调整描述相当于调整了整个系统的路由逻辑线上表现可能因此变化所以描述文件的修改也要走技能版本更新流程而不是随手改掉。2.3 运行时上下文与技能装载预算技能仓库里的技能数量一多就面临一个物理约束上下文窗口有限不可能把所有技能定义都塞进每一轮对话。HagiCode 的做法是把技能装载变成一个受控的预算分配过程。系统预先配置一个技能上下文预算比如 3000 token。每次发起模型请求前调度器先做检索把用户当前对话内容与所有技能的 description 做匹配选出候选集。如果候选集总量超出预算按相关度分数从高到低排序截断到预算内如果某些技能在之前几轮已经没被用到会优先淘汰。这样就保证了上下文里永远只出现与当前任务最相关的技能定义而不是全部技能的大杂烩。这个机制在实践里有一个容易被忽略的收益技能再多也不会显著拖慢请求响应时间。我们内部曾经把技能数量从 30 个涨到 120 个只要装载预算不变平均首字延迟基本没有波动。检索阶段多出来的毫秒级开销远小于把 120 个技能描述都塞进 Prompt 造成的数百甚至上千 token 的成本。3. 注册中心与加载链路可扩展性的核心枢纽3.1 注册不是存个表那么简单很多团队说到技能注册理解为往数据库里插一条记录就完了。HagiCode 早期也这么干过但很快发现不做校验的注册机制会让线上环境变成垃圾场。现在的注册流程分五步格式校验、Schema 版本检查、依赖解析、冲突检查、发布生效。格式校验是最基本的确保 manifest 结构合法、字段类型正确。Schema 版本检查则是为了兼容演进——manifest 的字段会不断增加老版本技能不能被新系统错误解析所以每个 manifest 都要声明schema_version由平台决定用哪个解析器处理它。依赖解析要验证技能声明的依赖是否真实存在、版本是否兼容比如技能声明依赖user_identity_resolve的 1.x 版本注册中心会拒绝把依赖版本指向已被下架的 0.9。冲突检查是这几步里最有价值的一环。两个技能如果 name 重复直接拒绝如果 description 的语义高度重叠系统会用向量相似度做一个提示要求提交者确认意图。这是为了从源头上减少模型在相似技能之间端水的情况。最后才是发布此时技能状态从草稿变成已发布但还要等调度器轮询到新状态或者主动刷新缓存后才真正对外生效。技能的生命周期状态也不是只有在/不在两种。HagiCode 的每个技能都处在草稿、测试、已发布、下架、退役这五个状态之一。下架和退役的区别很重要下架的技能不再被新会话调度但已产生的历史日志和审计记录仍保留可查退役则意味着彻底清除运行时资源连审计信息之外的一切都可移除。这种设计能让平台在演进过程中始终清楚哪些技能还能用、哪些已经没了。3.2 发现与注入查询策略的取舍技能装载的前提是发现也就是从技能仓库里找出当前会话可能需要的候选技能。HagiCode 提供了三种发现策略实际使用时会组合起来。第一种是关键词倒排索引适合命名规范、意图明确的技能。比如用户提到退款就直接匹配到refund_apply这类名字里带 ref 或 refund 的技能。这种方案快、省资源但对描述写得不规范的情况无能为力。第二种是向量语义检索把所有技能的 description 向量化再用用户当前的对话内容进行相似度检索。它擅长处理描述和用户表达不完全一致的情况比如我的东西买错了想退回去也能命中退款技能。第三种是规则白名单适用于平台级别的强制路由比如某些技能只允许在特定流程中被调用不经语义检索直接注入。实际运行中我倾向于把三种策略串起来先用关键词和规则做一次粗筛再用向量检索做精排最后按预算截断。这样既保证了高优先级技能的稳定曝光又不会让语义检索把候选集冲得太大。3.3 沙箱隔离与权限边界技能要被模型调度执行但执行环境绝不能和主服务裸奔在一起。HagiCode 的沙箱设计遵循一个原则技能代码默认不信任。每个技能执行时都被限制在独立的进程或容器内只有通过入口声明暴露的接口才能与主服务通信。权限边界是整个隔离模型里最容易被忽视的部分。很多平台把权限做成了技能自己声明要什么就给什么这等于让被审计的人自己设计审计规则等于没做。HagiCode 的做法是双层授权技能在 manifest 里的permissions只是请求管理员在后台审批后才真正授予。授权粒度细化到三个维度数据访问范围、外部网络访问、可读取的环境变量。 比如订单查询技能申请了order:read和ORDER_SERVICE_TOKEN管理员只批这两个权项即便技能代码里写着读用户手机号运行时也会被强制拦截。这种边界带来的直接好处是安全事故的爆炸半径被压小了。曾经有一次某技能依赖的第三方库被上报有漏洞我们做的第一件事不是改代码而是先看它的授权范围发现它根本没有外网访问权之后修复的优先级就被大幅下调。3.4 扩展点设计让平台不只有一套玩法谈到可扩展很多系统的做法是尽量多写配置项但技术解析到这里我想强调一个更根本的取舍扩展性应该来自明确的扩展点而不是无限枚举配置。HagiCode 把扩展点设计在技能生命周期的关键事件上。具体来说平台在技能执行前、执行后、注册时、下架时各留了一组钩子hook。比如执行前钩子可以做参数改写或流控检查执行后钩子可以做结果缓存或日志抽样。钩子的实现方式支持两种本地函数和远程 Webhook团队可以根据技能所在的位置就近选择。这样做之后新需求大多数时候只需要写一个钩子实现不需要改调度器主流程代码。另外还有一层扩展是路由策略的扩展。不同业务方可能希望同一技能在不同项目里有不同的排序权重或可见范围平台就把路由策略本身做成了可插拔的接口。目前系统里内置了按相关度、按业务优先级、按成本优先三套默认策略需要更复杂的策略时团队可以直接在接口上实现自定义策略类注册进调度器即可。技能数量一旦上百这种平台只提供骨架、玩法由业务方注入的设计正是它能保持长期可用性的关键。4. 实战中绕不开的五类坑冲突、权限、长度、评测与回滚4.1 技能冲突同名、同意图、同调用优先级技能一多最常遇到的问题是两个技能抢同一个活儿。常见场景是业务线 A 和业务线 B 各自提交了查库存的技能描述高度相似模型在两者之间端水一会儿调 A、一会儿调 B下游数据口径都对不上。排查这类问题不能靠肉眼 review 描述。我们在注册中心接入了语义相似度检查每次新技能提交注册时自动和所有已发布技能算一遍向量相似度超过 0.85 就直接提醒与某技能高度相似请确认意图边界。对于相似度在 0.7 到 0.85 之间的会强制要求提交者在描述里写明与既有技能的使用分界。但技术手段解决不了所有冲突剩下那部分靠的是路由显式化。如果两个技能确实都无法舍弃平台允许在调度规则里做硬路由指定某些技能只在特定意图或特定项目下生效。这个功能相当于给模型划定了一条明确的分界线牺牲一点灵活性换取确定性。4.2 权限越界技能拿到了不该拿的上下文技能执行时的数据可见范围是另一个实际运维中反复出问题的点。早期的实现里技能执行器直接把整个会话上下文对象传给了技能函数本意是图省事结果任何技能都能从上下文里读到用户手机号、历史对话里的敏感信息甚至系统指令片段。我们后来改成显式上下文裁剪技能执行器只把 manifest 里声明的参数和授权范围内的数据传给技能代码。会话级上下文被隔离在调度器内部技能代码根本拿不到完整对象。同时加了一层脱敏管道如果技能确实需要用户手机号做查询那它拿到的是脱敏后的版本只有获得额外授权才会返回明文。这个坑的教训可以总结成一句话技能执行时的数据可见面应该等于该技能的最小必要面句号。权限放大一时爽出事后悔都来不及。4.3 上下文过长技能描述把 Prompt 挤爆了技能描述写得详细是好事但所有团队都会经历一个误区每个技能都写满几百字的描述结果候选技能一多Prompt 被技能定义占掉大头用户对话反而被压缩。特别是在模型输入按 token 计费的场景下这直接变成一笔冤枉钱。HagiCode 的做法我上一节讲过是给技能装载加预算上限。落到具体落地有几个参数值得参考单条技能描述建议不超过 150 字单次请求注入技能数不超过 8 个技能上下文总预算不超过模型上下文窗口的 15%。这个比例是我们拿内部真实请求做的统计——绝大多数会话真正调用的技能不超过 3 个超过 8 个基本上都出现了无效候选。预算机制上线后还有一个副作用团队开始被迫精简技能描述。因为描述写得再长超预算时照样被截断还不如把最核心的触发条件写精练。这是一种用约束逼质量的设计。4.4 评测困难怎么知道技能确实有用没有评测体系的技能管理平台是不完整的。很多团队在技能上线时只看调用了没有却不看该不该被调用导致误调用率居高不下。HagiCode 建立了一套基于回归集的路由评测机制这块可能是整篇里最值得带回去参考的实践。回归集里的每条样本都是一条真实对话记录标注了当时应该命中哪个技能以及实际命中了哪个技能。评测时离线跑一遍检索和路由算出三个关键指标调用准确率该调的调对了、误调用率不该调的却调了、召回率该调的都找出来了。注意准确率和召回率的分母不同——准确率的分母是实际调用的次数召回率的分母是应该调用的次数。这两个指标合起来看才能判断一个技能描述是太贪心召回高但准确低还是太保守准确高但召回低。这个回归集的建设一定要趁早。我们在技能数量只有十几个的时候就开始人工标注每个技能攒了四五十条样本等到技能多了之后再扩充新样本基数已经在事情就好办得多。真等线上出了误调用事故再来补标注数据质量和信心都会受影响。4.5 回滚困难升级之后行为漂移技能升级后行为变化是版本管理里最隐蔽的坑。表面上看version从 1.2 升到 1.3调用规则没变参数没变一切应该照旧。但实际跑起来下游服务质量抖动、返回结果格式微调、甚至依赖服务切换了鉴权方式各种连锁反应都可能在升级后冒出来。HagiCode 给每个技能都保留了完整的版本快照包含 manifest、实现代码的镜像标识、依赖解析结果。发布新版本时不直接替换现网流量而是先走金丝雀把少量请求路由到新版本观察路由评测指标的波动。一旦发现行为漂移超过阈值随时一键回滚到旧版本。这里有个细节值得注意回滚必须连同技能的注册信息一起回滚只把代码切回去、manifest 里还写着新版本号会在下一次依赖解析时造成混乱。现在我把这套回滚机制看成是技能状态应该像数据库迁移一样可管理。每一次变更都有记录、有验证、有回退路径平台规模越往上走这一点越值钱。5. 从零到一落地搭建路径与实践心法5.1 MVP 三件套先跑通如果你的团队也想搭一套类似的技能管理平台我强烈建议不要一开始就照搬完整架构。HagiCode 的第一版非常朴素只包含三样东西一个技能清单 JSON 文件、一个调度函数、一个技能执行函数。技能清单放在配置文件里调度函数先做关键词匹配再加一个简单的 TF-IDF 排序执行函数直接调用本地方法。这三件套跑通之后再逐步演进到 manifest 独立存储、注册中心、沙箱隔离、评测回归集。演进路线应该跟着痛点走发现描述冲突了就加语义注册检查发现技能读取越权了就加权限模型发现线上行为无法追溯就加版本快照。初期过度设计反而会拖慢验证节奏。5.2 分批迁移与灰度策略已经跑起来的 Agent 系统要怎么平滑迁移到技能管理平台上我建议按被动优先、主动随后的顺序分批来。先把内部被调用性质的工具函数迁进来它们的调用链路简单迁移风险低等团队熟悉了 manifest 编写和发布流程再把那些模型主动发起的技能迁进来。每次迁移都要做流量灰度。HagiCode 的思路是按百分比灰度从 5% 流量开始观察误调用率、平均响应时长、用户反馈这几个指标稳定后逐步放大。如果迁移过程中出现指标抖动立即把对应技能的流量切回旧通道。这套灰度策略不需要什么高深基建服务网关做一个流量染色就能满足。5.3 运维观测的关键指标技能管理平台的生命线是可观测性。我们内部最常盯的指标是下面这几个技能调用量支撑业务大盘、命中率候选集是否有效、误调用率路由是否精准、平均耗时执行性能、上下文占比成本与窗口压力。它们之间的关系我在评测一节里已经解释了一部分这里补充一个运维视角。下表整理了每个指标常见异常时的排查方向指标异常表现首选排查方向技能调用量突然归零注册状态是否下架、调度规则是否被改、关键词索引是否失效命中率持续走低候选技能是否被其他相似技能抢占、描述是否需要更新以贴近新话术误调用率明显上升新增技能是否存在语义重叠、描述中的排除项是否遗漏平均耗时明显拉长技能实现的内部依赖是否变慢、沙箱资源是否不足上下文占比超过预算单条描述是否超长、注入技能数是否需要收紧提示这些指标的另一个用途是反推技能描述优化方向。某技能频繁出现在候选集但从未被调用说明它的 description 语义太泛模型看得见但想不起用某技能调用准确率极高但召回率低则说明描述写得过于保守需要适度扩展触发场景。5.4 扩展演进从平台到生态当技能数量继续膨胀管理平台本身也要思考如何向生态化演进。HagiCode 目前已经打开了技能市场的雏形不同业务团队可以把自己维护的技能发布到内部公共仓库其他团队通过授权后直接复用。跨团队复用带来的连带效应是超预期的基础性技能身份解析、费用测算、状态查询被复用的次数比单一业务技能高一个数量级这也反过来说明当初把技能的接口和权限都标准化的设计没有白做。最后再分享一个我个人的小习惯每次新技能上线我都会手动在回归集里补 20 到 30 条负样本——也就是明确不应该触发该技能的对话记录。这件事做起来枯燥但恰恰是这些负样本让系统的误调用率在实际调度中长期维持在很低的水平。技能管理这种平台本质上拼的不是单点技术多炫而是异常发生时你有多少底牌可打。先把底牌一张张备好再谈可扩展这个顺序别搞反了。