MineNasAI/README.md

# MineNASAI

基于 NAS 的智能个人 AI 助理，支持企业微信/飞书通讯，集成多 LLM 编程能力。

[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://python.org)
[![Tests](https://img.shields.io/badge/Tests-131%20passed-green.svg)](tests/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](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