falling-ts/dsh-force-compact

dsh-force-compact

面向 DeepSeek Harness 智能体的激进、本地优先的上下文压缩。

一个 DSH Cordis 函数插件，通过设计让智能体的工作上下文保持精简：在自托管的 llama.cpp 上以适度的上下文运行 Qwen3.8‑27B，而插件会自行收缩对话——带来大窗口的体验，且无 API 成本、无数据外泄。

为什么

- 自托管推理——智能体通过标准 DeepSeek 适配器与本地 OpenAI 兼容的 llama.cpp 服务器通信；无需单独的适配器。
- 低上下文，高信号——插件不是去对抗较小的上限，而是收缩对话，因此智能体在紧凑的提示上进行推理，同时在压缩后的头部保留深层记忆。
- 压缩时关闭思考，其他场景一律透传——disableThinking: true（默认）仅对本插件自身的压缩摘要调用关闭思考；其他所有模型请求都按机器配置原样执行。
- 私密且免费——无按 token 计费，无数据外泄。

它做什么

两个压缩引擎共存于一个门面（resolveCompaction）之后，对调用方透明：

| 引擎 | 使用时机 | 说明 |
|--------|-----------|-------|
| 官方 | compaction 服务在智能体领域中解析成功 | 优先使用；委托给 compaction/basic。 |
| 内置 | 自动回退（典型标准预设会隔离该服务） | 在 ctx.sessions / ctx.llm.stream / ctx.tokenMeter 上自包含的持久化事务；复用官方 compaction/ 事件词汇，因此可跨构建安全重放。 |

无需切换——官方引擎可达时胜出，否则内置引擎接管。

触发点

- 每请求守卫（agent/pre-step）——读取会话的预计上下文 token 数（即 harness 在右下角渲染的精确数字）。达到 autoThresholdTokens 时，它拒绝即将发出的请求，转而压缩头部，并逐字保留最新的 retainLatestTokens。低于阈值时请求继续。
- 回合结束 / 空闲（agent/status → idle）——当智能体静止时，可选地通过 compactNow 进行压缩（门控：turnEndForceCompactionEnabled）。
- 手动 /force-compact——空闲时立即执行 compactNow；忙碌时则排队一个进程本地标志，在下一个模型步骤消费。惰性加载——参见安装下的“命令可用性”。
- session/flush——被等待的持久化检查点。

每条路径都汇入同一个“压缩结果已落入会话”边界——也就是 LiveUI 信号触发的同一点。

决策键是 projectedTokens（以提供方为锚，与 UI 角落显示的数字相同），因此插件绝不会与你所见产生偏差；阈值感知的收缩门控会跳过那些可证明无法将会话拉到阈值以下的摘要调用（消除低阈值死循环）。

内置事务从同一个 tokenMeter.measure 中计费 shadowedTokenCount
官方引擎使用的每节点价格，因此计量器的折叠协议会正确地结算这一下降——右下角的计数器在压缩之后会下降。

思考控制：作用域限定于压缩

自 2026-08 语义修订以来，disableThinking 只控制一件事：本插件自身的摘要调用（engine/builtin.js → engine/summarizer.js → ctx.llm.stream）是否携带 reasoningEffort:'off'。其他一切均不受影响：

| 调用点 | 在 disableThinking: true 时 |
|---|---|
| 内置引擎摘要调用 | 携带 reasoningEffort:'off' |
| 其他所有模型请求（业务、子代理、工具、其他插件） | 机器的 LlmCallConfig 不变 |
| 官方 compaction 服务调用 | 不经过任何插件接缝路由——不受影响 |

当目标是 llama.cpp / OpenAI 兼容端点时，适配器发出的 thinking: { type: 'disabled' } 字段在那里会被静默忽略——因此摘要器还会在完全相同的条件下，额外打上 llama.cpp 原生的顶层 reasoning_effort: "none"。一个 options 对象同时携带两个字段：

| 端点家族 | 读取 | 结果 |
|---|---|---|
| 真正的 DeepSeek API | reasoningEffort:'off' → thinking:{type:'disabled'} | 思考关闭 ✅ |
| llama.cpp / OAI 兼容 | reasoning_effort:"none"（顶层） | enable_thinking=false ✅ |

每个家族都会容忍并忽略外来键，因此同时发出两者是无害的。该字段在 src/engine/summarizer.js 中打上（紧接在 llm.stream(options) 之前），而不是在 llm/stream 瀑布流中——早先的草稿在那里注入，但结构上被证明无效（中间层返回值会被丢弃；就地修改种子会导致宿主崩溃）；相关说明见 src/hooks/wire-rewrite.js 的模块头注释。该钩子现在只承担 LiveUI 水印角色。

还需要在业务调用上关闭思考？在请求头层面设置你的提供商的 reasoningEffort——本插件有意不介入该决策。

可观测性：每次尝试的审计行

每次摘要尝试都会记录两行日志（在默认 debug: true 下可见）——这是作用域决策及其线上字段的持久证明，无需抓取流量：

