dsh-super-injector — Super Module Injector

🎉 v0.3.0 Major Announcement (2026-08-14)

From empirical patches to source-code contracts — the injector has completed a spec-driven refactor.

This version refactors self-reload around docs/SPEC.md (a design contract derived from the DSH 0.1.0-rc.6 source semantics) into the official REPLACE structure: the tool only schedules; it never kills itself; reboot goes through entry._dispose (official _disposing exemption) + automatic rollback on failure. From now on, every behavior of the injector has source-code grounding, no longer relying on empirical patches.

Milestone recap:

• Three rounds of zero-context subagent evaluation: 9/10 → 9.5/10 → 10/10
• Self-destruction stress test: cascading self-suicide / bad syntax / dangling junction / circular inject-unload — zero crashes, zero residue
• Cloud self-bootstrap: download release copy → assemble → injector runs from the cloud copy (self-test 8/8)
• Resilient process recovery: failure → touch patch (in-process re-assembly of include.refresh) → back in 6 seconds
• DSH stable release compatibility: runs on 0.1.0-rc.6 with zero code changes (peerDeps range declaration verified)

The philosophy is unchanged: everything is a plugin — the injector is the runtime injection standard layer of the DSH ecosystem, making it "whatever shape you want a plugin to grow into, it can."

The DSH ecosystem's BepInEx-style mod injection entry point: at runtime, inject any local plugin package into a running web, without touching patch / package.json / bundles list, no process restart. Injection takes full effect immediately (host tools + client UI).

Inspiration: the official assembly mechanism (profile bundle / repository-plugin) is the only "official entry point," just like a game where only the launcher can install mods. This plugin breaks that — the bootstrap installs once via the official entry, and after that everything can be injected at runtime.

Install (pick 1 of 3)

Option A: Release Package (recommended, no build required)

Download dsh-external-dsh-super-injector-0.0.1.tgz from Releases, unpack to get the plugin directory (including lib/ and cordis.patch.yml), then:

# 官方装配（重启后由 bundles 接管，生产态）
dsh plugin --profile web add <解压目录>

# 或运行时注入（免重启，开发态；需任一环境已常驻注入器）
# 对 AI 说：dev_inject_plugin <解压目录>

Option B: git assembly

dsh plugin --profile web add github:yjh051108/dsh-super-injector

git dependencies pull the source repository (without lib/); the package's prepare hook automatically builds a self-contained lib/ with tsdown at install time (the first time requires network to fetch tsdown; subsequent times use local cache). If the build fails, use the prebuilt tgz from Option A instead.

Option C: Bootstrap Assembly (source-code approach, one-time only)

⚠️ Only use when you are not going through bundles assembly: the injector's built-in bundle layer auto-registers dsh-super-injector, which collides with the manual insert below on the same loader entry id and will report duplicate loader entry id. After assembling via Option A/B, do not add this entry.

Add to ~/.dsh/profiles/web/cordis.patch.yml:

- insert:
    - id: dsh-super-injector
      name: '@yjh051108/dsh-super-injector'
      config: {}

Bootstrap is resident; any mod on demand, no more config.

Compatibility

• No hardcoded DSH version: peerDependencies are all range declarations (@deepseek-ai/dsh-tools: >=0.0.1-rc <2, cordis: >=4.0.0-rc <5) — DSH upgrades won't break it.
• Adapted to service renames: webServer (formerly httpServer), compaction (formerly compact).

Features

• 🔥 Hot reload + self-reload: dev_reload_package reloads the whole package (clear cache → re-import → rebuild fiber, failure rolls back keeping the old generation); the injector itself also supports self-reload (self-kill → global timer rebuild)
• 🤖 Auto watch: injection automatically watches the plugin directory; after a code build, auto-reload in ~1.5 seconds (no manual trigger needed)
• 🖥️ Injected plugin UI fully works: clears loader ghost entry isolation (normalizeEntry), client module rescan/linked cleanup/unload — the injected plugin's host tools + graph/panels etc. UI all available
• 🧪 Dev staging + persistence: test tools hang "on the back side" and don't enter the tools schema, zero cache pollution; dev_stage_promote promotes to official with one click; staging persists to disk, promoted tools auto-restore after self-reload/restart
• 🧹 One-click uninstall: dev_uninject_plugin fully cleans up the fiber (tools/listeners/routes/client tables) → clears injection registry → deletes junction, no restart needed
• 🛠️ Route self-healing: dev_clear_routes goes straight to the webserver's internal route table, orphan routes left by hot reload are cleared without restart
• 🔁 Auto-recovery on restart: injection registry persisted (~/.dsh/super-injector/registry.json), auto-restored after web restart
• 📊 Operation self-check: each inject/reload/install returns host ✓ / client ✓ dual verification; dev_plugin_status includes operation success-rate stats
• 🛡️ Failure is retryable: hasActiveEntry authoritative dedup + automatic cleanup of failed residue cache + automatic cleanup of residue entries

