SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场terminal-screenshot

terminal-screenshot

编程与开发

查看项目

更新于 10-15 14:11

技能介绍

用途

Terminal Screenshot 用于把终端命令的彩色输出渲染成 PNG 图像，然后读取该图像，以人眼实际看到的效果来判断配色结果。

它存在的理由：当命令输出作为工具结果返回时，Claude 看到的是纯文本加上原始转义码，例如 \x1b[48;2;92;30;34m，而不是渲染后的颜色。这使得它无法诚实回答“diff 的增删对比是否足够强”或“这个主题是不是太暗了”这类问题。读取十六进制值只是在猜测。该技能把输出变成图像，让判断基于人类在屏幕上真正会看到的内容。

主要能力

  • 将终端命令的全保真 ANSI 彩色输出捕获为 .ansi 文件。
  • 将 .ansi 文件渲染为 PNG 图像，优先使用 freeze，回退到标准库渲染器加无头 Chrome。
  • 支持 24 位真彩色、256 色、粗体和重置，保留背景色块。
  • 提供针对 delta、git diff、bat、eza、ls、ripgrep 等工具的捕获配方。

使用方式

方法分为两个独立步骤，保持分离是关键。

第一步：将全保真 ANSI 捕获到文件

大多数 CLI 在检测到不是写入真实终端（管道或子进程）时会丢弃或降级颜色。需要强制完整着色并保存到 .ansi 文件。具体标志取决于工具，配方如下。

最重要的一条规则：绝不要让渲染器替你运行命令。freeze --execute "git diff | delta" 看起来方便，但会产生降级结果——delta（以及 lazygit，以及任何探测终端能力的程序）在 freeze 的子 pty 中运行，检测到受限环境，会静默丢弃背景块、行号列和头部框。先在普通 shell 中捕获，再渲染。

第二步：将 ANSI 文件渲染为 PNG，然后读取

使用捆绑的包装脚本，它优先使用 freeze，回退到标准库渲染器加无头 Chrome：

scripts/render_ansi.sh <input.ansi> <output.png> [background_hex]

然后用 Read 工具读取 PNG 并判断颜色。

背景色必须与真实终端一致，否则在白色页面上验证的暗色主题看起来会不对。在 macOS 上使用 Ghostty 时：

ghostty +show-config --default | grep '^background'   # 例如 282c34（默认值）

将其作为 #282c34 传入。如果未知，暗色终端通常接近 #1d1f21–#282c34。

各工具的捕获配方

选择接近真实终端的 --width（约 100–120），以便换行匹配。

工具 捕获命令（写入全彩 ANSI）
delta (git diff) `git --no-pager diff
git diff (原生) git -c color.ui=always --no-pager diff > /tmp/x.ansi
bat bat --color=always --style=numbers <file> > /tmp/x.ansi
eza eza -la --color=always --icons > /tmp/x.ansi
ls (GNU) ls -la --color=always > /tmp/x.ansi
ls (macOS/BSD) CLICOLOR_FORCE=1 ls -laG > /tmp/x.ansi
ripgrep rg --color=always 'pattern' <path> > /tmp/x.ansi
其他 CLICOLOR_FORCE=1 <cmd> > /tmp/x.ansi 或 <cmd> --color=always，或用真实 pty 包装：script -q /dev/null <cmd>

注意：delta 即使输出到文件也总是发出其配置的颜色，所以 delta 唯一的陷阱是第一步的规则（不要通过 freeze --execute 渲染它）。

完整示例：验证 delta 颜色更改

# 在 gitconfig 中编辑 [delta] 颜色后，在任意有 diff 的仓库中：
git --no-pager diff | delta --dark --line-numbers --width=110 > /tmp/diff.ansi
scripts/render_ansi.sh /tmp/diff.ansi /tmp/diff.png "#282c34"
# 然后：Read /tmp/diff.png 并判断增删对比是否清晰

TUI 程序（lazygit、htop、top）——超出范围

全屏 TUI 使用光标定位绘制，而不是线性 ANSI 流，因此无法用这种方式捕获。要检查 TUI 的颜色，请单独验证底层部分——例如对于 lazygit 的 diff，按上述方式渲染 git diff | delta（lazygit 调用相同的 delta 配置）。要获得真正的 TUI 截图，请在真实终端中运行并捕获屏幕（screencapture/computer-use 任务），而不是使用此技能。

安装 freeze（首选渲染器）

freeze 是 charmbracelet/freeze——它将 ANSI 渲染为 PNG/SVG/WebP，具有忠实的背景块和美观的边框。

不要运行 brew install freeze——那会安装同名的无关 GUI 应用（一个 cask）。CLI 位于 charmbracelet 的 tap 中，或通过 go install：

# 选项 A — Homebrew tap（需要能访问 GitHub）
brew install charmbracelet/tap/freeze

# 选项 B — go install（可通过 Go 模块镜像在防火墙后工作）
GOPROXY=https://goproxy.cn,direct GOSUMDB=off \
  go install github.com/charmbracelet/freeze@latest
# 二进制文件位于 "$(go env GOPATH)/bin/freeze"

当校验和数据库（sum.golang.org）不可达且 go install 卡在“verifying module ... 504”时，需要 GOSUMDB=off。

如果无法安装 freeze，包装脚本会自动回退到捆绑的 scripts/ansi2html.py（仅标准库）加无头 Chrome——除了 Chrome 安装外无需额外依赖。回退使用固定窗口大小；如果输出被裁剪，请加宽 render_ansi.sh 中的 --window-size。

捆绑脚本

  • scripts/render_ansi.sh — 将捕获的 .ansi 文件渲染为 PNG（freeze，否则 Chrome 回退）。这是入口点；在第一步之后调用它。
  • scripts/ansi2html.py — 回退路径使用的标准库 ANSI→HTML 转换器。处理 24 位真彩色、256 色、粗体和重置，保留背景色块（朴素渲染器会丢弃的部分）。

适用场景

  • 在更改任何 CLI 颜色配置（delta/bat/主题/lazygit 分页器）之后立即使用。
  • 验证 diff 的增删对比是否足够清晰。
  • 检查主题是否过暗或过亮。
  • 验证 delta、bat、eza、ls、ripgrep 等线性输出工具的配色。

限制

  • 全屏 TUI 程序（lazygit、htop、top）无法用此方式捕获，因为 TUI 使用光标定位绘制而非线性 ANSI 流。
  • 绝不能让渲染器运行命令（如 freeze --execute），否则输出会降级。
  • 非 TTY 会剥离颜色，必须强制着色。
  • 背景色必须与真实终端一致，否则对比判断会出错。
  • 明暗主题必须匹配：如果终端是暗色，CLI 颜色必须是其暗色变体。
  • brew install freeze 会安装错误的 GUI cask 工具，应使用 tap 或 go install。