简体中文 | English

dsh-TUI

An interactive terminal interface plugin for DeepSeek Harness: pixel-whale header, live work status, streaming thinking display, double-Esc time rewind, context progress bar and a TPS gauge. Zero core changes, pure plugin mounting. Install to enable; uninstall leaves no core patches.

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.

🎉 Featured Officially

This plugin was featured in an article by the DeepSeek Harness official WeChat account, and is listed in the dshfind plugin directory and on GitHub Trending, where it also reached #7 on GitHub's daily trending list.

Core Features

When Windows Terminal supports Sixel, full-screen transcripts show inline thumbnails; clicking one opens a large-image preview. Non-full-screen inline mode keeps the text fallback. Sixel uses an adaptive 256-color palette; transparent pixels composite against the background. The Worker caches quantization results, encodes only the visible part on scroll, and erases old images when out of view or covered by an overlay. Attachment reading/decoding allows up to two concurrent paths; when the last user leaves, reading is cancelled and pending decodes stop. Multi-image cache, queued tasks, and single-frame transfers all have capacity limits; when exceeded, the text fallback is kept. Auto-detection prefers Kitty, then Sixel capabilities declared via DA1. DSH_TUI_IMAGE_PROTOCOL=auto|kitty|sixel|none overrides protocol selection; DSH_TUI_DISABLE_TERMINAL_IMAGES=1, accessibility mode, non-TTY output, and tmux/screen still disable graphics. Missing image dependencies or encoding failures keep the text fallback; forcing a protocol does not enable inline Sixel. Light-theme panels and image previews default to a white background; the preview border uses a neutral color. Large-image previews budget about 95% of the conversation area's width/height, with a longest side up to 2048 px, while still capping total pixel volume and background overhead; thumbnail size is unchanged. Preview supports fit-to-window, 100% original pixels, and 200%/400%/800% zoom; pan via drag, scroll wheel, or direction buttons; 100% requires the terminal to report character cell pixel size. The bottom "Open Original" link calls the system image viewer directly on the raw, un-reencoded attachment, including images restored from historical sessions. The large-image dialog uses ←/→ or bottom ‹/› to go prev/next, shows the current count, no wrap-around at the ends; switching returns to fit-to-window.

