一句话定位

这是 dsh-harmony 仓库 .impeccable/fixtures/ 目录下的内部测试夹具 stack-gamma，自带 7 个空实现的 Harmony Patch，用来演示和验证"长卡片堆"场景下的 Patch 顺序与堆叠规则，并非给终端用户使用的功能插件。

核心能力

• 声明一个名为 dsh-harmony-motion-gamma 的私有 bundle 插件，向宿主注入自身（inject: [harmony]）
• 在 patches.cjs 中输出 7 个 Patch ID：gamma-brand、gamma-history、gamma-library、gamma-shortcuts、gamma-settings、gamma-updates、gamma-profile
• 所有 Patch 锁定同一个目标 @deepseek-ai/dsh-client-ui-sidebar 的 lib/client.js，选择器为 SourceFile，期望匹配数为 1
• 通过空的 apply() {} 显式声明"不修改源码"，仅作为顺序与堆叠的占位
• 归类为 plugin-development（插件开发工具类）展示条目

技术实现

• 语言: CommonJS（index.cjs / patches.cjs）
• 关键依赖: 无运行时依赖；仅依赖 dsh-harmony 的 Patch 协议（dsh.bundle.patch + dsh.harmony.patches）
• 架构模式: 双层声明——harmony.patch.yml 负责 bundle 注入，patches.cjs 负责 Patch 元数据；所有 Patch 共用同一个 target，依靠顺序而非覆盖来测试 Patch 链
• 入口文件: index.cjs（仅导出 inject: ['harmony'] 与空 apply）

适用场景

适合想直观看到"一个插件挂 7 个 Patch、共用同一目标文件"的开发者用于排版展示或手工演练 Patch 顺序；不适用于想要真实改动 DeepSeek Harness 侧边栏行为的场景——若需要实际修改，请改用 dsh-harmony 自身的官方文档和示例。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:memorax-ai/dsh-harmony/.impeccable/fixtures/stack-gamma

配置项

本插件无需额外配置——patches.cjs 中所有 7 个 Patch 均为固定的 target / select / expect 三元组，apply() 为空函数，不读取任何外部配置。

常见问题

Q: 这个插件能用来做什么？

A: 它在源码层面不产生任何实际行为，所有 7 个 Patch 的 apply 函数都是空操作。它的定位是 dsh-harmony 项目内部的测试夹具，主要用于手工验证 Patch 顺序、堆叠和启用规则的展示效果。

Q: 它为什么是 private？

A: 因为它不是面向终端用户发布的插件，而是 dsh-harmony 仓库的内部测试素材。package.json 中 private: true 且 version: 0.0.0，作者字段是 Harmony Fixture Team。

Q: 它针对的目标文件是什么？

A: 7 个 Patch 全部针对同一个目标：包 @deepseek-ai/dsh-client-ui-sidebar，文件 lib/client.js，select 为 SourceFile，expect 为 1。

Q: 仓库里还有类似的夹具吗？

A: 同级的 .impeccable/fixtures/ 目录还有 stack-alpha（3 个 Patch）和 stack-beta（5 个 Patch），三者共同构成"卡片堆顺序"测试夹具组。

Q: 安装后是否需要额外配置？

A: 不需要。它的 patches.cjs 没有读取任何配置，也没有暴露 Schema。安装后 7 个 Patch 全部处于"已声明但不做任何事"的状态。

Q: 这个夹具被 dsh-harmony 自身的测试代码引用了吗？

A: 在仓库的 src/ 与 test/ 下未发现对 .impeccable/ 路径的引用，hook.e2e.ts 等用例使用的是 test/fixtures/ 下的另一组夹具；该 stack-* 夹具目前在源码中没有自动化消费者。

上手难度

入门 — 文件只有 4 个、合计 39 行、没有任何运行时逻辑；阅读门槛只在理解 Harmony 的 Patch 元数据协议。

已知问题与限制

• package.json 标注 private: true、version: 0.0.0，明确表示不应作为正式插件分发；安装命令本身可执行，但语义上属于内部测试素材
• 所有 Patch 的 apply 为空函数，安装到任意 profile 都不会改变宿主行为
• 仓库的 src/ 与 test/ 未引用 .impeccable/ 路径，说明该夹具目前未被自动化测试覆盖，与 stack-alpha / stack-beta 同处"声明但未消费"状态
• 全部 Patch 共用同一目标文件与相同 select: 'SourceFile'、expect: 1，若宿主侧边栏文件不存在或版本不匹配，将按 Harmony 规则进入失败状态而非无感跳过

Usage

Just type "What about we use dsh-harmony" when vibe coding your DSH plugin.

Introduction

Use Harmony when one DeepSeek Harness plugin needs to change another without maintaining a fork. Harmony loads Patches before the target runs, changes its compiled code in memory, and starts Harness with the result.

Source Patches find TypeScript AST nodes with TSQuery and rewrite their source ranges with MagicString. They run one after another, each reading the source left by the previous Patch. This lets several plugins change the same target while leaving installed files untouched.

