qiaoqichaoandClaude Code
d56c699ce6
按 docs/v2/05-implementation-plan.md §1 候选迁移表与 claude_use/T00 白名单， 从 55e2cdb 抽取 224 个文件（2.48 MB）到独立目录 F:/mini-OpenClaw-v2。 - 排除：凭据(.env/server-deploy.conf/旧DELIVERY.md)、运行数据(xingbang_data 等 4 个 SQLite)、依赖(venv/node_modules 符号链接)、归档(_backup*/test-evidence/ ori_file)、Office 临时文件 - 目标目录独立 git 仓库，初始恢复点；Gitea 远程与分支待 OQ-06 Q2 定案 - 未部署、未启动服务、未调用模型 Co-Authored-By: Claude Code <noreply@anthropic.com>
11 KiB
11 KiB
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}
扩展性设计
添加新工具
- 在
backend/tools/创建新文件 - 实现
@tool装饰的函数 - 在
tools/__init__.py注册
添加新技能
- 在
backend/skills/创建目录 - 添加
SKILL.md(frontmatter + 步骤) - 重启后端自动加载
添加新 API 端点
- 在
backend/api/创建新路由文件 - 在
app.py中注册路由 - 前端
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 全栈框架