琉璃 · Liuli Theme

DeepSeek Harness 的 Material Design 3 × Fluent 2 融合主题插件:取 Material 3 的 动态取色、形状系统与状态层,取 Fluent 2 的亚克力 / 云母材质与分层深度,壁纸磨砂、声纹可视化、日/夜圆形遮罩、 悬浮工具球——并打包为可独立安装、可 git 发布的浏览器插件。

包名 @deepseek-ai/liuli-theme · 版本 0.1.0 仓库:https://github.com/LilycleHeart/liuli-theme.git

预览

以下截图来自插件真实运行时的 DSH Web 界面:

开始页 · 亮色	开始页 · 暗色

动态取色变体 · 亮色	动态取色变体 · 暗色

会话页 · 暗色

设计语言:Material 3 × Fluent 2

两个体系各取所长,避免风格打架:

功能

全部设置随浏览器持久化(denpa:settings / denpa:wallpaper / denpa:header-height);DSH Desktop 因每次重启 Web 端口会变(localStorage 按 origin 隔离),还会额外同步到 Host 端 ~/.liuli-theme/settings.json,跨重启不丢失。

页面内窗口按钮(无边框模式):系统最小化/最大化/关闭三按钮移入页面——会话 header 最右端常驻、开始页兜底为标题拖拽条右上角的磨砂胶囊;动作经 Host /liuli-window 路由直驱 Electron 窗口(close 收进托盘,与原生同语义)。依赖对 DSH Desktop 的窗口参数补丁(resources/app.asar.unpacked/lib/electron-runtime-*.js 的 win32 advanced 分支:titleBarStyle: "hidden" + titleBarOverlay → frame: false),应用重启后生效;未打补丁时原生覆盖按钮仍在,页面内按钮与其并存。macOS 保持原生红绿灯不动。

供应商额度凭据

• DeepSeek：读取 DEEPSEEK_API_KEY / DEEPSEEK_OFFICIAL_API_KEY,请求 https://api.deepseek.com/user/balance 显示余额。
• OpenCode Go：读取 OPENCODE_GO_API_KEY / OPENCODE_API_KEY,请求 https://opencode.ai/zen/go/v1/usage 显示 5 小时 / 本周 / 本月套餐额度。

密钥只在 Host 侧 /liuli-quota 路由中通过 credentials/env 解析,不会进入浏览器 bundle。

安装

重要：全新 DSH Desktop 安装时，只改 cordis.patch.yml 是不够的，必须同时把 @deepseek-ai/liuli-theme 安装进 desktop profile 的 package.json 依赖，否则会报： Cannot find package '@deepseek-ai/liuli-theme'。

另外，全新 DSH Desktop 默认没有应用 win32 无边框宿主补丁，原生标题栏/窗口按钮 不会隐藏。需要额外执行 pnpm patch:desktop。

自动安装（推荐）

在插件源码目录执行：

# 1. 安装插件到 DSH Desktop desktop profile（本地源码会先 pack 成 tarball，
#    确保 iconv-lite、react 等依赖能正确装进 profile）
pnpm install:desktop

# 2. 给 DSH Desktop 打 win32 无边框宿主补丁（隐藏原生标题栏/窗口按钮）
pnpm patch:desktop

# 或等发布到 npm 后，从 npm 安装：
pnpm install:desktop:npm

pnpm install:desktop 会：

1. 把 @deepseek-ai/liuli-theme 写入 ~/.dsh/profiles/desktop/package.json 的 dependencies；
   • 本地源码模式：pnpm pack 生成 tarball，以 file:<tarball> 安装；
   • 这样插件自身的 dependencies（iconv-lite、react 等）会被装进 profile。
2. 确保 ~/.dsh/profiles/desktop/cordis.patch.yml 注册了 liuli-theme；
3. 在 desktop profile 目录执行 pnpm install。

pnpm patch:desktop 会：

