billion-context-dsh

中文 | English

⚠️ Beta notice — do not use in production This project (v0.2.23) is still a beta under development. DeepSeek Harness itself is also in the public beta stage. Do not use either of them in engineered / production environments — breaking changes and rough edges are expected.

衷心感谢以下项目——请给它们一个 ⭐：
DeepSeek Harness · billion-context-pi · acp-kernel · opencode-acp

Billion-Context for DeepSeek Harness
由模型决定何时压缩、压缩什么——而不是一个硬性上限。

---

npm install billion-context-dsh

---

Why?

When conversations grow long, the model runs out of context. Most tools just hard-truncate — silently dropping early messages. billion-context-dsh gives the model a compress tool: the LLM decides when and what to compress, writing high-fidelity summaries that reclaim context space while preserving critical details (file paths, decisions, error messages).

Unlike DSH's built-in automatic compaction (which replaces a range with auto-generated summaries), billion-context-dsh:

• Model-driven — summaries are written by the model itself, with no second LLM summarization call
• Suggests only, never commands — the auto-policy only nudges; the model decides whether and when to compress
• Durable and recoverable — compressed ranges become checkpoint nodes; the original text is retained in the append-only session log; decompress can restore it, and search_context can search within blocks
• Stable on long tasks — each step builds on the previous one, key conclusions stay available and keep accumulating, making very long tasks more likely to complete
• Context always stays slim — every request uses only a small, refined context keeping just the key information; no large-scale blanket compaction, so details don't degrade with it, and token consumption stays naturally lower

This is a port of billion-context-pi (the Pi coding-agent adapter) onto DeepSeek Harness: the compaction kernel (acp-kernel) is reused as-is, and the adapter layer is rewritten for DSH's durable-surface model — see docs for the verified mappings.

Installation

💡 Want DeepSeek Harness to install it for you? This repo itself runs on DSH: hand docs/INSTALL.md to the agent in the session — it will read the guide, resolve your profile, edit the composition config, and verify the mount. Prerequisites: ① the config lives under ~/.dsh, which requires you to grant file permissions once; ② after install, have it call acp_status to prove it.

Method 1 (recommended): DSH Store / dsh plugin one-click install (bundle) — takes effect globally right after install, zero config.

Click install in the DSH plugin store, or run in the command line:

dsh plugin --profile web add billion-context-dsh

Internally the command installs the package and automatically attaches this package's bundle patch (cordis.patch.yml) into that profile's layer stack. The patch does two things:

• Disables the host's compaction-basic — to prevent two backends from registering ctx.compaction simultaneously within the same realm (modern DSH web bundles already ship with this disable; this is an idempotent safety net that holds on any supported version);
• Attaches the ACP engine to the host plane — the four model tools (compress / decompress / search_context / acp_status), the /acp command, the nudge, and the ACP prompt section take effect for all modes of that profile (standard / code / minimal / cordis / custom presets). Window auto-detection, tools/commands/nudge are on by default — no manual configuration needed.

After installing, restart dsh (the bundle layer is composed at startup), and it will be available in new sessions — have the model call acp_status or run /acp status to verify. The realm-level compaction-basic auto-compaction fallback inside shipped presets (standard / code / cordis) remains (in those modes "auto summarization" works as before, coexisting with the ACP tools and nudge); presets without a compaction realm, such as minimal, use this engine directly.

