dsh-tui-theme 🌸

dsh-TUI 的樱花粉主题插件。一个包带来五种个性化，全部走官方接缝：

| 个性化 | 接缝 | 说明 | | --- | --- | --- | | 三套粉色主题 | 主题运行时（dsh-TUI ≥ 0.10.0）/ 静态资产（旧宿主） | pink-night 夜樱 / pink-day 昼樱 / pink-ansi 樱·ANSI；新宿主优先即时注册，服务晚到时短暂回退并清理本次文件，旧宿主使用 ~/.dsh-tui/themes/ | | 缓存背景跟随 | 设置 + 本地缓存 | 可选地应用已有 theme-follow.json 的昼樱/夜樱结果；不直接读取终端输入或发送 OSC 查询 | | 花符状态行 | tuiStatus | 输入框上方一行小装饰：✿ · 时钟 · 实时轮数（默认仅粉主题下显示）；dsh-TUI ≥ 0.10.1 经富状态视图按主题配色渲染，旧宿主为无色标量行 | | 设置面板 | tuiSettingsSections | /settings 里一个可编辑区块（背景跟随 / 状态行两组子页），改完即时生效 | | 屏幕提示 | tuiToast（dsh-TUI ≥ 0.10.0） | 背景跟随结果、主题文件自愈、旧文件遮蔽提醒各弹一行短提示；旧宿主自动静默降级 | | 旧文件清理 | tuiDialogs（dsh-TUI ≥ 0.9.3） | 检测到遮蔽旧主题文件时，额外提供一次性宿主确认对话框，确认后清理逐字节相同的副本；拒绝/忽略则不做任何改动 |

明确不做的事：不注册快捷键、不注册/修改任何命令、不拦截输入、不追加会话事件、不注入 system prompt（tuiDialogs 是宿主托管的中性确认面板：宿主自渲染、宿主拥有键盘，插件只提交请求，不属于输入拦截）。卸载即无痕（可选删除主题文件）。

主题预览

| 主题 | 基底 | 风格 | | --- | --- | --- | | pink-night 夜樱 | dark | 暗梅底、玫瑰粉强调，宿主 Theme 全键覆盖（0.10.x 为 73 语义键，旧键名经宿主别名映射兼容） | | pink-day 昼樱 | light | 象牙粉底、墨梅正文、柔和玫瑰强调（已通过宿主浅色身份判定） | | pink-ansi 樱·ANSI | dark-ansi | 16 色 ANSI 回退，品牌色映射到 magenta 系 |

三套均通过 dsh-TUI 官方校验器（零警告、全键覆盖）与 WCAG 对比度检查（正文 ≥ 11:1）。

截图

主题主界面截图实测于 dsh-tui 0.9.2；0.9.3 的 /settings 卡片界面见下图：

| 昼樱 pink-day | 夜樱 pink-night | | :---: | :---: | | | |

/settings 里的 pink-theme 区块（终端背景 / 花符 / 时钟 / 轮数 / 状态行展示，保存即时生效）：

图中 ❯ 提示符与链接是宿主硬编码的，见下文宿主限制。

缓存背景跟随

dsh-TUI 没有向插件公开安全的终端查询接缝。为了不与宿主的 stdin/raw-mode 生命周期竞争，插件不会直接发送 OSC 11，也不会读取终端输入。

“应用上次保存的终端背景”开启后：

• 启动时读取 ~/.dsh-tui/theme-follow.json 中已有的 light 结果，亮 → pink-day，暗 → pink-night，并将选择写入 ~/.dsh-tui/theme.json；
• 不存在缓存时完全保留当前 /theme 选择；插件不会自行创建或刷新缓存；
• 默认关闭。该缓存可由之前的兼容版本留下；未来 dsh-TUI 提供宿主拥有的查询接缝后，插件才会安全地恢复刷新能力；
• 开启后该缓存会在启动时覆盖 /theme 的持久选择；关闭即可恢复手动选择；
• DSH_TUI_THEME 环境变量仍然最优先（宿主行为，插件不覆盖环境变量）。

