name: terminal-theme description: 配置和管理终端多彩主题轮换系统 — 添加/修改/删除主题、调整颜色和背景混合比例、排查显示问题。当用户提到终端主题、终端颜色、终端配色、prompt颜色、tab颜色时触发。 user-invocable: true argument-hint: "[add/modify/remove/list/reset/troubleshoot]"

Terminal Theme - 多彩终端主题轮换系统

为 zsh + Starship 打造的多主题轮换系统，兼容主流终端（iTerm2/Kitty/Ghostty/WezTerm/Alacritty/VS Code/Qoder/Windows Terminal）。每个新终端窗口自动分配不同主题色，包括提示符标签、终端背景色（深色混合）和 Tab 标题，让多窗口工作时一眼区分。

终端兼容性

不支持 OSC 11 的终端会自动降级为仅显示彩色提示符标签。

意图路由

根据用户的话判断走哪个流程：

流程 A: 添加新主题

Step 1: 确认新主题信息

向用户确认（如果未提供）：

• 主题名称：中文名，2-4 个字（如"樱花粉"、"极光紫"）
• 主题颜色：HEX 色值（如 #ff6b9d），或描述颜色让 AI 推荐
• 图标 emoji：一个能代表这个颜色/氛围的 emoji

如果用户没指定颜色，从以下推荐色中选一个（避免与现有主题撞色）：

撞色检查：新色与现有 8 色的色相差应 > 30°，避免太接近。

Step 2: 确定前景色

根据背景色亮度自动判断前景色：

• 将 HEX 转为 RGB，计算亮度 (R×299 + G×587 + B×114) / 1000
• > 128 → 浅色背景 → 深色字 1a1b26
• ≤ 128 → 深色背景 → 白色字 ffffff

Step 3: 编辑 ~/.zshrc

1. 用 Grep 搜索 _PROMPT_FG= 定位到主题数组区域
2. 找到 5 个数组：_PROMPT_FG、_PROMPT_BG、_PROMPT_TEXT、_PROMPT_ICON、_PROMPT_NAME
3. 在每个数组的末尾元素后、右括号前追加新值

_PROMPT_FG=(... "新前景色")     # ffffff 或 1a1b26
_PROMPT_BG=(... "新背景色")     # 6位 hex，不带 #
_PROMPT_TEXT=(... "新主题色")    # 同背景色，ANSI 调色基准
_PROMPT_ICON=(... "新图标")     # emoji
_PROMPT_NAME=(... "新名称")     # 中文名

关键：5 个数组必须同步，新值都在同一索引位置。

Step 4: 验证

运行验证命令确认数组长度一致：

zsh -c 'source ~/.zshrc 2>/dev/null; echo "FG=${#_PROMPT_FG[@]} BG=${#_PROMPT_BG[@]} TEXT=${#_PROMPT_TEXT[@]} ICON=${#_PROMPT_ICON[@]} NAME=${#_PROMPT_NAME[@]}"'

5 个数字必须相同，否则说明编辑有误。

Step 5: 更新文档 & 通知用户

1. 更新本 skill 文档中的"当前主题列表"表格
2. 告诉用户：打开新终端窗口即可看到新主题

流程 B: 修改现有主题

Step 1: 确认修改内容

向用户确认：

• 要修改哪个主题（名称或序号）
• 要改什么（颜色/图标/名称）

Step 2: 编辑 ~/.zshrc

1. 用 Grep 搜索 _PROMPT_FG= 定位到主题数组区域
2. 根据序号确定索引位置（序号 = 数组中第几个元素）
3. 替换目标元素

如果改了背景色，需要重新判断前景色（参考流程 A Step 2）。

Step 3: 验证

运行流程 A Step 4 的验证命令。

Step 4: 更新文档

更新本 skill 文档中的"当前主题列表"表格。

流程 C: 删除主题

Step 1: 确认要删除的主题

Step 2: 编辑 ~/.zshrc

