mcpField
T
terminal-screenshot

terminal-screenshot

github.com/daymade测试与质量1.5k438 次安装今天更新
代码仓库

关于 terminal-screenshot

将终端命令的彩色 ANSI 输出渲染为 PNG 的技能，供需要视觉检查命令行主题或差异对比效果的人使用。它先保存完整色彩输出，再单独渲染，避免子进程运行环境导致颜色降级。

主要功能

  1. 01捕获完整色彩 ANSI 输出
  2. 02将 ANSI 文件渲染为 PNG
  3. 03支持 truecolor 与 256 色
  4. 04按真实终端背景检查效果

适用场景

  1. 01检查 Git diff 增删行对比度
  2. 02评估命令行主题的明暗效果
  3. 03确认终端输出的颜色块和排版

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/daymade/claude-code-skills --skill terminal-screenshot

安装后在 Claude Code 中输入/terminal-screenshot确认已加载。

附带文件scripts/ansi2html.pyscripts/render_ansi.sh

详细介绍

终端截图

将终端命令的彩色输出渲染成 PNG 图片，然后读取图片，以视觉方式判断结果。

为什么需要这个工具

当命令输出作为工具结果返回时，Claude 看到的是纯文本和原始转义码，例如 \x1b[48;2;92;30;34m，而不是渲染后的颜色。因此，无法诚实地回答“差异中新增和删除内容的对比度够强吗？”或“这个主题是不是太暗了？”。读取十六进制值只能靠猜。此技能会将输出转换为图像，让判断依据是人们在屏幕上实际看到的内容。

方法：先捕获，再渲染

分为两个独立步骤。保持这两个步骤分开——这正是整个技巧的关键。

步骤 1 — 将完整保真的 ANSI 输出捕获到文件

大多数 CLI 检测到输出目标不是真正的终端（例如管道或子进程）时，都会关闭或降低颜色效果。强制启用完整着色，并保存到 .ansi 文件。具体标志取决于工具，以下提供了相应命令。

最重要的一条规则：绝不要让渲染器替你运行命令。freeze --execute "git diff | delta" 看起来很方便，但会生成效果欠佳的结果——delta（以及 lazygit 和其他会探测终端功能的程序）会在 freeze 的子 pty 中运行，检测到环境受限后，便会悄悄关闭背景色块、行号列和标题框。先在普通 shell 中捕获，再进行渲染。

步骤 2 — 将 ANSI 文件渲染为 PNG，然后读取

使用随附的包装脚本，它会优先使用 freeze，并在不可用时回退到标准库渲染器和无头 Chrome：

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

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

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

ghostty +show-config --default | grep '^background'   # e.g. 282c34 (the default)

将其设为 #282c34。如果不清楚，深色终端通常接近 #1d1f21–#282c34。

各工具的捕获命令

选择接近真实终端的 --width（≈100–120），以便换行效果一致。

工具捕获命令（写入完整彩色 ANSI 输出）
delta（git diff）git --no-pager diff | delta --dark --line-numbers --width=110 > /tmp/x.ansi
git diff（原生）git -c color.ui=always --no-pager diff > /tmp/x.ansi
batbat --color=always --style=numbers <file> > /tmp/x.ansi
ezaeza -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
ripgreprg --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 时唯一要注意的就是步骤 1 中的规则（不要通过 freeze --execute 渲染）。

完整示例：验证 delta 颜色变更
# after editing [delta] colors in gitconfig, in any repo with a 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"
# then: Read /tmp/diff.png and judge whether add/remove contrast is clear

TUI 程序（lazygit、htop、top）——不在适用范围内

全屏 TUI 使用光标定位绘制界面，而不是生成线性 ANSI 流，因此无法通过这种方式捕获。若要检查 TUI 的颜色，请单独验证底层部分——例如，对于 lazygit 的差异视图，可按上述方式渲染 git diff | delta（lazygit 调用的是同一套 delta 配置）。若要获取真正的 TUI 截图，请在真实终端中运行程序并捕获屏幕（使用截屏或计算机操作任务），而不是使用此技能。

安装 freeze（推荐的渲染器）

freeze 是 charmbracelet/freeze——它可以将 ANSI 渲染为 PNG/SVG/WebP，忠实呈现背景色块，并提供美观的窗口装饰。

不要运行 brew install freeze——它安装的是一个同名但无关的 GUI 应用（一个 cask）。CLI 可通过 charmbracelet 的 tap 或 go install 安装：

# Option A — Homebrew tap (needs GitHub reachable)
brew install charmbracelet/tap/freeze

# Option B — go install (works behind a firewall via a Go module mirror)
GOPROXY=https://goproxy.cn,direct GOSUMDB=off \
  go install github.com/charmbracelet/freeze@latest
# binary lands in "$(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）。这是入口点；请在步骤 1 后调用。
  • scripts/ansi2html.py — 回退路径使用的标准库 ANSI→HTML 转换器。支持 24 位真彩色、256 色、粗体和重置，并保留背景色块（朴素渲染器会丢弃的部分）。

常见问题

  • 让渲染器运行命令（freeze --execute "delta …"）→ 输出质量下降。先在普通 Shell 中捕获，再渲染文件。
  • 非 TTY 会剥除颜色 → 强制启用颜色（--color=always / CLICOLOR_FORCE=1 / script -q /dev/null）。
  • 背景颜色错误 → 在白色页面上渲染深色 CLI 主题会导致对比度判断失准。请使用终端的实际背景色。
  • 明暗模式不匹配 → 如果终端为深色，CLI 颜色也必须使用深色变体。在深色终端中验证 light=true 配置会显示反转且难以辨认的颜色（这本身就是问题所在，而不是渲染器的过错）。
  • brew install freeze 会安装错误的工具（GUI cask）——请使用 tap 或 go install。

评论

支持 Markdown