Zum Hauptinhalt springen
F

dsh-tui-pi

fan56/dsh-tui-pi

Voll ausgestattete TUI für DeepSeek Harness: Streaming-Konversation, Powerline-Statusleiste, Echtzeit-Think/Tool/Todo-Panels, Subagent-Doppelansicht, Theme-Umschaltung im laufenden Betrieb — alles als reine cordis-Plugins ohne Upstream-Patches.

Installation

dsh plugin --profile web add github:fan56/dsh-tui-pi

README

English | 简体中文

dsh-tui-pi

A fully-featured pi-style terminal UI for DeepSeek Harness (dsh) — a plugin suite that turns dsh into a pi-like coding-agent experience: /history look-back & fork-at-turn, guided preset switching, live subagent steering, model profiles, 20+ built-in themes (10 light + 10 dark) with user theme directory discovery, and a powerline footer.

Requires dsh >= 0.2.2-rc.1 — this plugin targets the dsh RC/stable line only (CI and releases resolve the newest of the latest/next dist-tags at runtime). The alpha line is no longer supported. A startup guard logs a one-line warning and exits cleanly when the host is older than the floor (opt out with DSH_TUI_SKIP_HOST_CHECK=1). See ADR 0002 for the now-superseded alpha single-target decision.

https://github.com/user-attachments/assets/67a7c6ca-ff42-4005-b543-437ba61771bb

A live recording of a session (MP4, 1.5× speed) — todos, running subagents, think/tool panels and the powerline footer in action.

✨ Features

Each item links to its own doc under docs/features/ — one line here, the details (and demo videos) there.

  • Footer — live session overview — provider/model, context pressure and the session cache-hit rate at a glance, always in view.
  • Think & tool panels — reasoning and tool activity stay out of the transcript, so the conversation reads clean.
  • Subagents — every running subagent gets a status line; watch its live transcript and decode speed (tok/s), steer it in place.
  • Tool approvals — review the operation and allow it once or deny it; no automatic approval.
  • Ask User Question — the model can pause and ask you structured questions, answered without leaving the TUI.
  • Feishu integration — dsh-tui-pi on the desktop and Feishu/Lark on the phone driving (and answering for) the same dsh session.
  • Dynamic context pruning (DCP) — context stays within limits automatically, with zero LLM calls.
  • Persistent context — your ground rules ride along on every request, hot-applied with no restart.
  • Model profiles & favorites — profile switching lives in dsh-profile-switch now; this suite keeps the TUI read side (session seeding from the pin, live-selection bridge, scope-aware /agents edits) and the /model favorites that keep the picker small.
  • Agent preset switching — /preset between the agent presets the host's 0.1.7 registry declares (standard, minimal, …); a switch is confirmed and starts a NEW session on the preset (the current one stays resumable); what a preset really gates, and how to migrate a 0.1.5 directory preset (same-id bundle patch).
  • Sessions & resume — sessions stay tidy automatically and resume in a few keystrokes; /session breaks out the session's decode speed and per-model usage; the host's kernel write lease keeps the log single-writer across processes.
  • History browser — /history opens a fixed two-pane look-back over the session: completed turns on the left, the selected turn's replies on the right; copy a prompt back to the editor, or cold-read any stored session without resuming it (read-only).
  • Themes — 20 built-in palettes (10 light + 10 dark) plus user theme discovery (~/.dsh/themes/); hot-switchable, auto follows your terminal.
  • Search, selection & images — two searches: Ctrl+Shift+F searches THIS session's transcript (pi-tui built-in) while /search (or Ctrl+Alt+F) full-text searches EVERY stored session — best-match snippet per hit, Enter opens it (↳ subagent-child hits browse read-only); drag-select copies to the OS clipboard, attachments from web/Feishu render inline, LaTeX replies draw as Unicode math.
  • Slash commands — /model, /resume, /btw, /plugins, /search, … plus everything dsh-native.
  • Plugin manager — /plugins toggles bundles on/off, uninstalls behind a confirm, installs a spec (npm name / git URL / path / tarball) after an inspect preview; every change reports applied / takes effect at the next start / failed inline.
  • Settings browser & UI languages — /settings edits everything in place (alphabetical categories, per-provider model lists, a Subagent group); /language switches the UI language from any surface.
  • Startup plugin tree — every profile plugin with its installed npm version, printed at launch.

