MineNasAI/CLAUDE.md

CLAUDE.md

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

开发命令

安装与设置

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

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

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

代码质量

# 格式化代码
ruff format src tests

# 检查代码规范
ruff check src tests

# 类型检查
mypy src

测试

# 运行所有测试
pytest

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

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

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

运行服务

# 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 是一个基于 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

根据以下因素评估任务复杂度：

• 文本长度
• 关键词匹配（简单/复杂/工具关键词）
• 代码块检测
• 多步骤指令检测

支持命令前缀覆盖：

• /快速 或 /简单 → 强制快速执行
• /深度、/复杂 或 /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 中）：

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）
3. 实现 chat() 方法
4. 在 llm/manager.py 注册客户端
5. 在 core/config.py 添加配置字段
6. 在 .env.example 添加环境变量模板

添加新的通讯渠道

1. 在 src/minenasai/gateway/channels/ 创建新文件
2. 继承 BaseChannel（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 检查后再提交