首页 / 全部技能 / 基础工具与工作流 / terminal-screenshot
English (EN)简体中文 (ZH)日本語 (JA)
基础工具与工作流 · daymade/claude-code-skills

terminal-screenshot

Render a terminal CLI program's colored output to a PNG so Claude can actually SEE the real visual result — color contrast, alignment, background blocks, highlighting — instead of only reading plain text and raw ANSI escape codes. Use this whenever verifying or debugging how a CLI tool looks in the terminal: delta git diff colors, bat syntax highlighting, starship prompt, eza/ls colors, git diff, ripgrep matches, or any ANSI-colored output. ALWAYS use it right after changing any CLI color config (delta / bat / themes / lazygit pager) to visually confirm the result rather than guessing from hex values — reading a hex code is not the same as seeing the rendered contrast on the real terminal background. Trigger phrases: 看终端效果, 终端截图, 验证配色, 配色对比, 终端真实效果, terminal screenshot, render terminal output, ANSI to image, "does this color look right", "is the contrast enough", delta/bat color verification.

L4 高权限 · 分级授权与审计V1 已固定执行命令联网读写文件Dual-pass Audit
Author daymadeGitHub daymade/claude-code-skills ↗Stars 1385License MIT（仓库根 LICENSE；GitHub API spdx MIT）Commit d5c4678cb5
管控等级描述 skill 的能力与建议配套的管控措施，不代表质量或安全认证，也不表示可用或不可用。是否使用由用户和管理者决定。不同 agent 宿主对权限的约束各不相同，请勿假定宿主一定会提供安全兜底。第三方 skill 版权归原作者，使用风险由使用者自行承担。

1实现原理 · 为什么它能做到

两步分离是核心 trick：先在被测 CLI 的真实 shell 里把全保真 ANSI 落成 .ansi 文件，再单独渲染成 PNG——绝不让渲染器替你执行命令，因为 freeze 的子 pty 会让 delta/lazygit 探测到降级环境而静默丢掉背景块/行号列/头框。

daymade-claude-code/terminal-screenshot/SKILL.md
The single most important rule: **never let the renderer run the command for you.**
SKILL 举反例：'`freeze --execute "git diff | delta"` looks convenient but produces a *degraded* result'。捕获侧给出每工具配方（delta/git/bat/eza/ls/rg + CLICOLOR_FORCE=1 / script -q /dev/null）。

渲染侧双层回退：render_ansi.sh 优先 freeze（charmbracelet，背景块/行号盒忠实），找不到则 python3 ansi2html.py（纯 stdlib 的 ANSI→HTML）+ 无头 Chrome 截图。

daymade-claude-code/terminal-screenshot/scripts/render_ansi.sh
# Prefers charmbracelet/freeze (faithful background blocks, line-number boxes, # window chrome). Falls back to a zero-dependency stdlib HTML renderer + # headless Chrome when freeze is not installed.
freeze 定位 PATH 后查 go env GOPATH/bin；Chrome 回退路径硬编码 macOS /Applications/Google Chrome.app，非 macOS 且无 freeze 时明确报错退出。

ansi2html.py 只处理真实 CLI 会发的 SGR 子集：24-bit truecolor(38;2;r;g;b/48;2;r;g;b)、256 色(38;5;n + xterm 调色板映射)、bold、reset(0/39/49)；关键是把背景色块（delta 的增删底色）保真下来，文本一律 html.escape 防注入。

daymade-claude-code/terminal-screenshot/scripts/ansi2html.py
Background color blocks (48;...) are preserved faithfully — that is the whole point, since tools like delta encode add/remove as background blocks.
渲染循环里 `esc = H.escape(p)` 再包 span——ANSI 文本里的任何 HTML 都先被转义，产出页面无脚本注入面；xterm256 映射有独立实现（base 16 + 232 灰阶 + 6×6×6 立方）。

背景色必须匹配真实终端，否则深色主题在白底上误判对比度；SKILL 给 macOS Ghostty 取背景命令与常见默认值（#282c34/#1d1f21）。

daymade-claude-code/terminal-screenshot/SKILL.md
**Background color must match the real terminal**, or a dark theme verified on a white page looks wrong.
render_ansi.sh 第三参 bg_hex 默认 #282c34；'Pass it as `#282c34`.'

TUI 程序（lazygit/htop/top）被显式划出范围：它们用光标定位画全屏，不是线性 ANSI 流，无法用此法捕获；验证其颜色要拆出底层（如 lazygit 的 diff 走 delta 配置）。

daymade-claude-code/terminal-screenshot/SKILL.md
## TUI programs (lazygit, htop, top) — out of scope
这是能力边界声明而非缺陷：告诉 agent 什么情况该换 screencapture/computer-use 路线，防止硬套。

