# DeepSeek Harness TUI 用户手册

本手册面向**安装使用** `deepseek-harness-tui` 的用户，介绍如何把终端界面（TUI）安装进 DeepSeek Harness（dsh）的 profile，并以最方便的方式启动。开发者本地开发方式见文末[开发模式启动](#开发模式启动)。

## 1. 简介

`deepseek-harness-tui` 是一个运行在 dsh 进程内的终端界面插件。它通过 `ctx.agents` 创建/恢复会话，渲染持久化的 `session/event` 事件流（用户消息、流式回复、工具卡片、待办列表），并把键盘输入通过 `agent.followup()` 送回 agent；授权询问会在界面内直接回答。

它不是一个独立的 agent 运行时。模型路由、工具执行、授权、命令、会话存储和凭据仍由 dsh 负责，插件只负责终端里的输入与显示。

## 2. 安装前准备

| 项目 | 要求 |
| --- | --- |
| Node.js | >= 22 |
| dsh CLI | 已安装 `@deepseek-ai/dsh`，例如 `npm install -g @deepseek-ai/dsh` |
| pnpm | 已加入 PATH（`dsh plugin` 内部转发给 pnpm） |
| 终端 | 交互式终端（Windows Terminal / ConPTY、iTerm2、GNOME Terminal 等） |
| 模型配置 | `$DSH_HOME/settings.yaml` 与 `$DSH_HOME/.credentials.yaml` 中已配置可用的模型路由（与 Web GUI 共用） |

检查 dsh 与 pnpm 是否可用：

```sh
dsh --version
pnpm --version
```

## 3. 安装插件

### 3.1 官方安装：一条命令

```sh
dsh plugin --profile tui add deepseek-harness-tui
```

这条命令会：

1. 首次使用时初始化 `$DSH_HOME/profiles/tui`（默认组合为 `@deepseek-ai/dsh-base`）。
2. 用 pnpm 把 `deepseek-harness-tui` 安装进该 profile 的 `node_modules`。
3. 因为本包声明了 `dsh.bundle.patch`，dsh 会自动把 `deepseek-harness-tui` 追加到 profile 的 `dsh.profile.bundles`。

安装完成后无需手动编辑任何配置。

### 3.2 从本地目录或 tarball 安装

未发布到 npm 之前，可以从源码目录或打包好的 tarball 安装：

```sh
# 在包含 deepseek-harness-tui 的目录下执行
dsh plugin --profile tui add ./deepseek-harness-tui

# 或使用 pnpm pack 生成的 tarball
dsh plugin --profile tui add ./deepseek-harness-tui-0.1.0.tgz
```

`dsh plugin` 会把相对路径按你执行命令时所在的目录解析后再转发给 pnpm。

### 3.3 从 GitHub 安装

```sh
dsh plugin --profile tui add github:you/deepseek-harness-tui
```

本包是纯 JavaScript，不需要构建步骤。若未来版本增加了 `prepare` 构建脚本，pnpm >= 10 会要求先在 profile 的 `pnpm-workspace.yaml` 中允许该包执行构建（allowBuilds），然后重试。

### 3.4 验证安装

```sh
dsh --profile tui --dump-config
```

输出中应能看到 `# == deepseek-harness-tui` 这一层，其中包含 `tui-startup` 与 `tui-app` 两行。

## 4. 启动 TUI

### 4.1 标准启动

```sh
dsh --profile tui
```

启动后先进入标题界面，发送第一条消息即创建会话。常用启动参数：

```sh
dsh --profile tui --resume <sessionId>  # 恢复已保存的会话
dsh --profile tui --model <modelId>     # 新会话默认模型
dsh --profile tui --provider <route>    # 新会话默认 provider 路由
dsh --profile tui --no-sidebar          # 不显示侧边栏
dsh --profile tui --help                # 查看 TUI 自己的参数帮助
```

### 4.2 便捷启动器 dsh-tui

本包附带 `dsh-tui` 命令。它等价于 `dsh --profile tui`，但会在启动前检查 `tui` profile 是否已安装本插件；如果没有，会直接打印一次性安装命令，而不是进入一个空转的 profile。

```sh
dsh-tui                 # 启动 tui profile
dsh-tui --profile mytui # 启动名为 mytui 的 profile
dsh-tui --help          # 查看启动器帮助
dsh-tui --version       # 查看启动器版本
```

`dsh-tui` 优先使用 PATH 中的 `dsh`；找不到时回退到 `npx --yes @deepseek-ai/dsh`。要把 `dsh-tui` 安装到 PATH：

```sh
npm install -g deepseek-harness-tui
```

支持的环境变量：

| 环境变量 | 作用 |
| --- | --- |
| `DSH_TUI_PROFILE` | 未指定 `--profile` 时的默认 profile 名（默认 `tui`） |
| `DSH_TUI_SKIP_CHECK` | 设为 `1` 跳过 profile 预检（高级安装方式使用） |

### 4.3 想要输入 `dsh tui`？

dsh 启动器只把 `web` 硬编码为裸子命令别名，插件无法注册新的裸子命令。可以加一行 shell 别名实现：

```bat
:: CMD
doskey tui=dsh --profile tui $*
```

```sh
# PowerShell profile
function tui { dsh --profile tui @args }
```

## 5. 快捷键

| 按键 | 作用 |
| --- | --- |
| Enter | 发送消息 |
| Ctrl+Enter / Shift+Enter / Alt+Enter | 输入换行 |
| Ctrl+C | 清空非空输入框 / 取消进行中的轮次；空闲时连按两次退出 |
| Ctrl+P | 打开设置菜单 |
| Ctrl+E | 打开/关闭输入框下方的推理强度滑块 |
| Ctrl+N | 新建会话 |
| Ctrl+D | 在 设置 → 管理会话 中删除当前选中的会话（连按两次确认） |
| Ctrl+L | 清空当前转录视图 |
| Up / Down | 输入历史 |
| PgUp / PgDn | 滚动转录区 |
| Esc | 关闭上下文仪表盘 / 关闭强度滑块 / 关闭帮助 / 取消授权询问 |
| y / n | 回答界面内的授权询问 |

## 6. 斜杠命令

`/help` `/settings` `/new` `/resume <id>` `/model <id>` `/provider <route>` `/clear` `/cancel` `/quit`

dsh 的人类命令（如 `/compact`、`/goal`）会转发给 `ctx.commands`，不经过模型轮次执行。

## 7. 设置菜单

按 `Ctrl+P` 打开。菜单覆盖与 WebUI 相同的 Host 设置命名空间，修改通过 `ctx.settings` 持久化到 `$DSH_HOME/settings.yaml`：

- Busy Enter 行为
- 默认 agent 预设与权限预设
- 默认 provider / model / 推理强度
- 会话管理

默认 agent 预设来自 profile 挂载的 `agent-presets` 名单（内置预设 + 你在 `$DSH_HOME/.agent-presets` 下自建的预设）。TUI 会话始终从进程级 base 组合生成，因此该默认值只在按预设创建会话时生效。

WebUI 专属选项（`ui-theme` 外观、`locale` 语言）不在 TUI 中显示。Provider 凭据、API 端点和 provider 定义也不在 TUI 中编辑，请使用设置文件或 WebUI。

### 7.1 推理强度滑块

输入框右上角显示当前生效的推理强度，与 `provider · model` 标签对角。按 `Ctrl+E` 打开滑块，`←`/`→` 调整并保存，`Esc` 或 `Ctrl+E` 关闭。滑块选项来自当前模型在 provider 适配器中实际声明的等级（`ctx.llm.resolveModelInfo`），因此不同模型显示的可选等级不同（例如 DeepSeek 只显示 `Off`/`High`/`Max`）。选择结果通过 `agent/request` waterfall 应用到会话请求，并保存到 `agent-default-model.reasoningEffort`。

### 7.2 上下文仪表（Context meter）

状态栏带有一个实时的上下文占用条（例如 `ctx ▓▓░░ 32K/128K 25%`），数据来自 token-meter 的 `contextPressure` 投影，与 Web 界面输入框右侧的环形仪表同源：

- **`当前上下文长度 / 上下文长度上限`**：一旦 provider 上报了已用 token 与上下文窗口容量，就会显示（例如 `32K/128K`）。分子优先使用 `projectedTokens`（最新一次采样随会话表面变化推进），因此刚压缩过的上下文会立即反映在读数里。
- **可视化**：占用条随百分比填充，超过 90% 时转为警示色、达到 100% 时转为错误色。
- **明细面板**：鼠标点击占用条会打开一个明细面板（再次点击或按 `Esc` 关闭），显示占用百分比、`当前/上限` 读数，以及按启发式拆分的占用条与图例——系统提示词、工具、对话消息——对应 Web 界面 ContextMeter 的弹出面板。
- 当 profile 缺少 token-meter 投影（例如没有 `@deepseek-ai/dsh-base`）时，占用条自动隐藏，不影响其他功能。

## 8. 卸载

```sh
dsh plugin --profile tui remove deepseek-harness-tui
```

该命令会同时移除 profile 依赖和 bundle 层。profile 目录本身会保留；如需删除整个 profile，可直接删除 `$DSH_HOME/profiles/tui`。

## 9. 常见问题

### 9.1 `dsh --profile tui` 报 profile 不存在

说明 profile 还没创建。执行一次：

```sh
dsh plugin --profile tui add deepseek-harness-tui
```

### 9.2 `dsh plugin` 提示 `pnpm not found on PATH`

`dsh plugin` 依赖 pnpm。先安装 pnpm：

```sh
npm install -g pnpm
```

然后重试 `dsh plugin --profile tui add ...`。

### 9.3 `dsh-tui` 启动前提示 profile 未安装

这是 `dsh-tui` 的预检：它发现 `$DSH_HOME/profiles/tui` 不存在，或 profile 的 `dsh.profile.bundles` 里没有 `deepseek-harness-tui`。按提示执行：

```sh
dsh plugin --profile tui add deepseek-harness-tui
```

如果你使用的是开发模式（在 profile 的 `cordis.patch.yml` 里写绝对路径），可设置 `DSH_TUI_SKIP_CHECK=1` 跳过预检。

### 9.4 `--dump-config` 里没有 TUI 层

通常是安装命令没有成功完成，或包名拼写不一致。重新执行 `dsh plugin --profile tui add deepseek-harness-tui`，确认 `dsh.profile.bundles` 中包含 `deepseek-harness-tui`。

### 9.5 启动后立刻退出或没有界面

先确认在交互式终端中运行（不是重定向/管道环境）。TUI 需要 stdin/stdout 都是 TTY。再确认 model/provider 已在 `$DSH_HOME/settings.yaml` 中配置好，且凭据文件存在。

### 9.6 `--resume` 或 设置 → 管理会话 不可用

这两个功能需要 profile 中的共享 `sessionQuery` 服务，该服务由 `@deepseek-ai/dsh-base` 挂载。确认 profile 的 bundle 列表第一个仍是 `@deepseek-ai/dsh-base`。

### 9.7 修改插件源码不生效

profile 的热更新监视的是 profile 目录，不是插件目录。修改插件源码后重启 `dsh --profile tui` 即可。

## 10. 开发模式启动

开发本插件时，可以跳过 pnpm 安装，直接让 profile 引用源码的绝对路径：

1. 初始化基础 profile：

   ```sh
   dsh --profile tui --dump-config
   ```

2. 编辑 `$DSH_HOME/profiles/tui/cordis.patch.yml`，加入（路径换成你的实际路径）：

   ```yaml
   - insert:
       - id: tui-startup
         name: 'file:///D:/Projects/DeepSeekHarnessPlugins/deepseek-harness-tui/lib/startup.js'
       - id: tui-app
         name: 'file:///D:/Projects/DeepSeekHarnessPlugins/deepseek-harness-tui/lib/index.js'
         config:
           sidebar: true
           showReasoning: true
   ```

3. 启动：

   ```sh
   dsh --profile tui
   ```

插件对 dsh 各包的 import 会通过 `$DSH_HOME/profiles/node_modules` 共享回退解析，无需在插件目录里安装依赖。

运行测试：

```sh
node tests/smoke.test.mjs   # 不依赖 dsh 的纯模块测试
node --check lib/*.js       # 语法检查
node --check bin/*.js       # 启动器语法检查
```

## 11. 目录结构

```
lib/index.js       插件入口：agents、事件、输入、命令、授权
lib/startup.js     命令行参数提供者（tuiStartup 服务）
lib/term.js        终端引擎（raw 模式、屏幕、按键解码）
lib/ui.js          响应式视图模型 + 渲染器
lib/metrics.js     持久事件遥测统计
lib/interrupt.js   Ctrl+C 生命周期状态机
lib/web-settings.js WebUI 设置投影
lib/markdown.js    Markdown -> 带样式文本行
lib/util.js        文本/显示工具
bin/dsh-tui.js     便捷启动器
cordis.patch.yml   bundle 补丁层（TUI 行）
tests/smoke.test.mjs 独立冒烟测试
```