终端交互界面 tomowang/dsh-tui

dsh-tui

DeepSeek Harness（dsh）的开源终端入口。

@tomowang/dsh-tui 是树外模式包：它和随包发布的 dsh-web-app、dsh-headless 一样，叠加在 @deepseek-ai/dsh-base 之上，区别在于它从终端驱动智能体，而不是从浏览器。这个包既是 Cordis 插件（负责终端输入与呈现），也是 dsh 包（package.json 里的 dsh.bundle.patch 指向 cordis.patch.yml）；其余部分——模型适配器、工具、会话持久化、沙箱与审批策略——都留在 dsh-base 里，并且仍可在下层打补丁。

dsh-tui screencast

工作原理

- TUI 只从持久化会话日志渲染：启动时重放 agent.session.snapshotEvents()，之后实时跟随 session/event，所以 --resume 显示的就是日志里原样的历史——harness 的「模型可见 ⟺ 已记录」不变式承担了主要工作。
- 界面全屏运行在终端的备用屏幕缓冲区里，转录视口归应用自己管理（用鼠标滚轮/触控板、PageUp/PageDown 滚动），自动跟随新输出，直到你向上滚动。
- 行输入映射到智能体收件箱：空闲时走 agent.followup()，回合运行中走 agent.steer()，Ctrl+C 取消正在运行的回合。
- tui-startup 通过 dsh-cmdline 解析本应用的参数（启动器自身参数之后的所有内容），并作为普通 Cordis 服务发布；runner 行通过包补丁读取它们，做法与 dsh-headless 一致。
- stdin 和 stdout 都必须是真正的 TTY；插件会直接报错退出，不做降级，所以管道场景继续用 dsh --profile headless。

功能

