feat: 添加项目规则、环境配置示例及开发文档
This commit is contained in:
锦麟 王
263
PoC总结.md
Normal file
263
PoC总结.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# MineNASAI - PoC 验证总结
|
||||
|
||||
**日期**: 2025-02-04
|
||||
**状态**: PoC 验证完成
|
||||
|
||||
---
|
||||
|
||||
## PoC 验证结果
|
||||
|
||||
### PoC 1: Claude Code CLI 集成
|
||||
|
||||
**状态**: ⚠️ 部分可行
|
||||
|
||||
**测试结果**:
|
||||
- ✅ Claude CLI 已安装（版本 2.1.31）
|
||||
- ✅ Claude CLI 在命令行可正常运行
|
||||
```bash
|
||||
claude -p "今天上海温度" # 正常返回结果
|
||||
```
|
||||
- ❌ Python `subprocess` 集成失败
|
||||
- 进程卡住不返回
|
||||
- 可能原因：缓冲问题、进程通信问题
|
||||
|
||||
**影响**:
|
||||
- 核心功能（编程能力）依赖CLI，但集成有技术难度
|
||||
- 需要寻找替代方案或深入解决subprocess问题
|
||||
|
||||
**建议方案**:
|
||||
1. **使用 Anthropic API**（最可靠）
|
||||
- 优点：稳定、可控、易集成
|
||||
- 缺点：失去CLI的IDE集成能力
|
||||
|
||||
2. **混合方案**（推荐）
|
||||
- 简单任务：使用API
|
||||
- 复杂编程：在TUI中手动调用CLI
|
||||
- 务实且风险低
|
||||
|
||||
3. **继续研究CLI集成**
|
||||
- 深入调试subprocess问题
|
||||
- 尝试文件重定向、异步IO等方案
|
||||
- 时间成本高，不确定性大
|
||||
|
||||
---
|
||||
|
||||
### PoC 2: 智能路由算法
|
||||
|
||||
**状态**: ✅ 验证通过
|
||||
|
||||
**测试结果**:
|
||||
- ✅ 启发式规则准确率: **85.7%** (6/7)
|
||||
- ✅ 超过70%门槛
|
||||
- ✅ 响应速度快（< 1ms）
|
||||
|
||||
**测试用例**:
|
||||
| 用例 | 消息 | 预期 | 实际 | 结果 |
|
||||
|------|------|------|------|------|
|
||||
| 1 | NAS状态? | fast | fast | ✅ |
|
||||
| 2 | 搜索最新的Python教程 | fast | fast | ✅ |
|
||||
| 3 | 实现一个Web服务 | deep | deep | ✅ |
|
||||
| 4 | 重构这个模块 | deep | deep | ✅ |
|
||||
| 5 | 修改配置文件中的端口 | medium | medium | ✅ |
|
||||
| 6 | 添加一个新的API端点 | medium | medium | ✅ |
|
||||
| 7 | 长文本分析任务 | medium | deep | ❌ |
|
||||
|
||||
**结论**:
|
||||
- 启发式规则足够应对大部分场景
|
||||
- 可后续优化规则或引入LLM增强
|
||||
|
||||
---
|
||||
|
||||
### PoC 3: MCP Server 加载
|
||||
|
||||
**状态**: ⚠️ 测试未完成
|
||||
|
||||
**遇到问题**:
|
||||
- Node.js 和 npx 已安装
|
||||
- MCP Server 进程启动后无响应
|
||||
- 可能原因：协议通信、进程管理问题
|
||||
|
||||
**建议**:
|
||||
- MCP Server集成复杂度较高
|
||||
- 可作为Phase 2或更后期的功能
|
||||
- 先用内置工具和API实现MVP
|
||||
|
||||
---
|
||||
|
||||
## 总体评估
|
||||
|
||||
### 可行性结论
|
||||
|
||||
✅ **项目整体可行**，但需要调整技术方案
|
||||
|
||||
| 组件 | 可行性 | 风险 | 建议 |
|
||||
|------|--------|------|------|
|
||||
| Claude CLI | ⚠️ 部分 | 高 | 改用API或混合方案 |
|
||||
| 智能路由 | ✅ 可行 | 低 | 启发式规则足够 |
|
||||
| MCP Server | ⚠️ 待定 | 中 | 延后或简化 |
|
||||
| 其他组件 | ✅ 可行 | 低 | 技术栈成熟 |
|
||||
|
||||
---
|
||||
|
||||
## 推荐技术方案调整
|
||||
|
||||
### 方案A: 使用 Anthropic API（推荐）
|
||||
|
||||
**修改内容**:
|
||||
- Agent运行时直接使用 `anthropic` SDK
|
||||
- 去掉 Claude CLI 桥接模块
|
||||
- TUI仅用于监控和管理
|
||||
|
||||
**优点**:
|
||||
- ✅ 稳定可靠
|
||||
- ✅ 开发速度快
|
||||
- ✅ 易于测试和调试
|
||||
- ✅ 完整的工具调用支持
|
||||
|
||||
**缺点**:
|
||||
- ❌ 失去CLI的特殊能力（如IDE集成）
|
||||
- ❌ 无法利用Claude Code的高级功能
|
||||
|
||||
**影响**:
|
||||
- Phase 3（Claude CLI集成）工作量大幅减少
|
||||
- 整体开发周期缩短约2周
|
||||
|
||||
---
|
||||
|
||||
### 方案B: 混合方案（平衡）
|
||||
|
||||
**实现方式**:
|
||||
1. **日常任务**：使用 Anthropic API
|
||||
- 企业微信/飞书消息处理
|
||||
- 简单查询和对话
|
||||
- 工具调用
|
||||
|
||||
2. **复杂编程**：手动调用 Claude CLI
|
||||
- 在TUI中提供CLI快捷入口
|
||||
- 用户主动选择使用CLI模式
|
||||
- 结果可回传到知识库
|
||||
|
||||
**优点**:
|
||||
- ✅ 保留CLI的编程能力
|
||||
- ✅ API部分稳定可靠
|
||||
- ✅ 用户可按需选择
|
||||
|
||||
**缺点**:
|
||||
- ⚠️ 体验不够无缝
|
||||
- ⚠️ 需要手动切换
|
||||
|
||||
---
|
||||
|
||||
### 方案C: Web TUI集成（用户建议 ✅ 推荐）
|
||||
|
||||
**实现方式**:
|
||||
1. **简单任务**：使用 Anthropic API
|
||||
- 企业微信/飞书消息处理
|
||||
- 日常查询、简单操作
|
||||
- API稳定高效
|
||||
|
||||
2. **复杂编程任务**：Web TUI + SSH + Claude CLI
|
||||
```
|
||||
消息提示 "请在Web TUI处理"
|
||||
↓
|
||||
用户打开Web终端页面
|
||||
↓
|
||||
xterm.js显示终端界面
|
||||
↓
|
||||
WebSocket连接后端
|
||||
↓
|
||||
paramiko SSH连接localhost
|
||||
↓
|
||||
直接运行 claude 命令
|
||||
↓
|
||||
用户在浏览器中与Claude交互
|
||||
```
|
||||
|
||||
**核心优势**:
|
||||
- ✅ **完全避开subprocess问题** - 不做进程间通信
|
||||
- ✅ **保留CLI完整能力** - 用户直接操作，无限制
|
||||
- ✅ **实现简单** - xterm.js成熟稳定
|
||||
- ✅ **体验自然** - 像使用SSH工具一样
|
||||
- ✅ **权限隔离** - SSH本身就是隔离机制
|
||||
- ✅ **跨平台** - 浏览器即可访问
|
||||
|
||||
**技术栈**:
|
||||
- 前端：xterm.js（Web终端模拟器）
|
||||
- 通信：WebSocket（双向I/O）
|
||||
- 后端：paramiko（Python SSH库）
|
||||
- 连接：SSH localhost
|
||||
|
||||
**影响**:
|
||||
- Phase 3工作量适中（约5-7天）
|
||||
- 无subprocess调试成本
|
||||
- 用户体验最优
|
||||
|
||||
---
|
||||
|
||||
## 下一步建议
|
||||
|
||||
### 立即行动
|
||||
|
||||
1. **✅ 采用方案C（Web TUI集成）**
|
||||
- 简单任务用Anthropic API
|
||||
- 复杂任务用Web TUI + SSH + Claude CLI
|
||||
- 避免所有subprocess问题
|
||||
- 保留完整CLI能力
|
||||
|
||||
2. **开始 Phase 0: 项目初始化**
|
||||
- 创建项目结构
|
||||
- 配置开发环境
|
||||
- 设置依赖管理
|
||||
|
||||
3. **✅ 设计文档已更新**
|
||||
- 技术栈已调整
|
||||
- Phase 3为Web TUI集成
|
||||
- 时间估算已优化
|
||||
|
||||
### 风险管理
|
||||
|
||||
**已降低的风险**:
|
||||
- ✅ 智能路由效果 → 85.7%准确率，风险低
|
||||
- ✅ Python技术栈 → 成熟可靠
|
||||
|
||||
**需要关注的风险**:
|
||||
- ⚠️ MCP Server集成 → 建议延后
|
||||
- ⚠️ 性能优化 → 需要后期压力测试
|
||||
|
||||
---
|
||||
|
||||
## 资源和时间重估
|
||||
|
||||
### 方案C（Web TUI集成）✅ 采用
|
||||
|
||||
| Phase | 原估算 | 新估算 | 变化 | 说明 |
|
||||
|-------|--------|--------|------|------|
|
||||
| Phase 0 | 2-3天 | 2-3天 | 不变 | 项目初始化 |
|
||||
| Phase 1 | 14-21天 | 14-21天 | 不变 | Gateway + 通讯 |
|
||||
| Phase 2 | 14-21天 | **10-14天** | ⬇️ 简化 | 暂不做MCP/RAG |
|
||||
| Phase 3 | 12-17天 | **7-10天** | ⬇️ 减少 | Web TUI + API |
|
||||
| Phase 4 | 10-14天 | 10-14天 | 不变 | 高级特性 |
|
||||
| Phase 5 | 7-10天 | 7-10天 | 不变 | 生产就绪 |
|
||||
|
||||
**新总计**: 52-81天（优化约7-12天）
|
||||
|
||||
**技术债务降低**:
|
||||
- ❌ 无subprocess调试成本
|
||||
- ❌ 无MCP集成复杂度（可选）
|
||||
- ❌ 无RAG初期成本（可选）
|
||||
- ✅ Web TUI成熟方案
|
||||
|
||||
---
|
||||
|
||||
## 附录：PoC 验证文件
|
||||
|
||||
- `poc/router_test/poc_2_heuristic.py` - 智能路由测试（✅ 通过）
|
||||
- `poc/claude_cli_test/poc_1_basic.py` - CLI基础测试（⚠️ 问题）
|
||||
- `poc/mcp_test/poc_3_basic.py` - MCP连接测试（⚠️ 未完成）
|
||||
|
||||
---
|
||||
|
||||
**PoC验证完成时间**: 2025-02-04 16:55
|
||||
**方案确定时间**: 2025-02-04 17:10
|
||||
**采用方案**: ✅ 方案C - Web TUI集成
|
||||
**下一步**: 开始Phase 0项目初始化
|
||||
Reference in New Issue
Block a user