# 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状态 │ └── / │ ├── 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*