billion-context-dsh 0.2.11 → 0.2.12

package/README.en.md

@@ -3,7 +3,7 @@
 [English](./README.en.md) | [中文](./README.md)
 
 > **⚠️ Beta notice — not for production use**
-> This project (**v0.2.11**) is a work-in-progress beta. The [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) itself is also in **public beta**. **Do not use either in engineering / production environments** — expect breaking changes and rough edges.
+> This project (**v0.2.12**) is a work-in-progress beta. The [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) itself is also in **public beta**. **Do not use either in engineering / production environments** — expect breaking changes and rough edges.
 
 <p align="center">
 <strong>Built with gratitude on top of these projects</strong> — please give them a ⭐:
@@ -53,25 +53,53 @@ This is the DeepSeek Harness port of [billion-context-pi](https://github.com/ran
 
 > 💡 **Want DeepSeek Harness to install it for you?** This repo itself runs on DSH: hand [docs/INSTALL.md](docs/INSTALL.md) to an agent in a session and it will read the guide, inspect your profile, wire the composition, and verify the mount. Two preconditions: ① the config lives under `~/.dsh`, so you approve one file-permission prompt; ② afterwards ask it to call `acp_status` as proof.
 
+**Path A (recommended): one-command install via the DSH store / `dsh plugin` (bundle) — globally active right after install, zero configuration.**
+
+Click install in DSH's plugin store, or run:
+
 ```bash
-npm install billion-context-dsh
+dsh plugin --profile web add billion-context-dsh
 ```
 
-> 💡 **One-command install via `dsh plugin` (bundle, v0.2.0+)**. The package declares a `dsh.bundle`
-> manifest, so DSH's plugin command installs it into the profile and applies the patch
-> automatically (equivalent to the composition row below):
+The command installs the package and automatically layers this package's bundle patch ([cordis.patch.yml](cordis.patch.yml)) into the profile's composition. The patch does two things:
+
+- **Disables the host `compaction-basic`** — so two backends do not both register `ctx.compaction` in the same realm (modern DSH web bundles already ship this disable; the row is an idempotent safety net that holds on every supported DSH);
+- **Mounts the ACP engine at the HOST plane** — the four model tools (`compress` / `decompress` / `search_context` / `acp_status`), the `/acp` command, the advisory nudge, and the ACP guidance section reach **EVERY mode** of the profile (standard / code / minimal / cordis / custom presets). Window auto-detection and the tools/command/nudge defaults are all on — **no manual configuration needed**.
+
+Restart `dsh` afterwards (bundle layers are composed at startup), open a new session, and verify: ask the model to call `acp_status`, or run `/acp status`. Shipped presets (standard / code / cordis) keep their realm-local `compaction-basic` fallback (automatic pressure compression still runs there; the ACP tools and nudge coexist); minimal and presets without a compaction realm use this engine directly.
+
+> **DSH version compatibility.** The package declares the peer range
+> `^0.1.0-rc.6 || ^0.1.1-rc.1` for `@deepseek-ai/dsh-compaction`, covering both the
+> `0.1.0-rc.x` and `0.1.1-rc.x` release lines (including the current DSH release;
+> the seam's `src/` is unchanged from `0.1.0-rc.6` to `0.1.1-rc.2`, so the public
+> API is identical). The range is two `||` clauses **on purpose**: npm
+> (node-semver) only lets a prerelease version satisfy a range that carries a
+> comparator on the SAME `[major, minor, patch]` tuple as the candidate, so a lone
+> `^0.1.0-rc.6` can never match `0.1.1-rc.x` (issue #68) — older releases fail to
+> install on DSH 0.1.1-rc.x; upgrade to a release containing this fix.
+
+**Path B: plain `npm install` (package only — a composition row is required).**
 
 ```bash
-dsh plugin --profile web add billion-context-dsh
+npm install billion-context-dsh
 ```
 
-Restart `dsh` afterwards (bundle layers are composed at startup). For custom `config`
-(such as `modelContextLimit` / `prompts`), keep the hand-written composition row — the
-bundle patch ([cordis.patch.yml](cordis.patch.yml)) only inserts the default row without `config`.
+This only installs the package into your project/global store; it does **not** touch any profile — add a composition row as shown below or the engine never mounts.
 
-That's it. Then add a composition row where a compaction backend is expected — two scopes, pick by how wide you want it:
+## Scope & customization
+
+Two audiences: ① Path B (plain npm install) users, who must write a composition row; ② Path A users who want custom `config` (the bundle already ships sane defaults — override them with a SAME-ID row).
+
+**Custom `config` (Path A bundle users).** Append a `compaction-acp` row with `config:` to your profile patch (e.g. `~/.dsh/profiles/web/cordis.patch.yml`) — the same-id row overrides the bundle's default row:
+
+```yaml
+- id: compaction-acp
+  name: 'billion-context-dsh'
+  config:
+    modelContextLimit: 128000   # optional; omit to auto-detect the model's real window (fallback 128000)
+```
 
-**Global — host plane, every mode** (recommended). In your profile patch (e.g. `~/.dsh/profiles/web/cordis.patch.yml`), add:
+**Global — host plane, every mode** (recommended). This is what Path A's bundle already does; plain-npm users add all of the following (bundle users skip the first two rows):
 
 ```yaml
 # ACP as the global compaction backend: four model tools + `/acp` command +
@@ -79,6 +107,7 @@ That's it. Then add a composition row where a compaction backend is expected —
 # (standard / code / minimal / cordis / custom presets).
 # Must also disable the host compaction-basic: two backends providing
 # `ctx.compaction` in the same realm collide.
+# (The bundle install already ships these two rows.)
 - id: compaction-basic
   disabled: true
 

package/README.md

@@ -3,7 +3,7 @@
 [中文](./README.md) | [English](./README.en.md)
 
 > **⚠️ 测试版声明——请勿用于生产环境**
-> 本项目（**v0.2.11**）仍处于开发中的测试版。[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 本身也处于**公开测试版**阶段。**请勿将两者用于工程化 / 生产环境**——预期会有破坏性变更与粗糙之处。
+> 本项目（**v0.2.12**）仍处于开发中的测试版。[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 本身也处于**公开测试版**阶段。**请勿将两者用于工程化 / 生产环境**——预期会有破坏性变更与粗糙之处。
 
 <p align="center">
 <strong>衷心感谢以下项目——请给它们一个 ⭐：</strong>
@@ -56,30 +56,58 @@
 > 你的 profile、编辑组合配置并验证挂载。前提：① 配置写在 `~/.dsh` 下，需要
 > 你批准一次文件权限；② 装完让它调用 `acp_status` 自证。
 
+**方式一（推荐）：DSH 商店 / `dsh plugin` 一键装（bundle）——装完即全局生效，零配置。**
+
+在 DSH 的插件商店里点安装，或命令行执行：
+
 ```bash
-npm install billion-context-dsh
+dsh plugin --profile web add billion-context-dsh
 ```
 
-> 💡 **v0.2.0 起支持 `dsh plugin` 一键安装（bundle）**。包已声明 `dsh.bundle`
-> manifest，DSH 的插件命令会把它装进 profile 并自动应用补丁（等价于下面的组合行）：
+命令内部会装包并把本包的 bundle 补丁（[cordis.patch.yml](cordis.patch.yml)）自动挂进该 profile 的层栈。补丁做了两件事：
+
+- **禁用 host 的 `compaction-basic`**——避免同一 realm 内两个后端同时注册 `ctx.compaction` 冲突（现代 DSH 的 web bundle 已自带该禁用，此行为幂等兜底，任何受支持版本下都成立）；
+- **把 ACP 引擎挂到 host 平面**——四种模型工具（`compress` / `decompress` / `search_context` / `acp_status`）、`/acp` 命令、nudge、ACP 提示词段对该 profile 的**所有模式**（standard / code / minimal / cordis / 自定义预设）生效。窗口自动探测、工具/命令/nudge 默认全开，**无需任何手工配置**。
+
+装完**重启 `dsh`**（bundle 层在启动时组合），新开会话即可用——让模型调用 `acp_status` 或执行 `/acp status` 自证。shipped 预设（standard / code / cordis）内部的 realm 级 `compaction-basic` 自动压缩兜底仍然保留（这些模式里"自动摘要"照旧，ACP 工具与 nudge 并存）；minimal 等不带 compaction realm 的预设直接使用本引擎。
+
+> **与 DSH 版本的兼容性。** 包声明 peer 依赖 `@deepseek-ai/dsh-compaction` 为
+> `^0.1.0-rc.6 || ^0.1.1-rc.1`，同时覆盖 `0.1.0-rc.x` 与 `0.1.1-rc.x` 两条 rc 线
+> （含当前最新 DSH release；从 `0.1.0-rc.6` 到 `0.1.1-rc.2`，seam 的 `src/` 源码
+> 零改动，公开 API 完全一致）。范围写成两个并集子句是**有意为之**：npm
+> （node-semver）的预发布匹配规则要求 range 里存在与候选版本**相同
+> `[major, minor, patch]` 元组**的比较器，单一 `^0.1.0-rc.6` 永远匹配不了
+> `0.1.1-rc.x`（issue #68）——因此旧发布的包在 DSH 0.1.1-rc.x 上装不上，
+> 升级到含本次修复的新版本即可。
+
+**方式二：纯 `npm install`（只装包，需要手写组合行）。**
 
 ```bash
-dsh plugin --profile web add billion-context-dsh
+npm install billion-context-dsh
 ```
 
-装完重启 `dsh`（bundle 层在启动时组合）。需要自定义 `config`（如
-`modelContextLimit` / `prompts`）时仍建议手写组合行——bundle 补丁
-（[cordis.patch.yml](cordis.patch.yml)）只插入无 `config` 的默认行。
+这只把包装进你的项目/全局，**不会**触碰任何 profile——请按下方「两种生效范围与自定义」手写组合行，引擎才会挂载。
 
-就这样。然后在需要压缩后端的位置加组合配置——两种范围，按需选择：
+## 两种生效范围与自定义
+
+本节服务于两类人：① 方式二（纯 npm 安装，必须手写组合行）；② 方式一用户想自定义 `config`（bundle 已有默认行为，只需用**同 id** 行覆盖）。
+
+**自定义 config（方式一 bundle 用户）。** 在你的 profile 补丁（如 `~/.dsh/profiles/web/cordis.patch.yml`）里追加一个 `compaction-acp` 行并附 `config:`——同 id 行覆盖 bundle 的默认行：
+
+```yaml
+- id: compaction-acp
+  name: 'billion-context-dsh'
+  config:
+    modelContextLimit: 128000   # 可选；省略时自动探测模型真实窗口（回退 128000）
+```
 
-**全局生效（host 平面，所有模式）——推荐**。在你的 profile 补丁（如 `~/.dsh/profiles/web/cordis.patch.yml`）中追加：
+**全局生效（host 平面，所有模式）——推荐**。这是方式一 bundle 的默认行为；纯 npm 安装的用户在 profile 补丁中追加以下全部内容（bundle 用户跳过前两行）：
 
 ```yaml
 # ACP 作为全局压缩后端：四个模型工具 + `/acp` 命令 + nudge + ACP 提示词段，
 # 对所有模式（standard / code / minimal / cordis / 自定义预设）生效。
 # 必须同时禁用 host 的 compaction-basic：同一 realm 内两个后端同时
-# provide `ctx.compaction` 会冲突。
+# provide `ctx.compaction` 会冲突。（bundle 安装已自动带上这两行。）
 - id: compaction-basic
   disabled: true
 

package/cordis.patch.yml

@@ -1,11 +1,32 @@
-# dsh bundle patch: inserts the ACP compaction backend into a profile's layer stack.
+# dsh bundle patch: makes billion-context-dsh ACTIVE right after a one-command
+# install — the plugin store and `dsh plugin --profile web add
+# billion-context-dsh` both run the same command, and this file (declared in
+# package.json as `dsh.bundle.patch`) becomes a layer of the profile's
+# composition automatically. No manual configuration is needed.
 #
-# This is what makes the package installable via `dsh plugin --profile web add
-# billion-context-dsh` (declared in package.json as `dsh.bundle.patch`). The row
-# below is exactly the manual composition row documented in docs/INSTALL.md (§2a),
-# minus config: omitting `modelContextLimit` means auto-detection (fallback 128000),
-# and the built-in prompt copy (config.prompts) is used. Users who want custom
-# config can still write the row by hand in their profile patch.
+# Two rows land in the profile's composition root:
+#   1. `compaction-basic` disabled — the host's own auto-compaction backend
+#      would otherwise register `ctx.compaction` at the root realm too, and
+#      only one provider per realm may own that service name. (On dsh
+#      0.1.0-rc.6+ the web-app bundle already ships this disable; the row is
+#      idempotent and keeps the plugin self-sufficient on every supported DSH.)
+#   2. `compaction-acp` — the ACP engine, mounted at the HOST plane, so its
+#      model tools (`compress`, `decompress`, `search_context`, `acp_status`),
+#      the `/acp` command, the advisory nudge, and the guidance section reach
+#      EVERY mode (standard / code / minimal / cordis / custom presets) of the
+#      profile the plugin was installed into.
+#
+# No `config` is set on purpose: the context window is auto-detected from the
+# model API (fallback 128000) and the built-in prompt copy is used. Users who
+# want custom config write a SAME-ID `compaction-acp` row in their profile's
+# own `cordis.patch.yml` — it overrides this row (see README).
+#
+# Shipped presets (standard / code / cordis) keep their realm-local
+# compaction-basic fallback (automatic pressure compression); minimal and
+# presets without a compaction realm use the host ACP engine directly.
+- id: compaction-basic
+  disabled: true
+
 - insert:
     - id: compaction-acp
-      name: 'billion-context-dsh'
+      name: 'billion-context-dsh'

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "billion-context-dsh",
-	"version": "0.2.11",
+	"version": "0.2.12",
 	"description": "Active Context Pruning (ACP) for the DeepSeek Harness — model-driven context management as a CompactionEngine backend.",
 	"keywords": [
 		"deepseek",
@@ -47,7 +47,7 @@
 	},
 	"peerDependencies": {
 		"@deepseek-ai/cordis": "^4.0.1",
-		"@deepseek-ai/dsh-compaction": "^0.1.0-rc.6"
+		"@deepseek-ai/dsh-compaction": "^0.1.0-rc.6 || ^0.1.1-rc.1"
 	},
 	"devDependencies": {
 		"acp-kernel": "0.0.29",
@@ -62,6 +62,7 @@
 		"@deepseek-ai/dsh-tools": "0.1.0-rc.6",
 		"@deepseek-ai/schemastery": "3.18.1",
 		"@types/node": "^26.1.2",
+		"semver": "^7.7.1",
 		"tsup": "^8.5.1",
 		"tsx": "^4.23.1",
 		"typescript": "^7.0.2"