# 发布 Ratel Lumina

本文只讲**发到 npm 并让 DSH 插件商店发现**的路径。官方发布教程见
[Package and install a plugin](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md)；
商店自动发现规则见 [dsh-plugin-shop](https://github.com/LivXue/dsh-plugin-shop)。

## 0. 当前状态与前置条件

| 项 | 当前 | 说明 |
| --- | --- | --- |
| 包名 | `@ratel-works/dsh-lumina` | 最近已发布 `1.2.0`（2026-10-29） |
| 版本 | 已发布 `1.2.0` | 公开 registry、标签与 GitHub Release 附件均已核验 |
| npm 登录 | 以发布前 `npm whoami` 为准 | 优先网页登录；登录与发布可能分别要求验证 |
| npm registry | 发布目标固定为 `registry.npmjs.org` | 本机默认源可能不同，命令显式指定官方 registry |
| npm 2FA | 已开启 | 优先 PTY + `--auth-type=web`，由本人网页 Touch ID / 通行密钥确认 |
| npm scope | `@ratel-works` | 已确认当前账号是 owner |
| 发版文件 | `files` 白名单 | `npm pack --dry-run` 已确认含 `lib/`、patch、README、hero |

发布前确认：

```sh
npm login --registry=https://registry.npmjs.org/ --auth-type=web
npm whoami --registry=https://registry.npmjs.org/
npm org ls ratel-works --registry=https://registry.npmjs.org/   # 确认 scope 归属
```

`npm whoami` 报 `ENEEDAUTH` 就是还没登录。npmmirror 不能发布，只能用 npmjs。

## 1. 构建与预检

```sh
npm run typecheck
npm test
npm run build
node tools/check-dsh-compat.mjs --json --dry-run
npm pack --dry-run
```

接口标识核查通过不等于原生客户端完整验收。首次安装、旧配置升级、真实输入与消息交接仍需单独确认。构建后的 `lib/` 不提交 Git，由 npm 包的 `files` 白名单分发；包内检查以最终 tarball 为准。

## 1.1 网页认证

在交互终端执行 `npm login --registry=https://registry.npmjs.org/ --auth-type=web`，按提示打开本次认证页面，由本人完成通行密钥或 Touch ID 验证。npm 登录成功后，发布仍可能要求另一次独立验证，继续使用同一发布进程给出的页面。默认不索取 OTP，不把验证码或认证链接写入仓库。

## 2. 如果 `@ratel-works` scope 不是你的

有两个选择：

1. 在 npm 创建/加入 `ratel` org，然后发布；
2. 改用你拥有的 scope，例如 `@golddream-y/dsh-lumina`。

改 scope 不只改 `package.json.name`：`tsdown.config.ts` 的 `PACKAGE_ID`、`cordis.patch.yml`
的 `name`、profile 安装 spec、README/文档里的包名都要一起改。不要在首发后随意换名——
一个 profile 同名包只能装一个，换名等于迁移。

## 3. 后续版本

### 0.3.0 发布记录

本轮发布说明见根目录 `CHANGELOG.md`。代码与版本准备提交完成后，先检查包内版本、客户端构建、patch、双语 README、两张宣传图和第三方声明；不以源码目录里的文件存在代替包内检查。

本轮发布命令（已执行）：

```sh
npm publish /absolute/path/ratel-works-dsh-lumina-0.3.0.tgz --access public --registry=https://registry.npmjs.org/
```

需要时在本人终端完成 npm 登录或 2FA。2026-10-23 已确认 npm `latest` 为 `0.3.0`，公开 registry 的包完整性与本地 tarball 一致。发布提交包含类型检查、构建、72 项测试和实际包内检查；真实客户端观感与帧率验收的限制保留在更新记录中。

### 1.0.0 正式发布流程（已完成）

1.0.0 已公开发布。下列保留本次执行流程，最终源码标签与完整性记录见文末。

```sh
npm run typecheck
npm test
npm run build
npm pack --pack-destination /private/tmp --ignore-scripts --json
```

检查生成的 `ratel-works-dsh-lumina-1.0.0.tgz`：包名与版本、host/client 入口、声明、patch、双语 README、宣传图、LICENSE 和第三方声明均应存在，个人邮件与本地诊断不得入包。使用该包完成新装和从 0.7.0 升级检查，并提交对应源码；后续认证或重试继续使用同一个已检查 tarball。

```sh
npm publish /private/tmp/ratel-works-dsh-lumina-1.0.0.tgz --registry=https://registry.npmjs.org/ --tag=latest --access public --auth-type=web
npm view @ratel-works/dsh-lumina@1.0.0 version dist.integrity --registry=https://registry.npmjs.org/
npm view @ratel-works/dsh-lumina dist-tags --registry=https://registry.npmjs.org/
```

CLI 返回“处理中”时先等待公开 registry 可查，不重复发布。公开版本、latest 与本地 tarball 完整性一致后，补齐远端核验记录，推送对应提交和版本标签，并创建附有同一 tarball 的 GitHub Release。修复通常用 patch、新增能力通常用 minor；本次 1.0.0 按用户确定的发布目标准备，不借升级版本清空旧配置。

## 4. 商店如何发现

商店（如 `dsh-plugin-shop`）是**自动抓取**的，不需要单独提交：

- npm 包在 `package.json.keywords` 里带 **`dsh-plugin`** 或 **`deepseek-harness`**；
- 或 GitHub 仓库带同名 **topic**，且根 `package.json` 有 `name` + `dsh.bundle`；
- 每天构建一次，通过自动检查后第二天出现在商店；
- 不发布 npm 的仓库路径要求把构建产物提交进 Git（`lib/` 不能忽略），否则会被 `requires-build` 拒绝。

本包已声明：

- `keywords: ["dsh-plugin", "deepseek-harness", ...]`
- `dsh.bundle.patch`
- `dsh.catalog`（category `ui`、中英文 summary、capabilities）
- `repository`、`homepage`、`bugs`、`license`
- `engines.dsh: ">=0.2.1-rc.2 <0.3.0-0"`

`dsh.catalog` 是可选声明；不写也会从 npm `description` 生成摘要，但分类会是 `other`，
所以这里显式声明 `ui`。

商店卡片会检查：

- `dsh.bundle` 是否存在；
- license / repository 是否可审查；
- 是否 deprecated；
- `engines.dsh` 和 `@deepseek-ai/dsh*` peer 是否覆盖读者版本；
- `dsh.catalog` 字段是否合法。

自动发现不等于人工审核；商店卡片不提供沙箱承诺。

## 5. 以读者身份验证

发布后，用干净的 `DSH_HOME` 安装一次，避免本地 profile 掩盖问题。以下以正式发布后的 1.0.0 为例；候选包的新装检查使用已经核对的本地 tarball，不提前假定公开版本存在：

```sh
export DSH_HOME="$(mktemp -d)"
dsh plugin --profile web add @ratel-works/dsh-lumina@1.0.0
dsh --profile web --no-open --port 0
```

打开打印的地址，确认：

1. 插件出现在 profile `dsh.profile.bundles`；
2. 品牌、设置页 Lumina 和当前启用的效果可见；
3. 控制台无 `cannot occupy` / `effect failed` / slot crash。

## 6. 常见失败

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| `ENEEDAUTH` | 未登录 npmjs | `npm login --registry=https://registry.npmjs.org/ --auth-type=web` |
| `E404` / `E403` scope | `@ratel-works` 不归你 | 创建 org 或换 scope |
| 发布到 npmmirror | 当前 registry 是镜像 | `publishConfig.registry` 已固定 npmjs；命令也显式带 `--registry` |
| 安装后没有插件层 | 包缺 `dsh.bundle` 或 profile 行没加 | 检查 `dsh.profile.bundles`；`dsh plugin add` |
| 商店不收录 | 缺 keyword / license / repository / description | 补齐后等下一轮构建 |
| `requires-build` | GitHub 路径没提交 `lib/` | 用 npm 发布，或提交构建产物 |
| 读者安装被拒 | `engines.dsh` / peer 范围不含其版本 | 调整范围；预发布要显式覆盖 |
| pnpm 11 拒绝 build | 包在安装时跑构建脚本 | 发布预构建 `lib/`，不要让读者构建 |

## 7. 0.3.0 发布检查（历史记录）

- [x] npm 网页登录与发布验证完成
- [x] `@ratel-works` scope 发布权限确认
- [x] `npm run typecheck` / `npm test` 通过（0.3.0，72 项测试）
- [x] `npm run build` 通过
- [x] 实际 tarball 含 `lib/client.js`、`cordis.patch.yml`、双语 README、hero、更新记录与第三方声明
- [x] `package.json.version` 发布前未被占用
- [x] `keywords` 含 `dsh-plugin` / `deepseek-harness`
- [x] `engines.dsh` 覆盖当前 DSH
- [x] npm 发布 `0.3.0`，公开 registry 的 `latest` 与完整性已核对
- [x] Git tag + push（`v0.3.0`）
- [x] [GitHub Release `v0.3.0`](https://github.com/golddream-y/ratel-dsh-lumina/releases/tag/v0.3.0)，含更新记录与预构建 tarball
- [ ] 第二天检查商店/构建报告

## 8. awesome-dsh-plugin 收录

[awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/blob/main/contributing.md)
是另一个独立列表，和 npm 商店自动抓取不同，需要提交 **一个 YAML 文件**。

文件路径：

```text
data/plugins/golddream-y__ratel-dsh-lumina.yml
```

可直接提交的文件位于 [收录条目](../distribution/golddream-y__ratel-dsh-lumina.yml)，描述与 `package.json` 的中英文 catalog summary 保持一致。将它复制到对方仓库上述路径即可，不需要改对方 README。

内容：

```yaml
url: https://github.com/golddream-y/ratel-dsh-lumina
name: golddream-y/ratel-dsh-lumina
category: ui
description:
  en: 'Let interaction glow. A subtle layer of motion for DeepSeek Harness, with customizable effects and reduced-motion support.'
  zh: '让交互，泛起流光。为 DeepSeek Harness 添一层恰到好处的动效，支持效果调整并跟随系统「减少动态效果」。'
```

注意：

- 中英文描述统一加引号，避免后续含 `: ` 时被 YAML 误解析；
- 仓库已加 `dsh-plugin` / `deepseek-harness` topic；
- 根 `package.json` 已有 `dsh.bundle`；
- 已加 `screenshots.json`（README hero），市场可展示截图；
- 必须等仓库创建满 **1 天**：本仓库创建于 `2026-10-21 16:21 UTC`，
  因此 PR 最早在 **2026-10-22 16:21 UTC / 2026-10-23 00:21 +08** 提交；
- 一个 PR 只加这一条；不要手工改 README。
- npm 已发布，条目优先走 npm；GitHub Release 里的预构建 tarball 仍保留，作为
  读者/镜像无法访问 npm 时的备用安装源。

PR 流程：

1. Fork `awesome-dsh-plugin/awesome-dsh-plugin`；
2. 新建上面的 YAML 文件；
3. 提交 PR，标题例如 `Add Ratel Lumina`；
4. 等 CI 和 maintainer 审核；分类不准确时维护者会直接改，不会打回。

**状态：已收录**（[PR #8714](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/8714)，2026-10-22 合并，
条目 `data/plugins/golddream-y__ratel-dsh-lumina.yml`）。更新描述时只改自己那一条，不要手工改 README。

### 收录前的文案与依赖校正

README 保留顶部图，正文改为产品定位、交互价值、使用场景、安装设置与精简文档入口，不再用固定效果数量定义产品。包简介、catalog summary 与本地收录条目沿用宣传图的品牌表达，定位于客户端的视觉动效增强，不限定于对话场景；保留效果可调、可关闭和减少动态支持的说明。收录仓库的简介已补交 [PR #8955](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/8955)，已于 2026-10-23 合并；仅更新该条目的中英文描述。

DSH peer 范围增加 0.2.1 预发布分支，显式覆盖当前验证基线 0.2.1-rc.2，同时保留 0.2.0-rc.2 分支。不宣称支持所有未来预发布版本。重新打包后使用新 tarball，旧的发布准备提交 330ad74 不再作为最终发布标签目标。

## 0.4.0 发布记录

本轮新增侧栏星河、分组与面板过渡，重构设置页并兼容旧配置。发布版本 0.4.0；具体功能、性能取舍与验收范围见 CHANGELOG 对应章节。类型检查、构建及 74 项测试通过，tarball 已核对（54 文件，432637 字节）。提交 c650c5a 与标签 v0.4.0 已推送；[GitHub Release](https://github.com/golddream-y/ratel-dsh-lumina/releases/tag/v0.4.0) 已创建并附 tarball。npm 已通过网页 Touch ID 验证并发布 0.4.0；公开 registry 已返回 0.4.0，dist.integrity 与本地最终 tarball 一致。

## Changelog 编写规则

- 以“上一个已发布版本 → 本次最终交付版本”为比较基准，不把工作区迭代过程当作发布历史。
- “修复”仅用于上一个已发布版本中确实存在的问题。若问题只发生在本轮未发布的新功能开发期间，合并进新功能的最终行为描述，不单列修复项。
- “优化”须明确基准。新效果内部的调参、重写和性能调整可归入实现说明，不暗示上一版本已经具备此效果。
- 合并反复试验、用户反馈与中间方案，只保留最终能力、兼容性、已知限制和必要验证事实。开发过程另记需求文档或决策记录。
- 发布前逐条对照上一版本标签；不能确认已发布影响面的条目不使用“修复”，也不以内部实现过失充当用户更新价值。

## 0.5.0 发布记录

品牌质感、预设预览与鲸鱼喷水，详情见 CHANGELOG。类型检查、构建及 74 项测试通过。最终 tarball 54 文件、437705 字节，integrity 为 `sha512-JR2csWp+upf/6od0/tKUKvAbX1PQAwMNGu6Bc1gjuh0vDOiB/Xj5Y/oQS3rdq4m/LrEtS/9utJBPOiWxh9VTdg==`。提交 f326ad0 与标签 v0.5.0 已推送，GitHub Release 已创建并附 tarball。npm 已通过网页认证发布，公开 registry 返回 0.5.0，latest 为 0.5.0，dist.integrity 与本地最终 tarball 一致。本地 desktop/web 已安装 0.5.0；代码需用户完整退出再重开客户端生效。第三方品牌许可边界见 THIRD_PARTY_NOTICES.md。

## 0.6.0 发布准备

本轮交付新会话丝带与独立设置，更新 README 宣传图，并带上 0.5.0 后提交的开发用兼容检查工具。类型检查、构建及 82 项测试通过；当前 0.2.1-rc.3 所需与可选钩子均可找到，开发依赖仍锁定 rc.2，不能据此声称所有未来版本兼容。实际 bundle 的 WebGPU 生命周期、无 GPU 降级、点击穿透、会话退出和减少动态检查通过。细线与亮部最终精修仍待原生视觉确认。

本地邮件草稿及未采用的宣传图草稿不纳入发布提交或 npm 包。npm 和 GitHub 发布结果待远端核验后追加。

### 0.6.0 当前发布进度

最终发布提交 9776eba 与 v0.6.0 标签已推送；GitHub Release 已创建并附上预构建包。清理过期资产约 4.95 MB，移除旧曲面实验及对应测试后保留 82 项测试，全部通过。最终包 60 文件、397484 字节，integrity 为 `sha512-X7CrzudFWRcE3H9pf+PdA8j31XwbI4h4cJFJuEkpQFMrj5w2aNkt6bhvI5UptFGKoZIVcJKzft5nMGvghk6Ohw==`。本地 desktop/web 已安装 0.6.0。npm 已完成网页登录及独立发布验证；CLI 成功提交后等待 registry 处理，公开查询现已返回 0.6.0，latest 为 0.6.0，dist.integrity 与上述最终 tarball 完全一致。npm 发布核验完成。

## 0.6.1 发布准备

相对 0.6.0 更新发送按钮两圈水纹与真实提交确认，解除转场接管时的抑制。87 项测试与实际 bundle 浏览器验证通过；原生视觉待确认。版本、完整性、npm 与 GitHub 结果在完成远端核验后追加。

### 0.6.1 发布完成

功能提交 0a8094e 与 v0.6.1 标签已推送。GitHub Release 已创建并附 tarball（61 文件、399917 字节），integrity 为 `sha512-z0XUZKOePMLZLb9SW4DchmXvkIdfQFyxp4zCrR2ikCj8O8PwJ7X0/fJRHe05fBTJ8vIL6l9wtppt+NZcNpCXCw==`。npm 已完成网页发布验证，公开 registry 返回 0.6.1，latest 为 0.6.1，远端 integrity 与同一本地 tarball 完全一致。类型检查、构建及 87 项测试通过，本地 desktop/web 已安装 0.6.1；原生视觉仍需重启查看。

## 0.6.2 发布准备

相对 0.6.1 修复界面比例调整后的光带遮罩及水纹定位，新增共享视口校准与有限比例变化监听。类型检查、构建及90项测试通过，多比例实际 WebGPU 回归见 tools/verify-viewport-scale.mjs。发布与完整性结果在核验后补充，原生视觉待用户重启确认。

### 0.6.2 发布完成

修复提交 423f7ac 与 v0.6.2 标签已推送。GitHub Release 已创建并附最终 tarball（62 文件、402127 字节），integrity 为 `sha512-4vGZAz1l+Ga12mf5QMCd1VZjPRazd+FIKT4Z+5het/kb8ZxdfJg0YUXZCociUMJLrsBC+rMYaptGOup1w58PGA==`。npm 登录与独立发布网页验证完成；处理等待后，公开 registry 返回 0.6.2，latest 为 0.6.2，远端 integrity 与最终包一致。类型检查、构建及90项测试通过，本地 desktop/web 已安装。原生客户端最终视觉仍待用户完整重启确认。


## 0.7.0 发布记录

相对v0.6.2，新增flow发送、首次布局交接与消息整行接棒，细化水滴，并将flow设为默认；不覆盖已保存的有效模式。准备阶段与正式发布结果分别记录，最终状态见下文「发布完成」。诊断证据使用本地忽略目录，个人邮件草稿不纳入提交和发布包。正式发布应使用本轮检查过的同一个tarball；不要仅凭本节标题判断已发布。


### 0.7.0 准备结果

类型检查、构建、99项测试及DSH兼容性只读检查通过。准备时npm公开latest为0.6.2，账号只读检查为~golddream。最终包为 `/private/tmp/ratel-works-dsh-lumina-0.7.0.tgz`，66个文件，压缩后418582字节，解包1019112字节；integrity为 `sha512-zzPWm11XQQ2a0RDKhr5o0UOsW+WoI4bARx3RJJHoD7jXoKZj+79fN3FDIdLXSQhBDJSJ3a/se7u/pQkVYfavRA==`。已实际打开tarball检查包名/版本、运行入口、声明、patch、双语README、宣传图、LICENSE和第三方声明，确认不含个人邮件、诊断目录、Agent Note或本地配置。pnpm锁文件不记录根包版本，本轮没有依赖变更，无需为版本号改锁文件。

以上为准备阶段记录；正式发布使用同一个tarball，并按下文完成核验。


### 0.7.0 发布完成

2026-10-25，npm登录与本次发布的独立网页验证均已完成。CLI提交后曾返回处理中；随后公开registry确认版本0.7.0、latest=0.7.0，远端integrity与最终tarball一致。发布提交5a998ac及v0.7.0标签已推送；GitHub Release已公开并附同一个418582字节的tarball。发布地址：https://github.com/golddream-y/ratel-dsh-lumina/releases/tag/v0.7.0 。个人邮件草稿未提交，诊断证据未分发。


## 1.0.0 准备与发布核验

发布说明以 0.7.0 为比较基准，用户可见变化维护在根目录 `CHANGELOG.md`。测试数量、工程核对与待验收项维护在本节，不作为 changelog 的常规内容。

- [x] 类型检查、构建与 116 项测试通过。
- [x] 受控浏览器验证档位保存与取消、按钮组提示及宽窄布局、设置页静止分区的边缘渐亮、短反光及减少动态、四档 WebGPU 管线与纹理复用、失焦暂停恢复、缩放对齐，以及发送流光和水滴转场回归。
- [x] 自审补齐退出画面的原生内边距和边框保留、动画启动失败时的装饰清理，并新增回归覆盖。
- [x] 居中弹框、原生菜单及提示浮层进退场与会话选中底板已接入；受控浏览器多次采样确认动画变化、退出清理、点击穿透、80% 缩放对齐与减少动态；验证入口 `tools/verify-surfaces.mjs`。原生客户端观感仍待重启确认。
- [x] 新增 `tools/perf-motion.mjs` 与 `tools/verify-performance.mjs`；受控数据与原生客户端指标分开，原始测量与截图保留在本地忽略目录。
- [x] 本机 desktop/web 已安装当前构建，加载新代码需要完整重启。
- [x] 双语 README 与宣传图、功能状态入口、配置 schema、观察者约束、设置设计和新增语义钩子清单已对齐；2026-10-26 本机 DSH 0.2.1-rc.3 所需接口标识核查无缺失。构建期类型包仍为 rc.2，未以文案替代依赖升级或原生运行验收。
- [ ] 原生客户端实际体验与性能确认。
- [x] 同一个实际 tarball 在独立 DSH_HOME 新装与 0.7.0 原位升级成功；实际 bundle 对比确认品牌、强度、发送模式和关闭意图保留，新增字段按兼容规则补齐。`tools/verify-release.mjs` 覆盖新装默认值、配置迁移与卸载清理。
- [x] 版本已提升为 1.0.0，实际打包与内容检查完成。
- [x] 本地发布准备提交。
- [x] 远端推送与标签、npm 与 GitHub 发布及远端完整性核验。

1.0.0 已完成公开发布；原生客户端最终体验仍是单独的验收项，不能由包级核验替代。


## 历史验证记录补充

2026-10-26 整理历史更新记录时，将面向开发维护的验证说明移至发布文档。下表记录各版本发布时的情况，不能视为当前版本或原生客户端的新增验收结果；0.6.0 至 0.7.0 的验证与发布结果沿用前文各版本记录。

| 版本 | 当时的工程验证 | 当时保留的验收边界 |
| --- | --- | --- |
| 0.2.0 | 类型检查、构建与 49 项测试；水滴和幽灵使用实际 bundle 在受控页面连续采样 | 原生视觉、帧率及长任务仍待确认；逐字波浪仅为原型，未启用 |
| 0.3.0 | 类型检查、构建与 72 项测试；受控浏览器覆盖描边、粒子、Echo 顺序、自动聚焦、延迟挂载、输入打断、减少动态、窄屏与卸载清理 | 受控结果不替代原生客户端视觉、IME 与帧率验收 |
| 0.4.0 | 类型检查、构建与 74 项测试；覆盖配置迁移、设置草稿、星河变化、分组清理及设置结构 | 最终面板性能方案未做帧率测量；原生完整视觉与性能仍待确认 |
| 0.5.0 | 类型检查、构建与 74 项测试；受控浏览器覆盖周期喷水、入场后单次喷水及减少动态 | 本地 desktop/web 已安装，原生观感仍待重启确认 |

历史版本的“已安装本机”仅说明文件已更新，不能代替客户端重启与最终验收。旧原型、草稿和实验资产的清理，以及开发用兼容性检查工具的加入，属于工程维护，不再占用用户更新记录。

## 1.0.0 候选包自审（2026-10-26）

已对照 0.7.0 检查新增能力和更新记录，并补齐代码异常清理、退出画面布局保留及现行配置文档。116 项测试、类型检查、构建、四档 WebGPU 管线与资源复用、默认流光发送回归、短过渡清理与缩放检查通过；本机 DSH 0.2.1-rc.3 必需和可选标识均未缺失。构建期类型包仍为 rc.2，不把标识检查等同于全部原生验收。

英文宣传图已与中文版同步为流光发送，底部图标同步，右下角小字已移除。中文版保持此前确认稿；两份 README 均引用包内对应 WebP。

候选包为 `/private/tmp/ratel-works-dsh-lumina-1.0.0.tgz`，74 个文件，压缩后 466989 字节，解包 1152771 字节。integrity：`sha512-9byTC9wqOrypC5Ib65pnXu1+ZCfEtYncn/UNwBV6KHn4ZQHJ6dhKjtGXvGfz4vGVJfiR4i3AvMMg+SzlRAVA9A==`。已展开核对运行入口、声明、patch、双语 README、宣传图、更新记录及许可文件，确认不含个人邮件、诊断、Agent 文件或本地配置。

独立临时目录完成包级新装与升级检查，两个安装后的 client bundle 与构建逐字节一致。实际 bundle 受控验证保存配置兼容；这不替代原生窗口的最终视觉确认。候选检查时 npm latest 为 0.7.0；随后使用上述同一个包完成 1.0.0 发布，结果见下节。

## 1.0.0 发布完成（2026-10-26）

发布源码提交 `88288f5` 和标签 `v1.0.0` 已推送。npm 网页登录与独立发布验证完成；CLI 接受后经过处理等待，公开 registry 已返回版本 1.0.0，latest 为 1.0.0，dist.integrity 与上述 466989 字节的最终 tarball 完全一致。

[GitHub Release v1.0.0](https://github.com/golddream-y/ratel-dsh-lumina/releases/tag/v1.0.0) 已公开，附同一个安装包。附件大小与 SHA-256 摘要均与本地包一致。本机 desktop/web 已安装此包；发布记录和功能文档已同步为已发布状态。个人邮件草稿未提交、未入包；诊断目录未分发。

## 商店图标补充（2026-10-26）

用户确认莫比乌斯环作为 Lumina 商店图标。确认稿在 `assets/brand/lumina-icon.png`，商店尺寸为 `assets/brand/lumina-icon.webp`（512 × 512）。本地收录条目已补 `icon`，指向本仓库 main 分支的 GitHub 托管位图。截图继续沿用 `screenshots.json` 中的宣传图，不添加真实客户端截图。本次不改插件代码或已发布的 1.0.0 包；图标资产与声明已推送，收录更新提交为 [PR #9634](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/9634)。仅增加自己条目的 `icon` 一行，待合并后随市场构建同步。

## 本地试作安装配置核对（2026-10-27）

运行光团试作的目标为官方桌面客户端 `desktop` 配置；该客户端宿主启动参数已确认引用 `.dsh/profiles/desktop`。只安装到 `web` 无法更新此桌面实例。后续本机验收前必须确认目标实例的 profile，并核对对应安装副本与构建文件摘要；不能以另一 profile 的安装成功代替。当前已补装新版至 desktop，待完整退出重开后的视觉确认；不改变已发布的 1.0.0 记录。

## 1.1.0 发布准备与发布核验（2026-10-27）

本轮交付运行中会话行的柔和光团（SVG 定义美术、Canvas 合成动态，复用星河画布与调度），以及赞助说明、商店安装说明与 npm/许可徽标。

- [x] 类型检查、构建与 118 项测试通过（新增 `tests/session-handover.spec.ts`）。
- [x] DSH 兼容核查（`node tools/check-dsh-compat.mjs --json --dry-run`）对本机 `0.2.1-rc.3` 无必需/可选缺失；构建期类型包仍为 rc.2，不据此声称未来版本兼容。
- [x] `npm pack --dry-run` 通过：77 文件、483.7 kB，含 `lib/`、patch、双语 README、两张宣传图、`CHANGELOG.md`、`THIRD_PARTY_NOTICES.md`。
- [x] `assets/session/session-cloud.svg` 是构建输入（`npm run build` 先跑 `gen-session-cloud-art.mjs`），已随源码提交，避免他人构建失败。
- [x] 版本提升为 `1.1.0`，CHANGELOG 增补对应章节。
- [x] 源码提交 `916ccbb` 与标签 `v1.1.0` 已推送（标签随 CHANGELOG 收紧后前移）。
- [x] [GitHub Release v1.1.0](https://github.com/golddream-y/ratel-dsh-lumina/releases/tag/v1.1.0) 已创建并附同一个 tarball（483.7 kB / 77 文件，SHA-256 `9d9da9858a31e36826b05e0ff9108ead0f2ea7e334f1f0920e49c403fb668fd3`），与 npm 发布包逐字节一致。
- [x] npm 网页认证后发布 `1.1.0`；公开 registry 返回 `latest = 1.1.0`，`dist.integrity` 为 `sha512-J5E3OF17hUp6ZxJvdZc9Q2VpawrAYlLgOjBRlQxwjkFoNHKC99Hg+KfQXDfyHrmgr2tCbebn53N1/JyaW6Gw+g==`，与本地 tarball 一致。
- [ ] 本机 desktop/web 安装 1.1.0 后完整退出重开，确认光团真实客户端观感。
- [ ] 原生客户端视觉与性能验收（受控页面通过不等于原生确认）。

个人邮件草稿 `docs/distribution/deepseek-brand-permission-draft.eml` 未提交、未入包。


## 1.1.1 发布与核验（2026-10-28）

对照 v1.1.0 合并更新记录，交付设置页整理、可见窗口失焦时保持背景动效、长对话发送流光修复，以及双语介绍与宣传图更新。保留既有设置，不调整性能档位参数。

- 类型检查、122 项测试及完整构建通过。
- 本机 DSH 为 0.2.1-rc.3，接口扫描未发现必需或可选接口缺失；开发依赖仍锁定 rc.2。接口扫描不替代真实客户端验收。
- 发送流光的实际构建受控回归已覆盖近距离、自动滚动、部分裁切气泡和用户主动滚动；真实客户端的最终观感仍待重启确认。
- 实际 tarball 已检查入口、声明、patch、双语 README、两张宣传图、LICENSE 与第三方声明；77 个文件，640376 字节，不含个人邮件和诊断文件。
- 本地 tarball 完整性：`sha512-Y5fCvGQZ2IoGFEcUxFL3nZwiIQmZq1TvHH1jqIA+6NdqANCH8q/zpwcVzHhHsk2CcXB+5I2uTNJ8AbABnolWQg==`。

npm 网页登录与独立发布验证已完成；发布进程成功退出。公开 registry 已确认 `1.1.1`，`latest` 指向 `1.1.1`，远端完整性与上述本地 tarball 一致。源码标签 `v1.1.1` 指向发布准备提交 `457ad4d`；GitHub Release 附同一 tarball。


## 未发布：窗口恢复检查（2026-10-29）

本次针对“切到其他应用再回来动画消失”的笼统反馈检查恢复链路，尚未复现反馈者的原始 macOS 场景，不能把以下缺口直接认定为其根因。

- 原实现的针对性测试复现：隐藏时销毁健康丝带设备，以及绘制错误后继续排入空任务。修正后通过；补充异步结果过期、卸载不复活、返回事件恢复调度的回归。
- 类型检查、127 项测试与完整构建通过。`tools/verify-motion-resume.mjs` 使用实际客户端构建及 Chrome 原生 GPU，在受控页面验证焦点切换、隐藏和恢复事件、WebGL 上下文恢复、WebGPU 设备失效后重建、减少动态及卸载清理；控制台无页面异常，清理后画布、宿主接管标记和全局暂停标记均为零。
- 普通切换和隐藏恢复过程中 WebGPU 设备数保持 1；注入设备失效并触发返回后增至 2。WebGL 恢复后资源从 1 组重建为 2 组，原生状态标记在丢失时恢复可见，成功绘制后再次接管。隐藏期间绘制提交计数不增长，返回后继续增长。
- 验证为受控生命周期事件与真实 GPU 失效注入，不是实际 macOS 最小化、锁屏或睡眠录制；未测量本轮真实客户端 CPU/GPU 占用，不据此宣称资源占用降低。

已安装本机 desktop/web，两份 `lib/client.js` 与验证构建 SHA-256 一致（`b31bf1ff6090286fd559af884e9070446c1a63d296efcd89cd96021ccf5db151`）。未发布 npm 新版本；需要完整退出并重新打开客户端后验证原生场景。


## 未发布：工具执行动效（2026-10-29）

首版接入通用工具和 Bash 标题，设置增加独立开关、默认开启；不做正文关闭与高度让位，不覆盖未知或多根嵌套结构。

- 类型检查、136 项测试及完整构建通过；rc.3 接口静态扫描包含新增工具钩子，结果以本轮扫描为准。
- `tools/verify-tool-motion.mjs` 运行实际客户端构建，在源代码核实过的原生结构上验证：持续光绸变化、同屏上限、完成交接、历史不补播、快速完成不闪烁、正文展开反馈、日志追加不重播、减少动态、标题高度不变和卸载清理。受控页面无异常，不代表真实客户端视觉已验收。
- 同一 Chrome 受控页面以 1/3/8 个运行工具、固定 60 ms 追加一次日志、每组 2 秒的开启/关闭场景记录主线程时间与样式、布局次数。该数据用于检查是否引入逐帧脚本或无界装饰，不代表客户端 CPU/GPU 占用或长期帧率承诺。

本轮不发布 npm；安装后完整重启客户端，再确认实际工具布局、深浅背景、缩放和滚动表现。

本机 desktop/web 已安装同一构建，`lib/client.js` SHA-256 为 `2ac820022542602bb5cbd3373c2cf022273f2bc06f920f09ffe2d44cb15429c4`；未替用户退出或重启当前客户端。


### 工具动效图标柔光调整（2026-10-29，未发布）

根据客户端截图反馈，取消标题下方波浪线，改为围绕原生图标的两层冷暖柔光；完成时向图标中心收拢，图标本身、标题和行高保持原样。缺少有效图标槽位时不显示装饰，不回退到固定位置。

类型检查、137 项测试、完整构建与实际构建回归通过。受控 75% / 100% / 125% 比例下，柔光中心与原生图标中心偏差均小于 1 px；并发、快速完成、正文展开、日志追加、减少动态和卸载检查通过。主线程短样本随实际构建回归保存在本地，不作为真实客户端性能承诺。预览与现行产品设计已同步；真实客户端观感需重启确认。

图标柔光版已安装本机 desktop/web，安装文件与验证构建 SHA-256 一致：`6ba7b6e9f06d7056351a4720ecafff453516cf9064601980cafee6a507639ec5`。未发布 npm。


## 1.2.0 版本准备（2026-10-29）

`package.json` 已调整为 1.2.0；新增工具执行动效采用 minor 版本。Changelog 对照 v1.1.1 收成工具图标柔光、可见窗口启停及绘图资源恢复三条，合并未发布阶段的波浪线试作和调整，不列作线上修复。pnpm 锁文件的根 importer 不记录包自身版本，依赖未变化，无需改写锁文件。

本次仅整理更新说明与版本准备，不发布 npm、不创建发布标签；最近公开版本仍为 1.1.1。工具图标柔光的源码验证与本机安装记录见前节，真实客户端观感仍需确认。

## 1.2.0 发布与核验（2026-10-29）

对照 v1.1.1 合并更新记录，交付工具执行动效（原生工具图标周围的冷暖柔光、完成原位收束、展开轻淡入，独立开关默认开启），并修复可见窗口失焦时弹框、菜单与会话选中不动效，以及光团上下文丢失、丝带设备异常后无法恢复的问题。

- 类型检查、137 项测试及完整构建通过。
- 本机 DSH 为 0.2.1-rc.3，接口扫描未发现必需或可选接口缺失；开发依赖仍锁定 rc.2。接口扫描不替代真实客户端验收。
- 实际 tarball 79 个文件、652.3 kB，含入口、声明、patch、双语 README、宣传图、LICENSE 与第三方声明；个人邮件草稿未提交、未入包。
- 本地 tarball 完整性：`sha512-LsEw7JallOEu0IrXWI2NHpyysWJBLOTVbD1YpS9ykCgBGyqCyVj55G0DLXvMsEAVFbbqm6S8u7LWGqtuoB7+XQ==`。

npm 网页登录与发布认证均已完成；公开 registry 已确认 `1.2.0`，`latest` 指向 `1.2.0`，远端完整性与本地 tarball 一致。源码标签 `v1.2.0` 指向 `38188cc`；[GitHub Release v1.2.0](https://github.com/golddream-y/ratel-dsh-lumina/releases/tag/v1.2.0) 附同一 tarball（SHA-256 `864d58cacaa6d7730760fc67d2c019c0b7df54f361f3fcbd4e46287605830c4f`）。

真实客户端观感与帧率仍待重启确认，工具执行动效的原生验收另计。