# l4j-sandbox

**Repository Path**: qfmx/l4j-sandbox

## Basic Information

- **Project Name**: l4j-sandbox
- **Description**: L4J-Sandbox Agent 动态技能沙箱系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-11
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# L4J-Sandbox Agent 动态技能沙箱系统

基于 Spring Boot + LangChain4j 的企业级 AI Agent 系统，支持通过自然语言动态调用用户定义的 Python/JS 脚本，脚本在 Piston Docker 沙箱中安全执行。

> **版本**: v1.1.0 | **更新日期**: 2026-05-13 | **LangChain4j**: 1.14.1 (稳定版)

## 🔄 LangChain4j 迁移说明

### 迁移背景

项目最初基于 LangChain4j 早期 alpha/beta 版本（1.3.0-beta9）开发，但该版本不存在于 Maven 仓库。代码中使用了大量不存在的 API，导致无法编译。

### 2026-05-13 重构

**升级版本**: `1.3.0-beta9` → `1.14.1`（最新稳定版）

**API 变更对比**：

| 旧 API（不存在） | 新 API（1.14.1） | 说明 |
|----------------|----------------|------|
| `ToolExecutor` | 直接方法调用 | 移除函数式接口抽象 |
| `ToolProvider` | `LangChainToolProviderAdapter` | 改为服务类 |
| `ChatMemoryProvider` | `ChatMemoryStore` | 使用原生接口 |
| `MessageWindowChatMemory` | `MyBatisChatMemoryStore` | 自定义实现 |
| `AiServices.builder()` | `ChatModel.chat()` | 直接调用 |

**新增配置类**：
- ✅ `LangChain4jConfig.java` - 统一管理 ChatModel，从 `application.yml` 读取配置

**重构文件**：
- ✅ `ToolExecutorFactory.java` - 简化工具执行逻辑
- ✅ `LangChainToolProviderAdapter.java` - 改为服务类，提供工具规格和执行
- ✅ `AgentConfig.java` - 使用 ChatModel 直接调用
- ✅ `LangChainAgentAdapter.java` - 调用 ChatService

**参考文档**: [LangChain4j 官方文档](https://langchain4j.com/docs/)

## 📁 项目结构

```
l4j-sandbox/
├── pom.xml                           # 父 POM
│
├── l4j-app/                          # 主应用模块
│   ├── src/                          # 业务代码（DDD 六边形架构）
│   └── pom.xml
│
├── l4j-starters/                     # Starter 模块聚合
│   ├── pom.xml
│   └── crypto-spring-boot-starter/   # 加密解密 Starter
│
├── l4j-ui/                           # 前端项目（React + Vite）
├── docs/                             # 文档目录
├── API.md                            # API 接口文档
├── DDD_ARCHITECTURE.md               # DDD 架构文档
└── README.md                         # 项目说明（本文件）
```

本项目采用 **领域驱动设计（DDD）六边形架构**（端口-适配器模式），实现业务逻辑与技术实现的完全解耦。

### 架构分层

```
┌─────────────────────────────────────────────────────────┐
│              Interface Layer (接口适配层)                 │
│         ┌─────────────────────────────────┐             │
│         │  REST API (ApiController)      │             │
│         │  REST DTOs (请求/响应对象)      │             │
│         └─────────────────────────────────┘             │
└──────────────────────────────────┬──────────────────────┘
                                   │ 调用
┌──────────────────────────────────▼──────────────────────┐
│        Application Layer (用例编排层)                     │
│  ┌──────────────────────────────────────────────────┐   │
│  │  ┌──────────────────────────────────────────┐   │   │
│  │  │  Common Ports (通用端口)                  │   │   │
│  │  │  - ChatUseCase                            │   │   │
│  │  │  - SkillCommandUseCase / SkillQueryUseCase │   │   │
│  │  │  - AgentGateway / CodeExecutionGateway    │   │   │
│  │  └──────────────────────────────────────────┘   │   │
│  │                                                  │   │
│  │  AgentSkillManagementService                     │   │
│  │  ChatOrchestrationService                        │   │
│  │  ConversationManagementService                   │   │
│  └──────────────────────────────────────────────────┘   │
└──────────────────────────────────┬──────────────────────┘
                                   │ 依赖（通过端口接口）
┌──────────────────────────────────▼──────────────────────┐
│           Domain Layer (核心业务层)                       │
│  ┌──────────────────────────────────────────────────┐   │
│  │  ┌─────────────┐      ┌─────────────┐          │   │
│  │  │AgentSkill   │      │Conversation │          │   │
│  │  │Aggregate    │      │Aggregate    │          │   │
│  │  └─────────────┘      └─────────────┘          │   │
│  │                                                  │   │
│  │  ┌─────────────────────────────────────────┐   │   │
│  │  │   Repository Interfaces (输出端口)        │   │   │
│  │  │  - AgentSkillRepository                  │   │   │
│  │  │  - ConversationRepository                │   │   │
│  │  └─────────────────────────────────────────┘   │   │
│  │                                                  │   │
│  │  ┌─────────────────────────────────────────┐   │   │
│  │  │   Shared Kernel (共享内核)               │   │   │
│  │  │  - Language, ScriptCode (跨限界上下文)   │   │   │
│  │  └─────────────────────────────────────────┘   │   │
│  └──────────────────────────────────────────────────┘   │
└──────────────────────────────────┬──────────────────────┘
                                   │ 实现
┌──────────────────────────────────▼──────────────────────┐
│      Infrastructure Layer (基础设施层)                    │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐  │
│  │ MyBatis      │  │ Piston       │  │ LangChain4j │  │
│  │ Repositories │  │ Client       │  │ Adapter     │  │
│  └──────────────┘  └──────────────┘  └─────────────┘  │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Focused Configuration (模块化配置)               │   │
│  │  - DomainServicesConfig                          │   │
│  │  - ApplicationUseCaseConfig                       │   │
│  │  - AdapterConfig                                  │   │
│  └──────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────┘
```

### ✨ 架构优化亮点

#### 🎯 1. Shared Kernel（共享内核）
将多个限界上下文共享的通用值对象提取到 `domain/shared` 包：
- **Language** - 编程语言枚举
- **ScriptCode** - 脚本代码值对象
- **DomainEvent** - 领域事件基类
- **DomainException** - 领域异常基类
- **ValueObjects** - 通用值对象工具类

**优势**：避免重复代码，统一业务概念，降低维护成本。

#### 🔌 2. Common Ports（通用端口）
在 `application/common/port` 中定义可复用的用例接口：

**输入端口（Inbound Ports）**：
- **ChatUseCase** - 聊天用例接口
- **SkillCommandUseCase** - 技能命令操作接口
- **SkillQueryUseCase** - 技能查询接口

**输出端口（Outbound Ports）**：
- **AgentGateway** - AI Agent 网关接口
- **CodeExecutionGateway** - 代码执行网关接口
- **DomainEventPublisher** - 领域事件发布接口

**优势**：统一用例抽象，提高代码复用性，降低模块间耦合。

#### ⚙️ 3. Focused Configuration（模块化配置）
将原来的单体 `DDDConfig.java`（145行）拆分为3个职责明确的配置类：

- **DomainServicesConfig** - 领域服务配置
- **ApplicationUseCaseConfig** - 用例服务配置
- **AdapterConfig** - 适配器配置（外部服务、持久化等）

**优势**：符合单一职责原则，配置更清晰，易于维护和扩展。

#### 🧪 4. Architecture Tests（架构测试）
新增 `HexagonalArchitectureTest` 使用 ArchUnit 强制 enforce 架构规则：

```java
✅ Domain层不能依赖Application/Infrastructure/Interface层
✅ Application层不能依赖Infrastructure/Interface/框架SDK
✅ REST适配器不能依赖Infrastructure层
✅ REST适配器必须使用输入端口，不能直接使用Application实现
✅ Domain模型不能暴露public setter方法
```

**优势**：防止架构腐化，保证代码质量，CI/CD自动检查。

#### 🔗 5. LangChainAgentAdapter
新增 `LangChainAgentAdapter` 实现 `AgentGateway` 端口，替换旧的 `LangChainToolProviderAdapter`，提供更清晰的适配层。

**优势**：职责更明确，易于替换AI框架实现。

### DDD 核心要素

#### 1. 限界上下文（Bounded Context）

| 限界上下文 | 核心职责 | 聚合根 |
|-----------|---------|--------|
| **Agent技能管理** | 技能生命周期管理、动态工具提供 | AgentSkill |
| **聊天会话** | 会话管理、消息持久化 | Conversation |
| **代码执行** | 沙箱代码执行、结果处理 | CodeExecutionRequest |

#### 2. Shared Kernel（共享内核）✨ 新增

多个限界上下文共享的通用领域概念：

| 共享元素 | 类型 | 用途 |
|---------|------|------|
| **Language** | 枚举 | 编程语言定义（Python、JavaScript等） |
| **ScriptCode** | 值对象 | 脚本代码封装 |
| **DomainEvent** | 抽象基类 | 所有领域事件的基类 |
| **DomainException** | 抽象基类 | 所有领域异常的基类 |
| **ValueObjects** | 工具类 | 通用值对象校验工具 |

**设计原则**：
- ✅ 仅包含 truly shared 的概念
- ✅ 避免限界上下文间的循环依赖
- ✅ 变更需谨慎，影响范围广

#### 3. 聚合根（Aggregate Root）

```
AgentSkill (技能聚合根)
├── SkillCode (值对象)
├── SkillName (值对象)
├── SkillDescription (值对象)
├── SkillStatus (枚举)
├── DomainEventCollector (事件收集器)
└── 方法: create(), updateScriptCode(), toggleStatus(), enable(), disable()

Conversation (会话聚合根)
├── MemoryId (值对象)
├── List<ChatMessage> (实体集合)
└── 方法: create(), addMessage(), clearMessages()

CodeExecutionRequest (执行请求聚合根)
├── Language (共享值对象)
├── ScriptCode (共享值对象)
├── ExecutionStatus (枚举)
├── ExecutionResult (实体)
└── 方法: create(), markAsExecuting(), markAsSuccess(), markAsFailed()
```

#### 4. 领域服务（Domain Service）

- **SkillValidationService** - 技能验证逻辑
- **SkillExecutionService** - 技能执行上下文构建
- **MessageManagementService** - 消息管理
- **CodeExecutionService** - 代码执行验证和超时控制

#### 5. 仓储接口（Repository Port）

- **AgentSkillRepository** - 技能数据访问接口
- **ConversationRepository** - 会话数据访问接口

#### 6. 应用端口（Application Ports）✨ 优化

**输入端口（Inbound Ports）- 用例接口**：
- **ChatUseCase** - 聊天用例统一接口
- **SkillCommandUseCase** - 技能命令操作接口
- **SkillQueryUseCase** - 技能查询接口

**输出端口（Outbound Ports）- 网关接口**：
- **AgentGateway** - AI Agent 网关（抽象 LangChain4j）
- **CodeExecutionGateway** - 代码执行网关（抽象 Piston）
- **DomainEventPublisher** - 领域事件发布接口

#### 7. 领域事件（Domain Event）

- **SkillCreatedEvent** - 技能创建事件
- **SkillUpdatedEvent** - 技能更新事件
- **SkillStatusChangedEvent** - 技能状态变更事件

#### 8. 架构测试（Architecture Tests）✨ 新增

使用 **ArchUnit** 强制 enforce 架构规则：

```java
✅ Domain层不能依赖外层（Application/Infrastructure/Interface）
✅ Application层不能依赖Infrastructure/Interface/框架SDK
✅ REST适配器不能直接依赖Infrastructure层
✅ REST适配器必须使用输入端口，不能直接调用Application实现
✅ Domain模型不能暴露public setter方法（保护业务 invariants）
```

## 📁 优化后的 DDD 目录结构

```
com.demo
├── L4jSandboxApplication.java          # 启动类
│
├── domain/                            # ⭐ Domain层（核心业务层）
│   ├── agent/                         # Agent技能限界上下文
│   │   ├── model/                     # 领域模型
│   │   │   ├── AgentSkill.java        # 聚合根
│   │   │   ├── SkillCode.java         # 值对象
│   │   │   ├── SkillName.java
│   │   │   ├── SkillDescription.java
│   │   │   └── SkillStatus.java       # 枚举
│   │   ├── service/                   # 领域服务
│   │   │   ├── SkillValidationService.java
│   │   │   └── SkillExecutionService.java
│   │   ├── event/                     # 领域事件
│   │   │   ├── SkillCreatedEvent.java
│   │   │   ├── SkillUpdatedEvent.java
│   │   │   └── SkillStatusChangedEvent.java
│   │   ├── repository/                # 仓储接口（输出端口）
│   │   │   └── AgentSkillRepository.java
│   │   └── exception/                 # 领域异常
│   │       ├── InvalidSkillCodeException.java
│   │       └── SkillExecutionException.java
│   │
│   ├── conversation/                  # 聊天会话限界上下文
│   │   ├── model/                     # 领域模型
│   │   │   ├── Conversation.java      # 聚合根
│   │   │   ├── ChatMessage.java       # 实体
│   │   │   ├── MemoryId.java          # 值对象
│   │   │   ├── MessageContent.java
│   │   │   └── MessageRole.java       # 枚举
│   │   ├── service/                   # 领域服务
│   │   │   └── MessageManagementService.java
│   │   ├── repository/                # 仓储接口
│   │   │   └── ConversationRepository.java
│   │   └── exception/                 # 领域异常
│   │       ├── ConversationNotFoundException.java
│   │       └── ConversationOperationException.java
│   │
│   ├── execution/                     # 代码执行限界上下文
│   │   ├── model/                     # 领域模型
│   │   │   ├── CodeExecutionRequest.java  # 聚合根
│   │   │   ├── ExecutionResult.java       # 实体
│   │   │   ├── ExecutionStatus.java       # 枚举
│   │   │   └── ScriptCode.java
│   │   ├── service/                   # 领域服务
│   │   │   └── CodeExecutionService.java
│   │   └── exception/                 # 领域异常
│   │       ├── CodeExecutionException.java
│   │       └── ExecutionTimeoutException.java
│   │
│   └── shared/                        # ⭐ Shared Kernel（共享内核）✨ 新增
│       ├── model/                     # 跨限界上下文共享的通用值对象
│       │   ├── Language.java          # 编程语言枚举
│       │   ├── ScriptCode.java        # 脚本代码值对象
│       │   └── ValueObjects.java      # 通用值对象工具类
│       ├── event/                     # 共享领域事件
│       │   └── DomainEvent.java       # 领域事件基类
│       └── exception/                 # 共享领域异常
│           └── DomainException.java   # 领域异常基类
│
├── application/                       # ⭐ Application层（用例编排层）
│   ├── common/                        # ⭐ 通用组件 ✨ 优化
│   │   ├── port/                      # 端口定义
│   │   │   ├── in/                    # 输入端口（用例接口）
│   │   │   │   ├── ChatUseCase.java
│   │   │   │   ├── SkillCommandUseCase.java
│   │   │   │   └── SkillQueryUseCase.java
│   │   │   └── out/                    # 输出端口（网关接口）
│   │   │       ├── AgentGateway.java
│   │   │       ├── CodeExecutionGateway.java
│   │   │       └── DomainEventPublisher.java
│   │   └── exception/                  # 应用异常
│   │
│   ├── agent/                         # Agent技能用例
│   │   ├── service/
│   │   │   ├── AgentSkillManagementService.java
│   │   │   ├── SkillQueryService.java       # 接口
│   │   │   └── SkillQueryServiceImpl.java   # 实现
│   │   ├── dto/                       # 数据传输对象
│   │   │   ├── command/
│   │   │   │   ├── CreateAgentSkillCommand.java
│   │   │   │   ├── UpdateAgentSkillCommand.java
│   │   │   │   └── ToggleSkillStatusCommand.java
│   │   │   └── query/
│   │   │       └── AgentSkillDTO.java
│   │   └── mapper/                    # DTO映射器
│   │       └── AgentSkillDTOMapper.java
│   │
│   ├── chat/                          # 聊天编排用例
│   │   └── service/
│   │       ├── ChatOrchestrationService.java
│   │       └── ChatOrchestrationServiceImpl.java
│   │
│   └── conversation/                  # 会话管理用例
│       ├── service/
│       │   ├── ConversationManagementService.java
│       │   └── ConversationServiceImpl.java
│       └── dto/
│           └── ConversationDTO.java
│
├── infrastructure/                    # ⭐ Infrastructure层（基础设施层）
│   ├── config/                        # 配置类 ✨ 优化（模块化配置）
│   │   ├── LangChain4jConfig.java     # LangChain4j配置（新增）✨ 优化
│   │   ├── DomainServicesConfig.java       # 领域服务配置
│   │   ├── ApplicationUseCaseConfig.java   # 用例服务配置
│   │   └── AdapterConfig.java              # 适配器配置
│   │
│   ├── external/                      # 外部服务适配
│   │   ├── piston/                    # Piston沙箱
│   │   │   ├── PistonClient.java
│   │   │   ├── PistonCodeExecutionService.java
│   │   │   └── dto/                   # Piston API DTO
│   │   │       ├── PistonExecuteRequest.java
│   │   │       └── PistonExecuteResponse.java
│   │   └── langchain4j/               # LangChain4j适配 ✨ 重构
│   │       ├── LangChainAgentAdapter.java      # Agent网关适配器
│   │       ├── LangChainToolProviderAdapter.java # 工具提供器
│   │       └── ToolExecutorFactory.java         # 工具执行工厂
│   │
│   ├── event/                         # 领域事件基础设施 ✨ 新增
│   │   └── SpringDomainEventPublisher.java
│   │
│   └── persistence/                   # 持久化实现
│       ├── entity/                    # 数据层实体（DO）
│       │   ├── AgentSkillDO.java
│       │   └── ChatMemoryDO.java
│       ├── mapper/                    # MyBatis Mapper
│       │   ├── AgentSkillMapper.java
│       │   └── ChatMemoryMapper.java
│       ├── repository/                 # 仓储实现（适配器）
│       │   ├── MyBatisAgentSkillRepository.java
│       │   └── MyBatisConversationRepository.java
│       └── store/                     # LangChain4j存储适配
│           └── MyBatisChatMemoryStore.java
│
└── interfaces/                        # ⭐ Interface层（接口适配层）
    └── rest/                          # REST API
        ├── controller/
        │   └── ApiController.java
        ├── dto/                       # API DTO
        │   ├── request/
        │   │   ├── ChatRequestDTO.java
        │   │   ├── UpdateSkillRequestDTO.java
        │   │   └── ToggleSkillRequestDTO.java
        │   └── response/
        │       └── ChatResponseDTO.java
        └── exception/                  # 全局异常处理
            └── GlobalExceptionHandler.java
```

## ✅ DDD 原则验证

### ✅ 1. 依赖倒置原则（DIP）
- Domain层定义Repository接口和输入端口（定义"what"）
- Infrastructure层实现输出端口（实现"how"）
- Application层通过接口调用，不依赖具体实现

### ✅ 2. 单一职责原则（SRP）
- **Domain**: 只负责业务逻辑
- **Application**: 只负责用例编排
- **Infrastructure**: 只负责技术实现
- **Interface**: 只负责HTTP请求/响应

### ✅ 3. 开闭原则（OCP）
- 对扩展开放：新增限界上下文只需添加新包
- 对修改关闭：现有代码无需改动

### ✅ 4. 接口隔离原则（ISP）
- 细粒度的Repository接口
- 专门的Command/Query DTO
- 通用的输入/输出端口

### ✅ 5. 技术无关性
- Domain层纯Java，无任何框架依赖
- 可轻松替换MyBatis、LangChain4j等技术栈

### ✅ 6. 架构一致性原则（ACP）✨ 新增
- 使用ArchUnit自动 enforce 架构规则
- 防止依赖方向错误
- 保证代码符合DDD六边形架构规范

## 📊 代码统计（优化后）

```
Domain层:          27个类（模型+服务+仓储+事件+异常+共享内核）
Application层:     28个类（服务+DTO+映射器+通用端口）✨ 优化
Infrastructure层:  29个类（配置+外部服务+持久化+事件发布）✨ 优化
Interface层:       6个类（Controller+DTO+异常处理）
架构测试:          1个类（HexagonalArchitectureTest）✨ 新增

总计: 91个类
```

### 优化对比

| 层级 | 优化前 | 优化后 | 变化 |
|------|--------|--------|------|
| **Domain层** | 23个 | 27个 | +4（新增Shared Kernel） |
| **Application层** | 18个 | 28个 | +10（新增Common Ports） |
| **Infrastructure层** | 24个 | 29个 | +5（模块化配置+事件发布+LangChainAgentAdapter） |
| **架构质量** | 无自动检查 | ArchUnit架构测试 | 质的提升 ✨ |
| **总代码量** | 71个 | 91个 | +20（约28%增长，质量大幅提升） |

**关键优化点**：
- ✅ Shared Kernel 减少重复代码
- ✅ Common Ports 提高复用性
- ✅ 模块化配置 提高可维护性
- ✅ 架构测试 防止架构腐化
- ✅ 配置类从145行拆分为3个30-70行的类

## 技术栈

| 组件 | 版本 | 备注 |
|------|------|------|
| Java | 17 | |
| Spring Boot | 3.4.5 | |
| LangChain4j | 1.14.1 | 最新稳定版 |
| MyBatis-Plus | 3.5.16 | |
| MySQL | 8.x | |
| Caffeine Cache | 3.1.8 | Spring Boot 管理 |
| React | 18.x | 前端框架 |
| Vite | 6.x | 前端构建工具 |
| Ant Design | 5.x | UI 组件库 |

## 📝 版本更新日志

### 2026-05-13 - v1.1.0

#### 🐛 Bug 修复
- **修复 LangChain4j 依赖问题**
  - 升级 LangChain4j 从 `1.3.0-beta9` 到稳定版 `1.14.1`
  - 修正不存在的 artifactId `langchain4j-open-ai-spring-boot-starter` → `langchain4j-open-ai`
  - 统一依赖版本管理，消除版本冲突

- **API 不兼容重构**
  - 移除不存在的 LangChain4j API（`ToolExecutor`、`ToolProvider`、`ChatMemoryProvider` 等）
  - 基于 LangChain4j 1.14.1 实际 API 完全重构工具调用逻辑
  - 新增 `LangChain4jConfig` 配置类，统一管理 ChatModel

#### 🏗️ 架构优化
- **POM 结构优化**
  - 统一父模块标识为 `l4j-sandbox`
  - 补充 `dependencyManagement` 统一版本管理
  - 移除子模块重复配置
  - 优化 `crypto-spring-boot-starter` 继承关系

#### 🧪 测试修复
- 更新单元测试适配新的 LangChain4j API

### 2026-05-xx - v1.0.0

- 初始版本发布
- 实现 DDD 六边形架构
- 支持动态技能管理
- 集成 LangChain4j AI 能力
- 集成 Piston 代码沙箱

## 快速开始

### 1. 环境准备

- JDK 17+
- MySQL 8.x
- Docker（运行 Piston 沙箱）
- 兼容 OpenAI API 的 LLM 服务（如 Ollama、vLLM）

### 2. 初始化数据库

```sql
-- 执行建表脚本
source src/main/resources/db/init.sql;
```

### 3. 启动 Piston 沙箱

```bash
docker run -d --name piston -p 2000:2000 ghcr.io/engineer-man/piston
```

### 4. 配置 application.yml

```yaml
server:
  port: 8090

spring:
  datasource:
    url: jdbc:mysql://localhost:3308/agent_db?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root
    password: root1234
    driver-class-name: com.mysql.cj.jdbc.Driver

  cache:
    type: caffeine
    caffeine:
      spec: maximumSize=100,expireAfterWrite=10m

# LangChain4j - OpenAI 兼容接口配置
langchain4j:
  open-ai:
    chat-model:
      base-url: https://cpa.520999.best/v1  # OpenAI 兼容接口地址
      api-key: sk-hgqXgfFFdQ54xdOw8         # API密钥
      model-name: opencode/glm-5.1          # 模型名称
      temperature: 0.7                       # 温度参数
      timeout: 60s                           # 超时时间

# Piston 沙箱配置
piston:
  base-url: http://127.0.0.1:2000
  run-timeout: 5000

# MyBatis-Plus
mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
  global-config:
    db-config:
      id-type: auto

logging:
  level:
    com.demo: DEBUG
    dev.langchain4j: DEBUG
```

**配置说明**：
- `LangChain4jConfig` 读取 `langchain4j.open-ai.*` 配置
- 自动创建 `ChatModel` Bean
- 支持 `base-url`、`api-key`、`model-name`、`temperature`、`timeout` 等参数

### 5. 启动前端

```bash
cd l4j-ui
pnpm install
pnpm dev
```

前端将在 `http://localhost:5173` 启动（Vite 默认端口）。

## API 接口文档

详细的 API 接口文档请查看 [API.md](API.md)。

### 快速测试

```bash
# 聊天接口
curl "http://localhost:8090/api/chat?msg=帮我算一下1+2+3的和&memoryId=user1"

# 查看所有启用的技能
curl http://localhost:8090/api/skills

# 热更新技能脚本
curl -X POST http://localhost:8090/api/skill/update \
  -H "Content-Type: application/json" \
  -d '{"id": 1, "scriptCode": "import json\nprint(json.dumps({\"result\": 42}))"}'
```

## 会话记忆

会话历史通过 `MyBatisChatMemoryStore` 持久化到 MySQL 的 `chat_memory` 表，重启服务后对话不丢失。每个 `memoryId` 独立维护最多 10 条消息的滑动窗口。

## 测试

```bash
mvn test
```

## 架构优势

- 🎯 **清晰的业务边界** - 3个限界上下文，职责明确
- 🔧 **高可维护性** - 依赖倒置，易于理解和修改
- 🧪 **高可测试性** - 领域层可独立单元测试 + ArchUnit架构测试
- 📈 **良好的扩展性** - 新增功能无需修改核心业务逻辑
- 🔄 **技术栈可替换性** - Domain层纯Java，可轻松替换基础设施
- 🎁 **Shared Kernel** - 减少重复代码，统一业务概念
- 🔌 **通用端口** - 提高代码复用性，降低模块间耦合
- ✅ **架构保证** - ArchUnit自动 enforce 架构规则，防止腐化

## ✨ DDD六边形架构优化总结

本次优化在原有DDD六边形架构基础上，引入了业界最佳实践：

### 核心优化点

| 优化项 | 优化前 | 优化后 | 收益 |
|--------|--------|--------|------|
| **共享内核** | 值对象分散在各限界上下文 | `domain/shared` 统一管理 | 减少重复，统一概念 |
| **通用端口** | 端口定义分散 | `application/common/port` 集中管理 | 提高复用性 |
| **配置模块化** | 单体DDDConfig（145行） | 4个职责明确的配置类 | 符合SRP，易维护 |
| **架构测试** | 无自动检查 | ArchUnit 5条规则自动检查 | 防止架构腐化 |
| **LangChain4j集成** | 不存在的API（1.3.0-beta9） | 稳定版1.14.1实际API | 可编译运行 |
| **配置类** | - | `LangChain4jConfig` 统一管理 | 简化配置 |

### 优化效果

✅ **代码质量提升**
- 架构规则自动化检查，CI/CD集成
- 配置类平均规模从145行降至50行
- Shared Kernel 消除4处重复定义
- LangChain4j 版本从不存在的beta版升级到稳定版

✅ **可维护性提升**
- 新增限界上下文更简单
- 替换技术栈更便捷
- 代码结构更清晰，新人上手更快
- 依赖版本统一管理，避免冲突

✅ **可扩展性增强**
- Common Ports 支持快速添加新用例
- Shared Kernel 支持跨上下文复用
- 模块化配置支持按需加载

### 关键设计决策

1. **Shared Kernel 只包含 truly shared 的概念**
   - Language、ScriptCode 等跨多个上下文使用的值对象
   - 避免过度设计，保持最小化

2. **Common Ports 聚焦于可复用场景**
   - ChatUseCase、SkillCommandUseCase、SkillQueryUseCase
   - AgentGateway、CodeExecutionGateway 等外部服务接口
   - 不滥用，只在确实需要复用时才提取

3. **架构测试作为质量门禁**
   - 在CI/CD pipeline中运行
   - 5条规则覆盖主要架构约束
   - 防止"破窗效应"

4. **配置类按职责拆分**
   - `LangChain4jConfig`：AI模型配置
   - `DomainServicesConfig`：领域服务Bean
   - `ApplicationUseCaseConfig`：用例服务Bean
   - `AdapterConfig`：外部适配器Bean
   - 每个配置类职责单一，易于理解和修改

5. **LangChain4j 版本锁定与API适配**
   - 使用稳定版 `1.14.1`，避免 beta 版本的不稳定性
   - 基于实际 API 重构，不使用不存在的抽象层
   - 简化工具调用流程：直接使用 `ChatModel.chat()` 而非 `AiServices.builder()`
   - 新增 `LangChain4jConfig` 统一管理配置，避免硬编码

### 下一步建议

1. **扩展架构测试覆盖**
   - 添加更多业务规则验证
   - 添加命名规范检查
   - 添加循环依赖检查

2. **完善 Shared Kernel**
   - 添加通用ID生成器
   - 添加通用校验器
   - 添加通用事件基类

3. **增加 CQRS 支持**
   - 查询侧独立优化
   - 命令侧事件溯源
   - 读写分离

4. **文档自动化**
   - 从代码生成架构文档
   - 从架构测试生成架构规则文档
   - 集成到CI/CD自动更新README