[force-compact] : compaction thinking-policy — settings.disableThinking=true → extra.reasoningEffort='off' (this summarization call carries thinking-OFF)
[force-compact] : summarization wire-fields → /: reasoningEffort='off' + reasoning_effort="none" (llama.cpp-native wire field)

- 第 1 行（engine/builtin.js）记录 disableThinking 在哪里被读取并路由进调用选项；当该设置为关闭时，它记录的是机器默认值。
- 第 2 行（engine/summarizer.js）记录两个线上字段离开 options 对象时的确切内容，以及解析后的提供商/模型；未打上的字段会标注为 (absent…)。

基于实证：针对本地 llama.cpp 端点进行探测时，一个基线请求返回了
已填充 reasoning_content（模型默认会思考），而同一请求在顶层使用
reasoning_effort:"none" 时则完全没有返回——该字段在那里确实会禁用
思考，而业务调用（省略该字段）则保持思考。

LiveUI 状态

一个极小的宿主→客户端信使（liveUi 设置字段实时镜像到浏览器）会在回合旁边固定一个
徽章：

- 红色“compressing”——就在压缩提交之前；
- 绿色“done”——压缩落地的瞬间；3 秒后一条新的随机工作行
接管；
- 蓝色“working”——其他情况下轮换显示一句俏皮话；
- 在对话结束时清除——当 agent 进入 idle（回合完全
结束）时，会推送一个空文本（isImportant）：徽章文本被清除，
阶段颜色被移除，恢复官方外观。取代了之前的
对话开始时强制工作对覆盖（已于 2026-09 移除）。

徽章文本跟随应用语言：宿主会写入一个与语言环境无关的 textId
（阶段名称或 working.N）以及规范文本，客户端一半则通过其 ctx.locale 词典
将其映射为 zh/en——英文 UI 显示英文俏皮话，
中文 UI 显示原始中文。

发布者是故障安全的：信使故障绝不会干扰实际的压缩。

工作原理

agent/request(payload, next)              # 每个模型请求
return await next()                  # 纯直通（thinking-off 作用域
仅限插件自己的摘要器）

agent/pre-step(payload, next)             # 每个模型步骤之前
projectedTokens >= autoThresholdTokens?
no  -> next()                     # 让请求继续
yes -> compactRegion(head-before-retainLatestTokens, signal)
return { kind: "reject" }  # 此步骤不发起模型请求

agent/status({ agent, status })          # 生命周期转换
status === "idle" && turnEndForceCompactionEnabled?
-> compactNow(agent, freshSignal) # 回合结束压缩

session/flush(session)                   # 持久化检查点
select region -> project messages -> preview + shrink gate
-> compaction.compactRegion(start, end, agent, signal)

支持模块：

- src/hooks/guard.js — agent/request 纯直通 + pre-step 阈值门控 +
进程本地强制标志（thinkingDisabled 仅作为遗留谓词保留）。
- src/hooks/command.js — /force-compact 命令（延迟注册）。
- src/hooks/idle.js — 回合结束强制压缩。
- src/hooks/wire-rewrite.js — llm/stream LiveUI 水印钩子（不做 wire 操作；
历史说明见模块头部）。
- src/engine/region.js — 头/尾锚定的区域选择（带官方配对账本）。
- src/engine/summarizer.js — 一次性 LLM 摘要器，与官方
compaction-basic 完全对齐（目标解析、前缀缓存对齐、purpose:'compaction' 标签、
故障关闭式完成分类、用量捕获）。
- src/engine/builtin.js —— 内置持久化事务（官方 compaction/ 词汇表）。
- src/engine/checkpoint.js —— 预览 + 收缩门控 + 委托给压缩服务。
- src/core/projected.js —— 以 provider 为锚点的 projectedTokens。
- src/core/ui-signal.js —— LiveUI 消息器。

安装

作为可安装包（推荐）：

从 npm（已发布）：
npm install @falling-ts/dsh-force-compact
从 git：
dsh plugin --profile web add github:falling-ts/dsh-force-compact
从本地检出：
dsh plugin --profile web add ./dsh-force-compact

或者，从本地检出，作为 --patch 覆盖层而无需安装：

dsh web --patch dsh-force-compact/cordis.patch.yml

当且仅当 ~/.dsh/logs/dsh-force-compact.log 中出现以下内容时，插件即被加载：

[force-compact] debug logging enabled — writing [force-compact] lines to

命令可用性 —— /force-compact 延迟加载

commands 服务随 agent-presets 平面一起到达，晚于插件的启动时 apply，因此注册发生在首次受保护监听器激活时（agent/request / agent/pre-step / agent/status / session/flush），并在首次成功后永久稳定。实际效果：在（重新）启动实例后，新会话的 / 选择器不会显示 /force-compact，直到该会话发出第一次模型请求 —— 发送任意一条消息，然后该命令便会在整个进程范围内注册。

