mini-openclaw/ARCHITECTURE.md

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)

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)

def build_system_prompt(base_dir, rag_mode):
    # 读取 IDENTITY.md
    # 读取 AGENTS.md
    # 构建 SKILLS_SNAPSHOT
    # (可选) RAG 检索相关记忆
    # 组装完整系统提示

SessionManager (backend/graph/session_manager.py)

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:

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)

interface ChatState {
  sessions: Session[]
  currentSessionId: string
  messages: Message[]
  isStreaming: boolean
}

// 全局状态通过 Context API 管理

API 客户端 (src/lib/api.ts)

// 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)

# 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)

{
  "rag_mode": false
}

可通过 API 动态修改:

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