终端网关客户端rbelem/dsh-tui

dsh-tui

一个用于 deepseek-harness
网关（dsh）的 Rust 终端客户端——一个与其 Web UI 对等的终端界面。它
通过线协议（RPC + 主机帧）连接到网关：
浏览工作区和会话、与智能体聊天、取消或重试
轮次、重命名/分叉/归档会话、创建会话，以及切换主题
或 UI 语言环境。

网关生命周期遵循 herdr 模型：如果启动时在
解析出的端口上没有监听，dsh-tui 会在后台自行启动 dsh web
（它在 TUI 退出后继续运行），并且仅通过
dsh-tui server stop 停止它。

版本 0.1.0。约 36 次提交，293 个测试。

安装

npm（入口包 + 平台预构建）

已发布的包：

| 包 | 内容 |
|---|---|
| @rbelem/dsh-tui | 入口包：cordis 补丁层 + 运行时胶水插件，使用 DSH_PORT 启动 TUI |
| @rbelem/dsh-tui-linux-x64 / -linux-arm64 | 用于 linux x64 / arm64 的预构建二进制文件 |
| @rbelem/dsh-tui-darwin-x64 / -darwin-arm64 | 用于 macOS x64 / arm64 的预构建二进制文件 |

该包将四个平台包固定为精确版本的
optionalDependencies；npm 根据其 os/cpu 字段选择匹配的那个。
通过 harness 插件机制安装：

dsh plugin --profile tui add @rbelem/dsh-tui

启动（网关 + TUI）或仅连接：

dsh --profile tui              # 启动网关（操作系统分配端口）并启动 TUI
dsh --profile tui --port 8080  # 固定端口
dsh --profile tui --no-spawn   # 仅网关；稍后用二进制文件 + DSH_PORT 连接
dsh-tui --port           # 连接到任何正在运行的网关

有关完整的包契约，请参见 bundle/README.md。

从源码构建

先决条件：Rust 工具链（rustup）和 devbox
（devbox.json 固定了 rustup@latest）。

git clone  dsh-tui
cd dsh-tui
devbox run -- cargo build --release
二进制文件位于 target/release/dsh-tui

网关：默认自动启动

dsh-tui 连接到 deepseek-harness 仓库中的 dsh web 网关。
默认情况下，当没有监听时它会自行启动网关：启动时探测
解析出的端口，若端口无响应则分离式启动 dsh web
（stdout+stderr → $XDG_STATE_HOME/dsh-tui/gateway.log）。网关
在 TUI 退出后仍然存在——使用 dsh-tui server
stop 显式停止它。网关启动时无需提供商密钥（浏览/连接/列出
均可正常工作）；提交提示需要在
环境中配置提供商——没有提供商时，运行会失败并在
UI 中显示轮次错误（不会崩溃）。

端口解析优先级为 CLI > 环境变量 > 配置 > 默认 3080（dsh web
配置文件的组合默认值）：

dsh-tui --port 4000              # CLI 优先
DSH_PORT=4000 dsh-tui            # 环境变量
config.toml: [gateway] port = 4000
dsh-tui                          # 默认 3080，无需设置

手动启动的网关工作方式相同——它会被
探测检测到并按原样连接：

终端 1：网关
dsh web --port 8765

终端 2：TUI
dsh-tui --port 8765

要禁用自动启动（保持纯手动流程），请在 ~/.config/dsh-tui/config.toml 中设置
[gateway] auto_start = false ——
此时端口无响应会报出“no gateway reachable”错误信息。

用法

在没有会话时，一个主屏幕会邀请你新建会话。一旦接入，布局如下：

- 侧边栏 —— 工作区分组、一个用于未被任何工作区认领会话的未分组组，以及底部一个折叠的 archived (N) 标题
（在 v1 中，已归档会话不参与导航）。
- 聊天面板 —— 当前会话的历史记录：用户消息、助手回复（markdown、推理、终端支持时的图片）、
工具活动、审批和队列项。
- 输入框 —— 底部的提示输入区；Enter 提交，Shift+Enter
插入换行，/ 和 @ 打开命令/技能补全弹窗。

TUI 会接入最近更新的非空会话，并通过 mux 下行流式接收新事件。

键位映射

| 按键 | 操作 |
|---|---|
| j/k、↑/↓ | 滚动聊天 / 移动侧边栏选择 / 移动选择器选择 |
| g/Home、G/End | 跳到聊天顶部 / 底部 |
| Ctrl+d / Ctrl+u | 滚动半页（聊天） |
| Ctrl+d | 从输入框退出（EOF） |
| Enter | 提交输入框；切换到选中的侧边栏会话；应用选择器选择 |
| Tab | 循环焦点：聊天 → 输入框 → 侧边栏 |
| Ctrl+w 然后 h/j/k/l | 在窗格之间移动焦点（侧边栏 / 聊天 / 输入框） |
| Esc | 返回聊天（关闭弹窗、选择器、编辑器） |
| n | 新建会话选择器（聊天或侧边栏焦点；j/k 移动，Enter 创建） |
| r | 重命名选中的侧边栏会话（内联编辑器：输入，Enter 提交，Esc 取消） |
| f | 分叉选中的侧边栏会话 |
| a | 归档选中的侧边栏会话 |
| v | 在聊天中启用鼠标选择模式（v select · esc cancel；拖动选择，松开复制） |
| i | 在会话的图片上打开图片查看器（聊天焦点） |
| t | 切换当前视图中工具行的工具详情行（开始/持续时间/schema）（聊天焦点） |
| s | 切换窄终端会话抽屉（低于 80 列） |
| q | 退出（聊天或侧边栏焦点） |
| Ctrl+p | 启动器：对命令、缓存技能和设置操作进行模糊搜索 |
| Ctrl+t | 主题选择器（j/k 移动，Enter 应用，Esc 关闭） |
| Ctrl+, | 设置视图（注意：无法从原始终端字节流到达 —— crossterm 将 0x0c 映射为 Ctrl+l；请使用启动器的“open settings”操作） |
| Ctrl+l | 循环切换 UI 语言（en ↔ zh），持久化 |
| Ctrl+c | 取消正在运行的回合；空闲时退出 |
| Ctrl+q | 退出 |
| Alt+q | 队列弹窗：j/k 滚动，x 移除，s 引导，e 编辑，Esc 关闭 |
| Shift+Enter | 在输入框中插入换行（见下方输入框说明） |

输入框编辑：方向键 / Home / End 移动光标，Backspace /
Delete 编辑，Esc 返回聊天。Shift+Enter 插入换行
（Web 对等；需要 CSI-u / kitty 键盘协议终端——
kitty、WezTerm、Alacritty ≥0.13、foot、Ghostty、Windows Terminal ≥1.19。
在旧式终端上，Shift+Enter 会以普通 Enter 到达并提交
——优雅降级，不会出问题）。

鼠标

鼠标捕获已开启（点击选择会话，滚轮每格滚动 3 行，
状态指示器）。在聊天中，v 启用选择模式：

- v，然后拖动：选择文本；松开后将其复制到剪贴板
（OSC 52）并退出该模式；Esc 取消。状态行在成功时
显示 copied · N chars 闪烁提示。
- 双击一个词：选中该词（CJK 连续文本保持完整）；之后拖动
会从该词扩展选择。
- 选择时滚动滚轮会滚动视口——选择会保持
锚定在下方文本上。
- 点击 ▸ N skills 标题行会展开或折叠该消息中
折叠的技能列表（点击标题绝不会开始选择）。

聊天的边距（2/2 内边距）锚定在钳制后的边缘，因此
拖动始终有起点。在低于 80 列时，s 打开会话
抽屉（完整标题；Esc/点击外部关闭）；聊天左上角的
≡ 控件可切换它。

终端逃生通道：当鼠标捕获处于活动状态时，按住 Shift
同时拖动或滚轮会绕过应用的捕获——终端
自己的选择和滚动会接管（标准 xterm/kitty 行为；
应用永远不会看到这些事件）。当你想要终端的
原生复制而不是 dsh-tui 的复制时，请使用它。

配置

- 设置视图——从启动器打开（Ctrl+P → “open settings”）。
由网关的 settings.describe/settings.update 驱动；实时
网关暴露的命名空间包括 ui-theme、locale、
ui-conversation 和 ui-onboarding，渲染为模式驱动的表单。
- 主题——15 个内置主题（catppuccin ×4、kanagawa、tokyonight ×3、
gruvbox、dracula、solarized、nord、rose-pine、everforest、one-dark）；
Ctrl+T 打开选择器，Enter 应用并持久化。用户主题从
~/.config/dsh-tui/themes/.toml 加载。没有显式主题时，
默认跟随检测到的终端/系统配色方案——在真彩色终端上为
catppuccin frappe（深色）/ catppuccin latte（浅色），当检测失败时
回退到跟随终端的中性外观（设置 COLORTERM 时为真彩色，
否则为 256 色）。
- 区域设置——zh/en，键控字符串表；Ctrl+L 循环切换并持久化；
CJK 宽度已处理。
- 配置文件——~/.config/dsh-tui/（在测试中通过 XDG_CONFIG_HOME
与宿主配置隔离）。[keymap] 部分按操作名称重新绑定快捷键
（默认值见上表）；键规格形如
"ctrl+q"、"shift+enter"、"alt+q"、"g"。缺失或无法解析的
规格会回退到内置默认值；配置在启动时应用。

开发

工具链：devbox（devbox.json——rustup@latest）。

sh
devbox run -- cargo test        # 293 个测试
devbox run -- cargo check --all-targets
devbox run -- cargo clippy --all-targets -- -D warnings
devbox run -- cargo fmt --check

实时网关冒烟测试

tests/live_smoke.rs 在 PTY 中运行真实二进制文件，针对测试自身启动的真实 dsh web
网关（隔离的 DSH_HOME，端口 18765 或空闲端口），并在拆卸时终止。由环境变量控制，
以便默认测试套件在没有外部基础设施的情况下保持通过：
sh
DSH_LIVE_SMOKE=1 devbox run -- cargo test --test live_smoke -- --nocapture --test-threads=1

冒烟测试是提供商自适应的：它探测 session.models.routable —— 有提供商时，
它断言提示词往返和流式回答；没有提供商时，它断言优雅的回合错误界面。
附加、侧边栏、导航、设置、主题和目录流程在两种情况下都会运行。

发布

发布流水线（scripts/release/、.github/workflows/release.yml）：

1. build.sh --target  将一个目标构建到
dist/dsh-tui-/（二进制文件 + SHA256SUMS，字节固定）—— darwin
目标在 macOS 运行器上构建。
2. prebuild-packages.sh 从 dist 产物组装四个 prebuilds//
包。
3. v 标签工作流将每个目标的资产以目标唯一名称上传到 GitHub release：
dsh-tui- 和
dsh-tui-.SHA256SUMS（在将二进制文件重命名为列出的名称 dsh-tui 后，
用 sha256sum -c 验证）。

npm 发布是手动的（workflow_dispatch、.github/workflows/publish.yml），
复用相同的产物 —— 无需重新构建：
sh
bash scripts/release/publish.sh            # 试运行：为全部 5 个执行 pack + publish --dry-run
bash scripts/release/publish.sh --publish  # 真实发布（需要 npm 认证）

平台包先发布，入口包最后发布；脚本会检查
npm whoami 并拒绝在未认证的情况下发布，且会快速失败并报告哪些包已发布。

对等性

参见 PARITY.md 了解与 Web UI 的逐功能对等契约
（验收标准 + 测试钩子），以及
.scratch/dsh-tui/issues/ 中的决策记录。