@shuaihaov/dsh-theme-wandering-earth-2

Readme

# The Wandering Earth II · 流浪地球2 — DSH Web 主题

为 DeepSeek Harness (DSH) Web GUI 打造的《流浪地球2》电影风格主题插件包：深空底舱配色、行星发动机等离子蓝、MOSS 红光点缀；AI 生成的行星发动机插图沉底展示，随会话运行状态点火/熄火联动，叠加星场 HUD 氛围层。

- **包名**：`@shuaihaov/dsh-theme-wandering-earth-2`
- **部署形态**：静态 Web 插件包，经 `~/.dsh/profiles/web`（`dsh plugin add` 安装 + `cordis.patch.yml` insert 行）持久挂载——DSH 重启自动加载，效果常驻
- **AI 协作开发规范**：见 [`AGENTS.md`](./AGENTS.md)（硬性约束、工作流、踩坑档案）

## 效果预览

![DSH Web GUI 效果截图](./assets/screenshot.png)

*`assets/screenshot.png`（2998×1620 全窗口截图）：深色模式下完整主题效果——行星发动机插图沉底、星场 HUD 氛围层、MOSS 化发送按钮。*

## 快速开始（安装）

**前置条件**：已完成 DSH 安装与初始化，Web GUI 可访问（默认 `http://127.0.0.1:3080`）。下述 `<repo>` 为克隆本仓库的本地路径，`<profile>` 为 DSH 的 web profile 目录（默认 `~/.dsh/profiles/web`）。

### 1. 安装依赖（一条命令）

```bash
dsh plugin --profile web add https://github.com/shuaihaoV/dsh-TheWanderingEarthII
```

`dsh plugin add` 是 pnpm add 的封装，支持任意 pnpm 可解析的来源：GitHub URL、`github:owner/repo`、本地 `link:` 路径等，依赖自动写入 `<profile>/package.json`。

### 2. 注册插件行

编辑 `<profile>/cordis.patch.yml`，追加：

```yaml
# The Wandering Earth II theme: cinematic HUD + sunken planet-engine artwork
- insert:
    - id: theme-wandering-earth-2
      name: '@shuaihaov/dsh-theme-wandering-earth-2'
```

### 3. 重启 DSH 生效

完全退出 DSH 进程后重新启动——插件的 `insert` 行随 profile 自动加载。**无需在设置里手动选主题**：配色经 `theme.overrideTokens` 叠加层常驻压在任何主题之上，装好即生效。

### 验证

```bash
curl -sI http://127.0.0.1:3080/twe2-assets/moss-eye.jpg   # 期望 HTTP 200 + image/jpeg
```

浏览器打开 Web GUI：输入框底部透出行星发动机插图、发送按钮呈 MOSS 眼形态，即主题已加载；发送消息后发动机点火（蓝色光柱），停止后熄火。

### 卸载

1. 删除 `<profile>/cordis.patch.yml` 中的 `theme-wandering-earth-2` insert 段
2. `dsh plugin --profile web rm @shuaihaov/dsh-theme-wandering-earth-2`
3. 重启 DSH

## 特性总览

| 特性 | 说明 |
| --- | --- |
| 发动机插图沉底 | `body::before`（z-index: -1）承载竖版透明行星发动机插图，从输入框与文字底部透出，不遮挡交互 |
| 点火状态桥 | 会话 running = 蓝色等离子光柱喷射形态（burn）；停止 = 喷口泛微弱蓝辉光形态（idle）；切换经 1.2s cross-fade 过渡 |
| 双色模式 | 深色 = 深空黑夜版插图；浅色 = 白昼光照版专用插图（避免黑底去背图在浅底呈脏灰边） |
| 粒子蔓延 | burn 时快速亮蓝火星（4.2s 上升循环）；idle 时慢速淡蓝微粒（9.5s） |
| 星场 HUD | 顶层 `body::after`：顶部能量线 + 左右舷窗刻度尺 + 星点 + 蓝图网格（常显） |
| MOSS 化发送按钮 | shell 发送/停止主按钮纯 CSS 换肤为 MOSS 眼：停止/空闲 = 灰色，输入就绪 = 蓝光无动效，运行中 = 蓝光呼吸动效；点击行为保留原按钮 |
| 内容工业化 | caret 发动机蓝、kbd 金属键帽、表格蓝色细分隔线、pre 控制台面板化、hr 能量分隔线、blockquote 情报框 |
| 常驻不失效 | 配色经 `theme.overrideTokens` 叠加层压在任何当前主题之上——外观切换、页面刷新均不影响 |

