billion-context-dsh 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +179 -0
- package/README.md +132 -67
- package/dist/index.js +144 -40
- package/dist/index.js.map +1 -1
- package/dist/nudge.d.ts +6 -0
- package/dist/region.d.ts +27 -6
- package/package.json +3 -2
- package/README.zh-CN.md +0 -116
package/README.en.md
ADDED
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
# billion-context-dsh
|
|
2
|
+
|
|
3
|
+
[English](./README.en.md) | [中文](./README.md)
|
|
4
|
+
|
|
5
|
+
> **⚠️ Beta notice — not for production use**
|
|
6
|
+
> This project (**v0.1.2**) 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.
|
|
7
|
+
|
|
8
|
+
<p align="center">
|
|
9
|
+
<strong>Built with gratitude on top of these projects</strong> — please give them a ⭐:
|
|
10
|
+
<br />
|
|
11
|
+
<a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> ·
|
|
12
|
+
<a href="https://github.com/ranxianglei/billion-context-pi">billion-context-pi</a> ·
|
|
13
|
+
<a href="https://github.com/ranxianglei/acp-kernel">acp-kernel</a> ·
|
|
14
|
+
<a href="https://github.com/ranxianglei/opencode-acp">opencode-acp</a>
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
<p align="center">
|
|
18
|
+
<strong>Billion-Context</strong> for <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a>
|
|
19
|
+
<br />
|
|
20
|
+
The model decides <em>when</em> and <em>what</em> to compress — not a hard limit.
|
|
21
|
+
</p>
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
<p align="center">
|
|
26
|
+
<a href="https://www.npmjs.com/package/billion-context-dsh"><img src="https://img.shields.io/npm/v/billion-context-dsh.svg?style=flat-square" alt="npm"></a>
|
|
27
|
+
<a href="https://github.com/Tyan66666/billion-context-dsh/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/billion-context-dsh.svg?style=flat-square" alt="license"></a>
|
|
28
|
+
<a href="https://github.com/Tyan66666/billion-context-dsh"><img src="https://img.shields.io/badge/GitHub-Tyan66666%2Fbillion--context--dsh-181717?style=flat-square&logo=github" alt="GitHub"></a>
|
|
29
|
+
<a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/topic-dsh--plugin-blue?style=flat-square" alt="dsh-plugin"></a>
|
|
30
|
+
</p>
|
|
31
|
+
|
|
32
|
+
<p align="center">
|
|
33
|
+
<code>npm install billion-context-dsh</code>
|
|
34
|
+
</p>
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Why?
|
|
39
|
+
|
|
40
|
+
When conversations get long, the model runs out of context. Most tools hard-truncate — silently dropping earlier messages. **billion-context-dsh** gives the model a `compress` tool: the LLM decides **when** and **what** to compress into high-fidelity summaries, preserving critical details (file paths, decisions, error strings) while reclaiming context space.
|
|
41
|
+
|
|
42
|
+
Unlike DSH's built-in auto-compaction (which replaces a range with an automatically generated summary), billion-context-dsh:
|
|
43
|
+
|
|
44
|
+
- **Model-driven** — the model writes the summary itself; there is no second LLM summarization call (the ACP cost win)
|
|
45
|
+
- **Advisory, never imperative** — automatic policy only *nudges*; the model decides whether and when to compress
|
|
46
|
+
- **Durable & recoverable** — a compressed range becomes a checkpoint node, the originals stay in the append-only session log; `decompress` restores them, `search_context` finds information inside blocks
|
|
47
|
+
- **Seq-based refs** — no message tags; surface seqs are carried by the nudge's range table, with auto-balanced range edges and `#callId` tolerance
|
|
48
|
+
|
|
49
|
+
This is the DeepSeek Harness port of [billion-context-pi](https://github.com/ranxianglei/billion-context-pi) (the Pi coding-agent adapter): the compression core ([acp-kernel](https://github.com/ranxianglei/acp-kernel)) is reused verbatim, and the adapter layer was rewritten against DSH's durable-surface model — see [docs](https://github.com/Tyan66666/billion-context-dsh/tree/main/docs) for the verified mapping.
|
|
50
|
+
|
|
51
|
+
## Install
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
npm install billion-context-dsh
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
That's it. Then add a composition row where a compaction backend is expected — two scopes, pick by how wide you want it:
|
|
58
|
+
|
|
59
|
+
**Global — host plane, every mode** (recommended). In your profile patch (e.g. `~/.dsh/profiles/web/cordis.patch.yml`), add:
|
|
60
|
+
|
|
61
|
+
```yaml
|
|
62
|
+
# ACP as the global compaction backend: four model tools + `/acp` command +
|
|
63
|
+
# nudge + ACP guidance section for EVERY mode
|
|
64
|
+
# (standard / code / minimal / cordis / custom presets).
|
|
65
|
+
# Must also disable the host compaction-basic: two backends providing
|
|
66
|
+
# `ctx.compaction` in the same realm collide.
|
|
67
|
+
- id: compaction-basic
|
|
68
|
+
disabled: true
|
|
69
|
+
|
|
70
|
+
- insert:
|
|
71
|
+
- id: compaction-acp
|
|
72
|
+
name: 'billion-context-dsh'
|
|
73
|
+
config:
|
|
74
|
+
modelContextLimit: 128000 # default; the pressure window
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
**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:
|
|
78
|
+
|
|
79
|
+
```yaml
|
|
80
|
+
# First disable the realm's default backend (or just delete this row)
|
|
81
|
+
- id: compaction-basic
|
|
82
|
+
disabled: true
|
|
83
|
+
|
|
84
|
+
# Then mount this engine
|
|
85
|
+
- id: compaction-acp
|
|
86
|
+
name: 'billion-context-dsh'
|
|
87
|
+
config:
|
|
88
|
+
modelContextLimit: 128000 # default; the pressure window
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
> **One context manager per agent.** Two backends providing `ctx.compaction` collide — never run both in the same realm. Full install & verification guide: [docs/INSTALL.md](docs/INSTALL.md).
|
|
92
|
+
|
|
93
|
+
## How it works
|
|
94
|
+
|
|
95
|
+
DSH derives every model request from its append-only session log (the *surface*). ACP semantics map onto that model directly:
|
|
96
|
+
|
|
97
|
+
| ACP concept | DSH implementation |
|
|
98
|
+
|---|---|
|
|
99
|
+
| `compress` tool shadows a range | durable `surfaceOp: { op: 'replace' }` — the model-written summary becomes a checkpoint node; the originals stay in the log |
|
|
100
|
+
| refs (`m00001` tags) | surface seqs, carried by the nudge's compressible-range table |
|
|
101
|
+
| nudge ("consider compressing") | injected at `agent/pre-step` by the kernel's pressure decision — a short advisory, never an order |
|
|
102
|
+
| `decompress` | read-only recovery of shadowed originals from the log |
|
|
103
|
+
| `search_context` | scores block summaries + originals rebuilt from the log |
|
|
104
|
+
| `acp_status` | block ledger + context pressure |
|
|
105
|
+
| block state | in-memory kernel state + **log-rebuilt ledger** (no sidecar files) |
|
|
106
|
+
|
|
107
|
+
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).
|
|
108
|
+
|
|
109
|
+
## Video
|
|
110
|
+
|
|
111
|
+
A walkthrough of the ACP philosophy this project inherits — how active context compression keeps a session lean at ~200K tokens (opencode-acp & billion-context-pi). *Video credit: the original author, [裘香莲](https://space.bilibili.com/) on Bilibili — not ours.*
|
|
112
|
+
|
|
113
|
+
[](https://www.bilibili.com/video/BV1qAMR6MEA4/)
|
|
114
|
+
|
|
115
|
+
## Model-facing tools
|
|
116
|
+
|
|
117
|
+
| Tool | What it does |
|
|
118
|
+
| --- | --- |
|
|
119
|
+
| `compress` | Replace a seq range with a dense summary you write (edges auto-balanced to tool-pair boundaries) |
|
|
120
|
+
| `decompress` | Restore a previously compressed block's original content (read-only) |
|
|
121
|
+
| `search_context` | Search compressed block summaries and originals by keyword |
|
|
122
|
+
| `acp_status` | Context usage, compressed blocks, compressible ranges |
|
|
123
|
+
| `/acp` | status / compress / decompress from the command bar |
|
|
124
|
+
|
|
125
|
+
## Upstream & credits
|
|
126
|
+
|
|
127
|
+
This project is a **port/derivation** and stands on the shoulders of the following upstream work — all MIT licensed. **Thank you** to [ranxianglei](https://github.com/ranxianglei) and the DeepSeek Harness team for building these projects and making them open source:
|
|
128
|
+
|
|
129
|
+
| Upstream | Author | Role |
|
|
130
|
+
|---|---|---|
|
|
131
|
+
| **[billion-context-pi](https://github.com/ranxianglei/billion-context-pi)** | [ranxianglei](https://github.com/ranxianglei) | The Pi coding-agent adapter this project ports to DeepSeek Harness; source of the adapter design, tool semantics, and this project's default configuration |
|
|
132
|
+
| **[acp-kernel](https://github.com/ranxianglei/acp-kernel)** | [ranxianglei](https://github.com/ranxianglei) | Framework-agnostic context-compression engine — reused **verbatim** (refs, blocks, tiers, nudge decisions, search, status) |
|
|
133
|
+
| **[opencode-acp](https://github.com/ranxianglei/opencode-acp)** | [ranxianglei](https://github.com/ranxianglei) | Origin of the ACP ("model decides when and what to compress") design |
|
|
134
|
+
| **[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)** | DeepSeek AI | The host platform this project extends (compaction capability seam, agent presets, durable session log) |
|
|
135
|
+
|
|
136
|
+
This project reuses `acp-kernel`'s compression core and `billion-context-pi`'s default behavior unchanged; the DSH adapter layer (session-event projection, durable surface transaction, model tools, nudge, config) is original work in this repository. Upstream copyright and licenses remain with their respective authors; see [LICENSE](LICENSE) for this project's terms.
|
|
137
|
+
|
|
138
|
+
## Configuration
|
|
139
|
+
|
|
140
|
+
| Key | Default | Meaning |
|
|
141
|
+
|---|---|---|
|
|
142
|
+
| `modelContextLimit` | `128000` | Context window used for the kernel's pressure decisions |
|
|
143
|
+
| `nudgeMinContextLimitPct` | kernel default `0.45` | Nudge window lower bound (usage fraction) — same default as billion-context-pi |
|
|
144
|
+
| `nudgeMaxContextLimitPct` | kernel default `0.75` | Over-limit line: above this the nudge fires regardless of growth |
|
|
145
|
+
| `nudgeEmergencyThresholdPct` | kernel default `0.95` | Emergency nudge (bypasses the per-turn dedup) |
|
|
146
|
+
| `coreOverrides` | — | Any other acp-kernel `Config` override (billion-context-pi's `coreOverrides` escape hatch) |
|
|
147
|
+
| `autoTools` | `true` | Register the four model tools on `ctx.tools` |
|
|
148
|
+
| `autoCommand` | `true` | Register the `/acp` command on `ctx.commands` |
|
|
149
|
+
| `autoNudge` | `true` | Inject the nudge into `agent/pre-step` |
|
|
150
|
+
|
|
151
|
+
## Development
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
npm install
|
|
155
|
+
npm run typecheck # strict TS
|
|
156
|
+
npm test # node --import tsx --test tests/*.test.ts
|
|
157
|
+
npm run build # tsup bundle (inlines acp-kernel) + .d.ts
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
`dist/index.js` is self-contained except for the `@deepseek-ai/*` seam packages, which the hosting deployment provides.
|
|
161
|
+
|
|
162
|
+
## Architecture
|
|
163
|
+
|
|
164
|
+
```
|
|
165
|
+
src/
|
|
166
|
+
├── index.ts # AcpCompactionEngine (CompactionEngine backend) + wiring
|
|
167
|
+
├── messages.ts # M1: session events ↔ acp-kernel CoreMessage projection
|
|
168
|
+
├── state.ts # M2: per-session kernel state
|
|
169
|
+
├── region.ts # M5: durable region transaction + log-rebuilt block ledger
|
|
170
|
+
├── tools.ts # M3: compress / decompress / search_context / acp_status
|
|
171
|
+
├── nudge.ts # M4: kernel pressure decision → injected advisory nudge
|
|
172
|
+
├── system-prompt.ts# M4: one-time ACP guidance section (keeps nudges short)
|
|
173
|
+
├── config.ts # kernel config assembly (thresholds + coreOverrides)
|
|
174
|
+
└── commands.ts # M4: /acp slash command
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## License
|
|
178
|
+
|
|
179
|
+
MIT
|
package/README.md
CHANGED
|
@@ -1,111 +1,176 @@
|
|
|
1
1
|
# billion-context-dsh
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[中文](./README.md) | [English](./README.en.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
> **⚠️ 测试版声明——请勿用于生产环境**
|
|
6
|
+
> 本项目（**v0.1.2**）仍处于开发中的测试版。[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 本身也处于**公开测试版**阶段。**请勿将两者用于工程化 / 生产环境**——预期会有破坏性变更与粗糙之处。
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+
<p align="center">
|
|
9
|
+
<strong>衷心感谢以下项目——请给它们一个 ⭐：</strong>
|
|
10
|
+
<br />
|
|
11
|
+
<a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> ·
|
|
12
|
+
<a href="https://github.com/ranxianglei/billion-context-pi">billion-context-pi</a> ·
|
|
13
|
+
<a href="https://github.com/ranxianglei/acp-kernel">acp-kernel</a> ·
|
|
14
|
+
<a href="https://github.com/ranxianglei/opencode-acp">opencode-acp</a>
|
|
15
|
+
</p>
|
|
8
16
|
|
|
9
|
-
|
|
17
|
+
<p align="center">
|
|
18
|
+
<strong>Billion-Context</strong> for <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a>
|
|
19
|
+
<br />
|
|
20
|
+
由模型决定<em>何时</em>压缩、<em>压缩什么</em>——而不是一个硬性上限。
|
|
21
|
+
</p>
|
|
10
22
|
|
|
11
|
-
|
|
23
|
+
---
|
|
12
24
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
25
|
+
<p align="center">
|
|
26
|
+
<a href="https://www.npmjs.com/package/billion-context-dsh"><img src="https://img.shields.io/npm/v/billion-context-dsh.svg?style=flat-square" alt="npm"></a>
|
|
27
|
+
<a href="https://github.com/Tyan66666/billion-context-dsh/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/billion-context-dsh.svg?style=flat-square" alt="license"></a>
|
|
28
|
+
<a href="https://github.com/Tyan66666/billion-context-dsh"><img src="https://img.shields.io/badge/GitHub-Tyan66666%2Fbillion--context--dsh-181717?style=flat-square&logo=github" alt="GitHub"></a>
|
|
29
|
+
<a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/topic-dsh--plugin-blue?style=flat-square" alt="dsh-plugin"></a>
|
|
30
|
+
</p>
|
|
19
31
|
|
|
20
|
-
|
|
32
|
+
<p align="center">
|
|
33
|
+
<code>npm install billion-context-dsh</code>
|
|
34
|
+
</p>
|
|
21
35
|
|
|
22
|
-
|
|
36
|
+
---
|
|
23
37
|
|
|
24
|
-
|
|
38
|
+
## 为什么？
|
|
25
39
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
| block state | in-memory kernel state + **log-rebuilt ledger** (no sidecar files) |
|
|
40
|
+
当对话变长，模型会耗尽上下文。多数工具直接硬截断——悄悄丢弃早期消息。**billion-context-dsh** 给模型一个 `compress` 工具：由 LLM 决定**何时**、**压缩什么**，写成高保真摘要，保留关键细节（文件路径、决策、错误信息）的同时回收上下文空间。
|
|
41
|
+
|
|
42
|
+
与 DSH 内置的自动压缩（用自动生成的摘要替换一段范围）不同，billion-context-dsh：
|
|
43
|
+
|
|
44
|
+
- **模型驱动** —— 摘要由模型自己书写，没有第二次 LLM 摘要调用（ACP 的成本优势）
|
|
45
|
+
- **只建议、不强令** —— 自动策略只 *nudge*（提醒），是否压缩、何时压缩由模型决定
|
|
46
|
+
- **持久且可恢复** —— 压缩范围成为 checkpoint 节点，原文保留在 append-only 会话日志中；`decompress` 可恢复，`search_context` 可在块内查找
|
|
47
|
+
- **基于 seq 引用** —— 不需要消息标签；surface seq 由 nudge 的范围表携带，范围边界自动平衡、容忍 `#callId` 片段
|
|
35
48
|
|
|
36
|
-
|
|
49
|
+
这是 [billion-context-pi](https://github.com/ranxianglei/billion-context-pi)（Pi 编码代理适配器）在 DeepSeek Harness 上的移植：压缩内核（[acp-kernel](https://github.com/ranxianglei/acp-kernel)）原样复用，适配层针对 DSH 的 durable-surface 模型重写——经过验证的映射关系见 [docs](https://github.com/Tyan66666/billion-context-dsh/tree/main/docs)。
|
|
50
|
+
|
|
51
|
+
## 安装
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
npm install billion-context-dsh
|
|
55
|
+
```
|
|
37
56
|
|
|
38
|
-
|
|
57
|
+
就这样。然后在需要压缩后端的位置加组合配置——两种范围，按需选择：
|
|
39
58
|
|
|
40
|
-
|
|
59
|
+
**全局生效（host 平面，所有模式）——推荐**。在你的 profile 补丁（如 `~/.dsh/profiles/web/cordis.patch.yml`）中追加：
|
|
41
60
|
|
|
42
61
|
```yaml
|
|
43
|
-
#
|
|
62
|
+
# ACP 作为全局压缩后端：四个模型工具 + `/acp` 命令 + nudge + ACP 提示词段，
|
|
63
|
+
# 对所有模式（standard / code / minimal / cordis / 自定义预设）生效。
|
|
64
|
+
# 必须同时禁用 host 的 compaction-basic：同一 realm 内两个后端同时
|
|
65
|
+
# provide `ctx.compaction` 会冲突。
|
|
66
|
+
- id: compaction-basic
|
|
67
|
+
disabled: true
|
|
68
|
+
|
|
44
69
|
- insert:
|
|
45
|
-
- id: compaction-
|
|
70
|
+
- id: compaction-acp
|
|
46
71
|
name: 'billion-context-dsh'
|
|
47
72
|
config:
|
|
48
|
-
modelContextLimit: 128000 #
|
|
73
|
+
modelContextLimit: 128000 # 默认；压力窗口
|
|
49
74
|
```
|
|
50
75
|
|
|
51
|
-
|
|
76
|
+
**单模式生效（agent preset 的 `compaction` realm）**。先在该 realm 内*禁用（或删除）原有的 `dsh-compaction-basic` 行*，再插入本引擎——同一 realm 内两个后端不能并存：
|
|
52
77
|
|
|
53
78
|
```yaml
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
79
|
+
# 先禁用 realm 内默认后端（或直接删掉这一行）
|
|
80
|
+
- id: compaction-basic
|
|
81
|
+
disabled: true
|
|
82
|
+
|
|
83
|
+
# 再插入本引擎
|
|
84
|
+
- id: compaction-acp
|
|
85
|
+
name: 'billion-context-dsh'
|
|
59
86
|
config:
|
|
60
|
-
|
|
61
|
-
name: 'billion-context-dsh'
|
|
62
|
-
config:
|
|
63
|
-
modelContextLimit: 128000
|
|
87
|
+
modelContextLimit: 128000 # 默认；压力窗口
|
|
64
88
|
```
|
|
65
89
|
|
|
66
|
-
|
|
90
|
+
> **每个 agent 只留一个上下文管理器。** 两个后端同时 provide `ctx.compaction` 会冲突——同一 realm 内切勿并存。完整安装与验证指南见 [docs/INSTALL.md](docs/INSTALL.md)。
|
|
91
|
+
|
|
92
|
+
## 工作原理
|
|
93
|
+
|
|
94
|
+
DSH 的每个模型请求都派生自其 append-only 会话日志（*surface*）。ACP 语义直接映射到这一模型：
|
|
95
|
+
|
|
96
|
+
| ACP 概念 | DSH 实现 |
|
|
97
|
+
|---|---|
|
|
98
|
+
| `compress` 工具遮蔽一段范围 | 持久化 `surfaceOp: { op: 'replace' }`——模型书写的摘要成为 checkpoint 节点；原文保留在日志中 |
|
|
99
|
+
| refs（`m00001` 标签） | surface seq，由 nudge 的可压缩范围表携带 |
|
|
100
|
+
| nudge（"考虑压缩一下"） | 由内核的压力决策在 `agent/pre-step` 注入——简短建议，绝非命令 |
|
|
101
|
+
| `decompress` | 从日志只读恢复被遮蔽的原文 |
|
|
102
|
+
| `search_context` | 对从日志重建的块摘要与原文打分 |
|
|
103
|
+
| `acp_status` | 块账本与上下文压力 |
|
|
104
|
+
| 块状态 | 内存内核状态 + **日志重建账本**（无旁车文件） |
|
|
105
|
+
|
|
106
|
+
承载性的压缩指引（工具、哲学、摘要规则）注册为一次性系统提示段，因此 nudge 保持简短。刻意**不做自动摘要**：自动策略只 nudge 模型（`compactIfNeeded` 返回 null）。
|
|
107
|
+
|
|
108
|
+
## 视频讲解
|
|
109
|
+
|
|
110
|
+
本项目继承的 ACP 哲学讲解——主动上下文压缩如何在约 20 万 token 内保持会话精简（opencode-acp 与 billion-context-pi）。*视频原作者：[裘香莲](https://space.bilibili.com/)（B 站 UP 主），非本项目制作。*
|
|
111
|
+
|
|
112
|
+
[](https://www.bilibili.com/video/BV1qAMR6MEA4/)
|
|
113
|
+
|
|
114
|
+
## 模型工具
|
|
115
|
+
|
|
116
|
+
| 工具 | 作用 |
|
|
117
|
+
| --- | --- |
|
|
118
|
+
| `compress` | 用你书写的紧凑摘要替换 seq 范围（边界自动平衡到 tool-call/result 配对点） |
|
|
119
|
+
| `decompress` | 恢复已压缩块的原始内容（只读） |
|
|
120
|
+
| `search_context` | 按关键词搜索压缩块摘要与原文 |
|
|
121
|
+
| `acp_status` | 上下文占用、压缩块、可压缩范围 |
|
|
122
|
+
| `/acp` | 从命令栏执行 status / compress / decompress |
|
|
123
|
+
|
|
124
|
+
## 上游项目与致谢
|
|
125
|
+
|
|
126
|
+
本项目是一个**移植/派生项目**，站在以下上游工作的肩膀上——全部为 MIT 许可。**衷心感谢** [ranxianglei](https://github.com/ranxianglei) 和 DeepSeek Harness 团队创建并开源这些项目：
|
|
127
|
+
|
|
128
|
+
| 上游项目 | 作者 | 角色 |
|
|
129
|
+
|---|---|---|
|
|
130
|
+
| **[billion-context-pi](https://github.com/ranxianglei/billion-context-pi)** | [ranxianglei](https://github.com/ranxianglei) | 本项目移植的 Pi 编码代理适配器；适配器设计、工具语义与本项目默认配置的来源 |
|
|
131
|
+
| **[acp-kernel](https://github.com/ranxianglei/acp-kernel)** | [ranxianglei](https://github.com/ranxianglei) | 框架无关的上下文压缩引擎——**原样复用**（refs、blocks、tiers、nudge 决策、search、status） |
|
|
132
|
+
| **[opencode-acp](https://github.com/ranxianglei/opencode-acp)** | [ranxianglei](https://github.com/ranxianglei) | ACP（"模型决定何时压缩、压缩什么"）设计的源头 |
|
|
133
|
+
| **[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)** | DeepSeek AI | 本项目所扩展的宿主平台（compaction 能力接缝、agent preset、持久化会话日志） |
|
|
67
134
|
|
|
68
|
-
|
|
69
|
-
- `decompress` — recover a block's original content (read-only)
|
|
70
|
-
- `search_context` — find information inside compressed blocks
|
|
71
|
-
- `acp_status` — block ledger and pressure
|
|
72
|
-
- `/acp` — status / compress / decompress from the command bar
|
|
135
|
+
本项目原样复用 `acp-kernel` 的压缩内核与 `billion-context-pi` 的默认行为；DSH 适配层（会话事件投影、持久化表面事务、模型工具、nudge、配置）为本仓库原创。上游版权与许可归其各自作者所有；本项目的许可条款见 [LICENSE](LICENSE)。
|
|
73
136
|
|
|
74
|
-
##
|
|
137
|
+
## 配置
|
|
75
138
|
|
|
76
|
-
|
|
|
139
|
+
| 键 | 默认值 | 含义 |
|
|
77
140
|
|---|---|---|
|
|
78
|
-
| `modelContextLimit` | `128000` |
|
|
79
|
-
| `nudgeMinContextLimitPct` |
|
|
80
|
-
| `nudgeMaxContextLimitPct` |
|
|
81
|
-
| `nudgeEmergencyThresholdPct` |
|
|
82
|
-
| `coreOverrides` | — |
|
|
83
|
-
| `autoTools` | `true` |
|
|
84
|
-
| `autoCommand` | `true` |
|
|
85
|
-
| `autoNudge` | `true` |
|
|
141
|
+
| `modelContextLimit` | `128000` | 用于内核压力决策的上下文窗口 |
|
|
142
|
+
| `nudgeMinContextLimitPct` | 内核默认 `0.45` | Nudge 窗口下界（用量占比）——与 billion-context-pi 相同的默认值 |
|
|
143
|
+
| `nudgeMaxContextLimitPct` | 内核默认 `0.75` | 过限线：超过此值则无论增长与否都触发 nudge |
|
|
144
|
+
| `nudgeEmergencyThresholdPct` | 内核默认 `0.95` | 紧急 nudge（绕过每轮去重） |
|
|
145
|
+
| `coreOverrides` | — | 任何其他 acp-kernel `Config` 覆盖（billion-context-pi 的 `coreOverrides` 逃生口） |
|
|
146
|
+
| `autoTools` | `true` | 在 `ctx.tools` 注册四个模型工具 |
|
|
147
|
+
| `autoCommand` | `true` | 在 `ctx.commands` 注册 `/acp` 命令 |
|
|
148
|
+
| `autoNudge` | `true` | 当内核建议时向 `agent/pre-step` 注入 nudge |
|
|
86
149
|
|
|
87
|
-
##
|
|
150
|
+
## 开发
|
|
88
151
|
|
|
89
152
|
```bash
|
|
90
153
|
npm install
|
|
91
|
-
npm run typecheck #
|
|
154
|
+
npm run typecheck # 严格 TS
|
|
92
155
|
npm test # node --import tsx --test tests/*.test.ts
|
|
93
|
-
npm run build # tsup
|
|
156
|
+
npm run build # tsup 打包（内联 acp-kernel）+ .d.ts
|
|
94
157
|
```
|
|
95
158
|
|
|
96
|
-
`dist/index.js`
|
|
159
|
+
`dist/index.js` 自包含，仅外链 `@deepseek-ai/*` 接缝包（由宿主部署提供）。
|
|
97
160
|
|
|
98
|
-
##
|
|
161
|
+
## 架构
|
|
99
162
|
|
|
100
163
|
```
|
|
101
164
|
src/
|
|
102
|
-
├── index.ts
|
|
103
|
-
├── messages.ts
|
|
104
|
-
├── state.ts
|
|
105
|
-
├── region.ts
|
|
106
|
-
├── tools.ts
|
|
107
|
-
├── nudge.ts
|
|
108
|
-
|
|
165
|
+
├── index.ts # AcpCompactionEngine（CompactionEngine 后端）+ 接线
|
|
166
|
+
├── messages.ts # M1: 会话事件 ↔ acp-kernel CoreMessage 投影
|
|
167
|
+
├── state.ts # M2: 每会话内核状态
|
|
168
|
+
├── region.ts # M5: 持久化区域事务 + 日志重建块账本
|
|
169
|
+
├── tools.ts # M3: compress / decompress / search_context / acp_status
|
|
170
|
+
├── nudge.ts # M4: 内核压力决策 → 注入的建议式 nudge
|
|
171
|
+
├── system-prompt.ts# M4: 一次性 ACP 指引段（让 nudge 保持简短）
|
|
172
|
+
├── config.ts # 内核配置组装（阈值 + coreOverrides）
|
|
173
|
+
└── commands.ts # M4: /acp 斜杠命令
|
|
109
174
|
```
|
|
110
175
|
|
|
111
176
|
## License
|