mcpField
C
cmux-ref

cmux-ref

github.com/manaflow-aiAgent 工作流39720 次安装9 周前更新
代码仓库

关于 cmux-ref

cmux-ref 是一项 Agent 技能，用于解析用户提供的 cmux 工作区、窗格、界面和窗口标识。它会验证并选择最具体的目标执行后续操作，而不退回到视觉焦点所在位置。

主要功能

  1. 01解析 cmux 引用和 UUID
  2. 02选择最具体的目标
  3. 03操作前验证目标
  4. 04通过 UUID 恢复过期引用
  5. 05保留明确的路由上下文

适用场景

  1. 01向指定终端界面发送命令
  2. 02在指定工作区和窗格中打开内容
  3. 03cmux 状态变化后解析过期引用
  4. 04避免在视觉焦点所在工作区误操作

安装

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

$npx skills add https://github.com/manaflow-ai/cmux-skills --skill cmux-ref

安装后在 Claude Code 中输入/cmux-ref确认已加载。

附带文件agents/openai.yaml

详细介绍

cmux 引用

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

识别内容

用户可能以纯文本、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

同时识别用户意图附近单独出现的引用，例如 workspace:1、pane:2 或 surface:370。

含义

  • *_ref 值是简短的 cmux 引用，例如 workspace:1、pane:2 和 surface:370。它们便于在同一 cmux 实例中立即调用 CLI，但状态发生变化后可能会重新编号。
  • *_id 值是相应对象的 UUID。如果两种形式都可用，身份检查和过期引用恢复时优先使用 UUID。
  • 提供的对象中最具体的对象是默认目标：surface 优先于 pane，pane 优先于 workspace，workspace 优先于 window。
  • 完整区块描述一个层级结构。除非用户明确说明它们属于同一层级，否则不要将一个粘贴区块中的 surface_id 与另一个区块中的 workspace_ref 混用。

工作流

步骤 1：解析区块

不区分大小写地提取键。接受 = 或 : 分隔符，并忽略引号、逗号和代码围栏。

实用模式：

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

如果用户只提供单独的引用，将其中最具体的引用设为目标：

workspace:1 pane:2 surface:370
步骤 2：说明目标

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

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

如果提供了 UUID，将其保留在内部目标记录中，并在有助于消除歧义时一并说明：

I will target surface:370 (661B301A-2423-44F1-B789-7AEA1021CFCE).
步骤 3：修改前验证

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

使用当前 cmux CLI，同时请求引用和 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>

如果引用已过期，但 UUID 存在于 tree --all 中，则使用与该 UUID 关联的当前引用。如果既找不到引用，也找不到 UUID，则停止操作并请用户提供新的 cmux 引用区块。

步骤 4：使用明确的目标

用户粘贴了明确引用时，不要回退到视觉上聚焦的工作区。将解析出的 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 对应预期对象，则优先使用 UUID。

歧义规则

只有在无法安全推断目标时，才提出一个简洁的问题：

  • 粘贴了多个互不相关的引用区块，且指令只有“用这个”或“用那个”。
  • 同时提供了 workspace 引用和 surface 引用，但验证发现它们属于不同的当前层级结构。
  • 粘贴的标识符已过期，且在 cmux --json --id-format both tree --all 中找不到匹配的 UUID。

如果只有一个完整区块，则不要提问。使用该区块中最具体的目标。

安全规则

  • 用户提供的 cmux 引用优先于调用方环境变量和视觉焦点。
  • 如果可用，在备注或脚本中同时保留引用和 UUID。
  • 不要仅为验证或使用目标而更改焦点。优先使用不会造成干扰的命令；在支持时使用 --focus false 或 --no-focus。
  • 在当前 socket 中验证目标之前，不要关闭、移动目标，也不要向其发送输入。
  • 浏览器快照元素引用与 cmux 拓扑引用是不同的。对于 DOM 或 webview 快照引用，请使用 cmux-browser。

评论

支持 Markdown