一站式 AI 应用构建平台，让每个团队都能拥有自己的 AI 基础设施。
Spring AI · MCP 生态 · 多模型适配 · Agent 自进化 · 工作流编排 · 知识库 · 小模型训练
--- ## 为什么选择 lingclaw？ 市面上的 AI 平台要么只做大模型对话，要么只做模型训练，很少有产品能**同时覆盖大模型智能体和小模型训练**两条主线。lingclaw 正是为此而生—— - **大模型 + 小模型双引擎**：大模型负责理解、推理、决策；小模型负责垂直领域感知（人脸识别、目标检测、NER 等）。两者协同，补齐单一大模型在专业场景的短板。 - **开箱即用的 AI 中台**：不是 SDK，不是框架，而是一个**完整的、可独立运行的平台产品**。接入即用，多系统、多平台共享同一套 AI 能力。 - **全流程可视化管理**：从模型管理、知识库构建、MCP 工具编排、智能体配置到工作流调度，所有环节都有直观的管理界面。 --- ## 核心功能全景 ### 一、🤖 AI 智能体（Agent） lingclaw 的智能体不是简单的"提示词 + 模型调用"，而是一套**具备自主决策、自我进化、多级协作能力的 Agent 架构**。 #### 1. 灵活的智能体配置 - **多模型自由切换**：支持 Ollama 本地模型、OpenAI 兼容接口、自训练模型等，按需为每个 Agent 绑定不同模型 - **提示词工程**：可视化编辑 System Prompt，精细控制 Agent 人设与行为边界 - **能力装配**：为 Agent 自由组合知识库、MCP 工具、Skills 技能包，像搭积木一样构建专属能力
#### 2. 主Agent + 子Agent 多级协作
支持**主从 Agent 架构**。主 Agent 作为"决策大脑"，根据任务自主判断应该分配给哪个子 Agent 执行：
- 主 Agent 分析用户意图 → 选择最合适的子 Agent → 下发子任务
- 子 Agent 独立执行（拥有自己的模型、工具、超时控制）→ 结果汇报主 Agent
- 支持**实时状态推送**，前端可以看到每个子 Agent 的执行进度
这意味着你可以构建一个"团队"：一个规划 Agent 负责拆解需求，一个编码 Agent 负责写代码，一个测试 Agent 负责验证——**真正的 AI 团队协作**。
#### 3. 🧬 Agent 自进化能力（Self-Evolution）
这是 lingclaw 最核心的差异化能力。受 Voyager（Wang et al., 2023）论文中 Skill Library 机制启发，我们实现了 Agent 在任务执行过程中的**自主学习与能力升级**：
**Skills 技能库**
- Agent 在执行任务时，如果发现本地知识不足，会**自动连接 Skills 市场**，搜索并下载最佳实践、脚本方案
- 下载的技能以 Markdown 文件形式保存，并**自动同步到向量库**，下次遇到类似问题直接语义检索复用
- 支持多个技能集分类管理，每个技能集独立同步
**进化记忆（Evolution Memory）**
- Agent 在执行任务中积累的经验——成功的解决方案、失败的教训、发现的规律——会以**语义向量的形式持久化存储**
- 下次遇到类似问题，Agent 会**主动查询历史记忆**，避免重复踩坑
- 每个 Agent 拥有独立的记忆空间，互不干扰，重启后自动恢复
**MCP 工具自主发现与安装**
- Agent 遇到能力不足时，会**自动搜索 MCP 工具市场**，发现合适的工具后一键安装
- 安装完成后**热重载自身配置**，新工具立即生效，无需重启服务
- 整个过程完全自主，无需人工干预
**强制进化决策链**
- 当 Agent 在任务中遇到困难，系统会引导其按照严格顺序尝试：
1. 先查本地 Skills 技能库
2. 再到 Skills 市场搜索下载
3. 再搜索 MCP 工具市场
4. 最后才用基础编码能力兜底
- 这套机制确保 Agent **不会盲目重试**，而是系统性地寻找最优解
---
### 二、🛡️ 生产级稳定性优化
lingclaw 不只是一个 Demo，而是面向**真实生产环境**设计的。以下是我们在稳定性和可靠性方面的核心优化：
#### 1. 智能安全熔断机制
大模型在 Tool Calling 场景下有一个行业痛点：**容易陷入无限循环**——反复调用同一个失败的工具，消耗大量 Token 却毫无产出。
lingclaw 内置了三级保护：
- **连续失败熔断**：连续多次工具调用无实质输出时，自动终止循环，避免 Token 浪费
- **进化策略注入**：连续失败达到阈值后，系统不是简单终止，而是**智能注入引导指令**，提醒 Agent 换思路、查记忆、找工具
- **总轮次硬上限**：不管成功失败，达到总轮次上限一律终止，兜底防护
所有阈值均可通过配置文件灵活调整，适配不同业务场景。
#### 2. 任务自动续传
大模型输出存在 Token 上限，复杂任务经常在执行到一半时被截断。传统方案需要用户手动"继续"。
lingclaw 实现了**全自动任务续传**：
- 主 Agent 输出结束后，系统自动判断任务是否真正完成
- 支持**模型完成度验证**——调用模型做二次确认，避免误判
- 未完成时自动构造续传指令，无缝发起下一轮，**前端完全无感知**
- 多轮续传的输出直接拼接推送，用户看到的是一次完整的流畅交互
#### 3. 两级上下文压缩
长对话场景下，上下文窗口会不断膨胀，导致 Token 消耗飙升甚至超出模型限制。lingclaw 创新性地引入**两级压缩策略**：
- **L1 规则压缩（零成本）**：每轮工具调用后，自动截断旧轮次的工具输出，只保留最新结果完整。零 LLM 调用，实时生效
- **L2 模型摘要压缩**：当对话历史达到阈值时，自动调用模型将早期对话压缩为精炼摘要，释放上下文空间。支持指定轻量模型做压缩，降低成本
两级策略配合，既保证了对话质量，又大幅降低了长对话场景的 Token 开销。
#### 4. 跨对话任务记忆
传统 AI 对话"关了就忘"，下次打开又要从头开始。lingclaw 支持**跨对话的任务进度记忆**：
- 每次对话结束后，自动提取任务进度摘要并持久化
- 下次新对话时，自动注入上次的进度摘要到 System Prompt
- Agent 能清楚知道"上次做到哪了"，直接从断点继续，**避免重复劳动**
#### 5. 跨平台命令智能适配
Agent 在执行系统命令时，最常见的问题就是**跨平台语法不兼容**——在 Windows 上用 Linux 命令，在 Mac 上用 PowerShell 语法。
lingclaw 内置了**三平台命令规范引擎**：
- 自动检测当前操作系统（Windows / macOS / Linux）
- 为 Agent 动态注入**当前平台的完整命令规范**：正确语法 + 禁用命令清单
- 命令失败时，错误提示会明确告知当前运行环境，引导 Agent 使用正确语法
Windows 用 PowerShell、Mac 用 bash/zsh、Linux 用 bash——Agent 永远不会搞混。
---
### 三、🔧 CodingTool — 全能系统操作工具
为 Agent 提供**完整的操作系统交互能力**，一个工具覆盖所有场景：
| 能力 | 说明 |
|------|------|
| **bash** | 执行任意 Shell/PowerShell 命令（git、mvn、npm、curl、docker…） |
| **file_read** | 读取文件内容，支持行号范围 |
| **file_edit** | 精准文本替换或创建文件，支持增量编辑 |
| **search** | 目录级文件内容搜索（正则/关键词） |
| **list_dir** | 目录树结构查看 |
同时内置**安全防护**：
- 禁止杀死宿主 Java 进程（避免 Agent 误杀自己）
- 禁止修改应用端口配置
- 危险命令正则拦截（覆盖 Windows/Linux 双平台的各种变体写法）
- 后台进程启动强制规范（防止 Agent 启动阻塞式前台服务导致超时）
---
### 四、📚 知识库（RAG）
- **多格式文档支持**：PDF、Word、Excel、Markdown 等主流格式，基于 Docling 解析，准确率 85%~90%
- **向量化语义检索**：文档内容自动 Embedding 入库，Agent 对话时实时检索相关知识片段
- **可视化管理界面**：上传、解析、检索、删除，全流程可视化操作
---
### 五、🔌 MCP 工具生态
lingclaw 深度集成 MCP（Model Context Protocol）标准，让 Agent 能力无限扩展：
- **可视化 MCP 管理**：添加、配置、启停 MCP 服务，支持 stdio 和 SSE 两种传输方式
- **MCP 市场搜索**：直接对接 MCP 官方 Registry，一键搜索全球开发者发布的工具
- **一键本地部署**：搜到的工具直接安装到本地，自动配置，无需手动折腾
- **Agent 自主发现安装**：Agent 在任务中遇到能力缺口时，可自动搜索并安装 MCP 工具
---
### 六、⚡ 工作流编排
- **基于 Agent 的工作流**：每个节点可以绑定不同的 Agent，Agent 之间支持参数传递
- **可视化编排**：拖拽式配置工作流节点和连接关系
- **定时调度**：支持 Cron 表达式定时触发工作流，实现自动化任务
- **执行日志**：完整记录每次工作流的执行详情，方便排查和回溯
- **对话中触发**：用户可以在对话中 @工作流，让 Agent 自动调用执行
---
### 七、🧠 小模型训练（NLP + 视觉）
大模型不是万能的，垂直领域的精准感知仍然需要专业的小模型。lingclaw 提供完整的小模型训练流水线：
#### NLP 方向
- **分类管理**：定义业务场景，配置关键词提取规则和缺失信息回复策略
- **数据标注**：为对话内容标注关键实体，构建高质量训练数据集
- **Q&A 管理**：一问一答格式的对话数据管理，支持批量上传
- **训练与测试**：一键启动训练，训练完成后立即在线测试效果
#### 视觉方向
- **图像训练**：图片上传 → 自动裁剪 → 内容标注 → 模型训练 → 在线测试，全流程闭环
- **视频分析**：支持视频实时分析，适用于安防监控、质检等场景
- **特征管理**：统一管理标注标签体系，支持跨数据集复用
---
### 八、🖥️ 更多平台特性
| 特性 | 说明 |
|------|------|
| **Electron 桌面端** | 支持打包为桌面应用，Windows/Mac/Linux 三端运行 |
| **多用户多角色** | 完整的用户、角色、菜单权限体系 |
| **操作审计** | 全链路操作日志记录 |
| **安全配置** | 密码复杂度、登录锁定、密码过期等企业级安全策略 |
| **国际化** | 支持多语言切换 |
---
### 九、💬 lingclaw-chat — 开放对话组件
#### 我们提供了什么
lingclaw-chat 是一个基于 Web Component 构建的 AI 对话组件，**一行 HTML 标签即可将平台的 Agent 对话能力嵌入任何页面**：
```html
---
## 技术参数一览
lingclaw 的参数体系分为**三层**：
- **后端 yml 全局参数**：`application.yml` 中配置，影响整个平台，修改后需重启生效
- **Agent 前端对话参数**：每个 Agent 独立配置，通过前端「参数调试」弹窗的「知识库检索 / 技能检索 / 超时控制」面板设置，保存后下次对话生效
- **Agent 前端高级参数**：每个 Agent 独立配置，通过前端「参数调试」弹窗的「工具调用 / CodingTool / 子Agent / 记忆与上下文 / 任务续传」面板设置，保存后下次对话生效
此外，前端对话窗口顶部有两个**会话级开关**（不持久化到 Agent 配置，仅影响当前浏览器会话）：
| 开关 | 说明 | 默认 |
|------|------|------|
| 深度思考 | 关闭后禁用模型的 thinking/reasoning 模式，减少 Token 消耗 | 开启 |
| 联网搜索 | 开启后为 Agent 注入 web_search 工具，允许实时抓取网页内容 | 关闭 |
---
### 后端 yml 全局参数
配置路径均在 `application.yml` 中，前缀 `spring.ai`：
| 配置项（yml 路径） | 说明 | 默认值 |
|---------------------|------|--------|
| `spring.ai.http.connect-timeout` | 模型 API TCP 连接超时（秒），建立连接的最大等待时间 | 60 |
| `spring.ai.http.read-timeout` | 模型 API 读取超时（秒），等待首次响应的最大时间（流式场景指首个 SSE 事件） | 120 |
| `spring.ai.skill.max-summary-length` | 技能文件向量索引摘要最大字符数，用于 Embedding，越短匹配越精准 | 800 |
| `spring.ai.mcp-registry.registry-base-url` | MCP 官方 Registry API 基础地址，可替换为镜像或私有部署 | `https://registry.modelcontextprotocol.io/v0` |
| `spring.ai.mcp-registry.request-timeout-seconds` | MCP 市场搜索和元数据查询的 HTTP 请求超时（秒） | 30 |
| `spring.ai.mcp-registry.install-timeout-seconds` | MCP 工具安装超时（秒），覆盖预下载 + 写入 DB 全流程 | 180 |
| `spring.ai.skill-markets` | Skills 市场资源链接列表，Agent 搜索 Skills 时从这些链接中获取内容 | 4 个默认链接 |
| `spring.docling.method` | 文档解析引擎，`none`（原 Tika）或 `docling`（深度解析） | docling |
| `spring.docling.url` | Docling 服务地址 | `http://127.0.0.1:5001` |
| `spring.docling.timeout` | Docling 异步解析超时（秒） | 300 |
| `spring.docling.concurrency` | Docling 最大并发解析数，防止 CPU/GPU 过载 | 10 |
---
### Agent 前端对话参数（chatParams）
每个 Agent 独立配置，通过前端「参数调试 → 知识库检索 / 技能检索 / 超时控制」面板设置：
#### 知识库检索
| 参数 | 字段名 | 说明 | 默认值 |
|------|--------|------|--------|
| 查询文档数量 | `topK` | 知识库语义检索返回的最大文档数，值越大召回越多但可能引入噪声 | 5 |
| 文档相似度 | `similarityThreshold` | 知识库文档相似度阈值（0~1），低于此值的文档不返回，越接近 1 越严格 | 0.5 |
| 追加提示词 | `prompt` | 额外追加的知识库检索提示词，用于引导模型如何使用检索到的文档内容，留空使用默认 | 空 |
#### 技能检索
| 参数 | 字段名 | 说明 | 默认值 |
|------|--------|------|--------|
| 技能检索数量 | `skillTopK` | 技能语义检索返回的最大匹配数 | 3 |
| 技能相似度 | `skillSimilarityThreshold` | 技能检索相似度阈值（0~1），低于此值的技能不返回 | 0.3 |
| 技能内容长度 | `skillMaxLength` | 单个技能文件注入 System Prompt 的最大字符数，过大会占用上下文窗口 | 4000 |
#### 超时控制
| 参数 | 字段名 | 说明 | 默认值 |
|------|--------|------|--------|
| 工作流超时 | `workflowTimeout` | 工作流执行的最大等待时间（秒），超时后中断执行 | 300 |
| 流式超时 | `streamTimeout` | 流式响应超时（秒），连续 N 秒内无任何数据推送则判定超时 | 180 |
---
### Agent 前端高级参数（advanced）
每个 Agent 独立配置，通过前端「参数调试」弹窗的高级面板设置：
#### 工具调用
| 参数 | 字段名 | 说明 | 默认值 |
|------|--------|------|--------|
| 模型重试次数 | `retryMaxAttempts` | 模型 API 调用失败后的自动重试次数 | 2 |
| 工具调用最大轮次 | `maxToolRounds` | 单次对话中工具调用的总轮次上限，达到后强制终止，防止无限循环 | 15 |
| 连续失败熔断次数 | `maxConsecutiveFailures` | 连续 N 次工具调用无实质输出时触发熔断终止，防止 Token 浪费 | 5 |
| 进化提醒阈值 | `evolutionRemindThreshold` | 连续 N 次失败后注入进化策略引导，提醒 Agent 查记忆、找工具、换思路 | 3 |
| 进化记忆查询数 | `evolutionMemoryTopK` | `memory_query` 动作单次最多返回的记忆条数 | 10 |
| 进化记忆相似度 | `evolutionMemorySimilarity` | 进化记忆语义相似度阈值（0~1），低于此值的记忆不返回 | 0.3 |
| 进化技能内容长度 | `evolutionSkillMaxLength` | `skill_search` 动作单个技能返回的最大字符数 | 4000 |
| 进化技能搜索阈值 | `evolutionSkillSearchThreshold` | `skill_search` 语义搜索相似度阈值（0~1），低于此值的技能不返回 | 0.5 |
#### CodingTool
| 参数 | 字段名 | 说明 | 默认值 |
|------|--------|------|--------|
| Bash 输出最大字符 | `codingMaxBashOutput` | `bash` 动作执行命令后返回结果的最大字符数，超出截断 | 4000 |
| 文件读取最大字符 | `codingMaxReadLength` | `file_read` 动作单次读取文件的最大字符数 | 4000 |
| 目录最大条目数 | `codingMaxDirEntries` | `list_dir` 动作递归列出目录树的最大条目数 | 100 |
| 搜索输出最大字符 | `codingMaxSearchOutput` | `search` 动作搜索结果的最大字符数 | 4000 |
#### 子 Agent
| 参数 | 字段名 | 说明 | 默认值 |
|------|--------|------|--------|
| 子 Agent 超时 | `subAgentTimeout` | 子 Agent 单次执行的超时时间（秒） | 120 |
| 子 Agent 工具轮次 | `subAgentMaxRounds` | 子 Agent 内部工具调用的最大轮次，防止子 Agent 无限循环 | 5 |
#### 记忆与上下文
| 参数 | 字段名 | 说明 | 默认值 |
|------|--------|------|--------|
| 记忆窗口最大消息数 | `maxMemoryMessages` | 对话历史保留的最大消息条数，超出后早期消息被移除 | 50 |
| 最大输出 Token 数 | `maxOutputTokens` | 模型单次响应的最大输出 Token 数 | 16384 |
| L2 上下文压缩 | `compactEnabled` | 是否启用 L2 模型摘要压缩，开启后消息数达到阈值时自动调用模型压缩早期对话 | 关闭 |
| L2 压缩触发阈值 | `compactThresholdRatio` | 触发 L2 压缩的消息数比例（消息数 ÷ 窗口最大消息数），例如 0.7 表示达到 70% 时触发 | 0.7 |
| L1 工具输出裁剪长度 | `toolOutputMaxLength` | 旧轮次工具输出保留的最大字符数（0=不裁剪），零 LLM 调用实时生效 | 200 |
| L2 压缩批次大小 | `compactBatchSize` | 每次 L2 压缩处理最早的 N 条消息，替换为一条摘要 | 10 |
| L2 摘要最大字符 | `compactMaxSummaryLength` | L2 压缩生成的摘要最大字符数 | 800 |
| L2 压缩 Agent | `compactAgentId` | 执行 L2 压缩的 Agent，可指定轻量模型 Agent 降低成本，默认使用当前 Agent | 当前 Agent |
| L2 消息截断长度 | `compactMsgTruncateLength` | 压缩 Prompt 中每条消息的最大截断字符数，控制压缩调用本身的 Token 开销 | 500 |
#### 任务续传
| 参数 | 字段名 | 说明 | 默认值 |
|------|--------|------|--------|
| 续传最大轮次 | `taskResumeMaxRounds` | 自动续传的最大轮次，0 表示关闭续传功能 | 0 |
| 完成度验证 | `taskResumeVerify` | 是否开启模型完成度验证，开启后由模型二次确认任务是否真正完成 | 关闭 |
| 跨对话任务记忆 | `taskMemoryEnabled` | 是否开启跨对话任务记忆，开启后对话结束自动提取进度摘要，下次新对话注入 | 开启 |
| 任务记忆摘要长度 | `taskMemoryMaxLength` | 跨对话任务记忆摘要的最大字符数 | 300 |
| 验证 Agent | `verifyAgentId` | 执行续传完成度验证的 Agent，可指定轻量模型降低成本，默认使用当前 Agent | 当前 Agent |
| 摘要输入最大字符 | `summaryInputMaxLength` | 摘要提取时只取对话尾部 N 字符送给模型，控制 Token 消耗 | 3000 |
---
## 技术栈
| 层 | 技术 |
|----|------|
| 后端框架 | Spring Boot 3.x + Spring AI 1.1.3 |
| AI 协议 | MCP (Model Context Protocol) |
| 模型服务 | Ollama / OpenAI 兼容接口 |
| 文档解析 | Docling 2.74.0 |
| 向量检索 | 本地 Embedding (ONNX MiniLM) + SimpleVectorStore |
| 数据库 | MySQL 8.0+ |
| 前端 | Vue 3 + Element Plus |
| 桌面端 | Electron |
| 对话组件 | lingclaw-chat（Web Component，跨框架嵌入） |
| 认证鉴权 | easy-security |
| 脚手架 | 盘古（Pangu） |
---
## 快速开始
### 环境要求
- JDK 21
- MySQL 8.0+
- Node.js 20.x+（建议使用 yarn）
- Ollama 最新版
### 三步启动
ollama 安装，不要安装c盘
```shell
# D:\ollama 就是默认安装位置
PowerShell 打开ollama的安装目录，然后执行 .\OllamaSetup.exe /DIR="D:\ollama"
# 安装完毕后，会有个对话窗口，在里面设置模型的安装路径，它默认还是c盘
```
```bash
# 1. 创建数据库（项目启动后自动建表）
# 2. 修改 application.yml 中的数据库连接和文件存储路径
# 3. 启动后端 + 前端
# 默认账号：superAdmin / superAdmin@2025
```
遇到如下报错，可以先对项目进行 maven compile，然后启动
```text
Error creating bean with name 'embeddingModel' defined in class path resource [com/wt/admin/config/AIConfig.class]: Error code - ORT_INVALID_PROTOBUF - message: Failed to load model because protobuf parsing failed.
```
---
## 开源协议
本项目采用 **AGPL** 开源协议。使用必须遵守国家法律法规，不允许非法项目使用。
---
lingclaw — 让 AI 能力触手可及