dsh-workspace-overlay

English version: docs/README.en.md

DSH 树外插件：为每个 canonical workspace 路径提供共享的 Cordis scope（workspaceCordis service）。同一 workspace 的所有消费者（session、agent）租用同一个 scope；最后一个租约释放时 scope 被 dispose。可选地，首个租约会把 /.dsh/cordis.yml 挂载为该 workspace 的 Cordis composition；bundle 同时接线 Agent 集成：ctx.agents.create/resume 前置 workspace 绑定，官方 agentPresets 的 mount/composeFrom/recompose 被 decorator 接管为 workspace-local preset generation（见下文「Agent 集成」）。./mcp 子路径提供从官方 rc.6 @deepseek-ai/dsh-mcp-client 移植的 MCP core（transport / tool sync / connection supervisor），以及 workspace-aware MCP manager + 插件入口（global 每 serverName 一进程、workspace override 每 workspace 一进程、继承 global 的 workspace 零额外进程、同名 namespace 整体遮蔽，见「MCP manager」）。

目标 DSH：0.1.0-rc.6。运行时peer包括@deepseek-ai/cordis 4.0.1、@deepseek-ai/dsh-scope 0.1.0-rc.6、@deepseek-ai/cordis-plugin-include 1.0.6、@deepseek-ai/cordis-plugin-loader 1.0.2、@deepseek-ai/dsh-agent-presets 0.1.0-rc.6及代码实际import的DSH service包；版本均与安装版一致。@deepseek-ai/dsh-mcp-client 0.1.0-rc.6只作为开发依赖用于Config parity测试。

API（./registry）

• WorkspaceRegistry extends Service：默认导出；注册为 ctx.workspaceCordis（避免与 DSH Web 的持久 workspace 实体服务 ctx.workspaceRegistry 冲突）。static inject = ['loader']：provider 只在 Host Loader 存在时激活，workspace scope 继承 Host base，供裸包 specifier 解析。
• Config：trustWorkspaceConfig: boolean，默认 true（是否信任 /.dsh/cordis.yml）。
• acquire(cwd)：cwd 必须为绝对路径且指向已存在目录；canonical 为 realpath(resolve(cwd))（symlink 归一）。同一 canonical 通过 Map + single-flight 共享一个 entry；并发 acquire 只挂载一次；失败不残留缓存、可重试。
• 首次创建 entry 时：/.dsh/cordis.yml 不存在 → 空 workspace scope（继承 global，不启动任何东西）；存在且 trustWorkspaceConfig → 挂载 composition，acquire 在全部 row 可用后才返回；存在但 trust=false → 只 stat 不读／parse／import，仍建立空 scope。
• lease：key（不透明 ScopeKey）、（scope-owned context）、、、、（，仅已挂载时存在）； 幂等，最后一次 release 并从 Map 删除——composition 子树由 scope 持有，随 scope dispose 完整清理（含 fixture 的 effect disposer）。