dsh-harmony

<div align="center">

<a href="https://memorax-ai.github.io/dsh-harmony/zh/">

<img width="132" alt="Harmony" src="assets/harmony-icon.png">

</a>

<h1>dsh-harmony</h1>

<p>

<strong>DeepSeek Harness 插件的运行时 Patch 协调层。</strong>

<br />

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

</p>

<p>

<a href="https://memorax-ai.github.io/dsh-harmony/zh/guide/installation"><strong>开始使用</strong></a>

·

<a href="https://memorax-ai.github.io/dsh-harmony/zh/">文档</a>

·

<a href="https://github.com/memorax-ai/dsh-harmony/issues">报告问题</a>

</p>

<p>

<a href="LICENSE"><img alt="许可证：MIT" src="https://img.shields.io/badge/license-MIT-0b63f6.svg"></a>

<a href="package.json"><img alt="Node.js" src="https://img.shields.io/badge/node-%5E22.15.0%20%7C%7C%20%3E%3D23.5.0-2f6f3e.svg"></a>

<a href="https://www.npmjs.com/package/dsh-harmony"><img alt="npm 版本" src="https://img.shields.io/npm/v/dsh-harmony.svg?style=flat&amp;color=0b63f6"></a>

<a href="https://github.com/memorax-ai/dsh-harmony/stargazers"><img alt="GitHub Stars" src="https://img.shields.io/github/stars/memorax-ai/dsh-harmony?style=flat&amp;color=0b63f6"></a>

<a href="https://awesome-dsh-plugin.com"><img alt="Awesome DSH Plugin" src="https://awesome-dsh-plugin.com/badge.svg"></a>

<a href="https://memorax-ai.github.io/dsh-harmony/"><img alt="Harmony" src="https://memorax-ai.github.io/dsh-harmony/harmony-powered.svg"></a>

</p>

[简体中文](README.zh-CN.md) / [English](README.md)

</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 会把每个新 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。

<!-- AGENTS: Before installing, authoring, reviewing, or debugging Harmony Patches, read the main-branch skill at https://github.com/memorax-ai/dsh-harmony/blob/main/.agents/skills/use-dsh-harmony/SKILL.md. -->

<details>

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

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

</details>

安装

需要 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 触

…(truncated)