billion-context-dsh 0.1.9 → 0.2.1

package/README.en.md

@@ -3,7 +3,7 @@
 [English](./README.en.md) | [中文](./README.md)
 
 > **⚠️ Beta notice — not for production use**
-> This project (**v0.1.9**) 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.1**) 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 ⭐:
@@ -56,6 +56,18 @@ This is the DeepSeek Harness port of [billion-context-pi](https://github.com/ran
 npm install 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):
+
+```bash
+dsh plugin --profile web add 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`.
+
 That's it. Then add a composition row where a compaction backend is expected — two scopes, pick by how wide you want it:
 
 **Global — host plane, every mode** (recommended). In your profile patch (e.g. `~/.dsh/profiles/web/cordis.patch.yml`), add:
@@ -76,19 +88,19 @@ That's it. Then add a composition row where a compaction backend is expected —
         modelContextLimit: 128000   # optional; omit to auto-detect the model's real window (fallback 128000)
 ```
 
-**(Optional) Custom prompt copy — `config.prompts`.** Every model-visible prompt (normal/emergency nudge opener, tier line, range table, the ACP system-prompt section, the four tool descriptions) ships with built-in copy that you can override per slot through the composition row's `config`. Templates support named placeholders (e.g. `{pct}` for nudges, `{surface}` for the range table) and are **validated at construction**: a misspelled placeholder fails engine startup (fail-fast) instead of leaking a literal `{pct}` into the model context:
+**(Optional) Custom prompt copy — `config.prompts`.** Every model-visible prompt (normal/emergency nudge opener, context breakdown, growth line, batch tip, tier line, range table, the ACP system-prompt section, the four tool descriptions) defaults to **acp-kernel's own `renderNudgeText`** — the efficiency note, context breakdown, compression rules, and batch tip all come from the kernel verbatim; only the range table is swapped for the surface-seq version (the kernel uses mNNNNN refs, and DSH has no `<acp>` tags). Overriding any nudge slot switches to template rendering. Templates support named placeholders (e.g. `{pct}` and `{philosophy}` for nudges, `{surface}` for the range table) and are **validated at construction**: a misspelled placeholder fails engine startup (fail-fast) instead of leaking a literal `{pct}` into the model context:
 
 ```yaml
       config:
         modelContextLimit: 128000
         prompts:
           nudge:
-            normal: 'Context usage is at {pct}%. This is a suggestion, not a requirement — you decide.'  # custom nudge opener
+            normal: 'This is an efficiency nudge to compress early and keep context lean.'  # custom nudge opener
           tools:
             acpStatus: 'Report the ACP block ledger: compressed blocks, reclaimed tokens, and current context pressure.'  # custom tool description
 ```
 
-See [docs/configurable-prompts-design.md](docs/configurable-prompts-design.md) for the full slot list, per-slot placeholders, and the empty-string/`null` semantics. Deployments that omit `prompts` behave exactly as before (default copy byte-identical).
+See [docs/configurable-prompts-design.md](docs/configurable-prompts-design.md) for the full slot list, per-slot placeholders, and the empty-string/`null` semantics. Deployments that omit `prompts` use the kernel rendering directly (aligned with kernel/pi; see design doc v6).
 
 **Per-mode — an agent preset's `compaction` realm.** First *disable (or delete) the realm's existing `dsh-compaction-basic` row*, then mount this engine — two backends cannot coexist in the same realm:
 
@@ -114,14 +126,14 @@ DSH derives every model request from its append-only session log (the *surface*)
 |---|---|
 | `compress` tool shadows a range | durable `surfaceOp: { op: 'replace' }` — the model-written summary becomes a checkpoint node; the originals stay in the log |
 | refs (`m00001` tags) | surface seqs, carried by the nudge's compressible-range table |
-| nudge ("consider compressing") | injected at `agent/pre-step` by the kernel's pressure decision — a short advisory, never an order |
+| nudge ("efficiency note — compress early and keep context lean") | injected at `agent/pre-step` by the kernel's pressure decision — efficiency note + context breakdown + compression rules, tone aligned with kernel/pi; never an order |
 | `decompress` | read-only recovery of shadowed originals from the log |
 | `search_context` | scores block summaries + originals rebuilt from the log |
 | `acp_status` | block ledger + context pressure |
 | block state | in-memory kernel state + **log-rebuilt ledger** (no sidecar files) |
 | tiered distillation (T2/T3) | re-compressing a block's summary node distills that block (tier 2); distilling a tier-2 block yields tier 3. Tier + kernel block ids are persisted to the log, so kernel state rehydrates from the log after a restart and stays distillable |
 
-The load-bearing compression guidance (tools, philosophy, summary rules) is registered as a one-time system-prompt section, so nudges stay short. There is deliberately **no automatic summarization**: automatic policy only nudges the model (`compactIfNeeded` returns null).
+The load-bearing compression guidance (tools, philosophy, summary rules, tier rules) is registered as a one-time system-prompt section; each nudge carries a condensed version (efficiency note + philosophy + context breakdown + HOW_TO_COMPRESS_RULES + range table + batch tip). There is deliberately **no automatic summarization**: automatic policy only nudges the model (`compactIfNeeded` returns null).
 
 ## Video
 
@@ -190,6 +202,7 @@ src/
 ├── nudge.ts        # M4: kernel pressure decision → injected advisory nudge
 ├── system-prompt.ts# M4: one-time ACP guidance section (keeps nudges short)
 ├── config.ts       # kernel config assembly (thresholds + coreOverrides)
+├── window.ts       # auto context-window detection (LLM runtime probe, fallback 128000)
 └── commands.ts     # M4: /acp slash command
 ```
 

