wmux：原生Windows终端复用器，集成AI与浏览器自动化

1. 项目概述：为什么我们需要一个原生的 Windows 终端复用器？

如果你是一名长期在 Windows 上工作的开发者，尤其是深度依赖命令行工具和 AI 编程助手（如 Claude Code、Cursor、GitHub Copilot CLI）的开发者，那么你一定对 Linux/macOS 上强大的tmux或screen工具心生羡慕。在 Windows 上，我们长期面临一个尴尬的局面：要么依赖 Windows Subsystem for Linux (WSL)，在 Linux 子系统中运行tmux；要么使用一些功能有限或体验割裂的第三方工具。这种“曲线救国”的方式，不仅增加了系统复杂性，也让 AI 助手与本地开发环境的深度集成变得困难重重。

wmux的出现，正是为了解决这个痛点。它不是一个简单的模仿者，而是一个为现代 Windows 开发工作流，特别是 AI 辅助编程场景，量身打造的原生终端复用器。它的核心价值在于：让你能在单个窗口内，以原生、高效的方式，同时运行多个终端会话和浏览器自动化任务，并让 AI 助手（如 Claude Code）真正“看见”和“操作”这个环境。想象一下，你可以在左侧窗格让 Claude Code 编写后端 API，在右侧窗格用 Codex CLI 生成前端组件，同时在底部的浏览器面板中实时预览效果，所有操作都在一个无缝集成的界面中完成。这不仅仅是窗口管理，更是工作流的革命性整合。

我最初接触这个项目，是因为在尝试构建一个多 AI 代理协作的自动化脚本时，被 Windows 上终端管理的碎片化体验深深困扰。wmux 不仅提供了tmux式的分屏、会话持久化等核心功能，更关键的是，它通过内置的 MCP 服务器和 Chrome DevTools Protocol 桥接，为 AI 助手打开了一扇直接与本地开发环境交互的“大门”。这意味着，AI 不仅能读取终端输出，还能控制浏览器进行搜索、点击、填写表单等真实操作，将 AI 的“思考”直接转化为“行动”。对于追求效率的开发者而言，这无疑是一个强大的生产力倍增器。

2. 核心设计思路与架构解析

2.1 定位：不止于 tmux 替代品

很多用户第一眼看到 wmux，会认为它只是一个 Windows 版的tmux。这理解对了一半，但低估了它的野心。wmux 的设计目标是成为一个“AI 代理优先”的终端工作台。它从底层架构上就考虑到了如何更好地服务于 AI 编码代理。

传统的终端复用器主要解决两个问题：1) 会话管理（防止 SSH 断开导致任务终止）；2) 屏幕空间管理（分屏）。wmux 在此基础上，增加了第三个维度：环境感知与自动化接口。它通过 MCP 协议，将终端状态、浏览器控制能力暴露给 AI 代理，使得 AI 能够理解当前上下文并执行复杂操作。这种设计思路，让 wmux 从一个被动的“显示容器”，转变为一个主动的“协作平台”。

2.2 技术栈选型：为什么是 Electron + ConPTY + xterm.js？

这是一个非常务实且高效的技术组合，每一项选择都针对 Windows 平台的特定挑战：

1. Electron：作为跨平台桌面应用框架，它允许使用 Web 技术（HTML/CSS/JS）快速构建复杂的 GUI。对于 wmux 这种需要高度定制化 UI（分屏布局、浏览器面板、通知中心）的应用来说，Electron 提供了极大的灵活性。同时，其成熟的 IPC 机制便于主进程（Node.js）和渲染进程（Web UI）之间的通信，这对于管理 PTY 进程和转发数据至关重要。

2. ConPTY (Windows Console Pseudo-Terminal)：这是 wmux 实现“原生”体验的关键。ConPTY 是 Windows 10 1809 及以上版本引入的官方伪终端 API。与传统的winpty等方案相比，ConPTY 提供了与系统控制台主机 (conhost.exe) 同等级别的兼容性和性能。这意味着 wmux 可以无缝运行cmd.exe、PowerShell、pwsh甚至原生 Linux 工具链（通过 WSL），而不会遇到字符编码、颜色渲染或信号处理等历史遗留问题。它直接与 Windows 控制台子系统对话，确保了最高的兼容性。