Install and launch

npm i -g @aiwayds/dsh-tui-pi
dsh-tui-pi          # or the short form: dst

The package carries no install-time hook — the machine is set up on the first run of the launcher, which prints one progress line per step: it installs the @deepseek-ai/dsh host when missing (via npm, resolved as the newest of the latest/next dist-tags — the latest tag alone lags the rc line; if npm itself is not on PATH, it prints what to install and stops), installs pnpm, and creates the tui profile with this plugin and its bundled companions. The first run can take a few minutes — the host download is large. Host compatibility window: 0.2.2-rc.1 and newer — a host at or above the floor is kept as-is; an older one is upgraded automatically. Whatever the first run cannot finish (e.g. an offline machine) completes automatically on a later launch. After a later npm i -g upgrade of this package, the profile's mounted copy is moved to the new version on the next launch — a profile that is newer than the global install (dev-upgraded ahead) is left untouched.

The manual steps do exactly what the onboarding runs, if you prefer them:

npm i -g @deepseek-ai/dsh
npm i -g pnpm
dsh plugin --profile tui add @aiwayds/dsh-tui-pi
dsh --profile tui          # launch

Never add @deepseek-ai/* packages to a profile by hand — the host provides them, and their npm latest tag is a 0.0.1 stub (a bare-name pnpm add @deepseek-ai/dsh-llm lands that stub next to the plugin and shadows the host's copy; the symptom is the loader's does not provide an export named … and the plugin not activating). The dsh-tui-pi launcher checks for exactly this before every boot and, when it finds a shadowing copy, stops with both paths, both versions and the removal commands instead of booting into the broken state.

Legacy session_projcache records (written before dsh 0.1.2-alpha.4) are migrated automatically at profile load — idempotent, with per-file backups, never blocking startup; the dsh-tui-pi launcher runs the same preflight.

Everything that used to need manual patching — the canvas background, the @deepseek-ai module closure, the compaction backend — now happens automatically. For a normal install, upgrading the global package upgrades the profile on the next launch (see above). dev-upgrade remains for dev machines that install the profile from a checked-out repo:

node scripts/dev-upgrade.mjs                  # latest
node scripts/dev-upgrade.mjs 1.0.5 --dry-run  # preview the plan first

Uninstall

dsh plugin --profile <name> remove @aiwayds/dsh-tui-pi

The dsh-tui-pi bin shim is global and can stay; if you installed the package globally and want it gone too: npm -g rm @aiwayds/dsh-tui-pi.

The host cleans up the profile automatically: the dsh.profile.bundles entry is spliced and the whole patch layer goes away with the package — the stock session-projection-cache row re-enables, and the projcache wrapper, the tool-ask-user insert and its disable row all vanish.

User data stays on disk on purpose (deleting it is destructive; a reinstall reuses all of it): ~/.dsh/APPEND_SYSTEM.md, tui-command-usage.json, model-profiles.json, keybindings.json, ~/.dsh/agents/ + ~/.dsh/skills/, workspace .dsh-profile pins, the dsh-tui entry config in the profile patch (a pre-0.1.7 settings.yaml section lands there as settings.yaml.imported), and the session projection cache (incl. .bak-preflight-* migration backups). While the plugin runs, the retention janitor (default maxCount: 300 / maxAgeDays: 90) deletes old session logs — uninstalling stops that, but already-deleted logs are gone. scripts/install-font.mjs mutates OS font/terminal state and has a documented backup; uninstall doesn't touch it.


Companion plugins

Default dependencies — the nine plugins below ship with this package (installed into the profile's node_modules); activation still follows the profile's bundles list — list each one there to activate it.

Recommended install — @aiwayds/dsh-topics-memory, OKF topic memory for dsh (zero-LLM hot-path injection + a local git-tracked bundle; formerly dsh-llmwiki-memory):

dsh plugin --profile tui add @aiwayds/dsh-topics-memory

Optional — @aiwayds/dsh-feishu — drives the same dsh session from Feishu/Lark on your phone (demo).


Keyboard shortcuts

KeyAction
EnterSend the prompt
EscDouble-press to stop everything — the first press arms, the second opens a confirmation dialog naming what is running (main turn + subagent count); Enter there stops the main turn AND every running subagent, Esc keeps everything running. A popup open closes it instead. Works while only background subagents run.
Ctrl+CMid-task: first press stops (same everything-stop, no dialog), second quits; idle: clears editor / quits. Held-key auto-repeat never quits.
Ctrl+DQuit (only when the editor is empty)
Ctrl+LOpen the model/think picker
Ctrl+GOpen the subagent picker (viewer Enter opens steer, x ×2 stops that subagent while it runs / closes when settled)
Ctrl+OPending-message queue (s steer now · d remove)
Ctrl+Shift+FTranscript search (pi-tui built-in): Enter/Ctrl+G next match, Shift+Enter/Ctrl+Shift+G previous, Esc close
Ctrl+Alt+FCross-session full-text search — same as /search: Enter opens the hit (resume; ↳ child rows open a read-only browse), n loads more, q starts a new query, Esc close. /search works everywhere; the chord arrives as the legacy ESC+Ctrl+F encoding on most terminals
↑ / ↓Browse submitted-message history

Remap any app key through ~/.dsh/keybindings.json (a partial JSON map, live-applied) or interactively with /hotkeys.


Configuration

Everything lives in the plugin's dsh-tui entry config inside your profile's cordis.patch.yml (dsh 0.1.7 projects every volatile field of a plugin's declared Config schema into the settings surface) — but you rarely touch the file: /settings browses and edits it in place (searchable categories — Agent Presets / General / Models / Plugins / TUI — with live values, per-field descriptions, and an add-provider flow under Models). Language, theme, panel height, footer hints and icon set hot-apply on change; the rest reads at the next launch.

Most knobs have sensible defaults and need no configuration. The few you might actually set:

- id: dsh-tui         # the plugin's entry row in the profile patch
  config:
    language: zh-CN   # UI language — or just /language (asks on any surface; bundled: en, zh-CN, ja, ko)
    theme: auto       # auto / light / dark / any registered theme name — or /theme
    maxAgents: 4      # subagent concurrency, 0 = unlimited (also tunable in /agents → l)

/agents → l also mirrors the OFFICIAL dsh-subagent caps (maxActiveSubagents, default 8; maxDepth, default 1) as read-only rows — those belong to the subagent plugin entry and are edited in /settings, while the panel's own rows (maxAgents / maxRounds / maxRoundsGrace / the two fences) stay hot-editable here.

Upgrading from dsh 0.1.5? Your old ~/.dsh/settings.yaml dsh-tui: section is imported into the profile automatically on the first 0.1.7 boot (the original file is kept next to it as settings.yaml.imported).

Adding a UI language is one JSON file in ~/.dsh/locales/ — a same-id file merges per key over the bundled one, a new id registers (details: Settings browser & UI languages). The session-store janitors (retention / resume) and ask-user timeouts (askUser) live in the same entry config with documented defaults.

The plugin ships a bundled skill (dsh-tui-pi-config): ask the agent to "configure the TUI" and it collects your choices interactively and writes the section for you. The full key table and the DSH_TUI_* env var list live in skills/dsh-tui-pi-config/SKILL.md.


Development

pnpm check    # tsc --noEmit
pnpm build    # emit lib/
pnpm test     # unit tests, node --test against lib/ (pretest builds — the current baseline lives in AGENTS.md)

pi-tui runs pristine from npm — no patches, no fork. See AGENTS.md for the iron rules and quality gates.


Documentation

  • docs/features/ — one doc per feature, with demo videos.
  • ARCHITECTURE.md — full design: process model, layers, data flow.
  • CHANGELOG.md — release history.
  • AGENTS.md — working conventions and quality gates for contributors.
  • docs/ — design notes (steer/follow-up flow, showcase drafts, …).

Compatibility note

Resuming, under a dsh 0.1.6 host, a session saved under dsh 0.1.5-rc.2 whose subagent completion notices carried reasoning content fails to serialize the first model request (upstream B-21 — host-side data issue, not a plugin defect). If /resume fails this way, start a new session instead.


Credits

The Ask User Question interaction is inspired by juicesharp/rpiv-ask-user-question (adapted to this TUI's docked-panel and dsh userQuestions provider architecture; all code here is original).

Ähnliche Plugins