dsh-session-manager 0.5.3 → 0.6.2

package/CHANGELOG.md

@@ -1,4 +1,31 @@
 
+## 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.
+
 ## 0.5.3 — 2026-09-26
 
 - **fix**: issue #17.2 (panel `MoveDialog` now forwards `t` so labels render translated) and issue #17.4 (row Open unarchives archived sessions first).
@@ -15,7 +42,7 @@
 
 ## 0.5.2 — 2026-09-23
 
-- **fix(bulk management)**: add a missing entry-point for batch operations. The previous build gated the row checkboxes and `BulkActionBar` behind `selectedIds.size > 0`, so neither was ever reachable from the UI. A new **Select / 选择** toggle in the panel header now reveals the row checkboxes and the bulk action bar; toggling it a second time clears the selection and exits selection mode. Selection-mode state is also reset whenever the panel closes.
+- **fix(bulk management)**: add a missing entry-point for batch operations. The previous build gated the row checkboxes and `BulkActionBar` behind `selectedIds.size > 0`, so neither was ever reachable from the UI. A new **Select** toggle in the panel header now reveals the row checkboxes and the bulk action bar; toggling it a second time clears the selection and exits selection mode. Selection-mode state is also reset whenever the panel closes.
 
 - **fix(bulk management)**: the SessionManagerPanel had a duplicated `return` statement above the bulk-dialog declarations (`bulkPreviewDialog`, `bulkProgressDialog`, `bulkResultDialog`, `bulkTagDialog`, `bulkPriorityDialog`, `bulkMoveDialog`, `bulkPresetDialog`). The early return made every bulk dialog unreachable, so the user never saw the confirmation preview, progress bar, or per-id success / failed / skipped result dialog. The duplicate return has been removed; the panel now keeps every dialog declaration live and renders them all in the final Fragment.
 
@@ -27,7 +54,7 @@
 
   2. **favorite / review / set-priority / add-tags / remove-tags** threw `annotations is not a function` on the first id because the original `runBatchAction` signature destructured `annotations` from its parameter object and callers did not pass it. `runBatchAction` now resolves the annotation accessor from the surrounding closure so it can never again be silently `undefined`.
 
-  3. **unfavorite / unreview** were not in the `BATCH_ACTIONS` set and were rejected with `action 不支持: unfavorite`. Both are now first-class annotation actions; `annotationPatchFromBatchAction` maps them to `{ favorite: false }` / `{ reviewLater: false }`.
+  3. **unfavorite / unreview** were not in the `BATCH_ACTIONS` set and were rejected with `action not supported: unfavorite`. Both are now first-class annotation actions; `annotationPatchFromBatchAction` maps them to `{ favorite: false }` / `{ reviewLater: false }`.
 
   4. the `BATCH_ACTIONS` set, the annotation action set inside `runBatchAction`, and `annotationPatchFromBatchAction` have been kept in sync.
 
@@ -46,19 +73,19 @@
 
 - **feat(annotations)**: add favorites, manual review flags, tags, multiline notes and priority (1 highest → 5 lowest, default **3 Normal**) to the manager and title bar. Add annotation search/filtering and priority sorting. Persist separately from session history with atomic writes, an inter-process lock, strict limits, conflict detection and deletion cleanup; synchronize browser surfaces and preserve unsaved drafts on failure.
 