3. xterm.js：这是一个功能强大、性能优异的终端前端渲染库。选择它的原因在于其卓越的 Unicode 支持（特别是对 CJK 字符和 emoji 的宽度计算）、GPU 加速渲染（通过 WebGL）以及丰富的插件生态系统。对于需要显示 AI 代理复杂输出（可能包含彩色高亮、特殊符号）的场景，一个稳定、准确的渲染引擎是基础。xterm.js 的 999K 行回滚缓冲区实现，也为会话持久化提供了底层支持。

这个技术栈的组合，巧妙地平衡了开发效率、原生兼容性和用户体验。Electron 负责“面子”（交互界面），ConPTY 负责“里子”（系统级终端兼容性），xterm.js 负责“呈现”（精准高效的画面绘制），三者各司其职，构成了 wmux 稳固的基石。

2.3 核心架构：多进程协同模型

wmux 并非一个单一进程的应用，它采用了多进程协同的架构来确保稳定性、安全性和功能解耦。理解这个架构，有助于我们明白其强大功能背后的运行机制。

[用户界面层] ├── 主窗口 (Electron Renderer Process) │ ├── xterm.js 终端实例（每个窗格一个） │ ├── Webview 浏览器面板 │ ├── React 状态管理 (Zustand) │ └── UI 交互逻辑 │ [核心服务层] ├── Electron 主进程 (Main Process) │ ├── PTY 管理器：通过 node-pty 创建/管理 ConPTY 进程 │ ├── 会话管理器：负责保存/恢复窗格布局、工作目录、命令行历史 │ ├── MCP 注册器：自动在 ~/.claude.json 中注册服务 │ ├── 管道服务器：提供安全的 Named Pipe JSON-RPC 接口供 MCP 调用 │ └── 自动更新器：从 GitHub Releases 检查更新 │ [后台守护层] ├── 守护进程 (Daemon Process) - 独立进程 │ ├── 会话守护者：在 wmux 主程序关闭后，保持 PTY 进程存活 │ ├── 回滚缓冲区管理器：将终端输出异步写入磁盘 │ ├── 进程监视器：监控异常退出的子进程 │ └── 内存看门狗：在内存压力过大时自动清理闲置会话 │ [协议桥接层] ├── MCP 服务器进程 (Stdio) │ ├── Playwright 引擎：建立与内置浏览器的 CDP 连接 │ ├── 终端工具实现：响应 `terminal_read`, `terminal_send` 等调用 │ └── 代理间通信路由：处理 A2A (agent-to-agent) 消息

这个架构设计的精妙之处在于：

• 稳定性：即使 GUI 部分崩溃或重启，守护进程也能保证你的npm run dev或python script.py等长时间运行的任务不会中断。这是实现“会话持久化”的核心。
• 性能：将耗时的操作（如浏览器自动化、滚动缓冲磁盘 I/O）放到独立进程，避免阻塞 UI 渲染，保证终端输入的跟手性。
• 安全性：MCP 服务器和管道通信均采用了令牌认证，并且有严格的输入清洗和 SSRF 防护，防止恶意指令注入或内部网络探测。
• 扩展性：清晰的协议层（MCP、CDP、IPC）使得未来增加新的工具或集成新的 AI 代理变得相对容易。

注意：这种多进程模型会带来一定的内存开销（通常额外占用 100-200MB），这是 Electron 类应用和功能复杂性的权衡。但对于现代开发机来说，这通常是可接受的，换来的则是强大的功能和稳定的体验。

3. 从安装到上手：详细配置与核心功能实操

3.1 多种安装方式详解

wmux 提供了极其友好的安装体验，几乎覆盖了所有 Windows 用户的习惯。

1. 通过 Winget 安装（推荐给大多数用户）Winget 是微软官方的 Windows 包管理器，类似于 macOS 的 Homebrew 或 Linux 的 apt。这是最干净、最易于管理的方式。

