seektty

一句话定位

SeekTTY 是 DeepSeek Harness 的官方外置终端 Bundle，把整套 Harness 装进终端里跑——流式对话、工具卡、会话管理、插件市场和主题/语言切换全在键盘里完成，无需打开浏览器。

核心能力

• 在终端内呈现流式 Markdown 对话、工具调用卡（折叠/展开/隐藏）、代码块统一语法高亮、推理内容显隐、模型重试与 Ctrl+C 取消
• 提供完整的会话生命周期：/new /resume /rename /fork /archive /export /export md，以及 /sessions 浏览、/copy 复制上一条回答
• 支持工作区（/workspace）创建、选择、重排、注销；切换 Agent 模式（/mode）、模型与 Provider（/model）、权限（/permission）后自动开新会话
• /plugin 中心：列表、搜索、详情、安装、移除、更新、Bundle 排序、源管理、/plugin doctor 诊断；支持 npm、Git、tarball、本地路径
• 主题系统独立：界面主题与代码主题可分别切换，支持 3–16 色调色板生成、/theme import 读本地 VS Code JSON/JSONC 主题（含 TextMate token colors）
• 中英双语：/language 切换；自动跟随 LC_ALL/LC_MESSAGES/LANG/LANGUAGE（auto）；与 Harness Web 共用 locale.preference
• 首启 API Key 引导：检测到 Profile 无可用 Provider 时居中弹出掩码输入框，只走 Harness credentials.set，SeekTTY 不留日志

技术实现

• 语言: TypeScript（ESM，"type": "module"，tsdown 构建到 lib/）
• 关键依赖: @deepseek-ai/cordis、@deepseek-ai/dsh-host-apiproxy、@deepseek-ai/dsh-host-plugin-inventory、@mariozechner/pi-tui、@shikijs/core
• 架构模式: 以 Cordis Profile Bundle 形态挂载（name: 'tui-runner'，cordis.patch.yml 禁用 Web/浏览器/HMR/工具等默认行），通过 seektty/in-process 进程内 RPC 替代 Web server，再由 seektty/attachment-compat 补齐 rc.6/rc.7 → rc.8 的 imageLimits 兼容层
• 入口文件: src/index.ts → src/host/index.ts（apply/run 启动终端 Surface）→ src/client/index.ts（startTui → surface.ts）；全局命令入口 lib/bin.js（deepseek）

适用场景

开发者日常在终端写代码，希望像 Claude Code 一样随时与 AI 对话、看工具调用、可视化推理，又不想切换到浏览器；或者已经习惯 DSH Web 端、想换键盘优先的工作流。SeekTTY 与官方 Web 共享同一份 Profile 和 Session，两端可无缝接续。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Hilbert-beinghappy/seektty

安装命令为插件市场统一入口；该插件的实际 Profile 名固定为 tui（由 bin.ts 与启动器在首次运行时创建），不通过 web Profile 启动。dsh plugin --profile tui add github:Hilbert-beinghappy/seektty 是更直白的等价写法。

配置项

SeekTTY 不直接接受命令行配置，行为开关都落在 DSH Settings 命名空间（通过 /settings 或 dsh plugin --profile tui set 写入）：

常用环境变量（影响启动器与渲染，非 Settings）：

常见问题

Q: 启动器报"找不到 dsh"，怎么办？

A: 这是启动器探测 dsh --version 失败时的标准提示（src/bin.ts:175-184）。装上 pnpm add --global @deepseek-ai/dsh@0.1.0-rc.8，或者用 DSH_BIN=/path/to/dsh 显式指定路径再跑 deepseek。

Q: dsh 是 0.1.0-rc.8，但 rc.6/rc.7 的 imageLimits 跟 rc.8 不一致，会报错吗？

A: SeekTTY 在 cordis.patch.yml:153-155 顺序上把 seektty/attachment-compat 排在 api-gateway 之前；它只对 rc.6/rc.7 那个具体 capability shape 才补 maxImageDimension，原生 rc.8 对象原样保留（src/host/attachment-compat.ts:36-90）。所以跨版本运行无需手动改 dsh。

Q: 自动更新会阻塞启动吗？

A: 不会。maybeAutoUpdate 用 try/catch 静默吞掉网络与安装失败（src/bin.ts:325-348）；DSH_BIN 锁定后 dsh 也不动，SEEKTTY_UPDATE=0 可彻底关闭。

Q: 卸载会丢会话或改动 dsh 吗？

