feat: 添加项目规则、环境配置示例及开发文档

2026-02-04 18:49:38 +08:00
commit df76882178
88 changed files with 13150 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,149 @@
+# MineNASAI
+
+基于 NAS 的智能个人 AI 助理，支持企业微信/飞书通讯，集成 Claude 编程能力。
+
+## 特性
+
+- **多渠道通讯**: 企业微信、飞书接入
+- **智能路由**: 自动识别任务复杂度，选择最优处理方式
+- **双界面模式**:
+  - 通讯工具：日常交互、简单任务
+  - Web TUI：深度编程、复杂项目
+- **安全隔离**: Python 沙箱执行、权限分级
+- **可扩展**: 支持 MCP Server 插件
+
+## 快速开始
+
+### 环境要求
+
+- Python 3.11+
+- Redis (可选，用于任务队列)
+- SSH 服务 (Web TUI 需要)
+
+### 安装
+
+```bash
+# 克隆项目
+git clone https://github.com/minenasai/minenasai.git
+cd minenasai
+
+# 创建虚拟环境
+python -m venv .venv
+source .venv/bin/activate  # Linux/macOS
+# .venv\Scripts\activate  # Windows
+
+# 安装依赖
+pip install -e ".[dev]"
+
+# 安装 pre-commit 钩子
+pre-commit install
+```
+
+### 配置
+
+```bash
+# 复制环境变量模板
+cp .env.example .env
+
+# 编辑 .env 文件，填入 API Key 等配置
+# ANTHROPIC_API_KEY=sk-ant-xxxxx
+
+# 初始化配置文件
+minenasai config --init
+```
+
+### 运行
+
+```bash
+# 启动 Gateway 服务
+minenasai server --port 8000
+
+# 启动 Web TUI 服务（另一个终端）
+minenasai webtui --port 8080
+```
+
+## 项目结构
+
+```
+minenasai/
+├── src/minenasai/
+│   ├── core/           # 核心模块（配置、日志）
+│   ├── gateway/        # Gateway 服务
+│   │   ├── protocol/   # 消息协议
+│   │   └── channels/   # 通讯渠道（企业微信、飞书）
+│   ├── agent/          # Agent 运行时
+│   │   └── tools/      # 内置工具
+│   └── webtui/         # Web TUI 界面
+│       └── static/     # 前端静态文件
+├── tests/              # 测试用例
+├── config/             # 配置文件模板
+└── docs/               # 文档
+```
+
+## 架构概述
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    通讯接入层 (Channels)                      │
+│      企业微信Bot          飞书Bot          Web UI            │
+└────────────────────────────┬────────────────────────────────┘
+                             │
+┌────────────────────────────┴────────────────────────────────┐
+│                   Gateway 服务 (FastAPI)                     │
+│              WebSocket协议 / 消息队列 / 权限验证              │
+└────────────────────────────┬────────────────────────────────┘
+                             │
+┌────────────────────────────┴────────────────────────────────┐
+│                   智能路由层 (SmartRouter)                    │
+│              任务复杂度评估 / 单/多Agent决策                  │
+└────────────────────────────┬────────────────────────────────┘
+                             │
+         ┌───────────────────┼───────────────────┐
+         ↓                   ↓                   ↓
+   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+   │ 快速执行通道 │     │ Anthropic   │     │  Web TUI    │
+   │ Python沙箱  │     │    API      │     │ SSH+Claude  │
+   └─────────────┘     └─────────────┘     └─────────────┘
+```
+
+## 开发
+
+### 代码规范
+
+```bash
+# 格式化代码
+ruff format src tests
+
+# 检查代码
+ruff check src tests
+
+# 类型检查
+mypy src
+```
+
+### 测试
+
+```bash
+# 运行测试
+pytest
+
+# 带覆盖率
+pytest --cov=minenasai
+```
+
+## 配置说明
+
+配置文件位置: `~/.config/minenasai/config.json5`
+
+主要配置项:
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| `gateway.port` | Gateway 端口 | 8000 |
+| `webtui.port` | Web TUI 端口 | 8080 |
+| `agents.default_model` | 默认模型 | claude-sonnet-4-20250514 |
+| `router.mode` | 路由模式 | agent |
+
+## 许可证
+
+MIT License