dsh-scratch-workspace 0.1.3 → 0.1.4

package/README.md

@@ -22,7 +22,7 @@
 
 ---
 
-## 为什么需要它（面向什么问题）
+## 插件用途
 
 在 DeepSeek Harness 日常开发中，同时运行多个会话或使用默认工作区即兴提问时，开发者普遍面临以下三大核心痛点：
 
@@ -42,20 +42,34 @@
 
 ---
 
-## 用什么方法（架构与技术原理）
+## 效果一览
+
+- 🚀 **并行开发零干扰**：多个会话同时对同一项目执行重构、分析或测试，产物互不交叉。
+- 🛡️ **无感平滑升级**：不受 DSH 小版本架构调整影响，插件长久稳定运行。
+- 📂 **侧边栏清爽如初**：所有会话紧密附着于所属工作区，消除孤儿会话打扰。
+- 🧹 **磁盘常态零负担**：废弃临时目录自动清理，保持本地环境轻盈纯净。
+
+| 侧边栏原生聚合 (DSH 界面) | 物理沙箱隔离 (Finder 真实目录) |
+| :---: | :---: |
+| <img src="https://raw.githubusercontent.com/MDX-Tom/dsh-scratch-workspace/main/assets/02-sidebar-workspace-grouping.png" width="280" alt="侧边栏工作区归集效果" /> | <img src="https://raw.githubusercontent.com/MDX-Tom/dsh-scratch-workspace/main/assets/01-finder-isolated-folders.png" width="280" alt="Finder 目录隔离效果" /> |
+| **顶层统一归集**：会话在侧边栏完整归属母工作区，拒绝臃肿碎片化，保持工作区清爽 | **底层物理隔离**：每个会话分配专属 `session-<标题>-<ID>` 子目录，改名实时就地同步，产物互不踩踏 |
+
+| 交互式斜杠指令 (Slash Command) | ⭐ 即时状态看板与向导 (/scratch) |
+| :---: | :---: |
+| <img src="https://raw.githubusercontent.com/MDX-Tom/dsh-scratch-workspace/main/assets/03-slash-command-menu.png" width="240" alt="斜杠指令菜单" /><br/><br/><img src="https://raw.githubusercontent.com/MDX-Tom/dsh-scratch-workspace/main/assets/04-slash-command-args.png" width="240" alt="子命令提示" /> | <img src="https://raw.githubusercontent.com/MDX-Tom/dsh-scratch-workspace/main/assets/05-scratch-status-card.png" width="580" alt="即时状态看板" /> |
+| **开箱即用的指令交互**：输入 `/scratch` 自动补全，支持 `status`、`enable`、`disable` 与 `gc` | **状态一目了然（核心看板）**：清晰展示母工作区映射、会话沙箱物理路径与快捷运维向导 |
+
+---
+
+## 架构与技术原理
 
 ```mermaid
-flowchart TD
-    User["用户在工作区新建会话"] --> Controller["sessionController.create()"]
-    Controller --> Check{"检测是否为隔离工作区或默认工作区"}
+flowchart LR
+    Create["新建会话"] --> 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 守护：空闲回收 + 会话销毁即时释放"]
+    Check -- 是 --> Alloc["分配专属子沙箱<br/>session-xxx"]
+    Alloc --> Safe["微秒重定向 & 防冲突<br/>解绑 blank cwd"] --> Compat["双轨索引拦截<br/>挂靠母工作区"]
+    Compat --> Ready["沙箱安全写入<br/>侧边栏原生聚合"] -. 守护 .-> GC["常态生命周期 GC<br/>空闲清理 & 销毁即释"]
 ```
 
 ### 核心方法与实现机制
@@ -73,25 +87,24 @@ flowchart TD
 
 ---
 
-## 达到了什么效果
-
-- 🚀 **并行开发零干扰**：多个会话同时对同一项目执行重构、分析或测试，产物互不交叉。
-- 🛡️ **无感平滑升级**：不受 DSH 小版本架构调整影响，插件长久稳定运行。
-- 📂 **侧边栏清爽如初**：所有会话紧密附着于所属工作区，消除孤儿会话打扰。
-- 🧹 **磁盘常态零负担**：废弃临时目录自动清理，保持本地环境轻盈纯净。
+## 安装与使用
 
----
+### 方式一：从 npm 安装（推荐）
 
-## 安装与使用
+```bash
+dsh plugin add dsh-scratch-workspace
+# 或者通过 npm / pnpm
+pnpm add dsh-scratch-workspace
+```
 
-### 方式一：从本地安装（开发调试）
+### 方式二：从本地安装（开发调试）
 
 在 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"