A: 不会。dsh plugin --profile tui remove seektty 只清 Profile 里的依赖、Bundle 顺序与配置项；Profile 自身保留，会话仍在 $DSH_HOME/profiles/<profile>/sessions/ 下，dsh 安装不动（README.md:167-180）。

Q: 首启居中弹窗要 API Key，会不会写进日志/截图？

A: 不会。SeekTTY 只把用户输入转发给 Harness credentials.set；自己的日志、设置、截图都不持久化这个值（README.md:97-110）。第一次正常发送时，鉴权失败会走官方 Provider error path 返回给用户。

Q: 终端粘贴图片为什么没生效？

A: macOS 走 osascript（可选 pngpaste），Linux 试 wl-paste/xclip，Windows 走 PowerShell Get-Clipboard（README.md:50）。剪贴板位图以临时 PNG 落地后插入；当前默认 v4-flash/v4-pro 不接收图片，会按附件上限做拒绝（help.ts:23-32）。

Q: /theme import 必须用 VS Code 主题吗？

A: /theme import 接受本地 VS Code JSON/JSONC 主题文件，递归解析 include，映射 editor 与 semantic token colors，TextMate 前景/背景/粗体/斜体/下划线/删除线规则可移植（README.md:223-227）。界面色不替换；字体族/字号被忽略（终端字体由网格决定）。

Q: 自动恢复上次会话怎么做？

A: deepseek --resume 恢复最近会话；deepseek --resume <sessionId> 恢复指定会话；deepseek --cwd <path> 指定工作目录。重启走 seektty-v1 通道交接 draft/attachments/cwd/profile（src/host/app-handoff.ts:1-14 / src/host/restart-handoff.ts:1-15）。

上手难度

入门 — 默认配置无需修改，安装即用；想做主题、Keymap 自定义、插件市场 catalog 扩展时再进入 Settings。

已知问题与限制

• 官方 host.describe 版本号是占位符：rc.6–rc.8 都返回 version: '0.0.1'，SeekTTY 把它当成"版本未知"忽略，不当作真实版本做兼容性判断（src/dsh-compat.ts:15-21 / 90）
• 首启 API Key 引导有边界：如果官方 Provider 适配器缺席、凭据层只读、或 Provider inspection 失败，SeekTTY 直接放弃弹窗并指向 /settings 和 /doctor，不会留下死表单（README.md:110）
• 重启交接无效时会"按普通启动继续"：handoff envelope 解析失败或 channel/profile/cwd 不一致，仅在状态栏显示一条提示，不阻塞启动（src/host/restart-handoff.ts:17-19 / 63-81）
• 依赖更新会触发重启：插件 add/remove/update/reorder 后 restartRequired 为 true，宿主走受控重启恢复 workspace/session/draft/attachments（src/host/profile-plugin-manager.ts:387 / README.md:188-189）
• pnpm 输出含 Token/Key/Secret 等环境变量会被脱敏：InstallerOutputRedactor 对跨块 secret 做了 hold + 长度边界保护（src/host/installer-output.ts:31-101）
• /clarify 仅在 Clarify Remote Receiver 存在时才出现：通过 /api 通道探测；插件缺席时不显示该命令，也不修改其它行为（src/client/clarify-remote.ts:1-15 / docs/任务书B-seektty-shell.md:7）

English | 中文

SeekTTY brings DeepSeek Harness into the terminal. Run deepseek from a project directory to work in a keyboard-first interface for prompting, code changes, tool calls, session management, model and permission switching, plugin installation, subagent coordination, and runtime diagnostics.

SeekTTY joins Harness as a Profile Bundle and uses its native Agent, Session, model, permission, Settings, Profile, plugin, and persistence services. Every terminal action uses the same Harness state, so upgrades stay focused on the compatibility baseline and adapters.

DeepSeek light and dark interfaces

Light theme

Dark theme

The live view fills the terminal and keeps the composer and status at the bottom. Unused rows remain inside the conversation viewport and disappear as output grows; longer conversations continue into native terminal scrollback.

Custom interface and code themes, including VS Code imports

Theme customization is a first-class SeekTTY feature: interface background and text colors are editable, code-block colors and syntax styles are independently editable, and /theme import accepts local VS Code JSON/JSONC themes with portable TextMate token colors. A palette of 3–16 colors can also generate a complete light or dark theme for preview and further adjustment.

TypeScript in the DeepSeek light interface

Tool parameters, file reads, and Diff in the DeepSeek dark interface

