Mr. Mak Workspace 架构深度解析:Tauri 2 + Node 本地服务如何驱动真实 PTY 终端

原创2026-11-05 03:27:002,500 阅读

Mr. Mak Workspace 架构深度解析:Tauri 2 + Node 本地服务如何驱动真实 PTY 终端

Mr. Mak Workspace 是一个面向 Codex、Claude Code 等 CLI Agent 的本地桌面工作区,它的核心架构可以用一句话概括:Tauri 2 负责窗口与系统能力,Node 本地服务负责会话与业务逻辑,node-pty 负责驱动真实的 PTY 终端。下面带你从外到内逐层拆解这套架构,看完你会明白一个"网页窗口里的终端"为什么和真正的终端一模一样。

Mr. Mak Workspace 双窗口架构:左侧 Chats 窗口运行真实 PTY 终端会话,右侧 Workspace 窗口展示项目报告

🏗️ 全景图:壳、服务、终端三层结构

整个桌面端由三层组成,职责清晰、边界明确:

层 位置 职责
系统壳 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,它做的事情和上面的服务端正好镜像:

  1. 连接 WebSocket 后发送 { type: "subscribe", id };
  2. 收到 snapshot 事件:terminal.reset() 后一次性写入全屏快照;
  3. 之后的 output 事件按 sequence 递增逐段 terminal.write() 追加;
  4. 键盘输入通过 terminal.onData 回传 { type: "input", id, data },写回 PTY。

配合 FitAddon 自动测量像素算出行列数、ResizeObserver 触发 { type: "resize" }(TerminalPane.tsx#L140-L170),窗口一缩放,服务端同步 proc.resize(cols, rows),CLI 全屏渲染随之重排——这就是它和"网页模拟终端"的本质区别:屏幕状态由真实进程持有,窗口只是显示器。

Mr. Mak Workspace 的 Conversation 视图:终端会话被解析为对话消息,终端与对话视图可一键切换

🎯 三个让"读屏"变得可靠的设计细节

  • 权限菜单可点击回答:terminal-prompt.mjs 用正则识别终端底部的编号菜单,为整个可见区域生成 SHA-256 指纹;提交答案前重新读屏校验指纹,再逐键发送方向键和 Enter(terminal-prompt.mjs#L70-L99),防止迟到的点击答错新弹出的问题。

Mr. Mak Workspace 终端权限菜单识别:Claude Code 的权限询问被解析为可点击按钮

  • 干净的子进程环境: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/ 目录下的任何模块都会胸有成竹。

登录后查看全文
mr-mak-workspace