dsh-brain-compaction

English  |  中文

dsh-brain-compaction — Human-brain-style context compaction, unified

Since 0.1.5 this targets DeepSeek Harness 0.1.5. See "DSH 0.1.5 compatibility" below.

A DeepSeek Harness plug-in (Cordis bundle) that composes seven community context-compression plug-ins into one coordinated, verifiable system — not a dependency collector:

DSH 0.1.5 compatibility

0.1.5 changed three runtime API shapes. Every one of them fails at module evaluation time (or fails silently), so a static contract test cannot see them — which is why this release also upgrades verification from "read the source" to "actually mount it".

Related adjustments:

• Dependency lines: dsh-argp moves to ^1.1.0 (its peerDependencies name ^0.1.5-rc.1, and it too moved to the 0.1.5 settings source thunk); peerDependencies becomes >=0.1.5-rc.1.
• dsh-compaction-instant is currently unusable: 0.1.4 still imports installSettingsSection / settingsNamespace, so enabling that row on 0.1.5 fails at startup. The patch keeps it disabled: true with a comment; switch engines once upstream ships a fix.
• Engine detection hardened: argp 1.1.0 also exports ArgpT1Engine, ArgpRecallEngine, and ArgpProbeEngine; all four class names now count as argp, and an unknown class name is named in the report instead of a generic FAIL.
• dsh.client.inject drops the removed dsh-client-runtime (and the unused connection).

Verification (new in 0.1.5)

npm run build       # esbuild bundles the host half; the client half is copied verbatim
npm run test        # 42 static contract checks (incl. 0.1.5 regression guards)
npm run test:mount  # 16 real-runtime mount checks (built artifact onto real cordis + ToolRuntime + SettingsProvider)
npm run test:client # 16 browser-half smoke checks (stub require really executes the factory)
npm run verify      # all of the above