# 打开 PowerShell 或终端，直接运行 winget install openwong2kim.wmux

优点：自动处理依赖，安装路径规范，方便后续通过winget upgrade一键更新。缺点：需要 Windows 10 1709 以上版本，且 Winget 本身已安装。

2. 通过 Chocolatey 安装Chocolatey 是社区维护的 Windows 包管理器，历史悠久，生态丰富。

choco install wmux

优点：对于已经使用 Chocolatey 管理软件生态的用户来说，可以统一管理。缺点：需要先安装 Chocolatey。

3. 下载安装包手动安装直接从 GitHub Releases 页面下载wmux Setup.exe文件，双击运行。这是最传统的方式。优点：无需任何前置条件，适合网络环境特殊或对包管理器不熟悉的用户。缺点：更新需要手动下载新版本。

4. 一键 PowerShell 脚本安装这是一个非常方便的“快速体验”方式，适合喜欢尝鲜的开发者。

irm https://raw.githubusercontent.com/openwong2kim/wmux/main/install.ps1 | iex

这条命令会下载并执行安装脚本。脚本会做什么？它会自动检测并安装缺失的依赖（如 Python、Visual Studio Build Tools），然后从最新的 Release 拉取并安装 wmux。

重要提示：在 PowerShell 中执行远程脚本前，请确保你理解脚本内容（你可以在浏览器中打开上述链接查看）。如果遇到执行策略错误，可以临时以管理员身份运行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process，但完成后建议改回默认的Restricted以保证安全。

安装后首次运行：首次启动 wmux，你可能会看到一个命令行窗口一闪而过，这是守护进程在启动。主界面加载后，你会看到一个干净的单窗格终端，默认 Shell 是你的系统默认 Shell（通常是 PowerShell）。

3.2 核心功能实操：像高手一样使用 wmux

3.2.1 终端分屏与工作区管理

这是终端复用器的基本功，但 wmux 做得更顺手。

• 基础分屏：

  • Ctrl+D：将当前窗格水平向右拆分。
  • Ctrl+Shift+D：将当前窗格垂直向下拆分。
  • 操作逻辑：你不需要先选择窗格再操作。焦点在哪个窗格，拆分命令就作用于哪个窗格。拆分后，新窗格会继承当前的工作目录。