dsh-TUI ≥ 0.10.0 上，跟随结果会以 toast 短提示呈现：真正改写了 theme.json 时提示「已按保存的终端背景改用 …，/reload 即时生效」（当前画面仍显示旧主题，/reload 或重启后生效）；在 /settings 里手动开启但无缓存时如实提示「没有保存的终端背景缓存」。启动基线未变化时保持安静，避免每次开机重复打扰。

屏幕提示（toast）

插件日志对 TUI 用户不可见，因此少数值得知道的事件会走宿主 toast（dsh-TUI ≥ 0.10.0 的 tuiToast 接缝，纯输出、不拦截任何输入；旧宿主没有该接缝，自动退回纯日志行为）：

| 事件 | 提示 | | --- | --- | | 背景跟随改写了主题偏好 | ✿ 已按保存的终端背景改用 …，/reload 即时生效 | | 手动开启跟随且缓存与当前一致 | ✿ 已按保存的终端背景保持 … | | 手动开启跟随但无缓存 | ✿ 没有保存的终端背景缓存，保持当前主题（警告色） | | 主题文件损坏被自动修复 | ✿ 已修复损坏的主题文件：…（警告色） | | 旧版遗留的同名主题文件与内置版本完全相同 | ✿ … 与插件内置相同，删除后配色将随插件自动更新 |

最后一条只针对与内置副本逐字节相同的文件——你手动调过色的文件永远不会被提及或删除。遮蔽场景还会在支持该接缝的宿主上（dsh-TUI ≥ 0.9.3）提供一次性确认对话框：确认后插件按同样的逐字节校验清理副本并以 toast 反馈结果，拒绝/忽略则一切维持现状。

安装

# 方式一：从 npm（已发布）
dsh plugin --profile dsh-tui add -w dsh-tui-theme@latest

# 方式二：本地 tarball（开发/自用；不要直接安装源码目录）
cd /path/to/dsh-tui-theme
npm run build
npm pack
dsh plugin --profile dsh-tui add -w ./dsh-tui-theme-<版本号>.tgz

不要以本地源码目录作为依赖安装：其开发 node_modules 可能与 dsh-TUI 宿主解析出不同的 Cordis/DSH framework instance，造成插件无法注册服务。

升级

# npm 已发布版本：请求最新版本并刷新 profile 依赖
dsh plugin --profile dsh-tui add -w dsh-tui-theme@latest

在 dsh-TUI ≥ 0.10.0 中，三套主题通过 ctx.tuiThemes 运行时注册：调色板随插件即时生效，正常挂载时不写入用户目录，主题选择器显示中文 displayName。若服务晚到，插件会先同步回退到静态路径，并在确认运行时服务后删除本次写入且仍未被改写的文件。旧宿主使用静态文件路径：插件只在主题文件缺失时复制，绝不覆盖你编辑过的 ~/.dsh-tui/themes/pink-*.json。唯一的例外是已损坏的目标文件（无法解析为 JSON，例如安装中途中断留下的残文件）：插件会把它改名为 <文件名>.corrupt-<时间戳> 保留现场，再重新安装内置副本，记录一条警告，并在支持 toast 的宿主上弹一条屏幕提示。

从旧宿主升级后，若希望改用运行时托管，请先备份并删除 ~/.dsh-tui/themes/pink-{night,day,ansi}.json；插件不会自动删除用户文件。遗留文件若与内置副本完全相同，插件会在运行时托管确认时弹一条一次性提醒，并额外提供一次性确认对话框（宿主 tuiDialogs 面板）：确认删除则清理这些遮蔽副本，拒绝或忽略则不做任何改动；你手动调过色的文件永远不会被提及或删除。

旧宿主重启 dsh-TUI 后插件会把三套主题复制进 ~/.dsh-tui/themes/（仅缺失时复制，绝不覆盖你已有的同名文件）；0.10.0 及更新宿主则直接使用运行时注册，然后：