test:mount needs a DSH installation to resolve @deepseek-ai/*: it probes $DSH_RUNTIME_ROOT → $DSH_HOME/profiles/node_modules → a few common paths and skips (exit 0) when none exists. It asserts what static analysis never can: the built artifact imports, the fiber really reaches ACTIVE, all three tools register, the settings namespace really registers and accepts a write, and brain_verify really reads 2 compaction summaries out of snapshotEvents().

Deep integration = composition + coordination, not dependencies

• Assemble: cordis.patch.yml mounts every component row through the Cordis composition mechanism (row insertion, package-name references, disabled overrides). The profile uses nodeLinker: hoisted, so sub-plugins listed as regular dependencies resolve by row name — no per-plugin dsh plugin add.
• Coordinate: src/host/integration.ts probes at runtime with zero imports — tool registry (ctx.tools.schemas()), services (ctx.get('compaction'), tokenMeter), engine class name. Any missing/disabled component degrades gracefully.
• Arbitrate: ctx.compaction allows exactly one implementation per context. argp and instant both register the tool recall (duplicates throw), so the patch keeps exactly one engine row enabled (argp by default); brain_verify validates this.
• One panel: Settings → Plugins → Brain Compaction binds multiple settings namespaces (this plug-in + compaction-instant + headroom) in one card; writes still go through each plug-in’s native scope (schema-validated, live-applied).
• Routing chain (We-Need): dsh-routing-suite is a host row — zero extra LLM calls; it regex-classifies the first user task (fix/diagnose/review → inspect-first; build/create/implement → direct) and appends one ~90-char guidance line, but only for sessions whose preset id is exactly routing-suite. Deep integration: mounted under the unique id brain-routing-suite (status API and strategy surface stay available), and the same We-Need discipline is baked into the brain preset persona (always-on for any first task, no id check). The honest token story: direct tasks skip redundant exploration, maintenance tasks never skip root cause — fewer wasted turns, less context growth; it does NOT lower per-request injection cost. If you previously installed the standalone bundle, remove it before using this assembly.

Install

One-liner (recommended):

dsh plugin --profile web add "github:Lsc-91-69/dsh-brain-compaction"
# restart dsh web (stop it and start again, or use the GUI's restart control)

From a source checkout:

git clone https://github.com/Lsc-91-69/dsh-brain-compaction
dsh plugin --profile web add "file:<path-to-the-clone>"
# restart dsh web

Use the file: (or github:) spec, never link: — a link: spec does not install this package's sub-plug-in dependencies and the composed rows would fail to resolve. For iterative development you may link: and pnpm install the sub-deps yourself. Ship the built lib/ either way.

Verify the install (2 minutes)

1. Restart dsh web — the profile composes its plugin rows at boot; a running process never hot-loads a new bundle.

2. Check the composed tree (no server started, read-only):

   dsh --profile web --dump-config | Select-String 'brain-|compaction'
   

   Expected: dsh-brain-compaction ENABLED, dsh-argp ENABLED, compaction-basic disabled (this bundle's patch turns the stock summarizer off), brain-compaction-instant / brain-tool-recall / brain-command-recall disabled (engine exclusivity), and brain-memory-vault / brain-mcp-lens / brain-routing-suite ENABLED.

3. Ask the model to run brain_verify in a fresh session. A healthy install reports engine: ArgpGraphEngine and PASS for argp / memory-vault / mcp-lens / routing-suite; instant / headroom / sgme / context-doctor are SKIP by design.

4. Open Settings → Plugins — the "Brain Compaction" card is contributed by this plug-in's browser half. (That tab renders the intersection of the namespaces the Host serves and the cards the browser registered, so a missing card means the Host half did not mount — check the host log for an import error.)

Troubleshooting a fresh install

• The requested module '@deepseek-ai/dsh-settings' does not provide an export named 'installSettingsSection' → you are on a pre-0.1.5-dsH release. This version (0.1.5) targets DSH 0.1.5-rc.1+; upgrade both sides.
• tool "recall" is already registered → argp and instant are both enabled; restore engine exclusivity (see "Engine switching").
• Duplicate row id → a sub-plug-in was also added as its own bundle; run dsh plugin --profile web remove <name> and keep this bundle's assembly.
• The profile cannot resolve dsh-brain-compaction → re-run dsh plugin --profile web install; the dependency must be present in the profile's own node_modules.

Optional component (Context Doctor — GitHub-only, not published to npm):

dsh plugin --profile web add "github:Zhenyu98/dsh-context-doctor#main"

Install from GitHub & distribution

# any machine (append #v0.1.5 to pin a release)
dsh plugin --profile web add "github:<your-name>/dsh-brain-compaction"
# restart dsh web

This works because the repository root IS the package: package.json, lib/, src/, preset/, scripts/, test/ all sit at the top level beside the README. pnpm resolves a github: spec by packing the repo root, so a layout that nests the package one level down (e.g. repo/<name>/package.json) fails with "no package.json" — verified against real GitHub tarballs: a subdirectory layout yields a root containing only README.md and the subdirectory, and pnpm has nothing to pack.

• The repo must contain lib/ (build artifacts) — a GitHub install uses the repo as-is and does not build; contract test 5d guards this.
• Installing pulls the sub-plug-in dependencies automatically (npm versions resolve by row name under nodeLinker: hoisted); do NOT dsh plugin add any sub-plug-in separately (duplicate row ids).
• For local development use file: (or link: + pnpm install the sub-deps).
• Run npm run verify before publishing: build + 42 contract assertions + 16 real-runtime mount assertions + 16 browser-half assertions. The mount suite needs a DSH install to resolve @deepseek-ai/* (it probes $DSH_RUNTIME_ROOT → $DSH_HOME/profiles/node_modules → each parent directory's node_modules) and skips cleanly when none exists.

The agent preset ships along: the validated 人脑式上下文压缩 preset lives in preset/ (compression-discipline persona + session-level argp engine row). Copy it to $DSH_HOME/.agent-presets/brain-compaction/; see preset/README.md.

Release checklist: git init, commit everything (.gitignore excludes node_modules/; commit lib/, preset/, src/, scripts/, test/, cordis.patch.yml, READMEs, LICENSE), tag v0.1.5, then dsh plugin --profile web add "github:<you>/dsh-brain-compaction#v0.1.5".

In a fresh session ask the model to run brain_verify — component matrix (PASS/SKIP/FAIL), session token snapshot, recent compaction history, and the context_audit hook, all in one report.

Engine switching (argp ↔ instant ↔ headroom)

Edit the plug-in’s cordis.patch.yml (or override its rows in your own profile patch): set disabled: true on the currently enabled engine row, remove disabled from the target row (instant also needs brain-tool-recall and brain-command-recall enabled), restart.

Session-level engine: the 人脑式上下文压缩 preset places its engine row inside the per-session compaction realm in agent.cordis.yml (default dsh-argp) — that row is the engine brain-preset sessions actually use; the host-level engine row serves presets without their own compaction group. Keep the two planes consistent when switching (the preset already replaced compaction-basic with dsh-argp for you).

Verification (before/after token comparison)

1. Call brain_verify (summary): engine state + component matrix + current tokens + recent compaction/summary leaf fields (shadowed/checkpoint). (This used to report nothing on 0.1.5 — session.events was removed; it now reads session.snapshotEvents().)
2. If Context Doctor is installed, call context_audit: per-item token cost of AGENTS.md chain / skill catalog / tool schemas / MCP surface, duplicates and conflicts (per-request injection; compaction shrinks the conversation, not this baseline).
3. Run two manual compactions (/compact), then brain_verify again and compare sessionTokens and the compaction history — that is the before/after Token delta.
4. brain_status for arbitrary snapshots; brain_recall(seq|query) for unified recovery of pruned content.
5. Three shipped suites (npm run verify): test/contract.test.mjs (42 static contract assertions), test/mount.test.mjs (16 real-runtime mount assertions), test/client.test.mjs (16 browser-half smoke assertions).

Config matrix

Layout

src/host/index.ts       entry (settings soft-dependency registration, tools, events, boot self-check)
src/host/config.ts      unified config (brain-compaction namespace + schema; settings package is type-only)
src/host/integration.ts component matrix / engine arbitration / verify / unified recall
src/client.js           unified settings panel (verbatim ModuleLoader factory; platform word dsh-client-store)
cordis.patch.yml        assembly: component rows + engine exclusivity + basic disabled
scripts/build.mjs       esbuild packaging (src/host/*.ts → lib/*; falls back to the official CLI on EPERM)
test/contract.test.mjs  static contract tests (42, incl. 0.1.5 regression guards)
test/mount.test.mjs     real-runtime mount tests (16; needs a DSH install, else skipped)
test/client.test.mjs    browser-half smoke tests (16; no browser needed)

Development

npm run build       # esbuild host + verbatim client copy
npm run test        # static contract tests (42)
npm run test:mount  # real-runtime mount tests (16; skipped without a DSH install)
npm run test:client # browser-half smoke tests (16)
npm run verify      # all of the above

Troubleshooting

• Boot error tool "recall" is already registered: argp and instant are both enabled — restore engine exclusivity.
• Boot error duplicate row id: a sub-plug-in was previously added as its own bundle (dsh plugin --profile web remove <name>, keep this bundle’s assembly).
• Boot error The requested module '@deepseek-ai/dsh-settings' does not provide an export named 'installSettingsSection': you are on a pre-0.1.5 version (that one only targets 0.1.0-rc.x). Upgrade to 0.1.5+.
• Startup fails after enabling the instant engine: dsh-compaction-instant@0.1.4 is not 0.1.5-compatible (same removed exports). Keep that row disabled: true, or wait for an upstream release.
• The "Brain Compaction" card is missing from Settings → Plugins: either the host half did not mount (the host log carries the import error), or the host brain-compaction namespace failed to register — on 0.1.5 the plug-in configuration tab only renders the intersection of namespaces the Host serves and card keys registered, so a failed registration means no card (this is not a rendering bug). npm run test:mount answers this directly.
• brain_verify engine FAIL naming a class not in the engine table: the ctx.compaction implementation is new. If it is another argp assembly, add the class name to ENGINE_CLASS_MAP in src/host/integration.ts.
• brain_verify engine FAIL with no class name: something re-enabled compaction-basic or preempted the engine.
• A section is missing from the panel: that plug-in’s row is disabled by default (see table); enable and restart.

License

MIT. Sub-plug-ins keep their own licenses (dsh-argp MIT, dsh-compaction-instant MIT, dsh-memory-vault MIT, @wanyantiande/dsh-headroom MIT, dsh-mcp-lens MIT/EULA, dsh-sgme MIT, dsh-context-doctor BSD-3-Clause).

---

English  |  中文

人脑式上下文压缩逻辑 · dsh-brain-compaction

0.1.5 起适配 DeepSeek Harness 0.1.5。 详见下方「DSH 0.1.5 适配」。

一个 DeepSeek Harness 插件（Cordis bundle）。它不是"Hell World 依赖收集器"，而是把 社区里七个人脑式上下文压缩方向的插件组装成一个统一、协同、可验证的体系：

DSH 0.1.5 适配

0.1.5 把三处运行时 API 形状改了。它们全都是"模块求值期直接抛错/静默失效"级别， 静态契约测试看不见——所以本版本除了改代码，还把验证方式从"读源码"升级成"真挂载"。

连带调整：

• 依赖线：dsh-argp 提到 ^1.1.0（其 peerDependencies 明确 ^0.1.5-rc.1，且自身也 改用 0.1.5 的 settings 源 thunk）；peerDependencies 改为 >=0.1.5-rc.1。
• dsh-compaction-instant 暂不可用：0.1.4 仍 import { installSettingsSection, settingsNamespace } ——在 0.1.5 上该行一旦启用即启动失败。patch 里保持 disabled: true 并留注释；等上游适配后再切引擎。
• 引擎识别加固：argp 1.1.0 除 ArgpGraphEngine 外还导出 ArgpT1Engine/ArgpRecallEngine/ ArgpProbeEngine，四个类名都认作 argp；未知类名会在报告里点名，而不是笼统 FAIL。
• dsh.client.inject 清掉已删除的 dsh-client-runtime（顺带移除未使用的 connection）。

验证方式（0.1.5 新增）

npm run build      # esbuild 打包 host + 逐字复制 client
npm run test       # 42 项静态契约（含 0.1.5 回归守卫：禁止改回已删除的 API 形状）
npm run test:mount # 16 项真实运行时挂载（把构建产物挂到真的 cordis + ToolRuntime + SettingsProvider）
npm run test:client# 16 项浏览器半区烟雾（桩 require 真的把 factory 跑一遍）
npm run verify     # 以上全部

test:mount 需要一个 DSH 安装来解析 @deepseek-ai/*：按 $DSH_RUNTIME_ROOT → $DSH_HOME/profiles/node_modules → 若干常见路径 依次探测，都没有则跳过（exit 0）。 它断言的是静态测试永远看不见的东西：构建产物可 import、fiber 真的 ACTIVE、三个工具 真的注册、settings namespace 真的注册且写入生效、brain_verify 真的从 snapshotEvents() 里读出了 2 条压缩历史。

深度融合 = 组合 + 协调，而不是依赖

• 组装：cordis.patch.yml 用 Cordis 组合机制（insert 行、包名引用、disabled 覆盖） 把全部组件行一次装入 profile 组合树；profile 用 nodeLinker: hoisted，所以子插件 作为本 bundle 的 dependencies 可被 loader 直接按行名解析（无需逐个 dsh plugin add）。
• 协调：src/host/integration.ts 运行时零 import 探测——工具注册表 (ctx.tools.schemas())、服务 (ctx.get('compaction') / tokenMeter)、引擎类名 判定当前激活引擎；任何组件缺失/禁用都优雅降级，不会崩。
• 互斥仲裁：ctx.compaction 每上下文只允许一个实现。argp 与 instant 都会注册 工具 recall（重名即抛错），因此 patch 里恰好一个引擎行启用（默认 argp）； brain_verify 会校验这一点。
• 统一面板：Settings → Plugins → 人脑式上下文压缩。一张卡片绑定多个 settings namespace（本插件 + compaction-instant + headroom），哪些在场就渲染哪些小节； 写入仍走各插件原生 scope（schema 校验 + live 生效）。
• 路由思维链（We-Need）：dsh-routing-suite 是 host 行——0 次额外 LLM 调用, 用正则对首条用户任务分类（修复/排查/审查→检查优先；新建/实现→直接执行并验证）, 仅在预设 id 恰为 routing-suite 的会话注入一句约 90 字符的引导。深度融合 = 本插件用自研 id brain-routing-suite 挂载它（状态 API/策略面可用）, 且把同一套 We-Need 纪律固化进 brain 预设的 persona（任何首任务常驻生效, 不依赖 id 判断）。 token 节省的真实机理：直接任务免去无谓探索, 维护任务避免跳过根因——减少返工轮次 与上下文生长; 它不改变注入物的常驻成本, 请勿夸大。 若你在此前单独安装过 dsh-routing-suite, 请先移除独立 bundle 再使用本插件的组装。

安装

一条命令（推荐）：

dsh plugin --profile web add "github:Lsc-91-69/dsh-brain-compaction"
# 重启 dsh web（dsh web 停掉再起, 或使用 GUI 的重启控件）

从源码目录安装：

git clone https://github.com/Lsc-91-69/dsh-brain-compaction
dsh plugin --profile web add "file:<克隆下来的目录路径>"
# 重启 dsh web

用 file:（或 github:）规格，不要用 link:——link: 不安装本包的子插件 依赖，组装行会解析失败。开发迭代时可以 link: 并自行 pnpm install 子依赖。 两种方式都依赖仓库里已提交的 lib/ 构建产物。

安装后验证（约 2 分钟）

1. 重启 dsh web：profile 在启动时组合插件行，运行中的进程不会热加载新 bundle。

2. 核对组合树（不启服务，只读）：

   dsh --profile web --dump-config | Select-String 'brain-|compaction'