Files
MineNasAI/项目分析.md

881 lines
22 KiB
Markdown
Raw Permalink Normal View History

# 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: 核心框架MVP14-21天
#### 1.1 配置管理系统2-3天
**优先级**: 🔥 最高
**依赖**: 无
**任务清单**:
- [ ] 定义配置SchemaPydantic模型
- [ ] 实现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与TUI12-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检查
- DocstringGoogle风格
- 测试覆盖率 > 80%
### Git工作流
- 主分支: `main`
- 开发分支: `develop`
- 功能分支: `feature/<name>`
- 提交格式: `<type>: <description>`
### 文档要求
- 每个模块有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费用按需
---
**文档结束**