Positioning differences vs dsh-evolve (ecosystem complementarity)

	dsh-evolve	dsh-super-injector
Form	Creation mode: agent writes single-file plugin source on the fly (~/.dsh/evolve/<name>.mjs) hot-mounted	Surgical table: injects developer prebuilt complete plugin packages (package.json + lib/)
Use cases	agent grows small tools from the conversation (bookkeeping/weather/weekly reports)	Install/swap finished mods, autonomous dev loop (write → build → inject → hot reload)
Interop	Source grown by evolve can be upgraded to a complete package, then loaded via the injector	After injection, can be hot-reloaded by dev_reload_package

Ecosystem Position

Official direction for the plugin system (2026-07 agent notes):

1. Rejected install commands + install database + marketplace — persistent plugins have only one state: configuration (cordis.patch.yml / profile bundles / repositories), transactional HMR reconciliation;
2. Agents manage their own runtime — self-referential cordis toolset, runtime is the agent's responsibility.

Translation: official dictates "what to install" (bundle / repository + configuration), but "how to change it after installation" — hot reload, side-mounted testing, one-click promotion, uninstall, failure self-healing — is left blank by official. This entire runtime management surface is handled by this plugin.

Ecosystem entry	Layer	One-line role
Official bundle / repository	Assembly layer	The only official entry, config as state
plugin-registry	Official thin console	Official-format plugin management and dev guidance
marisa	Agent-side toolchain	Solidification bridge from temporary to persistent plugins
mygo	Managed-object layer	Plugin lifecycle objectification (lock/start-stop/dependency graph)
dsh-evolve	Creation mode	agent grows single-file capabilities on the fly
dsh-super-injector	Runtime surgical table	Full dev-loop toolkit: inject / hot reload / side-promote / uninstall / route self-heal / UI linkage

Design principles:

1. No protocol invention: injected packages are standard plugin packages (package.json + lib/), the format is the official one, installing means official semantics;
2. Dual-path, respects "config is singular": runtime injection (no restart, dev mode) ↔ dev_install_package writes to profile bundles (after restart, official takes over, prod mode) — the injection registry is just a runtime recovery cache, not a second install database;
3. Model-driven: all dev_* are tools, the agent itself injects/uninstalls/promotes — squarely on the official "agent manages its own runtime" direction;
4. Reversible and self-healing: injection is rollbackable (failure keeps old gen), uninstall is clean (full fiber cleanup), residue self-heals (routes/cache/entry auto-cleaned).

Goal: the de-facto standard runtime layer below official assembly — "launcher" is just the start; the injector gives DSH a Mod-class experience: everything injectable, rollbackable, instant effect.

Full Toolkit (all without restart)

Tool	Description
dev_inject_plugin	Runtime-inject a local plugin package (junction link + loader.create, hasActiveEntry dedup)
dev_uninject_plugin	One-click uninstall of an injected mod (fiber dispose full cleanup; bundle plugins auto-write disabled to block self-assembly)
dev_injected_list	List the injection registry
dev_install_package	Hot-assemble a local bundle plugin (profile package.json + junction + loader.create; after restart, the bundles list assembles normally)
dev_reload_package	Whole-package hot reload (clear cache → re-import → rebuild fiber, failure rolls back keeping old gen; includes self-reload)
dev_plugin_status	List of assembled plugins, fiber status, and operation success-rate stats
dev_clear_routes	Webserver route-residue self-heal (orphan routes deleted by path prefix)
dev_stage_add	Dev side-mount: test tools on the back side (not in tools schema, zero cache pollution)
dev_stage_call	Invoke a side-mounted tool for testing
dev_stage_list	List side-mounted tools (including promotion status)
dev_stage_promote	One-click promote: side-mounted tool moves to the front side for formal registration (the only cache refresh)
dev_stage_demote	Withdraw/revoke a side-mounted or already-promoted tool

Dev Guide

Philosophy: a plugin can take whatever form — toolkit / guardian loop (timer + LLM autonomous agent loop) / UI panel / hybrid, same injection channel; injection takes full effect (host + UI), hot-reloadable and self-reloadable, clean on uninstall; the plugin's own prompts/tools/loops are self-optimizable (edit → build → reload loop). When creating a new plugin, prioritize cloning/borrowing/refactoring existing ecosystem resources (dsh-external repos, already-injected plugins, official packages patterns); don't reinvent the wheel.

