终端 TUI 客户端 edabchann/dsh-neotui

dsh-neotui

dsh-neotui 是 DeepSeek Harness 的 keyboard-first 终端客户端：以 Vim/Nvim 风格的 NORMAL / INSERT / VISUAL 只读导航、tmux 风格 pane 焦点和 Yazi 风格文件选择器为主，鼠标作为辅助，访问与 WebUI 相同的 Host 会话、工具、审批、任务和设置能力。

本仓库发布两个 npm 包：

| 包 | 用途 |
| dsh-neotui | TUI 客户端、核心界面和 dsh-neotui 命令 |
| dsh-neotui-app | 将 TUI、API gateway 和 Host 服务装配成 DSH profile 的 bundle |

0.2.0 亮点

- 三栏 Yazi 风格文件与工作区选择器：路径编辑、模糊筛选、隐藏项、Nerd Font 图标和 Kitty 图片预览；列表、预览与 @ 补全全部通过 workspaceFiles/ / fileReferences/list 走 Host，远端 attach 时看到的就是 Host 的文件系统；
- 「文件/改动」主窗口标签：订阅 Host workspaceFiles/changes，按路径列出 M/A/D，Enter 读取内容（长文件分页、带 patch 时按 diff 配色），r 重新订阅；
- 图片附件栏、附件管理器、dd 删除和等比例 Kitty 预览；非图片文件经 fileUploads/upload 成为真正的 Host 附件（以 receiptId 随消息发送）；
- 全屏跨会话全文搜索：工作区→会话→匹配块树、附近内容预览和精确跳转；
- NORMAL / INSERT / VISUAL 只读模式、正文块选择与可编辑的快捷键目录；
- 独立的命令、设置和插件目录，插件支持即时筛选；
- Queue / Steering、Goal、TODO、Plan Review、后台任务和 Subagent 状态；
- grapheme-aware framebuffer、CJK/组合字符、Kitty keyboard、SGR mouse、OSC 8/52。

完整变化见 CHANGELOG.md。

安装与启动

需要 Node.js 22 或更高版本（客户端使用 Node 内置 fetch、WebSocket、crypto.randomUUID 和 Intl.Segmenter）。

独立 DSH profile

dsh plugin --profile dsh-neotui add dsh-neotui-app
dsh --profile dsh-neotui

常用参数：

dsh --profile dsh-neotui --session
dsh --profile dsh-neotui --cwd ~/work
dsh --profile dsh-neotui --host 127.0.0.1 --port 3981

出于安全原因，--host 0.0.0.0 会被拒绝。能够执行工具的 Host 不应直接暴露到不受信任的网络。

连接已有 Web Host

dsh --profile dsh-neotui --attach 3080

dsh 0.1.5 起 Host 的 /api 需要访问令牌（令牌随 dsh web 启动时打印的 URL 一起给出）。attach 到这类 Host 时补上 --token（或设 DSH_TUI_TOKEN，或把令牌写进 --base 的 ?token=）：

dsh --profile dsh-neotui --attach 3080 --token

自托管模式（不带 --attach）由进程内的 connection 行自动注入令牌，无需手动指定。客户端在连接后会探测 Host 版本：旧版（≤0.1.2）走点号方法名 + 平铺 payload，0.1.5 走 namespace/method + args。

也可以直接运行客户端：

node bin/dsh-tui.js
node bin/dsh-tui.js --base http://127.0.0.1:3080
node bin/dsh-tui.js --base http://127.0.0.1:3080 --token

默认连接 http://127.0.0.1:3080；可通过 --base、DSH_URL 或 DSH_WEB_URL 覆盖。--attach 不会启动或替换 WebUI。

从源码运行

.
├── app/ dsh-neotui-app bundle
├── bin/dsh-tui.js 客户端入口 ├── src/ TUI 核心 └── test/ 单元、终端协议与 PTY 测试

使用本地 profile：

mkdir -p ~/.dsh/profiles/node_modules
ln -sfn "$(pwd)" ~/.dsh/profiles/node_modules/dsh-neotui
ln -sfn "$(pwd)/app" ~/.dsh/profiles/node_modules/dsh-neotui-app
dsh --profile dsh-neotui

