dsh-workspace-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ice5kysl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# dsh-workspace-kit
+
+> GitHub: <https://github.com/ice5kysl/dsh-workspace-kit> ｜ MIT License ｜ Target dsh: `@deepseek-ai/dsh` ≥ 0.1.1-rc.2 ｜ English · [简体中文](./README.zh-CN.md)
+
+A **dsh (DeepSeek Harness) plugin** written to official conventions, in the Cordis "bundle" form. It solves two pain points:
+
+1. **Too many workspaces, hard to find** → **⌘K / Ctrl+K Spotlight search**: fuzzy-search all workspaces and sessions (including ungrouped and archived ones), navigate with ↑↓ and press Enter to **open / jump** directly.
+2. **Want to archive old workspaces** → **soft archive** (hidden + restorable, no data deleted):
+   - **Built-in sidebar**: the plugin registers into the `sidebar.workspaces` slot at low priority (-1), **replacing the shipped workspace browser** — archived workspaces leave the "Workspaces" list and move into a collapsible "Archived (N)" section where you can restore / open / start a new session; ungrouped sessions live in their own section too.
+   - **Spotlight**: the idle list hides archived items; when you type, matching archived items appear with an "Archived" badge so you can locate and restore them.
+   - Archive / restore is also available on every sidebar row and Spotlight result.
+
+The plugin ships **two faces** carried by a single Loader entry (`dsh-workspace-kit`):
+
+| Face | File | Responsibility |
+|---|---|---|
+| Host (node) | `lib/index.js` | `workspace_find` / `workspace_list` model tools; `/workspace-find`, `/workspace-list` slash commands (read-only lookup; write actions stay in the GUI) |
+| Browser (client) | `lib/client.js` | Spotlight palette (registered into the official, otherwise-empty `shell.overlay` slot) + soft-archive store (localStorage-persisted) + enhanced sidebar browser |
+
+> Design rationale: dsh's official model only has **session-level** (irreversible) archiving and the shipped sidebar browser has no per-row hide seam, so this plugin takes a "**view-layer soft archive** + **shadow the sidebar browser**" approach: archive state is managed by the plugin (browser-persisted) and, by shadowing `sidebar.workspaces` with its own browser that carries the collapsible "Archived" section, archived workspaces truly leave the main sidebar list. The v1 capability boundary of the replacement browser is documented in [known-limitations.md](./docs/known-limitations.md).
+
+Beyond archive/restore, the enhanced sidebar (when active) adds:
+
+- **New workspace** (the plus button next to search) — system directory picker → register → open.
+- **Sidebar search** (expandable input) — filter workspaces/sessions by title and path, plus **full-text session-content search** (≥2 chars, debounced, via the official host content index).
+- **Per-workspace icon + accent color** — hover a row and click the palette button (or the icon itself); 32 SVG icons + 9 colors, "clear" to reset; Spotlight results show the same look (browser-persisted).
+- **Drag reorder** — drag workspace rows → official `insertBefore`; drag sessions within their workspace → `insertSessionBefore`; once a workspace is manually dragged its sessions switch to the manual (account) order, matching the shipped Manual semantics.
+- **Styled dialogs** — rename / delete / archive confirmations use in-app styled dialogs instead of `prompt`/`confirm`.
+- **One-click sidebar toggle** — a footer button switches between the enhanced sidebar and the official sidebar instantly; the choice persists across restarts.
+
+You can also say things like "use `workspace_find` to find the pms workspace" in a session, or type `/workspace-find pms`.
+
+## Languages (i18n)
+
+All user-facing copy is bilingual (Simplified Chinese / English):
+
+- **Browser (client)**: locale is resolved from the `localStorage` key `dsh.workspace-kit.locale` (`zh` | `en`) when set, otherwise from `navigator.language(s)` (`zh*` → Chinese, anything else → English).
+- **Host (node)**: locale is resolved from the `WSKIT_LOCALE` environment variable (`zh` | `en`) when set, otherwise from `LC_ALL` / `LANG` (`zh*` → Chinese), defaulting to English.
+- Translations live at the call site via an `L('中文', 'English', vars?)` helper backed by `src/shared/i18n.ts`; see the per-side `src/client/locale.ts` and `src/host/locale.ts` for detection.
+
+## Quick install (personal dsh)
+
+Prerequisites: `dsh` on PATH (`@deepseek-ai/dsh` ≥ 0.1.1-rc.2), Node 20+.
+
+```bash
+# 0. Get the source (or use a local directory)
+git clone https://github.com/ice5kysl/dsh-workspace-kit && cd dsh-workspace-kit
+
+# 1. Build (produces lib/index.js + lib/client.js; the prepare hook of
+#    npm install already runs the build for you)
+npm install                # installs build-time deps (typescript/esbuild/@types …)
+npm run build
+
+# 2. Install into your web profile (equivalent to the official `dsh plugin add`)
+bash scripts/install-personal.sh
+#    The script locates this directory itself and runs
+#    `dsh plugin --profile web add .`, which appends the package to
+#    `dsh.profile.bundles` in ~/.dsh/profiles/web (after dsh-web-app) and
+#    lets the in-package cordis.patch.yml insert the single Loader row.
+
+# 3. Verify the composition (no restart needed)
+dsh --profile web --dump-config | grep -n "workspace-kit"
+
+# 4. Restart the GUI to activate
+#    Quit the current dsh web (Ctrl+C or kill the process), run `dsh web`
+#    again, then refresh the browser at http://127.0.0.1:3080
+```
+
+> Also usable as a monorepo subdirectory (e.g. `plugins/dsh-workspace-kit`): the install script walks up from `package.json` to find the plugin directory, so both layouts need no command changes.
+
+## Package / distribute (optional)
+
+```bash
+npm pack          # produces dsh-workspace-kit-0.1.0.tgz (prebuilt lib/; prepack builds automatically)
+# Other machine: dsh plugin --profile web add ./dsh-workspace-kit-0.1.0.tgz
+```
+
+## Development
+
+```bash
+npm run typecheck   # tsc --noEmit (host + client sources)
+npm run build       # esbuild: src/host → lib/index.js; src/client → lib/client.js
+```
+
+Source layout:
+
+```
+src/host/      Host side: locale.ts (env-based locale), util.ts (search/list pure
+               functions), tools.ts (model tools), commands.ts (slash commands),
+               index.ts (apply: registers per service availability)
+src/client/    Browser side: locale.ts (navigator-based locale), archive-store.ts
+               (defineStore soft-archive set + appearance, persist localStorage),
+               dialogs.tsx, SidebarToggle.tsx, Spotlight.tsx (⌘K palette),
+               WorkspaceSidebar.tsx, index.ts (apply: slot registrations + closures)
+src/shared/    i18n.ts (pure locale helpers shared by both faces)
+cordis.patch.yml    bundle layer: inserts the single Loader entry `dsh-workspace-kit`
+```
+
+## How it works / design notes (based on official docs & source)
+
+- Plugin shape = a **bundle package** (`dsh.bundle.patch`) + a **browser face** (`dsh.client.platform: 'web'` + the `./client` export). The host scans enabled Loader entries; one package provides both the node and the browser side from the same entry, and **one package may only have one entry** (multiple entries resolving to the same package name are rejected by the client module system).
+- Spotlight mounts into **`shell.overlay` (list/root)** — the official slot reserved for whole-window custom overlays. The sidebar registers into **`sidebar.workspaces` (single/root)** at **priority -1** to shadow the built-in occupant (lower priority renders; only equal priorities conflict) — the officially allowed "full replacement" route, at the cost of re-implementing some built-in browser capabilities yourself (see known-limitations).
+- Data is read through the framework's standard hooks (`useWorkspaces` / `useSessions` / `useStore`); actions go through registered `inject` closures that call the official session service: `ctx.workspaces.startSession(workspaceId)` (reuse/create and open that workspace's session) and `ctx.sessions.open(id)`.
+- The archive set uses the framework's `defineStore` + `persist` (bare JSON in localStorage under `dsh.workspace-kit.archive.v1`), the same mechanism as built-in view preferences (e.g. `dsh.workspace.view.v5`).
+- There is no official registration API for global hotkeys (no keyboard service anywhere in the repo), so, following the convention of built-in plugins, a `window` keydown listener is attached (⌘K/Ctrl+K); the palette stays mounted and renders `null` while closed to keep the listener alive.
+- The host side is deliberately **read-only**: archive semantics are view-layer (browser) state; keeping a second copy host-side would drift from the GUI, so it is intentionally not written.
+
+## Compatibility
+
+- Target dsh: `@deepseek-ai/dsh` v0.1.1-rc.2 (`dsh web`, profile `web`). The browser face targets that release's `shell.overlay` / `IWorkspaces` / `ISessions` contracts; re-validate against the upstream contract on version upgrades.
+- Known limitations and the backlog are tracked in [docs/known-limitations.md](./docs/known-limitations.md) (中文版见 [docs/known-limitations.zh-CN.md](./docs/known-limitations.zh-CN.md)).
+
+## License
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,114 @@
+# dsh-workspace-kit
+
+> GitHub：<https://github.com/ice5kysl/dsh-workspace-kit> ｜ MIT License ｜ 目标 dsh：`@deepseek-ai/dsh` ≥ 0.1.1-rc.2 ｜ 简体中文 · [English](./README.md)
+
+按官方规范编写的 **dsh（DeepSeek Harness）插件**（Cordis bundle 形态），解决两个痛点：
+
+1. **工作区太多、难找** → **⌘K / Ctrl+K Spotlight 搜索**：模糊搜索全部工作区与会话（含未归组、已归档），↑↓ 选择、回车**直接打开/跳转**。
+2. **想归档旧工作区** → **软归档**（隐藏 + 可恢复，不删任何数据）：
+   - **内置侧栏**：插件以 `sidebar.workspaces` 槽位低优先级（-1）**替换内置工作区浏览器**——归档后的工作区从「工作区」列表消失，收进可折叠的「已归档 (N)」分区，展开后可「恢复 / 打开 / 新建会话」；未归组会话也在独立分区。
+   - **Spotlight**：空闲列表不显示已归档；输入关键词时命中项带「已归档」标记出现，方便定位与恢复。
+   - 归档/恢复同样可从侧栏每行与 Spotlight 结果行操作。
+
+插件分**两个 face**，由同一个 Loader 入口（`dsh-workspace-kit`）携带：
+
+| Face | 文件 | 职责 |
+|---|---|---|
+| 宿主（node） | `lib/index.js` | `workspace_find` / `workspace_list` 模型工具；`/workspace-find`、`/workspace-list` 斜杠命令（只读定位，写动作留在 GUI） |
+| 浏览器（client） | `lib/client.js` | Spotlight 面板（注册进官方空置的 `shell.overlay` 槽）+ 软归档 store（localStorage 持久化）+ 增强侧栏浏览器 |
+
+> 设计取舍：dsh 官方模型只有**会话级**归档（不可逆）且内置侧栏浏览器无行级隐藏接缝，所以本插件采用「**视图层软归档** + **shadow 替换侧栏浏览器**」：归档状态由插件管理（浏览器持久化），并通过把 `sidebar.workspaces` 替换成自带「已归档」折叠分区的浏览器让归档真正从侧栏主列表消失。替换式浏览器 v1 的能力边界见 [known-limitations.zh-CN.md](./docs/known-limitations.zh-CN.md)。
+
+除归档/恢复外，增强侧栏（启用时）还提供：
+
+- **新建工作区**（搜索按钮旁的加号按钮）——系统目录选择器 → 注册 → 打开。
+- **侧栏搜索**（展开输入框）——按工作区标题/路径与会话标题过滤，另有 **会话内容全文搜索**（≥2 字符防抖调官方 host 内容索引，结果按「会话内容命中」列出）。
+- **每工作区图标 + 强调色**——hover 工作区行点调色板按钮（或直接点图标）：32 个 SVG 图标 + 9 色可选，「清除」还原；Spotlight 结果同步显示（浏览器持久化）。
+- **拖拽排序**——工作区行拖动 → 官方 `insertBefore` 持久化；工作区内会话拖动 → `insertSessionBefore`；某工作区一旦手动拖过，其会话改按手动（账户）顺序展示（对齐内置 Manual 语义）。
+- **内置风格对话框**——重命名/删除/归档确认统一走插件样式化弹窗。
+- **侧栏一键切换**——底部常驻按钮在「增强侧栏 / 官方侧栏」间即时互切，选择持久化、重启保持。
+
+会话里可直接说「用 workspace_find 找一下 pms 工作区」，或输入 `/workspace-find pms`。
+
+## 多语言（i18n）
+
+所有面向用户的文案均为中英双语（简体中文 / English）：
+
+- **浏览器（client）**：优先读取 `localStorage` 键 `dsh.workspace-kit.locale`（`zh` | `en`），否则按 `navigator.language(s)` 判定（`zh*` → 中文，其它 → 英文）。
+- **宿主（node）**：优先读取环境变量 `WSKIT_LOCALE`（`zh` | `en`），否则按 `LC_ALL` / `LANG` 判定（`zh*` → 中文），默认英文。
+- 双语文案在调用点以 `L('中文', 'English', vars?)` 形式就地书写，基础设施在 `src/shared/i18n.ts`，语言探测分别在 `src/client/locale.ts` 与 `src/host/locale.ts`。
+
+## 快速安装（本机个人 dsh）
+
+前置：`dsh` 在 PATH（`@deepseek-ai/dsh` ≥ 0.1.1-rc.2），Node 20+。
+
+```bash
+# 0. 获取源码（或直接使用本地目录）
+git clone https://github.com/ice5kysl/dsh-workspace-kit && cd dsh-workspace-kit
+
+# 1. 构建（产出 lib/index.js + lib/client.js；npm install 的 prepare 钩子会自动构建）
+npm install                # 安装构建期依赖（typescript/esbuild/@types 等）
+npm run build
+
+# 2. 安装进你的 web profile（等价于官方 dsh plugin add 组合包）
+bash scripts/install-personal.sh
+#    脚本会自动定位本目录，实际执行 dsh plugin --profile web add .，
+#    把这个包加入 ~/.dsh/profiles/web 的 dsh.profile.bundles（追加在
+#    dsh-web-app 之后），包内 cordis.patch.yml 自动插入唯一 Loader 行。
+
+# 3. 验证组合（无需重启）
+dsh --profile web --dump-config | grep -n "workspace-kit"
+
+# 4. 重启 GUI 生效
+#    退出当前 dsh web（Ctrl+C 或 kill 进程）后重新运行 dsh web；
+#    浏览器刷新 http://127.0.0.1:3080
+```
+
+> 也支持作为 monorepo 子目录使用（如 `plugins/dsh-workspace-kit`）：
+> 安装脚本按 `package.json` 自动向上定位插件目录，两种布局都无需改命令。
+
+## 打包 / 分发（可选）
+
+```bash
+npm pack          # 产出 dsh-workspace-kit-0.1.0.tgz（含预构建 lib/，prepack 自动 build）
+# 其他机器：dsh plugin --profile web add ./dsh-workspace-kit-0.1.0.tgz
+```
+
+## 开发
+
+```bash
+npm run typecheck   # tsc --noEmit（宿主 + 浏览器两侧源码）
+npm run build       # esbuild：src/host → lib/index.js；src/client → lib/client.js
+```
+
+源码布局：
+
+```
+src/host/     宿主侧：locale.ts（env 语言探测）、util.ts（搜索/列表纯函数）、
+             tools.ts（模型工具）、commands.ts（斜杠命令）、index.ts（apply：
+             按服务可用性注册）
+src/client/   浏览器侧：locale.ts（navigator 语言探测）、archive-store.ts
+             （defineStore 软归档集 + 外观，persist localStorage）、dialogs.tsx、
+             SidebarToggle.tsx、Spotlight.tsx（⌘K 面板）、WorkspaceSidebar.tsx、
+             index.ts（apply：槽位注册 + 动作闭包）
+src/shared/   i18n.ts（两侧共享的纯 i18n 工具）
+cordis.patch.yml   bundle 层：插入唯一 Loader 入口 dsh-workspace-kit
+```
+
+## 设计说明（为什么这样写，均依据官方文档/源码）
+
+- 插件形态 = **组合包**（`dsh.bundle.patch`）+ **浏览器 face**（`dsh.client.platform: 'web'` + `./client` 导出）。host 扫描已启用的 Loader 条目，同一入口的包同时提供 node 与浏览器两侧，且**一个包只能有一个入口**（多入口解析到同一包名会被 client 模块系统拒绝）。
+- Spotlight 挂载到 **`shell.overlay`（list/root）**——官方为"整窗自定义浮层"预留的槽。侧栏浏览器注册进 **`sidebar.workspaces`（single/root）并用 priority -1 shadow** 内置占用者（priority 升序、最低者渲染，同 priority 才会报错）——这是官方允许的"整体替换"路线，代价是内置浏览器的部分高级能力需要自行补齐或舍弃（见 known-limitations）。
+- 数据读取只用框架标准 hook（`useWorkspaces`/`useSessions`/`useStore`），动作经注册的 `inject` 闭包调用官方会话服务：`ctx.workspaces.startSession(workspaceId)`（复用/新建并打开该工作区会话）与 `ctx.sessions.open(id)`。
+- 归档集用框架 `defineStore` + `persist`（localStorage 裸 JSON，key `dsh.workspace-kit.archive.v1`），与内置视图偏好（如 `dsh.workspace.view.v5`）同一机制。
+- 全局快捷键无官方注册 API（全仓无 keyboard 服务），按内置插件惯例自挂 `window` keydown（⌘K/Ctrl+K），面板常驻挂载、关闭时渲染 null 以保活监听。
+- 宿主侧只做**只读**定位工具/命令：归档语义是视图层（浏览器）状态，宿主侧另存一份会导致与 GUI 不一致，故刻意不写。
+
+## 兼容性
+
+- 目标 dsh：`@deepseek-ai/dsh` v0.1.1-rc.2（`dsh web`，profile `web`）。浏览器 face 面向该版本的 `shell.overlay`/`IWorkspaces`/`ISessions` 契约；上游契约变更时需随版本校验。
+- 已知限制与后续方向见 [docs/known-limitations.zh-CN.md](./docs/known-limitations.zh-CN.md)（英文版 [docs/known-limitations.md](./docs/known-limitations.md)）。
+
+## License
+
+[MIT](./LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# dsh-workspace-kit — bundle layer
+#
+# One Loader entry per package (the dsh client module system rejects multiple
+# active sources resolving to one package name), so the single `workspace-kit`
+# entry carries host apply (tools + commands), and the same enabled entry's
+# `dsh.client` metadata makes the browser load the ./client face (archive UI
+# + Spotlight).
+- insert:
+    - id: workspace-kit
+      name: dsh-workspace-kit

package/docs/known-limitations.md

@@ -0,0 +1,32 @@
+# Known limitations & roadmap (dsh-workspace-kit)
+
+Based on a review of the official sources/docs (deepseek-ai/deepseek-harness @ master and the installed `@deepseek-ai/dsh` v0.1.1-rc.2), this is the current boundary of the plugin, why it exists, and the optional next steps. (简体中文版见 [known-limitations.zh-CN.md](./known-limitations.zh-CN.md)。)
+
+## Current limitations
+
+1. **The sidebar is replaced via shadow and the replacement browser is a v1 subset**
+   - The official model only has **session-level** archiving (`ctx.workspaceRegistry.archiveSession` → `archivedSessionIds`) with **no unarchive**, and **no workspace-level archive/hide verb**; the sidebar workspace browser occupies `sidebar.workspaces` (single slot) as a built-in, with no third-party per-row seam.
+   - Archive state lives in the browser (`defineStore` persist → localStorage `dsh.workspace-kit.archive.v1`). The sidebar **shadows `sidebar.workspaces` at priority -1** to replace the built-in browser so "archived" workspaces leave the main list into a collapsible section; Spotlight's idle list also hides them and shows an "Archived" marker when searching.
+   - The replacement browser re-implements: **new workspace** (the plus button next to search: system directory picker → register → open), **in-sidebar search** (expandable input filtering workspace titles/paths and session titles), workspace **rename / delete-registration** (confirmed; sessions return to ungrouped), session **archive** (official irreversible set, with confirmation), **drag reorder** (workspace rows → official `insertBefore`; sessions within their workspace → `insertSessionBefore`; after the first manual move the workspace keeps its manual/account order), **full-text session-content search** (≥2 chars, debounced, against the official host content index; hits listed under "session content hits"), **styled dialogs** (rename/delete/archive confirmations replace `prompt`/`confirm`), per-workspace **SVG icon + accent color** picker (browser-persisted), and a footer **enhanced/official sidebar toggle** (`sidebar.footer.action`; switching to the official sidebar unregisters the plugin occupant so the built-in browser at priority 0 renders again; the choice persists). The built-in browser's remaining advanced capabilities are not re-implemented.
+   - Hiding the sidebar *entirely* is out of reach for a third-party plugin: (a) shadow-rewriting the whole `sidebar.workspaces` (≈ rewriting the built-in browser) or (b) upstream adding `archiveWorkspace`/`unarchiveWorkspace` verbs plus row-level extension points to the workspace controller/registry — the recommended upstream direction.
+
+2. **The archive set is browser-local**
+   - Same mechanism as built-in view preferences (e.g. `dsh.workspace.view.v5`): no sync across browsers/devices; a fresh browser needs re-archiving.
+   - The host side deliberately keeps **no second copy**: two copies would drift, and there is no third-party custom RPC between host and client (the client can only consume build-time-generated `ctx.remote.*` namespaces).
+
+3. **Spotlight opening a workspace = the official "new session" flow**
+   - `ctx.workspaces.startSession(workspaceId)` reuses an available blank session or creates one and makes it current. If the directory was moved/deleted, behavior follows the official host (an error may surface in the list state).
+
+4. **Host tools are read-only and ignore browser archive state**
+   - `workspace_find` / `workspace_list` and `/workspace-find` / `/workspace-list` enumerate the official registry (all workspaces, without the browser's archive filter) for location purposes only; archive/restore write actions live only in the GUI (browser).
+
+5. **Theme & copy conventions**
+   - UI copy is now **bilingual (Simplified Chinese / English)** via the plugin's own locale module (browser: localStorage `dsh.workspace-kit.locale` → `navigator.language`; host: env `WSKIT_LOCALE` → `LC_ALL`/`LANG`; default English).
+   - Styles are still **inline styles** and do not follow the system light/dark theme. The upstream convention wants CSS-variable tokens + locale dictionaries checked inside the official repo; as an out-of-tree package this plugin is not wired into that build check.
+
+## Backlog (roadmap)
+
+- **Upstream-ize**: add `archiveWorkspace` / `unarchiveWorkspace` verbs to the workspace domain (host storageDomain persistence + follow deltas + UI row-level entry points); the plugin then becomes a thin shell.
+- **Cross-device archive sync** (host-side domain storage + custom remote verbs — needs upstream typert/generator support for out-of-tree remote protocols).
+- **Spotlight enhancements**: session-content search in the palette, recent items, `>` command mode, drag reorder, theme following.
+- **Upstream contract regression**: whenever `@deepseek-ai/dsh` moves to a new rc, re-validate the browser contract (`shell.overlay`, `IWorkspaces.startSession`, `ISessions.open`, `defineStore` persist) and update the plugin accordingly.

package/docs/known-limitations.zh-CN.md

@@ -0,0 +1,32 @@
+# 已知限制与后续方向（dsh-workspace-kit）
+
+基于对官方源码/文档（deepseek-ai/deepseek-harness @ master + 已安装 `@deepseek-ai/dsh` v0.1.1-rc.2）的核查，以下是本插件当前的边界、原因与后续可选方向。（English version: [known-limitations.md](./known-limitations.md)。）
+
+## 当前限制
+
+1. **侧栏通过 shadow 替换实现折叠，但替换式浏览器是 v1 子集**
+   - 官方模型：只有**会话级**归档（`ctx.workspaceRegistry.archiveSession` → `archivedSessionIds`），且**没有 unarchive**；**没有工作区级归档/隐藏**动词；侧栏 workspace 浏览器是 `sidebar.workspaces`（single 槽）被内置包独占，行级动作无第三方接缝。
+   - 归档状态存浏览器（`defineStore` persist → localStorage `dsh.workspace-kit.archive.v1`）。侧栏用 **priority -1 shadow `sidebar.workspaces`** 替换内置浏览器，实现「已归档 → 移出主列表、收进可折叠分区」；Spotlight 空闲列表同样不显示已归档，搜索时带标记出现。
+   - 替换式浏览器已补回：**新建工作区**（搜索旁的加号按钮：系统目录选择器 → 注册 → 打开）、**侧栏内搜索**（展开输入框，按工作区标题/路径与会话标题过滤）、工作区行 **重命名 / 删除注册**（确认后删除，会话回未归组）、会话行 **归档**（官方不可逆归档集，含确认）、**拖拽排序**（工作区行 → 官方 `insertBefore`；工作区内会话行 → `insertSessionBefore`；某工作区一旦手动拖过，其会话改按手动（账户）顺序展示）、**会话消息全文搜索**（≥2 字符防抖调官方 host 内容索引，结果分「会话内容命中」列出）、**内置风格对话框**（重命名/删除/归档确认统一走插件样式化弹窗）、每工作区 **SVG 图标 + 强调色** 选择器（浏览器持久化）、侧栏底部 **增强/官方侧栏一键切换**（`sidebar.footer.action`：切到官方侧栏即注销插件占用者，内置浏览器 priority 0 恢复渲染，选择持久化）。内置浏览器其余高级能力未补全。
+   - 想"连侧栏一起隐藏"只有两条路（超出第三方插件能力）：(a) shadow 重写整个 `sidebar.workspaces`（等于重写内置浏览器，工作量大）；(b) 上游在 workspace-controller/registry 增加 `archiveWorkspace`/`unarchiveWorkspace` 动词与行级扩展点——推荐上游化。
+
+2. **归档集是浏览器本地的**
+   - 与内置"视图偏好"（如 `dsh.workspace.view.v5`）同机制：多浏览器/多设备不同步；换浏览器需重新归档。
+   - 宿主侧刻意**不**保存第二份归档集：两侧各存一份必然漂移，而且没有第三方可用的 host 与 client 之间自定义 RPC（client 只能消费构建期生成的 `ctx.remote.*` 命名空间）。
+
+3. **Spotlight 打开工作区 = 官方"新建会话"流程**
+   - `ctx.workspaces.startSession(workspaceId)` 复用该工作区可用的 blank 会话或新建并置为当前。若目录已被移动/删除，行为以官方 host 为准（可能报错展示在列表状态）。
+
+4. **宿主侧工具只读且不含归档状态**
+   - `workspace_find` / `workspace_list` 与 `/workspace-find`、`/workspace-list` 枚举官方 registry 的全部工作区（不含浏览器归档过滤），只做定位；归档/恢复写动作只在 GUI（浏览器）里。
+
+5. **主题与文案**
+   - UI 文案现为**中英双语**（简体中文 / English），经插件自带 locale 模块实现（浏览器：localStorage `dsh.workspace-kit.locale` → `navigator.language`；宿主：env `WSKIT_LOCALE` → `LC_ALL`/`LANG`，默认英文）。
+   - 面板样式仍为**内联样式**，深/浅色模式未跟随系统主题。上游规范要求在仓库内用 CSS 变量 token + locale 字典（在官方仓库内由构建检查强制）；本插件作为 out-of-tree 包未接入该构建检查。
+
+## 后续方向（backlog）
+
+- **上游化**：为 workspace 域增加 `archiveWorkspace` / `unarchiveWorkspace`（host storageDomain 持久化 + follow 增量 + UI 行级入口），届时插件改为薄壳。
+- **跨端同步归档集**（host 侧 domain 存储 + 自定义远程动词——需要上游 typert/generator 支持 out-of-tree 远程协议）。
+- **Spotlight 增强**：面板内会话内容搜索、最近项目、`>` 命令模式、拖拽排序、主题跟随。
+- **上游契约回归**：`@deepseek-ai/dsh` 升级到新 rc 后，重新校验浏览器契约（`shell.overlay`、`IWorkspaces.startSession`、`ISessions.open`、`defineStore` persist）并同步更新插件。