SKILL.md 不够用了：Spring AI 与 LangChain4j 的企业级 Skills 包管理实践-CSDN博客

SKILL.md 不够用了：Spring AI 与 LangChain4j 的企业级 Skills 包管理实践

引言：问题不在 SKILL.md，而在我们把它当成了“企业级能力分发系统”

过去一年，越来越多团队开始把 AI Agent 从 Demo 推向生产环境。最初阶段，大家通常都会从一个非常自然的做法开始：

每个能力目录下面放一个 SKILL.md
在文档里写清楚这个技能能做什么、什么时候触发、依赖哪些工具
由 Agent 在运行时读取这些技能说明，再决定调用哪些 Tool

这个思路在单机场景里几乎无可挑剔。它足够轻、足够直观，也足够符合“把能力文档化”的设计哲学。

但一旦进入企业级场景，规模和组织复杂度会迅速把这个模式推到极限。

我们在一个多团队共享的智能运维平台里就经历过这个过程。最开始只有十几个技能：日志分析、数据库巡检、发布回滚、异常工单归因。三个月后，技能数量涨到 200+，同时还出现了三个典型变化：

同一个技能被多个团队复制后私改，出现大量“同名异构”版本
技能更新频率明显提升，开始从周级变成天级甚至小时级
Agent 的调用链越来越长，工具、Prompt、上下文、知识库、审批流开始互相耦合

这时问题就不再是“SKILL.md 写得好不好”，而是：

我们实际上已经在用一套松散的文档文件，承担包管理、版本分发、权限治理、运行时调度、缓存一致性和跨团队协作的职责。

这当然撑不住。

所以本文要解决的，不是“怎么把 SKILL.md 写得更漂亮”，而是：

如何把 Skills 从本地文档组织方式，升级为企业级 Agent Runtime 的能力包体系。

文章会围绕 Spring AI 与 LangChain4j 两条常见技术栈展开，重点回答以下问题：

为什么单纯依赖 SKILL.md 会在生产环境失控
Skills 与 Tool Calling 的边界到底是什么
企业级 Skills 管理系统应该具备哪些核心能力
如何在 Spring AI 中实现技能注册、激活、缓存、隔离与灰度发布
如何在 LangChain4j 中落地同样的运行时治理模型
在高并发、多实例、Kubernetes、多团队协作场景下，Skills 怎么做成真正可运营的基础设施

如果你现在还只有十几个技能，这篇文章会帮你提前建立正确的架构边界；如果你已经在维护几十到几百个技能，这篇文章更重要，因为它会直接决定你们的 Agent 系统能不能继续规模化。

一、从 Tool Calling 到 Skills：先把抽象层次讲清楚

1.1 Tool 是执行原子，Skill 是执行策略

Spring AI、LangChain4j、OpenAI function calling、Anthropic tool use，本质都在解决同一个问题：

让模型在推理过程中有机会调用外部能力。

例如：

查询订单
读取库存
调用工单系统
发送告警
获取数据库慢查询报告

这些都属于 Tool 的范畴。Tool 的本质是一个受控的、结构化的、参数明确的外部能力入口。

但真实业务不会只靠一个 Tool 完成。以“数据库故障诊断”为例，一个成熟技能往往包含以下步骤：

先判断是连接池耗尽还是慢 SQL
再检查最近发布记录
如果慢 SQL 频繁出现，进一步拉取 TopN SQL
如果存在锁等待，再检查事务堆积与连接数
最后输出结论，并给出风险等级和处理建议

这就已经不是单个 Tool 了，而是一套“如何组织工具调用”的业务策略。

所以我们可以把两者严格区分为：

层次	核心职责	典型形态
Tool 层	提供原子执行能力	`queryOrder`、`executeRollback`、`fetchSlowSql`
Skill 层	组织工具调用策略	“订单退款排障流程”“数据库故障诊断流程”
Agent 层	面向用户完成任务闭环	客服 Agent、运维 Agent、运营 Agent

一句话概括：

Tool 决定能做什么
Skill 决定应该怎么做
Agent 决定为了谁、在什么上下文里做

1.2 企业级问题为什么会在 Skill 层爆发

Tool 层相对容易治理，因为它天然有工程边界：

可以通过代码审查控制
可以通过接口契约定义输入输出
可以通过权限系统限制访问范围
可以通过限流、熔断、审计进行治理

而 Skill 层的问题更难，因为它同时具备三种属性：

它是文档
它是 Prompt
它又在实际影响运行时行为

