dsh-harmony | DeepSeek Harness 插件

<h1>dsh-harmony</h1>

<p> <strong>DeepSeek Harness 插件的运行时 Patch 协调层。</strong> <br /> 一个用于在运行时修补、替换和装饰 DeepSeek Harness 插件的库。 </p>

简体中文 / English </div>

使用

在用 Vibe Coding 开发 DSH 插件时，只需输入 *“如果使用 dsh-harmony 呢”*。

简介

当一个 DeepSeek Harness 插件需要修改另一个插件、又不值得为此维护 Fork 时，可以使用 Harmony。它会在目标插件运行前加载 Patch，在内存中修改编译产物，再让 Harness 运行修改后的代码。

Source Patch 使用 TSQuery 查找 TypeScript AST 节点，再用 MagicString 改写对应的源码区间。Patch 逐个执行，后一个会读取前一个留下的结果，因此多个插件可以修改同一目标。安装目录里的文件不会改变。

Provider 可以声明自己的 Patch 应排在另一个 Provider 之前或之后；单个 Patch 也可以改用自己的规则。用户还能把不同 Provider 的 Patch 交错排列。若几处修改必须一起成功，可以把它们放进组合 Patch：它们共用一个位置和开关，任何成员失败时都不应用。

对于浏览器插件，Harmony 还会按 Patch 顺序整理 Provider 所属的 <style data-plugin> 标签。每个 Provider 只有一组样式，它在 CSS 层叠中的位置由最后一个启用的 Patch 决定。Patch 重载后，Harmony 会再整理一次。

Harmony 为 DeepSeek Harness 插件之间的协作补上了修改能力。

演示视频 on Bilibili

【Harmony 框架: 让你的 DeepSeek Harness 插件可以运行时修改、替换和装饰其它插件】

为什么使用 Harmony

目标已经暴露所需能力时，普通 DSH 扩展点仍然是首选。Harmony 解决的是公开 API 与维护 Fork 之间的空白：修改目标没有暴露的内部组件、Loader 条目或编译后行为。

不使用 Harmony	使用 Harmony
隐藏或复制内部 UI，并长期同步两套实现	在原位置替换选中的组件或编译后调用点
修改 `node_modules`、维护 Fork，或升级后重新应用改动	只在内存中变换源码；已安装文件逐字节保持不变
选择器漂移后由 UI 静默失效暴露问题	钉死目标版本和 `expect`；失配会在 `status` 中明确失败
把最终 Bundle 当作黑盒	检查原始源码、每一步 Patch 和最终变换结果
手动清理定制改动	禁用或移除 Provider 即恢复原始行为

Harmony 不会把编译内部变成稳定的公开 API；它让这项依赖变得明确、有序、可检查且可逆。

Respect

灵感来源于 Andreas Pardeike 和其它开发者创作的同名 C# 项目 Harmony。

<details> <summary><strong>AI Agent：使用仓库内置 Skill</strong></summary>

安装、选择和编写 Patch、执行运行时操作或排查问题前，请加载 use-dsh-harmony。

</details>

安装

需要 Node.js ^22.22.3 或 >=24.11.1，并支持 @deepseek-ai/dsh@0.1.0-rc.8 或 @deepseek-ai/dsh@0.1.1-rc.1。

npm install -g @deepseek-ai/dsh@0.1.1-rc.1
npm install -g dsh-harmony
dsh web

启动 WebUI 后打开 设置 → Harmony。Profile、Desktop 集成、更新和卸载说明参见安装指南。

终端 TUI 和非交互命令可操作任意 profile。命令会事务连接正在运行的 Host 并报告 live；已停止的 profile 则在本地校验后原子更新并报告 offline。

同一 profile 可以由多个 Host 使用。Harmony 沿用 DSH Settings 的写入模型：整份配置通过文件锁串行并原子提交；陈旧界面的保存会被拒绝并刷新，跨进程并发写则以后完成的完整配置为准。

dsh harmony --profile web
dsh harmony status --json --profile web
dsh harmony disable my-provider/optional-patch --profile web
dsh harmony enable-provider my-provider --profile web
dsh harmony patch-order show --profile web
dsh harmony patch-order move my-provider/optional-patch --before other-provider/base --profile web
dsh harmony patch-order auto --profile web
dsh harmony provider-order move my-provider --after base-provider --profile web
dsh harmony inspect target-package --patch my-provider/optional-patch --summary --profile web
dsh harmony reload my-provider --profile web

在 TUI 中按 Tab 可切换 Provider 和 Patch 视图。Patch 视图支持单项及整组启停、Patch 排序、自动排序、运行状态和简要检查；profile 大于终端窗口时，两个视图都会保持选中项可见。

