SmartCLI — drive terminal TUIs

SmartCLI

阅读其他语言版本：English · 简体中文 · 繁體中文 · 日本語 · 한국어

一款本地 Python 工具包，用于驱动、感知和渲染终端——三个 Agent Skill 共用一个可插拔的 PTY + pyte 核心。

让 AI 驱动、感知并渲染真实的终端程序。 SmartCLI 使用 pyte 单元格模型读取真实屏幕——而不是字节管道——因此它能识别高亮的菜单行，按下正确的按键，并等待屏幕稳定下来。下方演示：它端到端驱动真实的 lazygit TUI（使用方向键导航、打开提交差异、突出显示分支）——无需脚本，也不使用模拟环境。

pip install smartcli-toolkit

需要 Python 3.10 或更高版本。安装包包含共享 Python 库、持久化 TUI 驱动程序和 stdio MCP 服务。

30 秒内驱动一个程序

复制并粘贴此代码。它会在 PTY 下启动一个真实的 Python REPL，等待提示符出现（绝不盲目使用 sleep），向其中输入内容，然后读取屏幕：

pip install smartcli-toolkit
SID=$(smartcli-tui start --cmd "python3 -i -q" --cols 80 --rows 24 --json | python3 -c "import json,sys;print(json.load(sys.stdin)['sid'])")
smartcli-tui wait-regex --id $SID ">>> " --timeout-ms 15000
smartcli-tui send-line --id $SID "print(6*7)"
smartcli-tui wait-regex --id $SID "42"          # prints the cell grid it sees
smartcli-tui close --id $SID

在 Windows 上使用 --cmd "py -i -q"。将命令替换为 vim、htop 或 lazygit，同样的五个动词也能驱动它们——这正是关键所在： wait-regex 等工具会根据屏幕上的实际内容作出响应，因此 Agent 不会猜测按键是否生效。

想要用真实编辑器端到端完成操作，并验证结果？ examples/drive_vim.py 会驱动真正的 vim 二进制文件——打开文件、追加一行、保存，然后检查文件系统，而不是屏幕：

python examples/drive_vim.py
#   [OK ] vim painted its screen
#   [OK ] file contents visible on screen
#   [OK ] alternate screen is active
#   [OK ] vim entered insert mode (so G and o both landed)
#   [OK ] typed text appears on screen
#   [OK ] vim restored the main screen on exit
#   [OK ] file on disk really changed

注意第四步。之所以要加这一步，是因为这个示例本身曾连续发送五个按键，中间毫无间隔；在负载较高时，o 到达时 vim 还没处理完 G，因此没有插入任何内容，运行也失败了，却没有给出有用的诊断信息。确认进入插入模式，能证明两个按键都已生效——这正是该工具旨在提供的严谨操作方式，也应用到了它自己的演示中。

用 smartcli-toolkit==0.1.8 运行同一个文件，会有两个步骤失败——而且文件永远不会保存，因为无法识别备用屏幕的驱动程序会错误判断何时执行 :wq。这就是下文模拟工作的重要性：错误的屏幕模型不会报错，只会悄无声息地一无所成。

已经在运行 MCP 客户端（Claude Code、Cursor、VS Code）？同样的动词也可作为 MCP 工具使用，并会自动附加每个会话的令牌：

smartcli-mcp        # stdio MCP server; or `uvx --from smartcli-toolkit smartcli-mcp`

内容与原因

SmartCLI 是一个用于终端工作的工作区，供 Agent 和人类共同使用：驱动交互式终端程序，感知屏幕实际显示的内容，并渲染视觉效果和布局。它基于一个共享、可插拔的 PTY 后端和一个 pyte 屏幕模型构建——相比截图或视觉识别，我们选择了这种方案，因为同一个结构化屏幕模型既能用于感知（读取屏幕），也能用于渲染（绘制屏幕）。PTY 层有意不绑定 tmux：本地开发可通过 ConPTY（pywinpty）在 Windows 上运行，而目标程序也可以在其他环境的 POSIX pty 或 tmux 下运行。基于这一核心提供三项技能，每项都是可在项目检出目录中就地运行的独立工具。

