507 lines
19 KiB
Markdown
507 lines
19 KiB
Markdown
# 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*
|