渲染结果由 agent 用 Read/图像工具读回做视觉判断——把『十六进制猜色』换成『看真实渲染的对比度/对齐/背景块』。

daymade-claude-code/terminal-screenshot/SKILL.md
Then read the PNG with the Read tool and judge the colors.
SKILL 用途定位：'ALWAYS use it right after changing any CLI color config (delta / bat / themes / lazygit pager) to visually confirm the result rather than guessing from hex values'。

2核心能力

01把任意 ANSI 着色 CLI 输出渲染成 PNG（delta/git/bat/eza/ls/rg 等），供视觉判定配色
02渲染前捕获的每工具配方表（含非 TTY 强制着色：--color=always / CLICOLOR_FORCE=1 / script -q /dev/null）
03freeze→Chrome 双层回退渲染（freeze 缺失自动降级零依赖路径）
04忠实还原背景色块/24-bit truecolor/256 色的 stdlib ANSI→HTML 转换器
05freeze 安装指引（避开同名 GUI cask：用 charmbracelet tap 或 go install + GOPROXY 镜像/GOSUMDB=off）

3外部依赖

KindDependency / Endpoint
clifreeze（charmbracelet/freeze，首选渲染器，可选）
cliGoogle Chrome（无头模式，回退渲染路径；路径硬编码 macOS）
clipython3（ansi2html.py 运行环境，纯 stdlib）
cligo/brew（仅安装 freeze 时的可选项）

4管控建议与判定依据

建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
  • scripts/: 执行本地脚本或命令: render_ansi.sh（bash，set -euo pipefail）：执行 freeze 或 python3 ansi2html.py + G
  • 网络端点: 声明外部网络访问: 无（脚本零网络调用；freeze 的安装命令属用户主动操作且可走 go module 镜像）
  • 本地工作目录: 文件读写与工件输出: 按用户给定路径写 output.png（及回退路径的中间 output.html）；输入 .ansi 由用户在捕获步骤自行写到 /tmp 等
审计说明： 。自带 stdlib/本地脚本，无网络外发、无凭证读取；渲染链为本地 freeze 或本地 Chrome 无头渲染本地文件。注意点：回退路径用 Chrome --no-sandbox（安全降级 flag，但对象是 html.escape 过的本地 HTML，无脚本注入链），Chrome 路径硬编码 macOS（非 macOS 需 freeze 否则显式报错）。

5第二遍独立确认

  • [ok] 文本是否先转义再进 HTML（防注入） — ansi2html.py 'esc = H.escape(p)' 后拼入 span/裸文本；输出文档无其他用户可控拼接。
  • [ok] Chrome --no-sandbox 与降级面 — render_ansi.sh 回退路径含 --no-sandbox；渲染对象为本地生成、已转义的 HTML；freeze 存在时该路径不触发。
  • [ok] 无网络外发/凭证读取 — 两脚本无 curl/wget/http/url/env 密钥访问；go install 仅出现在 SKILL.md 安装指引（用户主动）。
  • [ok] SKILL 声称的每工具捕获配方 — 配方表为文档层指引（agent 在 shell 执行），脚本不含这些 CLI 调用，无隐藏依赖。
  • [ok] TUI 边界声明与实现一致 — SKILL 明确 TUI 光标定位无法线性捕获；脚本只处理线性 ANSI 流输入。
  • [unlocatable] freeze/Chrome 实际渲染保真度 — 依赖外部渲染器行为（背景块/行号盒/字体度量），本环境未实装 freeze/Chrome，未做端到端截图验证。

6结论

  • 解决真实盲区：让 agent『看见』终端颜色而非读十六进制与原始转义码
  • 两步分离防降级的设计判断准确（子 pty 探测是 delta/lazygit 等真实陷阱）
  • 回退链与边界声明让它在缺 freeze/非 macOS 上仍可预期工作或明确失败
  • 注入面在实现层被处理（html.escape + 只认 m 结尾 SGR），不是靠运气
    • 适合： 适合 CLI 配色/主题验证与调试工作流：delta/bat/starship/eza/ls/rg 改完颜色后立刻渲染确认；适合 agent 视觉 QA 需要『终端里人眼看到的效果』的场合；适合装得起 freeze 或 macOS+Chrome 的用户。
    不适合： 不适合全屏 TUI（lazygit/htop）截图（应走真实终端截屏/computer-use）；不适合无 freeze 且非 macOS 的环境（回退路径不可用）；不适合需要交互式终端会话捕获而非单条输出渲染的场景。
    Install Agent-Ready
    ① Verified Mirror 2026-09-09
    Option A · Direct DownloadDownload terminal-screenshot.tar.gz
    sha256: f71128c440db3c5b…
    Option B · Copy Guide for Agent
    install.json
    agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit d5c4678cb5.