只调试客户端时，保证目标 Host 已运行即可：

node bin/dsh-tui.js --base http://127.0.0.1:3080

交互模型

NORMAL / INSERT

- NORMAL：单字符用于导航和操作；
- INSERT：键盘输入交给消息编辑器；
- i 或点击输入框进入 INSERT；
- Esc 离开 INSERT；
- INSERT 中 Esc 不会中断当前回合；
- NORMAL 中 Esc 会中断正在运行的回合，否则返回上一级；
- NORMAL 中连续两次 Ctrl+C 退出，INSERT 中 Ctrl+C 清空输入。

底栏始终显示当前模式。按 Ctrl+Space 打开快捷键、命令、设置和插件目录。

输入与附件

| 模式 | 按键 | 功能 |
| INSERT | Enter | 发送 |
| INSERT | Shift+Enter / Ctrl+J | 换行 |
| INSERT | Ctrl+L | 展开/折叠输入栏 |
| INSERT | ↑ / ↓ | 在首尾行浏览输入历史 |
| INSERT | Ctrl+Shift+C | 复制输入框选区 |
| INSERT | Ctrl+Z / Ctrl+Y | 撤销 / 重做（发送后清空历史） |
| INSERT | Ctrl+O | 打开文件选择器 |
| INSERT | Ctrl+Shift+V | 粘贴剪贴板图片 |
| INSERT | Esc | 退出输入（可重映射；Esc 始终保留兜底） |
| NORMAL | Ctrl+O | 打开附件管理器 |

输入框草稿按会话镜像：切换到另一会话时保存当前未发送文本，切回时原样恢复（发送后清空）。

文件选择器支持：

| 按键 | 功能 |
| ↑ / ↓ | 移动光标 |
| ← / → | 返回上级 / 进入目录 |
| Space | 选择或取消文件 |
| Enter | 确认上传 |
| / | 筛选当前目录 |
| Ctrl+/ | 清除筛选并退出筛选模式 |
| Ctrl+F | 编辑路径，支持 ~、$HOME 和环境变量 |
| Ctrl+. | 显示/隐藏隐藏项 |
| Esc | 关闭 |

附件管理器支持 Enter 预览、Shift+Enter 或双击用默认程序打开、dd 删除。图片以 {type:"image"} 内联内容块随消息发送；非图片文件在 dsh 0.1.5 Host 上会成为真正的 Host 附件：TUI 通过 fileUploads/upload（{agentId, request:{data, name}}）把文件字节上传到 Host，拿到 receiptId 后以 {type:"file", receiptId} 随 session/prompt 发送，Host 在收件时校验该回执。只有 Host 缺少该接口（0.1.5 以前的旧 Host）时，条目才退化为「仅元数据」（名称 / 大小 / 类型），绝不伪装成可发送附件。

Kitty graphics 可用时，图片在文件选择器和附件预览中等比例显示；否则回退到 MIME、尺寸和文件大小信息。

Queue / Steering

模型运行时，Enter 的策略由 busyEnter 决定：

- queue：加入下一回合队列；
- steer：追加到当前回合。

Ctrl+Y 切换策略，Ctrl+N 打开排队命令详情。队列面板每条命令一行，使用 ↑/↓ 循环选择、Enter 展开详情、Ctrl+↑/↓ 独立滚动详情、dd 删除、Esc 关闭。

快捷键

以下是默认绑定。控制面板中的快捷键页以 MODE / KEY1 / KEY2 / FUNCTION 四列显示，每个功能拥有主/备两个槽位，并允许编辑用户覆盖；配置写入 $DSH_HOME/tui-config.json。这些绑定是运行时的唯一来源：修改后立即生效（无需重启），全部定义集中在 src/keybindings.js。