- 状态栏——会话 id、当前 LLM 服务商/模型、当前智能体预设、带 spinner 的实时运行状态、排队消息数、已记录事件数。
- 统计行——回合/步骤计数、LLM/工具实际耗时、TTFT 与解码 tok/s、缓存命中率、计费 token 数，以及精简的上下文用量摘要；各区块在有数据之前自动隐藏。
- /model 服务商管理——从服务商目录中挑选切换当前模型，还能新增、编辑、删除自定义 LLM 服务商（路由、base URL、API key、模型发现），全程不用离开终端。
- 智能体预设——用 --agent-preset 在指定预设上开新会话，或从 /presets 浏览并切换预设（会话首个回合跑完后即固定）。
- 会话检查器 — /trajectory 查看按轮次/步骤记录的事件账本，带详情视图和筛选；/context 查看上下文窗口用量明细；/plugins 查看已加载的 Cordis 插件树和 fiber 状态。
- 折叠的工具调用与实时 spinner — 运行中的工具调用在提示词区域只显示为一行 spinner；结果返回后，收成一行折叠的 ✓/✖ 记录，不再显示成内联的多行卡片。
- 工具卡片浮层 — /tools 或 Ctrl+O 打开可滚动的浏览器，浏览本次会话的工具调用与结果，每张卡片默认展开到完整呈现（Enter/Space 把卡片折叠回标题）。
- 推理内容展示 — 模型的推理/思考内容不会刷屏：还在流式输出时，用一行动态的 ✦ thinking 代替；写入记录后，收成一行 ✦ think · … 摘要，放在可见回答之前；完整文本随时可通过 /trajectory 查看。
- Markdown 渲染 — 助手文本带有明确的 Markdown 信号（围栏代码、标题、列表、引用块、分隔线、表格、链接、粗体/删除线、行内代码）时，按终端样式渲染；普通散文原样输出。
- 权限预设循环切换 — Shift+Tab 在 read-only / workspace-write / danger-full-access / custom 之间循环，提示词区域实时显示当前值。
- 终端内审批与提问 — 工具调用停在 ask 权限决策上时，直接在终端里回答（允许一次 / 拒绝）；ask_user_question 和 plan 模式的计划评审以选项列表呈现，支持多选和自由文本「Other…」，按 esc 跳过。这类等待一开始就会触发一次桌面通知（OSC 9 —— Claude Code 自己的命令行用的也是同一机制），支持该机制的终端（Ghostty、Kitty、开启转义序列提醒的 iTerm2）在你看向别处时也能提醒你；不支持 OSC 9 的终端会直接忽略。
- Plan 模式 — /plan [message] 进入 plan 模式（可选地顺带发送第一条消息），/plan off 退出；模型提出的计划进入现有的提问流程，以 Approve/Keep-planning 评审呈现。
- Goal 模式 — /goal <objective> 设定长期目标，以实时 dock 条显示（阶段 + 目标，完成后隐藏，与 web portal 一致）；/goal clear|edit <objective>|pause|resume 管理目标；目标处于激活且已武装状态时，自动续跑轮次会在同一会话中持续运行。
- 停靠式子代理切换器 — 当前批次里只要有至少一个子代理在运行，输入框正下方就会停靠一条实心/空心圆点条（Claude Code 命令行风格）：提示词为空时，按 ←/→ 切换主滚动区显示哪份记录——主会话，或任意子代理子会话，最新生成的排最前——输入框和圆点条本身都不会隐藏，按 Esc 回到主会话。正在运行的子会话还会在圆点旁带一个实时转圈指示，与当前选中哪一个无关——实心/空心标记导航（你正在看哪个），转圈标记活动（哪个还在干活），两者永远不会混淆。子会话超过 4 个时，可见窗口装不下的部分用暗色的 ‹N/N› 计数标出，循环切换时窗口会滑动，让打开的那个始终留在窗口内。这条圆点条是当前活跃工作批次的实时指示，不是永久日志——一切结束且没有正在查看的内容后，它就会消失。
- 手动压缩 — /compact 按需总结并压缩会话历史。
- 会话重命名 — /rename 设置显式标题；不带参数的 /rename 会根据到目前为止的对话生成标题，通过一次按需模型调用，产出 kebab-case 形式的 slug（Claude Code 命令行自己的惯例，例如 fix-auth-bug），而不是 harness 自带的自然语言默认标题。接受的标题还会右对齐显示在提示词框自己的上边框里，与终端窗口/标签页标题并列。
- 会话恢复 — /resume <sessionId> 在新屏幕中切换到已持久化的会话（id 未知时回退到全新会话并给出提示）；不带参数的 /resume 则打开当前工作目录历史会话的选择器——最新的排最前，每个都带上已落定的折叠标题。
- 持久化提示词历史 — 提交过的行会跨进程和 /clear 保存（在 $DSH_HOME/dsh-tui/history.jsonl，默认 ~/.dsh/…），用 ↑/↓ 召回。
- Readline 风格输入 — 按词/按行移动、kill/yank 风格删除、多行草稿，以及类似 shell 的双击 Ctrl+C/Ctrl+D 退出。
- Shell 模式 — 空提示词下以 ! 开头（Claude Code 的惯例）会把 Enter 改为将这一行作为本地 shell 命令执行，而不是发给智能体；期间提示词边框变黄，输出流进记录区，不碰会话日志。
- @ 文件提及自动补全 — 输入 @ 会打开仓库文件的模糊过滤下拉列表（git ls-files，在 git 仓库外则做有界遍历）；Tab/Enter 在光标处插入选中的路径。
- 更新提示 — 启动时尽力检查 npm registry，一旦发布了更新的 @tomowang/dsh-tui，就显示一条常驻停靠行，带上升级命令；任何网络失败或超时都静默处理。
- 终端窗口/标签页标题 —— 会话拿到标题后（标题是首条消息的简短摘要，前提是配置档组合了 dsh-session-title），终端标题栏显示 <session title> — dsh-tui；在此之前，或者没有挂载该服务时，标题保持 dsh-tui。
- 全屏可滚动记录 —— 界面占用终端的备用屏幕缓冲区，不撑大原生回滚区，支持鼠标滚轮/触控板和 PageUp/PageDown 滚动，记录自动跟随底部；退出时把最后一屏内容平铺回终端正常的回滚区。要浏览视口之外的更早内容，仍用 /trajectory 工具。
- 某个浮层依赖的服务没在配置档里挂载时，浮层降级为一条普通提示，不会让整个 TUI 失败。

安装

需要 Node ^22.19 || >=24 和 DEEPSEEK_API_KEY。

1. Install the dsh launcher
npm install -g @deepseek-ai/dsh

2. Create the profile and install this bundle into it
(dsh reconciles the profile manifest's "dsh.profile.bundles" list
automatically, appending any installed dependency that declares
dsh.bundle.patch — no manual package.json edit needed)
dsh plugin --profile tui add @tomowang/dsh-tui

3. Run
dsh --profile tui
dsh --profile tui --resume <sessionId> # reopen a persisted session
dsh --profile tui --resume # pick a past session from a list, newest first
dsh --profile tui --agent-preset <presetId> # start a fresh session on a given preset
dsh --profile tui --dump-config # inspect the composed plugin tree

--dump-config 打印出的任何一行 —— 模型适配器、工具集、沙箱策略、这个 TUI 自己的配置 —— 都能在配置档的 cordis.patch.yml 里覆盖，不用改这个包。--agent-preset 是 dsh 启动器的参数（由 tui-startup 解析，不是上面 --dump-config 打印的内容），只对新会话生效；和 --resume 一起用时会被忽略；配置档没挂载 dsh-agent-preset-registry 时它不生效，启动时会给出提示。这个包内置了和 Web 门户相同的四个预设（Standard、PTC、Minimal、Creator），放在 presets/ 下。--resume 不带 id 时，打开的是下面 /resume 那个会话选择器。

