19 KiB
19 KiB
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
-- 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 权限分级
DANGER_LEVELS = {
"safe": [], # 只读操作：查询文件、读取状态
"low": ["read"], # 低风险：写入工作目录、Python验证
"medium": ["exec"], # 中风险：系统命令、Docker操作
"high": [], # 高风险：删除文件、系统配置
"critical": [] # 极高危：格式化磁盘、清空数据库
}
7.2 确认策略
| 等级 | 处理方式 |
|---|---|
| safe/low | 自动执行 |
| medium | AI评估后决定 |
| high/critical | 强制用户确认 |
7.3 沙箱隔离
- Python快速验证：
restrictedPython或Docker容器 - MCP Server：独立进程运行，限资源/网络
- Claude Code CLI：指定工作目录，限制可访问路径
7.4 配置示例
{
agents: {
list: [
{
id: "main",
tools: {
allow: ["read", "python", "web_search", "claude_cli"],
deny: ["delete", "system_config"],
},
sandbox: {
mode: "workspace",
},
},
],
},
}
8. 代理服务支持
8.1 代理配置
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 错误分类
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