企业官网建设流程全解析

• 桌面应用
• AI 应用

it2cli 是 iTerm2 仓库内随附的一个 Swift 命令行工具（可执行文件名为it2），通过 iTerm2 的 Python API 直接管理会话（Session）、窗口（Window）、标签页（Tab）、Profile、应用级设置、输出监控与认证。本篇以 it2cli/TESTING.md 为核心骨架，逐条展开其全部测试场景，并结合仓库源码（it2cli/Package.swift、it2cli/Sources/it2core 等）补充底层实现原理，帮助你在真实 iTerm2 环境中完成一次系统性的 CLI 功能验收，同时理解每个命令背后的 API 调用链。

一、测试前的环境准备

1.1 前置条件

TESTING.md 明确要求：所有测试都必须在iTerm2 内部且已启用 Python API的终端中运行。具体包含两个步骤：

1. 将编译产物加入 PATH：

export PATH=/path/to/it2cli/.build/debug:$PATH

2. 开启 Python API：打开 iTerm2 的Settings > General > Magic > Enable Python API开关。若该开关未开启，后续所有命令都会在认证环节失败（详见“错误处理”一节的 API disabled 场景）。

1.2 构建方式（结合源码）

it2二进制由 it2cli/Package.swift 定义的 SwiftPM 包构建而来。该包声明了 macOS 13+ 平台、一个名为it2的 executable product，依赖swift-argument-parser与Yams（后者用于解析 YAML 格式的~/.it2rc.yaml配置文件）。构建前需先运行 it2cli/setup.sh 创建指向仓库内ThirdParty/ProtobufRuntime与sources/proto的符号链接：

cd it2cli ./setup.sh swift build # 产物位于 .build/debug/it2

从 it2cli/Sources/it2/main.swift 可以看到，it2只是一个“瘦驱动”：所有逻辑都收敛在it2core库中，以便命令树还能以 In-App 方式嵌入 iTerm2 进程内部运行（InApp/目录提供了对应的 ProtobufRuntime modulemap）。因此你看到的it2 session ...、it2 window ...等命令树，在两种运行形态下是一致的。

1.3 测试总览

按 TESTING.md 的编排，测试共分九大类，本文将依次展开：

• Session（会话）命令：list / split / run / send / close / restart / focus / read / clear / capture / set-name / set-color / get-var / set-var
• Window（窗口）命令：new / list / focus / move / resize / fullscreen / close / arrange
• Tab（标签页）命令：new / list / select / close / next / prev / goto / move
• Profile（配置）命令：list / show / apply / set
• App（应用）命令：activate / hide / version / theme / get-focus / broadcast / quit
• Monitor（监控）命令：output / keystroke / variable / prompt / activity
• Auth（认证）命令：cookie
• 顶层快捷命令：ls / send / run / split / vsplit / clear / new / newtab
• Config（配置）命令：config-path / config-reload / load / alias
• 环境变量：IT2_APP_PATH / IT2_SUITE / ITERM2_COOKIE / ITERM2_KEY
• 错误处理：坏 session ID、API 未开启、非法颜色格式

二、Session 命令测试

会话（Session）在 iTerm2 中对应一个 pane（窗格）。it2 session的完整子命令树定义在 it2cli/Sources/it2core/Commands/SessionCommand.swift，除测试计划覆盖的子命令外，还包括copy、set-status、get-background-tasks、add-clipping、archive-clippings等。

2.1 session list

it2 session list

期望输出：每个会话一行，格式为<UUID>\t<title>；行数应等于所有窗口、所有标签页中打开会话的总数。

从 SessionCommand.swift 的实现可见，该命令通过ITMListSessionsRequest请求 iTerm2，遍历响应中每个 window 的 tab 树，并用walkSplitTree递归展开每个 tab 的分屏结构，最终为每个会话输出id / name / title / size / tty等字段。测试要点：核对 UUID 数量与界面上打开的 pane 数量一致。该命令还支持--json输出结构化结果，便于脚本消费。

2.2 session split（水平 / 垂直 / 定向 / 指定 Profile）

水平分割（在当前活动会话中创建右/下方新窗格）：