package/README.md

@@ -3,7 +3,7 @@
 [中文](./README.md) | [English](./README.en.md)
 
 > **⚠️ 测试版声明——请勿用于生产环境**
-> 本项目（**v0.1.9**）仍处于开发中的测试版。[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 本身也处于**公开测试版**阶段。**请勿将两者用于工程化 / 生产环境**——预期会有破坏性变更与粗糙之处。
+> 本项目（**v0.2.1**）仍处于开发中的测试版。[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 本身也处于**公开测试版**阶段。**请勿将两者用于工程化 / 生产环境**——预期会有破坏性变更与粗糙之处。
 
 <p align="center">
 <strong>衷心感谢以下项目——请给它们一个 ⭐：</strong>
@@ -59,6 +59,17 @@
 npm install billion-context-dsh
 ```
 
+> 💡 **v0.2.0 起支持 `dsh plugin` 一键安装（bundle）**。包已声明 `dsh.bundle`
+> manifest，DSH 的插件命令会把它装进 profile 并自动应用补丁（等价于下面的组合行）：
+
+```bash
+dsh plugin --profile web add billion-context-dsh
+```
+
+装完重启 `dsh`（bundle 层在启动时组合）。需要自定义 `config`（如
+`modelContextLimit` / `prompts`）时仍建议手写组合行——bundle 补丁
+（[cordis.patch.yml](cordis.patch.yml)）只插入无 `config` 的默认行。
+
 就这样。然后在需要压缩后端的位置加组合配置——两种范围，按需选择：
 
 **全局生效（host 平面，所有模式）——推荐**。在你的 profile 补丁（如 `~/.dsh/profiles/web/cordis.patch.yml`）中追加：
@@ -78,19 +89,19 @@ npm install billion-context-dsh
         modelContextLimit: 128000   # 可选；省略时自动探测模型真实窗口（回退 128000）
 ```
 
-**（可选）自定义提示词文案 —— `config.prompts`。** 所有模型可见的提示词（普通/紧急 nudge 首句、tier 蒸馏行、范围表、ACP system prompt 段、四个工具描述）默认是内置文案，可通过组合行的 `config` 按槽位覆盖。模板支持命名占位符（如 nudge 的 `{pct}`、范围表的 `{surface}`），**构造期校验**：占位符拼写错误会在引擎启动时抛错（fail-fast），而不是把字面 `{pct}` 漏进模型上下文：
+**（可选）自定义提示词文案 —— `config.prompts`。** 所有模型可见的提示词（普通/紧急 nudge 首句、上下文分解、增长行、批量提示、tier 蒸馏行、范围表、ACP system prompt 段、四个工具描述）默认**直接复用 acp-kernel 的 `renderNudgeText`**——效率提示、上下文分解、压缩规则、批量提示全部来自 kernel 原文，仅范围表换成 surface-seq 版（kernel 用 mNNNNN 引用，我们架构没有 `<acp>` 标签）。覆盖任一 nudge 槽位后自动切换到模板渲染。模板支持命名占位符（如 nudge 的 `{pct}`、`{philosophy}`、范围表的 `{surface}`），**构造期校验**：占位符拼写错误会在引擎启动时抛错（fail-fast），而不是把字面 `{pct}` 漏进模型上下文：
 
 ```yaml
       config:
         modelContextLimit: 128000
         prompts:
           nudge:
-            normal: '上下文使用率 {pct}%。这是建议而非命令——由你决定是否压缩。'  # 中文 nudge 首句
+            normal: '上下文使用率 {pct}%。这是效率提示——请尽早压缩保持上下文精简。'  # 中文 nudge 首句
           tools:
             acpStatus: '报告 ACP 块账本：压缩块数、回收 token、当前上下文压力。'  # 自定义工具描述
 ```
 
-可配置槽位清单、每槽可用占位符、空串/`null` 语义见 [docs/configurable-prompts-design.md](docs/configurable-prompts-design.md)。未配置 `prompts` 的部署行为与以往完全一致（默认文案逐字节不变）。
+可配置槽位清单、每槽可用占位符、空串/`null` 语义见 [docs/configurable-prompts-design.md](docs/configurable-prompts-design.md)。未配置 `prompts` 的部署直接使用 kernel 渲染（对齐 kernel/pi，见设计文档 v6）。
 
 **单模式生效（agent preset 的 `compaction` realm）**。先在该 realm 内*禁用（或删除）原有的 `dsh-compaction-basic` 行*，再插入本引擎——同一 realm 内两个后端不能并存：
 
@@ -116,14 +127,14 @@ DSH 的每个模型请求都派生自其 append-only 会话日志（*surface*）
 |---|---|
 | `compress` 工具遮蔽一段范围 | 持久化 `surfaceOp: { op: 'replace' }`——模型书写的摘要成为 checkpoint 节点；原文保留在日志中 |
 | refs（`m00001` 标签） | surface seq，由 nudge 的可压缩范围表携带 |
-| nudge（"考虑压缩一下"） | 由内核的压力决策在 `agent/pre-step` 注入——简短建议，绝非命令 |
+| nudge（"效率提示——尽早压缩保持精简"） | 由内核的压力决策在 `agent/pre-step` 注入——效率通知 + 上下文分解 + 压缩规则，语气对齐 kernel/pi；绝非命令 |
 | `decompress` | 从日志只读恢复被遮蔽的原文 |
 | `search_context` | 对从日志重建的块摘要与原文打分 |
 | `acp_status` | 块账本与上下文压力 |
 | 块状态 | 内存内核状态 + **日志重建账本**（无旁车文件） |
 | 分层蒸馏（T2/T3） | 再次压缩某块的摘要节点 = 蒸馏该块（tier 2），蒸馏 tier-2 块得 tier 3；tier 与内核块 id 持久化进日志，重启后内核状态从日志再水合、可继续蒸馏 |
 
-承载性的压缩指引（工具、哲学、摘要规则）注册为一次性系统提示段，因此 nudge 保持简短。刻意**不做自动摘要**：自动策略只 nudge 模型（`compactIfNeeded` 返回 null）。
+承载性的压缩指引（工具、哲学、摘要规则、tier 蒸馏/浓缩规则）注册为一次性系统提示段；每条 nudge 携带精简版（效率提示 + 哲学 + 上下文分解 + 压缩规则 + 范围表 + 批量提示）。刻意**不做自动摘要**：自动策略只 nudge 模型（`compactIfNeeded` 返回 null）。
 
 ## 视频讲解
 
@@ -192,6 +203,7 @@ src/
 ├── nudge.ts        # M4: 内核压力决策 → 注入的建议式 nudge
 ├── system-prompt.ts# M4: 一次性 ACP 指引段（让 nudge 保持简短）
 ├── config.ts       # 内核配置组装（阈值 + coreOverrides）
+├── window.ts       # 自动上下文窗口探测（LLM 运行时探测，回退 128000）
 └── commands.ts     # M4: /acp 斜杠命令
 ```
 

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# dsh bundle patch: inserts the ACP compaction backend into a profile's layer stack.
+#
+# 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.
+- insert:
+    - id: compaction-acp
+      name: 'billion-context-dsh'

package/dist/index.d.ts

@@ -30,10 +30,12 @@ import { CompactionEngine, type CompactionAgentContext, type CompactionResult, t
 import { type CompressionCore } from 'acp-kernel';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import { AcpStateStore } from './state.ts';
+import { type AcpPrompts, type ResolvedPrompts } from './prompts.ts';
 import { type AcpWindow } from './window.ts';
 export { AcpStateStore } from './state.ts';
 export { kernelConfigFor, type KernelConfigInput } from './config.ts';
 export { ACP_SYSTEM_PROMPT, ACP_SYSTEM_PROMPT_ORDER } from './system-prompt.ts';
+export { DEFAULT_PROMPTS, DEFAULT_RESOLVED, renderSystemPrompt, renderTemplate, resolvePrompts, type AcpPrompts, type NudgePrompts, type PromptInput, type PromptOverride, type RangeTablePrompts, type ResolvedPrompts, type ToolPrompts, } from './prompts.ts';
 export { makeTools, type ToolEnvironment } from './tools.ts';
 export { acpCommand } from './commands.ts';
 export { buildNudge, resolveTokenCount, type NudgeEnvironment, type NudgeOutcome } from './nudge.ts';
@@ -87,6 +89,8 @@ export interface AcpConfig {
     readonly autoCommand: boolean;
     /** Inject the nudge into `agent/pre-step` when the kernel recommends it. Default true. */
     readonly autoNudge: boolean;
+    /** Per-stage prompt template overrides (nudge / range table / system prompt / tool descriptions). See docs/configurable-prompts-design.md. */
+    readonly prompts?: AcpPrompts;
 }
 export declare function resolveAcpConfig(config?: Partial<AcpConfig>): AcpConfig;
 /**
@@ -101,6 +105,8 @@ export declare class AcpCompactionEngine extends CompactionEngine {
     readonly store: AcpStateStore;
     /** Resolved engine configuration. */
     readonly config: AcpConfig;
+    /** Resolved prompt templates (validated at construction — fail-fast on template typos). */
+    readonly prompts: ResolvedPrompts;
     private readonly lastNudgeTurn;
     /** Per provider/model route the resolved window (probe failures cached too). */
     private readonly windowCache;