# 在 dsh-TUI 里
/theme              # 选择器：夜樱 / 昼樱 / 樱·ANSI
/theme pink-night   # 或直接切换（开启跟随后由插件接管）

配置

配置有三层，优先级：/settings 用户层 > cordis.yml 配置层 > 内置默认值。

/settings 里找到 pink-theme 区块即可编辑（分「背景跟随」「状态行」两组子页）：

| 字段 | 默认 | 说明 | | --- | --- | --- | | followSystem | false | 启动时应用上次保存的终端背景结果（昼樱 ↔ 夜樱）；插件不刷新缓存。开启时该字段会直接显示缓存状态，如 on（缓存: light · 2026-09-12） 或 on（无缓存，启动时不动） | | showGlyph | true | 花符开关：开 = 以花符开头，关 = 不显示 | | statusGlyph | ✿ | 花符字符（文本字段）：1–2 个显示单元、不接受控制字符，留空恢复默认 | | showClock | true | 显示 HH:MM 时钟 | | showTurns | true | 显示当前会话轮数（N✦，自本次启动起计） | | statusSeparator | · | 各段之间的分隔符（文本字段）：同花符字符的校验规则 | | statusScope | pink-only | 状态行展示：pink-only 仅樱花粉主题 / all-themes 所有主题 |

三项装饰全关时状态行整体消失。另有仅 profile 层的开关（cordis.patch.yml，不出现在 /settings）：autoInstallThemes、statusEnabled。

受宿主限制、目前无法定制的部分

以下元素的颜色/形态由 dsh-TUI 宿主硬编码，不读取任何主题键，主题 JSON 与插件接缝都覆盖不到（dsh-TUI 0.9.3 实测）：

| 元素 | 现状 | 位置（宿主源码） | | --- | --- | --- | | 输入框 ❯ 提示符 | 默认态无颜色参数（终端默认前景色，模型工作时变暗）；最高推理档充能动画用写死的蓝色 ramp（深色端 #82B9FF / 浅色端 #1E5FEB） | EffortChargeGlyph.tsx、trajectory/effortIgnition.ts | | 底栏上下文进度条分段色 | system / prompt / assistant / thinking / tools 五段为写死的藏青→品牌蓝系（#22305F→#5A7CFF），永远不随主题变化 | screens/StatusMetrics.ts | | 进度条空余段配色 | 宿主按 themeName === 'light' 字符串比较取浅色配色——自定义浅色主题（如 pink-day）不等于 'light'，会拿到深色空余段，在浅色终端上偏深 | screens/StatusLine.tsx | | 状态行文字颜色 | 旧路径标量状态行（tuiStatus.set）由宿主统一以无色 + 终端 dim 渲染；dsh-TUI ≥ 0.10.1 插件已改用 tuiStatus.registerView 富状态视图按主题配色渲染（✿ 品牌色 / 正文 text 色 / 分隔符 subtle 色，颜色取自生效主题文件，pink-ansi 为具名 ANSI 值），旧宿主自动回退标量路径（无色 + dim） | screens/Chat.tsx、dsh-adapter/status.ts | | 输入框块状光标 | 宿主挂载期间隐藏终端原生光标（?25l），输入框光标由应用以反色字符自绘（<Text inverse>），颜色即主题 text/background 的反色——OSC 12 光标色只能染到不可见的原生光标，插件无法给输入光标上色（辅助功能模式 CLAUDE_CODE_ACCESSIBILITY=1 下原生光标才可见） | ink/components/App.tsx、components/PromptInput.tsx | | 正文链接 | OSC 8 超链接默认写死的 ANSI 蓝（chalk.blue）；注释说明 wrap-ansi 无法跨 OSC 8 保留主题 RGB 色，故链接色不读主题键 | cc/hyperlink.ts | | 顶栏像素鲸鱼颜色 | 四色调色板（描边/身体/腹部/嘴）写死且模块加载时预渲染，不读取任何主题键——任何主题都无法改变鲸鱼配色 | components/Whale.tsx | | 顶栏文字色 | ✦ dsh-TUI 字标与欢迎语经 claude（0.10.1 起 accent）跟主题；DEEPSEEK 像素字主色与渐变结尾色分别跟 claude / claudeBlue_FOR_SYSTEM_SPINNER（0.10.1 起 accent / activity）；HARNESS 像素字只有主色跟主题——渐变结尾色是宿主固定常量 PALE，不读任何主题键，主题覆盖不到它的结尾段；两词的扫过高光（FLASH）同为宿主常量。另：宿主 parseRGB 只认 rgb(r,g,b) 格式，hex/ansi 值会静默回退固定品牌蓝（pink-ansi 因此顶栏仍为蓝色） | components/LogoV2.tsx、components/bigfont.ts、components/shimmer.ts、components/Spinner/spinnerUtils.ts | | 主界面组件与布局 | 顶栏像素鲸鱼、工具卡、输入框等宿主组件不可被插件替换或改布局——平台规则（内建优先，无组件替换接缝）；主题能碰的只有颜色层 | 宿主架构约定 |

