企业官网建设流程全解析

• 桌面应用
• AI 应用

本文以 iTerm2 官方 Python API 文档中的示例脚本目录（api/library/python/iterm2/docs/examples/index.rst）为核心，系统梳理该仓库为开发者提供的全部示例脚本分类：会话标题提供器、自定义状态栏组件、Tmux 集成、事件监听、配色方案、窗口标签管理、键盘钩子、输入广播等。读完本文，你将掌握 iTerm2 脚本的安装路径、注册机制（run_forever/run_until_complete）、核心异步 API 用法，并能够直接参照源码级示例动手编写自己的自动化脚本。

一、示例脚本目录：一份按功能分类的"抄作业清单"

官方文档在examples/index.rst中这样定位这批脚本："Here are a collection of working scripts for you to crib from"——这是一批开箱即用的可运行脚本集合，虽然每个脚本按其主功能归类，但不少脚本同时演示了多种脚本特性。官方建议开发者直接在这份清单中搜索需求，或顺着各 API 文档中的See Also章节找到演示特定 API 的示例。

这份目录按主题分为 16 个大类、约 60 个脚本，可运行代码分散在同目录下的.its/.py文件中（如 statusbar.its、launch_and_run.py）。整体分类如下：

二、脚本的运行环境与两种生命周期模式

所有脚本都基于iterm2Python 库（即当前仓库 api/library/python/iterm2 所构建的包），并通过两种入口函数运行：

• iterm2.run_forever(main)：脚本常驻运行（daemon），适合状态栏组件、键盘监听这类需要持续响应的场景。文档特别说明，此类脚本应放入 AutoLaunch 文件夹，随 iTerm2 启动自动加载。
• iterm2.run_until_complete(main, keep_trying)：脚本执行完毕即退出，适合一次性操作（如创建窗口、执行命令）。第二个参数传True表示"持续尝试连接直到 iTerm2 启动完成"。

2.1 脚本安装位置

按照 launch_and_run.rst 的说明，从命令行运行脚本需要先安装依赖：

brew install python3 pip3 install iterm2 pip3 install pyobjc # 仅当脚本需要操作 macOS 应用层（如启动 iTerm2）时

长驻脚本则放置在~/Library/Application Support/iTerm2/Scripts/AutoLaunch目录下，启动后可通过Scripts > AutoLaunch > 脚本名手动触发，或重启 iTerm2 自动加载。

2.2 从命令行启动 iTerm2 并执行命令

launch_and_run是"Standalone Scripts"中最具代表性的一例，它同时演示了两件事：用 PyObjC 启动 iTerm2 应用，以及创建一个运行指定命令的新窗口：

#!/usr/bin/env python3 import iterm2 import AppKit # 1. 启动 App（适用于从命令行而非 iTerm2 内部运行脚本的场景） AppKit.NSWorkspace.sharedWorkspace().launchApplication_("iTerm2") async def main(connection): app = await iterm2.async_get_app(connection) # 2. 将应用置前 await app.async_activate() # 3. 通过 shell 启动 vi（经 bash -l 可继承 $PATH，无需写全路径） await iterm2.Window.async_create(connection, command="/bin/bash -l -c vi") # 4. 第二个参数 True：一直重试连接，直到 App 启动就绪 iterm2.run_until_complete(main, True)

关键点：Window.async_create(command=...)允许直接以命令创建新窗口；而run_until_complete(main, True)的第二个参数保证了"App 尚未启动时脚本不会因连接失败而崩溃"。

三、Session Title Providers：自定义会话标题

标题提供器（Title Provider）是 iTerm2 脚本化中应用面最广的功能之一，核心装饰器为iterm2.registration.TitleProviderRPC。

3.1 简单示例：把 Badge 写进 Tab 标题

badgetitle.rst 演示了"最简标题提供器"：将 Badge（徽标）名称拼入标签页标题。运行脚本后，在Prefs > Profiles > General > Title中选择Badge + Name即可生效：

