@michengai/dsh-codex-ui

dsh plugin --profile web add @michengai/dsh-codex-ui

<p align="center">

<img src="assets/branding/dsh-banner.png" alt="DSH Codex UI" width="100%">

</p>

<div align="center">

# DSH Codex UI v2.0

现代化 DeepSeek Harness 全方位界面增强套件：极速历史召回、全屏设置皮肤、原生物理毛玻璃换肤与模块化侧栏

[English](README.en.md) · [更新日志](CHANGELOG.zh-CN.md) · [Apache-2.0](LICENSE)






</div>

声明：DSH Codex UI 是社区维护的 DeepSeek Harness（DSH）现代化界面增强插件，并非 DeepSeek AI 官方产品。

---

为什么选择 Codex UI 2.0？

在日常使用 DeepSeek Harness 时，原生界面可能存在设置窗口狭小局促、主题配色单一、侧栏长插件列表不易整理、输入历史丢失等痛点。Codex UI 2.0 经历了从底层架构到视觉体系的全面重塑，以七大独立子插件构建起一套高性能、低侵入、官方原生的现代化界面增强体系：

• 🚀 极速输入召回与智能预测：智能行内意图预测与续写（Tab 一键采纳，Alt+↓/↑ 切换候选项），终端风格输入框历史（↑ / ↓ 快捷召回），支持自适应宽度微调；
• 🪟 全屏悬浮双岛设置：告别局促模态框，接入 Ambient Ground 漫反射画布与双岛卡片工作台；
• 🎨 物理级毛玻璃换肤：内置 7 款高品质主题配色（含 Codex 炭黑与极简纸白），支持原版平铺玻璃与云母悬浮双排版模态、三档材质预设与独立地面光斑；
• 🧭 模块化侧边栏：展开态支持原位平滑折叠抽屉与自由拖拽排序；收缩折叠态 100% 对齐宿主官方 56px 原生导轨，所有图标整齐排列、新会话常驻高对比度；
• 🧠 智能会话标题：首条消息语义解析，自动提炼精炼标题，完美适配推理大模型长上下文；
• 🖥️ 桌面原生窗口菜单：在官方桌面端系统标题栏无缝注入帮助菜单，提供原生视图刷新与跨端可靠的应用与 Host 重启能力；
• 📦 生态配套管理：官方与第三方生态插件集中看护、版本检测与一键批量升级。

---

为什么选择彻底重构？（历史演变与技术决策）

1. 早期 1.x 时代的无奈选择：“暴力覆盖组件”的技术负债

在 DeepSeek Harness（DSH）生态起步阶段，官方宿主的客户端扩展能力与基础设施尚不完善：不仅缺少细粒度的标准 Slots 插槽机制，亦未开放官方原语控件库，插件生命周期钩子也相对稀少。为了能在短时间内为开发者打造出接近 OpenAI / Codex 质感的沉浸式体验，早期 1.x 版本不得不采用了大量激进的“覆盖组件”策略：直接拦截并强行替换宿主 DOM 树、使用高权重 CSS 暴力覆盖原生视图、全量硬编码注入自定义 CSS 变量。

随之而来的维护困局：随着 DSH 官方宿主的快速迭代演进（先后引入 profile 多环境隔离体系、shortcuts 服务门控、标准 Slots 插槽注册契约以及官方原生原语库 @deepseek-ai/dsh-client-ui-primitives 等），早期“强行覆盖”的技术负债开始集中爆发，日常维护愈发举步维艰：

• 💥 版本兼容极度脆弱：宿主上游稍有 DOM 结构微调或 CSS 类名 hash 变动，就会导致覆盖式选择器失效甚至整页渲染崩溃，难以平滑跟进官方新特性；
• 🎨 样式污染与半降级顽疾：暴力注入的全局样式难以做到干净的生命周期销毁。当用户切换或关闭自定义主题时，残存的根属性与色彩变量导致原生暗色模式被严重污染，甚至出现“毛玻璃材质关闭了、但深色背景被卡死无法复原”的半降级尴尬；
• 🧩 状态脱节与“僵尸配置”：在插件或子特性被停用时，覆盖式组件无法干净退回到宿主原生外观，依然在设置面板中渲染无法生效的失效配置项，破坏了系统的整洁度与用户心智。

2. 2.0.0 的彻底重构决策：全面拥抱官方原生体系

面对维护困局，我们在 2.0.0 版本痛定思痛，彻底推翻了 1.x 的全部“组件覆盖”代码，确立了“零侵入、微内核解耦、全面拥抱官方原生”的全新技术路线：

• 🏛️ 严格复用官方原生原语与标准 Slots：坚决禁止用 CSS 自行手绘宿主已有控件，全面接入官方 Switch、SegmentedControl、Button 原生原语库；侧栏收起时 100% 严丝合缝退回官方原生 56px 导轨规范，真正做到与宿主体系同生共荣；
• 🧩 七大微内核子插件物理解耦：将臃肿的单体代码彻底拆解为 7 个高内聚、自闭环的独立子插件，彼此边界分明、支持按需独立启停，极大提升了工程可维护性与审计透明度；
• 🛡️ 严格的 Fail-Closed 熔断与动态隐匿 UI：建立标准的高可用防御契约。一旦探测到子插件在当前 Profile 被停用或服务端不可达，底层不仅物理熔断 Token 注入并彻底清空根属性，前台设置面板更会直接整体隐匿对应卡片（0 DOM 节点），绝不残留任何置灰死项，瞬间 100% 干净回退至官方原生；
• 🔒 严格 Profile 隔离与无缝自愈机制：统一权威的 Profile 路径解析，彻底杜绝跨环境串读与配置污染；同时接入 focus 窗口重获焦点自愈探活，兼顾极致安全与网络抖动下的高可用性；
• 🎨 纯正 Codex 科技蓝黑美学：彻底清洗历史残留的绿色硬编码，精准还原官方 #339cff 科技蓝、极简纸白与沉浸炭黑质感，辅以双排版模态与地面柔光反射光斑。

