# 🎨 AI Agent Draw.io：用自然语言「说」出一张架构图

> 你有没有经历过这样的场景——脑子里有一张清晰的架构图，打开 draw.io 却对着空白画布发呆十分钟？这个项目就是来解决这个问题的。


 <img src="https://img.shields.io/badge/Java-17-orange?logo=java" alt="Java 17">
 <img src="https://img.shields.io/badge/Spring_Boot-3.4.3-brightgreen?logo=springboot" alt="Spring Boot">
 <img src="https://img.shields.io/badge/Next.js-16.1-black?logo=next.js" alt="Next.js">
 <img src="https://img.shields.io/badge/React-19.2-61DAFB?logo=react" alt="React">
 <img src="https://img.shields.io/badge/Google_ADK-0.5.0-4285F4?logo=google" alt="Google ADK">
 <img src="https://img.shields.io/badge/Tailwind-v4-06B6D4?logo=tailwindcss" alt="Tailwind">
 <img src="https://img.shields.io/badge/Docker-Ready-2496ED?logo=docker" alt="Docker">
 <img src="https://img.shields.io/badge/License-Apache_2.0-blue" alt="License">



 🔗 GitHub 仓库：<a href="https://github.com/lechan775/ai-agent-drawio">github.com/lechan775/ai-agent-drawio</a>


---

## 📖 一句话说清楚

**AI Agent Draw.io** 是一个 AI 驱动的智能架构图生成平台。你只需要用中文或英文描述想要画什么——"画一个微服务架构，包含 API Gateway、三个微服务、MySQL 和 Redis"——AI Agent 就能自动在嵌入式 draw.io 画布上渲染出专业级图表。

更关键的是，它**不是一个简单的 ChatGPT 套壳**：后端基于 Google ADK 实现了完整的 Multi-Agent 编排、MCP 协议工具链集成，以及 Sequential / Parallel / Loop 三种 Agent 工作流模式。

---

## 🏗️ 整体架构

```
┌──────────────────────────────────────────────────────────────────┐
│ 🌐 用户浏览器 │
│ │
│ ┌─────────────────────┐ ┌─────────────────────────────┐ │
│ │ 💬 对话面板 │ │ 📐 Draw.io 嵌入式画布 │ │
│ │ │ │ │ │
│ │ • Agent 选择下拉 │ ←→ │ • AI 生成的 XML 实时渲染 │ │
│ │ • 多轮对话历史 │ │ • 鼠标拖拽微调 │ │
│ │ • 流式打字效果 │ │ • SVG/PNG 一键导出 │ │
│ │ • 画布上下文携带 │ │ • 多会话画布独立管理 │ │
│ └─────────┬───────────┘ └──────────────────────────────┘ │
└─────────────┼─────────────────────────────────────────────────────┘
 │ HTTP REST + SSE 流式
 ▼
┌──────────────────────────────────────────────────────────────────┐
│ ☕ Spring Boot 后端 (Java 17) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Trigger │ │ App │ │ Domain │ │Infrastructure│ │
│ │ (HTTP) │──▶│ (Config) │──▶│ (Agent) │──▶│ (DB/Redis) │ │
│ └──────────┘ └──────────┘ └────┬─────┘ └──────────────┘ │
│ │ │
│ ┌───────────────────────────┼───────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌─────────────────────┐ ┌──────────────┐ │
│ │ Google ADK │ │ Spring AI │ │ LangChain4j │ │
│ │ Agent 编排 │ │ Tool/LLM/MCP 集成 │ │ MCP/LLM 集成│ │
│ └──────────────┘ └─────────────────────┘ └──────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 🔌 MCP Protocol (Model Context Protocol) │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │SSE Client│ │ STDIO │ │ Local │ ← 工具接入 │ │
│ │ │远程服务 │ │子进程 │ │本地函数 │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────┐ │ │
│ │ │ MCP Server (对外暴露) │ → 供其他Agent │ │
│ │ └──────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
```

---

## 🔥 核心亮点

### 1. 自然语言 → 图表，端到端闭环

不是把 AI 回复 copy-paste 到 draw.io，而是 **AI 直接操控画布**。后端 Agent 输出 draw.io XML 格式，前端 `react-drawio` 组件实时解析并渲染。

```json
// Agent 响应结构
{
 "type": "drawio", // ← 告诉前端：这是图，直接渲染
 "content": "<mxGraphModel>...</mxGraphModel>"
}
```

