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

进度.md

@@ -0,0 +1,381 @@
+# MineNASAI 项目进度跟踪
+
+**更新日期**: 2026-02-04
+**当前阶段**: Phase 3 完成，准备 Phase 4 开发
+**整体进度**: 80% (4/5 Phase 完成)
+**技术方案**: Web TUI集成（方案C）+ 多 LLM 支持
+
+---
+
+## 进度概览
+
+| Phase | 名称 | 状态 | 完成度 | 预计时间 | 实际时间 |
+|-------|------|------|---------|----------|----------|
+| Phase 0 | 项目初始化 | ✅ 已完成 | 7/7 | 2-3天 | 1天 |
+| Phase 1 | 核心框架(MVP) | ✅ 已完成 | 7/7 | 14-21天 | 1天 |
+| Phase 2 | Agent与工具系统 | ✅ 已完成 | 6/6 | 14-21天 | 1天 |
+| Phase 3 | Web TUI与Claude集成 | ✅ 已完成 | 5/5 | 7-10天 | 1天 |
+| Phase 4 | 高级特性 | ⏸️ 未开始 | 0/2 | 10-14天 | - |
+| Phase 5 | 生产就绪 | ⏸️ 未开始 | 0/3 | 7-10天 | - |
+
+**图例**: ⏸️ 未开始 | 🔄 进行中 | ✅ 已完成 | ⚠️ 阻塞
+
+---
+
+## Phase 0: 项目初始化 (100%) ✅
+
+### 0.1 创建项目目录结构
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 验收标准:
+  - [x] 所有目录已创建
+  - [x] 每个Python包有 `__init__.py`
+  - [x] 目录结构与设计文档一致
+
+---
+
+### 0.2 配置Python项目管理
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 验收标准:
+  - [x] pyproject.toml 配置完成
+  - [x] 虚拟环境已创建 (.venv)
+  - [x] 依赖包已安装
+  - [x] Python 3.13 验证通过
+- 备注: 使用 hatchling 作为构建后端
+
+---
+
+### 0.3 配置代码质量工具
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 验收标准:
+  - [x] pre-commit 配置完成
+  - [x] Ruff 配置完成
+  - [x] Mypy 配置完成
+
+---
+
+### 0.4 创建配置文件模板
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 验收标准:
+  - [x] Settings 可以成功加载
+  - [x] 环境变量可以覆盖配置
+  - [x] 配置验证正常工作
+- 备注: config/config.json5 + .env.example
+
+---
+
+### 0.5 配置日志系统
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 验收标准:
+  - [x] structlog 日志系统
+  - [x] JSON 格式支持
+  - [x] 审计日志独立存储 (AuditLogger)
+
+---
+
+### 0.6 创建README和开发文档
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 验收标准:
+  - [x] README.md 清晰易懂
+  - [x] 安装步骤可执行
+  - [x] 项目结构说明完整
+
+---
+
+### 0.7 配置Git仓库
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 验收标准:
+  - [x] Git 仓库已初始化
+  - [x] .gitignore 配置完整
+  - [ ] 首次提交（待用户确认）
+
+---
+
+## Phase 1: 核心框架(MVP) (100%) ✅
+
+### 1.1 数据存储层 ✅
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 子任务进度: 3/3
+  - [x] 1.1.1 设计数据库Schema (agents, sessions, messages, cron_jobs, audit_logs)
+  - [x] 1.1.2 实现数据库管理器 (core/database.py - aiosqlite)
+  - [x] 1.1.3 JSONL会话存储 (core/session_store.py)
+
+---
+
+### 1.2 Gateway WebSocket服务 ✅
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 子任务进度: 4/4
+  - [x] 1.2.1 定义消息协议 (gateway/protocol/schema.py)
+  - [x] 1.2.2 实现WebSocket处理器 (gateway/server.py)
+  - [x] 1.2.3 创建FastAPI应用
+  - [x] 1.2.4 协议测试 (13个测试通过)
+
+---
+
+### 1.3 智能路由(Router) ✅
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 子任务进度: 1/1
+  - [x] 1.3.1 实现启发式路由 (gateway/router.py)
+- 备注: 支持命令覆盖 (/快速, /深度)，关键词检测，代码/多步骤检测
+
+---
+
+### 1.4 Python沙箱执行 ✅
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 子任务进度: 2/2
+  - [x] 1.4.1 基础Python eval工具 (agent/tools/basic.py)
+  - [x] 1.4.2 安全白名单机制 (SAFE_BUILTINS + 危险关键词过滤)
+- 备注: Docker沙箱延后到 Phase 4
+
+---
+
+### 1.5 通讯渠道基础框架 ✅
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 子任务进度: 3/3
+  - [x] 1.5.1 渠道基类 (gateway/channels/base.py)
+  - [x] 1.5.2 企业微信渠道 (gateway/channels/wework.py)
+  - [x] 1.5.3 飞书渠道 (gateway/channels/feishu.py)
+- 备注: 基础框架完成，实际接入需配置 API Key
+
+---
+
+## Phase 2: Agent与工具系统 (100%) ✅
+
+### 2.1 多 LLM API 架构 ✅
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 支持的提供商:
+  - [x] Anthropic (Claude) - 境外，需代理
+  - [x] OpenAI (GPT) - 境外，需代理
+  - [x] Google Gemini - 境外，需代理
+  - [x] DeepSeek - 国内
+  - [x] 智谱 GLM - 国内
+  - [x] MiniMax - 国内
+  - [x] Moonshot (Kimi) - 国内
+
+### 2.2 LLM 管理器 ✅
+- 状态: ✅ 已完成
+- 功能:
+  - [x] 统一调用接口
+  - [x] 代理自动配置（境外服务）
+  - [x] 故障自动转移
+  - [x] 流式响应支持
+  - [x] 工具调用支持
+
+### 2.3 Agent 运行时集成 ✅
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 子任务:
+  - [x] 基础 Agent 运行时
+  - [x] 与 LLM Manager 集成
+  - [x] 支持动态切换提供商
+
+---
+
+## Phase 3: Web TUI 集成 (100%) ✅
+
+### 3.1 Web 终端前端 ✅
+- 状态: ✅ 已完成
+- 实际完成: 2026-02-04
+- 组件:
+  - [x] xterm.js 终端集成
+  - [x] 响应式 UI 设计
+  - [x] 主题切换支持
+  - [x] 全屏模式
+
+### 3.2 WebSocket 终端服务器 ✅
+- 状态: ✅ 已完成
+- 功能:
+  - [x] 终端 I/O 双向传输
+  - [x] 连接管理
+  - [x] 终端大小调整
+
+### 3.3 SSH 连接管理 ✅
+- 状态: ✅ 已完成
+- 功能:
+  - [x] paramiko SSH 客户端
+  - [x] 密钥/密码认证
+  - [x] 会话池管理
+  - [x] 空闲会话清理
+
+### 3.4 用户认证 ✅
+- 状态: ✅ 已完成
+- 功能:
+  - [x] Token 生成与验证
+  - [x] 令牌刷新
+  - [x] 会话管理
+  - [x] 过期清理
+
+### 3.5 Web TUI 服务器 ✅
+- 状态: ✅ 已完成
+- 功能:
+  - [x] FastAPI 服务器
+  - [x] 静态文件服务
+  - [x] WebSocket 端点
+
+---
+
+## Phase 4-5 (详细任务待展开)
+
+Phase 4-5 的详细任务清单参见 [开发步骤.md](./开发步骤.md)
+
+---
+
+## 关键里程碑
+
+### Milestone 1: MVP可运行 (Phase 1完成)
+- 目标日期: -
+- 实际日期: -
+- 标准:
+  - [ ] Gateway可接收企业微信/飞书消息
+  - [ ] 消息可通过WebSocket转发
+  - [ ] Python代码可在沙箱执行
+  - [ ] 基本配置和日志系统运行
+
+---
+
+### Milestone 2: Agent系统完整 (Phase 2完成)
+- 目标日期: -
+- 实际日期: -
+- 标准:
+  - [ ] Agent可调用内置工具
+  - [ ] MCP Server可动态加载
+  - [ ] RAG知识库可搜索
+
+---
+
+### Milestone 3: 双界面模式 (Phase 3完成)
+- 目标日期: -
+- 实际日期: -
+- 标准:
+  - [ ] Claude CLI可通过TUI调用
+  - [ ] 编程任务可在TUI完成
+  - [ ] 通讯工具集成完成
+
+---
+
+### Milestone 4: 高级特性 (Phase 4完成)
+- 目标日期: -
+- 实际日期: -
+- 标准:
+  - [ ] 多Agent协作运行
+  - [ ] 定时任务自动执行
+
+---
+
+### Milestone 5: 生产就绪 (Phase 5完成)
+- 目标日期: -
+- 实际日期: -
+- 标准:
+  - [ ] 系统可生产部署
+  - [ ] 完整的监控和日志
+  - [ ] 用户文档完善
+
+---
+
+## 当前工作项
+
+### 正在进行
+- Phase 1: 核心框架(MVP) 开发
+
+### 待办事项
+1. 完成 Phase 1.1 数据存储层
+2. 完成 Phase 1.2 Gateway WebSocket 服务
+
+### 已完成
+- ✅ 2025-02-04: 完成设计文档
+- ✅ 2025-02-04: 完成项目分析报告
+- ✅ 2025-02-04: 完成开发步骤规划
+- ✅ 2025-02-04: 创建PoC验证文档和测试脚本
+- ✅ 2025-02-04: 完成PoC验证
+  - PoC 1: Claude CLI - 部分可行（subprocess有问题）
+  - PoC 2: 智能路由 - 通过（85.7%准确率）
+  - PoC 3: MCP Server - 测试未完成
+- ✅ 2025-02-04: 确定技术方案（方案C - Web TUI集成）
+- ✅ 2025-02-04: 更新设计文档和开发步骤
+- ✅ 2026-02-04: **Phase 0 项目初始化完成**
+  - 项目目录结构创建
+  - pyproject.toml + 依赖管理
+  - 代码质量工具配置 (ruff, mypy, pre-commit)
+  - 配置系统 (Pydantic Settings + JSON5)
+  - 日志系统 (structlog + 审计日志)
+  - Gateway 基础服务骨架
+  - 测试框架 (pytest, 9/9 通过)
+
+---
+
+## 问题与风险
+
+### 当前问题
+- 无
+
+### 风险追踪
+| 风险 | 影响 | 缓解措施 | 状态 |
+|------|------|----------|------|
+| Claude CLI集成复杂 | 高 | 采用Web TUI方案避免subprocess | ✅ 已解决 |
+| 智能路由效果不佳 | 中 | PoC验证85.7%准确率 | ✅ 已验证 |
+| MCP Server不稳定 | 低 | 延后到Phase 4，MVP不依赖 | 📋 已降级 |
+
+---
+
+## 变更记录
+
+### 2025-02-04
+
+#### 上午：项目初始化
+- **项目初始化**: 创建设计文档、分析报告、开发步骤文档
+- **设计调整**: 智能路由改为Agent实现(基于用户反馈)
+- **设计确认**: 权限控制通过沙箱隔离实现
+- **PoC准备**: 创建完整的PoC验证计划和测试脚本
+
+#### 下午：PoC验证
+- **PoC 1**: Claude CLI集成测试 - 命令行可用，Python subprocess有问题
+- **PoC 2**: 智能路由算法 - 通过，准确率85.7%
+- **PoC 3**: MCP Server加载 - 未完成（可延后）
+
+#### 晚上：方案确定
+- **重大决策**: 采用**Web TUI集成方案**（方案C）
+  - 简单任务：Anthropic API
+  - 复杂任务：Web终端 + SSH + Claude CLI
+  - 优势：避开subprocess，保留CLI完整能力
+- **文档更新**: 
+  - 设计文档.md - 添加Web TUI架构
+  - PoC总结.md - 添加方案C详细说明
+  - 开发步骤.md - 调整Phase 3为Web TUI集成
+  - 进度.md - 更新状态
+- **清理工作**: 准备删除poc目录（待手动完成）
+
+---
+
+## 下一步行动
+
+1. **立即执行**: 开始 Phase 0 项目初始化
+2. **本周目标**: 完成项目骨架搭建
+3. **两周目标**: 完成 Phase 1 MVP
+4. **一个月目标**: 完成 Phase 2 Agent系统
+
+---
+
+## 团队成员
+
+| 成员 | 角色 | 负责模块 |
+|------|------|----------|
+| - | 开发者 | 全部 |
+
+---
+
+**备注**: 
+- 本文档应随开发进度实时更新
+- 每完成一个任务,更新对应的状态和时间
+- 遇到问题及时记录在"问题与风险"部分