DeepSeek Harness 插件：dsh-workspace-overlay

前言¶

在 DSH（DeepSeek Harness）的單進程模型下，管理多個 workspace 的配置隔離與動態更新通常需要重啓宿主或複雜的腳本介入。dsh-workspace-overlay 插件通過引入 workspace 級別的 Scope、Composition 熱重載以及 workspace-aware MCP 管理器，解決了多環境配置共享與動態變更的問題。

插件介紹¶

這是一個樹外（Out-of-tree）DSH bundle，由 TTTPOB 維護，遵循 MIT 許可證。它旨在爲每個 canonical workspace 路徑提供共享的 Cordis scope 服務（workspaceCordis），支持 workspace composition 的掛載與熱重載，並提供了 Agent 集成和基於 workspace 的 MCP 管理功能。

核心功能¶

該插件主要包含以下能力：

共享 Workspace Scope：爲每個 canonical workspace 路徑提供共享的 Cordis scope（workspaceCordis service）。同一 workspace 的所有消費者（session、agent）租用同一個 scope；最後一個租約釋放時 scope 被 dispose。
Composition 熱重載：支持 workspace-scoped Cordis composition 掛載與熱重載。首個租約會將 <workspace>/.dsh/cordis.yml 掛載爲該 workspace 的 composition，並在默認開啓監聽的情況下，編輯保存即觸發整樹熱重載。
Agent 集成：提供 Agent 集成，接管官方 agentPresets 的 mount/composeFrom/recompose 爲 workspace-local preset generation。
Workspace-aware MCP：提供 workspace-aware MCP manager，支持 global/serverName/workspace 級別的進程控制與同名 namespace 遮蔽。同時移植了官方 rc.6 MCP core（transport/tool sync/connection supervisor）。
依賴管理：運行時依賴 DSH service 包 0.1.5-rc.2、Cordis 4.0.2、Include 1.0.7、Loader 1.0.3。

安裝與啓用¶

安裝該插件需要使用 dsh plugin 命令配合 profile。安裝後，通過 dsh --dump-config 可以查看注入的配置項。

dsh plugin --profile web add https://github.com/TTTPOB/dsh-workspace-overlay/releases/download/v0.1.1/dsh-workspace-overlay-0.1.1.tgz
dsh --profile web --dump-config

安裝後，插件會在 dsh.bundle.patch 中插入三行配置：workspace-registry、workspace-mcp-manager 和 workspace-agent-integration。

典型用法¶

配置信任與監聽：在安裝並啓用插件後，插件會默認將 trustWorkspaceConfig 和 watchWorkspaceConfig 設置爲 true。這意味着 <workspace>/.dsh/cordis.yml 會被信任並掛載。
編寫 Workspace MCP：在 workspace 的 .dsh/cordis.yml 中編寫 MCP 行配置。
熱重載控制：如果需要調整熱重載的行爲，可以顯式配置 reloadDebounceMs（默認 150ms）。如果不想監聽文件變化，可以將 watchWorkspaceConfig 設爲 false。

注意事項與限制¶

使用該插件時，請注意以下限制和依賴：

不監聽特定文件：插件不 watch preset agent.cordis.yml，也不 watch 被 composition import 的 JS/package 模塊。修改這些文件需要手動 touch 或重新保存頂層 cordis.yml 來觸發重載。
不中斷工具調用：插件不 drain 任意 in-flight 的第三方工具調用。第三方工具的 pending 生命週期會一直保留，直到其自然結束。
失敗策略：插件不做 blue-green 部署，失敗後不保留上一好樹。這與 DSH 全局 patch HMR 的運行模型一致。
不支持 Provider HMR：插件自身的 structural provider（如 workspace-agent-integration）不支持 live HMR。開發時需要先 dispose 全部 live Agent 或重啓 Host。
RC 兼容性：RC 兼容範圍按 package.json 聲明，不自動承諾跨 RC 基線兼容。
權限與來源：該插件以當前 DSH 進程權限運行，安裝前建議檢查源碼與許可證。

總結¶

dsh-workspace-overlay 爲 DSH 提供了一套完整的 workspace 隔離與動態配置方案。通過 workspaceCordis scope 和熱重載機制，開發者可以在不重啓宿主的情況下管理多 workspace 的 Agent 和 MCP 配置，適合需要精細控制工作流環境的技術團隊。