LLM 终端自动化交互

自 v0.11 起可用

正如 Playwright 在 Web 自动化测试中所起的作用一样，LLM 要操作 TUI（文本用户界面），同样需要一个反馈闭环：观察终端当前的视觉状态、发送按键，并评估由此引发的状态变动。然而，常规的 CLI 执行方式在命令初次输出完成后便立即退出，无法交互式地操作诸如 vim、fzf 或交互式安装向导这类具备持续状态的应用程序。

console2svg session 通过在后台常驻守护进程来保持伪终端（PTY）会话，为 LLM 提供了一套基于 JSON 输入输出的编程式终端控制接口。 LLM 可以将屏幕文本缓冲区和渲染出的 SVG 快照作为“眼睛”，自主开展试错闭环，完成 TUI 布局微调与行为验证。

智能体前置配置

要让 LLM 智能体理解终端操作流程，请将预置的智能体指令书 SKILL.md 载入系统提示词中。智能体将遵循该指南调用下述基于 JSON 的子命令。

所有 console2svg session 子命令均以 JSON 格式向标准输出返回响应。这样可以确保 LLM 能够直接将执行状态和界面内容作为结构化数据进行精确判定，而无需依赖脆弱的正则表达式。失败时请根据 error.code 分支；error.message 和标准错误诊断面向用户，文字可能调整。

交互操作基本流程

LLM 操作会话的标准工作流分为 5 个阶段：启动、调屏、观测、输入、终止。

1. 启动会话

指定目标命令启动后台会话：

console2svg session start -- bash

启动成功后，命令将返回包含唯一 sessionId 的 JSON 对象。后续的所有交互操作均以此 ID 作为目标标识：

{
  "sessionId": "s_a1b2c3d4e5f6",
  "state": "running",
  "command": "bash",
  "width": 80,
  "height": 24,
  "createdAt": "2025-01-15T10:00:00Z"
}

2. 调整终端尺寸

多数 TUI 程序会根据终端的列数和行数动态改变排版。可使用 session resize 根据需求调整界面尺寸：

console2svg session resize s_a1b2c3d4e5f6 --width 120 --height 30

3. 观测终端状态

为确认应用程序对上一步输入的响应情况，可读取屏幕文本内容或捕获 SVG 图像：

# 立即读取当前屏幕文本
console2svg session read s_a1b2c3d4e5f6

# 等待文本出现，或等待曾经出现的文本消失
console2svg session wait s_a1b2c3d4e5f6 --text "Ready"
console2svg session wait s_a1b2c3d4e5f6 --text "Working" --until absent --stable-for 2s

# 将当前屏幕渲染结果保存为 SVG 图像
console2svg session capture s_a1b2c3d4e5f6 -o /tmp/current-screen.svg

# 无需指定输出路径的临时目视检查（Observation，不进入 Scenario 导出）
console2svg session inspect s_a1b2c3d4e5f6

session read 会立即返回当前屏幕纯文本、从 0 开始的光标坐标及可见状态、备用屏幕状态、滚动缓冲区行数和视口范围。添加 --structured 可获取包含单元格样式、超链接和宽字符信息的带版本数据。条件等待请使用 session wait --text <literal>；等待文本消失时，必须先观察到它出现。--stable-for 要求条件持续成立，--timeout 可选且没有最大限制。session capture 则导出包含颜色、字体样式的真实几何排版。session inspect 以相同渲染链路输出到按用户隔离的随机临时 SVG 并返回路径；仅需目视时用 inspect，需要持久化成果物时用 capture -o。多模态 LLM 可直接读取生成的 SVG 图片，分析是否存在布局变形或色彩对比度异常。 session list 默认显示正在启动或运行中的会话。使用 session list --all 可查找仍在保留期内的已退出或不可用会话；可确定时会显示 expiresAt。保留期内仍可通过 ID 读取或捕获。使用 session stop 显式停止的会话会被删除，之后无法再通过 ID 访问。

4. 发送按键输入

确认当前状态后，向终端发送下一步的按键序列：

# 发送普通字符串
console2svg session send s_a1b2c3d4e5f6 --text "git status"

# 发送 Enter 或方向键等特殊功能键
console2svg session send s_a1b2c3d4e5f6 --keys Enter

# 按指定顺序连续发送文本、粘贴内容和按键
console2svg session send s_a1b2c3d4e5f6 --text "i" --keys Enter --paste "hello" --keys Esc

--text、--paste、--keys 和 --raw-hex 可以重复指定，输入会按指定顺序发送。若要在应用启用时附加 bracketed paste 标记，请使用 --paste。语义方向键和小键盘按键会遵循应用选择的终端模式。发送完毕后，可再次调用 session read 检查界面是否如预期发生状态迁移。

5. 终止会话

全部交互流程结束后，应显式关闭后台常驻进程：

# 终止指定会话
console2svg session stop s_a1b2c3d4e5f6

# 批量终止所有运行中的会话
console2svg session stop --all --yes

终止会话后，守护进程将关闭 PTY、清理关联子进程，并释放 Unix 域套接字文件。