第1课：HAPI的架构#

为什么需要这个#

在第一级课程中，你学会了启动和使用HAPI。现在让我们了解它的内部结构。这将帮助你理解"底层"发生了什么，更快地找到问题并按需配置系统。

四个核心组件#

HAPI由四个部分组成，像团队一样协同工作：

┌──────────────────────────────────────────────────┐
│            你的电脑                                │
│                                                  │
│   CLI ◄──────► Hub ◄──────► Web App              │
│  (代理)       (服务器)      (浏览器)              │
│                  │                               │
└──────────────────┼───────────────────────────────┘
                   │
              Relay (隧道)
                   │
              📱 手机

让我们逐一介绍。

1. CLI——AI代理的包装器#

CLI（Command Line Interface——命令行界面）是你在终端中通过 hapi 命令启动的程序。

它的功能：

启动AI代理（Claude Code、Codex、Gemini或OpenCode）——这就是编写代码的"智能助手"
连接Hub ——以便你可以远程管理会话
传递消息 ——在你和代理之间
发送权限请求 ——当代理想执行某些操作（例如编辑文件）时，它会先征求你的同意

启动示例：

hapi              # 使用Claude Code启动会话
hapi codex        # 使用OpenAI Codex启动会话
hapi gemini       # 使用Google Gemini启动会话

💡 简单类比： CLI就像汽车司机。它操控AI代理并与调度中心（Hub）通信。

2. Hub——中央服务器#

Hub（中心、节点）是HAPI的"调度室"。它在你的电脑上运行，协调所有其他部分。

它的功能：

存储数据 在SQLite数据库中（所有会话、消息、权限）
提供Web界面 ——你在浏览器中打开的那个页面
实时连接CLI和Web应用
发送通知 到Telegram

Hub的通信技术：

连接	技术	说明
Hub ↔ CLI	Socket.IO	实时双向通信（类似聊天）
Hub ↔ 浏览器	REST + SSE	REST——用于操作（发送消息），SSE——用于即时更新

REST 是程序通过互联网通信的方式（像发送信件）。SSE（Server-Sent Events）是服务器主动向浏览器推送更新的技术（像广播）。Socket.IO 是实时双向通信技术（像电话通话）。

启动Hub：

hapi hub           # 本地模式
hapi hub --relay   # 可通过互联网访问

3. Web App——浏览器界面#

Web App 是一个React应用（PWA），在手机或电脑的浏览器中打开。

PWA（Progressive Web App）是一种可以像普通应用一样"安装"到手机上的网站。即使没有持续的网络连接也能工作。

你可以在Web App中：

📋 查看会话列表 ——所有活跃和历史会话
💬 向代理发送消息 ——像普通聊天一样
✅ 批准或拒绝操作 ——当代理请求权限时
📁 浏览项目文件 ——查看代码中的更改
🚀 启动新会话 ——直接从手机

4. Relay——远程访问隧道#

Relay（中继器）是一项服务，允许你通过互联网连接到Hub，即使你的电脑在路由器或防火墙后面。

防火墙（firewall）是一道保护墙，阻止来自互联网的不需要的连接到你的电脑。NAT 是路由器中的一项技术，将你的电脑"隐藏"在外部世界之外。

当你运行 hapi hub --relay 时，会发生以下情况：

Hub连接到Relay服务器
Relay为你的Hub创建一个公共地址（URL）
你获得一个可以用手机扫描的QR码
手机通过Relay连接到Hub

加密：WireGuard + TLS#

HAPI非常重视安全性。通过Relay的所有流量都受到双重加密保护：

WireGuard 是一种VPN协议（在两个设备之间创建安全"隧道"的技术）。它加密数据，使得你和你的电脑之间没有人能读取它们。
TLS（Transport Layer Security）——与带"锁"图标的网站（https://）使用的相同加密类型。这是第二层保护。

💡 简单类比： 想象你在寄一封信。WireGuard是你把信放进去的保险箱。TLS是运输保险箱的装甲车。即使有人拦截了装甲车，他也无法接触到信的内容。

你的手机 → [TLS加密] → [WireGuard隧道] → Relay → 电脑上的Hub

所有部分如何协同工作#

场景：你从手机发送消息#

1. 你在手机上的Web App中写消息
         │
2. 消息通过Relay到达Hub
         │
3. Hub通过Socket.IO将消息传递给CLI
         │
4. CLI将消息传递给AI代理
         │
5. 代理处理请求并回复
         │
6. 回复原路返回：CLI → Hub → SSE → Web App
         │
7. 你在手机屏幕上看到回复

场景：代理请求权限#

1. AI代理想编辑文件
         │
2. CLI将权限请求发送到Hub
         │
3. Hub保存请求并通知你（SSE + Telegram）
         │
4. 你在手机上收到通知
         │
5. 你在Web App中点击"批准"
         │
6. Hub将决定传递给CLI → 代理继续工作

在本地和远程模式之间切换#

HAPI的核心"特色"之一是能够在终端和手机之间切换而不丢失会话。

方向	工作原理
终端 → 手机	从手机发送消息——终端自动进入等待模式
手机 → 终端	在终端中按双空格——立即恢复本地控制

这就像遥控器：你可以从沙发上控制同一台电视，也可以走到它面前操控。

课程总结#

CLI ——在你的电脑上启动和管理AI代理
Hub ——中央服务器，将所有部分连接在一起并存储数据
Web App ——浏览器界面，从任何设备管理
Relay ——通过互联网访问的安全隧道
流量受双重加密保护：WireGuard + TLS
你可以在终端和手机之间自由切换，不会丢失会话