lokkju/term-recorder

term-recorder 是做什么的？

term-recorder 在一个固定大小的终端中运行命令，通过步骤驱动它，并捕获其显示内容。当你要问“它在屏幕上看起来什么样”而阅读代码无法回答时使用它：例如对话框如何对长文本换行，Markdown 是否渲染，TUI 在 100 列下如何显示，点击位置在哪里。

它在自己的 tmux 服务器（tmux -L term-record-<pid>，使用生成的配置，没有状态行）和最小化环境中运行命令，因此不会触及用户的 tmux 会话，命令也不会继承本会话的变量。运行结束后服务器会被终止。

运行它

调用 record 工具（即 term-recorder MCP 服务器提供的工具；在 Claude Code 中为 mcp__plugin_term-recorder_term-recorder__record），参数如下：

• command：程序及其参数构成的列表，例如 ["claude", "--model", "haiku"]。
• steps：内联步骤，每行一个（见下文），或者使用 steps_file 指定步骤文件；两者都会先运行文件。步骤中的 ${EXAMPLES} 指向捆绑的示例目录。
• cwd：命令的起始工作目录（默认为项目目录）。内联步骤中的 include 和 paste 路径相对于此目录。
• out：快照的输出目录（默认为新建的临时目录）；该目录会被创建。

每个 snap NAME 会写入 <out>/NAME.txt，并且在运行结束时始终会截取一次最终屏幕快照，命名为 final。返回结果是每个快照的屏幕文本，以及快照存放的路径；读取它们即可得到答案。show: "final" 只返回最终屏幕，show: "none" 则不返回任何屏幕（文件仍会写入）。snaps 工具可以列出之前运行产生的快照，或按名称读取某个快照。如果某一步失败（等待超时、待点击的文本未出现在屏幕上、命令退出等原因），结果会是一个错误，指明步骤名称并显示当时的屏幕状态。

check_steps 可以用来解析步骤而不实际执行任何操作，这对于在真正消耗 Claude Code 对话配额之前进行低成本验证非常有用。

默认设置：100x30 终端尺寸（size），TERM 为 screen-256color，仅从服务器环境中继承 HOME、PATH、USER、LOGNAME、SHELL、LANG、LC_ALL、LC_CTYPE 和 TMPDIR。可以通过 env（对象形式）或 pass（变量名列表）添加环境变量，通过 vars 添加步骤替换变量。

不使用 MCP 服务器

在没有 MCP 服务器的代理中，可以直接通过 CLI 运行同一套代码。将步骤写入你的临时目录中的文件，然后作为独立的命令运行（不要通过管道连接其他命令）：

"${CLAUDE_SKILL_DIR}/scripts/term-record" -C <工作目录> -s <步骤文件> -o <输出目录> -- <命令> [参数...]

${CLAUDE_SKILL_DIR} 是保存此 SKILL.md 的目录。Claude Code 会自动填充它；如果代理中该变量未被替换，请替换为对应的实际路径。快照会同时输出到 stdout 和 <输出目录>。退出码 1 表示某一步骤失败，屏幕内容会输出到 stderr；退出码 2 表示用法或设置问题。命令行标志与工具参数对应：--size、--env NAME=VALUE、--pass NAME、--var NAME=VALUE、--cast、--gif、--agg-arg，以及从 stdin 读取步骤的 -s -。

步骤

每行一个步骤，遵循 Shell 引号规则，# 表示注释：

步骤	说明
wait REGEX [TIMEOUT]	等待直到屏幕匹配（Python re，多行模式；超时 90 秒）
gone REGEX [TIMEOUT]	等待直到不再匹配
idle REGEX [QUIET] [TIMEOUT]	等待直到 REGEX（忙碌标记）连续 QUIET 秒（默认 3 秒）未出现（总超时 240 秒）
keys KEY...	发送 tmux 按键名称：Enter、Down、Escape、C-c
type TEXT [DELAY]	逐字输入 TEXT，每个字符间隔 DELAY 秒（默认 0.03；设为 0 则立即发送）
paste FILE	将 FILE 作为一次括号粘贴内容粘贴，适合多行提示
click TEXT	在屏幕上左键单击第一个出现的 TEXT
sleep SECONDS	休眠指定秒数
snap NAME	捕获当前屏幕文本作为快照
resize COLSxROWS	在运行中改变终端尺寸；每次调整后使用 snap 来观察布局变化
record on|off	打开或关闭投屏帧录制
include FILE	原地执行 FILE 中的步骤
when REGEX STEP...	仅当当前屏幕匹配 REGEX 时执行 STEP

include 和 paste 中的路径相对于步骤文件（对于内联步骤，则相对于 cwd）。

以 Claude Code 为目标

使用 include ${EXAMPLES}/claude-start.steps 可以启动一个全新的会话，跳过文件夹信任对话框直达空提示；请将其放在最前面。${EXAMPLES}/ask-dialog.steps 是一个完整的示例，会打开提问对话框并截取快照。

• 在临时目录（cwd）中启动它，使用便宜的模型（--model haiku），除非模型本身很重要；并在 env 中添加 DISABLE_AUTOUPDATER=1，以免更新提示出现在帧中。
• 要测试某个插件的代码，添加 --plugin-dir <路径>，并通过 --settings <文件> 关闭已安装的副本（设置 "enabledPlugins": {"<名称>@<市场>": false}）。
• 在 Claude 5 模型上，无论是交互模式还是 -p，任务工具（TaskCreate 等）默认都是关闭的，除非在 env 中设置了 CLAUDE_CODE_ENABLE_TODO_TOOLS=1。自 Claude Code 2.1.300 起，--model haiku 对应 Haiku 5.5，因此也包括该情况。即便如此，它们也只是延迟工具：出现在延迟工具列表中，通过 ToolSearch 加载，而不是初始工具列表。
• 你的提示会回显在屏幕上，所以请等待只会在结果中出现的文本（例如对话框中的编号选项，如 '[0-9]\. Accept'），绝不要等待提示本身中的词语。
• 它的忙碌标记（用于 idle 步骤）为：'\([0-9]+m? ?[0-9]*s · |esc to interrupt'。
• 每次运行都是用户账户上的真实对话。请只执行检查所需的交互轮次。

录制

cast 会写入一个 asciicast v2 文件，gif 会通过 agg 渲染成 GIF（agg_args 可以替换其参数）；结果会同时返回两个路径。帧在屏幕发生变化时捕获；在 idle 等待期间，投屏的时钟会以八分之一速度运行（busy_timescale），因此一分钟的思考时间只需几秒即可播放。