AI导哈

终端AI控制工具

Imprint 是一个允许AI代理通过MCP协议控制终端并进行TUI测试的工具，提供真实的终端环境和像素级屏幕截图功能。

  • by kessler-frost
  • Go
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 kessler-frost/imprint

使用说明

imprint

Lets AI agents control a terminal and see what's on screen via MCP, allowing precise TUI testing.

概述

Imprint提供了一个AI代理可以编程控制的真实终端。代理可以随时请求终端的屏幕截图，让他们能够精确地看到用户会看到什么。

这让代理可以像真实用户一样进行测试——与终端交互，查看屏幕上的实际内容，而不管应用程序是如何构建的。TUI测试变得与框架无关，允许您测试任何终端应用程序，而无需学习或使用其内部测试策略。

它是如何工作的：

  • ttyd：Web终端守护进程通过WebSocket暴露真实的PTY
  • 终端复用器：终端多路复用器支持AI和用户之间的会话共享
  • 加油杆：用于键盘输入和屏幕截图的无头Chrome自动化
  • xterm.js：在Chrome中运行的终端模拟器，用于像素完美渲染

特性

  • MCP本地：通过stdio协议直接集成Claude代码
  • 真实终端：实际的shell执行，而不是模拟
  • 像素完美截图：这正是你在真实终端中看到的
  • 框架不可知：在没有框架特定工具的情况下测试任何TUI应用程序
  • 实时会话共享：通过浏览器观看AI实时控制终端

安装

curl -fsSL https://raw.githubusercontent.com/kessler-frost/imprint/main/install.sh | sh

这将安装印记及其依赖项（ttyd和tmux）（如果尚未安装）。

卸载

curl -fsSL https://raw.githubusercontent.com/kessler-frost/imprint/main/install.sh | sh -s -- --uninstall

手动安装

如果您更喜欢手动安装：

  1. 安装ttyd和tmux：

    # macOS
brew install ttyd tmux

# Ubuntu/Debian
sudo apt install ttyd tmux

# Arch Linux
sudo pacman -S ttyd tmux

  2. 从下载印记 发布 或者：

    go install github.com/kessler-frost/imprint/cmd/imprint@latest

用法

Imprint旨在由Claude Code作为MCP服务器启动。请参阅下面的配置。

手动测试

# Run imprint directly (MCP on stdio)
imprint

# Options
imprint --help
  --shell   Shell to run (default: $SHELL)
  --rows    Terminal rows (default: 24)
  --cols    Terminal columns (default: 80)
  --version Print version and exit

MCP服务器（克劳德代码）

添加印记作为MCP服务器：

claude mcp add imprint -- ~/.local/bin/imprint

使用自定义终端尺寸：

claude mcp add imprint -- ~/.local/bin/imprint --rows 30 --cols 120

可用工具

  • send_keystrokes -发送按键（例如。， ["enter"], ["up", "up", "enter"])
  • type_text -键入字符串
  • get_screenshot -以base64 JPEG格式获取屏幕
  • get_screen_text -以纯文本形式获取屏幕
  • get_status -获取终端状态
  • get_ttyd_url -获取web URL和tmux附加命令以查看代理正在使用的终端
  • resize_terminal -调整终端大小
  • restart_terminal -重新启动终端（可选地使用新命令）
  • wait_for_text -等待文本出现在屏幕上（默认超时5秒）
  • wait_for_stable -等待屏幕停止变化（500毫秒稳定持续时间）

实时观看AI

imprint的一个独特功能是能够在浏览器中实时观看AI代理对终端的控制。您和AI共享相同的tmux会话。

要查看终端：

  1. 让AI打电话 get_ttyd_url
  2. 通过以下任一方法连接：
    • 浏览器：打开网络URL（例如。， http://127.0.0.1:55529)
    • 终端：运行tmux附加命令（例如。， tmux attach -t imprint_55529)
  3. 观察AI键入命令并导航终端

您还可以通过浏览器与终端进行交互，人工智能将实时看到您的更改。这有助于：

  • 调试：看看AI到底看到了什么
  • 协作：当AI陷入困境时帮助它
  • 德莫斯：向其他人展示AI代理如何与终端交互

例子

这 examples/ 目录包含用于测试印记的演示应用程序：

屏幕截图演示

泡泡茶TUI 需要屏幕截图分析的视觉元素:

  • 随机颜色：启动时随机选择彩色方块-显示文本提取 ████ 但屏幕截图显示了实际颜色
  • 视觉缺陷：只能通过屏幕截图检测到的故意渲染问题（标题错位、颜色渗出、对比度差）

这说明了为什么 get_screenshot 有价值——有些东西只能通过实际操作来验证 看见 终端。

文本演示

一个使用ASCII字符的简单的基于文本的TUI。适合测试 get_screen_text 以及基本的键盘导航。

发生了什么变化

一款视觉记忆游戏，旨在展示印记的截图功能。游戏显示了一个彩色单元格网格，然后更改了一个单元格——玩家必须确定更改了哪个单元格。非常适合测试AI代理检测屏幕截图之间视觉差异的能力。

测试

单元测试（Go）

go test ./...

端到端测试（Python）

这 tests/ 该目录包含端到端测试，用于验证印记是否与真实的AI代理正常工作。这些测试使用 Claude 代码 SDK 生成Claude，然后Claude使用imprint的MCP工具与示例TUI进行交互。

为什么是Python？ Claude Code SDK仅在Python和TypeScript中可用。由于目标是从AI代理的角度测试印记（而不仅仅是Go代码的单元测试），我们使用SDK让Claude实际控制终端，并验证它是否可以完成导航菜单、切换复选框和识别视觉错误等任务。

cd tests
uv sync        # Install dependencies
uv run pytest  # Run all tests

单个测试文件：

  • test_text_demo.py -测试基于文本的导航和交互
  • test_screenshot_demo.py -通过屏幕截图测试视觉错误检测
  • test_what_changed.py -测试内存游戏的屏幕截图比较

建筑

flowchart TB
    subgraph imprint
        MCP["MCP Server<br/>(stdio)"]
        TM["Terminal Manager<br/>(go-rod + ttyd)"]
        TMUX["tmux session<br/>(shared terminal)"]
        TTY["ttyd + Chrome/xterm<br/>(real PTY + render)"]

        MCP --> TM
        TM --> TTY
        TTY --> TMUX
    end

    Claude["Claude Code"] -->|"JSON-RPC over stdio"| MCP
    Browser["Your Browser"] -->|"WebSocket via ttyd"| TMUX

AI和浏览器连接到同一个tmux会话，实现实时协作。

贡献

欢迎投稿！我在空闲时间处理印记，所以回复可能需要一段时间，但我很感激所有的公关和问题。

许可证

Apache 2.0

相关 MCP