dsh-tmux-cc

dsh plugin --profile web add dsh-tmux-cc

dsh-tmux-cc

简体中文 · [English](./README.md)

一个用于 DeepSeek Harness Web 的持久化 tmux 控制模式工作台。它通过 tmux -C 连接已有的 tmux 会话，用 xterm.js 渲染每个窗格，并且在切换聊天时始终保持可见。




进程和布局仍由 tmux 管理，本插件只是一个新的显示与控制端。它不是“在浏览器终端里运行 tmux”，不需要 PTY，也没有原生 Node.js 扩展依赖。

界面预览

<p align="center">

<img src="./assets/dsh-tmux-cc-desktop.png" alt="dsh-tmux-cc 桌面工作台并排显示 btop、Claude Code、Codex、CI 日志、omp 和 README 卡片" width="49%" />

<img src="./assets/dsh-tmux-cc-desktop-right.png" alt="dsh-tmux-cc 右侧边栏模式纵向叠放 Claude Code、Codex 和 omp" width="49%" />

<br />_{桌面：底部工作台容纳六个实时窗格（btop、Claude Code、Codex、滚动 CI 日志、omp、项目 README），以镜像模式呈现、不抢占窗口尺寸（左）；右侧边栏模式纵向叠放三个编程 CLI（右）。}

</p>

<p align="center">

<img src="./assets/dsh-tmux-cc-mobile.png" alt="dsh-tmux-cc 移动工作台保留完整四窗格 tmux 网格" width="300" />

&nbsp;&nbsp;

<img src="./assets/dsh-tmux-cc-mobile-zoom.png" alt="dsh-tmux-cc 移动工作台使用原生 tmux 窗格缩放" width="300" />

<br />_{移动端：全屏抽屉保留真实的四窗格 tmux 网格（左）；对 Metrics 窗格使用原生 <code>resize-pane -Z</code> 缩放（右）。}

</p>

[!NOTE]

所有截图均来自完全隔离的 DSH profile 和独立 tmux server。截图中的 agent CLI 均停留在欢迎界面，从未发送任何提示词；画面不包含私人对话、工作区或终端输出。

功能特性

• 跨聊天持久显示 —— 工作台属于 DSH Web 外壳，而不是某个对话。
• 原生 tmux 窗格 —— 窗格布局、窗口标签、焦点、缩放、分屏和大小调整都会与 tmux 同步。
• 不干扰其他终端 —— 有其他终端连接时使用 ignore-size 镜像模式；只有工作台参与尺寸计算时，自动切换为清晰的 1:1 接管模式。
• 可靠的输入传输 —— 通过十六进制 send-keys -H 原样转发输入，包括回车、粘贴和 Unicode。
• 多会话与多窗口 —— 支持连接、断开、切换窗口，以及按需启动可选的命名会话方案。
• 忠于 tmux 的移动工作台 —— 视口小于 768px 时使用全屏抽屉，同时保留真实 tmux 窗格网格和原生窗格缩放。
• 中英文界面 —— 自动跟随 DSH 的语言设置显示英文或简体中文。
• 无原生依赖 —— 控制通道仅使用标准输入/输出管道。

环境要求

• 带 Web profile 的 DeepSeek Harness
• Node.js 22 或更高版本
• pnpm（推荐通过 Corepack 使用）
• tmux 与 DSH 安装在同一台主机上（已在 tmux 3.7b 验证）
• Linux 或 macOS

安装

从 npm 安装（推荐，预构建）：

dsh plugin --profile web add dsh-tmux-cc

从 GitHub 安装：

dsh plugin --profile web add github:adrianleb/dsh-tmux-cc

或从本地克隆安装：

git clone https://github.com/adrianleb/dsh-tmux-cc.git
cd dsh-tmux-cc

corepack enable
pnpm install
pnpm run check

dsh plugin --profile web add "$PWD"

重启当前的 dsh web 进程，然后强制刷新 Web 页面。右下角会出现 tmux 悬浮按钮；设置 → tmux 中会显示工作台的实时状态，并提供另一个打开入口。

更新方法：

cd dsh-tmux-cc
git pull --ff-only
pnpm install
pnpm run check
# 重启 dsh web，然后刷新浏览器。

使用方法

1. 打开 tmux 工作台。

2. 在下拉列表中选择一个正在运行的 tmux 会话；插头按钮用于断开或重新连接。

3. 点击窗格获取焦点，然后正常输入。

4. 窗格获得焦点后，可使用 Ctrl+B，再按方向键、x、z、" 或 % 执行常用 tmux 操作。

5. 拖动工作台边缘或窗格分隔条调整大小；使用标签切换 tmux 窗口。

为了避免意外终止整个会话，本插件拒绝关闭会话中的最后一个窗格。

移动端

视口宽度小于 768px 时，工作台采用 dsh-better-sidebar 已验证的窄屏布局思路：

• 工作台变为全屏浮动抽屉，不再挤压 DSH 对话区域。
• 所有 tmux 窗格仍显示在真实 tmux 网格位置；不再额外引入客户端窗格标签或单窗格模式。
• 点击窗格选中后，使用工具栏缩放按钮或 Ctrl+B z；插件会发送 tmux 原生 resize-pane -Z，再次操作即可恢复网格。双击窗格标题也执行同一个原生切换。
• 点击窗格不会唤起软键盘；工具栏的键盘按钮负责显式唤起和收起，滚动阅读不再被打断。
• 单指拖动即可按自然方向滚动窗格回滚缓冲区，并带惯性；窗格程序启用鼠标上报时，手势交还给程序处理。
• 窄视口是纯镜像：会撤回该浏览器此前上报的网格，并且永远不会改变共享 tmux 窗口尺寸。软键盘弹出或地址栏收起不会引发刷新循环，也不会重排其他客户端；字体自动缩放适配。
• 禁用工作台和窗格拖动条，隐藏桌面端方向选择器，主要按钮采用 44px 触控区域。
• 刘海屏通过 safe-area 内边距适配；visualViewport 的 resize/scroll 监听会在软键盘弹出时将终端保持在键盘上方。
• 视口达到 768px 后，会自动恢复完整的桌面布局和尺寸调整功能。

尺寸策略

插件每五秒自动检查一次，并在以下两种模式间切换：

• 镜像（Mirror） —— 存在普通 tmux attach 或 iTerm2 -CC 等其他尺寸客户端。工作台保持 ignore-size，不会改变其他客户端的终端尺寸；每个窗格按真实字符网格渲染，再缩放字体以适应工作台。
• 接管（Takeover） —— 当前只有 ignore-size 客户端。工作台通过 refresh-client -C 上报可用网格，并按原生字体大小渲染。只有桌面宽度的客户端会上报网格；移动端始终镜像。

打开其他 tmux 客户端后，工作台会退回镜像模式；关闭后，如果主机共享策略为 自动，则恢复接管模式。如果不希望本插件在任何情况下调整 tmux 窗口，可在 设置 → tmux → 行为与安全 中选择 仅镜像。无论选择哪种策略，移动端都只会镜像。

设置

设置 → tmux 会区分本浏览器的显示偏好和主机共享行为：

• 停靠栏： 底部/右侧位置、打开/收起以及恢复默认设置。
• 终端： 字体、首选字号、光标样式与闪烁、回滚行数，以及是否同步应用到 DSH 代码字体。镜像模式可能缩小字号，以完整保留真实网格。
• 行为与安全： 主机持久化的 自动 / 仅镜像 尺寸策略，以及本浏览器的窗格关闭确认。

浏览器本地设置采用版本化 local storage，且不会广播给其他查看端。重置时会保留工作台当前的打开状态和该浏览器选择的 session。尺寸策略通过 DSH settings 服务注册；使用可写的本机 settings provider 时，会保存到常规设置文档中。

回滚默认保留 2,000 行，上限为 20,000 行且每个窗格最多 800 KB。该数值同时控制 xterm 保留量和重新连接/切换窗口后请求的 tmux 历史；历史回复只发送给发起请求的浏览器。捕获任务会串行执行，同一浏览器重复提交的待处理请求会合并为最新一次。

窗格关闭确认默认开启。需在三秒内重复同一个关闭按钮、工具栏操作或 Ctrl+B x 才会真正关闭。主机仍会拒绝关闭会话中的最后一个窗格。

字体

tmux-cc 用浏览器里的 xterm.js 绘制，因此只能使用 正在浏览 GUI 的那台电脑 上已安装的字体（或通过 @font-face 下发的字体）。DSH 主机上的字体不会自动出现在远程浏览器中。

字体设置为空时，工作台会按下面的栈回退，浏览器会选用它能解析的第一个家族：

Berkeley Mono Nerd Font Mono、Berkeley Mono、JetBrainsMono Nerd Font Mono、FiraCode Nerd Font Mono、Hack Nerd Font Mono，然后是 ui-monospace。

若已安装 Berkeley Mono，浏览器里的家族名通常是 Berkeley Mono 和 Berkeley Mono Nerd Font Mono（窗格里如果有 nerd/powerline 符号，Nerd 版本更合适）。

可在 设置 → tmux → 终端字体 填写自定义栈，例如：

"Berkeley Mono", "Berkeley Mono Nerd Font Mono", ui-monospace, monospace

留空则继续用默认栈。在 Chromium 中，聚焦输入框时还可以通过 Local Font Access API 列出本机字体。

可选勾选 同时用于 DSH 代码字体，以设置 --ds-font-family-code（以及 --dsw-font-mono），让 Markdown、工具输出、以及跟随主题等宽字体的侧栏终端使用同一字体。这不会改掉整个 DSH 界面；若也要改 UI 无衬线字体，可通过 dsh-better-sidebar 的 自定义 方案注入：

:root {
  --dsw-font-family: "Berkeley Mono", ui-sans-serif, system-ui, sans-serif;
}

dsh-better-sidebar 侧栏终端设置里还有单独的 终端字体 项，只作用于侧栏 PTY 标签，不会影响本 tmux 工作台。

配置

在 DSH Web profile 的插件配置中添加选项：

- id: tmux-cc
  name: dsh-tmux-cc
  config:
    # 可选的部署默认值；设置 → tmux 可保存用户覆盖。
    sizePolicy: auto # auto | mirror

    # 可选。默认依次使用 $DSH_TMUX_BIN 和 PATH 中的 `tmux`。
    tmuxBin: /usr/local/bin/tmux

    # 可选的命名会话方案。
    layouts:
      - id: project
        label: 项目工作台
        session: project
        launch: /home/me/.local/bin/start-project-tmux
        launchArgs: ["--ensure-only"]

sizePolicy 提供部署层默认值；通过设置页面保存的值会覆盖它。auto 只在没有外部尺寸客户端时允许接管，mirror 则始终让本插件退出 tmux 窗口尺寸计算。

如果方案对应的会话不存在，选择该方案时会先执行 launch 和 launchArgs，然后连接。如果省略 launchArgs，默认值为 ["--ensure-only"]。启动器配置属于受信任的管理员输入，并会以运行 DSH 的操作系统用户权限执行。主机上

…(truncated)