1. 备份 resources/app.asar 为 app.asar.bak-frameless；
2. 修改 resources/app.asar.unpacked/lib/electron-runtime-he0yaDKX.js；
3. 重建 resources/app.asar 并同步 integrity；
4. 写入 resources/app.asar.patched。

手动安装

# 1. 进入 desktop profile
cd ~/.dsh/profiles/desktop

# 2a. 已发布到 npm：
pnpm add @deepseek-ai/liuli-theme

# 2b. 本地源码（先 pack，避免 link 导致依赖缺失）：
pnpm pack --pack-destination /tmp/liuli
pnpm add file:/tmp/liuli/deepseek-ai-liuli-theme-0.1.0.tgz

然后确认 ~/.dsh/profiles/desktop/cordis.patch.yml 里有：

- insert:
    - id: liuli-theme
      name: '@deepseek-ai/liuli-theme'

最后重启 DSH Desktop。移除该注册行即回到素版外观（shell 的外观行降级为直连切换，无圆形遮罩）。

Agent / AI 安装方式（避坑）

如果你是 AI Agent，请按下面顺序执行，避免最常见的几个坑：

1. 确定目标 profile
   DSH_HOME 默认是 ~/.dsh；DSH Desktop 的 desktop profile 位于：
   $DSH_HOME/profiles/desktop

2. 优先使用仓库自带安装器（推荐）
   cd <liuli-theme 源码目录>
   DSH_PROFILE_DIR="$DSH_HOME/profiles/desktop" node scripts/install-desktop.mjs

   它会自动完成：
   - pnpm pack 生成 tarball
   - 写入 package.json 的 dependencies（file:<tarball>）
   - 修复 cordis.patch.yml（全新 profile 的 [] 会被替换为 insert 块）
   - 在 profile 目录执行 pnpm install

3. 如果必须手动安装，不要用 link:
   # 错误示范：pnpm add @deepseek-ai/liuli-theme@link:... 
   # link: 不会安装插件自身的 dependencies，会报 Cannot find package 'iconv-lite'

   正确方式：
   cd <liuli-theme 源码目录>
   pnpm install          # 触发 prepare，构建 lib/
   pnpm pack --pack-destination /tmp/liuli
   cd "$DSH_HOME/profiles/desktop"
   pnpm add file:/tmp/liuli/deepseek-ai-liuli-theme-0.1.0.tgz

4. 只改 cordis.patch.yml 是不够的
   package.json 的 dependencies 里必须真的有 @deepseek-ai/liuli-theme，
   否则启动时报：
   Cannot find package '@deepseek-ai/liuli-theme'

5. 全新 profile 的 cordis.patch.yml 默认是 []
   不要直接在 [] 后面追加 YAML，会解析失败。
   应替换为：
   - insert:
       - id: liuli-theme
         name: '@deepseek-ai/liuli-theme'

6. 安装后不需要重启 DSH Desktop
   客户端插件安装到 profile 后，刷新页面即可加载新 bundle；不要主动重启 DSH Desktop（会改变 Web 端口并打断调试）。

7. 隐藏原生标题栏需要额外宿主补丁
   插件只能提供页面内窗口按钮，不能从渲染进程隐藏原生标题栏。
   在 DSH Desktop 安装目录执行：
   DSH_DESKTOP_DIR="C:\Program Files\DSH Desktop" node scripts/patch-desktop-frameless.mjs
   或使用仓库脚本：
   pnpm patch:desktop

8. 验证清单
   - $DSH_HOME/profiles/desktop/node_modules/@deepseek-ai/liuli-theme/lib/index.js 存在
   - $DSH_HOME/profiles/desktop/node_modules/@deepseek-ai/liuli-theme/lib/client.js 存在
   - cordis.patch.yml 包含 liuli-theme insert
   - 重启后页面出现 [data-liuli-theme] 和右侧边栏/窗口控制胶囊

依赖宿主主题服务（ctx.theme，由 dsh-client-ui-theme 提供）：偏好持久化与 theme/change 事件由宿主承担，本插件只消费。host 半（node 半）提供两条本地路由：/liuli-quota（凭据额度）与 /preview（会话 cwd 静态站点，preview 面板用）。

