iTerm2 —— macOS 终端仿真器 系统分析

iTerm2 是 George Nachman 开发的 macOS 平台开源终端仿真器（Terminal Emulator），项目托管于 github.com/gnachman/iTerm2，以 GPLv3 协议发布。截至最新版本 3.6，拥有 17.9k+ Stars 和 1.4k+ Forks，16,911+ 次提交，是 macOS 平台上功能最丰富的终端仿真器。

1. 终端仿真器的定位：GUI 桌面 vs 纯服务器

要理解 iTerm2 的价值，首先需要理清 "终端仿真器" 在整个计算生态中的位置——它本质上是 GUI 桌面操作系统 的产物，纯服务器环境不需要它。

1.1 两种完全不同的交互模型

1.2 远程连接场景：你的终端仿真器在哪里？

日常工作中最常见的场景是：

你 → iTerm2 (macOS GUI) → SSH → CentOS 服务器 (纯 CLI)

也就是说：终端仿真器永远运行在"有人坐在屏幕前"的那台机器上。它负责把字符渲染成像素、把按键转成字节。服务器端从不下这个活——它们的"显示"就是 SSHD 把字节流扔回网络，由你本地的终端仿真器来渲染。

1.3 iTerm2 在完整链路中的位置

1.4 终端的历史演变

第一部分：行为图 —— 系统"做什么"

1.1 用例图（Use Case Diagram）

从外部参与者的视角，描述 iTerm2 为不同角色提供的核心能力边界。

1.2 活动图（Activity Diagram） —— 核心工作流

描述用户启动 iTerm2 后从创建会话到输入输出的完整主流程。

1.3 时序图（Sequence Diagram） —— 会话创建与输入输出

展示一次完整的会话生命周期中，各组件间的消息交互顺序。

1.4 状态机图（State Machine Diagram） —— 会话生命周期

描述一个 PTYSession 从创建到销毁的完整状态变迁。

第二部分：结构图 —— 系统"由什么组成"

2.1 组件图（Component Diagram） —— 宏观架构

展示 iTerm2 系统的顶层组件划分及其依赖和数据流关系。

2.2 部署图（Deployment Diagram） —— 进程模型与沙箱架构

iTerm2 采用多进程架构以兼顾稳定性与沙箱安全。应用程序分为主 GUI 进程、沙箱化 Worker 进程、Python 脚本进程等多个运行时实体。

3. Python API 架构

iTerm2 提供一套完整的 Python 脚本 API，替代了已废弃的 AppleScript 接口。Python 脚本通过本地 WebSocket 与 iTerm2 进程通信，使用 Protocol Buffers 序列化消息，支持同步操作和常驻守护进程两种模式。

3.1 API 连接模型

3.2 Demo 代码示例

#!/usr/bin/env python3
# 示例1：简单脚本 —— 创建窗口并执行命令
import iterm2

async def main(connection):
    app = await iterm2.async_get_app(connection)
    window = await app.current_terminal_window
    if window is None:
        return
    # 在当前窗口创建新 Tab
    await window.async_create_tab()
    session = app.current_terminal_window.current_tab.current_session
    # 写入命令（不执行，仅发送文本）
    await session.async_send_text("echo 'Hello from Python API'\n")

iterm2.run_until_complete(main)

# 示例2：常驻守护 —— 监听键盘事件
# 放在 Scripts/AutoLaunch/ 下自动启动
import iterm2

async def monitor(connection):
    app = await iterm2.async_get_app(connection)
    async def on_keystroke(connection, notification):
        print(f"按键: {notification.characters}")
    await iterm2.notifications.async_subscribe_to_keystroke_notification(
        connection, on_keystroke)

iterm2.run_forever(monitor)

# 示例3：自定义状态栏组件
import iterm2

async def clock_sb(connection):
    component = iterm2.StatusBarComponent(
        short_description="Clock",
        detailed_description="Show current time",
        knobs=[],
        exemplar="12:00",
        update_cadence=1,
        identifier="com.example.clock"
    )
    @iterm2.StatusBarRPC
    async def clock_coro(knobs):
        import datetime
        return datetime.datetime.now().strftime("%H:%M:%S")
    await component.async_register(connection, clock_coro)

iterm2.run_forever(clock_sb)

4. 核心特性原理

4.1 Shell 集成原理

iTerm2 Shell Integration 的工作机制分为三步：

1. 注入脚本：安装时将 Shell 集成脚本（bash/zsh/fish）写入 `~/.iterm2_shell_integration.*`，在 `.zshrc`/`.bashrc` 中 source。
2. Prompt 标记：每次显示提示符时输出 proprietary escape sequence OSC 1337;RemoteHost=... ST 和 OSC 1337;CurrentDir=... ST，让 iTerm2 知道主机名和当前目录。
3. 命令边界：命令执行前输出 OSC 133;C ST，执行完毕后输出 OSC 133;D ST，这样 iTerm2 就能划分"上一个命令的输出"和"下一个提示符"之间的边界，实现按命令跳转（Cmd+Shift+上/下）。

