agentic-awesome-skills 中的 cmux 技能实战：macOS 终端多 AI Agent 编排与全拓扑控制指南

AI 技能AI 插件【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址https://gitcode.com/gh_mirrors/an/agentic-awesome-skills点击查看免费下载导读本指南围绕 AASagentic-awesome-skills仓库中收录的cmux技能技能镜像文档主仓库同款位于 skills/cmux/SKILL.md展开系统讲解如何在 macOS 原生终端应用 cmux 中安全、精准地编排并行运行的多个 AI 编码 Agent。读完本文你将掌握 cmux 的 Window / Workspace / Pane / Surface 四级拓扑概念与带前缀引用语法、基于环境变量的 Agent 归属锚定、非破坏性自动化六条铁律、WKWebView 浏览器自动化流程、Markdown 查看器复用与换文件模式以及通过 CLI 与 Unix Socket JSON-RPC v2 双通道控制 cmux 的完整方法从而避免静默失败读到自己的页脚这类最常见陷阱。技能概览与适用场景cmux是一款面向 macOS 的原生终端应用专为同时并行运行多个 AI 编码 Agent设计。它对外暴露两层控制面CLIcmux命令与 Unix Socket JSON-RPC API默认位于/tmp/cmux.sock用于实现对完整拓扑结构和内嵌浏览器的控制。在 AAS 仓库中该技能被归类为development类别、risk: critical高风险因为它直接操控用户终端布局与输入流来源为社区source: community原作者davidondrej标记适配claude与codex两类 Agent。仓库的插件兼容性清单将cmux条目明确标记为codex: supported、claude: supported且setup.type为none——即无需额外安装脚本即可被 Claude Code 与 Codex 直接调用技能全文也已被索引进 data/aas-v1/skill-content.v1.ndjson 的统一内容索引中。什么场景应该调用本技能需要检查、创建、关闭或重排cmux 中的 pane窗格、surface表面或 workspace工作区时需要向运行在 cmux 内的 Agent 发送输入或监控其输出时。与之形成对照的是cmux 本身没有定时器 / watch / cron 能力——它是编排器而非调度器。如果你需要周期性的循环调度应当以自身时钟驱动的方式send→sleep→read-screen轮询、外层 while-sleep 包装或借助cmux notify与 OSC 终端钩子的事件驱动方式实现详见仓库中agent-self-scheduling技能的交叉印证。其中read-screen属于非中断式操作可放心用于轮询。核心概念四级拓扑与句柄理解 cmux 的层级模型是正确使用一切命令的前提自顶向下分为四级层级含义WindowmacOS 顶层的 cmux 窗口Workspace窗口侧边栏内的一个标签页对应一个 git 分支 / 项目上下文Pane工作区内部的拆分区域split regionSurface窗格内部的标签页类型为终端terminal或浏览器browser句柄Handle默认采用短引用short ref形式例如workspace:2、pane:1、surface:7同时接受 UUID 作为输入。如果需要输出 UUID 格式可追加--id-format uuids|both参数切换。Ref 语法搞错就会静默失败这是整个技能中最容易出问题、且失败方式是静默的部分务必逐条遵守始终使用带前缀的引用pane:38、surface:46。裸数字会被当作索引INDEX而非 ID——例如--surface 46的语义是索引为 46 的那个 surface通常不存在导致静默失败而不是surface:46。read-screen与capture-pane没有--pane标志——它们只接受--workspace或--surface作为目标。传入--pane会直接报错而传入裸数字或缺省目标时会回退到你自己的 surface——你将读到自己的页脚并得出错误结论。正确读取某个 pane 内容的方式是先用cmux list-pane-surfaces --pane pane:N将 pane 解析为 surface再执行cmux read-screen --surface surface:N。永远不要给 cmux 命令追加2/dev/null。错误信息走 stderr 且退出码为 1屏蔽 stderr 等于蒙住自己的眼睛让你无法发现 ref / flag 写错——这正是 (no output) 的第一大根因。在 Shell 中检测是否处于 cmux每个由 cmux 派生的终端都会被注入一组环境变量因此可以用一行测试来判断当前 shell 是否在 cmux 中[ -S ${CMUX_SOCKET_PATH:-/tmp/cmux.sock} ] || exit 0 # 不在 cmux 中则直接退出 [ -n ${CMUX_WORKSPACE_ID:-} ] echo inside cmux surface每次由 cmux 派生的终端都会注入CMUX_WORKSPACE_ID、CMUX_SURFACE_ID、CMUX_SOCKET_PATH、CMUX_PORT。铁律任何自动化都锚定到CMUX_WORKSPACE_ID。屏幕上当前视觉焦点所在的工作区未必是调用你的那个 Agent 所属的工作区——视觉焦点随时可能被用户切换而环境变量中携带的 workspace ID 才是 Agent 的归属地。这一原则贯穿全文所有命令示例所有--workspace一律传$CMUX_WORKSPACE_ID。快速开始拓扑查询与布局构建以下是获取我是谁 / 全局拓扑 / 各层清单的最小命令集全部为可复制运行的真实命令cmux identify --json # 我是谁window/workspace/pane/surface cmux tree # 完整层级树 cmux list-workspaces --json cmux list-panes --workspace $CMUX_WORKSPACE_ID cmux list-surfaces --workspace $CMUX_WORKSPACE_ID cmux new-workspace --name feature-x --cwd /path/to/repo cmux new-pane --workspace $CMUX_WORKSPACE_ID --type terminal --direction right --focus false cmux new-pane --workspace $CMUX_WORKSPACE_ID --type browser --direction right --url http://localhost:3000 cmux move-surface --surface surface:7 --pane pane:2 --focus false cmux split-off --surface surface:7 right cmux reorder-surface --surface surface:7 --before surface:3 cmux close-surface --surface surface:7要点说明new-workspace同时指定--name与--cwd可一步创建一个 git 分支 / 一个项目上下文的独立工作区new-pane的--type支持terminal与browserbrowser 类型配合--url直接打开目标地址--direction right把新窗格放在右侧--focus false表示创建后不抢占焦点非破坏性自动化原则之一move-surface/reorder-surface/close-surface用于布局微调与清理。需要留意cmux list-surfaces命令不存在查询某个 pane 内的 surface 请使用cmux list-pane-surfaces [--pane ...]下文 Markdown 查看器一节会反复用到。轮询窗格内的 Pi Agent保持短 sleep当你在 cmux 窗格内启动一个 Pi Agent 并轮询输出时请使用 2–5 秒的短sleep间隔。Pi 本身快速且极简且通常在极速的推理通道上运行token 流式输出非常快。除非确实需要例如大构建 / 大规模重构不要使用sleep 15——多数场景下sleep 2到sleep 5已经绰绰有余。配套的沟通纪律每次检查 Agent 之后给用户发送一行状态更新Agent 正在做什么、是否按计划推进。保持极度精简。Claude Code 特有的注意事项Claude 完成任务后可能会预填写一条预测的下一条用户消息——那段草稿是 Claude 自己写的不是用户在说话读取输出时要能识别这种预填内容避免误判为用户的真实指令。向 Agent 发送输入命令命名陷阱命令命名上有一个高频误区不存在send-surface/send-key-surface这两个命令名。向某个特定 surface 发送输入用的是send/send-key加--surface标志——与面向焦点终端的是同一组命令。send-panel/send-key-panel只对 panel--panel有效不能用于 surface。cmux send echo hi\n # 发给焦点终端 cmux send-key ctrlc # 支持 enter|tab|esc|backspace|arrows|ctrlx|shifttab cmux send --surface surface:7 npm run build # 指定 surface注意不是 send-surface cmux send-key --surface surface:7 enter # 指定 surface注意不是 send-key-surface通知与侧边栏元数据cmux 提供一套面向 Agent 的状态反馈机制让后台运行的 Agent 能以非打断的方式把进度呈现给用户cmux notify --title Done --body tests passed cmux set-status build compiling --icon hammer --color #ff9500 cmux set-progress 0.5 --label Building... cmux log --level success All 42 tests passed # 级别: info|progress|success|warning|error cmux trigger-flash --workspace $CMUX_WORKSPACE_ID # 蓝色圆环注意力提示 cmux sidebar-state --json # 导出全部侧边栏元数据其中notify用于系统级通知set-status/set-progress/log用于在侧边栏维护结构化进度元数据log支持按--level分级trigger-flash是请求用户注意的轻量提示以 workspace 锚定sidebar-state --json则可在排障时一次性导出侧边栏的全部元数据。浏览器自动化WKWebViewcmux 内置基于 WKWebView 的浏览器 surface标准工作流为open打开→ wait等待加载→ snapshot快照→ act动作→ re-snapshot复核快照。S$(cmux --json browser open https://example.com | jq -r .result.surface_ref) cmux browser $S wait --load-state complete --timeout-ms 15000 cmux browser $S snapshot --interactive # 元素以 e1, e2, ... 形式返回 cmux browser $S fill e1 email-address cmux browser $S click e2 --snapshot-after # 导航 / 检查 cmux browser $S goto URL | back | forward | reload cmux browser $S get url | get title | get text body | get value #email | get count .row cmux browser $S eval return document.title # 等待条件 cmux browser $S wait --selector #ready --timeout-ms 10000 cmux browser $S wait --url-contains /dashboard --timeout-ms 10000 # 会话管理 cmux browser $S cookies get | cookies set --name foo --value bar cmux browser $S state save /tmp/auth.json | state load /tmp/auth.json # 诊断 cmux browser $S console list | errors list | screenshot流程要点首步用cmux --json browser open url打开页面并用jq -r .result.surface_ref取出返回的 surface 引用之后所有子命令都以该引用$S为第一参数snapshot --interactive会把页面可交互元素编号为e1, e2, ...后续fill/click直接引用编号即可click加--snapshot-after可在点击后自动复查快照形成动作—复核闭环等待既支持--load-state complete页面加载状态也支持--selector/--url-containsDOM / URL 条件并统一配--timeout-ms控制超时会话层支持 cookie 读写与state save/load可将登录态序列化到本地文件如/tmp/auth.json供后续复用诊断层可列出 console 与错误信息或直接截图。WKWebView 的能力边界返回not_supported视口模拟viewport emulation、地理位置 / 离线模拟、trace 录制、网络路由拦截network route interception、原始输入注入。WKWebView ≠ CDP——不要指望获得 Playwright 同等的网络 mock 或视口模拟能力。Markdown 查看器复用右栏与换文件模式cmux 的 Markdown surface 是一个实时监视渲染器live-watching renderer适合让 Agent 在右侧窗格持续展示文档cmux markdown open plan.md --direction right # 实时监视渲染 cmux open file.pdf # 自动路由到右侧查看器cmux markdown open支持的标志--workspace、--surface、--window、--direction right|down|left|up、--focus true|false。没有--pane标志——传入会报错若要定向到某个 pane请传--surface 该 pane 内已有的 markdown surface。复用已有右侧 Markdown 窗格不要衍生散乱窗格markdown open的默认行为是每次都新建一个 pane即使带了--direction right也不例外。若希望所有文档都以标签页形式收拢在同一个右侧 pane 中请严格按下述三步执行# 1. 找到右侧窗格及其 surface锚定到当前 workspace cmux list-panes --workspace $CMUX_WORKSPACE_ID cmux list-pane-surfaces --pane pane:10 # 右侧/辅助窗格 # 2. 定向到该 pane 内已有的 markdown surface 打开复用 pane、新增标签页 cmux markdown open /abs/path/file.md --surface surface:12 --focus false # 3. 如果仍然衍生出了新 pane确实可能发生把新 surface 移入并复核 cmux move-surface --surface surface:NEW --pane pane:10 --focus false cmux list-panes --workspace $CMUX_WORKSPACE_ID # 确认散乱 pane 已消失在单一右侧窗格内替换文件先关闭、再打开要替换右侧那个唯一 Markdown 窗格中显示的文档唯一可靠的操作顺序是先关闭上一个 surface再以全新状态markdown open新文件——绝不移动已有查看器也绝不先开后关。# 1. 关闭上一个右侧 markdown surface右侧短暂留空 cmux list-panes --workspace $CMUX_WORKSPACE_ID cmux close-surface --surface surface:PREV # 2. 然后以全新状态打开新文件 cmux markdown open /abs/path/new.md --direction right --focus false顺序至关重要先关旧、后开新。如果反过来先开新再关旧或者用move-surface移动已有查看器最终结果是右侧窗格空白。血泪教训免去试错成本Surface 引用是全局的不限于某个 workspace。早前某次markdown open得到的surface:126可能位于另一个 window/workspace。复用它之前务必重新list-panes/list-pane-surfaces——永远不要假设上一轮拿到的引用还在原右侧窗格中。move-surface移动 Markdown 查看器常常导致其空白。被移动的 surface 仍保持typemarkdownsurface-health也看似正常但实际渲染为空。修复方式close-surface后cmux markdown open path全新打开再按需移动新 surface。不要在refresh-surfaces上浪费时间——它通常救不活移动后变空白的查看器。无法对 markdown surface 截图或read-screen报Surface is not a terminal且浏览器截图仅限 WKWebView。要验证 Markdown 查看器是否成功渲染请询问用户或在浏览器 surface 中打开该文件——不要浪费多轮去尝试捕获它。cmux list-surfaces不存在请用cmux list-pane-surfaces [--pane ...]。设置与配置cmux.json 与 Ghostty配置管理命令如下cmux docs settings # 打印路径、schema URL、重载命令 —— 编辑前务必先读 cmux settings path # 输出 cmux.json 路径 cmux settings cmux-json # 在编辑器中打开 cmux reload-config # 热重载 cmux.json ~/.config/ghostty/config等价于 CmdShift,配置文件位置与职责划分cmux 设置~/.config/cmux/cmux.json权威配置项目级覆盖为.cmux/cmux.json或./cmux.json终端渲染字体、光标、主题、回滚缓冲、不透明度、模糊效果位于~/.config/ghostty/config——不在 cmux.json 中。编辑纪律编辑cmux.json之前先将其复制一份带时间戳的.bak备份到旁边便于用户随时回滚。配置 schema 由官方仓库web/data/cmux.schema.json提供可用cmux docs settings查看其 URL 与重载命令后再动手。安装与 Agent Hooks在 macOS 上安装 cmux 并接通各类 Agent 的完整链路brew tap manaflow-ai/cmux brew install --cask cmux sudo ln -sf /Applications/cmux.app/Contents/Resources/bin/cmux /usr/local/bin/cmux cmux hooks setup # 为检测到的所有 Agent 安装钩子 cmux hooks setup codex|grok|antigravity|opencode # 仅指定某个 Agent npx skills add manaflow-ai/cmux -g -y # 为 Agent 安装 cmux 技能其中cmux hooks setup负责把会话钩子注入各 Agent支持按名称定向安装npx skills add manaflow-ai/cmux -g -y则为 Agent 安装配套的 cmux 技能文件。原生会话恢复session-resume支持的 AgentClaude Code、Codex、Grok、OpenCode、Pi、Amp、Cursor CLI、Gemini、Antigravity、Rovo Dev、Hermes、Copilot、CodeBuddy、Factory、Qoder。Socket API高级用法对于需要高频调用、子进程启动成本不可忽略的紧循环场景可以直接走 Unix Socket/tmp/cmux.sock协议为JSON-RPC v2其余场景优先使用 CLI。echo {id:1,method:workspace.list,params:{}} | nc -U /tmp/cmux.sock方法名前缀system.*、window.*、workspace.*、pane.*、surface.*、notification.*、browser.*。注意旧的 v1 socket 载荷{command:...}会被拒绝必须使用 v2 JSON-RPC。当前构建支持的全部 socket 方法可用cmux capabilities --json枚举。Socket 访问模式模式说明cmuxOnly默认仅允许 cmux 派生的进程连接automation允许任意本地进程连接password需要密码allowAll最宽松不安全如果遇到Failed to connect to socket很可能是你在cmuxOnly模式下作为外部进程连接——请在 Settings Automation 中切换模式或改为在 cmux 终端内部执行。非破坏性自动化的六条铁律以下规则源自cmux-workspace技能旨在防止 Agent 在自动化过程中强行抢占用户焦点锚定CMUX_WORKSPACE_ID永远不要假设视觉焦点所在的工作区就是目标工作区。绝不投机性地调用改变焦点的动词select-workspace、focus-pane、focus-panel、focus-surface只能在用户明确要求时调用凡可用之处一律传--focus false。一步加法式构建布局cmux new-pane --type … --focus false优于先建→再移→再聚焦的命令链。右侧辅助窗格模式若已存在非调用方的辅助窗格则复用否则只创建恰好一个右侧窗格。绝不向非自己所有的 surface 发送输入除非用户明确要求跨工作区路由否则只定向到调用方所在 workspace 内的 surface。路由输入前先检查 surface 健康状态当 UI 状态可能过期时使用cmux surface-health。常见陷阱清单Pi / Pi 系外部进程 socket 连接失败→ 默认处于cmuxOnly模式在 cmux 终端内运行或更改 socket 模式。仅限 macOS没有 Linux / Windows 移植版。WKWebView ≠ CDP不要期待 Playwright 同等的网络 mock 与视口模拟。会话恢复会剥离敏感环境变量Agent 若在恢复后需要 token需在恢复时重新注入。技能在应用启动时快照编辑技能文件后消费方 Agent 需要重启才能生效。旧版 v1 socket 载荷{command:...}会被拒绝只使用 v2 JSON-RPC。不要cat ~/.cmuxterm/*-hook-sessions.json期待看到密钥这些文件中的敏感信息已被擦除仅用于查看会话 / surface 映射。常用键盘快捷键类别快捷键Workspaces⌘N 新建⌘1–8 跳转⌃⌘[ / ⌃⌘] 上一个/下一个⌘⇧W 关闭⌘B 侧边栏Surfaces⌘T 新建⌘⇧[ / ⌘⇧] 上一个/下一个⌘W 关闭⌃1–8 跳转Splits⌘D 右侧拆分⌘⇧D 下侧拆分⌥⌘D 右侧浏览器⌥⌘←→↑↓ 方向聚焦⌘⇧↵ 缩放Browser⌘⇧L 打开⌘L 地址栏⌘[ / ⌘] 后退/前进⌥⌘I 开发者工具App⌘, 设置⌘⇧, 重载配置⌘⇧P 命令面板⌘⇧O 恢复会话⌃⌥⌘. 全局显示/隐藏参考与局限性说明权威帮助任何命令都以cmux cmd --help为准当前构建支持的 socket 方法可用cmux capabilities --json枚举。本技能改编自davidondrej/skills社区仓库AAS 收录时标注source: community、MIT 许可。行动前请核对本地路径、工具、凭据与各 Agent 的实际功能特性。涉及命令执行、远程访问、定时调度、浏览器自动化或文件变更类工作流时先获得用户明确批准并确认目标环境再执行操作——这既是技能自身的限制声明也符合 AAS 对risk: critical类技能的安全使用约定。赞分享AI 技能AI 插件【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址https://gitcode.com/gh_mirrors/an/agentic-awesome-skills点击查看免费下载相关推荐agentic-awesome-skills 实战从单 Agent 到多 Agent 编排的 AI 开发工作流全指南agentic awesome skills 实战从单 Agent 到多 Agent 编排的 AI 开发工作流全指南 导读 本文以 agentic awesoAI 技能AI 插件Antigravity Workflows 技能编排指南在 agentic-awesome-skills 中用多技能工作流交付 SaaS、安全审计与 AI AgentAntigravity Workflows 技能编排指南在 agentic awesome skills 中用多技能工作流交付 SaaS、安全审计与 AI AAI 技能AI 插件antigravity-skill-orchestrator 技能编排器Agentic Awesome Skills 中的元技能与多领域任务编排实战指南antigravity skill orchestrator 技能编排器Agentic Awesome Skills 中的元技能与多领域任务编排实战指南 anAI 技能AI 插件上一篇让 Goal 目标可被验证Qwen Code /goal-draft 内置技能的设计与实践下一篇Mastra 仓库中的 Ralph 命令规划指南从目标到可执行命令的完整工作流创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考