it2 session split

垂直分割：

it2 session split -v

两者都应打印Created new pane: <UUID>。

定向分割（对指定会话，而非活动会话）：

SESSION=$(it2 session list | head -1 | cut -f1) it2 session split -v -s "$SESSION"

这里cut -f1取的就是session list输出的第一列 UUID。-s指定目标会话 ID。

指定 Profile 分割：

PROFILE=$(it2 profile list | head -1 | cut -f2) it2 session split -p "$PROFILE"

注意这里取的是profile list的第二列（Profile 名称）。-p让新窗格使用指定 Profile 的终端配置。

2.3 session run 与 session send

run（在窗格中执行命令）：

SESSION=$(it2 session split -v | awk '{print $NF}') it2 session run -s "$SESSION" "echo hello from it2"

split -v的输出形如Created new pane: <UUID>，awk '{print $NF}'取最后一个字段即新窗格的 UUID。执行后应在新窗格内看到hello from it2。

send（键入文本但不回车）：

it2 session send -s "$SESSION" "typed without enter"

与run的本质区别：send只向终端输入字符、不发送回车，因此文本会停留在提示符处而不会执行。这是模拟人工输入的关键能力，也是后续广播（broadcast）测试的基础。

广播到所有会话：

it2 session send -a "broadcast test"

-a/--all会将文本键入到每一个会话中，用于验证批量发送能力。

2.4 session close

强制关闭（-f，跳过确认）：

SESSION=$(it2 session split | awk '{print $NF}') it2 session close -f -s "$SESSION"

期望打印Session closed，窗格消失。

不强制关闭：

SESSION=$(it2 session split | awk '{print $NF}') it2 session close -s "$SESSION"

期望 iTerm2 弹出确认对话框（除非用户已在偏好设置中关闭“关闭前确认”）。

2.5 session restart / focus / read / clear / capture

restart（重启会话的 shell）：

SESSION=$(it2 session list | head -1 | cut -f1) it2 session restart -s "$SESSION"

期望打印Session restarted，该会话的 shell 重新启动。

focus（将某个会话变为活动窗格）：

SESSION=$(it2 session list | tail -1 | cut -f1) it2 session focus "$SESSION"

期望打印Focused session: <UUID>，同时该会话成为活动 pane、其所在标签页被选中、窗口置前。这里用tail -1选取列表中最后一个会话，避免与当前活动会话冲突。

read（读取屏幕内容）：

it2 session read it2 session read -l 5 # 只输出最后 5 行

前者打印活动会话的可见屏幕内容，后者通过-l限制行数。仓库中 Tests/it2coreTests/SessionReadTests.swift 对读取逻辑有对应单元测试。

clear（清屏）：

it2 session clear

等价于向活动会话发送Ctrl+L，应清空屏幕。

capture（捕获屏幕到文件）：

it2 session capture -o /tmp/it2-capture.txt cat /tmp/it2-capture.txt rm /tmp/it2-capture.txt

期望打印Screen captured to: /tmp/it2-capture.txt，并检查文件内容确实包含屏幕快照。-o指定输出路径。

2.6 session set-name / set-color

修改会话名：

SESSION=$(it2 session list | head -1 | cut -f1) it2 session set-name -s "$SESSION" "Test Name"

期望打印Session name set to: Test Name，标签页/会话标题随之更新。

设置标签颜色：

SESSION=$(it2 session list | head -1 | cut -f1) it2 session set-color -s "$SESSION" "#FF0000" # 恢复为黑色 it2 session set-color -s "$SESSION" "#000000"

期望打印Tab color set to #FF0000且标签变红。颜色使用#RRGGBB十六进制格式；若传入非法格式（如notacolor），应输出错误（见“错误处理”一节）。

2.7 session get-var / set-var（变量读写）

读取变量：

it2 session get-var session.name

期望打印session.name的 JSON 编码值。session.name、session.tty这类内建变量由 iTerm2 通过ITMVariableRequest提供，前面 session list 的实现 正是用同样的变量请求机制补齐会话名称与 tty 信息的。

写入用户自定义变量：

