Chapter 05
产品架构总览
系统架构图、技术栈概览与部署架构方案
5.1 系统架构图
用户触点层
WhatsApp · Telegram · Discord · Slack · Signal · iMessage · Google Chat · MS Teams · Matrix · WebChat + 更多
WhatsApp · Telegram · Discord · Slack · Signal · iMessage · Google Chat · MS Teams · Matrix · WebChat + 更多
▼ 消息协议
🌐 Web UI
⌨️ CLI
📱 Native Apps
◄►
Gateway（控制面）
WebSocket ws://127.0.0.1:18789
HTTP REST API (Express v5)
会话管理 · 认证安全 · Cron · Webhooks · Nodes
WebSocket ws://127.0.0.1:18789
HTTP REST API (Express v5)
会话管理 · 认证安全 · Cron · Webhooks · Nodes
▼ WebSocket RPC
AI Agent 运行时 (Pi Agent)
模型路由: Claude · GPT · Gemini · Ollama +10
上下文: Compaction · Memory · Logs
Browser
Canvas
Exec
Memory
Cron
TTS
Web
File
Image
48 内置 Skills · 30+ Extension Plugins · MCP (mcporter) · ClawHub
5.2 技术栈概览
| 层次 | 技术选型 | 选型理由 |
|---|---|---|
| 运行时 | Node.js >= 22.12 | 异步 I/O 天然适合消息网关 |
| 语言 | TypeScript (ESM) | 可读性 + 类型安全，降低贡献门槛 |
| 包管理 | pnpm 10 (monorepo) | 高效依赖管理 |
| 构建 | tsdown (rolldown) | 极速构建 |
| HTTP | Express v5 | 成熟稳定 |
| WebSocket | ws 8 | 轻量高性能 |
| Schema | Zod v4 | 运行时类型安全 |
| 前端 | Lit + Vite 7 | 轻量 Web Components |
| 测试 | Vitest 4 | Vite 深度集成 |
| AI Agent | Pi Agent | 灵活 Agent 框架，支持 RPC |
| 浏览器 | Playwright Core (CDP) | 企业级浏览器控制 |
| 向量检索 | sqlite-vec / LanceDB | 本地优先，零外部依赖 |
| TTS | node-edge-tts | 免费高质量语音合成 |
| 原生应用 | Swift / Kotlin | 各平台最佳原生体验 |
5.3 部署架构
| 部署方式 | 适用场景 | 复杂度 |
|---|---|---|
| npm 全局安装 | 个人 Mac/Linux 开发机 | ⭐ 低 |
| Docker Compose | 服务器 / NAS / VPS | ⭐⭐ 中 |
| Fly.io / DigitalOcean | 云端常驻运行 | ⭐⭐ 中 |
| Nix Flake | 可复现环境 | ⭐⭐⭐ 高 |
| Ansible Playbook | 批量部署 | ⭐⭐⭐ 高 |
| Tailscale Serve/Funnel | 安全远程暴露 Gateway | ⭐⭐ 中 |