iterm2-layout

iTerm2 布局配置

通过合理划分职责来配置 iTerm2 工作区布局：在 TOML 配置中保存私有路径，在 Python 脚本中保存可发布的代码。

自我进化技能：此技能会随着使用不断改进。如果说明有误、参数发生变化，或需要采用变通方案，请立即修复此文件，不要拖延。只针对真实且可复现的问题进行更新。

何时使用此技能

在以下情况下使用此技能：

• 配置 iTerm2 工作区布局
• 添加、移除或修改工作区标签页
• 为 iTerm2 设置 AutoLaunch 脚本
• 配置 git worktree 标签页自动发现

配置概览

文件位置

文件	位置	用途
配置（私有）	~/.config/iterm2/layout.toml	用户工作区路径
脚本（公开）	~/scripts/iterm2/default-layout.py	布局逻辑
模板	~/scripts/iterm2/layout.example.toml	配置示例

配置文件格式

# ~/.config/iterm2/layout.toml

[layout]
left_pane_ratio = 0.20    # 0.0 to 1.0
settle_time = 0.3         # seconds

[commands]
left = "br --sort-by-type-dirs-first"
right = "zsh"

[worktrees]
# Optional: Enable git worktree discovery
# main_repo_root = "~/projects/my-project"
# worktree_pattern = "my-project.worktree-*"

[[tabs]]
name = "home"
dir = "~"

[[tabs]]
name = "projects"
dir = "~/projects"

[[tabs]]
dir = "~/Documents"  # name defaults to "Documents"

设置说明

首次设置

/usr/bin/env bash << 'CONFIG_EOF'
# 1. Ensure config directory exists
mkdir -p ~/.config/iterm2

# 2. Copy template
cp ~/scripts/iterm2/layout.example.toml ~/.config/iterm2/layout.toml

# 3. Edit with your workspace paths
# Add [[tabs]] entries for each workspace

# 4. Restart iTerm2 to test
CONFIG_EOF

添加新标签页

在 ~/.config/iterm2/layout.toml 中添加一个 [[tabs]] 条目：

[[tabs]]
name = "MyProject"  # Tab display name (optional)
dir = "~/path/to/project"

Name 字段：

• 如果省略，则使用目录基本名称
• 自定义名称适用于缩写（例如，使用 “AF” 代替 “research-repo”）

移除标签页

删除或注释掉 [[tabs]] 条目：

# [[tabs]]
# name = "OldProject"
# dir = "~/old/project"

配置架构

分区	键	类型	默认值	说明
[layout]	left_pane_ratio	浮点数	0.20	左侧窗格宽度（0.0-1.0）
[layout]	settle_time	浮点数	0.3	执行 cd 后等待的时间（秒）
[commands]	left	字符串	br...	左侧窗格命令
[commands]	right	字符串	zsh	右侧窗格命令
[worktrees]	alpha_forge_root	字符串	null	worktree 根目录（可选）
[worktrees]	worktree_pattern	字符串	*.worktree-*	Glob 模式
[[tabs]]	dir	字符串	必填	目录路径
[[tabs]]	name	字符串	basename	标签页显示名称

故障排除

错误：“未找到布局配置”

现象：Script Console 显示配置缺失错误

解决方案：

# Create config from template
cp ~/scripts/iterm2/layout.example.toml ~/.config/iterm2/layout.toml

错误：“TOML 语法无效”

现象：Script Console 显示 TOML 解析错误

解决方案：

1. 检查 TOML 语法（引号、方括号）
2. 使用以下命令验证：python3 -c "import tomllib; tomllib.load(open('~/.config/iterm2/layout.toml', 'rb'))"

标签页未显示

现象：iTerm2 已打开，但未创建自定义标签页

原因：

1. 配置中没有 [[tabs]] 条目
2. 配置文件位于错误位置
3. 脚本未添加到 AutoLaunch

解决方案：

# Verify config location
ls -la ~/.config/iterm2/layout.toml

# Verify AutoLaunch symlink
ls -la ~/Library/Application\ Support/iTerm2/Scripts/AutoLaunch/

# Check Script Console for errors
# iTerm2 > Scripts > Manage > Console

目录不存在警告

现象：Script Console 中显示警告并跳过标签页

解决方案：确认目录路径存在，或创建该目录：

mkdir -p ~/path/to/missing/directory

错误处理行为

脚本使用“打印信息后提前返回”的模式：

1. 缺少配置：在 Script Console 中记录操作说明，然后正常退出
2. TOML 无效：记录包含详细信息的解析错误，然后正常退出
3. 缺少目录：记录警告、跳过该标签页，并继续处理其他标签页

查看错误：在 iTerm2 中选择 Scripts > Manage > Console

Git Worktree 检测（可选）

启用为 git worktree 动态创建标签页的功能：

[worktrees]
main_repo_root = "~/projects/my-project"
worktree_pattern = "my-project.worktree-*"

工作原理：

1. 脚本会对 ~/projects/my-project.worktree-* 目录进行 Glob 匹配
2. 使用 git worktree list 验证每个目录
3. 根据首字母生成标签页名称（例如，sharpe-statistical-validation 对应 AF-ssv）
4. 将 worktree 标签页插入主项目标签页之后

参考资料

• iTerm2 Python API
• TOML Specification
• XDG Base Directory Spec
• ADR：iTerm2 Layout Config

执行后复盘

此技能完成后，请在结束前检查：

1. 命令是否成功？ — 如果没有，请修正导致失败的说明或错误表。
2. 参数或输出是否有变化？ — 如果底层工具的接口发生变化，请相应更新用法示例和参数表。
3. 是否需要变通处理？ — 如果你不得不临时调整（使用不同的标志、增加步骤），请更新此 SKILL.md，以便下次调用时无需采用同样的变通方法。

仅当问题真实且可复现时才更新，不要基于猜测更新。