A provider can place its Patches before or after another provider. One Patch may override that rule, and users may interleave Patches from different providers. When several changes must succeed together, a composite Patch gives them one position and one switch; if a member fails, Harmony applies none of them.

For browser plugins, Harmony also keeps provider-owned <style data-plugin> tags in Patch order. A provider owns one style group, so its last enabled Patch decides where that group appears in the CSS cascade. Harmony repeats the ordering after a Patch reload.

Harmony adds modification to the ways DeepSeek Harness plugins can work together.

Why Harmony

Ordinary DSH extension points remain the first choice when the target exposes the behavior you need. Harmony is for the gap between those APIs and maintaining a fork: changing an internal component, loader entry, or compiled behavior that the target does not expose.

Harmony does not turn compiled internals into a stable public API. It makes that dependency explicit, ordered, inspectable, and reversible.

Respect

Inspired by Harmony, the project of the same name created by Andreas Pardeike and other contributors for C#.

AI agents: use the repository skill

Load use-dsh-harmony for installation, Patch selection and authoring, runtime operations, and troubleshooting.

Install

Requires Node.js ^22.22.3 or >=24.11.1 and @deepseek-ai/[email protected].

npm install -g @deepseek-ai/[email protected]
npm install -g dsh-harmony
dsh web

Open Settings → Harmony after starting the WebUI. For profiles, Desktop integration, updates, and removal, see the installation guide.

Use the terminal UI or non-interactive commands against any profile. Commands contact a running Host transactionally and report live; stopped profiles are validated and updated atomically as offline.

Multiple Hosts may use the same profile. Harmony follows DSH Settings' write model: whole-profile writes are serialized by a file lock and committed atomically; a stale UI save is rejected and refreshed, while concurrent processes use last-complete-write-wins semantics.

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

Press Tab in the TUI to switch between Provider and Patch views. The Patch view supports individual and Provider-wide enablement, Patch ordering, automatic sorting, runtime details, and concise inspection. Both views keep the selection visible when a profile is larger than the terminal.

status, patch-order show, and provider-order show exit with status 1 when their health or order constraints fail. patch-order auto and provider-order auto minimize violations while preserving the current order where possible. inspect --summary omits transformed source, while --patch <key> limits inspection to targets touched by one Patch. reload requires a running Host.

Patch model

Harmony runs every Patch from one global patchOrder. Provider-level before and after rules set the usual order. A Patch that declares either rule uses its own rules instead. In Settings → Harmony, users can move a whole provider or place one Patch between Patches from another provider. Plugin and Patch details provide their enable and disable actions, while the Patch status page is a read-only runtime monitor. Harmony checks that the saved list contains every registered Patch exactly once.

Plugin-wide disablement is an independent provider/* flag. It never clears or creates individual Patch flags. Re-enabling a plugin therefore restores only the Patches that were individually enabled before the plugin was disabled.

Every Patch may declare a human-readable description. Harmony exposes it through Patch status and JSON output, and displays it in Settings so users can understand the Patch before changing its order or enablement.

A composite Patch groups several Patches under one order position and switch. Members keep their declared order and apply only when every member succeeds. A failed standalone Patch is reported and skipped; later Patches and the Host continue to run.

Plugin compatibility

Any DSH plugin package can describe its relationships with other plugins under dsh.plugin.compatibility, whether or not it provides Harmony Patches:

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

requires reports a missing, inactive, or incompatible dependency; conflicts warns when an incompatible pair is active; and integrates reports an available optional integration. These declarations never install, enable, disable, or block plugins. Targets are package names and values are semver ranges. Reciprocal conflict declarations produce one warning, and disabling a Harmony Patch does not disable its owning plugin.

Live reports use the plugins active in Loader. When the profile is stopped, Harmony can only inspect its installation and therefore treats installed profile packages as active.

React-aware patches

Install dsh-harmony-react in a Patch provider when the target is compiled React:

npm install dsh-harmony-react

Use element() to change selected compiled jsx / jsxs calls. Use component() to change the shared component definition. Harmony applies both in the same Patch order as every other Source Patch.

To let later Component Patches modify the same definition, Harmony rewrites a function declaration as an initialized const. The new binding is not hoisted. If the file reads the component before its declaration, use a core Source Patch instead. React integration covers selectors, Inspect traces, and Studio.

Documentation

Powered by Harmony

If your plugin uses Harmony, you’re welcome to use this badge to show your support!

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

Development

All maintained implementation code uses TypeScript. Build artifacts are generated for packaging and are not tracked by Git.

Documentation sources and local preview tooling live on the docs branch.

npm test

Set DSH_HARMONY_PERF=1 when starting DSH to log one structured timing record for each Harmony startup, plugin update, profile update, and manual reload:

DSH_HARMONY_PERF=1 dsh web --no-open

Each record separates Patch preparation, source transformation, Host reload, browser rebuild, and total time. The probe stays inactive by default. Node.js diagnostic tools can instead subscribe to the diagnostics_channel channel dsh-harmony:load without enabling log output.

License

MIT