SESSION=$(it2 session list | head -1 | cut -f1) it2 session set-var user.testVar '"hello"' -s "$SESSION" it2 session get-var user.testVar -s "$SESSION"

期望set-var打印Set user.testVar = "hello"，随后get-var打印"hello"（注意 JSON 字符串自带引号）。user.*是用户命名空间，可自由存取，适合作为脚本间的轻量状态传递。

三、Window 命令测试

窗口命令定义在 it2cli/Sources/it2core/Commands/WindowCommand.swift。窗口 ID（window_id）与会话 UUID 不同，通常是自增数字。

3.1 window new / list

it2 window new

期望打印Created new window: <window_id>并出现新窗口。带 Profile 创建：

it2 window new -p Default

使用名为Default的 Profile 创建新窗口（注意这里用的是 Profile 名称而非 GUID）。

it2 window list

期望每窗口一行：<window_id>\t<N> tabs，即窗口 ID 与标签页数量。Tests/it2coreTests/WindowListTests.swift 对窗口列表解析逻辑做了单元测试。

3.2 window focus / move / resize

聚焦窗口：

WINDOW=$(it2 window list | head -1 | cut -f1) it2 window focus "$WINDOW"

期望打印Focused window: <id>并将窗口置前。

移动窗口：

WINDOW=$(it2 window list | head -1 | cut -f1) it2 window move 100 100 "$WINDOW"

期望打印Moved window to (100, 100)，窗口移动到屏幕坐标 (100, 100)（注意该坐标为当前显示器的全局坐标）。

调整窗口大小：

WINDOW=$(it2 window list | head -1 | cut -f1) it2 window resize 800 600 "$WINDOW"

期望打印Resized window to 800x600。

3.3 window fullscreen

WINDOW=$(it2 window list | head -1 | cut -f1) it2 window fullscreen on "$WINDOW" # 进入全屏 it2 window fullscreen off "$WINDOW" # 退出全屏 it2 window fullscreen toggle # 切换当前窗口全屏状态

on/off针对指定窗口，toggle作用于当前窗口。

3.4 window close 与窗口布局（arrange）持久化

关闭窗口：

it2 window new WINDOW=$(it2 window list | tail -1 | cut -f1) it2 window close -f "$WINDOW"

期望打印Window closed。tail -1选取刚创建的那个新窗口，-f强制关闭。

保存 / 列出 / 恢复窗口布局：

it2 window arrange save test-arrangement it2 window arrange list it2 window arrange restore test-arrangement

依次期望打印Saved arrangement: test-arrangement、列表中出现test-arrangement、Restored arrangement: test-arrangement且窗口/标签被完整还原。这是验证 iTerm2 窗口布局持久化能力的关键测试，恢复后可继续测试其他命令。

四、Tab 命令测试

标签页命令定义在 it2cli/Sources/it2core/Commands/TabCommand.swift。

4.1 tab new / list

it2 tab new

期望打印Created new tab: <tab_id>并在当前窗口出现新标签页。带 Profile 创建：

it2 tab new -p Default

it2 tab list

期望每标签页一行，输出 tab ID、窗口 ID、索引（index）与会话数。按窗口过滤：

WINDOW=$(it2 window list | head -1 | cut -f1) it2 tab list -w "$WINDOW"

只应列出该窗口内的标签页。

4.2 tab select / close

选中标签页：

TAB=$(it2 tab list | head -1 | cut -f1) it2 tab select "$TAB"

期望打印Selected tab: <id>且该标签页变为活动页。

关闭标签页：

it2 tab new TAB=$(it2 tab list | tail -1 | cut -f1) it2 tab close -f "$TAB"

期望打印Tab closed。

4.3 tab next / prev / goto / move

it2 tab next # 打印 Switched to tab <N>，切换到下一个标签页 it2 tab prev # 返回上一个标签页 it2 tab goto 0 # 选中第一个标签页（索引从 0 开始）

移动标签页到新窗口：

it2 tab new it2 tab move

期望打印Moved tab to new window，当前标签页从原窗口分离、进入新窗口。

五、Profile 命令测试

Profile 命令定义在 it2cli/Sources/it2core/Commands/ProfileCommand.swift，注意 Profile 有 GUID 与名称两个标识维度。

