Introduction¶

The design philosophy of DSH (DeepSeek Harness) is “everything is a plugin”. There are already some performance-oriented plugins in the community: @linxin666/dsh-perf handles observation and frontend rendering load reduction, and dsh-pref-kit performs streaming incremental merging at the source. However, there is a class of problems in existing large sessions that they cannot address: once the event count for a single session accumulates to several hundred thousand, forking a subsession, reopening a historical session, or persisting the fork result all become synchronous heavy workloads on the event loop—at worst, causing hundreds of milliseconds of lag, at best saturating a single core for 20 minutes, or even directly throwing a RangeError.

dsh-large-proj-perf (v1.2.0, MIT license, author orangeofcarl0-sys) introduced in this article targets these three types of blocking: zero-copy fork, sharded projection warmup, sharded materialize, and cold session memory management. It equips all these in one go. The following sections will unfold in the order of problem identification, implementation solutions, and installation/operations.

What Problems Does It Solve¶

In dsh 0.1.x, there are three types of synchronous blocking on large sessions, with the README providing source-level positioning and real-world test data:

The root causes are all within the DSH implementation itself; what the plugin layer can do is workarounds or sharding. The following explains the plugin’s approach item by item.

Core Features¶

Zero-Copy Fork¶

The forked seed itself is a deepFreezed immutable JSON tree, so event-by-event deep copying is not semantically required. The plugin redirects the forked seed through the Session.prepare(seedSource:'persistence') fromRestore channel, freezing in place and reusing the reference. The subsession header matches the official implementation field-by-field. In testing, a single fork dropped from 346ms to 19ms.

Sharded Projection Warmup and Fork Cache Backfill¶

When a session enters and the event count exceeds the threshold (minEvents, default 20000), the plugin interleaves sharded replays of cells before the first cold folding. It uses setImmediate to yield the event loop between shards, writing the results directly to registration.cells. When projection cache rows already exist on disk, it skips the folded prefix by taking a baseline. A session with 740k events was reduced from blocking 20 minutes to approximately 200ms.

The subsession forked from the original had no projection cache rows, so reopening would take a full read (minutes). After warmup, the plugin backfills the cache rows, reducing the reopen time to seconds.

Sharded Materialize¶

Fork persistence originally serialized the entire seed at once; 600k events is a massive 501MB string. The plugin changed to writing one zstd frame per materializeChunkEvents (default 50000). The multi-frame format is the native format for the decoding end’s scanZstdFrames, is byte-compatible, and requires no changes on the decoding side.

Cold Session LRU Trimming and Heap Detection¶

The live event tree of a large session is approximately 700MB. When multiple cold sessions stack up, the default V8 heap limit (about 4GB) will cause an OOM. The plugin reduces SessionPreparations.capacity to preparedCacheSize (default 1) at runtime and evicts the oldest ready entries. In testing, this saved approximately 2.8GB; config.set takes effect immediately, and the original capacity is restored upon disposal.

The accompanying heap detection will alert when the heap limit is below the threshold (default 6GB) and suggest adding --max-old-space-size.

Fast initFor: Boilerplate Retirement by Item¶

Persistence’s initFor performs a structuredClone on the seed. The plugin changes to freezing the reference for reuse. In testing, this dropped from 135ms to approximately 0ms. Starting from DSH 0.1.0-rc.8, upstream has natively implemented the same zero-copy form, and this patch automatically retires—the feature is missing, but it only logs an info message when the upstream zero-copy form is detected, avoiding false positive drift.

This reflects the plugin’s overall strategy: after upstream absorbs a capability, the corresponding patch retires by item rather than being disabled entirely. The actual status of each patch is exposed via the patches field of stats.get (active / retired / inactive / off).

dsh-std Standard Compatibility¶

The plugin provides compatibility for dsh-std Community v0.15: the dsh-plugin.json manifest adds facets.host.entry (pointing to lib/std-host.js). Currently, dsh 0.1.x loads lib/index.js via cordis.patch.yml, and behavior remains unchanged; in the future, standard hosts will load via the manifest, running in parallel.

Patch Security Mechanism¶

All patches are implemented via monkey-patching internal methods and are highly coupled with the DSH version. The security design consists of three layers:

1. Each patch is accompanied by source code signature verification; if the signature does not match, it is automatically skipped and alerted, never blindly patched.
2. Three-layer fallback: capability probe / try-catch / config switch. It automatically falls back to the official implementation on failure.
3. Complete restoration on disposal, leaving no residual modifications.

Installation and Activation¶

