251 lines
8.4 KiB
Markdown
251 lines
8.4 KiB
Markdown
# MineNASAI
|
||
|
||
基于 NAS 的智能个人 AI 助理，支持企业微信/飞书通讯，集成多 LLM 编程能力。
|
||
|
||
[](https://python.org)
|
||
[](tests/)
|
||
[](LICENSE)
|
||
|
||
## 特性
|
||
|
||
- **多 LLM 支持**: Anthropic Claude、OpenAI、DeepSeek、智谱、MiniMax、Moonshot、Gemini
|
||
- **多渠道通讯**: 企业微信、飞书接入
|
||
- **智能路由**: 自动识别任务复杂度，选择最优处理方式
|
||
- **双界面模式**:
|
||
- 通讯工具：日常交互、简单任务
|
||
- Web TUI：深度编程、复杂项目
|
||
- **安全隔离**: Python 沙箱执行、权限分级、确认机制
|
||
- **生产就绪**: 健康检查、监控指标、Docker 部署
|
||
- **可扩展**: 工具注册中心、Cron 定时任务
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Python 3.11+
|
||
- Redis (可选，用于任务队列)
|
||
- SSH 服务 (Web TUI 需要)
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone http://jiulu-gameplay.com.cn:13001/congsh/MineNasAI.git
|
||
cd MineNasAI
|
||
|
||
# 创建虚拟环境
|
||
python -m venv .venv
|
||
.venv\Scripts\activate # Windows
|
||
# source .venv/bin/activate # Linux/macOS
|
||
|
||
# 安装依赖
|
||
pip install -e ".[dev]"
|
||
|
||
# 安装 pre-commit 钩子
|
||
pre-commit install
|
||
```
|
||
|
||
### 配置
|
||
|
||
```bash
|
||
# 复制环境变量模板
|
||
cp .env.example .env
|
||
|
||
# 编辑 .env 文件，填入 API Key
|
||
# MINENASAI_ANTHROPIC_API_KEY=sk-ant-xxxxx
|
||
# MINENASAI_DEEPSEEK_API_KEY=sk-xxxxx
|
||
```
|
||
|
||
### 运行
|
||
|
||
```bash
|
||
# 启动 Gateway 服务
|
||
python -m uvicorn minenasai.gateway.server:app --port 8000
|
||
|
||
# 启动 Web TUI 服务（另一个终端）
|
||
python -m uvicorn minenasai.webtui.server:app --port 8080
|
||
```
|
||
|
||
### Docker 部署
|
||
|
||
```bash
|
||
# 构建并启动
|
||
docker-compose up -d
|
||
|
||
# 查看日志
|
||
docker-compose logs -f gateway
|
||
|
||
# 停止服务
|
||
docker-compose down
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
MineNasAI/
|
||
├── src/minenasai/
|
||
│ ├── core/ # 核心模块
|
||
│ │ ├── config.py # 配置管理
|
||
│ │ ├── logging.py # 日志系统
|
||
│ │ ├── database.py # 数据库
|
||
│ │ ├── monitoring.py # 监控与健康检查
|
||
│ │ └── cache.py # 缓存与限流
|
||
│ ├── gateway/ # Gateway 服务
|
||
│ │ ├── protocol/ # 消息协议
|
||
│ │ ├── router.py # 智能路由
|
||
│ │ ├── server.py # FastAPI 服务
|
||
│ │ └── channels/ # 通讯渠道
|
||
│ ├── llm/ # LLM 集成
|
||
│ │ ├── base.py # 基础接口
|
||
│ │ ├── manager.py # LLM 管理器
|
||
│ │ └── clients/ # 各提供商客户端
|
||
│ ├── agent/ # Agent 运行时
|
||
│ │ ├── runtime.py # Agent 执行
|
||
│ │ ├── permissions.py # 权限管理
|
||
│ │ ├── tool_registry.py # 工具注册
|
||
│ │ └── tools/ # 内置工具
|
||
│ ├── scheduler/ # 定时任务
|
||
│ │ └── cron.py # Cron 调度器
|
||
│ └── webtui/ # Web TUI
|
||
│ ├── server.py # TUI 服务器
|
||
│ ├── auth.py # 认证管理
|
||
│ ├── ssh_manager.py # SSH 管理
|
||
│ └── static/ # 前端文件
|
||
├── tests/ # 测试用例 (131 tests)
|
||
├── config/ # 配置模板
|
||
├── Dockerfile # Docker 构建
|
||
└── docker-compose.yml # 容器编排
|
||
```
|
||
|
||
## 架构概述
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 通讯接入层 (Channels) │
|
||
│ 企业微信Bot 飞书Bot Web UI │
|
||
└────────────────────────────┬────────────────────────────────┘
|
||
│
|
||
┌────────────────────────────┴────────────────────────────────┐
|
||
│ Gateway 服务 (FastAPI) │
|
||
│ WebSocket协议 / 监控指标 / 健康检查 / CORS │
|
||
└────────────────────────────┬────────────────────────────────┘
|
||
│
|
||
┌────────────────────────────┴────────────────────────────────┐
|
||
│ 智能路由层 (SmartRouter) │
|
||
│ 任务复杂度评估 / 单/多Agent决策 │
|
||
└────────────────────────────┬────────────────────────────────┘
|
||
│
|
||
┌───────────────────┼───────────────────┐
|
||
↓ ↓ ↓
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ 快速执行通道 │ │ 多 LLM │ │ Web TUI │
|
||
│ Python沙箱 │ │ API │ │ SSH+Claude │
|
||
└─────────────┘ └─────────────┘ └─────────────┘
|
||
│
|
||
┌───────────────────┼───────────────────┐
|
||
↓ ↓ ↓
|
||
Anthropic Claude DeepSeek/智谱 OpenAI/Gemini
|
||
```
|
||
|
||
## 支持的 LLM 提供商
|
||
|
||
| 提供商 | 模型示例 | 区域 | 代理 |
|
||
|--------|----------|------|------|
|
||
| Anthropic | claude-sonnet-4-20250514 | 境外 | 需要 |
|
||
| OpenAI | gpt-4o | 境外 | 需要 |
|
||
| Google | gemini-2.0-flash | 境外 | 需要 |
|
||
| DeepSeek | deepseek-chat | 国内 | 不需要 |
|
||
| 智谱 | glm-4-flash | 国内 | 不需要 |
|
||
| MiniMax | abab6.5s-chat | 国内 | 不需要 |
|
||
| Moonshot | moonshot-v1-8k | 国内 | 不需要 |
|
||
|
||
## API 端点
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/` | GET | 服务状态 |
|
||
| `/health` | GET | 完整健康检查 |
|
||
| `/health/live` | GET | 存活检查 (K8s) |
|
||
| `/health/ready` | GET | 就绪检查 (K8s) |
|
||
| `/metrics` | GET | 监控指标 |
|
||
| `/ws` | WebSocket | 消息通道 |
|
||
| `/api/agents` | GET | Agent 列表 |
|
||
| `/api/sessions` | GET | 会话列表 |
|
||
|
||
## 开发
|
||
|
||
### 代码规范
|
||
|
||
```bash
|
||
# 格式化代码
|
||
ruff format src tests
|
||
|
||
# 检查代码
|
||
ruff check src tests
|
||
|
||
# 类型检查
|
||
mypy src
|
||
```
|
||
|
||
### 测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
pytest
|
||
|
||
# 带覆盖率
|
||
pytest --cov=minenasai
|
||
|
||
# 详细输出
|
||
pytest -v --tb=short
|
||
```
|
||
|
||
### 当前测试覆盖
|
||
|
||
- **test_core.py**: 配置、日志 (9 tests)
|
||
- **test_gateway.py**: 协议、路由 (14 tests)
|
||
- **test_llm.py**: LLM 客户端 (10 tests)
|
||
- **test_monitoring.py**: 监控、健康检查 (17 tests)
|
||
- **test_cache.py**: 缓存、限流 (21 tests)
|
||
- **test_permissions.py**: 权限、工具注册 (17 tests)
|
||
- **test_scheduler.py**: Cron 调度 (15 tests)
|
||
- **test_tools.py**: 内置工具 (14 tests)
|
||
- **test_webtui.py**: Web TUI (14 tests)
|
||
|
||
## 配置说明
|
||
|
||
配置文件: `config/config.json5`
|
||
|
||
主要配置项:
|
||
|
||
| 配置项 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `gateway.port` | Gateway 端口 | 8000 |
|
||
| `webtui.port` | Web TUI 端口 | 8080 |
|
||
| `llm.default_provider` | 默认 LLM 提供商 | anthropic |
|
||
| `llm.default_model` | 默认模型 | claude-sonnet-4-20250514 |
|
||
| `proxy.enabled` | 是否启用代理 | false |
|
||
| `router.mode` | 路由模式 | agent |
|
||
|
||
## 环境变量
|
||
|
||
```bash
|
||
# LLM API Keys
|
||
MINENASAI_ANTHROPIC_API_KEY=sk-ant-xxx
|
||
MINENASAI_OPENAI_API_KEY=sk-xxx
|
||
MINENASAI_DEEPSEEK_API_KEY=sk-xxx
|
||
MINENASAI_ZHIPU_API_KEY=xxx
|
||
MINENASAI_MINIMAX_API_KEY=xxx
|
||
MINENASAI_MOONSHOT_API_KEY=sk-xxx
|
||
MINENASAI_GEMINI_API_KEY=xxx
|
||
|
||
# 代理设置 (境外 API)
|
||
MINENASAI_PROXY_ENABLED=true
|
||
MINENASAI_PROXY_HTTP=http://127.0.0.1:7890
|
||
MINENASAI_PROXY_HTTPS=http://127.0.0.1:7890
|
||
```
|
||
|
||
## 许可证
|
||
|
||
MIT License
|