One-minute start (the production-line trio)

# 1. 生成骨架（toolkit / daemon-loop / ui-panel / hybrid）
#    对 AI 说：dev_scaffold_plugin {"dir": "D:/dev/my-plugin", "name": "my-plugin", "form": "daemon-loop", "description": "..."}

# 2. 构建打包（探测 DSH_CHECKOUT → tsc host → tsdown client（如声明）→ npm pack → tgz）
#    对 AI 说：dev_build_plugin {"dir": "D:/dev/my-plugin"}

# 3. 发布（gh release create v<version> + tgz）
#    对 AI 说：dev_release_plugin {"dir": "D:/dev/my-plugin", "version": "0.1.0"}

# 注入即活：dev_inject_plugin {"dir": "D:/dev/my-plugin"}
# 改代码 → build → 自动 watch ~1.5s 重载（或 dev_reload_package）

30-line "thinking plugin" (minimal guardian-loop example)

import type { Context } from 'cordis'
import type LlmService from '@deepseek-ai/dsh-llm'
import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'

type AppContext = Context & { llm: LlmService; setInterval(fn: () => void, ms: number): any }

export const name = 'my-daemon'
export const inject = ['timer', 'llm']

export function apply(ctx: AppContext): void {
  let route: { provider: string; model: string } | null = null
  ctx.on('llm/stream', (options, next) => { route = { provider: options.provider, model: options.model }; return next() })
  ctx.setInterval(() => {
    void (async () => {
      if (!route) return
      const stream = ctx.llm.stream({
        provider: route.provider, model: route.model,
        system: '判断是否需要人工介入，直接输出结论',
        messages: [createUserMessage({ source: { kind: 'user' }, content: [{ type: 'text', text: '检查事项...' }] })],
        reasoningEffort: ReasoningEffortId('off'), maxTokens: 200,
      })
      for await (const chunk of stream) { /* 决策 → 行动 */ }
    })().catch(() => {})
  }, 60_000)
}

Spec rules (distilled from injector field tests):

1. Resource registration must hook ctx.effect (tools/routes/listeners) — only then will hot reload/uninstall auto-clean; otherwise zombie residue (the injector learned this the hard way)
2. peerDependencies as range declarations (>=0.0.1-rc <2, >=4.0.0-rc <5) — no hardcoded versions, DSH upgrades won't break it
3. client bundle needs a separate build (tsdown → lib/client.js) — UI form requires a two-step build
4. Prompt injection follows the cache principle: static text + early order (static goes to the front); dynamic content goes to the tail of messages (dynamic goes to the end); never splice dynamic content into system — any dynamic change to the system prefix = full-session cache miss (a hit is 10× cheaper)
5. Self-test: after editing code, run dev_self_test once to ensure the inject/reload/self-reload/precheck/unload chain doesn't regress
6. First-round anchoring (V4 Pro tested; see dsh-anchored-standard, Project2 98/99): when the tool surface is large (≥5 tools), expose only the 1–2 most core tools in the first request, then restore all after the first tool/call — the first request's structure determines the whole session's strategy trajectory; anchor to the narrow tool surface the model was trained on, then open up, with no capability loss. Implementation: system-prompt/assemble Waterfall filterer (built into the scaffold, see dev_scaffold_plugin)
7. Lean tool schema: keep description short and purpose-clear; put details in tool result / static guidance text, not in the schema — the tool directory is billed by character into first-round prefill; measured: 6 plugins can inflate to 176K characters, diluting first-round attention and the uncached prefill is the most expensive (a cache hit is 10× cheaper)
8. Proximity signal principle (strongest mechanism; P14/P16/P20 tested): all behavior guidance (classify/deep-think/converge) must be injected after the user message (proximal); the same instruction placed in system (distal) decays or even inverts (P13 protocol acceleration decay; P20 deep-segment injected into persona routing crashed to 67%); keep fixed text to preserve cache hits (92–94%)
9. Weak in-domain routing (P8/P11): when task type is ambiguous, don't assert a mode — use a weak persona (the model classifies itself); choose persona per model (Pro = spec sentence + few-shot; Flash = neutral + classify; the same persona can behave oppositely across two models)
10. Three anchors for single-task long chains (P22/P23): uncontrolled exploration on open tasks is the main failure mode (0% completion) — a persona static anchor of "review done + produce when info is sufficient + ban env-check / exhaustive grep" pulls completion to 100%

High-performance plugins (first-round anchoring · why & how)

