@anionex/dsh-pinned-sessions 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 0.1.2 — 2026-10-01
+
+- Use DSH 0.2's official session-menu slot and workspace navigation service. Keep the legacy menu bridge for older hosts, and bundle icons whose old host export names were removed.
+- 使用 DSH 0.2 的官方会话菜单 slot 和工作区导航服务；保留旧版菜单桥接，并打包已被宿主移除旧名称的图标。
+- The plugin's top section remains independent of the new native workspace pin action. Menu labels explicitly name the top section.
+- 插件顶部分组与新版宿主工作区内置置顶分别保留；菜单文字明确指向顶部分组。
+- Verified DSH `0.2.0-rc.2` on Web and the official Electron Desktop: clean tarball installation, pin, restart persistence, navigation from the pinned section, and unpin.
+- 已在 DSH `0.2.0-rc.2` Web 及官方 Electron Desktop 实测压缩包安装、置顶、重启持久化、置顶会话导航和取消置顶。
+
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) while its public API remains pre-1.0.
+
+## [Unreleased]
+
+## [0.1.1] - 2026-09-04
+
+### Added
+
+- A hover/focus ellipsis menu on every pinned Session row.
+- Native Rename, Fork, Unpin, and Archive actions on Web.
+- Optional Delete and action-failure Toasts when the Desktop Archive Manager capability is active.
+- Keyboard menu navigation and focus handoff after a pinned row disappears.
+- English and Chinese product visuals, setup guidance, compatibility notes, and project policies.
+
+### Changed
+
+- Replaced the direct unpin control with the same Menu, Modal, Button, and icon primitives used by DSH.
+- Made Desktop delete availability react to service activation and disposal.
+
+## [0.1.0] - 2026-09-04
+
+### Added
+
+- Initial Web and Desktop profile bundle.
+- Exact Session ID capture from native menus.
+- Local pinned-session storage and a compact Workspace-header section.
+
+[Unreleased]: https://github.com/Anionex/dsh-pinned-sessions/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/Anionex/dsh-pinned-sessions/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/Anionex/dsh-pinned-sessions/releases/tag/v0.1.0

package/README.md

@@ -1,44 +1,103 @@
+<p align="center">
+  <img src="assets/hero.png" alt="DSH Pinned Sessions showing a pinned Session and its native action menu in the DeepSeek Harness sidebar" width="100%">
+</p>
+
 # DSH Pinned Sessions
 
-Pin important DeepSeek Harness sessions at the top of the Workspace sidebar.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@anionex/dsh-pinned-sessions"><img alt="npm version" src="https://img.shields.io/npm/v/@anionex/dsh-pinned-sessions?style=flat-square"></a>
+  <a href="https://github.com/Anionex/dsh-pinned-sessions/actions/workflows/ci.yml"><img alt="CI status" src="https://img.shields.io/github/actions/workflow/status/Anionex/dsh-pinned-sessions/ci.yml?branch=main&style=flat-square&label=CI"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/Anionex/dsh-pinned-sessions?style=flat-square"></a>
+  <img alt="DeepSeek Harness Web and Desktop" src="https://img.shields.io/badge/DSH-Web%20%2B%20Desktop-0F766E?style=flat-square">
+</p>
+
+<p align="center"><strong>Pin important Sessions. Open them without searching through every Workspace.</strong></p>
+
+<p align="center">
+  <strong>English</strong> · <a href="README.zh.md">简体中文</a>
+</p>
+
+DeepSeek Harness keeps Sessions inside their original Workspaces. Once the list grows, returning to a few active Sessions takes repeated scanning. DSH Pinned Sessions adds a compact pinned section below the Workspace header while leaving every native Session row in place.
+
+## See It in Action
+
+<p align="center">
+  <img src="assets/pinned-session-menu.png" alt="A pinned Session at the top of the Workspace sidebar with Rename, Fork, Unpin, and Archive actions open" width="465">
+</p>
+
+Hover a pinned row to reveal its ellipsis menu. The Web profile shows **Rename**, **Fork session**, **Unpin from top section**, and **Archive session**. The Desktop profile also shows **Delete session** when Archive Manager provides the same action on native rows.
 
-## Features
+## Highlights
 
