使用 iTerm2 Python API 将 Pane 图标标题自动同步到 Tab 标题(sync_title 示例深度解析)
使用 iTerm2 Python API 将 Pane 图标标题自动同步到 Tab 标题(sync_title 示例深度解析)
导读
本文围绕 iTerm2 官方 Python API 示例脚本 sync_title 展开:当终端会话(Session/Pane)的"图标标题(icon title)"因 OSC 控制序列发生变化时,脚本会自动把该标题同步为所在 Tab 的标题。文中不仅完整还原示例代码的每一步实现,还会结合本仓库 Python 库源码(variables.py、lifecycle.py、tab.py)讲解 VariableMonitor、EachSessionOnceMonitor 等核心类的工作机制,并说明"用户变量 + 插值字符串"这一安全模式的必要性。读完本文,你将能独立理解、运行并改写该脚本,实现自己的标题/变量同步逻辑。
示例文档原文位于 api/library/python/iterm2/docs/examples/sync_title.rst,对应可下载脚本为
sync_title.its(同目录下),本文所有代码均以仓库内实现为准。
一、背景:iTerm2 的图标标题(Icon Title)与 Tab 标题
1.1 终端标题的两层结构
在 iTerm2 中,标题分为两层:
-
Icon Title(图标标题):通常由应用程序通过控制序列设置,用于在 Tab 上显示简短标题。例如在 bash 中执行:
printf "\e]1;Hello world\a"这条命令发送 OSC 1 控制序列(
ESC ] 1 ; title BEL),把当前 Pane 的图标标题修改为Hello world。 -
Window Title(窗口标题):由 OSC 0 控制序列(
ESC ] 0 ; title BEL)设置,同时影响窗口标题栏与图标标题。也就是说printf "\e]0;Hello world\a"会同时改变图标标题和窗口标题。
iTerm2 将这两者分别作为会话变量暴露给脚本层,与本文直接相关的是 terminalIconName(会话作用域),此外还有 terminalWindowName 等变量(可参考 variables.rst 中的会话变量清单)。
1.2 默认行为:Tab 显示当前 Pane 的图标标题
一个 Tab 中可以存在多个 Pane(分屏),每个 Pane 各自维护自己的图标标题,因此同一 Tab 内可能同时存在多个不同的图标标题。默认情况下:
- Tab 上显示的是当前活动 Pane 的图标标题;
- 当切换活动 Pane 时,Tab 标题会随之切换为对应 Pane 的标题。
从脚本的角度看,会话(Session)才持有图标标题,而 Tab 本身并没有"自动跟随所有 Pane 更新"的机制——这正是本示例脚本要解决的问题。
二、脚本目标与整体思路
sync_title 脚本实现的核心语义是:
把"最后被更新的那个 Pane 的图标标题"复制到所在 Tab 的标题上,使 OSC 1(以及 OSC 0)控制序列在修改 Pane 图标标题的同时,也让 Tab 标题发生同样的变化。
整体流程分三步:
- 获取 App 对象:通过
iterm2.async_get_app(connection)拿到全局应用快照,后续用app.get_session_by_id(...)按 ID 查会话。 - 监听每个会话的图标标题变化:对每一个会话(含未来新建的会话),使用
VariableMonitor订阅会话作用域的terminalIconName变量,一旦变化就进入更新流程。 - 更新 Tab 标题:把新值先写入 Tab 的用户变量
user.title,再通过async_set_title("\\(user.title)")让 Tab 标题渲染该变量的值。
为什么不能直接把标题写进 Tab? 关键点在于 async_set_title 接收的是"插值字符串(interpolated string)"——它会在 iTerm2 端被当作模板求值。如果把来自会话的原始文本直接拼接进插值字符串,等于把终端输出内容当成了可执行模板,存在被注入控制逻辑的风险。因此安全做法是:先把原始值存入用户变量(用户变量只是纯数据,不做任何计算),再让 Tab 标题通过 \(user.title) 引用它。这是本示例最重要的安全设计,下文第 5 节会结合源码详细展开。
三、完整代码与逐行拆解
以下代码即 sync_title.its 的完整内容(与 sync_title.rst 中展示的代码块一致):
#!/usr/bin/env python3.7
import asyncio
import iterm2
async def main(connection):
app = await iterm2.async_get_app(connection)
async def watch_title(session_id):
session = app.get_session_by_id(session_id)
# When the session's "icon name" changes, update the tab title.
# The icon name is set with OSC 0 and OSC 1.
# e.g., ESC 0 ; title BEL
async with iterm2.VariableMonitor(
connection,
iterm2.VariableScopes.SESSION,
"terminalIconName",
session_id) as mon:
while True:
new_value = await mon.async_get()
# Note: it's unsafe to pass input from the session to async_set_title
# because it's an interpolated string. Instead, set a user variable
# (which can't do any computation) and then make the tab title
# show its contents.
await session.tab.async_set_variable("user.title", new_value)
await session.tab.async_set_title("\\(user.title)")
# Make every session monitor its title.
async with iterm2.EachSessionOnceMonitor(app) as mon:
while True:
session_id = await mon.async_get()
coro = watch_title(session_id)
asyncio.create_task(coro)
iterm2.run_until_complete(main)
3.1 运行入口与连接
iterm2.run_until_complete(main)
这是所有 iTerm2 Python 脚本的统一入口:它会建立与 iTerm2 的 WebSocket 连接,并把连接对象传给 main(connection)。脚本以 #!/usr/bin/env python3.7 开头,可执行权限配合 shebang 可直接运行;通过 iTerm2 的 Scripts 菜单导入 .its 脚本后,iTerm2 会为脚本自动配置好 Python 运行时环境。
3.2 获取应用快照
app = await iterm2.async_get_app(connection)
App 对象保存了当前窗口、Tab、会话的完整树结构,脚本后续用它查询会话:
session = app.get_session_by_id(session_id)
3.3 定义监听协程 watch_title
watch_title(session_id) 负责单个会话的标题同步,是脚本的核心单元:
async def watch_title(session_id):
session = app.get_session_by_id(session_id)
async with iterm2.VariableMonitor(...) as mon:
while True:
new_value = await mon.async_get()
await session.tab.async_set_variable("user.title", new_value)
await session.tab.async_set_title("\\(user.title)")
它内部是一个"订阅 → 无限等待 → 更新"的循环:mon.async_get() 会阻塞直到 terminalIconName 变量发生变化,每次变化都会触发一次 Tab 标题更新。
3.4 覆盖所有会话:EachSessionOnceMonitor
async with iterm2.EachSessionOnceMonitor(app) as mon:
while True:
session_id = await mon.async_get()
coro = watch_title(session_id)
asyncio.create_task(coro)
EachSessionOnceMonitor 保证当前已存在以及未来新建的每个会话都恰好触发一次 watch_title。拿到 session_id 后,脚本用 asyncio.create_task 为每个会话创建独立的监听任务,任务各自长期运行互不阻塞,即使某个会话结束时也不影响其他会话的监听。
补充:如果想让任务随会话结束自动清理,Python 库还提供了等价的静态方法
iterm2.EachSessionOnceMonitor.async_foreach_session_create_task(app, task),它会为每个会话创建任务并在会话终止时取消该任务(见 lifecycle.py 中的示例)。原脚本选择手写create_task的写法,语义更直观。
四、核心机制一:VariableMonitor 如何感知标题变化
VariableMonitor 定义在 api/library/python/iterm2/iterm2/variables.py,是一个异步上下文管理器,职责是"监听某个 iTerm2 变量在某个作用域内的变化"。
4.1 构造参数
| 参数 | 含义 | 本例取值 |
|---|---|---|
connection |
与 iTerm2 建立的连接对象 | connection |
scope |
变量求值的作用域,见 VariableScopes 枚举 |
iterm2.VariableScopes.SESSION(会话作用域) |
name |
要监听的变量名 | "terminalIconName" |
identifier |
对应作用域内的对象标识符(会话/标签/窗口 ID) | session_id |
VariableScopes 枚举(variables.py)提供四种作用域:
SESSION:会话作用域,本示例使用;TAB:标签作用域;WINDOW:窗口作用域;APP:整个应用作用域。
其中 identifier 必须与 scope 匹配:当作用域是 APP 时应传 None;当作用域是 SESSION 或 WINDOW 时还可以传 "all" 或 "active" 来一次性覆盖全部或当前对象。
4.2 底层工作机制
VariableMonitor 的订阅/取消订阅逻辑如下:
- 进入上下文(
__aenter__)时,调用iterm2.notifications.async_subscribe_to_variable_change_notification(connection, callback, scope, name, identifier)向 iTerm2 注册变量变更通知,并把回调收到的消息推入内部的asyncio.Queue; async_get()从队列中取出下一条变更消息,解析其中的json_new_value字段并返回实际值(通过json.loads反序列化);- 退出上下文(
__aexit__)时,通过async_unsubscribe注销订阅,实现资源自动释放。
因此 while True: new_value = await mon.async_get() 就是一个可靠的"等待下一次变化"原语:只有当 terminalIconName 真正改变时 async_get 才会返回。
4.3 与 OSC 控制序列的对应关系
会话作用域的 terminalIconName 变量正是 OSC 1 序列(\e]1;...\a)写入的"图标标题",而 OSC 0 序列(\e]0;...\a)会同时写图标标题与窗口标题,因此它也会触发 terminalIconName 的变化。文档原文明确指出:
printf "\e]0;Hello world\a"同时改变图标标题和窗口标题,本脚本同样能捕获该控制序列带来的图标标题变化。
也就是说,脚本对 OSC 0 与 OSC 1 产生的标题更新都有效。
五、核心机制二:为什么必须走"用户变量 + 插值"这条安全路径
5.1 async_set_title 的插值字符串语义
Tab.async_set_title 实现在 api/library/python/iterm2/iterm2/tab.py:
async def async_set_title(self, title: str):
"""Changes the tab's title.
This is equivalent to editing the tab's title with the menu item Edit
Tab Title. The title is an interpolated string.
...
"""
invocation = iterm2.util.invocation_string(
"iterm2.set_title",
[self.__tab_id, title],
[self.connection])
从源码注释可以确认两点:
- 该操作等价于菜单中的 Edit Tab Title;
- title 参数是插值字符串(interpolated string),会在 iTerm2 端被解析求值——例如
\(user.foo)会被替换为user.foo变量的当前值,还可能执行更复杂的表达式。
5.2 安全隐患与正确姿势
如果直接把会话传入的原始文本塞进插值字符串,例如:
# 危险写法(仅示意,切勿照做)
await session.tab.async_set_title(f"\(session.terminalIconName)")
当 terminalIconName 的值本身是终端输出的任意字符串时,它可能包含会被 iTerm2 当作表达式解释的内容,产生意料之外的计算甚至注入行为。示例代码中的注释明确告诫:
It's unsafe to pass input from the session to async_set_title because it's an interpolated string. Instead, set a user variable (which can't do any computation) and then make the tab title show its contents.
正确的两步走:
await session.tab.async_set_variable("user.title", new_value) # ① 存入用户变量
await session.tab.async_set_title("\\(user.title)") # ② 标题引用该变量
5.3 async_set_variable 的约束
Tab.async_set_variable(tab.py)通过 RPC async_variable 把变量写入指定 Tab 作用域。其文档明确要求:变量名必须以 user. 开头,否则调用会失败;变量值则是任意的 JSON 可序列化数据。因为用户变量只存储纯数据、不做任何表达式求值,所以它是跨会话输入与标题模板之间的安全隔离层。
同理,本脚本使用的 session.tab 属性直接由会话对象回溯到其所属 Tab,无需额外查找。
六、运行与验证
6.1 运行方式
- 在 iTerm2 菜单栏选择 Scripts → Manage → New Python Script,按向导创建脚本(环境会自动准备好 Python 运行时);
- 将本文代码保存为脚本(或直接导入仓库中提供的
sync_title.its); - 通过 Scripts 菜单运行该脚本;
- 脚本运行后即开始监听,无需额外配置。
6.2 验证步骤
在任意已打开或新建的会话中执行:
printf "\e]1;Hello world\a"
- 该 Pane 的图标标题变为
Hello world; - 由于脚本捕获了
terminalIconName的变化,所在 Tab 的标题也会变为Hello world。
再尝试同时修改两层标题:
printf "\e]0;Window and Icon\a"
- 图标标题与窗口标题同时变为
Window and Icon; - 脚本同样会把该值同步到 Tab 标题。
由于脚本使用了 EachSessionOnceMonitor,在脚本运行期间新建的会话也会自动被监听,不需要重启脚本。
6.3 实验对比:关掉脚本后的默认行为
停止脚本后,Tab 标题恢复默认策略:只显示当前活动 Pane 的图标标题,切换活动 Pane 时标题随之切换。这正是该脚本存在的意义——它把"最近更新的 Pane"的标题固定同步到 Tab,与默认的"跟随当前 Pane"策略形成对比。
七、扩展思路:复用同一套监听模式的变体
理解了 VariableMonitor + EachSessionOnceMonitor 的组合后,可以轻松改写脚本实现多种标题/变量同步需求,仅需替换监听的变量名与更新目标:
| 需求 | 监听变量(SESSION 作用域) | 更新目标 |
|---|---|---|
| 同步图标标题到 Tab(本文) | terminalIconName |
Tab 标题 |
| 同步窗口标题相关变化 | terminalWindowName 等窗口类变量 |
Window 标题 |
| 同步当前工作目录到 Tab | path |
Tab 用户变量 + 标题 |
监听 jobName 变化做自定义动作 |
jobName |
任意动作(如状态栏组件刷新) |
所有变体共享同一骨架:外层用 EachSessionOnceMonitor 枚举全部会话并为每个会话 create_task,内层用 VariableMonitor 无限等待目标变量变化,最后通过"用户变量 + 插值引用"安全地影响标题等 UI 元素。
关于会话作用域可用变量的完整清单,可参考 variables.rst;Tab 对象的能力(标题、变量、关闭、布局等)见 tab.rst。
八、小结
sync_title 示例虽短,却浓缩了 iTerm2 Python API 的四个关键知识点:
- 标题体系:OSC 1 只改图标标题,OSC 0 同时改图标与窗口标题,二者都会驱动
terminalIconName变化; - 监听机制:
VariableMonitor(SESSION作用域)以异步队列方式订阅变量变更,async_get()即"等待下一次变化"; - 全覆盖枚举:
EachSessionOnceMonitor保证现存与未来的每个会话都只被处理一次; - 安全边界:
async_set_title接受插值字符串,来自会话的文本必须先存入user.前缀的用户变量,再以\(user.title)引用,避免模板注入。
把这套"枚举会话 → 监听变量 → 安全写标题"的流程内化之后,你就能举一反三地写出各种基于 iTerm2 变量的自动化脚本,实现标题同步、状态联动、会话行为定制等个性化功能。
关键参考文件
- 示例文档:api/library/python/iterm2/docs/examples/sync_title.rst
- 可下载脚本:
api/library/python/iterm2/docs/examples/sync_title.its - 变量监听实现:api/library/python/iterm2/iterm2/variables.py
- 会话枚举实现:api/library/python/iterm2/iterm2/lifecycle.py
- Tab 标题/变量 API:api/library/python/iterm2/iterm2/tab.py
- 变量参考文档:api/library/python/iterm2/docs/variables.rst