dsh-xiao-theme 0.0.0-stage → 1.2.1

package/CHANGELOG.md

@@ -0,0 +1,80 @@
+# 更新记录
+
+## 1.2.1 — npm 分发与宿主声明统一
+
+- 发布到 npm，供插件市场优先使用 registry 安装并读取版本、宿主和 peer 声明；GitHub Release 保留为后备。
+- 将 DSH 与 settings peer 统一为 `>=0.2.0-rc.2 <0.3.0`，排除旧 0.1.x 并保持本机 RC.2 可用。
+- 不修改主题功能、设置默认值、已保存参数或既有动效。
+
+## 1.2.0 — Custom backgrounds and dedicated settings
+
+- 增加本地背景图片设置，支持 PNG/JPEG/WebP，并在客户端缩放、转为限长 WebP 后保存在 DSH Profile；图片不上传。
+- 增加自动提取图片强调色和背景可见度滑条（0–100%，默认 75%），由主题表面透明度呈现图片，保持明暗模式与语义状态色。
+- 将完整魈主题设置从 General 列表迁移到独立的 Settings → Xiao 分区。
+- 保留已有动画、减少动态效果适配、会话状态、余额和素材来源记录。
+
+## 1.1.3 — Hidden ripple fix and rounded birthday artwork
+
+- 修复 `.xiao-wind-ripple` 的 `display: block` 覆盖 `hidden` 状态的问题。隐藏的池节点明确不绘制，动画子图形默认透明，取消动画不会暴露静态边框。
+- 统一播放前与窗口切换时的风痕清理，防止旧动画完成回调影响复用节点。
+- 生日贺图采用 32 px 圆角裁切，设置预览采用 20 px 圆角，去掉此前的径向蒙版。
+- 增加播放、取消、复用和过期完成回调的回归检查，并提供真实浏览器回归预览。
+
+## 1.1.2 — Focus recovery and artwork blending
+
+- 窗口重新获得焦点、文档可见性切换、`pageshow` 与 `pagehide` 时清理完整点击风痕池，避免动画节点在 Desktop 窗口切换后残留。
+- 状态/余额面板位置改为根据伙伴坐标、面板尺寸和视口剩余空间计算；空间不足时居中，超高内容可在面板内滚动。
+- 生日贺图主立绘增加径向软边，使方形场景自然融入主题背景。
+
+## 1.1.1 — Companion panel placement and transient cleanup
+
+- 状态/余额面板按伙伴位置与可用空间选择左右、上下方向，避免面板被伙伴或视口边缘遮住。
+- 窗口失焦、页面隐藏或卸载时取消并隐藏点击风痕池中的所有节点，避免桌面窗口切换后残留装饰边框。
+- 生日贺图作为立绘使用柔和径向透明边缘，与主题背景自然融合；设置页展示仍保持完整画面。
+
+## 1.1.0 — Settings clarity, artwork choice and amplified motion
+
+- 拆开设置实时预览中的伙伴头像与主立绘，避免两张图叠在一起；在窄窗口中仍保留立绘预览。
+- 新增「静立立绘 / 生日贺图」设置，同一主立绘位置、转场、透明度和位置配置均适用于两个版本；旧设置默认继续使用静立立绘。
+- 增强傩面素材的对比度、锐化、颜色与显示清晰度。
+- 将呼吸、伙伴动作、风痕、粒子漂移、选中反馈和沉浸视差的表现幅度提高到原来的三倍；减少动态效果仍按无障碍设置执行。
+
+## 1.0.0
+
+首个完整版本。
+
+### 主题与视觉
+- 新增魈主题：约 80 个明暗语义令牌（青玉 / 墨青 / 月白 / 旧金 / 紫色暗纹）。
+- 新增统一页面设计：侧栏品牌、欢迎页、会话页、设置页。
+- 新增三档视觉强度（简约 / 平衡 / 沉浸），只控制装饰强度，明暗跟随 DSH。
+- 新增欢迎页与会话页共节点的 700 ms 连续角色转场（可反向、可打断）。
+
+### 魈伙伴
+- 新增可拖动伙伴，含指针捕获、单帧合并跟随与位置持久化。
+- 新增键盘操作：方向键 8 px、Shift 32 px、Home 复位；仅在自身聚焦时生效。
+- 新增状态面板（会话状态 + 可选余额），含 `role="dialog"`、Escape 关闭与焦点恢复。
+- 新增欢迎页临时停靠，不覆盖用户保存位置。
+
+### 会话与余额
+- 新增按 `sessionId` 隔离的会话状态桥，后台会话不污染主视图。
+- 关键改进：**不再以「运行变空闲」判定成功**。只有读到显式结束原因才发布「已完成」，否则发布中性的「已结束」。
+- 新增可选官方 DeepSeek 余额：Host 侧解析凭据、凭据指纹绑定缓存、请求序号守卫、60 s 自动 / 15 s 手动下限 / 指数退避限流，401/403 不重试。
+- CNY 10 以下只做伙伴局部提示，不通体变红、不加速、不禁用交互。
+
+### 动效
+- 新增点击风痕（固定 6 节点池 + Web Animations API，260 ms，半径上限 82 px）。
+- 新增环境粒子（简约 ≤6 / 平衡 ≤18 / 沉浸 ≤28，工作时收敛减半）。
+- 新增立绘呼吸、伙伴待机漂浮、运行状态环、完成光环收束。
+- 新增沉浸档欢迎页视差（上限 3.5 px，仅页面稳定后启用）。
+- 生命周期：页面隐藏暂停动画、插件关闭完整清理、`prefers-reduced-motion` 自动降级。
+
+### 设置
+- 新增 17 项设置与串行化写入（连续调整不产生乱序覆盖）。
+- 新增写入失败可见反馈与部分回退提示。
+- 新增伙伴位置复位与全部设置复位（二次点击确认）。
+
+### 工程
+- 独立命名空间：包名、设置、CSS 类、插槽条目、语言字典、模块 id 全部 `xiao` 前缀，不继承 Kinich 的样式或资源。
+- 素材流水线 `scripts/extract-assets.py`：边界连通去白底、轻量超分、水印条带清除、傩面局部提取，可复现。
+- 验证：`npm run verify` 覆盖契约检查与 6 个测试套件（共 288 条断言），含构建产物级的 Host/Client 注册与路由测试。
+- 文档：设计动效说明、兼容基线、验证记录、第三方素材记录。

package/LICENSE

@@ -0,0 +1,30 @@
+dsh-xiao-theme
+
+Copyright (c) 2026 Xian-JL (LiqWhisper)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+the plugin source code in this repository (excluding third-party character art,
+which is documented in THIRD_PARTY_ASSETS.md), to deal in the software without
+restriction, including without limitation the rights to use, copy, modify,
+merge, publish, distribute, sublicense, and/or sell copies of the software, and
+to permit persons to whom the software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the software.
+
+THIRD-PARTY NOTICE
+
+This package displays character artwork derived from images supplied by the
+user. The source, author information, and processing steps for every such file
+are recorded in THIRD_PARTY_ASSETS.md. Recording a source is not a grant of
+redistribution rights: the artwork remains the property of its original rights
+holders and is not covered by the MIT-style grant above.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# Xiao · Vigil of the Azure Sky (dsh-xiao-theme)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An independent character theme plugin for DeepSeek Harness (Web and Desktop). It rebuilds the interface hierarchy in **jade, ink-teal and moon-white**, offers a choice of two character artworks in the same welcome/conversation slot, and adds a draggable Xiao companion, amplified wind traces and ambient motes, and optional official DeepSeek balance monitoring.
+
+> All interface copy is original theme copy and is not presented as official character dialogue. Character artwork sources and licensing notes are in [THIRD_PARTY_ASSETS.md](THIRD_PARTY_ASSETS.md).
+
+## Features
+
+- **Complete light and dark themes** built from roughly 80 semantic tokens. Light/dark follows DSH; the "minimal / balanced / immersive" presets only change decoration strength.
+- **One visual language** across the sidebar brand, welcome page, conversation page and settings.
+- **Two character artworks**: choose the standing illustration or birthday artwork; the selected image shares one welcome/conversation slot and its reversible, interruptible 700 ms transition.
+- **Xiao companion**: idle float, hover, click-to-open status panel, drag with saved position, arrow-key movement (Shift to accelerate, Home to reset), and a temporary welcome-page dock that never overwrites the user's position. Its status and balance panel chooses a clear side from the companion's location.
+- **Truthful session feedback**: sending, running, completed, ended, failed, stopped, unknown and awaiting-input, isolated per `sessionId` so background sessions cannot repaint the main view.
+- **Optional official balance**: off by default. When enabled the Host reads `https://api.deepseek.com/user/balance`; the API key never reaches the client. Below CNY 10 the companion shows a local warning only.
+- **Amplified motion system**: breathing, companion reactions, click wind traces, ambient motes and immersive parallax use three times their original amplitude, with bounded effects and reduced-motion support.
+- **Durable settings**: serialized writes, visible failure feedback, position reset and full reset; disabling the plugin releases styles, listeners and timers.
+- **Custom local background**: choose an image, tune its visibility, and optionally match Xiao's accent colors; settings stay in the active DSH Profile.
+
+## Install
+
+```powershell
+dsh plugin --profile web add dsh-xiao-theme@latest
+dsh web
+```
+
+Remove:
+
+```powershell
+dsh plugin --profile web remove dsh-xiao-theme
+```
+
+Then open **Settings → Xiao**. The theme is enabled by default; the balance readout is off by default.
+
+## Coexistence with other character themes
+
+- `dsh-kinich-theme` may stay installed. This plugin never disables, edits or removes another plugin.
+- For the first release, keep only one full character theme enabled per profile: both take over the sidebar brand slots and a set of theme tokens, so enabling two at once produces unpredictable visuals.
+
+## Settings
+
+Open DSH **Settings → Xiao**. With a local background selected, the dedicated page can tune its visibility and optional accent matching.
+
+| Group | Settings |
+| --- | --- |
+| Theme | Enable the Xiao theme |
+| Visual intensity | Presentation (minimal / balanced / immersive), main illustration choice, conversation visibility and position, character visibility, breathing, welcome parallax |
+| Xiao companion | Show companion, size, horizontal direction, idle animation, reset position |
+| Session feedback | Converge decoration while running |
+| Environment | Background ornament, ambient particles, click wind trace |
+| Background | Local image, background visibility, automatic accent matching |
+| Official balance | Show the official DeepSeek balance |
+| Reset | Reset companion position, reset all settings (two-step confirm) |
+
+## Development
+
+Marketplace submission and release maintenance: [full workflow](docs/MARKETPLACE_SUBMISSION.md). Since 1.2.1, npm is the primary distribution source; GitHub Release tarballs remain a fallback. A catalog probe must discover the new npm package before catalog cards acquire its metadata.
+
+```powershell
+npm install
+npm run assets    # python scripts/extract-assets.py (requires Pillow)
+npm run build     # esbuild Host and Client bundles
+npm run verify    # build + contract checks + all tests
+```
+
+```
+assets/source/     untouched originals (excluded from the package)
+assets/...         processed assets
+src/host/          Host entry, settings schema, balance route
+src/client/        theme, scene, companion, session, balance, motion, settings
+scripts/           build, check, tests, asset pipeline
+lib/               prebuilt distribution artifacts
+docs/              design/motion, compatibility baseline, validation record
+```
+
+## Compatibility
+
+- Verified on **DSH 0.2.0-rc.2** (Node v24.x): isolated profile install, composition, page manifest and the Host balance route.
+- DSH and settings-peer range: `>=0.2.0-rc.2 <0.3.0` (retains the verified rc.2 baseline and excludes 0.1.x).
+- See [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) and [docs/VALIDATION.md](docs/VALIDATION.md).
+
+## License
+
+Source code is licensed under [LICENSE](LICENSE). Character artwork is not covered by that grant; see [THIRD_PARTY_ASSETS.md](THIRD_PARTY_ASSETS.md).

