277 lines
7.4 KiB
Markdown
277 lines
7.4 KiB
Markdown
# 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 检查后再提交
|