wmux

wmux 是一个面向 AI coding agent 工作流的桌面终端复刻项目，目标参考 cmux 的核心体验：垂直工作区、分屏面板、终端/浏览器/Notebook surface、通知状态、命令面板、CLI/socket 自动化与可恢复布局。

本仓库当前先沉淀可落地方案，不追求 1:1 复制品牌和视觉，而追求达到 cmux 80%-90% 的能力覆盖。

文档索引

• 需求文档
• cmux 能力拆解
• 技术架构
• UI 设计与 gpt-image-2 资产流程
• CLI 与 Socket API 设计
• 数据模型与配置格式
• 实施路线图
• 验收清单
• Browser Automation CLI/socket 规格设计
• Socket 安全模式、trusted cwd 与 token 规格
• cmux 对齐优化清单
• Warp 风格终端体验升级 PRD

推荐路线

第一阶段不要直接做原生 Swift + libghostty。为了从零开始快速落地，建议采用：

• 桌面壳：Electron
• UI：React + TypeScript + Zustand/Jotai
• 终端：node-pty + xterm.js + WebGL renderer
• 浏览器：Electron BrowserView/WebContentsView
• 自动化：本地 Unix domain socket / Windows named pipe + CLI
• 数据：SQLite + JSON 配置
• 打包：electron-builder

这条路线牺牲一部分原生轻量感，但能最快验证分屏、终端、多 surface、内置浏览器、CLI 控制和 agent 通知这些核心价值。等产品跑通后，再评估 macOS 原生重写或局部替换为 Swift/libghostty。

Browser Automation 最小示例

启动 wmux 后，可以用本地 CLI 控制当前 browser surface：

wmux browser open "http://localhost:5173"
wmux browser list
wmux browser snapshot --surface <surfaceId>
wmux browser wait "#name" --surface <surfaceId>
wmux browser fill "#name" "wmux" --surface <surfaceId>
wmux browser type "#name" "!" --surface <surfaceId>
wmux browser press "#name" Backspace --surface <surfaceId>
wmux browser click "#submit" --surface <surfaceId>
wmux browser console list --surface <surfaceId>
wmux browser errors list --surface <surfaceId>
wmux browser cookies list --surface <surfaceId>
wmux browser storage list --surface <surfaceId>
wmux browser screenshot --surface <surfaceId> --out output/playwright/browser.png

当当前 workspace 有多个 browser surface 时，先用 wmux browser list 找到目标 surfaceId，再把 --surface <surfaceId> 加到后续命令里。

CLI/API 兼容示例

wmux current-workspace
wmux config
wmux list-surfaces
wmux focus-surface --surface <surfaceId>
wmux new-notebook --name "Runbook" --notebook-id runbook
wmux send-surface --surface <surfaceId> "npm test\n"
wmux send-key-surface --surface <surfaceId> enter
wmux new-split --direction vertical
wmux status set --status running --notice "npm test"
wmux status list
wmux status history --limit 5
wmux clear-status

Project Config

项目命令默认读取仓库根目录的 wmux.json。为兼容 cmux 项目，若 wmux.json 不存在，wmux 会读取 .cmux/cmux.json，并复用同一套 command/workspace layout schema。 可用 wmux config --json 查看当前加载的全局/项目配置来源和命令清单。

commands 支持参数化 workflow：使用 commandTemplate 和 args 后，命令面板会先打开参数表单，确认后把渲染出的命令写入当前终端输入行，由用户再按 Enter 执行。 项目根目录 .warp/workflows/*.yaml 也会自动加载，支持 Warp 的 name、command、tags、description、arguments[].name/description/default_value 字段。

Workspace layout 也支持 type: "notebook" surface。Notebook 正文保存在当前 workspace 的 .wmux/notebooks/<notebookId>.md，代码块通过隐藏 PTY session 运行，不会占用当前可见终端。

{
  "commands": [
    {
      "name": "Git Rebase",
      "commandTemplate": "git rebase {{base}} {{branch}}",
      "args": [
        { "name": "base", "default": "main", "required": true },
        { "name": "branch", "required": true }
      ]
    },
    {
      "name": "Open Runbook",
      "workspace": {
        "name": "Docs",
        "layout": {
          "pane": {
            "surfaces": [
              { "type": "notebook", "name": "Runbook", "notebookId": "runbook" }
            ]
          }
        }
      }
    }
  ]
}

Terminal Link

wmux terminal 中出现的 http:// / https:// 链接可以点击打开到当前 workspace 的内置 browser surface。若当前 workspace 没有可用 browser surface，wmux 会在当前 pane 创建一个。

Terminal Clipboard

在 terminal surface 中可以直接拖选文本。右键有选区时复制选中内容；右键无选区时把系统剪贴板内容粘贴到终端输入。

Terminal Blocks

wmux 的命令块使用 OSC 133 shell integration。需要在 shell 配置中按需启用：

# bash
source /path/to/wmux/scripts/shell-integration/wmux.bash

# zsh
source /path/to/wmux/scripts/shell-integration/wmux.zsh

PowerShell：

. D:\IdeaProject\codex\wmux\scripts\shell-integration\wmux.ps1

未启用时终端仍按普通 xterm 模式工作，只是不显示命令块。