一、Lunel 是什么？（用一个小故事带你入门）
小明是一个程序员，某天晚上躺在床上，突然灵光一闪想到了一个绝妙的代码优化方案。但他身边只有手机，笔记本电脑还在书房的书桌上。他懒得爬起来，心想：“要是能用手机直接操作电脑上的代码，甚至让 AI 帮我改代码，那该多好啊！”
这时候，Lunel 出现了。
Lunel 就是一个让你用手机（或平板）随时随地操控电脑进行 AI 编程的神器。 官方描述是：“AI-powered mobile IDE and cloud development platform”，翻译成人话就是：用手机写代码，在电脑或云端运行。
Lunel 的设计哲学非常巧妙，它把手机变成一个“显示器和触摸屏”，而电脑负责所有“真正的计算和存储”。手机只管展示界面、接收你的点击和输入，所有的文件读写、Git 操作、终端命令，甚至 AI 对话背后的推理工作，全都在你的电脑上完成。
二、核心组件——拆开 Lunel 看看里面有什么
| 组件 | 技术栈 | 一句话功能 |
|---|---|---|
| App（移动端） | Expo / React Native | “门面担当”——负责显示界面、接收用户操作 |
| CLI（命令行工具） | Node.js | “苦力担当”——执行所有真实操作（文件、Git、终端） |
| Proxy（中继服务器） | Bun + WebSocket | “信使担当”——在手机和电脑之间传递消息 |
| PTY（伪终端） | Rust（基于 wezterm） | “终端专家”——模拟终端，渲染字符网格 |
1️⃣ App：智能手机上的“指挥中心”
App 是一个“哑客户端”（dumb client），意思是它自己不做任何实际工作，只负责把操作指令发送出去，然后接收结果并漂亮地展示出来。它用 Expo + React Native 构建，支持 iOS、Android 和 Web。功能包括：
2️⃣ CLI：电脑上的“万能管家”
CLI 是运行在你电脑上的 Node.js 工具，可以通过 npx lunel-cli 一键启动。它是真正的“实干家”，负责：
- 文件系统操作（读文件、写文件、grep 搜索等）
- Git 命令（status、commit、push、pull 等）
- 终端操作（通过 PTY 模块）
- 进程管理
- 端口扫描
- 系统监控（CPU、内存、磁盘、电池）
当你在手机 App 上点击“读取文件”或“执行 git status”时，CLI 就是那个默默干活的人。
3️⃣ Proxy：跨网络的消息“快递员”
Proxy 是一个用 Bun 编写的 WebSocket 中继服务器，公开部署在 gateway.lunel.dev。它的核心作用是连接手机 App 和电脑 CLI，让它们即使身处不同网络也能顺利通信。
Proxy 的核心设计亮点：
- 双通道架构：Control Channel（控制通道）+ Data Channel（数据通道），控制指令和数据传输分开，互不干扰
- 会话管理：每个连接有一个 10 分钟有效期的 Session Code，超时自动清理
- QR 码配对：手机 App 扫码即可完成配对，无需手动输入 IP 和端口
4️⃣ PTY：终端的“渲染引擎”
PTY 是一个用 Rust 写的伪终端二进制文件，基于 wezterm 终端的内部库开发。它的核心能力是：
- 真正的 PTY 会话（模拟一个完整的 Linux/macOS 终端环境）
- 将屏幕内容表示为 Cell Grid（字符网格） ，每个格子包含：字符、前景色、背景色
- 24fps 渲染循环，但只有在内容变化时才发送更新——网络流量非常节省
- 通过 stdin/stdout 使用 JSON 行协议 与 CLI 通信
三、时序图：一次 AI 指令请求的完整旅程
下面用一个完整的时序图，展示你在手机上对 AI 说“帮我写一个排序函数”时，Lunel 内部是如何协同工作的：
text
手机 App 中继服务器(Proxy) 本地 CLI PTY模块 AI模型
| | | | |
| 1. 扫码配对建立WebSocket | | | |
|-------------------------->| | | |
| | 2. 转发配对请求 | | |
| |------------------------->| | |
| | | | |
| 3. 用户输入："帮我写一个快速排序函数" | | |
|-------------------------->| | | |
| | 4. 封装消息转发 | | |
| | {ns:"ai", action:"ask"} | | |
| |------------------------->| | |
| | | | |
| | | 5. 收集上下文 | |
| | | (文件结构+终端 | |
| | | 最后几行输出) | |
| | | | |
| | | 6. 调用AI模型API | |
| | |-------------------->| |
| | | (用户输入+上下文) | |
| | | | |
| | | 7. AI返回建议代码 | |
| | |<--------------------| |
| | | (quicksort函数) | |
| | | | |
| 9. 显示AI回复 | 8. 转发AI回复 | | |
|<--------------------------|<-------------------------| | |
| | | | |
| (如果AI返回了"运行命令"指令，则进入终端通道) | | |
| | | | |
| 10. 执行AI建议的命令 | | | |
| 例如:"python test.py" | | | |
|-------------------------->| | | |
| | 11. 封装消息转发 | | |
| | {ns:"pty", action:"input"} | | |
| |------------------------->| | |
| | | | |
| | | 12. 写入stdin | |
| | |-------------------->| |
| | | | |
| | | 13. 执行命令并渲染 | |
| | | 终端输出为Cell | |
| | | Grid | |
| | |<--------------------| |
| | | | |
| 15. 更新终端显示 | 14. 返回渲染结果 | | |
|<--------------------------|<-------------------------| | |
| | | | |
时序图关键节点说明
节点 1-2（配对建立） ：手机 App 扫描电脑 CLI 生成的二维码，通过 Proxy 中继服务器建立 WebSocket 长连接。二维码中包含 Session Code，Proxy 用这个 code 将手机和电脑配对起来。
节点 3-4（用户输入） ：你在手机 AI 面板输入问题，App 不直接发送原始文本，而是封装成标准化的 Message 对象。关键字段包括：
节点 5-7（AI 处理） ：CLI 接收到 ns:"ai" 的消息后，会做三件事：
- 收集上下文：自动读取当前项目的文件结构、终端最后几行的输出，让 AI 更了解你的项目状况
- 调用 AI API：使用配置的 API Key（Anthropic 或 OpenAI）发送请求
- 解析并执行工具调用：如果 AI 返回“修改文件”或“运行命令”的指令，CLI 会解析并真实执行
节点 8-9（返回结果） ：AI 回复通过 Proxy 原路返回给手机 App，显示在 AI 对话面板上。
节点 10-15（终端执行） ：如果 AI 建议运行某个命令，你的“确认”操作会通过 ns:"pty" 通道发往 CLI。CLI 将命令通过 stdin 写入 PTY 进程，PTY 在真实终端中执行命令，然后将输出渲染成 Cell Grid（字符网格），只发送变化的部分回手机。
四、工作原理——为什么说“手机做 UI，电脑做大脑”？
Lunel 最核心的设计思想是 “哑客户端 + 智能服务端” 的架构。
4.1 双通道架构
- Control Channel：传输控制类指令，如建立连接、心跳检测、会话管理
- Data Channel：传输实际数据，如终端渲染数据、文件内容、AI 对话内容
这种设计的好处是：即使数据通道传输大文件时卡顿，控制通道仍然可以正常收发指令，保证连接不会断开。
4.2 PTY 的高效渲染机制
传统远程终端会发送整个屏幕的图像或大量文本，网络开销很大。Lunel 的 PTY 模块采用更聪明的方式：
- 将屏幕内容抽象为 Cell Grid（字符网格），每个格子记录一个字符及其颜色
- 24fps 渲染循环，但只在内容变化时发送更新
- 通过 JSON 行协议 传输，而非二进制图像流
这意味着当你敲一个字母时，PTY 只发送那一个变化的格子，而不是整个屏幕。网络流量极小，即使在移动网络下也能流畅使用。
4.3 消息路由机制
当 CLI 接收到消息时，根据 ns 字段路由到不同的执行器：
ns: "pty"→ 交给 PTY 模块处理终端输入ns: "ai"→ 交给 AI 代理模块（如 OpenCode SDK），调用 AI 模型ns: "fs"→ 交给文件系统模块，执行文件读写ns: "git"→ 交给 Git 模块，执行版本控制命令
五、最佳用法——手把手教你用 Lunel
5.1 快速开始：Lunel Connect 模式
这是目前最成熟的使用方式，让你用手机远程操控本地电脑：
Step 1：在电脑上启动 CLI
bash
# 不需要安装，直接用 npx 运行
npx lunel-cli
运行后，CLI 会在终端显示一个二维码和 Session Code。
Step 2：手机安装 App
从 App Store（iOS）或 Google Play（Android）下载 Lunel App，或者直接访问 Web 版。
Step 3：扫码配对
打开 App，扫描电脑终端显示的二维码。App 会通过 Proxy 服务器（gateway.lunel.dev）与你的电脑 CLI 建立 WebSocket 连接。
Step 4：开始编码
配对成功后，你就可以在手机上：
- 浏览和编辑电脑上的代码文件
- 执行 Git 命令（commit、push、pull）
- 使用终端执行任何命令
- 在 AI 面板中与 Codex/OpenCode/Claude Code 对话
5.2 AI 编程的高级用法
Lunel 最强大的功能之一是 AI 编程集成。以 OpenCode 为例，CLI 会这样工作：
typescript
// CLI 内部使用 OpenCode SDK 启动本地 AI 服务器
import { createOpencodeServer } from "@opencode-ai/sdk";
// 在本地随机端口启动 OpenCode 服务器
const server = await createOpencodeServer();
// 创建 API 客户端，通过 SSE 监听 AI 响应
const client = server.getClient();
// 发送用户输入 + 上下文，AI 可以调用本地工具
const response = await client.ask({
prompt: userInput,
context: { files, terminalOutput }
});
关键特性：
- 上下文感知：CLI 自动读取当前文件结构和终端输出，AI 知道你正在做什么
- 工具调用：AI 可以直接返回“修改文件”或“运行命令”的指令，CLI 自动执行
- SSE 实时流式响应：AI 回复一个字一个字地显示在手机上，体验流畅
5.3 最佳实践建议
- 公网使用场景：Lunel 通过 Proxy 中继，支持公网访问。你在咖啡厅用手机控制家里的电脑完全可行，无需配置路由器端口转发。
- 移动网络优化：PTY 的增量渲染机制（只发送变化的 Cell Grid）天然适配移动网络，即使 4G/5G 网络也能流畅使用。
- 会话管理：每个会话有 10 分钟的 TTL（生存时间），超时后需要重新配对。如果你要长时间使用，注意保持活跃或提前准备重新配对。
- Lunel Cloud（即将推出） ：未来你甚至不需要自己的电脑，直接用 Lunel 提供的云虚拟机即可开始编码。
六、架构总览图
text
┌─────────────────────────────────────────────────────────────────────────────┐
│ Lunel 整体架构 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ WebSocket ┌──────────────┐ │
│ │ 手机 App │◄──────────────────►│ Proxy │ │
│ │ (React Native)│ (中继服务器) │ (Bun) │ │
│ │ │ │ │ │
│ │ - AI 面板 │ │ - 双通道 │ │
│ │ - 终端显示 │ │ - 会话管理 │ │
│ │ - 文件浏览 │ │ - QR 配对 │ │
│ └──────────────┘ └──────┬───────┘ │
│ │ │
│ │ WebSocket │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ 本地 CLI │ │
│ │ (Node.js) │ │
│ │ │ │
│ │ ┌────────────────┐ │ │
│ │ │ AI 代理模块 │ │ │
│ │ │ (OpenCode SDK) │ │ │
│ │ └───────┬────────┘ │ │
│ │ │ │ │
│ │ ┌───────▼────────┐ │ │
│ │ │ PTY 模块 │ │ │
│ │ │ (Rust) │ │ │
│ │ │ - Cell Grid │ │ │
│ │ │ - 增量渲染 │ │ │
│ │ └───────┬────────┘ │ │
│ │ │ │ │
│ │ ┌───────▼────────┐ │ │
│ │ │ 文件系统/Git │ │ │
│ │ └────────────────┘ │ │
│ └──────────────────────┘ │
│ │ │
│ │ 真实执行 │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ 你的本地电脑 │ │
│ │ (终端 / 文件系统) │ │
│ └──────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
七、总结
Lunel 是一个设计精妙的开源项目，核心思想可以概括为：把手机当作 UI，把电脑当作算力，用 WebSocket 连接两者，让 AI 编程触手可及。
它的价值在于：
- ✅ 随时随地编码：不需要带电脑，手机 + 网络就能操控你的开发环境
- ✅ AI 深度融合：Claude Code、OpenCode 等 AI 助手无缝集成，且能直接操作本地文件系统
- ✅ 技术栈优雅：React Native 做 UI，Node.js 做逻辑，Rust 做高性能终端渲染，Bun 做中继——各取所长
- ✅ 开源免费：MIT 协议，任何人都可以学习和贡献
对于想要在移动端体验 AI 编程的开发者来说，Lunel 提供了一个非常有趣的解决方案。正如它官网所说的：“Code on your phone, run on your machine.”——这就是 Lunel 带给我们的自由。
如果你想深入了解，可以直接访问 GitHub 仓库，项目虽新但已有 500+ stars，社区活跃，值得关注。
