运行时补丁协调 memorax-ai/dsh-harmony

dsh-harmony

DeepSeek Harness 插件的运行时 Patch 协调层。

一个用于在运行时修补、替换和装饰 DeepSeek Harness 插件的库。

开始使用

文档

报告问题

简体中文 / English

使用

在用 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 所属的 标签。每个 Provider 只有一组样式，它在 CSS 层叠中的位置由最后一个启用的 Patch 决定。Patch 重载后，Harmony 会再整理一次。

Harmony 会把每个新 session 与创建它时“已启用 Patch 的有序 profile”绑定，并记录 Provider 版本与 Patch 内容指纹。绑定保存在 DSH 共享数据根的 harmony-sessions.json 中，不改动 DSH session 文件。Web 加载已记录的 session 前会先比较绑定状态与当前 profile；如果存在缺失、新增、实现变化或换序，会显示警告，并允许不加载、返回原来的 session。

Harmony 还会在 $DSH_HOME/harmony-instance.json 中记录上一次启动共享 DSH 实例的有序 Patch profile。每次启动都会先把当前配置与这份数据侧记录比较；若不一致，会写入日志并在 Web 中显示一次警告，然后才把记录推进到本次运行配置。因此切换 profile 或修改 Patch 后，第一次开始接触同一 DSH_HOME 下共享的 session、附件、workspace 元数据和其他 storage 时会明确提示。

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.15.0 或 >=23.5.0，以及当前版本的 @deepseek-ai/dsh。Harmony 同时支持旧版导入即执行的入口和新版 runCli() 入口，并在发现 profile 时规范化 Windows 命名空间路径。旧版集成区间仍限定在 0.1.2 之前，新版区间覆盖 >=0.1.2-alpha.4 <0.1.8-0 和 >=0.2.0-rc.1 <0.2.1-0。区间内可直接兼容的版本不会仅因版本号变化而要求升级 Harmony。区间外仍会尝试应用，并通过版本漂移警告和精确匹配检查报告结果，不阻止安装；上游接口或补丁目标发生变化时，再升级 Harmony 获取对应适配。

回归基线为 0.1.1-rc.2。隔离上游检查覆盖 0.1.2-rc.1、0.1.5-rc.2、0.1.6-alpha.2、0.1.7-rc.2 和 0.2.0-rc.1，验证 Web 启动、5 个内置补丁无版本警告地绑定、在线 CLI 状态，以及客户端补丁禁用/启用时的热重载。构建后，将 DSH_HARMONY_DSH_ENTRY 指向隔离安装的 @deepseek-ai/dsh/lib/bin.js，即可运行 npm run test:upstream。该检查不覆盖浏览器交互或模型对话。

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

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

设置 → 插件 → 插件配置 → Harmony → 多线程装载 用于控制 Patch 预检并行度。默认值为 1，完整保留原来的单线程执行模型。提高线程数后，互不依赖的源码 Patch 文件连通分量会在 worker 线程中并行执行；触及同一文件的所有 Patch，以及跨文件的组合 Patch，仍会留在同一分量内按顺序运行。语义 Patch 分量继续在主线程执行。worker 中的模块状态和全局状态彼此隔离，并且每个 worker 都会增加内存开销。

终端 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 不等于停用其所属插件。

如果一个插件必须激活另一个 Harmony Provider 的 bundle，请在 dsh.harmony.requires 中声明。Harmony 会从声明方包的位置解析依赖，将其 bundle 作为临时启动层加入；如果该 bundle 已经在 profile 中配置，则直接复用，不会创建重复的 Loader entry。依赖包本身仍须由包管理器安装。

{
"dsh": {
"harmony": {
"requires": {
"the-binding-of-dsh": ">=0.1.3 <0.2.0"
}
}
}
}

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

加载协调

Harmony 会在每个 Patch generation 中索引最终变换后的模块图。浏览器模块顺序会包含 Patch 新增的 import 和 require()，Host 重载则跟随 Node.js 实际解析到的模块边，并在同一事务中重载受影响的依赖方。

已经注入 Harmony 服务的插件可以检查当前 generation，而不必自行控制 Loader 生命周期：

export const inject = ['harmony']

export function apply(ctx) {
const plan = ctx.harmony.loadPlan()
// 包、Patch 目标、变换后模块和已观察到的 Loader entry }

loadPlan() 是已提交 generation 的诊断数据。静态分析得到的 inject 与 provide 只描述可能的模块关系；已观察到的 Entry 记录包含 Cordis 报告的准确运行时元数据，实际激活状态仍以 Cordis Fiber 为准。

Provider 发现目前跟随组合后的 profile 包图。因此，被 Loader 配置禁用的 Provider Entry——包括 disabled: !!js ... 表达式结果为真的情况——仍可能贡献 Harmony Patch。需要让 Patch 激活服从明确运行时设置时，请使用 Harmony 自身的 Provider 或 Patch 开关。

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

Powered by 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