MineNasAI/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 开发命令

### 安装与设置

```bash
# 安装依赖（包含开发工具）
pip install -e ".[dev]"

# 安装 pre-commit 钩子
pre-commit install

# 复制环境变量模板
cp .env.example .env
# 编辑 .env 文件，填入至少一个 LLM API Key
```

### 代码质量

```bash
# 格式化代码
ruff format src tests

# 检查代码规范
ruff check src tests

# 类型检查
mypy src
```

### 测试

```bash
# 运行所有测试
pytest

# 带覆盖率报告
pytest --cov=minenasai

# 运行单个测试文件
pytest tests/test_core.py -v

# 运行特定测试
pytest tests/test_core.py::test_config_load -v
```

### 运行服务

```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 是一个基于 NAS 的智能个人 AI 助理，采用智能路由架构，根据任务复杂度自动选择最优处理方式：

1. **简单任务** → 快速执行通道（Python 沙箱）
2. **中等复杂度** → Agent 执行（多 LLM API）
3. **复杂任务** → Web TUI（SSH + 深度编程）

### 模块结构

```
src/minenasai/
├── core/           # 核心基础设施
│   ├── config.py   # 配置管理（支持环境变量覆盖）
│   ├── logging.py  # 结构化日志（structlog）
│   ├── database.py # 数据库（aiosqlite）
│   ├── monitoring.py # 健康检查与监控指标
│   └── cache.py    # 缓存与限流
│
├── gateway/        # Gateway 服务（FastAPI）
│   ├── server.py   # 主服务器
│   ├── router.py   # 智能路由器（任务复杂度评估）
│   ├── protocol/   # WebSocket 消息协议
│   └── channels/   # 通讯渠道（企业微信/飞书）
│
├── llm/            # LLM 集成层
│   ├── manager.py  # LLM 管理器（统一接口）
│   ├── base.py     # 基础抽象
│   └── clients/    # 各提供商客户端
│       ├── anthropic.py    # Claude（需代理）
│       ├── deepseek.py     # DeepSeek（国内）
│       ├── zhipu.py        # 智谱（国内）
│       ├── minimax.py      # MiniMax（国内）
│       ├── moonshot.py     # Moonshot（国内）
│       ├── openai_compat.py # OpenAI 兼容接口
│       └── gemini.py       # Gemini（需代理）
│
├── agent/          # Agent 运行时
│   ├── runtime.py  # Agent 执行引擎
│   ├── permissions.py # 权限与危险等级管理
│   ├── tool_registry.py # 工具注册中心
│   └── tools/      # 内置工具
│
├── webtui/         # Web TUI 服务
│   ├── server.py   # TUI FastAPI 服务器
│   ├── auth.py     # 会话认证
│   └── ssh_manager.py # SSH 连接管理
│
└── scheduler/      # 定时任务
    └── cron.py     # Cron 调度器
```

### 配置系统

配置加载优先级：**环境变量 > 配置文件 > 默认值**

- 配置文件：`config/config.json5`（JSON5 格式，支持注释）
- 环境变量前缀：`MINENASAI_`（嵌套配置使用 `__` 分隔）
- 示例：
  - `MINENASAI_LLM__DEFAULT_PROVIDER=anthropic`
  - `MINENASAI_PROXY__HTTP=http://127.0.0.1:7890`

关键配置项：
- `router.mode`: 路由模式（`agent` 或 `heuristic`）
- `llm.default_provider`: 默认 LLM 提供商
- `proxy.enabled`: 是否启用代理（境外 API 需要）

### 智能路由器

位置：[gateway/router.py](src/minenasai/gateway/router.py)

根据以下因素评估任务复杂度：
- 文本长度
- 关键词匹配（简单/复杂/工具关键词）
- 代码块检测
- 多步骤指令检测

支持命令前缀覆盖：
- `/快速` 或 `/简单` → 强制快速执行
- `/深度`、`/复杂` 或 `/tui` → 强制 Web TUI

## 编码规范

### 通用规范

- **必须使用中文进行交流和注释**
- 文件编码：UTF-8
- Python 3.11+
- 使用类型注解（type hints）
- Docstring 使用中文简洁说明
- 函数添加必要注释

### Git 提交规范

使用中文提交信息：
- `feat: 添加xxx功能`
- `fix: 修复xxx问题`
- `docs: 更新文档`
- `refactor: 重构xxx`
- `test: 添加测试`

### 文档规范

**重要：避免过度文档化**

- 仅在明确需要时生成文档
- 文档必须使用中文命名
- 代码优先，文档次之
- 先实现 MVP，再迭代优化

文档命名规范：
- 设计文档：`设计-[主题].md`
- 技术方案：`方案-[主题].md`
- 问题记录：`问题-[描述].md`
- 进度跟踪：`进度.md`

## LLM 提供商

### 境内 API（无需代理）

- **DeepSeek**: `deepseek-chat`
- **智谱**: `glm-4-flash`
- **MiniMax**: `abab6.5s-chat`
- **Moonshot**: `moonshot-v1-8k`

### 境外 API（需要代理）

- **Anthropic Claude**: `claude-sonnet-4-20250514`
- **OpenAI**: `gpt-4o`
- **Google Gemini**: `gemini-2.0-flash`

### 代理配置

境外 API 需要配置代理（在 `.env` 中）：
```bash
MINENASAI_PROXY__ENABLED=true
MINENASAI_PROXY__HTTP=http://127.0.0.1:7890
MINENASAI_PROXY__HTTPS=http://127.0.0.1:7890
```

系统支持自动检测常见代理端口（7890, 7891, 1080, 1087, 10808）

## 测试

当前测试覆盖（131 tests）：
- `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）

## API 端点

| 端点 | 说明 |
|------|------|
| `/health` | 完整健康检查 |
| `/health/live` | 存活检查（K8s） |
| `/health/ready` | 就绪检查（K8s） |
| `/metrics` | 监控指标 |
| `/ws` | WebSocket 消息通道 |
| `/api/agents` | Agent 列表 |
| `/api/sessions` | 会话列表 |
| `/webhook/wework` | 企业微信回调 |
| `/webhook/feishu` | 飞书回调 |

## 常见任务

### 添加新的 LLM 客户端

1. 在 `src/minenasai/llm/clients/` 创建新文件
2. 继承 `BaseLLMClient`（[llm/base.py](src/minenasai/llm/base.py)）
3. 实现 `chat()` 方法
4. 在 `llm/manager.py` 注册客户端
5. 在 `core/config.py` 添加配置字段
6. 在 `.env.example` 添加环境变量模板

### 添加新的通讯渠道

1. 在 `src/minenasai/gateway/channels/` 创建新文件
2. 继承 `BaseChannel`（[channels/base.py](src/minenasai/gateway/channels/base.py)）
3. 实现 `send_message()` 和 `verify_signature()` 方法
4. 在 `config/config.json5` 添加渠道配置
5. 在 Gateway 服务器注册 webhook 路由

### 添加新的 Agent 工具

1. 在 `src/minenasai/agent/tools/` 创建或扩展工具文件
2. 工具函数需要包含类型注解和中文 docstring
3. 在 `agent/tool_registry.py` 注册工具
4. 在 `config/config.json5` 配置权限级别

## 注意事项

- 维护 `进度.md` 文件记录关键进展
- 重大技术决策需要记录理由
- 遇到问题优先查看现有代码和文档
- 不确定时先问，再动手
- 所有代码必须通过 ruff 和 mypy 检查后再提交