dsh-session-manager 0.4.11 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,63 @@
-# Changelog
-
+# Changelog
+
+## 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
+
+- **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 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)**: 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)."
+
+- **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.
+
+- **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.
+
+- **feat(manager)**: add case-insensitive title/session-ID search, workspace/ungrouped filtering, four time-order modes, matching/total counts and reset controls; combine them with the existing archive filter. Creation times are supplied from cached host headers when DSH summaries omit them, without reading logs. Add workspace load/retry handling, stale-request cancellation, narrow-screen layout, IME-safe Escape handling and real-bundle interaction tests.
+
+- **fix(safety)**: validate session IDs, directory containment, symlinks/junctions and artifact identity before deletion or file rewrites; reject an already occupied move destination.
+- **fix(persistence)**: separate backup/publication/rollback phases; never delete the original after a failed backup rename. Preserve recovery files and report their paths if rollback fails, and clean uncommitted temporary files after write failures.
+- **fix(zstd)**: use structural frame decoding on every rewrite path and reject corrupt/torn logs instead of publishing a decoded prefix.
+- **fix(startup)**: distinguish incomplete scans from empty libraries; normalize snapshot headers, preserve live/concurrently attached sessions, and reconcile using a fresh immutable registry state.
+- **perf**: read only orphan artifact headers during enumeration and avoid duplicate full readRaw decoding for mutations.
+- **chore(test)**: test the real plugin routes instead of a copied move implementation; cover traversal, junctions, corruption, rollback failures, concurrent mutations, and startup read failures. Run module imports, tests, and package checks on Windows/Linux with Node 22.15.0/24; declare the Zstd-capable Node requirement.
+
 ## 0.4.11 — 2026-09-14
 
 - **chore(client)**: drop `@deepseek-ai/dsh-client-runtime` from `dsh.client.inject`. The package is no longer shipped by DSH 0.1.5-rc.2 / 0.1.2-alpha or newer (its client-bootstrap role was folded into `@deepseek-ai/dsh-client-store`). This plugin's bundle never required it, so removing the stale reference is a no-op at runtime and only cleans up the published manifest (#12).

package/README.md

@@ -7,75 +7,100 @@ 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)
 
-A DeepSeek Harness (DSH) Web plugin for session management: delete sessions, archive sessions, move sessions across workspaces, and migrate a session's Agent preset. 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.
 
-- **Archive / unarchive** sessions.
-- **Delete sessions** with an explicit irreversible-action confirmation.
-- **Move to workspace**: preserves history, title, archive state, and derived-session relationships, and rewrites the session's working directory to the target workspace.
-- **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.
-- **Session manager panel**: browse active and archived sessions in the sidebar, and run Open, Archive / Unarchive, Move, Migrate preset, or Delete on each row.
-- The current session's title area offers Archive / Unarchive, Move to workspace, and a red Delete session button.
-- Each dialog button (Move, Migrate preset, Delete, plus the Session manager toggle) closes its own popup when clicked a second time, matching the built-in title-area buttons.
+## 1 Features
 
-## Where to find the UI
+### 1.1 Session lifecycle management
 
-- **Session title area (right side):** Archive / Unarchive, Move to workspace, Delete session.
-- **Sidebar footer → Session manager:** browse all sessions (including archived ones) and operate on each one.
+- **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.
 
-## Agent preset migration
+### 1.2 Session shortcuts
 