1. 用 Grep 搜索 _PROMPT_FG= 定位到主题数组区域
2. 从 5 个数组中同步删除对应索引位置的值

Step 3: 重置计数器 & 验证

rm -f /tmp/.zsh_prompt_counter

运行流程 A Step 4 的验证命令。

Step 4: 更新文档

更新本 skill 文档中的"当前主题列表"表格。

流程 D: 查看当前主题列表

直接展示下方"当前主题列表"表格给用户。

流程 E: 调整背景混合比例

Step 1: 确认新比例

当前是 25%（经验最佳值）。参考：

• 20-25% → 推荐值，平衡色调辨识和阅读舒适
• 8-12% → 更接近纯黑，色调微弱
• 30%+ → 色调更明显，但背景更亮

Step 2: 编辑 ~/.zshrc

用 Grep 搜索 _R * 25 定位到混合计算代码，将 3 行中的 25 替换为新比例值。

Step 3: 验证

提示用户打开新终端窗口查看效果。

流程 F: 重置计数器

当所有窗口颜色相同或顺序混乱时：

rm -f /tmp/.zsh_prompt_counter

提示用户重新打开终端窗口。

流程 G: 排查问题

当前主题列表

前景色规则：浅色背景用深色字 #1a1b26，深色背景用白色字 #ffffff。

配色来源：Tokyo Night 主题色板。

ANSI 调色映射

每次主题轮换时，除了背景色和 Starship 标签，还会同步修改终端 ANSI 调色板，让 Claude Code 的文字颜色也跟着主题走。

基准色来自 _PROMPT_TEXT 数组（通常与 _PROMPT_BG 相同），自动计算 3 个 ANSI 槽位：

通过 OSC 4 转义序列设置：\033]4;槽位号;rgb:RR/GG/BB\007

注意：这些颜色会自动跟随 _PROMPT_TEXT 变化，添加/修改主题时无需额外配置。

技术架构（供参考）

~/.zshrc 底部配置
├── 主题定义：5 个并行数组（_PROMPT_FG / _PROMPT_BG / _PROMPT_TEXT / _PROMPT_ICON / _PROMPT_NAME）
├── 窗口计数器：/tmp/.zsh_prompt_counter（每个新窗口 +1，取模轮换）
├── 背景色混合：25% 主题色 + 75% 纯黑（通过 OSC 11 转义序列设置）
├── ANSI 调色：基于 _PROMPT_TEXT 自动映射 ANSI 15/7/9（通过 OSC 4 转义序列设置）
├── Starship 提示符：precmd hook 注入带色标签到 PROMPT 变量
├── iTerm2 标题：OSC 1（Tab 标题）+ OSC 2（窗口标题）联动目录名
└── zsh 插件：语法高亮 + 自动建议

定位代码的搜索关键词：_PROMPT_FG=（数组定义区）、_PROMPT_TEXT=（ANSI 调色基准）、_R * 25（混合比例）、OSC 4（ANSI 槽位设置）、starship_precmd（提示符注入）、_update_iterm_title（标题联动）

安全检查（每次编辑 .zshrc 前必须执行）

在读取或编辑用户的 ~/.zshrc 前，必须扫描是否存在明文密钥/凭证：

grep -niE '(KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL|API_KEY)=' ~/.zshrc | grep -v '^#'

如果发现明文密钥：

1. 立即警告用户：告知哪一行存在风险
2. 建议迁移：将密钥移到独立文件（如 ~/.env.secrets），zshrc 中改为 source ~/.env.secrets
3. 设置权限：chmod 600 ~/.env.secrets
4. 不要在对话中展示密钥内容：只报告"第 X 行存在 XXX_KEY"，不输出值

Why：用户可能将 .zshrc 分享到 GitHub 或截图发社交媒体，明文密钥泄露后果严重。

依赖项

一键安装/卸载

项目提供了安装和卸载脚本，位于 GitHub 仓库：

bash install.sh   # 自动检测环境、安装依赖、注入配置
bash uninstall.sh  # 清理配置、还原 zshrc