881 lines
22 KiB
Markdown
881 lines
22 KiB
Markdown
# 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/<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费用（按需）
|
||
|
||
---
|
||
|
||
**文档结束**
|