# 🖥️ WaLiSSH：当 SSH 终端遇上大模型 — 一个 AI 驱动的智能运维终端


 <img src="https://img.shields.io/badge/Status-Active%20Development-success?style=flat-square" alt="Status"/>
 <img src="https://img.shields.io/badge/Client-Tauri%202-FFC131?logo=tauri&logoColor=black&style=flat-square" alt="Tauri 2"/>
 <img src="https://img.shields.io/badge/Frontend-React%2019-61DAFB?logo=react&style=flat-square" alt="React 19"/>
 <img src="https://img.shields.io/badge/Server-Spring%20Boot%203.4.3-6DB33F?logo=springboot&style=flat-square" alt="Spring Boot"/>
 <img src="https://img.shields.io/badge/AI-Google%20ADK-4285F4?logo=google&style=flat-square" alt="Google ADK"/>
 <img src="https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square" alt="License"/>



 📦 GitHub（私有仓库，持续开发中） 
 <a href="https://github.com/lechan775/walissh">🔗 github.com/lechan775/walissh</a>


---

## 为什么要再做一款 SSH 工具？

市面上的终端工具已经足够多了。从 PuTTY 到 iTerm2，从 Termius 到 Tabby，从 MobaXterm 到 WindTerm——每个都有自己的拥趸。

但这些工具的 AI 能力几乎都停留在「在你终端旁边开一个 ChatGPT 侧边栏」的水平。它们能**回答你的问题**，但不能**直接接管你的终端**。

WaLiSSH 要解决的核心命题是：

> **让 LLM 真正在服务器上干活，而不是只动嘴皮子。**

想象一下：你输入「帮我排查一下 8080 端口为什么起不来」，Agent 自动执行 `netstat`、`lsof`、`journalctl`，读取日志和配置，最终给你一个结构化的诊断结果——全程不需要你手动敲一行命令。

这就是 WaLiSSH。

---

## 🏗️ 架构总览

WaLiSSH 采用 **C/S 分离的 DDD 分层架构**。核心设计原则只有一条：

> 所有 SSH 操作与 AI 控制逻辑全部收敛在服务端，客户端仅仅负责渲染与交互。

这是刻意为之的**安全架构决策**。在企业场景中，如果把 AI + SSH 能力放在客户端，可能导致：
- 服务器凭证在本地泄露
- 误操作执行危险命令无审计追溯
- 多人协作时权限管理混乱

```mermaid
graph TB
 subgraph Client["🖥️ WaLiSSH Client（Tauri 2 + React 19）"]
 T["Terminal xterm.js + WebGL"]
 S["SFTP Browser 文件浏览 & 拖拽上传"]
 A["AI Chat Panel Agent 对话 & SSH 绑定"]
 C["Command Palette Ctrl+Shift+P"]
 E["Monaco Editor 远程文件编辑"]
 end

 subgraph Server["⚙️ WaLiSSH Server（Spring Boot 3.4.3）"]
 subgraph Trigger["Trigger Layer"]
 HC["HTTP Controllers RESTful API"]
 end
 subgraph Domain["Domain Layer（DDD）"]
 SD["SSH Domain 终端 · 连接 · SFTP"]
 AD["Agent Domain 编排 · 意图 · 上下文"]
 BD["Business Domain 业务逻辑"]
 end
 subgraph Infra["Infrastructure Layer"]
 DB["MySQL + MyBatis"]
 SSH_LIB["SSH Adapter"]
 end
 subgraph AI["AI Stack"]
 ADK["Google ADK 1.2"]
 SAI["Spring AI 1.1.5"]
 LC4J["LangChain4j 1.4"]
 MCP["MCP Client / Server"]
 INTENT["Intent Classifier"]
 CTXT["Context Reducer"]
 end
 end

 subgraph Target["🎯 Target Servers"]
 TS1["生产服务器 A"]
 TS2["测试服务器 B"]
 TS3["..."
 ]

 Client -->|"HTTP/REST"| HC
 HC --> Domain
 Domain --> Infra
 Domain --> AI
 SSH_LIB --> Target
```

### 为什么是服务端收敛？

| 放在客户端 ❌ | 放在服务端 ✅ |
|-------------|-------------|
| SSH 私钥散落在每个开发者本机 | 凭证统一加密存储于服务器 |
| 无法审计「谁在什么时间执行了什么」 | 全链路操作日志可追溯 |
| 更新 Agent 能力需要所有人升级客户端 | 服务端热更新，客户端无感知 |
| AI API Key 暴露在客户端代码中 | Key 仅存于服务端配置 |

---

## 🧠 AI 核心能力矩阵

### 1. Agent ↔ SSH 终端双向绑定

这是 WaLiSSH 最核心的机制。每个 AI 会话可以与一个（且仅一个）SSH 终端建立**双向绑定**：

```
┌──────────────────────┐ ┌──────────────────────┐
│ AI Chat Session │ bind │ SSH Terminal │
│ (chatSessionId) │◄───────►│ (terminalSessionId) │
└─────────┬────────────┘ └──────────┬───────────┘
 │ │
 │ "查一下 8080 端口" │
 ├─────────────────────────────────►│
 │ │ netstat -tlnp
 │ │ lsof -i :8080
 │ │ ps aux | grep java
 │◄─────────────────────────────────┤
 │ │
 ▼ ▼
 结构化诊断报告 原始命令输出
```