Compatibility with DSH versions. The package declares all five runtime seam packages (dsh-compaction / dsh-session / dsh-llm / dsh-tools / dsh-settings) as peer dependencies, sharing the same range >=0.1.5-alpha.1 <0.1.6-0 — exactly the entire 0.1.5 line (all prereleases plus the final 0.1.5). From the 0.1.5 line on, the protocol fields for session replace operations were renamed from { op, start, end } to { op, startSeq, endSeq }, with strict validation (only these three fields are accepted); this engine only emits the new shape, so on older DSH (< 0.1.5) every compress would be rejected by the host at runtime (issue #136) — older versions are no longer supported; please upgrade DSH before installing this release. The range is written as an explicit interval rather than a caret deliberately: a caret would silently pull in unverified 0.1.6+ lines. Declaring all five seam packages as peers (rather than just dsh-compaction) is to ensure that under pnpm's integrated/hoisted layout they still resolve to the host's own copies, rather than some stale nested copy that is inconsistent with the host.

Behavior note (from 0.1.5 on): the host no longer allows "invisible" replace nodes; when the engine cleans up orphaned tool messages, it leaves a short visible placeholder message in their place; the host's system-prompt node (surface node 0) is excluded from the compressible range table.

Method 2: plain npm install (package only, requires hand-writing the composition line).

npm install billion-context-dsh

This only adds the package to your project/global scope; it does not touch any profile. Hand-write the composition line (see below) for the engine to mount.

Git source install (the github: spec, the form shown in the plugin store). The prebuilt artifacts dist/ are committed to the repo, so installing from a git source is equally out-of-the-box — no build step required; pnpm 11's default blocking of build scripts (allowBuilds) does not obstruct this package:

dsh plugin --profile web add github:Tyan66666/billion-context-dsh#v0.2.23

Installing with #<tag> is recommended, giving you artifacts that are exactly identical to the corresponding npm version; without a ref, the latest build from the default branch is installed. Only building from source yourself by cloning the repo (npm run build) requires allowing builds. See docs/git-source-install-design.md (issue #92) for background and design trade-offs.

Scopes and Customization

This section serves two audiences: ① Method 2 (plain npm install, where the composition line must be hand-written); ② Method 1 users wanting to customize config (the bundle already has defaults; you only need to override with a line of the same id).

Customizing config (Method 1 bundle users). Append a compaction-acp line with a config: to your profile patch (e.g. ~/.dsh/profiles/web/cordis.patch.yml) — a line with the same id overrides the bundle's default line:

- id: compaction-acp
  name: 'billion-context-dsh'
  config:
    modelContextLimit: 128000   # 可选；省略时自动探测模型真实窗口（回退 128000）

Globally effective (host plane, all modes) — recommended. This is the default behavior of the Method 1 bundle; plain-npm-install users should append all of the following in their profile patch (bundle users skip the first two lines):

# ACP 作为全局压缩后端：四个模型工具 + `/acp` 命令 + nudge + ACP 提示词段，
# 对所有模式（standard / code / minimal / cordis / 自定义预设）生效。
# 必须同时禁用 host 的 compaction-basic：同一 realm 内两个后端同时
# provide `ctx.compaction` 会冲突。（bundle 安装已自动带上这两行。）
- id: compaction-basic
  disabled: true

- insert:
    - id: compaction-acp
      name: 'billion-context-dsh'
      config:
        modelContextLimit: 128000   # 可选；省略时自动探测模型真实窗口（回退 128000）

(Optional) Custom prompt wording — config.prompts. All model-visible prompts (normal/urgent nudge first lines, context breakdown, growth line, batch prompts, tier distillation lines, range table, ACP system prompt section, the four tool descriptions) by default directly reuse acp-kernel's renderNudgeText — efficiency prompts, context breakdown, compression rules, and batch prompts all come from the kernel's original text; only the range table is swapped to the surface-seq version (the kernel uses mNNNNN references; our architecture has no <acp> tags; the seq range table likewise carries [tool X% | text Y%] composition ratios and is sorted oldest-first, matching the kernel's display semantics). Overriding any nudge slot automatically switches to template rendering. Templates support named placeholders (e.g. {pct}, {philosophy} for the nudge, {surface} for the range table), with construction-time validation: a misspelled placeholder will throw an error at engine startup (fail-fast) instead of leaking a literal {pct} into the model context:

      config:
        modelContextLimit: 128000
        prompts:
          nudge:
            normal: '上下文使用率 {pct}%。这是效率提示——请尽早压缩保持上下文精简。'  # 中文 nudge 首句
          tools:
            acpStatus: '报告 ACP 块账本：压缩块数、回收 token、当前上下文压力。'  # 自定义工具描述

See docs/configurable-prompts-design.md for the list of configurable slots, the placeholders available per slot, and the semantics of empty-string/null. Deployments that do not configure prompts use kernel rendering directly (aligned with kernel/pi, see design doc v6).

(Optional) Runtime settings — edit ~/.dsh/settings.yaml or use /acp config, no restart required. The six scalar keys (modelContextLimit, autoModelContextLimit, nudgeMinContextLimitPct, nudgeMaxContextLimitPct, nudgeEmergencyThresholdPct, autoNudge; see the rows in the "Configuration" table marked "runtime hot-tunable") have a hot-reloadable copy in the host settings layer: editing the settings file or /acp config takes effect immediately on the running session (the composition line config: remains the starting point — layering is schema defaults → composition line → user settings section):

# ~/.dsh/settings.yaml
compaction-acp:
  nudgeMaxContextLimitPct: 0.72   # 保存即生效，无需重启

/acp config                                  # 列出六个键当前值 + 来源层（user / base / default）
/acp config set nudgeMaxContextLimitPct 0.72 # 热改一个键
/acp config set autoNudge false              # 布尔键（false 是合法值）
/acp config reset nudgeMaxContextLimitPct    # 退回组合行 / 引擎默认
/acp config reset all

Changes to window-related keys (modelContextLimit / autoModelContextLimit) clear the window detection cache — the next pre-step re-probes with the new values (a probe failure is also cached, which is exactly the mechanism that allows re-probing after the gateway is fixed). Under a plain-npm-install composition without a settings provider, /acp config degrades to guidance text; settingsEnabled: false turns off this integration entirely (composition-line only, not carried into the settings layer — the switch cannot turn itself off). Design details in docs/settings-integration-design.md.

Per-mode only (the agent preset's compaction realm). First disable (or delete) the existing dsh-compaction-basic line within that realm, then insert this engine — two backends cannot coexist in the same realm:

# 先禁用 realm 内默认后端（或直接删掉这一行）
- id: compaction-basic
  disabled: true

# 再插入本引擎
- id: compaction-acp
  name: 'billion-context-dsh'
  config:
    modelContextLimit: 128000   # 可选；省略时自动探测模型真实窗口（回退 128000）

Keep only one context manager per agent. Two backends providing ctx.compaction simultaneously will conflict — never coexist in the same realm. See docs/INSTALL.md for the full installation and verification guide.

How It Works

Every model request in DSH derives from its append-only session log (the surface). ACP semantics map directly onto this model:

ACP Concept	DSH Implementation
compress tool shadows a range	Persistent surfaceOp: { op: 'replace' } — the model-written summary becomes a checkpoint node; the original text remains in the log
refs (m00001 tags)	surface seq, carried by the nudge's compressible range table
nudge ("efficiency hint — compress early to stay lean")	Injected at agent/pre-step by the kernel's pressure decision — efficiency notice + context breakdown + compression rules, tone aligned with kernel/pi; never a command
decompress	Read-only restore of the shadowed original from the log
search_context	Rebuilds a unified document set of block summaries + shadowed originals from the log (cached per log snapshot: repeated searches before new events hit disk are served directly from the cache, issue #133), scored by acp-kernel searchBlocks (hybrid: stemming + CJK bigram + character n-gram fuzzy); hits back-link to their owning block
acp_status	CONTEXT BREAKDOWN (tool/text/summaries share of the visible total) + compressed-block ledger + nudge decision line + Checkpoint seqs line (bN → seq mapping of active blocks — compressing a checkpoint seq distills that block, issue #60); no context window; supports drill-down via scope/view/tool/sort/limit
Block state	In-memory kernel state + log-rebuilt ledger (no sidecar files)
Tiered distillation (T2/T3)	Compressing a block's summary node again = distill that block (tier 2); distilling a tier-2 block yields tier 3; tier and kernel block id are persisted in the log; on restart the kernel state is re-hydrated from the log and can continue distilling
Compaction accounting (shadow price)	shadowedTokenCount (the host's occupancy is deducted by this) is priced at the host token-meter's fixed heuristic price (ctx.tokenMeter.measure preferred, read via heuristicTokens ?? tokens for the fixed heuristic price baseline, src/host-tokens.ts exact mirror as fallback) — never mixes in the plugin's internal CJK-aware estimate (that is a display currency; mixing would drive the host's ledger negative and freeze Chinese sessions, issue #54), nor prices via the routing-repriced node.tokens (under 0.1.2+ image-routing pricing that is a request-pressure price; reading it would make claims over image spans over-report the visual price, also driving the ledger negative, issue #103)
Image/file block visibility	image/file blocks have no characters and were previously silently dropped by the projection layer — so they had no ref in the compressible range table, could not serve as boundaries, weren't protected by the kernel's "most recent user message" rule, and were priced at 0 tokens (in screenshot sessions the last question could be compressed away wholesale, issue #117). Now extractText generates a deterministic one-line placeholder from the attachment's persistent metadata ([image image/png shot.png 800x600 4.2KB], [file notes.txt 1.0KB], same source as the host's file handle text projection), media price is read as the difference between tokens and heuristicTokens on the host token-meter node (that node exposes only these two prices: tokens is the request pressure under the current routing, carrying the adapter-declared visual price when media is present; heuristicTokens is the routing-agnostic fixed heuristic — the difference is exactly the extra amount routing charges), and on top of that the host's fixed-heuristic structural price for media references is added (hostMediaStructuralPrice, mirroring the host's own estimateStructuralBlock): today no adapter declares a visual price, the difference is always 0, reading only the difference would make images look "free" again; the range-table line tail is annotated [+N images]; sessions without media perform no extra measurement
Injection directive hygiene	The host injects policy files such as AGENTS.md into the session surface; compressing the current copy would cause the host to immediately re-inject the same file — an infinite compress→re-inject→compress loop (issue #71). The compressible range table treats injection lines as barriers: never offered, never counted into segments; manual compression (the model's compress tool, the human-facing /acp compress command) that covers a file's current copy is rejected outright (the error names the line number and notes that stale older copies may be compressed), because compressing the current copy yields no benefit — the host will always re-post it. Grouped by source.changes[].scope (= one file), only the newest copy per group is protected — older copies superseded by an update can be safely compressed

Carrying compaction guidance (tools, philosophy, summary rules, tier distillation/condensation rules) is registered as a one-time system prompt section; each nudge carries a slimmed version (efficiency hint + philosophy + context breakdown + compression rules + range table + batch prompt). No automatic summarization by design: the auto-policy only nudges the model (compactIfNeeded returns null).

Video Walkthrough

A walkthrough of the ACP philosophy this project inherits — how active context compression keeps a session lean within roughly 200K tokens (opencode-acp and billion-context-pi). Original video by: Qiu Xianglian (Bilibili uploader), not produced by this project.

Model Tools

Tool	Function
compress	Replaces a seq range with your compact summary (boundaries are auto-balanced to tool-call/result pair points); compressing a block's summary node again = hierarchical distillation (tier 2/3). Each range can carry verifiedReadings: string[]—a record of files/sections you actually read and verified within that range; it persists with the summary and is echoed back as verified: … in compress results, so subsequent turns know what has been verified without re-reading
decompress	Restores original content of a compressed block (read-only); accepts the bN shown by acp_status or a compaction id. Large blocks are paginated by character budget (default ~7K chars per page, up to 100 pages) so ordinary pages stay below the host's tool-result truncation threshold (8192); offset/limit + continuation hints walk through the whole block
search_context	Keyword search across compressed block summaries and originals (acp-kernel hybrid retrieval: stemming + CJK bigram + fuzzy); hits are back-linked to their owning block
acp_status	CONTEXT BREAKDOWN (tool/text/summaries as share of visible total) + compressed block ledger + nudge decision line + Checkpoint seqs line (the bN → seq distillation entry point for active blocks, issue #60); excludes the context window. Drill-down supported: scope:"compressed" per block, scope:"uncompressed" + view:"messages"/"ranges" per message/interval, tool filter, sort ordering, limit truncation. Drill-down row refs are kernel mN—usable directly as startSeq/endSeq for compress (auto-mapped to live surface seq); the seq on Surface: lines is also usable
/acp	Run status / compress / decompress from the command bar; status additionally displays human-side window info (estimated context, context window source, compression ledger, nudge arbitration — nudge: idle/ACTIVE — reason and how many tokens until the next nudge, using the same kernel decision as the nudge path)

• Source labeling on summaries (framework line for model-written summaries): every compressed summary is prefixed on write with [Model-written summary — not user words; re-verify any obligations before relying on them]—written into both the persisted summary event and its checkpoint node (same text); the projection path idempotently back-fills the framing for older blocks. Purpose: prevent the model from treating obligation statements inside a summary as verbatim user instructions and executing them directly.
• Slim nudge: the compression philosophy/rules section is no longer repeated on every nudge (it is already in the system prompt); nudge body keeps only the trigger framing + context breakdown + range table. The template path (config.prompts.nudge) strips these sections too. Design background: docs/injection-governance-design.md.

Upstream Projects & Credits

This project is a port/derivative built on the shoulders of the following upstream work — all under the MIT license. Sincere thanks to ranxianglei and the DeepSeek Harness team for creating and open-sourcing these projects:

Upstream Project	Author	Role
billion-context-pi	ranxianglei	The Pi coding-agent adapter this project ports; source of the adapter design, tool semantics, and default configuration
acp-kernel	ranxianglei	Framework-agnostic context compression engine — reused as-is (refs, blocks, tiers, nudge decisions, search, status)
opencode-acp	ranxianglei	Origin of the ACP ("the model decides when to compress and what to compress") design
DeepSeek Harness	DeepSeek AI	The host platform this project extends (compaction capability seam, agent presets, persistent session logs)

This project reuses acp-kernel's compression core and billion-context-pi's default behaviors verbatim; the DSH adapter layer (session event projection, durable surface transactions, model tools, nudge, configuration) is original to this repository. Upstream copyright and licensing belong to their respective authors; this project's license terms are in LICENSE.

配置

Key	Default	Description
modelContextLimit	Auto-detected (falls back to 128000)	The context window used for kernel pressure decisions; explicit configuration takes priority and skips detection. When omitted, the host session projection contextPressure.contextWindow is read first (the newly disclosed window for the current active routing; switching models in a session automatically follows without restart), and if no projection is available, the model API is queried; explicit configuration also skips the output-reservation deduction (the denominator is fully operator-defined) (runtime hot-tune: /acp config)
autoModelContextLimit	true	Automatically detect the real window from the model API (agent.ctx.llm.resolveModelInfo); detection failure falls back to the default value; the /acp command displays the window source (the model tool acp_status does not include window information). When omitted, the window is read first from the host projection (windowFor → projectedContextWindow, src/window.ts) and then from detection; both projection and detection are skipped when autoModelContextLimit: false. A detection failure is flagged in host logs and the /acp panel (restart to re-probe) — failed results are also cached; re-detection requires a restart or an explicit modelContextLimit after the gateway is fixed. On successful detection, the per-request output limit for the adapter (defaultMaxTokens, the guaranteed per-request output reservation at the tail of the window) is also subtracted: all downstream pressure decisions (nudge tiers, truncate, growth) use "sustainable input budget" (window − output reservation) as the denominator — a 96K window + 16K cap can actually hold at most 80K input; the raw window denominator would underestimate usage by cap/window (≈17% here; the ratio is higher for small-context-window models). When the cap is not disclosed, explicitly configured, or detection fails, the raw-window behavior is preserved; /acp status shows the deduction details (raw − reservation). Changing modelContextLimit/autoModelContextLimit via /acp config clears the window cache; re-detection happens immediately after the change
nudgeMinContextLimitPct	Kernel default 0.45	Nudge window lower bound (usage ratio) — only used for configuration validation; the growth-path trigger has no percentage floor — same default as billion-context-pi (runtime hot-tune: /acp config)
nudgeMaxContextLimitPct	Engine default 0.70 (kernel/pi default 0.75)	Over-limit line: exceeding this value triggers a nudge regardless of growth — intentionally set below the host's compaction-basic 80% auto-compaction threshold to ensure the forced nudge fires first; explicit configuration takes priority (the same-named key in coreOverrides.nudge has higher precedence, see below) (runtime hot-tune: /acp config)
nudgeEmergencyThresholdPct	Engine default 0.85 (kernel/pi default 0.95)	Emergency nudge (bypasses per-turn deduplication, but at most 3 injections per user turn — issue #108) — lowered from 0.95: at 95% the model has no room to act and is masked by the 80% auto-compaction line; explicit configuration takes priority (the same-named key in coreOverrides.nudge has higher precedence, see below) (runtime hot-tune: /acp config)
preset	—	(Optional) pick the nudge aggressiveness in one word: preserve / relaxed / balanced / efficient / aggressive (see "Presets" below). Fills in only the three nudge thresholds you have not explicitly set; priority is explicit value > preset > engine default; unknown names throw at construction time; if the combined result has a reversed window (min / max / emergency order wrong) it also throws at construction time. Does not affect other keys (modelContextLimit / autoNudge / prompts / coreOverrides) (composition-line only: preset is not yet wired to /acp config; see follow-up on issue #75)
coreOverrides	—	Any other acp-kernel Config overrides (the coreOverrides escape hatch from billion-context-pi). Merge order: kernel defaults → top-level pct config → coreOverrides.nudge applied last — same-named keys here win (read-only: composition-line only, not exposed through the settings layer)
autoTools	true	Registers the four model tools in ctx.tools
autoCommand	true	Registers the /acp command in ctx.commands
autoNudge	true	Injects a nudge into agent/pre-step when the kernel recommends it (runtime hot-tune: /acp config)
settingsEnabled	true (enabled when not configured)	(Optional) Disables runtime settings integration entirely (composition-line only; not in the settings layer — the toggle cannot switch off itself; once disabled, the composition-line config: is the only active channel)
prompts	—	(Optional) Custom prompt text: override nudge / scope table / system prompt / tool description per slot (template + named placeholders, validated at construction time; see "Custom Prompt Text" above and docs/configurable-prompts-design.md)

Presets

不想逐个调三个百分比时，用一个词选择 nudge 的激进程度——从「尽量保留上下文」到「尽早频繁压缩」共五档：

preset	min	max	emergency	定位
preserve	0.55	0.78	0.93	尽量保留上下文，接近上限才提醒压缩
relaxed	0.50	0.75	0.90	轻度压缩，比 preserve 稍早提醒
balanced	0.45	0.70	0.85	默认平衡——与插件开箱阈值一致（选它等于不改）
efficient	0.40	0.60	0.78	更勤快地修剪，偏向低 token 占用而非保留完整历史
aggressive	0.30	0.50	0.70	精简上下文，更早更频繁地压缩

• 只填未设的阈值：preset 仅填充你没有显式设置的 nudge*ContextLimitPct；同时写了 preset 和某个阈值时，该阈值以你的显式值为准（优先级 显式 > preset > 默认）。
• 不碰其他旋钮：modelContextLimit、autoNudge、prompts、coreOverrides 完全不受影响；coreOverrides.nudge 仍最后落地、同名键最高优先。
• 查看当前档位：/acp status 会打印生效的 preset 及其真实生效的三个阈值——这一行镜像 kernelConfigFor 的合并顺序，所以你在其上做的显式覆盖、以及 coreOverrides.nudge 里的同名键都会如实显示。
• 拼错即报错：未知名称在引擎构造期直接抛错并列出合法值（与自定义提示词模板同一约定），不会静默回退默认。注意 bundle 行本身不带 config，preset 只能由你自己的同 id compaction-acp 行提供；该行构造失败即挂载失败，profile 会在你修好配置前一直起不来（fail-fast 的既定行为）。
• 运行时热切换：预设目前走组合配置（安装 / cordis.patch.yml）；待 #75 的 settings.yaml 热加载落地后，可在 /acp config 里改。本 PR 先让它在组合层可用。
• 反向窗口直接报错：与显式阈值合并后若出现 min > max、max > emergency 或 min > emergency（例如 preset: 'preserve' 配 nudgeMaxContextLimitPct: 0.5），引擎在构造期抛错并列出三个值。内核对这种配置只打警告、不会拒绝，所以这道校验由引擎在 resolveAcpConfig 里补上。
• 与宿主 80% 线赛跑的是 max：反复触发的过限提醒（OVER-LIMIT）由 max 决定；preserve / relaxed 的 emergency（0.93 / 0.90）高于宿主 compaction-basic 的 80% 线，只是超过它之后的标签升级，宿主先压缩时不会到达。
• min 是首见提醒与 T2/T3 块数触发的地板：内核 0.0.63 在运行时读它两处——① firstSightMassReady（从未提醒过、还没有基线、用量 ≥ min 且待压内容达到增长下限时立刻提醒一次，理由串带 [first-sight mass]）；② tierCountUsageFloor（T2/T3 的「块数达标」触发同样要求用量 ≥ min）。常规 T1 增长提醒不看 min（由 max 与 growthRatio 决定），所以五档之间的主要差异仍来自 max 与 emergency，但更低的 min 会让首见提醒来得更早。
• 两个暂未纳入的旋钮：原始需求里的 growthRatio（内核已有 nudge.growthRatio，可经 coreOverrides 调）和 protectedLastMessages（≈ 内核 preserveRecentMessages）目前不是本项目的一等旋钮；是否采纳为命名键 / UI 项由维护者决定，未擅自并入预设。

开发

npm install
npm run typecheck   # 严格 TS
npm test            # node --import tsx --test tests/*.test.ts
npm run build       # tsup 打包（内联 acp-kernel）+ .d.ts
npm run test:e2e   # 端到端宿主回归：真实 agent 循环 + 脚本化假 LLM（见下文）

端到端回归（scripts/e2e/）在进程内组装真实 DSH 宿主（cordis + agent-loop + DeepSeek 适配器），指向脚本化假 LLM 服务，挂载本引擎作为压缩后端，然后断言持久化事件日志：compaction 起止配对、durable replace 节点、严格 tool-call/result 配对、nudge 注入节奏；以及假 LLM 实际收到的请求体（wire 级 prompt-cache 字节稳定性：envelope、tools 数组、leading message，无 compaction 场景全程 append-only）。背景与取舍见 docs/e2e-harness-design.md（issue #120）。

dist/index.js 自包含，仅外链 @deepseek-ai/* 接缝包（由宿主部署提供）。

架构

src/
├── index.ts        # AcpCompactionEngine（CompactionEngine 后端）+ 接线
├── messages.ts     # M1: 会话事件 ↔ acp-kernel CoreMessage 投影
├── state.ts        # M2: 每会话内核状态
├── region.ts       # M5: 持久化区域事务 + 日志重建块账本
├── block-ledger.ts # M5 支持：tier/lineage 字段编码进 compaction/summary 的 rawOutput（绝不作顶层成员，issue #141）
├── tools.ts        # M3: compress / decompress / search_context / acp_status
├── nudge.ts        # M4: 内核压力决策 → 注入的建议式 nudge
├── system-prompt.ts# M4: 一次性 ACP 指引段（让 nudge 保持简短）
├── config.ts       # 内核配置组装（阈值 + coreOverrides）
├── window.ts       # 自动上下文窗口探测（宿主投影优先，LLM 运行时探测回退，兜底 128000）+ 输出预留探测（defaultMaxTokens，windowFor 内扣除）
└── commands.ts     # M4: /acp 斜杠命令

License

MIT