驱动真实的 TUI

上方的演示展示了 SmartCLI 如何驱动 lazygit——一个真实的全屏 curses 应用——通过“感知 → 操作 → 确认”循环工作：读取 pyte 单元格网格（选中的是哪一行、备用屏幕上的差异），使用方向键移动，打开某条提交的差异，并高亮显示一个分支。该演示是在 Linux 容器中驱动实际程序捕获的，并非脚本模拟或伪造。像 pexpect 这样的字节流匹配器无法感知“哪一行被高亮”；屏幕模型可以。

我们如何确认感知结果正确。 屏幕模型只有在与真实终端显示内容一致时才有用，因此我们会进行测量，而不是仅凭断言：将相同字节发送到真实的 tmux 窗格和我们的模型，然后对两个单元格网格进行差异比较。我们通过三个测试套件验证：34 个精选案例、一项只有在 tmux 和 GNU screen 都一致时才认可行为的三方检查，以及针对随机 VT 序列的生成式模糊测试。该测试活动发现并修复了 12 个仿真错误，其中包括备用屏幕缓冲区问题（pyte 未实现 1049/1047/47 模式，因此全屏程序的输出过去会覆盖主屏幕，且无法恢复）。适用范围和剩余问题： LIMITATIONS.md。

实时效果

cmd-art fx 引擎的真实录制效果——每个 GIF 都是通过项目自有管线逐帧渲染的实际效果（未使用屏幕录制软件）。运行 python -m fx play <name> 即可重现任意效果（参见快速入门）。

_{solarsystem — 太阳系仪：行星沿椭圆轨道围绕脉动的太阳运行}

donut — 经典 ASCII 环面	fire — 演示场景热场	rain — Matrix 数字雨

🌐 探索实时展示 → — 体验效果引擎，用方向键操作菜单，并在浏览器中试用这些小组件。

安装

只想要三个 Claude Code 技能？ 下载一个 zip，解压即可——无需 git、pip 或市场：

curl -LO https://github.com/dwgx/SmartCLI/releases/latest/download/smartcli-skills.zip

unzip smartcli-skills.zip -d ~/.claude/skills/

这会为你提供 cmd-art、drive-tui 和 tui-ui（总计 309 KiB）。cmd-art 和 tui-ui 只需 CPython 3.10+ 即可运行——已在空白虚拟环境中验证， 全部 30 种效果和 17 个组件均可加载。drive-tui 还需要 pyte，可通过 下方的 PyPI 安装方式安装。或者通过插件市场安装全部三个： /plugin marketplace add dwgx/SmartCLI。

主要方式——从 PyPI 安装（库、CLI 和 MCP 服务）：

pip install smartcli-toolkit

发行包名称与导入名称： PyPI 发行包名为 smartcli-toolkit （smartcli / smart-cli 已被占用或屏蔽），但可导入的 包名是 smartcli_core。因此，执行 pip install smartcli-toolkit 后，仍需 写作 from smartcli_core import PtySession。

备用方式——从源代码检出版本重建完整开发环境：

git clone https://github.com/dwgx/SmartCLI SmartCLI
cd SmartCLI
python -m pip install -r requirements.txt

requirements.txt 会安装 pyte、MCP SDK，并且仅在 Windows 上安装 pywinpty（POSIX 使用标准库的 pty 后端）。pip install . 会安装 smartcli_core 以及 smartcli-tui、smartcli-mcp 和 smartcli-toolkit 命令。可视化 cmd-art 和 tui-ui 技能仍可在检出目录中直接运行，分别使用 python -m fx 和 python -m ui。

可选扩展（真实 FIGlet 字体、光栅图像、权威的单元格宽度——缺少时 会优雅地回退到标准库实现）：

python -m pip install -r requirements-optional.txt
# or, from the checkout, via pyproject extras:
pip install ".[all]"        # pyfiglet + Pillow + wcwidth
pip install ".[art]"        # pyfiglet only
pip install ".[image]"      # Pillow only  (also: the PNG screenshot harness needs it)
pip install ".[width]"      # wcwidth only