| 模式 | 按键 | 功能 |
| ALL | Ctrl+Space / F7 | 控制面板 |
| NORMAL | Ctrl+F / / | 打开全屏跨会话全文搜索；Enter 执行，/ 重新编辑 |
| NORMAL | Ctrl+B | 显示/隐藏侧栏 |
| NORMAL | Ctrl+M | 模型与思考强度 |
| NORMAL | F8 | 权限模式轮换 |
| NORMAL | F9 | Agent 模式 |
| NORMAL | Ctrl+W | 工作区 |
| NORMAL | Ctrl+Shift+W | 添加工作区 |
| NORMAL | Ctrl+T | 轨迹视图 |
| NORMAL | Ctrl+← | pane 焦点移到上一窗格（工作区栏 / 对话 / 轨迹循环） |
| NORMAL | Ctrl+→ | pane 焦点移到下一窗格（两个方向独立可重映射） |
| NORMAL | Ctrl+E | 按 step 快速跳转 |
| NORMAL | Ctrl+J | 后台任务与 Subagent |
| NORMAL | Ctrl+N | 排队命令详情 |
| NORMAL | Ctrl+Y | 运行中 Enter 策略（追加 / 排队） |
| NORMAL | Ctrl+O | 附件管理 |
| NORMAL | Ctrl+G | Goal / TODO |
| NORMAL | Ctrl+S | Settings |
| NORMAL | Ctrl+A | Subagent |
| NORMAL | Ctrl+H | Skills |
| NORMAL | Ctrl+K | 用默认编辑器（$EDITOR / $VISUAL / vi）打开 tui-config.json；编辑完成后快捷键立即重载 |
| NORMAL | Ctrl+Shift+C | 复制正文选区/当前块（与 y 等价） |
| NORMAL | Ctrl+D | 配色主题选择器（/theme 同义） |
| NORMAL | Ctrl+C | 双击退出（第一次按仅提示） |
| ALL | Ctrl+Q | 退出 |
| 正文块 | ↑ / ↓、j / k | 上下选择正文块，两端停留不环绕；Ctrl+↑/↓ 只滚动视口 |
| 正文块 | Space / Enter / Ctrl+R | 折叠块 / 进入只读光标 / 打开上下文菜单（消息级菜单含「从此消息之后分叉」） |
| NORMAL 光标 | h l w b e 0 $、v / V | Vim 式只读移动与字符/整行 VISUAL（无 x / d） |
| NORMAL / VISUAL | y / Ctrl+Shift+C | 复制当前代码块/正文块或选区 |
| 正文块 | t / b | 全局展开/折叠思考块 / 工具块 |
| 正文块 | g g / G | 首个 / 最新正文块；G 选中最新块并让块头落在视口底部 |
| NORMAL | [ / ] | 上一个 / 下一个提问终点 |
| NORMAL | PgUp / PgDn | 翻页；到顶时加载更早历史 |
When the sidebar is focused, ↑/↓ cycles through workspaces or sessions, Space expands/collapses a workspace, Enter opens a session while keeping sidebar focus, n creates a new session, i enters input, and Ctrl+R opens the current item menu. When the trace is focused, ↑/↓ cycles through steps, Space expands the full event, Enter jumps back to the conversation, and Ctrl+R opens the step menu.

The search buffer top bar keeps only Shift+/ Help; pressing Shift+/ (terminals usually send ?) opens the full shortcut and search scope description, and pressing it again or pressing Esc returns. During the input stage, ↑/↓ recalls the most recent 20 persisted queries; Enter executes the query or jumps to a result, / returns to query editing, s cycles between relevance / most recently updated / hit count sorting, Space collapses workspaces/sessions, t / b collapses thought/tool matches, PgUp / PgDn / Home / End page through the result list, and Ctrl+↑/↓ and Ctrl+PgUp/PgDn scroll the right-side preview. Mouse: clicking a result row selects it, double-clicking jumps (double-clicking a workspace/session toggles collapse), the scroll wheel scrolls the list/preview/help page by position, and clicking the query row returns to the input stage; after a terminal resize, the preview re-anchors to the hit block. During parsing, per-session progress is displayed (Host candidates show the parsed count, local scans show the scanned and hit counts; Esc can cancel at any time), result rows and the preview both scroll with the selected item and highlight query terms, hit-term highlighting is computed once and colored across line-wrap boundaries (huge tool results will not slow down rendering); session rows show the hit count, with the latest match within a session first; for sessions that have Host hits but are not in the sidebar list, the latest event time from their history tail page is used in the "most recently updated" sort. Switching the sort preserves the currently selected session/match row. After jumping, only query terms within the hit block are highlighted, and Esc clears the highlight. If the Host has not mounted the search index (session.search unavailable), it automatically degrades to a bounded local scan of the recent history of the most recent 20 sessions, and shows a notice at the top of the buffer.

