使用

在用 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。

AI Agent：使用仓库内置 Skill

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

安装

需要 Node.js ^22.22.3 或 >=24.11.1，以及 @deepseek-ai/dsh@0.1.0-rc.8。

npm install -g @deepseek-ai/dsh@0.1.0-rc.8
npm install -g dsh-harmony
dsh web

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

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

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 之间。保存时，Harmony 会检查列表是否恰好包含每个已注册 Patch 一次。

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

插件冲突

任何 DSH 插件包都可以在 dsh.plugin.conflicts 中声明不兼容的插件版本，无论它是否提供 Harmony Patch：

{
  "dsh": {
    "plugin": {
      "conflicts": {
        "legacy-plugin": "*",
        "@vendor/other-plugin": "<2.0.0"
      }
    }
  }
}

当匹配的插件包同时启用时，Harmony 会发出警告，但不会停用或阻止任何一方。单方声明即可生效；双方重复声明只产生一条警告；停用 Harmony Patch 不等于停用其所属插件。冲突目标使用包名，值使用 semver 范围。

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 · 限制 · 故障排查

开发

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

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

npm test

许可证

MIT