dsh-scratch-workspace 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek Harness Community
+
+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

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+<h1 align="center">📦 dsh-scratch-workspace</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  DeepSeek Harness (DSH) 会话级沙箱隔离与草稿常态洁净插件
+</p>
+
+<p align="center">
+  <img alt="DSH Plugin" src="https://img.shields.io/badge/DSH-Plugin-4c6ef5?style=flat-square" />
+  <img alt="Node.js 22+" src="https://img.shields.io/badge/Node.js-22%2B-339933?style=flat-square&logo=node.js&logoColor=white" />
+  <img alt="Cordis" src="https://img.shields.io/badge/Cordis-Ready-blueviolet?style=flat-square" />
+  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/License-MIT-yellow?style=flat-square" /></a>
+</p>
+
+<p align="center">
+  <strong>简体中文</strong> · <a href="README_EN.md">English</a>
+</p>
+
+> [!IMPORTANT]
+> **本插件顺应 DSH 原生架构规范，以永久兼容设计解决即兴会话文件踩踏、侧边栏混乱与磁盘残留痛点。**
+>
+> 既保持会话与项目在侧边栏的优雅归集，又为每个即兴会话提供独立的写入沙箱与自动垃圾回收（GC），杜绝版本断层风险。
+
+---
+
+## 为什么需要它（面向什么问题）
+
+在 DeepSeek Harness 日常开发中，同时运行多个会话或使用默认工作区即兴提问时，开发者普遍面临以下三大核心痛点：
+
+1. **文件相互踩踏**：原生机制下所有会话共享同一个工作区目录，并行运行的 Agent 会互相覆盖对方产出的代码或临时脚本。
+2. **版本断层红屏**：传统补丁方案（如 `dsh-session-isolation`）强依赖旧版内部私有函数 `sessionPath`，在 DSH 升级到 `0.2.x` 后直接抛错崩溃。
+3. **磁盘垃圾持续蔓延**：即兴会话产生的废弃文件与临时产物长期滞留，缺乏生命周期回收机制。
+
+### 方案对比
+
+| 评估维度 | 原生 DSH 默认机制 | 传统猴子补丁 (`dsh-session-isolation`) | dsh-scratch-workspace (本插件) |
+| :--- | :--- | :--- | :--- |
+| **会话写隔离** | 共享工作区根目录，易互相踩踏 | 独立 `session-<id>` 子沙箱 | **独立 `session-<id>` 子沙箱，项目只读安全** |
+| **DSH 版本兼容** | 官方原生 | 强依赖 `sessionPath`，0.2.x 升级即红屏 | **永久兼容：自适应 `candidateMatches` 与 `sessionPath`，防认领冲突** |
+| **侧边栏整洁** | 堆叠在单一工作区 | 易因校验失效退化为 Ungrouped 孤儿项 | **常态整洁：会话严格归集于母工作区树下** |
+| **磁盘生命周期** | 无清理机制，废弃文件永久堆积 | 无有效 GC，废弃目录长期滞留 | **双重 GC：销毁即时释放 + 孤儿与空闲自动回收** |
+| **即兴提问体验** | 污染 `default-workspace` | 需手动放置 `.dsh-isolate` 标记 | **默认工作区自动隔离，即用即走** |
+
+---
+
+## 用什么方法（架构与技术原理）
+
+```mermaid
+flowchart TD
+    User["用户在工作区新建会话"] --> Controller["sessionController.create()"]
+    Controller --> Check{"检测是否为隔离工作区或默认工作区"}
+    Check -- 否 --> Native["原生创建流程"]
+    Check -- 是 --> Alloc["分配专属 session-<id> 沙箱子目录"]
+    Alloc --> SafeClaim["安全消除 blank 会话 cwd 认领冲突"]
+    SafeClaim --> TempRedirect["微秒级重定向 workspace.path & record"]
+    TempRedirect --> Attach["session 与 workspace 建立原生归集"]
+    Attach --> CompatIndex["兼容层索引拦截 (candidateMatches / sessionPath)"]
+    CompatIndex --> Ready["会话就绪：文件写入局限于子沙箱，侧边栏归属母工程"]
+    Ready --> GC["常态 GC 守护：空闲回收 + 会话销毁即时释放"]
+```
+
+### 核心方法与实现机制
+
+1. **物理级写沙箱与项目只读保护**：
+   在隔离工作区中为新会话动态创建 `session-<shortId>` 子目录，并重定向会话的写入边界。所有文件写入均收敛于该子目录，项目既有代码和文件对会话只读可用。
+2. **双轨版本自适应（永久兼容）**：
+   - 适配 DSH `0.2.x+`：包裹 `candidateMatches(id, path)`，将沙箱路径映射至母工作区。
+   - 兼容 DSH `0.1.x`：保留对 `sessionPath(id)` 与 `rememberSessionPath(id, path)` 的安全适配。
+   - 彻底防范 `ApiSessionCwdConflict`：当客户端复用带有历史根路径的空白会话时，自动解除路径认领绑定，平滑分配新会话标识。
+3. **磁盘常态化垃圾回收引擎 (Lifecycle GC)**：
+   - **实时释放**：监听会话删除事件，实时删除对应的沙箱目录。
+   - **空闲回收**：对创建后超过 5 分钟且无实际文件产出的空沙箱进行静默清理。
+   - **TTL 孤儿扫描**：后台每 30 分钟轮巡检测已无活动会话对应且超过 24 小时的孤儿目录。
+
+---
+
+## 达到了什么效果
+
+- 🚀 **并行开发零干扰**：多个会话同时对同一项目执行重构、分析或测试，产物互不交叉。
+- 🛡️ **无感平滑升级**：不受 DSH 小版本架构调整影响，插件长久稳定运行。
+- 📂 **侧边栏清爽如初**：所有会话紧密附着于所属工作区，消除孤儿会话打扰。
+- 🧹 **磁盘常态零负担**：废弃临时目录自动清理，保持本地环境轻盈纯净。
+
+---
+
+## 安装与使用
+
+### 方式一：从本地安装（开发调试）
+
+在 DeepSeek Harness 所在配置 Profile 中添加本插件依赖（例如 `~/.dsh/profiles/desktop`）：
+
+```bash
+# 1. 链接到你的 DSH Profile
+cd ~/.dsh/profiles/desktop
+pnpm add "link:/Users/midaxia/Documents/Projects/Codex Projects/dsh-plugins/dsh-scratch-workspace"
+
+# 2. 将 "dsh-scratch-workspace" 添加到 package.json 中的 dsh.profile.bundles 列表
+
+# 3. 重启 DeepSeek Harness
+```
+
+### 方式二：通过 Git URL 安装
+
+```bash
+dsh plugin --profile desktop add https://github.com/MDX-Tom/dsh-scratch-workspace.git
+```
+
+---
+
+## 开启与控制隔离
+
+隔离状态以工作区目录内的 `.dsh-isolate` 标记文件作为持久化依据，设置随目录移动，也可在以下入口灵活控制：
+
+1. **对话内 Slash 命令**：
+   在聊天输入框键入 `/scratch` 或 `/isolate` 即可调出交互命令，支持：
+   - `/scratch status`：查看当前工作区隔离状态与草稿目录信息
+   - `/scratch enable`：为当前工作区开启沙箱隔离（写入 `.dsh-isolate`）
+   - `/scratch disable`：关闭隔离
+   - `/scratch gc`：立即执行磁盘垃圾清理，回收空闲与孤儿会话目录
+2. **默认工作区自动开启**：
+   默认工作区 (`default-workspace`) 自动享受沙箱隔离与草稿清理效果，无需任何手动配置。
+3. **Agent 智能调用 (LLM Tool)**：
+   模型可自动调用 `session_isolation` 工具查看或切换隔离状态：
+   - `action: "enable"`：为当前工作区开启隔离
+   - `action: "disable"`：关闭隔离
+   - `action: "status"`：查看当前目录隔离状态
+   - `action: "gc"`：立即执行磁盘垃圾清理
+4. **插件详情与配置说明**：
+   在 DSH 侧边栏点击 **「插件」** → 选择 **dsh-scratch-workspace** 即可查看插件行为与自动清理机制摘要。
+
+---
+
+## 运行自动化测试
+
+本插件内置轻量单元测试，完全基于 Node.js 原生 test runner：
+
+```bash
+cd "dsh-scratch-workspace"
+node --test "tests/*.test.js"
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh-scratch-workspace bundle patch
+- insert:
+    - id: scratch-workspace
+      name: dsh-scratch-workspace

package/docs/DETAIL.zh.md

@@ -0,0 +1,29 @@
+### 插件行为与核心机制
+
+**dsh-scratch-workspace** 为 DeepSeek Harness (DSH) 提供会话级沙箱隔离与草稿常态洁净能力：
+
+- **子沙箱写隔离**：在已开启隔离的工作区（或默认工作区）中，每个新会话均在专属的 `session-<id>` 子目录中工作。该子目录自动作为会话的文件写入边界，杜绝并行任务相互覆盖代码或测试文件；母工作区文件对所有会话只读可用。
+- **侧边栏常态归集**：会话在侧边栏中始终整洁归属于母工作区，不产生未分组孤儿项。
+- **永久兼容架构**：无缝适配 DSH `0.1.x` 与 `0.2.x+` 的实体宿主索引机制（同时支持 `candidateMatches` 与 `sessionPath`），并平滑处理空白会话认领冲突，杜绝红屏崩溃。
+
+---
+
+### 磁盘自动清理机制 (Lifecycle GC)
+
+插件内置常态化垃圾回收引擎，杜绝磁盘废弃文件堆积：
+
+1. **会话销毁即时清理**：会话归档或删除时，即时释放其绑定的沙箱子目录。
+2. **空闲废弃目录回收**：自动识别超过 5 分钟且无实际产物的空会话目录并静默清理。
+3. **TTL 孤儿目录扫描**：启动与运行中（每 30 分钟）自动轮巡工作区，安全回收已不存在对应会话且超过 24 小时的孤儿目录。
+4. **一键手动触发**：可在对话框中键入 `/scratch gc` 或通过 `session_isolation` 工具随时手动触发即时清理。
+
+---
+
+### 快捷指令支持 (Slash Commands)
+
+在任意会话输入框键入 `/` 即可调出本插件命令：
+- `/scratch status` (或 `/isolate`)：查看当前工作区隔离状态与沙箱目录。
+- `/scratch enable`：为当前工作区启用隔离（创建 `.dsh-isolate`）。
+- `/scratch disable`：关闭当前工作区隔离。
+- `/scratch gc`：立即回收空闲与孤儿草稿目录。
+

package/index.js

@@ -0,0 +1,87 @@
+/**
+ * dsh-scratch-workspace — Ephemeral Scratch Workspace & Session Isolation for DeepSeek Harness (DSH).
+ *
+ * Provides:
+ * 1. Per-session sandbox working directory (session-<id>) within parent workspaces.
+ * 2. Permanent multi-version compatibility across DSH 0.1.x and 0.2.x+.
+ * 3. Sidebar cleanliness with automatic session grouping under parent workspaces.
+ * 4. Disk cleanliness with automatic lifecycle GC for empty and orphan directories.
+ * @module dsh-scratch-workspace
+ */
+
+import { createIsolationState } from './lib/state.js'
+import {
+  isolatedSessionsApi,
+  patchFs,
+  patchRegistry,
+  patchSessionCreate,
+  patchWorkingDirectory,
+  renameSessionDirToTitle,
+} from './lib/patch.js'
+import { isMeaningfulTitle } from './lib/isolate.js'
+import { setupAutoGc } from './lib/gc.js'
+import { registerIsolationTool } from './lib/tool.js'
+import { registerCommands } from './lib/command.js'
+import { registerWebRoutes } from './lib/web.js'
+
+export const inject = ['sessionController', 'workspaceRegistry', 'tools', 'commands', 'sessions', 'workingDirectory', 'fs']
+
+async function apply(ctx) {
+  const iso = createIsolationState(ctx)
+
+  const unpatchRegistry = patchRegistry(ctx.root?.workspaceRegistry ?? ctx.workspaceRegistry, iso)
+  const unpatchCreate = patchSessionCreate(ctx, iso)
+  const unpatchWorkingDirectory = patchWorkingDirectory(ctx, iso)
+  const unpatchFs = patchFs(ctx, iso)
+
+  const api = isolatedSessionsApi(ctx, iso)
+  const provideIsolation = ctx.provide('isolatedSessions', api)
+  const provideScratch = ctx.provide('scratchWorkspace', api)
+
+  const unregisterTool = registerIsolationTool(ctx, iso)
+  const unregisterCommands = registerCommands(ctx, iso, api)
+  const stopGc = setupAutoGc(ctx, iso)
+
+  await iso.scan()
+  const stopWatching = ctx.on('domain/changed', (change) => {
+    if (change?.domain !== 'workspace') return
+    void iso.scan().catch(() => {})
+  })
+
+  const stopTitleEvents = ctx.on('session/event', async (session, event) => {
+    if (event?.type !== 'session/title') return
+    const title = event?.data?.title
+    if (!isMeaningfulTitle(title)) return
+    const sessionId = session?.id
+    if (!sessionId) return
+    const reg = ctx.root?.workspaceRegistry ?? ctx.workspaceRegistry
+    await renameSessionDirToTitle(sessionId, title, iso, reg, ctx, session)
+  })
+
+  const webServer = ctx.get('webServer', false)
+  const offRoutes = webServer === undefined ? undefined : registerWebRoutes(ctx, webServer, iso)
+
+  ctx.logger?.info?.(
+    `dsh-scratch-workspace ready: ${iso.roots().length} isolating director${iso.roots().length === 1 ? 'y' : 'ies'}`,
+  )
+
+  ctx.effect(() => () => {
+    offRoutes?.()
+    stopTitleEvents?.()
+    stopWatching()
+    stopGc()
+    unregisterCommands()
+    unregisterTool()
+    provideScratch()
+    provideIsolation()
+    unpatchFs()
+    unpatchWorkingDirectory()
+    unpatchCreate()
+    unpatchRegistry()
+    iso.clear()
+  }, 'dsh-scratch-workspace.patches')
+}
+
+apply.inject = inject
+
+export default apply

package/lib/client.js

@@ -0,0 +1,256 @@
+/**
+ * Browser UI for DSH Settings → Plugins: Workspace Isolation & Disk GC.
+ */
+window.__ModuleLoader__.load({
+  id: 'dsh-scratch-workspace',
+  factory: (require) => {
+    const module = { exports: {} }
+    const exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+
+    const React = require('react')
+    const { useEffect, useState } = React
+
+    const LIST_ROUTE = '/scratch-workspace/workspaces'
+    const TOGGLE_ROUTE = '/scratch-workspace/toggle'
+    const GC_ROUTE = '/scratch-workspace/gc'
+
+    const TEXT = {
+      tab: '工作区隔离与清理',
+      title: '工作区隔离与磁盘清理',
+      intro: '开启隔离后，每个新会话均在独立的 session-<id> 子沙箱中运行，隔离写权限，避免并行会话相互覆盖；'
+        + '项目文件对所有会话完全只读可用。插件内置常态 GC 引擎，自动回收空闲与孤儿会话目录，保持磁盘整洁。',
+      empty: '当前没有已注册的工作区。请先在侧边栏打开项目目录。',
+      loading: '读取中…',
+      retry: '重试',
+      on: '已开启',
+      off: '未开启',
+      enable: '开启隔离',
+      disable: '关闭隔离',
+      sessions: '会话',
+      isolatedCount: (count) => `已开启隔离的工作区：${count}`,
+      runGc: '立即清理磁盘孤儿目录',
+      gcRunning: '正在清理…',
+      gcDone: (count) => `清理完成：已回收 ${count} 个孤儿/废弃目录`,
+      failed: (message) => `操作失败：${message}`,
+      unavailable: '宿主未响应接口，请确认插件已加载。',
+    }
+
+    async function fetchState() {
+      const response = await fetch(LIST_ROUTE, { headers: { accept: 'application/json' } })
+      if (!response.ok) throw new Error(`${response.status} ${response.statusText}`)
+      return await response.json()
+    }
+
+    async function toggle(workspaceId, enabled) {
+      const response = await fetch(TOGGLE_ROUTE, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json' },
+        body: JSON.stringify({ workspaceId, enabled }),
+      })
+      const payload = await response.json().catch(() => ({}))
+      if (!response.ok) throw new Error(payload?.error ?? `${response.status} ${response.statusText}`)
+      return payload
+    }
+
+    async function triggerGc() {
+      const response = await fetch(GC_ROUTE, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json' },
+      })
+      const payload = await response.json().catch(() => ({}))
+      if (!response.ok) throw new Error(payload?.error ?? `${response.status} ${response.statusText}`)
+      return payload
+    }
+
+    const styles = {
+      root: { padding: '4px 0 24px', color: 'var(--dsw-alias-label-primary)', fontSize: 13, lineHeight: 1.6 },
+      title: { margin: '0 0 6px', fontSize: 14, fontWeight: 600 },
+      intro: { margin: '0 0 16px', color: 'var(--dsw-alias-label-secondary)', fontSize: 12 },
+      toolbar: {
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        margin: '0 0 12px',
+        padding: '8px 12px',
+        background: 'var(--dsw-alias-bg-layer-2)',
+        borderRadius: 8,
+      },
+      summary: { color: 'var(--dsw-alias-label-tertiary)', fontSize: 12 },
+      row: {
+        display: 'flex',
+        alignItems: 'center',
+        gap: 12,
+        padding: '10px 0',
+        borderTop: '0.5px solid var(--dsw-alias-border-l2)',
+      },
+      main: { minWidth: 0, flex: 1 },
+      name: { fontWeight: 500 },
+      path: {
+        color: 'var(--dsw-alias-label-tertiary)',
+        fontSize: 12,
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+        whiteSpace: 'nowrap',
+      },
+      state: { flex: 'none', color: 'var(--dsw-alias-label-secondary)', fontSize: 12, minWidth: 48, textAlign: 'right' },
+      button: {
+        flex: 'none',
+        font: 'inherit',
+        fontSize: 12,
+        cursor: 'pointer',
+        color: 'var(--dsw-alias-label-primary)',
+        background: 'var(--dsw-alias-bg-layer-3)',
+        border: '0.5px solid var(--dsw-alias-border-l4)',
+        borderRadius: 8,
+        padding: '5px 12px',
+      },
+      gcButton: {
+        font: 'inherit',
+        fontSize: 12,
+        cursor: 'pointer',
+        color: 'var(--dsw-alias-label-primary)',
+        background: 'var(--dsw-alias-bg-layer-3)',
+        border: '0.5px solid var(--dsw-alias-border-l4)',
+        borderRadius: 6,
+        padding: '4px 10px',
+      },
+      buttonBusy: { opacity: 0.6, cursor: 'default' },
+      notice: { color: 'var(--dsw-alias-state-success-primary, #10b981)', fontSize: 12, margin: '8px 0 0' },
+      error: { color: 'var(--dsw-alias-state-error-primary)', fontSize: 12, margin: '8px 0 0' },
+      empty: { color: 'var(--dsw-alias-label-tertiary)', fontSize: 12 },
+    }
+
+    function ScratchWorkspacePage() {
+      const [state, setState] = useState(undefined)
+      const [error, setError] = useState(undefined)
+      const [notice, setNotice] = useState(undefined)
+      const [busyId, setBusyId] = useState(undefined)
+      const [gcBusy, setGcBusy] = useState(false)
+
+      const load = () => {
+        fetchState().then(
+          (next) => { setState(next); setError(undefined) },
+          (cause) => { setError(cause?.message ?? String(cause)) },
+        )
+      }
+
+      useEffect(() => {
+        load()
+        const timer = setInterval(load, 5000)
+        return () => clearInterval(timer)
+      }, [])
+
+      const apply = async (workspaceId, enabled) => {
+        setBusyId(workspaceId)
+        try {
+          setState(await toggle(workspaceId, enabled))
+          setError(undefined)
+        } catch (cause) {
+          setError(cause?.message ?? String(cause))
+          load()
+        } finally {
+          setBusyId(undefined)
+        }
+      }
+
+      const handleGc = async () => {
+        setGcBusy(true)
+        setNotice(undefined)
+        try {
+          const res = await triggerGc()
+          setNotice(TEXT.gcDone(res.cleanedCount ?? 0))
+          setError(undefined)
+        } catch (cause) {
+          setError(cause?.message ?? String(cause))
+        } finally {
+          setGcBusy(false)
+        }
+      }
+
+      const workspaces = state?.workspaces ?? []
+
+      return React.createElement(
+        'div',
+        { style: styles.root },
+        React.createElement('h3', { style: styles.title }, TEXT.title),
+        React.createElement('p', { style: styles.intro }, TEXT.intro),
+        React.createElement(
+          'div',
+          { style: styles.toolbar },
+          React.createElement(
+            'span',
+            { style: styles.summary },
+            state ? TEXT.isolatedCount(state.isolatedCount ?? 0) : TEXT.loading,
+          ),
+          React.createElement(
+            'button',
+            {
+              type: 'button',
+              style: gcBusy ? { ...styles.gcButton, ...styles.buttonBusy } : styles.gcButton,
+              disabled: gcBusy,
+              onClick: handleGc,
+            },
+            gcBusy ? TEXT.gcRunning : TEXT.runGc,
+          ),
+        ),
+        notice ? React.createElement('p', { style: styles.notice }, notice) : null,
+        error ? React.createElement(
+          'p',
+          { style: styles.error },
+          TEXT.failed(error),
+          React.createElement('button', {
+            type: 'button',
+            style: { ...styles.button, marginLeft: 8 },
+            onClick: load,
+          }, TEXT.retry),
+        ) : null,
+        state !== undefined && workspaces.length === 0
+          ? React.createElement('p', { style: styles.empty }, TEXT.empty)
+          : null,
+        workspaces.map((workspace) => React.createElement(
+          'div',
+          { key: workspace.workspaceId, style: styles.row },
+          React.createElement(
+            'div',
+            { style: styles.main },
+            React.createElement('div', { style: styles.name }, workspace.title),
+            React.createElement('div', { style: styles.path, title: workspace.path }, workspace.path),
+          ),
+          React.createElement(
+            'span',
+            { style: styles.state },
+            `${TEXT.sessions} ${workspace.sessionCount} · ${workspace.isolates ? TEXT.on : TEXT.off}`,
+          ),
+          React.createElement(
+            'button',
+            {
+              type: 'button',
+              style: busyId === workspace.workspaceId
+                ? { ...styles.button, ...styles.buttonBusy }
+                : styles.button,
+              disabled: busyId === workspace.workspaceId,
+              onClick: () => { void apply(workspace.workspaceId, !workspace.isolates) },
+            },
+            workspace.isolates ? TEXT.disable : TEXT.enable,
+          ),
+        )),
+      )
+    }
+
+    const inject = ['slots']
+
+    function apply(ctx) {
+      ctx.slots.inject('settings.plugins.tab', () => ctx.slots.register({
+        name: 'settings.plugins.tab',
+        id: 'scratch-workspace',
+        order: 90,
+        label: TEXT.tab,
+      }, ScratchWorkspacePage))
+    }
+
+    exports.apply = apply
+    exports.inject = inject
+    return module.exports
+  },
+})

package/lib/command.js

@@ -0,0 +1,110 @@
+/**
+ * Slash commands for DeepSeek Harness (DSH) chat composer:
+ * - /scratch [status|enable|disable|gc]
+ * - /isolate [status|enable|disable|gc]
+ * @module dsh-scratch-workspace/lib/command
+ */
+
+/**
+ * Register human-facing slash commands for the chat input box.
+ * @param ctx - Cordis context.
+ * @param iso - shared isolation state.
+ * @param api - public isolation API.
+ * @returns disposer removing command registrations.
+ */
+export function registerCommands(ctx, iso, api) {
+  const commands = ctx.get('commands', false)
+  if (!commands || typeof commands.register !== 'function') {
+    return () => {}
+  }
+
+  const handler = async (invocation) => {
+    const rawInput = invocation.rawInput?.trim() ?? ''
+    const args = rawInput.split(/\s+/).filter(Boolean)
+    const action = args[0]?.toLowerCase() ?? 'status'
+
+    const session = invocation.agent?.session
+    const sessionCwd = session?.header?.cwd
+    const sessionId = session?.id
+
+    const parentRoot = sessionCwd
+      ? (iso.ownerOf(sessionCwd) ?? sessionCwd)
+      : (iso.roots()[0] ?? iso.defaultPath?.())
+
+    if (action === 'status') {
+      const isIso = parentRoot ? (iso.workspaceRoot(parentRoot) !== undefined || iso.roots().includes(parentRoot)) : false
+      const sessionPath = sessionId ? (iso.sessionPath(sessionId) ?? sessionCwd) : sessionCwd
+      const lines = [
+        `📁 **工作区隔离状态**`,
+        `- **母工作区**: \`${parentRoot ?? '未知'}\``,
+        `- **隔离状态**: ${isIso ? '✅ 已开启' : '⚪ 未开启'}`,
+        `- **当前会话沙箱**: \`${sessionPath ?? '继承工作区'}\``,
+        `- **已隔离工作区数**: ${iso.roots().length}`,
+        ``,
+        `💡 **可用操作**:`,
+        `- \`/scratch enable\`：开启当前工作区隔离`,
+        `- \`/scratch disable\`：关闭当前工作区隔离`,
+        `- \`/scratch gc\`：立即清理磁盘废弃与孤儿草稿目录`,
+      ]
+      return { kind: 'success', text: lines.join('\n') }
+    }
+
+    if (action === 'enable') {
+      if (!parentRoot) {
+        return { kind: 'error', text: '无法识别当前会话所属工作区，请在工作区内执行。' }
+      }
+      await api.setIsolatedPath(parentRoot, true)
+      return {
+        kind: 'success',
+        text: `✅ 已为工作区开启会话隔离：\`${parentRoot}\`\n后续新建会话将自动运行于专属 \`session-<id>\` 沙箱目录中。`,
+      }
+    }
+
+    if (action === 'disable') {
+      if (!parentRoot) {
+        return { kind: 'error', text: '无法识别当前会话所属工作区，请在工作区内执行。' }
+      }
+      await api.setIsolatedPath(parentRoot, false)
+      return {
+        kind: 'success',
+        text: `⚪ 已关闭工作区会话隔离：\`${parentRoot}\`。`,
+      }
+    }
+
+    if (action === 'gc') {
+      const result = await api.cleanOrphans()
+      const cleanedCount = result?.cleanedCount ?? (Array.isArray(result) ? result.length : 0)
+      const scannedCount = result?.scannedCount ?? cleanedCount
+      return {
+        kind: 'success',
+        text: `🧹 **磁盘常态清理完成**\n- 扫描项目/目录: ${scannedCount} 个\n- 已回收废弃/孤儿目录: ${cleanedCount} 个\n- 磁盘状态: 常态洁净`,
+      }
+    }
+
+    return {
+      kind: 'error',
+      text: `未知参数: \`${action}\`。\n可用参数: \`status\` | \`enable\` | \`disable\` | \`gc\``,
+    }
+  }
+
+  const unregScratch = commands.register({
+    definitionId: 'dsh-scratch-workspace:scratch',
+    name: 'scratch',
+    description: '瞬态草稿工作区管理：查看隔离状态、切换隔离或清理磁盘垃圾',
+    input: { hint: 'status | enable | disable | gc' },
+    handler,
+  })
+
+  const unregIsolate = commands.register({
+    definitionId: 'dsh-scratch-workspace:isolate',
+    name: 'isolate',
+    description: '查看或切换当前工作区会话隔离状态',
+    input: { hint: 'status | enable | disable | gc' },
+    handler,
+  })
+
+  return () => {
+    unregScratch?.()
+    unregIsolate?.()
+  }
+}