ccch1mneyyy/dsh-TUI

简体中文 | English

dsh-TUI

一个面向 DeepSeek Harness 的交互式终端界面插件：提供像素鲸鱼顶栏、实时工作状态行、流式思考展示、双击 Esc 时间回溯、上下文进度条与 TPS 仪表。

零核心改动，纯插件挂载。安装插件即可启用，卸载后不会留下核心补丁。

>An interactive terminal UI plugin for DeepSeek Harness: pixel-whale header, live work status, streaming thinking display, double-Esc time rewind, a context progress bar, and a TPS gauge.

Zero core changes, pure plugin mounting. Install to enable; uninstall leaves no core patches.

🎉 官方收录

本插件被 DeepSeek Harness 官方公众号 推文收录，也被 dshfind 插件目录与 GitHub Trending 收录，同时登上了Github Treding日榜第七

核心能力

Windows Terminal 支持 Sixel 时，全屏会话记录可直接显示内嵌缩略图，点击后打开大图预览；非全屏 inline 模式仍保留文字回退。 Sixel 使用最多 256 色的自适应调色板，透明像素与背景合成；Worker 缓存量化结果，滚动时仅编码可见部分，移出视野或被浮层覆盖时擦除旧图。 附件读取与解码最多两路并发；最后一个使用者离开后取消读取，未启动的解码不再执行。多图缓存、排队任务与单帧传输均有容量上限，超限时保留文字回退。 自动探测优先 Kitty，其次使用 DA1 声明的 Sixel 能力。DSH_TUI_IMAGE_PROTOCOL=auto|kitty|sixel|none 可覆盖协议选择； DSH_TUI_DISABLE_TERMINAL_IMAGES=1、无障碍模式、非 TTY 输出以及 tmux/screen 仍禁用图形。 缺少图片依赖或编码失败时保留文字回退；强制协议也不会启用 inline Sixel。 浅色主题的面板和图片预览默认使用白底，图片预览边框使用中性色。 大图预览以对话区约 95% 宽高为预算，最长边可达 2048 像素，仍限制总像素量和后台开销；缩略图大小不变。 预览支持适应窗口、100% 原像素与 200%/400%/800% 放大，拖动、滚轮或方向按钮平移；100% 需终端报告字符格像素尺寸。 底部「打开原图」链接直接调用系统看图程序，打开未经重编码的原始附件，包括从历史会话恢复的图片。 大图弹窗用 ←/→ 或底部 ‹/› 切换上一张、下一张，显示当前张数，首尾不循环；切图回到适应窗口。

• 终端交互：低资源占用，长会话稳定可靠；多种主题切换，样式美观，实时显示工作状态、TPS、缓存命中率等

