ccch1mneyyy/dsh-TUI / guide/dsh-tui-guide
dsh-tui-guide
UnverifiedUse when the user asks about dsh-tui itself (usage, shortcuts, config, themes, migration, VS Code). Load before answering; skip for normal coding tasks.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.3 KB |
| claude-backend.en.md | markdown | 14.5 KB |
| claude-backend.md | markdown | 13.2 KB |
| cli.en.md | markdown | 9.0 KB |
| cli.md | markdown | 8.4 KB |
| codex-backend.en.md | markdown | 23.3 KB |
| codex-backend.md | markdown | 20.7 KB |
| configuration.en.md | markdown | 43.0 KB |
| configuration.md | markdown | 39.4 KB |
| getting-started.en.md | markdown | 30.9 KB |
| getting-started.md | markdown | 28.9 KB |
| interaction.en.md | markdown | 75.1 KB |
| interaction.md | markdown | 68.8 KB |
| migrate.en.md | markdown | 10.5 KB |
| migrate.md | markdown | 9.5 KB |
| plugins.en.md | markdown | 16.8 KB |
| plugins.md | markdown | 14.5 KB |
| themes.en.md | markdown | 10.3 KB |
| themes.md | markdown | 10.0 KB |
| user-guide.en.md | markdown | 80.9 KB |
| user-guide.md | markdown | 75.0 KB |
| vscode.en.md | markdown | 13.8 KB |
| vscode.md | markdown | 12.6 KB |
user-guide.md
View on GitHub# dsh-TUI 使用说明
[文档索引](README.md) · [English](user-guide.en.md)
> 面向日常用户的操作手册:启动、键位、命令、会话工作流、界面指标与常用技巧。
## 目录
- [1. 快速上手](#1-快速上手)
- [2. 快捷键速查](#2-快捷键速查)
- [3. 命令全集](#3-命令全集)
- [4. 会话工作流](#4-会话工作流)
- [5. 界面与状态栏](#5-界面与状态栏)
- [6. 模型 / 预设 / 主题 / 语言](#6-模型--预设--主题--语言)
- [7. 常用技巧](#7-常用技巧)
## 1. 快速上手
### 1.1 安装与启动
```sh
# 全局安装 CLI + 本插件(插件自带 dsh-tui 直达命令)
npm install -g @deepseek-ai/dsh @deepseek-harness-tui/dsh-tui
# 启动(首次运行自动初始化 dsh-tui profile,需 pnpm)
dsh-tui
```
- `dsh-tui --resume`:恢复上次会话;Windows 可用仓库里的 `dsh-tui.cmd`(等价)。
- `dsh-tui safe`:安全模式——只读查看环境、列出 profile 插件并给出修复建议,还能创建干净的救援 profile(见 §5.5)。
- `dsh --profile dsh-tui`:与 `dsh-tui` 等价的手工启动方式(`/update` 仅此方式可用)。
- `deepseek-official` 路由需要 `DEEPSEEK_API_KEY`;DSH 0.2.0-rc.1+ 可用标准 profile 的 `deepseek-account` 浏览器授权路由。其他支持的订阅模型可用内置 OAuth 登录。环境自检用 `/doctor`。
- 主验证 dsh 引擎版本 `0.2.2-rc.5`;兼容列表以 `ADAPTER.md` 为准,列表之外的版本在 logo 页提示版本漂移与对齐命令。
- 如果 logo 页出现 ⚠ 版本漂移警告,按提示执行 `npm i -g @deepseek-ai/dsh@<版本>` 对齐 dsh 引擎。
### 1.2 首次启动你会看到
1. **首次引导**(在"还没完成过引导"时出现:首次安装,或引导本身升级过版本):四步向导 ——
**账号与模型接入 → 语言与主题 → 模型与工作区 → 快捷键与招式**。
第一步不再只做检查,而是列出**动作**:`登录订阅账号(OAuth)`(ChatGPT / Claude / Grok 等订阅,
或 DeepSeek 账号浏览器授权,按已登录/未登录标注掩码状态)、`添加模型提供方(API key)`
(与 `/provider` 同一条向导:内置目录或自定义端点)、`重新检查`、`跳过这一步`。
订阅登录之后,**新出现的模型会被接住**:没有新模型只报结果;只有一个直接设为默认;
有多个则进入内联选默认层:这些模型登录后都已可用,这里只选一个作为默认(`↑`/`↓` 移动、`Enter` 设为默认;末尾"保持当前模型"或 `Esc` 不动默认)。
已登录订阅账号或配好 key 路由时,第一步不再把缺 `DEEPSEEK_API_KEY` 报成失败——那只是 DeepSeek 官方 API 的余额检查被跳过。
添加模型提供方时,启用哪些模型、切到其中哪一个(或保持当前模型)由 `/provider` 向导自己问;回到引导只报告结果,
不再重复询问,也不改动向导里定下的默认模型。
没有可用接缝时(老宿主或裸 `cordis.yml`)给的是**真实**的手工路径:`$DSH_HOME/.credentials.yaml`
的 `refs:` 段,以及 PowerShell 用户级环境变量 / cmd `setx`——不再指向并不存在的配置文件。
`←/→` 换步骤、`Tab` 在两组面板间切、`↑/↓` 移动选择、`Enter` 执行这一步、`Esc` 跳过;
**跳过不记账**(下次启动还会问),最后一步要在**键位卡**上按 `Enter` 才算"完成"并写入记账文件
(焦点落在命令卡上时 `Enter` 是"试一下")。之后随时可用 `/setup` 重跑。
2. **落地页**(**普通启动**的第一屏:没带 `--resume`、没指定工作区、也没带首句提示词;
可在 /settings 用 `launchpad` 关掉(默认开,重启生效),`DSH_TUI_NO_LAUNCHPAD=1` 可整体跳过):像素鲸鱼顶栏(`✦ dsh-TUI` 版本号、
`DEEPSEEK / HARNESS` 大字、当前模型与 effort、工作目录,及一行**启动提示**;
这一屏的头部**直接定格**——开场动画留给进入对话后的转录区顶部),
下面是一个**真输入框**(第一句话在这里打,**回车直接发送**)与框下一行**参数行**
(模型 · 思考深度 · 模式 · 权限——四段都可点,点开对话页同款选择器就地换值;四段常在,
一行装不下时只把超长的段截尾成 `前缀…`(权限段不截断),悬停被截断的段可看**完整名**
(落地页这一屏恒启用鼠标跟踪,inline 模式下也是);其余各段压到下限后**完整权限名放不进预算**时
(终端 ≥76 列后,再宽也不改变结果;更窄的终端或更长的权限名都会更早触发)才回落到按显示顺序从尾部整段省掉),
隔一行留白再一行**快捷入口**(第七版四格:`继续「…」`(快捷键 `Alt+R`,没有可继续会话时整格不画)·
`会话与工作区`(历史会话与工作区本就是 `/home` 同一个界面,合并成一个入口)· `设置` ·
**条件位**——有后台任务在跑显 `后台任务`、检测到新版本显 `有新版本`、用量到档且没 star 过显
`投喂一颗 Star`,都不成立兜底 `帮助`)。
入口与参数段用 `↑/↓` 或 `Tab` 移焦点、`Enter` 激活,也可以直接点;终端变矮时按"整块撤"的顺序降级
(快捷入口 → 提示行 → 只留输入框),变窄时按 5.1 的阶梯降级。
从这一屏打开的整屏界面(会话与工作区 / 设置 / 后台任务 / 引导向导)都**盖在落地页之上**,
`Esc` 退出即回到落地页(草稿、参数、焦点原样保留);离开落地页进对话页有两条路:
**回车提交一条非命令消息**,或在输入框里按 `Shift+Enter`(`Option+Enter`)带着未发送的草稿
进入对话页、在光标处换行继续编辑。
dsh 引擎版本不在验证范围时会出现 **⚠ 版本漂移警告** 及对齐命令。
3. **底部状态栏**:工作状态行、上下文进度条、TPS 仪表与各类实时指标(见
[5. 界面与状态栏](#5-界面与状态栏))。
4. **启动提示行**:Logo 下方固定一行 `提示:<随机小技巧> · /tips 更多技巧`,每次启动随机换一条;
`/tips` 打开完整技巧面板(`↑/↓` 滚动、`Esc` 关闭)。
5. **第一次普通启动**(没带 `--resume`、没指定工作区、也没带首条提示词)在落地页之后进入
**会话管理界面**先挑工作区,离开后 `~/.dsh-tui/home.json` 记下"已看过",以后启动直接进对话;
界面随时可用 `/resume`、`/home`、`/agentview`、`/bg` 或输入框行首 `⌸` 打开。
6. 输入 `/` 看命令菜单,按 `?` 看快捷键帮助。
### 1.3 核心心智模型
- 命令都可用 **Tab 补全**(带参数时先输入 `/命令 ` 再 Tab)。
- 非命令输入就是普通对话;**未知命令会作为普通消息发给模型**。
## 2. 快捷键速查
> 表内 `Ctrl` 在 macOS 上大多可换 `⌘`(`⌘V` `⌘O` `⌘R` `⌘T` `⌘L` `⌘Enter`);
> `Ctrl+C`/`Ctrl+D` 不变。
> `⌘` 需扩展键盘协议(见 §5.4),Terminal.app 用 Ctrl。
### 2.1 发送与投递(模型工作时的三种语义)
| 键 | 功能 |
|---|---|
| `Enter` | 空闲=发送;**已知 `/` 命令(可带参数)=执行该命令**(回合运行中由命令自己的门禁裁决);模型工作时=steer(注入下一步边界,不中断);菜单打开=确认选中项 |
| `Tab` | 补全 `/` 命令或 `@` 文件;**模型工作时=follow-up**(排入当前回合之后) |
| `Ctrl+Enter`(⌘Enter) | 打断当前回合并立即发送输入 |
| `Shift+Enter` / `Ctrl+J` | 换行(`Option+Enter` 是 mac Terminal.app 的兜底) |
| `Alt+Up` | 把最后一条未处理消息取回输入框编辑(不中断回合) |
| `Esc`(工作 + 有 pending) | 中断回合并立即重投 pending 消息 |
| 工作中的 `/btw …` | Enter 直接执行(侧问永不打断主回合) |
回合运行中的 `/` 浮窗按「对当前对话的影响」分区:不影响的命令在上(原样式),会被门禁拦下 / 会打断或替换对话 / 会 steer 的沉到下方、整行变灰(`subtle`,不额外插标题行)。灰区不阻止使用:选中执行后该门禁的门禁、该 steer 的 steer。回合运行中只有两种输入会加塞:不构成命令的普通文本,以及**直接调用技能**的手势(`/技能名 …`,浮窗里同样按「会 steer」沉到灰区)。
### 2.2 中断 / 退出 / 系统
| 键 | 功能 |
|---|---|
| `Ctrl+C` | 工作中=中断;中断未收敛时再按=强制退出;空闲有输入=清空输入;空闲空输入=双击退出(3s 窗口) |
| `Ctrl+D` | 工作中=中断(中断未收敛时再按=强制退出);空闲时双击退出 |
| `Ctrl+L`(⌘L) | 清屏并强制重绘 |
| `Ctrl+O`(⌘O) | 展开/收起详情(思考全文、工具参数与输出) |
| `Ctrl+E` | 输入框=光标到行尾;转录中=展开/折叠隐藏的旧消息 |
| `Ctrl+P` | 切换启动时 loaded-context 面板(面板在屏时有效) |
| `?` | 输入框为空时打开快捷键/命令帮助菜单 |
### 2.3 搜索
| 键 | 功能 |
|---|---|
| `Ctrl+R`(⌘R) | 历史消息搜索(只搜当前项目);重复按或 `↓` 到下一匹配;`Enter` 回填输入框 |
| `/`(转录态) | 会话全文搜索;`n` / `N` 跳转(仅 Ctrl+O 展开态) |
### 2.4 输入编辑
| 键 | 功能 |
|---|---|
| `←` / `→` | 按字符移动光标(有选区时坍缩到选区对应边缘) |
| `Ctrl+←` / `Ctrl+→`(⌘←/→) / `Alt/Option+←/→` | 按空白分隔的单词跳转;启动页也支持 |
| `Home` / `End`,`Ctrl+E` | 逻辑行首 / 行尾(`Ctrl+A` 已改用于子代理面板,见 §2.7) |
| `Ctrl+U` / `Ctrl+K` | 删除光标前(至行首)/ 光标后(至行尾) |
| `Ctrl+W` / `Alt/Option+Backspace` | 删除前一个单词;已暂存的图片附件整体删除 |
| `Ctrl+Z` | 撤销草稿上一步「词级」编辑(含光标与图片);只作用于草稿,提交或用历史召回(`Ctrl+R`/`↑`)后不再可撤销,与 `Esc Esc` 的会话/消息回溯无关;可经 `/settings` 重映射 |
| `Backspace` / `Delete` | 删前一 / 后一字符;**有选区时删除整个选区** |
| `↑` / `↓` | 多行时行间移动;单行时浏览输入历史(按项目隔离,每个项目最近 200 条,跨重启保留;升级前的旧历史各项目都可见) |
| `Ctrl+V`(⌘V)/ `Alt+V` | 粘贴:文本 / 文件路径(图片自动 `@` 引用)/ 剪贴板位图(`[Image #N]` 附件);终端拦截 `Ctrl+V` 时用 `Alt+V` |
| `Ctrl+G` | 用 `$VISUAL`/`$EDITOR` 外部编辑器编辑输入(`:cq` 保留原稿;未设置变量时提示配置) |
| `Ctrl+Shift+E`(⌘⇧E) | 展开**全屏草稿编辑器**(也可点输入行尾 `⛶`):带行号、高亮当前行,`Enter` 换行、`Ctrl+Enter` 发送、`Esc` 收起(草稿还在);`/settings → 全屏草稿编辑` 可关 |
| 超长草稿自动折叠 | 粘贴 **≥6 行或 ≥600 字**的块折成 `▸ N 行・M 字` 小条:点小条或 `▾` 切换折叠;`Enter` 提交的始终是全文 |
| `/vim` | **vim 编辑模式开关**(会话级、不持久化):开启后输入框显示 `INSERT` 徽标,`Esc` 切 `NORMAL`,`i/I/a/A/o/O` 回 INSERT。NORMAL 键位见下 |
| 打字 | **有选区时替换整个选区**(和标准编辑器一致),光标落在插入文本之后 |
| 右键 / `Ctrl+Shift+V` | 终端原生粘贴(含换行原样插入) |
| `Esc`(输入框) | 一层层关:帮助 → **图片预览** → 命令菜单 → 文件菜单(只关当前 `@` token)→ 退出排队选择器 → **有选区就先清选区(文字不动)** → 收起草稿编辑器 → 展开粘贴折叠块 → 移除上下文附件 → 中断并暂存队列(普通草稿保留、不重投)→ 空闲有输入清空 → 空闲空输入双击=时间回溯 |
| 双击 `Esc`(空闲空输入) | **时间回溯 rewind**(3s 窗口内按两次) |
**vim NORMAL 键位**:移动 `h/l` `j/k` `0/^/$` `w/b`;
删除 `x/X` `dd`/`d$`/`d0`/`d^`/`dw`;`u` 撤销、`Enter` 发送。
未识别键忽略,`Esc` 无操作,清空用 `Ctrl+C`/`dd`。
### 2.5 导航 / 模式
| 键 | 功能 |
|---|---|
| `Shift+Tab` | 循环会话模式(默认 → plan 计划 → full 完全访问);挂载了第三方权限预设时,它们按 registry 顺序排在循环末尾 |
| `Shift+↑` | 消息选择模式(`↑/↓` 移动,`Enter` 展开单条,`Esc` 退出) |
| `Ctrl+T`(⌘T) | 打开轨迹场景(同 `/trace`) |
| `Alt+R` | 落地页上**继续最近一条会话**(同入口行的「继续「…」」;仅启动页生效,无可继续会话时无动作)。键位可在 `/settings` 改 |
| `Alt+S` | 一键 star(同 `/star`;开屏那句求 star 标语整行也可点)。键位可在 `/settings` 改;成功后会演一小段「鲸鱼娘接住星星」的庆祝。想随时看这段庆祝:`DSH_TUI_STAR_MODAL=1 dsh-tui`;想随时看开屏那句求 star 标语:`DSH_TUI_STAR_LINE=1 dsh-tui`(都是预览用环境变量,不动账本) |
### 2.6 鼠标(fullscreen 全屏模式;拖拽/双击/三击即选即复制)
| 操作 | 功能 |
|---|---|
| 左键拖拽 | 选文本,**松开即复制**(OSC 52 + 系统剪贴板工具兜底),复制后保留选区;重新拖选会替换现有选区 |
| 双击 / 三击 | 选词 / 选行,即选即复制 |
| 滚轮 | 滚动消息列表(±3 行/格);**有文本选区时随内容平移选区** |
| 输入框内 | 拖拽 / Shift+click / 双击建立选区;`Backspace`/`Delete` 删选区、打字替换、`←/→` 坍缩、`Esc` 仅清选区、`Ctrl+C` 复制选区 |
| `Esc` | 取消选区(不复制) |
| 单击 | 消息行=展开/收起 · 超链接=打开浏览器 · 「加载更早消息」/StickyHeader/「↓ N new」=加载/跳转 |
| 悬停截断内容 | 停留约 600ms 浮层显示完整内容;拖选文本期间浮层不出现 |
| 键盘扩展选区 | 有选区时 `Shift+←/→/↑/↓/Home/End` 扩展/收缩(跨行环绕) |
### 2.7 各场景键位
**问卷(模型 ask_user_question)**
- `↑/↓` 选、`Space` 多选、`Tab` 切自定义回答、`Enter` 提交;`←/→` 换题(不提交,草稿保留);`Ctrl+V` 粘贴、`Ctrl+K` 折叠。
- 问题正文与说明可用 `Alt+Up` / `Alt+Down` 翻阅(可在 `/settings` 改键);全屏也可在正文区域使用滚轮。选项和回答焦点保持原位,OAuth 授权链接不会因预览上限而丢失尾部。
- `Esc` 第 2 题起返回、第 1 题取消整批;`Ctrl+C` 任意题取消。输入行里 `←/→` 先移动光标,到行首/行尾才换题。
**计划评审(plan review)**
- `↑/↓` 移动、`1`/`2` 快选;直接打字 = 填反馈(`Ctrl+V` 粘贴、`Enter` 提交);`Esc` 打断;**批准必须不带反馈**。
**工具审批(approval)**
- `↑/↓` 移动、`1` 允许(仅本次)、`2` 拒绝、`Enter` 提交;`Esc`/`Ctrl+C` 拒绝。
- 极矮终端采用紧凑布局,保留决策行和状态栏;`Alt+Up` / `Alt+Down` 翻阅完整预览,标题、命令和理由仍可读取。
**会话管理界面**(`/resume`、`/home`、`/agentview`、`/bg`、输入框行首 `⌸`,同一个界面)
- 布局:左栏工作区、右栏会话;≥84 列两栏并排,更窄收起工作区栏。
- 换栏 `←/→`;移动 `↑/↓`/`PgUp`/`PgDn`;**直接打字 = 实时筛选**(按标题/目录/分支/模型)。
- 进入 `Enter`(第 0 行 = 在该工作区新建会话);新建 `Ctrl+Enter`/`Ctrl+N`;停止后台会话 `Ctrl+X`。
- `Ctrl+L` 重读 · 工作区栏 `Enter` 打开操作菜单 · `Esc` 关提示→清空筛选→离开。
- 来源标签:本机的 Claude Code / Codex / Grok Build / zcode 有会话时,标题栏右侧出现对应标签,`Tab`/`Shift+Tab` 或点击切换;
外部标签里 `Enter`/单击 = 只导入这一条并直接打开(导入过的直接打开),工作目录已不存在时只提示不导入,`Ctrl+L` 重扫该来源。
- 鼠标:点击会话行=进入、点 `★`/`☆` 切固定、右键工作区行出菜单。
- 输入框空着按 `←`(或 `/bg`)= 转后台并打开本界面,会话继续跑。
切换会话只是**停放**——正在跑的回合继续跑;被其他终端占用的会话标红写 `占用 pid <pid>`、点不动,对方退出后恢复。
固定项存到 `~/.dsh-tui/session-pins.json`。
工作区菜单四项:编辑 / 在此新建 / 重命名 / 从列表移除(**只删登记**,目录与会话日志都保留)。
移除后,仍有历史会话的目录会以「仅历史」行留在侧栏;栏头分别统计已登记工作区与历史目录,移除成功也会显示提示。
「仅历史」行的菜单只有编辑与在此新建;重命名、移除只适用于已登记工作区。
**大图预览**(点输入框里的 `[Image #N]` 或转录缩略图打开)
- `←/→` 上/下一张;底部按钮缩放:`适应`/`100%`/`200%`/`400%`/`800%`;拖动、滚轮平移。
- `Esc`/`Ctrl+C`/`Enter` 或点卡片外关闭;底部「打开原图」用系统看图程序打开。
**IDE 选区**(VS Code companion 扩展 `dsh-tui-vscode`,需 ≥ 0.7.0)
- 编辑器选中代码 → 输入框下方**实时**出现 `⧉ N lines selected` 徽标,提交时选中行**自动附加**进上下文。
- 转录里有「⧉ Selected N lines from <相对路径>」指示行(附加编辑器里的文本,未保存也带上)。
- 没装/没连 IDE 时自动跳过、不影响其他功能(详见 [vscode.md](vscode.md))。
**历史搜索(Ctrl+R)**
只列出当前项目(会话工作目录)的输入,外加升级前未分项目的旧历史。
`↑/↓` 选择 · 重复 `Ctrl+R` 或 `↓` 下一项 · `Enter` 回填 · `Esc`/`Ctrl+C`/`Ctrl+D` 取消
**轨迹场景(Ctrl+T / /trace)**
- `↑/↓`/`PgUp`/`PgDn` 移动 · `←/→`(或 `h`)切换时间线/热点 · `g`/`G` 顶/底 · `q`/`Esc` 退出
- `[`/`]` 跳失败点 · `{`/`}` 跳轮次 · `m` 循环投影 · `Enter` 展开详情(`j`/`k` 翻页)· 热点 `t` 排序
- `/` 查询行(前缀 `tool:` `kind:` `turn:` `err:` `run:` `>10s` `tok>1k`)
**/settings 设置面板**
`↑/↓` 移动 · `Enter` 展开/切换/编辑 · `←/→` 在**有选项的字段**上循环切换(布尔项仍只响应 `Enter`)·
`Tab` / `Shift+Tab` 或点击页签(全屏模式)切换**页**(「常规」+ 插件声明的页;只有一页时不显示页签)·
改动自动保存,`Esc` 退出
**/btw 侧问面板**
`↑/↓` 滚动 · `Space`/`Enter`/`Esc` 关闭 · `c` 复制答案 · 等待中 `Esc` 取消
**/effort 滑杆**
`←/→` 实时调整(Esc 不还原)· `Enter`/`Esc` 完成
**@ 文件补全**
`@` 在消息任意位置触发 · `↑/↓` 移动 · `Tab`/`Enter` 接受 · 目录可继续深入 ·
`Esc` 只关当前 token 菜单
- **两种查询**:路径形输入(`@src/` `@./` `@~/` `@D:\`)只列该目录;
普通片段**模糊匹配**(`@ink` 命中 `src/ink/Box.js`)。
- 图片路径自动变 `[Image #N]` 附件。
**子代理面板(Ctrl+A)**
`↑/↓` 浏览 · `Enter` 查看详情 · `Esc` 关闭;详情页 `←/→` 翻页,运行中 `X` 中断;子代理以卡片行实时展示。面板镜像本会话派出的全部子代理——`subagent`/`send_message` 运行、可续子代理的重派(每轮新任务重置该行)、workflow/ralph 成员——并在恢复会话时从日志重新折叠持久发现事实,重启不再清空面板。无实时计时的历史行以 `⚪` 状态展示,不伪造时长。
**双击 Esc 时间回溯(rewind)**
列表 `↑/↓` + `Enter` 进入确认 · 确认页 `Enter` 回退 / `Esc` 返回 · 插件决策等待中只响应 `Esc`
### 2.8 侧栏(Side panel)
`Ctrl+B`(可在 `/settings` → `Shortcuts` 重映射)在聊天右侧展开一条侧栏:顶部胶囊标签栏、
中间活动面板、底部按键提示行,与聊天之间隔一列中缝。
- **三种形态**:**分栏**(split,聊天约 68% + 侧栏,`+`/`-` 每次调 4 列)、**收起**(collapsed,
布局与以前逐字节相同)、**缩放**(zoom,面板占满,聊天列保留最小宽度)。
- **分栏条件**:fullscreen 且内容区 ≥93 列(默认页边距下约合终端 97 列);窄屏、inline 模式、
展开全屏草稿编辑器时自动回退——`/jobs` 等命令仍走整屏面板,`Ctrl+B` 与 `/panel` 则不分栏。
- **焦点模型**:同一时刻只有一处键盘焦点,焦点在右栏时面板边框与中缝一起提亮。`Ctrl+B` 三态:
未开 → 打开并聚焦右栏;已开但焦点在聊天 → 聚焦右栏;焦点已在右栏 → 关闭并回聊天。
- **右栏按键**:`Esc` 一步回到输入框(不关面板)· `←`/`→` 或 `[`/`]` 切换面板 · `1`-`9` 直达第 N 个 ·
`z` 或 `Alt+Z` 缩放 · `+`/`-` 调宽(`+` 加宽面板,步长 4 列) · `↑`/`↓`/`PgUp`/`PgDn` 交给活动面板(jobs 用它选择与滚动,todo 用 `↑`/`↓` 逐行滚动长目标);
面板没吃下的键不会再落到聊天,但 `Ctrl+C`/`Ctrl+D`/`Ctrl+L` 等 Ctrl 组合照旧作用于聊天。
- **鼠标**:点聊天栏把焦点给聊天,点右栏把焦点给面板;点标签栏上的标签直接切到那个面板(悬停会高亮),
点右端的 `⤢` 把当前面板放大成整屏。悬停中缝会提亮,按住鼠标左键左右拖拽即可实时调宽:
向左加宽侧栏、向右缩窄,聊天列至少 64 列、侧栏至少 28 列;拖拽会退出 zoom,保留键盘焦点,
宽度在当前会话内保留。聊天内起拖只选聊天文字,右栏内起拖可选右栏文字。
- **面板**:默认(`sidePanel.panels: '*'`)启用全部面板——8 个内置面板加上之后注册的插件面板;可在 `sidePanel.panels` 或 `/settings` 勾选里改成显式列表。`todo`(Goals/Todos,分栏时从输入框上方迁到这里;长目标按面板宽度换行、状态独立一行,内容超出时聚焦面板用 `↑`/`↓` 或滚轮滚动,目标全文与全部待办都能滚到)、`jobs`(后台任务,点转录里的任务卡
会直接定位到该任务)、`agents`(子代理 Dashboard 与详情:Enter 进详情、Esc 逐级返回)、`companion`
(宠物:跟随会话状态换心情动画,点击
比爱心、Enter 戳一戳;皮肤 `dsh-tui.companion.skin` 可选 deepy(默认,非官方粉丝作品 deepy
小鲸鱼)或 whale)、`info`(信息栏:模型 / 思考深度 / 工作模式 / 权限 / 上下文占用 / 缓存命中 /
Token / TPS / 消耗 / 工作目录 / 会话标题与 ID)、`trajectory`(会话轨迹:唤醒带 + 账本 + 检视器,
↑/↓ 选择、Enter 展开、Tab 切热点视图;←/→ 恒归侧栏切面板,Tab 才是切视图)、`workspace`
(工作目录/工作区总览,Enter 打开整屏工作区主页)、`btw`(追问线程,可从 `/btw` 进入)。
- **宠物(companion)细节**:宠物锚在面板**底部**,上方是状态区(心情 · 子代理/会话计数 · 当前动作)。
互动:点它左半/右半会被戳(poke-left/right)、短窗口连点三次是挠痒(tickle)、**按住拖动它就跟着
指针在整个面板里走(松手弹回底部)**、鼠标悬停它会看向指针;Enter 也算戳一戳。后台任务完成、已打断
这类提示会由它头顶的对话气泡说出——此时输入框上方**不再重复弹**同一条(宠物面板不是活动面板时
toast 照旧;错误类通知永远走 toast)。情绪带防抖平滑:快速的工具调用不会让动画来回闪烁(离开工作
状态约 1.5s 才切换;审批/出错仍立即抢占)。子代理/会话数会切换配乐/指挥/施工等群像动画。面板窄到
连紧凑形态都放不下时它会「躲起来」,只留一行 `好挤呀!{{name}}暂时躲起来了~`。
皮肤 `dsh-tui.companion.skin` 三选一:`deepy`(默认,非官方粉丝作品小鲸鱼)、`whaleGirl`(鲸娘
表情包,22 个动画,被戳/被挠/被拎起来都有对应反应,独有「冒爱心」「举大拇指」)、`whale`(开屏
同款像素鲸)。**鲸娘在有图像协议(kitty/sixel)的终端里按原帧数 240px 像素级渲染**(267 帧全保留、
透明悬浮、按需解码),无图像协议自动回退字符画版。
开屏仅在 DeepSeek 品牌下使用这些皮肤:`deepy` 和 `whaleGirl` 会取代女仆娘立绘;选择 `whale` 并开启「女仆娘立绘」才会显示女仆娘。Claude 使用自己的图案,Codex 使用自己的真图或女仆娘字符画回退;这两个品牌的开屏图案不受宠物皮肤和女仆娘开关影响。见[优先级表](configuration.md)。
| 子命令 | 作用 |
|---|---|
| `/panel` | 打开面板选择器(↑↓ 选择、Enter 打开并聚焦) |
| `/panel toggle` | 真开 / 真关(关闭时焦点回聊天) |
| `/panel focus` | 打开并聚焦右栏 |
| `/panel zoom` | 打开并缩放当前面板 |
| `/panel <id>` | 打开指定面板:`todo` / `info` / `trajectory` / `jobs` / `agents` / `workspace` / `btw` / `companion`(补全列出已启用的 id) |
- 原本只能整屏的视图现在也能进侧栏:分屏开着且对应面板已启用时,`Ctrl+T` / `/trace` 打开轨迹面板、
`/home` 打开工作区面板;面板栏右端的 `⤢` 再把它们放回整屏(`⤢` 是鼠标入口,键盘等价物就是各自的
整屏快捷键:`Ctrl+T` 轨迹、`Ctrl+A` 子代理、`/jobs` 任务、`/home` 工作区主页)。
- 临时插件面板显示可读标题与本次运行的独立编号,勾选只改变当前界面,不保存为偏好。请移除旧 `actN:panel` 占位项并重新选择当前面板。
- 设置:`/settings` → `侧栏` 分组,或 `dsh-tui.sidePanel.{splitEnabled,open,ratio,panels}`
(见[配置参考](configuration.md#tui-配置))。
- **tmux 用户注意**:`Ctrl+B` 是 tmux 的默认前缀键,会被 tmux 截走、送不到 TUI——到
`/settings` → `Shortcuts` 把 `sidePanel` 换成别的组合(例如 `alt+b`)。
## 3. 命令全集
命令菜单 = 内置命令(含别名) + DSH 注册表命令(`/plan` `/goal` 等) + 技能目录
(仅补全,`/help` 菜单隐藏)。`/lang` 可切换中英文界面与命令描述。
### 3.1 会话
| 命令 | 参数 | 作用 |
|---|---|---|
| `/new` | 无 | 新开会话(无二次确认;旧会话可 `/resume` 恢复) |
| `/resume` | 无 | 打开**会话管理界面**(工作区栏 + 会话栏、实时筛选、固定常用、跨工作区):切换会话只是**停放**,旧会话转后台继续跑,正在跑的回合不中断(与 `/tree` 同类:浏览与切换都不打断当前回合;仅 Claude 后端例外,回合运行中切换会被拒绝) |
| `/home` / `/agentview` / `/bg` | 无 | 同一个会话管理界面(`/home`=工作区视角 · `/agentview`=托管会话状态 · `/bg`=转后台并打开,别名 `/background`) |
| `/tree` | 无 | 会话分叉树:悬停预览、点击回退 / 分叉 / 切换分支 |
| `/fork` | 无 | 把当前会话复制成可恢复的副本(原会话不受影响);DSH 有历史的副本记录来源,归入同一会话家族 |
| `/restart` | 无 | 重启进程并恢复本会话。回合运行中也可用:会中断该回合,排队输入(连同附带的图片)在重启后以暂存消息保留(在暂存区按 ⏎ 才发送);若工具不响应中断、进程无法正常收尾,约 5 秒后退出并打印恢复本会话的命令 |
| `/kernel` | 无 | 内核选择器:在 DSH、Codex 与实验性的 Claude 后端之间切换,记住选择并重启进入新会话(回合运行中会被拒绝);见 [Claude 后端](claude-backend.md) |
| `/dsh` / `/codex` / `/claude` | 无 | 直接选择对应内核,检查与重启流程同 `/kernel`;选择当前内核不重启,回合运行中不能切换,未安装 Claude 时进入安装向导 |
| `/rename` | `<新名称>` | 重命名当前会话(无参时显示当前标题与用法) |
| `/recap` | 无 | 最近活动摘要(一行)+ 建议标题;面板内 `a` 键或点击一键应用标题。设置 `dsh-tui.recapOnOpen`(默认开)开启时,打开/恢复会话自动在底部显示一条分隔线 + `回顾:` 摘要行,悬停可查看操作、点击展开,发送新消息后自动消失 |
| `/workspace` | `resume` / `rename <名称>` / `open <路径或URI>` | 管理工作区;`open` 支持绝对路径、file URI、插件 scheme |
| `/clear` | 无 | 清空当前会话视图(重置展开/选择状态) |
| `/compact` | 无 | 压缩会话历史(无可压缩内容时会提示) |
| `/export` | 无 | 导出会话为 Markdown 到会话启动时的项目目录(不跟随 Agent 的 `working_directory` cd) |
| `/btw` | `<问题>` | 侧问:单轮、无工具、不打断主回合、不写历史 |
| `/trace` | 无 | 打开轨迹场景(同 `Ctrl+T`) |
| `/rewind` | 无 | 回退选择器(同空输入双击 Esc 的时间回溯);**回合运行中会先取消当前回合**再回溯 |
| `/exit`(别名 `/quit` `/q`) | 无 | 退出 dsh-tui |
### 3.2 状态与诊断
| 命令 | 参数 | 作用 |
|---|---|---|
| `/context` | 无 | 已加载上下文明细(指令/运行时上下文/技能/工具等) |
| `/status` | 无 | 模型+effort、工作/空闲、会话 id、目录+git 分支、token、缓存命中率、上下文百分比、会话标题 |
| `/cost` | 无 | token 用量 + 缓存命中率 + 本会话估算(并入子代理)与「主会话/子代理」拆解;非官方/未收录模型只显示 token 并标注未计价(**估算是参考,以平台账单为准**) |
| `/balance` | 无 | DeepSeek 官方账户余额(免费只读接口):摘要行 + hover 明细(同款本会话估算拆解:主会话/子代理/未计价),点击刷新、`×` 关闭 |
| `/config` | 无 | 配置来源:`cordis.patch.yml` 路径、启动方式、模型路由 |
| `/doctor` | 无 | 环境自检 |
| `/migrate` | `[agent] [--dry-run]` | 从其他编程代理(claude-code/codex/omp/zcode/grok-build)导入对话历史,子进程运行不卡界面,详见[会话迁移](migrate.md) |
| `/init` | 无 | 在工作目录创建 `AGENTS.md`(created / exists / failed 三态提示) |
| `/agents` | 无 | 本会话子代理列表 |
| `/team` | `status`(默认)\| `on` \| `off [force]` | Agent Teams:`/team`(或 `/team status`)报告会话级选择、服务与本会话子代理;`/team on` / `/team off` 写入本会话(根会话及其整棵子代理树)的团队选择,跨重启保持。关闭不停止子代理也不删任务;仍有子代理在运行时 `off` 会先提示,确认用 `/team off force`。旧宿主(0.2.2-rc.1 及更早)上开关仍是 `/plugin enable\|disable @deepseek-ai/dsh-experimental-agent-team-profile`,`/team` 只报告并给出迁移提示 |
| `/jobs` | 无 | 后台任务面板:状态/运行时长/退出码实时跟踪,`↑/↓` 选择、`k` 停止;面板打开时 `Esc` **只关面板**不打断回合(想中断先关面板再 `Ctrl+C`) |
| `/settings` | 无 | 打开插件设置编辑器(命名空间读取/编辑) |
| `/setup` | 无 | 重跑首次引导向导(账号与模型接入 / 语言主题 / 模型工作区 / 快捷键),与首次启动是同一个界面 |
| `/help` | 无 | 快捷键 + 命令帮助菜单(`?` 入口) |
### 3.3 模型 / 显示
| 命令 | 参数 | 作用 |
|---|---|---|
| `/channel` | 无 | 中转渠道档案(仅 Claude 后端);**回合运行中导入 / 新建 / 管理,以及需要重启进程的切换会被拒绝**(选择器本身仍可打开),见 [交互与命令](interaction.md#渠道档案channel仅-claude) |
| `/model` | 无 | 模型选择器;**同会话切换模型**(保留 session ID、历史和标题,下一次请求使用新路由),选择持久化到 `~/.dsh-tui/model.json` |
| `/effort` | `status` / `<id>` | 推理强度:无参滑杆(`←/→` 实时调整);`status` 当前档位;`<id>` 直接设定。持久化 `~/.dsh-tui/effort.json`;新会话起始档看 /settings 的 `effortDefault`(§5.3) |
| `/thinking` | 无 | 扩展思考显示开关(流式时思考逐条展开) |
| `/tokens` | 无 | 分三段报数,不再并列两个不同量:**本次请求**上传量(input + 缓存读 + 缓存写,harness 的四个桶互斥)、**会话累计**(未缓存输入 / 输出 / 缓存读 / 缓存写)、**上下文占用** |
| `/activity` | `frames <名>` / `status` | 工作状态行动画:无参选择器浏览,`frames <名>` 直接设置(含 `random`),默认 `moon8`。持久化 `~/.dsh-tui/working-activity.json` |
| `/preset` | `<id>` / `status` | Agent 预设切换:`standard` / `ptc`(旧 0.1.1 名 `code`)/ `minimal` / `cordis` / **梁神模式 `liangshen`**;**已开始的会话不可切换**。持久化 `~/.dsh-tui/agent-preset.json` |
| `/theme` | `<名字>` / `status` | 主题:无参选择器;`<名字>` 直接切换;`status` 当前主题(auto 时附 OSC 11 解析结果)。持久化 `~/.dsh-tui/theme.json` |
| `/color` | 无参 / `<名>` / `status` / `reset` | 会话强调色:无参打开调色板(`↑/↓` 选、`Enter` 应用);`<名>` 直设;`reset` 恢复默认。颜色 `red/orange/yellow/green/blue/purple/pink/cyan`,按会话保存 |
| `/lang` | `en` / `zh` / `status` | 界面语言热切换。优先级:`DSH_TUI_LANG` > profile 配置(旧版 settings.yaml 用户层 > cordis.yml)> 持久化 |
| `/vim` | 无 | **vim 编辑模式开关**(见 §2.4):输入框切到 vim 键位编辑,会话级、不持久化 |
| `/panel` | `toggle` / `focus` / `zoom` / `<面板 id>` | 侧栏面板:开关 / 聚焦 / 缩放 / 切换;三态与子命令见 §2.8 |
### 3.4 账号 / 策略 / 扩展
| 命令 | 参数 | 作用 |
|---|---|---|
| `/provider` | 无 | 交互式管理模型提供方(添加 / 编辑 / 删除;标准 profile 的账号登录含 DSH 0.2.0-rc.1+ 的 DeepSeek,以及 ChatGPT/Codex / Claude / Grok;宿主 pi-ai 支持时还有 OpenAI 直连 / Meta Muse) |
| `/auth` | `status` / `login [provider]` / `logout <provider>` | 查看账号状态、登录或登出(DeepSeek 用 `deepseek-account`;pi-ai 订阅用 `openai-codex` / `anthropic` / `xai`,较新 pi-ai 另有 `openai` / `meta`) |
| `/login` | 无 | 凭证状态(来源、存储可写性、base URL;OAuth 模块挂载时另列账号状态) |
| `/logout` | 无 | 登出说明(env 来源需删环境变量并重启) |
| `/permission` | 无 / `<preset>` / `status` | 查看/切换权限预设与策略(无参打开选择器) |
| `/add-dir` | 无 | 文件策略范围说明(以工作目录为根) |
| `/hooks` | 无 | 占位:DSH hooks 未在组合中挂载时给出说明 |
| `/mcp` | 无 | MCP 连接状态(工具按 `mcp__服务器__工具` 分组);未配置时给出 `cordis.patch.yml` 插入示例 |
| `/skills` | 无 | 技能目录选择器(名称+来源+简述),Enter 将可直调技能以 `/name ` 填回输入行 |
| `/plugin` | `list` · `install <spec>` · `remove <bundle>` · `enable <名称\|id>` · `disable <名称\|id>` · `check <dsh-plugin.json 路径>` · `info <id 或 spec>` · `registries` | `list` 简洁列出你装的额外插件(不含其他安装自带;本应用已适配、默认关闭的实验性功能单独列出并给开启/用法);无参给完整诊断:信任横幅 + host 描述符 + 授权矩阵 + 台账 + profile 的 bundle/行;`install <spec>` 把插件装进当前 profile:装前提醒 + 信任确认,嫡系包按随包清单免确认,`esc` 收起面板(安装中尝试取消并等待写操作结束;来不及时等待安装完成,已登记的版本豁免保留),构建脚本被拦时在面板里批准,版本不兼容时可登记精确版本豁免;`remove` / `enable` / `disable` 是生命周期动作:bundle 名精确匹配优先,其次 `entryId` / `patchId` / 模块名,模块名匹配多行时须改用具体行 ID;门禁 2 对「提供本应用的 bundle / 宿主层 dsh-base / 本包自己的行」硬拒并给原因(零服务调用),任何启用与卸载都要确认(已装包来源无法验证)。**这三个动作没有取消**:`esc` 只关面板,写入照旧跑完并把结果写进转录;卸载不会删掉 `~/.dsh-tui` 下你自己的数据,有残留时报告一次。`check` 校验清单并给兼容状态,`info` 查已装条目或待装 spec,`registries` 列安装源 |
| `/update` | 无 | 一次对齐 TUI、全局 dsh 引擎与全局启动器(启动器对齐通常为 best effort;引擎已推进后若启动器失败,则拒绝重启并给修复命令),校验后自动重启恢复会话(仅 `dsh --profile` 启动可用;回合运行中会拒绝;新 TUI 的 peer 范围不支持当前引擎时拒绝升级:低于范围且安装可自动执行时先对齐引擎再重新 /update(打印命令;安装不可自动执行时给修复指引),高于范围时等声明支持该引擎的 TUI 发布(不降级)),见[更新到最新版本](getting-started.md#更新到最新版本) |
| `/terminal-setup` | 无 | 终端配置建议(Windows Terminal ≥110 列、粘贴键位) |
### 3.5 技能
dsh-TUI 不预装通用技能;`/skills` 浏览 DSH 发现的技能,可直调技能以 `/name` 加入命令菜单(详见 §4.8)。
### 3.6 占位命令
`/connect`:占位——DSH 暂无远程连接机制。
### 3.7 注册表命令(来自 DSH 生态,随组合动态并入 `/` 菜单)
| 命令 | 作用 |
|---|---|
| `/plan` | `[off\|message]` 计划模式;`/plan off` 退出 |
| `/goal` | 设置/查看会话目标 |
| `/feedback` | 提交使用反馈 |
| `/permission` | 查看/切换 DSH `permissionPresets` registry 的预设(第三方预设按 registry 顺序显示) |
> 这些命令由 DSH 命令注册表实现,本仓库只做菜单并入、补全与分发。
## 4. 会话工作流
### 4.1 会话生命周期
| 操作 | 命令/键 | 要点 |
|---|---|---|
| 新建 | `/new` | 无二次确认——旧会话已持久化,随时可 `/resume` 找回;顺带清空 resume 标记 |
| 恢复 | `/resume`(同 `/home` `/agentview` `/bg` 与输入框行首 `⌸`) | 三合一**会话管理界面**:`←/→` 切栏、打字筛选、`Enter` 进入、`Ctrl+N` 新建、`Ctrl+X` 停后台会话、行内 ★/☆ 固定。切换只是**停放**,回合继续跑;被其他终端占用的会话标红进不去(详见 §2.7) |
| 重命名 | `/rename <标题>` | 立即改名并持久化(写入 session/title 事件,会话管理界面里能读回) |
| 压缩 | `/compact` | 手动触发 compaction;**回合运行中拒绝**;minimal preset 下不可用;压缩点以 Divider 摘要行呈现 |
| 导出 | `/export` | 从完整 session log 导出 Markdown(含 thinking 与工具调用分节),文件 `dsh-tui-export-<时间戳>.md` 落在会话启动时的项目 cwd(不跟随 Agent cd) |
| 清屏 | `/clear` | 只清视图,不动会话日志 |
| 停止 | 会话管理界面 `Ctrl+X` | 停止光标所在的**后台**会话;当前终端正在用的会话停不了(想退出整个 TUI 用 `/exit` 或双击 `Ctrl+C`) |
| 退出 | `/exit`(或 `/quit` `/q`) | 空闲 `Ctrl+C` 双击或 `Ctrl+D` 双击也可退出;工作中中断迟迟不收敛时再按 `Ctrl+C`/`Ctrl+D` 强制退出 |
命令行恢复:`dsh-tui --resume`(最近会话)/ `dsh-tui --resume <id>`(指定会话)。
`-c` / `--continue` 等价。启动恢复只针对**本次启动所选的后端**:该后端没有上次会话,
或派生出的目标属于别的后端时,启动器明确报错并以退出码 1 收束,不静默冷启动、不新建
会话(安全模式的「重试正常启动」降级为告警 + 冷启动,见 [README](../README_ZH.md))。
### 4.2 时间回溯 rewind(双击 Esc)
**空输入时连按两次 `Esc`**(或 `/rewind`),进入回退选择器:
1. 选择器列出**你自己的消息**(最新在前),`↑/↓` + `Enter` 选中。
2. 若模型正在工作:先取消回合并等落定(最长 30s)。
3. 边界取该消息所属回合**开始之前**;**不能回退到第一条消息**。
4. 系统 fork 新会话并回放历史到回退点,**原消息放回输入框**供修改重发。
5. 回退分支留在 `/resume` 列表里,继续用当前模型路由 + 会话自己的 preset。
### 4.3 消息投递语义(模型工作中)
键位见 §2.1:
- `Enter` = 已知 `/` 命令(可带参数)按命令执行(回合运行中由该命令自己的门禁裁决);其余文本 **steer**(注入下一步边界,不中断)
- `Tab` = **follow-up**(排到回合后)
- `Ctrl+Enter` = **interrupt**(打断并发送)
- `Alt+Up` 取回最后一条未处理消息
- `↑` 召回到的消息若仍排在队列里,会一并把那条排队项撤回(同 `Alt+Up`,避免同一条发两遍);已被本轮取走时只提示、不撤回
- `Esc`(有 pending)中断并重投
- `/btw …` 侧问永不打断主回合
### 4.4 侧问 /btw
`/btw <问题>`:复用当前上下文做**无工具、单轮**回答,**不写历史、不计 token**,主回合照常。
面板 `↑/↓` 滚动 · `c` 复制 · `Esc` 关闭;侧栏面板的追问输入框里 `Ctrl+V`/`Alt+V` 粘贴到光标处。
### 4.5 轨迹场景(Ctrl+T / /trace)
整屏查看会话全程时间线(不污染 scrollback);键位见 §2.7。
### 4.6 模型切换与预设
同会话切换需要 DSH `0.1.2-alpha.3` 或更高版本;旧版会提示升级,防止子代理继续使用切换前的模型。停放中的会话保留所选路由。
- `/model`:选择器。**同会话切换模型**(保留 session ID 和历史,下一次请求使用新路由);
持久化 `~/.dsh-tui/model.json`,下次启动直接沿用它(cordis.yml/profile 中的
`provider`/`model` 只是首次启动的部署默认值)。
- DSH 的顶部标签以「最近使用」开头,再列各提供商,`Tab` / `Shift+Tab` 切换提供商;Codex 与 Claude 直接显示模型目录,不显示这些标签。所有后端均用 `↑/↓` 选模型、`←/→` 调推理等级、`Enter` 一并应用、`Esc` 取消草稿,支持点击可用的标签、模型、档位与选择/取消提示,以及滚轮移动模型焦点。点击推理档位会立即应用当前聚焦模型与该强度,并关闭选择器。
- 回合运行中切换会被拒绝。
- `/preset` 可选:`standard`(默认全功能)、`ptc`、`minimal`(内核「极简模式」:只暴露一个持久 shell 工具,无 compaction、无计划模式;也因此没有压缩、工具结果不剪枝——长会话可能撞上下文上限,`/compact` 与问卷不可用,Help 与 `/` 补全会标注,进入该预设时提示一次)、
`cordis`、`liangshen`(梁神模式)。
**已产生对话的会话不能切换**(blank-only):选择只保存为下次 `/new` 的默认。
这里的 preset 是**内核 Agent 预设**,决定模型能用哪些工具;界面上的 `/settings → 极简界面`(Minimal UI)与它无关。
- 会话模式用 `Shift+Tab` 循环:default(workspace-write + 审批)→ plan(read-only)→
full(danger-full-access)。
- 第三方权限预设按 registry 顺序排在末尾。
- **批准计划或 `/plan off` 之后,沙箱与审批策略回到进入计划模式之前的状态**。
### 4.7 问卷与审批
键位见 §2.7。要点:
- 问卷**最后一行是自由输入行**(直接打字连同选项标签一起提交)。
- 计划评审**批准必须无反馈文本**。
- 审批与问卷同时挂起时**审批优先**;后台会话发起的审批会标注 `来自后台会话 <会话 id 前 8 位>`。
- 等待中的工具授权会随「通知」开关走系统通知(标题「dsh-TUI · 等待授权」,见 §5.3 的 `taskNotifications`);开启 `jumpBack` 后点击这条通知会回到对应窗格,原生 toast 排队期间若开关关闭、会话已切换或审批已答完则取消。
- 等待中的提问会随「通知」开关走系统通知(标题「dsh-TUI · 等待回答」,正文是首个问题的标题与问题本身,选项留在面板里;见 §5.3 的 `taskNotifications`);本地向导与登录流程里的问卷提问同样提醒,子代理的提问只进面板,上游 0.2.2 的 approval intent 提问按普通等待回答提醒。开启 `jumpBack` 后点击这条通知也会回到对应窗格,原生 toast 排队期间若开关关闭、会话已切换或提问已答完则取消。
- 计划评审也会随「通知」开关走系统通知(标题「dsh-TUI · 计划评审」,正文只含问题标题与问题本身,不含整份计划与选项;见 §5.3 的 `taskNotifications`);它是唯一不让位的一类:外部通知插件只把审批与普通提问映射成通知,计划评审不在其中,让位就只剩它那条不区分事件的「等待输入」,不会标明是计划评审在等你。开启 `jumpBack` 后点击这条通知也会回到对应窗格,原生 toast 排队期间若开关关闭、会话切换或计划评审已处理则取消。
### 4.8 技能 / 注册表 / Goals-Todos
- `/skills` 浏览技能目录,可直调技能以 `/name` 加入命令菜单(dsh-TUI 不自带通用技能)。
- `/plan` `/goal` `/feedback` `/permission` 来自 DSH 注册表,随组合并入 `/` 菜单。
- **Goals/Todos 面板自动出现**:模型写入 goal/todo 时在输入框上方实时渲染(🎯 目标 + phase 徽章 + 树形 todo),
无需操作;分栏开启时它迁到右栏的 `todo` 面板(见 §2.8)。目标栏保留单行摘要:悬停被截断的目标正文看全文(右栏 `todo` 面板则完整换行,靠滚动读全文);
裸 `/goal` 把完整状态(目标全文、阶段、轮次或预算、可用命令)打印成 `/plugins` 同款的转录块——inline 没有鼠标指针,长目标靠这个块读。
### 4.9 MCP / Workspace / 其他
- `/mcp`:按服务器分组列出 `mcp__服务器__工具`;未配置时给出 `cordis.patch.yml` 插入示例。
- `/workspace`:`resume` / `rename <名>` / `open <路径|file:// URI>`(打开并新建会话)。
- `dsh-tui <路径>` 同样接受工作区目标。
- `/doctor` 自检:Node/平台、API key、模型路由、cwd、上下文窗口、会话存储、插件宿主。
- `/provider` 交互向导管理模型提供方:添加 / 编辑 / 删除。在模型列表聚焦一项后按 `Tab`,可编辑其上下文窗口、最大输出 token、推理档位和图片输入能力;`Enter` 保存到本次 provider 草稿,取消外层向导不会写入。
- 标准 profile 的内置 OAuth 模块提供 **订阅账号登录**(ChatGPT/Codex / Claude / Grok;较新 pi-ai 另有 OpenAI 直连 / Meta Muse,免 API key);也可用 `/auth login <provider>`,`/auth logout <provider>` 删除保存的 OAuth 凭据。
- DSH 0.2.0-rc.1+ 的 DeepSeek 账号经宿主浏览器授权:`/auth login deepseek-account`,随后用 `/model` 选独立的 `deepseek-account` 路由;`/auth logout deepseek-account` 由宿主退登。它不修改 `deepseek-official` 的 API key。
- 非环境变量 API key 写入 `~/.dsh/.credentials.yaml`(0600),界面只显示 `••••••`;pi-ai 订阅 OAuth 凭据另存于 `$DSH_HOME/dsh-auth/credentials.json`(未设置 DSH_HOME 时为 `~/.dsh/dsh-auth/credentials.json`)。DeepSeek 账号授权记录由宿主凭据服务持有,不写入此 OAuth 文件。
- 自定义端点需填路由名、API key、baseURL 与协议(`openai-completions` / `openai-responses` /
`anthropic-messages`)。
- 添加/编辑后运行 `/model` 切换到新路由。
- `/init` 创建 AGENTS.md;`/agents` 子代理列表;`/login` `/logout` 凭证管理。
- `/permission` `/add-dir` 权限说明;`/hooks` `/vim` `/connect` 为占位。
## 5. 界面与状态栏
空会话顶部是鲸鱼 Logo 区(随对话滚动消失):
- **开场动画**(约 3.4 秒,每次启动三选一,`/deepseek` 彩蛋重掷):经典 / 爱心 / 睡觉。
- **欢迎期闲置动画**(`whaleIdle`,默认开):摆鱼鳍、眨眼、拍尾巴,空闲 10 秒入睡冒 Z;**点击冒爱心唤醒**。
- **女仆娘立绘**(`whaleGirl`,默认关):DeepSeek 品牌下,宠物皮肤设为 `whale` 并开启本项后,显示作者绘制的女仆娘——优先走 Kitty/Sixel 真图,不支持时回落字符画。**显示真图时,点她一下**会换成「高兴鲸娘」几秒,再自动回安静版;第一个任务后定格,不再响应点击。字符画保持静态。`deepy` 和 `whaleGirl` 皮肤会取代立绘;Claude 使用自己的图案,Codex 使用自己的真图或女仆娘字符画回退;这两个品牌的开屏图案不受宠物皮肤和女仆娘开关影响。见[优先级表](configuration.md)。
- 开始第一个 agent 任务后定格为静态帧(`/new` 重新进入欢迎期)。
- 鲸鱼右侧文字列:`✦ dsh-TUI v版本号` → 块体大字 `DEEPSEEK / HARNESS`(加粗字形,两行等宽、中间空一行)→
当前模型 + effort → 工作目录 → 启动提示行。
- 大字字面按**本地日期**轮换(8 款:加粗 / 方角实心 / 半立体 / 宽体 / 点阵灰度 / 镂空模板 / 细笔 / 方板):
同一天内恒定、隔天换一款,与启动时刻无关。想固定看某一款,就在 `/settings → 开屏大字字体`
(`splashFont`)选它——选具体某款即 pin 住,选回 `按天轮换`(默认)恢复轮换;改完立即生效。
- 版本不在验证范围时多出 **⚠ 版本漂移警告**(附对齐命令)。
- 鲸鱼下方居中欢迎语:`探索未至之境!`
- 终端变窄按**内容区列数**逐档降级:**≥ 97 列**鲸鱼 + 大字;**55–96 列**只留大字(先撤鲸鱼);
**40–54 列**只留鲸鱼;**< 40 列**退成一行 `DeepSeek Harness` 纯文字。门槛随字面宽度浮动
(97 列是 6 列字身那几款的数;最宽的 `wide` 要 113 列,5 列的 `classic`/`slab` 96 列就够)。
- 像素鲸鱼原图与闲置行为移植自 [dsh-ui-whale](https://github.com/lhh010/dsh-ui-whale)(作者
[@lhh010](https://github.com/lhh010)),特此致谢。
**超长单行折叠**(默认开)
- **单行超过 1000 字符**的文本折叠为 `… 已折叠 N 字符(点击或 ctrl+o 展开)` 标记。
- 展开:**鼠标点这一行**(工具卡点卡面)再点收起;键盘用 `Ctrl+O`。
- 思考(thinking)行不折叠。
### 5.2 底部状态栏(输入框下方三行)
**Row 1 — 上下文分段进度条**(`/settings → statusBar.contextBar`,默认开)
- 按内容类型分段着色(system / prompt / assistant / thinking / tools)。
- 分段着色按内容类型(system / prompt / assistant / thinking / tools)。**已用段的长短严格等于读数**
(`13k/64k` 里的 13k):五段只按构成把这个长度切开,估算偏小/偏大都不会再让条画短或画长。
- 构成分两层:harness 的 `contextBreakdown` 投影(system 提示 / 本次请求信封里的工具 schema /
其余可见内容,注入的上下文也在这一项)+ 本地估算(把 meter 的消息侧再按 prompt / assistant /
thinking / 工具结果细分;ASCII ~4 字符/token、CJK ~1.4、其它脚本 ~2)。旧版 meter 不发布该投影时
只用本地估算。
- 悬停图例报的就是条上那批份额(按占用归因),**五段 + free 合起来正好是窗口**(`1.2k` 这类缩写
每项最多差半个单位),不再出现「五段加起来只有读数一半」。估算本身**不参与占用总量**——占用以
ctx 字段/读数为准(见下)。
- 构成无法归因到任何类别时,条保持单块已用区域;条和 ctx 字段的悬停明细都报实测 `used`,不列五个零分类。
- 条上唯一文字是最右缘读数 `13k/64k 19.5%`(窄屏只显示 `19.5%`)。
- 读数按占用率变色:<80% 灰蓝,**≥80% 琥珀、≥95% 红**。
- 悬停整条弹出图例:色块 + 名称 + token 数(窄屏自动改用短名)。
**Row 2 — 状态字段行**(每个字段独立开关,见 `/settings`)
- 左组:模型 → TPS → thinking → mode → ctx(**上下文占用** `19.5% (13k/64k)`:与分段条、工作线压力前缀、`/tokens`、`/status` 和上下文告警**同读一个值**,来源是 harness 自带的 `contextPressure` 投影——`projectedTokens ?? pressureTokens`,即「下一次请求」的占用,压缩与被拒请求都会立刻反映,不再等一次成功请求;投影缺席的裸 `cordis.yml` 组合回退到上次请求的计费用量)→ cache 缓存命中率 → tokens(`1.2k→340` 输入→输出)→
cost(`≈¥0.05 谷`,**本会话估算**:包含子代理用量,按各自模型 × 峰值/空闲 × 缓存分项计价;
hover 拆「主会话 ¥ / 子代理 ¥ / 未计价 N tok」;非官方/未收录模型只显示 token 并标注未计价;
**估算是参考,以平台账单为准**)
- 右组:git 分支(**跟随工作树 HEAD**——别处切分支约 1 秒内反映到界面,detached HEAD 时清空)→ 工作目录(紧凑模式:未移动时显示项目名;项目内移动显示 `项目›相对路径`,项目外移动显示 `项目→路径`)→ 会话标题 → 短会话 ID(`#` + 前 8 位,方便 `--resume` 定位)
- `statusBar.compact` 时左右合并为单行。
- **插件底栏字段**:插件可通过 `ctx.tuiStatus.setField` 贡献字段(三槽:左组末尾 / 右组开头 / 右组末尾,可选 hover 详情与全屏点击);`statusBar.pluginFields`(默认开)可一次关掉全部插件字段,关闭不会卸载插件。
- **逐字段启停与排序**:`/settings → Status bar → 插件底栏字段名单`(`statusBar.pluginFieldsOrder`)把字段按三槽分组列出,逐条勾选,并用底部「高级」行调整顺序。值形如 `build,ci;git;pet`——恰好三组(`;` 分隔),组序号即槽位、组内顺序即显示顺序;列进名单的字段跟随所在组(覆盖插件声明的槽)。留空 = 一个都不显示;`*`(默认)= 全部(含以后注册的字段,按声明槽与注册序)。从 `*` 进入高级行编辑会预填三组骨架,原样保存不改变模式;名单固定后新注册的字段默认不出现,需要勾选。
- 默认开:compact、model、thinking、cwd、contextUsage、cache、cost、goal、contextBar、pluginFields。
- 默认关:tokens、tps、gitBranch、sessionTitle、sessionId、mode、activity、trajectory。
**Row 3 — 提示 / 工作活动 + 迷你轨迹条**
- 空闲显示 `? for shortcuts`、运行中 `esc to interrupt`、选择中 `esc to return to input`。
- 空闲还显示 working-activity 动画帧(`statusBar.activity` 开),上下文 ≥80% 琥珀、≥95% 红(与 ctx 字段同一占用读数)。
- 右侧**迷你轨迹条 MiniWake**(`statusBar.trajectory`,默认关):会话投影为密度字形,颜色区分通道,失败列染红;
窄屏降格/隐藏。
**TPS 仪表**(`statusBar.tps`,默认关):流式中显示实时 gauge + `N tps`,回合后显示 sparkline;
速度 **≥50 绿 / ≥20 黄 / <20 红**。
### 5.3 /settings 设置编辑器
`/settings` 打开插件设置编辑器;**改动自动保存**,`Esc` 直接退出。
dsh-tui 自身区块在 0.1.7 写入当前 profile 的 `cordis.patch.yml`,旧版写入 settings.yaml 用户层。多数设置实时生效;全屏和图片预览开关需 `/restart`。
下表为常用项,完整列表见 /settings 屏。多数主题(**外观与布局** / **开屏与吉祥物** / **对话与输入** / **图表与图片**)的字段直接平铺在根页的小标题下,改起来不用进出子页;只有真正成块的域——**公式设置** / **底栏设置** / **侧栏** / **快捷键**——保留子页,根页一行入口点进去:
| 字段 | 说明 |
|---|---|
| lang | 界面语言 zh/en(DSH_TUI_LANG 钉死时不可改) |
| fullscreen | 全屏模式(默认开);保存后用 `/restart` 生效 |
| launchpad | 启动页(落地页,默认开):普通启动先落启动页输入第一句话;关闭后直接进入聊天页(带 `--resume` 等恢复目标的启动不受影响,仍直接进会话)。保存后用 `/restart` 生效 |
| minimal | 极简界面 Minimal UI(默认关):隐藏开屏头部、emoji 状态符与装饰性配色,底栏只留模型与目录;代码高亮与工具配色保留。**这是界面开关**,对模型能力没有任何影响——别和 `/preset` 的内核「极简模式」预设搞混 |
| terminalImages | 终端图片预览(默认开,需终端支持);保存后用 `/restart` 生效。关闭后只显示文字信息并跳过预览解码,不影响向模型发送图片 |
| imageBacking | 图片底色(默认 `transparent`,与上一条同在**图表与图片**主题下):聊天照片/插图背后垫什么。透明:只画图片自己的像素,抗锯齿边缘和透明圆角透出终端底色或壁纸;终端底色:先合成到终端背景色,柔和边缘更平滑。立即生效 |
| codeFrameStyle | 代码框样式(默认 `light`):`light` 左侧开放栏杆;`full` 带连续右边框和底边的封闭边框。终端太窄时显示纯代码围栏。立即生效 |
| whale | 开屏头部像素鲸鱼娘(默认开);每次启动随机三选一开场动画(经典/爱心/睡觉),`/deepseek` 彩蛋重掷 |
| whaleIdle | 鲸鱼娘欢迎期闲置动画(默认开):定格后摆鱼鳍/拍尾巴/眨眼,空闲 10 秒入睡冒 Z;点击冒爱心。开始第一个任务后定格 |
| splashFont | 开屏大字字体:按天轮换(默认,随本地日期换款)/ 加粗 / 方角实心 / 半立体 / 宽体 / 点阵灰度 / 镂空模板 / 细笔 / 方板。选某一款即固定那一款,选回「按天轮换」恢复。立即生效 |
| whaleGirl | 女仆娘立绘(默认关):DeepSeek 品牌下,设 `companion.skin=whale` 并开启本项;`deepy` 和 `whaleGirl` 皮肤会取代立绘。Claude 使用自己的图案,Codex 使用自己的真图或女仆娘字符画回退;这两个品牌的开屏图案不受宠物皮肤和女仆娘开关影响。优先 Kitty/Sixel 真图,不支持时回落字符画。见[优先级表](configuration.md) |
| diffLayout | Edit/Write diff 布局:auto(≥110 列双栏)/ split / unified;双栏(auto 在 ≥110 列,或显式 split)折叠时仍一行一条,超宽行会被截断,卡片末尾给一行 `… 已折叠 N 字符(ctrl+o 展开)` 提示;展开(`Ctrl+O` 或点击卡片)后超宽行按各自栏宽换行,两栏仍逐行对齐(同一改动行左右同起点) |
| thinkingFold | 思考块:preview(流式 2-3 行预览 + 落定折叠)/ full(展开到轮末) |
| btw.contextBudget | `/btw` 追问携带的最近问答总字符预算(默认 24000,范围 1000-200000);超出时从最旧的整组开始裁剪。立即生效 |
| btw.contextTurns | `/btw` 追问显式携带的最近完成问答组数(默认 4,范围 1-8);窗口外的问答不进入请求,线程与面板仍保留全文。立即生效 |
| jobGroupFold | 连续的后台任务卡:auto(默认,≥2 张成组;整组落定且 ≥3 张时折叠成汇总行)/ always(≥2 张立即折叠,含在跑的任务)/ never(从不自动折叠,每张卡都留着)。组头一行汇总状态与合计时长,点组头或 Ctrl+O 展开 |
| effortDefault | 默认推理强度:自动及当前后端/模型声明的档位(包括自定义 ID)。未支持的已存值仍可读;加载中或不可用时仅可选自动 |
| smoothStreaming | 流式平滑输出(默认开):回复/思考/工具卡正文按 ~30fps 匀速揭示;回放/历史完整直出 |
| toolBackground | 工具卡背景强调:none / subtle / strong;展开后也生效。`present` 交付卡始终保留自己的底色:无背景时暖橙,轻微/明显时紫罗兰;极简界面除外 |
| taskNotifications | 通知(默认「仅失焦时」):一个开关同时管四类系统通知——任务完成、等待工具授权、等待回答与计划评审。完成通知标题「dsh-TUI · 任务已完成」,正文为本轮回复的单行纯文本摘要;审批通知标题「dsh-TUI · 等待授权」,正文只含会话名、工具名与宿主给出的理由(已归一化并限长,模型写的理由会原样出现,不读取工具调用的参数);提问通知标题「dsh-TUI · 等待回答」,正文只含首个问题的标题与问题,不含选项与详情(模型提问与本地向导/登录等经问卷面板的提问都算;上游 0.2.2 的 approval intent 提问按这条提醒;子代理的提问本版只进面板);计划评审标题「dsh-TUI · 计划评审」,正文只含问题标题与问题本身、不含整份计划与选项,且是唯一不让位的一类;原生 toast 排队投递期间,开关关闭、会话切换或审批/提问/计划评审已处理都会取消。每条审批各提醒一条,且只提醒当前会话(后台会话与子代理不提醒)。投递方式由 `notificationMethod` 决定,原生 toast 投不出去时回落到响铃;外部 DSH 通知插件已启用并处于 active 时,完成、审批与提问让位,计划评审不让位。立即生效 |
| turnUsageRow | 回合用量行(默认关闭):在每回合末显示 token、缓存、耗时与重试摘要;`/tokens`、`/status` 和底栏 token 悬停不受此开关影响 |
| mermaidDiagrams | Mermaid 图表(默认开):回复中的 ```` ```mermaid ```` 代码块画成字符图,流式期间逐步成形;比终端宽或类型不支持的图保留源码并注明所需列数。立即生效 |
| nerdFontIcons | Nerd Font 文件图标(默认关):`present` 交付卡用文件类型图标代替四格徽章;需要终端使用 Nerd Font Mono,否则图标显示为方框。立即生效 |
| mathRendering | LaTeX 公式(默认 `auto`,在 `/settings` 的**公式设置**子页里):回复中的 `$…$`、`\(…\)` 行内公式,`$$…$$`、`\[…\]` 与单独成行的 `\begin{align}` 等显示环境块级公式的显示方式。`auto` 用当前最好的渲染方式(目前是 Unicode 文本,块级公式里的分数与上下限竖排),`image` 在支持图形的终端里用 MathJax 把公式排版成图片——Kitty 图形协议(Kitty、Ghostty、WezTerm、iTerm2 等)或 Sixel(Windows Terminal 1.22+、xterm、foot、WezTerm)(颜色跟随主题文字色;块级公式最多 16 行,行内公式在能压成一行且不糊时也显示为一行高的图片;流式中的公式、暗色的思考区、不支持图形的终端、压成一行太小以及任何渲染失败都退回 Unicode),`unicode` 固定用 Unicode 文本,`source` 保留原始 TeX。不支持、仍在流式输出或比终端宽的公式保留源码(过宽的块级公式先退成单行)。价格(`$5`)、shell 变量(`$HOME`)与代码里的 `$` 不受影响。旧的 `latexMath: false` 仍等同 `source`。**点击公式图片**打开预览卡:按 2 倍单元格尺寸重排,可 100%–800% 缩放、拖拽平移,`Esc` 或点击卡片外关闭,标题即该公式的 TeX。Sixel 下公式**不带衬底**(只画笔画),终端底色或壁纸会透出来。标题立绘这类自带透明留白的插图同样不带衬底(`whaleGirl` 的真图就是这个行为);照片、截图与卡片内的图像仍合成到底色上,因为 Sixel 表达不了软 alpha。立即生效 |
| mathImageScale | 公式图片大小(默认 `auto`,与上一条同在**公式设置**子页):配合 LaTeX 公式的「图片」使用——`auto` 与正文同尺寸,`large` / `xlarge` 把**块级**公式排得更大;终端图片是按设备像素 1:1 画的,所以"更大"就等于"每个笔画更多像素",是唯一的清晰度杠杆。行内公式不受影响(只能占一行)。立即生效 |
| scrollGutter | 转录边栏:timeline(轮次时间线,默认)/ scrollbar(比例滚动条)/ hidden。立即生效 |
| pageMargin | 页边距:整屏相对终端四边向里缩。预设 none / slim / normal(默认)/ roomy,或自定义 `NxM`(细节见下)。立即生效 |
| foldTerminalCommand | 折叠终端命令(默认关):终端卡(Bash/PowerShell)多行命令折成首行 + 计数;`Ctrl+O` 或点击卡片展开 |
| expandEditor | 全屏草稿编辑(默认开):输入行尾 `⛶` 或 `Ctrl+Shift+E` 展开成整屏编辑器;`Ctrl+Enter` 发送、`Esc` 收起(草稿还在);关掉后入口不显示 |
| statusBar.* | 上表全部状态栏开关(compact/model/thinking/cwd/contextUsage/cache/tokens/cost/tps/gitBranch/sessionTitle/sessionId/mode/contextBar/activity/trajectory/pluginFields/pluginFieldsOrder;statusBar.sessionId 是底栏显示开关,与 cordis 的启动 sessionId 无关;pluginFieldsOrder 是插件字段名单:`''`=不显示、`*`=全部、`a,b;c;d`=三组即三槽) |
| jumpBack | 通知跳回(Windows,默认关,管完成、等待授权、等待回答与计划评审):开启后窗格标题末尾追加 `[dsh-tui:<16 位十六进制>]` 标记;点击本会话的完成、等待授权、等待回答或计划评审通知回到这个窗格,无法核验的布局降级为普通通知。第一条能承诺跳回的 toast 会注册当前用户的 HKCU 协议键。立即生效 |
**effortDefault**:模型没有该档时向下选择最近的可用档位,否则回到模型默认,并弹提示。DSH 的优先级为 settings 用户层 > 上次 `/effort`
(effort.json,即上次实际运行的档位)> cordis `effort`(部署默认值)> 模型默认。Claude/Codex 通过自身控制接口和后端偏好应用修改;启动采用自动模式或恢复会话时保留原有选择,在设置中主动选择自动会重置为模型默认。
**scrollGutter**:scrollbar 轨道可直接拖;`Shift`/`Alt`/`Ctrl`+拖动仍是文字选择。
**pageMargin**:自定义 `NxM` = 左右 `N` 列、上下 `M` 行(上限 8x4);只填 `N` 则上下 1 行。
**通知投递**:支持 OSC 777/9 的终端上,标题与正文合计受 2048 字节序列预算约束(含协议开销),按完整字素截短;没有回复时只显示标题,BEL 只响铃。本地 Windows 上 `auto` 解析为原生 toast(`windows`):首次弹出注册当前用户的 AppUserModelID(AUMID,写 HKCU),弹出比任务结束晚约 3 秒(零安装路线要付的 PowerShell 冷启动代价);注册写不进去时回落到响铃,而不是静默。本地 Windows 上,外部 DSH 通知插件已启用且处于 active 时,完成、审批与提问让位给它,计划评审不让位。显式 `osc9` 与 iTerm2/Warp 一样把标题放在正文前;SSH 会话的 `auto` 保留所连接终端的通知协议,显式 `windows` 仍选择运行主机的原生通知。回放、取消与失败不通知;inline 与 fullscreen 都支持。
**通知跳回(`jumpBack`)**:Windows 上默认关闭,需要原生 toast 通道(`notificationMethod` = `windows`,本地 Windows 的 `auto` 会选它)。开启后窗格标题末尾追加 `[dsh-tui:<16 位十六进制>]` 标记,同一进程内不变;关闭即去掉后缀。开启期间,本进程在启用时与每次发出通知前刷新 `~/.dsh-tui/notify/jumpback/<session>.json`(`schemaVersion: 1`、`marker`、`pid`、`startedAt`),并由第一条能承诺跳回的 toast 注册当前用户的协议处理器(`URL Protocol` 与 `shell\open\command`)到 `HKCU\Software\Classes\dsh-tui`;正常退出删除该文件,并在没有其它存活实例需要时删除该键。只有发送前的探测恰好命中一个目标窗格(或一个标签标题)时,toast 才带 activation URI;点击时再跑五项核验——同一个窗格、获得键盘焦点、标题仍含标记、窗口在前台、未最小化——任一项不成立就拒绝跳转。目标已消失的点击不改变任何东西;无法核验的布局(目标在未选中标签且非该标签获焦窗格、使用 `suppressApplicationTitle`、非 Windows Terminal;在 Windows Terminal 1.24 实测)发普通 toast。探测会让每条 toast 晚约半秒,开启后第一条还可能等 helper 编译一次(几秒),本机编译器持续失败时最多每五分钟重试。外部发送方可读取同一个标记文件,把自己的 toast 指向 `dsh-tui:activate?m=<marker>`;URI 与文件格式是只读契约,本版不提供插件侧实现。
未声明 TUI 区块的命名空间以只读形式列出,需手工编辑 profile 配置(旧版为 `~/.dsh/settings.yaml`)。
以下设置**不在 /settings 内**,改 `$DSH_HOME/profiles/dsh-tui/cordis.patch.yml`:
provider / model / cwd / preset / workspace / sessionId / modes,
以及启动级 `effort` 键。
### 5.4 终端要求
- 必须交互 TTY;推荐 Windows Terminal(≥110 列、等宽、TrueColor)。
- macOS 的 ⌘ 修饰键需要扩展键盘协议(iTerm2 / kitty / WezTerm / ghostty / rio / Orca / tmux);列表外的终端可设 `DSH_TUI_FORCE_EXTENDED_KEYS=1` 自行打开。
- rio 0.5.x 默认已启用该协议,不用额外配置;只有把它关掉的旧版本才需要在 `~/.config/rio/config.toml` 的 `[keyboard]` 段打开 `use-kitty-keyboard-protocol`。dsh-tui 只负责发出开启序列,不改终端配置。
- Terminal.app 用 Ctrl。
- VS Code:装 companion 扩展 `dsh-tui-vscode`(拿到 **IDE 选区通道**,需 ≥ 0.7.0)。
- 或直接在集成终端运行 `dsh-tui`。
- **图片**:缩略图与大图预览需要 Kitty graphics 或 Sixel(自动探测,Kitty 优先)。
- `DSH_TUI_IMAGE_PROTOCOL=auto|kitty|sixel|none` 覆盖协议。
- `DSH_TUI_DISABLE_TERMINAL_IMAGES=1` 强制关闭。
- tmux/screen、非 TTY、无障碍模式下只显示文字,不影响把图片发给模型。
- **粘贴剪贴板图片(Ctrl+V / Alt+V)**:Linux 需要 `wl-paste`(wl-clipboard)、`xclip` 或 `xsel` 之一。
- WSL:WSLg 把 Windows 位图暴露为 `image/bmp`,dsh-tui 会转成 PNG 再附加。
- 上面的工具读不到时,回退到 `powershell.exe`(需要 Windows interop)读取 Windows 剪贴板,
支持截图、资源管理器复制的文件与文本。
- **通知**:tmux 的 OSC 通知需要 `set -g allow-passthrough on`,焦点报告需要 `set -g focus-events on`;不支持焦点报告的终端把 `taskNotifications` 设为 `always`。
- 环境自检:`/doctor`。
### 5.5 安全模式与救援 profile(`dsh-tui safe`)
dsh 意外退出时,安全模式给出**只读**的环境诊断、profile 插件清单和修复指引。
- **两个入口**:手动跑 `dsh-tui safe`;或 dsh 非零退出后按屏幕提示进入(非交互环境只打一行提示)。
- **只读范围**:诊断/清单/指引都不改状态。
- 例外:重试正常启动、创建/复用空白救援 profile(只写 `$DSH_HOME/profiles/dsh-tui-safe/`)。
- **救援 profile 先要证明干净**(无第三方插件、无 `cordis.patch.yml` 条目),证不出就拒绝并打印处理方法。
- **非交互**:`dsh-tui safe --rescue` 只报告结论(就绪退出 0,被拒绝退出 1)。
- **修复命令要自己执行**(安全模式只列出):
- `dsh plugin --profile dsh-tui remove <第三方插件>` 移除可疑插件。
- `dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui@<版本>` 重装对齐。
- `dsh-tui doctor` 环境诊断。
## 6. 模型 / 预设 / 主题 / 语言
| 项 | 命令 | 说明 |
|---|---|---|
| 模型 | `/model` | 选择器;**同会话切换模型**(保留 session ID 和历史,仅换后续请求路由);持久化 `~/.dsh-tui/model.json`,重启与 `/new` 沿用(恢复的会话沿用其最后一次请求的路由)——它**优先于** cordis.yml/profile 里写的 `provider`/`model`(后者只是首次启动的部署默认值)。从没选过的话,用配置值,再没有才用 Harness 默认(当前为 `deepseek-flash`) |
| 推理强度 | `/effort` | 滑杆(←/→ 实时)或 `/effort <id>`;`/effort status` 看当前;持久化 `~/.dsh-tui/effort.json` 并被下一次启动沿用(优先于 cordis.yml 的 `effort`),新会话默认档在 /settings → 默认推理强度 |
| Agent 预设 | `/preset` | `standard` / `ptc`(旧 0.1.1 名 `code`)/ `minimal` / `cordis` / **梁神模式 `liangshen`**;**已开始会话不可切换** |
| 主题 | `/theme` | `auto`(OSC 11 跟随终端背景)/ `light` / `dark` / `dark-ansi` / `pink-day` / `pink-night` / `pink-ansi`;`/theme <名>` 直接切;`/theme status` 看解析结果 |
| 自定义主题 | 手动 | `~/.dsh-tui/themes/<名>.json`,`{base, colors}` 格式,选中即热切换;命名为 `auto` 会被内置遮蔽 |
| 语言 | `/lang` | `en` / `zh` 热切换;优先级 `DSH_TUI_LANG` > profile 配置(旧版 settings.yaml 用户层 > cordis.yml)> 持久化 |
| 状态行动画 | `/activity` | 选择器或 `/activity frames <名>`;默认 `moon8`,`random` 随机 |
**主题优先级**:`DSH_TUI_THEME` > `~/.dsh-tui/theme.json` > OSC 11 终端背景检测 > dark 回退。
**~/.dsh-tui/ 偏好文件**(均 best-effort,坏文件回退默认):
- `theme.json`、`model.json`、`agent-preset.json`、`effort.json`、`working-activity.json`、`lang.json`、
`trajectory.json`、`resume.txt` / `last-used.json`、`themes/<名>.json`
**常用环境变量**:
- `DSH_TUI_LANG`、`DSH_TUI_THEME`、`DSH_TUI_PRESET`、`DSH_TUI_PERSONA`
- `DSH_TUI_DISABLE_MOUSE`、`DSH_TUI_DISABLE_TERMINAL_IMAGES`、`DSH_TUI_IMAGE_PROTOCOL`、
`DSH_TUI_ACCESSIBILITY`(无障碍:关动画/图形预览)
- `DSH_TUI_RESUME_SESSION`、`DSH_TUI_WORKSPACE_TARGET`、`DSH_TUI_SESSION_ROOT`、`DSH_TUI_DEBUG`、
`DSH_TUI_RENDER_LOG`(帧取证)
- `DEEPSEEK_API_KEY`、`DEEPSEEK_BASE_URL`、`VISUAL`/`EDITOR`(`Ctrl+G` 外部编辑器)、
`DSH_PERMISSION_MODE`
## 7. 常用技巧
**上手**
1. `?` 看快捷键、`/` 看命令,两者都支持 Tab 补全。
2. 不确定环境对不对?先 `/doctor`;想看会话全貌用 `/status`。
3. 中英界面 `/lang en|zh`,即时生效并持久化。
**效率**
4. 模型工作中三种投递:`Enter` 注入下一步(已知 `/` 命令除外,按命令执行)、`Tab` 排队、`Ctrl+Enter` 打断并发送。
5. `Alt+Up` 取回最后一条未处理消息改完重发,不用重打。
6. 想快速问又不打断主回合、不留历史:`/btw <问题>`。
7. 打错了想重来:**空输入双击 `Esc` 时间回溯**(或 `/rewind`),改完重发。
8. `@` 在消息任意位置补全文件,`@src/a.ts#L12-14` 精确引用行区间。
9. `Ctrl+A` 子代理面板:`Enter` 看详情、`X` 中断运行中的子代理。
10. `Ctrl+O` 展开/收起详情;`Ctrl+T` 看轨迹(`[`/`]` 跳失败点、`/` 字段查询)。
**排障**
11. 上下文压力 ≥80% 变琥珀、≥95% 转红——该 `/compact` 了(minimal 预设不可用)。
12. 会话管理界面(`/resume`、`/home`、`/agentview`、`/bg` 或输入框行首 `⌸`):
打字筛选、`★` 固定、`Ctrl+X` 停后台会话;切换只是**停放**。
13. 回合运行中 `/compact`、`/model` 会被拒绝——先 `Ctrl+C` 或等回合结束。`/restart` 不受此门禁:它会中断当前回合(排队输入连同图片在重启后暂存,不会自动发送)并重启;若 Esc/Ctrl+C 长时间无法终止(工具没有响应中断),进程会在约 5 秒后退出并打印恢复本会话的命令,按提示重新进入即可。
14. `/model` 在同一会话内切换后续请求的模型(ID 和历史保留);选择保存为新会话默认,恢复的会话沿用其最后一次请求的路由。
**问手册**
15. 不确定某个功能怎么用,**直接问会话里的 AI**:这份手册随包发布,回答会给出处;
想明确指定走手册,可以打 `/dsh-tui-guide <问题>`。手册正文只在被问到时才读进
上下文,平时不占额度。(绕过 `dst`/`dsh-tui` 启动器、直接跑
`dsh --profile dsh-tui` 时不带手册。)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |