tomowang/dsh-tui

dsh-tui

build status
npm version
license
TypeScript

一个面向 DeepSeek Harness（dsh）的开源终端入口。

@tomowang/dsh-tui 是一个树外模式包（out-of-tree mode bundle）：它像随附的 dsh-web-app 和 dsh-headless 包一样叠加在 @deepseek-ai/dsh-base 之上，但它是从你的终端而非浏览器驱动 agent。该包既是一个 Cordis 插件（终端输入与呈现），也是一个 dsh 包（package.json 中的 dsh.bundle.patch 指向 cordis.patch.yml）；其余一切——模型适配器、工具、会话持久化、沙箱与审批策略——都留在 dsh-base 中，并且仍可在其下层进行补丁修改。

dsh-tui 录屏

工作原理

- TUI 仅从持久化会话日志渲染：启动时重放 agent.session.snapshotEvents()，并实时跟随 session/event，因此 --resume 会显示日志所携带的精确历史——harness 的“模型可见 ⟺ 已记录”不变式承担了主要工作。
- 界面以全屏方式运行在终端的备用屏幕缓冲区中，拥有由应用持有的对话记录视口（可用鼠标滚轮/触控板、PageUp/PageDown 滚动），在你向上滚动之前会自动跟随新输出。
- 行输入映射到 agent 收件箱：空闲时调用 agent.followup()，回合运行中调用 agent.steer()，Ctrl+C 取消正在运行的回合。
- tui-startup 通过 dsh-cmdline 解析本应用的标志（即启动器自身标志之后的所有内容），并将它们作为普通的 Cordis 服务发布；runner 行通过 bundle patch 读取它们，与 dsh-headless 的做法一致。
- stdin 和 stdout 都必须是真正的 TTY；该插件会明确报错而不是降级，因此管道场景继续使用 dsh --profile headless。

功能特性

