# seektty

> 把 DeepSeek Harness 装进终端的 TUI 前端，含流式对话、主题/语言切换、插件市场和首启 API Key 引导。

## Metadata

- Author: [@Hilbert-beinghappy](https://github.com/Hilbert-beinghappy)
- Repo: <https://github.com/Hilbert-beinghappy/seektty.git>
- GitHub: [Hilbert-beinghappy/seektty](https://github.com/Hilbert-beinghappy/seektty)
- Stars: 46
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `agentic-ai`, `ai-agent`, `cli`, `coding-agent`, `command-line`, `deepseek`, `deepseek-harness`, `developer-tools`, `dsh`, `dsh-plugin`, `linux`, `llm`, `macos`, `seektty`, `syntax-highlighting`, `terminal`, `terminal-ui`, `tui`, `typescript`, `vscode-theme`
- Forks: 2
- Open Issues: 0
- Last push: 2026-08-20T17:30:23.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

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

## Wiki

## 一句话定位
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，两端可无缝接续。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | 0.1.0-rc.6+（已测试 0.1.0-rc.8） | `package.json#dsh.compatibility` 声明；旧版 `dshCompatibilityError` 直接拒绝，新版只给一行提示不阻塞（`src/dsh-compat.ts:85-133`） |
| Node.js | ^22.19.0 \|\| >=24.0.0 | `package.json#engines.node` |
| pnpm | 10+（推荐 11.7.0） | Profile 安装走 pnpm；启动器与插件管理都依赖 `pnpm` 在 PATH（`src/bin.ts:175-184`） |
| 平台 | macOS / Linux / Windows | `package.json#os` 列出 `darwin/linux/win32`；Windows 走 `pnpm add --global`，需 PATHEXT 解析 `dsh.cmd`（README.md:68-73） |
| 原生模块 | 无 | 全 JS/TS 依赖，无 `node-gyp` 构建 |
| Peer 依赖 | `@deepseek-ai/cordis ^4.0.1` | 由宿主 DSH 提供 |

## 安装方式
```bash
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` 写入）：

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `seektty-appearance.theme` | 字符串 | 当前界面主题（dark / light / `custom:<id>`） | `dark` |
| `seektty-appearance.codeTheme` | 字符串 | 代码块独立主题（auto / dark / light / `custom:<id>`） | `auto` |
| `seektty-appearance.customThemes` | 数组 | 命名自定义主题（含界面色、语法色、TextMate rules） | `[]` |
| `seektty-behavior.toolCards` | collapsed \| expanded \| hidden | 工具卡片默认形态 | `collapsed` |
| `seektty-behavior.showReasoning` | 布尔 | 推理内容默认是否显示 | `true` |
| `seektty-behavior.desktopNotifications` | 布尔 | 回合完成或待审批时是否发终端桌面通知 | `false` |
| `seektty-behavior.composerHistoryLimit` | 数字 | 输入历史持久化条数（0 表示关闭） | `100` |
| `seektty-behavior.clipboardFallback` | auto \| osc52 \| off | OSC 52 失败后剪贴板回退方式 | `auto` |
| `seektty-behavior.toolOutputLineLimit` | 数字 | 工具输出单块行数上限（0 表示不折叠） | `200` |
| `seektty-behavior.diffContextLines` | 数字 | Diff 上下文行数 | `3` |
| `seektty-behavior.keyBindings` | 对象 | 覆盖默认快捷键（id → 组合键） | `{}` |
| `tui-plugin-marketplace.sources` | 数组 | 额外 marketplace catalog 来源（id/label/url/enabled/credentialRef） | `[]` |
| `locale.preference` | auto \| zh \| en | 界面语言；与 Harness Web 共用 | `auto` |

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

| 环境变量 | 说明 |
|---|---|
| `DSH_BIN` | 指定 dsh 可执行文件路径；设了就不自动更新 dsh（src/bin.ts:71-77 / 222） |
| `SEEKTTY_UPDATE` | `auto`（默认）/`check`/`off`/显式关闭值，控制启动时与结束后的版本检查（src/bin.ts:45-53） |
| `SEEKTTY_SPEC` | 覆盖默认插件 spec（如本地 tarball 调试时） |
| `SEEKTTY_STARTUP_TRACE` | `1` 时往 stderr 输出各启动阶段耗时（src/startup-trace.ts:7-11） |
| `NO_COLOR` | 任意非空值都强制终端走 0 色（纯文本）模式（src/client/theme.ts:179） |

## 常见问题
**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）

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [seektty](https://deepseek-plugin.org/plugins/Hilbert-beinghappy/seektty)
Wiki generated by AI (model: `MiniMax-M3`)