# eh-claw

**Repository Path**: MISSMYSEIF/eh-claw

## Basic Information

- **Project Name**: eh-claw
- **Description**: 一个前后端分离的企业级 AI 助手平台
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🦞 eh-claw

> 企业级多租户 AI 助手平台 | Enterprise SaaS Multi-tenant AI Assistant Platform

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 📌 项目简介

eh-claw 是一个参考 Hermes、OpenClaw、MateClaw 等 AI 系统优点设计的企业级 AI 助手平台，采用 **Spring Cloud 微服务 + Vue3 前后端分离** 架构，支持 SaaS 多租户，提供多模型对话、知识库 RAG、工具调用、Agent 工作流编排四大核心能力。

---

## ✨ 核心特性

| 能力 | 描述 |
|------|------|
| 🤖 **多模型对话** | 支持 OpenAI/Anthropic/DeepSeek/Ollama/通义/GLM/Kimi 等多模型切换，SSE 真 token 流式输出，上下文窗口自动裁剪，智能路由，对话分享/导出/全文搜索/翻译 |
| 📚 **知识库 RAG** | 文档上传解析 (Apache Tika)，向量化 (Milvus)，语义检索增强生成，引用溯源，URL 同步，**大文件分片上传**，文档版本管理 |
| 🔧 **工具调用** | JSON Schema 工具注册，Docker 沙箱隔离执行，**高风险工具人工审批流**，Function Calling 协议，工具执行详细审计 |
| 🔄 **Agent 工作流** | 可视化 DAG 编排，版本管理与回滚，拓扑并行执行，断点续跑，实时状态推送，**定时调度**，**社区模板市场** |
| 🌐 **内容合规** | 敏感词库管理（增删改查/启停用），BLOCK/REPLACE/LOG 三级策略，消息链路自动过滤，命中打码 |
| 🏢 **SaaS 多租户** | 行级数据隔离，工作空间/成员/角色管理，Token/存储/API 配额控制，成员维度用量分摊 |
| 📱 **多端适配** | Web (Vue3) + Flutter 移动端 + Electron PC 端 + HarmonyOS 鸿蒙端，**四端全量双语化**（zh-CN/en-US），移动端 APNs/FCM 推送 |
| 🗄️ **多数据库** | SQLite（默认）/ MySQL / PostgreSQL 无缝切换 |
| 🔐 **安全认证** | JWT 令牌认证，Token 黑名单，API 限流，TOTP 双因素认证（MFA），登录防爆破/账户锁定（防 DoS），OAuth（Google/GitHub/钉钉），API Key 生命周期管理，审计日志（@Auditable 关键操作全链路落库） |
| 📊 **真实监控** | Dashboard 聚合真实请求/延迟/错误指标，模型用量真实落库与计费统计（按天/模型/Provider/成员），**Prometheus/Grafana 对接**，全链路 TraceId 日志关联（MDC），自定义 `ehclaw_http_*` 业务指标（按 application/uri 聚合 QPS/P95/错误率） |
| 🧩 **配额管控** | 知识库/文档/工具/工作流/Token 配额在业务链路真实检查、消费与释放（删除资源自动回退计数） |
| 🛰️ **运维健康** | RabbitMQ 死信队列深度监控，网关/服务健康检查，通知偏好逐用户过滤，Webhook 订阅与投递重试，用户通知收件箱（未读角标/已读同步），**Zipkin 链路追踪** |

---

## 🛠️ 技术栈

### 后端

| 技术 | 版本 | 用途 |
|------|------|------|
| Java | 17 | 运行时 |
| Spring Boot | 3.2.x | 应用框架 |
| Spring Cloud | 2023.0.x | 微服务治理 |
| MyBatis-Plus | 3.5.6 | ORM + 多租户 + 分页 |
| SQLite | 3.45+ | 默认数据库（开发） |
| MySQL | 8.0 | 关系数据库（生产） |
| PostgreSQL | 15 | 关系数据库（生产） |
| Redis | 7.2 | 缓存/限流/分布式锁 |
| RabbitMQ | 3.13 | 异步消息 |
| Milvus | 2.4 | 向量数据库 |
| MinIO | latest | 对象存储 |
| Resilience4j | 2.2.0 | 熔断降级 |
| Apache Tika | 2.9.x | 文档解析 |

### 前端

| 技术 | 版本 | 用途 |
|------|------|------|
| Vue3 + TypeScript | 3.x | Web 前端框架 |
| Vite | 5.x | 构建工具 |
| Pinia | 2.x | 状态管理 |
| Element Plus | 2.x | UI 组件库 |
| ECharts | 5.x | 图表 |
| Vue Flow | 1.x | 工作流可视化编排 |
| Flutter | 3.x | iOS/Android 移动端 |
| Electron | 28.x | PC 桌面端 |
| HarmonyOS ArkUI | - | 鸿蒙端 |

