cmux-groups

cmux 工作区组

工作区组是在 cmux 侧边栏中可折叠的命名分区。每个组都归一个锚点工作区所有。组标题就是锚点在侧边栏中的呈现形式，因此不会为锚点单独显示一行。关闭锚点会解散该组，同时保留其他成员作为未分组工作区。

CLI

建议使用规范的名词形式：

cmux workspace group list [--json]
cmux workspace group create --name <name> [--cwd <path>] [--from <id>,<id>]
cmux workspace group ungroup <group-id>
cmux workspace group delete <group-id>
cmux workspace group rename <group-id> --name <new>
cmux workspace group collapse <group-id>
cmux workspace group expand <group-id>
cmux workspace group pin <group-id>
cmux workspace group unpin <group-id>
cmux workspace group add --group <group-id> --workspace <workspace-id>
cmux workspace group remove --workspace <workspace-id>
cmux workspace group set-anchor --group <group-id> --workspace <workspace-id>
cmux workspace group new-workspace <group-id> [--placement afterCurrent|top|end]
cmux workspace group set-color <group-id> [--hex #RRGGBB]
cmux workspace group set-icon <group-id> [--symbol <sf-symbol>]
cmux workspace group move <group-id> --to-index <n> | --before <group-id> | --after <group-id>
cmux workspace group focus <group-id>

cmux workspace-group ... 是执行相同操作的兼容别名。<group-id> 接受 UUID 或 workspace_group:1 这样的引用。所有命令都支持 --json。

create 会插入一个新的锚点工作区，不会将现有工作区提升为锚点。--from 用于列出将作为子工作区加入新锚点的工作区。省略 --from 时，如果可用，cmux 会使用当前活动的侧边栏选中项或调用方工作区。

ungroup 会解散一个组，同时保留所有成员工作区，包括会变成普通未分组工作区的锚点。delete 具有破坏性，会关闭组内的所有工作区。

new-workspace 会执行组的新建工作区行为：在锚点的当前工作目录中创建一个新工作区，并将其加入该组。可以显式传入位置，也可以根据每个当前工作目录的配置或全局组默认值确定位置。

Socket 方法

CLI 是 v2 JSON socket API 的轻量封装。所有可通过 CLI 调用的操作也可以直接调用：

workspace.group.list
workspace.group.create        { name, cwd?, child_workspace_ids? }
workspace.group.ungroup       { group_id }
workspace.group.delete        { group_id }
workspace.group.rename        { group_id, name }
workspace.group.collapse      { group_id }
workspace.group.expand        { group_id }
workspace.group.pin           { group_id }
workspace.group.unpin         { group_id }
workspace.group.add           { group_id, workspace_id }
workspace.group.remove        { workspace_id }
workspace.group.set_anchor    { group_id, workspace_id }
workspace.group.new_workspace { group_id, placement? }
workspace.group.set_color     { group_id, hex? }
workspace.group.set_icon      { group_id, symbol? }
workspace.group.move          { group_id, to_index? | before_group_id? | after_group_id? }
workspace.group.focus         { group_id }

所有方法都接受标准的 window_id / window_ref 参数，以指定非焦点窗口。

配置（~/.config/cmux/cmux.json）

每个组的设置按锚点当前工作目录进行匹配。带有 * 或 ? 的键是支持 ~ 展开的 fnmatch glob。其他键是路径前缀。优先采用匹配长度最长的键。

{
  "workspaceGroups": {
    "newWorkspacePlacement": "afterCurrent",
    "byCwd": {
      "/abs/path/to/repo": {
        "color": "#7A4FD8",
        "icon": "ladybug.fill",
        "newWorkspacePlacement": "top",
        "contextMenu": [
          { "action": "newWorktreeAction", "title": "New Worktree" },
          { "action": "newWorkspace" }
        ]
      },
      "~/projects/*": {
        "icon": "leaf.fill",
        "newWorkspacePlacement": "end"
      }
    }
  }
}

workspaceGroups.newWorkspacePlacement 和 workspaceGroups.byCwd[...].newWorkspacePlacement 接受：

• afterCurrent：放在当前活动的组内工作区之后。如果没有活动成员引用，则回退到顶部。
• top：放在第二个位置，即紧跟锚点之后。
• end：放在最后一个成员之后。

组中新建工作区的位置解析顺序：

1. CLI 中显式指定 --placement afterCurrent|top|end，或 workspace.group.new_workspace 中的 "placement"。
2. 每个当前工作目录的 workspaceGroups.byCwd[...].newWorkspacePlacement。
3. 全局的 workspaceGroups.newWorkspacePlacement。
4. 内置默认值 afterCurrent。

在组内按 Cmd-N 时，会将当前活动的组工作区作为位置参考。组标题上的 + 按钮和 CLI 路径会将锚点作为参考，因此此处的 afterCurrent 效果等同于 top。

组上下文菜单项使用与 ui.newWorkspace.contextMenu 相同的架构；操作必须在全局 actions 块中定义，或属于内置操作，例如 newWorkspace。

键盘

默认快捷键：Cmd-Shift-G 将侧边栏中选中的工作区编组。如果没有侧边栏选中项，则会使用焦点工作区。可在“设置” > “键盘”中重新绑定。

锚点语义

• 锚点身份保存在组上（anchorWorkspaceId），而不是作为工作区的标志。
• 锚点会呈现为组标题，不会在侧边栏中单独显示一行。
• 关闭锚点会在确认对话框后解散该组。
• set-anchor 会重新指定哪个成员作为锚点；先前的锚点工作区会变成普通成员，并在侧边栏中显示自己的行。

持久化

组和成员关系通过现有的 SessionPersistenceStore 在 ~/Library/Application Support/cmux/session-<bundle-id>.json 中进行往返持久化。写入时会原子地重命名到目标位置；不使用 WAL。

规则

• 优先使用 CLI 或 socket 操作，而不是编辑会话 JSON。
• 不要写入尚不支持的未来配置键。不确定时，请检查 cmux 中的 web/data/cmux.schema.json。
• 编写脚本时应保留锚点语义：移动组意味着移动锚点分区，而不只是移动子工作区行。
• 需要保留工作区时使用 ungroup；只有在需要关闭组内所有工作区时才使用 delete。