当 `type` 为 `user` 时，内容渲染到聊天面板（追问、澄清）；当 `type` 为 `drawio` 时，内容直接推入画布。

### 2. 画布上下文「携带」能力

这是区别于普通 Chat-to-Diagram 工具的关键设计。你可以先在 draw.io 画布上手动拖出大致结构，然后打开「携带画布上下文」开关——当前画布的全部状态会作为上下文回传给 Agent，实现**增量修改**而非每次都从头生成。

### 3. Google ADK 多智能体编排

后端不是简单调一次 LLM，而是基于 **Google Agent Development Kit (ADK)** 构建的完整 Agent 系统：

| 工作流模式 | 说明 | 典型场景 |
|-----------|------|----------|
| `SequentialAgentNode` | 顺序执行多个子 Agent | 先搜索资料 → 再生成图表 |
| `ParallelAgentNode` | 并行执行多个子 Agent | 同时查询多个数据源 |
| `LoopAgentNode` | 循环迭代执行 | 生成 → 自检 → 修正 → 再生成 |

```yaml
# Agent 配置示例 (agent-draw-io.yml)
agent:
 agentId: drawioagent
 agentName: "Draw.io 架构助手"
 chatModel:
 model: gpt-5.1
 tool:
 mcp:
 - name: baidu-search # MCP 工具：联网搜索
 type: sse
 baseUri: http://appbuilder.baidu.com/v2/ai_search/mcp/
```

### 4. MCP 协议深度集成

后端同时作为 **MCP Client** 和 **MCP Server** 运行：

- **Client 侧**：接入百度搜索等外部 MCP 服务，Agent 可以实时检索技术文档来辅助绘图
- **Server 侧**：暴露自定义 MCP 工具供其他 AI Agent 调用，实现 Agent-to-Agent 通信

### 5. DDD 六层架构，工程化拉满

后端严格遵循领域驱动设计（DDD）分层，模块边界清晰：

```
ai-agent-scaffold-draw-io/
├── api/ # RPC 接口契约 + DTO
├── app/ # 启动入口 + 自动配置
├── domain/ # 领域核心（Agent、Chat、MCP、工作流）
├── infrastructure/ # DB/Redis/外部网关
├── trigger/ # HTTP Controller
└── types/ # 通用枚举/异常
```

---

## 🎯 技术选型

| 层级 | 技术选型 | 选型理由 |
|------|---------|----------|
| **后端框架** | Spring Boot 3.4.3 | 生态成熟，配置驱动，与 Spring AI 无缝集成 |
| **AI Agent 引擎** | Google ADK 0.5.0 | 原生支持 Multi-Agent 编排、Session 管理、流式事件 |
| **LLM 集成** | Spring AI + LangChain4j 双通道 | Spring AI 用于主链路，LangChain4j 作为备选与 MCP 补充 |
| **工具协议** | MCP (SSE/STDIO/Local) | 标准化工具接入，AI Agent 互联互通的标准协议 |
| **前端框架** | Next.js 16 + React 19 | SSR 优化 + RSC 架构，生产级性能 |
| **图表引擎** | react-drawio (draw.io 嵌入) | 业界标准图表编辑器，XML 驱动，零学习成本 |
| **样式方案** | Tailwind CSS v4 | 原子化 CSS，设计系统一致性 |
| **部署** | Docker Compose | MySQL + Redis + 前后端一键编排 |

---

## 🚀 一分钟本地跑起来

### 前置条件

- JDK 17+
- Maven 3.6+
- Node.js 20+
- (可选) Docker 24+

### 三步启动

```bash
# Step 1：编译后端
cd ai-agent-scaffold-draw-io
mvn clean package -DskipTests
java -jar ai-agent-scaffold-draw-io-app/target/ai-agent-scaffold-draw-io-app.jar

# Step 2：启动前端（新终端）
cd ai-agent-scaffold-draw-io-front
npm install
NEXT_PUBLIC_API_BASE_URL=http://localhost:8091/api/v1 npm run dev

# Step 3：打开浏览器
# 访问 http://localhost:3000，选择 Agent，开始对话！
```

### Docker 全家桶（生产环境）

```bash
# 基础设施（MySQL + Redis + 管理面板）
docker-compose -f docs/dev-ops/docker-compose-environment-aliyun.yml up -d

# 应用（后端 8091 + 前端 3000）
docker-compose -f docs/dev-ops/docker-compose-app.yml up -d
```

