cmux-customization

cmux 自訂指南

使用此技能進行使用者面向的 cmux 自訂。保留使用者的設定檔，優先採用結構化編輯，並在回報完成前進行驗證。

可自訂項目

• 自訂動作：在 cmux.json 中定義可重複使用的 actions。動作可出現在 Cmd+Shift+P、分頁標籤列、快捷鍵以及加號按鈕的右鍵選單中。
• 新增工作區按鈕：設定 ui.newWorkspace.action 取代一般加號按鈕點擊行為，並用 ui.newWorkspace.contextMenu 控制右鍵選單動作。ui.newWorkspace.rightClick 可作為別名使用，但新範例應使用 contextMenu。
• 分頁標籤列按鈕：設定 ui.surfaceTabBar.buttons 取代預設的分頁標籤列按鈕。僅在需要保留可見性時，才包含內建 ID，例如 cmux.newTerminal、cmux.newBrowser、cmux.splitRight 和 cmux.splitDown。
• 工作流程與佈局：使用 commands 搭配工作區定義，以刻意分割的佈局開啟工作樹、多個檢出、本地服務、瀏覽器預覽或 SSH 連線。
• Dock 控制項：建立 .cmux/dock.json 或 ~/.config/cmux/dock.json，用於右側邊欄的終端控制項，例如日誌、測試監視器、Git TUI、開發伺服器、佇列或 cmux feed tui --opentui。
• 側邊欄與應用程式行為：使用 cmux-settings 設定支援的選項，例如外觀、側邊欄顯示、通知行為、瀏覽器路由、自動化、快捷鍵以及新工作區放置位置。
• 工作區中繼資料：使用 cmux CLI 或 cmux-workspace 更新工作區名稱、描述、顏色、已讀狀態及側邊欄中繼資料。
• Feed 與通知：使用 cmux hooks setup 設定 Feed 事件來源、通知傳遞行為的設定，以及在 cmux.json 中設定通知鉤子以過濾或後處理橫幅。
• 團隊預設與範例：使用專案本地的 .cmux/cmux.json 和 .cmux/dock.json，與儲存庫分享工作樹、SSH、審查、開發、CI 及文件工作區模式。
• 匯入、匯出與重設：備份目前設定，套用最小差異，進行驗證，並保留使用者自訂的復原路徑。
• 終端行為：使用 Ghostty 設定字型、主題、游標樣式、選取即複製、Shell 整合、終端按鍵綁定及終端渲染。

選擇正確的層面

• cmux 應用程式偏好：使用 cmux-settings 設定全域的 ~/.config/cmux/cmux.json 設定，例如外觀、側邊欄、通知、瀏覽器行為、自動化及快捷鍵。
• 自訂動作、工作區佈局、分頁標籤列按鈕、加號按鈕行為及指令面板項目：全域編輯 ~/.config/cmux/cmux.json，或在專案中編輯 .cmux/cmux.json。專案本地的動作和指令會覆蓋相同 ID 或名稱的全域項目。
• Dock 控制項：在專案中編輯 .cmux/dock.json，或全域編輯 ~/.config/cmux/dock.json。可用時執行 cmux docs dock。
• 終端渲染與終端按鍵綁定：使用 Ghostty 設定，通常位於 ~/.config/ghostty/config。這包括字型、游標樣式、選取即複製、Shell 整合、主題及終端按鍵綁定。
• 專案特定行為：優先使用專案中的 .cmux/cmux.json，讓動作、指令、UI 動作綁定及通知鉤子隨儲存庫一起移動。請勿將全域應用程式偏好放在那裡。

如果請求可由 Ghostty 設定處理，請說明並使用 Ghostty 設定，而非自行發明 cmux UI 設定。

範例庫

如需可重複使用的模式，例如工作樹代理、全端開發佈局、SSH 開發盒、PR 審查工作區、文件工作區、快速代理分頁按鈕及 CI 監視器，請閱讀 references/examples.md。當使用者要求範例、預設、模板、入門設定或已知工作流程形狀時，請載入該檔案。

工作流程

1. 在編輯前檢查現有設定。

   test -f ~/.config/cmux/cmux.json && sed -n '1,220p' ~/.config/cmux/cmux.json
   test -f .cmux/cmux.json && sed -n '1,220p' .cmux/cmux.json
   

2. 選擇全域或專案本地範圍。僅在選擇會顯著改變行為時才詢問。預設對儲存庫特定指令使用專案本地，對應用程式偏好使用全域。

3. 編輯前，若目標檔案已存在則進行備份：

   stamp="$(date +%Y%m%d-%H%M%S)"
   test -f ~/.config/cmux/cmux.json && cp -p ~/.config/cmux/cmux.json ~/.config/cmux/cmux.json."$stamp".bak
   test -f .cmux/cmux.json && cp -p .cmux/cmux.json .cmux/cmux.json."$stamp".bak
   

   僅使用適用的路徑。若檔案不存在，請勿建立備份。