In the shortcut catalog: Enter edits the current JSON config item ({"mode":"normal|insert|all","key":"…","key2":"…"}, key2 may be empty), Shift+Tab cycles between NORMAL / INSERT / ALL, and Alt+Enter restores the default. Before saving, the JSON, mode, and both key slots are validated; error text is preserved so you can continue editing. Two-press key combinations (such as g g) are written separated by a space.

Slash Commands

After entering /, use Tab, ↑, ↓ to complete. The candidate bar first lists the Host command catalog (commands/list, showing the input.hint parameter hint), then appends TUI local commands. TUI local commands include:

| Command | Function |
| /reload | Redraw and reload the interface state |
| /restart | Restart the TUI and restore the session handoff |
| /model | Model selection |
| /theme | Switch theme |
| /permission | Permission selection |
| /goal | Goal panel |

Host-provided commands such as /compact, /export, /feedback, and /plan appear dynamically on the command page; the actual list is based on the current Host's commands/list.

Main Window Tabs and "Files/Changes"

The main window tabs are Conversation | Trace | Subagents | Background Tasks | Files/Changes, cycled with Shift+Tab (structural key), Ctrl+H / Ctrl+L, or by clicking the tab row directly.

"Files/Changes" subscribes to the Host's workspaceFiles/changes stream (after {kind:"ready"}, each observed write produces a frame {kind:"change", change:{absolutePath, version|absent:true}}), accumulating into one row per path: M/A/D status, path relative to the workspace, size (also displayed when the payload carries ±lines or a patch). ↑/↓ selects, Enter uses workspaceFiles/read to read the file content from the Host in pages (PgDn loads the next page; when the payload carries a patch, it is rendered with the existing diff color scheme), h/Backspace returns to the list, r resubscribes and re-stats each row, q/Esc returns to the conversation; if the Host has not observed any changes, an empty state is shown.

All file reads go through the Host: the file picker's directory listing and preview (workspaceFiles/list, workspaceFiles/read, image bytes readAll), @ mentions and path completion (fileReferences/list, Host index), the workspace tree, overflow output previews, and attachment bytes. Therefore, when the TUI is attached to a remote Host, what you see is the Host's filesystem, not a same-named file on the local disk; only local files such as $EDITOR drafts and tui-config.json are still read directly from the local machine. List/preview results have a TTL asynchronous cache and request deduplication, so rendering and keypresses do not re-hit the Host every frame.

Panels and Tool Cards

The TUI supports:

- Workspace and grouped session tree: create, open, rename, move, archive, delete, and export;
- terminal, read, search, web, diff, and generic presentation; minimized JSON (such as workflow results) is automatically laid out with 2-space indentation into a multi-line readable structure (body code blocks and thought content are left untouched);
- Tool approval, AskUser single/multiple choice, Plan Review;
- Goal, TODO, background tasks, and Subagent;
- Standalone plugin list with / filtering;
- Blank session welcome page: the mascot logo is hidden by default (Ctrl+R opens the logo panel: preset (40×19 quadrant blocks 80×38 true color) / custom JSON / off); the brand line is drawn with █▀▄ half-block pixel characters (two large wordmarks, DEEPSEEK / DSH NEOTUI), and a diagonal highlight sweeps across the wordmark about every 3.5 seconds (pure TUI rendering, following the theme's semantic colors); logo has three states (Ctrl+R opens the buffer): preset (built-in) / custom (Yazi-style file picker single-select JSON, format {palette, grid} 40×19) / off (title only), with the choice persisted to the config file; version update notices are collapsed to the bottom (DeepSeek Harness can update v… / dsh-neotui can update v…, clickable to check, not shown when up to date); mode selection is a bottom hint (F9 opens mode selection (custom supported)); in short viewports (」），Enter 或双击应用并停留继续调整，Esc 恢复已提交主题并关闭；选择持久化到 $DSH_HOME/tui-theme.txt。
- 启动动画（经典游戏启动器风格，默认关闭的 meme）：纯黑 → 白色从屏幕中心圆扩散到全屏（约 1s）→ 四行健康游戏忠告（"抵制不良游戏，拒绝盗版游戏。"等，逐句淡入，约 2s）→ 忠告淡出同时 DEEPSEEK 半块大字交叉淡入（约 2s）→ 底部闪烁「按任意键进入游戏」，按任意键进入。全程纯 ANSI（█▀▄）；dsh-tui --launcher-anime（或 DSH_TUI_LAUNCHER_ANIME=1）显式启用，DSH_TUI_NO_SPLASH=1 强制关闭，--script 模式不播放。

工作区（Ctrl+W）、设置（Ctrl+S）、模型供应商（模型选择器里的 ⚙ 管理供应商…）、子代理（Ctrl+A）和技能（Ctrl+H）都是全屏模态 Buffer：打开后覆盖整个界面，Esc 逐级返回并最终关闭。它们不再占用“标签页模式”，因此关闭后 Ctrl+←/→ 的 pane 聚焦立即恢复，两者互不冲突。轨迹仍是 pane 序列的一部分，由 Ctrl+T 或 Ctrl+←/→ 进入。

模型选择器（Ctrl+M / /model）是供应商文件夹 → 具体模型的层级结构：Space 展开/折叠文件夹，↑/↓ 移动，Enter 确认具体模型（带思考强度时再选一档），当前模型以 ● 标记并默认展开、默认选中。筛选与其他 buffer 一致：/ 进入筛选、Ctrl+/ 退出筛选，普通字符在浏览模式下不会误触发筛选。

所有 Buffer 都是模态的：点击外部只会吞掉事件，不会关闭 Buffer。退出必须使用界面明确提示的按键或操作。

鼠标与终端能力

- 点击工作区、会话、标签、工具块和输入框；
- 拖动侧栏分隔线；
- 滚轮浏览对话、列表和弹窗；
- 输入框拖选并通过 OSC 52 复制；
- 右键消息、轨迹 step 和工作区树打开菜单；
- SGR mouse、bracketed paste、Kitty keyboard、OSC 8、OSC 52；
- ANSI truecolor 差量 framebuffer；
- CJK、组合字符和 ZWJ emoji 的 grapheme-aware 渲染。

不同终端、tmux 和 SSH 环境对 Kitty graphics、keyboard、OSC 52 的支持不同。WezTerm 和 Kitty 是图片预览的推荐终端。

实时更新（0.1.5 Host）

dsh 0.1.5 不再转发 session/event，也不落库 assistant/chunk：一次回合里持久化日志只在
模型流结束后写入 assistant/message，因此单靠轮询只能在回合结束后看到整段回答。对话主通道因此改为 Remote 流 session/follow（mode:"stream"，request:{address, maxMessages, assistantStream:true}）：

- 打开/切换会话时对当前会话开流；切换、恢复、/reload 与退出都会换流/关流；socket 断开按退避重连并在新连接上重开（Host 会重发快照）。
- 首帧 snapshot 给出开场窗口与游标 cursor（开场窗口最后一个已提交 seq），TUI 据此发出 session/subscribed；随后是 cursor+1 起严格递增的 {type:"event", event} 记录。
- assistant-stream 增量帧是 0.1.5 唯一的分词级实时文本来源；中途接入会话时用快照里的累积流回放已生成文本。
- 同一事件可能同时被流和轮询看到：两条路径共用一个 seq 游标（ChatView.acceptRecords），只有严格递增的记录会被应用，重复/乱序一律丢弃。

轮询仍在：session/follow 健康时它退化为约 15 秒一次的安全网（只做对账）；流不可用（旧协议 Host、mux 不可达、流出错）时恢复原有节奏，并一次性 toast 提示。

工作区/归档没有推送：Host 不广播工作区事件，侧栏只能定时刷新——会话列表 窗口聚焦时约 2 秒（进入该窗口时立即刷一次），其余情况约 5 秒；本机的重命名/归档/新建等操作仍会立即刷新。

配置

TUI 设置：

$DSH_HOME/tui-config.json

包含显示名、默认折叠状态、运行中 Enter 策略和快捷键覆盖。主题保存在：

$DSH_HOME/tui-theme.txt

DSH_TUI_USER_PREFIX 可覆盖默认用户名。

测试

npm test # 单元与协议测试
npm run test:pty # 真实 PTY 生命周期
npm run test:rc # 完整发布候选验证

PTY 测试会验证 alternate screen、SGR mouse、界面渲染、退出恢复和常见运行时错误；有私有 Host 可用时还会播种会话并断言 session/list/session/page 数据到达界面、审批推送（$events waterfall + $events/result）以及实时增量渲染（session/follow：回合仍在流式输出时增量文本已出现在渲染帧里，轮询在该时刻不可能提供这段文本）。需要可用的 DSH Host；Host 不可用时测试会明确输出 SKIP。

脚本化 smoke：

node bin/dsh-tui.js --script test/smoke.script --plain

当前限制

- TUI 与 Host 必须使用兼容的事件、RPC 和内容块契约；
- 工作区/归档没有推送：Host 不广播工作区变更（$events 白名单只有 api-session/ 与 commands/change），其它客户端或守护进程改动分组/归档时，TUI 只能靠定时刷新感知（会话列表 聚焦 ~2s、其余 ~5s），本机操作则立即刷新；
- session/follow 的基线回放是进程内状态：回合进行中接入会话时，已生成文本来自 Host 进程内的累积流；若此时 Host 进程重启，该回合剩余文本只能等 assistant/message 落地后才出现（Host 侧限制，TUI 无法补出已丢失的增量）；
- 二进制附件依赖 dsh 0.1.5：非图片文件通过 fileUploads/upload + {type:"file", receiptId} 成为真正的 Host 附件；旧 Host 没有该通道时，条目退化为「仅元数据」（名称/大小/类型）且不会发送；工具结果若含原始二进制字节（NUL/控制字符），工具卡同样只显示二进制数据元数据而不渲染字节（Host 侧协议限制，TUI 无法单独扩展）；
- 文件改动流只覆盖 Host 插入式写入：workspaceFiles/changes 转发的是 fs/observed（Host 组合文件系统上的写入/编辑工具等）。子进程、shell 命令或用户编辑器直接改文件不会产生任何帧（实测确认），因此「文件/改动」页只显示本会话内被 Host 观测到的改动；
- Kitty 图片效果受终端实现、cell 尺寸和复用器支持影响；
- 超长工具输出由 Host 截断并给出恢复路径：TUI 检测 [output truncated; full output: ] / stored at: 类提示，在工具卡内显示完整输出文件，选中该块后 Ctrl+R 菜单可 host.openPath 打开、复制路径；「TUI 内预览完整输出」通过 workspaceFiles/read 从 Host 读取该文件（上限 500 行），因此远端部署同样可用，只有 Host 上没有该文件时才回退到本机同路径读取；
- 可编辑快捷键覆盖配置已持久化并经过校验；输入/编辑/全局快捷键均已接入动态 dispatch，Esc 退出输入、Ctrl+Q 退出与审批弹窗 y/n 等安全键保持固定语义。

代码结构

src/api.js HTTP RPC、WebSocket 和 respond src/term.js raw mode、鼠标、paste、Kitty keyboard src/screen.js cell framebuffer 与 ANSI diff src/text.js grapheme、显示宽度和截断 src/md.js Markdown、代码块和 OSC 8 src/keybindings.js 可编辑快捷键注册表（每个功能主/备两个槽位） src/widgets.js Input、Popup、ScrollView、Menu、StatusBar src/views.js App、ChatView、会话树和主路由 src/panels.js Workspace、Trajectory、Queue、Jobs、Settings src/file-picker.js 三栏文件/目录选择器与图片预览（列表/预览走 Host） src/host-files.js Host 文件访问（workspaceFiles/、fileReferences/、改动流、附件上传）与异步缓存 app/ DSH bundle 与 Cordis patch

许可证

MIT