构建

独立仓库已自包含构建链，全新 clone 后可直接：

pnpm install   # 自动触发 prepare：tsc + tsdown，生成 lib/
# 或手动构建：
pnpm build

产出 lib/index.js（node 半）+ lib/client.js（浏览器半，closure-factory 产物）。 类型声明由 tsc -p tsconfig.json 生成到 lib/types，供 tsdown 打包入口引用。

结构

packages/client/liuli-theme/
├── package.json              # 包声明:dsh.client.inject 平台模块、exports["./client"]
├── tsdown.config.ts          # clientBundle 预设(node 半 + 浏览器半)
├── docs/
│   ├── preview-start-light.png / preview-start-dark.png   # 开始页亮/暗真实截图
│   ├── preview-color-light.png / preview-color-dark.png   # 动态取色变体亮/暗
│   └── preview-session-dark.png                           # 会话页暗色(声纹/气泡/悬浮球)
├── src/
│   ├── index.ts              # node 半:注册 /liuli-quota(凭据额度)与 /preview(会话 cwd 静态服务)路由
│   ├── invariant.ts          # 包级 invariant 伴生(无运行时检查)
│   ├── denpa-settings.ts     # 20 项设置 schema 与默认值(类型 + schemastery + 防御合并)
│   └── client/
│       ├── index.ts          # 浏览器入口:CSS 注入 + 设置分区 + 事件桥 + header slots + 悬浮球 + 预览列
│       ├── denpa.css         # 主题令牌源(亮/暗双主题 + 铬色样式 + 圆形遮罩 + 入场动画)
│       ├── denpa-css.ts      # denpa.css 的字符串化拷贝(运行时注入 <style>,幂等;含字体 @import)
│       ├── denpa-store.ts    # 设置表单 store(ui-slots EngineStore)
│       ├── denpa-palette.ts  # M3 调色板 → DSH 令牌映射(含用户气泡明暗互换)
│       ├── denpa-runtime.ts  # 设置应用运行时(isDark 竞态保护 + seq 令牌 + 壁纸承载层)
│       ├── denpa-transition.ts # 会话切换/新消息入场动画(MutationObserver 挂类 + 级联延迟)
│       ├── DenpaAppearance.tsx / .module.css   # 设置页「界面」分区
│       ├── HeaderEffects.tsx / .module.css     # 声纹/监听/主题切换/拉伸手柄(单例引擎)
│       ├── supplier-quota.ts                    # 供应商额度适配层(适配器任务列表 + 通用 settings 识别 + 控制器)
│       ├── SupplierQuota.tsx / .module.css      # header 标题区额度/余额普通文本
│       ├── TurnRail.tsx / .module.css           # DenpaPush 时间线风格轮次刻度侧边栏
│       ├── FloatBall.tsx / .module.css / .types.ts  # 悬浮工具球 + 拾取模式
│       ├── PreviewPanel.tsx / .module.css       # ZCode 侧边面板壳:标签条/概览/新增/右键菜单/空状态 + 宽度覆盖 + header 切换按钮
│       ├── RightSidebarPanels.tsx / .module.css  # 侧边面板标签内容:命令中心/文件树/Wiki/Git
│       ├── SidePaneIcons.tsx                     # 侧边面板图标(lucide 路径取自 ZCode bundle,1:1)
│       ├── right-sidebar-api.ts                  # /liuli-sidebar/* Host 数据 API
│       ├── element-picker.ts # 元素选择器:selector/文本/矩形/颜色信息提取与序列化(支持 iframe 文档)
│       ├── element-card.ts   # 用户消息中的元素引用纯文本 → 卡片 DOM(MutationObserver 装饰)
│       ├── locales.ts        # denpa-appearance 文案(zh/en,键集完整性互检)
│       └── vendor/material-color-utilities.{js,d.ts}  # Material 3 取色库(vendored)
└── README.md

