cmux-customize

cmux-customize

当你需要更改存储在应用源码树之外的个人 cmux 配置时，尤其是 ~/.config/cmux/cmux.json 和项目本地的 .cmux/cmux.json 文件，请使用此技能。它涵盖操作注册表条目、界面标签栏按钮、加号按钮的点击和右键菜单行为、自定义工作区命令、右侧边栏配置，以及相关配置清理。

前提条件

• 读取和写入全局 ~/.config/cmux/cmux.json 时，请使用 cmux-settings 技能中的 cmux-settings 辅助脚本。
• 如果任务涉及 app、terminal、notifications、sidebar、sidebarAppearance、workspaceColors、automation、browser 或 shortcuts 下的标准设置，请先阅读 cmux-settings 技能。

参考

全局配置：

cmux-settings path
cmux-settings dump --no-comments

cmux.json 中常见的结构区段：

• actions：供自定义界面和命令使用的操作注册表。
• ui.surfaceTabBar.buttons：在界面标签栏中显示的按钮。
• ui.newWorkspace.action：点击加号按钮时触发的操作。
• ui.newWorkspace.contextMenu：右键点击加号按钮时显示的菜单项。
• commands：命名的工作区命令和布局。
• rightSidebar：自定义右侧边栏配置。
• vault：自定义 Vault Agent 注册项。

ui.surfaceTabBar.buttons 可包含以字符串形式表示的内置操作 ID，也可包含对象引用：

[
  "cmux.newTerminal",
  "cmux.newBrowser",
  "cmux.splitRight",
  "cmux.splitDown",
  { "action": "custom-action-id" }
]

加号按钮的右键菜单请使用 ui.newWorkspace.contextMenu。cmux 接受 ui.newWorkspace.rightClick 作为旧版别名，但新增或修改配置时应使用 contextMenu。

工作流

步骤 1：检查当前配置

更改前先读取现有配置。

cmux-settings dump --no-comments

如果用户提到了某个可见界面区域，请搜索相关 ID。

rg -n "surfaceTabBar|newWorkspace|rightSidebar|<action-id>|<label>" ~/.config/cmux/cmux.json

步骤 2：进行最小幅度的配置修改

修改全局配置时请使用辅助脚本。它会解析 JSONC 并以原子方式写入。

从界面标签栏中移除自定义 Agent 启动按钮，同时保留内置界面控件：

cmux-settings set ui.surfaceTabBar.buttons \
  '["cmux.newTerminal","cmux.newBrowser","cmux.splitRight","cmux.splitDown"]'

从标签栏中移除一个指定操作，但不删除操作注册表条目：

cmux-settings get ui.surfaceTabBar.buttons
# Edit the array to remove only { "action": "<action-id>" }, then set it back.

只有当用户要求从所有界面中彻底移除某条命令时，才删除对应的操作定义。

cmux-settings unset actions.<action-id>

自定义加号按钮及其右键菜单：

cmux-settings set ui.newWorkspace.action '"workspace-new-cmux-worktree"'
cmux-settings set ui.newWorkspace.contextMenu \
  '[{"action":"workspace-new-cmux-worktree","title":"New cmux Worktree"},{"action":"workspace-terminal-browser","title":"Terminal + Browser"},{"type":"separator"},{"action":"cmux.newTerminal","title":"New Terminal"},{"action":"cmux.newBrowser","title":"New Browser"}]'

步骤 3：验证

务必重新读取已更改的路径。

cmux-settings get ui.surfaceTabBar.buttons
cmux-settings get ui.newWorkspace.contextMenu

验证配置是否可解析。受支持键的严格验证器可能会将有效的结构键或较新应用的键标记为无效，特别是在检出的源码列表早于正在运行的应用时。如果出现这种情况，不要删除无关的键。确认文件可以解析，并说明这是无关的验证器警告。

cmux-settings dump --no-comments >/tmp/cmux-config.json

步骤 4：说明应用方式

cmux 会监视 ~/.config/cmux/cmux.json，因此配置编辑保存后即可生效，无需重新构建。仅修改配置或技能时，不要执行带标签的应用重载。

规则

• 保留无关的自定义操作、命令、菜单、Vault 条目和右侧边栏配置。
• 不要仅因为按钮已从标签栏移除，就删除操作定义。
• 不要使用 defaults write 修改持久化的产品配置。
• 不要为用户配置更改编辑 repo/。
• 仅修改配置或技能时，不要执行应用重载。
• 回复应简短，并注明具体更改的路径或键。