📦 TUI USE — tui-use — 通过 tui-agent 操作终端界面程序

Name: TUI USE — tui-use — 通过 tui-agent 操作终端界面程序
Rating: 1

v1.0.0

通过 tui-agent CLI 工具操作终端用户界面（TUI）程序。当用户要求交互、自动化、控制或测试任何基于终端的程序时使用此技能，包括编辑器（vim、nano、emacs）、系统监控工具（htop、top、btop）、文件管理器（ranger、mc）、数据库客户端（mycli、pgcli）或任何 ncurses/TUI 应用程序。

1· 28·0 当前·0 累计

by @zbflcy·MIT-0

生产力工具

下载技能包

License

MIT-0

最后更新

2026/4/16

安全扫描

VirusTotal

可疑

查看报告

OpenClaw

可疑

medium confidence

技能的目的（通过 tui-agent CLI 自动化终端 UI）是合理的，但 SKILL.md 期望你安装并运行来自 GitHub 路径的外部 tui-agent 实现，而注册表中未声明该依赖——这种不匹配和非正式的安装指导值得警惕。

评估建议

在安装或使用此技能前：1) 验证你确实有可信的 tui-agent 二进制文件可用（注册表元数据应声明此依赖但实际没有）。2) 不要盲目运行 SKILL.md 的安装建议；仓库 URL 指向任意 GitHub 用户，建议的 'pip install -e tui-agent/' 含糊不清——更推荐使用官方发布包或在安装前检查仓库内容。3) 理解自动化终端程序会让工具看到终端上显示的所有内容（可能是敏感的），外部 tui-agent 守护进程会创建 PTY 并运行命令——如果要安装请审计代码。4) 如果继续，请限制为手动调用（不要为不可信技能启用任何始终开启/自主行为），并考虑在沙盒环境中运行该工具直到确认其安全性。...

详细分析 ▾

ℹ 用途与能力

名称/描述与指令匹配：该技能是通过名为 tui-agent 的 CLI 控制 TUI 程序的指令集。然而，注册表元数据未声明任何必需的二进制文件，而 SKILL.md 明确要求 tui-agent CLI（并指向 GitHub 仓库）。缺失的声明依赖是一个不一致之处：合法的 TUI 自动化技能应将 CLI 列为必需二进制文件或提供适当的安装规范。

ℹ 指令范围

SKILL.md 紧扣主题：记录了启动会话、捕获屏幕、发送按键、等待文本等，未指导读取任意系统文件或导出凭证。也就是说，该技能假定代理将运行任意终端程序（编辑器、数据库客户端、监控工具）——这些程序可能在屏幕上暴露敏感数据。指令还引导用户从第三方 GitHub 仓库获取代码并运行 pip install -e tui-agent/，这是下载和执行外部代码的操作（在技能包之外）。

⚠ 安装机制

注册表中没有安装规范（仅指令），但 SKILL.md 告诉用户克隆或使用 GitHub 树 URL 并运行 'pip install -e tui-agent/'。该指导含糊不清（pip install -e 期望本地路径）并指示从外部 GitHub 仓库 (zbflcy/tui-use) 安装代码。从第三方仓库安装任意代码风险较高，应在安装元数据中声明或替换为清晰、可验证的发布 URL 或包。由于该技能鼓励安装/执行没有来源的外部代码，这是一个值得关注的问题。

✓ 凭证需求

该技能未声明所需的环境变量、凭证或配置路径。SKILL.md 同样不请求密钥。这是相称的。值得注意的是，自动化终端程序本质上让操作者（或使用此技能的代理）能看到打印到终端的任何内容（可能包括密钥），因此即使没有明确请求密钥访问，操作时也需要谨慎。

✓ 持久化与权限

标志显示没有 'always: true'，该技能仅可由用户调用。默认允许自主模型调用，但这里没有请求额外权限。该技能确实引用了 tui-agent 运行时启动的守护进程，但该守护进程是外部工具的一部分，而非技能包本身。没有证据表明该技能试图修改其他技能或系统范围的代理设置。

安全有层次，运行前请审查代码。

License

MIT-0

可自由使用、修改和再分发，无需署名。

查看条款 ↗

运行时依赖

无特殊依赖

版本

latestv1.0.02026/4/16

tui-use 1.0.0 — 初始版本 - 引入 tui-agent CLI 工具用于自动化和控制终端用户界面（TUI）程序。- 支持启动、停止和管理多个 TUI 应用程序会话。- 提供屏幕捕获、文本输入、特殊按键和剪贴板式粘贴命令。- 支持鼠标操作，包括 TUI 会话中的点击和滚动。- 添加了强大的程序状态和屏幕稳定性等待机制。- 记录了 vim 和 nano 等工具的最佳实践和工作流程示例。

● 可疑

安装命令

点击复制

官方npx clawhub@latest install tui-use

镜像加速npx clawhub@latest install tui-use --registry https://cn.longxiaskill.com

技能文档

本技能教你如何使用 tui-agent CLI 工具启动、交互和控制 TUI（终端用户界面）程序。可以将 tui-agent 视为终端程序的眼睛和双手——它让你能看到屏幕上显示的内容、输入文本、按键、鼠标点击以及等待事件发生。