• 终端交互：低资源占用，长会话稳定可靠；多种主题切换，样式美观，实时显示工作状态、TPS、缓存命中率等 推理等级、输入/输出 token 与 Git/会话信息；终端卡多行命令可经 /settings 折叠为首行 + 计数提示（Ctrl+O 或点击卡片展开）；全屏模式下悬停在截断的工具卡标题、用户消息或会话标题上约 600ms，浮层显示完整内容。 用户附图及助手/工具结果中的持久图片块会直接显示在会话记录中；Kitty graphics 或 Sixel 可用时显示等比缩略图，否则保留同尺寸文字回退。全屏下点击输入框 [Image #N] 或 transcript 缩略图在对话区域居中打开大图预览，卡片外的对话文字变暗，不遮挡输入栏（Esc/点击外部关闭），标题为 Image #N — 格式 · 尺寸 · 体积 · 文件名，本会话暂存的图片在卡片底行显示来源路径；Finder 复制的图片文件粘贴时直接入附件库为 [Image #N]；输入框里的 [Image #N] 是一个整体，光标整体跳过、删除整体生效，光标落在其上时整块反显并自动打开预览、离开时关闭。Vim 的 x/X/d… 同样整张删除，u 同时恢复文字与附件；撤销仅限当前草稿。 终端图片预览默认开启，可在 /settings → 终端图片预览 或配置 terminalImages: false 中关闭，使用 /restart 后生效。已保存的 /settings 选择优先于 Cordis 配置；若曾保存为开启，请在 /settings 中关闭后再 /restart。关闭时保留文字信息并跳过预览解码，不影响向模型发送图片；DSH_TUI_DISABLE_TERMINAL_IMAGES=1 始终强制关闭预览。
• 功能全面：/resume 按工作目录分类浏览、搜索与预览历史会话（左键恢复、右键弹出操作菜单；可固定常用会话——「已固定」分组置顶显示，行内 ★ 或 Ctrl+P 切换，持久化到 ~/.dsh-tui），另有 /agentview 会话总览（空输入 ← 一键后台化，后台会话派发、预览、回复与停止一站式管理）、/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 只将完整读取并确认没有用户消息的日志判为空会话；仅发图片、读取不完整或解析失败的会话不会被归入空会话清理。
• 扩展丰富：原生浏览器交互，compter use等大量附属功能性扩展
• 技能归 DSH 管理：/skills 展示当前 profile、用户与项目发现的技能；dsh-TUI 不预装通用技能。 技能目录暂时不完整时，保留最后一次完整观测的技能菜单与命令注册，并按 800/1600/3200ms 最多重试三次；耗尽后等待 DSH 的 skills/change 通知或显式刷新，不持续轮询。只有完整观测才能移除已消失的技能，包括完整空目录。
• 工作状态动画：默认使用 moon8；读取旧版本地配置中的 claude 值时自动映射为 moon8，选择器只显示当前预设。
• 像素鲸鱼娘：开屏随机三选一开场动画；欢迎期（开始第一个任务前）可点击冒爱心并唤醒睡着的鲸鱼，闲置时摆鱼鳍、拍尾巴、入睡冒 Z（/settings → whaleIdle 可关）。开始第一个任务后永久定格为静态标准帧，零持续开销。鲸鱼娘的 22 帧手绘原图与闲置行为移植自 dsh-ui-whale（作者 @lhh010），特此致谢。

UI Preview

Quick Start

Prerequisites: install Nodejs and deepseek-harness, and register DEEPSEEK_API_KEY.

To install:

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

Launch command:

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

If you prefer to install manually, you can use install.sh in the repository root:

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

New user tip: If dsh plugin installation reports ERR_PNPM_IGNORED_BUILDS (pnpm ≥11 blocks dependencies with install scripts by default, such as @google/genai, protobufjs — these scripts are not needed at runtime, so it's safe to ignore them), add the following to the profile's pnpm-workspace.yaml:

allowBuilds:
  '@google/genai': false
  protobufjs: false

/update and dsh-tui update write this config automatically; no manual handling is required.

For a more beginner-friendly installation workflow, the profile overlay mechanism, source builds and FAQs, see Installation & Quick Start.

Plugin Extensions & Dev Guide

Want to build a plugin/extension for dsh-TUI? Join the ecosystem!

• Interface & compatibility agreement / plugin development guide: Terminal Interaction Ecosystem Plugin Admission & Development Guide (admission spec, seams, contracts, verification checklists)
• Ecosystem organization: dsh-tui-ecosystem (home of community plugins and templates)
• Template repository: plugin-template (start from the template; ship a plugin in 5 minutes)
• Reference implementation: dsh-working-activity (live work status line: TUI slot + activity/status session event dual outlets)

Seam Stability Reference

The following informal grading reflects current implementation maturity to help plugin authors assess the investment; the official status and compatibility agreement are defined by the Admission & Development Guide:

Grade	Seams
Stable candidate (shape frozen; if a breaking change is needed, deprecation warning in a minor version first, then removal)	Six Settings section · Eight Full-screen scenes · Ten Hosted dialogs · Eleven Status line · Twelve Keyboard shortcuts · Thirteen Entry renderers
Experimental (may still evolve with dsh-std / admission spec)	Nine Decision events · toast notifications (ctx.tuiToast, new)
Follows upstream (stability determined by cordis / dsh official mechanisms)	One Session events · Two Official prompt slots · Three Skill packaging · Four Themes · Five system prompt section · Seven Profile composition

Also: @deepseek-harness-tui/dsh-tui/api (pure type entry) is an experimental public surface. The @deepseek-harness-tui/dsh-tui/test-utils public subpath has been removed — it contained test helpers able to inject real activationIds, which is unsuitable as a public production API; for headless testing, replicate the approach of scripts/lib/plugin-test-utils.ts in the repository and run the formal admission process in your own test environment.

Import migrations:

• ctx.tuiPluginHost.grants.corrupt no longer exists. The new HostGrantFacade only exposes allows(pluginCtx, permission, scope), defaultOf, knownPermissions and onChange(pluginCtx, listener); corrupted grant files are no longer exposed to plugins via a boolean field. onChange is a subscribe-style hosted capability: the invoking activation must be passed in, it is gated by shadow, and the returned unsubscribe function is bound to that activation to avoid file polling/listener leaks. For diagnostics, use ctx.tuiPluginHost.selfCheck(), /doctor, or an explicit diagnostic query to inspect the grant file state on the host side.
• createAdmissionCatalog is no longer exported from ./plugin-host; for diagnostics, use ctx.tuiPluginHost.selfCheck() and /doctor.
• ctx.tuiPluginHost.grants is now a caller-safe HostGrantFacade: grants.allows(pluginCtx, permission, scope) derives identity on the host side from the current activation, and no longer accepts arbitrary GrantPrincipal/full GrantStore.
• GrantStore and GrantPrincipal are no longer publicly exported plugin APIs; they are retained in src/adapter/standard/grants.ts as host-internal implementation types. Hosts that need to construct/validate grant files should go through the in-repo internal path; ecosystem tests should not depend on these types from the public package.
• The @deepseek-harness-tui/dsh-tui/test-utils subpath has been removed; the in-repo scripts/lib/plugin-test-utils.ts is only used for headless verification within this repository and is not part of the public contract. Ecosystem plugins should replicate it through the formal admission process in their own test environments.

Known Platform Boundaries (Not Guaranteed Covered by Shadow Gating)

The TUI's shadow/gating only covers its own hosted seams; the following paths, owned by Cordis/upstream DSH, are hardcoded platform boundaries and are not described by the gating as full-path coverage:

• Direct ctx.get('commands').register / ctx.get('commands').execute (C-070);
• ctx.plugin() / candidate.plugin() sub-plugin installation (Cordis platform);
• agent preset registry / recompose registration (@deepseek-ai/dsh-agent-presets);
• system prompt section registration (@deepseek-ai/dsh-system-prompt);
• skill registry registration/invocation (@deepseek-ai/dsh-skill).

These paths are explicitly listed as platform-known boundary in verify-adapter-shadow. In addition, verify-adapter-shadow also explicitly records two known gating boundaries: internal TUI state/view helper classes not listed in NON_SERVICE_POLICY, and the React UI state and event handling in src/screens/ src/components — they are not adapter capability entries, and the gating does not describe them as covered.

Adapter live-probe honesty and P2 boundaries

This round advances Command / LocalStorage / MessageObserver from "staged without real probes" to "live with reversible real probes" (executed asynchronously in legacy/new modes), and implements a minimal KernelRuntime and passive/replay harness:

• Command live probe：在真实命令服务上临时注册唯一 no-op command，经 find / list 验证可见，并以内存 fake agent session 执行一次，确认 execute 返回 success；无论成功失败都在 finally 反注册。该操作不写任何 DSH 持久化 session 日志，唯一瞬时副作用是进程内命令注册表的一次 commands/change 通知。
• LocalStorage live probe：在真实 storage 目录下创建随机临时 namespace 文件，完成 write/read/delete，并在 finally 删除；不触碰任何真实插件 namespace，也不保留探针数据。
• MessageObserver live probe：通过 broker 的内部 probe-only 发布通道添加一个临时探针订阅并投递一条合成事件；真实插件的 session:* 通配订阅不会收到任何探针消息，探针结束后订阅数回到原值。这些 live probe 方法不是插件可见的公开 service 方法，宿主内核通过内部 host-only accessor 调用。
• 默认 legacy 兼容发布：DSH_TUI_ADAPTER_MODE 默认是 legacy，不会加载新 Kernel、不会执行可逆 live probe。该模式保留旧发布语义，使用独立的 buildLegacyHostDescriptor 路径：只要 Command / LocalStorage / MessageObserver 的既有服务行已挂载，describe() / hostDescriptor() 就发布这些契约供插件准入使用；构建结果会在 warnings 中明确标注为 legacy 兼容声明，与新模式 live-only 的公开 descriptor 分离。
• 模式配置 fail-closed：只有未设置 DSH_TUI_ADAPTER_MODE 时才默认 legacy；显式值只接受 legacy / passive-shadow / replay-shadow / new（忽略大小写与首尾空白），空值或未知值会报错并拒绝启动。非 legacy 模式在 Kernel 未就绪、refresh skipped/failed 或已释放时返回空契约 descriptor，不回退兼容发布。
• Host probe 访问边界：host-probe-access 内部的 token 是模块级不导出符号，普通包 exports 路径也拒绝 deep import。但插件与宿主同进程时，绝对路径加载内部文件仍无法被 exports 阻止——这是 trusted-in-process 边界，不是安全沙箱；宿主不会用“插件不可调用”这类无限定承诺。内部注册函数不会覆盖已引导的宿主 probe runner。
• Passive Shadow：不执行上述可逆 probe，只做只读 detect/descriptor 快照； Replay Shadow：生产环境不接真实 DSH，必须通过 scripts/verify-adapter-replay-harness.ts 或 src/adapter/kernel/replay.ts 在隔离 replay context 上运行，否则 fail-closed 并输出明确提示。
• Replay harness 用法：在隔离输入上运行 node --import tsx/esm scripts/verify-adapter-replay-harness.ts（门禁脚本）， 或在代码中调用 runReplayShadow({ schemaVersion: 'tui-adapter-replay/v1', ... }) 获取 { kernelContracts, legacyContracts, missing, extra, lifecycles } 对比报告。 P5 起还支持真实 DSH session snapshot/transcript 的 runChannelReplay(...) / verify:adapter-channel-conformance，走 tui.dsh/v1alpha1#Channel 的 Provider/Consumer 与协议校验。
• 公开 Host Descriptor 仍然只发布带真实 probe evidence 的 live 生命周期； 未完成 live refresh 或 passive/replay 下 Command / LocalStorage / MessageObserver 保持 staged/degraded，不伪造完整支持。DecisionEvents 维持逐 feature probe + 真实 channel/dispatch 拓扑发布规则。
• P6 已彻底移除内部 admissionCompat 平行视图，并删除 src/plugin-spec/* 与 src/dsh-adapter/{grants,host-descriptor}.ts compat shim。生产代码直接导入 src/adapter/standard/*；verify:compat-removal 现在扫描 src/、scripts/、bin/、生成 lib/（存在时）与 package export 图，verify:package 也会拒绝 npm tarball 中的旧 shim；仍保留的兼容别名 （ExtensionGrants、envelopeSchema、createAdmissionCatalog、 facadeFromLegacy 等）已明确标注为 P6 范围外/长期兼容面。
• 新 Kernel 不再是 P1 空壳：KernelRuntime 管理 driver 注册/mount、detection、 declared → staged → live、清理与诊断快照；生产 Host Descriptor、getHostFacade()、 /doctor、/plugins 均走该 runtime。
• P3 feature-level live 拆分：Workspace / Scenes / Settings / Extensions 不再用“注册+list+dispose”冒充整个能力 live。只有实际通过 只读/可逆探针验证的方法才进入 live（如 host.workspaces.list、 host.workspaces.resolve、host.scenes.register、host.settings.register、 host.status.set、host.command-trees.children 等）； host.toast.show 因尚未验证真实生产 deliver 路径，保持 degraded； rename / runCommand / commandShell / scenes.open / settings.subscribe / 快捷键 dispatch / command-tree descriptions 等未验证 方法保持 degraded/staged。Presentation 的交互 ask 已桥接到真实 QuestionStore，approve 在 P3 明确 staged。
• 生产 P3 slices 接入：非 legacy 的 TuiPluginHostRuntime 会把 ADAPTER_KERNEL_SLICES 传入生产 KernelRuntime，进入 mount/refresh/ descriptor 流程；依赖的服务未挂载时对应 slice 降级而不是崩溃。 DSH_TUI_ADAPTER_SLICES 现在会按 slice id / capability / effect 矩阵过滤 kernel slices，不再是无效果的死参数。
• 宿主初始化运行时快照：所有 adapter/宿主服务（storage/message/plugin-host、 P3 的 status/workspaces/scenes/settings/toast/dialogs/command-trees/questions/approvals 等）都会在初始化时捕获不可变 AdapterRuntimeOptions。之后同一进程再修改 DSH_TUI_ADAPTER_MODE / DSH_TUI_ADAPTER_SLICES 不能把 passive/replay 服务 解锁成 new；能力入口不再每次读 process.env。
• Slice 归属与边界：DSH_TUI_ADAPTER_SLICES 现在会大小写/空白归一化、支持 常见别名（如 dialogs → presentation、decisions → decisions），未知 slice id 直接拒绝并 fail-closed。toast 不再被 presentation 隐式加载， decisions 不再被 messages 隐式加载。
• P4 Channel Port/投影层（诚实表述）：新增 projection / actions / state / plugins / transcript 五个 Host Port 与 src/adapter/channel/* 拆分模块， 并由 channel KernelSlice 挂载到生产 HostFacade；生产 src/dsh-adapter/channel.ts 本体尚未物理拆分，仍由 live Channel 作为实现来源，拆分模块是生产 driver 实际消费的 Port/投影层；**T1 已做核心迁移：生产 plugin.ts 中的通知与初始提交 已优先走 HostFacade.channel.actions；非 shadow 模式下 facade 尚未 mount 时可回退原生 Channel，passive/replay shadow 下禁止回退，缺失或拒绝时丢弃； 其余 UI/Channel 内部动作仍大部分直接调用原生 Channel，尚未完整迁移。 HostFacade 按方法做 shadow 守卫，passive/replay 下只读投影可用、变更动作被拒。
• P5 Channel Provider/Consumer：新增本地 Channel Provider/Consumer， 实现 tui.dsh/v1alpha1#Channel 的 open/subscribe/invoke/close 协议包络与 规范校验；runChannelReplay 支持录制 snapshot 数组，也支持把真实 DSH agent.session.events 形状事件投影为单调 TuiChannelSnapshot。该投影定位为 minimal transcript replay：覆盖 transcript/status/基础 session 字段， 并在调用方提供元数据时带入 model/mode/preset/settings/scene/diagnostic/trace/ context/pending/usage 等 RFC 相关字段；仍不声明是完整 RFC 0007 Channel state/conformance。未知方法按协议失败、 features 必须显式声明且每个 feature 必须有 state/method 可观察证据、 重复 features 先拒绝、未知非 ignorable DSH event fail-closed、 method handler 只能在 replay isolation 内执行、replay provider 不解析 workspace/sessionId selector（显式 unsupported）；连续性错误 fail-closed。
• P3 feature 生命周期稳定性：refresh 之后执行 mount() / descriptorBuild() / diagnosticSnapshot() 再次触发同步 detect()，也不会清空已探测的 P3 feature； 这些 feature 是内部 Kernel/Port 事实，不进入公开 Host Descriptor。
• Settings section live 诚实性：host.settings.section 的 live 依据是探针中 真实调用 section() 解析临时 namespace；解析缺失/失败时该 feature 降级，不再 仅凭 register/list 就标 live。
• Host Port 逐方法 shadow guard：KernelRuntime.facade() 返回的每个 Port 方法都会先执行统一 effect-class 检查。passive/replay 生产模式下 rename、runCommand、commandShell、scenes.open、settings.subscribe、 各类 register 等会被拒绝；只读方法仍可用于诊断。
• Toast live probe 使用独立 probe-only sink 管道，不替换/不吞并发生产 toast；Status live probe 在 clearIf 失败或残留时降级，不会标 live。
• verify:adapter-slices / verify:adapter-detection 现在同时检查生产 plugin-host 确实传递 ADAPTER_KERNEL_SLICES，避免门禁只测直接 new KernelRuntime 的自证。

Docs Index

Topic	Content
Installation & Quick Start	Prerequisites, installation, launch, profile lifecycle, source development
Configuration Reference	Cordis overrides, config fields, Agent presets, MCP, environment variables
Theme System	Built-in themes, auto-detection, static JSON and npm plugin themes, validation rules
Interaction & Commands	Shortcuts, mouse, questionnaires, slash commands and session workflows
Architecture & Limitations	Execution chain, rendering and persistence design, security boundaries, known limitations
Community Management Framework	Community entry points, roles, proposal process, roadmap rules and maintenance cadence
Project Roadmap	Public goals, phases, task status, exit conditions and Future Work
VS Code User Guide	Run dsh-tui in the VS Code integrated terminal; the companion extension dsh-tui-vscode provides multi-session, session history and resuming a specific session (listed on the Marketplace)
Contributing & Development Conventions	Contribution process, repository map, build artifacts, verification matrix and modification rules
Plugin Admission & Development Guide	Interface & compatibility agreement / plugin admission spec / plugin seams / contracts / verification checklists (now part of dsh-ecosystem-spec)

For the full bilingual index, see docs/README.md.

Community

• Ecosystem organization: dsh-tui-ecosystem — home of community plugins, templates and the featured list. Come share plugins, pitch ideas, and support each other 🐋
• Community discussion groups: usage questions, plugin ideas, feature wishes — all welcome.
• Code of Conduct: please read the Contributor Code of Conduct before participating.

WeChat Group (dsh-TUI community chat group 4)	QQ Group (group ID 572549239)

The WeChat group QR code expires roughly every 7 days; if it's no longer valid, join via the QQ group (572549239), or open an issue to let us know so we can update it.

Permissions & Security

Windows security warning: The Windows profile defaults to danger-full-access, and approval defaults to never. This grants tools unrestricted access; before starting in environments with sensitive credentials or untrusted repositories, be sure to check and tighten the profile configuration first.

dsh-TUI does not implement an independent sandbox; it uses the current DSH profile's file, Shell, sandbox and approval policies. Permission presets come from the DSH permissionPresets registry: when the service is missing, the legacy three-item compat roster is used; when the service is mounted but empty, corrupted, or inconsistent, it is marked unavailable, the TUI fails closed, and no roster is faked. An available registry provides third-party presets in declared order and automatically enters completion, the picker, and the Shift+Tab cycle (excluding custom/status, canonical presets, duplicate identities and unsafe tokens); the first observation follows registry order, and subsequent refreshes preserve the relative order of already-seen identities. When the service is available, /permission remains in the menu as a local command: switching prefers calling the official /permission <preset> command; when the command is not exposed to this agent, it falls back to the permissionPresets service's own official write path (same implementation as the command handler, writing real permission/preset/sandbox/mode/approval/policy events, never faked by the TUI), confirmed by event/read-back; when neither path is available, it explicitly notifies rather than failing silently. Exiting plan mode first restores the atom from before entering, then reverts the permission identity to the preset you were in before entering (when the registry still provides it). Before starting in environments containing sensitive credentials or untrusted repositories, check the profile configuration first.

See Permission Boundaries & Known Limitations for details.

Credits

• The pixel whale girl's 22 hand-drawn source frames (drawn cell by cell in Excel) and idle animation behaviors (flapping fins, slapping tail, drifting off with Z's, clicking to float hearts) are ported from dsh-ui-whale (a whale pet plugin for the DeepSeek Harness web client, by @lhh010, BSD-3-Clause). Thanks to the author and the inspiration 🐋💜

Friend Links

Community, related projects, and companion tools developed by friends

Stars

License

MIT