| 服务 | 端口 | 说明 |
|------|------|------|
| 前端 | `:3000` | AI Chat + Draw.io 画布 |
| 后端 API | `:8091` | REST + SSE 流式 |
| phpMyAdmin | `:8899` | MySQL 可视化管理 |
| RedisAdmin | `:8081` | Redis 可视化管理 |

---

## 📡 API 一览

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/query_ai_agent_config_list` | 获取可用 Agent 列表 |
| `POST` | `/api/v1/create_session` | 创建对话 Session |
| `POST` | `/api/v1/chat` | 发送消息，返回 Agent 响应 |
| `POST` | `/api/v1/chat_stream` | SSE 流式对话 |

### 对话接口示例

```bash
curl -X POST http://localhost:8091/api/v1/chat \
 -H "Content-Type: application/json" \
 -d '{
 "agentId": "drawioagent",
 "userId": "demo_user",
 "sessionId": "sess_001",
 "message": "画一个三层架构：前端Next.js、后端Spring Boot、数据库MySQL，用箭头标注数据流向"
 }'
```

响应中包含 `type: "drawio"` 的消息，前端会自动渲染到画布。

---

## 🧭 Agent 内部工作流

一个完整的绘图请求在 Agent 内部经过如下流程：

```
用户输入 "画微服务架构图"
 │
 ▼
┌───────────────────┐
│ RootNode │ ← 接收用户原始输入
│ 意图解析 │
└────────┬──────────┘
 │
 ▼
┌───────────────────┐
│ ChatModelNode │ ← 调用 LLM (GPT/Claude/DeepSeek...)
│ 需求理解 + 检索 │ MCP 工具：百度搜索补充技术细节
└────────┬──────────┘
 │
 ▼
┌───────────────────┐
│ AgentNode │ ← 可选的工作流编排
│ Sequential/ │ 多 Agent 协作处理复杂图表
│ Parallel/Loop │
└────────┬──────────┘
 │
 ▼
┌───────────────────┐
│ RunnerNode │ ← 最终输出 draw.io XML
│ 生成 XML 模板 │ 格式化、自检、修正
└────────┬──────────┘
 │
 ▼
 {"type": "drawio", "content": "<mxGraphModel>..."}
 │
 ▼
 前端 react-drawio 实时渲染 🎉
```

---

## 🔧 Agent 自定义配置

你可以通过环境变量灵活切换 LLM 和工具链：

```bash
# 换个模型试试 Claude
export AI_AGENT_CONFIG_TABLES_DRAWIOAGENT_MODULE_AI_API_BASE_URL=https://api.anthropic.com
export AI_AGENT_CONFIG_TABLES_DRAWIOAGENT_MODULE_AI_API_API_KEY=sk-ant-xxx
export AI_AGENT_CONFIG_TABLES_DRAWIOAGENT_MODULE_CHAT_MODEL_MODEL=claude-3-opus

# 接入你自己的 MCP 服务
export AI_AGENT_CONFIG_TABLES_DRAWIOAGENT_MODULE_CHAT_MODEL_TOOL_MCP_LIST_0_SSE_NAME=my-tool
export AI_AGENT_CONFIG_TABLES_DRAWIOAGENT_MODULE_CHAT_MODEL_TOOL_MCP_LIST_0_SSE_BASE_URI=https://my-mcp-server
export AI_AGENT_CONFIG_TABLES_DRAWIOAGENT_MODULE_CHAT_MODEL_TOOL_MCP_LIST_0_SSE_SSE_ENDPOINT=sse
```

---

## 🎬 使用场景

- **系统设计评审** — 口头描述架构，即时生成可视化图表，省去拖拽时间
- **技术文档配图** — 写 README / 设计文档 / 论文时，用自然语言快速出图
- **教学演示** — 课堂上用对话方式逐步构建架构，学生直观理解组件关系
- **增量修改** — 先让 AI 生成初版，手动微调布局后，再让 AI 添加新模块

---

## 🛣️ 后续规划

- [ ] 支持导出为 PNG/SVG/PDF 多格式
- [ ] Agent Skills 热加载（无需重启即可添加新 Agent）
- [ ] 多模态输入（上传手绘草图 → AI 识别 → 生成规范图表）
- [ ] Langfuse / LangSmith 可观测性集成
- [ ] Kubernetes Helm Chart 部署方案
- [ ] 对话模板市场（社区贡献 Prompt 模板）

---

## 📄 License

Apache License 2.0


 
 ⭐ 如果这个项目对你有帮助，欢迎给个 Star： 
 <a href="https://github.com/lechan775/ai-agent-drawio">github.com/lechan775/ai-agent-drawio</a>
 


---


 
 Built with ❤️ by <a href="https://github.com/lechan775">@lechan775</a> ·
 基础架构源自 <a href="https://bugstack.cn">小傅哥</a> 的 DDD 脚手架

🎨 AI Agent Draw.io：用自然语言「说」出一张架构图

# mobile-open-claw：基于 Google ADK 构建移动端 AI Agent 应用的全栈实践

> **GitHub 仓库**：[lechan775/mobile-open-claw](https://github.com/lechan775/mobile-open-claw) ⚠️ 私有仓库 
> **后端**：Spring Boot 3.4.3 + Google ADK 0.5.0 + D Domain-Driven Design 
> **前端**：Android Jetpack Compose + Nginx 静态 Web 页面 
> **核心能力**：多智能体自动装配 · MCP 协议集成 · 并行/串行/循环工作流 · SSE 流式对话

---

## 一、项目定位

mobile-open-claw 是一套**移动端 AI Agent 全栈应用**，解决的核心问题是：**如何在一套工程框架内，以声明式配置（YAML）快速定义、装配和运行多个 AI Agent，并通过统一的 REST API 对外暴露对话能力**。

它的设计初衷是降低 AI Agent 应用的工程门槛——你只需要写一份 YAML 配置文件，就可以得到一个拥有 MCP 工具调用、多智能体协作能力、且同时支持 Web 和 Android 客户端的完整应用。

---

## 二、核心架构

### 2.1 整体分层

```mermaid
graph TB
 subgraph Clients["客户端层"]
 Web["🌐 Nginx 静态页面 login.html + index.html"]
 Android["📱 Android App Jetpack Compose + Material3"]
 end

 subgraph Trigger["触发器层 (Trigger)"]
 Controller["AgentServiceController REST API + SSE Stream"]
 end

 subgraph App["应用编排层 (App)"]
 AutoConfig["AiAgentAutoConfig 启动时自动装配 Agent"]
 end

 subgraph Domain["领域层 (Domain) - 核心"]
 Armory["🔧 ArmoryService Agent 装配流水线"]
 Chat["💬 ChatService 会话管理与对话调度"]
 MCP["🔌 MCP 协议 Stdio / SSE / Local"]
 Skills["📦 Skills 技能系统"]
 Workflow["⚙️ Agent 工作流 Parallel / Sequential / Loop"]
 end

 subgraph Infra["基础设施层 (Infrastructure)"]
 DAO["MyBatis DAO"]
 Gateway["外部 Gateway"]
 Redis["Redis 缓存"]
 end

 Web --> Controller
 Android --> Controller
 Controller --> Chat
 AutoConfig --> Armory
 Armory --> Workflow
 Armory --> MCP
 Armory --> Skills
 Chat --> Armory
 Domain --> Infra
```

### 2.2 DDD 六模块划分

| 模块 | 职责 | 关键类 |
|------|------|--------|
| **api** | 接口契约定义 | `IAgentService`, DTOs |
| **app** | 应用启动 & 自动装配 | `Application`, `AiAgentAutoConfig` |
| **domain** | 领域模型 & 核心逻辑 | `ArmoryService`, `ChatService`, Agent 节点树 |
| **infrastructure** | 数据访问 & 外部集成 | DAO, Gateway, Redis |
| **trigger** | HTTP 控制器 & 事件监听 | `AgentServiceController` |
| **types** | 公共枚举/常量/异常 | `ResponseCode`, `AppException` |

---

## 三、Agent 装配流水线：声明式配置 → 运行时 Agent

这是整个项目最核心的设计——**基于责任链模式的 Agent 自动装配引擎**。

### 3.1 YAML 配置示例

```yaml
ai:
 agent:
 config:
 enabled: true
 tables:
 myAgent:
 app-name: MyAssistant
 agent:
 agent-id: 100001
 agent-name: 通用助手
 agent-desc: 支持百度搜索的通用对话助手
 module:
 ai-api:
 base-url: https://apis.xxx.cn
 api-key: sk-xxx
 completions-path: v1/chat/completions
 chat-model:
 model: gpt-4.1
 tool-mcp-list: # MCP 工具列表
 - sse:
 name: baidu-search
 base-uri: http://appbuilder.baidu.com/v2/ai_search/mcp/
 sse-endpoint: sse?api_key=xxx
 - local:
 name: myToolCallbackProvider # 本地工具
 tool-skills-list: # Skills 技能
 - type: resource
 path: agent/skills
 agents:
 - name: assistant
 description: 通用AI助手
 instruction: |
 你是一个全能的AI助手，可以使用百度搜索获取最新信息。
 runner:
 agent-name: assistant