也就是说，Skill 是一种“介于代码与配置之间的半结构化运行时资产”。

这决定了它在企业环境里有天然的治理难点：

代码系统不把它当代码
配置系统不把它当配置
发布系统不把它当应用
安全系统不把它当权限边界

结果就是：最容易失控的，反而是 Skill。

1.3 一个更适合企业架构讨论的三层模型

很多文章习惯把 Skills 理解成“比 Tool 更大一点的 Prompt 片段”，这在工程上是不够的。更适合生产场景的理解方式，是把 Skills 系统拆成三层：

┌──────────────────────────────────────────────┐
│                协议层 Protocol               │
│  技能描述、清单、依赖、版本、兼容性、签名    │
├──────────────────────────────────────────────┤
│                治理层 Governance             │
│  发布、审批、灰度、权限、审计、配额、回滚    │
├──────────────────────────────────────────────┤
│                状态层 Runtime State          │
│  激活、缓存、会话绑定、上下文收缩、隔离执行  │
└──────────────────────────────────────────────┘

这三层非常关键。

协议层

解决的是“这个 Skill 究竟是什么”的问题，包括：

包名
版本
描述
依赖
所需工具
输入约束
输出期望
签名校验
兼容的 Agent Runtime 版本

治理层

解决的是“谁可以发布、谁可以使用、出了问题怎么回滚”的问题，包括：

谁能创建或修改 Skill
哪些团队可见
哪些环境允许启用
如何灰度发布
如何做审批与审计
怎么做版本冻结和紧急撤回

状态层

解决的是“Skill 在一次推理流程里如何被激活、持有、切换、回收”的问题，包括：

当前会话激活了什么 Skill
是否允许并发激活多个 Skill
激活后的上下文如何注入
执行失败是否要降级
多实例缓存如何一致
激活超时如何自动回收

企业级 Skills 管理，真正难的不是“写一个好 Prompt”，而是把这三层一起做完整。

二、为什么 `SKILL.md` 在企业级场景下会失灵

2.1 单机可行，不等于分布式可用

在本地开发环境中，技能通常是这样使用的：

代码仓库里维护若干 SKILL.md
应用启动时读取这些文件
模型收到请求后，从这些技能中选择匹配项

问题在于，这个流程默认了几个强假设：

技能总量不大
技能更新不频繁
所有技能都由同一个团队维护
技能可见范围不需要精细控制
推理上下文容量足够大
运行节点数量不多

这些假设一旦被打破，问题会以非常快的速度积累。

2.2 典型失控点一：版本与依赖不可管理

当技能数量上来之后，最先出问题的通常不是执行，而是演进。

例如：

db-diagnosis 依赖 sql-analyzer
release-rollback 依赖 deployment-audit
order-refund-investigation 依赖 crm-profile-reader

如果技能只是一个 Markdown 文件，那么依赖关系只能藏在自然语言里。结果是：

没有语义化版本
没有最小兼容版本
没有循环依赖检测
没有废弃声明
没有升级影响分析

当某个公共技能变更之后，下游 Agent 什么时候会坏，往往只能等线上流量来告诉你。

2.3 典型失控点二：上下文爆炸与 Token 成本失控

很多团队的第一个直觉是：既然模型需要知道有哪些技能，那就把所有技能描述都塞进系统提示词。

这在十几个技能时还能勉强接受，到了几十上百个技能就会迅速恶化：

技能名越多，模型选择成本越高
描述越长，系统提示词越臃肿
无关技能越多，误选概率越高
激活内容越多，后续上下文越重

这本质上是把“技能发现问题”粗暴转化成“把所有技能一次性灌给模型”的问题。

结果通常有两个：

成本上升
准确率反而下降

这也是为什么生产级系统必须引入：

元数据瘦身
候选集筛选
按需激活
激活后上下文裁剪
自动去激活

2.4 典型失控点三：安全边界模糊

在很多原型系统里，技能可以直接引导 Agent：

cat 某个文件
curl 某个服务
执行某段 shell
修改某个目录

在单机实验环境中，这种做法确实灵活；但在生产环境里，它会引出严重问题：

技能说明本身变成了间接命令入口
工具授权边界失效
技能作者可以通过 Prompt 间接绕过代码权限
审计系统很难区分“模型自发行为”与“技能诱导行为”

所以企业里有一条几乎不可妥协的底线：

Skill 可以决定执行策略，但不能突破 Tool 的受控执行边界。