Markdown fences disappear into continuous code surfaces. Assistant code, Shell commands, structured tool parameters, file reads, JSON, and Diff use the same active code theme; ordinary conversation text keeps the interface style. Every code background occupies continuous terminal cells instead of producing disconnected per-line stripes.

Harness capabilities available in the TUI

The current release covers these capabilities:

Models, Providers, Agent Presets, permissions, Host commands, tools, Settings, Skills, MCP, and marketplace sources are discovered from the running Harness. New capabilities registered by upstream or third-party Bundles enter the dynamic catalogs, with Schema controls, structured details, and actionable diagnostics available while dedicated views evolve.

Install the bare command

The repository is public and can be installed directly from GitHub without private-repository authentication. SeekTTY supports macOS, Linux, and Windows. On Windows, install with pnpm add --global as shown below so PATHEXT-aware shims (dsh.cmd) can be resolved.

pnpm add --global github:Hilbert-beinghappy/seektty#v1.2.0
deepseek

deepseek requires DeepSeek Harness (dsh) on PATH, or DSH_BIN pointing at the executable (pnpm add --global @deepseek-ai/dsh@0.1.0-rc.8). On first run, deepseek uses the native dsh plugin command to create the default tui Profile and install this Bundle. Later runs boot the same Profile. Initial tasks, workspaces, Session resume, and custom Profiles are supported:

deepseek "check this project"
deepseek --cwd ../project
deepseek --resume
deepseek --resume <sessionId>
deepseek --profile team-tui
deepseek --version
deepseek --update

The native dsh entry remains available:

dsh plugin --profile tui add github:Hilbert-beinghappy/seektty#v1.2.0
dsh --profile tui

deepseek --update still force-scans and installs. By default deepseek itself is SEEKTTY_UPDATE=auto: on launch it fetches official dsh npm latest (not next or GitHub pre-releases) and the newest SeekTTY GitHub Release, then updates the global dsh install (skipped when DSH_BIN pins the executable) and the SeekTTY Bundle through native dsh plugin add. Local link:/file: installs and SEEKTTY_SPEC overrides are left alone. Network or install failures never block boot. Set SEEKTTY_UPDATE=check to restore a post-session notice, or SEEKTTY_UPDATE=0 to disable.

First-run API key setup

When the active Profile has no usable model Provider, and the official DeepSeek Provider exposes a missing writable credential reference, SeekTTY opens a centered write-only prompt before the first interface frame. An existing environment credential, a credential already stored by Harness, or another active Provider that uses ambient or keyless authentication skips the prompt.

Dark first-run prompt

Light first-run prompt

Paste only the API key. Input is masked, and Enter passes the normalized value directly to Harness credentials.set; SeekTTY does not read it back, write a credential file, or place it in settings, logs, screenshots, or Session data. Saving does not send a paid validation request—the first real model request reports any authentication failure through the normal Harness Provider error path.

Escape defers setup without blocking /settings, /plugin, or other local surfaces. Sending a normal prompt, a Skill command, or a prompt with attachments opens the same setup again. An initial deepseek "task", submitted text, and draft attachments remain intact; after a successful save the pending prompt continues automatically, while another deferral restores it to the composer. If Provider inspection is unavailable, the official adapter is absent, or the credential layer is read-only, SeekTTY avoids an unusable form and points to /settings and /doctor while preserving Harness behavior.

Slash commands

Typing / opens a searchable command and Skill menu. It merges SeekTTY commands, Host commands registered for the active Agent, and user-invocable Skills.

/plugin, /workspace, and /profile provide both complete interactive centers and direct subcommands. Unknown commands produce nearby suggestions instead of being sent to the model as ordinary prompts. /clarify is not a stock command: it is added to the local / catalog only while a compatible Clarify 0.2.0 six-method Remote is present. It asks context-specific questions generated from the active Session and current draft, evolves a reviewed preview after every answer, and lets you answer, refine, accept, or cancel. It never shows a permanent grey suggestion line and never auto-sends. Run it from the palette to keep the whole composer as the seed, type /clarify some text, or end an existing draft with a final /clarify token or line. Accepting writes the complete reviewed draft back into the ordinary composer; press Enter yourself only if you want to send it.

Common controls

Migrate from deepseek-tui

Replace the former global package once. The new deepseek launcher then uses native dsh plugin commands to replace the legacy Bundle identity in the target Profile with seektty:

pnpm remove --global deepseek-tui
pnpm add --global github:Hilbert-beinghappy/seektty#v1.2.0
deepseek

Custom Profiles migrate independently on first launch, for example deepseek --profile team-tui. Native dsh-only installations can migrate explicitly:

dsh plugin --profile tui remove deepseek-tui
dsh plugin --profile tui add github:Hilbert-beinghappy/seektty#v1.2.0

Plug and unplug

Removal changes only the target Profile, never the dsh installation:

dsh plugin --profile tui remove seektty

Reinstall with the same native command:

dsh plugin --profile tui add github:Hilbert-beinghappy/seektty#v1.2.0

Installation writes directly to the target Harness Profile dependencies, Bundle order, and pnpm lockfile. TUI /plugin and native dsh plugin operate on that same Profile state.

Plugin center

Bare /plugin opens the current Profile's plugin center, and /plugins is an alias. Direct subcommands include list, search, info, install, remove, update, reorder, source, and doctor.

• Search npm Registry by default, add JSON/HTTP Catalogs, and consume sources registered by other Harness Bundles.
• Install npm names, Git URLs, tarballs, file URLs, and local directories.
• Preflight dsh.bundle.patch, packed files, the final install spec, build scripts, and the target Profile.
• Restart immediately after install, removal, update, or reorder while restoring the workspace, session, draft, and attachments.
• Inspect version, source, publisher, Bundle state, load order, and actionable diagnostics.

Models, settings, and themes

/model discovers Providers, models, and reasoning efforts from Harness and immediately refreshes the effective model shown in the composer. /mode manages Agent Presets, while /permission manages the active session permission; each has a separate runtime meaning.

/settings lists every Settings namespace registered in the current Profile. Default model, default permission, default Agent mode, and marketplace sources have dedicated selectors. Boolean, enum, number, text, JSON, Secret, Credential Ref, and other fields remain editable through the generic Schema UI. It shows inherited values, user overrides, reset actions, and live/restart timing; revision checks protect concurrent writes. Secrets expose only whether a value is configured and use masked input.

SeekTTY terminal copy ships in Chinese and English. /language opens the language selector, and direct forms are available for scripts or quick switching:

/language auto
/language zh
/language en

The selection is stored by the official @deepseek-ai/dsh-client-locale Host plugin as locale.preference, so the TUI and Harness Web use the same explicit preference. auto removes that override: SeekTTY then checks LC_ALL, LC_MESSAGES, LANGUAGE, and LANG, while the browser keeps using its own platform-language fallback. Switching is live and rebuilds the terminal chrome and transcript presentation without changing model, tool, user, Provider, or plugin-authored content.

SeekTTY starts with its DeepSeek dark theme. /theme opens a complete theme center; built-in and named themes can also be managed directly:

/theme dark
/theme light
/theme code [auto|dark|light|<name>]
/theme use <name>
/theme edit [name]
/theme palette [name]
/theme import [name] [local-file]
/theme delete <name>

The interface theme and code-block theme are independent. /theme light, /theme dark, and /theme use <name> select a complete matching interface/code pair. With /theme code auto, code background, foreground, syntax colors, and dark/light direction follow the active interface theme, so DeepSeek light uses light code blocks. /theme code dark, /theme code light, or /theme code <name> explicitly overrides only code until another complete interface theme is selected. /theme edit changes a complete named theme, while /theme palette accepts 3–16 HEX/RGB color codes and builds dark and light candidates.

/theme import reads a local VS Code JSON/JSONC theme, recursively resolves relative include files, maps editor and semantic-token colors, and preserves portable TextMate foreground, background, bold, italic, underline, and strikethrough rules. An imported VS Code theme becomes the active code theme without replacing the current interface theme. Every customization path opens a live preview before saving. Low-contrast colors are never silently replaced; the preview identifies the affected roles and asks for a second confirmation.

Custom themes cover the terminal canvas, panels, selection, text, border, brand and status colors, code background and foreground, and semantic roles for comments, keywords, strings, numbers, constants, functions, types, variables, properties, parameters, operators, punctuation, tags, attributes, and regular expressions. Assistant Markdown code, Shell invocations, structured tool parameters, file reads, JSON, and Diff all use the same code theme. Tool calls render as a compact action/duration header followed by ⎿-connected invocation code; the duration advances from the Harness call timestamp while the tool is active and freezes at settlement. Collapsed cards retain the invocation while expanded cards add results. Common grammars are ready at startup; other supported grammars load on demand and redraw in place. Theme changes recolor existing messages without moving the transcript, losing expanded state, or changing the draft.

