dsh-theme-endfield 1.2.2 → 1.2.4

package/README.md

@@ -1,22 +1,12 @@
 # dsh-theme-endfield
 
-参考《明日方舟：终末地》官网风格的 DSH Web 主题插件。
+参考《明日方舟：终末地》官网风格的 DSH Web 主题插件：奶油纸底、墨黑文字、信号黄／武陵青强调色、全直角工业编辑风。
+<img src="docs/preview.gif" alt="dsh-theme-endfield" width="720">
 
-奶油纸底、墨黑文字、信号黄/武陵青强调色、全直角工业编辑风。Client 侧（`client.js`）通过主题令牌和样式覆盖界面；Host 侧（`index.js`）负责设置持久化与可选的音频通知（派生系统播放器子进程），均不修改应用代码。
+- **Client 侧**（`client.js`）：通过主题令牌与样式覆盖界面。
+- **Host 侧**（`index.js`）：设置持久化与可选的音频通知（派生系统播放器子进程）。
 
-## 版本支持
-
-| DSH | 设置持久化 | 备注 |
-| --- | --- | --- |
-| **0.2.x**（在 **0.2.0-rc.2** 上实测） | Host 导出 `Config`，浏览器 `ctx.configForms` | 当前支持目标 |
-| 0.1.7 – 0.1.x | 同一套 Config/configForms 接缝 | 无需改动 |
-| ≤ 0.1.5 | `ctx.settings.register` + `ctx.settingsScope` | 自动回落，无需配置 |
-
-0.2 改动了三处本插件依赖的应用侧细节，本次已跟进（都验证过「旧写法在 0.2 上静默失效」）：
-
-- **回合状态标签**（“Deep diving…”）从 `@deepseek-ai/dsh-client-ui-conversation` 的**渐变文字**搬到 `@deepseek-ai/dsh-client-ui-chat` 的**遮罩扫光文字**，不再有 `turnStatus` 类名，着色改由 `--dsw-alias-label-deep-diving` / `-shimmer` 两个令牌承担，所以旧规则已删除、改在 `theme.overrideTokens` 层换色（实测：留着旧规则时该令牌仍是应用自带值，标签完全没有主题色）；
-- **右侧栏**列名由 `_detailsCol` 改为 `_rightbarCol`，且不透明底色移到列元素本身——等高线图层在右侧栏打开时不会再被整块盖住；
-- **插件卡片展示文案**改由 `locale/<语言>.json` 的 `meta.title` / `meta.description` 提供；`package.json` 的 `dsh.client.inject` 也不再列 0.2 已删除的 `@deepseek-ai/dsh-client-runtime` 与 `@deepseek-ai/dsh-client-ui-slots`（改为列出 0.2 真正的提供方）。
+两侧都不修改应用自身代码。
 
 ## 安装
 
