8.4 KiB
8.4 KiB
MineNASAI
基于 NAS 的智能个人 AI 助理，支持企业微信/飞书通讯，集成多 LLM 编程能力。
特性
- 多 LLM 支持: Anthropic Claude、OpenAI、DeepSeek、智谱、MiniMax、Moonshot、Gemini
- 多渠道通讯: 企业微信、飞书接入
- 智能路由: 自动识别任务复杂度，选择最优处理方式
- 双界面模式:
- 通讯工具：日常交互、简单任务
- Web TUI：深度编程、复杂项目
- 安全隔离: Python 沙箱执行、权限分级、确认机制
- 生产就绪: 健康检查、监控指标、Docker 部署
- 可扩展: 工具注册中心、Cron 定时任务
快速开始
环境要求
- Python 3.11+
- Redis (可选，用于任务队列)
- SSH 服务 (Web TUI 需要)
安装
# 克隆项目
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
配置
# 复制环境变量模板
cp .env.example .env
# 编辑 .env 文件，填入 API Key
# MINENASAI_ANTHROPIC_API_KEY=sk-ant-xxxxx
# MINENASAI_DEEPSEEK_API_KEY=sk-xxxxx
运行
# 启动 Gateway 服务
python -m uvicorn minenasai.gateway.server:app --port 8000
# 启动 Web TUI 服务（另一个终端）
python -m uvicorn minenasai.webtui.server:app --port 8080
Docker 部署
# 构建并启动
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 | 境外 | 需要 |
| 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 | 会话列表 |
开发
代码规范
# 格式化代码
ruff format src tests
# 检查代码
ruff check src tests
# 类型检查
mypy src
测试
# 运行所有测试
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 |
环境变量
# 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