5.1 profile list / show

it2 profile list

期望每 Profile 一行：<GUID>\t<name>（GUID 是第一列、名称是第二列，这正是前面 split / apply 测试中cut -f2取名称的原因）。Tests/it2coreTests/ProfileListTests.swift 覆盖了该命令的解析。

it2 profile show Default

期望以key: value键值对形式打印名为Default的 Profile 的全部属性（参数名、颜色、字体、快捷键绑定等）。

5.2 profile apply / set

将 Profile 应用到会话：

PROFILE=$(it2 profile list | head -1 | cut -f1) it2 profile apply "$PROFILE"

期望打印Applied profile '<name>' to session，当前会话立即套用该 Profile 的外观与行为。

修改 Profile 属性：

it2 profile set Default badge-text '"test badge"'

期望打印Set badge-text = "test badge" for profile 'Default'。TESTING.md 特别强调：这会实际修改 Profile 本体，而非仅作用于当前会话——也就是说，此命令是持久化的写操作，测试前请确认不会破坏现有配置（建议用一次性测试 Profile 执行）。

六、App 命令测试

应用级命令定义在 it2cli/Sources/it2core/Commands/AppCommand.swift，作用于 iTerm2 整体。

6.1 activate / hide / version / theme

it2 app activate # 打印 iTerm2 activated，应用置前 it2 app hide # 打印 iTerm2 hidden，应用隐藏（点 Dock 图标恢复） it2 app version # 打印 iTerm2 version: <version string> it2 app theme # 打印 Current theme: <theme name> it2 app theme dark # 打印 Theme set to: dark it2 app theme automatic # 恢复为自动跟随系统

主题取值通常包括dark/light/automatic（自动跟随系统外观）。

6.2 app get-focus

it2 app get-focus

期望打印当前窗口、标签页、会话的 ID，且输出中不应出现Optional(...)包裹——这是验证底层 Swift 可选值正确解包的回归测试点，保证输出可直接被cut等工具消费。

6.3 app broadcast（输入广播）

先制造两个窗格，再开启广播：

it2 session split -v it2 app broadcast on

期望打印Broadcasting enabled for current tab，此后在任意一个窗格键入的内容会同时出现在两个窗格中。

it2 app broadcast off

期望打印Broadcasting disabled。

自定义广播组：

S1=$(it2 session list | sed -n '1p' | cut -f1) S2=$(it2 session list | sed -n '2p' | cut -f1) it2 app broadcast add "$S1" "$S2"

期望打印Created broadcast group with 2 sessions。与broadcast on（当前标签页内所有窗格）不同，add允许跨窗格/跨标签页指定成员。

6.4 app quit

it2 app quit

警告：这会退出 iTerm2。期望打印iTerm2 quit command sent。Tests/it2coreTests/AppQuitTests.swift 对该命令的请求构造有对应测试。建议将此场景放到整套测试的最后执行，或在无其他任务的测试环境中进行。

七、Monitor 命令测试（长驻命令）

Monitor 命令定义在 it2cli/Sources/it2core/Commands/MonitorCommand.swift，用于订阅 iTerm2 的实时事件。它们都是长驻进程，测试完用Ctrl+C终止。仓库中的 Tests/it2coreTests/MonitorOutputTests.swift 对输出监控的事件处理有单元测试支撑。

7.1 monitor output

it2 monitor output

注意与session read的区别：该命令打印一次当前屏幕内容后立即退出（可视为流式输出接口的快照模式）。

跟随模式：

it2 monitor output -f & MONITOR_PID=$! # 在另一个窗格中执行若干命令 kill $MONITOR_PID

-f/--follow会持续打印屏幕更新；测试时先在后台启动，再到其他窗格操作，最后 kill 掉后台进程。

模式过滤：

it2 monitor output -p "ERROR"

-p/--pattern只打印匹配ERROR的行，适合日志跟踪场景。

7.2 monitor keystroke

it2 monitor keystroke

测试时键入若干按键，每个按键应输出一行Keystroke: <char>，Ctrl+C结束。

7.3 monitor variable