推理等级、输入/输出 token 与 Git/会话信息；终端卡多行命令可经 /settings 折叠为首行 + 计数提示（Ctrl+O 或点击卡片展开）；全屏模式下悬停在截断的工具卡标题或会话标题上约 600ms，浮层显示完整内容，拖选文本期间浮层一律不出现（避免覆盖待复制的单元格）。全屏模式右侧栏提供 timeline / 滚动条 / 隐藏三种模式；滚动条模式下轨道本身即拖拽目标——未修饰左键按住拖动可按指针所在轨道位置连续滚动（轨道点击定位的直接延伸），Shift/Alt/Ctrl+拖动仍为文字选择。 用户附图及助手/工具结果中的持久图片块会直接显示在会话记录中；Kitty graphics 或 Sixel 可用时显示等比缩略图，否则保留同尺寸文字回退。全屏下点击输入框 [Image #N] 或 transcript 缩略图在对话区域居中打开大图预览，卡片外的对话文字变暗，不遮挡输入栏（Esc/点击外部关闭），标题为 Image #N — 格式 · 尺寸 · 体积 · 文件名，本会话暂存的图片在卡片底行显示来源路径；Finder 复制的图片文件粘贴时直接入附件库为 [Image #N]，交给附件库之前先按 profile 的图片限额适配：超过单边像素/总像素上限的图片等比缩放到上限内；profile 不接受该格式时按可接受格式重编码（有透明通道时优先保留透明，只能转 JPEG 时透明区域填白）；需要改动字节的动图（多帧）明确拒绝，而不是把它的帧悄悄丢掉。适配过的图片会在粘贴提示里说明最终入库的尺寸与格式（提示取自附件库的回报，因此与预览卡一致；适配需可选依赖 sharp，且只覆盖「交给附件库之前」这一步——附件库自身的归一化不在本功能范围内）；输入框里的 [Image #N] 是一个整体，光标整体跳过、删除整体生效，光标落在其上时整块反显并自动打开预览、离开时关闭。Vim 的 x/X/d… 同样整张删除，u 同时恢复文字与附件；撤销仅限当前草稿。 终端图片预览默认开启，可在 /settings → 终端图片预览 或配置 terminalImages: false 中关闭，使用 /restart 后生效。已保存的 /settings 选择优先于 Cordis 配置；若曾保存为开启，请在 /settings 中关闭后再 /restart。关闭时保留文字信息并跳过预览解码，不影响向模型发送图片；DSH_TUI_DISABLE_TERMINAL_IMAGES=1 始终强制关闭预览。 回复中的 ``` `mermaid `` 代码块直接画成 Unicode 字符图（flowchart / sequence / state / class / ER / pie / mindmap / timeline / gitGraph），纯进程内布局，不依赖浏览器或图片协议，流式输出时随内容逐步成形；比终端宽或类型不支持的图保留源码并注明所需列数。默认开启，/settings → Mermaid 图表 或配置 mermaidDiagrams: false` 关闭，立即生效。

• 功能全面：/resume、/home、/agentview、/bg 与输入框行首 ⌸ 打开同一个会话管理界面——左侧工作区栏（持久登记：编辑 / 在此新建 / 重命名 / 从列表移除），右侧该工作区的会话列表（实时状态、筛选、行内 ★ 固定，持久化到 ~/.dsh-tui）；被其他 TUI 终端占用的会话照常列出但拒绝进入，本终端停放中的会话可随时切回（切换不中断正在跑的回合）；未登记目录下的会话有兜底分组，不会因"没有登记"而消失、/new、/compact、/export、/btw，模型热切换（新会话默认推理强度可在 /settings → 默认推理强度 预设），原生subagent，会话fork，自动更新，输入框 /vim vim 编辑模式、鼠标选区编辑（拖选高亮、Shift+click 扩展、双击选词、Ctrl+C 复制选区）与全屏草稿编辑（Ctrl+Shift+E 或输入行 ⛶ 按钮：行号 + 当前行高亮、Enter 换行、Ctrl+Enter 发送、滚轮滚动、点击/拖选，长草稿独占整屏；/settings 可关）；可在vs code中以vscode插件形式启动，已上架 VS Code Marketplace。

/resume 只将完整读取并确认没有用户消息的日志判为空会话；仅发图片、读取不完整或解析失败的会话不会被归入空会话清理。

• IDE 选区通道：搭配 VS Code 扩展启动时，编辑器选中代码后 prompt 下方实时显示 ⧉ N lines selected 徽标，提交消息自动附加选中行内容（transcript 有「⧉ Selected N lines」指示行）；手动启动（tmux/SSH）通过 lock 自动发现本机 IDE，无 IDE 时静默降级零影响。详见 vscode.md。
• 扩展丰富：原生浏览器交互，compter use等大量附属功能性扩展
• 技能归 DSH 管理：/skills 展示当前 profile、用户与项目发现的技能；dsh-TUI 不预装通用技能。

技能目录暂时不完整时，保留最后一次完整观测的技能菜单与命令注册，并按 800/1600/3200ms 最多重试三次；耗尽后等待 DSH 的 skills/change 通知或显式刷新，不持续轮询。只有完整观测才能移除已消失的技能，包括完整空目录。

• 工作状态动画：默认使用 moon8；读取旧版本地配置中的 claude 值时自动映射为 moon8，选择器只显示当前预设。
• 像素鲸鱼娘：开屏随机三选一开场动画；欢迎期（开始第一个任务前）可点击冒爱心并唤醒睡着的鲸鱼，闲置时摆鱼鳍、拍尾巴、入睡冒 Z（/settings → whaleIdle 可关）。开始第一个任务后永久定格为静态标准帧，零持续开销。鲸鱼娘的 22 帧手绘原图与闲置行为移植自 dsh-ui-whale（作者 @lhh010），特此致谢。

界面预览

快速开始

前置条件：安装Nodejs与deepseek-harness，注册DEEPSEEK_API_KEY。

安装命令：

npm install -g @deepseek-ai/dsh @deepseek-harness-tui/dsh-tui

启动命令：

# 完整命令
dsh-tui
如果你不想按键盘七次
dst

如果你想手动安装，可以使用仓库根目录的 install.sh：

sh install.sh
或：dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui
之后 dsh-tui 与 dsh --profile dsh-tui 等价

新用户提示：若 dsh plugin 安装时报 ERR_PNPM_IGNORED_BUILDS（pnpm ≥11 默认阻止带安装脚本的依赖，如 @google/genai、protobufjs——这些脚本运行时不需要，忽略即可），在 profile 的 pnpm-workspace.yaml 里加入：

>

> allowBuilds:

'@google/genai': false

protobufjs: false

> /update 与 dsh-tui update 会自动写入这份配置，无需手工处理。

> 更新时还会维护 ignoredOptionalDependencies（忽略异平台的 @img/sharp-* 原生包）——sharp 以全平台可选依赖分发，不处理时 pnpm update 会把各平台二进制一起下载（实测约 200MB）。名单每次更新按当前平台重算，异平台原生包不再下载（当前平台原生包与无平台归属的 wasm 回退包保留）；把 profile 搬到别的平台或 musl 容器后，在那台机器上跑一次更新即可刷新。老 profile 的 lockfile 里仍写着全平台条目，第一次更新会照旧下载一遍，之后才被忽略。块内不属于这两张平台表的条目（fsevents、自己写的 @img/sharp-wasm32 豁免）原样保留；需要 pnpm 支持该键，不认识的版本不会因此报错，只失去这项收益。

更面向零基础的安装流程、profile 叠加机制、源码构建与常见问题见安装与快速开始。

安全模式（dsh-tui safe）

dsh 意外结束时，安全模式提供只读的环境诊断、profile 插件清单与修复指引。

• 双入口：手动运行 dsh-tui safe；或在 dsh 以非零退出码结束后按提示进入。该询问仅出现在交互终端——脚本/管道等非交互环境只追加一行提示，且退出码保真；询问只覆盖最终 dsh 子进程的非零退出码，不含启动挂起（dsh 启动失败等同退出码 1 处理）。
• 只读边界：安全模式控制面只读（诊断/清单/指引均不改动状态），例外有二："重试正常启动"与"创建/复用空白救援 profile"——后者是显式救援动作，它自己的安装只写进 $DSH_HOME/profiles/dsh-tui-safe/。另有两件要如实说明（都不是安全模式引入的新写行为）：① 任何一次 dsh 启动都会维护共享的 $DSH_HOME/profiles/node_modules 模块回退链接（上游 dsh 的 healProfilesModuleFallback，没有开关），救援启动同样如此；② 安装由 pnpm 执行，pnpm 自己的全局 store（pnpm store path，默认在 $DSH_HOME 之外）也会被写入或复用。
• 救援 profile 的干净性必须先被证明，证不出就拒绝：进入救援前逐条校验，任一不成立即拒绝启动并打印原因与处置办法（门禁本身只读）：① 候选目录已存在但不是可识别的 profile（拒绝往未知目录安装）；② 既有 profile 的根 manifest 声明了第三方插件（启动它就不是干净环境）；③ $DSH_HOME/cordis.patch.yml（home 层）存在即拒绝——上游 dsh 把它叠加到每个 profile 之上（排在 bundle 层与 profile 层之后）；④ profile 自带的 dsh-tui-safe/cordis.patch.yml（profile 层）有条目即拒绝——dsh 同样把它组合进 profile（bundle 层之后）。后两层启动器既不解析 YAML 也拿不到组合结果，故一律 fail-closed；dsh 默认生成的「注释 + []」不算条目，不影响复用。校验通过后：创建 dsh-tui-safe（仅 base + TUI，钉当前版本，走官方 dsh plugin add）并以显式构造的环境（剥离宿主遗留的会话控制变量）启动——主 profile 装炸时用 dsh 修 dsh 的通道；救援会话结束回到菜单。已存在且干净时按现状复用，绝不重复安装；半装或「安装报成功但包不可读」的救援 profile 会被清掉重建——删除前按名字与形态核对顶层条目（package.json/pnpm-lock.yaml/pnpm-workspace.yaml/cordis.patch.yml/cordis.yml 必须是文件，node_modules/.dsh-module-fallback 必须是目录，后者是 dsh 每次 profile 启动都会建的），发现别的名字或形态不符就拒绝并列出名字，绝不静默删你的文件；注意这些生成目录内部的内容会随目录一起被删掉。手动等价命令见指引（选项 4）。
• 非交互环境：dsh-tui safe --rescue 在脚本/管道下执行同一套门禁与创建/复用，只报告结论（就绪退出 0，被拒绝退出 1）；在交互终端里等价于菜单选项 5。
• 旧全局启动器：profile 副本不可读或过旧时，先升级启动器：npm install -g --legacy-peer-deps @deepseek-harness-tui/dsh-tui@<版本>。
• 修复命令示例（安全模式只列出，需自行执行）：dsh plugin --profile dsh-tui remove <第三方插件> 逐个移除可疑插件；dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui@<版本> 重装对齐；dsh-tui doctor 环境诊断。

插件扩展与开发指南

想为 dsh-TUI 做插件/扩展？欢迎加入生态！

• 接口与兼容性协定 / 插件开发指南：终端交互生态插件准入与开发指南（准入规范、接缝、契约、验证清单）
• 生态组织：dsh-tui-ecosystem（社区插件与模板的家）
• 模板仓库：plugin-template（从模板起步，5 分钟出一个插件）
• 参考实现：dsh-working-activity（实时工作状态行：TUI 槽位 + activity/status 会话事件双出口）

接缝稳定性参考

按当前实现成熟度给出的非正式分级，帮助插件作者评估投入；正式状态与兼容性协定以 准入与开发指南为准：

| 分级 | 接缝 | | --- | --- | | 稳定候选（形态冻结；如有破坏性变更，先在次版本弃用告警再移除） | 六 设置区块 · 八 全屏场景 · 十 托管对话框 · 十一 状态行 · 十二 键盘快捷键 · 十三 条目渲染器 | | 实验性（仍可能随 dsh-std / 准入规范演进调整） | 九 决策事件 · toast 通知（ctx.tuiToast，新增） | | 跟随上游（稳定性由 cordis / dsh 官方机制决定） | 一 会话事件 · 二 官方 prompt 槽位 · 三 技能打包 · 四 主题 · 五 system prompt 段 · 七 profile 组合 |

另：@deepseek-harness-tui/dsh-tui/api（纯类型入口）为实验性公开面； @deepseek-harness-tui/dsh-tui/test-utils 子路径与 ctx.tuiPluginHost.grants.corrupt 已随 adapter 分层重构（#705）移除，grants 收窄为 HostGrantFacade，迁移细节见该 PR。

文档索引

| 主题 | 内容 | | --- | --- | | 安装与快速开始 | 前置条件、安装、启动、profile 生命周期、源码开发 | | 配置参考 | Cordis 覆盖、配置字段、Agent preset、MCP、环境变量 | | 主题系统 | 内置主题、自动检测、静态 JSON 与 npm 插件主题、校验规则 | | 交互与命令 | 快捷键、鼠标、问卷、slash command 与会话工作流 | | 架构与限制 | 运行链路、渲染与持久化设计、安全边界、已知限制 | | 社区管理框架 | 社区入口、角色、提案流程、roadmap 规则与维护节奏 | | 项目路线图 | 公开目标、阶段、任务状态、退出条件与 Future Work | | VS Code 使用指南 | 在 VS Code 集成终端运行 dsh-tui；companion 扩展 dsh-tui-vscode 提供多会话、会话历史与指定会话恢复（已上架 Marketplace） | | 贡献与开发约定 | 贡献流程、仓库地图、构建产物、验证矩阵与修改规则 | | 插件准入与开发指南 | 接口与兼容性协定 / 插件准入规范 / 插件接缝 / 契约 / 验证清单（已并入 dsh-ecosystem-spec） |

完整的中英文索引见 docs/README.md。

社区

• 生态组织：dsh-tui-ecosystem —— 社区插件、模板与收录列表的家。欢迎来发插件、提创意、互相取暖 🐋
• 社区交流群：使用问题、插件创意、功能许愿，都欢迎进来聊。
• 行为准则：参与前请读一遍贡献者行为准则。

| 微信群（dsh-TUI 社区交流 4 群） | QQ 群（群号 572549239） | | :---: | :---: | | | |

微信群二维码约 7 天过期一次，如遇失效请走 QQ 群（572549239），或开个 issue 提醒我们更新。

权限与安全边界

Windows 安全警告： Windows profile 默认使用 danger-full-access，且 approval 默认是 never。这会授予工具不受限制的访问权限；在敏感凭证或不可信仓库环境中启动前，务必先检查并收紧 profile 配置。

dsh-TUI 不实现独立沙箱，而是使用当前 DSH profile 的文件、Shell、sandbox 与 approval 策略。权限预设来自 DSH permissionPresets registry：服务缺失时使用 legacy 三项兼容名册；服务已挂载但为空、损坏或不一致时标记为 unavailable，TUI fail closed，不伪造名册。可用 registry 按声明顺序提供第三方预设并自动进入补全、picker 与 Shift+Tab 循环（排除 custom/status、canonical 预设、重复 identity 与不安全 token）；首次观察遵循 registry 顺序，后续刷新保留已见 identity 的相对顺序。服务可用时 /permission 以本地命令形式常驻菜单：切换优先调用官方 /permission 命令；命令行未暴露给本 agent 时，回退到 permissionPresets 服务自身的官方写路径（与命令 handler 同一实现，写真实 permission/preset/sandbox/mode/approval/policy 事件，绝不由 TUI 伪造），并以事件/读回确认；两条路都不可用时显式提示，绝不静默。计划模式退出先恢复进入前的 atom，再把权限身份还原到你进入前所在的预设（registry 仍提供时）。在包含敏感凭证或不可信仓库的环境中启动前，请先检查 profile 配置。

详见权限边界与已知限制。

致谢

• 像素鲸鱼娘的 22 帧手绘原图（Excel 逐格绘制）与闲置动画行为（摆鱼鳍、拍尾巴、入睡冒 Z、点击冒爱心）移植自 dsh-ui-whale（DeepSeek Harness Web 端鲸鱼宠物插件，作者 @lhh010，BSD-3-Clause），感谢作者与灵感 🐋💜

友情链接

朋友们开发的社区、相关项目与周边工具

Stars

License

MIT