# ~/.iterm2_shell_integration.zsh 核心逻辑（简化）
iterm2_before_prompt() {
  printf "\033]1337;RemoteHost=%s@%s\007" "$USER" "$(hostname -f)"
  printf "\033]1337;CurrentDir=%s\007" "$PWD"
}
iterm2_preexec() {
  printf "\033]133;C\007"
}
iterm2_precmd() {
  printf "\033]133;D;%s\007" "$?"
  iterm2_before_prompt
}
preexec_functions+=(iterm2_preexec)
precmd_functions+=(iterm2_precmd)

4.2 tmux 集成原理

tmux 的 -CC 参数进入 Control Mode，此时 tmux 不输出格式化的 TUI 界面，而是通过 stdout 发送结构化控制序列（如 %output %1 hello、%window-add @2），通过 stdin 接收 iTerm2 的命令（如 new-window -t @2）。iTerm2 的 TmuxController 解析这些序列，将 tmux 的虚拟窗口一对一映射为原生 NSWindow。

# 基本用法
tmux -CC                        # 新建 tmux 会话，iTerm2 接管窗口
tmux -CC attach                 # 重新连接到已有会话
# 在 iTerm2 中，Cmd+D 分屏 = tmux split-window
# Cmd+W 关窗 = tmux kill-window

4.3 即时回放（Instant Replay）原理

iTerm2 在内存中维护一个环形缓冲区（默认 4MB），每次屏幕状态变更时（VT100Parser 解析后），将完整屏幕的 差分快照 或全量快照追加到此缓冲区。用户进入回放模式时，PTYTextView 不再渲染实时输出，而是根据时间轴从缓冲区读取历史帧进行渲染。

4.4 内联图像（Inline Images）原理

通过 proprietary escape sequence OSC 1337;File=... ST 将 Base64 编码的图像数据传输到终端。VT100Parser 解析后，将图像数据解码并存储，PTYTextView 在渲染时将此区域替换为图像纹理（支持 animated GIF）。

# 使用 imgcat 显示图片（需安装 Shell Integration Utilities）
imgcat photo.jpg
# 等价于：
printf '\033]1337;File=name=...;size=%d;inline=1:%s\a' "$(wc -c < photo.jpg)" "$(base64 < photo.jpg)"

5. 数据流全链路

以下描述一次完整的终端 I/O 数据流从用户按键到屏幕渲染的全链路。

6. 实战速查手册

6.1 快捷键速查

6.2 Profile 配置要点

6.3 Shell Integration 安装

# 方法1：通过菜单安装（推荐）
# iTerm2 → Install Shell Integration

# 方法2：手动安装 zsh
curl -L https://iterm2.com/shell_integration/zsh \
  -o ~/.iterm2_shell_integration.zsh
echo 'test -e "${HOME}/.iterm2_shell_integration.zsh" && source "${HOME}/.iterm2_shell_integration.zsh"' >> ~/.zshrc

# 方法3：远程主机安装
curl -L https://iterm2.com/shell_integration/install_shell_integration_and_utilities.sh | bash

6.4 tmux 集成速查

6.5 Python 脚本开发速查

# 获取当前会话
app = await iterm2.async_get_app(connection)
win = app.current_terminal_window
session = win.current_tab.current_session

# 发送文本
await session.async_send_text("ls -la\n")

# 获取屏幕内容
screen = await session.async_get_screen_contents()
for line in screen:
    print(line.string)

# 创建窗口
new_win = await iterm2.Window.async_create(connection)

# 分屏
new_sess = await session.async_split_pane(vertical=True)

# 监听新会话
async def on_new(conn, notif):
    print("新会话创建")
await iterm2.notifications.async_subscribe_to_new_session_notification(conn, on_new)

# 运行命令并等待完成
prompt = await session.async_get_prompt()
await session.async_send_text("make build\n")
# 等待新提示符出现（命令执行完毕）
while True:
    await asyncio.sleep(1)
    p = await session.async_get_prompt()
    if p != prompt:
        break

6.6 进阶配置

{
  "Profiles": [{
    "Name": "My Dev Server",
    "Guid": "uuid-gen-here",
    "Command": "ssh dev.example.com",
    "Custom Directory": "Recycle",
    "Badge Text": "\\(user.host)",
    "Tags": ["dev", "ssh"],
    "Transparency": 0.1,
    "Background Color": { "Red": 0, "Green": 0, "Blue": 0.1 }
  }]
}

# 在 Profile → Advanced → Automatic Profile Switching 中配置规则
# 规则示例：Hostname = *.prod.example.com → 切换到 "Production" Profile
# 规则示例：Username = root → 切换到 "Root User" Profile