-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`.
+- **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.
 
-1. Open **Session manager**.
-2. Locate the session and select **Migrate preset**.
-3. Choose one of the currently available target presets and confirm.
+### 1.3 Bulk management
 
-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.
+- **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.
 
-> A preset migration changes session metadata only. It does not alter message history, files, or the selected workspace.
+## 2 UI entry points
 
-## Install
+### 2.1 Title bar
 
-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.
+The right side of the title area exposes actions for the **current session**: **Archive / Unarchive**, **Tags / Notes**, **Move to workspace**, **Delete session**.
 
-### From dsh-market
+### 2.2 Session manager panel
+
+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.
+
+### 2.3 Bulk management
+
+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
+
+### 3.1 From the official plugin management
+
+Go to **plugin management** inside DSH, search for `dsh-session-manager`, and install it.
+
+### 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.
-- Move and Migrate preset do **not** tear down the live agent or session. They keep the in-memory session/agent alive, write the new artifact in place, update the in-memory session header to point at the new cwd (move) or append the new event (migrate), and refresh the workspace registry. The api-gateway's chat panel therefore stays "available" without a manual refresh.
-- Move rewrites the session's stored `cwd`; subsequent tool calls run in the target workspace.
-- Subagent sessions and transient blank-session placeholders are excluded from Delete, Move, and Migrate preset.
-- The move path encodes the artifact in the backend's own physical layout (zstd frames with a one-header-line first frame, or plain JSONL), matching DSH's own writer. The migrate path rewrites the relevant event in place at the existing file.
+- **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 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 (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 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.4.11 | v0.1.5-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 |
@@ -83,28 +108,32 @@ dev_inject_plugin {"dir": "<absolute path to this repository>"}
 | 0.1.1 | v0.1.0-rc.7 |
 | 0.1.0 | v0.1.0-rc.7 |
 
-The plugin is a Cordis plugin and declares `cordis: ">=4.0.0-rc <5"` as its peer dependency.
+Requires Node.js 22.15+ (22.x) or 24+ for built-in Zstd support.
+
+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:
 
 ```powershell
