dsh-session-manager 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -1,4 +1,46 @@
-# Changelog
+
+## 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).
+
+- **fix**: issue #18 — `moveSession` stamps `header.version` from the target filename so v4-named artifacts don't carry stale v0 headers (which broke DSH startup's `listArtifacts`).
+
+- **fix**: dialog descriptions (`confirm.move.desc`, `confirm.delete.desc`) show only the friendly `displayTitle`, never the raw id. The title-bar lookup is resolved once per render via IIFE — an earlier attempt invoked `useSessions()` inside an event handler, which crashed the slot framework's `useSyncExternalStore` subscriber and let `SlotErrorBoundary` replace the whole `conversation.session.header.actions` slot with `<div data-slot-error="…" />`, taking every title-bar button down.
+
+- **fix**: drop UTF-8 BOM from `package.json` (`JSON.parse` was rejecting it and surfacing the plugin as "all components disabled").
+
+- **chore**: remove leftover `TEMP DEBUG` block in `lib/index.js` (issue #18 debugging residue that spammed the log every 2 s).
+
+- **test**: regression guard added in `test/issue-17-static-guards.test.mjs`; existing `test/issue-18-move-version.test.mjs` covers #18.
+
+## 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)**: 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.
+
+- **feat(bulk management)**: add the **Migrate preset…** button to the bulk action bar. Selecting rows and clicking the new button opens a preset picker (sourced from `/preset-scan`) and, on confirm, runs the `preset-migrate` action against every selected session through the existing `/batch` endpoint. Sessions already on the chosen preset are reported as skipped in the result dialog; failed sessions can be retried individually.
+
+- **fix(host /batch)**: the `/session-manager/api/batch` host handler had four regressions that were hidden by the bulk-dialog UI bug fixed in the same release:
+
+  1. **archive** called `ctx.workspaces.archiveSession(sessionId)` directly from the per-request dispatch; Cordis rejected it with `cannot get property 'workspaces' without inject`. The host now exposes an `archiveSession` helper that mirrors `unarchiveSession` and updates `workspaceRegistry.archivedSessionIds` atomically.
+
+  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 }`.
+
+  4. the `BATCH_ACTIONS` set, the annotation action set inside `runBatchAction`, and `annotationPatchFromBatchAction` have been kept in sync.
+
+  As a hygiene cleanup, an orphan copy of the same handler that was left inside the file header JSDoc (between `/**` and the real `* @dsh-session-manager` description) has been removed. **Important:** if any of these errors were seen before this fix, hard-refresh DSH (Ctrl+Shift+R) so the cached plugin bundle is replaced with the new one.
+
+- **fix(bulk dialog positioning)**: the bulk preview / progress / result / tag-input / priority / move / preset-migrate dialogs had only a `z-index` rule on `.sm-bulkDialog.sm-nativeDialogLayer` and inherited the default `position: static`, so they rendered in normal document flow at the bottom of the panel (below the row list). They now reuse the same fixed-position `inset: calc(50vh - 90px) auto auto calc(50vw + 308px)` as `.sm-confirmDialog.sm-nativeDialogLayer` and pop up to the right of the panel, matching every other per-row dialog.
+
+- **fix(bulk dialog dark mode)**: every `[data-sm-theme=dark]` override that previously covered `.sm-panelDialog` / `.sm-confirmDialog` / `.sm-migrateDialog` now also covers `.sm-bulkDialog`. Without this, dark mode rendered the bulk dialog body, header, footer, list, result list, progress bar and progress fill in default white-on-white, making the dialog text invisible.
+
+- **fix(footer)**: FooterAction now reads `props.wide` from `SidebarFooterActionOwnerProps` and renders differently for collapsed (`scope: 'root'` rail, 36x36 icon-only button) vs expanded (full-width row, icon + label, left-aligned) sidebar (DSH 0.1.6+ `sidebar.footer.action` slot contract).
+- **test(bulk management)**: add client-side coverage for issue #13:     est/client-bulk-selection.test.mjs (static guards on the selection-state hooks),     est/client-bulk-actions.test.mjs (static guards on the BulkActionBar wiring + locale coverage),     est/client-bulk-runbatch.test.mjs (unit coverage for the runBatch wrapper via runInNewContext with a stubbed fetch), and     est/client-bulk-static-guards.test.mjs (cross-cutting structural invariants -- namespace ownership, panel dialog sibling layout, fan-out refresh, host/client action vocabulary). Total tests: 225 (188 pre-existing + 37 new).
+- **feat(bulk management)**: add multi-select checkboxes to session rows plus a sticky bulk action bar with archive, unarchive, favorite, unfavorite, mark-for-review, clear-review, add-tags, clear-tags, set-priority, move-to-workspace, and delete actions. Destructive actions run through a BatchPreviewDialog with per-id skip/fail grouping; non-destructive ones fire immediately. Progress, success/failure counts, per-item error reasons, and a one-click **Retry failed** re-arm the failed ids back into the selection. The /batch endpoint is reused so per-id errors surface as partial failures without aborting the batch. Bulk state is reset when the panel closes or the filter excludes a selected row.
+- **feat(sessions)**: `ARTIFACT_NAMES` now lists `session.v4.jsonl.zstd` first so DSH 0.1.7 V4-default session artifacts are picked up by the list-snapshot reader. Existing V3/V2/V1 files remain readable; the reader is version-agnostic and parses the header JSON regardless of declared version, so no per-version code paths are required.
 
 ## 0.5.1 — 2026-09-18
 

package/README.md

@@ -7,119 +7,101 @@ English | [中文](README.zh.md)
 [![CI](https://github.com/hkkz9522/dsh-session-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/hkkz9522/dsh-session-manager/actions/workflows/ci.yml)
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
-DSH Web session manager: delete, archive, move across workspaces, migrate preset; favorites, review-later, search, sort, priority, add tags and notes (manual / semi-automated). Suggestions are welcome on GitHub.
+## 0 Overview
 
-## Features
+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.
 
-### Session lifecycle
+## 1 Features
 
-- **Archive / unarchive** sessions.
-- **Delete sessions** with an explicit irreversible-action confirmation. Deletion is rejected for subagent sessions and transient blank placeholders.
-- **Move to workspace**: preserves history, title, archive state, and derived-session relationships, and rewrites the session's working directory (`cwd`) to the target workspace. The move updates the live writer's header in place so any pending tool calls keep landing on the new path.
-- **Migrate Agent preset**: change the preset on demand. Typical use case: when the original preset was renamed or removed and the session can no longer resume, you can repair that session. The migration rewrites the latest `agent-preset/selected` event (or the session header if no such event exists) without altering message history.
+### 1.1 Session lifecycle management
 
-### Session manager panel (sidebar)
+- **Delete** is irreversible and always asks for confirmation. Subagent sessions and transient blank placeholders (no persisted artifact) cannot be deleted.
+- **Archive / Unarchive** moves a session in and out of the active list without touching its disk content.
+- **Move to workspace** keeps history, title, archive state and derived-session relationships intact, rewrites the session's `cwd` to the target workspace, and updates the live writer's header in place so any pending tool calls keep landing on the new path.
+- **Migrate Agent preset** rewrites the latest `agent-preset/selected` event (or the session header if no such event exists) so a session whose preset was renamed or removed can resume. Message history is never altered.
 
-- Browse active and archived sessions, switch workspaces, and filter, sort, search across the list.
-- Open a session directly from a row, or click a tag chip to filter the list to that tag.
-- Per-row actions: **Open**, **Archive / Unarchive**, **Move**, **Migrate preset**, **Delete**.
-- Each popup dialog (Move / Migrate preset / Delete / the panel itself) toggles closed when its trigger is clicked a second time, matching the built-in title-area buttons.
+### 1.2 Session shortcuts
 
-### Search, filters, and sorting
+- **Favorites / Review-later** are manual flags that survive archive and session end; neither is cleared automatically.
+- **Search** matches title, session ID, note and tags case-insensitively, trims whitespace, and never reads chat history.
+- **Filters and sorting** combine a workspace selector (All / Ungrouped / specific) with an archive filter (All / Active / Archived), then layer favorites / review, tag and priority filters on top. Sort by recently updated (default), least recently updated, newest created, oldest created, or **priority (1 → 5)**.
+- **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.
 
-- Case-insensitive title and session-ID search; whitespace is trimmed. Message history is never read.
-- Combine a workspace selector (All / Ungrouped / specific) with the archive filter (All / Active / Archived).
-- Combine favorite/review flags, tag and priority filters; sort by recently updated (default), least recently updated, newest created, oldest created, or **priority (1 → 5)**.
-- See matching/total counts and reset all view controls together. These controls only affect the manager panel — workspace membership, archive state, and the native sidebar ordering are untouched.
-- Failed workspace loads can be retried without losing search, sort state.
+### 1.3 Bulk management
 
-### Favorites, review flags, tags, notes and priority
+- **Batch process mode**: click the toggle in the panel header to reveal row checkboxes, a **Select all in filter / Clear selection** toolbar pair, and the bulk action bar. Exiting batch process clears the current selection.
+- **Action bar** lists every batch action:
+  - **Annotation toggles**: **Archive / Unarchive / Favorite / Unfavorite / Mark for review / Clear review flag**.
+  - **Mutating actions**: **Add tags / Clear tags / Set priority / Move to workspace / Migrate preset / Delete session**.
+- **Confirmation flow**:
+  - 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.
 
-- Favorite / Review / **Tags/Notes** / priority controls are reachable from both the **title bar** (current session) and the **manager panel** (every row).
-- Favorites and review flags are manual — independent of archive / running state, never cleared automatically.
-- Priority is a dropdown **1 Highest, 2 High, 3 Normal, 4 Low, 5 Lowest** with **3 (Normal) as the default**; the manager row and title bar always show a P1–P5 badge. Legacy `null` priorities are normalized to 3.
-- Tags: up to 20 per session, 32 characters each. Both English `,` and Chinese `，` are separators, whitespace is trimmed, duplicates are merged case-insensitively.
-- Notes: plain multiline text, up to 2000 characters.
-- Tags, notes and the AI **paste** textarea all share the same `sm-noteInput` style and `rows: 3` height (60px min-height), so the three input boxes line up visually.
-- The "Tags/Notes" editor also surfaces **Copy Prompt** / **Import** controls for AI-assisted tagging (see below).
-- Annotations are stored as plain text in `dsh-session-manager/annotations.v1.json` under the DSH home, keyed by session ID. They do not rewrite history or enter model context automatically. Move / Migrate preserve them; Delete cleans them up (and reports cleanup failures separately).
-- Both UI surfaces share live state. Same-origin browser tabs receive change notifications via `BroadcastChannel`; refocusing or reopening the manager refreshes data.
-- Saves are atomic, use a cross-process lock, and never silently overwrite another editor: revision conflicts surface a "load latest" prompt. Unsaved drafts survive a save failure.
-- A crash-left `annotations.v1.lock` is not forcibly removed; verify no writer is active before handling it.
+## 2 UI entry points
 
-### AI-assisted tagging (manual, opt-in)
+### 2.1 Title bar
 
-The **Tags/Notes** editor has two extra buttons above the paste box. Neither calls a model automatically — both keep you in control:
+The right side of the title area exposes actions for the **current session**: **Archive / Unarchive**, **Tags / Notes**, **Move to workspace**, **Delete session**.
 
-- **复制 Prompt** / **Copy Prompt** copies a structured prompt (Chinese or English, matched to the active UI language) to the clipboard. Paste it into the current conversation to ask the model to generate tags / note / priority within the plugin's limits.
-- **导入** / **Import** reads the clipboard, extracts the first JSON object (tolerating Markdown fences, conversational wrappers, smart quotes, stray backslashes and a leading BOM), validates it against the same limits, and populates the editor fields. Oversized notes are truncated; invalid tags / priority are dropped with reasons. Importing into a dirty draft asks for confirmation first. If parsing still fails, the error message includes the actual `JSON.parse` position from each recovery attempt so you can see exactly which character broke it.
+### 2.2 Session manager panel
 
-The prompt templates and import parser live in `lib/clipboard-parser.js` and are bundled into the client; no build step or network call is required.
+Open the **Session manager** panel from the bottom of DSH's sidebar to browse every session, switch workspaces, search by title or ID, apply filters and sorting, and run **Open / Archive / Unarchive / Tags / Notes / Move / Migrate preset / Delete** on any row. The panel header carries the workspace selector, archive filter, favorites / review flags, tag and priority filters, sort order, and matching / total counts plus a reset action.
 
-### Current session title bar
+### 2.3 Bulk management
 
-The right side of the title area offers:
+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.
 
-- **Archive / Unarchive** the current session.
-- **Move to workspace** with a workspace picker.
-- A red **Delete session** button with confirmation.
+## 3 Install
 
-The same buttons appear in the manager row.
-## Agent preset migration
+### 3.1 From the official plugin management
 
-Use this when a session can no longer resume because its original preset no longer exists, for example after removing a custom preset such as `router-standard`.
+Go to **plugin management** inside DSH, search for `dsh-session-manager`, and install it.
 
-1. Open **Session manager**.
-2. Locate the session and select **Migrate preset**.
-3. Choose one of the currently available target presets and confirm.
-
-The plugin determines the session's effective preset from its latest `agent-preset/selected` event when present; otherwise it uses the session header. It then rewrites that event in place (or appends a fresh one if the session has never recorded a selection), so the migration is durable and the prior entry remains visible in the event log as history. For a live session, the new event is appended in memory via `Session.append()` and flushed to disk via `SessionStore.flush()`; the api-gateway's chat panel sees the new preset on the next event fold.
-
-> A preset migration changes session metadata only. It does not alter message history, files, or the selected workspace.
-
-## Install
-
-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), and can be installed directly from the **Plugin Marketplace** inside DSH.
-
-### From dsh-market
+### 3.2 From dsh-market
 
 ```powershell
 dsh plugin --profile web add npm:dsh-session-manager
 ```
 
-### From GitHub
+### 3.3 From GitHub
 
 ```powershell
 dsh plugin --profile web add github:hkkz9522/dsh-session-manager
 ```
 
-Restart DSH Web after installation. If the browser still holds an older client bundle, force refresh with `Ctrl+Shift+R`.
+After installing, restart DSH Web. If the browser still holds an older client bundle, force-refresh with `Ctrl+Shift+R`.
 
-### Local development / runtime injection
+### 3.4 Local development / runtime injection
 
 ```text
 dev_inject_plugin {"dir": "<absolute path to this repository>"}
 ```
 
-## Safety and behavior
+## 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.
-- Move and preset migration retain the live session/agent; deletion cancels and disposes it. Move updates the stored cwd and the existing live writer's header.
+- Move and preset migration keep the live session / agent alive; only deletion cancels and disposes the session. Move updates the stored `cwd` and the existing live writer's header.
 - The management list hides subagent sessions and the move API rejects them. Blank sessions without a persisted artifact cannot be moved.
-- Cold rewrites preserve the artifact's stored format rather than forcing a v2 → v3 upgrade. Moves and rewrites refuse corrupt/truncated Zstd logs or JSONL logs with incomplete final lines instead of publishing partial history.
+- Cold rewrites preserve the artifact's stored format (V1 / V2 / V3 / V4 are all readable; the plugin never forces an upgrade). Moves and rewrites refuse corrupt / truncated Zstd logs or JSONL logs with incomplete final lines instead of publishing partial history.
 - Preset migration separates backup, publication and rollback. If rollback fails, recovery files are retained and their paths are included in the error; do not remove them.
-- Incomplete startup scans skip workspace reconciliation. Complete scans preserve live sessions and membership added during the scan.
-- Plugin mutations are serialized per session and request bodies are limited to 64 KiB. This queue supplements, rather than replaces, DSH's persistence coordination.
+- Incomplete startup scans skip workspace reconciliation. Complete scans preserve live sessions and any membership added during the scan.
+- Plugin mutations are serialized per session and request bodies are limited to 64 KiB. This queue supplements, rather than replaces, DSH's own persistence coordination.
 
-## Compatibility
+## 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 |
@@ -129,9 +111,9 @@ dev_inject_plugin {"dir": "<absolute path to this repository>"}
 
 Requires Node.js 22.15+ (22.x) or 24+ for built-in Zstd support.
 
-The plugin is a Cordis plugin and declares `cordis: ">=4.0.0-rc <5"` as its peer dependency.
+This is a Cordis plugin and declares `cordis: ">=4.0.0-rc <5"` as its peer dependency.
 
-## Development
+## 6 Development
 
 - `lib/index.js` is the host-side ESM plugin; `lib/client.js` is the Web client bundle. No build step is required.
 - Before submitting changes, run:
@@ -143,16 +125,16 @@ npm run check:package
 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.
+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. This 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 test instance of DSH Web. It contacts a real service and is not part of the default unit test suite.
 
 Release history is in [CHANGELOG.md](CHANGELOG.md).
 
-## Acknowledgments
+## 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. 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). 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. 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.
 
-## License
+## 8 License
 
 [MIT](LICENSE)

package/README.zh.md

@@ -7,125 +7,99 @@
 [![CI](https://github.com/hkkz9522/dsh-session-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/hkkz9522/dsh-session-manager/actions/workflows/ci.yml)
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
-DSH Web 会话管理：删除、归档、跨工作区移动、迁移预设；收藏、待看、搜索、排序、设置优先级、添加（手动/半自动）标签和备注。欢迎至 GitHub 提意见。
+## 0 简介
 
-## 功能
+DSH Web 会话管理：删除、归档、跨工作区移动、迁移预设；收藏、待看、搜索、排序、设置优先级、添加标签和备注；批量处理。欢迎至 GitHub 提意见。
 
-### 会话生命周期
+## 1 功能
 
-- **归档 / 移出归档**会话。
-- **删除会话**：不可逆操作的二次确认。subagent 会话和临时空白会话占位会被拒绝。
-- **移动至工作区**：保留历史、标题、归档状态和派生会话关系，同时把会话的 `cwd` 更新为目标工作区。移动会就地更新 live writer 的 header，使挂起的工具调用继续落到新路径。
-- **迁移 Agent 预设**：按需修改。典型工况：当原预设被改名或删除，导致会话无法恢复时，可修复该会话。迁移会就地重写最后一条 `agent-preset/selected` 事件（若从未记录选择事件则修改会话 header），不会改写历史消息。
+### 1.1 会话生命周期管理
 
-### 会话管理窗口（侧边栏）
+- **删除**：不可逆操作，UI 始终要求二次确认。subagent 会话和尚未落盘的空白会话占位不能删除。
+- **归档 / 移出归档**：把会话移出或移回主列表，不删除磁盘内容。
+- **移动至工作区**：跨工作区移动时保留历史、标题、归档状态和派生会话关系，同时把 `cwd` 重写为目标工作区，并就地更新 live writer 的 header，使挂起的工具调用继续落到新路径。
+- **迁移 Agent 预设**：原预设被改名或删除导致会话无法恢复时，可修复该会话。迁移会就地重写最后一条 `agent-preset/selected` 事件（若从未记录则修改会话 header），不改动历史消息。
 
-- 浏览未归档和已归档会话、切换工作区、在列表中筛选 / 排序 / 搜索。
-- 直接从某一行打开会话，或点击标签直接按该标签筛选。
-- 每行操作：**打开**、**归档 / 移出归档**、**移动**、**迁移预设**、**删除**。
-- 各弹窗（移动 / 迁移预设 / 删除 / 面板本身）在触发按钮再次点击时会切换关闭，与标题栏原生按钮的行为一致。
+### 1.2 会话快捷管理
 
-### 搜索、筛选和排序
+- **收藏 / 待回看**：长期标记和手动提醒；不会随归档或会话结束自动清除。
+- **搜索**：按标题、会话 ID、备注、标签不区分大小写匹配，自动去除首尾空格，不读取聊天历史。
+- **筛选与排序**：工作区（全部 / 未分组 / 具体）与归档状态（全部 / 未归档 / 已归档）可叠加；可叠加收藏 / 待回看、标签和优先级筛选；排序支持最近更新（默认）、最早更新、最新创建、最早创建以及**优先级（1 → 5）**。
+- **优先级**：下拉 **1 最高、2 高、3 普通、4 低、5 最低**，**默认 3（普通）**；旧数据中的 `null` 归一化为 3。
+- **标签 / 备注**：每会话最多 20 个标签（每个 ≤ 32 字符）、备注最多 2000 字符。英文 `,` 与中文 `，` 都是分隔符，首尾空白被去除，重复标签按大小写不敏感合并。
+- **AI 整理（手动、可选）**：标签 / 备注编辑窗口内的 **复制 Prompt** 把结构化提示复制到剪贴板，**导入** 解析剪贴板 JSON（可识别 Markdown 代码块、对话包裹、智能引号、孤立反斜杠和开头 BOM），按相同规则校验后填入字段；两者都不会自动调用模型。
+- 标记保存在 `dsh-session-manager/annotations.v1.json`，按会话 ID 关联；同源浏览器标签页通过 `BroadcastChannel` 同步；保存可跨进程崩溃恢复，版本冲突会提示"载入最新内容"。
 
-- 不区分大小写的标题和会话 ID 搜索，自动去除首尾空格；不读取聊天历史。
-- 工作区下拉（全部 / 未分组 / 具体工作区）可与归档状态筛选（全部 / 未归档 / 已归档）叠加。
-- 可叠加收藏 / 待回看、标签和优先级筛选；排序支持最近更新（默认）、最早更新、最新创建、最早创建以及**优先级（1 → 5）**。
-- 显示匹配 / 总数，并提供"重置筛选"。这些控件只影响管理窗口，不改变会话归属、归档状态或原生侧边栏顺序。
-- 工作区加载失败时可重试，标题 / ID 搜索和更新时间排序仍可使用。
+### 1.3 批量处理
 
-### 收藏、待回看、标签、备注与优先级
+- **批量模式入口**：在会话管理窗口顶部点击 **批量处理** 切换按钮，行左侧出现复选框，工具栏出现 **全选当前筛选 / 清空选择** 和 **批量按钮区**；退出批量模式会清空当前选中。
+- **批量按钮区** 列出所有批量动作：
+  - **标记切换**：**归档 / 取消归档 / 收藏 / 取消收藏 / 待回看 / 取消待看**。
+  - **变更操作**：**添加标签 / 清空标签 / 设置优先级 / 移动至工作区 / 迁移预设 / 删除会话**。
+- **执行流程**：非破坏性操作（归档 / 取消归档 / 收藏 / 取消收藏 / 待回看 / 取消待看 / 添加标签 / 清空标签 / 设置优先级 / 移动至工作区 / 迁移预设）立即执行，结果按会话逐条展示在 **结果对话框** 的 **成功 / 失败 / 跳过** 分组里，并提供 **重试失败项** 一键把失败 ID 重新加入选中；破坏性操作（**删除会话**）先弹 **预览对话框** 列出受影响的会话，再显示进度条，最后给出逐条结果。
 
-- **标题栏**（当前会话）和 **管理窗口**（每一行）都提供收藏 / 待回看 / **标签 / 备注** / 优先级操作入口。
-- 收藏是长期标记，待回看是手动提醒；不会随归档或会话结束自动清除。
-- 优先级下拉：**1 最高、2 高、3 普通、4 低、5 最低**，**默认 3（普通）**；管理行 / 标题栏始终显示 P1–P5 徽标。旧数据中的 `null` 优先级归一化为 3。
-- 标签：每个会话最多 20 个，每个最多 32 字符；英文 `,` 与中文 `，` 都是分隔符，首尾空白被去除，重复标签按大小写不敏感合并。
-- 备注：最多 2000 字符的多行纯文本。
-- 标签、备注、AI 粘贴三个输入框使用相同的 `sm-noteInput` 样式与 `rows: 3` 高度（60px min-height），三个字段在视觉上对齐。
-- "标签 / 备注" 编辑窗口内还提供 **复制 Prompt** / **导入** 两个按钮，用于 AI 辅助整理（见下）。
-- 标记明文保存在 DSH home 下的 `dsh-session-manager/annotations.v1.json`，按会话 ID 关联；不写入 JSONL/Zstd 历史，也不自动发送给模型。移动 / 迁移预设会保留标记；删除会话后会清理对应标记（清理失败会单独提示）。
-- 标题栏和管理窗口实时共享状态；同源浏览器标签页通过 `BroadcastChannel` 通知同步，重新获得焦点或打开管理窗口也会刷新数据。
-- 保存采用原子写入并使用跨进程锁；版本冲突时保留草稿，要求显式"载入最新内容"。保存失败不会关闭编辑窗口或丢弃草稿。
-- 异常退出遗留的 `annotations.v1.lock` 不会被自动强行删除；应在确认没有进程写入后再处理。
+## 2 UI入口
 
-### AI 整理（手动、可选）
+### 2.1 标题栏入口
 
-**标签/备注** 编辑窗口在标准"取消 / 保存标记"按钮之外，还多了两个按钮，位于粘贴输入框上方。两者都不会自动调用模型，是否发送完全由你决定：
+标题栏右侧对**当前会话**提供：**归档 / 移出归档**、**标签 / 备注**、**移动至工作区**、**删除会话**。
 
-- **复制 Prompt** / **Copy Prompt**：把结构化 Prompt（中文或英文，跟随当前界面语言）复制到剪贴板。粘贴到当前对话中，要求模型按本插件的限制生成标签 / 备注 / 优先级（最多 20 个标签、每个 ≤ 32 字符、备注 ≤ 2000 字符、优先级 1–5 默认 3）。
-- **导入** / **Import**：读取剪贴板，提取首个 JSON 对象（可识别 Markdown 代码块、对话包裹、智能引号、孤立反斜杠和开头 BOM），按相同规则校验后填入编辑窗口。如果当前有未保存的修改，会先询问是否覆盖再继续。超限的标签会被丢弃、超长的备注会被截断，所有调整都会在状态消息中列出，确认后再保存。如果仍然解析失败，错误信息会附带每一次修复尝试中 `JSON.parse` 给出的具体位置（原始 / 修复引号反斜杠 / 扫描对象 / 扫描对象+修复），方便定位坏掉的字符。
+### 2.2 会话管理入口与界面
 
-Prompt 模板和导入解析逻辑位于 `lib/clipboard-parser.js`，直接打包进客户端，无需额外构建步骤，也不会发起任何网络请求。
+从 DSH 侧边栏底部进入 **会话管理**，可浏览全部会话、切换工作区、按标题 / ID / 备注 / 标签搜索、应用筛选与排序，并对每条会话执行 **打开 / 归档 / 移出归档 / 标签 / 备注 / 移动 / 迁移预设 / 删除** 操作。窗口顶部承载工作区选择、归档筛选、收藏 / 待回看、标签、优先级筛选与排序控件，以及匹配 / 总数计数和"重置筛选"。
 
-### 当前会话标题栏
+### 2.3 批量管理入口
 
-标题栏右侧提供：
+会话管理窗口顶部的 **批量处理** 按钮即是入口：点一下进入批量模式，行左侧出现复选框，工具栏出现 **全选当前筛选 / 清空选择** 和 **批量按钮区**；再点一次退出批量模式。
 
-- **归档 / 移出归档** 当前会话。
-- **移动至工作区**，弹窗选择目标工作区。
-- 红色的 **删除会话** 按钮，带确认。
+## 3 安装
 
-同样的按钮在管理窗口每一行也可用。
+### 3.1 从官方插件管理入口安装
 
-## UI 入口
+进入 DSH 应用内的 **插件管理**，搜索 `dsh-session-manager` 并安装。
 
-- **会话标题右侧**：归档 / 移出归档、移动至工作区、删除会话。
-- **侧边栏底部 → 会话管理**：查看全部会话（含归档会话）并操作每一条会话。
-
-## Agent 预设迁移
-
-1. 打开**会话管理**。
-2. 找到目标会话，点击**迁移预设**。
-3. 从当前可用的预设中选择目标预设并确认。
-
-例如：当会话无法恢复，报错表明原 Agent 预设不存在时（例如删掉了 `router-standard`），可以使用迁移功能。
-
-插件会读取最后一条 `agent-preset/selected` 事件中的有效预设（若不存在则读取会话 header）。冷会话会重写最后一条选择事件；从未记录选择事件时修改 header。正常的 live session 通过 `Session.append()` 追加选择事件，再通过 `SessionStore.flush()` 刷到磁盘；api-gateway 的聊天面板在下次事件折叠时即可看到新预设。
-
-> 迁移预设只会修改会话元数据，不会改写历史消息、文件或当前工作区。
-
-## 安装
-
-本插件已收录于 [dsh-market](https://github.com/dsh-market/dsh-market) 和 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)，可以通过 DSH 应用内的**插件市场**直接搜索安装。
-
-### 从 dsh-market 安装
+### 3.2 从 dsh-market 安装
 
 ```powershell
 dsh plugin --profile web add npm:dsh-session-manager
 ```
 
-### 从 GitHub 安装
+### 3.3 从 GitHub 安装
 
 ```powershell
 dsh plugin --profile web add github:hkkz9522/dsh-session-manager
 ```
 
-安装后重启 DSH Web。若浏览器仍加载旧的客户端代码，请使用 `Ctrl+Shift+R` 强制刷新。
+安装后重启 DSH Web；若浏览器仍加载旧的客户端代码，请使用 `Ctrl+Shift+R` 强制刷新。
 
-### 本地开发 / 运行时注入
+### 3.4 本地开发 / 运行时注入
 
 ```text
 dev_inject_plugin {"dir": "<本仓库的绝对路径>"}
 ```
 
-## 安全与行为说明
+## 4 安全说明
 
-- **删除不可恢复**，因此界面始终要求确认。删除前校验会话 ID、目录边界和工件 header；不允许通过路径穿越、符号链接或 junction 操作其他目录。
-- 移动和迁移预设保留 live session / agent；删除才会取消运行并释放会话。移动会更新保存的 cwd 和 live writer 的 header。
+- **删除不可恢复**，UI 始终要求二次确认；删除前校验会话 ID、目录边界和工件 header，不允许通过路径穿越、符号链接或 junction 操作其他目录。
+- 移动和迁移预设保留 live session / agent；只有删除才会取消运行并释放会话。移动会更新保存的 cwd 和 live writer 的 header。
 - 会话管理列表隐藏 subagent 会话，移动接口也拒绝 subagent；尚未落盘的空白会话不能跨工作区移动。
-- 冷会话重写保留原工件格式，不强制升级 v2 → v3。损坏或截断的 Zstd 日志、缺少完整尾行的 JSONL 会拒绝移动/重写，不会把部分历史当作完整日志保存。
-- 迁移预设按“备份 → 发布 → 回滚”分阶段处理。如果回滚失败，会保留恢复文件并在错误中报告路径；不要删除这些文件。
+- 冷会话重写保留原工件格式（V1 / V2 / V3 / V4 都可读，绝不强制升级）。损坏或截断的 Zstd 日志、缺少完整尾行的 JSONL 会拒绝移动 / 重写，不会把部分历史当作完整日志保存。
+- 迁移预设按"备份 → 发布 → 回滚"分阶段处理。如果回滚失败，会保留恢复文件并在错误中报告路径；不要删除这些文件。
 - 启动扫描不完整时跳过工作区归属修复；完整扫描也不会清除仍在内存中或扫描期间新加入的会话。
 - 同一会话的插件写操作按顺序执行；请求体限制为 64 KiB。该队列不替代 DSH 自身的持久化写入协调。
 
-## 兼容性
+## 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   |
@@ -137,7 +111,7 @@ dev_inject_plugin {"dir": "<本仓库的绝对路径>"}
 
 本插件是 Cordis 插件，peer dependency 为 `cordis: ">=4.0.0-rc <5"`。
 
-## 开发
+## 6 开发
 
 - `lib/index.js` 是 host 端 ESM 插件，`lib/client.js` 是 Web 客户端 bundle，无需构建步骤。
 - 提交修改前请运行：
@@ -149,18 +123,16 @@ npm run check:package
 git diff --check
 ```
 
-测试使用隔离临时目录和真实插件入口，不操作真实会话。CI 在 Windows/Linux、Node 22.15.0/24 上执行相同检查。
+测试使用隔离临时目录和真实插件入口，不操作真实会话。CI 在 Windows / Linux、Node 22.15.0 / 24 上执行相同检查。
 
 可选集成检查：在 DSH Web 已运行的测试环境中执行 `node scripts/smoke-test.mjs`；它会请求实际服务，不属于默认单元测试。
 
 发布记录见 [CHANGELOG.md](CHANGELOG.md)。
 
-## 致谢
-
-感谢每一位安装和使用 dsh-session-manager 的用户，也感谢提交 Issue 与 Pull Request 帮助改进本插件的朋友们。
+## 7 致谢
 
-本插件已被 [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 帮助改进本插件的朋友们。本插件已被 [dsh-market](https://github.com/dsh-market/dsh-market) 和 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 收录。欢迎提出修改意见。
 
-## 开源许可
+## 8 开源许可
 
 [MIT](LICENSE)