```

### 3.2 装配流水线

应用启动时，`AiAgentAutoConfig` 监听 `ApplicationReadyEvent`，触发以下装配流程：

```mermaid
flowchart LR
 Start(["🚀 应用启动"]) --> Config["读取 YAML 配置 AiAgentAutoConfigProperties"]
 Config --> Factory["DefaultArmoryFactory 构建责任链"]
 Factory --> AiApi["AiApiNode 创建 OpenAI API 客户端"]
 AiApi --> ChatModel["ChatModelNode 装配 ChatModel + MCP + Skills"]
 ChatModel --> Agent["AgentNode 逐条注册 LlmAgent"]
 Agent --> Workflow{"存在 AgentWorkflow?"}
 Workflow -->|Parallel| PNode["ParallelAgentNode 并行执行"]
 Workflow -->|Sequential| SNode["SequentialAgentNode 串行执行"]
 Workflow -->|Loop| LNode["LoopAgentNode 循环迭代"]
 Workflow -->|无| Runner["RunnerNode 注册 InMemoryRunner"]
 PNode --> Runner
 SNode --> Runner
 LNode --> Runner
 Runner --> Done(["✅ Agent 就绪"])
```

### 3.3 责任链节点设计

```java
// 每个 Node 继承 AbstractArmorySupport，实现策略路由
@Service
public class ChatModelNode extends AbstractArmorySupport {
 @Override
 protected AiAgentRegisterVO doApply(ArmoryCommandEntity param, DynamicContext ctx) {
 // 1. 构建 Spring AI ChatModel
 // 2. 注入 MCP 工具回调（Stdio/SSE/Local）
 // 3. 注入 Skills 技能
 // 4. 路由到下一个节点
 return router(requestParameter, dynamicContext);
 }

 @Override
 public StrategyHandler<...> get(...) {
 return agentNode; // 下一站：AgentNode
 }
}
```

> 责任链模式来自 `xfg-wrench-starter-design-framework`（@小傅哥的设计模式框架），每个 Node 只关心自己的装配逻辑，通过 `router()` 传递到下一节点。

---

## 四、多智能体工作流

mobile-open-claw 支持三种 Agent 编排模式，直接封装自 Google ADK：

### 4.1 并行执行（Parallel）

多个子 Agent 同时运行，互不依赖，适用于多维度信息收集：

```yaml
agent-workflows:
 - type: parallel
 name: ParallelResearch
 sub-agents:
 - RenewableEnergyResearcher # 研究可再生能源
 - EVResearcher # 研究电动车技术
 - CarbonCaptureResearcher # 研究碳捕获
```

### 4.2 串行执行（Sequential）

Agent 按顺序执行，后续 Agent 可引用前置 Agent 的输出（通过 `output-key` + `{}` 占位符）：

```yaml
agent-workflows:
 - type: sequential
 name: ResearchAndSynthesis
 sub-agents:
 - ParallelResearch # 先并行研究
 - SynthesisAgent # 再汇总生成报告
```

### 4.3 循环执行（Loop）

子 Agent 迭代执行直到收敛或达到 `maxIterations`：

```yaml
agent-workflows:
 - type: loop
 name: SelfImprovingWriter
 max-iterations: 3
 sub-agents:
 - DraftAgent
 - ReviewAgent
```

---

## 五、MCP 协议集成

支持三种 MCP (Model Context Protocol) 工具接入模式，覆盖本地到远程的全部场景：

| 模式 | 通信方式 | 实现类 | 适用场景 |
|------|----------|--------|----------|
| **Stdio** | 标准输入输出进程 | `StdioToolMcpCreateService` | 本地命令行工具 |
| **SSE** | HTTP Server-Sent Events | `SSEToolMcpCreateService` | 远程 MCP Server |
| **Local** | JVM 直接调用 | `LocalToolMcpCreateService` | Spring Bean 方法 |

```java
// SSE 模式核心实现
HttpClientSseClientTransport transport = HttpClientSseClientTransport
 .builder(baseUri)
 .sseEndpoint(sseEndpoint)
 .build();