@iterm2.TitleProviderRPC async def badge_title( badge=iterm2.Reference("badge?"), auto_name=iterm2.Reference("autoName?")): if badge and auto_name: return auto_name + u" \u2014 " + badge elif auto_name: return auto_name elif badge: return badge else: return "Shell" await badge_title.async_register(connection, "Name + Badge", "com.iterm2.example.name-and-badge")

同样的模式还衍生出"窗口标题同步到标签页"的变体windowtitle.its：当应用只设置窗口标题（terminalWindowName）而不设置标签标题时，把它也显示到标签上。

3.2 复杂示例：George's Title Algorithm（含 Git 分支）

georges_title.rst 是文档中标注为"复杂会话标题提供器"的旗舰示例，它把Shell Integration 用户变量与自定义标题函数组合起来，最终产出一个包含主机名、路径、Git 分支和图标的精美标题。

第一步：安装 Shell Integration 并在.bashrc中定义用户变量

function iterm2_print_user_vars() { iterm2_set_user_var gitBranch $((git branch 2> /dev/null) | grep \* | cut -c3-) iterm2_set_user_var home $(echo -n "$HOME") }

第二步：将脚本放入 AutoLaunch 目录并注册标题提供器

@iterm2.TitleProviderRPC async def georges_title( pwd=iterm2.Reference("path?"), hostname=iterm2.Reference("hostname?"), branch=iterm2.Reference("user.gitBranch?"), auto_name=iterm2.Reference("autoName?"), profile_name=iterm2.Reference("profileName?"), tmux_title=iterm2.Reference("tmuxWindowTitle?"), user_home=iterm2.Reference("user.home?")): if tmux_title: return tmux_title parts = [make_title(auto_name, profile_name), make_hostname(hostname, localhost), make_pwd(user_home, localhome, pwd), make_branch(branch)] return " ".join(list(filter(lambda x: x, parts))) await georges_title.async_register( connection, display_name="George's Title Algorithm", unique_identifier="com.iterm2.example.georges-title-algorithm")

第三步：在Prefs > Profiles > General > Title中选择George's Title Algorithm。

这个示例的关键知识点：

• iterm2.Reference("path?")的?后缀表示变量可选，当变量尚未定义（如新会话刚创建）时不会抛异常，这是文档反复强调的防御性写法；
• 标题的各组成部分由辅助函数make_title、make_hostname、make_pwd、make_branch分头生成，再过滤空值拼接，体现了"组合式标题构建"的工程化思路；
• 用户通过iterm2_set_user_var定义的变量以user.前缀在 Python 侧读取（如user.gitBranch），这正是 variables.rst 所描述的变量命名空间体系。

四、Status Bar Components：自定义状态栏组件

这是示例数量最多的类别（9 个），核心 API 是iterm2.StatusBarComponent+iterm2.StatusBarRPC。通用安装流程（以 statusbar.rst 为准）：启动脚本后，进入Preferences > Profiles > Session，打开Status Bar Enabled→ 点击Configure Status Bar，将组件拖入状态栏区域，选中后点击Configure Component即可调整配置项。

4.1 基础组件 + 配置旋钮（Knob）

statusbar示例演示了带可配置旋钮（knob）的变长文本组件：当开启 "Variable-Length Demo" 旋钮时，组件会根据可用宽度自动切换文本（从完整句子逐步缩短到 "It's getting tight"）；关闭时显示rows x cols尺寸：

