# 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)

[English](README.md)

`@spy2006/dsh-jspace-harness` 把 **J-Space Cognition Suite V3.6** 打包成
DeepSeek Harness 的 **agent preset**。它用正确的方式把上游协议适配到 Harness
运行时：**Harness 原生 scoped prompt section、按 agent 隔离的状态、请求缓存
稳定的 turn 边界 checkpoint、以及可复现的 V3.6/Harness 双重校验**——而不是像
pi 适配那样猜测 provider payload 或改写对话记录。

## 这个 preset 提供什么

| 能力 | Harness 原生行为 |
|---|---|
| 认知协议注入 | 注册一个 scoped `systemPrompt.section()`，每次 assembly 按调用 agent 的上下文求值（与 `dsh-plan-mode`/`dsh-persona` 同模式）。不污染对话记录，不改写 provider payload。 |
| 任务门控（`fast` / `full` / `loop`） | 每轮分类一次并持久化到 per-session ledger 文件，在 prompt section 中呈现。 |
| 按 agent 隔离的状态 | Ledger 以 `session.id` 为键存放在 `$DSH_HOME/j-space/<session-id>.json`，配合 per-agent `WeakMap` 缓存；会话之间绝不共享状态。 |
| 缓存稳定性 | 一轮之内 system prompt section 逐字节不变：`pass` 每轮只分类一次，`checkpoint` 只在 turn 边界推进。`[system + 历史]` 稳定前缀可被请求缓存复用，只需重算新尾部。 |
| Prompt 构建成本 | `compact` 与 `reminder` 的协议文本在加载时构建一次；`full` 按需读取 `SKILL.md` 并缓存（不再每次 assembly 重读）。 |
| 状态写入韧性 | Ledger 写入非致命、使用唯一临时文件（`<pid>.<ts>.tmp`），磁盘故障不会中断 Agent turn。 |
| 校验 | 上游 V3.6 锚点（`PREMISE`、`INVARIANTS`）、严格 frontmatter/路由检查、中英文验证声明与覆盖范围词表——由两个持久化 verifier 强制执行。 |
| 运行时控制 | `/jspace` 命令：`status`、`on`、`off`、`compact`、`full`、`reminder`。 |

## 安装

### 通过 DSH 插件市场（dshmarket v1）安装——推荐

npm 包已发布：**`@spy2006/dsh-jspace-harness@0.1.1`**。

1. 让目录条目可见：
   - **DSH 1024Store（自动收录）：** 本仓库带 `dsh-plugin` topic，默认分支已
     通过 1024Store 静态校验（`package.json` 含 `dsh.bundle.patch` + 同一
     tree 内存在 `cordis.patch.yml`），会被流水线的增量扫描收录。在插件市场
     的 1024 Store 标签页搜索 `jspace` 即可。
   - **自定义标准来源：** 部署 `market/worker.mjs`
     （`npx wrangler deploy`），然后在插件市场 → 来源添加
     `https://<worker>/catalog-source.json`。
2. 在 DSH 插件市场打开该条目，**Preview**（Host 会复核精确 npm 身份、仓库
   backlink、lifecycle scripts、engine 与 DSH bundle 证据），确认后
   **重启 DSH Desktop**。
3. 首次启动时 `index.js` 会把 `preset/` 复制到
   `$DSH_HOME/.agent-presets/jspace-harness`。已存在的用户自有 preset 会被
   **刻意跳过**（不覆盖），本地定制不会丢失。
4. 新建会话并选择 **J-Space Harness** 预设。

### 手动安装

```text
git clone git@github.com:2006spy/jspace-harness.git
# 把 preset 目录复制到 DSH 用户预设根目录：
robocopy preset %USERPROFILE%\.dsh\.agent-presets\jspace-harness /E   # Windows
cp -R preset ~/.dsh/.agent-presets/jspace-harness                     # macOS/Linux
```

重启 DSH，在新建会话的预设选择器中选择 **J-Space Harness**。

## 使用

在该预设的任意会话中，用 `/jspace` 控制运行时：

| 命令 | 效果 |
|---|---|
| `/jspace` 或 `/jspace status` | 显示启用状态与模式 |
| `/jspace on` / `/jspace off` | 启用 / 关闭认知层 |
| `/jspace compact` | 默认：约 1.5k 字符协议块；模块按需读取 |
| `/jspace full` | 注入整本 `SKILL.md`（截断至 18 000 字符）；仅在需要时使用 |
| `/jspace reminder` | 最轻量：只注入一句门控提醒，适合长会话 |

