Mr. Mak Workspace 架构深度解析:Tauri 2 + Node 本地服务如何驱动真实 PTY 终端
Mr. Mak Workspace 架构深度解析:Tauri 2 + Node 本地服务如何驱动真实 PTY 终端
Mr. Mak Workspace 是一个面向 Codex、Claude Code 等 CLI Agent 的本地桌面工作区,它的核心架构可以用一句话概括:Tauri 2 负责窗口与系统能力,Node 本地服务负责会话与业务逻辑,node-pty 负责驱动真实的 PTY 终端。下面带你从外到内逐层拆解这套架构,看完你会明白一个"网页窗口里的终端"为什么和真正的终端一模一样。
🏗️ 全景图:壳、服务、终端三层结构
整个桌面端由三层组成,职责清晰、边界明确:
| 层 | 位置 | 职责 |
|---|---|---|
| 系统壳 | src-tauri/src/ | Tauri 2 窗口管理、进程生命周期、系统快捷键、原生拖放 |
| 本地服务 | desktop/service/ | HTTP + WebSocket API、PTY 会话、历史恢复、文件操作 |
| 前端渲染 | src/desktop/ | React 界面、xterm.js 终端渲染、输入回传 |
官方架构说明见 desktop/README.md,其中一张表就把各目录职责讲清楚了。
🪟 Tauri 2 壳层:本地 Node 服务是如何被拉起的
入口是 src-tauri/src/main.rs。应用启动时做三件关键的事:
1. 拉起 Node 服务进程。 壳程序用 Command 直接 spawn 一个 Node 进程运行 desktop/service/main.mjs,并注入父进程 PID(见 main.rs#L407 的 MRMAK_PARENT_PID)。发布包自带打包好的 Node 运行时,所以用户机器上不需要单独安装 Node。
2. 用标准输入/输出建立私有管道。 服务启动后在 stdout 打印一行 JSON:{ type: "ready", workspace: <url>, chats: <url> }(见 main.mjs#L14-L18)。壳程序逐行读取这条消息,拿到两个带鉴权 token 的本地 URL 后,才创建 Workspace 和 Chats 两个窗口(main.rs#L430-L439)。窗口凭据只走这条私有管道传递,绝不落盘。
3. 进程保护,绝不留孤儿。 Windows 上把服务放进 Job Object 并开启 JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE(main.rs#L33-L47),应用一退出,服务及其所有子终端进程被操作系统整体回收;Node 侧也每 2 秒检查父进程是否存活,父进程消失就自行优雅退出(main.mjs#L26-L29)。双重保险,保证关闭应用后不会残留任何 agent 或 MCP 进程。
🌐 Node 本地服务:只监听 127.0.0.1 的"本地后端"
服务的核心是 desktop/service/server.mjs,它其实是两个 HTTP 服务器 + 一个 WebSocket 升级处理器:
- UI 服务器:绑定在
127.0.0.1的随机端口上(server.listen(0, '127.0.0.1'),见 server.mjs#L38),从磁盘直接提供构建好的前端页面; - API 鉴权:所有
/api/*请求都要求Authorization: Bearer <token>,token 是服务启动时随机生成的短期凭据(server.mjs#L489); - 实时推送:前端通过
/events建立 WebSocket,先发送{ type: "auth", token }完成鉴权,之后终端输出、会话状态、系统通知全部走这条长连接推送(server.mjs#L452-L483)。
这种设计让浏览器窗口天然具备"多端共享"能力——桌面、手机(通过 Tailscale 配对)访问的是同一个本地服务,会话状态完全同步。
💻 PTY 核心:真实终端是如何诞生的
这是整个架构最有意思的部分,核心代码在 desktop/service/sessions.mjs:
1. node-pty 启动真实进程。 每次新建会话,服务用 pty.spawn(command.file, command.args, ptyOptions(...))(sessions.mjs#L185)启动你电脑上真实安装的 CLI——Codex、Claude Code、Antigravity、OpenCode 或系统 Shell。每个 agent 的启动参数由 agents.mjs 组装,例如 Codex 会带上 --no-alt-screen 保留回滚区、检测版本后追加 --no-daemon(agents.mjs#L101-L111)。Windows 上则启用 ConPTY(platform.mjs#L71-L75),保证行为与 Linux/macOS 一致。
2. 服务端的"隐形终端"。 服务进程内部还维护一个 @xterm/headless 无头终端(sessions.mjs#L75,3000 行 scrollback),所有 PTY 输出先写入它。这个无头终端有三个用途:
- 屏幕持久化:每 3 秒把终端画面序列化保存到
.mrmak/screen-<id>.json(sessions.mjs#L601-L624),下次重启应用时整屏原样恢复; - 屏幕快照:客户端订阅时先发送
serialize({ scrollback: 1500 })的全屏快照(sessions.mjs#L367),再续传增量,保证切标签页或断线重连后画面无缝衔接; - 读屏能力:服务可以像人一样"看"终端最后 N 行,这是实现"点击回答权限菜单"的基础。
3. 16ms 批量输出,防止刷屏。 PTY 的原始输出先累积,每隔约 16ms(一帧)批量 flushOutput 一次并通过 WebSocket 广播给前端(sessions.mjs#L196-L201),每条输出带递增 sequence 序号,前端据此丢帧补传,避免高输出量的终端冲垮 UI。
🖥️ 前端渲染:xterm.js 如何还原屏幕
前端渲染器是 src/desktop/TerminalPane.tsx,它做的事情和上面的服务端正好镜像:
- 连接 WebSocket 后发送
{ type: "subscribe", id }; - 收到
snapshot事件:terminal.reset()后一次性写入全屏快照; - 之后的
output事件按sequence递增逐段terminal.write()追加; - 键盘输入通过
terminal.onData回传{ type: "input", id, data },写回 PTY。
配合 FitAddon 自动测量像素算出行列数、ResizeObserver 触发 { type: "resize" }(TerminalPane.tsx#L140-L170),窗口一缩放,服务端同步 proc.resize(cols, rows),CLI 全屏渲染随之重排——这就是它和"网页模拟终端"的本质区别:屏幕状态由真实进程持有,窗口只是显示器。
🎯 三个让"读屏"变得可靠的设计细节
- 权限菜单可点击回答:terminal-prompt.mjs 用正则识别终端底部的编号菜单,为整个可见区域生成 SHA-256 指纹;提交答案前重新读屏校验指纹,再逐键发送方向键和 Enter(terminal-prompt.mjs#L70-L99),防止迟到的点击答错新弹出的问题。
- 干净的子进程环境:agents.mjs#L140-L153 启动 PTY 前会剥离
CLAUDECODE、CODEX_THREAD_ID等宿主 agent 的身份变量,让每个终端里的 CLI 都是独立的会话,而不是嵌套在某个 agent 之下。 - macOS 登录环境:从 Dock/Finder 启动的 App 拿不到用户的 shell 环境,壳程序通过登录 shell 发现真实
PATH再注入给服务(main.rs#L273-L290),保证codex、claude等命令都能被找到。
📂 关键文件速查
| 想了解的模块 | 从这里看起 |
|---|---|
| Tauri 窗口与进程生命周期 | src-tauri/src/main.rs |
| 服务入口与父子进程守护 | desktop/service/main.mjs |
| HTTP API 与 WebSocket 推送 | desktop/service/server.mjs |
| PTY 会话、快照与恢复 | desktop/service/sessions.mjs |
| 各 Agent 启动参数 | desktop/service/agents.mjs |
| ConPTY 与跨平台差异 | desktop/service/platform.mjs |
| 终端前端渲染 | src/desktop/TerminalPane.tsx |
| 前端状态与 WebSocket 客户端 | src/desktop/client.ts |
| 架构总览文档 | desktop/README.md |
🧭 小结
Mr. Mak Workspace 的架构思路值得借鉴:Tauri 2 只做"系统管家",Node 服务承载全部业务,PTY 保证终端的真实性;三层之间用环回地址 + 随机 token + 私有管道通信,安全边界清晰;服务端无头 xterm 既做持久化又做读屏,让"AI 看懂终端"成为可能。理解了这套结构,你再去读 desktop/ 目录下的任何模块都会胸有成竹。


