# dsh-tianshu-tui

> Official DeepSeek Harness interactive terminal UI plugin: streaming markdown, slash commands, conversation tabs, LSP diagnostic badges, cost tracking, and 16+

## Metadata

- Author: [@huiliyi37](https://github.com/huiliyi37)
- Repo: <https://github.com/huiliyi37/dsh-tianshu-tui.git>
- GitHub: [huiliyi37/dsh-tianshu-tui](https://github.com/huiliyi37/dsh-tianshu-tui)
- Stars: 224
- Language: TypeScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Homepage: <https://github.com/huiliyi37/dsh-tianshu-tui>
- Topics: `coding`, `dsh`, `dsh-plugin`, `harness`, `harness-engineering`, `tui`
- Forks: 8
- Open Issues: 1
- Last push: 2026-08-20T10:49:27.000Z
- Added: 2026-08-13T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:huiliyi37/dsh-tianshu-tui
```

## Wiki

## One-line Positioning
dsh-tianshu-tui is an interactive terminal UI plugin for the DeepSeek Harness official host, purely for presentation-layer rendering of session event streams. It presents the same agent/session/model service in the terminal through streaming markdown, slash commands, session tabs, LSP badges, cost tracking, and multiple themes.

## Core Capabilities
- Provides streaming markdown rendering in terminal, reasoning chain folding with in-place expansion (`Ctrl+O`), parallel tool call folding into groups, turn-end summary lines (`turn N · readX editY · duration`)
- Offers 30+ slash commands and session workflows: `/session` `/fork` `/branch` `/rewind` `/export` `/clear` `/compact` `/steer` `/model` `/effort` `/theme` `/density` `/status` `/config` `/skills` `/tasks` `/goal` `/subagents` `/workflow` `/btw` `/remember` `/memory` `/doctor` `/mcp` `/lsp` `/help` and more
- Multi-session tab bar (`Ctrl+X` cycle, `Alt+1`~`Alt+9` jump), command palette (`Ctrl+P`), keymap overlay (`Ctrl+.`), history search (`Ctrl+F`), `@`-path Tab completion, optional vim keybindings, external editor (`Ctrl+E`)
- End-to-end image support: clipboard paste (`Ctrl+V`) → terminal graphics protocol inline rendering (kitty/iTerm2) → attachment service delivery → main model vision capability declaration; when main model lacks vision, automatically converts images to descriptions via independent vision model (vision bridge)
- Real-time panels: status, config, skills, tasks, delegation tree, workflow, memory; panels fallback to ⚠ warnings when host services are missing, not silent blank
- Auto-restart on update: compares with npm `latest` on startup, auto-restarts after disk write if session is empty; 16 built-in themes + `~/.dsh-tui/themes/*.json` custom themes

## Technical Implementation
- **Language**: TypeScript
- **Key Dependencies**: chalk / diff / get-east-asian-width / string-width (all pure JS packages at runtime, no native modules)
- **Architecture Pattern**: Cordis bundle patch — `cordis.patch.yml` inserts into host with stable id `tui-runner` on top of `dsh-base`; `apply(ctx, config)` injects three required services (`sessions`/`agents`/`agentDefaultModel`) and constructs `TuiApp`, optional services (goals/subagents/memory/skills/workflow etc.) are probed via reflect.get, missing services cause panel degradation instead of blocking assembly
- **Entry File**: `src/index.ts` (also re-exports rendering core 30+ submodules: `engine/*`, `ui/app.ts`, `commands/registry.ts`, `theme-palettes.ts`, `prefs.ts`, etc.)

## Use Cases
Developers who prefer keyboard interaction with AI agents in the terminal, need streaming markdown and structured tool cards, but don't want to leave the shell; especially those using DeepSeek models for long-running tasks, needing `/rewind` rollback, `/fork` branch exploration, `/export` archive transcription, or remote operations in VPS/CI environments.

## Prerequisites & Compatibility
| Dependency | Minimum Version | Description |
|---|---|---|
| DeepSeek Harness | 0.1.0-rc.7 | Constrained by peerDependencies; plugin doesn't modify host core, only mounted as bundle patch |
| Node.js | ^22.19 \|\| >=24 | Declared by `engines.node` |
| Platform | macOS / Windows / Linux | Cross-platform; Windows from 0.1.2-rc.10 has Ctrl+C dedup and terminal recovery fallback for PowerShell/conhost |
| Native Modules | None | Runtime dependencies are all pure JS packages (chalk, diff, get-east-asian-width, string-width) |
| pnpm | Any | `dsh plugin` command forwards to pnpm; peer missing warnings on first install can be ignored |

## Installation
```bash
dsh plugin --profile web add github:huiliyi37/dsh-tianshu-tui
```

## Configuration Options
| Config | Type | Description | Default |
|---|---|---|---|
| `theme` | string | Theme name (`auto` / built-in / `custom:<name>`), priority: assembly > `~/.dsh-tui/prefs.json` > `auto` | `auto` |
| `vimEnabled` | boolean | Enable vim keybindings | `false` |
| `editorKey` | string | External editor trigger key; `ctrl+o` reserved for reasoning expansion | `ctrl_e` |
| `workflowHistoryLimit` | positive integer | `/workflow` panel settled run cache limit (drop-oldest when exceeded) | `50` |
| `lsp.enabled` | boolean | LSP diagnostics pull switch (lazy-start language service by extension when agent touches files) | `true` |
| `lsp.timeoutMs` | number | Single diagnostics pull timeout (ms) | `2000` |
| `vision.supportsVision` | boolean | Whether main control model natively supports vision (when not passed, auto-refreshed by llm catalog) | Auto-detect |
| `vision.bridgeEnabled` | boolean | Whether independent vision bridge model is configured (converts to text description via bridge when main model lacks vision) | Auto-detect by host `visionBridge` service existence |
| `autoRestartOnUpdate` | boolean | Auto-restart after startup self-update disk write | `true` |
| `prefsPath` | string or `null` | Local prefs file path; `null` explicitly disables (no read/write `~/.dsh-tui/prefs.json`) | `~/.dsh-tui/prefs.json` |
| `inputHistoryPath` | string or `null` | Input history file path; `null` explicitly disables | `~/.dsh-tui/input-history.json` |
| Env var `DEEPSEEK_API_KEY` | string | API key (welcome page/status line tiers by credentials) | Not set |
| Env var `DSH_TUI_SKIP_UPDATE` | string | `1` to skip npm update check on startup | Not set |
| Env var `EDITOR` / `VISUAL` | string | `Ctrl+E` external editor command (supports `.cmd`/`.bat` on Windows) | Not set |

## FAQ

**Q: What's the relationship between this plugin and the official web client? Will they conflict?**

A: No conflict. This plugin attaches to dsh-base as a Cordis bundle patch, sharing the same Agent, model, session, and tool services with the official dsh-web-app; under the same profile, both share true source of session/events, can be installed simultaneously.

**Q: Will uninstalling the plugin lose existing sessions? Will it modify the harness core?**

A: No. This plugin doesn't modify DeepSeek Harness core code; TUI's own preferences and input history are stored in `~/.dsh-tui/`, which can be manually deleted after uninstall.

**Q: Startup shows `ERR_FS_EISDIR` / `Path is a directory .../@deepseek-ai/dsh` - what to do?**

A: This is a conflict between old installation fallback in `~/.dsh/profiles/node_modules` and the official CLI. Reinstall with a clean `DSH_HOME` directory (see README and docs/getting-started.md).

**Q: Pasted an image but model says it can't see it?**

A: When main model lacks vision, you need to install the vision bridge plugin `dsh-vision-bridge` (provides `visionBridge` service) or explicitly inject vision config in the assembly; if neither exists, images won't be sent and a warning will display - this is intentional "fail loud" design.

**Q: Why are LSP diagnostics only shown on TUI screen, model can't see them?**

A: The LSP bridge in this plugin is a presentation-layer local bridge; diagnostics only go to tool card badges and `/lsp` panel, not registered to model tool surface; if you need model-accessible tools like `lsp_goto_definition`, install community plugin `omdsh-dev/dsh-lsp`.

**Q: How to skip npm update check on startup?**

A: Set env var `DSH_TUI_SKIP_UPDATE=1` to skip; copies installed via `github:` or `link:` won't be rewritten to npm packages.

**Q: After update, must exit and manually restart?**

A: Starting from 0.1.2-rc.10, when session is empty, auto-restart after startup self-update disk write; when session is non-empty or `autoRestartOnUpdate` is off, it only prompts, you can manually input `/restart`.

**Q: Can it run on Windows? Anything to note?**

A: Yes. Ctrl+C interrupt generates both 0x03 byte and SIGINT signal; from 0.1.2-rc.10, SIGINT dual registration and deduplication prevents "input box disappearing", with terminal recovery fallback for PowerShell/conhost console on exit.

## Learning Curve
Intermediate — terminal interaction + slash command system requires adaptation, but common operations (enter to chat, `Ctrl+C` interrupt, `Ctrl+N` new session, `Ctrl+Q` quit) are ready out of the box; to leverage deep capabilities like `/fork` `/rewind` `/lsp` `/cost`, you need to read through the interaction manual.

## Known Issues & Limitations
- Image follow-up questions need companion plugin `@deepseek-ai/dsh-vision-ask` (separate package in same repo); TUI itself doesn't have `ask_image` tool and image registry, once sent without it, images cannot be re-queried
- LSP bridge is presentation-layer local bridge: diagnostics go to screen only, not to model tool surface; server init defaults to 2s timeout then silently no diagnostics, next file touch pulls again; large repo tsserver stays resident (lazy-start mitigates, no idle GC); session switch doesn't restart server, rootUri uses first session cwd
- `app.ts` monolith is ~4032 lines, suspended state machine has been controllerized (question/approval), rendering composition and key arbitration still in app.ts, C4 split (pure function panel segments) ongoing
- Projection layer partially wired: turn-summary (`turn N · readX editY · duration` summary line) and summary-state (`/status` session summary segment) wired; activity-status/activity-store intentionally left unwired
- Vision bridge one-shot submission path: without `vision-ask` installed, same-angle repeated descriptions call vision model again, no per-image cache
- Startup auto-update requires network; in offline/restricted network, set `DSH_TUI_SKIP_UPDATE=1`, but lose "auto-restart after update" capability

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-tianshu-tui](https://deepseek-plugin.org/plugins/huiliyi37/dsh-tianshu-tui)
Wiki generated by AI (model: `MiniMax-M2.5`)