# 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 全栈框架