---

七大核心子插件架构

子插件 ID · 模块名称 · 核心能力说明

composer · 输入框增强 · 智能输入预测与行内续写（Tab 采纳、Alt+↓/↑ 候选循环）、终端风格历史记录（↑/↓）快捷召回、工作区隔离存储、自适应宽度拖拽手柄与快捷提示。

settings-skin · 原生设置皮肤 · 全屏设置工作台美化、悬浮双岛架构、Ambient Ground 自然光漫反射底板、分类导航与原生输入框搜索。

theme · 主题与界面换肤 · 内置 7 款主题配色（含 Appearance Cube 色彩方块）、原版平铺/云母悬浮双排版、三档材质预设与地面光斑开关。

sidebar · 模块化侧栏导航 · 模块化侧边栏导航、手风琴原位平滑折叠抽屉、自由拖拽排序、会话右键「标记为未读 / 标记为已读」；折叠态 100% 对齐宿主官方 56px 原生导轨。

session-title · 会话智能标题 · 基于首条消息语义提取并生成规范的会话标题，支持推理模型 4096 tokens 上下文，防止乱码截断。

desktop-menu · 桌面窗口菜单 · 官方桌面端系统原生标题栏菜单无缝增强，提供视图快速重载与跨端高可靠的应用与 Host 优雅重启。

dependencies · 配套生态管理 · 深度集成 DSH 官方与第三方生态插件集中管理，实时显示 npm 下载量、安装状态与一键批量升级。

---

真机界面预览

以下界面均使用 ego-browser 在真实的 DeepSeek Harness Web 运行环境中捕获。

1. 沉浸主界面与输入增强（深色模式）

沉浸炭黑（Codex Dark）配色，居中展示品牌标语与快捷动作引导卡片，底部输入框提供「↑↓ 翻历史」快捷召回与自适应宽度手柄。

---

2. 极简纸白主界面（浅色模式）

极简纸白（Codex Light）配色，接入 Ambient Ground 自然光漫反射渐变底板，温润通透，视觉流平滑舒缓。

---

3. 全屏悬浮双岛设置中心（模块化卡片体系）

告别局促的弹窗，重塑为模块化卡片工作台（功能与内置子插件、界面外观与换肤、配套管理插件），层次严谨秩序井然，支持根据子组件启用状态动态自适应呈现。

---

4. 界面外观换肤与毛玻璃配置

内置 7 款主题色盘（官方默认、Codex 经典科技蓝黑白、Mocha、Macchiato、Frappé、Latte），支持原版平铺玻璃与云母悬浮双模态，清透/标准/磨砂三档材质直选与地面反射光斑开关。

---

5. 模块化侧边栏导航（展开态）

支持插件、技能、常用工具（IM 助理、定时任务、归档会话、代码审查等）自由拖拽排序与「更多」手风琴平滑折叠收纳。

---

6. 官方原生 56px 折叠导轨（收缩态）

侧栏收起后自动对齐官方原生紧凑 56px 导轨规范，无缝完整显示全部功能图标，新会话常驻高亮显示，无需鼠标悬停试探。

---

7. 增强会话菜单

支持在会话项上快速执行置顶、重命名、未读标记、归档、派生新会话与安全清理。

---

宿主兼容性

• 支持范围：DeepSeek Harness 0.2.x 全系列（>=0.2.0-rc.1 <0.3.0-0）；
• 实测验证：支持矩阵为全部 0.2.x RC（0.2.0-rc.1、0.2.0-rc.2、0.2.1-rc.1～0.2.1-rc.5、0.2.2-rc.1）；中间版本阿尔法不在支持范围内；
• 环境要求：Node.js ^22.19.0 || >=24.0.0，pnpm ^11.0.0。

⚠️ 互斥提示：请勿同时启用 Codex UI 与 ds-bot。两者均重塑侧栏与主会话插槽，功能重叠。启用前请先停用或卸载另一个。

---

安装与快速上手

方式 A：让 Agent 帮您安装（推荐）

复制以下指令发送给任意具备终端执行权限的 Agent（将 web 替换为您实际使用的 profile 名称）：

请将 DSH 插件 @michengai/dsh-codex-ui 安装到本机 web profile，执行：
dsh plugin --profile web add @michengai/dsh-codex-ui@latest --registry=https://registry.npmjs.org/
安装后执行 dsh --profile web --dump-config 确认包含 codex-ui，并提示我刷新浏览器。

方式 B：终端手动安装

在终端（Windows PowerShell 或 MSYS Bash）中执行：

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8
dsh plugin --profile web add @michengai/dsh-codex-ui@latest --registry=https://registry.npmjs.org/
dsh --profile web --dump-config

安装完成后，重启 DSH Web 实例并硬刷新浏览器页面（`Ctrl + Shif

…(truncated)