package/README.zh-CN.md

@@ -0,0 +1,86 @@
+# 魈 · 青霄守夜（dsh-xiao-theme）
+
+面向 DeepSeek Harness（DSH）Web 与 Desktop 的独立角色主题插件。以**青玉、墨青、月白**重构界面层次，可在静立立绘与生日贺图间切换，并提供可拖动的「魈伙伴」、强化风痕与环境粒子、可选的官方 DeepSeek 余额展示，以及可靠的设置保存。
+
+> 本插件的界面文案为原创主题文案，不标注为官方角色台词。角色图像来源与授权说明见 [THIRD_PARTY_ASSETS.md](THIRD_PARTY_ASSETS.md)。
+
+## 功能
+
+- **完整明暗主题**：约 80 个语义令牌，明暗跟随 DSH；「简约 / 平衡 / 沉浸」只控制装饰强度，不建立第二套明暗模式。
+- **统一页面设计**：侧栏品牌、欢迎页、会话页与设置页共用同一套视觉语言。
+- **双立绘连续转场**：可在静立立绘与生日贺图间切换；所选立绘在欢迎页与会话页复用同一位置，并以 700 ms 可反向、可打断的过渡呈现。
+- **魈伙伴**：待机漂浮、悬停、点击打开状态面板、拖动跟随并保存位置、方向键移动（Shift 加速、Home 复位）、欢迎页临时停靠且不覆盖用户位置；余额面板依据伙伴位置自动选择不遮挡的一侧。
+- **真实会话状态**：区分发送中、运行中、已完成、已结束、失败、已停止、状态未知与等待用户操作，并按 `sessionId` 隔离，后台会话不污染主视图。
+- **可选官方余额**：默认关闭；启用后由 Host 侧读取 `https://api.deepseek.com/user/balance`，API Key 不进入客户端；CNY 10 以下只在伙伴处给出局部提示。
+- **强化动效系统**：呼吸、伙伴动作、点击风痕、环境粒子和沉浸视差均为原来的三倍幅度；保留数量上限并遵守减少动态效果设置。
+- **可靠设置**：串行化写入、失败可见反馈、位置复位与全部设置复位；关闭插件后完整释放样式、监听器与定时器。
+- **自定义本地背景**：选择图片、调整背景可见度并可选自动匹配魈主题强调色；设置只保存在当前 DSH Profile。
+
+## 安装
+
+```powershell
+# 从 npm 安装；桌面端把 web 替换为 desktop，并先完全退出客户端
+dsh plugin --profile web add dsh-xiao-theme@latest
+dsh web
+```
+
+卸载：
+
+```powershell
+dsh plugin --profile web remove dsh-xiao-theme
+```
+
+安装后打开 **Settings → 魈**。主题默认启用，余额展示默认关闭。
+
+## 与 Kinich 主题共存
+
+- 允许与 `dsh-kinich-theme` 同时安装；本插件不会自动禁用、修改或卸载任何其他插件。
+- 首版建议同一 Profile 只启用一个完整角色主题。两者都会接管侧栏品牌插槽与一批主题令牌，同时启用时视觉效果不可预期。
+
+## 设置项
+
+在 DSH 中打开 **Settings → 魈**。选择本地背景后，可调整背景可见度与自动强调色。
+
+| 分组 | 设置 |
+| --- | --- |
+| 主题 | 启用魈主题 |
+| 视觉强度 | 界面表现（简约 / 平衡 / 沉浸）、主立绘样式、会话页可见度与位置、立绘显示、立绘呼吸、欢迎页视差 |
+| 魈伙伴 | 显示伙伴、伙伴大小、水平方向、待机动画、复位伙伴位置 |
+| 会话反馈 | 工作时收敛环境 |
+| 环境与装饰 | 背景纹饰、环境粒子、点击风痕 |
+| 自定义背景 | 本地图片、背景可见度、自动匹配强调色 |
+| 官方余额 | 显示官方 DeepSeek 余额 |
+| 复位 | 伙伴位置复位、全部设置复位（二次点击确认） |
+
+## 开发
+
+市场提交与后续发行步骤见 [插件市场提交全流程](docs/MARKETPLACE_SUBMISSION.md)。1.2.1 起以 npm 为优先分发来源，GitHub Release 保留为后备。市场目录重新探测 npm 后可展示版本与宿主要求；本地安装来源以实际依赖和 lockfile 为准。
+
+```powershell
+npm install
+npm run assets    # 由 python scripts/extract-assets.py 生成处理后素材（需要 Pillow）
+npm run build     # esbuild 打包 Host 与 Client
+npm run verify    # 构建 + 契约检查 + 全部测试
+```
+
+目录结构：
+
+```
+assets/source/      四张原始素材（不进入发布包）
+assets/{character,companion,ornaments,showcase}/  处理后素材
+src/host/           Host 入口、设置 schema、余额路由
+src/client/         主题、场景、伙伴、会话、余额、动效、设置
+scripts/            构建、检查、测试、素材处理
+lib/                预构建分发产物（Host + Client bundle）
+docs/               设计动效、兼容基线、验证记录
+```
+
+## 兼容性
+
+- 已实测：**DSH 0.2.0-rc.2**（Node v24.x），隔离 Profile 安装、组合、页面清单与 Host 余额路由。
+- DSH 与 settings peer 声明：`>=0.2.0-rc.2 <0.3.0`（保持本机兼容，0.1.x 不再列入支持范围；实测基线仍为 0.2.0-rc.2）。
+- 详见 [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) 与 [docs/VALIDATION.md](docs/VALIDATION.md)。
+
+## 许可
+
+源代码按 [LICENSE](LICENSE) 授权。角色图像不属于该授权范围，见 [THIRD_PARTY_ASSETS.md](THIRD_PARTY_ASSETS.md)。

