SuperAPI AI 工具集

cmux

智能体与模型

查看项目

更新于 10-26 16:21

技能介绍

用途

cmux 是一个通过 Unix 套接字 CLI 控制的终端复用器,负责管理窗口(window)、工作区(workspace)、窗格(pane)和界面(surface)。该技能供 AI 代理(如 Claude Code)在需要创建隔离终端窗格执行并行任务、发送命令、读取输出并在完成后清理时调用。

核心概念

  • 窗口:顶层操作系统窗口,可用 cmux list-windows 列出。
  • 工作区:窗口内的一个标签页,拥有自己的窗格布局,用 cmux new-workspace 创建,cmux select-workspace 切换。
  • 窗格:工作区内矩形的分屏区域,包含一个或多个界面,用 cmux new-pane --direction <dir> 创建。
  • 界面:窗格内实际的终端(或浏览器)实例,形如 surface:42,是发送命令和读取输出的对象。
  • 引用格式:短引用如 pane:5、surface:12、workspace:3,可通过 --id-format uuids 输出 UUID,--id-format both 同时输出两者。

主要能力

  1. 识别上下文:cmux --json identify 返回调用者的 surface_ref、pane_ref、workspace_ref、window_ref。
  2. 创建分屏窗格:cmux --json new-pane --direction right(右分屏)或 --direction down(下分屏),可加 --workspace workspace:3 指定工作区,返回新窗格及其界面引用。
  3. 发送命令:cmux send --surface surface:42 "npm test" 只输入文本不回车,需配合 cmux send-key --surface surface:42 Enter 执行;也支持 Escape、Tab、ctrl+c、ctrl+d、Up、Down 等按键。
  4. 读取屏幕:cmux read-screen --surface surface:42,可加 --scrollback 包含回滚缓冲,--lines 50 只取最后 N 行。
  5. 关闭界面:cmux close-surface --surface surface:42。
  6. 列表与焦点:cmux --json list-panes、cmux --json list-pane-surfaces --pane pane:5、cmux focus-pane --pane pane:5。
  7. 工作区管理:列出、创建(可带 --command 启动命令)、切换、重命名、关闭、获取当前工作区。
  8. 通知:cmux notify --title "Task Complete" --body "All tests passed"。

环境变量

cmux 在其创建的每个终端中自动设置:

  • CMUX_WORKSPACE_ID:所有命令的默认 --workspace
  • CMUX_SURFACE_ID:命令的默认 --surface
  • CMUX_TAB_ID:tab-action/rename-tab 的默认 --tab
  • CMUX_SOCKET_PATH:覆盖套接字路径(默认 /tmp/cmux.sock)

因此在 cmux 内部运行时,多数命令无需显式指定 ID。

使用方式

所有命令统一为 cmux [--json] <command> [options],程序化解析输出时应始终加 --json。典型子代理工作流:先 identify 确认位置,再 new-pane 创建分屏并取得界面引用,用 send 加 send-key Enter 执行任务,随后 read-screen --scrollback 读取结果,最后 close-surface 清理。并行子代理可重复该流程,用 right、down 等不同方向形成网格布局。

适用场景

  • 为子代理任务或多代理并行开发创建隔离终端窗格
  • 向指定终端界面发送命令与按键、读取屏幕内容
  • 编排多窗格布局、创建与管理工作区
  • 在终端窗格旁打开浏览器界面
  • 重命名、重排或在 工作区之间移动界面/窗格

不适用于与 cmux 无关的普通 shell 脚本,也不适用于 tmux 或 screen 命令(cmux 有独立协议)。

限制与注意事项

  • send 不按回车:只输入文本不执行,必须随后 send-key ... Enter,否则 read-screen 只看到输入没有输出。
  • 读取长输出需 --scrollback:命令输出滚出可见区域后,不加该参数可能只返回 shell 提示符。
  • 引用会失效:工作区关闭后其所有界面引用失效,报 "Surface not found",发送前应重新 list-panes。
  • 嵌套环境套接字路径可能不继承:在子 shell 或 sudo 中 CMUX_SOCKET_PATH 可能未传递,需显式 --socket-path。
  • close-surface 关闭的是界面而非窗格,误关会静默移除仍需要的终端,关闭前应用 list-pane-surfaces 核验引用。
  • 常见错误:套接字未找到(应用未运行或路径错误)、界面未找到、工作区未找到、认证失败(套接字密码不匹配,可设 CMUX_SOCKET_PASSWORD 或 --password)。

参考资料

详细内容分文件存放:references/pane-management.md(窗格高级操作:调整大小、交换、拆分、合并、拖拽分屏、面板)、references/browser-automation.md(浏览器界面的打开、导航、快照、点击、填表、执行 JS)、references/subagent-workflows.md(多代理编排、并行任务执行、输出轮询、清理策略)。仅在任务需要时加载,避免消耗上下文。

首次激活时会检查已安装的配套技能,缺失时提示安装:npx skills add AbsolutelySkilled/AbsolutelySkilled --skill <name>。