-- Adds **Pin session** / **Unpin session** to the native Session actions menu.
-- Keeps pinned Sessions in a compact list above the native Workspace tree.
-- Opens a pinned Session through the official DSH Session service.
-- Preserves the original Session in its Workspace and keeps search, grouping, drag ordering, fork, rename, and archive behavior unchanged.
-- Stores pins in versioned browser-profile storage and removes stale or archived entries after DSH data is ready.
-- Supports both the DSH `web` profile and DSH Desktop's embedded Web client.
+- **Reach active work from the top of the sidebar:** pinned copies stay below the Workspace header, ordered newest first.
+- **Keep native organization intact:** the original Session remains in its Workspace.
+- **Use familiar actions:** pinned rows use DSH Menu, Modal, Button, icon, and service APIs.
+- **Work with exact Session identities:** pinning never guesses from a title or list position.
+- **Stay local:** the plugin stores Session IDs and pin timestamps in browser storage. It does not read or copy conversation content.
+- **Navigate by keyboard:** Arrow keys move through the menu, Escape returns focus, and removed rows hand focus to the next useful target.
 
-## Install
+## Quick Start
 
-From a checkout:
+Install the plugin in either profile, or run both commands:
 
 ```bash
-dsh plugin --profile web add .
-dsh plugin --profile desktop add .
+dsh plugin add @anionex/dsh-pinned-sessions --profile web
+dsh plugin add @anionex/dsh-pinned-sessions --profile desktop
 ```
 
-Restart each long-running profile after installation. Open a Session's `...` menu and choose **Pin session**. The pinned list appears directly below the Workspace header.
+Refresh Web or restart Desktop. Open any native Session ellipsis menu and choose **Pin to top section**. The pinned copy appears below the Workspace header; use **Unpin from top section** from either menu to remove it.
 
-Pins persist independently in each browser/Desktop profile. They are UI preferences and are not written into Session logs or Workspace files.
+### Requirements
+
+- DeepSeek Harness `>=0.1.0-rc.8 <0.2.0`
+- Node.js `^22.19.0` or `>=24.0.0`
+- A `web` or `desktop` DSH profile
 
 ## Compatibility
 
-DSH currently exposes additive root overlays but no row-level Session menu or Workspace-list header slot. This plugin mounts through the official `shell.overlay` lifecycle, then uses DSH's stable `[data-slot="sidebar.workspaces"]` and ARIA roles for placement. It captures a row's real Session ID from the native `sessions.open(node.id)` callback without navigating; if that verified capture is unavailable, the plugin fails closed and does not add a menu action.
+| Profile | Pinned-row actions | Verified behavior |
+| --- | --- | --- |
+| Web | Rename, Fork, Unpin, Archive | Official DSH primitives and Session/Workspace services |
+| Desktop | Rename, Fork, Unpin, Archive, optional Delete | Delete and failure Toasts appear only while Archive Manager exposes its Session deletion capability |
+
+Existing release ranges are preserved. Version 0.1.2 adds DSH `0.2.0-rc.2` installation support and uses its official session-menu slot and workspace navigation service. The plugin's top section remains separate from native workspace pinning. Web and official Electron Desktop installation and interactions have been verified; see [CHANGELOG](CHANGELOG.md). Legacy hosts retain the stable slot/ARIA bridge.
+
+## How It Works
+
+1. A click in the native Session menu captures that Session's exact ID synchronously.
+2. `PinStore` persists the ID and pin timestamp under `dsh.pinned-sessions.v1` in `localStorage`.
+3. The `shell.overlay` mount observes `[data-slot="sidebar.workspaces"]` and portals a compact list below its header.
+4. Pinned actions call DSH Session and Workspace services; Desktop Delete calls the optional Workspace Registry service.
 
-No title or list-position matching is used. All observers, listeners, portal hosts, and styles are removed on plugin disposal/HMR.
+The store keeps at most 500 unique IDs and prunes Sessions that no longer exist or have been archived.
+
+## Data and Limitations
+
+- Pins belong to the current DSH browser origin/profile. The plugin does not sync them between machines.
+- The plugin stores only Session IDs and `pinnedAt` timestamps in `localStorage`.
+- Pinned rows duplicate native rows by design; they do not move or remove the originals.
+- Delete stays hidden unless the Desktop deletion provider is active.
+- DSH client APIs change across prereleases; use the exact tested release verdicts in the package compatibility metadata.
 
 ## Development
 
 ```bash
-pnpm install
+git clone https://github.com/Anionex/dsh-pinned-sessions.git
+cd dsh-pinned-sessions
+corepack enable
+pnpm install --frozen-lockfile
 pnpm run check
 ```
 
-The repository commits `lib/` so a Git checkout can be installed directly.
+`pnpm run check` type-checks both targets, rebuilds the distributable client, runs the Vitest and package-layout suites, and performs an npm pack dry run.
+
+## Community
 
