Skip to content

ccch1mneyyy/dsh-TUI / guide/dsh-tui-guide

dsh-tui-guide

Unverified

Use when the user asks about dsh-tui itself (usage, shortcuts, config, themes, migration, VS Code). Load before answering; skip for normal coding tasks.

FileKindSize
SKILL.mdskill md2.3 KB
claude-backend.en.mdmarkdown14.5 KB
claude-backend.mdmarkdown13.2 KB
cli.en.mdmarkdown9.0 KB
cli.mdmarkdown8.4 KB
codex-backend.en.mdmarkdown23.3 KB
codex-backend.mdmarkdown20.7 KB
configuration.en.mdmarkdown43.0 KB
configuration.mdmarkdown39.4 KB
getting-started.en.mdmarkdown30.9 KB
getting-started.mdmarkdown28.9 KB
interaction.en.mdmarkdown75.1 KB
interaction.mdmarkdown68.8 KB
migrate.en.mdmarkdown10.5 KB
migrate.mdmarkdown9.5 KB
plugins.en.mdmarkdown16.8 KB
plugins.mdmarkdown14.5 KB
themes.en.mdmarkdown10.3 KB
themes.mdmarkdown10.0 KB
user-guide.en.mdmarkdown80.9 KB
user-guide.mdmarkdown75.0 KB
vscode.en.mdmarkdown13.8 KB
vscode.mdmarkdown12.6 KB
# 主题系统

[文档索引](README.md) · [English](themes.en.md)

## 内置主题

dsh-TUI 内置两个色板族共六套主题,外加一个 `auto` 伪主题:

| 名称 | 族 | 用途 |
| --- | --- | --- |
| `auto` | — | 伪主题:跟随系统/终端背景,自动解析为 `light` 或 `dark` |
| `light` | 雾蓝 | 白色面板、墨色正文、雾蓝交互色 |
| `dark` | 雾蓝 | 深色终端适配,暖灰正文与柔雾蓝强调色 |
| `dark-ansi` | 雾蓝 | 16 色 ANSI 兼容回退(点火色对除外) |
| `pink-day` | 樱 | 浅色终端:淡粉面板、樱粉交互色 |
| `pink-night` | 樱 | 深色终端:暖调面板、樱粉交互色 |
| `pink-ansi` | 樱 | 16 色 ANSI 兼容回退(点火色对除外) |

两族保持相同的角色划分(浅色 / 深色 / ANSI 回退)。`auto` 只在雾蓝族内解析,
樱族需要显式选择。

未明确指定主题时,TUI 通过 OSC 11 查询终端背景,
在 `light` 与 `dark` 之间选择;终端不响应时回退到 `dark`。

浅色主题的面板与工具卡各用本族的浅色表面色(雾蓝 `light` 为纯白 `#FFFFFF`,
樱 `pink-day` 为淡粉 `#F9ECF1`;两族的输入框底色另有暖色 `#F6F3ED` / `#FBF3F0`),
图片预览一律用中性边框。深色主题及强调色保持原样。此设置不修改终端自身的背景色或壁纸。

`auto` 把这一次性启动检测变成常驻选择:

- 在 `/theme`、`DSH_TUI_THEME`、`~/.dsh-tui/theme.json` 中都是合法值。
- 选中时立即应用上次检测结果,并在后台重新查询 OSC 11。
- 跟随系统主题的终端切换深浅色后,再次选择 `auto`(或重启)即可跟上。
- `/theme status` 显示 `auto` 当前解析到的色板。
- 解析结果通过 `getTheme('auto')` 对所有消费方生效。
- 用户自定义主题若命名为 `auto`,会被内置伪主题遮蔽(选择器中不列出)。

选择优先级:

```text
DSH_TUI_THEME
  > ~/.dsh-tui/theme.json 中的持久化选择
  > OSC 11 背景检测
  > dark 回退
```

## 切换主题

- `/theme`:打开主题选择器。`auto` 与内置主题在前,
  静态 JSON 主题和插件主题在后。宽终端(≥76 列)在列表右侧并排一列实时预览:
  用**焦点行**主题的调色板实渲染代码块、代码操作工具卡与 diff——移动光标即可
  比较语法色、diff 色与工具卡底色,Enter 才真正应用;窄终端预览堆叠在列表
  下方,浮层高度不够时整块让位,列表与焦点行始终完整。