Runtime requirements: Node ≥ 22.15.0 (zstd interface depending on node:zlib); dsh 0.1.0-rc.6 ~ 0.1.2-rc.1 (version declared in package.json’s engines).

First execute the installation command, then restart dsh web; success is indicated by the log [dsh-perf] installed (...):

dsh plugin --profile web add github:orangeofcarl0-sys/dsh-large-proj-perf

For local development, use the file: protocol:

dsh plugin --profile web add file:<local-repo-path>

Note that file: installation does not automatically follow repository changes. After modifying code, you must sync lib/, cordis.patch.yml, package.json, and dsh-plugin.json to the profile directory, or re-execute dsh plugin add.

Recommended Startup Method¶

LRU trimming can save memory, but the heap limit is a startup parameter. When multiple large sessions coexist, the default ~4GB is insufficient. It is recommended to use the script provided in the repository, which includes --max-old-space-size=8192:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-dsh.ps1

Configuration and Runtime API¶

All configuration can be modified via the Settings card, config.set API, or settings persistence. Numerical items have lower bounds (e.g., materializeChunkEvents ≥ 1000, chunkSize ≥ 1, preparedCacheSize ≥ 1). Main configuration items:

The API endpoints are mounted at http://127.0.0.1:3080/dsh-large-proj-perf/api/<method>, accepting only loopback addresses with CORS checks. stats.get returns the dshVersion version probe, the patches status of each patch, and fork / warmup / backfill counters; stats.reset zeroes the counters; config.get / config.set handle runtime toggles, with config.set also writing to settings persistence.

curl -X POST http://127.0.0.1:3080/dsh-large-proj-perf/api/stats.get
curl -X POST http://127.0.0.1:3080/dsh-large-proj-perf/api/config.set -d '{"zeroCopyFork": false}'

Upgrade and Version Compatibility¶

The plugin has been developed and verified on dsh 0.1.0-rc.6 / rc.7 / rc.8, 0.1.1-rc.1 / rc.2, 0.1.2-alpha.5, and 0.1.2-rc.1. After upgrading DSH, do two things:

1. Run node tests/verify_compat.mjs to perform 16 structural assertions on the actually installed source code.
2. After starting, confirm there are no signature mismatch alerts in the logs—if the patches do not match, it will not crash, but the optimizations will fail silently.

Upstream rc.7 fixed historical pagination stack overflow, and rc.8 optimized the SQLite backend; neither overlaps with this plugin nor touches the root causes (historical loading full decode, live event tree full residency).

Coexistence with Other Performance Plugins¶

All three can be installed simultaneously. The only note: the whitelists for row management experimental items all contain session-projection-cache. Do not disable this row, otherwise projection cache backfill and baseline reading will fail (there is a defensive fallback, it won’t crash, but functionality is degraded).

Use Cases and Considerations¶

The use cases are clear: DSH sessions have tens of thousands of events, or forking/reopening historical sessions is noticeably slow, or OOM has been encountered. Users with small session scales will not perceive much difference, as warmup has a minEvents threshold as a fallback.

Before installation, there are a few points that must be known:

1. The plugin runs with the permissions of the current DSH process and modifies internal methods via monkey-patching. It is recommended to review the GitHub repository source code and license (MIT) before installing.
2. This plugin is a passive optimization and cannot reduce the live event tree currently in use. It is recommended to pair it with the author’s dsh-fresh-start: /fresh for one-click “Summary → New Session → Archive Old Session” to actively control scale; one for bottom-line performance, the other for scale control.
3. Relieving does not cure: the root causes of live event tree full residency (approx. 700MB per large session) and historical loading full decode are in the DSH architecture; curing depends on upstream support for event pagination loading / on-demand residency. enqueue’s per-event structuredClone and the cold session’s coldSnapshot full readFrom(0) also cannot be safely eliminated at the plugin layer.

If you want to verify it yourself on the development side: first run scripts/link-deps.ps1 to link DSH internal packages, then npm test (8 suites, 112 assertions).

Summary¶

After the steps above, there are corresponding solutions for the three types of blocking: fork, historical loading, and persistence. Each has independent switches, signature verification, and fallbacks. Patches retire item-by-item after upstream absorbs them. For DSH instances slowed down by large sessions, this is a low-cost, easily reversible mitigation solution.

Source code and documentation can be found on the GitHub repository: https://github.com/orangeofcarl0-sys/dsh-large-proj-perf; Community Directory Page: https://www.skillhub.cn/plugins/orangeofcarl0-sys/dsh-large-proj-perf. The community directory is an independent site with no official affiliation to DeepSeek or Fangfang; information listed is based on the directory site.