大家好,我是 WeiWill。
最近我在用 Spring AI Alibaba 做一个审图工具。复杂施工图会先通过 Python 提取数据,再封装成一组可调用的 Skill。项目推进过程中,我们遇到一个很典型的问题:
声明里明明有这个 Skill,Agent 为什么就是选不中?
用户需求并不含糊,系统里也确实有对应能力,但 Agent 要么没有选择它,要么在几个相似 Skill 之间摇摆。
这类问题很容易把团队带到一个结论上:
技能多了,大模型找不准,应该加一个向量库。
这个思路听起来合理。把 Skill 描述转成向量,把用户请求也转成向量,再按相似度召回候选能力,最后交给模型判断。
但我把用户请求、候选 Skill 和 description 放在一起看了一遍后,发现真正的问题没有那么复杂。
不是模型理解不了,而是我们没有把 Skill 描述清楚。
所以我先做了一件更简单的事:不增加向量检索,不增加中间层,只重写 description,让它明确说明“什么情况下应该调用我”。调整后,原来匹配不稳定的场景,很快就能被模型正确识别。
这件事提醒我:Agent 的技能发现,不一定一开始就是向量检索问题。

技能发现和知识检索不是一回事
向量检索最适合解决“召回”问题。
比如从几万篇文档中找相关段落,从历史工单中找相似案例,从产品手册中召回可能包含答案的章节。这类任务有一个共同点:系统不知道答案在哪里,只能先从大量非结构化内容中找出候选。
但 Skill 发现不完全一样。
Skill 通常是一项边界相对明确的可执行能力,例如查询订单状态、生成销售报表、提取发票字段、创建项目任务、检查服务器状态。
这里的核心不是“哪段文本和用户问题更相似”,而是:
用户当前意图,是否满足某个能力的调用条件?
这更接近语义路由和能力选择,而不是传统知识检索。
如果系统里只有几十个,或者一两百个 Skill,并且每个描述都比较短,大模型完全可以一次读取这些描述,再结合用户意图做判断。这个阶段直接上向量库,未必能解决根因,反而可能把描述问题藏起来。
一个 Skill 为什么会匹配不上
假设系统里有一个销售报表 Skill,它的描述是:
用于处理销售相关数据。
这句话从人的角度看没错,但对 Agent 来说几乎没有决策价值。
“销售相关数据”到底包括什么?查询单个订单算不算?查看客户欠款算不算?分析销售趋势算不算?导出月度报表算不算?修改订单金额算不算?
如果系统里同时存在订单查询、客户管理、财务统计和报表生成等多个 Skill,模型很难只凭这一句话划清边界。
当用户说:
帮我看看华东区 6 月份的回款异常,按客户汇总。
Agent 需要判断这到底属于销售查询、财务分析,还是报表生成。
如果几个 Skill 都写成“处理销售数据”“查询业务信息”“生成业务报表”,无论使用大模型还是向量库,匹配结果都可能不稳定。向量检索甚至会让问题更隐蔽,因为“回款”“客户”“销售”“报表”在语义上都很接近。
真正该改的,是 Skill 对自身能力边界的表达。
可以把描述改成这样:
当用户需要按区域、客户、时间范围汇总销售额、回款额、欠款额或异常记录时,使用此 Skill 生成只读统计结果。它不负责修改订单、不负责发起收款,也不用于查询单个订单的物流状态。
这段描述提供了四类关键信息:
- 什么意图会触发它;
- 它依赖哪些维度;
- 它会输出什么结果;
- 它明确不做什么。
这些信息比几个抽象关键词更有价值。
Description 是一份能力契约
很多团队写 Skill 描述时,会把它当成名称旁边的补充说明。
于是常见写法是:查询数据、处理文件、生成报告、管理用户、执行任务。
这些描述适合放在功能菜单里,却不适合让 Agent 做决策。Agent 不只需要知道“这个 Skill 是什么”,还需要知道:
什么时候应该选它,什么时候不应该选它?
所以我更愿意把 description 理解成一份面向模型的能力契约。它至少要说清四件事。
触发场景
说明用户通常会提出什么需求。
不要只写“生成报表”,而要写:
当用户需要按时间、部门、区域或客户维度汇总业务数据,并输出表格或摘要时使用。
必要输入
说明执行前需要哪些信息。
例如:
需要明确统计时间范围;区域、部门和客户为可选筛选条件。
这能帮助 Agent 判断信息是否充足。信息不足时,应该先追问,而不是直接调用。
输出结果
说明调用后会得到什么。
例如:
返回只读统计结果,包括汇总指标、异常明细和可选 CSV 文件。
模型知道输出类型后,才能判断这个 Skill 是否真的满足当前任务。
排除边界
说明哪些相似需求不应该调用它。
例如:
不负责修改业务数据,不用于查询单个订单状态,不执行预测分析。
这一点很重要。很多 Skill 冲突,不是因为正向描述太少,而是因为没有写清“不做什么”。
在 Agent 系统里,排除边界和能力范围同样重要。
为什么先改描述,通常更有效
如果问题来自描述不清,先改 description 有三个优势。
第一,反馈链路短。
模型选错 Skill 后,我们可以直接检查用户怎么表达、模型看到了哪些候选、正确 Skill 缺少什么触发信息、错误 Skill 为什么产生误导。改完后,用同一批请求重测,很快就能看到效果。
如果先引入向量库,排查链路会变长:文本怎么切分、向量有没有更新、阈值怎么设、Top-K 取多少、召回结果是否完整、最终排序为什么仍然错。每增加一层,系统就多一份配置、成本和故障点。
第二,语义边界可以被直接表达。
比如用户说:
查询服务器日志,并分析最近一次发布失败的原因。
“查询日志”和“执行服务器命令”在语义上很接近,但权限风险完全不同。
一个只读日志 Skill 可以被调用,不代表 Agent 就应该获得远程执行命令的能力。这类差异很难只靠向量距离表达,却可以在 description 中写清楚:
仅允许读取指定服务日志,不执行命令,不修改文件,不重启服务。
当然,描述不能替代权限控制,但它能减少错误路由。
第三,系统更容易保持简单。
Agent 工程里有个常见倾向:效果不稳定,就继续加组件。匹配不准,加向量库;排序不准,加重排模型;选择不准,再加规划 Agent。
复杂架构不是不能用,但它应该由明确指标推动,而不是由直觉推动。
如果几十个 Skill 通过一次模型判断就能稳定匹配,我不会为了架构看起来完整,再额外维护一套检索系统。
什么时候应该引入向量检索
“优先改描述”不等于“永远不用向量库”。
当 Skill 数量和复杂度继续增长,直接把所有描述交给模型也会遇到边界。
第一,候选能力太多。
如果系统里有几千甚至上万个 Skill,每次都把完整列表放进上下文,会带来明显的 Token、延迟和成本问题。这时向量检索适合做第一阶段候选召回:先找出几十个可能相关的 Skill,再交给模型做最终选择。
第二,技能来源分散。
如果 Skill 来自多个团队、插件市场或业务系统,能力列表持续变化,统一索引会更方便管理。但前提仍然是每个能力有相对规范的描述。否则向量库只是把低质量描述更快地召回出来。
第三,对延迟和成本非常敏感。
高并发场景下,每次都用较大模型读取完整能力列表,成本可能不可接受。此时可以用规则、分类器或向量召回先缩小范围,再用模型完成路由。
但这类优化应该基于真实调用量和延迟数据,而不是在系统刚开始开发时提前设计。
向量召回、模型判断和规则校验要分层
在复杂系统里,更合理的结构不是二选一,而是分层。
向量检索负责从大规模能力列表中快速找候选,解决上下文过大和召回效率问题。
大模型负责理解当前对话、判断真实意图、区分相似 Skill 边界、检查输入是否完整,并决定调用、追问还是拒绝。
确定性规则负责校验权限、限制高风险操作、检查参数、控制生产环境访问,阻止未授权执行。
这三层解决的问题不同。
最危险的设计,是把它们混在一起,认为“相似度最高”就等于“允许调用”。
技能发现只是在回答“可能应该使用哪个能力”,它不能替代鉴权,更不能替代执行前的风险检查。
我会怎么迭代 Skill 发现机制
如果一个 Agent 项目出现技能匹配不准,我建议先按下面的顺序验证。
第一,整理真实请求。
先准备 30 到 50 条典型请求,既包括应该命中的,也包括不应该命中的。里面要故意放入简称、不同表达、信息缺失、同时涉及多个 Skill、高风险操作和系统没有对应能力的请求。
第二,重写 Skill 描述。
每个描述都检查四件事:什么时候使用、需要什么输入、返回什么结果、明确不处理什么。两个 Skill 经常混淆,就把它们并排比较,补充彼此的排除边界。
第三,先做直接匹配测试。
让模型读取用户请求和候选描述,输出选择的 Skill、是否需要追问、缺少哪些参数、为什么排除其他相似能力。如果没有合适能力,就明确返回不匹配。
第四,记录失败案例。
不要只记录最终选了什么,还要保留用户请求、当时可见的候选能力、模型选择结果、实际正确结果、失败原因和修改后的描述版本。
第五,用指标决定是否增加向量库。
如果问题主要来自候选数量太大、上下文成本过高或响应延迟明显,再引入向量召回。如果问题仍然集中在几个相似 Skill 之间,继续调整描述和边界通常更有效。
最后的工程判断
现在 Agent 正在从“能调用工具”走向“能在真实工作流中长期运行”。到了这个阶段,Skill 数量会越来越多,技能发现也会逐渐成为基础问题。
在能力规模还可控时,优先让大模型直接理解 Skill 描述;匹配不准时,先检查描述质量,而不是第一时间增加向量库。
因为 Skill 描述不是装饰文案,而是 Agent 理解能力、区分边界和做出选择的接口。
向量库当然有价值,但它更适合解决大规模候选召回、上下文成本和检索效率问题。它不能自动修复模糊的能力定义,也不能替代权限校验和执行安全。
先把简单链路跑准,再决定是否增加复杂组件。
很多时候,Agent 不是缺少更高级的检索系统,而是缺少一份真正让模型看得懂的能力说明。
我是 WeiWill,深耕软件工程一线,专注 AI 应用落地与 Agent 开发。