iTerm2 控制

概述

iTerm2 Control

Drive the user's iTerm2 terminal on macOS from the assistant. This is distinct from the assistant's own Bash/shell tool: commands run in a visible iTerm2 window the user can see and interact with.

When to use

• The user wants a command executed in their visible iTerm2 (e.g. "在 iTerm2 里跑一下", "让我看到终端输出").
• You want to open a dedicated tab/window/pane for a long-running process (dev server, watcher, build) so it stays visible and separate.
• You need to capture the output of a command that ran in iTerm2.

触发词（自动命中）

当用户的指令出现以下任一表述时，应优先调用本 skill（而非助手的沙箱 Bash）：

• 「在 iTerm2 里跑 / 执行 / 看一下」「让我看到终端输出」「在可见终端执行」
• 「开个新标签 / 新窗口 / 分屏跑」「iTerm2 里跑个 dev server / 构建 / 监听」
• 「抓取 / 捕获 iTerm2 当前输出」「把 iTerm2 里的内容导出来」
• 用户明确要求命令必须发生在他们肉眼可见的终端（演示、需交互、需长期驻留的进程）

Prerequisites

• iTerm2 installed at /Applications/iTerm2.app (or running). The skill launches it if not running.
• osascript (built into macOS). No other dependencies.

Permissions (macOS, one-time)

Controlling iTerm2 via AppleScript requires macOS Automation permission. This is a security gate, not a skill bug:

• capture / read works without it.
• send / write / run / tab / window / split-* (anything that sends a command) requires it. You'll see error -10004 (权限违例) if missing.

Grant it (one time):

1. The first time a write text command runs, macOS may pop a dialog: "[App] 想要控制 iTerm2" → click 允许 (Allow).
2. If no dialog appears (e.g. command runs from a background/non-GUI context), grant manually:
   • 系统设置 → 隐私与安全性 → 自动化 (Automation)
   • Find the app that runs your commands (the terminal app, or the app hosting WorkBuddy's shell) → enable iTerm2.
3. If you want the assistant to drive iTerm2, the permission must be granted to whatever app hosts the assistant's shell — approve the dialog the first time the assistant attempts it, then it persists.

Usage

Run the bundled helper:

"$HOME/.workbuddy/skills/iterm2-control/iterm2_ctl.sh" <subcommand> [args]

Examples

S="$HOME/.workbuddy/skills/iterm2-control/iterm2_ctl.sh"

# Run a build in a fresh tab so it stays visible
"$S" tab "npm run dev"

# Run a long task in a new window and grab its output after 5s
"$S" run "python train.py" 5        # prints /tmp/iterm2_capture.XXXXXX.txt

# Multi-pane: split current pane and run two watchers
"$S" split-v "npm run watch:css"
"$S" split-h "npm run watch:js"

# Read what the current session shows
"$S" capture                         # prints path; then Read that file

Important rules

1. Quote commands properly. Pass COMMAND in single quotes so the user's shell does not expand $, backticks, or ! before the helper sees it:

   "$S" send 'export FOO="bar"; echo "$FOO"'

1. Capture writes to a temp file, not stdout. This keeps large scrollback out of the assistant's context (token-efficient). Read the printed path only when you need the output.
2. run waits a fixed time, not for a prompt. Increase secs for slow commands, or use send then capture after the user confirms completion.
3. Never use this to run destructive commands the user hasn't approved — it acts on their live, visible terminal.
4. If iTerm2 has no open window, send/capture/split-* auto-create one (harmless).

常见问题（FAQ）

• Q：$、反引号、感叹号被吞或提前展开？

A：必须用单引号包裹 COMMAND（见规则 #1），让 shell 原样传给脚本，避免助手侧先展开。

• Q：报 -10004 权限违例？

A：macOS 自动化（Automation） 未授权。按「Permissions」一节给宿主 App 开启控制 iTerm2 的权限即可。

• Q：capture 的输出去哪了？

A：写入 /tmp/iterm2_capture.XXXXXX.txt 并打印路径，不在 stdout——这是为省 token 的设计。用 Read 读该路径即可。

• Q：run 还没跑完就 capture 了？

A：run 只固定等待 N 秒（默认 3）。慢命令把秒数调大（如 run "python train.py" 30），或改用 send + 用户确认后再 capture。

• Q：命令里内嵌的双引号被截断？

A：脚本 escape_as 已把 " 转义为 "；若仍异常，尽量改用单引号包裹内部字符串，避免命令内嵌双引号。

• Q：没有开着的 iTerm2 窗口会报错吗？

A：不会。send/capture/split-* 在窗口缺失时会自动创建一个（无害）。

How it works

iterm2_ctl.sh calls osascript with iTerm2's AppleScript dictionary: write text sends a command to a session; create tab/window and split vertically/horizontally manage layout; get contents reads the full scrollback. Command strings are escaped for AppleScript ( → \, " → ").