## 架构

```
┌─ Host 半  src/index.js ──────────── 直接加载（无需构建）
│    inject: ['webServer']
│    注册 /twe2-assets/* 前缀路由 → serve assets/ 内 PNG/JPG
│
├─ Client 半 src/client/index.js ──── 源码（人改这里）
│    inject: ['theme', 'slots']
│    overrideTokens 配色 + HUD CSS + EngineBeacon 状态桥 + MOSS 眼
│         │
│         ▼ pnpm run bundle（scripts/build.mjs，零依赖）
│    lib/client.js ────────────────── 构建产物（机生成，勿手改）
│         │
│         ▼ window.__ModuleLoader__.load({ id, factory })
│    浏览器加载执行
│
└─ assets/ 插图 ← .tmp/ 生成管线产出（genimg*.py 生成 + cutout*.py 去背）
```

### 目录结构

```
├── package.json        # 包声明 + dsh.client platform:web + bundle 脚本
├── src/
│   ├── index.js        # Host 半：/twe2-assets/* 白名单静态路由
│   └── client/index.js # Client 半源码：配色 + HUD 样式 + 状态桥 + slots
├── scripts/build.mjs   # 零依赖构建：包装为 __ModuleLoader__ handoff
├── lib/client.js       # 构建产物（pnpm run bundle 重新生成）
├── assets/             # 去背插图 + 效果截图（由 Host 半路由 serve）
├── refs/               # MORE VFX 概念参考图（版权原因不入库，本地保留）
└── .tmp/               # 生成管线（gitignore：脚本含 API key、raw/ 为原图库）
```

### 部署链路

```
本仓库 ──link:──▶ ~/.dsh/profiles/web/package.json（dependencies）
              ~/.dsh/profiles/web/cordis.patch.yml
                └─ insert: theme-wandering-earth-2 行 ──▶ DSH 启动加载
```

## 工作原理

**Host 半**（`src/index.js`，组合行加载的 ESM cordis 插件）：`webServer.register({ kind: 'prefix', path: '/twe2-assets' })` 白名单静态路由。文件名校验为「小写 slug + png/jpg 扩展名」正则（`ASSET_NAME`），query string 在匹配前剥离（兼容 `?v=` cache-busting），路径穿越不可能；assets 目录从 `import.meta.url` 相对解析，包可任意 link 移动。**必须声明 `export const inject = ['webServer']`**——本行位于组合树尾部，fiber 激活早于 webServer 服务注册，`ctx.get` 竞态落空会导致路由静默缺失（v7.1 实测坑）。

**Client 半**（`src/client/index.js` → bundle 成 `lib/client.js`）：

