DSH Hub / 插件 / dsh-blackhole Asaiuta/dsh-blackhole ↗ ★ 0
dsh-blackhole Dual-pipeline compaction for DeepSeek Harness: official server-side Responses compaction v2 for OpenAI-routed targets, with a deterministic VCC-style local compiler (zero model calls) as the default fallback and for every other provider.
包名 dsh-blackhole
版本 0.2.0
许可证 NOASSERTION
最近更新 2026年8月15日 GitHub ↗ 文档 ↗ 安装 $ npx -p @deepseek-ai/dsh dsh plugin --profile web add github:Asaiuta/dsh-blackhole复制
dsh-blackhole
English | 简体中文
k0valik/pi-blackholeDeepSeek Harness(DSH)移植版 — 移植了 pi-blackhole 的 brief 编译器(VCC 会话压缩编译器),并封装进一个双管线压缩引擎。
是官方 @deepseek-ai/dsh-compaction-basic 后端的即插即用替代品,在唯一的 summarize() 钩子内部做路由:
OpenAI(或任何配置了 Responses endpoint 的 provider) — 官方远程路径:通过 Responses API 的 compaction_trigger 把摘要委托给模型服务器 (与 Codex 远程压缩同一协议),每次会话持久化不透明的替换历史;远程失败 (无 endpoint、缺 key、超时、协议错误)— 默认由确定性 VCC 风格本地编译器 编译该区域(零模型调用,(seq N) 指针近似无损地指回持久会话日志),也可通过 fallbackMode: "llm" 使用原生一次性 LLM 摘要器;其他所有 provider — 直接走本地编译器,零网络。
远程压缩分支移植自
algal/pi-openai-server-compactionpi-blackhole brief.ts 编译器的移植 (VCC 会话压缩编译器,MIT;规则谱系:lllyasviel/VCC → dsh-compaction-instant)——差分测试套件将内容级等价性钉死在真实 pi-blackhole 源码上(见下文 Equivalence )。
为什么
pi DSH(本插件) 远程压缩 v2 经 algal/kky42/lll9p 扩展 路由引擎的 remote 分支 零成本本地压缩 pi-vcc / pi-blackhole(算法式) 本地编译器分支 (fallbackMode: "instant")压缩接缝 扩展事件钩子 CompactionEngine.summarize() — 官方唯一自定义钩子回退链 — instant →(可选)原生 LLM → 失败 不透明窗口持久化 pi 会话 JSONL compaction.details.remoteCompaction $DSH_HOME/plugins/dsh-blackhole/state 下的逐会话 JSON 状态
工作原理
DSH 决定压缩(压力 / 溢出 / /compact)并以重放的会话区域调用引擎的 summarize() 钩子。
解析路由的 provider/model(先持久请求头,再 agent options),与配置的 endpoints 匹配。
远程分支 (endpoint 匹配):区域转换为 Responses 输入项(text、reasoning、tool calls/results),追加 compaction_trigger,压缩响应从 {baseUrl}/responses 流式返回。助手撰写的摘要成为可读 checkpoint;不透明的
dsh-blackhole · DSH Hub
compaction
回退 :任何远程失败都会记录警告,并把区域交给本地编译器(instant,默认)或原生 LLM 摘要器(llm)。instant-then-llm 先试编译器,仅当编译器自身失败才用 LLM。
本地编译器分支 (无 endpoint 匹配,或回退):对区域做确定性零模型遍历,只保留原始 token ——每个工具调用变成一行 * bash "ls" (seq 2 -> result 3),工具结果从不占用条目(通过指针一次 recall 即得),推理被省略,长文本以 ...(truncated from seq N) 截断,噪声 XML 被剥离,token 上限优先丢弃最老行并给出显式 [N entries elided: seqs a-b] 说明。(seq N) 指针解析到真实持久会话日志 (每条压平消息按 id 匹配存储事件),因此挂在本引擎旁的 recall 工具能还原精确原始内容。引擎继承官方 BasicCompactionEngine,所有压力 / 保留 / 策略旋钮、token 计费定价、上下文溢出恢复都与上游完全一致。
安装 需要 DSH 0.1.0-rc.6(web 或 headless profile)。
# 安装到服务你会话的 profile
dsh plugin --profile web add dsh-blackhole
# 或从本地 tarball:
npm pack dsh-blackhole && dsh plugin --profile web add ./dsh-blackhole-0.2.0.tgz
禁用官方 compaction-basic 行(web-app bundle 已禁用 — 幂等),
重新启用 command-compact(/compact 命令,web-app bundle 禁用了它;与后端无关),
在本引擎自己的行下插入。
最终只挂载一个 compaction 服务;双管线在引擎内部。
配置 在 profile 的设置中(或 ~/.dsh/settings.yaml 的插件 key 下):
dsh-blackhole:
# 继承的 BasicCompactionEngine 旋钮(全部可选,默认值与
# @deepseek-ai/dsh-compaction-basic 相同):
thresholdRatio: 0.75
retainRatio: 0.25
auto: true
# Responses 辅助旋钮:
endpoints:
# 直连 OpenAI Responses
- provider: openai
baseUrl: https://api.openai.com/v1
apiKeyEnv: OPENAI_API_KEY
# 任何转发 Responses API 的 OpenAI 兼容网关
- provider: '*'
baseUrl: https://my-gateway.example.com/v1
apiKeyEnv: MY_GATEWAY_KEY
# 官方 Codex 后端(需要 beta-feature 头)
- provider: openai-codex
baseUrl: https://chatgpt.com/backend-api
apiKeyEnv: CODEX_TOKEN
headers:
OpenAI-Beta: responses=experimental
x-codex-beta-features: remote_compaction_v2
timeoutMs: 120000 # 2 分钟后中止远程尝试
fallbackMode: instant # instant | instant-then-llm | llm
retainedMessageTokenBudget: 20000
persistRemoteHistory: true
stateDir: ~/.dsh/plugins/dsh-blackhole/state
# 本地编译器旋钮(全部可选):
compileMaxTokens: 8192 # 下限;在大区域按 checkpointScale 放大
checkpointScale: 0.1 # 上限 = max(compileMaxTokens, 影子区域 x scale)
checkpointCap: 65536 # 硬顶
textTokens: 512 # 每条 assistant text/reasoning block
userTextTokens: 1024 # 每条 user text block
toolCallTokens: 128 # 每条工具单行
includeReasoning: false
stripNoiseXml: true
noisePatterns: [] # 空 = 内置 VCC 模式
toolArgTools: [] # 空 = 内置白名单
hideTools: [] # 例如 [TodoWrite, ToolSearch]
Endpoint 匹配:provider 匹配最近一次请求运行的 DSH provider 路由(精确,或 * 任意);model 匹配精确 id 或 * glob。鉴权使用 apiKeyEnv(环境变量名)或 apiKey(内联 — 切勿提交真实 key)。
fallbackMode 语义(仅适用于远程失败):
模式 远程成功 远程失败 instant(默认)服务器摘要 本地编译器(零模型调用) instant-then-llm服务器摘要 本地编译器;仅当编译器本身失败才用 LLM llm服务器摘要 原生一次性 LLM 摘要器
遗留的 fallbackToLlm 布尔值仍映射:false 强制 instant;true 与默认行为一致。无匹配 endpoint 的目标总是走本地编译器(或 llm 模式下的原生 LLM)。
行为说明
图片 :DSH 把图片字节存在 attachment store 中,远程压缩调用无法解析;图片块以显式 "image content omitted" 文本访问代替静默丢弃。本地编译器将其渲染为 [image] (seq N) 标签。Checkpoint 框架 :引擎返回纯文本;继承的后端用标准 `` checkpoint 框架包裹。带 agent presets 的部署 :presets 挂载自己的压缩域。如果 preset 也压缩,要么在某一侧禁用 auto,要么删掉 preset 的压缩行 — 两个引擎不得压缩同一会话。普通轮的 opaque 重放仍归 adapter 所有 :DSH 不可变的 llm/stream 请求没有消息重写钩子。因此本包提供可选的 responsesCompactionReplay 服务。Responses adapter 应在构建 HTTP payload 之前 调用 prepareInput({ sessionId, provider, model, trailingMessages, endpoint });它返回 [自有 opaque 替换历史, ...trailingMessages](含正在发送的请求的最后一个未完成 user/tool 轮),若没有自有 artifact 则返回所提供 DSH 消息的可移植转换。replayHistory(...) 仍可用于压缩侧变体,它刻意只保留已完成的尾部轮。外来 provider/model 状态、遗留 artifact、endpoint 不匹配与回退压缩都会被拒绝或移除,而不是重放。Responses 压缩路径在下一次压缩时自动使用已完成轮契约。
Adapter 接线契约(responsesCompactionReplay) 接缝是 adapter 内序列化普通 Responses 请求时的一次方法调用。tests/protocol-smoke.mjs 把整个矩阵钉为可执行断言;adapter 需要实现的形状如下:
// 在 Responses adapter 内部:
const replay = ctx.get('responsesCompactionReplay') as
import('dsh-blackhole').ResponsesCompactionReplay | undefined
// 在为 NON-compaction 轮构建 HTTP payload 之前立即调用:
const input = replay === undefined
? dshMessagesToResponseItems(trailing)
: await replay.prepareInput({
sessionId, // agent/session id(opaque 窗口以它为 key)
provider, // 持久路由:例如 'openai'
model, // 持久模型:例如 'gpt-5'
trailingMessages: trailing, // 本轮要发送的 DSH Messages
endpoint, // 可选;已知时传入 base URL
})
// builder.send({ model, input, stream: true, store: false, ... })
契约语义(全部由 RemoteCompactionStateStore 强制):
自有 artifact (同一 provider/model/endpoint,带版本 details):返回 [opaque 替换项, ...trailingMessages 的输入项],保留最后一个未完成 user/tool 轮(includePending),以免丢失正在发送的请求。无状态 / 外来路由 / 遗留 artifact / endpoint 不匹配 :返回普通 DSH→Responses 转换(故障关闭 — 绝不返回陈旧 opaque 窗口)。replayHistory() 在恰好这些情况下返回 undefined。压缩轮 :不要以压缩意图调用 prepareInput() — RoutingCompactionEngine 在摘要时已在内部重放已完成轮窗口。该服务只服务于普通对话轮。回退压缩 会使存储窗口失效(state.remove),因此后续同路由轮从 DSH 消息开始,不会跳过新的本地 checkpoint。纯文本区域 的压缩率低于工具密集区域(工具结果在编译视图中零 token);编译器无法缩小的区域会故障关闭地拒绝,与上游 instant 引擎的 shrink 保证完全一致。
开发 pnpm install
pnpm run typecheck # tsc --noEmit(针对 rc.6 包)
pnpm run build # esbuild → lib/index.js
node tests/smoke-load.mjs # loader 组合挂载引擎
node tests/protocol-smoke.mjs # 转换/SSE/回环(本地 fake endpoint)
node tests/hybrid-smoke.mjs # 编译器单元 + 路由(remote/instant/llm/compat)
node tests/equivalence/build-algal.mjs && node tests/equivalence/differential.mjs
# 与真实上游 bundle 的协议等价
node tests/equivalence/build-blackhole.mjs && node tests/equivalence/differential-brief.mjs
# 与真实 pi-blackhole brief 编译器的内容级差分
# (BRIEF-DIFF.md: 11/12 向量对齐)
node tests/instant-blackhole-align.mjs
# 钉齐 brief 规则的回归套件
node tests/equivalence/differential-real-session.mjs
# 在真实 pi 会话记录上的内容差分
# (直播转录,非合成向量)
node tests/equivalence/entity-fidelity.mjs
# 实体级保留审计(路径/符号/错误)
DSH_EVAL_KEY=... DSH_EVAL_BASE=... node tests/equivalence/eval-fidelity-llm.mjs
# LLM A/B:完整 vs brief 上下文的回答准确性
# (见 FIDELITY.md;key/base/model/session 走环境变量)
与上游移植的等价性 tests/equivalence/ 在固定 commit 快照上游源码(algal/SOURCE.json),并 stub pi 依赖后打包(只替换计算辅助函数;协议代码原样运行)。随后差分测试向两个实现喂相同向量:请求体、替换历史(保留、20K 截断、图片豁免、空消息过滤)、SSE 解析(成功 + 每条错误路径)、消息转换(pi↔DSH 语义投影)、身份头,以及一次完整的本地 endpoint 回环。15/15 向量通过。
资格检测 :上游从 pi-ai 注册表自动检测直连 OpenAI / Codex 模型(host 必须是 api.openai.com);本移植匹配声明的 endpoints(provider + model glob),因此也能指向你自己的网关。上游的 host 门禁恰会拒绝本插件面向的部署。Checkpoint 文本来源 :上游并行运行本地摘要并把远程 artifact 存进 details.remoteCompaction(pi 有该槽位);DSH 的 summarize() 只返回一个文本,因此本移植把服务器侧摘要文本作为 checkpoint,并按 fallbackMode 回退。至多一次 LLM 调用 — 默认零次。图片 :pi 携带图片字节(→ input_image);DSH 只有 attachment id,因此图片访问变成显式占位文本。暴露的旋钮 :retainedMessageTokenBudget(上游固定 20K)、timeoutMs、sendIdentityHeaders、installationId 是额外选项;默认值精确复现上游行为。
许可