@@ -24,30 +14,67 @@
 dsh plugin --profile web add github:ymh0000123/dsh-theme-endfield
 ```
 
-重启或重新加载 `web` profile 后生效。**更新插件文件时注意**：Client 半（`client.js`）由 Host 按请求从磁盘读取，浏览器刷新即可生效；Host 半（`index.js`）只在 profile 启动时 import 一次，**必须整进程重启 DSH** 才会重新加载（`dsh-hmr` 的 watch 默认忽略 `**/node_modules`，软链安装的仓库文件不在其观察范围内）。只刷新页面时，运行的仍是启动时那份 Host 代码。卸载：
+重启或重新加载 `web` profile 后生效。卸载：
 
 ```bash
 dsh plugin --profile web rm dsh-theme-endfield
 ```
 
+### 更新插件文件时的加载时机
+
+| 改动 | 生效方式 |
+| --- | --- |
+| Client 半 `client.js` | Host 按请求从磁盘读取，浏览器刷新即可 |
+| Host 半 `index.js` | 只在 profile 启动时 import 一次，**必须整进程重启 DSH** |
+
+`dsh-hmr` 的 watch 默认忽略 `**/node_modules`，软链安装的仓库文件不在其观察范围内；只刷新页面时，运行的仍是启动时那份 Host 代码。
+
 ## 功能
 
-在 **设置 › 终末地主题设置** 中调整：
+开关集中在 **设置 › 终末地主题设置**：
+
+- **主题**：总开关、谷地黄／武陵青配色、直角／圆角模式。
+- **背景**：等高线背景（默认关闭）及动态开关、`24 / 60 / 120 FPS`、速度 `1x / 2x / 4x`；可选鼠标轨迹（鼠标附近的等高线局部变形并逐渐恢复，默认关闭）；背景水印及持续显示。
+- **动画**：输出滚动动画（默认开启，强度分 `柔和 / 标准 / 轻快`）——把模型流式输出的「整段跳一大格」摊成逐帧滑动，不改动应用自己的滚动位置，因此跟随不会中断，向上滚动、读者手势与系统「减少动态效果」下都保持瞬时；启动加载动画。
+- **娱乐**：雷霆大字及入场动画；顶部余额胶囊（默认关闭）。
+- **音频**：启动音、任务开始／结束音、需要回应时提示，音量与自定义音效目录可调（默认关闭）。
+
+几处需要单独说明的行为：
+
+- **顶部余额胶囊**：悬浮显示 DeepSeek API 余额与峰谷时段（高峰为工作日 `9-12` 点、`14-18` 点；周末、法定节假日与落在周末的调休日都按低谷半价）。会话使用 [dsh-codearts-auth](https://www.npmjs.com/package/dsh-codearts-auth) 渠道模型时自动切换为该渠道的剩余额度与积分消耗进度，随渠道切换实时跟随，主读数可在设置中选择右侧百分比显示剩余或已用。
+- **输出滚动动画**与**渠道额度模式**的完整行为、默认值与边界情况见 [docs/features.md](docs/features.md)。
+- **音频通知**的防噪规则与自定义音效见 [docs/audio-notifications.md](docs/audio-notifications.md)。
+
+所有设置由 DSH 自己的设置服务持久化，与页面 origin／端口无关，DSH web 与 DSH Desktop 都能正确保存并在重启／换端口后恢复（不再使用会被 Desktop 随机端口清空的 `localStorage`）。设置文案支持中英文；动态等高线尊重系统「减少动态效果」，动画帧率与速度可独立调整。
 
-- 主题总开关、谷地黄/武陵青配色、直角/圆角模式；
-- 等高线背景、动态开关、`24 / 60 / 120 FPS`；
-- 等高线速度 `1x / 2x / 4x`；
-- 可选鼠标轨迹：鼠标附近的等高线局部变形并逐渐恢复，默认关闭；
-- 背景水印及持续显示；
-- 输出滚动动画：模型流式输出时把「整段跳一大格」摊成逐帧滑动（默认开启，强度分 `柔和 / 标准 / 轻快` 三档）；不改动应用自己的滚动位置，因此跟随不会中断，向上滚动、读者手势与系统「减少动态效果」下都保持瞬时（详见 [docs/features.md](docs/features.md)「输出滚动动画」）；
-- 启动加载动画；
-- 雷霆大字及入场动画；
-- 顶部余额胶囊：悬浮显示 DeepSeek API 余额与峰谷时段（高峰为工作日 `9-12` 点、`14-18` 点；周末、法定节假日与落在周末的调休日都按低谷半价），默认关闭；会话使用 [dsh-codearts-auth](https://www.npmjs.com/package/dsh-codearts-auth) 渠道模型时自动切换为该渠道的剩余额度与积分消耗进度，随渠道切换实时跟随，主读数可在设置中选择右侧百分比显示剩余或已用（详见 [docs/features.md](docs/features.md)「渠道额度模式」）；
-- 可选音频通知：启动音、任务开始/结束音、需要回应时提示，音量与自定义音效目录可调（默认关闭，详见 [docs/audio-notifications.md](docs/audio-notifications.md)）。
+## DSH 版本支持与设置持久化
 
-所有设置由 DSH 自己的设置服务持久化，与页面 origin/端口无关：在 **DSH 0.2.0-rc.2 / 0.1.7-rc.1 及以后**，Host `index.js` 导出一份 31 个字段全部 `.volatile()` 的 schemastery `Config`（命名空间 = 本插件 profile entry id `theme-endfield`），浏览器 `client.js` 通过 `ctx.configForms` 读写并订阅，值随 `<profile>/cordis.patch.yml` 落盘；在**更旧的 DSH（≤ 0.1.5）** 上则回落到 `ctx.settings.register('dsh-theme-endfield', schema)` + `ctx.settingsScope`（`<dshHome>/settings.yaml`）。两代都与页面 origin 无关，因此 DSH web 与 DSH Desktop 都能正确保存并在重启/换端口后恢复，不再使用会被 Desktop 随机端口清空的 `localStorage`。详见 [docs/features.md](docs/features.md) 与 [docs/engineering-notes.md](docs/engineering-notes.md)；0.1.7 升级后旧设置需要在设置页重设一次（`settings.yaml` 已被 DSH 废弃，见 [engineering-notes.md § DSH 0.1.7-rc.1 换掉了整套 settings API](docs/engineering-notes.md#dsh-017-rc1-换掉了整套-settings-api-v110-已跟进)）。设置文案支持中英文；动态等高线尊重系统「减少动态效果」，动画帧率和速度可独立调整。
+| DSH | 设置持久化 | 备注 |
+| --- | --- | --- |
+| **0.2.x**（在 **0.2.0-rc.2** 与 **0.2.1-rc.2** 上实测；0.2.2-rc.1 的 composer seat 改动见下） | Host 导出 `Config`，浏览器 `ctx.configForms` | 当前支持目标 |
+| 0.1.7 – 0.1.x | 同一套 Config／configForms 接缝 | 无需改动 |
+| ≤ 0.1.5 | `ctx.settings.register` + `ctx.settingsScope` | 自动回落，无需配置 |
+
+- **0.2.x / 0.1.7+**：Host `index.js` 导出一份 34 个字段全部 `.volatile()` 的 schemastery `Config`（命名空间 = 本插件 profile entry id `theme-endfield`），浏览器 `client.js` 通过 `ctx.configForms` 读写并订阅，值随 `<profile>/cordis.patch.yml` 落盘。
+- **≤ 0.1.5**：回落到 `ctx.settings.register('dsh-theme-endfield', schema)` + `ctx.settingsScope`（`<dshHome>/settings.yaml`）。
+- 0.1.7 升级后旧设置需要在设置页重设一次（`settings.yaml` 已被 DSH 废弃，见 [engineering-notes.md § DSH 0.1.7-rc.1 换掉了整套 settings API](docs/engineering-notes.md#dsh-017-rc1-换掉了整套-settings-api-v110-已跟进)）。
+
+### 0.2 改动（v1.1.6 已跟进）
+
+0.2 改动了四处本插件依赖的应用侧细节，旧写法在 0.2 上会**静默失效**：
+
+- **回合状态标签**（“Deep diving…”）从 `@deepseek-ai/dsh-client-ui-conversation` 的渐变文字搬到 `@deepseek-ai/dsh-client-ui-chat` 的遮罩扫光文字，不再有 `turnStatus` 类名；着色改由 `--dsw-alias-label-deep-diving` / `-shimmer` 两个令牌承担，因此旧规则已删除，改在 `theme.overrideTokens` 层换色（留着旧规则时该令牌仍是应用自带值，标签完全没有主题色）。
+- **右侧栏**列名由 `_detailsCol` 改为 `_rightbarCol`，且不透明底色移到列元素本身——等高线图层在右侧栏打开时不会再被整块盖住。
+- **插件卡片展示文案**改由 `locale/<语言>.json` 的 `meta.title` / `meta.description` 提供；`package.json` 的 `dsh.client.inject` 也不再列 0.2 已删除的 `@deepseek-ai/dsh-client-runtime` 与 `@deepseek-ai/dsh-client-ui-slots`，改为列出 0.2 真正的提供方。
+- **composer seat 的 `will-change: transform`**（0.2.2-rc.1）：它会让 seat 成为 `position: fixed` 后代的 containing block，而审批白条正是靠 fixed 铺满视口——白条因此塌成窗口底部的一条线，只剩「等待审批」可见（[#41](https://github.com/ymh0000123/dsh-theme-endfield/issues/41)）。主题在审批面板挂载期间把该提示降回 `auto`，不改 DOM、也不长期关掉上游的合成提示。
 
-**如果开关总是「刷新后复位」**：先看 Host 侧有没有这份 `Config`（`Config.listConfigs` 对该 entry 报 `absent` 就是没有）。没有 Config 时 DSH 不投影任何表单，Host `apply()` 会打一行 warn 并在 profile 目录留下报告文件 `theme-endfield-diagnostic.json`（`Config` 构建成功时会自动删除它；报告里的 `schemaMode` / `loaded` / `loadError` 会写明走了哪条解析路径、以及某个副本是否「解析得到却加载失败」）——排查与判据见 [docs/testing.md](docs/testing.md#设置页)。另外注意：**改 Host 半（`index.js`）必须整进程重启 DSH**，刷新页面只重载 `client.js`。
+细节见 [docs/engineering-notes.md](docs/engineering-notes.md)。
+
+### 开关总是「刷新后复位」
+
+先看 Host 侧有没有这份 `Config`（`Config.listConfigs` 对该 entry 报 `absent` 就是没有）。没有 Config 时 DSH 不投影任何表单，Host `apply()` 会打一行 warn 并在 profile 目录留下报告文件 `theme-endfield-diagnostic.json`（`Config` 构建成功时会自动删除它；报告里的 `schemaMode` / `loaded` / `loadError` 会写明走了哪条解析路径、以及某个副本是否「解析得到却加载失败」）。排查与判据见 [docs/testing.md#设置页](docs/testing.md#设置页)。
+
+另外注意：**改 Host 半（`index.js`）必须整进程重启 DSH**，刷新页面只重载 `client.js`。
 
 ## 文档
 
@@ -58,6 +85,11 @@ dsh plugin --profile web rm dsh-theme-endfield
 | [docs/engineering-notes.md](docs/engineering-notes.md) | 算法、层叠、动画和性能实现说明 |
 | [docs/testing.md](docs/testing.md) | 校验脚本与测试套件说明 |
 | [docs/contour-trail.md](docs/contour-trail.md) | 鼠标轨迹的采样、衰减与验证 |
+| [docs/contour-worker.md](docs/contour-worker.md) | 可选 Worker / WebGL 等高线渲染与回退 |
+| [docs/contour-scan-bounds.md](docs/contour-scan-bounds.md) | 等高线提取的分块边界算法 |
+| [docs/audio-notifications.md](docs/audio-notifications.md) | 音频通知的实现、防噪规则与自定义音效 |
+| [docs/glass.md](docs/glass.md) | 可选磨砂玻璃：模糊档位与刻意排除的部件 |
+| [docs/PR-description.md](docs/PR-description.md) | 音频通知那次改动的 PR 描述草稿 |
 
 ## 开发与验证
 
@@ -67,7 +99,18 @@ node selftest.js
 npm test
 ```
 
