#architecture #ai-tools #claud-code #mobile

Happy Coder 架构分析

项目概述

Happy Coder 是一个开源项目，提供 Claude Code 和 Codex 的移动/Web 客户端，支持端到-end 加密、实时语音和设备间无缝切换。

GitHub: https://github.com/slopus/happy
许可证: MIT
当前版本: 0.14.0-0 (happy-cli)
文档: https://happy.engineering/docs/

核心特性

📱 移动端访问 - 在手机/平板上控制 AI 编程助手
🔔 推送通知 - AI 需要权限或遇到错误时及时通知
⚡ 设备即时切换 - 一键在手机和桌面间切换控制
🔐 端到端加密 - 代码从不以未加密形式离开设备
🛠️ 开源透明 - 可自行审计代码，无遥测无追踪
💰 零成本 - 使用自己的电脑，无使用费或订阅费

系统架构

整体架构图

┌─────────────────────────────────────────────────────────────┐
│                        用户设备                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│   │  Happy App  │    │  Happy CLI  │    │  Happy App  │    │
│   │  (移动端)   │    │  (桌面端)   │    │  (Web)      │    │
│   └──────┬──────┘    └──────┬──────┘    └──────┬──────┘    │
│          │                  │                  │            │
│          └──────────────────┼──────────────────┘            │
│                             │                               │
│                    ┌────────▼────────┐                      │
│                    │   Happy Server  │                      │
│                    │   (加密同步)     │                      │
│                    └────────┬────────┘                      │
│                             │                               │
│              ┌──────────────┼──────────────┐                │
│              │              │              │                │
│        ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐         │
│        │ Claude    │  │  Codex    │  │   MCP     │         │
│        │ Code      │  │           │  │  Server   │         │
│        └───────────┘  └───────────┘  └───────────┘         │
└─────────────────────────────────────────────────────────────┘

工作流程

本地模式 (桌面端):
- 用户运行 happy 替代 claude
- CLI 作为包装器启动 Claude Code/Codex
- 会话在本地运行
远程模式 (移动端控制):
- 用户从手机发起远程控制请求
- CLI 将会话切换到远程模式
- 通过 Happy Server 建立加密通道
设备切换:
- 在手机上按任意键切换回本地控制
- 桌面端检测到键盘输入后恢复本地模式

项目组件

1. Happy CLI (`happy-coder`)

位置: packages/happy-cli

功能:

Claude Code 和 Codex 的命令行包装器
作为守护进程运行 (daemon start/stop/status)
支持稳定版和开发版切换
提供 happy-mcp MCP 服务器集成

技术栈:

TypeScript (ESM)
Node.js CLI (ink - React CLI 框架)
Socket.io 客户端
Fastify 服务器

关键依赖:

@modelcontextprotocol/sdk - MCP 协议支持
@agentclientprotocol/sdk - Agent 客户端协议
ai - AI 相关工具
socket.io-client - WebSocket 通信
ink - React CLI 界面

入口点:

happy         # 主命令
happy codex   # Codex 模式
happy-mcp     # MCP 服务器模式

2. Happy App

位置: packages/happy-app

功能:

跨平台移动应用 (iOS/Android)
Web 应用
macOS 桌面版 (Tauri)

技术栈:

框架: Expo (React Native)
UI: React Navigation, Expo UI
实时通信: LiveKit (WebRTC 语音)
语音: ElevenLabs (AI 语音)
加密: libsodium (react-native-libsodium)
桌面: Tauri (Rust + React)

开发环境:

yarn start          # 启动开发服务器
yarn ios:dev        # iOS 开发版
yarn android:dev    # Android 开发版
yarn tauri:dev      # macOS 桌面版

关键依赖:

@livekit/react-native - WebRTC 实时通信
@elevenlabs/react - 语音合成
@react-navigation/* - 导航
@shopify/react-native-skia - 高性能渲染
expo-* - Expo 生态系统

3. Happy Server

位置: packages/happy-server

功能:

设备间加密同步
认证服务
Socket.io 实时通信
文件存储 (S3/MinIO)

技术栈:

Node.js + TypeScript
Fastify (Web 框架)
Prisma (ORM)
PostgreSQL (数据库)
Redis (缓存/消息)
Socket.io (实时通信)

关键依赖:

fastify + fastify-type-provider-zod - API 框架
prisma + @prisma/client - 数据库 ORM
socket.io - 实时通信
@socket.io/redis-streams-adapter - Redis 适配器
minio - S3 兼容存储
elevenlabs - 语音服务集成
privacy-kit - 隐私加密工具

服务脚本:

yarn dev           # 开发模式 (端口 3005)
yarn migrate       # 数据库迁移
yarn db            # 启动 PostgreSQL Docker
yarn redis         # 启动 Redis Docker
yarn s3            # 启动 MinIO

安全架构

端到端加密

┌─────────────────────────────────────────┐
│              设备 A (桌面)               │
│  ┌─────────────────────────────┐        │
│  │  明文数据                   │        │
│  └──────────┬──────────────────┘        │
│             │ 加密                          │
│       ┌─────▼─────┐                       │
│       │ libsodium │                       │
│       │ 加密层    │                       │
│       └─────┬─────┘                       │
│             │ 密文传输                      │
└─────────────┼─────────────────────────────┘
              │
              │ 网络 (Happy Server 中转)
              │
┌─────────────┼─────────────────────────────┐
│       ┌─────▼─────┐                       │
│       │ libsodium │                       │
│       │ 解密层    │                       │
│       └─────┬─────┘                       │
│             │ 解密                          │
│  ┌─────────────────────────────┐        │
│  │  明文数据                   │        │
│  └─────────────────────────────┘        │
└─────────────────────────────────────────┘

加密特性:

使用 libsodium 进行端到端加密
代码从不以未加密形式离开用户设备
服务器只中转加密数据，无法解密内容

认证流程

首次安装时生成设备密钥对
通过 QR 码或链接关联设备
JWT token 管理会话
Bearer auth 保护 API

数据流

消息传输流程

用户输入 → Happy App → Happy Server → Happy CLI → Claude Code
              ↑                                        ↓
              ←───────── 加密响应 ←────────────────────┘

文件同步

代码变更 → 本地加密 → Happy Server → 目标设备解密
大文件 → S3 存储 (加密) → 分享链接
增量同步 → WebSocket 实时推送

开发环境设置

Monorepo 结构

{
  "workspaces": ["packages/happy-app", "packages/happy-cli", "packages/happy-server"],
  "packageManager": "yarn@1.22.22"
}

环境变量

Happy CLI:

HAPPY_API_URL - Happy Server 地址
HAPPY_DEV - 开发模式

Happy App:

APP_ENV - 环境 (development/preview/production)

Happy Server:

DATABASE_URL - PostgreSQL 连接
REDIS_URL - Redis 连接
S3_* - MinIO/S3 配置
JWT_SECRET - JWT 密钥

API 设计

Web API (Fastify + Zod)

// 示例路由结构
POST /auth/login       // 设备认证
GET /sessions          // 列出活跃会话
WS /ws                 // WebSocket 实时连接
POST /files/upload     // 文件上传 (S3)
GET /files/:id         // 文件下载

MCP 集成

Happy CLI 提供 MCP 服务器:

happy-mcp              // MCP 服务器模式
                       // 支持 Claude Desktop 集成

部署架构

开发环境

┌────────────────────────────────────────┐
│         开发机器 (macOS/Linux)          │
│  ┌──────────────────────────────────┐  │
│  │ Docker Containers               │  │
│  │ ├── PostgreSQL:5432             │  │
│  │ ├── Redis:6379                  │  │
│  │ └── MinIO:9000/9001             │  │
│  └──────────────────────────────────┘  │
│  ┌──────────────────────────────────┐  │
│  │ Happy Server (localhost:3005)    │  │
│  └──────────────────────────────────┘  │
└────────────────────────────────────────┘

生产环境

服务器: 云主机 (VPS/云函数)
数据库: 托管 PostgreSQL (RDS/Cloud SQL)
存储: S3 兼容存储
CDN: 静态资源分发

性能优化

增量同步 - 只传输变化部分
本地缓存 - 减少网络请求
WebRTC 直连 - 语音通话低延迟
React Native FlatList - 长列表优化
React Native Skia - GPU 加速渲染

优缺点分析

优点

✅ 完全开源，可审计
✅ 端到端加密保护隐私
✅ 跨平台支持 (iOS/Android/Web/macOS)
✅ 零使用成本
✅ 保留本地开发环境
✅ 实时语音支持

缺点

⚠️ 需要自建服务器 (无托管服务)
⚠️ 初始配置较复杂
⚠️ 移动端功能依赖网络连接
⚠️ 对 Claude Code 版本有依赖

与竞品对比

特性	Happy Coder	Claude Desktop	GitHub Copilot
移动端	✅	❌	❌
开源	✅	❌	❌
端到端加密	✅	❌	❌
自托管	✅	❌	❌
免费	✅	✅	❌ 订阅制
实时语音	✅	❌	❌

参考资源

官方文档: https://happy.engineering/docs/
GitHub: https://github.com/slopus/happy
Discord: https://discord.gg/fX9WBAhyfD
演示视频: https://youtu.be/GCS0OG9QMSE
iOS App: https://apps.apple.com/us/app/happy-claude-code-client/id6748571505
Android App: https://play.google.com/store/apps/details?id=com.ex3ndr.happy
Web App: https://app.happy.engineering

最后更新: 2026-02-02
数据来源: GitHub 仓库 + 官方文档

Happy Coder 架构分析

项目概述

核心特性

系统架构

整体架构图

工作流程

项目组件

1. Happy CLI (happy-coder)

2. Happy App

3. Happy Server

安全架构

端到端加密

认证流程

数据流

消息传输流程

文件同步

开发环境设置

Monorepo 结构

环境变量

API 设计

Web API (Fastify + Zod)

MCP 集成

部署架构

开发环境

生产环境

性能优化

优缺点分析

优点

缺点

与竞品对比

参考资源

1. Happy CLI (`happy-coder`)