package/RELEASE_NOTES.md

@@ -0,0 +1,9 @@
+# Xiao Theme v1.2.1
+
+First npm distribution of this theme, alongside the existing GitHub Release fallback. The package now supplies registry metadata for marketplace version/host-requirement display. DSH and optional @deepseek-ai/dsh-settings declarations are `>=0.2.0-rc.2 <0.3.0`, matching Kinich and preserving the local RC.2 baseline.
+
+Theme behavior, artworks, optional balance monitoring, background controls, settings and existing animations are unchanged. Marketplace catalog discovery may update separately; npm and installed dependency records identify the actual source.
+
+```powershell
+dsh plugin --profile desktop add dsh-xiao-theme@latest
+```

package/THIRD_PARTY_ASSETS.md

@@ -0,0 +1,84 @@
+# 第三方素材记录（THIRD_PARTY_ASSETS.md）
+
+本文件记录 `dsh-xiao-theme` 中每一件非原创视觉素材的原文件、用途、来源、作者信息、处理方式、署名与最终资产路径。
+
+**重要：记录来源不等于获得再分发许可。** 本插件的源代码按仓库 LICENSE 授权，但下列角色图像不属于该授权范围，其权利仍归原作者或权利方所有。公开发布前必须由发布者单独确认授权。
+
+## 1. 处理原则
+
+- 四张原文件完整保留在 `assets/source/`，不做任何修改；处理结果另行存放于 `assets/character`、`assets/companion`、`assets/ornaments`、`assets/showcase`。
+- 提取、去背景、超分与补绘后的资产**不标注为完全原创**。
+- 去背景保留白色衣物、浅色风纹与细小边缘（采用边界连通的洪水填充，而非全局按颜色删除）。
+- 允许轻量超分（Lanczos 上采样 + 再采样 + 锐化），产物分辨率与处理步骤全部记录在案。
+- 处理流程可复现：`python scripts/extract-assets.py`。
+
+## 2. 逐项记录
+
+### 2.1 `Standing_illustration.jpg`
+
+| 字段 | 内容 |
+| --- | --- |
+| 原文件 | `assets/source/Standing_illustration.jpg`（745×600，JPEG，70,555 字节） |
+| 用途 | 欢迎页主视觉立绘；会话页安全边缘立绘 |
+| 来源 | [原神角色立绘展示网站](https://dimengke.github.io/yuanshenlihui/)（由用户提供；页面标注数据来源为米游社） |
+| 作者信息 | 未随文件提供；发布前由发布者核对 |
+| 处理方式 | 边界连通白底去除（容差 16/最低通道 200/最大饱和度 24）→ 1 px 腐蚀 + 0.9 px 羽化 → 内容裁剪 → 2× Lanczos 超分后降至宽 1080 → UnsharpMask(1.1, 78%, 3) |
+| 最终资产 | `assets/character/xiao-standing.webp`（1080×870，约 200 KB，透明占比 51.6%） |
+| 署名 | 界面内不标注；随包 `README` 与本源文件说明 |
+
+### 2.2 `Xiao_bird.jpg`
+
+| 字段 | 内容 |
+| --- | --- |
+| 原文件 | `assets/source/Xiao_bird.jpg`（600×664，JPEG，55,771 字节） |
+| 用途 | 交互伙伴「魈伙伴」；侧栏与品牌标记 |
+| 来源 | [米游社文章 77973816](https://www.miyoushe.com/ys/article/77973816)（由用户提供） |
+| 作者信息 | **尚未核实。** 用户提供了原图及来源文章链接，未提供作者确认或许可证明。原图右下角带有社区水印，本插件**不依据水印推定作者或许可** |
+| 处理方式 | 先以背景色清除原图右下角水印条带（466×630 起的矩形区域，周围为纯背景像素），再做边界连通白底去除（容差 20/最低通道 198/最大饱和度 28）→ 1 px 腐蚀 + 0.9 px 羽化 → 内容裁剪 → 底边 14 px 渐隐 → 2× Lanczos 超分后降至宽 640 → UnsharpMask(1.1, 78%, 3) |
+| 最终资产 | `assets/companion/xiao-companion.webp`（640×728，约 71 KB，透明占比 41.0%）；`assets/companion/xiao-companion-mark.webp`（224×224，约 13 KB，取自同一处理结果的面部方形区域） |
+| 署名 | 界面内不标注；公开发布前必须在 `README` 中补齐作者与文章链接 |
+
+### 2.3 `Nuo_mask.png`
+
+| 字段 | 内容 |
+| --- | --- |
+| 原文件 | `assets/source/Nuo_mask.png`（840×400，PNG，458,323 字节） |
+| 用途 | 背景纹饰（傩面装饰层） |
+| 来源 | [原神角色立绘展示网站](https://dimengke.github.io/yuanshenlihui/)（由用户提供；页面标注数据来源为米游社） |
+| 作者信息 | 未随文件提供；发布前由发布者核对 |
+| 处理方式 | 仅取右侧完整傩面局部（x 430–790，y 0–400）→ 1.5× Lanczos → 对比度 1.24×、饱和度 1.12×、UnsharpMask(1.8, 155%, 2) → 椭圆 α 渐隐（fade 0.14）→ 画布下延 60 px 并对底部 120 px 渐隐；界面提升到 0.3 不透明度 |
+| 补绘说明 | 源图裁切处傩面下缘不完整。**未虚构补画轮廓**，而是以透明渐隐收边，使裁切读作有意的装饰处理 |
+| 最终资产 | `assets/ornaments/nuo-mask-mark.webp`（540×660，约 48 KB，透明占比约 29%） |
+| 署名 | 界面内不标注；随包 `README` 与本源文件说明 |
+
+### 2.4 `Birthday_celebration.jpg`
+
+| 字段 | 内容 |
+| --- | --- |
+| 原文件 | `assets/source/Birthday_celebration.jpg`（600×600，JPEG，111,669 字节） |
+| 用途 | 设置页主题介绍卡片（Settings → General → 魈主题 头部横幅）与主立绘选项二「生日贺图」；和 `xiao-standing.webp` 共用欢迎页/会话页立绘位置 |
+| 来源 | [原神角色立绘展示网站](https://dimengke.github.io/yuanshenlihui/)（由用户提供；页面标注数据来源为米游社） |
+| 作者信息 | 未随文件提供；发布前由发布者核对 |
+| 处理方式 | 保留完整插画构图；等比降至 540×540；WebP q82。主立绘用 32 px CSS 圆角裁切，预览用 20 px 圆角；设置页横幅继续显示完整画面 |
+| 最终资产 | `assets/showcase/celebration-card.webp`（540×540，约 59 KB） |
+| 署名 | 界面内不标注；随包 `README` 与本源文件说明 |
+
+## 3. 原创部分
+
+以下内容为本插件原创，不包含第三方素材：
+
+- 明暗语义色板与全部主题令牌（`src/client/theme/tokens.js`）；
+- 云纹、风痕线、光晕、氛围层与边角装饰（CSS 渐变与矢量图形）；
+- 点击风痕（固定节点池 + Web Animations API）；
+- 环境粒子（程序生成的光尘与风屑）；
+- 运行状态环、完成光环收束、焦点与选中反馈；
+- 侧栏品牌标记的环、风弧与光晕层（叠加在第三方伙伴图像之上）；
+- 全部界面文案（原创主题文案，不标注为官方角色台词）。
+
+## 4. 发布前检查清单
+
+- [ ] 确认三张「原神角色立绘展示网站」素材的原始作者与授权范围。
+- [ ] 补齐 `Xiao_bird.jpg` 对应的米游社文章作者与链接。
+- [ ] 确认角色图像与《原神》相关商标的使用是否符合目标发布渠道的要求。
+- [ ] 确认发布包内不含 `assets/source/`（`package.json` 的 `files` 白名单已排除）。
+- [ ] 在 `README` 与 Release 说明中保留本文件的链接。

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# Bundle row for dsh-xiao-theme.
+# The Host entry registers the optional settings section and the authenticated
+# DeepSeek balance route; the Client entry owns the theme, scene, companion and
+# motion layers. Both are released together with this patch.
+- insert:
+    - id: dsh-xiao-theme
+      name: dsh-xiao-theme

package/docs/COMPATIBILITY.md

@@ -0,0 +1,86 @@
+# 兼容性与接口基线（docs/COMPATIBILITY.md）
+
+本文件记录 `dsh-xiao-theme` 实际核实的 DSH 接口基线、继承的约定与未验证事项。开发接手者应先核对本文件，再假设其中任何数值仍然成立。
+
+2026-10-16，1.2.1：统一 DSH 与 settings peer 范围为 `>=0.2.0-rc.2 <0.3.0`，不再声明 0.1.x。宿主实测基线仍为 0.2.0-rc.2；下表中的旧安装清单属于原测试记录。本次以 npm 优先分发，与 Kinich 的宿主要求一致。
+
+## 1. 本轮核实的环境
+
+| 项目 | 实测值 | 核实方式 |
+| --- | --- | --- |
+| DSH 版本 | `0.2.0-rc.2` | `E:\Deepseek-harness\resources\runtime\cli\bin\dsh.cmd --version` |
+| 应用内 Node | v24.18.1 | DSH CLI 运行时报错栈 |
+| 开发用 Node / npm | v24.19.0 / 11.17.0 | 本机 `node -v`、`npm -v` |
+| 目标 Profile（验收） | 隔离 profile `xiao-lab`（由 shipped `web` 模板初始化） | `dsh --profile xiao-lab --from-default-profile web --dump-config` |
+| 既有 Profile（未改动） | `desktop`（已装 `dsh-kinich-theme@1.7.1`）、`web`（`dsh-kinich-theme@1.5.0`） | 读取 profile `package.json` |
+| profile 根目录 | `%USERPROFILE%\.dsh\profiles\<name>` | 实测 |
+
+**注意**：`E:\Deepseek-harness\resources\app.asar\dsh\` 是归档文件内部的路径，磁盘上不存在该目录。要读取 DSH 本体代码需先解包 `app.asar`，或通过 CLI 与 profile 的 `node_modules` 间接核实。
+
+## 2. 使用的 DSH 接口
+
+| 接口 | 用途 | 在本插件中的位置 |
+| --- | --- | --- |
+| `dsh.manifestVersion = 1`、`dsh.client.inject`、`dsh.bundle.patch` | 插件清单与客户端注入 | `package.json`、`cordis.patch.yml` |
+| Host `name` / `Config` / `apply(ctx)` | Host 入口与实时配置 | `src/host/index.js` |
+| `ctx.inject(["settings"], ctx => ctx.settings.register(ns, schema, { applies: "live" }))` | 注册设置命名空间 | `src/host/index.js` |
+| `ctx.settings.configure({ auto: false }, ctx.fiber)` | 旧版 DSH 的 Config 呈现回退路径 | `src/host/index.js` |
+| `ctx.inject(["connection", "settings", "credentials"], …)` | 认证型 Host 路由 | `src/host/balance-route.js` |
+| `connection.fetch.register({ path, methods, requestBody, fetch })` | 注册 `/api/xiao-balance` | `src/host/balance-route.js` |
+| `credentials.resolve(envName)` | Host 侧解析 API Key | `src/host/balance-route.js` |
+| Client `inject = ["theme", "slots", "locale", "connection", "remote"]` | 声明的客户端服务 | `src/client/index.js` |
+| `ctx.get("configForms")` / `ctx.get("settingsScope")` | 两代 DSH 的设置表单解析 | `src/client/settings/resolve.js` |
+| `settings.mutate([{ op: "set", path: [field], value }])` / `settings.set(field, value)` | 原子或逐字段写入 | `src/client/settings/write.js` |
+| `ctx.theme.overrideTokens(source, tokens)` | 明暗语义令牌覆盖 | `src/client/overlay/xiao-overlay.js` |
+| `ctx.slots.inject(name, () => ctx.slots.register(def, Component))` | 插槽注入 | `src/client/index.js` |
+| `ctx.locale.register(namespace, dictionaries)` | 中英文文案 | `src/client/index.js`、`src/client/locales.js` |
+| `shell.overlay` 的 `useSessions` prop | 主视图会话选择 | `src/client/overlay/xiao-overlay.js` |
+| `shell.overlay` 的 `t` prop | 文案取值 | 同上 |
+| DSH `[data-phase='hero']` 标记 | 欢迎页阶段侦测 | `src/client/scene/phase-model.js` |
+| `[class$='_headline']`、`[class$='_composerHero']` | 欢迎页原生排版的视觉让位 | `src/client/styles.css` |
+
+### 已使用的插槽
+
+| 插槽 | 条目 id | 说明 |
+| --- | --- | --- |
+| `sidebar.brand.mark` | — | 侧栏品牌标记 |
+| `sidebar.brand.name` | — | 侧栏品牌名 |
+| `conversation.hero.brand.mark` | — | 欢迎页品牌标记 |
+| `conversation.composer.dock` | `xiao-session-state` | Session scope 的会话状态桥（不可见） |
+| `shell.overlay` | `xiao-theme-decoration` | 场景、立绘、伙伴、动效层 |
+| `settings.section` | `xiao-theme` | Settings → Xiao 独立设置页 |
+
+## 3. 明确不依赖的接口
+
+- 不注入 `@deepseek-ai/dsh-client-runtime`（已移除的包）。
+- 不调用 `settingsNamespace()`、`installSettingsSection()` 等已移除 API：`scripts/check.mjs` 会断言其不存在。
+- 不通过宿主全局变量读取会话内部状态；会话反馈只来自 `useSession` 选择器与按 `sessionId` 隔离的桥。
+
+## 4. 会话状态字段的兼容策略
+
+`src/client/session/compat.js` 会读取以下可能存在的字段，缺失时不影响运行：
+
+- 错误：`promptError`、`openError`、`lastAgentError`、`error`、`lastError`
+- 活跃：`awaitingFirstTurn`、`pendingSubmissions`、`running`
+- 结束原因：`stopReason`、`lastStopReason`、`finishReason`、`endReason`、`completionStatus`、`lastCompletionStatus`、`stop_reason`、`finish_reason`
+- 等待用户：`awaitingInput`、`awaitingUserInput`、`awaiting_input`、`pendingApproval`、`pendingPermission`、`pendingToolApproval`
+
+在 0.2.0-rc.2 上实测：`running`、`awaitingFirstTurn` 与错误字段可用；**未观测到可靠的结束原因字段**。因此：
+
+- `completed` 只在读到明确的成功原因值时发布；
+- 其余「由运行变空闲」的情形一律发布中性的 `ended`（界面文案：已结束）；
+- `awaiting-input` 仅在存在上述字段时出现，否则该状态不会触发。
+
+## 5. 未验证事项（请勿据此假设）
+
+1. **浏览器内的视觉与交互人工验收尚未执行。** 已完成的隔离验证覆盖：安装、profile 组合、页面清单包含 `dsh-xiao-theme/client.js`、Host 路由 200 返回真实快照。欢迎页转场、伙伴拖动、粒子与视差的观感需在真实浏览器中人工确认。
+2. 窗口尺寸矩阵（1280×720 / 1440×900 / 1920×1080 / 2560×1440）与 100%–200% 缩放未逐项人工核对，布局规则按 CSS clamp 与断点编写。
+3. `[class$='_headline']` / `[class$='_composerHero']` 依赖 DSH 的类名后缀约定；DSH 改版后需重新核对。
+4. 0.1.5 / 0.1.6 / 0.1.7 的 `engines.dsh` 区间为继承自既有插件的声明，本轮**未**在那些版本上实测。
+5. 与 `dsh-kinich-theme` 同时安装时的视觉冲突未做实测对比；按设计两者各自独立命名空间，不互相覆盖。
+
+## 6. 与 Kinich 主题共存
+
+- 允许同时安装；本插件**不会**自动禁用、修改或卸载其他主题。
+- 首版建议同一 Profile 只启用一个完整角色主题；设置页「主题」区域包含常驻说明文案。
+- 冲突已知点：两者都会接管侧栏品牌插槽与 `shell.overlay`（各自条目 id 不同），也都会覆盖一批 `--dsw-alias-*` 主题令牌；同时启用时后注册者胜出，视觉效果不可预期。这属于产品层面的互斥，不做样式优先级对抗。

package/docs/DESIGN_AND_MOTION.md

@@ -0,0 +1,122 @@
+# 设计与动效说明（docs/DESIGN_AND_MOTION.md）
+
+## 1. 视觉方向
+
+整体使用**青玉、墨青、月白**，辅以少量**旧金**与**紫色暗纹**。
+
+| 元素 | 处理 |
+| --- | --- |
+| 深色界面 | 墨青背景（`#0A1214` / `#0E1B1E`），青玉强调色（`#35C4A6`），柔和月白文字（`#E8F1F0`） |
+| 浅色界面 | 浅灰白背景（`#F2F6F5`），深青文字（`#10302C`），低饱和绿色表面（`#E7EFED`） |
+| 主操作 | 青玉色，含 hover / press / focus 三态 |
+| 辅助装饰 | 傩面局部、云纹、风痕线、局部紫色暗纹 |
+| 角色呈现 | 欢迎页突出（不透明度 ≈ 0.98），会话页退至安全边缘（默认 0.32） |
+| 正文与代码 | 只改语义令牌，不改业务状态色与语法色 |
+
+明暗模式跟随 DSH；「简约 / 平衡 / 沉浸」只控制视觉强度，不建立第二套明暗模式。
+
+### 语义令牌
+
+`src/client/theme/tokens.js` 以 `token(light, dark)` 成对声明约 80 个 `--dsw-alias-*` / `--dsw-specific-*` 令牌，覆盖背景层级、边框、品牌色、按钮态、交互悬停、文本层级、Markdown 代码块、滚动条、业务状态与气泡/输入/侧栏专用色。装饰层另外派生局部变量：
+
+```
+--xiao-jade        = var(--dsw-alias-brand-primary)
+--xiao-jade-deep   = color-mix(jade 72%, label-primary)   /* 明暗自适应 */
+--xiao-gold        = #b8934a
+--xiao-violet      = #8b7bd8
+--xiao-line        = var(--dsw-alias-border-l3)
+```
+
+以 `color-mix(in srgb, ... var(--dsw-alias-label-primary))` 派生装饰色，可在不判断明暗模式的前提下自动获得对比度合理的深浅两套表现。
+
+### 强度档位
+
+| 档位 | 立绘 | 环境粒子 | 视差 | 装饰 |
+| --- | --- | --- | --- | --- |
+| 简约 minimal | 欢迎页保留，会话页隐藏 | ≤ 6 且可关 | 关闭 | 傩面/云纹隐藏，光晕减弱 |
+| 平衡 balanced（默认） | 欢迎页主视觉 + 会话页边缘 0.32 | ≤ 18 | 关闭 | 云纹 + 风痕 + 傩面 |
+| 沉浸 immersive | 同上，可见度更高 | ≤ 28 | ≤ 10.5 px | 全部层次 |
+
+主立绘可在「静立立绘」与「生日贺图」间选择。两者共用同一舞台、位置、可见度与欢迎/会话转场；旧配置缺少该字段时默认选静立立绘。
+
+选择档位会同时套用 `XIAO_VISUAL_PRESETS` 中的相关开关，但**不会**改动总开关 `enabled`。
+
+## 2. 页面布局
+
+**欢迎页**：左侧（`left: clamp(310px, 21vw, 470px)`，`top: 26%`）为品牌标记与两行主题文案；右侧为用户选择的静立立绘或生日贺图。原生输入框、工作区选择器、附件与发送操作全部保留，仅在欢迎阶段把原生 hero 标题让位、把 hero 输入区下移 108 px。伙伴停靠在右下侧下方，不遮挡操作。
+
+**会话页**：立绘经 `transform` 回到右下角并缩小，不透明度降为设置值；环境效果降档；伙伴回到用户保存位置；正文、代码、表格与复制按钮所在的「禁装饰区」不放置任何装饰元素。
+
+**侧栏**：品牌标记为伙伴头像 + 环 + 风弧；选中项使用青玉窄条（`inset 2px 0`）；悬停不改变列表高度；DSH 原生导航与菜单行为不变。
+
+**响应式**：`≤1180px` 收敛立绘与文案宽度；`≤960px` 欢迎页改为 8vw 起排、立绘缩小；`≤720px` 隐藏云纹与部分风痕线，设置预览缩小但仍显示所选主立绘；`max-height: 720px` 降低欢迎页立绘的抬升量。会话页立绘另按 `characterPosition`（corner / edge）、`characterOpacity`（low / medium / high）和 `characterVariant` 微调。
+
+## 3. 角色转场
+
+欢迎页与会话页共用**同一个** `.xiao-hero-frame` 节点，只改变 `transform` 与 `opacity`，因此转场连续、可反向、可中途打断：
+
+| 阶段 | transform | opacity |
+| --- | --- | --- |
+| conversation | `translate3d(parallax) scale(0.94)` | 0.32（按设置） |
+| entering-hero / hero | `translate3d(parallax - 3vw, parallax - 34vh) scale(1.24)` | 0.98 |
+
+时长 700 ms（`cubic-bezier(.22,.68,.24,1)`）；`prefers-reduced-motion` 下降为 80 ms。阶段侦测只观察 DSH 的 `[data-phase='hero']` 标记，并带 700 ms 稳定窗口，初始加载不误播。
+
+## 4. 魈伙伴
+
+伙伴是主要交互入口；傩面不承担第二套浮标操作。
+
+| 场景 | 行为 |
+| --- | --- |
+| 待机 | 3.6 s 周期漂浮 ±9 px，幅度 ≤ 1.03 缩放 |
+| 悬停 | 环亮起，伙伴姿态变化幅度为首版三倍 |
+| 点击 | 打开状态面板（会话状态 + 可选余额），触发放大的三倍风痕 |
+| 拖动 | `pointer` 捕获即时跟随，`requestAnimationFrame` 合并到单帧；释放后节流写回设置 |
+| 点击/拖动判定 | 位移 ≤ 4 px 记为点击；超出即拖动，拖动结束不打开面板 |
+| 键盘 | 伙伴自身聚焦时：方向键 8 px、Shift 32 px、Home 复位 |
+| 发送反馈 | 虚线风环 + 更醒目的火花 |
+| 运行反馈 | 三倍速度的旋转风环与增大幅度的漂浮 |
+| 完成反馈 | 单次光环收束 + 三倍幅度轻跳 |
+| 结束/停止 | 中性灰环 |
+| 错误反馈 | 局部错误色环 + 明确的文字状态 |
+| 欢迎页停靠 | 临时移动到 `{x:95, y:90}`，不覆盖用户保存位置；离开欢迎页自动复原 |
+| 尺寸变化 | `ResizeObserver` + rAF 重新收敛到安全区域；不写回设置 |
+| 低余额 | 仅伙伴环与文字变为旧金提示，整体不变红、不禁用任何交互 |
+
+状态/余额面板使用伙伴当前位置和覆盖层可用宽高选择左右与上下方向；两侧空间不足时居中显示。面板自身限制最大高度并允许滚动，窗口缩放时重新计算锚点。
+
+## 5. 动效参数
+
+| 动效 | 参数 |
+| --- | --- |
+| 主立绘呼吸 | 6.5 s 循环，`scale 1 → 1.018`，位移 ≤ 4.5 px，不改布局 |
+| 伙伴待机漂浮 | 3.6 s 循环，±9 px |
+| 伙伴轻跳 | 保持原有时长，位移与缩放幅度 ×3 |
+| 点击风痕 | 260 ms；节点池固定 6 个，每击 8 个碎片；半径上限 246 px |
+| 环境光尘 | 14–26 s 非同步周期，尺寸、漂移与垂直位移幅度 ×3 |
+| 运行状态环 | 0.8 s 线性旋转（原 2.4 s） |
+| 完成光环收束 | 420 ms 单次 |
+| 欢迎页视差 | 最大 10.5 px，仅沉浸档 + 页面稳定后启用 |
+| 面板出现 | 180 ms |
+| 导航选中脉冲 | 280 ms，内侧强调边宽 ×3 |
+| 按压反馈 | 190 ms `filter: brightness(.88)`，加深至原来的三倍（不使用 transform，避免影响布局） |
+
+## 6. 性能与生命周期预算
+
+- 动画只使用 `transform` 与 `opacity`（按压反馈除外，为 `filter`）。V1.1 将可见位移、缩放、粒子与风痕尺寸设为首版三倍；减少动态效果仍优先于主题动画开关。
+- 常驻动画元素上限：沉浸档 28 粒子 + 6 风痕节点 + 1 立绘 + 1 伙伴 ≈ 36，低于 40 的预算。
+- 点击风痕使用固定节点池与 Web Animations API，**不使用 `setTimeout` 逐帧驱动**，连续点击不产生 DOM 分配。
+- 风痕 `[hidden]` 节点明确使用 `display: none !important`；子图形默认 `opacity: 0`，只有活动动画使其显示。取消动画之前先隐藏节点并失效旧完成回调。
+- 流式回复不驱动装饰层：装饰只订阅会话状态枚举，不订阅 token 级变更。
+- 页面隐藏、Desktop 窗口失焦和 `pagehide` 时，点击风痕节点池全部取消并隐藏，防止窗口切回后遗留边框；页面其余循环动态仍按活动门控暂停。
+- `prefers-reduced-motion: reduce` 时全部动画关闭、转场压缩到 80 ms、风痕与视差不启用（`data-reduced` 同时阻断 JS 侧调度）。
+- 余额请求：自动 60 s、手动 15 s 下限、失败指数退避至 5 min、401/403 不重试；`useBalance(enabled)` 只在功能启用时才持有轮询。
+- 插件关闭时释放：样式表、5 个宿主监听器、`MutationObserver`、rAF、定时器、风痕动画、视差变量、body 上的 `data-xiao-*` 属性。
+
+## 7. 无障碍
+
+- 伙伴为可聚焦按钮（`aria-label`、`aria-expanded`、`aria-haspopup="dialog"`、`aria-controls`、`aria-describedby`）。
+- 面板 `role="dialog"`、`aria-modal="false"`、`aria-busy`；Escape 关闭并把焦点还给触发者；面板外指针按下即关闭。
+- 会话反馈通过 `role="status"` + `aria-live="polite"` 播报。
+- 欢迎页文案在可视层 `aria-hidden`，同时提供一条屏幕阅读器专用标题。
+- 所有控件具备 `:focus-visible` 可见焦点。