+pnpm add "link:/path/to/dsh-scratch-workspace"
 
 # 2. 将 "dsh-scratch-workspace" 添加到 package.json 中的 dsh.profile.bundles 列表
 
@@ -108,16 +121,17 @@ dsh plugin --profile desktop add https://github.com/MDX-Tom/dsh-scratch-workspac
 
 ## 开启与控制隔离
 
-隔离状态以工作区目录内的 `.dsh-isolate` 标记文件作为持久化依据，设置随目录移动，也可在以下入口灵活控制：
+插件支持多种灵活的开启与控制方式：
 
-1. **对话内 Slash 命令**：
+1. **对话内 Slash 命令（推荐）**：
    在聊天输入框键入 `/scratch` 或 `/isolate` 即可调出交互命令，支持：
    - `/scratch status`：查看当前工作区隔离状态与草稿目录信息
-   - `/scratch enable`：为当前工作区开启沙箱隔离（写入 `.dsh-isolate`）
+   - `/scratch enable`：为当前工作区开启沙箱隔离（自动写入 `.dsh-isolate` 标记）
    - `/scratch disable`：关闭隔离
    - `/scratch gc`：立即执行磁盘垃圾清理，回收空闲与孤儿会话目录
-2. **默认工作区自动开启**：
-   默认工作区 (`default-workspace`) 自动享受沙箱隔离与草稿清理效果，无需任何手动配置。
+2. **目录标记文件 (`.dsh-isolate`) 与免配置自启**：
+   - **自定义工程/普通工作区**：在根目录下放置 `.dsh-isolate` 标记文件作为持久化依据，设置随目录与代码仓库移动。
+   - **默认工作区 (`default-workspace`)**：内置免配置自启，开箱即用，无需手动放置或生成标记文件。
 3. **Agent 智能调用 (LLM Tool)**：
    模型可自动调用 `session_isolation` 工具查看或切换隔离状态：
    - `action: "enable"`：为当前工作区开启隔离

package/index.js

@@ -58,8 +58,22 @@ async function apply(ctx) {
     await renameSessionDirToTitle(sessionId, title, iso, reg, ctx, session)
   })
 