-- **feat(annotations)**: add an opt-in AI-assisted workflow in the annotation editor. A **Copy Prompt** / **复制 Prompt** button copies a strict-JSON prompt (Chinese or English, matched to the UI locale) to the clipboard for the user to paste into the current conversation. An **Import** / **导入** button reads the clipboard, extracts the first JSON object (tolerating Markdown fences, conversational wrappers, smart quotes, stray backslashes and a leading BOM), validates tags/note/priority against the same limits, and populates the editor fields. Oversized notes are truncated and flagged in the status message; invalid tags/priority are dropped with reasons. Importing into a dirty draft triggers a confirm. Both buttons stay out of the conversation history — the plugin never calls the model directly. The parser is also exported as `parseClipboardAnnotation` from `lib/clipboard-parser.js` for tests and potential server-side reuse.
+- **feat(annotations)**: add an opt-in AI-assisted workflow in the annotation editor. A **Copy Prompt** button copies a strict-JSON prompt (Chinese or English, matched to the UI locale) to the clipboard for the user to paste into the current conversation. An **Import** button reads the clipboard, extracts the first JSON object (tolerating Markdown fences, conversational wrappers, smart quotes, stray backslashes and a leading BOM), validates tags/note/priority against the same limits, and populates the editor fields. Oversized notes are truncated and flagged in the status message; invalid tags/priority are dropped with reasons. Importing into a dirty draft triggers a confirm. Both buttons stay out of the conversation history — the plugin never calls the model directly. The parser is also exported as `parseClipboardAnnotation` from `lib/clipboard-parser.js` for tests and potential server-side reuse.
 
 - **feat(annotations)**: add inline clear buttons inside the **Tags** and **Note** fields of the annotation editor. Each button only appears while the corresponding field has content and clears it without touching the other controls. Both buttons are disabled while a save is in flight and respect the existing Escape / IME handling.
 
-- **feat(annotations)**: redesign the annotation editor layout. Favorite and review flags stack vertically on the left; priority and its small help text occupy the right column. The **Tags**, **Note**, and AI **paste** textareas all share the same `sm-noteInput` style and `rows: 3` height (60px min-height), so the three input boxes line up visually. The "{count} / 2000 字符" note counter and the "仅用于会话整理" privacy hint are removed; help text is moved into each input's `placeholder`. In the AI paste block the two buttons now sit **above** the paste textarea (导入 on the left, 复制 Prompt on the right) so the editor footer stays consistent. The priority label now uses the same 13px font as the favorite / review checkboxes.
+- **feat(annotations)**: redesign the annotation editor layout. Favorite and review flags stack vertically on the left; priority and its small help text occupy the right column. The **Tags**, **Note**, and AI **paste** textareas all share the same `sm-noteInput` style and `rows: 3` height (60px min-height), so the three input boxes line up visually. The "{count} / 2000 chars" note counter and the privacy hint are removed; help text is moved into each input's `placeholder`. In the AI paste block the two buttons now sit **above** the paste textarea (Import on the left, Copy Prompt on the right) so the editor footer stays consistent. The priority label now uses the same 13px font as the favorite / review checkboxes.
 
-- **feat(annotations)**: remove the "未设置 / Not set" priority option. Priority is always one of 1–5, and the default is **3 (Normal)**; legacy data with `priority: null` is normalized to 3 in display, sort and filter, so there is no longer a separate "always-sorts-last" state. The priority filter dropdown, row badges and header badge all reflect the unified 1–5 scale; AI-returned `"priority": null` is also normalized to 3 by the clipboard parser. The priority help text now reads "1 最高，5 最低，默认 3（普通）" / "1 is highest, 5 is lowest. Default is 3 (Normal)."
+- **feat(annotations)**: remove the "Not set" priority option. Priority is always one of 1–5, and the default is **3 (Normal)**; legacy data with `priority: null` is normalized to 3 in display, sort and filter, so there is no longer a separate "always-sorts-last" state. The priority filter dropdown, row badges and header badge all reflect the unified 1–5 scale; AI-returned `"priority": null` is also normalized to 3 by the clipboard parser. The priority help text now reads "1 is highest, 5 is lowest. Default is 3 (Normal)."
 
 - **fix(annotations)**: in the manager's row badges, P1–P5 now always render (legacy `null` renders as P3) so the priority column is visually consistent across all rows instead of being absent for unset entries. The header shortcut button likewise always shows the current P-number badge.
 
 - **fix(annotations)**: the AI copy/paste prompt now follows the active UI language. The dialog detects the language from the t() function (probing `marks.favorite`) instead of relying on `window.__smActiveLanguage`, which was never set; the prompt button writes Chinese under a Chinese UI and English under an English UI even when the global flag is missing.
 
