AI Skills
cmux-workspace

cmux-workspace

熱門

在目前的 cmux 工作區與終端機中執行作業。適用於 cmux 工作區、目前工作區、呼叫者 surface、窗格 (panes)、surfaces、指定 socket 目標，以及無干擾的 cmux 自動化操作。

2.5萬星標
2120分支
更新於 2026/8/1
獲取技能源代碼

相關技能

taste24萬ui-to-vue24萬imagegen-frontend-mobile9.4萬
SKILL.md
唯讀
名稱
cmux-workspace
描述

在目前的 cmux 工作區與終端機中執行作業。適用於 cmux 工作區、目前工作區、呼叫者 surface、窗格 (panes)、surfaces、指定 socket 目標，以及無干擾的 cmux 自動化操作。

cmux Workspace

將工作範圍限制在呼叫 Agent 的 cmux 工作區內。

  • Window：macOS cmux 視窗。
  • Workspace：側邊欄中的項目。UI 介面稱其為分頁 (tab)；CLI/socket API 則稱其為工作區 (workspace)。
  • Pane：工作區內的分割區域。
  • Surface：窗格內的分頁，可以是終端機 (terminal) 或瀏覽器 (browser)。
  • Panel：surface 內部的內容類型。請優先使用 CLI 的 surface 指令，而非操控 panel 內部細節。

預設規則

將操作範圍限制在目前的呼叫者工作區（caller workspace），除非使用者明確要求切換至其他工作區、其他視窗或全域狀態。切勿假設當前視覺焦點所在的工作區就是正確的目標：Agent 可以在某個工作區中執行，而使用者正關注著另一個工作區。

printf 'workspace=%s\nsurface=%s\nsocket=%s\n' \
  "${CMUX_WORKSPACE_ID:-}" "${CMUX_SURFACE_ID:-}" "${CMUX_SOCKET_PATH:-}"
cmux identify --json

CMUX_WORKSPACE_ID 是預設的工作區錨點，CMUX_SURFACE_ID 則是預設的呼叫者終端機錨點。若兩者缺失，請回退使用 cmux identify --json，並明確告知使用者你正使用當前聚焦的上下文。

無干擾自動化

請將「佈局 (layout)」與「焦點 (focus)」視為獨立的事務。select-workspace、focus-pane、focus-panel 以及會改變焦點的 tab-action 動詞，都屬於會影響使用者操作的行為（類似滑鼠點擊）。即便是在呼叫者自己的工作區內，也絕不要投機性地呼叫這些指令，因為使用者當時可能正在關注其他地方。

請以「一次到位」且「不干擾」的方式建構佈局，直接使用能建立新窗格並填入正確 surface 的指令：

cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type browser --direction right --url "http://127.0.0.1:8765"
cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type terminal --direction down

避免使用「建立 → 移動 → 聚焦」這種連續操作鏈。只要指令支援 --focus false 參數就請務必加上（例如 move-surface --focus false 可以保留使用者的注意力；未來會有更多指令支援此旗標，詳見 https://github.com/manaflow-ai/cmux/issues/1418 及 https://github.com/manaflow-ai/cmux/issues/2820）。如果佈局指令拒絕了有效的 surface: 或 pane: 參照，請回報此 Bug 並停止執行，切勿透過強行聚焦來規避問題。

右側輔助窗格

對於輔助輸出（預覽應用程式、TUI、日誌、一次性 Shell、瀏覽器檢查等），請重用呼叫者終端機右側的單一輔助窗格（helper pane）。請先使用 cmux identify --json、cmux list-panes 與 cmux list-pane-surfaces 進行檢查，然後：

  • 若輔助窗格已存在：直接向其新增 surface。
    cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:<helper> --type terminal --focus false
  • 若不存在輔助窗格：精確建立一個。
    cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false
  • 若發現先前自動化留下的多個明顯過時的輔助窗格，且使用者要求整理：保留一個並清理重複項。絕不要關閉你無法確定是否為過時輔助輸出的窗格。

