chore: mini-openclaw 初始版本
Next.js 前端 + FastAPI/LangChain 后端透明 agent平台 - 含 .gitignore, 敏感文件(sessions数据/.env/venv等)已排除 - 待后续添加 trajectory 自进化机制
This commit is contained in:
NathanAlex7
+323
@@ -0,0 +1,323 @@
|
||||
# mini-OpenClaw 架构说明
|
||||
|
||||
## 系统架构图
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 用户界面 │
|
||||
│ (Next.js Frontend) │
|
||||
│ http://localhost:3000 │
|
||||
└───────────────────────┬─────────────────────────────────────┘
|
||||
│ HTTP/SSE
|
||||
│
|
||||
┌───────────────────────▼─────────────────────────────────────┐
|
||||
│ FastAPI Backend │
|
||||
│ http://localhost:8002 │
|
||||
│ ┌──────────────────────────────────────────────────────┐ │
|
||||
│ │ API Routes (/api) │ │
|
||||
│ │ • /chat - 流式聊天 (SSE) │ │
|
||||
│ │ • /sessions - 会话管理 │ │
|
||||
│ │ • /files - 文件操作 │ │
|
||||
│ │ • /config - 配置管理 │ │
|
||||
│ └───────────────────┬──────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────────────────▼──────────────────────────────────┐ │
|
||||
│ │ Agent Manager (LangChain) │ │
|
||||
│ │ • build_system_prompt() - 构建系统提示 │ │
|
||||
│ │ • astream() - 流式生成 │ │
|
||||
│ │ • tool_invocation - 工具调用 │ │
|
||||
│ └───────┬──────────────────────────────┬───────────────┘ │
|
||||
│ │ │ │
|
||||
│ ┌───────▼─────────┐ ┌──────▼──────────┐ │
|
||||
│ │ Core Tools │ │ Session Mgr │ │
|
||||
│ │ • terminal │ │ • history │ │
|
||||
│ │ • python_repl │ │ • persistence │ │
|
||||
│ │ • fetch_url │ │ • title_gen │ │
|
||||
│ │ • read_file │ └─────────────────┘ │
|
||||
│ │ • search_kb │ │
|
||||
│ └─────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────┐ │
|
||||
│ │ Knowledge Base (RAG) │ │
|
||||
│ │ • LlamaIndex Indexer │ │
|
||||
│ │ • BM25 + Embedding Retrieval │ │
|
||||
│ │ • memory/ 目录索引 │ │
|
||||
│ └──────────────────────────────────────────────────────┘ │
|
||||
└───────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ API Calls
|
||||
│
|
||||
┌───────────────────────▼─────────────────────────────────────┐
|
||||
│ DeepSeek Gateway │
|
||||
│ http://49.232.133.151/v1 │
|
||||
│ (deepseek-v4-flash) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 核心流程
|
||||
|
||||
### 1. 聊天流程
|
||||
|
||||
```
|
||||
用户输入 → Frontend
|
||||
↓
|
||||
POST /api/chat (SSE stream)
|
||||
↓
|
||||
Agent Manager
|
||||
↓
|
||||
┌─ build_system_prompt()
|
||||
│ ├─ 读取 IDENTITY.md
|
||||
│ ├─ 读取 AGENTS.md
|
||||
│ ├─ 加载 SKILLS_SNAPSHOT
|
||||
│ └─ (可选) RAG 检索 MEMORY
|
||||
│
|
||||
┌─ astream(message, history)
|
||||
│ ├─ 构建 LangChain messages
|
||||
│ ├─ 调用 DeepSeek API
|
||||
│ ├─ 流式返回 tokens
|
||||
│ └─ 自动工具调用
|
||||
│
|
||||
↓ SSE events
|
||||
├─ {"type": "token", "content": "..."}
|
||||
├─ {"type": "tool_start", "tool": "...", "input": "..."}
|
||||
├─ {"type": "tool_result", "output": "..."}
|
||||
└─ {"type": "done"}
|
||||
↓
|
||||
Frontend 实时渲染
|
||||
```
|
||||
|
||||
### 2. 技能调用流程
|
||||
|
||||
```
|
||||
用户: "查询北京天气"
|
||||
↓
|
||||
Agent 识别意图 → 需要 get_weather 技能
|
||||
↓
|
||||
Agent 调用 read_file("skills/get_weather/SKILL.md")
|
||||
↓
|
||||
读取技能定义:
|
||||
name: get_weather
|
||||
description: 获取指定城市的实时天气信息
|
||||
步骤:
|
||||
1. 提取城市名称
|
||||
2. fetch_url("https://wttr.in/{城市}?format=j1")
|
||||
3. 解析 JSON
|
||||
4. 自然语言汇报
|
||||
↓
|
||||
Agent 按步骤执行:
|
||||
├─ 提取: 北京 (Beijing)
|
||||
├─ 调用 fetch_url("https://wttr.in/Beijing?format=j1")
|
||||
├─ 解析天气数据
|
||||
└─ 回复: "北京当前天气：晴，温度 25°C..."
|
||||
↓
|
||||
用户收到回复
|
||||
```
|
||||
|
||||
### 3. 记忆系统
|
||||
|
||||
#### 短期记忆 (Session)
|
||||
- 存储位置: `backend/sessions/{session_id}.json`
|
||||
- 内容: 对话历史 (role: user/assistant, content: 消息内容)
|
||||
- 生命周期: 会话期间持久化
|
||||
|
||||
#### 长期记忆 (MEMORY.md)
|
||||
- 存储位置: `backend/memory/MEMORY.md`
|
||||
- 内容: 跨会话的重要信息（用户偏好、重要决策）
|
||||
- 更新方式: Agent 使用 terminal 工具追加内容
|
||||
|
||||
#### RAG 检索记忆
|
||||
- 索引位置: `backend/knowledge/.index/`
|
||||
- 检索方式: BM25 + Embedding 混合检索
|
||||
- 触发条件: config.json 中 `rag_mode: true`
|
||||
|
||||
## 关键组件说明
|
||||
|
||||
### AgentManager (backend/graph/agent.py)
|
||||
|
||||
```python
|
||||
class AgentManager:
|
||||
def initialize(base_dir):
|
||||
# 初始化 LLM (DeepSeek)
|
||||
# 加载工具
|
||||
# 初始化会话管理器
|
||||
|
||||
def _build_agent():
|
||||
# 构建系统提示
|
||||
# 创建 LangChain Agent
|
||||
|
||||
async def astream(message, history):
|
||||
# 流式生成响应
|
||||
# 处理工具调用
|
||||
# 返回 SSE 事件
|
||||
```
|
||||
|
||||
### PromptBuilder (backend/graph/prompt_builder.py)
|
||||
|
||||
```python
|
||||
def build_system_prompt(base_dir, rag_mode):
|
||||
# 读取 IDENTITY.md
|
||||
# 读取 AGENTS.md
|
||||
# 构建 SKILLS_SNAPSHOT
|
||||
# (可选) RAG 检索相关记忆
|
||||
# 组装完整系统提示
|
||||
```
|
||||
|
||||
### SessionManager (backend/graph/session_manager.py)
|
||||
|
||||
```python
|
||||
class SessionManager:
|
||||
def load_session(session_id):
|
||||
# 加载会话历史
|
||||
|
||||
def save_session(session_id, messages):
|
||||
# 保存会话到 JSON
|
||||
|
||||
def update_title(session_id, title):
|
||||
# 更新会话标题
|
||||
```
|
||||
|
||||
### Tools (backend/tools/)
|
||||
|
||||
每个工具都是一个 LangChain Tool:
|
||||
|
||||
```python
|
||||
from langchain_core.tools import tool
|
||||
|
||||
@tool
|
||||
def terminal(command: str) -> str:
|
||||
"""执行 Shell 命令"""
|
||||
# 实现...
|
||||
|
||||
@tool
|
||||
def python_repl(code: str) -> str:
|
||||
"""运行 Python 代码"""
|
||||
# 实现...
|
||||
|
||||
# 等等...
|
||||
```
|
||||
|
||||
## 前端架构
|
||||
|
||||
### 组件树
|
||||
|
||||
```
|
||||
App (src/app/page.tsx)
|
||||
└── ChatInterface (src/components/chat/)
|
||||
├── Sidebar
|
||||
│ ├── SessionList
|
||||
│ └── NewSessionButton
|
||||
│
|
||||
└── ChatArea
|
||||
├── MessageList
|
||||
│ └── Message[]
|
||||
│ ├── UserMessage
|
||||
│ ├── AssistantMessage
|
||||
│ └── ToolCallDisplay
|
||||
│
|
||||
└── InputBox
|
||||
├── TextArea
|
||||
└── SendButton
|
||||
```
|
||||
|
||||
### 状态管理 (src/lib/store.tsx)
|
||||
|
||||
```typescript
|
||||
interface ChatState {
|
||||
sessions: Session[]
|
||||
currentSessionId: string
|
||||
messages: Message[]
|
||||
isStreaming: boolean
|
||||
}
|
||||
|
||||
// 全局状态通过 Context API 管理
|
||||
```
|
||||
|
||||
### API 客户端 (src/lib/api.ts)
|
||||
|
||||
```typescript
|
||||
// SSE 流式聊天
|
||||
async function* streamChat(message, sessionId)
|
||||
|
||||
// 会话管理
|
||||
async function listSessions()
|
||||
async function createSession()
|
||||
async function deleteSession(id)
|
||||
|
||||
// 文件操作
|
||||
async function readFile(path)
|
||||
async function saveFile(path, content)
|
||||
```
|
||||
|
||||
## 配置系统
|
||||
|
||||
### 后端配置 (.env)
|
||||
|
||||
```env
|
||||
# LLM
|
||||
DEEPSEEK_API_KEY=...
|
||||
DEEPSEEK_BASE_URL=http://49.232.133.151/v1
|
||||
DEEPSEEK_MODEL=deepseek-v4-flash
|
||||
|
||||
# Embedding
|
||||
EMBEDDING_MODEL=text-embedding-3-small
|
||||
|
||||
# Server
|
||||
PORT=8002
|
||||
```
|
||||
|
||||
### 运行时配置 (config.json)
|
||||
|
||||
```json
|
||||
{
|
||||
"rag_mode": false
|
||||
}
|
||||
```
|
||||
|
||||
可通过 API 动态修改:
|
||||
|
||||
```bash
|
||||
PUT /api/config/rag-mode
|
||||
{"enabled": true}
|
||||
```
|
||||
|
||||
## 扩展性设计
|
||||
|
||||
### 添加新工具
|
||||
|
||||
1. 在 `backend/tools/` 创建新文件
|
||||
2. 实现 `@tool` 装饰的函数
|
||||
3. 在 `tools/__init__.py` 注册
|
||||
|
||||
### 添加新技能
|
||||
|
||||
1. 在 `backend/skills/` 创建目录
|
||||
2. 添加 `SKILL.md` (frontmatter + 步骤)
|
||||
3. 重启后端自动加载
|
||||
|
||||
### 添加新 API 端点
|
||||
|
||||
1. 在 `backend/api/` 创建新路由文件
|
||||
2. 在 `app.py` 中注册路由
|
||||
3. 前端 `src/lib/api.ts` 添加客户端函数
|
||||
|
||||
## 安全考虑
|
||||
|
||||
- **工具沙箱**: `terminal` 和 `read_file` 限制在 `base_dir` 内
|
||||
- **会话隔离**: 每个 session_id 独立存储
|
||||
- **API 密钥**: 通过 .env 管理，不提交到 Git (.gitignore)
|
||||
- **CORS**: 开发模式允许所有来源，生产环境需配置白名单
|
||||
|
||||
## 性能优化
|
||||
|
||||
- **流式响应**: SSE 降低首字延迟
|
||||
- **会话缓存**: 内存中缓存活跃会话
|
||||
- **RAG 索引**: 预构建知识库索引
|
||||
- **前端**: Next.js App Router + React 18 Streaming
|
||||
|
||||
## 参考资料
|
||||
|
||||
- OpenClaw: 架构理念和配置组织方式
|
||||
- LangChain: Agent 框架和工具系统
|
||||
- LlamaIndex: RAG 检索和索引
|
||||
- FastAPI: 高性能异步 Web 框架
|
||||
- Next.js: React 全栈框架
|
||||
Reference in New Issue
Block a user