-- **fix(annotations)**: the AI paste workflow's error message now appends the actual `JSON.parse` error position from each recovery attempt (原始 / 修复引号/反斜杠 / 扫描对象 / 扫描对象+修复), so users can see exactly which character broke parsing when the auto-repair still fails. The parser also strips a leading UTF-8 BOM, normalizes smart quotes, and repairs stray single backslashes inside string values.
+- **fix(annotations)**: the AI paste workflow's error message now appends the actual `JSON.parse` error position from each recovery attempt (raw / fix quotes & backslashes / scan object / scan object + fix), so users can see exactly which character broke parsing when the auto-repair still fails. The parser also strips a leading UTF-8 BOM, normalizes smart quotes, and repairs stray single backslashes inside string values.
 
 - **feat(annotations)**: tag input accepts both English `,` and Chinese `，` as separators (regex `/[,，\n]/`), trims whitespace around each tag, drops empty entries, and merges case-insensitive duplicates — so AI outputs in either locale parse cleanly without the user having to re-type the separator.
 
@@ -136,7 +163,7 @@
   DSH 0.1.5-rc.1's persistence backend writes generation v3 artifacts at
   that filename; the 0.4.6 release scanned only v2/plaintext names, so
   fresh sessions appeared to have no disk record and the move/migrate
-  endpoints failed with "会话没有磁盘记录" / "session has no artifact".
+  endpoints failed with "session has no artifact".
 
 - **chore**: bump version to 0.4.7.
 
@@ -170,7 +197,7 @@
   called `ctx.agents.resume` to re-create the agent. DSH's `agent/status` event
   is only emitted on phase changes, so a freshly resumed agent never told the
   client it was now idle, leaving the sidebar's model selector and send button
-  disabled ("会话不可用") until a manual browser refresh. The new path flushes
+  disabled ("session unavailable") until a manual browser refresh. The new path flushes
   pending events to disk, updates the in-memory session header + coordinator
   state + workspace accounting in place, and atomically renames the artifact,
   so the agent's UI keeps showing the same in-memory session with no client
@@ -188,7 +215,7 @@
 
 ## 0.4.4 — 2026-09-03
 
-- **docs**: rename the English README wording from `conversation` to `session` to align with the plugin name (`dsh-session-manager`), the Chinese README (`会话`), the DSH host APIs, and the [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) registry entry.
+- **docs**: rename the English README wording from `conversation` to `session` to align with the plugin name (`dsh-session-manager`), the Chinese README (`README.zh.md`), the DSH host APIs, and the [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) registry entry.
 - **chore**: rewrite `package.json` `description` to use `Session manager` / `sessions` for the same alignment, and bump the version to `0.4.4`.
 - **chore(repo)**: update the GitHub repository description to match.
 

package/README.local-workflow.md