-`npm test` 覆盖样式不变量、配色、设置页、真实浏览器渲染、等高线平滑/尖点、动画可访问性、覆盖率和 24/60/120 FPS 性能预算。部分浏览器测试需要本机安装 Chrome 或 Edge。跑测试请用 Node 22+（浏览器 fixture 依赖全局 `WebSocket`/`fetch`，版本不足会在测试处明确报错；插件本身的运行没有这个要求）。
+`npm test` 覆盖样式不变量、配色、设置页、真实浏览器渲染、等高线平滑／尖点、动画可访问性、覆盖率和 24／60／120 FPS 性能预算。部分浏览器测试需要本机安装 Chrome 或 Edge。
+
+**版本与 CI 口径**（三者不是同一个集合）：
+
+| | Node | 测试范围 |
+| --- | --- | --- |
+| 插件运行（`package.json` 的 `engines`） | `>=18` | — |
+| 本地 `npm test` | Node 22+ | 全量 |
+| CI 阻塞门禁（`test:ci`） | Node 22 | 全量减去下面三项 |
+| CI 非阻塞 job | Node 22 | `test:perf` + `test:coverage`，`continue-on-error`，结果只写进摘要 |
+
+跑测试请用 Node 22+：浏览器 fixture 依赖全局 `WebSocket`／`fetch`，版本不足会在测试处明确报错（插件本身的运行没有这个要求）。`npm test` 比 CI 的 `test:ci` 多出 `contour-coverage`、`contour-perf` 两项：这两项重（渲染全图 / 性能计时），由 CI 的非阻塞 job 单独跑（`continue-on-error`），结果只写进 PR 摘要而不阻塞合并。
 
 ## 项目结构
 
