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 配置，适合需要精细控制工作流环境的技术团队。