夜雨聆风前言
这是QwenPaw源码解析系列的最后一篇文章，我们将探讨控制台（Console）的设计与实现，以及QwenPaw的部署方式。
Console控制台架构
QwenPaw的Web控制台采用前后端分离架构：
┌─────────────────────────────────────────────────────┐
│ Console架构 │
├─────────────────────────────────────────────────────┤
│ │
│ 前端 (TypeScript/React) 后端 (Python) │
│ ┌─────────────────────┐ ┌──────────────┐│
│ │ React组件 │ ←REST→ │ API Server ││
│ │ 状态管理 │ │ WebSocket ││
│ │ 样式 (Less) │ │ Agent ││
│ └─────────────────────┘ └──────────────┘│
│ │
└─────────────────────────────────────────────────────┘
前端结构
console/
├── src/
│ ├── components/ # React组件
│ │ ├── Chat/ # 聊天界面
│ │ ├── Settings/ # 设置面板
│ │ ├── AgentList/ # 智能体列表
│ │ └── Memory/ # 记忆查看
│ ├── hooks/ # 自定义Hooks
│ ├── services/ # API服务
│ ├── store/ # 状态管理
│ └── styles/ # 样式文件
├── dist/ # 构建输出
└── package.json
API服务层
# app/server.py
class APIServer:
"""API服务器"""
def __init__(self, agent: QwenPawAgent):
self.agent = agent
self.app = FastAPI()
self._setup_routes()
def _setup_routes(self) -> None:
"""设置API路由"""
# 对话接口
@self.app.post("/api/chat")
async def chat(request: ChatRequest):
"""发送消息并获取回复"""
response = await self.agent.reply(
Msg(
role="user",
content=request.message,
)
)
return ChatResponse(
message=response.get_text_content(),
agent_id=self.agent.agent_id,
)
# WebSocket实时通信
@self.app.websocket("/ws/chat")
async def chat_ws(websocket: WebSocket):
"""WebSocket聊天接口"""
await websocket.accept()
while True:
data = await websocket.receive_json()
message = data.get("message", "")
# 处理消息
response = await self.agent.reply(
Msg(role="user", content=message)
)
# 发送响应
await websocket.send_json({
"type": "message",
"content": response.get_text_content(),
})
# 配置接口
@self.app.get("/api/config")
async def get_config():
"""获取当前配置"""
return self.agent.get_config()
@self.app.post("/api/config")
async def update_config(config: dict):
"""更新配置"""
await self.agent.update_config(config)
# 记忆接口
@self.app.get("/api/memory")
async def get_memory():
"""获取记忆内容"""
return await self.agent.get_memory_summary()
@self.app.post("/api/memory/compact")
async def compact_memory():
"""触发记忆压缩"""
return await self.agent.compact_context()
控制台核心组件
聊天界面
// components/Chat/ChatPanel.tsx
interface ChatMessage {
id: string;
role: "user" | "assistant" | "system";
content: string;
timestamp: Date;
}
export const ChatPanel: React.FC = () => {
const [messages, setMessages] = useState<ChatMessage[]>([]);
const [input, setInput] = useState("");
const [loading, setLoading] = useState(false);
const sendMessage = async () => {
if (!input.trim()) return;
const userMessage: ChatMessage = {
id: generateId(),
role: "user",
content: input,
timestamp: new Date(),
};
setMessages(prev => [...prev, userMessage]);
setInput("");
setLoading(true);
try {
const response = await fetch("/api/chat", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ message: input }),
});
const data = await response.json();
const assistantMessage: ChatMessage = {
id: generateId(),
role: "assistant",
content: data.message,
timestamp: new Date(),
};
setMessages(prev => [...prev, assistantMessage]);
} finally {
setLoading(false);
}
};
return (
<div className="chat-panel">
<div className="messages">
{messages.map(msg => (
<MessageBubble
key={msg.id}
role={msg.role}
content={msg.content}
timestamp={msg.timestamp}
/>
))}
</div>
<div className="input-area">
<textarea
value={input}
onChange={e => setInput(e.target.value)}
onKeyDown={e => {
if (e.key === "Enter" && !e.shiftKey) {
e.preventDefault();
sendMessage();
}
}}
/>
<button onClick={sendMessage} disabled={loading}>
{loading ? "发送中..." : "发送"}
</button>
</div>
</div>
);
};
WebSocket实时聊天
// services/websocket.ts
export class ChatWebSocket {
private ws: WebSocket | null = null;
private reconnectAttempts = 0;
private maxReconnectAttempts = 5;
connect() {
this.ws = new WebSocket("ws://localhost:8088/ws/chat");
this.ws.onopen = () => {
console.log("WebSocket connected");
this.reconnectAttempts = 0;
};
this.ws.onmessage = (event) => {
const data = JSON.parse(event.data);
this.handleMessage(data);
};
this.ws.onerror = (error) => {
console.error("WebSocket error:", error);
};
this.ws.onclose = () => {
this.handleClose();
};
}
private handleClose() {
if (this.reconnectAttempts < this.maxReconnectAttempts) {
this.reconnectAttempts++;
setTimeout(() => this.connect(), 2000 * this.reconnectAttempts);
}
}
send(message: string) {
if (this.ws?.readyState === WebSocket.OPEN) {
this.ws.send(JSON.stringify({ message }));
}
}
}
部署方式
Docker部署
# Dockerfile
FROM python:3.11-slim
WORKDIR /app
# 安装系统依赖
RUN apt-get update && apt-get install -y \
curl \
&& rm -rf /var/lib/apt/lists/*
# 安装Node.js (前端构建)
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
&& apt-get install -y nodejs
# 复制前端代码
COPY console/ ./console/
# 构建前端
WORKDIR /app/console
RUN npm ci && npm run build
# 复制Python代码
WORKDIR /app
COPY src/ ./src/
COPY pyproject.toml ./
COPY setup.py ./
# 安装Python依赖
RUN pip install -e .
# 复制前端构建产物
RUN mkdir -p src/qwenpaw/console \
&& cp -R console/dist/* src/qwenpaw/console/
# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
CMD curl -f http://localhost:8088/health || exit 1
# 启动命令
CMD ["qwenpaw", "app"]
Docker Compose
# docker-compose.yml
version: '3.8'
services:
qwenpaw:
image: agentscope/qwenpaw:latest
ports:
- "8088:8088"
volumes:
- qwenpaw-data:/app/working
- qwenpaw-secrets:/app/working.secret
- qwenpaw-backups:/app/working.backups
environment:
- DASHSCOPE_API_KEY=${DASHSCOPE_API_KEY}
restart: unless-stopped
# 可选：Redis缓存
redis:
image: redis:7-alpine
ports:
- "6379:6379"
volumes:
- redis-data:/data
volumes:
qwenpaw-data:
qwenpaw-secrets:
qwenpaw-backups:
redis-data:
阿里云ECS一键部署
# 使用阿里云Compute Nest进行一键部署
# 参考: https://computenest.console.aliyun.com/service/instance/create/cn-hangzhou
性能优化
模型响应流式输出
# 支持流式输出的API
@self.app.post("/api/chat/stream")
async def chat_stream(request: ChatRequest):
"""流式响应接口"""
async def generate():
async for chunk in self.agent.reply_stream(
Msg(role="user", content=request.message)
):
yield f"data: {json.dumps({'chunk': chunk})}\n\n"
return StreamingResponse(
generate(),
media_type="text/event-stream",
)
前端流式处理
// services/streamChat.ts
export const streamChat = async (
message: string,
onChunk: (chunk: string) => void,
onComplete: () => void,
onError: (error: Error) => void
) => {
const response = await fetch("/api/chat/stream", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ message }),
});
const reader = response.body?.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader!.read();
if (done) {
onComplete();
break;
}
const chunk = decoder.decode(value);
onChunk(chunk);
}
};
监控与日志
日志配置
# utils/logging.py
def setup_logger(level: str = "info") -> None:
"""设置日志"""
# 创建日志目录
log_dir = WORKING_DIR / "logs"
log_dir.mkdir(exist_ok=True)
# 文件处理器
file_handler = logging.handlers.RotatingFileHandler(
log_dir / "qwenpaw.log",
maxBytes=10 * 1024 * 1024, # 10MB
backupCount=5,
)
file_handler.setFormatter(
logging.Formatter(
"%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
)
# 控制台处理器
console_handler = logging.StreamHandler()
console_handler.setFormatter(
logging.Formatter("%(levelname)s: %(message)s")
)
# 配置根日志
logging.basicConfig(
level=getattr(logging, level.upper()),
handlers=[file_handler, console_handler],
)
健康检查
@self.app.get("/health")
async def health_check():
"""健康检查接口"""
checks = {
"status": "healthy",
"agent": "running" if self.agent else "stopped",
"timestamp": datetime.now().isoformat(),
}
# 检查各组件状态
if self.agent:
try:
memory_status = await self.agent.get_memory_status()
checks["memory"] = memory_status
except Exception:
checks["memory"] = "error"
return checks
源码系列总结
核心架构回顾
┌─────────────────────────────────────────────────────┐
│ QwenPaw核心架构 │
├─────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌──────────┐│
│ │ Console │ │ ACP │ │ Skills ││
│ │ (前端) │ │ (通信协议) │ │ (扩展) ││
│ └──────┬──────┘ └──────┬──────┘ └────┬─────┘│
│ │ │ │ │
│ └──────────────────┼──────────────────┘ │
│ ↓ │
│ ┌────────────────────┐ │
│ │ QwenPawAgent │ │
│ │ (核心智能体) │ │
│ └─────────┬──────────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ ↓ ↓ ↓ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Memory │ │ Context │ │ Tools │ │
│ │ Manager │ │ Manager │ │ Guard │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ │
└─────────────────────────────────────────────────────┘
设计模式总结
| 模式 | 应用场景 |
|---|---|
| Mixin | ToolGuardMixin扩展功能 |
| Factory | ModelFactory创建模型 |
| Registry | 记忆管理、上下文管理器插件化 |
| Observer | 生命周期钩子系统 |
| Strategy | 同名工具冲突处理策略 |
| Builder | 配置加载与验证 |
关键设计亮点
学习建议
如果你想深入学习QwenPaw源码，建议：
资源链接
往期回顾：
感谢大家的陪伴！如果这个系列对你有帮助，请：
如果你有任何问题或建议，欢迎在评论区留言，我们下个项目见！
