dsh-session-manager 0.5.4 → 0.6.3

package/CHANGELOG.md

@@ -1,4 +1,85 @@
 
+## 0.6.3 — 2026-10-03
+
+- **feat(settings)**: 新增「弹窗透明度 / Dialog opacity」偏好设置（Issue #23），为第三方主题下的插件弹窗提供通用、不依赖任何主题插件的调节手段：
+  - 位置：设置卡片「偏好设置」区域；滑块范围 50%–100%，步长 5%，默认 100%，实时显示当前百分比，并提供「恢复默认」按钮。
+  - 通过 `localStorage`（`dsh-session-manager-dialog-opacity`）持久化，复用现有偏好存储，未新建存储系统；拖动滑块立即生效，无需重启 DSH。
+  - 透明度只作用于弹窗**背景填充**：新增插件自有变量 `--sm-dialog-opacity`，配合 `color-mix()` 施加到 DSH 的抬升表面 token（`--dsw-alias-bg-layer-1`）上。文字、按钮、输入框、标签、badge、边框、hover 与危险按钮颜色保持完全不透明，并继续跟随 DSH 主题变量。未使用整元素 `opacity`。
+  - **不破坏 token 自带 alpha**：默认 100% 时 `color-mix(in srgb, <token> 100%, transparent)` 会**原样**还原 token（含其自身 alpha），因此插件绝不会把 DSH（或主题重新发布的）半透明表面强行变为不透明；只有用户主动下调滑块时才会额外增加透明。输入框、textarea、select、按钮、菜单、filter、卡片等内部控件读取各自的 DSH token，不继承该透明度设置（「统一主题来源，不统一透明度」）。
+  - 未检测任何主题插件、未枚举主题名称、未读取第三方插件私有变量；第三方主题只需发布 `--dsw-alias-*` token 即可被继承。
+- **fix(css)**: 修复第三方主题被硬编码背景阻断的问题（Issue #23）：
+  - 原代码使用的 `--dsw-alias-surface-l1` 在 DSH 中并不存在，所有 `var(--dsw-alias-surface-l1, #fff)` 实际总是回退为硬编码 `#fff`；已改为真实的 DSH token（弹窗 `--dsw-alias-bg-layer-1`，对话框内输入/下拉与菜单 `--dsw-alias-bg-layer-2`）。
+  - 移除 `background:#fff!important` / `background-color:#fff!important` / `background:#1f1f23!important` / `background-color:#1f1f23!important` 强制锁色，以及弹窗根节点上多余的 `opacity:1` 与 `.sm-migrateDialog` 上的 `backdrop-filter:none`。
+  - 删除 `smApplyInlineTheme()`：它向弹窗根节点写入内联 `!important` 背景/文字/边框颜色，会无条件覆盖包括第三方主题在内的任何主题；浅色/深色适配改由 `html[data-sm-theme]` 作用域 CSS 与 token 回退值承担。
+  - 弹窗头部/主体/底部不再各自绘制不透明底色（迁移弹窗原本重绘 `#fff`），透明度因此只叠加一次，50% 设置不会被内部不透明层抵消。
+- **fix(plugin-css)**: 插件样式表按 `data-plugin-css` 去重时只创建不更新，导致客户端插件热重载后页面沿用旧版本 CSS（表现为「设置项已出现但样式不生效」）；现在每次加载都会重写样式表内容。
+- **feat(opacity)**: 统一接入透明度的弹窗：会话管理主面板 / 标记（annotation）面板（`.sm-panelDialog`、`.sm-annotationSurface`）、删除/移动/迁移确认弹窗（`.sm-confirmDialog .sm-nativeDialog`）、迁移预设弹窗（`.sm-migrateDialog`）、更新弹窗（`.sm-updateDialogLayer .sm-nativeDialog`）、批量操作弹窗（`.sm-bulkDialog .sm-nativeDialog`，含预览/进度/结果/标签/预设迁移）。
+- **test**: 新增 `test/client-dialog-opacity.test.mjs`（18 项）覆盖默认 100%、持久化与恢复、范围/步长归一化、设置卡片交互、样式表实际注入内容、热重载重写回归、「文字/按钮/输入/边框不随透明度变化」、「100% 原样保留 DSH token 自带 alpha（不做无意义的覆盖）」、「input / textarea / select / 菜单 / 卡片等内部控件不继承弹窗透明度且各自读取 DSH token」，以及「不得引用特定主题插件或第三方私有变量」的守卫；`test/helpers/client-harness.mjs` 增加 `rootStyleValues` / `styleTags` / `initialStorage` 观测点。
+- **refactor(theme)**: 插件不再自建一套独立的浅色/深色配色，改为直接消费 DSH 主题 token（Issue #23 后续）：
+  - **删除所有局部 `--dsw-alias-*` 重定义**。原 `[data-sm-theme=light]` / `[data-sm-theme=dark]` 规则曾把 `label-primary`、`label-secondary`、`label-tertiary`、`border-l1`、`border-l2`、`fill-l1`、`fill-l2`、`interactive-bg-hover`、`state-error-primary`、`accent-primary`、`accent-primary-bg`、`state-warning-primary` 全部改写为固定 hex，这会无条件覆盖任何主题（含第三方主题）对这些 token 的修改。现在 DSH 的 `--dsw-alias-*` 只被读取，从不赋值。
+  - **修正一批 DSH 中并不存在的 token**（它们的 `var()` 一直静默回退到硬编码字面量，是主题失效的真正原因）：`--dsw-alias-surface-l1` → `--dsw-alias-bg-layer-1`；`--dsw-alias-fill-l1` → `--dsw-alias-bg-layer-2`；`--dsw-alias-fill-l2` 按语义拆分 → `--dsw-alias-bg-layer-2`（内嵌面板）/ `--dsw-alias-markdown-tag`（标签、badge、chip）/ `--dsw-alias-bg-module-platform`（选中行、开关态）/ `--dsw-alias-interactive-bg-hover`（hover）/ `--dsw-alias-bg-skeleton`（进度槽）；`--dsw-alias-fill-l3` → `--dsw-alias-button-ghost-active-fill`；`--dsw-alias-accent-primary` → `--dsw-alias-state-business-primary`；`--dsw-alias-accent-primary-bg` → `--dsw-alias-state-business-tertiary`；`--dsw-alias-accent-primary-hover` → `--dsw-alias-button-info-hover`；`--dsw-alias-state-warning-primary` → `--dsw-alias-state-warn-primary`。
+  - **补齐语义化 token**：warn 提示框改用 `state-warn-tertiary` / `state-warn-label`，success 改用 `state-success-tertiary` / `state-success-primary`，error 与危险边框由 `state-error-primary` 经 `color-mix()` 派生（DSH 无 error tertiary），危险 hover 用 `interactive-bg-hover-danger`；填充式按钮的文字色改用 `--dsw-alias-label-primary-foreground`（浅色白字 / 深色深字，深色下蓝、红按钮对比度更好）。
+  - **删除被后续声明完全覆盖的固定颜色“旧浏览器双声明”**（如 `color:#111;color:var(…)`、`background-color:#356ae6;background-color:var(…)`、`border:1px solid #d4d4d8;border:1px solid var(…)`）；迁移弹窗不再残留 `#fff`/`#356ae6`/`#4576f0`/`#e8e8e8` 等固定色。
+  - **移除大量 `!important`**：`[data-sm-theme=dark]` 下所有 `background` / `background-color` / `color` / `border-color` 强制覆盖全部删除（settingsTag、settingsBadgeLink、updateVersionGrid、bulkSessionList、bulkProgressBar、settingsSelect、header/footer border 等），`.sm-headerBtnDanger:hover` 的三处也不再需要（选择器权重已足够）。保留的 8 条规则中：1 条颜色相关（`.sm-markIcon.sm-markOn`）取值是 `var(--dsw-alias-*)` token，因此不阻断主题，仅用于压过插件自身的同类颜色规则（原 `.sm-danger` / `.sm-dangerText` 两条颜色 `!important` 属死代码，见下方 fix(ui) 已删除）；`.sm-tooltip` 用于覆盖 DSH Tooltip primitive 的内联样式（Issue #21 回归守卫，边框同样使用 token）；其余 6 条为纯布局（overlay portal 提层、`.sm-updateDialogLayer` 居中、`@container` 隐藏、DSH 行 primitives 的文本对齐）。
+  - **保留的唯一浅/深色分支**：`--sm-dialog-surface-fallback`（透明度设置在 token 缺失时的回退底色）与 `.sm-priority-1/2`（优先级是插件自有语义，DSH 无对应 token）。
+  - 浅色/深色现值与改动前基本一致：`--dsw-alias-border-l2` 浅色等价于原 `#e5e5e5`、深色等价于原 `#3a3a40`，`--dsw-alias-interactive-bg-hover` 亦与原 `#eee` / `rgba(255,255,255,.06)` 基本等价。
+- **fix(ui)**: 修复「删除会话」按钮（标题栏 / 面板行 / 批量栏）在主题把表面 token 设为半透明或大面积色时看不清的问题：
+  - 根因：这些按钮的底片用的是**表面 token** `--dsw-alias-bg-layer-1`，而表面 token 可能带 alpha 或为大片区域选择的色相；按钮的文字用 `--dsw-alias-state-error-primary`，两者叠加后对比度不再可控（实测注入「洋红半透明表面 + 橙色错误色」时，橙字压在洋红底片上几乎不可读）。
+  - 修复：按钮底片改用 DSH 的**按钮**填充 token `--dsw-alias-button-floating-fill`（浅色 `#fff` / 深色 `#2c2c2e`，均不透明），语义上也是 §三 要求的「按钮 → 按钮 token」；涉及 `.sm-headerBtn`、`.sm-headerBtnDanger`、`.sm-bulkBar .sm-bulkBtn`。这样无论主题给表面 token 什么 alpha/色相，危险按钮的文字与图标都落在稳定的不透明按键底上。
+  - 面板行内危险按钮（透明底）新增专用 hover：`.sm-rowBtnDanger:hover` 使用 `--dsw-alias-interactive-bg-hover-danger`（与菜单里的危险项一致），不再复用普通 hover。
+  - 顺带删除**死代码** `.sm-danger` / `.sm-dangerText`（没有任何元素带这两个 class），它们是仅剩的两条颜色类 `!important`，删除后颜色类 `!important` 只剩 `.sm-markIcon.sm-markOn` 一条。
+- **fix(ui)**: 统一「会话标记」窗口里复制 Prompt / 导入区域的格式，使其与上方字段一致：
+  - 去掉该区域自带的表面底色（`--dsw-alias-bg-layer-2` 横条，在带色主题下会形成一条与弹窗主体不同色的色带），改为继承弹窗表面，仅保留与其它分区一致的上边框。
+  - 补齐与上方字段相同的「标签 + 字段」结构：新增 `AI 返回结果`（复用已有 `marks.import.paste.label` 文案）标签行，两个操作按钮改为靠右排列在同一行；粘贴框仍复用 `.sm-noteInput` / `.sm-fieldWithClear`。
+  - 修正内边距叠层：`.sm-importGroup` 改为 `padding:12px 16px`（与弹窗主体 16px 对齐），`.sm-importStatus` 的 `margin:0 16px` 改为 `margin:0`（原本在分组内边距之上又叠加 16px，导致状态框比其它内容缩进更多）。
+  - 导入/复制按钮由「表面色填充」改为与弹窗内其它按钮一致的描边样式（透明底 + `border-l2` + `label-primary`）。
+- **fix(ui)**: 统一全部弹窗的按钮设计（上一轮把迁移预设弹窗的按钮底色换成 `button-floating-fill` 后，它成了唯一「白色/深灰实底」的取消按钮）：
+  - **全部弹窗的次要/取消按钮统一为同一套规格**：`background:transparent` · `border:1px solid var(--dsw-alias-border-l2)` · `border-radius:8px` · `padding:3px 14px` · `min-height:28px` · `font-size:12px` · `line-height:20px`。迁移预设弹窗的实底取消按钮已改回透明；会话管理主窗口与标记窗口原先的 `6px` 圆角 / `3px 12px` / `18px` 行高也统一到同一规格。
+  - **hover 统一**：原先只有确认弹窗的 Cancel、迁移/更新弹窗的基类有 hover，批量弹窗、会话管理主窗口与标记窗口的取消按钮**完全没有 hover 反馈**；现合并为一条覆盖五个弹窗的 `.sm-nativeDialogCancel:hover` 规则（`--dsw-alias-interactive-bg-hover`）。标记窗口的取消按钮原先漏了 `sm-nativeDialogCancel` class，已补上以纳入统一规则。
+  - **填充态保持一致**：确认按钮一律 `state-business-primary` + `label-primary-foreground`，危险按钮一律 `state-error-primary` + `label-primary-foreground`（五个弹窗完全一致）。
+  - **标记窗口的导入/复制按钮**对齐到同一套对话框按钮规格（`min-height:28px` / `3px 14px` / `20px` 行高）。
+  - **批量工具栏按钮** `.sm-bulkBar .sm-bulkBtn` 由实底改为透明描边：其填充色与所在容器（`bg-layer-2`）在 DSH 默认浅/深色下取值相同（`#fff` / `#2c2c2e`），实底等同于无效，改为透明后与面板内其它按钮（`.sm-rowBtn`、`.sm-filterBtn`、`.sm-settingsCheckBtn`）一致。
+  - **删除死代码**：`.sm-nativeDialogGhost`、`.sm-panelHeaderSelect`（含 `:hover` / `:disabled` / `.sm-on`）从未被任何元素使用（有测试专门断言 JSX 不再使用 `sm-panelHeaderSelect`）。
+  - 设计约定（本次确立）：**弹窗动作按钮 = 28px 规格**（透明描边 + 单一 hover）；**面板内的密集控件**（行内操作 `.sm-rowBtn` 22px、筛选开关 `.sm-filterBtn` 24px、批量网格 `.sm-bulkBtn`）保持紧凑尺寸，但共用同一套「透明底 + `border-l2` + hover token」语言与填充态 token。
+- **fix(ui)**: 修复深色模式下插件下拉框（`<select>`）的弹出列表仍是白底、与全局主题不一致的问题：
+  - 根因：`<select>` 的弹出列表属于**浏览器原生 UA 控件**，它**不读取任何 `--dsw-*` token**。DSH 的机制是把解析后的配色投影给原生控件——ui-layout 的 `ThemePresenter` 订阅官方 `theme/change` 事件后执行 `documentElement.style.colorScheme = snapshot.active.colorScheme`（官方文档：`html { color-scheme }` for native UA chrome）。插件此前没有给 `<option>` 任何样式，于是列表项使用平台默认底色（白）。
+  - **插件不再声明 `color-scheme`**：曾有一版把插件镜像的浅/深色状态写成 `html[data-sm-theme=dark] …{color-scheme:dark}`。原生控件是 DSH 的职责——ui-layout 的 presenter 会在 `theme/change` 时写入 `documentElement.style.colorScheme`；插件一旦与 DSH 的投影不一致（镜像判错或过期），就会把原生控件锁在相反的配色上，表现为「切到浅色模式后下拉列表仍然是深色」。现已删除：DSH 是原生控件的唯一权威，插件只负责列表项本身的颜色。
+  - 修复（列表项本身）：给插件自有表面内的 `<option>` 显式指定 DSH token——`background-color:var(--dsw-alias-bg-layer-3)` + `color:var(--dsw-alias-label-primary)`，选中项用 accent 文字色标记（`--dsw-alias-state-business-primary`），禁用项 `--dsw-alias-label-tertiary`。
+    - **为什么是 layer-3 而不是控件自身的 layer-2**：浮动列表必须保持不透明。主题可能给 `bg-layer-2` 加上 alpha，半透明填色叠在原生弹出列表自身的底上仍然呈现为白/浅色（第一版修复看起来「没生效」即由此而来）。`--dsw-alias-bg-layer-3` 在 DSH 调色板中是不透明的（浅色 `#fff` / 深色 `#353638`），且语义上是位于弹窗（layer-1）与控件（layer-2）之上的一层。选中行改用文字色而非填充色，同样避免任何半透明 token 把它冲淡。
+  - 作用范围只限插件自有表面内的 `option`，不会影响 DSH 自己的下拉框；插件全部 7 个 `<select>`（面板的工作区/排序/标签/优先级筛选、弹窗内的选择器、设置卡片的安装源）都位于这四个表面之内，无需逐个枚举 class。
+  - 已知平台边界：若宿主把 `<select>` 弹出列表交给**操作系统**绘制（Windows 下 Electron/浏览器在某些版本上如此），该列表将忽略页面 CSS，包括 `option` 样式；DSH 桌面端通过把主题同步到 Electron `nativeTheme.themeSource` 规避了这一点，浏览器端没有该通道。这种情况下唯一的通用解法是不使用原生 `<select>`，改为用 DSH 的 `Menu` primitive 渲染 HTML 下拉层（DSH 自身产品界面即如此，其 primitive 包中并没有 `Select`，只有 `Menu`）。
+- **fix(theme)**: 主题镜像改用 DSH 官方事件，不再只靠 DOM 属性观察：`ctx.on("theme/change", () => smApplyTheme())`（ui-layout 的 presenter 在同一事件上投影配色）。原先只靠 MutationObserver 观察 `class` / `data-ds-dark-theme` / `style` 等属性，若某个主题只改 token 值而不触碰这些属性，`data-sm-theme` 镜像就会过期。该镜像现在只影响两处装饰性分支（token 缺失时的透明度回退底色、优先级颜色），并被测试锁定为**不得**声明 `color-scheme`、不得重定义任何 `--dsw-*` token。
+- **test(theme)**: 新增 `test/client-theme-tokens.test.mjs`（6 项）：逐个校验插件引用的每个 `--dsw-*` token 都存在于按 DSH 0.2.0-rc.2 主题 token 表固化的白名单中（杜绝再次凭空发明 token）、插件从不重定义 DSH token、浅/深色分支被限制在允许的两处、不存在任何主题插件检测/枚举/私有变量读取、15 类 UI 语义各自引用对应 token、以及弹窗透明度设置（名称/默认值/范围/存储键/color-mix 结构）未被改动。同步更新 6 个原有 static guard，使它们校验新的等价实现而非旧的硬编码字符串。
+- **fix(ui)**: 修复弹窗内 tooltip 被弹窗自身遮住的问题（会话管理窗口标题栏的 GitHub / npm / 关闭图标，以及面板内所有带提示的按钮）：
+  - 根因：插件通过 DSH 的 `Tooltip` primitive（`renderTip`）渲染提示，而该气泡的 z-index 是**写死的**（内联 100、portal 到 body 时 1100），且不转发 `className`，插件无法单独抬高它；同时插件把面板设为 `z-index:9999`、portal 根节点设为 `99999`，因此任何插件界面都会盖住 1100 档的提示气泡。
+  - 修复：把插件的两个文档级图层收进 DSH 自己的层级区间——面板 `9999 → 1020`，`#dsh-session-manager-overlay-root` `99999 → 1050`（CSS 与运行时内联值同步）。DSH 的层级为 `1000`（模态遮罩/全屏遮罩）与 `1100`（浮层：菜单、popover、对话框、tooltip），插件保持在 `1000..1100` 之间，因此提示与 DSH 浮层都能正常压在插件界面之上，而插件界面仍在 DSH 页面内容与遮罩之上。
+  - portal 根节点内部各对话框的静态 z-index（确认 10000 / 迁移 10001 / 批量 10002 / 更新 10010 / 标记 100002+）与 `nextDialogZ()` 计数器都在该 stacking context 内部解析，取值本身不参与与 DSH 的层级竞争，故未改动，仅在代码与注释中固化层级契约。
+- **test(ui)**: 新增层级回归守卫：断言 overlay root 与面板的 z-index 严格位于 DSH `1000..1100` 区间、面板低于 overlay root、内联值与 CSS 一致、提示仍走 DSH primitive + body portal；并在代码注释中固化「不要把插件图层抬到 1100 以上」的契约（测试总数 364）。
+- **docs**: 明确验证范围——自 0.6.3 起本插件**仅在官方 DSH Desktop 客户端上进行验证**，Web UI 与本插件共用同一套 Host / 客户端代码但不再纳入验证范围。中英文 README 的「简介」与「兼容性」章节均已注明。
+
+## 0.6.2 — 2026-10-02
+
+- **fix(ui)**: 修复删除当前打开的会话后未自动跳转的问题：删除当前会话时显式调用 `ctx.uiWorkspace.clearMain()` 并回退触发新建会话，使界面正确跳转到新建会话欢迎视图，与会话归档行为保持一致。
+- **fix(css)**: 修复无作用域全局样式覆盖宿主组件的缺陷（Issue #21）：移除未带前缀的全局规则选择器 `[role=tooltip]`, `.bubble`, `[class*=bubble]`, `.tooltip`，仅保留插件作用域 `.sm-tooltip`，避免给 DSH 官方消息气泡强加 1px 边框；将 tooltip 浮层 z-index 调降回官方 Toast 档位（1100）。
+- **fix(ui)**: 优化顶部标题栏动作按钮排列与显示（归档按钮置于首位、图标垂直居中对齐、紧凑折叠菜单定位保持跟随）。
+- **feat(update)**: add self-update checking and installation workflow:
+  - Header 🐋 (Whale) icon button: checks for updates against the npm registry with indicator badge / red dot notification when a new version is released.
+  - Update Dialog (`UpdateDialog`): modal overlay displaying current and latest versions, check progress, and one-click update via the DSH Plugin Manager `installBundle()`.
+  - Update state management (`UpdateStore`): unified state machine (`idle`, `checking`, `available`, `updating`, `done`, `error`) with development overrides (`window.__DSH_SM_TEST_UPDATE__`).
+  - Host update endpoints: `GET /session-manager/api/update/check` and `POST /session-manager/api/update/install`.
+- **feat(settings)**: add Settings Card (`SessionManagerSettingsCard`) registered in DSH Settings under `settings.plugin.item` (`key: "dsh-session-manager"`):
+  - Displays current version, latest version, inline check/update buttons, auto-check for updates toggle, and GitHub repository link.
+  - **Install Source (Registry)**: add a registry source dropdown allowing users to select between **npm official registry** (`registry.npmjs.org`, default) and **China mainland mirror** (`registry.npmmirror.com`). Both check and install requests flow directly through the selected registry and the preference is persisted in `localStorage`.
+- **feat(ui)**: responsive Header layout enhancements:
+  - Header actions use Container Queries (`@container (max-width: 720px)` and `@container (max-width: 520px)`): automatically transitions between full labels, 32×32 icon-only compact mode, and secondary action overflow menu (`⋯`).
+  - Surface buttons: `.sm-headerBtn` styled with opaque background tokens for consistent visibility across light/dark themes.
+  - Danger button: unified red text/border resting state and filled red hover state.
+- **fix(ui)**: overlay root, stacking context, and footer fixes:
+  - Dedicated Overlay Root (`#dsh-session-manager-overlay-root`) ensures dialogs break out of ancestor stacking contexts (fixing issue #19).
+  - Dynamic z-index layering (`nextDialogZ()`) ensures dialogs stack properly above panels and other overlays.
+  - Footer action (`FooterAction`): renders directly as native buttons in wide/rail modes, avoiding double container wrappers and layout overflow (fixing issue #20).
+- **test**: comprehensive test suite expansion: added coverage for semver comparisons, UpdateStore state machine, UpdateDialog, Settings Card, responsive header layout, registry source switching, Host update endpoints, delete-current-session navigation and regression guards (338 tests total).
+
 ## 0.5.4 — 2026-09-30
 
 - **docs**: update project description and metadata to reflect official Web UI and Desktop app support; clarify client synchronization, install profiles, and runtime requirements.

package/README.md

@@ -11,7 +11,7 @@ English | [中文](README.zh.md)
 
 DeepSeek Harness session manager: delete, archive, move sessions across workspaces, migrate presets, favorites, review-later, search, filter, sort, prioritize, add tags and notes, and batch-manage sessions.
 
-Verified with the current official DSH Web UI and Desktop app. Both environments use the same plugin's Host/client functionality; environment-specific installation notes are documented below.
+Verified with the official DSH Desktop client; see [5 Compatibility](#5-compatibility) for the current verification scope. Both environments use the same plugin Host/client functionality; environment-specific installation notes are documented below.
 
 ## 1 Features
 
@@ -42,6 +42,14 @@ Verified with the current official DSH Web UI and Desktop app. Both environments
   - Non-destructive actions (archive / unarchive / favorite / unfavorite / review / unreview / add-tags / clear-tags / set-priority / move / preset-migrate) fire immediately and report per-session results in a **result dialog** with **Success / Failed / Skipped** groups and a one-click **Retry failed** that re-arms the failed IDs into the selection.
   - Destructive actions (**delete session**) first open a **preview dialog** listing the targeted sessions, then show a progress bar, then a per-id result dialog.
 
+### 1.4 Plugin updates and settings
+
+- **Self-update check**: A 🐋 (Whale) icon button in the session manager panel header checks for updates and displays a notification dot when a new version is available. Click to open the update dialog with current and latest versions, and one-click update via the DSH Plugin Manager.
+- **Settings Card**: Registered under DSH Settings (`settings.plugin.item`). Displays current version, latest version, inline check/update buttons, an auto-check toggle, and GitHub repository link.
+- **Install Source (Registry)**: Select between **npm official registry** (`registry.npmjs.org`, default) and **China mainland mirror** (`registry.npmmirror.com`) in the Settings Card. Check for updates and download packages directly from the selected registry.
+- **Dialog opacity**: A 50%–100% slider (5% steps, default 100%) in the Settings Card's preferences section, with a "Reset to default" button. It tunes the plugin dialog **background fill only** — text, buttons, inputs, tags, badges, borders, hover and danger colours stay fully opaque and keep following the active DSH theme. Implemented with the plugin's own `--sm-dialog-opacity` variable mixed into DSH's raised-surface token via `color-mix()`, so any theme that publishes `--dsw-alias-*` tokens is honoured without the plugin detecting, naming or reading private variables of a theme plugin. Persisted in `localStorage` (`dsh-session-manager-dialog-opacity`) and applied live.
+- **Theme**: The whole UI (dialogs, settings card, title-bar buttons, dropdown menus, inputs, selects, badges, tooltips, row hover/selected states) reads DSH's own `--dsw-alias-*` tokens directly. The plugin never redefines a DSH token and keeps no private light/dark palette, so any theme — including a theme plugin — that modifies or republishes those tokens is picked up automatically. The only light/dark branches left are the token-less fallback colour for the dialog-opacity fill and the plugin-specific priority colours. Every `--dsw-*` reference is locked to the token set DSH actually declares, because a non-existent token would silently degrade to its hard-coded fallback and block theming.
+
 ## 2 UI entry points
 
 ### 2.1 Title bar
@@ -56,6 +64,10 @@ Open the **Session manager** panel from the bottom of DSH's sidebar to browse ev
 
 The **Batch process** button in the session manager panel header is the entry point: click it once to enter batch process (row checkboxes appear, the **Select all in filter / Clear selection** pair and the bulk action bar show up); click it again to exit batch process.
 
+### 2.4 Settings Card
+
+Navigate to DSH Settings -> Plugins -> Session Manager to inspect versions, switch between npm official and China mainland mirror registries, toggle auto-update checks, or trigger updates.
+
 ## 3 Installation
 
 ### 3.1 Install from Plugins
@@ -118,9 +130,11 @@ After changing plugin dependencies, `package.json`, bundle configuration, or oth
 
 DSH versions are shown above plugin versions; each column represents a tested version combination.
 
+> Verification note: from 0.6.3 on, this plugin is verified with the official DSH Desktop client only (the Web UI shares the same Host/client code but is no longer covered by the verification matrix).
+
 | v0.2.0-rc.2 | v0.1.7-rc.2 | v0.1.7-rc.1 |
 | --- | --- | --- |
-| 0.5.4 | 0.5.3 | 0.5.2 |
+| 0.6.3, 0.6.2, 0.5.4 | 0.5.3 | 0.5.2 |
 
 | v0.1.6-alpha.2 | v0.1.5-rc.2 | v0.1.5-rc.1 |
 | --- | --- | --- |

package/README.zh.md

@@ -11,7 +11,7 @@
 
 DeepSeek Harness 会话管理插件：支持删除、归档、跨工作区移动、预设迁移、收藏、待回看、搜索、筛选、排序、优先级、标签、备注及批量操作。
 
-当前版本已在官方新版 DSH Web UI 与 Desktop 客户端完成实际测试；两种环境共用本插件的 Host 与客户端功能，具体安装方式见下文。
+已在官方 DSH Desktop 客户端完成实际测试，当前验证范围见「5 兼容性」；两种环境共用本插件的 Host 与客户端功能，具体安装方式见下文。
 
 ## 1 功能
 
@@ -40,6 +40,14 @@ DeepSeek Harness 会话管理插件：支持删除、归档、跨工作区移动
   - **变更操作**：**添加标签 / 清空标签 / 设置优先级 / 移动至工作区 / 迁移预设 / 删除会话**。
 - **执行流程**：非破坏性操作（归档 / 取消归档 / 收藏 / 取消收藏 / 待回看 / 取消待看 / 添加标签 / 清空标签 / 设置优先级 / 移动至工作区 / 迁移预设）立即执行，结果按会话逐条展示在 **结果对话框** 的 **成功 / 失败 / 跳过** 分组里，并提供 **重试失败项** 一键把失败 ID 重新加入选中；破坏性操作（**删除会话**）先弹 **预览对话框** 列出受影响的会话，再显示进度条，最后给出逐条结果。
 
+### 1.4 插件更新与设置卡片
+
+- **检查更新**：会话管理窗口顶部增加 🐋（鲸鱼）图标按钮，点击可检查新版本并在有更新时展示小红点提示；点击弹出更新窗口，展示当前版本与最新版本，支持一键调用插件管理器安装更新。
+- **设置卡片**：注册在 DSH 设置的插件配置页（`settings.plugin.item`）。展示当前安装版本、最新版本状态、卡片内检查更新与更新按钮、自动检查偏好开关以及 GitHub 仓库链接。
+- **安装源选择**：在设置卡片中可随时切换安装源，可选 **npm 官方源**（`registry.npmjs.org`，默认）与 **中国大陆镜像源**（`registry.npmmirror.com`）；检查更新与版本下载将直接请求所选源。
+- **弹窗透明度**：设置卡片「偏好设置」区域提供 50%–100% 滑块（步长 5%，默认 100%），并提供「恢复默认」按钮。该设置只调整插件弹窗的**背景填充**：文字、按钮、输入框、标签、badge、边框、hover 与危险按钮颜色保持完全不透明，并继续跟随 DSH 当前主题。实现方式为插件自有变量 `--sm-dialog-opacity` 通过 `color-mix()` 作用于 DSH 的抬升表面 token，因此任何发布 `--dsw-alias-*` token 的主题都能被继承——插件不会检测主题插件、枚举主题名称，也不会读取第三方插件的私有变量。设置保存在 `localStorage`（`dsh-session-manager-dialog-opacity`）并即时生效。
+- **主题**：整个界面（弹窗、设置卡片、标题栏按钮、下拉菜单、输入框、下拉选择、badge、tooltip、行 hover / 选中态）直接读取 DSH 自己的 `--dsw-alias-*` token。插件从不重新定义 DSH token，也不再维护私有的浅色/深色配色，因此任何修改或重新发布这些 token 的主题（含第三方主题插件）都会自动生效。仅剩的浅/深色分支只有两处：透明度设置在 token 缺失时的回退底色，以及插件自有的优先级颜色。所有 `--dsw-*` 引用都被锁定在 DSH 实际声明的 token 集合内——引用不存在的 token 会静默回退到硬编码颜色，从而阻断主题。
+
 ## 2 UI入口
 
 ### 2.1 标题栏入口
@@ -54,6 +62,10 @@ DeepSeek Harness 会话管理插件：支持删除、归档、跨工作区移动
 
 会话管理窗口顶部的 **批量处理** 按钮即是入口：点一下进入批量模式，行左侧出现复选框，工具栏出现 **全选当前筛选 / 清空选择** 和 **批量按钮区**；再点一次退出批量模式。
 
+### 2.4 设置卡片入口
+
+在 DSH 设置中进入插件设置页（会话管理），可查看版本信息、切换 npm 官方源或中国大陆镜像源、开启/关闭自动检查更新，或手动检查并更新。
+
 ## 3 安装
 
 ### 3.1 从插件安装
@@ -116,20 +128,20 @@ dsh plugin --profile web add <本仓库路径>
 
 DSH 版本在上，插件版本在下；每列表示一组已测试的版本组合。
 
+> 版本验证说明：自 0.6.3 起，本插件仅在官方 DSH Desktop 客户端上进行验证（Web UI 与本插件共用同一套 Host / 客户端代码，但不再纳入验证范围）。
+
 | v0.2.0-rc.2 | v0.1.7-rc.2 | v0.1.7-rc.1 |
 | --- | --- | --- |
-| 0.5.4 | 0.5.3 | 0.5.2 |
+| 0.6.3, 0.6.2, 0.5.4 | 0.5.3 | 0.5.2 |
 
 | v0.1.6-alpha.2 | v0.1.5-rc.2 | v0.1.5-rc.1 |
 | --- | --- | --- |
 | 0.5.1 | 0.4.11 | 0.4.10, 0.4.9, 0.4.7 |
 
-| 0.1.3-alpha.2 | v0.1.2-rc.1 | v0.1.0-rc.7 |
 | v0.1.3-alpha.2 | v0.1.2-rc.1 | v0.1.0-rc.7 |
 | --- | --- | --- |
 | 0.4.6, 0.4.4, 0.4.1 | 0.4.0 | 0.1.2, 0.1.1, 0.1.0 |
 
-以上版本组合已在官方 Web UI 和 Desktop 客户端中完成测试。其他版本组合可能同样兼容，但未逐一验证。
 以上版本组合已在官方 Web UI 或 Desktop 客户端中完成测试。其他版本组合可能同样兼容，但未逐一验证。
 
 使用独立 DSH CLI / runtime 时，需要 Node.js 22.15+（22.x）或 24+，以提供内置 Zstd 支持。官方 Desktop 客户端单独携带并管理与其版本匹配的 runtime。

package/lib/annotation-store.js

@@ -46,7 +46,7 @@ export function normalizeAnnotationPatch(patch) {
   return out;
 }
 
-export function createAnnotationStore(directory, { io = fs, lockWaitMs = 1500 } = {}) {
+export function createAnnotationStore(directory, { io = fs, lockWaitMs = 3000 } = {}) {
   if (typeof directory !== "string" || !directory) throw fail("无法定位会话标记目录", "annotations-unavailable");
   const root = resolve(directory);
   const path = join(root, "annotations.v1.json");