- 状态栏 —— 会话 id、当前活跃的 LLM 提供商/模型、当前 agent 预设、带 spinner 的实时运行状态、排队消息数，以及已记录事件数。
- 统计行 —— 回合/步骤计数、LLM/工具墙钟时间、TTFT 与解码 tok/s、缓存命中率、计费 token 数，以及紧凑的上下文用量摘要；各区块在有数据之前会自行隐藏。
- /model 提供商管理 —— 从提供商的目录中挑选来切换活跃模型，并可在不离开终端的情况下添加、编辑或删除自定义 LLM 提供商（路由、base URL、API key、模型发现）。
- Agent 预设 —— 使用 --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/计划模式的计划审查会以选项列表形式呈现，支持多选和自由文本“Other…”，按 esc 跳过。每当此类等待开始时，会触发一次桌面通知（OSC 9 — 与 Claude Code 自身 CLI 使用的机制相同），因此支持它的终端（Ghostty、Kitty、启用了转义序列警报的 iTerm2）可以在你看向别处时提醒你；不支持 OSC 9 的终端会直接忽略它。
- 计划模式 — /plan [message] 进入计划模式（可选地在计划模式下引导第一条消息），/plan off 退出；模型提出的计划会进入现有的提问流程，作为 Approve/Keep-planning 审查呈现。
- 目标模式 — /goal  设置一个长期运行的目标，以实时 dock 条显示（阶段 + 目标，完成后像 Web 门户一样隐藏）；/goal clear|edit |pause|resume 用于管理它，并且在目标处于活动且已武装状态时，自动续跑轮次会在同一会话中持续运行。
- 停靠式子代理切换器——只要当前批次中至少有一个子代理正在运行，一个实心/空心圆点条就会直接停靠在输入框下方（Claude Code CLI 风格）：当提示为空时，←/→ 可切换主滚动区域显示哪个转录记录——主代理，或任意子代理子项，最新生成的排在最前——同时不会隐藏输入框或圆点条本身，按 Esc 返回主代理。正在运行的子项还会在其圆点旁显示一个实时旋转指示器，与当前选中哪一个无关——实心/空心标记导航（你正在查看的内容），旋转指示器标记活动（仍在工作的内容），因此两者永远不会相互混淆。当子项超过 4 个时，一个暗淡的 ‹N/N› 计数会标记可见窗口未容纳的部分，并随着你循环切换而滑动，以保持当前打开的那个位于窗口内。该圆点条是当前活跃工作批次的实时指示器，而非永久日志——一旦一切稳定下来且没有正在查看的内容，它就会消失。
- 手动压缩——/compact 按需对会话历史进行总结和压缩。
- 会话重命名——/rename  设置显式标题；单独使用 /rename 则通过一次按需模型调用，根据迄今为止的对话生成一个标题，采用 kebab-case 短横线命名格式（Claude Code CLI 自身的约定，例如 fix-auth-bug），而非 harness 自有的自然语言默认格式。接受的标题还会右对齐显示在提示框自身的顶部边框上，与终端窗口/标签页标题并列。
- 会话恢复——/resume  在一个全新屏幕中切换到已持久化的会话（若 id 未知，则回退到一个全新会话并给出提示）；单独使用 /resume 则会打开一个选择器，列出此工作目录下的过往会话——最新的排在最前，每个会话都带有其折叠后的标题（如果有的话）。
- 持久化提示历史——已提交的行会跨进程和 /clear 保存，可用 ↑/↓ 召回。
- 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 时，会生成一个简短的首条消息摘要），终端标题栏就会显示  — dsh-tui；在此之前或未挂载该服务时，它保持为 dsh-tui。
- 全屏可滚动记录 — 该界面占用终端的备用屏幕缓冲区，而不是扩展原生回滚缓冲区，支持鼠标滚轮/触控板和 PageUp/PageDown 滚动，并自动跟随底部；退出时，最后一屏内容会被平铺回终端正常的回滚缓冲区中。/trajectory 仍然是浏览超出视口范围更早内容的工具。
- 当某个覆盖层的支撑服务未在给定配置文件中挂载时，每个覆盖层都会降级为一条普通提示，而不是让整个 TUI 失败。

安装

需要 Node ^22.19 || >=24 以及 DEEPSEEK_API_KEY。

1. 安装 dsh 启动器
npm install -g @deepseek-ai/dsh

2. 创建配置文件并将此 bundle 安装到其中
（dsh 会自动协调配置文件清单中的 "dsh.profile.bundles" 列表，
追加任何声明了 dsh.bundle.patch 的已安装依赖 — 无需手动编辑 package.json）
dsh plugin --profile tui add @tomowang/dsh-tui

3. 运行
dsh --profile tui
dsh --profile tui --resume            # 重新打开一个已持久化的会话
dsh --profile tui --resume                       # 从列表中挑选一个过往会话，最新的在前
dsh --profile tui --agent-preset       # 在给定预设上启动一个新会话
dsh --profile tui --dump-config                  # 检查组合后的插件树

--dump-config 打印的任何一行 — 模型适配器、工具集、沙箱策略、此 TUI 自身的配置 — 都可以从配置文件的 cordis.patch.yml 中覆盖，而无需改动此包。--agent-preset 是 dsh 启动器的一个标志（由 tui-startup 解析，而非上面的 --dump-config），仅适用于新会话；它会与 --resume 一起被忽略，并且在未挂载 dsh-agent-presets 的配置文件上是一个无操作，并会给出启动提示。不带 id 的 --resume 会打开与下面裸 /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  / /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

要在某个 profile 中试用本地检出，请将该 profile 的依赖指向此目录（dsh plugin --profile tui add /path/to/dsh-tui），并在每次运行前重新构建——profile 在普通 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。推送标签会触发 CI 进行构建、创建 GitHub Release，并发布到 npm。完整流程见 AGENTS.md。

许可证

MIT