- `/theme <name>`:直接切换内置、静态 JSON 或运行时插件主题。
- `/theme status`:显示当前主题与持久化位置。

选择器确认后立即热切换,并把选择写入 `~/.dsh-tui/theme.json`。
如果设置了 `DSH_TUI_THEME`,它在下一次启动时仍然优先。

## 自定义主题

在 `~/.dsh-tui/themes/` 下放置 JSON 文件。每个文件定义一个主题,
并从一个内置色板开始覆盖:

```json
{
  "name": "sakura",
  "displayName": "樱花粉",
  "base": "dark",
  "colors": {
    "accent": "#FF9EC7",
    "accentShimmer": "#FFC0D5",
    "activity": "#7DA1DE",
    "activityShimmer": "#ABC2EC",
    "mascotBody": "#D98A63",
    "inputBackground": "#000000",
    "permission": "#FFB3CC",
    "promptBorder": "#B08B99",
    "text": "#E8E6E0",
    "inactive": "#A99BA0",
    "subtle": "#8A7A80",
    "selectionBg": "#5C3A44",
    "success": "#9CC7A8",
    "error": "#E08591",
    "warning": "#E0C08A"
  }
}
```

字段:

| 字段 | 必需 | 说明 |
| --- | --- | --- |
| `base` | 是 | `light`、`dark` 或 `dark-ansi`,作为未覆盖颜色的来源 |
| `colors` | 是 | Theme 颜色键的部分覆盖 |
| `name` | 否 | 主题 ID;缺省使用文件名 |
| `displayName` | 否 | 选择器显示名称;缺省使用 `name` |

可用颜色键按用途分组:

- 品牌/焦点/活动:`accent`、`accentShimmer`、`activity`、`activityShimmer`
- 品牌/焦点/活动(续):`suggestion`、`remember`
- 面板/边框:`permission`、`permissionShimmer`、`promptBorder`、`promptBorderShimmer`
- 面板/边框(续):`bashBorder`、`planMode`、`ide`、`background`
- 正文:`text`、`inverseText`、`inactive`、`inactiveShimmer`、`subtle`
- 工具名与状态点:`toolNameMutate`、`toolNameExec`、`toolDotExec`、`toolDotRead`
- 工具名与状态点(续):`toolDotWrite`、`toolDotWeb`、`toolDotTask`
- 工具卡衬底:`toolCardBackground`、`toolCardBackgroundDim`、`presentCardWarm`、`presentCardTint`
- 状态:`autoAccept`、`success`、`error`、`warning`、`warningShimmer`、`merged`
- diff:`diffAdded`、`diffRemoved`、`diffAddedDimmed`、`diffRemovedDimmed`
- diff(续):`diffAddedWord`、`diffRemovedWord`
- diff 语法高亮:`syntaxKeyword`、`syntaxString`、`syntaxComment`、`syntaxNumber`
- diff 语法高亮(续):`syntaxFunction`、`syntaxType`、`syntaxVariable`、`syntaxOperator`
- diff 语法高亮(续):`syntaxPunctuation`、`syntaxConstant`
- 徽标/强调:`mascotBody`、`inputBackground`、`professionalBlue`、`chromeYellow`
- 界面动画与光标:`contextBarSystem`、`contextBarPrompt`、`contextBarAssistant`
- 界面动画与光标(续):`contextBarThinking`、`contextBarTools`、`ignition`、`ignitionDim`、`cursor`
- 消息/输入:`userMessageBackground`、`userMessageBackgroundHover`
- 消息/输入(续):`messageActionsBackground`、`selectionBg`、`bashMessageBackgroundColor`
- 消息/输入(续):`memoryBackgroundColor`、`rate_limit_fill`、`rate_limit_empty`
- 消息/输入(续):`fastMode`、`fastModeShimmer`、`userPromptLabel`
- 子代理消息:`subagentBullet`、`subagentDescription`、`subagentModel`
- 子代理消息(续):`subagentElapsed`、`subagentToolName`、`subagentStatusRunning`
- 子代理消息(续):`subagentStatusCompleted`、`subagentStatusFailed`

如果文件声明了 `name`,文件名仍可作为加载别名。完整颜色键见
[`src/theme.ts`](../src/theme.ts) 中的 `Theme` 类型。

几条键的语义与默认行为:

- `contextBarSystem` … `contextBarTools`:上下文进度条的五个分段填充色,按条上顺序
  (system → prompt → assistant → thinking → tools)。静态 JSON 与插件主题都从所选
  `base` 继承这五个键;只有旧运行时解析器直接返回、缺键的色板才沿用写死的深蓝坡道。
- `ignition` / `ignitionDim`:最高思考强度档的点火动画用色——扫光波形、`❯` 前缀与档位徽标
  同源,`ignitionDim` 是波形淡出的本底色。波形逐列输出真彩色 SGR,所以这两个键要写成能解析
  出固定通道的形式(`#rgb`、`#rrggbb`、`#rrggbbaa`(alpha 会被忽略)或 `rgb(r,g,b)`);
  写成 `ansi:*` / `ansi256(n)`(或整键缺失)时**逐键**回退到按主题明暗选定的内置点火色对,
  另一个键不受牵连。
- `cursor`:无原生光标的静态呈现中,主输入框、落地页输入框及选择器搜索框绘制光标的填充色,
  也用于主输入框的图片标记焦点高亮。常规 TTY 文本输入使用原生光标,形状、颜色、闪烁与动画由终端配置控制。
  块上的字形取 `text` 与 `inverseText` 中对该填充对比度更高
  的一个(16 色的 `ansi:*` 填充,或 `text`/`inverseText` 解析不出通道的调色板,
  都量不出对比度,仍用 `inverseText`),所以浅色光标也能配深墨字形。
  内置主题留空——绘制回退采用反色块;自定义填充只影响这些绘制高亮。
- 正文链接的文字色跟随 `accent`;accent 为空或解析不出时回落到原来的固定蓝。

## npm 插件主题

npm 插件通过 `tuiThemes` 服务注册运行时主题,不必写入
`~/.dsh-tui/themes/`。最小示例:

```ts
import type { Context } from '@deepseek-ai/cordis'

export function apply(ctx: Context): void {
  ctx.get('tuiThemes', false)?.register({
    name: 'my-plugin:night',
    base: 'dark',
    colors: { accent: '#88AAFF' },
  }, ctx)
}
```

- 使用 `plugin-id:theme-id` 形式的小写安全 ID。
- `auto`、内置主题名和 `status` 是保留字,不能作为插件主题名。
- 注册随插件 activation 自动清理,返回的 disposer 可以提前注销。
- 插件主题出现在 `/theme` 选择器和补全里,名字沿用
  `~/.dsh-tui/theme.json` 持久化。
- 优先级:内置主题 > 静态 JSON > 同名插件主题。
- 旧 profile 没有 `tuiThemes` 时插件静默降级,静态主题不受影响。

完整的可覆盖键、旧键映射与注册契约见
[终端交互生态插件准入与开发指南](../tui-profile/docs/plugin-admission-and-development.md)。

## 颜色格式

支持:

- `#rgb`
- `#rrggbb`
- `#rrggbbaa`
- `rgb(r,g,b)`
- `ansi256(n)`
- `ansi:black`、`ansi:redBright` 等 16 色 ANSI 名称

颜色必须是具体值,不能使用 CSS 变量、渐变或任意 CSS 颜色名。

## 校验与失败策略

- 未知 Theme 键:跳过该键并写入警告,其余颜色继续生效。
- 非法颜色:跳过该值并写入警告。
- 非法 `base`、损坏的 JSON、非对象 `colors`:跳过整个文件。
- 环境变量或偏好文件引用不存在的主题:写入警告并继续背景自动检测。
- 一个坏主题不会阻止 TUI 启动,也不会影响其他主题。

主题名来自用户输入。加载器检查路径是否仍位于主题目录内,防止
通过名称跳出 `~/.dsh-tui/themes/`。修改这部分实现时必须保留路径约束。

## 设计建议

- 使用颜色键,而不是只替换 `text` 与 `background`。至少检查正文、
  非活动文字、焦点、选择、成功、警告、错误和 diff 色。
- 浅色主题应在真正的浅色终端验证;深色主题同理。
- 检查 16 色、256 色和 truecolor 终端的回退表现。
- 在窄终端、工具 diff、问卷、多行输入与选区状态下检查对比度。
- 不要把密钥或其他用户数据写进主题文件;主题只应包含显示元数据和颜色。

开发主题系统时运行:

```sh
node --import tsx/esm scripts/verify-themes.mjs
```

进一步的终端能力与渲染说明见[架构与限制](architecture.md)。
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 implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall