前言¶

DeepSeek Harness（DSH）采用“一切皆插件”的架构。对于仍依赖旧版 Claude Code 或 Codex 生态的插件，直接集成往往存在兼容性问题。@rvaim/dsh-compat 提供了一个兼容层，将这些旧插件作为完整的生命周期单元接入 DSH，使其能像管理原生插件一样被整体管理、运行和更新。

核心功能¶

Source 与 Plugin 分离管理¶

插件区分两个概念：Source 负责获取和缓存内容（Git 仓库、本地目录或压缩包），Plugin 负责运行时行为。一个 Source 可包含一个或多个 Plugin。

支持的来源与格式¶

支持 Git URL、github: 简写、本地目录以及 ZIP/TAR/TGZ 归档。
支持 Claude Code、Codex Marketplace 及混合 Marketplace。无 Marketplace 时识别根目录中的单插件。

生命周期操作¶

支持一次原子安装一个或多个 Plugin。提供整体启用、禁用、更新、检查和卸载功能。安装失败时不会提交变更。

能力适配¶

支持 Skill、MCP（stdio 与 streamable-http 接入）、Hook（包含参数边界、事件映射、超时控制）、Command、Agent 等能力的发现与适配。

安装¶

通过 npm 安装到指定 profile：

dsh plugin --profile web add @rvaim/dsh-compat@latest

首次安装或升级后，需要重启 profile 并重新加载 Web 页面，因为 DSH 的 Host/Client 插件图发生了变化。

使用¶

Web 界面管理¶

启动 profile 后，在 DSH Web 设置中打开“兼容插件”。点击“添加”输入来源（Git URL、本地路径或归档）。单插件来源直接安装，多插件来源显示复选列表，确认后从同一快照安装。

使用开关在线启用或停用插件，使用刷新按钮检查更新。卸载操作会移除插件。

API 调用¶

其他插件可以声明 inject: ['compat']，然后通过 ctx.compat 调用服务 API 执行操作，例如：
- ctx.compat.sourceAdd(source, options?)
- ctx.compat.sourceRemove(sourceId)
- ctx.compat.sourceUpdate(sourceId, options?)
- ctx.compat.sourceList()
- ctx.compat.sourceInspect(sourceId)
- ctx.compat.prepareInstall(source, options?)
- ctx.compat.install(sourceOrSourceId, options?)
- ctx.compat.checkUpdates()
- ctx.compat.update(pluginId, options?)
- ctx.compat.enable(pluginId)
- ctx.compat.disable(pluginId)
- ctx.compat.uninstall(pluginId)
- ctx.compat.list()
- ctx.compat.inspect(pluginId)

架构与数据¶

转换流程¶

来源解析器将 Git/归档解析为 Source，Plugin 解析器将 Source 中的内容解析为具体的 Skill/MCP/Hook，最后由 CompatPlugin 适配到 DSH 的运行时。

存储布局¶

数据存储在 $DSH_HOME/dsh-compat/ 下，分为 sources（缓存源内容）和 installed（管理插件状态）。

安全模型¶

安装阶段不执行构建脚本，Git 不创建工作树，仅进行读取和解析。归档检查路径穿越、符号链接等风险。敏感配置使用引用而非明文写入。

适用场景与注意¶

适合需要统一管理旧版 Claude Code/Codex 插件的工作流开发者。使用时需注意：插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。不执行构建脚本和 Command/Agent。

总结¶

@rvaim/dsh-compat 通过分离 Source 与 Plugin 模型，为旧版插件提供了标准化的接入方式，并提供了完整的生命周期管理。