-## License
+- Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+- Report vulnerabilities through the process in [SECURITY.md](SECURITY.md).
+- Use [SUPPORT.md](SUPPORT.md) to choose the right issue path.
+- Review release history in [CHANGELOG.md](CHANGELOG.md).
+- Read [FUNDING.md](FUNDING.md) before sponsoring maintenance.
+- Follow the [Code of Conduct](CODE_OF_CONDUCT.md) in project spaces.
 
-MIT
+Released under the [MIT License](LICENSE).

package/README.zh.md

@@ -1,44 +1,103 @@
-# DSH 置顶会话
+<p align="center">
+  <img src="assets/hero.png" alt="DeepSeek Harness 侧栏中显示置顶会话及其原生操作菜单" width="100%">
+</p>
 
-把重要的 DeepSeek Harness 会话固定在左侧工作区列表顶部。
+# DSH Pinned Sessions
 
-## 功能
+<p align="center">
+  <a href="https://www.npmjs.com/package/@anionex/dsh-pinned-sessions"><img alt="npm 版本" src="https://img.shields.io/npm/v/@anionex/dsh-pinned-sessions?style=flat-square"></a>
+  <a href="https://github.com/Anionex/dsh-pinned-sessions/actions/workflows/ci.yml"><img alt="CI 状态" src="https://img.shields.io/github/actions/workflow/status/Anionex/dsh-pinned-sessions/ci.yml?branch=main&style=flat-square&label=CI"></a>
+  <a href="LICENSE"><img alt="MIT 许可证" src="https://img.shields.io/github/license/Anionex/dsh-pinned-sessions?style=flat-square"></a>
+  <img alt="支持 DeepSeek Harness Web 和 Desktop" src="https://img.shields.io/badge/DSH-Web%20%2B%20Desktop-0F766E?style=flat-square">
+</p>
 
-- 在原生会话“...”菜单中增加“置顶会话 / 取消置顶”。
-- 在原生工作区树上方显示紧凑的置顶会话列表。
-- 点击置顶项时通过 DSH 官方 Session 服务打开会话。
-- 原会话仍保留在原工作区中，搜索、分组、拖拽排序、分叉、重命名和归档全部保持原样。
-- 使用带版本号的浏览器 profile 存储；DSH 数据就绪后自动移除已归档或已消失的条目。
-- 同时支持 DSH `web` profile 和 DSH Desktop 内嵌的 Web 客户端。
+<p align="center"><strong>置顶重要会话，不必再从每个工作区里反复查找。</strong></p>
 
-## 安装
+<p align="center">
+  <a href="README.md">English</a> · <strong>简体中文</strong>
+</p>
 
-在插件仓库中执行：
+DeepSeek Harness 会把 Session 保留在原工作区中。会话增多后，返回少数活跃 Session 需要反复扫描列表。DSH Pinned Sessions 在工作区标题下增加一块紧凑的置顶区，同时保留每条原生 Session 行。
+
+## 实际效果
+
+<p align="center">
+  <img src="assets/pinned-session-menu.png" alt="工作区侧栏顶部的一条置顶会话，已打开重命名、分叉、取消置顶和归档操作" width="465">
+</p>
+
+悬浮置顶行即可显示三点菜单。Web profile 提供**重命名**、**分叉会话**、**从顶部分组取消置顶**和**归档会话**。Desktop profile 在 Archive Manager 为原生会话提供删除能力时，还会显示**删除会话**。
+
+## 主要能力
+
+- **从侧栏顶部直接返回活跃任务：**置顶副本位于工作区标题下，按最近置顶排序。
+- **保留原有工作区结构：**原生 Session 不会被移动或删除。
+- **沿用熟悉的操作：**置顶行使用 DSH 的 Menu、Modal、Button、图标和服务 API。
+- **绑定准确的 Session ID：**插件不会根据标题或列表位置猜测会话。
+- **数据留在本机：**插件只保存 Session ID 和置顶时间，不读取或复制对话内容。
+- **支持键盘操作：**方向键可切换菜单项，Escape 会归还焦点，删除行后焦点会落到下一个有效目标。
+
+## 快速开始
+
+按需安装到一个 profile，也可以执行两条命令：
 
 ```bash
-dsh plugin --profile web add .
-dsh plugin --profile desktop add .
+dsh plugin add @anionex/dsh-pinned-sessions --profile web
+dsh plugin add @anionex/dsh-pinned-sessions --profile desktop
 ```
 