1. **声明 `inject: ['theme', 'slots']`**（同理：fiber 激活可能早于 theme 服务注册，竞态落空会让主题静默不注册——v7.2 实测坑）
2. **配色经 `theme.overrideTokens` 常驻叠加**——不走主题注册：DSH 外观偏好经 zod 枚举只持久化内置 light/dark/system 三选（AppearanceRow 硬编码三选，不读主题注册表），第三方主题 `setTheme` 只改内存不写 settings，刷新即回落；override 层压在任何当前主题之上，切换外观、刷新页面效果均不消失。每个 token 给 `{ light, dark }` 双值（运行时校验，裸字符串抛错），浅色外观自动切「冰原白昼版」槽位
3. **插图沉底**：`--dsw-alias-bg-base` / `sidebar-fill` 半透明化 + `html` 深底色兜底；插图从输入框与文字**底部**透出
4. **状态桥**：`EngineBeacon`（`shell.overlay` slot）用 `useSessions` 读当前会话 `running`，经 `theme.overrideTokens` 把 `--twe2-engine-img` / `--twe2-glow` 写到 body inline token，驱动沉底层换图与光晕变色
5. **切换过渡**：`body::before` 的 `transition: background-image 1.2s ease-in-out`——变量换图触发 cross-fade，光晕颜色同步插值渐变；双态插图（双色共四张）预载避免首次切换闪跳
6. **粒子蔓延**：CSS 点阵动画 + mask 限制在右侧发动机上方区域
7. `body::after` 顶层：边缘 HUD（能量线/刻度尺）+ 星场 + 蓝图网格（常显，浅色模式下星点反转为深空蓝尘）
8. **MOSS 化发送按钮**：shell 的发送/停止主按钮经纯 CSS 换肤为 MOSS 眼（详见下方「MOSS 化发送按钮」节）
9. **浅色模式适配**：token 双槽位 + CSS 浅色覆盖段（钩子 `body:not([data-ds-dark-theme])`，由 theme presenter 按当前 colorScheme 写入）

## MOSS 化发送按钮（v7.9）

shell 的发送/停止主按钮是硬编码 chrome，无替换 slot；`conversation.input.right` 只给只读 props（拿不到 submit/stop 动作）。故采用**纯 CSS 换肤**：

| 状态 | DOM 特征 | CSS 锚点 | 视觉 |
| --- | --- | --- | --- |
| 空闲（草稿空） | send 形态 + `:disabled` | `:disabled` | 灰色 MOSS（grayscale） |
| 输入就绪 | send 形态 + enabled，SVG 内为 `<path>` | `:has(svg path):not(:disabled)` | 蓝光无动效 |
| 运行中 | stop 形态，SVG 内为 `<rect>` | `:has(svg rect)` | 蓝光呼吸动效（1.6s） |

实现要点：

- 类名锚点 `[class*="_trailing"] [class*="_primary"]`——CSS modules 类名带构建 hash（如 `uV2eYG_primary`），本地名 `_primary` 子串跨构建稳定
- 原 SVG 图标 `display: none`，`background-image: var(--twe2-moss-url)`（token 注入，URL 自带 `?v=` cache-bust）
- 点击行为完全保留 shell 原按钮（不劫持、不重建）
- **坑**：shell 的 hover 规则用 `background` 简写（特异性更高），会把背景图重置为 none——hover 态必须重申 `background-image`
- 浅色模式保留呼吸动效，蓝系换 `#0B7FDA`、光晕收敛

## 意象取色

| Token | 深色值 | 浅色值 | 电影意象 |
| --- | --- | --- | --- |
| `--dsw-alias-bg-base` | `rgba(7,11,20,.48)`* | `rgba(226,234,246,.55)`* | 深空 / 冰原白昼 |
| `--dsw-alias-bg-layer-1` | `#0C1322` | `#EDF2FA` | 领航员空间站舱体 |
| `--dsw-alias-bg-layer-2` | `#121B2E` | `#E2EAF6` | 控制台面板 |
| `--dsw-alias-bg-overlay` | `#18243C` | `#F7FAFE` | 全息投影层 |
| `--dsw-alias-border-l1` | `#233350` | `#C6D3E8` | 金属接缝 |
| `--dsw-alias-border-l2` | `#35496F` | `#A4BAD9` | 结构框架 |
| `--dsw-alias-brand-primary` | `#35A8FF` | `#0B7FDA`** | 行星发动机等离子焰 |
| `--dsw-alias-label-primary` | `#DCE9F8` | `#1B2740` | 舱内冷白照明 |
| `--dsw-alias-label-secondary` | `#8098BC` | `#5C6E8E` | 金属铭牌灰蓝 |
| `--dsw-alias-state-error-primary` | `#FF4D3D` | `#E03A2C` | MOSS 红眼 |
| `--dsw-alias-state-success-primary` | `#2FD4A0` | `#14966F` | 系统正常青绿 |
| `--dsw-alias-state-warn-primary` | `#FFA62B` | `#D98A00` | 预警橙 |
| `--dsw-specific-sidebar-fill` | `rgba(9,15,27,.60)`* | `rgba(228,236,248,.68)`* | 侧舱 |