---

## 🚀 快速开始

### 环境要求

| 依赖 | 版本 | 必装 |
|------|------|------|
| JDK | 17+ | ✅ |
| Maven | 3.8+ | ✅ |
| Node.js | 18+ | ✅ |
| npm | 8+ | ✅ |
| Python | 3.9+ | 可选（测试） |
| Docker | latest | 可选 |

> 💡 **SQLite 开发模式**：无需安装 MySQL/Docker，直接启动即可。

### Windows 一键启动

```bat
start-dev.bat    # 一键启动开发环境
stop-dev.bat     # 一键暂停开发环境
```

### 手动启动

```bash
# 1. 启动后端
cd backend
mvn clean package -DskipTests
# 依次启动各服务（网关优先）
java -jar gateway-service/target/gateway-service-1.0.0-SNAPSHOT.jar

# 2. 启动前端
cd frontend/web
npm install
npm run dev
```

访问 **http://localhost:5173**

### 默认账号

| 用户名 | 密码 | 说明 |
|--------|------|------|
| `admin` | 由 `ADMIN_DEFAULT_PASSWORD` 环境变量指定 | 平台管理员。若未设置该环境变量，系统首次启动时自动生成随机安全密码并打印到日志 |

> **生产部署安全提醒**：请务必设置强随机 `ADMIN_DEFAULT_PASSWORD` 环境变量，避免使用默认/弱密码。

---

## 📚 文档中心

详细文档请参考 [docs/README.md](./docs/README.md)：

| 文档 | 说明 |
|------|------|
| [快速开始](./docs/tutorials/quickstart.md) | 从零搭建开发环境 |
| [系统架构](./docs/architecture/system-architecture.md) | 微服务架构设计 |
| [数据库设计](./docs/architecture/database-design.md) | 多数据库适配说明 |
| [LLM 对接教程](./docs/tutorials/llm-integration.md) | 模型 Provider 完整接入指南 |
| [API 文档](./docs/api/README.md) | 全部接口文档 |
| [接口全集参考](./docs/api/reference.md) | 180 个接口速查表 |
| [变更日志](./CHANGELOG.md) | 完整变更记录 |
| [测试指南](./docs/development/testing.md) | 完整测试体系与覆盖率说明 |

---

## 📁 项目结构

```
eh-claw/
├── 📄 README.md             # 项目说明
├── 📄 LICENSE               # MIT 开源协议
├── 📄 start-dev.bat         # Windows 一键启动
├── 📄 stop-dev.bat          # Windows 一键暂停
├── 📁 docs/                 # 项目文档
├── 📁 backend/              # 后端微服务（10个）
├── 📁 frontend/             # 前端（Web/Mobile/Desktop/Harmony）
├── 📁 tests/                # Python 测试脚本
├── 📁 deploy/               # Docker/K8s/监控
└── 📁 scripts/              # 数据库脚本
```

## 数据库适配

项目支持多数据库，默认使用 SQLite（零配置开发）。

| 数据库 | 场景 | 配置 |
|--------|------|------|
| SQLite | 开发环境（默认） | 无需配置 |
| MySQL 8.0 | 生产环境 | `DB_DRIVER=mysql` |
| PostgreSQL 15 | 生产环境 | `DB_DRIVER=postgresql` |

## 测试

### 测试体系

| 类型 | 数量 | 说明 |
|------|------|------|
| Python 单元测试/守护 | 1117（968 通过 + 149 跳过） | 纯逻辑与结构守护测试，无需后端 |
| Java 单元测试 | 740（111 文件） | 后端各服务单元测试（由 Maven CI 编译运行） |
| 前端 Vitest | 258（37 文件） | 前端组件/API/i18n/SSE/工作流/通知中心/语言切换/状态管理测试 |

### Python 测试脚本

```bash
pip install -r tests/requirements.txt
pytest tests/ -v
```

### Java 单元测试

```bash
cd backend && mvn test
```

### 前端测试

```bash
cd frontend/web && npx vitest run
```

### 覆盖率

```bash
# Python 覆盖率
pip install pytest-cov
pytest tests/unit/ --cov=. --cov-report=term-missing

# Java 覆盖率
cd backend && mvn test -Djacoco.skip=false
```

---

## 📄 开源协议

本项目使用 [MIT License](./LICENSE) 开源协议。

---

## 📞 联系方式

- Issue: [GitHub Issues](https://cnb.cool/tucheng_cheng/eh-claw/-/issues)
- 文档: [docs/](docs/README.md)

---

*Powered by eh-claw Team* 🚀