这些都需要上游 dsh-TUI 修改（例如：把充能色/进度条分段色接入主题键、空余段判断改用 isLightThemeActive()、给输入光标增加主题键）。上游修复前，任何社区主题包都受同样约束。

卸载

# 先在 dsh-TUI 内切换到非 pink-* 主题，例如：
/theme auto

# 再移除插件和可选的本地主题资产
dsh plugin --profile dsh-tui remove -w dsh-tui-theme
rm ~/.dsh-tui/themes/pink-{night,day,ansi}.json
rm ~/.dsh-tui/theme-follow.json

开发

npm install --include=dev   # 见下方安装前提，本仓不提交 lockfile
npm run build
npm run verify
npm run verify:package
DSH_TUI_ADAPTER_DIR=/path/to/dsh-TUI/lib/types/dsh-adapter \
DSH_TUI_SOURCE_ROOT=/path/to/dsh-TUI-source \
npm run verify:host

安装前提（这两条会让普通 npm install 失败或静默不装依赖）：

• 本仓有意不提交 package-lock.json。 devDependency 里的宿主 tarball 内嵌 @dsh-std/*，其包内 manifest 仍声明 workspace:*；提交的 lockfile 会被 npm 忠实重放，于是 npm install 与 npm ci 都报 EUNSUPPORTEDPROTOCOL。删掉 lockfile 后 npm 会直接跳过 tarball 内的 bundle 目录，正常安装。请勿把 lockfile 提交回来（CI 的 contract 档会直接拦下）。
• 安装时不要带 NODE_ENV=production。 该变量会让 npm 按 omit=dev 静默省略 devDependencies，表现为 up to date 但 node_modules 为空、随后 tsc 找不到。所以显式写 --include=dev（CI 里另外固定 NODE_ENV=development）。

verify:host 默认使用开发依赖中的 dsh-TUI（当前为 0.10.1）进行零配置验证，无需本地宿主源码检出；需要验证旧版或发布基线时，再显式指向同一版本的宿主 adapter 与源码。需要锁定版本时，额外设置 DSH_TUI_EXPECTED_VERSION。CI 只覆盖这条 0.10.1 零配置线，0.9.x 兼容回归仍需本机按上面的 env 指向对应宿主 worktree。

主题调色板改起来最直接：编辑 themes/*.json 后重新 npm run verify，再删掉 ~/.dsh-tui/themes/ 下对应文件让插件重装。

兼容性

• dsh-TUI 版本下限：0.8.8（状态行与设置面板；0.9.3 实测）。0.10.0 及更新版本使用运行时主题注册；0.10.1 起状态行经富状态视图按主题配色（更旧宿主自动回退无色标量行）；更旧的宿主缺 dsh-tui-extensions 扩展面时，插件自动降级为“仅安装三套主题”，不报错。
• Node ^22.19 || >=24，纯 ESM，MIT。