congsh/MineNasAI

Fork 0

Files

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

2026-02-04 18:49:38 +08:00

22 KiB

Raw Blame 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 技术可行性评估

✅ 可行且成熟的技术

FastAPI + WebSocket: 成熟框架，Python生态完善
企业微信/飞书API: 官方SDK支持良好，文档完整
Redis + Celery: 成熟的任务队列解决方案
SQLite: 轻量级存储，适合单机部署
textual/rich: Python TUI开发成熟库

⚠️ 需要特别注意的技术

Claude Code CLI集成:
- 需要子进程管理和stdout/stderr解析
- 需要处理交互式输入/输出
- 需要考虑超时和资源限制
MCP Server动态加载:
- FastMCP框架较新，需要深入了解
- 进程管理和通信协议需要仔细设计
智能路由（任务复杂度评估）:
- 需要设计评估算法（token预估、工具需求分析）
- 可能需要机器学习模型辅助
多Agent协作:
- 需要设计消息总线和状态同步机制
- 并发控制和死锁预防

⚠️ 潜在风险点

权限控制复杂度: 需要精细的权限分级和审计
沙箱隔离: Python沙箱实现需要考虑安全性
代理服务稳定性: 网络代理可能影响服务可用性
性能瓶颈: WebSocket连接数、并发任务处理
RAG向量库规模: Qdrant性能随数据量增长

2.2 依赖关系分析

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            # 安全工具

四、开发步骤规划

阶段划分原则

先基础后高级: 从核心框架到高级特性
最小可用: 每阶段产出可运行版本
风险前置: 高风险模块优先验证
并行开发: 独立模块可并行

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配置加载器
支持环境变量覆盖
配置验证和错误提示
编写配置文档

验收标准:

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会话存储
数据库连接池

验收标准:

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客户端可连接
支持多客户端并发
消息正确路由
断线自动重连

测试脚本:

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

任务清单:

任务复杂度评估算法（启发式）
路由决策引擎
用户指令覆盖（/快速 /深度）
路由日志和统计

验收标准:

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）
安全验证和测试

验收标准:

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）
工具调用编排
上下文窗口管理
会话状态持久化
流式响应支持

验收标准:

agent = Agent(id="main", model="claude-sonnet-4")
response = await agent.chat("你好")
assert response.content != ""

2.2 工具管理框架（4-5天）

优先级: 🔥 高依赖: Agent运行时

任务清单:

工具注册表实现
工具Schema定义
权限检查机制
审计日志记录
内置工具实现（read/write/shell）

验收标准:

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版本管理

验收标准:

skills = SkillsLoader().load("~/.config/minenasai/skills")
assert "web-search" in skills

2.5 RAG知识库（5-7天）

优先级: 🔥 中依赖: 配置管理

任务清单:

Qdrant向量库初始化
Embedding模型集成（sentence-transformers）
文档切片和向量化
语义搜索API
增量更新机制

验收标准:

kb = KnowledgeBase()
kb.ingest("这是一段测试文本")
results = kb.search("测试", top_k=5)
assert len(results) > 0

2.6 文件索引（3-4天）

优先级: 🔥 低依赖: 知识库

任务清单:

文件系统扫描
Whoosh全文索引
增量索引更新
搜索API

验收标准:

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伪终端管理
实时输出流解析
交互式输入处理
超时和资源限制
会话保持和恢复
错误处理

验收标准:

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间通信协议
并发控制和同步
死锁检测和预防

验收标准:

main_agent = Agent(id="main")
sub = main_agent.spawn_subagent(task="分析日志")
result = await sub.wait()

4.2 定时任务调度（3-4天）

优先级: 🔥 低依赖: Celery、数据存储

任务清单:

Celery应用配置
Cron任务管理API
任务执行器
任务结果存储
Web界面管理（可选）

验收标准:

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天）

目标: 验证子进程调用和输出解析可行性

# 测试脚本
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天）

目标: 验证任务复杂度评估效果

# 简单规则
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协议通信

from mcp import MCPClient
client = MCPClient.connect("npx", ["-y", "@modelcontextprotocol/server-filesystem"])
tools = client.list_tools()

六、风险与缓解措施

风险清单