The interface selection, independent code selection, and named definitions live in the seektty-appearance Harness Settings namespace under revision protection. /settings can therefore edit the same data through its generic Schema UI. Theme names are case-insensitively unique; overwrites and deletion require confirmation. Deleting an active interface theme returns the interface to DeepSeek dark, while deleting an active code theme returns code to automatic pairing. VS Code font families and sizes are deliberately ignored because the terminal owns the character-grid font; imported bold/italic and related styles apply only to code tokens and never restyle ordinary Chinese, English, system text, or tool titles.

Verified scope

• Isolated install, configuration composition, and PTY boot against official stock @deepseek-ai/dsh@0.1.0-rc.8, plus the add/boot/remove/re-add contract against the declared minimum @deepseek-ai/dsh@0.1.0-rc.6.
• Clarify 0.2.0 retains historical standalone lifecycle evidence for official dsh rc.6/rc.7/rc.8; the complete dynamic production stack is claimed only for exact 0.1.0-rc.8 with dsh-plugin-auxiliary-runtime@0.1.0. The three packed tarballs pass native add/boot/remove/re-add, /doctor 0 errors/0 warnings, live model-generated questions/options/previews, multi-round preview evolution, review-and-accept into the composer without auto-send, interruption recovery, and privacy checks.
• Auxiliary calls persist usage/limits/cancel only in the auxiliary_runtime storage domain. Official Agent tokenUsage remains unchanged, while /status displays validated Official, Auxiliary, and derived Combined buckets only when the optional snapshot contract is healthy.
• Model listing, Provider/model/reasoning selection, request submission, and Harness error propagation.
• First-run Provider readiness, masked API-key setup, deferral and draft restoration, Harness credential persistence, and restart without another prompt under an isolated DSH_HOME.
• Real dark, light, and palette-generated PTY rendering, independent live interface/code switching, 80/120/160-column layouts, and persistence after restarting the same Profile.
• Chinese/English locale resolution, revision-protected shared preference writes, live terminal switching, and preservation of unknown external content.
• Native removal clears the dependency, Bundle, and config entries; re-add boots again.
• A fresh packed global install, with no workspace development dependencies or duplicate @deepseek-ai/* packages, exposes bare deepseek, provisions the tui Profile, and boots through the official dsh module fallback.
• A real native todo_write journey passes after installation; the package gate also rejects Profile-local copies of official identity-bearing Host packages and verifies that Cordis, API proxy, Session, and tool runtime resolve to the official fallback instance.
• Installation, startup, keyboard navigation, and terminal interaction are supported on macOS, Linux, and Windows.

A real first-run session was verified with a valid DeepSeek credential pasted into the masked overlay under an isolated DSH_HOME: v4-flash returned REALCHECK_58597, then used that answer in the next turn to return REALCHECK_58598. Restarting the same Profile did not reopen setup, the Harness credential file was mode 0600, and the credential never appeared in terminal output, screenshots, or the repository. The isolated credential store was removed after verification.

Reusable stock-dsh contract check:

DSH_BIN=/path/to/dsh \
SEEKTTY_SPEC=/path/to/seektty.tgz \
pnpm test:stock

Reusable cross-package doctor check:

CLARIFY_SPEC=/path/to/dsh-plugin-clarify.tgz \
pnpm test:clarify-doctor

Compatibility and upgrades

The tested SeekTTY baseline is official 0.1.0-rc.8; the shell's declared minimum remains official 0.1.0-rc.6, with shell lifecycle coverage on rc.6/rc.7/rc.8. The optional Clarify + Auxiliary production combination is narrower and is verified only on exact rc.8. A newer dsh than tested still boots the shell with a notice, but the auxiliary runtime rejects known versions outside its published range; older than the shell minimum is rejected. The published Bundle does not install a second copy of Cordis or any @deepseek-ai/dsh-* Host package into a Profile: optional peers describe the host contract, while runtime imports resolve through the official $DSH_HOME/profiles/node_modules fallback. This preserves identity-bearing symbols such as the native tool scheduler. Pure client helpers that the official fallback does not ship are bundled instead. The Host plugin seektty/attachment-compat still runs immediately before api-gateway and adapts only the exact valid legacy image-limit capability shape; all other shapes fail closed. Future hosts are matched by capability and unsupported optional features degrade safely. A scheduled workflow scans the official npm latest dist-tag, upgrades development baselines only after pnpm run check, packed-launcher isolation, and the stock-dsh contract pass, then opens a pull request. npm next and GitHub harness pre-releases are not followed.

The source repository and its GitHub Releases are public. No npm-registry package is published; install the tagged GitHub source above or use the tarball attached to the matching Release.