cmux Ref 是一个面向 cmux 环境的技能，用于解释用户粘贴的 cmux 工作区、窗格、表面或窗口的 ref 与 id。当用户粘贴 cmux 拓扑标识符并期望智能体定位到确切的 workspace、pane、surface 或 window 时，应使用此技能。这些标识符被视为后续指令的显式路由上下文。
用途
该技能的核心用途是让智能体能够准确识别用户提供的 cmux 拓扑标识符，并将其作为操作目标，而不是依赖视觉焦点或环境变量。它适用于需要在特定 cmux 对象上执行命令、读取屏幕、发送输入、创建表面或打开文件等场景。
主要能力
识别多种格式的标识符。用户可能以纯文本、Markdown、JSON、YAML、shell 风格赋值或日志等形式粘贴以下字段的任意组合：
workspace_ref=workspace:1 workspace_id=D9C23F06-55C8-4EF6-96D2-F2531B3327A8 pane_ref=pane:2 pane_id=60495E4A-56E3-469D-A274-A7877F48B54D surface_ref=surface:370 surface_id=661B301A-2423-44F1-B789-7AEA1021CFCE
需要识别的键包括：window_ref、window_id、workspace_ref、workspace_id、pane_ref、pane_id、surface_ref、surface_id。同时也要识别用户意图附近的裸 ref，例如 workspace:1、pane:2 或 surface:370。
区分 ref 与 id 的含义。_ref 值是简短的 cmux ref，如 workspace:1、pane:2 和 surface:370。它们便于在同一 cmux 实例中立即进行 CLI 调用，但在状态变化后可能会重新编号。_id 值是同一对象的 UUID。当两种形式都可用时，优先使用 UUID 进行身份检查和过期 ref 恢复。
确定默认目标。提供的最具体对象是默认目标：surface 优先于 pane，pane 优先于 workspace，workspace 优先于 window。一个完整的块描述一个层级结构。除非用户明确说明它们属于一起，否则不要将一个粘贴块中的 surface_id 与另一个块中的 workspace_ref 混用。
使用方式
工作流程分为四个步骤。
第一步：解析标识块。以不区分大小写的方式提取键。接受 = 或 : 分隔符，忽略引号、逗号和代码围栏。可用的模式为：\b(window|workspace|pane|surface)_(ref|id)\b\s*[:=]\s*["']?([A-Za-z0-9:-]+)["']?。如果用户只提供裸 ref，则将最具体的一个绑定为目标，例如 workspace:1 pane:2 surface:370。
第二步：声明目标。在执行操作时，简要说明确切目标，例如：I will target surface:370 in pane:2, workspace:1. 如果存在 UUID，将其保留在内部目标记录中，并在有助于消歧时包含它，例如：I will target surface:370 (661B301A-2423-44F1-B789-7AEA1021CFCE).
第三步：变更前验证。在发送文本、关闭任何内容、移动表面、更改布局或为非当前目标读取屏幕之前，验证目标是否存在于活动的 cmux socket 中。使用当前的 cmux CLI 并请求 ref 和 UUID：
cmux --json --id-format both tree --all cmux --json --id-format both identify cmux --json --id-format both list-pane-surfaces --workspace <workspace_ref_or_id>
如果 ref 已过期但 UUID 存在于 tree --all 中，则使用与该 UUID 关联的当前 ref。如果 ref 和 UUID 都找不到，则停止并请用户提供新的 cmux ref 块。
第四步：使用显式目标。当用户粘贴了显式 ref 时，不要回退到视觉焦点的工作区。将解析出的 workspace、pane 和 surface 传递给 cmux 命令。示例：
cmux read-screen --workspace workspace:1 --surface surface:370 --scrollback --lines 120 cmux send --workspace workspace:1 --surface surface:370 "npm test\n" cmux new-surface --workspace workspace:1 --pane pane:2 --type terminal --focus false cmux open ./report.html --workspace workspace:1 --pane pane:2 --no-focus
如果命令只接受一个句柄，则使用最具体的相关句柄。当命令接受 UUID 且已验证其映射到预期对象时，优先使用 UUID。
歧义规则
仅当无法安全推断目标时，才提出一个简洁的问题。情况包括：粘贴了多个不相关的 ref 块，而指令只说“use this”或“that one”；同时存在 workspace ref 和 surface ref，但验证显示它们属于不同的当前层级；粘贴的标识符已过期，且在 cmux --json --id-format both tree --all 中不存在 UUID 匹配。当存在一个完整的块时，不要提问，使用该块中最具体的目标。
安全规则
用户提供的 cmux ref 优先于调用方环境变量和视觉焦点。在可用时，在笔记或脚本中同时保留 ref 和 UUID。不要仅仅为了验证或使用目标而更改焦点。优先使用非破坏性命令，并在支持时使用 --focus false 或 --no-focus。在目标于当前 socket 中验证之前，不要关闭、移动或向其发送输入。浏览器快照元素 ref 与 cmux 拓扑 ref 是分开的。对于 DOM 或 webview 快照 ref，请使用 cmux-browser。
适用场景
该技能适用于用户粘贴 cmux 拓扑标识符并期望智能体针对确切的 workspace、pane、surface 或 window 执行操作的场景。例如，在特定表面中运行测试、读取特定表面的屏幕内容、在特定窗格中创建新表面或打开文件等。
限制
该技能依赖于 cmux 环境及其 CLI。如果目标无法在当前 socket 中验证，则无法安全操作。ref 可能因状态变化而过期，此时需要 UUID 进行恢复。如果既无有效 ref 也无 UUID，则必须停止并请求用户提供新的标识块。该技能不处理浏览器快照元素 ref，后者应使用 cmux-browser。