前提条件

tui-agent 必须已安装并在 PATH 中可用，你可以从 tui-use github 克隆。从同级的 tui-agent/ 目录安装：

pip install -e tui-agent/

架构概览

你（通过 Bash 工具） --> tui-agent CLI --> 守护进程（自动启动） --> PTY --> TUI 程序
                              ^                              |
                              |                              |
                        stdout/JSON <-- Unix Socket <-- pyte 虚拟屏幕

守护进程在首次使用时自动启动——无需手动设置。

核心工作流程

每次 TUI 交互都遵循此模式：

启动一个会话（启动 TUI 程序）
等待程序准备就绪
捕获屏幕以查看显示内容
交互（输入文本、发送按键、点击、滚动）
再次捕获以验证结果
完成时停止会话

这个捕获-操作-捕获循环是基本节奏。在重要操作前后都要捕获屏幕，以便验证发生了什么。

命令参考

会话管理

启动 TUI 程序：

tui-agent start --name  [--cols 120] [--rows 40] --  [args...]

--name：此会话的唯一标识符（你将在所有后续命令中使用）
--cols/--rows：终端尺寸（默认：80x24）。复杂 UI 使用更大值
-- 之后的所有内容是要运行的命令

列出活动会话：

tui-agent list

检查会话状态：

tui-agent status --name

停止会话：

tui-agent stop --name 
# 或停止所有：
tui-agent stop --all

查看屏幕

捕获完整屏幕：

tui-agent capture --name

带光标位置捕获：

tui-agent capture --name  --cursor

这会将光标坐标附加到输出中——有助于了解在编辑器中的位置。

捕获特定区域：

tui-agent capture --name  --top 0 --left 0 --height 5 --width 40

保存快照以供后续比较：

tui-agent capture --name  --save my_snapshot

将当前屏幕与保存的快照进行比较：

tui-agent diff --name  --snapshot my_snapshot

读取回滚历史（滚动到顶部的内容）：

tui-agent scrollback --name  --lines 200

输入和按键

输入文本：

tui-agent type --name  "hello world"

输入文本并按 Enter：

tui-agent type --name  --enter "ls -la"

发送特殊按键：

tui-agent key --name   [key2] [key3...]

重要：key vs type — key 命令只接受下面列出的特殊键名。对于常规字符（字母、数字、符号），如 vim 的 i、o、dd、:wq，始终使用 type。仅对非可打印字符的键使用 key。支持的键名（不区分大小写）：

导航：up、down、left、right、home、end、pageup、pagedown
编辑：enter/return、tab、backspace、delete、insert、space、escape/esc
功能键：f1 到 f12
Ctrl 组合：ctrl-a 到 ctrl-z

粘贴文本（使用带括号的粘贴模式，对编辑器安全）：

tui-agent paste --name  "multi-line\ntext content"

向编辑器插入多行内容时使用 paste 而非 type——带括号的粘贴模式可防止编辑器将换行符解释为命令。

鼠标操作

点击位置（从 0 开始的行和列）：

tui-agent click --name  --row 5 --col 10

上/下滚动：

tui-agent scroll-up --name  --row 12 --col 40 --lines 3
tui-agent scroll-down --name  --row 12 --col 40 --lines 3

等待条件

等待对于可靠的自动化至关重要。TUI 程序需要时间渲染，动作太快会导致错误。

等待特定文本出现在屏幕上：

tui-agent wait --name  --text "Ready" --timeout 10

等待文本消失：

tui-agent wait --name  --text "Loading..." --absent --timeout 15

等待屏幕停止变化（稳定 N 秒）：

tui-agent wait --name  --stable 2.0 --timeout 10

当你不知道具体期望什么文本，但需要程序完成渲染时，使用 --stable。

调整终端大小

tui-agent resize --name  --cols 160 --rows 50

最佳实践

始终在捕获前等待

TUI 程序需要时间渲染。启动会话或发送输入后，捕获前务必等待：

tui-agent start --name ed -- vim file.py
tui-agent wait --name ed --stable 1.0  # 等待 vim 完全加载
tui-agent capture --name ed --cursor    # 现在可以安全读取屏幕

使用有意义的会话名称

根据用途命名会话，而非程序：

好：editor、monitor、file-browser
差：s1、test、abc

在操作前后捕获

这样可以验证你的操作是否产生了预期效果：

tui-agent capture --name ed --save before_edit
tui-agent type --name ed "i"                    # 进入插入模式（单个字符，使用 type）
tui-agent type --name ed "new line of code"
tui-agent key --name ed escape                   # Escape 是特殊键，使用 key
tui-agent capture --name ed                      # 检查结果

选择合适的终端尺寸

简单程序（bash、基本 TUI）：80x24（默认）即可
编辑器或复杂 UI：使用 120x40 或更大
宽表格程序：将 cols 增加到 160+

完成后清理会话

不再需要时务必停止会话：

tui-agent stop --name ed

或完成后停止所有会话：

tui-agent stop --all

