cmux-ref

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cmux Ref

cmux 引用

Use this skill when the user pastes cmux topology identifiers and expects the agent to target that exact workspace, pane, surface, or window. Treat those identifiers as explicit routing context for later instructions.

当用户粘贴cmux拓扑标识符并期望Agent定位到对应的工作区、面板、界面或窗口时，使用此技能。将这些标识符视为后续指令的显式路由上下文。

What To Recognize

需要识别的内容

Users may paste any mix of these fields, in plain text, Markdown, JSON, YAML, shell-style assignments, or logs:

text

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

Recognize these keys:

```
window_ref
```
,
```
window_id
```
```
workspace_ref
```
,
```
workspace_id
```
```
pane_ref
```
,
```
pane_id
```
```
surface_ref
```
,
```
surface_id
```

Also recognize bare refs near user intent, such as

workspace:1

pane:2

, or

surface:370

用户可能会以纯文本、Markdown、JSON、YAML、Shell风格赋值或日志的形式粘贴这些字段的任意组合：

text

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
```

同时识别用户意图附近的裸引用，例如

workspace:1

、

pane:2

或

surface:370

。

Meaning

含义

```
*_ref
```
values are short cmux refs such as
```
workspace:1
```
,
```
pane:2
```
, and
```
surface:370
```
. They are convenient for immediate CLI calls in the same cmux instance, but can be renumbered after state changes.
```
*_id
```
values are UUIDs for the same objects. Prefer them for identity checks and stale-ref recovery when both forms are available.
The most specific provided object is the default target:
```
surface
```
beats
```
pane
```
,
```
pane
```
beats
```
workspace
```
, and
```
workspace
```
beats
```
window
```
.
A complete block describes a hierarchy. Do not mix a
```
surface_id
```
from one pasted block with a
```
workspace_ref
```
from another unless the user clearly says they belong together.

```
*_ref
```
值是简短的cmux引用，例如
```
workspace:1
```
、
```
pane:2
```
和
```
surface:370
```
。它们适用于同一cmux实例中的即时CLI调用，但在状态变更后可能会被重新编号。
```
*_id
```
值是对应对象的UUID。当两种格式都可用时，优先使用它们进行身份校验和失效引用恢复。
提供的最具体对象为默认目标：
```
surface
```
优先于
```
pane
```
，
```
pane
```
优先于
```
workspace
```
，
```
workspace
```
优先于
```
window
```
。
一个完整的块描述了层级结构。除非用户明确说明它们属于同一组，否则不要将一个粘贴块中的
```
surface_id
```
与另一个块中的
```
workspace_ref
```
混合使用。

Workflow

工作流程

Step 1: Parse The Block

步骤1：解析块

Extract keys case-insensitively. Accept

separators and ignore quotes, commas, and code fences.

Useful pattern:

text

\b(window|workspace|pane|surface)_(ref|id)\b\s*[:=]\s*["']?([A-Za-z0-9:-]+)["']?

If the user provides only bare refs, bind the most specific one as the target:

text

workspace:1 pane:2 surface:370

不区分大小写地提取键名。接受

或

作为分隔符，忽略引号、逗号和代码围栏。

实用正则表达式：

text

\b(window|workspace|pane|surface)_(ref|id)\b\s*[:=]\s*["']?([A-Za-z0-9:-]+)["']?

如果用户仅提供裸引用，则将最具体的那个绑定为目标：

text

workspace:1 pane:2 surface:370

Step 2: Announce The Target

步骤2：声明目标

When taking action, say the exact target briefly:

text

I will target surface:370 in pane:2, workspace:1.

If a UUID is present, keep it in your internal target record and include it when useful for disambiguation:

text

I will target surface:370 (661B301A-2423-44F1-B789-7AEA1021CFCE).

执行操作时，简要说明确切的目标：

text

I will target surface:370 in pane:2, workspace:1.

如果存在UUID，请将其保存在内部目标记录中，并在需要消除歧义时包含它：

text

I will target surface:370 (661B301A-2423-44F1-B789-7AEA1021CFCE).

Step 3: Verify Before Mutating

步骤3：变更前验证

Before sending text, closing anything, moving surfaces, changing layout, or reading a screen for a non-current target, verify the target exists in the active cmux socket.

Use the current cmux CLI and request both refs and UUIDs:

bash

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>

If a ref is stale but the UUID exists in

tree --all

, use the current ref associated with that UUID. If neither the ref nor UUID can be found, stop and ask the user for a fresh cmux ref block.

在发送文本、关闭任何内容、移动界面、更改布局或读取非当前目标的屏幕内容之前，验证目标是否存在于活动的cmux套接字中。

使用当前的cmux CLI，并同时请求引用和UUID：

bash

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>

如果引用已失效但UUID在

tree --all

中存在，则使用该UUID对应的当前引用。如果引用和UUID都无法找到，请停止操作并向用户请求新的cmux引用块。

Step 4: Use Explicit Targets

步骤4：使用显式目标

Do not fall back to the visually focused workspace when the user pasted explicit refs. Pass the parsed workspace, pane, and surface to cmux commands.

Examples:

bash

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

If the command accepts only one handle, use the most specific relevant handle. Prefer the UUID when the command accepts UUIDs and you have verified it maps to the intended object.

当用户粘贴了显式引用时，不要退回到视觉聚焦的工作区。将解析后的工作区、面板和界面传递给cmux命令。

示例：

bash

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。

Ambiguity Rules

歧义处理规则

Ask one concise question only when the target cannot be inferred safely:

Multiple unrelated ref blocks are pasted and the instruction says only "use this" or "that one".
A workspace ref and surface ref are both present but verification shows they belong to different current hierarchies.
The pasted identifiers are stale and no UUID match exists in
```
cmux --json --id-format both tree --all
```
.

Do not ask when one complete block is present. Use the most specific target in that block.

仅当无法安全推断目标时，提出一个简洁的问题：

粘贴了多个不相关的引用块，而指令仅说明‘使用这个’或‘那个’。
同时存在工作区引用和界面引用，但验证显示它们属于不同的当前层级结构。
粘贴的标识符已失效，且在
```
cmux --json --id-format both tree --all
```
中找不到匹配的UUID。

当存在一个完整的块时，无需询问。使用该块中最具体的目标。

Safety Rules

安全规则

User-provided cmux refs override caller environment variables and visual focus.
Preserve both the ref and UUID in notes or scripts when available.
Do not change focus just to verify or use a target. Prefer non-disruptive commands and
```
--focus false
```
or
```
--no-focus
```
when supported.
Do not close, move, or send input to a target until it has been verified in the current socket.
Browser snapshot element refs are separate from cmux topology refs. Use
```
cmux-browser
```
for DOM or webview snapshot refs.

用户提供的cmux引用优先于调用者环境变量和视觉焦点。
如果可用，请在笔记或脚本中同时保留引用和UUID。
不要仅为了验证或使用目标而更改焦点。优先使用非破坏性命令，在支持时使用
```
--focus false
```
或
```
--no-focus
```
。
在当前套接字中验证目标之前，不要关闭、移动或向目标发送输入。
浏览器快照元素引用与cmux拓扑引用是分开的。对于DOM或webview快照引用，请使用
```
cmux-browser
```
。