import iterm2 async def main(connection): vl = "variable_length_demo" knobs = [iterm2.CheckboxKnob("Variable-Length Demo", False, vl)] component = iterm2.StatusBarComponent( short_description="Status Bar Demo", detailed_description="Tests script-provided status bar components", knobs=knobs, exemplar="row x cols", update_cadence=None, # None 表示仅在依赖变量变化时更新 identifier="com.iterm2.example.status-bar-demo") @iterm2.StatusBarRPC async def coro( knobs, rows=iterm2.Reference("rows"), cols=iterm2.Reference("columns")): if vl in knobs and knobs[vl]: return ["This is an example of variable-length status bar components", "This is a demo of variable-length status bar components", ..., "It's getting tight"] return "{}x{}".format(rows, cols) await component.async_register(connection, coro) iterm2.run_forever(main)

要点：

• knobs参数：CheckboxKnob("显示名", 默认值, 内部key)定义配置项，用户在图层面板修改后通过knobs[key]读取；
• 返回值列表即变长候选集：状态栏在空间不足时自动从列表中选择更短的文本，这是实现"自适应宽度"的标准手法；
• update_cadence：设为None表示由变量驱动更新；设为数字（秒）则周期刷新；
• 该脚本是长驻 daemon，官方明确要求放入 AutoLaunch 目录。

4.2 键盘监听 + 变量作为脚本内部通信通道

escindicator.rst 是文档中"含金量"最高的示例之一，演示了四件事：自定义状态栏组件、键盘监听、用用户变量作为脚本内部模块间的回程通道（back-channel）、以及 asyncio 任务调度与取消。

counter = 0 async def main(connection): app = await iterm2.async_get_app(connection) tasks = {} component = iterm2.StatusBarComponent( short_description="Esc Key Indicator", detailed_description="Shows a visual indicator when the esc key is pressed", knobs=[], exemplar="[esc]", update_cadence=None, identifier="com.iterm2.escindicator") async def reset(session): await asyncio.sleep(2) await session.async_set_variable("user.showEscIndicator", False) async def keystroke_handler(keystroke): if keystroke.keycode != iterm2.Keycode.ESCAPE: return try: session = app.current_terminal_window.current_tab.current_session except: return global counter counter += 1 # 值必须每次不同，才能触发变量变更通知 await session.async_set_variable("user.showEscIndicator", counter) @iterm2.StatusBarRPC async def coro( knobs, show_indicator=iterm2.Reference("user.showEscIndicator?"), session_id=iterm2.Reference("id")): if show_indicator: if session_id in tasks: tasks[session_id].cancel() del tasks[session_id] task = asyncio.create_task(reset(app.get_session_by_id(session_id))) tasks[session_id] = task return "[ESC]" else: return " " await component.async_register(connection, coro) async with iterm2.KeystrokeMonitor(connection) as mon: while True: keystroke = await mon.async_get() await keystroke_handler(keystroke) iterm2.run_forever(main)

值得注意的实现细节：

• 用户变量user.showEscIndicator是"键盘监听器"与"状态栏组件"之间的通信通道：键盘监听写入变量，StatusBarRPC仅在变量变化时被回调；
• 由于 RPC 只在值变化时触发，计数必须自增（counter += 1），否则快速连按时可能丢失更新；
• 通过tasks[session_id].cancel()实现"2 秒后自动熄灭"的延迟逻辑，并防止上一次的定时任务与新任务竞争；
• 变量名带?（user.showEscIndicator?）使其在未定义时安全返回None，这正是该示例最值得复用的防御模式。

4.3 点击处理 + Popover 网页视图

jsonpretty.rst 演示了支持点击的状态栏组件：选中终端中的 JSON 文本，点击组件即可弹出 600×600 的 popover，展示格式化（按 key 排序、缩进 4 空格）后的结果：

@iterm2.RPC async def onclick(session_id): session = app.get_session_by_id(session_id) selection = await session.async_get_selection() selectedText = await session.async_get_selection_text(selection) await component.async_open_popover(session_id, tohtml(prettyprint(selectedText)), iterm2.util.Size(600, 600)) ... await component.async_register(connection, coro, onclick=onclick)

这里async_open_popover接受转义后的 HTML 字符串（示例中的tohtml负责转义&与<），配合async_get_selection/async_get_selection_text实现了"选中即格式化"的完整闭环。

4.4 变量响应型、定时刷新型与其他组件

• mousemode.rst：通过iterm2.Reference("mouseReportingMode")监听变量mouseReportingMode，< 0显示空位，否则显示 🐭 图标，演示"组件响应变量变化"；
• gmtclock.rst：把update_cadence设为1（秒），配合datetime.datetime.now(datetime.timezone.utc).strftime("%H:%M:%S GMT")实现每秒刷新一次的世界时钟；
• diskspace：周期性更新自身，展示磁盘剩余空间；
• unread：带图标与"未读计数"的组件；
• weather：周期性抓取网页并在组件中展示数据，同时演示为组件提供图标；
• venv：展示当前 Python 虚拟环境名称的状态栏组件。

五、Tmux 集成

tmux.rst 演示 Tmux 集成 API 的基础用法。前提：先通过tmux -CC附加到至少一个 tmux 会话。脚本将向第一个 tmux 会话创建一个含两个标签页的新窗口：

async def main(connection): tmux_conns = await iterm2.async_get_tmux_connections(connection) tmux_conn = tmux_conns[0] # 取第一个 tmux 集成连接 window = await tmux_conn.async_create_window() # 新建窗口 tab2 = await window.async_create_tmux_tab(tmux_conn) # 追加第二个标签页 iterm2.run_until_complete(main)

配套的tile示例则演示在 Tmux 集成模式下向 tmux 服务器直接发送命令，适合需要精细控制 tmux 布局/窗口的自动化场景。完整的 tmux 集成 API 见 tmux.rst。

六、事件监听与变量监控

"Monitoring for Events" 类目下的示例共同展示了 iTerm2 脚本的两大核心能力：监听异步事件与监控变量变化。

• random_color：新建会话时触发动作，并应用颜色预设（Color Preset）；
• colorhost：并发监听多种类型事件，是学习多事件协调的范例；
• fs-only-status-bar：监听窗口的创建与窗口样式变化；
• theme：监控变量并应用颜色预设；
• copycolor：监听会话创建并应用颜色预设；
• tabtitle：监听新标签页创建，并演示向用户弹窗请求字符串、改写标签标题（async_request_string类交互 API）；
• autoalert：监控所有会话中的长时任务，并发送系统通知（Notification API）；
• stty：在所有会话中监听变量变化并回写文本；
• app_tab_color：监听当前前台任务（foreground job）的变化，根据当前命令动态调整标签页颜色；
• sync_title：监听窗格标题变化并复制到标签标题，同时演示变量监控与变量设置（async_set_variable）。

这类脚本的价值在于：它们展示了"事件 → 回调 → 动作"的完整编程模型，且大量使用iterm2.Reference("...")绑定系统变量路径，配合?后缀保证变量缺失时的健壮性。

七、Profile 与颜色预设操作

这组示例围绕Profile对象与颜色预设展开，覆盖"读取、局部修改、全局修改"三个层级：

• current_preset：获取会话的 Profile 并查询颜色预设列表；
• blending：注册一个函数（@iterm2.RPC）用于调整多个 Profile 的取值，演示函数注册 API；
• settabcolor：只修改会话的局部 Profile（不更新底层 Profile），适合"临时改颜色、不改配置"的场景；
• increase_font_size：改变会话字号而不改动底层 Profile；
• resizeall：注册一个函数，批量修改窗口中所有会话的字体；
• change_default_profile：修改默认 Profile；
• setprofile：修改会话当前使用的 Profile。

这组示例揭示了 iTerm2 的 Profile 模型：会话级（session）、局部（local）、底层（underlying）三层结构。async_set_profile系列方法允许脚本在不污染持久化配置的前提下临时调整外观，也可以反过来持久化修改，是"配置即代码"的重要接口。

八、键盘、输入广播与窗口标签管理

8.1 键盘钩子：function_key_tabs

function_key_tabs演示改写按键行为：通过KeystrokeMonitor监听按键流，拦截特定键码后执行自定义动作（如切换标签页）。它与escindicator中的键盘监听同一套机制，区别在于用途是"改键"而非"驱动 UI"。

8.2 广播输入：Broadcast Domains

• enable_broadcasting：演示**广播域（Broadcast Domains）**的创建与使用；
• broadcast：综合演示分割窗格（split panes）、广播域、按键过滤、发送输入，是学习"多窗格协同操作"的完整样例。

广播域允许把一次击键同时送入多个会话，示例展示了从代码侧动态创建/管理广播域、并配合session.async_send_text发送输入的完整链路。

8.3 窗口与标签页管理

• movetab：在窗口间移动标签页；
• apply_layout：通过iterm2.App.async_apply_layout在标签页、窗口、分割窗格之间搬移会话，这是布局编排的底层能力；
• sorttabs：重排窗口内标签页顺序；
• mrutabs：监听键盘焦点变化，始终保持标签页按"最近使用"（MRU）排序，第一个标签页始终被选中；
• mrutabs2：当前标签关闭时自动选中"次最近使用"的标签页，对分割窗格同样生效；
• findps：弹窗请求进程 ID，然后定位并显示包含该进程的窗格（配合进程查询 API）；
• tab_group_test：演示标签组（Tab Group）API——创建分组、增删标签、重命名、改色、折叠分组。

九、Asyncio、工具栏、右键菜单与选区

9.1 Asyncio 并行与定时

• close_to_the_right：演示用asyncio.gather并行执行多个异步动作，适合批量操作多个会话/窗口时显著提速；
• darknight：演示在一天中的特定时刻执行动作（如切换深色主题），本质是 asyncio 定时任务 + 变量/预设的组合。

9.2 自定义 Toolbelt 工具

targeted_input演示自定义 Toolbelt（右侧工具条）工具，结合广播域与发送输入，把"定向输入"能力封装成可点击的工具栏面板。

9.3 自定义右键菜单项

sumselection演示自定义上下文菜单项：在选中文本上右键，即可计算所选中数字之和——通过注册菜单项回调并读取选区文本实现。

9.4 选区操作

zoom_on_screen演示选中菜单项并修改选区，展示了通过菜单 API（MainMenu）与选区 API（Selection）联动的可能性。

十、其他高级示例：控制序列与函数注册

• cls：注册函数、注入控制序列、遍历会话（清屏类操作）；
• create_window：演示自定义控制序列（Custom Control Sequence）——应用可以向终端发送自定义 OSC/DCS 序列触发脚本动作；
• ccs：进一步演示能识别"哪个会话收到了该序列"的自定义控制序列，是实现"终端内快捷键驱动脚本"的关键技术，相关实现见 customcontrol.rst；
• oneshot：注册函数并弹出模态警告框（modal alert），适合需要用户确认的一次性动作；
• open_browser_tab：创建浏览器标签页并加载 URL（配合 iTerm2 的浏览器扩展能力）。

十一、从示例到生产：三条可复用的工程经验

1. 生命周期选择决定脚本形态：持续响应（状态栏、键盘监听）用run_forever并放入 AutoLaunch；一次性任务（建窗口、跑命令）用run_until_complete，需要拉起 App 时第二个参数传True。
2. ?后缀是变量引用的"安全带"：所有可能未定义的iterm2.Reference路径都应在末尾加?，这是georges_title、escindicator等官方示例中反复出现的模式。
3. 用户变量是脚本内部的最佳通信通道：user.*命名空间既能让 Shell Integration（.bashrc中的iterm2_set_user_var）把 shell 数据喂给 Python，也能像escindicator那样让脚本内部模块互相协作，还能由sync_title用于跨会话状态同步。

若想深入某条 API 的完整签名，可从 api/library/python/iterm2/docs/index.rst 进入各模块文档（如 session.rst、statusbar.rst、tmux.rst），再借助各文档中的See Also反向索引定位本目录中演示对应 API 的示例脚本——这正是官方推荐的"示例-文档互查"学习路径。

• 桌面应用
• AI 应用