终端命令

| 输入 | 效果 |
| 任意文本 | 空闲时作为后续消息，回合运行中作为引导 |
| /help | 显示可用命令和键盘快捷键 |
| /model | 管理 LLM 服务商配置档：从服务商目录里选当前模型（s 打开选择器；↑/↓ 选择，Enter 激活，Esc 退出），添加/编辑/删除自定义服务商 |
| /presets | 查看和切换智能体预设（会话首个回合跑完后固定） |
| /trajectory | 浏览回合/步骤事件账本，带详情查看器和过滤器 |
| /tools | 浏览工具卡片，展开折叠的记录行 |
| /context | 以条形图明细显示上下文窗口用量 |
| /plugins | 显示已加载的 Cordis 插件树和 fiber 状态 |
| /plan [message] | 进入计划模式，可选把 message 作为该模式下的第一步 |
| /plan off | 退出计划模式 |
| /goal [objective] | 设置长期目标（不带参数时显示当前目标） |
| /goal clear / /goal edit <objective> / /goal pause / /goal resume | 清除、改写、暂停或恢复当前目标 |
| /compact | 总结并压缩会话历史 |
| /rename [title] | 设置显式会话标题；不带参数时，根据目前为止的对话生成一个 |
| /resume [sessionId] | 按 id 切换到已持久化的会话；不带参数时，打开本目录历史会话的选择器 |
| /clear | 清空当前会话并开始新会话 |
| /exit、/quit | 取消、等待空闲、清空会话、退出 |

键盘快捷键

| 按键 | 作用 |
| 鼠标滚轮/触控板、PageUp/PageDown | 滚动对话记录；回到底部后重新自动跟随新输出 |
| Ctrl+C | 取消正在运行的回合；在空闲的空行上，2 秒内按两次退出 |
| Ctrl+D | 向前删除；在空闲的空行上，2 秒内按两次退出 |
| Shift+Tab | 循环切换权限预设（read-only / workspace-write / danger-full-access / custom） |
| Ctrl+O | 打开工具卡片浮层；↑/↓ 选择卡片，Enter/Space 展开或折叠，PgUp/PgDn/Home/End 滚动已展开的卡片，Esc/q/Ctrl+O 关闭 |
| !（在空提示词上） | 进入 shell 模式：Enter 将该行作为本地 shell 命令运行；Esc/在空行上按退格键返回普通模式 |
| @ | 打开文件提及下拉框；↑/↓ 移动，Tab/Enter 插入路径，Esc 关闭 |
| ←/→（空提示词） | 停靠的子代理切换器显示时，移到上一个/下一个会话（主会话，然后是各子代理子会话） |
| Esc（查看子代理、空提示词时） | 返回主对话记录 |
| /resume（不带参数） | 打开会话选择器；↑/↓ 选择，Enter 恢复选中的会话，Esc/q 关闭且不恢复 |
| Tab | 在 /command 模式下，自动补全高亮的命令 |
| ↑ / ↓、Ctrl+P / Ctrl+N | 调出提示词历史，或在多行草稿内移动 |
| Shift+Enter、Alt+Enter、行尾 \ + Enter | 插入换行而不是提交 |
| Home/Ctrl+A、End/Ctrl+E、Ctrl+B/Ctrl+F/方向键 | readline 风格的字符和行移动 |
| Alt+Left/Alt+Right、Ctrl+Left/Ctrl+Right | 按词移动 |
| Ctrl+K/Ctrl+U、Ctrl+W/Alt+Backspace、Alt+D | 删除到行尾/行首、向前/向后删除一个词 |

开发

pnpm install
pnpm run build # tsc → lib/
pnpm run typecheck
pnpm run lint
pnpm run test

要在配置档里试用本地检出，把配置档的依赖指向本目录（dsh plugin --profile tui add /path/to/dsh-tui），并在每次运行前重新构建——配置档在普通 Node 下加载构建好的 lib/。

发布

CHANGELOG.md 和 GitHub Release 说明由 git-cliff 从 Conventional Commits 生成。发布流程：先改 package.json 里的 version，再运行 pnpm run changelog，然后以 chore(release): vX.Y.Z 提交，最后执行 git tag vX.Y.Z && git push && git push --tags。推送 tag 会触发 CI 构建、创建 GitHub Release，并发布到 npm。完整流程见 AGENTS.md。

许可证

MIT