McpSyncClient client = McpClient.sync(transport)
 .requestTimeout(Duration.ofMillis(500000))
 .build();

ToolCallback[] callbacks = SyncMcpToolCallbackProvider.builder()
 .mcpClients(client)
 .build()
 .getToolCallbacks();
```

---

## 六、REST API 接口

基础路径：`/api/v1/` | 端口：`8091` | CORS：全部开放

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/query_ai_agent_config_list` | 获取可用 Agent 列表 |
| `POST` | `/api/v1/create_session` | 创建对话会话 |
| `POST` | `/api/v1/chat` | 提交对话（同步） |
| `POST` | `/api/v1/chat_stream` | 流式对话（SSE） |

统一响应结构：

```json
{
 "code": "0000",
 "info": "成功",
 "data": { "content": "..." }
}
```

---

## 七、技术栈一览

| 层级 | 技术 | 版本 |
|------|------|------|
| AI 编排引擎 | Google ADK | 0.5.0 |
| AI 框架 | Spring AI | 1.1.0-M3 |
| | LangChain4j | 1.4.0 |
| 后端框架 | Spring Boot | 3.4.3 |
| 语言 | Java | 17 |
| ORM | MyBatis | 3.0.4 |
| 数据库 | MySQL | 8.x |
| 缓存 | Guava Cache | 32.1.3-jre |
| Android UI | Jetpack Compose + Material3 | — |
| Web 前端 | 原生 HTML/CSS/JS (Nginx) | — |
| 容器化 | Docker + Docker Compose | — |

---

## 八、快速启动

### 环境要求

- Java 17+
- Maven 3.8+
- MySQL 8.x
- Docker（可选）

### 三步运行

```bash
# 1. 克隆仓库
git clone https://github.com/lechan775/mobile-open-claw.git
cd mobile-open-claw/mobile-open-claw

# 2. 配置 application-dev.yml 中的数据库连接 & API Key

# 3. 启动
cd mobile-open-claw-app
mvn spring-boot:run -Dspring-boot.run.profiles=dev
```

访问 `http://localhost:8091` 即可使用。

### Docker 一键部署

```bash
cd docs/dev-ops
docker-compose -f docker-compose-environment.yml up -d # MySQL 等基础设施
docker-compose -f docker-compose-app.yml up -d # Nginx + 应用
```

---

## 九、项目结构

```
openclaw_andro/
├── mobile-open-claw/ # 🔧 后端 (Spring Boot + DDD)
│ ├── mobile-open-claw-api/ # API 接口契约层
│ ├── mobile-open-claw-app/ # 应用启动 & 自动配置
│ ├── mobile-open-claw-domain/ # 领域核心（Agent/Workflow/MCP/Skills）
│ ├── mobile-open-claw-infrastructure/ # 基础设施（DAO/Gateway/Redis）
│ ├── mobile-open-claw-trigger/ # HTTP 控制器 & 事件触发
│ ├── mobile-open-claw-types/ # 公共类型 & 异常
│ └── docs/ # 部署脚本 & 开发文档
│
└── mobileopenclawgateway/ # 📱 Android 前端 (Jetpack Compose)
 └── app/
 └── src/main/java/cn/bugstack/ai/mobileopenclawgateway/
```

---

## 十、致谢

- 后端 DDD 脚手架及设计模式框架来自 [@小傅哥](https://github.com/fuzhengwei) 的 `xfg-frame-archetype` v2.2
- Agent 编排能力基于 [Google ADK](https://github.com/google/adk-java)
- AI 对话能力由 Spring AI & LangChain4j 社区驱动

---

## 🔗 相关链接

- **GitHub 仓库**：[lechan775/mobile-open-claw](https://github.com/lechan775/mobile-open-claw)
- 原作者博客：[bugstack.cn](https://bugstack.cn)
- Google ADK 文档：[google.github.io/adk-docs](https://google.github.io/adk-docs/)

---

*本文发布于 2026 年 5 月，项目持续迭代中。*

mobile-open-claw：基于 Google ADK 构建移动端 AI Agent 应用的全栈实践

# 🖥️ 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 讨论。*