- 成功：[force-compact] /force-compact command registered (deferred)
- commands 永久缺失：一条 … still UNREGISTERED 10 min … 警告会解释空选择器。在注册之前，插件的其余部分仍可工作 —— 这是降级，而非安装失败。

验证发生了压缩：

idle compaction (builtin) shadowed N nodes (~M tokens)
builtin compaction OK — replaced span seq[A..B] (N nodes, ~K tokens) with a P-char checkpoint
compaction thinking-policy — settings.disableThinking=true → extra.reasoningEffort='off' (…)
summarization wire-fields → /: reasoningEffort='off' + reasoning_effort="none" (…)

（最后两行是“可观测性”下描述的每次尝试审计对。）

设置

$DSH_HOME/settings.yaml，命名空间 falling-ts-force-compact：

| key | type | default | meaning |
|-----|------|---------|---------|
| disableThinking | boolean | true | 仅插件自身的摘要调用携带 reasoningEffort:'off'；其他一切不变。 |
| autoThresholdTokens | number ≥ 32000 | 32000 | 门控的投影 token 触发阈值。下限 32000（读取时向上钳制）。 |
| retainLatestTokens | positive int ≥ 8000 | 8000 | 逐字保留最新的 N 个 token；更早的历史记录会一次性汇总。下限 8000。 同时驱动自动门控和 /force-compact。 |
| turnEndForceCompactionEnabled | boolean | true | 在 agent 的 idle 转换时进行压缩。 |
| debug | boolean | true | 向插件日志输出 [force-compact] 诊断信息。 |
| logFile | string | ~/.dsh/logs/dsh-force-compact.log | 诊断信息的目标位置（~ 展开为用户主目录）。 |
| compactionMode | 'realm' \| 'global' | 'realm' | 官方服务解析策略（优先级 1 路径）。 |
| builtinEnabled | boolean | true | 内置引擎回退的开关。 |
| maxSummaryTokens | integer (1024–200000) | 1024 | 摘要器 LLM maxTokens 的上限。 |
| summarizationTimeoutMs | integer 5000–2147483647 (ms) | 90000 | 单次摘要流的硬性挂钟时间上限（挂起流防护）。下限 5000（低于 5 秒的上限会误中止缓慢的本地端点）；上限 2147483647，因为该值通过 AbortSignal.timeout 调度，而后者在遇到小数延迟时会抛出异常，并会将 2^31..2^32-1 的延迟静默降级为 1 毫秒。超出范围的值会被钳制，小数部分会被截断。 |

示例——一个激进的本地配置：

falling-ts-force-compact:
disableThinking: true
autoThresholdTokens: 40000   # 更早压缩 ⇒ 保持实时提示词较小
retainLatestTokens: 8000
turnEndForceCompactionEnabled: true

在没有 settings 服务的情况下，插件会回退到相同的默认值并仍然进行压缩——
该命名空间是可选的，绝不是硬性依赖。

针对低上下文 llama.cpp 的调优

让 autoThresholdTokens 舒适地低于所服务的上下文：实时提示词保持
较小、延迟保持平稳，而智能体通过压缩后的头部保持深层记忆。
压力以预估 token 数衡量（以提供方为锚点），因此该阈值可
可预测地映射到 UI 数值上。

行为说明

- 运行时依赖： compaction 服务（预设平面
agent-presets:compaction-basic），通过 ctx.get('compaction') 实时读取；不可达时 →
内置引擎接管（或请求继续执行）。
- 可选依赖： settings / tokenMeter / commands / llm / agents 通过
ctx.get(...) 读取并带有防护——缺失时优雅降级。
- 每请求读取设置： 参数在每次模型请求时读取，因此编辑会在
下一次请求时生效，无需重启。
- 信号： agent/ Waterfall 会转发当前轮次的信号；session/flush
检查点和 agent/status 空闲监听器各自创建一个新的 AbortController。
- 持久化： 持久输出是 compaction/ 括号事件 + 一个
surfaceOp:replace user/message 检查点，跨构建可安全重放。
- 客户端部分： web/client.js 添加了设置区段“Force Compact”（本地化
标签），无需重启即可实时编辑（uSES 安全镜像）。
- 一个有意为之的定时器： 3 秒的 publishDone 回退（仅用于呈现，已记录
的偏差）。除此之外，该插件是纯监听器 + 一个进程本地的 Map 强制标志。

截图

设置面板 — Force Compact 区段，所有旋钮均可实时编辑
设置页面 — Force Compact 部分；以上九个字段均可实时编辑，
无需重启。

对话页面 — 红色“compressing”徽章固定在进行中的回合旁边

对话页面 — LiveUI 信号绘制三种状态（红色：压缩中 / 绿色：完成 /
蓝色：工作中）；绿色横幅约 3 秒后淡出，恢复为随机的工作行；对话
结束时徽章被清除（空文本），恢复为官方外观。

许可证

MIT（见 LICENSE）。