Windows 注意事项： 运行任何技能前，请将输出设置为 UTF-8，以便方框绘制和 CJK 字形能够正确编码（CLI 也会自动重新配置标准输出，但为保险起见，仍请设置此项）：

set PYTHONIOENCODING=utf-8

开发机器上已验证的依赖版本（Windows 11、CPython 3.14.6）：pyte 0.8.2、 pywinpty 3.0.5、pyfiglet 1.0.4、Pillow 12.2.0、wcwidth 0.8.1。

诊断。 python -m smartcli_core 会输出你的操作系统、Python、终端、PTY 后端和依赖版本。smartcli-tui doctor 会报告核心库的加载位置，以及是否存在 驱动所需的依赖。提交与终端相关的错误报告时，请附上这两项命令的输出。

快速入门

cmd-art——终端视觉效果

cd skills/cmd-art
python -m fx list                          # list all 30 effects
python -m fx play donut --seconds 5        # play one effect (bounded)
python -m fx gallery                       # one frame of each effect
python -m fx show --seq "donut:fire:3,plasma::3"

tui-ui——单元格精确的终端 UI

cd skills/tui-ui
python -m ui widgets                       # list all 17 widgets
python -m ui gallery --width 100 --height 30
python -m ui demo table --width 80 --height 12 --theme dashboard

drive-tui——感知并驱动交互式程序

持久会话 CLI（状态会在 shell 调用之间保留）：

smartcli-tui start --cmd "python3 -i -q" --cols 80 --rows 24
smartcli-tui wait-regex --id <SID> ">>> " --timeout-ms 15000
smartcli-tui send-line --id <SID> "print(6*7)"
smartcli-tui snapshot --id <SID>
smartcli-tui close --id <SID>

在 Windows 上，将子命令改为 py -i -q。从源代码检出目录运行时，将 smartcli-tui 替换为 python skills/drive-tui/scripts/tui.py。

或者通过任意 MCP 客户端驱动——使用与 MCP 工具相同的动词，并自动附加 每个会话的令牌：

pip install smartcli-toolkit
smartcli-mcp     # stdio MCP server; smartcli-toolkit is an equivalent alias

作为库使用

可直接导入共享核心：

import sys
from smartcli_core import PtySession

s = PtySession()
s.start([sys.executable, "-q"])
s.wait_for(r">>> ")            # readiness sync, never a blind sleep
print(s.snapshot().to_text())  # pyte-backed structured screen
s.close()

完整的命令参考、截图/AGENTCLI 测试框架以及回归测试套件，请参阅 README-USAGE.md。

功能

cmd-art（skills/cmd-art）——一种“动态模板”效果引擎：Effect ABC + @register 装饰器 + 自动发现。30 种效果（donut、solarsystem、fire、plasma、 rain、starfield、tunnel、text3d、cube、sphere、boids、life、fireworks、sparkle、decrypt、 gradient_text、banner_scroll、image2ascii、typewriter、julia、mandelbrot、perlin、flames、water、nebula、text_flyin、text_converge、text_decrypt、spectrum_bars、cbonsai），涵盖 8 种主题（mono、fire、 ocean、synthwave、viridis、pastel、matrix-green、rainbow）。效果是纯帧生成器；play 默认有界运行，并且始终会恢复终端状态。

tui-ui（skills/tui-ui）——类 Web 的终端布局引擎，输出兼容 tmux 的 ANSI 帧（仅含 SGR 颜色序列和换行；没有光标移动，也不使用备用屏幕）。17 个 组件（badge、banner、braille_chart、card、fuzzy_filter_list、gradient_rule、kv、 meter、panel、preview_pane、progress、radial_glow、rule、slider_track、table、tabs、 tree），基于一个包含两个渲染路径实际调用的模块的引擎：field.py （着色器合成器）和 raster.py（子单元半块／四分块／braille 像素）。另外两个 辅助模块 box_junction.py 和 color_model.py 在 0.3.2 之前随包发布，但未接入 使用，并于 0.3.3 中移除：没有任何代码导入它们，而且 tui-ui 不会对 ui/ 自动发现，因此调用方根本无法访问它们。 针对 CJK／emoji／ZWJ 的显示单元精确处理，确保列不会错位。

