mcpField
C
control-cli

control-cli

github.com/poteto测试与质量17569 次安装23 周前更新
代码仓库

关于 control-cli

这项技能通过可重复的本地终端测试环境验证交互式 CLI 和 TUI，支持稳定复现故障、检查交互、记录输出和排查性能问题。

主要功能

  1. 01优先复用仓库自带测试环境
  2. 02确定性地发送终端输入
  3. 03捕获屏幕与交互记录
  4. 04分析 CPU 与内存
  5. 05清理测试会话和产物

适用场景

  1. 01复现 CLI 或 TUI 故障
  2. 02验证提示、按键和窗口缩放
  3. 03比较修复前后的终端输出
  4. 04排查启动延迟或卡顿

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/poteto/plugins --skill control-cli

安装后在 Claude Code 中输入/control-cli确认已加载。

详细介绍

控制 CLI

使用可重复的本地测试框架来测试交互式 CLI，而不是手动摸索。先复用仓库自带的测试／演示框架（如果有）；否则，使用标准本地工具搭建临时框架。

用途

  • 使用确定性输入重现 CLI／TUI 错误。
  • 验证键盘操作流程、提示、键盘中断、调整大小时的行为以及终端布局。
  • 为错误修复前后捕获会话记录。
  • 分析启动时间、缓慢操作、卡死或内存增长。
  • 如果终端输出比文字说明更直观，则录制一段简短的终端演示。

测试框架循环

  1. 确定待测试的命令以及最小可复现的工作区。
  2. 查找现有的本地测试框架：软件包脚本、端到端测试、演示录制工具、expect 脚本或 PTY 辅助工具。
  3. 如果不存在测试框架，则在隔离的终端会话中使用确定性的环境变量启动 CLI。
  4. 交互前捕获当前屏幕。
  5. 每次只发送一个操作：文本、Enter、方向键、Escape、Ctrl-C、调整大小。
  6. 等待出现明确的屏幕模式或提示，再执行下一步操作。
  7. 保存会话记录和任何性能分析产物。
  8. 正常结束会话。

测试框架选项

  • 仓库原生测试框架：优先使用已提交到仓库的脚本，因为它们了解应用的启动方式、环境和提示。
  • tmux：管理会话、使用 capture-pane、send-keys，以及附加／分离会话。
  • PTY 探测器：如果无法使用 tmux，则在需要时使用简短的 Python、Node 或 Expect 脚本。
  • 运行时检查器：使用 Node 或 Bun 检查器进行 CPU 性能分析、堆快照和实时求值。
  • 终端录制工具：用户要求演示时，使用仓库本地演示工具或兼容 asciinema 的工具。

最小 tmux 测试框架

SESSION="cli-harness-$(date +%s)"
tmux new-session -d -s "$SESSION" -- <command-under-test>
tmux capture-pane -pt "$SESSION"
tmux send-keys -t "$SESSION" "help" Enter
tmux capture-pane -pt "$SESSION"
tmux kill-session -t "$SESSION"

对于 Node CLI：

NODE_OPTIONS="--inspect=127.0.0.1:0" tmux new-session -d -s "$SESSION" -- <node-cli-command>

读取终端输出以找到检查器 URL，然后在需要进行性能分析时使用兼容 Chrome DevTools 的工具。

最小 PTY 测试框架

如果仓库没有 tmux 或演示测试框架，并且需要确定性地等待，请使用 PTY 脚本。除非用户要求添加可复用的测试，否则请将其保留为临时脚本。

import os
import pty
import select
import subprocess
import time

master_fd, slave_fd = pty.openpty()
proc = subprocess.Popen(
    ["<command>", "<arg>"],
    stdin=slave_fd,
    stdout=slave_fd,
    stderr=slave_fd,
    close_fds=True,
)
os.close(slave_fd)

deadline = time.time() + 30
buffer = b""
while time.time() < deadline:
    ready, _, _ = select.select([master_fd], [], [], 0.25)
    if not ready:
        continue
    chunk = os.read(master_fd, 4096)
    buffer += chunk
    if b"<ready text>" in buffer:
        os.write(master_fd, b"help\n")
        break

print(buffer.decode(errors="replace"))
proc.terminate()
os.close(master_fd)

如果 CLI 需要更丰富的终端控制，请使用 pty.fork() 或现有的 PTY 库。

性能分析方法

  • 启动回归：在相同的机器、环境和命令下，捕获基线与处理后的启动时间。
  • 缓慢操作：开始 CPU 性能分析，执行操作，停止性能分析，并比较自耗时最高的函数。
  • 内存泄漏：如果可用，则强制执行 GC 并获取堆快照；重复执行操作，再次强制执行 GC 并获取另一份快照。
  • 卡死：中断之前，捕获屏幕、活动句柄／资源以及堆栈／CPU 采样。

注意事项

  • 优先使用确定性等待，而不是休眠。如果必须休眠，请说明原因。
  • 不要向受控会话发送凭据或破坏性命令。
  • 除非仓库已有测试／演示框架，否则请将测试框架保留在 /tmp 中。
  • 不要硬编码其他仓库中的路径。请根据当前仓库的脚本和运行时调整命令。
  • 清理 tmux 会话、临时目录、检查器进程和演示产物，除非用户要求保留。

评论

支持 Markdown