\* 半透明化以透出沉底插图。 \*\* 浅底加深保对比度。

## 插图资产（assets/）

由 Right Code 平台 `nano-banana-2`（gemini-3.1-flash-image）生成，原图存 `.tmp/raw/`，`assets/` 内为去背透明版（PIL）：

| 文件 | 用途 | 内容 |
| --- | --- | --- |
| `engine-burn.png` (768×1376 透明) | 会话运行中（深色模式） | 完整展开的行星发动机沉底，喷口喷射**蓝色等离子光柱持续贯穿至画面顶部** + 火星 |
| `engine-idle.png` (768×1376 透明) | 会话停止（深色模式） | **burn 同机位同构图的熄火版**：光柱熄灭，喷口内仅泛微弱蓝色辉光 + 少量光粒子升腾消散 |
| `engine-burn-light.png` (768×1376 透明) | 会话运行中（浅色模式） | 白昼光照版 burn：高饱和蓝光柱在浅底下依然醒目 |
| `engine-idle-light.png` (768×1376 透明) | 会话停止（浅色模式） | 白昼光照版 idle：burn-light 同构图熄火版 |
| `moss-eye.jpg` (288px) | 状态点 | MOSS 白色机身 + 红色独眼 |
| `space-elevator.jpg` (832px) | 备用素材 | 地球 + 太空电梯 + 发动机蓝色尾焰 |

**发动机形态对齐电影设定**：扁平穹顶 + 辐射状拱形支撑腿（参考 MORE VFX 官方概念图；本地存于 `refs/`，因版权不入库）。

**生成管线要点**（详见 `AGENTS.md`）：

- **单一参考链原则**——idle 版以同代 burn 版为唯一参考生成（仅熄灭光柱）；历史双参考链导致机位/色调漂移，已废弃
- 深色底图黑底亮度法去背（`cutout.py`）；浅色底图按与背景色的欧氏色差去背（`cutout_light.py`，亮度法会误伤亮蓝光柱）
- 去背 `max_size ≥ 1400` 保全分辨率（CSS `auto 100vh` 渲染，低分辨率被放大会模糊）
- `src/client/index.js` 中 `TWE2_ASSET_VER` 为 `?v=` cache-busting 版本号：**每次更新 assets/ 图片后必须 bump 并 `pnpm run bundle`**

## 使用与维护

**首次安装已完成**（本仓库经 `link:` 挂载进 `~/.dsh/profiles/web`，patch 含 `theme-wandering-earth-2` insert 行）。日常操作：

| 操作 | 命令/路径 |
| --- | --- |
| 启用主题 | **无需操作**——安装即启用且常驻：overrideTokens 叠加层压在任何当前主题之上，外观切换、页面刷新都不影响 |
| 更新 Client 样式/逻辑 | `pnpm run bundle` 后刷新页面（bundle 自动 cache-bust） |
| 更新 assets 图片 | 替换文件 → bump `TWE2_ASSET_VER` → `pnpm run bundle` → 刷新 |
| 更新 Host 半路由 | 编辑 `src/index.js` → 重启 DSH |
| 验证插图路由 | `curl -sI http://127.0.0.1:3080/twe2-assets/moss-eye.jpg`（应 200 + `image/jpeg`） |
| 停用 | `~/.dsh/profiles/web/cordis.patch.yml` 删除对应 insert 段，重启 DSH |

## 演进记录

- **v0.0.1**：首次 GitHub 公开发布——README 增加「效果预览」截图（`assets/screenshot.png`）；`refs/` 外部概念参考图因版权原因明确不入库；包版本号统一为 0.0.1