drive-tui（skills/drive-tui）——通过 PTY 驱动交互式终端程序（REPL、 菜单、分页器、y/N 提示、向导），采用感知 → 决策 → 操作 → 等待 → 确认循环， 绝不盲目休眠。精简的 CLI （scripts/tui.py）提供持久的分离会话和一次性 run 模式，并附带可导入的模式 库，其中包含 8 个方案（repl、menu_select、pager、search_filter、 confirm、form、progress、wizard），用于对屏幕进行 classify() 并驱动操作。

等待能力所在位置。 等待功能可在子进程退出时结束，而不必耗尽剩余超时时间—— 如果程序在首次输入时崩溃，等待耗时就只是一个轮询周期，而非整个 超时上限。此功能需主动启用，默认关闭：使用 start --detect-child-exit / run --detect-child-exit，或在 MCP start 工具上设置 detect_child_exit。关闭时 行为与此前完全一致。启用后，每个等待响应都会包含 exited，且 wait 会报告 reason=EXITED。另外三项核心能力—— 屏幕版本等待基线、终端模式注册表和会话事件日志——仅供库使用： 它们可从 smartcli_core 导入，并且不会暴露在 CLI 或 MCP 接口中。各项能力的 设计原因请参阅 CHANGELOG.md（Unreleased）。

共享核心（smartcli_core）——可插拔的 PTY 后端 + pyte 屏幕模型 + 语义快照 + 就绪同步（pty_backend / screen_model / snapshot / readiness / session）。这是三个技能共用的可复用、可导入基础层。从 0.3.0 起，每次观测都会附带 有预算限制的读取路径和 io 块，因此调用方可以区分安静无变化与尚未读取 （local_cut、字节水位、待处理事实——未知值为 null，绝不会是 0）；STABLE 要求观测已排空；关闭时会报告 closed_confirmed 或 close_unconfirmed，并附上最后 的进度，而不是假定原生调用返回就意味着子进程已退出。

知识图谱（knowledge/）——一个 Wiki 链接图谱（140 多个 .md 文件），包含精确的 渲染公式、ANSI 序列和实测常量；每篇笔记均附有来源和交叉链接。请参阅 knowledge/INDEX.md。

项目布局

SmartCLI/
  smartcli_core/           shared PTY + pyte engine (importable package)
  skills/cmd-art/          fx effect package and CLI (30 effects, 8 themes)
  skills/drive-tui/        TUI pattern library and PTY driver CLI (8 recipes)
  skills/tui-ui/           terminal UI layout engine and widgets (17 widgets)
  tools/screenshot/        pyte -> PNG smoke-test harness
  tools/agentcli/          agent-CLI control validation harness
  knowledge/               wiki-link knowledge graph, 140+ .md files (see knowledge/INDEX.md)
  showcase/                rendered effect PNGs + demo GIFs (shown above)
  tests/                   direct script-style regressions
  research/                archived first-pass research notes

文档

• README-USAGE.md — 完整的使用速查表：所有技能、截图和 AGENTCLI 测试框架，以及回归测试命令。
• knowledge/INDEX.md — 知识图谱（140 多个 .md 文件）。
• AGENTCLI-VALIDATION.md — Agent 命令行控制测试矩阵。
• CHANGELOG.md — 发布历史。
• 验证证据目录 — 已于 2026-10-01 归档。 原有的 verification/ 目录（收据、探测文件、历史测试框架修订版）不再属于此仓库，也不会随软件包分发。该目录按字节原样移出，因此没有删除任何内容。之所以将其移出，是因为其中包含 8 份在三项错误修复前从 smartcli_core/screen_model.py 复制的过时文件，导致全仓库搜索返回修复前的代码。目录内的 sha256 校验值仍然有效——它们指向仍留在仓库中的文件。

许可证

MIT — 参见 LICENSE。