feat: 添加项目规则、环境配置示例及开发文档

2026-02-04 18:49:38 +08:00
commit df76882178
88 changed files with 13150 additions and 0 deletions
--- a/设计文档.md
+++ b/设计文档.md
@@ -0,0 +1,506 @@
+# 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*