优雅处理错误

如果 wait 命令超时（退出代码 1），捕获屏幕以了解发生了什么，而不是盲目重试：

tui-agent wait --name ed --text "Success" --timeout 5
# 如果失败，捕获以查看实际状态：
tui-agent capture --name ed

常见工作流程

使用 nano 编辑文件

# 启动 nano tui-agent start --name ed --cols 120 --rows 40 -- nano myfile.py tui-agent wait --name ed --stable 1.0 tui-agent capture --name ed # 输入一些代码 tui-agent type --name ed "print('hello world')" tui-agent key --name ed enter tui-agent type --name ed "print('goodbye')" tui-agent capture --name ed # 保存（Ctrl+O，然后 Enter 确认文件名） tui-agent key --name ed ctrl-o tui-agent wait --name ed --stable 0.5 tui-agent key --name ed enter tui-agent wait --name ed --text "Wrote"

# 退出（Ctrl+X） tui-agent key --name ed ctrl-x tui-agent stop --name ed

使用 vim 编辑文件

注意：vim 在某些平台上可能无法响应输入（参见平台说明）。如果 vim 在你的环境中工作：

# 启动 vim（使用 -u NONE 避免配置问题） tui-agent start --name ed --cols 120 --rows 40 -- vim -u NONE -N myfile.py tui-agent wait --name ed --stable 1.0 tui-agent capture --name ed # 导航到特定行（例如第 10 行） tui-agent type --name ed ":10" tui-agent key --name ed enter tui-agent capture --name ed # 进入插入模式并添加文本 tui-agent type --name ed "o" # 在下方打开新行（普通字符，使用 type） tui-agent type --name ed " print('hello')" tui-agent key --name ed escape # 返回普通模式

# 保存并退出 tui-agent type --name ed ":wq" tui-agent key --name ed enter tui-agent wait --name ed --stable 1.0

使用 htop 监控系统

# 启动 htop tui-agent start --name mon --cols 160 --rows 50 -- htop tui-agent wait --name mon --stable 2.0 tui-agent capture --name mon # 搜索进程 tui-agent key --name mon f3 # F3 是特殊键，使用 key tui-agent type --name mon "python" tui-agent key --name mon enter tui-agent capture --name mon # 滚动列表 tui-agent scroll-down --name mon --row 25 --col 80 --lines 10 tui-agent capture --name mon

# 退出 tui-agent type --name mon "q" # 普通字符，使用 type tui-agent stop --name mon

运行 Shell 命令并读取输出

# 启动 bash 会话 tui-agent start --name sh -- bash --norc --noprofile tui-agent wait --name sh --stable 1.0 # 运行命令 tui-agent type --name sh --enter "ls -la /tmp" tui-agent wait --name sh --stable 1.0 tui-agent capture --name sh # 如果输出很长，检查回滚 tui-agent scrollback --name sh --lines 100

# 退出 tui-agent type --name sh --enter "exit" tui-agent stop --name sh

与 ncurses 应用程序交互

# 启动任何 ncurses 应用（示例：midnight commander） tui-agent start --name fm --cols 120 --rows 40 -- mc tui-agent wait --name fm --stable 2.0 tui-agent capture --name fm # 使用方向键导航 tui-agent key --name fm down down down tui-agent capture --name fm # 按 Enter 打开目录 tui-agent key --name fm enter tui-agent wait --name fm --stable 1.0 tui-agent capture --name fm # 使用功能键 tui-agent key --name fm f5 # 复制对话框 tui-agent capture --name fm

# 退出 tui-agent key --name fm f10 tui-agent stop --name fm

平台说明

macOS 上的 vim：系统 vim（/usr/bin/vim）可能无法响应通过 tui-agent start 直接启动时的 type 输入。这似乎与 macOS vim 检测终端功能的方式有关。解决方法：

改用 nano 或 pico——它们与 tui-agent 配合可靠
使用 vim -u NONE -N 禁用 vimrc 并以 nocompatible 模式运行
安装不同的 vim 构建（例如通过 Homebrew：brew install vim）
对于简单文件编辑，考虑使用 shell 命令（sed、awk）而非 TUI 编辑器

其他程序：大多数终端程序（bash、htop、mc、ncurses 应用）与 tui-agent 开箱即用配合良好。如果程序不响应输入，尝试增加等待时间或使用更长时间参数的 --stable。

故障排除

"session not found" 错误：会话可能已停止或程序已退出。使用 tui-agent list 检查。

屏幕捕获为空或乱码：程序可能尚未完成渲染。添加更长的 --stable 等待或增加 --timeout。

按键似乎不起作用：某些程序期望特定的按键序列。捕获屏幕以验证程序的当前状态（例如，vim 是在插入模式还是普通模式？）。

程序意外退出：使用 tui-agent status --name 检查退出代码。程序可能崩溃或收到了信号。

守护进程未运行：守护进程自动启动。如果问题持续存在，检查套接字文件是否存在于 /tmp/tui-agent-*.sock。你可以手动启动守护进程或直接重试命令。

数据来源：ClawHub ↗ · 中文优化：龙虾技能库