congsh/MineNasAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: 更新配置文件和清理文档

Browse Source
This commit is contained in:
congsh
2026-02-05 16:21:25 +08:00
parent 64dc18f477
commit 950303ced5
7 changed files with 287 additions and 1614 deletions
Download Patch File Download Diff File Expand all files Collapse all files

251
README.md
View File

@@ -1,250 +1 @@
# 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
# MineNasAI