会话级变量监听：

it2 monitor variable session.name

通过偏好设置或it2 session set-name改变会话名，应打印Changed to: <new value>。

应用级变量监听：

it2 monitor variable effectiveTheme --app-level

--app-level将监听范围提升到整个应用；改变主题后应打印新值。

7.4 monitor prompt（依赖 Shell Integration）

it2 monitor prompt

前提：被监控会话必须已启用 Shell Integration（即 shell 启动脚本已加载）。在会话中运行命令时应依次看到：

• New prompt detected—— 出现新提示符
• Command started: <cmd>—— 命令开始执行
• Command finished (exit status: <N>)—— 命令结束并携带退出码

这是对 iTerm2 Shell Integration 事件的直接订阅，也是自动化任务编排的基础。

7.5 monitor activity（焦点活动）

it2 monitor activity -a

在不同会话间切换焦点，应打印Session active: <name>（获得焦点）与Session idle: <name>（失去焦点）。

八、Auth 认证命令测试

认证是 it2 CLI 与 iTerm2 建立授权通道的关键环节，实现位于 it2cli/Sources/it2core/Auth/CookieAuth.swift 与 it2cli/Sources/it2core/Commands/AuthCommand.swift。

8.1 auth cookie（可复用 cookie）

it2 auth cookie

运行后 iTerm2 会话内应出现授权公告，提供24 Hours、Forever、Always Allow All Apps、Deny等选项；选择24 Hours后，命令打印：

ITERM2_COOKIE=<cookie> ITERM2_KEY=<key>

验证 cookie 生效（性能对比）：

export $(it2 auth cookie) time it2 session list > /dev/null

期望耗时约10ms（而非未认证时的约 140ms）——速度差异来自绕过了每次都要执行的 AppleScript 授权流程。

验证复用：

time it2 session list > /dev/null time it2 session list > /dev/null

连续多次执行都应保持毫秒级。从 CookieAuth.swift 的实现可以确认：认证器优先检查ITERM2_COOKIE环境变量，只有环境变量缺失时才回退到 AppleScript 申请 cookie。

8.2 auth cookie（单次使用）

it2 auth cookie --single-use

应直接打印 cookie 且不弹出公告窗口，适合脚本内匿名调用。

8.3 关于远程路径的补充

从 it2cli/Sources/it2core/IT2.swift 的源码注释可以看出设计意图：auth命令子树被标记为RemoteForbiddenCommand——因为可复用的ITERM2_COOKIE/ITERM2_KEY一旦经 SSH 远程通道泄露，就绕过了 iTerm2 按会话授予、可撤销的 API 权限。因此在嵌入式 / over-SSH 路径下，it2 auth ...会被整体拒绝，防止 cookie 流出本机。这是安全设计上的一个值得注意的细节。

九、顶层快捷命令

为贴近 Python 版it2的使用习惯，CLI 提供了一组顶层快捷命令，实现位于 it2cli/Sources/it2core/Commands/ShortcutCommands.swift。它们本质上是把参数重新组装后转发给对应的完整子命令（例如SendShortcut将text、-s、-a转给Session.Send）。

测试时逐条运行并比对输出与等价命令是否一致。

十、Config 命令测试（~/.it2rc.yaml）

Config 命令定义在 it2cli/Sources/it2core/Commands/ConfigCommand.swift，负责加载用户主目录下的~/.it2rc.yaml（YAML 解析依赖Package.swift中的 Yams 库）。仓库内 Tests/it2coreTests/ConfigReloadTests.swift 对配置重载逻辑有单测覆盖。

10.1 config-path

it2 config-path

打印~/.it2rc.yaml的路径及该文件当前是否存在。

10.2 config-reload

先创建测试配置：

cat > ~/.it2rc.yaml << 'EOF' profiles: test: - command: echo "loaded from config" aliases: hello: session run "echo hello from alias" EOF

然后：

it2 config-reload

期望打印Configuration reloaded并列出加载到的 profiles 与 aliases。

10.3 load 与 alias

it2 load test

期望打印Loading profile: test并依次执行该 profile 中定义的命令（此处为echo "loaded from config"）。

