# MineNASAI 项目分析报告 **生成日期**: 2025-02-04 **基于文档**: 2025-02-03-minenasai-design.md **项目状态**: 设计阶段(无代码实现) --- ## 一、项目现状分析 ### 1.1 当前状态 - ✅ 完整的设计文档已完成 - ❌ 无任何代码实现 - ❌ 无依赖配置文件 - ❌ 无项目结构 - ✅ 有 .claude 配置(命令和代理定义) ### 1.2 技术栈概述 | 组件 | 技术选择 | 用途 | |------|----------|------| | 后端框架 | FastAPI | WebSocket服务器、REST API | | 消息队列 | Redis + Celery | 任务调度、异步处理 | | 通讯渠道 | 企业微信API + 飞书API | 消息接收与发送 | | Agent运行时 | pi-mono风格 | Agent执行引擎 | | 工具层 | FastMCP + AgentSkills | 插件化工具系统 | | 编程能力 | Claude Code CLI | 复杂编程任务 | | 向量数据库 | Qdrant | RAG知识库 | | 全文搜索 | Whoosh/Meilisearch | 文件索引 | | 存储 | SQLite | 会话、配置、日志 | | TUI界面 | textual/rich | 终端用户界面 | --- ## 二、可行性分析 ### 2.1 技术可行性评估 #### ✅ 可行且成熟的技术 1. **FastAPI + WebSocket**: 成熟框架,Python生态完善 2. **企业微信/飞书API**: 官方SDK支持良好,文档完整 3. **Redis + Celery**: 成熟的任务队列解决方案 4. **SQLite**: 轻量级存储,适合单机部署 5. **textual/rich**: Python TUI开发成熟库 #### ⚠️ 需要特别注意的技术 1. **Claude Code CLI集成**: - 需要子进程管理和stdout/stderr解析 - 需要处理交互式输入/输出 - 需要考虑超时和资源限制 2. **MCP Server动态加载**: - FastMCP框架较新,需要深入了解 - 进程管理和通信协议需要仔细设计 3. **智能路由(任务复杂度评估)**: - 需要设计评估算法(token预估、工具需求分析) - 可能需要机器学习模型辅助 4. **多Agent协作**: - 需要设计消息总线和状态同步机制 - 并发控制和死锁预防 #### ⚠️ 潜在风险点 1. **权限控制复杂度**: 需要精细的权限分级和审计 2. **沙箱隔离**: Python沙箱实现需要考虑安全性 3. **代理服务稳定性**: 网络代理可能影响服务可用性 4. **性能瓶颈**: WebSocket连接数、并发任务处理 5. **RAG向量库规模**: Qdrant性能随数据量增长 ### 2.2 依赖关系分析 ```mermaid graph TD A[FastAPI Gateway] --> B[通讯渠道层] A --> C[智能路由] C --> D[Agent Runtime] D --> E[工具管理器] E --> F1[MCP Server] E --> F2[AgentSkills] E --> F3[Claude CLI] E --> F4[Python沙箱] D --> G[知识库] G --> H1[Qdrant] G --> H2[文件索引] A --> I[会话管理] I --> J[SQLite] A --> K[定时任务] K --> L[Redis+Celery] ``` ### 2.3 实施难度评估 | Phase | 模块 | 难度 | 时间估算 | 风险等级 | |-------|------|------|----------|----------| | Phase 1 | Gateway基础服务 | 中 | 5-7天 | 低 | | Phase 1 | 企业微信/飞书接入 | 中 | 3-5天 | 中 | | Phase 1 | 智能路由基础 | 高 | 5-7天 | 高 | | Phase 1 | Python沙箱 | 高 | 3-5天 | 高 | | Phase 2 | MCP Server加载 | 高 | 5-7天 | 中 | | Phase 2 | Skills系统 | 中 | 3-5天 | 低 | | Phase 2 | RAG集成 | 中 | 5-7天 | 中 | | Phase 3 | Claude CLI桥接 | 高 | 7-10天 | 高 | | Phase 3 | TUI界面 | 中 | 5-7天 | 低 | | Phase 4 | 多Agent协作 | 高 | 10-14天 | 高 | | Phase 5 | 权限与审计 | 中 | 5-7天 | 中 | **总计**: 约 56-84 天开发时间(不含测试和调试) --- ## 三、模块分解 ### 3.1 核心模块划分 #### 模块1: Gateway服务(gateway/) **职责**: WebSocket服务器、消息路由、协议处理 ``` gateway/ ├── server.py # FastAPI应用入口 ├── websocket_handler.py # WebSocket连接管理 ├── protocol/ │ ├── schema.py # 消息Schema定义 │ └── frames.py # 帧构造/解析 ├── router.py # 智能路由器 └── middleware.py # 认证、限流中间件 ``` **依赖**: FastAPI, websockets, pydantic **关键功能**: - WebSocket连接管理(心跳、重连) - 消息验证和反序列化 - 智能路由决策(任务复杂度评估) - 流量控制和限流 #### 模块2: 通讯渠道(channels/) **职责**: 企业微信、飞书等通讯平台接入 ``` channels/ ├── base.py # Channel基类 ├── wework/ │ ├── client.py # 企业微信API客户端 │ ├── webhook.py # Webhook处理 │ └── message.py # 消息适配器 └── feishu/ ├── client.py # 飞书API客户端 ├── webhook.py # Webhook处理 └── message.py # 消息适配器 ``` **依赖**: httpx, pycryptodome(消息加解密) **关键功能**: - Webhook接收和验证 - 消息加解密 - API调用(发送消息、上传文件) - 事件订阅管理 #### 模块3: Agent运行时(agent/) **职责**: Agent执行引擎、工具调用、记忆管理 ``` agent/ ├── runtime.py # Agent主运行循环 ├── executor.py # 工具执行器 ├── memory.py # 短期记忆(Session) ├── context.py # 上下文管理 └── subagent.py # Sub-agent支持 ``` **依赖**: anthropic, aiohttp **关键功能**: - LLM API调用(Claude) - 工具调用编排 - 上下文窗口管理 - 多轮对话状态维护 #### 模块4: 工具管理(tools/) **职责**: 工具注册、权限控制、执行隔离 ``` tools/ ├── registry.py # 工具注册表 ├── executor.py # 工具执行框架 ├── builtin/ # 内置工具 │ ├── read.py │ ├── write.py │ ├── shell.py │ └── python.py ├── mcp_loader.py # MCP Server加载器 ├── skills_loader.py # AgentSkills加载器 ├── sandbox.py # 沙箱隔离 └── permission.py # 权限检查 ``` **依赖**: docker-py, mcp, subprocess **关键功能**: - 动态工具加载 - 权限白名单检查 - 沙箱执行(Docker/restricted) - 审计日志记录 #### 模块5: Claude Code CLI桥接(claude_bridge/) **职责**: Claude Code CLI子进程管理 ``` claude_bridge/ ├── cli.py # CLI调用封装 ├── process.py # 子进程管理 ├── parser.py # 输出解析 └── session.py # CLI会话管理 ``` **依赖**: subprocess, pty **关键功能**: - 子进程启动和监控 - 实时输出流解析 - 交互式输入处理 - 超时和资源限制 #### 模块6: 知识库(knowledge/) **职责**: RAG向量存储、文件索引、语义搜索 ``` knowledge/ ├── vector_store.py # Qdrant向量库 ├── embedder.py # Embedding模型 ├── file_index.py # 文件索引器 ├── searcher.py # 语义搜索 └── ingestion.py # 数据摄取管道 ``` **依赖**: qdrant-client, sentence-transformers, whoosh **关键功能**: - 文档向量化 - 语义搜索 - 全文索引 - 增量更新 #### 模块7: TUI界面(tui/) **职责**: 终端用户界面 ``` tui/ ├── app.py # Textual应用主入口 ├── screens/ │ ├── chat.py # 聊天界面 │ ├── sessions.py # 会话列表 │ ├── logs.py # 日志查看 │ └── settings.py # 设置界面 └── widgets/ ├── message.py # 消息组件 └── input.py # 输入框 ``` **依赖**: textual, rich **关键功能**: - 实时聊天界面 - Claude CLI输出展示 - 日志查看 - 配置管理 #### 模块8: 数据存储(storage/) **职责**: 数据库、会话持久化 ``` storage/ ├── database.py # SQLite ORM ├── models.py # 数据模型 ├── session_store.py # JSONL会话存储 └── migrations/ # 数据库迁移 ``` **依赖**: sqlalchemy, alembic **关键功能**: - SQLite数据库管理 - JSONL日志写入 - 数据迁移 #### 模块9: 任务调度(scheduler/) **职责**: 定时任务、异步任务队列 ``` scheduler/ ├── celery_app.py # Celery应用 ├── tasks.py # 任务定义 ├── cron.py # Cron任务管理 └── worker.py # Worker进程 ``` **依赖**: celery, redis, croniter **关键功能**: - Cron表达式解析 - 任务调度 - 分布式任务执行 - 任务结果存储 #### 模块10: 配置管理(config/) **职责**: 配置加载、环境管理 ``` config/ ├── settings.py # 配置Schema ├── loader.py # 配置加载器 └── validator.py # 配置验证 ``` **依赖**: pydantic, json5 **关键功能**: - JSON5配置解析 - 环境变量覆盖 - 配置验证 - 热重载 ### 3.2 模块依赖关系 ``` 配置管理 ← 所有模块 ↓ Gateway服务 → 通讯渠道 ↓ 智能路由 → Agent运行时 ↓ 工具管理 → {MCP, Skills, Claude CLI, 沙箱} ↓ 知识库 ← Agent运行时 ↓ 数据存储 ← {Gateway, Agent, 任务调度} ↓ TUI界面 → Gateway服务 ``` ### 3.3 公共基础设施 ``` core/ ├── logging.py # 结构化日志 ├── errors.py # 异常定义 ├── utils.py # 通用工具函数 ├── proxy.py # 代理服务管理 └── security.py # 安全工具 ``` --- ## 四、开发步骤规划 ### 阶段划分原则 1. **先基础后高级**: 从核心框架到高级特性 2. **最小可用**: 每阶段产出可运行版本 3. **风险前置**: 高风险模块优先验证 4. **并行开发**: 独立模块可并行 ### Phase 0: 项目初始化(2-3天) #### 任务清单 - [ ] 创建项目目录结构 - [ ] 配置开发环境(pyproject.toml) - [ ] 设置依赖管理(Poetry/pip-tools) - [ ] 配置代码质量工具(ruff, mypy, pre-commit) - [ ] 编写 README.md - [ ] 初始化 Git 仓库 - [ ] 配置 Docker 开发环境 #### 可交付成果 - ✅ 完整的项目骨架 - ✅ 开发环境可一键启动 - ✅ CI/CD基础配置 --- ### Phase 1: 核心框架(MVP)(14-21天) #### 1.1 配置管理系统(2-3天) **优先级**: 🔥 最高 **依赖**: 无 **任务清单**: - [ ] 定义配置Schema(Pydantic模型) - [ ] 实现JSON5配置加载器 - [ ] 支持环境变量覆盖 - [ ] 配置验证和错误提示 - [ ] 编写配置文档 **验收标准**: ```python from config import load_config config = load_config("~/.config/minenasai/config.json5") assert config.gateway.host == "0.0.0.0" ``` #### 1.2 日志和监控基础(2天) **优先级**: 🔥 高 **依赖**: 配置管理 **任务清单**: - [ ] 结构化日志(JSON格式) - [ ] 日志级别和轮转 - [ ] 审计日志独立输出 - [ ] 性能指标收集(基础) **验收标准**: - 日志可读性良好 - 支持按时间/级别过滤 - 审计日志包含完整上下文 #### 1.3 数据存储层(3-4天) **优先级**: 🔥 高 **依赖**: 配置管理 **任务清单**: - [ ] 设计SQLite Schema - [ ] SQLAlchemy ORM模型 - [ ] 数据库迁移脚本(Alembic) - [ ] JSONL会话存储 - [ ] 数据库连接池 **验收标准**: ```python from storage import Database db = Database() agent = db.create_agent(name="main", model="claude-sonnet-4") session = db.create_session(agent_id=agent.id, channel="wework") ``` #### 1.4 Gateway WebSocket服务(5-7天) **优先级**: 🔥 最高 **依赖**: 配置管理、日志 **任务清单**: - [ ] FastAPI应用骨架 - [ ] WebSocket连接管理 - [ ] 消息协议定义(schema.py) - [ ] 帧序列化/反序列化 - [ ] 心跳和重连机制 - [ ] 基础路由(agent/chat/presence) - [ ] 单元测试 **验收标准**: - WebSocket客户端可连接 - 支持多客户端并发 - 消息正确路由 - 断线自动重连 **测试脚本**: ```python async with websockets.connect("ws://localhost:8000/ws") as ws: await ws.send(json.dumps({"type": "agent/chat", "content": "hello"})) response = await ws.recv() assert json.loads(response)["status"] == "ok" ``` #### 1.5 通讯渠道接入(4-6天) **优先级**: 🔥 高 **依赖**: Gateway **任务清单**: - [ ] 企业微信Webhook接收 - [ ] 企业微信消息加解密 - [ ] 飞书Webhook接收 - [ ] 飞书消息加解密 - [ ] 消息适配器(统一格式) - [ ] 消息发送API封装 - [ ] 错误重试机制 **验收标准**: - 企业微信消息可接收和回复 - 飞书消息可接收和回复 - 支持文本、图片、文件消息 #### 1.6 智能路由基础(3-5天) **优先级**: 🔥 中 **依赖**: Gateway **任务清单**: - [ ] 任务复杂度评估算法(启发式) - [ ] 路由决策引擎 - [ ] 用户指令覆盖(/快速 /深度) - [ ] 路由日志和统计 **验收标准**: ```python router = SmartRouter() decision = router.evaluate("NAS状态?") assert decision.mode == "fast" decision = router.evaluate("实现一个Web服务") assert decision.mode == "deep" ``` #### 1.7 Python沙箱执行(3-5天) **优先级**: 🔥 高(安全关键) **依赖**: 工具管理 **任务清单**: - [ ] Docker沙箱容器镜像 - [ ] Python代码执行API - [ ] 超时和资源限制 - [ ] 输出捕获(stdout/stderr) - [ ] 安全验证和测试 **验收标准**: ```python sandbox = PythonSandbox() result = sandbox.execute("print(1+1)", timeout=5) assert result.stdout == "2\n" assert result.exit_code == 0 ``` #### Phase 1 里程碑 - ✅ Gateway可接收企业微信/飞书消息 - ✅ 消息可通过WebSocket转发 - ✅ Python代码可在沙箱执行 - ✅ 基本配置和日志系统运行 --- ### Phase 2: Agent与工具系统(14-21天) #### 2.1 Agent运行时(5-7天) **优先级**: 🔥 最高 **依赖**: Gateway、数据存储 **任务清单**: - [ ] Agent主循环实现 - [ ] Claude API集成(anthropic SDK) - [ ] 工具调用编排 - [ ] 上下文窗口管理 - [ ] 会话状态持久化 - [ ] 流式响应支持 **验收标准**: ```python agent = Agent(id="main", model="claude-sonnet-4") response = await agent.chat("你好") assert response.content != "" ``` #### 2.2 工具管理框架(4-5天) **优先级**: 🔥 高 **依赖**: Agent运行时 **任务清单**: - [ ] 工具注册表实现 - [ ] 工具Schema定义 - [ ] 权限检查机制 - [ ] 审计日志记录 - [ ] 内置工具实现(read/write/shell) **验收标准**: ```python registry = ToolRegistry() registry.register(ReadFileTool()) tool = registry.get("read_file") result = await tool.execute({"path": "/etc/hosts"}) ``` #### 2.3 MCP Server集成(5-7天) **优先级**: 🔥 中 **依赖**: 工具管理 **任务清单**: - [ ] MCP Server发现和加载 - [ ] MCP协议实现(stdio/sse) - [ ] 工具动态注册 - [ ] 进程生命周期管理 - [ ] 错误处理和重启 **验收标准**: - 可加载官方MCP Server示例 - MCP工具可被Agent调用 - MCP Server崩溃可自动重启 #### 2.4 AgentSkills集成(3-4天) **优先级**: 🔥 中 **依赖**: 工具管理 **任务清单**: - [ ] Skill目录扫描 - [ ] Skill.md解析 - [ ] Skill指令注入 - [ ] Skill版本管理 **验收标准**: ```python skills = SkillsLoader().load("~/.config/minenasai/skills") assert "web-search" in skills ``` #### 2.5 RAG知识库(5-7天) **优先级**: 🔥 中 **依赖**: 配置管理 **任务清单**: - [ ] Qdrant向量库初始化 - [ ] Embedding模型集成(sentence-transformers) - [ ] 文档切片和向量化 - [ ] 语义搜索API - [ ] 增量更新机制 **验收标准**: ```python kb = KnowledgeBase() kb.ingest("这是一段测试文本") results = kb.search("测试", top_k=5) assert len(results) > 0 ``` #### 2.6 文件索引(3-4天) **优先级**: 🔥 低 **依赖**: 知识库 **任务清单**: - [ ] 文件系统扫描 - [ ] Whoosh全文索引 - [ ] 增量索引更新 - [ ] 搜索API **验收标准**: ```python indexer = FileIndexer("/mnt/nas") indexer.index() results = indexer.search("*.py") ``` #### Phase 2 里程碑 - ✅ Agent可调用内置工具 - ✅ MCP Server可动态加载 - ✅ RAG知识库可搜索 - ✅ 完整的MVP可运行 --- ### Phase 3: Claude CLI与TUI(12-17天) #### 3.1 Claude Code CLI桥接(7-10天) **优先级**: 🔥 高(核心能力) **依赖**: Agent运行时 **任务清单**: - [ ] Claude CLI子进程启动 - [ ] PTY伪终端管理 - [ ] 实时输出流解析 - [ ] 交互式输入处理 - [ ] 超时和资源限制 - [ ] 会话保持和恢复 - [ ] 错误处理 **验收标准**: ```python cli = ClaudeCLI() session = cli.start_session(workspace="/tmp/test") response = await cli.send("实现一个计算器") assert "def calculator" in response.code_changes ``` **关键技术点**: - 使用 `pty.openpty()` 创建伪终端 - 使用 `asyncio.create_subprocess_exec` 启动子进程 - 解析ANSI转义序列 - 处理Claude CLI的交互式提示 #### 3.2 TUI界面(5-7天) **优先级**: 🔥 中 **依赖**: Gateway、Claude CLI **任务清单**: - [ ] Textual应用骨架 - [ ] 聊天界面(消息列表+输入框) - [ ] Claude CLI输出展示 - [ ] 会话列表和切换 - [ ] 日志查看器 - [ ] 设置界面 **验收标准**: - TUI可启动并连接Gateway - 可实时查看Agent对话 - Claude CLI输出实时展示 - 支持键盘快捷键 #### Phase 3 里程碑 - ✅ Claude CLI可通过TUI调用 - ✅ 编程任务可在TUI完成 - ✅ 双界面模式(通讯工具+TUI)运行 --- ### Phase 4: 高级特性(10-14天) #### 4.1 Sub-agent协作(7-10天) **优先级**: 🔥 中 **依赖**: Agent运行时 **任务清单**: - [ ] Sub-agent生命周期管理 - [ ] 消息总线实现 - [ ] Agent间通信协议 - [ ] 并发控制和同步 - [ ] 死锁检测和预防 **验收标准**: ```python main_agent = Agent(id="main") sub = main_agent.spawn_subagent(task="分析日志") result = await sub.wait() ``` #### 4.2 定时任务调度(3-4天) **优先级**: 🔥 低 **依赖**: Celery、数据存储 **任务清单**: - [ ] Celery应用配置 - [ ] Cron任务管理API - [ ] 任务执行器 - [ ] 任务结果存储 - [ ] Web界面管理(可选) **验收标准**: ```python scheduler = CronScheduler() scheduler.add_job( name="morning_report", schedule="0 9 * * *", task="生成昨日总结" ) ``` #### Phase 4 里程碑 - ✅ 多Agent协作运行 - ✅ 定时任务自动执行 --- ### Phase 5: 生产就绪(7-10天) #### 5.1 权限与审计(3-4天) **优先级**: 🔥 高(安全) **依赖**: 工具管理 **任务清单**: - [ ] 权限白名单配置 - [ ] 危险操作确认流程 - [ ] 完整审计日志 - [ ] 敏感信息脱敏 - [ ] 权限测试用例 #### 5.2 错误处理与监控(2-3天) **优先级**: 🔥 中 **依赖**: 所有模块 **任务清单**: - [ ] 全局异常处理 - [ ] 重试策略实现 - [ ] Circuit Breaker - [ ] 健康检查接口 - [ ] Prometheus指标导出 #### 5.3 部署与文档(2-3天) **优先级**: 🔥 中 **依赖**: 所有模块 **任务清单**: - [ ] Docker Compose配置 - [ ] 部署文档 - [ ] 配置示例 - [ ] 故障排查手册 - [ ] API文档 #### Phase 5 里程碑 - ✅ 系统可生产部署 - ✅ 完整的监控和日志 - ✅ 用户文档完善 --- ## 五、关键技术验证(PoC) ### 优先验证项 以下技术点建议在正式开发前进行PoC验证: #### PoC 1: Claude Code CLI集成(2-3天) **目标**: 验证子进程调用和输出解析可行性 ```python # 测试脚本 import subprocess import pty import os master, slave = pty.openpty() proc = subprocess.Popen( ["claude", "实现一个计算器"], stdin=slave, stdout=slave, stderr=slave ) os.close(slave) while True: output = os.read(master, 1024) if not output: break print(output.decode()) ``` #### PoC 2: 智能路由算法(1-2天) **目标**: 验证任务复杂度评估效果 ```python # 简单规则 def evaluate_complexity(message): if any(kw in message for kw in ["实现", "开发", "编写"]): return "high" if any(kw in message for kw in ["查询", "搜索", "状态"]): return "low" return "medium" ``` #### PoC 3: MCP Server加载(1-2天) **目标**: 验证MCP协议通信 ```python from mcp import MCPClient client = MCPClient.connect("npx", ["-y", "@modelcontextprotocol/server-filesystem"]) tools = client.list_tools() ``` --- ## 六、风险与缓解措施 ### 风险清单 | 风险 | 影响 | 概率 | 缓解措施 | |------|------|------|----------| | Claude CLI集成失败 | 🔥高 | 中 | PoC验证,备选方案:直接API调用 | | 智能路由效果差 | 🔥中 | 高 | 先用简单规则,后续迭代优化 | | MCP Server不稳定 | 🔥中 | 中 | 进程监控和自动重启 | | 代理服务不可用 | 🔥中 | 低 | 自动检测和Fallback | | 性能瓶颈 | 🔥中 | 中 | 压力测试,异步优化 | | 权限控制漏洞 | 🔥高 | 低 | 安全审计,沙箱隔离 | ### 备选方案 1. **Claude CLI不可用**: 直接使用Anthropic API,失去IDE集成能力 2. **Qdrant性能不足**: 降级为简单向量搜索(numpy) 3. **企业微信API限流**: 增加消息队列缓冲 --- ## 七、开发规范 ### 代码规范 - Python 3.11+ - 类型注解(mypy检查) - Docstring(Google风格) - 测试覆盖率 > 80% ### Git工作流 - 主分支: `main` - 开发分支: `develop` - 功能分支: `feature/` - 提交格式: `: ` ### 文档要求 - 每个模块有README - 关键函数有Docstring - API有OpenAPI文档 - 部署有详细步骤 --- ## 八、总结与建议 ### 项目可行性: ✅ 可行 **理由**: 1. 技术栈成熟,社区支持良好 2. 核心难点(Claude CLI集成)可通过PoC验证 3. 模块划分清晰,可并行开发 4. 风险可控,有备选方案 ### 关键成功因素 1. ✅ 先完成PoC验证关键技术 2. ✅ 严格按Phase推进,避免跳跃 3. ✅ 每个Phase产出可运行版本 4. ✅ 重视测试和文档 5. ✅ 预留20%时间处理意外问题 ### 下一步行动 1. **立即执行**: Phase 0 项目初始化 2. **本周完成**: PoC 1-3 关键技术验证 3. **两周目标**: Phase 1 MVP可运行 4. **一个月目标**: Phase 2 完整Agent系统 ### 资源需求 - **人力**: 1-2名全职开发者 - **时间**: 2-3个月完整实现 - **硬件**: NAS服务器(已有) - **成本**: 主要是LLM API费用(按需) --- **文档结束**