与宿主 shell 的配合(官方 harness 兼容)

主题完全自包含,只在官方 harness 已有的扩展点上挂载,不依赖任何未发布的自定义 slot 或组件改动:

• dsh-client-ui-conversation:header 的 actions / utilities 两个官方 slot 是全部 header 组件的挂点(声纹、主题切换、额度、拉伸手柄、回合导轨、预览按钮——组件把内容 portal 到自己的锚点,挂载点仅作生命周期)。会话切换动画不依赖宿主挂类逻辑:插件用 MutationObserver 直接在消息列([data-chat-flow])的新增节点上挂入场类。
• dsh-client-ui-layout:悬浮球是插件自有 overlay(独立 React root + fixed 定位);右侧边栏面板占用宿主 details 布局列(priority: -1 替换官方工具详情列),随布局动画从右侧展开/收起。
• dsh-client-ui-theme:Appearance 外观行点击时 dispatch denpa:set-theme(带坐标),由本插件的事件桥接 startViewTransition 圆形遮罩;桥未就绪时降级直连切换。
• dsh-host-webserver:node 半注册 /liuli-quota 与 /preview 两条前缀路由。
• 主题观感(令牌、材质、圆角、侧栏/设置浮层样式)全部在插件的 denpa.css 内以 CSS 变量与选择器覆盖实现,不改任一宿主组件源码。

许可

MIT

Model Experience

元素选择器引用 chip

What the model sees

元素选择器生成的引用 chip 经 @ 触发源与 ReferenceCodec 序列化后插入输入框,随用户消息提交,成为该消息中的模型可见引用内容。主题视觉、声纹、壁纸与 19 项设置只影响浏览器渲染,不进入任何模型请求。

Token effect

主题本身不占用 token;仅当用户把引用 chip 作为消息发送时,chip 携带的元素文本与标识计入该条用户消息的 token。

KV Cache effect

chip 内容随用户消息成为对话前缀的一部分,与普通用户消息同样参与后续 KV 缓存;主题渲染与 denpa:* 本地设置不改变 KV 缓存。

Known Limitations and Deferred Work

• 纯浏览器插件,只在 web 平台生效;无头、ACP 等无界面的会话看不到主题效果。
• 纯 Web 部署下,设置、壁纸与 header 高度只存 localStorage,清除站点数据或更换浏览器/设备不会同步;DSH Desktop 部署会额外经 Host /liuli-settings 写入 ~/.liuli-theme/settings.json 以跨 ephemeral 端口重启保留。
• 声纹监听只捕获系统音频,不降级麦克风:Web 端依赖 getDisplayMedia 用户授权(共享「整个屏幕」并勾选「分享系统音频」);DSH Desktop(Windows)由 Host 半安装 setDisplayMediaRequestHandler 直接授予系统回环音频(audio:'loopback',点击即监听、无选择器),audio: 'loopback' 是 Electron 官方标注的 Windows-only 能力,其他平台的 Desktop 仍走默认 getDisplayMedia 行为。
• 壁纸以压缩 JPEG dataURL 持久化,受 localStorage 配额限制;超大原图会先压缩再保存。
• 会话切换动画是 DOM 观察层实现(消息节点挂类),并非宿主组件级动画:流式更新触发的部分节点重挂载也会再次入场,与宿主组件的缓存策略无关。
• 右侧边栏面板占用宿主 details 布局列,会替换官方工具详情列(工具调用详情不再显示在右侧列);/preview 与 /liuli-sidebar 路由只接受 loopback/同源 Host(局域网部署需额外配置信任域名,当前未开放该选项)。浏览器模式直接 iframe 加载 localhost/127.0.0.1 地址,若目标 dev server 未允许被 iframe 嵌入则可能显示空白;面板内的元素拾取要求 /preview 与页面同源(默认满足)。
• 会话侧栏行标记(官方 WIP 里有但未发布):官方树行不在 DOM 暴露会话 id,插件无法可靠对应具体会话,故本插件不提供该功能。