绑定由 `sshAgentStore` 管理，通过 HTTP API 与后端的 `BindTerminalRequestDTO` 通信。一个会话一次只允许绑定一个终端，防止 AI 在多台服务器间误操作。

### 2. 意图识别：规则 + LLM 双引擎

直接让 LLM 自由调用终端存在风险。WaLiSSH 引入了**意图分类中间层**：

```mermaid
graph LR
 U["👤 用户输入"] --> IC["IntentService"]
 IC --> RIC["RuleIntentClassifier 规则引擎（关键词/正则）"]
 IC --> LIC["LLMIntentClassifier LLM 语义分类"]
 RIC --> ROUTE["意图路由"]
 LIC --> ROUTE
 ROUTE --> AGENT["对应 Agent 执行"]
 ROUTE --> TOOL["对应 Tool 调用"]
```

| 分类器 | 延迟 | 准确率 | 适用场景 |
|--------|------|--------|----------|
| `RuleIntentClassifier` | < 1ms | ~95%（高频意图） | 「查端口」「看日志」「重启服务」 |
| `LLMIntentClassifier` | ~500ms | ~98% | 「帮我看看最近 OOM 是哪个 Pod 导致的」 |

规则引擎先拦截确定性意图（零成本、零延迟），模糊或复合意图才走 LLM 通道。

### 3. 多智能体工作流

复杂运维任务需要**多步骤编排**。WaLiSSH 支持三种 Agent 工作流模式：

```java
// SequentialAgentNode — 串行：前一个 Agent 输出作为下一个输入
// ParallelAgentNode — 并行：多 Agent 同时执行后聚合
// LoopAgentNode — 循环：直到满足终止条件
```

💡 **实际场景举例**——「部署一个新版本并验证」：

```
Sequential:
 Step 1: Agent A → 拉取最新代码
 Step 2: Agent B → 编译 & 构建镜像 ← 前置条件：Step 1 成功
 Step 3: Agent C → 滚动更新 Deployment ← 前置条件：Step 2 成功

Parallel:
 Step 4: Agent D → curl /health 端点
 Step 5: Agent E → 检查 Pod 日志 ← 同时执行
 Step 6: Agent F → 检查监控指标
```

### 4. MCP 双模：既是 Client 也是 Server

[MCP（Model Context Protocol）](https://modelcontextprotocol.io/) 正在成为 AI Agent 工具调用的事实标准。WaLiSSH 同时支持两种角色：

| 模式 | 角色 | 能力 |
|------|------|------|
| **MCP Server** | 向外暴露 SSH 为工具 | 外部 Agent 可以通过 MCP 协议远程执行 Shell 命令 |
| **MCP Client** | 接入外部工具 | 连接 Stdio/SSE 协议的 MCP Server，扩展 Agent 工具集 |

实现层面：
- `SshExecuteMcpService` — 将 SSH 命令执行包装为 Spring AI `@Tool` 注解的方法
- `StdioToolMcpCreateService` / `SSEToolMcpCreateService` — 两种 MCP Client 连接模式
- `DefaultMcpClientFactory` — MCP Client 工厂，统一创建与管理

### 5. Agent 军械库（Armory）

借鉴了军事术语「军械库」，将 Agent 可用的所有能力统一管理为四个维度：

```
Agent Armory（军械库）
├── 🔧 MCP Tools → 通过 MCP 协议接入的外部能力
├── ⚔️ ADK Tools → 基于 Google ADK 的原生工具（SshExecuteAdkTool）
├── 📋 Skills → 可复用的技能模板（battle-plan / pdf）
└── 🔌 Plugins → 插件拦截器（日志记录 / 风险控制 / 性能监控）
```

### 6. 上下文管理

LLM 的上下文窗口是有限资源。长对话中，早期消息会「挤出」窗口。WaLiSSH 提供了三种缩减策略：

| 策略 | 类 | 原理 | 适用 |
|------|-----|------|------|
| 滑动窗口 | `SlidingWindowReducer` | 保留最近 N 轮，丢弃旧消息 | 简单对话 |
| 优先级 | `PriorityReducer` | 按消息重要性排序，优先保留关键上下文 | 重要任务 |
| 混合 | `HybridReducer` | 滑动窗口 + 优先级加权 | 生产默认 |

---

## 🎨 客户端体验

### 界面布局

```
┌──────┬────────────────────────────┬──────┐
│ │ Header │ │
│ A ├────────────────────────────┤ R │
│ c │ │ i │
│ t │ Workbench Panel │ g │
│ i │ ┌──────────────────────┐ │ h │
│ v │ │ File Tabs │ │ t │
│ i │ │ (Editor / SFTP) │ │ │
│ t │ ├──────────────────────┤ │ S │
│ y │ │ │ │ i │
│ │ │ Terminal Panel │ │ d │
│ B │ │ (xterm.js) │ │ e │
│ a │ │ │ │ b │
│ r │ └──────────────────────┘ │ a │
│ │ │ r │
└──────┴────────────────────────────┴──────┘
```

核心交互组件：

| 组件 | 技术 | 功能 |
|------|------|------|
| `TerminalPanel` | xterm.js + WebGL addon + Fit addon | GPU 加速终端渲染，窗口自适应 |
| `WorkbenchPanel` | 三模式布局（Tab / 水平分屏 / 垂直分屏） | 多文件 + 终端同屏协作 |
| `SFTPWorkspace` | 双面板 + 拖拽上传 | 本地↔远程文件传输 |
| `CodeEditor` | Monaco Editor（VS Code 同款内核） | 远程文件在线编辑，语法高亮 |
| `CommandPalette` | Ctrl+Shift+P 热键 | VS Code 风格命令面板 |
| `SSHConnectionModal` | 三标签页（基础 / 认证 / 高级） | 密码 + 私钥双模式连接 |

### 状态管理

基于 Zustand 的轻量级状态管理，五个 Store 各司其职：

| Store | 职责 | 关键状态 |
|-------|------|----------|
| `connectionStore` | SSH 连接生命周期 | 连接 CRUD、心跳检测、断线重连 |
| `sshAgentStore` | Agent ↔ SSH 绑定 | 绑定/解绑、输入框标签、连接选择器 |
| `fileExplorerStore` | 文件浏览与编辑 | 目录树、文件标签页、选中状态 |
| `agentStore` | AI 对话 | 会话管理、消息流、ReAct 事件 |
| `themeStore` | 主题 | 暗色/亮色切换、配色方案 |

---

## 📊 技术栈速览

```yaml
Client:
 Shell: Tauri 2 (Rust) # 桌面壳，替代 Electron，包体积 ~5MB
 UI: React 19 + TypeScript 5.8 # 前端框架
 Terminal: xterm.js 6.0 + WebGL Addon # GPU 加速终端渲染
 Editor: Monaco Editor 4.7 # VS Code 内核
 State: Zustand 5 # 轻量状态管理
 Style: Tailwind CSS 4.2 # 原子化 CSS
 Build: Vite 7 # 构建工具

Server:
 Framework: Spring Boot 3.4.3 # Java 微服务框架
 Language: Java 17 # LTS 版本
 ORM: MyBatis 3.0.4 + MySQL 8.0 # 持久层
 AI Core: Google ADK 1.2.0 # Agent 开发框架
 AI Ext: Spring AI 1.1.5 # Spring 生态 AI 集成
 AI Ext: LangChain4j 1.4.0 # Java 版 LangChain
 Protocol: MCP (Client + Server) # 模型上下文协议
```

---

## 🚀 快速上手

### 环境准备

| 依赖 | 版本要求 |
|------|----------|
| ☕ JDK | 17+ |
| 📦 Maven | 3.8+ |
| 🟩 Node.js | 18+ |
| 🦀 Rust | stable（Tauri 编译需要） |
| 🗄️ MySQL | 8.0+ |
| 🔑 LLM API Key | OpenAI 兼容接口（如 DeepSeek / Qwen / GPT-4o） |

### 三步启动

**Step 1 — 初始化数据库**

```sql
-- 执行 walissh-server/docs/dev-ops/mysql/sql/walissh.sql
```

**Step 2 — 启动服务端**

```bash
cd walissh-server
# 配置 LLM API Key（两处）：
# walissh-server-app/src/main/resources/application-dev.yml
# walissh-server-app/src/main/resources/agent/ssh-agent.yml

mvn clean install -DskipTests
cd walissh-server-app
mvn spring-boot:run -Dspring.profiles.active=dev
# → 服务端启动在 http://localhost:8080
```

> 💡 `ssh-agent.yml` 配置示例：
> ```yaml
> ai:
> agent:
> llm:
> api-key: sk-your-key-here
> base-url: https://api.deepseek.com/v1
> model: deepseek-chat
> ```

**Step 3 — 启动客户端**

```bash
cd walissh-client
npm install
npm run tauri dev
# → 桌面应用启动，连接 localhost:8080
```

---

## 🔐 安全设计

WaLiSSH 从架构层面做了一系列安全控制：

```
┌─────────────────────────────────────────────────────┐
│ 安全层次 │
├─────────────────────────────────────────────────────┤
│ 传输层 │ 客户端 ↔ 服务端：JWT Token 认证 │
│ │ 服务端 ↔ 目标机：SSH 加密隧道 │
├───────────┼─────────────────────────────────────────┤
│ 凭证层 │ SSH 私钥/密码仅存于服务端，客户端无感知 │
│ │ AI API Key 仅存于服务端配置 │
├───────────┼─────────────────────────────────────────┤
│ 操作层 │ 终端会话隔离：每个 session 独立 PTY │
│ │ Agent 执行命令全量日志审计 │
│ │ Armory Plugin 层可拦截危险命令 │
├───────────┼─────────────────────────────────────────┤
│ 应用层 │ CORS + CSP 双重防护 │
│ │ 密码传输：BCrypt 哈希存储 │
└─────────────────────────────────────────────────────┘
```

---

## 🗺️ 路线图

| 状态 | 功能 | 说明 |
|:----:|------|------|
| ✅ | SSH 基础连接与终端 | 密码/私钥双认证，xterm.js 渲染 |
| ✅ | AI 对话与终端绑定 | Agent ↔ SSH 一对一绑定 |
| ✅ | SFTP 文件浏览器 | 双面板拖拽上传/下载 |
| ✅ | Monaco 代码编辑器 | VS Code 内核，远程文件直接编辑 |
| ✅ | MCP Client/Server | 双模 MCP 协议支持 |
| ✅ | 多智能体工作流 | Sequential / Parallel / Loop |
| ✅ | 意图识别引擎 | 规则 + LLM 双路径分类 |
| ✅ | 动态 Prompt & 上下文缩减 | 三种缩减策略 + 里程碑追踪 |
| 🚧 | AI 命令补全 | 输入时实时预测下一步操作 |
| 🚧 | 终端输出智能解读 | 实时流式分析异常日志 |
| 🚧 | Runbook 自动化 | 预定义运维剧本，一键执行 |
| 🚧 | Web 版客户端 | 浏览器直接使用，无需安装 |
| 📋 | 多语言国际化 | i18n 支持 |

---

## 📁 项目结构速查

```
waliCode/
├── walissh-client/ # Tauri 2 桌面客户端（React + TypeScript + Rust）
│ ├── src/api/ # HTTP API 封装（terminal / ssh / agent / sftp）
│ ├── src/components/ # UI 组件（TerminalPanel / SFTPWorkspace / Monaco...）
│ ├── src/stores/ # Zustand 状态管理（5 个独立 Store）
│ ├── src-tauri/ # Rust 后端（系统调用 / 原生能力）
│ └── docs/ # 开发部署文档
│
└── walissh-server/ # Spring Boot 服务端（DDD 7 模块分层）
 ├── walissh-server-api/ # DTO 与 Feign 接口
 ├── walissh-server-app/ # Spring Boot 启动入口 + 配置
 ├── walissh-server-case/ # 用例编排层
 ├── walissh-server-domain/ # 🧠 核心领域层
 │ ├── agent/ # Agent 编排 / 意图 / 上下文 / MCP / Armory
 │ ├── ssh/ # SSH 终端 / 连接 / SFTP
 │ └── business/ # 业务领域
 ├── walissh-server-infrastructure/ # 持久化 / SSH 适配器 / DAO
 ├── walissh-server-trigger/ # HTTP Controller
 └── walissh-server-types/ # 公共常量 / 枚举 / 异常
```

> 💡 域名结构遵循 `cn.bugstack.ai`，基于 [fuzhengwei/ai-agent-scaffold-lite](https://github.com/fuzhengwei) 脚手架架构深度定制。

---

## 💬 最后

WaLiSSH 不是要替代你手中的终端工具，而是想探索一个问题：

> 当 LLM 不再只是聊天窗口里的「问答机器」，而是真正能**接管终端、执行命令、编排工作流**时，工程师与服务器的交互范式会发生什么变化？

如果你对这个方向感兴趣，欢迎 ⭐ Star / 🍴 Fork，或者直接提 Issue 讨论。


 
 <a href="https://github.com/lechan775/walissh">
 <img src="https://img.shields.io/badge/🔗-View%20on%20GitHub-black?style=for-the-badge&logo=github" alt="View on GitHub"/>
 </a>
 
 Built with ❤️ by <a href="https://github.com/lechan775">@lechan775</a> · Apache 2.0 License

🖥️ WaLiSSH：当 SSH 终端遇上大模型 — 一个 AI 驱动的智能运维终端

# 🚀 开源 | 我用 HarmonyOS + Spring Boot 写了一个全栈背单词 App，已上架 GitHub

> **晨读计划 (ChenDu Plan)** — 面向 CET-4/6、考研党的鸿蒙背单词应用，前后端完整开源，MIT 协议。

---

## 为什么又造了一个"背单词轮子"？

市面上的背单词 App 要么广告多到怀疑人生，要么词书老旧、UI 臃肿。作为一个同时搞 CV 科研 + 工程落地的人，我需要一个：

- ✅ **干净**：无广告、无社交、纯粹背词
- ✅ **可定制**：能自己加词库、改交互逻辑
- ✅ **全栈可控**：前端 UI + 后端 API + 数据库，三端代码全在自己手里
- ✅ **鸿蒙原生**：不套壳 WebView，纯 ArkTS/ArkUI 实现

于是就有了 **晨读计划**。

---

## 📱 运行效果一览

### 登录 & 主页

| 登录 | 注册 | 
|---|---|
| ![login](https://i-blog.csdnimg.cn/img_convert/866933947bc5fa524e32023f808ee0c3.png) | ![register](https://i-blog.csdnimg.cn/img_convert/54a703283dce39f768581a7176d2b5fd.png) |

### 核心功能页

| 词书切换 | 背词练习 | 个人中心 |
|---|---|---|
| ![books](https://i-blog.csdnimg.cn/img_convert/ac774c39fe12057ef27886dd134956ed.png) | ![practice](https://i-blog.csdnimg.cn/img_convert/ab476f7d60d9c7166a18fadd49392257.png) | ![profile](https://i-blog.csdnimg.cn/img_convert/7a0fb5683d23dc103eb4533f73aae28b.png) |

### 学习工具

| 生词本 | 错题本 |
|---|---|
| ![notebook](https://i-blog.csdnimg.cn/img_convert/e2073ce0ab45e0d04cdbe614737a3048.png) | ![wrongbook](https://i-blog.csdnimg.cn/img_convert/c0fd47aa9bf733255889418c7b5978c7.png) |

---

## 🏗 技术架构

```
┌─────────────────────────┐ ┌────────────────────────────┐
│ HarmonyOS ArkUI 前端 │────▶│ Spring Boot REST API │
│ ArkTS · 7 页面 │ │ 11 Controller · 22 端点 │
│ @kit.NetworkKit │ │ MyBatis · MySQL 8.0 │
└─────────────────────────┘ └────────────────────────────┘
```

| 层 | 技术栈 |
|---|---|
| 前端 | HarmonyOS ArkTS + ArkUI 声明式 UI |
| 后端 | Spring Boot 4.0.5 + Java 17 + MyBatis 4.0.1 |
| 数据库 | MySQL 8.0 · 8 张业务表 · utf8mb4 |
| API | RESTful JSON 统一 `{code, message, data}` 格式 |

---

## ✨ 核心特性

### 🔤 背词引擎

- **3 本词书**：四级 / 六级 / 考研核心词汇，每本 300 词
- **四选一答题**：单词 + 音标 + 释义，四个选项点击作答
- **即时反馈**：选对高亮绿色，选错标红，正确答案自动展示
- **双模式**：新学模式（顺序出题）+ 复习模式（回顾已学）
- **单词详情**：点击展开记忆技巧 + 英文例句 + 中文翻译

### 📊 学习追踪

- 累计学习词数 / 连续打卡天数 / 正确率 实时统计
- **月日历打卡视图**：学习日橙色圆点，今日蓝色高亮
- 每日学习流水：新学数、复习数、正确率、学习时长

### 📝 错词 & 生词管理

- **错题本**：答错自动入库，记录错误次数 + 答错句子 + 错误原因
- **生词本**：一键收藏，支持自定义笔记 + 掌握度标签 + 下次复习日期

### 🔐 用户系统

- 注册/登录（SHA-256 密码哈希）
- 个人资料编辑（昵称/每日目标/签名/默认词书）

---

## 🗄 数据库设计

8 张业务表，以 `users` 和 `books` 为中心：

![ER Diagram](https://i-blog.csdnimg.cn/img_convert/eba3c1b89d39b282bc4654ed4f0cf531.png)

| 表 | 职责 |
|---|---|
| `users` | 用户账户 + 学习统计 |
| `books` | 词书元数据（CET-4 / CET-6 / 考研） |
| `words` | 单词库（900+ 词） |
| `user_books` | 用户-词书多对多 + 进度追踪 |
| `study_records` | 每日学习记录 |
| `notebook_words` | 生词本 |
| `wrong_words` | 错题本 |
| `sign_records` | 签到打卡 |

---

## 📡 API 一览

| 方法 | 端点 | 说明 |
|---|---|---|
| `POST` | `/api/auth/register` | 注册 |
| `POST` | `/api/auth/login` | 登录 |
| `GET` | `/api/user/profile` | 个人信息 |
| `GET` | `/api/books/progress` | 词书进度 |
| `GET` | `/api/words/next` | 获取下一个单词 |
| `POST` | `/api/study/submit` | 提交答题结果 |
| `GET` | `/api/stats/overview` | 学习统计 |
| `POST` | `/api/sign` | 每日签到 |
| ... | ... | **共 22 个端点** |

---

## ⚡ 快速上手

### 环境

- DevEco Studio（HarmonyOS SDK）
- JDK 17+ / MySQL 8.0+ / Maven 3.6+

### 后端启动（3 步）

```bash
# 1. 初始化数据库
mysql -u root -p < demo_backend/src/main/resources/db/init_words_demo.sql

# 2. 配置环境变量
cp .env.example .env # 编辑填入数据库密码

# 3. 启动
cd demo_backend && mvn spring-boot:run
# → http://localhost:8080
```

### 前端启动

1. DevEco Studio 打开 `demo/` 目录
2. 修改 `ApiConfig.ets` 中的后端地址
3. 启动模拟器或连接真机

**测试账号**：`demo_user` / `123456`

---

## 🤝 社区协作

项目采用 **MIT 开源协议**，已搭建完整的开源协作基础设施：

- ✅ 中/英/日 **多语言 README**
- ✅ GitHub Actions **CI 自动构建**
- ✅ Swagger/OpenAPI **在线文档**
- ✅ 12 个 **Good First Issues** 供新手认领
- ✅ 核心团队 2 人，**持续招募贡献者**

### 贡献者

| 角色 | GitHub |
|---|---|
| 项目负责人 & 架构师 & 核心开发者 | [@tingnuanx](https://github.com/tingnuanx) |
| 核心开发者 | [@lechan775](https://github.com/lechan775) |

---

## 🔗 链接

| 平台 | 地址 |
|---|---|
| 🌟 **GitHub 仓库** | [github.com/lechan775/ChenDuPlan](https://github.com/lechan775/ChenDuPlan) |
| 📋 **Issue 面板** | [github.com/lechan775/ChenDuPlan/issues](https://github.com/lechan775/ChenDuPlan/issues) |
| 🏷️ **v0.1.0 Release** | [github.com/lechan775/ChenDuPlan/releases](https://github.com/lechan775/ChenDuPlan/releases) |

---

## 📮 关于我

研究方向为计算机视觉与 AI 基础设施。长期关注轻量级模型部署、无人机视觉、开源工程化。

- 🐙 GitHub: [@lechan775](https://github.com/lechan775)
- 📫 Email: uniquewilliams666@gmail.com
- 🔬 代表作: StarNet-Pose（Neurocomputing 在投）、BSDPose（羽毛球姿态检测）

---

> **如果这个项目对你有帮助，欢迎去 GitHub 点个 ⭐ Star，这对我非常重要！** 
> 有任何问题或想法，直接提 Issue，我看到就会回复。

🚀 开源 | 我用 HarmonyOS + Spring Boot 写了一个全栈背单词 App，已上架 GitHub

# 告别 Agent 胶水代码：用 YAML 声明式编排你的多智能体工作流

> 一个基于 Google ADK + Spring AI + LangChain4j 双引擎的 Java 多智能体脚手架，把 Agent 的定义、工具、技能、工作流全部 YAML 化，让「写 Agent」变成「配 Agent」。

---

## 一、多智能体开发的痛点

如果你在 Java 生态里做过 AI Agent，大概率经历过如下流程：

```java
// Step 1: 定义 Agent A
LlmAgent researcherA = LlmAgent.builder()
    .name("EVResearcher")
    .model(new SpringAI(chatModel))
    .instruction("调研电动车技术...")
    .outputKey("ev_result")
    .build();

// Step 2: 定义 Agent B
LlmAgent researcherB = LlmAgent.builder()
    .name("EnergyResearcher")
    .model(new SpringAI(chatModel))
    .instruction("调研可再生能源...")
    .outputKey("energy_result")
    .build();

// Step 3: 定义 Agent C
LlmAgent researcherC = LlmAgent.builder()
    .name("CarbonResearcher")
    .model(new SpringAI(chatModel))
    .instruction("调研碳捕获方法...")
    .outputKey("carbon_result")
    .build();

// Step 4: 并行执行
ParallelAgent parallel = ParallelAgent.builder()
    .subAgents(researcherA, researcherB, researcherC)
    .build();

// Step 5: 汇总 Agent
LlmAgent merge = LlmAgent.builder()
    .name("Synthesis")
    .instruction("汇总 {ev_result} {energy_result} {carbon_result}")
    .build();

// Step 6: 串行编排
SequentialAgent pipeline = SequentialAgent.builder()
    .subAgents(parallel, merge)
    .build();

// Step 7: 创建 Runner + Session...
```

每次新增一个 Agent 就要改 Java 代码、重新编译、重新部署。团队协作时，代码冲突、版本管理、依赖注入都是噩梦。而且你会发现 —— **这些 Java 代码本质上是「配置」，而不是「逻辑」。**

更致命的是：模型 API、MCP 工具连接、Skills 注入都被硬编码在 Java 类里。切换模型厂商？改代码。换个搜索工具？改代码。加一个 Agent 节点？还是得改代码。

---

## 二、解法：YAML 驱动的配置化体系

**ai-agent-scaffold-lite** 的思路很直接 —— 把一切应该是「配置」的东西从 Java 代码里抽出来，放进 YAML：

```yaml
# 并行调研 → 汇总报告，三行 Java 代码都不用写
agent-workflows:
  - type: parallel
    name: ParallelResearch
    sub-agents:
      - EVResearcher         # 预定义的子 Agent
      - EnergyResearcher
      - CarbonResearcher

  - type: sequential
    name: ResearchPipeline
    sub-agents:
      - ParallelResearch     # 先并行
      - SynthesisAgent       # 再汇总

runner:
  agent-name: ResearchPipeline   # 👈 入口，就这么简单
```

这正是 **"约定大于配置"** 在 AI Agent 领域的实践：

| 传统写法 | 本项目 |
|----------|--------|
| 每个 Agent 写一个 Java 类 | 一个 YAML 节点 |
| 改模型需改代码 + 重新部署 | 改 YAML + 热加载 |
| MCP 工具硬编码 + 手动注册 | `tool-mcp-list` 声明式注册 |
| 工作流用建造者模式手写 | `type: loop/parallel/sequential` |
| Skills 需手动注入 | 指向文件夹自动扫描 |

---

## 三、架构一览

整个项目的核心是 **"责任链 + 树形装配"** 模式。应用启动时，框架遍历 YAML 配置表，逐层装配：`RootNode → AiApiNode → ChatModelNode → AgentNode → AgentWorkflowNode → RunnerNode`，最终生成一个 Google ADK `InMemoryRunner` 实例注册到 Spring 容器。

```mermaid
flowchart TB
    subgraph Config["📋 YAML 配置层"]
        A["tables.myAgent"]
    end

    subgraph Armory["🏭 装配链 (Armory)"]
        direction LR
        RN["RootNode"] --> AN["AiApiNode\n→ 构建 OpenAI API 连接"]
        AN --> CN["ChatModelNode\n→ 创建 ChatModel + MCP 工具"]
        CN --> AGN["AgentNode\n→ 装配子 Agent (LlmAgent)"]
        AGN --> AWN["AgentWorkflowNode\n→ 创建 Loop/Parallel/Sequential"]
        AWN --> RUN["RunnerNode\n→ 创建 InMemoryRunner"]
    end

    subgraph Runtime["⚡ 运行时"]
        RUN --> R["InMemoryRunner"]
        R --> S["SessionService"]
    end

    subgraph Trigger["🌐 接入层"]
        S --> API["REST API\n/chat /chat_stream"]
    end

    Config --> RN
```

**DDD 六层分层：**

```mermaid
graph LR
    subgraph 接入层
        T["trigger\nHTTP Controller"]
    end
    subgraph 应用层
        APP["app\n启动 & 自动配置"]
    end
    subgraph 核心领域
        D["domain\nAgent 装配 · 工作流 · MCP · Skills"]
    end
    subgraph 基础设施
        I["infrastructure\nDAO / Redis / Gateway"]
    end
    subgraph 接口定义
        A["api\nDTO / Service 契约"]
    end
    subgraph 通用类型
        TP["types\n异常 / 枚举 / 响应码"]
    end

    T --> D
    APP --> D
    D --> A
    D --> I
    T --> TP
    D --> TP
```

---

## 四、核心能力拆解

### 4.1 工作流编排 —— Loop / Parallel / Sequential

三种工作流原语涵盖了绝大多数 Agent 编排场景：

```yaml
agent-workflows:
  # 🌀 循环：分析 → 执行 → 决策，重复至多 N 步
  - type: loop
    name: AnalyzeAndExecute
    max-iterations: 5
    sub-agents:
      - Planner
      - Executor

  # ⚡ 并行：多 Agent 同时执行，结果互不干扰
  - type: parallel
    name: MultiDimensionResearch
    sub-agents:
      - TechResearcher
      - MarketResearcher
      - PolicyResearcher

  # 🔗 串行：按序执行，后续 Agent 可用 {output_key} 获取前序结果
  - type: sequential
    name: CodePipeline
    sub-agents:
      - CodeWriterAgent
      - CodeReviewerAgent
      - CodeRefactorerAgent
```

其中 `sequential` 是胶水能力最强的原语 —— 它不仅可以串联单个 Agent，**还能串联其他 workflow**。你可以在一个 `sequential` 里放入 `loop` + `parallel` + 独立 Agent，自由组合。

### 4.2 Output 变量传递

Agent 之间通过 `{output_key}` 语法传递上下文，这是多 Agent 协作的关键：

```yaml
agents:
  - name: CodeWriterAgent
    instruction: |
      你是代码生成器。基于用户需求，直接输出 Java 代码块。
    output-key: generated_code        # 👈 输出变量

  - name: CodeReviewerAgent
    instruction: |
      你是代码评审专家。请审查以下代码：
      ```java
      {generated_code}               # 👈 引用上一 Agent 的输出
      ```
    output-key: review_comments

  - name: CodeRefactorerAgent
    instruction: |
      基于评审意见，重构以下代码：
      代码：{generated_code}
      意见：{review_comments}
```

**实际效果**：用户输入 "写一个线程安全的单例"，三个 Agent 依次执行：生成 → 审查 → 重构，最终返回优化后的代码。全程在 YAML 中配置，不写一行 Java Agent 代码。

### 4.3 MCP 工具 —— 三种接入方式

```yaml
chat-model:
  tool-mcp-list:
    # ① SSE 远程工具 —— 百度搜索、百度地图等
    - sse:
        name: baidu-search
        base-uri: http://appbuilder.baidu.com/v2/ai_search/mcp/
        sse-endpoint: sse?api_key=your_key
        request-timeout: 500000

    # ② Local 本地工具 —— 在 domain 模块实现
    - local:
        name: myToolCallbackProvider

    # ③ Stdio 进程工具 —— Python、Node 等独立进程
    - stdio:
        name: python-tool
        command: python
        args: ["/path/to/mcp_server.py"]
```

工具会被自动注入到 `ChatModel`，Agent 在运行时通过 Google ADK 的 function calling 机制直接调用。

### 4.4 Skills 技能注入

支持从 `classpath` 或文件系统自动扫描技能文件，Agent 启动时自动加载：

```yaml
chat-model:
  tool-skills-list:
    - type: resource          # classpath 下
      path: agent/skills
    - type: directory         # 文件系统绝对路径
      path: /app/config/skills
```

目录结构示例：
```
agent/skills/
├── code-review/SKILL.md     # 代码审查规范
├── math-reasoning/SKILL.md  # 数学推理规则
└── sql-generator/SKILL.md   # SQL 生成模板
```

每个 `SKILL.md` 会被作为系统 Prompt 注入到 Agent 的上下文中，实现领域知识的即插即用。

### 4.5 Plugin 插件机制

```yaml
runner:
  agent-name: demoAgent
  plugin-name-list:           # 拦截请求/响应
    - myLogPlugin             # 日志记录
    - myTestPlugin            # 内容过滤 / 审计
```

插件继承 Google ADK 的 `BasePlugin`，可在 Agent 执行链的各个环节插入自定义逻辑。

---

## 五、技术栈矩阵

| 层面 | 选型 | 版本 |
|------|------|------|
| JDK | OpenJDK | 17 |
| 主框架 | Spring Boot | 3.4.3 |
| Agent 运行时 | Google ADK (Java) | 0.5.0 |
| AI 引擎 A | Spring AI | 1.1.0-M3 |
| AI 引擎 B | LangChain4j | 1.4.0 |
| DDD 框架 | xfg-wrench | 3.0.0 |
| ORM | MyBatis | 3.0.4 |
| 容器化 | Docker Compose | — |

**双引擎设计**的考量：Spring AI 和 LangChain4j 各有优劣。Spring AI 与 Spring 生态天然集成，配置简洁；LangChain4j 的工具链更成熟、社区更活跃。两者通过 Google ADK 的抽象层解耦，在 YAML 中可通过 `chat-model` 配置项自由切换。

---

## 六、两个实战案例

### 案例一：可持续技术并行调研

```
用户提问：「调研最新的可再生能源、电动车、碳捕获技术进展」

┌─────────────────────────────────────────────┐
│               ParallelResearch               │
│  ┌───────────────┐  ┌───────────────┐       │
│  │ 可再生能源调研  │  │  电动车调研    │ ...   │
│  │ (百度搜索)     │  │  (百度搜索)   │       │
│  └───────┬───────┘  └───────┬───────┘       │
└──────────┼──────────────────┼───────────────┘
           │                  │
           ▼                  ▼
┌─────────────────────────────────────────────┐
│              SynthesisAgent                  │
│  汇总三份调研 → 结构化报告（分章节 + 结论）     │
└─────────────────────────────────────────────┘
```

三个 Researcher Agent 通过百度搜索 MCP 并行获取信息，SynthesisAgent 汇总为章节化的技术综述报告。

### 案例二：代码生成 → 审查 → 重构管道

```mermaid
flowchart LR
    Input["用户需求"] --> A["CodeWriterAgent\n生成代码"]
    A -->|"{generated_code}"| B["CodeReviewerAgent\n审查代码"]
    B -->|"{review_comments}"| C["CodeRefactorerAgent\n重构代码"]
    C --> Output["优化后的代码"]

    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#e8f5e9
```

代码生成、审查、重构三个环节串行执行，每一步的输出作为下一步的输入，形成完整的代码质量闭环。

---

## 七、快速上手

```bash
# 1. 获取项目
git clone git@github.com:lechan775/ai-agent-scaffold-lite.git
cd ai-agent-scaffold-lite

# 2. 编译（跳过测试）
mvn clean install -DskipTests

# 3. 启动
cd ai-agent-scaffold-lite-app
mvn spring-boot:run

# 4. 验证
curl http://localhost:8080/api/v1/query_ai_agent_config_list
```

**五分钟接入你自己的 Agent：**

```yaml
# 在 application.yml 中添加：
ai:
  agent:
    config:
      tables:
        myFirstAgent:
          app-name: myFirstAgent
          agent:
            agent-id: 10086
            agent-name: "我的第一个助手"
            agent-desc: "用 YAML 配置的智能体"
          module:
            ai-api:
              base-url: https://your-api-endpoint
              api-key: sk-your-key
              completions-path: v1/chat/completions
            chat-model:
              model: gpt-4.1
            agents:
              - name: echoAgent
                description: 回显测试
                instruction: 原样重复用户说的话，并在末尾追加「—— 来自 YAML Agent」
            runner:
              agent-name: echoAgent
```

重启应用，Agent 即刻就绪。没写一行 Java，没有重新编译。

---

## 八、设计约束与适用场景

### ✅ 适合

- 需要快速搭建多 Agent 工作流的项目
- 模型 / 工具 / 工作流频繁变更的迭代阶段
- 团队内有明确 Agent 角色分工（研究员、审阅员、汇总员等）
- 基于 OpenAI 兼容 API 的各类模型服务
- 需要 MCP 协议集成外部工具的 Agent 应用

### ⚠️ 不适合

- Agent 内部需要复杂的有状态逻辑（建议下沉到 Plugin 或 Local MCP 工具实现）
- 实时性要求极高的低延迟场景（框架基于 Spring Boot，非实时框架）
- 需要分布式 Agent 调度的场景（当前为单机 InMemoryRunner）

---

## 九、写在最后

这个项目的核心理念很简单：**写 Agent 应该像定义数据结构一样自然**。你定义 Agent 的名字、指令、工具、工作流，剩下的事情交给框架。

YAML 不是银弹，但当你面对 10+ 个 Agent 的复杂编排时，纯代码写法会让你在 `Builder` 的海洋里窒息。此时，一个声明式的 YAML 配置体系就是最好的救生圈。

> 📦 [GitHub 仓库 (Private)](https://github.com/lechan775/ai-agent-scaffold-lite)
>
> 基于 [小傅哥 xfg-frame-archetype](https://gitcode.net/KnowledgePlanet/ai-agent-scaffold-lite) v2.2 DDD 骨架重构
>
> 技术栈：Google ADK 0.5.0 + Spring Boot 3.4.3 + Spring AI 1.1.0-M3 + LangChain4j 1.4.0

---

*如果你对这个项目有任何想法或改进建议，欢迎通过 GitHub Issues 讨论。*
