cmux-customization

cmux 自定义

使用此技能进行面向用户的 cmux 自定义。保持用户配置不变，优先使用基于 schema 的编辑，并在报告完成前进行验证。

可自定义的内容

• 自定义操作：在 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 的命令面板操作。它将出现在 Cmd+Shift+P 中，除非 palette 为 false：

{
  "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": "Dev",
        "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 设置。
• 保持标签足够短，以适应菜单、按钮和命令面板。