\r\n English · 简体中文\r\n
\r\n\r\n# @dsh-xhl/workspace-groups\r\n\r\n\r\n\r\n![\"DeepSeek](\"https://img.shields.io/badge/DeepSeek%20Harness-plugin-202724\"){kind=icon}
\r\n\r\n> **A DeepSeek Harness (DSH) web client plugin: a complete workspace grouping manager.**\r\n> Turns the GUI sidebar's two-level workspace list (Projects → Sessions) into a\r\n> three-level **Category folder → Project folder → Session** tree, backed by full\r\n> group-management capabilities: manual group creation, rename/delete of any group,\r\n> drag-and-drop grouping, free ordering of projects and groups, rule-based\r\n> auto-classification, and tree-shaped search. Every action takes effect\r\n> **immediately and persists**, with **zero intrusion** on official data.\r\n\r\n\r\n## Screenshot\r\n\r\n![\"@dsh-xhl/workspace-groups](\"screenshot.png\")
\r\n\r\n## Features\r\n\r\n### Grouped tree browsing\r\n- **Group folder → project folder → session row**, both levels collapsible; expansion state\r\n persists independently (`dsh.workspace.groups.view.v1`, survives refresh/restart)\r\n- **Top-level project rows**: ungrouped projects (matching no rule, dragged out of a group,\r\n or returned by a group delete) render as plain rows right after the group folders, at the\r\n same level — **there is no \"未分类\" bucket**\r\n- **A \"flower branch\" runs down the tree and grows to the row you are on.** Ported from the\r\n [RewampUI Flower Sidebar](https://www.rewampui.com/components/flower-sidebar): one continuous\r\n SVG stem behind the rows, with **every dot anchored to its own row's marker** — a folder's dot\r\n sits on its expand triangle, a session's on its status dot — so the three levels form three\r\n clean columns instead of one stem floating beside them. A faint dashed *ghost* draws the whole\r\n route while a solid stroke is drawn only as far as the active row, so the stem visibly reaches\r\n where you are; that row's dot blooms (r 3.2 vs 2). Both coordinates are **measured per row**\r\n (the tree mixes row heights and indents per row via padding, so neither a single pitch nor a\r\n single stem x lands correctly). The overlay is `pointer-events: none` and paints behind the\r\n rows, so every click, hover and drag still belongs to the row. The host theme has no accent hue\r\n to borrow (`--dsw-alias-brand-primary` is the same near-black as the label colour, and the only\r\n saturated tokens are the state colours, which would falsely read as \"running\" / \"needs\r\n attention\"), so the bloom is expressed by **size plus full-strength ink** instead.\r\n- **You can tell at a glance which workspace a session belongs to.** Beyond the branch, three\r\n more independent cues — not indent alone, since a 20px indent with identical type at both\r\n levels was previously the *only* difference between a child session and a sibling project row:\r\n 1. **Weight**: folder labels 600 (700 for the folder holding the open session); session titles\r\n 400 (500 when that session is open).\r\n 2. **Typeface**: folder names are directory names and render **monospace**; session titles are\r\n prose in the UI font. This cue is not colour-based, so it survives every theme.\r\n 3. **Colour**: folder labels primary, session titles secondary — the open session lifts back.\r\n\r\n### Group management (full lifecycle)\r\n- **Create groups manually**: the \"新建分组\" button in the section header shows the group\r\n immediately (empty groups render too)\r\n- **Rename / delete any group**: every group row (**rule categories included**) has a hover\r\n `⋯` menu; deleting a group sends all of its projects back to the **top level**;\r\n rule-category rename/delete rides the overlay (`renamed` / `hidden`),\r\n **the rule YAML stays untouched**\r\n- **Rule-based auto-classification**: the sidecar YAML declares category rules (`pathPrefix` /\r\n `pathExact` / `nameContains` / `basenameContains`); edit the config to adjust grouping\r\n without touching code\r\n\r\n### Drag-and-drop grouping + ordering\r\n- **Drag projects into groups**: drop on any group row or on a project row inside a group\r\n (cross-group move = overrides the rule classification)\r\n- **Drag projects OUT of a group**: the **entire top-level area** is the move-out drop\r\n target while dragging, shown with an **insertion line** (not a highlight box) — drop on\r\n any top-level row (reorder before/after it), on the blank space below the last row\r\n (append), or, when the top level is empty, a standalone line under the last group\r\n folder; grouped projects also have a \"移出分组\" menu item (rule-classified ones included)\r\n- **Reorder projects inside a group**: top half of a project row = insert before it,\r\n bottom half = insert after it\r\n- **Reorder top-level projects**: top-level rows are draggable too — top half = insert\r\n before, bottom half = insert after; the top-level order persists under\r\n `workspaceOrder[\"__topLevel__\"]`\r\n- **Reorder groups**: group rows are draggable — top half of another group row = move before it,\r\n bottom half = move after it\r\n- **Insertion position indicator**: a 2px line (above/below the row) shows the exact drop\r\n point while dragging — what you see is where it lands\r\n- **Level-aware folding, auto-restored**: dragging a project folds every project row\r\n (grouped AND top-level; group rows stay expanded); dragging a group folds every group\r\n (project rows keep their expansion) — dragend restores the pre-drag expansion snapshot\r\n- **Distinct row icons**: group rows use a folder glyph, project rows a project glyph\r\n (same as the official workspace browser) — groups and projects are easy to tell apart\r\n\r\n### Search & operations\r\n- **Tree-shaped search**: results keep the three-level structure (category → project → matched\r\n session), matched rows highlighted with a content snippet, 250ms debounce\r\n- **No regression on workspace/session actions**: Add Workspace, project rename/delete,\r\n session new/open/rename/fork/archive\r\n- **Open in folder**: the project row menu gains an \"Open in folder\" entry whenever the\r\n host resolved a system file manager (reusing the official open-in-app routes — this\r\n plugin adds no host route of its own)\r\n\r\n### Session tabs\r\n- **A tab means \"in play\", not \"once opened\".** A session earns a tab only once a conversation\r\n has actually started in it *and* it is still engaged: **running**, **waiting on you**\r\n (approval / plan review / question), or **finished while you were away** (the unread marker —\r\n the tab is what tells you to come back). A blank draft holds no tab until its first message is\r\n sent, and **browsing settled history leaves the strip alone** — clicking through finished\r\n conversations no longer litters it with tabs. Tabs already opened stay open; this rule only\r\n decides whether a *new* one appears. (Browsing history is the sidebar's job; the strip is a\r\n working set. The earlier `!blank` rule failed because a conversation finished last week is\r\n also non-blank.)\r\n- **Each tab is shaped like a folder tab**: the workspace on a **short top line** over the session\r\n title on a **longer bottom line**, so the stacked pair reads as a labelled folder rather than two\r\n unrelated strings. The workspace line is monospace, smaller (10px) and secondary; the title is\r\n 12px and primary, making the conversation the chip's subject. Each line sizes to its own content\r\n (`align-items: flex-start`), which is what produces the short-over-long shape. Chips carry a\r\n faint inset outline that strengthens on the active one, so a row of them reads as separate\r\n objects instead of one continuous bar. A session in no workspace shows its title alone,\r\n vertically centred. The tooltip carries the full `workspace · title` plus the directory path.\r\n- **The strip is kept on the HOST, and survives a reload, a restart and a port change.** It is\r\n stored in a JSON sidecar under `$DSH_HOME` (`workspace-groups.tabs.json`), served over\r\n `GET|PUT /workspace-groups/tabs`. Browser storage **cannot** do this job: the origin includes\r\n the **port**, every launch picks a new one, and `localStorage` / `sessionStorage` are both\r\n scoped to the origin — so a tab list kept there starts empty next time. The read is deliberately\r\n **not gated by any browser-session marker**: a marker has to live in browser storage too, so the\r\n port change would erase it and every restart would look like a fresh session (that bug shipped\r\n once and silently discarded the user's tabs). The sidecar simply is the strip's memory, and a\r\n file written by the older marker-based build still loads — the extra field is ignored.\r\n- **A tab appears the moment a session starts working**: a sidebar session row, a workspace's\r\n `+` (New Session), the Ctrl+R quick switch, or a conversation-header crumb — open a session\r\n from any entry point and, once it starts running, is waiting on you, or finished while you\r\n were away, a tab appears in the strip at the **top of the conversation column**; opening\r\n another adds another (one tab per session)\r\n- **Positions never move once placed**: a tab's slot in the strip is decided when it is first\r\n opened and never changes afterwards. Switching to a tab — or re-opening a session that\r\n already has one — only moves the *highlight*; the chips stay exactly where they are, so a\r\n click never slides the chip out from under your pointer. Only two things change the order:\r\n a session opening for the first time (appended at the end) and a tab closing\r\n- **Scrolls sideways when the strip fills up, with no scrollbar**: chips hold their natural\r\n width instead of squeezing, so past the available width the row scrolls horizontally. The\r\n bar itself is hidden (`scrollbar-width: none` + `::-webkit-scrollbar`), keeping the strip\r\n one line tall. A plain mouse wheel scrolls it sideways, and the active chip is scrolled into\r\n view when you switch sessions — so a tab far to the right is never stranded off-screen\r\n- **Only YOU close a tab.** The `×` on the right of a tab is the single way it disappears — the\r\n plugin never trims the strip on its own. Not on archive, not on Host deletion, not when a\r\n session drops out of the catalog: a tab you opened stays until you say otherwise, and it\r\n survives reloads and restarts (see the persistence note below). This is deliberate. An\r\n automatic sweep eventually eats tabs the user wanted, and it also misfires for a mechanical\r\n reason — the session catalog is briefly empty on every load, so a \"close tabs whose session is\r\n gone\" rule deletes every restored tab before the sessions have even arrived.\r\n- **Session status per tab**: the dot reuses the sidebar's vocabulary — amber = a question,\r\n approval, or plan review is waiting, green = running (subagent work included), grey = idle\r\n (the unread-completion reminder uses the same completion dot)\r\n- **Active chip**: the tab whose session is open is highlighted with an inset accent bar; a\r\n click on a background chip switches through the official `ctx.uiWorkspace.openSession` — the\r\n exact path a sidebar row takes\r\n- **Double-click renames**: double-clicking a tab opens the session rename dialog (the same one\r\n the sidebar's `⋯` menu opens)\r\n- **Blank drafts never take a tab**: a scratch New Session stays out of the strip and earns a\r\n tab the moment its first turn gives the session a title\r\n- Tab order and the open selection **persist** (`dsh.workspace.groups.tabs.v1`), so a reload\r\n keeps the strip in the same order\r\n\r\n### Persistence & zero intrusion\r\n- Every manual action (groups, grouping, ordering, rename, hide) is written to the plugin's own\r\n overlay (`~/.dsh/workspace-groups.manual.json`), validated by the host and **written\r\n atomically** (a malformed write returns 400 and keeps the previous file)\r\n- **Zero intrusion**: never touches `~/.dsh/storages/workspace.json`, session on-disk\r\n structures, or the official `@deepseek-ai/dsh-client-ui-workspace` package; the rule YAML\r\n is never rewritten\r\n- **Self-contained artifact**: `lib/` is prebuilt and shipped with the repo — installing from\r\n Git runs no dependency scripts\r\n\r\n## How it works\r\n\r\n- The plugin is a **client plugin** with ONE slot registration plus one DOM-seated view:\r\n 1. the sidebar browser, registered into the official sidebar shell's `sidebar.workspaces`\r\n slot (`kind: 'single'`, `scope: 'root'`) at `priority: -1`, replacing the official\r\n WorkspaceBrowser (registered at priority 0; lowest priority wins in a single slot);\r\n 2. the session tab strip, which is **not a slot occupant**. It renders through a React\r\n portal into a container injected as the **first child of the conversation column**\r\n (`centerCol` in ui-layout's AppFrame) — the row directly above the conversation panel.\r\n- **Why a DOM seat instead of a slot**: the conversation column declares **no child slot**.\r\n Its only child is the `main` slot's occupant (the Conversation or a global panel), so there\r\n is nowhere to register a strip. The nearest shipped slot,\r\n `conversation.composer.dock`, is the band *under* the composer card — a different place\r\n entirely. The strip therefore claims a real DOM node: `tab-seat.ts` finds the column by the\r\n `_centerCol` class suffix the CSS-Modules transform always preserves (never the build-hashed\r\n prefix), prepends its own `