透過明確的 surface 參照將指令發送到新建或重用的 surface。重複的「開啟」請求應該在現有的右側輔助窗格內建立新分頁，而不是產生更多窗格分割。

呼叫者終端機

呼叫 Agent 的 surface 是進行相對操作時最安全的錨點。

cmux send "npm test\n"                                    # focused terminal in caller workspace
cmux send --surface "${CMUX_SURFACE_ID:-}" "git status\n"  # exact caller surface
cmux send-key --surface "${CMUX_SURFACE_ID:-}" enter

除非使用者明確指定該目標，否則切勿在其他工作區中傳送按鍵、關閉 surface 或變更焦點。

移動 Surface

cmux move-surface --surface "${CMUX_SURFACE_ID}" --before surface:3   # also --after, --index
cmux move-surface --surface surface:240 --pane pane:172 --focus false
cmux drag-surface-to-split --surface surface:240 down

已知痛點：drag-surface-to-split 會經由 V1 路由並透過 UI 焦點解析工作區，因此當呼叫者的工作區不是視覺上聚焦的工作區時，會失敗並顯示 ERROR: Surface not found（詳見 https://github.com/manaflow-ai/cmux/issues/1901，相關議題 https://github.com/manaflow-ai/cmux/issues/3189）。在該 issue 解決前，請以疊加方式建構佈局。絕不要為了從移動失敗中恢復而呼叫 focus-pane 或 focus-panel；請直接回報失敗並停止操作。

側邊欄狀態

將狀態、進度與日誌附隨至當前工作區，以便側邊欄能及時反映此任務的進度。

cmux set-status build "running" --workspace "${CMUX_WORKSPACE_ID:-}" --color "#ff9500"
cmux set-progress 0.4 --label "Building" --workspace "${CMUX_WORKSPACE_ID:-}"
cmux log --workspace "${CMUX_WORKSPACE_ID:-}" --level info -- "Started build"
cmux sidebar-state --workspace "${CMUX_WORKSPACE_ID:-}" --json

貢獻者重新載入 (Reloads)

在 cmux 原始碼工作目錄中進行 cmux 應用程式/執行階段變更時，請從目前活躍的 worktree 使用標籤化的重新載入（tagged reload）。這會建立獨立的應用程式名稱、Bundle ID、除錯 socket 以及 DerivedData 路徑。切勿建置或啟動未標籤的 cmux DEV。

./scripts/reload.sh --tag <short-tag>
CMUX_SOCKET_PATH=/tmp/cmux-debug-<short-tag>.sock cmux identify --json

Socket 存取權限

請在任何預設值之前，優先使用 cmux 提供給你的 socket 路徑：SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}"。Socket 存取權限可能是關閉的、僅限 cmux 產生的程序，或是對所有本機程序開放。如果指令無法連線，請在變更設定前先檢查 cmux capabilities --json 與 cmux ping。

規則

  • 預設在呼叫者工作區中執行操作；即使環境變數已設定，變更類的動作仍建議使用明確的 --workspace 和 --surface 旗標，使自動化流程具備可稽核性。
  • 除非使用者明確要求，否則絕不呼叫 focus-pane、focus-panel、select-workspace 或任何會改變焦點的 tab-action 動詞。
  • 在 move-surface 以及任何支援該旗標的建立動詞上，傳遞 --focus false。
  • 使用 new-pane --type ... --url ... 以疊加方式建構佈局，而不是使用「建立 → 移動 → 聚焦」模式。
  • 如果 CLI 指令拒絕了有效的 surface 或 pane 參照，請直接回報，切勿透過強行聚焦來規避。
  • 除非使用者指定該目標，否則不得對其他工作區進行關閉、聚焦、移動或傳送輸入等操作。
  • 在對話與範例中使用簡短參照（short refs）；僅在日誌記錄、持久化或偵錯時使用 UUID。

參考資料