-  const webServer = ctx.get('webServer', false)
-  const offRoutes = webServer === undefined ? undefined : registerWebRoutes(ctx, webServer, iso)
+  let offRoutes = undefined
+  const setupWeb = (ws) => {
+    if (ws && !offRoutes) {
+      offRoutes = registerWebRoutes(ctx, ws, iso)
+    }
+  }
+
+  const initialWs = ctx.get?.('webServer', false) ?? ctx.root?.get?.('webServer', false) ?? ctx.webServer
+  if (initialWs) {
+    setupWeb(initialWs)
+  } else if (typeof ctx.inject === 'function') {
+    ctx.inject(['webServer'], (innerCtx) => {
+      const ws = innerCtx.get?.('webServer', false) ?? innerCtx.webServer
+      setupWeb(ws)
+    })
+  }
 
   ctx.logger?.info?.(
     `dsh-scratch-workspace ready: ${iso.roots().length} isolating director${iso.roots().length === 1 ? 'y' : 'ies'}`,

package/lib/patch.js

@@ -24,6 +24,144 @@ import { cleanOrphans, isDirectoryEmpty, removeSessionDir, shortSessionId } from
 /** The registry-internal host property. */
 const HOST_PROPERTY = 'host'
 
+/**
+ * Resolves a session directory path to its actual existing on-disk location,
+ * reconciling title-based renames, cold restarts, and stale header cwds.
+ * @param {string} [targetPath] - candidate or stale path
+ * @param {object} [options]
+ * @param {string} [options.sessionId] - session ID if known
+ * @param {object} [options.iso] - isolation state
+ * @param {object} [options.ctx] - Cordis context
+ * @returns {Promise<string>} real on-disk directory or fallback targetPath
+ */
+export async function resolveSessionDir(targetPath, { sessionId, iso, ctx } = {}) {
+  // 1. If targetPath already exists on disk as a directory, it is valid
+  if (typeof targetPath === 'string' && targetPath !== '') {
+    try {
+      if ((await stat(targetPath)).isDirectory()) {
+        if (sessionId) iso?.recordSessionPath?.(sessionId, targetPath)
+        return targetPath
+      }
+    } catch {}
+  }
+
+  // 2. Check if isolation state has a recorded rewrite
+  if (typeof targetPath === 'string' && targetPath !== '') {
+    const rewritten = iso?.rewritePath?.(targetPath)
+    if (rewritten && rewritten !== targetPath) {
+      try {
+        if ((await stat(rewritten)).isDirectory()) {
+          if (sessionId) iso?.recordSessionPath?.(sessionId, rewritten)
+          return rewritten
+        }
+      } catch {}
+    }
+  }
+
+  // 3. If sessionId is provided, check if iso already knows its session path
+  if (sessionId) {
+    const current = iso?.sessionPath?.(sessionId)
+    if (current && current !== targetPath) {
+      try {
+        if ((await stat(current)).isDirectory()) {
+          if (targetPath) iso?.recordRename?.(targetPath, current)
+          return current
+        }
+      } catch {}
+    }
+  }
+
+  // 4. If sessionId is not provided, try to find sessionId from ctx.sessions or ctx.sessionQuery
+  let effectiveSessionId = sessionId
+  if (!effectiveSessionId && typeof targetPath === 'string' && targetPath !== '' && ctx) {
+    const sessionsService = typeof ctx.get === 'function' ? ctx.get('sessions', false) : ctx.sessions
+    if (typeof sessionsService?.list === 'function') {
+      try {
+        for (const s of sessionsService.list()) {
+          if (s?.header?.cwd === targetPath) {
+            effectiveSessionId = s.id
+            break
+          }
+        }
+      } catch {}
+    }
+
+    if (!effectiveSessionId) {
+      const query = typeof ctx.get === 'function' ? ctx.get('sessionQuery', false) : ctx.sessionQuery
+      if (typeof query?.listSessions === 'function') {
+        try {
+          const records = await query.listSessions()
+          for (const r of records) {
+            if (r?.header?.cwd === targetPath) {
+              effectiveSessionId = r.header.id
+              break
+            }
+          }
+        } catch {}
+      }
+    }
+  }
+
+  // 5. If effectiveSessionId is known, check workingDirectory service if available
+  if (effectiveSessionId && ctx) {
+    const wd = typeof ctx.get === 'function' ? ctx.get('workingDirectory', false) : ctx.workingDirectory
+    const sessionsService = typeof ctx.get === 'function' ? ctx.get('sessions', false) : ctx.sessions
+    const session = sessionsService?.get?.(effectiveSessionId)
+    if (session && typeof wd?.get === 'function') {
+      try {
+        const wdPath = wd.get(session)
+        if (wdPath && (await stat(wdPath)).isDirectory()) {
+          iso?.recordSessionPath?.(effectiveSessionId, wdPath)
+          if (targetPath && targetPath !== wdPath) iso?.recordRename?.(targetPath, wdPath)
+          return wdPath
+        }
+      } catch {}
+    }
+  }
+
+  // 6. Look for matching session directory on disk using candidate short IDs
+  const candidateShorts = new Set()
+  if (effectiveSessionId) {
+    candidateShorts.add(shortSessionId(effectiveSessionId))
+  }
+  if (typeof targetPath === 'string' && targetPath !== '') {
+    const b = basename(targetPath)
+    const match = b.match(SESSION_DIR_PATTERN)
+    if (match) {
+      const s = (match[2] ?? match[1] ?? '').split('-')[0].toLowerCase()
+      if (s) candidateShorts.add(s)
+    }
+  }
+
+  if (candidateShorts.size > 0) {
+    const roots = new Set(iso?.roots?.() ?? [])
+    if (typeof targetPath === 'string' && targetPath !== '') {
+      const parent = iso?.ownerOf?.(targetPath) ?? (await stat(targetPath).catch(() => null) ? null : resolve(join(targetPath, '..')))
+      if (parent) roots.add(parent)
+    }
+
+    for (const root of roots) {
+      try {
+        const entries = await readdir(root, { withFileTypes: true })
+        for (const entry of entries) {
+          if (!entry.isDirectory()) continue
+          const match = entry.name.match(SESSION_DIR_PATTERN)
+          if (!match) continue
+          const entryShort = (match[2] ?? match[1] ?? '').split('-')[0].toLowerCase()
+          if (candidateShorts.has(entryShort)) {
+            const foundDir = resolve(join(root, entry.name))
+            if (effectiveSessionId) iso?.recordSessionPath?.(effectiveSessionId, foundDir)
+            if (targetPath && targetPath !== foundDir) iso?.recordRename?.(targetPath, foundDir)
+            return foundDir
+          }
+        }
+      } catch {}
+    }
+  }
+
+  return targetPath
+}
+
 /**
  * Locate and remove a session's directory if it is empty.
  * Uses 3-tier lookup: in-memory iso state -> registry index -> isolating roots scan by shortId.
@@ -347,6 +485,65 @@ export function patchSessionCreate(ctx, iso) {
     }
   }
 
+  // Hook sessionController.list to project real on-disk session paths to frontend useSessions
+  const originalList = controller()?.list
+  if (typeof originalList === 'function') {
+    controller().list = async function list(request, signal) {
+      const res = await originalList.call(this, request, signal)
+      if (Array.isArray(res?.items)) {
+        for (const item of res.items) {
+          if (!item?.sessionId) continue
+          const resolved = await resolveSessionDir(item.cwd, {
+            sessionId: item.sessionId,
+            iso,
+            ctx,
+          })
+          if (resolved) {
+            item.cwd = resolved
+          }
+        }
+      }
+      return res
+    }
+  }
+
+  // Also hook controller().listState.list if present
+  const listState = controller()?.listState
+  const originalStateList = listState?.list
+  if (typeof originalStateList === 'function') {
+    listState.list = async function list(signal) {
+      const items = await originalStateList.call(this, signal)
+      if (Array.isArray(items)) {
+        for (const item of items) {
+          if (!item?.sessionId) continue
+          const resolved = await resolveSessionDir(item.cwd, {
+            sessionId: item.sessionId,
+            iso,
+            ctx,
+          })
+          if (resolved) {
+            item.cwd = resolved
+          }
+        }
+      }
+      return items
+    }
+  }
+
+  // Hook controller().openWorkspacePath to rewrite paths for file reveals/opens
+  const originalOpenWorkspacePath = controller()?.openWorkspacePath
+  if (typeof originalOpenWorkspacePath === 'function') {
+    controller().openWorkspacePath = async function openWorkspacePath(request, signal) {
+      if (request && typeof request.path === 'string') {
+        const resolved = await resolveSessionDir(request.path, { iso, ctx })
+        if (resolved && resolved !== request.path) {
+          request = { ...request, path: resolved }
+        }
+      }
+      return await originalOpenWorkspacePath.call(this, request, signal)
+    }
+  }
+
   // Hook workspaceController.archiveSession for frontend archive actions
   const wsCtrl = ctx.root?.workspaceController ?? ctx.workspaceController
   const originalWsArchive = wsCtrl?.archiveSession
@@ -365,6 +562,13 @@ export function patchSessionCreate(ctx, iso) {
     if (typeof originalRename === 'function') controller().rename = originalRename
     if (typeof originalDelete === 'function') controller().delete = originalDelete
     if (typeof originalWsArchive === 'function') wsCtrl.archiveSession = originalWsArchive
+    if (typeof originalList === 'function') controller().list = originalList
+    if (typeof originalStateList === 'function' && controller()?.listState) {
+      controller().listState.list = originalStateList
+    }
+    if (typeof originalOpenWorkspacePath === 'function') {
+      controller().openWorkspacePath = originalOpenWorkspacePath
+    }
   }
 }
 
@@ -481,7 +685,10 @@ export function patchWorkingDirectory(ctx, iso) {
  * @param {object} [sessionObj] - live session object if available
  */
 export async function renameSessionDirToTitle(sessionId, title, iso, registry, ctx, sessionObj) {
-  const currentDir = iso.sessionPath(sessionId)
+  let currentDir = iso.sessionPath(sessionId)
+  if (!currentDir) {
+    currentDir = await resolveSessionDir(undefined, { sessionId, iso, ctx })
+  }
   if (!currentDir) return
 
   const clean = sanitizeTitleForPath(title)

package/lib/web.js

@@ -3,6 +3,10 @@
  * @module dsh-scratch-workspace/lib/web
  */
 
+import { Readable } from 'node:stream'
+import { stat } from 'node:fs/promises'
+import { resolveSessionDir } from './patch.js'
+
 export const LIST_ROUTE = '/scratch-workspace/workspaces'
 export const TOGGLE_ROUTE = '/scratch-workspace/toggle'
 export const GC_ROUTE = '/scratch-workspace/gc'
@@ -11,6 +15,8 @@ export const GC_ROUTE = '/scratch-workspace/gc'
 export const LEGACY_LIST_ROUTE = '/session-isolation/workspaces'
 export const LEGACY_TOGGLE_ROUTE = '/session-isolation/toggle'
 
+export const OPEN_IN_APP_OPEN_PATH = '/open-in-app/open'
+
 const MAX_BODY_BYTES = 4096
 
 function json(res, status, body) {
@@ -110,7 +116,131 @@ export function registerWebRoutes(ctx, webServer, iso) {
   disposers.push(webServer.register({ kind: 'exact', path: LEGACY_LIST_ROUTE, handler: handleList }))
   disposers.push(webServer.register({ kind: 'exact', path: LEGACY_TOGGLE_ROUTE, handler: handleToggle }))
 
+  // Intercept open-in-app to rewrite stale or renamed session directories
+  disposers.push(interceptOpenInApp(webServer, iso, ctx))
+
   return () => {
     for (const d of disposers) d?.()
   }
 }
+
+function createFakeReq(originalReq, buffer) {
+  const fakeStream = Readable.from([buffer])
+  return new Proxy(originalReq, {
+    get(target, prop, receiver) {
+      if (
+        prop === Symbol.asyncIterator ||
+        prop === 'read' ||
+        prop === 'on' ||
+        prop === 'once' ||
+        prop === 'pipe' ||
+        prop === 'resume' ||
+        prop === 'pause'
+      ) {
+        const val = fakeStream[prop]
+        return typeof val === 'function' ? val.bind(fakeStream) : val
+      }
+      if (prop === 'headers') {
+        return {
+          ...target.headers,
+          'content-length': String(buffer.length),
+        }
+      }
+      const val = Reflect.get(target, prop, receiver)
+      return typeof val === 'function' ? val.bind(target) : val
+    },
+  })
+}
+
+export function interceptOpenInApp(webServer, iso, ctx) {
+  if (!webServer || typeof webServer.register !== 'function') return () => {}
+
+  const wrapHandler = (originalHandler) => {
+    if (typeof originalHandler !== 'function') return originalHandler
+    if (originalHandler.__dsh_scratch_wrapped) return originalHandler
+
+    const wrapped = async function openInAppHandler(req, res) {
+      if (req.method !== 'POST') {
+        return originalHandler(req, res)
+      }
+
+      const chunks = []
+      let size = 0
+      let tooLarge = false
+      try {
+        for await (const chunk of req) {
+          size += chunk.length
+          if (size > 65536) {
+            tooLarge = true
+            break
+          }
+          chunks.push(chunk)
+        }
+      } catch {}
+
+      const rawBuffer = Buffer.concat(chunks)
+      if (tooLarge) {
+        const fakeReq = createFakeReq(req, rawBuffer)
+        return originalHandler(fakeReq, res)
+      }
+
+      let body = null
+      try {
+        body = JSON.parse(rawBuffer.toString('utf8'))
+      } catch {}
+
+      if (!body || typeof body.path !== 'string') {
+        const fakeReq = createFakeReq(req, rawBuffer)
+        return originalHandler(fakeReq, res)
+      }
+
+      let isDir = false
+      try {
+        isDir = (await stat(body.path)).isDirectory()
+      } catch {
+        isDir = false
+      }
+
+      if (!isDir) {
+        const targetPath = await resolveSessionDir(body.path, { iso, ctx })
+        if (targetPath && targetPath !== body.path) {
+          body.path = targetPath
+          const newBuffer = Buffer.from(JSON.stringify(body), 'utf8')
+          const fakeReq = createFakeReq(req, newBuffer)
+          return originalHandler(fakeReq, res)
+        }
+      }
+
+      const fakeReq = createFakeReq(req, rawBuffer)
+      return originalHandler(fakeReq, res)
+    }
+
+    wrapped.__dsh_scratch_wrapped = true
+    wrapped.__dsh_scratch_original = originalHandler
+    return wrapped
+  }
+
+  // 1. If /open-in-app/open is already registered in webServer.exact
+  const existingRoute = webServer.exact?.get(OPEN_IN_APP_OPEN_PATH)
+  let originalExactHandler = undefined
+  if (existingRoute && typeof existingRoute.handler === 'function') {
+    originalExactHandler = existingRoute.handler
+    existingRoute.handler = wrapHandler(existingRoute.handler)
+  }
+
+  // 2. Wrap webServer.register to catch future /open-in-app/open registrations
+  const originalRegister = webServer.register.bind(webServer)
+  webServer.register = function (route) {
+    if (route?.kind === 'exact' && route?.path === OPEN_IN_APP_OPEN_PATH && typeof route.handler === 'function') {
+      route.handler = wrapHandler(route.handler)
+    }
+    return originalRegister(route)
+  }
+
+  return () => {
+    webServer.register = originalRegister
+    if (existingRoute && originalExactHandler) {
+      existingRoute.handler = originalExactHandler
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-scratch-workspace",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "DeepSeek Harness 瞬态会话隔离与草稿清理插件 — 顺应官方原生工作区规范的会话沙箱隔离、侧边栏归集与磁盘生命周期自动清理",
   "author": "Mi Tom <6468993+MDX-Tom@users.noreply.github.com>",
   "license": "MIT",