# Spring AI LoomAgent —— 灵梭：让 Spring AI 应用一梭成型

wb04307201

446人浏览 · 2026-05-11 07:15:57

wb04307201 · 2026-05-11 07:15:57 发布

Spring AI LoomAgent —— 灵梭：让 Spring AI 应用一梭成型

一行依赖，串起对话、知识、工具与技能 —— 属于 Spring 生态的 Agent 脚手架。

写在前面

如果你正在用 Spring AI 写应用，大概率踩过这些坑：

聊天 UI 得自己写 SSE、写侧边栏、写消息复制下载；
想加 RAG，要先选向量库、写文档读取、配检索阈值、拼 prompt 模板；
想接 MCP，写客户端配置、注册工具、处理同步异步切换；
想给业务方"开箱即用"的技能库，发现要么硬编码进 system prompt，要么写一堆 DSL。

每一件事都不难，但拼起来累。

灵梭（Spring AI LoomAgent）就是把这些散件预先织好的那个梭子 —— 你给它一个 Spring Boot 项目和一段 application.yml，它把 Chat、RAG、MCP、Skill 四大能力一梭串起来，5 分钟拿到一个能对话、能检索、能调用工具、能跑技能的生产级应用。

一梭四件套

1. 对话交互：开箱即用的 Chat UI

不用写一行前端代码。

SSE 流式输出，逐字渲染，长响应不再卡顿；
多轮对话基于 Spring AI MessageChatMemoryAdvisor，JDBC 持久化，重启不丢历史；
多模态：图片作为 Media、文档通过 Apache Tika 抽文本，统一注入上下文；
侧边栏 + 文件管理 + 模态框，Vue 写的响应式 SPA，挂在 /spring/ai/loom 路径下。

2. RAG 知识库：默认零外部依赖

多知识库管理，H2 存元数据，默认 JVector 本地向量库（HNSW 索引，磁盘持久化），不用额外装 Redis/Qdrant 就能跑；
想换 Qdrant / Redis / PGVector？加个 starter 依赖即可，零代码切换 —— 因为所有 Bean 都加了 @ConditionalOnMissingBean；
检索阈值、top-k、prompt 模板全部 yml 可配；可选 LLM 元数据增强（IDocumentRead）。

3. MCP 工具：同步异步双模式

内置 MCP 客户端，stdio / SSE 两种传输都支持；
yml 配置服务后，LLM 立刻发现工具，可在运行时按会话启用/禁用；
可为每个工具写中文 title 和 description，业务方不用记英文名。

4. Skill 技能库：差异化亮点 ✨

这一件是灵梭最不一样的地方。

一个 Skill 只有 4 个字段：

- name: 网络月度事件报告
  description: 围绕 {topic} 按月梳理当年的重要事件，做跨月因果关联与下一年趋势预判，产出 HTML 报告并返回预览链接
  load: true   # 是否预加载到 system prompt，默认 true
  content: classpath:skills/news-watch.st   # 支持 classpath: 前缀

技能内容是普通 Markdown，可以用 @工具名 直接引用 MCP 工具：

1. 用 @get_current_time 获取当前年
2. 用 @sequentialthinking 规划全年月度扫描
3. 每月用 @bing_search 搜索事件，必要时 @crawl_webpage 拿详情
4. 用 @writeFile 写 HTML 报告，用 @viewFileUrl 返回预览链接

这意味着：

业务方写一段"人话"流程，LLM 读完自己就知道该调哪个工具；
技能可以用 classpath:、file:、纯文本三种方式加载，热更新不需要重启；
load: false 的技能不进 system prompt，但用户能通过 UI 按钮精准触发 —— 不污染主对话，又保留了入口。

技能库 + MCP + LLM 自主发现 = 业务方不需要懂代码也能扩展 Agent 能力。

5 分钟上手

第一步：加依赖

<dependency>
    <groupId>io.github.wb04307201</groupId>
    <artifactId>spring-ai-loom-agent-spring-boot-starter</artifactId>
    <version>1.1.25</version>
</dependency>
<!-- 任意一个 Spring AI Chat 模型 starter -->
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    <version>1.1.2.3</version>
</dependency>

第二步：写 yml

spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}
    loom:
      agent:
        rag:
          similarityThreshold: 0.50
          top-k: 4
        skills:
          - name: 部署项目
            description: 从 Git 仓库拉取代码 → 本地编译打包 → 构建 Docker 镜像 → 启动容器 → 返回访问链接
            content: classpath:skills/package-docker.st

第三步：启动

访问 http://localhost:8080/spring/ai/loom，完事。

效果一览

启动后访问 http://localhost:8080/spring/ai/loom，聊一句、上传文档、调一下 MCP、点一下技能 —— 一梭穿完：

请添加图片描述

灵梭的工程哲学

1. 全组件可替换

每一个 Bean 都加了 @ConditionalOnMissingBean。不想要默认 JVector？加 Qdrant starter，自动切换。不想要默认聊天行为？写一个 IChat 实现丢进去，业务代码零改动。

接口 + 默认实现的模式覆盖了：Chat、知识库、文件、用户、对话映射、嵌入工具、Skill 存储、文档读取 —— 共 16 个扩展点。

2. 安全默认值

IGitTool、IMavenTool 默认关闭（git.enabled=false / maven.enabled=false），避免误把单点命令暴露给 LLM；
端到端部署走 ICompileAndDeployTool，单次 LLM 工具调用完成 git clone → 编译 → docker build → 容器启动 → 健康检查，避免 LLM 把流程拆碎；
HttpOnly Cookie + BFF 鉴权，前端不存 token，XSS 不致命。

3. 多栈友好

不是只服务 Java 项目。ICompileAndDeployTool 的 buildTool 支持：

buildTool	适用场景	默认 baseImage
`maven`	Spring Boot / Java 后端	`eclipse-temurin:17-jre-alpine`
`npm`	Node 长驻后端	`node:20`
`npm-frontend`	Vue/React 静态构建	`nginx:1.27-alpine`
`pip`	Python 后端	`python:3`

一个工具调用 = 一个部署任务。

适用场景

你想做什么	灵梭怎么帮你
给团队一个内部 AI 助手	starter 一加，UI 出来，权限基于 HttpOnly Cookie
让 LLM 读公司文档回答问题	上传 PDF/DOCX 到知识库，零代码开启 RAG
让 LLM 调内部 API / 数据库	写个 MCP server，配到 yml，LLM 自动发现
业务方想加"按月出报告"这种长流程	写个 Skill.st，业务方自己加，不用开发介入
AI 自动部署 demo 给客户看	"部署项目"技能，git URL + 端口，返回访问链接

加入我们

仓库：https://github.com/wb04307201/spring-ai-loom-agent
镜像：https://gitee.com/wb04307201/spring-ai-loom-agent
文档：docs/ 目录下有 API 文档 (Gitee) · GitHub、自定义能力 (Gitee) · GitHub、工具说明 (Gitee) · GitHub

Star 一下，提个 Issue，一起让灵梭跑得更顺。