@@ -75,9 +118,9 @@ npm test
 src/client/        Client 侧源码片段（拼接顺序见 src/client/manifest.js）
 src/host/          Host 侧源码片段（拼接顺序见 src/host/manifest.js）
 src/styles/        theme.css：主题样式表（那一整个模板字面量的内容）
-src/contour-*.js   等高线 worker / WebGL 源码（npm run build:worker 嵌入产物）
+src/contour/       等高线 worker 源码：contour-worker.js + contour-webgl.js（npm run build:worker 嵌入产物）
 client.js          Client 侧产物，由 src/client/ + src/styles/ 拼接而来
-index.js           Host 侧产物，由 src/host/ 拼接而来
+index.js           Host 侧产物，由 src/host/ 拼接而来；package.json 的 main 与 exports["."] 都指向它
 scripts/           构建与门禁：lib/bundle-build.js 拼接器 + build-*.js 入口
 lib/               音频通知：槽位定义、WAV 合成与播放运行时
 locale/            插件卡片的展示文案（meta.title / meta.description）
@@ -85,8 +128,11 @@ sounds/            生成的通知音（npm run sound:build 重新生成）
 cordis.patch.yml   Bundle 注入配置
 check.js           样式表静态校验
 selftest.js        校验器自检
-test/              渲染、设置、配色与性能测试
+test/              渲染、设置、配色与性能测试（tools/ 为截图与目视检查脚本）
 docs/              设计、功能、工程与测试文档
+SECURITY.md        安全边界：发布产物清单与运行时权限（由 CI 的 package-check.js 与 files 白名单逐项核对）
+screenshots.json   界面截图清单（对应 assets/ 下的 webp）
+.github/           CI 工作流与检查脚本（不进发布产物）
 ```
 
 `client.js` 与 `index.js` 是**构建产物，不要直接编辑**：改 `src/` 下的片段，再跑