状态按会话存放在 `$DSH_HOME/j-space/<session-id>.json`（可用
`JSPACE_STATE_DIR` 覆盖）。捆绑的 skill（`skills/j-space`）还提供可选的
`jspace.py` 控制器（`note` / `seam` / `resume` / `ship`）及其回归测试。

## 实测数据（本机测得）

方法：Python 3.12.10，冷启动子进程计时，每个 controller 生命周期使用全新
临时工作区，取 N 轮中位数。原始数据见 [`benchmarks/`](benchmarks/)。

### Controller 生命周期（上游 V3.6 vs 本 preset）

完整 ledger 生命周期（`note` goal/core/open/close + `seam` + `ship` 中文覆盖
验证声明），20 轮：

| 条件 | 中位数 | 均值 | 最小 | 最大 |
|---|---:|---:|---:|---:|
| 上游 V3.6 `jspace.py` | **800.299 ms** | 814.206 ms | 774.202 ms | 914.101 ms |
| 本 preset 的 `jspace.py` | **781.112 ms** | 780.362 ms | 749.431 ms | 836.777 ms |

在完整携带 V3.6 控制器逻辑、严格 verifier 与中英文验证词表的前提下，本
preset 中位生命周期仍快约 **2.4%**。

### Adapter 冷解析（pi 适配 vs 本 preset）

对两个 adapter 入口执行 `node --check`，20 轮：

| 条件 | 中位数 | 均值 | 字节数 |
|---|---:|---:|---:|
| pi 适配（`tonyxu721/pi-j-space`） | 206.535 ms | 200.709 ms | 12 175 |
| 本 preset 的 `preset/j-space.mjs` | 205.755 ms | 212.285 ms | **10 852**（-10.9%） |

### 同模型协议对比（10 题，盲评）

同一模型、无工具、固定 rubric（每题正确性 0–2 + 验证覆盖 0–1，满分 30）。
上游通用协议 vs 本 preset 的强制门控/ledger：

| 条件 | 正确性 | 验证覆盖 | 总分 |
|---|---:|---:|---:|
| 上游通用协议 | 20 | 10 | **30/30** |
| Harness 强制协议 | 20 | 10 | **30/30** |

结论：**平局**——Harness 强制没有降低短确定性任务上的正确性与验证覆盖。
任务集刻意较短，不能据此宣称能力分层。

### 校验套件

- 上游 V3.6 回归测试：**18/18 通过**
- `verify_suite.py`（上游锚点 + 严格 frontmatter/路由）：**clean**
- `verify_harness.py`（Harness 适配层契约）：**clean**

### 复现

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

### 数据边界

工程数据描述本地 controller/adapter 行为，不是模型能力分数。同模型对比是
10 题的协议冒烟测试。provider 级 prompt 缓存命中率与长程持久性需要固定
provider/model、温度/seed、任务集与 token 遥测。

## 在 DSH 插件市场被发现

- **DSH 1024Store（自动收录）：** 流水线扫描带 `dsh-plugin` topic 的 GitHub
  仓库，并校验默认分支的 `package.json` + `dsh.bundle.patch` + patch 文件。
  本仓库全部满足；已发布且 repository backlink 一致的 npm 包使条目可通过
  受管路径安装。参见
  https://github.com/imsai-sh/awesome-deepseek-harness-plugins。
- **自定义标准来源：** 部署 `market/worker.mjs` 并注册
  `https://<worker>/catalog-source.json`。参见 `market/README.md`。
- **dshfind** 是第三方只读索引，收录由 dshfind 控制，与本仓库无关。

## 开发检查

```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
```

## 目录结构

```text
jspace-harness/
├── index.js                # 插件入口：首次启动把 preset/ 复制到 .agent-presets
├── cordis.patch.yml        # DSH bundle patch（市场安装器挂载插件行）
├── package.json            # npm 包：dsh.bundle.patch，无 lifecycle scripts
├── preset/                 # agent preset（agent.cordis.yml + j-space.mjs + skills/j-space）
│   └── skills/j-space/     # SKILL.md、9 个模块、references、jspace.py、双 verifier
├── market/                 # 可部署的 Cloudflare Worker 标准来源目录
├── benchmarks/             # 可复现的工程与协议对比数据
└── .github/workflows/      # CI：verifiers + 语法检查 + npm pack
```

## 归属

捆绑的 J-Space skill 衍生自
[J-Space Cognition Suite V3.6](https://github.com/Tiger3807861189/J-Space-Cognition-Suite-V3.6)。
参见 `THIRD_PARTY_NOTICES.md` 与 `LICENSE`。