健康状态或顺序约束失败时，status、patch-order show 和 provider-order show 都以状态码 1 退出。patch-order auto 与 provider-order auto 会尽量保留当前相对顺序，同时把约束冲突降到最少。inspect --summary 不输出变换源码，--patch <key> 只保留指定 Patch 触及的目标。reload 只能用于正在运行的 Host。

Patch 模型

Harmony 按一份全局 patchOrder 运行所有 Patch。Provider 级 before / after 负责通常的先后关系；单个 Patch 只要声明其中一项，就改用自己的规则。在 设置 → Harmony 中，用户可以移动整个 Provider，也可以把一个 Patch 插到另一个 Provider 的两个 Patch 之间。插件与 Patch 详情提供启停操作，Patch 状态页则是只读的运行时监视器。保存时，Harmony 会检查列表是否恰好包含每个已注册 Patch 一次。

插件级停用使用独立的 provider/* 标志，不会清除或创建单个 Patch 的停用标志。因此重新启用插件时，只会恢复此前本就单独启用的 Patch。

每个 Patch 都可以声明便于阅读的 description。Harmony 会在 Patch 状态和 JSON 输出中公开它，并在设置界面中显示，让用户在调整顺序或启停之前了解该 Patch 的作用。

组合 Patch 让多个 Patch 共用一个排序位置和开关。成员按声明顺序执行，而且只有全部成功才会应用。独立 Patch 失败时，Harmony 会报告并跳过它；后续 Patch 和 Host 仍会运行。

插件兼容性

任何 DSH 插件包都可以在 dsh.plugin.compatibility 中描述它与其它插件的关系，无论它是否提供 Harmony Patch：

{
  "dsh": {
    "plugin": {
      "compatibility": {
        "requires": {
          "base-plugin": "^2.0.0"
        },
        "conflicts": {
          "legacy-plugin": "*"
        },
        "integrates": {
          "optional-renderer": "^1.0.0"
        }
      }
    }
  }
}

requires 报告缺失、未启用或版本不匹配的依赖，conflicts 警告同时启用的不兼容组合，integrates 报告当前可用的可选联动。声明只用于检测和展示，不会安装、启用、停用或阻止插件。目标使用包名，值使用 semver 范围；双方重复声明冲突时只产生一条警告。停用 Harmony Patch 不等于停用其所属插件。

实时报告使用 Loader 中实际启用的插件。配置停止运行时，Harmony 只能检查安装情况，因此会把配置中已安装的包视为已启用。

React-aware Patch

修改编译后的 React 目标时，在 Patch Provider 中安装 dsh-harmony-react：

npm install dsh-harmony-react

element() 修改选中的 jsx / jsxs 调用点，component() 修改这些调用共享的组件定义。它们和其它 Source Patch 使用同一份顺序。

API	作用范围
`element()`	一个或多个调用点：替换、包裹、插入、变换 Props 或移除
`component()`	所有通过已初始化变量或具名函数声明进行的调用：装饰或替换

为了让后续 Component Patch 继续修改同一定义，Harmony 会把函数声明改写为已初始化的 const。新绑定不再提升；如果文件在声明前读取组件，请改用核心 Source Patch。React 集成还介绍了选择器、Inspect trace 和 Studio。

文档

主题	指南
运行时架构	Harmony 是什么？
安装与 profile	安装
编写源码、语义、加载器与组合 Patch	Patch 编写指南
Provider/Patch 排序、状态、检查和重载	运行操作
使用 `dsh-harmony-react` 编写 React Patch	React 集成
Studio 预览	Studio 集成
命令、限制与故障	CLI · 限制 · 故障排查

Powered by Harmony

如果你的插件使用 Harmony，欢迎使用这枚徽章来表达支持！

![Powered by Harmony](https://memorax-ai.github.io/dsh-harmony/)

[![Powered by Harmony](https://memorax-ai.github.io/dsh-harmony/harmony-powered.svg)](https://memorax-ai.github.io/dsh-harmony/)

开发

所有维护中的实现源码均使用 TypeScript。用于发布的编译产物由构建生成，不纳入 Git 跟踪。

文档源码与本地预览工具位于 docs 分支。

npm test

启动 DSH 时设置 DSH_HARMONY_PERF=1，可让 Harmony 为每次启动、插件更新、配置更新和手动重载输出一条结构化耗时记录：

DSH_HARMONY_PERF=1 dsh web --no-open

记录分别包含 Patch 准备、源码变换、Host 重载、浏览器重建和总耗时。探针默认不工作，不会给正常加载路径增加计时开销。Node.js 诊断工具也可以直接订阅 diagnostics_channel 的 dsh-harmony:load 通道，而不打开日志输出。

许可证

[MIT](LICENSE)

来源信息

安装

检查来源文件

使用

简介

演示视频 on Bilibili

为什么使用 Harmony

安装

Patch 模型

插件兼容性

React-aware Patch

文档

Powered by Harmony

开发

许可证

更多相关插件

dsh-patchouli

dsh-base

dsh-headless