-安装后重启对应的长期运行 profile。打开任意会话的“...”菜单并选择“置顶会话”，置顶区会出现在“工作区”标题正下方。
+刷新 Web 或重启 Desktop。打开任意原生 Session 的三点菜单，选择**置顶到顶部分组**。置顶副本会出现在工作区标题下；从任意一侧菜单选择**从顶部分组取消置顶**即可移除。
 
-Web 与 Desktop 各自在自己的浏览器 profile 中持久化置顶状态；该状态不会写入会话日志或工作区文件。
+### 环境要求
 
-## 兼容实现
+- DeepSeek Harness `>=0.1.0-rc.8 <0.2.0`
+- Node.js `^22.19.0` 或 `>=24.0.0`
+- `web` 或 `desktop` DSH profile
 
-当前 DSH 提供可叠加的根级 overlay slot，但没有逐会话菜单或工作区列表头部 slot。本插件通过官方 `shell.overlay` 生命周期挂载，再使用 DSH 稳定的 `[data-slot="sidebar.workspaces"]` 和 ARIA role 完成精确放置。插件通过原生 `sessions.open(node.id)` 回调无导航地捕获真实 Session ID；如果无法验证该捕获路径，就直接不添加菜单项。
+## 兼容性
 
-实现不会按标题或列表序号猜测会话。插件卸载或热重载时会完整清理 observer、事件监听、portal 宿主和样式。
+| Profile | 置顶行操作 | 已验证行为 |
+| --- | --- | --- |
+| Web | 重命名、分叉、取消置顶、归档 | 使用 DSH 官方组件和 Session/Workspace 服务 |
+| Desktop | 重命名、分叉、取消置顶、归档、可选删除 | 仅在 Archive Manager 暴露删除能力时显示删除和失败 Toast |
+
+保留既有版本范围。0.1.2 版 增加 DSH `0.2.0-rc.2` 安装支持，使用其官方会话菜单 slot 和工作区导航服务。插件顶部分组与宿主工作区内置置顶分别保留。已通过 Web 及官方 Electron Desktop 安装与交互验收，见 [CHANGELOG](CHANGELOG.md)。旧版宿主继续使用稳定的 slot/ARIA 桥接。
+
+## 工作原理
+
+1. 用户点击原生 Session 菜单时，插件同步捕获该 Session 的准确 ID。
+2. `PinStore` 把 ID 和置顶时间写入 `localStorage` 的 `dsh.pinned-sessions.v1`。
+3. `shell.overlay` 挂载点观察 `[data-slot="sidebar.workspaces"]`，并把紧凑列表 portal 到标题下方。
+4. 置顶行通过 DSH Session 和 Workspace 服务执行操作；Desktop 删除使用可选的 Workspace Registry 服务。
+
+存储层最多保留 500 个唯一 ID，并自动清理已不存在或已归档的 Session。
+
+## 数据与限制
+
+- 置顶状态属于当前 DSH 浏览器源/profile，不会跨设备同步。
+- 插件只在 `localStorage` 中保存 Session ID 和 `pinnedAt` 时间戳。
+- 置顶行是原生行的快捷副本，不会移动或删除原位置。
+- Desktop 删除能力未加载时，删除菜单项保持隐藏。
+- DSH 客户端 API 会随预发布版本变化；请以包兼容元数据中明确实测的版本结论为准。
 
 ## 开发
 
 ```bash
-pnpm install
+git clone https://github.com/Anionex/dsh-pinned-sessions.git
+cd dsh-pinned-sessions
+corepack enable
+pnpm install --frozen-lockfile
 pnpm run check
 ```
 
-仓库提交 `lib/` 构建产物，因此 Git checkout 可以直接安装。
+`pnpm run check` 会检查两个目标的类型、重建可分发客户端、运行 Vitest 和包布局测试，并执行 npm 打包预检。
+
+## 社区
 
-## 许可证
+- 提交 Pull Request 前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
+- 安全问题按 [SECURITY.md](SECURITY.md) 中的私密渠道报告。
+- [SUPPORT.md](SUPPORT.md) 说明了不同问题应使用的入口。
+- [CHANGELOG.md](CHANGELOG.md) 记录每个版本的变化。
+- 赞助维护工作前请阅读 [FUNDING.md](FUNDING.md)。
+- 参与项目空间时请遵守 [行为准则](CODE_OF_CONDUCT.md)。
 
-MIT
+项目采用 [MIT License](LICENSE)。