也就是说，生产环境应以 Tool Mode 为主，而不是把 Skill 设计成“让模型自由读取和执行本地文件系统命令”的 Shell Mode。

2.5 典型失控点四：组织协作成本高于技术成本

很多团队低估了这一点。真正把 Skills 推向复杂化的，不是模型，而是组织。

当多个团队都在生产技能时，你会很快遇到：

命名冲突
描述风格不统一
技能边界重复
工具命名不一致
版本节奏不一致
测试标准不一致
发布责任不清晰

所以从组织视角看，Skills 管理系统并不是一个“小功能”，它其实更像：

Maven 私服
Helm Chart 仓库
API Gateway 的策略中心
配置中心
发布平台

只不过它服务的对象不是应用包，而是 Agent 的能力包。

三、企业级 Skills 系统应该长什么样

3.1 目标不是“存技能”，而是“托管能力生命周期”

一个成熟的 Skills 平台，至少应该覆盖以下能力：

能力域	必要能力
包管理	命名规范、版本、依赖、兼容性、签名、校验
分发	仓库存储、CDN/对象存储、缓存预热、按环境发布
发现	技能检索、标签、候选集筛选、权限过滤
运行时	激活、去激活、上下文注入、缓存、状态管理
安全	工具白名单、环境约束、审批、审计、撤销
可观测	激活率、命中率、误选率、耗时、Token 成本、失败链路
运维	灰度发布、回滚、冻结、失效广播、灾备同步

如果只能记住一句话，请记住这句：

企业级 Skills 平台管理的不是 Markdown 文件，而是 Agent 的能力生命周期。

3.2 推荐架构：控制面 + 数据面 + 运行时面

为了让架构更稳定，推荐把系统拆成三个平面：

┌───────────────────────────────────────────────────────────┐
│                        控制面 Control Plane              │
│  技能发布、审批、版本治理、权限策略、灰度与回滚            │
└───────────────────────────────────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────┐
│                         数据面 Data Plane                │
│  Git/制品库、对象存储、元数据库、索引库、缓存中心          │
└───────────────────────────────────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────┐
│                      运行时面 Runtime Plane              │
│  Agent 实例、技能激活器、工具网关、缓存、熔断、审计        │
└───────────────────────────────────────────────────────────┘

这样拆有几个好处：

控制面负责“变更”
数据面负责“存取”
运行时面负责“执行”

三者解耦之后，才能避免“技能更新逻辑、技能存储逻辑、技能执行逻辑全部混在 Agent 服务进程里”的问题。

3.3 核心组件划分

下面是一套比较实用的组件划分：

组件	核心职责
Skills Registry	存元数据索引、版本、标签、可见性、环境状态
Skills Repository	存包内容、引用文件、样例、签名文件
Skills Resolver	解析依赖、兼容性、冲突、激活候选
Skills Gateway	暴露 `activate_skill`、`deactivate_skill` 等能力
Tool Execution Gateway	技能上下文下的受控工具调用入口
Runtime Cache	元数据缓存、内容缓存、热点技能预热
Policy Engine	权限、白名单、禁用词、环境约束、审批策略
Observability Pipeline	埋点、链路追踪、指标、日志、审计事件

3.4 生产推荐的技能包结构

不要只维护一个 SKILL.md。推荐把 Skill 组织成可发布的包：

db-diagnosis/
├── skill.yaml
├── SKILL.md
├── references/
│   ├── slow-sql-guide.md
│   └── deadlock-playbook.md
├── examples/
│   ├── input.json
│   └── output.md
└── policies/
    └── tool-allowlist.yaml

其中：

skill.yaml：包清单
SKILL.md：给模型看的策略说明
references/：按需加载的参考资料
examples/：测试样例与评估基线
policies/：权限、环境、配额策略

这种结构的意义在于：把技能从“一个文件”升级成“一个最小交付单元”。

四、技能包协议设计：先把包描述清楚，后面所有治理才有基础

4.1 一个更适合企业使用的 `skill.yaml`

下面是一份更接近生产环境的技能清单示例：

apiVersion: skills.agent.example.com/v1
kind: SkillPackage
metadata:
  id: com.company.ops.db-diagnosis
  name: db-diagnosis
  version: 2.3.1
  displayName: 数据库故障诊断
  ownerTeam: platform-ops
  maintainers:
    - zhangsan
    - lisi
  labels:
    domain: ops
    system: database
    criticality: high
  tags:
    - mysql
    - postgresql
    - slow-sql
    - deadlock
spec:
  description: >