4. 對於應用程式設定和 cmux 擁有的快捷鍵，使用已安裝技能或檢出中的設定輔助工具：

   ~/.agents/skills/cmux-settings/scripts/cmux-settings list-supported
   ~/.agents/skills/cmux-settings/scripts/cmux-settings set browser.openTerminalLinksInCmuxBrowser true
   ~/.agents/skills/cmux-settings/scripts/cmux-settings validate
   

   如果使用者透過 skills.sh 安裝，請改用 ~/.codex/skills/cmux-settings/scripts/cmux-settings。

5. 對於動作、UI 綁定、工作區佈局、通知鉤子和 Dock 控制項，請仔細編輯 JSONC 或 JSON。保留不相關的區段，例如 vault、rightSidebar、commands、actions、ui 和 notifications。

6. 成功編輯後重新載入設定：

   cmux reload-config
   

7. 驗證設定的進入點是否存在。對於快捷鍵，讀回綁定。對於自訂動作，確認動作 ID 及其應出現的位置。

常見模式

新增一個指令面板動作，在新分頁中開啟 Codex。除非 palette 設為 false，否則它會出現在 Cmd+Shift+P 中：

{
  "actions": {
    "codex-new-tab": {
      "type": "agent",
      "agent": "codex",
      "title": "Codex",
      "subtitle": "在此工作區啟動 Codex",
      "target": "newTabInCurrentPane",
      "palette": true
    }
  }
}

取代加號按鈕點擊行為，並定義加號按鈕的右鍵選單。這是「自帶工作樹、多個檢出或 SSH 設定」的模式。workspaceCommand 動作 ID 為 worktree-agents，其 commandName 必須與同一設定中名為 Worktree Agents 的指令相符：

{
  "actions": {
    "worktree-agents": {
      "type": "workspaceCommand",
      "title": "Worktree Agents",
      "commandName": "Worktree Agents",
      "icon": { "type": "symbol", "name": "folder.badge.plus" }
    }
  },
  "ui": {
    "newWorkspace": {
      "action": "worktree-agents",
      "contextMenu": [
        { "action": "worktree-agents", "title": "Worktree Agents" },
        { "type": "separator" },
        { "action": "cmux.newTerminal", "title": "新增終端機" },
        { "action": "cmux.newBrowser", "title": "新增瀏覽器" }
      ]
    }
  },
  "commands": [
    {
      "name": "Worktree Agents",
      "description": "建立工作樹並在其中開啟代理",
      "workspace": {
        "name": "Worktree Agents",
        "cwd": "../worktrees/my-feature",
        "layout": {
          "direction": "horizontal",
          "children": [
            {
              "pane": {
                "surfaces": [
                  { "type": "terminal", "name": "Codex", "command": "codex" }
                ]
              }
            },
            {
              "pane": {
                "surfaces": [
                  { "type": "terminal", "name": "SSH", "command": "ssh devbox" }
                ]
              }
            }
          ]
        }
      }
    }
  ]
}

新增專案工作區佈局：

{
  "commands": [
    {
      "name": "dev",
      "workspace": {
        "name": "開發",
        "cwd": ".",
        "layout": {
          "direction": "horizontal",
          "children": [
            { "pane": { "surfaces": [{ "type": "terminal", "command": "bun dev" }] } },
            { "pane": { "surfaces": [{ "type": "browser", "url": "http://localhost:3000" }] } }
          ]
        }
      }
    }
  ]
}

取代分頁標籤列按鈕：

{
  "ui": {
    "surfaceTabBar": {
      "buttons": [
        "cmux.newTerminal",
        "cmux.newBrowser",
        {
          "action": "codex-new-tab",
          "title": "Codex",
          "icon": { "type": "symbol", "name": "terminal" }
        }
      ]
    }
  }
}

新增專案 Dock 控制項：

{
  "controls": [
    {
      "id": "git",
      "title": "Git",
      "command": "lazygit",
      "cwd": ".",
      "height": 300
    },
    {
      "id": "feed",
      "title": "Feed",
      "command": "cmux feed tui --opentui",
      "height": 260
    }
  ]
}

驗證

• 應用程式設定：執行 cmux-settings validate。
• JSONC 結構：保持有效的 JSONC，避免重複鍵值。
• Dock JSON：在回報完成前，使用 JSON 解析器解析 .cmux/dock.json 或 ~/.config/cmux/dock.json。
• 執行時期重新載入：當 CLI 可用時，執行 cmux reload-config。
• 使用者面向動作：確認使用者要求的動作標題、快捷鍵、加號按鈕行為、右鍵選單項目或分頁標籤列位置。

規則

• 除非您擁有整個區段，否則不要覆寫整個頂層設定區段。
• 不要直接將機密儲存在動作、指令或提示中。請使用環境變數或使用者的密碼管理員。
• 不要在產生的指令中使用應用程式/執行時期睡眠或時序繞道。
• 不要為 Ghostty 已擁有的行為新增 cmux 設定。
• 保持標籤簡短，以適合選單、按鈕和指令面板。