风险	影响	概率	缓解措施
Claude CLI集成失败	🔥高	中	PoC验证，备选方案：直接API调用
智能路由效果差	🔥中	高	先用简单规则，后续迭代优化
MCP Server不稳定	🔥中	中	进程监控和自动重启
代理服务不可用	🔥中	低	自动检测和Fallback
性能瓶颈	🔥中	中	压力测试，异步优化
权限控制漏洞	🔥高	低	安全审计，沙箱隔离

备选方案

Claude CLI不可用: 直接使用Anthropic API，失去IDE集成能力
Qdrant性能不足: 降级为简单向量搜索（numpy）
企业微信API限流: 增加消息队列缓冲

七、开发规范

代码规范

Python 3.11+
类型注解（mypy检查）
Docstring（Google风格）
测试覆盖率 > 80%

Git工作流

主分支: main
开发分支: develop
功能分支: feature/<name>
提交格式: <type>: <description>

文档要求

每个模块有README
关键函数有Docstring
API有OpenAPI文档
部署有详细步骤

八、总结与建议

项目可行性: ✅ 可行

理由:

技术栈成熟，社区支持良好
核心难点（Claude CLI集成）可通过PoC验证
模块划分清晰，可并行开发
风险可控，有备选方案

关键成功因素

✅ 先完成PoC验证关键技术
✅ 严格按Phase推进，避免跳跃
✅ 每个Phase产出可运行版本
✅ 重视测试和文档
✅ 预留20%时间处理意外问题

下一步行动

立即执行: Phase 0 项目初始化
本周完成: PoC 1-3 关键技术验证
两周目标: Phase 1 MVP可运行
一个月目标: Phase 2 完整Agent系统

资源需求

人力: 1-2名全职开发者
时间: 2-3个月完整实现
硬件: NAS服务器（已有）
成本: 主要是LLM API费用（按需）

文档结束

22 KiB Raw Blame History Unescape Escape

MineNASAI 项目分析报告

一、项目现状分析

1.1 当前状态

1.2 技术栈概述

二、可行性分析

2.1 技术可行性评估

✅ 可行且成熟的技术

⚠️ 需要特别注意的技术

⚠️ 潜在风险点

2.2 依赖关系分析

2.3 实施难度评估

三、模块分解

3.1 核心模块划分

模块1: Gateway服务（gateway/）

模块2: 通讯渠道（channels/）

模块3: Agent运行时（agent/）

模块4: 工具管理（tools/）

模块5: Claude Code CLI桥接（claude_bridge/）

模块6: 知识库（knowledge/）

模块7: TUI界面（tui/）

模块8: 数据存储（storage/）

模块9: 任务调度（scheduler/）

模块10: 配置管理（config/）

3.2 模块依赖关系

3.3 公共基础设施

四、开发步骤规划

阶段划分原则

Phase 0: 项目初始化（2-3天）

任务清单

可交付成果

Phase 1: 核心框架（MVP）（14-21天）

1.1 配置管理系统（2-3天）

1.2 日志和监控基础（2天）

1.3 数据存储层（3-4天）

1.4 Gateway WebSocket服务（5-7天）

1.5 通讯渠道接入（4-6天）

1.6 智能路由基础（3-5天）

1.7 Python沙箱执行（3-5天）

Phase 1 里程碑

Phase 2: Agent与工具系统（14-21天）

2.1 Agent运行时（5-7天）

2.2 工具管理框架（4-5天）

2.3 MCP Server集成（5-7天）

2.4 AgentSkills集成（3-4天）

2.5 RAG知识库（5-7天）

2.6 文件索引（3-4天）

Phase 2 里程碑

Phase 3: Claude CLI与TUI（12-17天）

3.1 Claude Code CLI桥接（7-10天）

3.2 TUI界面（5-7天）

Phase 3 里程碑

Phase 4: 高级特性（10-14天）

4.1 Sub-agent协作（7-10天）

4.2 定时任务调度（3-4天）

Phase 4 里程碑

Phase 5: 生产就绪（7-10天）

5.1 权限与审计（3-4天）

5.2 错误处理与监控（2-3天）

5.3 部署与文档（2-3天）

Phase 5 里程碑

五、关键技术验证（PoC）

优先验证项

PoC 1: Claude Code CLI集成（2-3天）

PoC 2: 智能路由算法（1-2天）

PoC 3: MCP Server加载（1-2天）

六、风险与缓解措施

风险清单

备选方案

七、开发规范

代码规范

Git工作流

文档要求

八、总结与建议

项目可行性: ✅ 可行

关键成功因素

下一步行动

资源需求

22 KiB

Raw Blame History