• Tmux 风格前缀模式： 如果你熟悉tmux，一定会喜欢这个功能。按下Ctrl+B进入前缀模式，然后按一个单键执行操作：

  • %：垂直拆分（相当于Ctrl+Shift+D）。
  • "：水平拆分（相当于Ctrl+D）。
  • 方向键：在窗格间切换焦点。
  • z：最大化/恢复当前窗格（Zoom）。
  • x：关闭当前窗格。
  • c：在当前窗格创建新标签页。
  • n/p：切换到下一个/上一个标签页。
  • [：进入滚动/复制模式（类似tmux的 copy-mode）。
  • ?：显示快捷键帮助。这个模式的意义在于：将一系列相关的窗格管理操作绑定到一个前缀键下，减少全局快捷键冲突，也符合很多资深命令行用户的操作肌肉记忆。你可以在设置 -> 快捷键中完全自定义这些绑定。

• 工作区与多视图： 工作区是比窗格更上一级的组织单元。你可以把不同的项目放在不同的工作区。

  • Ctrl+N：创建一个新的工作区。
  • Ctrl+1~Ctrl+9：快速切换到对应编号的工作区。
  • 多视图：这是 wmux 的一个亮点功能。按住Ctrl键点击侧边栏的工作区，可以将其加入“多视图”网格。这样，你就能在同一个窗口内同时看到多个工作区的布局，非常适合监控多个后台服务或对比代码。按Ctrl+Shift+G退出多视图模式。

• 浮动窗格： 按Ctrl+`（反引号键，在 Tab 键上方）可以呼出一个 Quake 风格的下拉终端。这个窗格拥有独立的 PTY 会话，并且会一直悬浮在所有窗口之上。当你需要临时执行几条命令，又不想打断主窗口的工作流时，这个功能无比好用。再次按Ctrl+`可以隐藏它，但其中的进程（比如top或日志 tail）会继续在后台运行。

3.2.2 滚动与搜索：高效回顾终端历史

终端输出滚滚向前，如何快速定位之前的某条命令或错误信息？

• 滚动书签：这是 wmux 独有的一个贴心功能。在查看一长串输出时，按Ctrl+M可以在当前滚动位置打上一个书签。之后，你可以用Ctrl+Up和Ctrl+Down在书签之间快速跳转。书签标记会显示在滚动条旁边，一目了然。这对于调试时在多个关键日志点之间切换特别有帮助。

• 智能搜索：按Ctrl+F会打开搜索框。它支持正则表达式（点击搜索框旁边的.*图标切换），并且会高亮所有匹配项。搜索结果是实时更新的，随着你继续输入或终端有新输出，高亮都会动态变化。

• 智能右键菜单：

  • 选中文本时右键：直接复制，无需再按Ctrl+C。这是 Windows Terminal 带来的好习惯，wmux 也继承了。
  • 在空白处右键：直接粘贴剪贴板内容。
  • 在超链接上右键：会弹出一个小菜单，提供“打开”和“复制链接”选项，而不是直接跳转，避免了误操作打断当前工作。

3.2.3 浏览器自动化与 AI 集成

这是 wmux 区别于其他终端复用器的杀手级功能。它不仅仅是一个终端，还是一个可以被 AI 控制的浏览器自动化平台。

1. 打开浏览器面板：按Ctrl+Shift+L可以在当前窗格内打开一个内置浏览器面板。这个浏览器基于 Chromium，并开启了 Chrome DevTools Protocol 接口。

2. 与 Claude Code 集成：

   • 自动注册：当你启动 wmux 时，它的守护进程会自动在~/.claude.json（Claude Desktop 的配置文件）中注册一个 MCP 服务器。这意味着，只要你同时运行着 Claude Desktop，Claude Code 就能自动发现并使用 wmux 提供的工具。
   • AI 能做什么：在 Claude Code 的对话中，你可以直接使用诸如browser_open、browser_navigate、browser_screenshot、browser_click等工具。例如，你可以对 Claude 说：“帮我在 GitHub 上搜索 wmux 的最新 issue”，Claude 就会通过 MCP 调用browser_open打开浏览器，然后browser_fill在搜索框输入关键词，最后browser_click点击搜索按钮。这一切都是自动完成的，你看到的是浏览器在自动操作。
   • 多代理独立控制：每个 wmux 窗格（对应一个 AI 代理会话）都可以拥有自己独立的浏览器实例。工具调用时可以指定surfaceId参数，确保 A 代理的操作不会干扰 B 代理的浏览器。这对于构建多 AI 代理协作的复杂工作流至关重要。

3. 元素检查器：在浏览器面板中，将鼠标悬停在网页元素上，它会高亮显示。点击元素，wmux 会复制一个“LLM 友好”的上下文描述到剪贴板，例如{tag: 'input', id: 'search', placeholder: 'Search GitHub'}。你可以直接将这个描述粘贴给 Claude，让它精确地操作这个元素。

实操心得：刚开始使用浏览器自动化时，建议从简单的任务开始，比如“打开百度”或“截图当前页面”。观察 Claude 生成的工具调用序列，理解其逻辑。你会发现，AI 对于网页结构的理解能力远超预期，它能处理复杂的 React 组件和动态加载的内容。对于需要登录的网站，可以先手动登录一次，浏览器会保存 cookies，后续的 AI 操作就能在已登录状态下进行。

4. 高级配置、问题排查与性能调优

4.1 深度配置指南

wmux 的设置界面 (Ctrl+,) 提供了丰富的自定义选项，但有些高级配置需要直接修改配置文件。

• 主题与外观：内置了 Catppuccin Mocha、Monochrome、Sandstone 等主题。你可以在设置中切换。如果想深度自定义，需要修改渲染进程的 CSS。配置文件通常位于%APPDATA%\wmux\config.json。你可以修改uiTheme、fontFamily、fontSize、lineHeight等字段。注意：修改前请备份原文件。

• 快捷键重映射：如果你习惯了其他工具的快捷键（比如 VSCode 的Ctrl+\分屏），可以在设置 -> 快捷键中完全重定义。wmux 的快捷键系统是分层的：全局快捷键、前缀模式快捷键。你可以导出你的快捷键配置为 JSON 文件，方便备份或分享。

• Shell 集成：为了更精准地识别命令提示符和命令输出边界（用于terminal_read_eventsMCP 工具），wmux 会尝试向 PowerShell 和 Bash 注入 Shell 集成脚本。这通常是自动完成的。如果发现有问题（比如提示符识别不准），可以在设置中关闭“自动注入 Shell 集成”，然后手动在你的 Shell 配置文件（如$PROFILE或.bashrc）中添加 wmux 提供的脚本片段。

• 会话持久化与守护进程：

  • 位置：会话数据（包括终端回滚缓冲）默认保存在%LOCALAPPDATA%\wmux\sessions目录下。
  • 清理：如果遇到会话恢复异常，可以尝试在设置中点击“重置所有工作区”。这会清空内存和磁盘中的会话状态，但不会终止正在后台运行的进程（由守护进程管理）。
  • 禁用守护进程：虽然不推荐，但如果你遇到兼容性问题，可以通过在启动 wmux 时加上--no-daemon参数来禁用守护进程。但这会失去“应用重启后恢复会话”的能力。

4.2 常见问题与排查实录

即使设计再精良的工具，在实际复杂环境中也可能遇到问题。以下是我在长期使用中总结的一些常见情况及解决方法。

问题 1：启动 wmux 后，终端一片空白，或者输入无响应。

• 可能原因 A：ConPTY 与你的默认 Shell 不兼容。某些旧的 Shell 或配置异常的 Shell 可能无法在 ConPTY 下正常工作。
• 排查步骤：
  1. 检查 wmux 底部状态栏，看是否显示了 Shell 类型（如pwsh）。
  2. 尝试在设置中更改“默认 Shell”，比如从cmd.exe切换到powershell.exe。
  3. 手动在新窗格中启动其他 Shell，例如输入bash（如果安装了 WSL）或pwsh。
• 可能原因 B：防病毒软件或安全策略拦截了子进程创建。
• 排查步骤：暂时禁用防病毒软件实时防护，或将 wmux 主程序及其安装目录添加到白名单中。

问题 2：Claude Code 无法连接到 wmux 的 MCP 服务器。

• 可能原因 A：MCP 注册失败。~/.claude.json文件没有正确更新。
• 排查步骤：
  1. 确保 wmux 正在运行。
  2. 打开文件%USERPROFILE%\.claude.json（或~/.claude.json）。
  3. 检查mcpServers部分是否包含一个指向wmux的条目，并且command指向正确的wmux-mcp-server可执行文件路径。该路径通常类似C:\Users\<YourName>\AppData\Local\Programs\wmux\resources\wmux-mcp-server.exe。
  4. 如果条目缺失或路径错误，可以尝试重启 wmux，或者手动按照正确格式添加。
• 可能原因 B：命名管道权限或防火墙问题。
• 排查步骤：wmux 使用命名管道进行本地 IPC 通信，通常不受防火墙影响。但如果使用了特别严格的安全软件，可以尝试暂时关闭防火墙测试。

问题 3：浏览器自动化工具调用失败（如browser_click没反应）。

• 可能原因 A：页面尚未加载完成，AI 就尝试操作元素。
• 解决方案：在给 AI 的指令中，明确要求“等待页面加载完成后再点击XX按钮”。或者，让 AI 在操作前先调用browser_snapshot确认元素存在。
• 可能原因 B：元素定位符失效。对于动态生成的页面，AI 基于快照生成的定位符可能在下次页面更新后失效。
• 解决方案：教导 AI 使用更稳定的选择器，如id或>