@spy2006/dsh-jspace-harness

Readme

# J-Space Harness

[![npm version](https://img.shields.io/npm/v/@spy2006/dsh-jspace-harness)](https://www.npmjs.com/package/@spy2006/dsh-jspace-harness)
[![CI](https://github.com/2006spy/jspace-harness/actions/workflows/verify.yml/badge.svg)](https://github.com/2006spy/jspace-harness/actions)
[![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)

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

`@spy2006/dsh-jspace-harness` packages the **J-Space Cognition Suite V3.6** as a
DeepSeek Harness **agent preset**. It adapts the upstream protocol to the
Harness runtime the right way: **Harness-native scoped prompt sections,
per-agent state isolation, request-cache-stable turn checkpoints, and durable
V3.6/Harness verification** — instead of guessing provider payloads or mutating
the conversation transcript the way the pi adapter does.

## What this preset gives you

| Capability | Harness-native behavior |
|---|---|
| Cognitive protocol injection | Registers one scoped `systemPrompt.section()` evaluated per assembly with the calling agent's context (`dsh-plan-mode`/`dsh-persona` pattern). No transcript pollution, no provider-payload mutation. |
| Gate (`fast` / `full` / `loop`) | Classified once per turn, persisted to a per-session ledger file, and surfaced in the prompt section. |
| Per-agent state isolation | Ledger keyed by `session.id` under `$DSH_HOME/j-space/<session-id>.json` with a per-agent `WeakMap` cache; sessions never share state. |
| Cache stability | The system-prompt section stays byte-identical across a turn's steps: `pass` is classified once per turn and `checkpoint` advances only at turn boundaries. The stable prefix `[system + history]` can be reused by the request cache; only the new tail is re-encoded. |
| Prompt construction cost | `compact` and `reminder` protocol text is built once at load; `full` reads `SKILL.md` lazily and caches it (no re-read per assembly). |
| State write resilience | Ledger writes are non-fatal, use a unique temporary file (`<pid>.<ts>.tmp`), and never interrupt an agent turn on disk failure. |
| Verification | Upstream V3.6 anchors (`PREMISE`, `INVARIANTS`), strict frontmatter/routing checks, and Chinese claim/coverage vocabulary — enforced by two durable verifiers. |
| Runtime control | `/jspace` command: `status`, `on`, `off`, `compact`, `full`, `reminder`. |

## Install

### Via DSH Plugin Market (dshmarket v1) — recommended

The package is published on npm: **`@spy2006/dsh-jspace-harness@0.1.1`**.

1. Make the catalog entry visible:
   - **DSH 1024Store (auto-collected):** this repository carries the `dsh-plugin`
     topic and its default branch already satisfies the 1024Store static check
     (`package.json` with `dsh.bundle.patch` + `cordis.patch.yml` in the same
     tree), so it is picked up by the pipeline's incremental scan. Search
     `jspace` in the 1024 Store tab of Plugin Market.
   - **Custom standard source:** deploy `market/worker.mjs`
     (`npx wrangler deploy`), then register
     `https://<worker>/catalog-source.json` in Plugin Market → Sources.
2. Open the entry in DSH Plugin Market, **Preview** (the host re-validates the
   exact npm identity, repository backlink, lifecycle scripts, engine, and DSH
   bundle evidence), confirm, and **restart DSH Desktop**.
3. On first launch `index.js` copies `preset/` into
   `$DSH_HOME/.agent-presets/jspace-harness`. An existing user-owned preset is
   deliberately **not** overwritten, so local customizations survive.
4. Start a new session and pick the **J-Space Harness** preset.

### Manual install

```text
git clone git@github.com:2006spy/jspace-harness.git
# copy the preset directory into the DSH user preset root:
robocopy preset %USERPROFILE%\.dsh\.agent-presets\jspace-harness /E   # Windows
cp -R preset ~/.dsh/.agent-presets/jspace-harness                     # macOS/Linux
```

Restart DSH and select **J-Space Harness** in the new-session preset picker.

## Usage

In any session on the preset, `/jspace` controls the runtime:

| Command | Effect |
|---|---|
| `/jspace` or `/jspace status` | Show enabled state and mode |
| `/jspace on` / `/jspace off` | Enable / disable the cognitive layer |
| `/jspace compact` | Default: ~1.5k-char protocol block; modules are read on demand |
| `/jspace full` | Inject the whole `SKILL.md` (truncated at 18 000 chars); use sparingly |
| `/jspace reminder` | Lightest: one gate line only, best for long sessions |

State is stored per session in `$DSH_HOME/j-space/<session-id>.json`
(override with `JSPACE_STATE_DIR`). The bundled skill (`skills/j-space`)
provides the optional `jspace.py` controller (`note` / `seam` / `resume` /
`ship`) and its regression tests.

## Benchmarks (measured on this machine)

Method: Python 3.12.10, cold subprocess timings, fresh temporary workspace per
controller lifecycle, median of N rounds. Raw data lives in
[`benchmarks/`](benchmarks/).

### Controller lifecycle (upstream V3.6 vs this preset)

Full ledger lifecycle (`note` goal/core/open/close + `seam` + `ship` with a
Chinese covered verification claim), 20 rounds:

| Condition | Median | Mean | Min | Max |
|---|---:|---:|---:|---:|
| Upstream V3.6 `jspace.py` | **800.299 ms** | 814.206 ms | 774.202 ms | 914.101 ms |
| This preset's `jspace.py` | **781.112 ms** | 780.362 ms | 749.431 ms | 836.777 ms |

This preset is ~2.4% faster on the median lifecycle despite carrying the V3.6
controller logic, strict verifier, and Chinese claim/coverage vocabulary.

### Adapter cold parse (pi adapter vs this preset)

`node --check` of each adapter entry, 20 rounds:

| Condition | Median | Mean | Bytes |
|---|---:|---:|---:|
| pi adapter (`tonyxu721/pi-j-space`) | 206.535 ms | 200.709 ms | 12 175 |
| This preset's `preset/j-space.mjs` | 205.755 ms | 212.285 ms | **10 852** (-10.9%) |

### Same-model protocol smoke comparison (10 tasks, blind-scored)

Same model, no tools, one fixed rubric (0–2 correctness + 0–1 verification per
task, max 30). Upstream generic protocol vs this preset's forced gate/ledger:

| Condition | Correctness | Verification | Total |
|---|---:|---:|---:|
| Upstream generic protocol | 20 | 10 | **30/30** |
| Harness forced protocol | 20 | 10 | **30/30** |

Verdict: **tie** — Harness forcing does not regress correctness or verification
coverage on short deterministic tasks. The task set is intentionally too short
to claim a capability separation.

### Verification suite

- Upstream V3.6 regression tests: **18/18 pass**
- `verify_suite.py` (upstream anchors + strict frontmatter/routing): **clean**
- `verify_harness.py` (Harness adapter contract): **clean**

### Reproduce

```text
python benchmarks/run_jspace_bench.py        # engineering timings -> engineering-results.json
python preset/skills/j-space/scripts/verify_suite.py
python preset/skills/j-space/scripts/verify_harness.py
```

### Scope of these numbers

Engineering measurements describe local controller/adapter behavior, not an
LLM capability score. The same-model comparison is a 10-task protocol smoke
test. Provider-level prompt-cache hit rate and long-horizon durability need a
fixed provider/model, temperature/seed, task corpus, and token telemetry.

## Discovery in DSH Plugin Market

- **DSH 1024Store (auto-collected):** the pipeline scans GitHub repositories
  carrying the `dsh-plugin` topic and validates `package.json` +
  `dsh.bundle.patch` + patch file on the default branch. This repository
  satisfies all checks, and the published npm package with a matching
  repository backlink makes the entry installable through the managed path.
  See https://github.com/imsai-sh/awesome-deepseek-harness-plugins.
- **Custom standard source:** deploy `market/worker.mjs` and register
  `https://<worker>/catalog-source.json`. See `market/README.md`.
- **dshfind** is a third-party read-only index; listing there is controlled by
  dshfind, not by this repository.

## Development checks

```text
python preset/skills/j-space/scripts/verify_suite.py
python preset/skills/j-space/scripts/verify_harness.py
node --check index.js
node --check preset/j-space.mjs
npm pack --dry-run
```

## Project layout

```text
jspace-harness/
├── index.js                # plugin entry: copies preset/ into .agent-presets on first launch
├── cordis.patch.yml        # DSH bundle patch (market installer mounts the plugin row)
├── package.json            # npm package: dsh.bundle.patch, no lifecycle scripts
├── preset/                 # the agent preset (agent.cordis.yml + j-space.mjs + skills/j-space)
│   └── skills/j-space/     # SKILL.md, 9 modules, references, jspace.py, dual verifiers
├── market/                 # deployable Cloudflare Worker standard-source catalog
├── benchmarks/             # reproducible engineering + protocol comparison data
└── .github/workflows/      # CI: verifiers + syntax + npm pack
```

## Attribution

The bundled J-Space skill derives from
[J-Space Cognition Suite V3.6](https://github.com/Tiger3807861189/J-Space-Cognition-Suite-V3.6).
See `THIRD_PARTY_NOTICES.md` and `LICENSE`.