congsh/MineNasAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
427ea6ae8d988adf879db63be9fe314aad45f2ee
MineNasAI/设计文档.md

507 lines
19 KiB
Markdown
Raw Normal View History

feat: 添加项目规则、环境配置示例及开发文档
2026-02-04 18:49:38 +08:00
# MineNASAI 设计文档
**项目名称**: MineNASAI
**版本**: v1.0-design
**创建日期**: 2025-02-03
**目标**: 基于NAS的智能个人AI助理，支持企业微信/飞书通讯，集成Claude Code CLI编程能力
---
## 1. 项目概述
### 1.1 目标
构建一个**自我进化的个人全能AI助理**，具备以下核心能力：
- **多渠道通讯**: 企业微信、飞书（可扩展）
- **强权限操作**: 对NAS环境拥有足够权限
- **编程能力**: 唤起Claude Code CLI进行复杂编程
- **快速验证**: Python解释器直接验证简单任务
- **工具扩展**: 支持MCP Server、Skills插件
- **联网能力**: 搜索查询、API调用
- **自主运行**: 定时任务、主动触发
- **多Agent协作**: 复杂任务多Agent讨论
### 1.2 设计原则
- **智能分流**: 简单任务快速处理，复杂任务深度分析
- **用户可控**: 智能路由默认行为，用户可显式覆盖
- **安全优先**: 沙箱隔离、权限分级、审计日志
- **可扩展**: MCP/Skills插件化架构
---
## 2. 整体架构
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 通讯接入层 (Channels) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 企业微信Bot │ │ 飞书Bot │ │ Web UI(预留) │ │
│ │ (Webhook) │ │ (Webhook) │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────┬───────────────────────────────────────────┘
│
┌─────────────────────────────┴───────────────────────────────────────────┐
│ Gateway 服务 (FastAPI) │
│ - WebSocket协议 (类OpenClaw协议设计) │
│ - 消息队列/流控/重试 │
│ - 设备配对/权限验证 │
│ - 事件分发 (agent/chat/presence/cron) │
└─────────────────────────────┬───────────────────────────────────────────┘
│
┌─────────────────────────────┴───────────────────────────────────────────┐
│ 智能路由层 (SmartRouter) │
│ - 任务复杂度评估 (token预估/工具需求分析) │
│ - 单/多Agent决策 │
│ - 快速通道 vs 深度讨论 │
│ - 用户指令覆盖 (/快速 /深度 /确认) │
└─────────────────────────────┬───────────────────────────────────────────┘
│
┌─────────────────────────────┴───────────────────────────────────────────┐
│ 工具管理层 (ToolManager) │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ MCP │ │ Skills │ │ 系统命令 │ │Claude Code │ │
│ │ Server │ │ 插件化 │ │ 封装 │ │ CLI桥接 │ │
│ │ (动态加载) │ │(AgentSkills)│ │(权限分级) │ │ (编程任务) │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
│ ↓ 权限白名单 / 危险操作确认 / 执行日志 / 沙箱隔离 │
└─────────────────────────────┬───────────────────────────────────────────┘
│
┌────────────────────┼────────────────────┐
↓ ↓ ↓
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│快速执行通道 │ │深度讨论组 │ │定时任务器 │
│Python直验 │ │多Agent协作 │ │Cron触发 │
│沙箱执行 │ │Sub-agents │ │自主任务 │
└─────────────┘ └─────────────┘ └─────────────┘
│
┌─────────────────────────────┴───────────────────────────────────────────┐
│ 信息三层架构 │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────────────────────────┐ │
│ │记忆层 │ │ 知识库层 │ │ 文件索引 + Web搜索 │ │
│ │(对话上下) │ │(RAG向量) │ │ NAS文件 │ │ │
│ │Session │ │Qdrant │ │ │ │
│ └──────────┘ └──────────┘ └──────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────────┘
```
---
## 3. 技术选型
| 层级 | 技术选择 | 说明 |
|------|----------|------|
| **后端框架** | FastAPI (Python) | WebSocket支持、异步高性能、类型安全 |
| **Agent Runtime** | Anthropic SDK | 直接API调用，稳定可靠 |
| **消息队列** | Redis + Celery | 任务调度、定时任务、并发控制 |
| **通讯接入** | 企业微信API + 飞书API | Webhook回调，支持应用消息/机器人 |
| **HTTPS** | Caddy | 自动HTTPS，配合lucky转发 |
| **工具层** | 内置工具 + MCP(可选) | 简化实现，后期可扩展 |
| **Claude集成** | Anthropic API + Web TUI | 简单任务用API，复杂任务用Web终端 |
| **Web终端** | xterm.js + WebSocket | Web前端终端模拟器 |
| **SSH连接** | paramiko (Python) | SSH客户端库，连接localhost |
| **Python沙箱** | Docker / restricted Python | 隔离执行 |
| **向量数据库** | Qdrant (可选) | 轻量、高性能，Phase 2 |
| **文件索引** | 基础文件系统 (可选) | Phase 2扩展 |
| **存储** | SQLite + JSONL | 配置、状态、会话 |
| **日志** | structured JSON + logrotate | 结构化日志 |
---
## 4. 数据流设计
### 4.1 消息处理流程（企业微信/飞书）
```
企业微信/飞书消息 → Gateway WebSocket接收
↓
消息网关 (解析/去重/用户识别)
↓
智能路由 (复杂度评估)
↙ ↘ ↘
快速查询 中等任务 编程任务
↓ ↓ ↓
Python沙箱 → 单Agent → 通知用户
直接执行 执行 "请用TUI处理"
↓ ↓
└───────→ 结果聚合
↓
知识库更新 (RAG入库)
↓
回传通讯工具
```
### 4.2 Web TUI + SSH 编程流程（推荐方案）
```
用户收到消息提示
↓
"此任务需要在Web TUI中处理"
↓
用户点击链接 → 打开Web界面
↓
┌───────────────────────────────────┐
│ Web Terminal (xterm.js) │
│ ↓ │
│ WebSocket连接后端 │
│ ↓ │
│ SSH连接 localhost (NAS自身) │
│ ↓ │
│ $ claude "实现一个xxx功能" │
│ → Claude分析/编码/执行 │
│ → 实时输出显示在Web终端 │
│ → 用户直接在浏览器中交互 │
└───────────────────────────────────┘
↓
完成 → (可选)结果同步到知识库
```
**核心优势**:
- ✅ **无需进程间通信** - 避免subprocess的所有问题
- ✅ **完整CLI能力** - 用户直接与Claude CLI交互
- ✅ **实现简单** - 成熟的Web终端方案（xterm.js）
- ✅ **权限隔离** - SSH本身提供隔离机制
- ✅ **跨平台访问** - 浏览器即可使用
### 4.3 双界面模式
| 界面 | 用途 | 技术方案 | 示例 |
|------|------|----------|------|
| 通讯工具 | 日常交互/简单任务 | Anthropic API | "NAS状态?"、"搜索xxx"、"定时提醒" |
| Web TUI | 深度编程/复杂项目 | xterm.js + SSH + Claude CLI | "重构这个模块"、"实现新功能"、"调试问题" |
---
## 5. 核心组件
### 5.1 Gateway核心模块
```
src/gateway/
├── __init__.py
├── server.py # WebSocket服务器入口
├── protocol/ # 协议定义
│ ├── schema.py # TypeBox/JSON Schema
│ └── frames.py # 帧构造/解析
├── channels/ # 通讯渠道
│ ├── __init__.py
│ ├── base.py # 基类
│ ├── wework.py # 企业微信
│ └── feishu.py # 飞书
├── router.py # 智能路由
├── tool_registry.py # 内置工具注册
├── anthropic_client.py # Anthropic API客户端
├── session_manager.py # 会话管理
└── scheduler.py # 定时任务
```
### 5.2 Agent Runtime
```
src/agent/
├── __init__.py
├── runtime.py # Agent运行时
├── tools/ # 内置工具
│ ├── read.py
│ ├── exec.py
│ ├── python.py # Python沙箱
│ └── web_search.py
├── memory.py # 记忆管理
├── knowledge.py # RAG知识库
└── subagent.py # Sub-agent支持
```
### 5.3 Web TUI界面
```
src/webtui/
├── __init__.py
├── server.py # WebSocket服务器（终端通信）
├── static/ # 前端静态文件
│ ├── index.html # Web终端页面
│ ├── xterm.css # xterm.js样式
│ └── app.js # 前端逻辑
├── ssh_manager.py # SSH连接管理（paramiko）
└── auth.py # 用户认证
```
**实现细节**:
- **前端**: xterm.js创建Web终端
- **通信**: WebSocket双向传输终端I/O
- **后端**: paramiko连接SSH到localhost
- **认证**: 基于Token或Session的用户验证
### 5.4 文件结构
```
~/.config/minenasai/
├── config.json5 # 主配置文件
├── database.db # SQLite数据库
├── workspace/ # 主Agent工作目录
│ ├── skills/ # 自定义Skills
│ ├── AGENTS.md # Agent指令/记忆
│ ├── SOUL.md # 人格/边界
│ └── TOOLS.md # 工具使用规范
├── agents/ # 多Agent状态
│ └── <agentId>/
│ ├── sessions/ # JSONL对话历史
│ └── auth.json # 认证配置
├── skills/ # 共享Skills
├── knowledge/ # Qdrant数据目录
├── logs/ # 日志文件
│ ├── gateway.log
│ └── audit.jsonl
└── mcp-servers/ # MCP Server配置
└── config.json
```
---
## 6. 数据模型
### 6.1 SQLite Schema
```sql
-- Agents表
CREATE TABLE agents (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
workspace_path TEXT NOT NULL,
model TEXT DEFAULT 'anthropic/claude-sonnet-4-5',
sandbox_mode TEXT DEFAULT 'workspace',
created_at INTEGER,
updated_at INTEGER
);
-- Sessions表
CREATE TABLE sessions (
id TEXT PRIMARY KEY,
agent_id TEXT REFERENCES agents(id),
channel TEXT, -- 'wework', 'feishu', 'tui'
peer_id TEXT, -- 用户ID
session_key TEXT, -- agent:main:xxx
status TEXT DEFAULT 'active',
created_at INTEGER,
updated_at INTEGER,
metadata JSON -- 扩展字段
);
-- Messages表（轻量，详细在JSONL）
CREATE TABLE messages (
id TEXT PRIMARY KEY,
session_id TEXT REFERENCES sessions(id),
role TEXT NOT NULL, -- 'user', 'assistant', 'system'
content TEXT,
tool_calls JSON,
timestamp INTEGER,
tokens_used INTEGER
);
-- Cron任务表
CREATE TABLE cron_jobs (
id TEXT PRIMARY KEY,
agent_id TEXT REFERENCES agents(id),
name TEXT NOT NULL,
schedule TEXT NOT NULL, -- cron表达式
task TEXT NOT NULL,
enabled BOOLEAN DEFAULT 1,
last_run INTEGER,
next_run INTEGER
);
-- 审计日志表
CREATE TABLE audit_logs (
id TEXT PRIMARY KEY,
agent_id TEXT,
tool_name TEXT NOT NULL,
danger_level TEXT,
params JSON,
result TEXT,
duration_ms INTEGER,
timestamp INTEGER
);
```
---
## 7. 权限与安全控制
### 7.1 权限分级
```python
DANGER_LEVELS = {
"safe": [], # 只读操作：查询文件、读取状态
"low": ["read"], # 低风险：写入工作目录、Python验证
"medium": ["exec"], # 中风险：系统命令、Docker操作
"high": [], # 高风险：删除文件、系统配置
"critical": [] # 极高危：格式化磁盘、清空数据库
}
```
### 7.2 确认策略
| 等级 | 处理方式 |
|------|----------|
| safe/low | 自动执行 |
| medium | AI评估后决定 |
| high/critical | **强制用户确认** |
### 7.3 沙箱隔离
- Python快速验证：`restricted` Python或Docker容器
- MCP Server：独立进程运行，限资源/网络
- Claude Code CLI：指定工作目录，限制可访问路径
### 7.4 配置示例
```json5
{
agents: {
list: [
{
id: "main",
tools: {
allow: ["read", "python", "web_search", "claude_cli"],
deny: ["delete", "system_config"],
},
sandbox: {
mode: "workspace",
},
},
],
},
}
```
---
## 8. 代理服务支持
### 8.1 代理配置
```python
PROXY_CONFIG = {
"enabled": true,
"mode": "system",
"system": {
"http_proxy": "http://127.0.0.1:7890",
"https_proxy": "http://127.0.0.1:7890",
"no_proxy": "localhost,127.0.0.1,.local",
},
"api_specific": {
"anthropic": "http://127.0.0.1:7890",
"openai": "http://127.0.0.1:7890",
"github": "http://127.0.0.1:7890",
},
"auto_detect": true,
"fallback_ports": [7890, 7891, 1080, 1087, 10808],
}
```
### 8.2 代理支持场景
- LLM API调用
- MCP Server
- Web搜索
- ClawHub同步
- Git操作
---
## 9. 错误处理与容错
### 9.1 错误分类
```python
ERROR_HANDLING = {
"retryable": [
"network_timeout", "api_rate_limit",
"mcp_unavailable", "proxy_timeout",
],
"degrade": [
"vector_db_down", "web_search_fail",
"claude_cli_timeout", "proxy_unavailable",
],
"critical": [
"auth_failed", "sandbox_escape",
"disk_full", "proxy_auth_failed",
],
}
```
### 9.2 重试策略
- 指数退避：1s → 2s → 4s → 8s，最多3次
- Circuit Breaker：连续失败后暂停5分钟
### 9.3 优雅降级
- RAG离线 → 直接对话
- MCP挂了 → 其他MCP继续
- Claude CLI不可用 → 通知用户
---
## 10. 实现路线图
### Phase 1：核心框架（MVP）
- [ ] Gateway基础服务 + WebSocket协议
- [ ] 企业微信/飞书通讯接入
- [ ] 智能路由基础逻辑
- [ ] Python沙箱执行
- [ ] 基础配置管理
### Phase 2：工具与知识库
- [ ] MCP Server动态加载
- [ ] Skills系统（AgentSkills兼容）
- [ ] RAG向量库集成
- [ ] NAS文件索引
### Phase 3：Web TUI与Claude集成
- [ ] Anthropic API集成（日常任务）
- [ ] xterm.js Web终端界面
- [ ] SSH连接管理（paramiko）
- [ ] WebSocket终端通信
- [ ] 用户认证与会话
### Phase 4：高级特性
- [ ] 多Agent协作（Sub-agents）
- [ ] 定时任务调度器
- [ ] 主动任务触发
### Phase 5：生产就绪
- [ ] 完整权限控制
- [ ] 审计日志
- [ ] 错误处理与监控
- [ ] Docker部署
---
## 11. 技术栈总结
| 层级 | 技术选择 |
|------|----------|
| Gateway | FastAPI + WebSocket |
| 通讯 | 企业微信API + 飞书API |
| Agent | Anthropic SDK |
| Claude集成 | API（简单任务）+ Web TUI（复杂任务）|
| Web终端 | xterm.js + paramiko SSH |
| 工具 | 内置工具（可扩展MCP）|
| 存储 | SQLite + JSONL |
| 队列 | Redis + Celery |
| 代理 | system/http(s)_proxy |
---
## 附录：参考项目
- **OpenClaw**: Gateway架构、AgentSkills、多Agent设计
- **Claude Code**: CLI集成、工具调用模式
- **FastMCP**: MCP Server开发框架
---
*文档版本: v1.0*
*最后更新: 2025-02-03*
Reference in New Issue Copy Permalink