@@ -0,0 +1,52 @@
+# AI Dev Workflow Template
+
+核心关系：
+```text
+AGENTS.md = Agent 统一入口
+.ai/      = 工作流和项目知识的唯一事实来源
+.codex/   = 由脚本从 .ai/skills 生成的 Codex Skill 转发层（不要手改）
+```
+
+## 新项目第一次使用
+复制到项目根目录后，先让 AI 初始化：
+- `.ai/architecture.md`
+- `.ai/safety.md`
+- `.ai/project-commands.md`
+
+推荐启动指令：
+```text
+先不要开始开发。
+请读取 AGENTS.md 和当前项目，帮我初始化 .ai 下的项目知识和验证规则。
+重点完善：
+- .ai/architecture.md
+- .ai/safety.md
+- .ai/project-commands.md
+只写能够从当前项目确认的事实；不确定的地方标记“待确认”，不要猜。
+填写完成后把每个文件头部的「最后核对日期」改成今天。
+暂时不要修改业务代码。
+```
+
+
+## 常用 Skill
+- requirements-grill
+- regression-fix
+- code-review
+- high-risk-review
+- release-check
+
+## 维护 Skill
+只改 `.ai/skills/<name>/SKILL.md`，然后重新生成转发层（PowerShell 7）：
+```powershell
+.\sync-codex-skills.ps1          # 生成 / 更新 .codex/skills，删除已不存在的 skill
+.\sync-codex-skills.ps1 -Check   # 只比对不写入，有漂移则报错
+```
+生成文件带日期标记；内容未变时不会重写，可重复运行。
+
+## 本地忽略（仅 Git 仓库需要）
+PowerShell 7，在主仓库根目录运行：
+```powershell
+.\setup-local-workflow.ps1
+```
+脚本会校验 `.git` 是真实的仓库根目录（不是 worktree / submodule 的 `.git` 文件），写入 `.git/info/exclude`，然后自动执行一次 `sync-codex-skills.ps1`。非 Git 仓库不需要运行；运行了会直接报错退出，不会写任何东西。
+
+然后运行 `git status` 确认本地 AI 文件未进入待提交列表。

package/README.md

@@ -9,7 +9,9 @@ English | [中文](README.zh.md)
 
 ## 0 Overview
 
-DSH Web session manager: delete, archive, move across workspaces, migrate preset; favorites, review-later, search, sort, priority, add tags and notes; bulk processing. Suggestions and feedback are welcome on GitHub.
+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.
 
 ## 1 Features
 
@@ -28,7 +30,7 @@ DSH Web session manager: delete, archive, move across workspaces, migrate preset
 - **Priority** is a dropdown **1 Highest, 2 High, 3 Normal, 4 Low, 5 Lowest**, default **3 (Normal)**; legacy `null` priorities are normalized to 3.
 - **Tags / Notes**: up to 20 tags per session (≤ 32 characters each) and a 2000-character note. Both English `,` and Chinese `，` are separators, whitespace is trimmed, duplicate tags are merged case-insensitively.
 - **AI-assisted tagging** is manual and opt-in: **Copy Prompt** writes a structured prompt (Chinese or English, matched to the active UI) to the clipboard; **Import** parses the clipboard JSON (tolerating Markdown fences, conversational wrappers, smart quotes, stray backslashes and a leading BOM), validates it against the same limits, and populates the editor fields. Neither button calls a model automatically.
-- Annotations live in plain text under the DSH home (`dsh-session-manager/annotations.v1.json`), keyed by session ID. Same-origin browser tabs stay in sync via `BroadcastChannel`. Saves are durable across crashes; revision conflicts surface a "load latest" prompt.
+- Annotations live in plain text under the DSH home (`dsh-session-manager/annotations.v1.json`), keyed by session ID. Same-origin client instances stay in sync via `BroadcastChannel`. Saves are durable across crashes; revision conflicts surface a "load latest" prompt.
 
 ### 1.3 Bulk management
 
@@ -40,6 +42,12 @@ DSH Web session manager: delete, archive, move across workspaces, migrate preset
   - 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.
+
 ## 2 UI entry points
 
 ### 2.1 Title bar
@@ -54,32 +62,58 @@ 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.
 
-## 3 Install
+### 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
 
-### 3.1 From the official plugin management
+In DSH, open **Plugins**, add a plugin, search for `dsh-session-manager`, and install it. This method is supported by both the official Web UI and Desktop app.
 
-Go to **plugin management** inside DSH, search for `dsh-session-manager`, and install it.
+### 3.2 Install from Third-Party Plugin Markets
 
