mcpField
C
control-cli

control-cli

github.com/cursor测试与质量14.5k2.4k 次安装今天更新
代码仓库

关于 control-cli

用于构建可重复本地测试环境的技能，可测试交互式 CLI。开发者可借此复现问题、验证终端行为，并采集性能分析或演示材料。

主要功能

  1. 01确定性 CLI 输入
  2. 02键盘与窗口尺寸测试
  3. 03记录交互转录
  4. 04启动及运行时性能分析
  5. 05录制终端演示

适用场景

  1. 01复现 TUI 问题
  2. 02检查中断与尺寸变化行为
  3. 03比较修复前后的 CLI 输出
  4. 04调查启动缓慢或挂起

安装

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

$npx skills add https://github.com/cursor/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