-node --check lib/client.js
-node --check lib/index.js
-node --test test/*.test.mjs
-node scripts/smoke-test.mjs
+npm run check
+npm test
+npm run check:package
 git diff --check
-npm pack --dry-run
 ```
 
+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.
+
 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

@@ -1,112 +1,137 @@
-# dsh-session-manager — DeepSeek Harness 会话管理器
-
-[English](README.md) | 中文
-
-[![npm version](https://img.shields.io/npm/v/dsh-session-manager)](https://www.npmjs.com/package/dsh-session-manager)
-[![GitHub](https://img.shields.io/badge/GitHub-仓库-blue)](https://github.com/hkkz9522/dsh-session-manager)
-[![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)
-
-用于在 DeepSeek Harness（DSH）Web 中进行会话管理，包括：删除会话、归档会话、跨工作区移动会话、迁移会话的 Agent 预设。欢迎至 GitHub 提意见。
-
-## 功能
-
-- **归档 / 移出归档**会话。
-- **删除会话**：带不可逆操作的二次确认。
-- **移动至工作区**：保留历史、标题、归档状态和派生会话关系，同时把会话的 `cwd` 更新为目标工作区。
-- **迁移 Agent 预设**：按需修改。典型工况：当原预设被改名或删除，导致会话无法恢复时，可修复该会话。
-- **会话管理窗口**：在侧边栏中浏览未归档和已归档会话，并对每一行执行打开、归档 / 移出归档、移动、迁移预设、删除。
-- 当前会话标题区域提供归档 / 移出归档、移动至工作区和红色的删除会话按钮。
-- 弹窗按钮（移动、迁移预设、删除，以及"会话管理"入口）再次点击会关闭对应弹窗，与标题栏原生按钮行为一致。
-
-## UI 入口
-
-- **会话标题右侧**：归档 / 移出归档、移动至工作区、删除会话。
-- **侧边栏底部 → 会话管理**：查看全部会话（含归档会话）并操作每一条会话。
-
-## Agent 预设迁移
-
-1. 打开**会话管理**。
-2. 找到目标会话，点击**迁移预设**。
-3. 从当前可用的预设中选择目标预设并确认。
-
-例如：当会话无法恢复，报错表明原 Agent 预设不存在时（例如删掉了 `router-standard`），可以使用迁移功能。
-
-插件会读取最后一条 `agent-preset/selected` 事件中的有效预设（若不存在则读取会话 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 安装
-
-```powershell
-dsh plugin --profile web add npm:dsh-session-manager
-```
-
-### 从 GitHub 安装
-
-```powershell
-dsh plugin --profile web add github:hkkz9522/dsh-session-manager
-```
-
-安装后重启 DSH Web。若浏览器仍加载旧的客户端代码，请使用 `Ctrl+Shift+R` 强制刷新。
-
-### 本地开发 / 运行时注入
-
-```text
-dev_inject_plugin {"dir": "<本仓库的绝对路径>"}
-```
-
-## 安全与行为说明
-
-- **删除不可恢复**，因此界面始终要求确认。
-- 移动和迁移预设会先 quiesce 该会话的 live agent（取消运行 + 释放 scope + 移出 SessionStore），即使聊天标签页还开着也能成功；侧边栏会自动刷新。
-- 移动会改写会话保存的 `cwd`，之后的工具调用将在目标工作区执行。
-- subagent 会话和临时空白会话占位不会参与删除、移动或迁移预设。
-- 持久化改写走 DSH 自身的 `open/create/append/flush` 接口，编解码链在内部处理 v2 → v3 格式迁移，写出的工件对当前 DSH 版本始终合法。
-
-## 兼容性
-
-| 插件版本 | 已验证 DSH 版本 |
-| --- | --- |
-| 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.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 |
-
-本插件是 Cordis 插件，peer dependency 为 `cordis: ">=4.0.0-rc <5"`。
-
-## 开发
-
-- `lib/index.js` 是 host 端 ESM 插件，`lib/client.js` 是 Web 客户端 bundle，无需构建步骤。
-- 提交修改前请运行：
-
-```powershell
-node --check lib/client.js
-node --check lib/index.js
-node --test test/*.test.mjs
-node scripts/smoke-test.mjs
-git diff --check
-npm pack --dry-run
-```
-
-发布记录见 [CHANGELOG.md](CHANGELOG.md)。
-
-## 致谢
-
-感谢每一位安装和使用 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) 收录。欢迎提出修改意见。
-
-## 开源许可
-
-[MIT](LICENSE)
+# dsh-session-manager — DeepSeek Harness 会话管理器
+
+[English](README.md) | 中文
+
+[![npm version](https://img.shields.io/npm/v/dsh-session-manager)](https://www.npmjs.com/package/dsh-session-manager)
+[![GitHub](https://img.shields.io/badge/GitHub-仓库-blue)](https://github.com/hkkz9522/dsh-session-manager)
+[![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)
+
+## 0 简介
+
+DSH Web 会话管理：删除、归档、跨工作区移动、迁移预设；收藏、待看、搜索、排序、设置优先级、添加标签和备注；批量处理。欢迎至 GitHub 提意见。
+
+## 1 功能
+
+### 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` 同步；保存可跨进程崩溃恢复，版本冲突会提示"载入最新内容"。
+
+### 1.3 批量处理
+
+- **批量模式入口**：在会话管理窗口顶部点击 **批量处理** 切换按钮，行左侧出现复选框，工具栏出现 **全选当前筛选 / 清空选择** 和 **批量按钮区**；退出批量模式会清空当前选中。
+- **批量按钮区** 列出所有批量动作：
+  - **标记切换**：**归档 / 取消归档 / 收藏 / 取消收藏 / 待回看 / 取消待看**。
+  - **变更操作**：**添加标签 / 清空标签 / 设置优先级 / 移动至工作区 / 迁移预设 / 删除会话**。
+- **执行流程**：非破坏性操作（归档 / 取消归档 / 收藏 / 取消收藏 / 待回看 / 取消待看 / 添加标签 / 清空标签 / 设置优先级 / 移动至工作区 / 迁移预设）立即执行，结果按会话逐条展示在 **结果对话框** 的 **成功 / 失败 / 跳过** 分组里，并提供 **重试失败项** 一键把失败 ID 重新加入选中；破坏性操作（**删除会话**）先弹 **预览对话框** 列出受影响的会话，再显示进度条，最后给出逐条结果。
+
+## 2 UI入口
+
+### 2.1 标题栏入口
+
+标题栏右侧对**当前会话**提供：**归档 / 移出归档**、**标签 / 备注**、**移动至工作区**、**删除会话**。
+
+### 2.2 会话管理入口与界面
+
+从 DSH 侧边栏底部进入 **会话管理**，可浏览全部会话、切换工作区、按标题 / ID / 备注 / 标签搜索、应用筛选与排序，并对每条会话执行 **打开 / 归档 / 移出归档 / 标签 / 备注 / 移动 / 迁移预设 / 删除** 操作。窗口顶部承载工作区选择、归档筛选、收藏 / 待回看、标签、优先级筛选与排序控件，以及匹配 / 总数计数和"重置筛选"。
+
+### 2.3 批量管理入口
+
+会话管理窗口顶部的 **批量处理** 按钮即是入口：点一下进入批量模式，行左侧出现复选框，工具栏出现 **全选当前筛选 / 清空选择** 和 **批量按钮区**；再点一次退出批量模式。
+
+## 3 安装
+
+### 3.1 从官方插件管理入口安装
+
+进入 DSH 应用内的 **插件管理**，搜索 `dsh-session-manager` 并安装。
+
+### 3.2 从 dsh-market 安装
+
+```powershell
+dsh plugin --profile web add npm:dsh-session-manager
+```
+
+### 3.3 从 GitHub 安装
+
+```powershell
+dsh plugin --profile web add github:hkkz9522/dsh-session-manager
+```
+
+安装后重启 DSH Web；若浏览器仍加载旧的客户端代码，请使用 `Ctrl+Shift+R` 强制刷新。
+
+### 3.4 本地开发 / 运行时注入
+
+```text
+dev_inject_plugin {"dir": "<本仓库的绝对路径>"}
+```
+
+## 4 安全说明
+
+- **删除不可恢复**，UI 始终要求二次确认；删除前校验会话 ID、目录边界和工件 header，不允许通过路径穿越、符号链接或 junction 操作其他目录。
+- 移动和迁移预设保留 live session / agent；只有删除才会取消运行并释放会话。移动会更新保存的 cwd 和 live writer 的 header。
+- 会话管理列表隐藏 subagent 会话，移动接口也拒绝 subagent；尚未落盘的空白会话不能跨工作区移动。
+- 冷会话重写保留原工件格式（V1 / V2 / V3 / V4 都可读，绝不强制升级）。损坏或截断的 Zstd 日志、缺少完整尾行的 JSONL 会拒绝移动 / 重写，不会把部分历史当作完整日志保存。
+- 迁移预设按"备份 → 发布 → 回滚"分阶段处理。如果回滚失败，会保留恢复文件并在错误中报告路径；不要删除这些文件。
+- 启动扫描不完整时跳过工作区归属修复；完整扫描也不会清除仍在内存中或扫描期间新加入的会话。
+- 同一会话的插件写操作按顺序执行；请求体限制为 64 KiB。该队列不替代 DSH 自身的持久化写入协调。
+
+## 5 兼容性
+
+| 插件版本   | 已验证 DSH 版本    |
+| ------ | ------------- |
+| 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 支持。
+
+本插件是 Cordis 插件，peer dependency 为 `cordis: ">=4.0.0-rc <5"`。
+
+## 6 开发
+
+- `lib/index.js` 是 host 端 ESM 插件，`lib/client.js` 是 Web 客户端 bundle，无需构建步骤。
+- 提交修改前请运行：
+
+```powershell
+npm run check
+npm test
+npm run check:package
+git diff --check
+```
+
+测试使用隔离临时目录和真实插件入口，不操作真实会话。CI 在 Windows / Linux、Node 22.15.0 / 24 上执行相同检查。
+
+可选集成检查：在 DSH Web 已运行的测试环境中执行 `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) 收录。欢迎提出修改意见。
+
+## 8 开源许可
+
+[MIT](LICENSE)