Why: DeepSeek V4 Pro's behavior strategy is strongly conditioned by the first-round request's "full system prompt + tool schema distribution." Same problem, same environment: minimal (2 tools) 99/96, standard (25 tools) 91, two-phase anchoring 98/99 — narrow first, then wide, gaining both capability and the full tool surface. Micro-probes prove that what matters is the callable schema surface (action space), not seeing tool-name text; the tool directory only changes once (one prefix-cache shift between the first and second requests; the uncached first-round prefill is the most expensive).

How (scaffold built-in; enable in three steps):

1. The toolkit scaffold generated by dev_scaffold_plugin has a commented-out anchoring block at the end of apply();
2. Add 'systemPrompt' to the inject array, replace MINE with your tool-name set and CORE with the core tools to keep in the first round;
3. After the first tool call, all tools are restored automatically; resume/reload doesn't lose state (phase is derived from persisted session events).

Verify: export the session JSONL and check request/header — the first entry contains only core tools; the entry after the first tool call has a full directory in its header change; it stays full from then on.

Complete cognition of high-performance guidance (v0.3.3 update, based on dsh-router-standard P1–P23 field tests)

Mechanism	Measured	Implementation
First-round anchoring (narrow tool surface)	Project2 98/99	tool-bootstrap filterer (scaffold built-in)
Proximity guidance (injected after user message)	Zero decay (same instruction distal accelerates decay)	Plugin listens session/event → inbox.append fixed guidance
Weak in-domain routing (ambiguous tasks self-classified by model)	Discriminability +5~5.7, choose persona per model	weak mode (dev_router_mode weak)
deep-guide (classify + deep-think + commit)	Routing 96% + convergence 100% + anti-dilution	Proximal fixed guidance text
Single-task three anchors (review + converge + anti-drift)	Completion 0%→100%	persona static anchor
plan-mode section retained	Amnesia fix (v6)	applyPersona only swaps the persona section

Full implementation and repro probes: dsh-router-standard (v0.1.0, includes the paper and P1-P23 full data).

References and acknowledgements: The "first-round anchoring" mechanism and statistical evidence in this guide reference xiaobright's open-source work — dsh-anchored-standard (MIT, two-phase anchoring preset and tool-bootstrap.mjs implementation, Project2 measured 98/99, first-round 2 tools → after first tool call restored to 25-item full Standard toolkit) and modeltest (V4.1b eval suite: same-environment comparison minimal 99/96 vs standard 91 vs two-phase 98/99, trigger-mechanism micro-probes, trajectory stats). The anchoring implementation in the scaffold is a plugin-level port of that preset filterer (only trims this plugin's tools).

Typical workflows

Install a mod: get the plugin package (package.json + lib/ artifacts) → tell the AI dev_inject_plugin (param = absolute path of the plugin package) → takes effect immediately (tools visible on the next step).

Dev iteration: edit code → build → auto watch reloads in ~1.5 seconds (or dev_reload_package) → verify → once stable, dev_stage_promote for one-click promotion.

Uninstall: dev_uninject_plugin (param = package name substring) → tools/listeners/routes/client tables all cleared, no restart needed.

Mechanism

1. junction link the plugin package into ~/.dsh/profiles/web/node_modules (loader standard resolution path);
2. ctx.loader.create({ name, config }) runtime assembly (full ctx);
3. Registry persistence (~/.dsh/super-injector/registry.json), auto-restores injection after restart;
4. Client linkage: after injection/reload, clears the entry disabled flag and rescans the client module table (client-modules.processOne); browser-side bundle rev updates in tandem.

Pitfall log

• Plugin package must self-link its dependencies: import '@deepseek-ai/dsh-tools' etc. inside lib/ resolves from the package's own node_modules — follow build.sh to create junctions into the checkout package (e.g. node_modules/@deepseek-ai/dsh-tools → <checkout>/packages/core/tools);
• client bundle needs a separate build: host side bash scripts/build.sh (tsc), client side npm run build:client (tsdown, artifact lib/client.js) — an injected plugin that ships UI must build both steps;
• A failed import poisons retries: loadCache keeps a partial job, so a same-name reload reuses the failed state — purgeCache before injecting;
• Resource registration must hook ctx.effect: if reloadPackage rebuild fails with duplicate / already registered, the resources were bare-registered — hooking ctx.effect makes hot reload correctly clean and rebuild;
• Client ops must use the full package name: client-modules.processOne exact-matches entry.options.name; passing a short name silently fails to register;
• Injected plugins don't enter the loader config persistence — after restart the injector auto-restores them (bootstrap is resident).

---

Repo: https://github.com/yjh051108/dsh-super-injector Release: https://github.com/yjh051108/dsh-super-injector/releases