-### 3.2 From dsh-market
+This plugin is listed in [dsh-market](https://github.com/dsh-market/dsh-market) and [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin).
+
+### 3.3 Install to the Web profile via CLI
+
+Install from npm:
 
 ```powershell
 dsh plugin --profile web add npm:dsh-session-manager
 ```
 
-### 3.3 From GitHub
+Install from GitHub:
 
 ```powershell
 dsh plugin --profile web add github:hkkz9522/dsh-session-manager
 ```
 
-After installing, restart DSH Web. If the browser still holds an older client bundle, force-refresh with `Ctrl+Shift+R`.
+Restart DSH Web after installation. If the browser still loads an older client bundle, use `Ctrl+Shift+R` to force-refresh the page.
+
+> The `desktop` profile is managed by the official Desktop app and is not intended to be modified with the regular `dsh` CLI. Desktop users should install the plugin through **Plugins** in the app.
+
+### 3.4 Local Development / Testing
+
+#### Web profile
 
-### 3.4 Local development / runtime injection
+Install the local repository via CLI:
 
-```text
-dev_inject_plugin {"dir": "<absolute path to this repository>"}
+```powershell
+dsh plugin --profile web add <path-to-this-repository>
 ```
 
+The local repository is linked to the current profile as a plugin checkout, making it suitable for modifying the source code directly and testing changes.
+
+#### Desktop app
+
+Open **Plugins** in the official Desktop app and use the absolute path to the local repository as the installation source.
+
+For client-side code, changes can be reloaded automatically after saving when HMR is working normally. If a change does not take effect immediately, reload the current interface or restart the corresponding DSH Web / Desktop client.
+
+After changing plugin dependencies, `package.json`, bundle configuration, or other installation- or loading-related settings, reinstalling the plugin or restarting the corresponding client is recommended.
+
 ## 4 Safety and behavior
 
 - **Deletion is permanent**, so the UI always asks for confirmation. The API checks the session ID, directory boundary and artifact header before deletion; traversal, symlinks and junctions are refused.
@@ -92,30 +126,29 @@ dev_inject_plugin {"dir": "<absolute path to this repository>"}
 
 ## 5 Compatibility
 
-| Plugin version | Verified DSH version |
-| --- | --- |
-| 0.5.3 | v0.1.7-rc.2 |
-| 0.5.2 | v0.1.7-rc.1 |
-| 0.5.1 | v0.1.6-alpha.2 |
-| 0.4.11 | v0.1.5-rc.2 |
-| 0.4.10 | v0.1.5-rc.1 |
-| 0.4.9 | v0.1.5-rc.1 |
-| 0.4.7 | v0.1.5-rc.1 |
-| 0.4.6 | 0.1.3-alpha.2 |
-| 0.4.4 | 0.1.3-alpha.2 |
-| 0.4.1 | 0.1.3-alpha.2 |
-| 0.4.0 | v0.1.2-rc.1 |
-| 0.1.2 | v0.1.0-rc.7 |
-| 0.1.1 | v0.1.0-rc.7 |
-| 0.1.0 | v0.1.0-rc.7 |
-
-Requires Node.js 22.15+ (22.x) or 24+ for built-in Zstd support.
+DSH versions are shown above plugin versions; each column represents a tested version combination.
+
+| v0.2.0-rc.2 | v0.1.7-rc.2 | v0.1.7-rc.1 |
+| --- | --- | --- |
+| 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 |
+
+| 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 |
+
+The version combinations above have been tested with either the official Web UI or Desktop app. Other version combinations may also work but have not been individually verified.
+
+When using a standalone DSH CLI/runtime, Node.js 22.15+ (22.x) or 24+ is required for built-in Zstd support. The official Desktop app ships and manages its matching runtime separately.
 
 This is a Cordis plugin and declares `cordis: ">=4.0.0-rc <5"` as its peer dependency.
 
 ## 6 Development
 
-- `lib/index.js` is the host-side ESM plugin; `lib/client.js` is the Web client bundle. No build step is required.
+- `lib/index.js` is the host-side ESM plugin; `lib/client.js` is the client UI bundle. No build step is required.
 - Before submitting changes, run:
 
 ```powershell
@@ -127,13 +160,13 @@ git diff --check
 
 Tests use isolated temporary directories and the real plugin entry point, never real sessions. CI runs these checks on Windows / Linux with Node 22.15.0 / 24.
 
-Optional integration check: run `node scripts/smoke-test.mjs` against a running test instance of DSH Web. It contacts a real service and is not part of the default unit test suite.
+Optional integration check: run `node scripts/smoke-test.mjs` against a running DSH Web-profile test instance. It contacts a real service and is not part of the default unit test suite.
 
 Release history is in [CHANGELOG.md](CHANGELOG.md).
 
 ## 7 Acknowledgments
 
-Thanks to everyone who installs and uses dsh-session-manager, and to the people who file issues and open pull requests to help improve it. The plugin is listed in [dsh-market](https://github.com/dsh-market/dsh-market) and [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin). Suggestions and feedback are welcome.
+Thanks to everyone who installs and uses dsh-session-manager, and to the people who file issues and open pull requests to help improve it. Suggestions and feedback are welcome.
 
 ## 8 License
 

package/README.zh.md

@@ -9,7 +9,9 @@
 
 ## 0 简介
 
-DSH Web 会话管理：删除、归档、跨工作区移动、迁移预设；收藏、待看、搜索、排序、设置优先级、添加标签和备注；批量处理。欢迎至 GitHub 提意见。
+DeepSeek Harness 会话管理插件：支持删除、归档、跨工作区移动、预设迁移、收藏、待回看、搜索、筛选、排序、优先级、标签、备注及批量操作。
+
+当前版本已在官方新版 DSH Web UI 与 Desktop 客户端完成实际测试；两种环境共用本插件的 Host 与客户端功能，具体安装方式见下文。
 
 ## 1 功能
 
@@ -28,7 +30,7 @@ DSH Web 会话管理：删除、归档、跨工作区移动、迁移预设；收
 - **优先级**：下拉 **1 最高、2 高、3 普通、4 低、5 最低**，**默认 3（普通）**；旧数据中的 `null` 归一化为 3。
 - **标签 / 备注**：每会话最多 20 个标签（每个 ≤ 32 字符）、备注最多 2000 字符。英文 `,` 与中文 `，` 都是分隔符，首尾空白被去除，重复标签按大小写不敏感合并。
 - **AI 整理（手动、可选）**：标签 / 备注编辑窗口内的 **复制 Prompt** 把结构化提示复制到剪贴板，**导入** 解析剪贴板 JSON（可识别 Markdown 代码块、对话包裹、智能引号、孤立反斜杠和开头 BOM），按相同规则校验后填入字段；两者都不会自动调用模型。
-- 标记保存在 `dsh-session-manager/annotations.v1.json`，按会话 ID 关联；同源浏览器标签页通过 `BroadcastChannel` 同步；保存可跨进程崩溃恢复，版本冲突会提示"载入最新内容"。
+- 标记保存在 `dsh-session-manager/annotations.v1.json`，按会话 ID 关联；同源客户端实例通过 `BroadcastChannel` 同步；保存可跨进程崩溃恢复，版本冲突会提示"载入最新内容"。
 
 ### 1.3 批量处理
 
@@ -38,6 +40,12 @@ DSH Web 会话管理：删除、归档、跨工作区移动、迁移预设；收
   - **变更操作**：**添加标签 / 清空标签 / 设置优先级 / 移动至工作区 / 迁移预设 / 删除会话**。
 - **执行流程**：非破坏性操作（归档 / 取消归档 / 收藏 / 取消收藏 / 待回看 / 取消待看 / 添加标签 / 清空标签 / 设置优先级 / 移动至工作区 / 迁移预设）立即执行，结果按会话逐条展示在 **结果对话框** 的 **成功 / 失败 / 跳过** 分组里，并提供 **重试失败项** 一键把失败 ID 重新加入选中；破坏性操作（**删除会话**）先弹 **预览对话框** 列出受影响的会话，再显示进度条，最后给出逐条结果。
 
+### 1.4 插件更新与设置卡片
+
+- **检查更新**：会话管理窗口顶部增加 🐋（鲸鱼）图标按钮，点击可检查新版本并在有更新时展示小红点提示；点击弹出更新窗口，展示当前版本与最新版本，支持一键调用插件管理器安装更新。
+- **设置卡片**：注册在 DSH 设置的插件配置页（`settings.plugin.item`）。展示当前安装版本、最新版本状态、卡片内检查更新与更新按钮、自动检查偏好开关以及 GitHub 仓库链接。
+- **安装源选择**：在设置卡片中可随时切换安装源，可选 **npm 官方源**（`registry.npmjs.org`，默认）与 **中国大陆镜像源**（`registry.npmmirror.com`）；检查更新与版本下载将直接请求所选源。
+
 ## 2 UI入口
 
 ### 2.1 标题栏入口
@@ -52,32 +60,58 @@ DSH Web 会话管理：删除、归档、跨工作区移动、迁移预设；收
 
 会话管理窗口顶部的 **批量处理** 按钮即是入口：点一下进入批量模式，行左侧出现复选框，工具栏出现 **全选当前筛选 / 清空选择** 和 **批量按钮区**；再点一次退出批量模式。
 
+### 2.4 设置卡片入口
+
+在 DSH 设置中进入插件设置页（会话管理），可查看版本信息、切换 npm 官方源或中国大陆镜像源、开启/关闭自动检查更新，或手动检查并更新。
+
 ## 3 安装
 
-### 3.1 从官方插件管理入口安装
+### 3.1 从插件安装
+
+在 DSH 的 **插件** 中添加插件，搜索 `dsh-session-manager` 并安装。该方式适用于官方 Web UI 和 Desktop 客户端。
 
-进入 DSH 应用内的 **插件管理**，搜索 `dsh-session-manager` 并安装。
+### 3.2 从第三方插件市场安装
 
-### 3.2 从 dsh-market 安装
+本插件已被 [dsh-market](https://github.com/dsh-market/dsh-market) 和 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 收录。
+
+### 3.3 通过 CLI 安装至 Web profile
+
+从 npm 安装：
 
 ```powershell
 dsh plugin --profile web add npm:dsh-session-manager
 ```
 
-### 3.3 从 GitHub 安装
+从 GitHub 安装：
 
 ```powershell
 dsh plugin --profile web add github:hkkz9522/dsh-session-manager
 ```
 
-安装后重启 DSH Web；若浏览器仍加载旧的客户端代码，请使用 `Ctrl+Shift+R` 强制刷新。
+安装后重启 DSH Web。若浏览器仍加载旧的客户端代码，可使用 `Ctrl+Shift+R` 强制刷新。
+
+> `desktop` profile 由官方 Desktop 客户端管理，普通 `dsh` CLI 不用于修改该 profile。Desktop 用户请通过客户端内的 **插件** 安装插件。
+
+### 3.4 本地开发 / 测试
+
+#### Web profile
 
-### 3.4 本地开发 / 运行时注入
+通过 CLI 安装本地仓库：
 
-```text
-dev_inject_plugin {"dir": "<本仓库的绝对路径>"}
+```powershell
+dsh plugin --profile web add <本仓库路径>
 ```
 
+本地仓库会作为插件 checkout 链接到当前 profile，适合直接修改源码并进行测试。
+
+#### Desktop 客户端
+
+在官方 Desktop 客户端中打开 **插件**，使用本地仓库的绝对路径作为安装源。
+
+对于 Client 端代码，在 HMR 正常工作的情况下，保存修改后可以自动重新加载；若修改未立即生效，可重新加载当前界面或重启对应的 DSH Web / Desktop 客户端。
+
+修改插件依赖、`package.json`、bundle 配置等安装或加载相关内容后，建议重新安装插件或重启对应客户端。
+
 ## 4 安全说明
 
 - **删除不可恢复**，UI 始终要求二次确认；删除前校验会话 ID、目录边界和工件 header，不允许通过路径穿越、符号链接或 junction 操作其他目录。
@@ -90,30 +124,29 @@ dev_inject_plugin {"dir": "<本仓库的绝对路径>"}
 
 ## 5 兼容性
 
-| 插件版本   | 已验证 DSH 版本    |
-| ------ | ------------- |
-| 0.5.3  | v0.1.7-rc.2   |
-| 0.5.2  | v0.1.7-rc.1   |
-| 0.5.1 | v0.1.6-alpha.2   |
-| 0.4.11 | v0.1.5-rc.2   |
-| 0.4.10 | v0.1.5-rc.1   |
-| 0.4.9  | v0.1.5-rc.1   |
-| 0.4.7  | v0.1.5-rc.1   |
-| 0.4.6  | 0.1.3-alpha.2 |
-| 0.4.4  | 0.1.3-alpha.2 |
-| 0.4.1  | 0.1.3-alpha.2 |
-| 0.4.0  | v0.1.2-rc.1   |
-| 0.1.2  | v0.1.0-rc.7   |
-| 0.1.1  | v0.1.0-rc.7   |
-| 0.1.0  | v0.1.0-rc.7   |
-
-运行时要求 Node.js 22.15+（22.x）或 24+，以提供内置 Zstd 支持。
+DSH 版本在上，插件版本在下；每列表示一组已测试的版本组合。
+
+| v0.2.0-rc.2 | v0.1.7-rc.2 | v0.1.7-rc.1 |
+| --- | --- | --- |
+| 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 |
+
+| 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 客户端中完成测试。其他版本组合可能同样兼容，但未逐一验证。
+
+使用独立 DSH CLI / runtime 时，需要 Node.js 22.15+（22.x）或 24+，以提供内置 Zstd 支持。官方 Desktop 客户端单独携带并管理与其版本匹配的 runtime。
 
 本插件是 Cordis 插件，peer dependency 为 `cordis: ">=4.0.0-rc <5"`。
 
 ## 6 开发
 
-- `lib/index.js` 是 host 端 ESM 插件，`lib/client.js` 是 Web 客户端 bundle，无需构建步骤。
+- `lib/index.js` 是 host 端 ESM 插件，`lib/client.js` 是客户端 UI bundle，无需构建步骤。
 - 提交修改前请运行：
 
 ```powershell
@@ -125,13 +158,13 @@ git diff --check
 
 测试使用隔离临时目录和真实插件入口，不操作真实会话。CI 在 Windows / Linux、Node 22.15.0 / 24 上执行相同检查。
 
-可选集成检查：在 DSH Web 已运行的测试环境中执行 `node scripts/smoke-test.mjs`；它会请求实际服务，不属于默认单元测试。
+可选集成检查：对正在运行的 DSH Web profile 测试实例执行 `node scripts/smoke-test.mjs`；它会请求实际服务，不属于默认单元测试。
 
 发布记录见 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 7 致谢
 
-感谢每一位安装和使用 dsh-session-manager 的用户，也感谢提交 Issue 与 Pull Request 帮助改进本插件的朋友们。本插件已被 [dsh-market](https://github.com/dsh-market/dsh-market) 和 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 收录。欢迎提出修改意见。
+感谢每一位安装和使用 dsh-session-manager 的用户，也感谢提交 Issue 与 Pull Request 帮助改进本插件的朋友们。欢迎提出修改意见。
 
 ## 8 开源许可
 

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");