it2 alias hello

期望打印Running alias 'hello': session run "echo hello from alias"并实际执行该命令。

清理：

rm ~/.it2rc.yaml

测试完成后删除临时配置，避免污染后续使用。（提示：这里文档使用rm清理的是用户自己创建的临时测试文件，并非仓库文件。）

十一、环境变量测试

11.1 IT2_APP_PATH

IT2_APP_PATH="/Applications/iTerm.app" it2 session list

用于指定 iTerm2 应用的路径，以便 AppleScript 认证流程定位正确的应用实例（例如多版本并存或非标准安装路径时）。

11.2 IT2_SUITE

IT2_SUITE="iTerm2" it2 session list

指定连接~/Library/Application Support/iTerm2/private/socket这个 Unix domain socket；换一个值就连接到不同的 socket 路径。这一机制让同一套二进制可以在多套 iTerm2 数据目录（如 beta 版与正式版）之间切换，与 Transport/APIChannel.swift 中“SocketChannel通过 iTerm2 本地 Unix domain socket 通信”的实现对应。还需注意 IT2Context.swift 中的设计约束：在 SSH 授权提示这类受限模式下，部分命令会被拒绝。

11.3 ITERM2_COOKIE / ITERM2_KEY

export $(it2 auth cookie --single-use) it2 session list unset ITERM2_COOKIE ITERM2_KEY

第一次session list应从环境变量直接读取 cookie（毫秒级，无公告弹窗）；unset之后应回退到 AppleScript 流程。结合第八节的源码可以串起完整链路：环境变量 → 单次 AppleScript 授权 → 建立 socket 通道。

十二、错误处理测试

错误路径是 CLI 健壮性的试金石，相关错误类型定义在 it2cli/Sources/it2core/IT2Error.swift。

12.1 无效的 session ID

it2 session run -s "nonexistent-uuid" "echo test"

期望打印错误信息并以非零退出码结束（可用echo $?验证）。

12.2 API 未开启

在设置中关闭 Python API，然后：

it2 session list

期望打印连接或认证错误。这验证了前置条件“Enable Python API”的必要性。

12.3 非法颜色格式

it2 session set-color -s "$(it2 session list | head -1 | cut -f1)" "notacolor"

期望打印关于颜色格式非法的错误信息，验证#RRGGBB格式校验逻辑。

十三、测试编排建议

综合 TESTING.md 的编排顺序，推荐按以下依赖关系组织测试流水线：

1. 准备阶段：setup.sh+swift build、配置 PATH、开启 Python API。
2. 快速冒烟：it2 session list、it2 app version、it2 app theme，确认通道与认证可用。
3. 对象创建：session split→window new→tab new，获得测试用 UUID/ID。
4. 功能验证：按会话 → 窗口 → 标签页 → Profile → 应用 → 监控 → 配置的顺序逐条执行，注意session run依赖 split 产生的会话、broadcast add依赖至少两个会话。
5. 持久化验证：window arrange save/restore与config-reload。
6. 错误路径：坏 ID、非法颜色、关闭 API 后的连接失败。
7. 收尾：app quit（置于最后）、清理/tmp/it2-capture.txt与~/.it2rc.yaml。

需要特别留意两个“破坏性”命令：it2 profile set（会持久修改 Profile 本体）与it2 app quit（会退出 iTerm2），务必在独立测试环境中执行。

结语

本测试计划覆盖了 it2 CLI 从对象管理（会话/窗口/标签页）、配置管理（Profile /~/.it2rc.yaml）、实时监控（输出/按键/变量/提示符/焦点）到认证（cookie 机制）与错误路径的完整功能面。结合源码可知，整条链路建立在三个技术支柱之上：基于 protobuf 的 API 协议（sources/proto 中的Api.proto定义消息格式）、本地 Unix domain socket 通道（Transport/APIChannel.swift）、以及环境变量优先、AppleScript 兜底的认证策略（Auth/CookieAuth.swift）。逐条跑完这套用例，你不仅能验收 CLI 的全部能力，也能为基于 iTerm2 的自动化脚本建立可复用的验证基线。

• 桌面应用
• AI 应用