本地上下文压缩 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；忙碌时排入一个进程内标志，在下一个模型步骤消费。懒加载——见 Install 下的「Command availability」。在 / 选择器里，这一行跟第一方命令长得一样：有图标、本地化名称和本地化描述（官方展示表只覆盖第一方命令，所以客户端这一半自己挂上外观——见 AGENTS.md，「指令行的官方外观」）。
- session/flush——等待中的持久化检查点。

所有路径都汇入同一个边界——「压缩结果落入会话」——也就是 LiveUI 信号触发的那一点。

决策键是 projectedTokens（以服务商为锚，跟 UI 角落显示的是同一个数字），所以插件永远不会偏离你看到的内容；阈值感知收缩门会跳过那些可证明无法把会话拉到阈值以下的摘要器调用（干掉低阈值死循环）。

内置事务从同一个 tokenMeter.measure 按节点计价，和官方引擎用的完全一致，因此计量器的坍缩协议能正确结算这次下降——压缩后右下角计数器会下降。

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

自 2026-08 语义修订起，disableThinking 只控制一件事：这个插件自己的摘要调用（engine/builtin.js → engine/summarizer.js → ctx.llm.stream）是否携带 reasoningEffort:'off'。其他一切都不动：

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

无法表达 off 的路由会降级，而不是失败。 并非每个目录模型都声明 off 级别——pi-ai 的 thinkingLevelMap 可能把它映射为 null，就像 opencode-go/deepseek-v4.1-flash 那样（它只接受 low / high / max，而 deepseek/deepseek-flash 也接受 off）。摘要器在调用前探测路由的能力（llm.resolveCallConfig，一次不涉及服务商 I/O 的独立查询），当 off 不可用时，就用该路由确实接受的最便宜级别；完全不支持推理的模型则不带 effort 字段。由于思考型路由会把推理轨迹计入同一个 maxTokens 上限，所以在 maxSummaryTokens（文档里定义为摘要文本的上限）之上再加一笔固定的推理额度，这样摘要仍然放得下。两者都会按路由记录一次日志：

summarization route opencode-go/deepseek-v4.1-flash does not support reasoning effort 'off'
— using the cheapest supported level 'low' instead; compaction continues

在这个防护之前，这样的路由会让每一次压缩都直接失败（harness 在任何服务商 I/O 之前就拒绝不支持的 effort）。

当目标是 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 waterfall —— 早先的草稿曾在那里注入，但结构上证明无效（中间层返回会被丢弃；原地修改 seed 会让宿主崩溃）；相关说明见 src/hooks/wire-rewrite.js 的模块头注释（该模块现已退役，只保留这份历史记录）。

业务调用也需要关闭思考？在请求头层面设置服务商的 reasoningEffort —— 插件刻意不插手这个决定。

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

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

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

- 第 1 行（engine/builtin.js）记录 disableThinking 在哪里被读取、又如何路由进调用选项；设置关闭时，它记录的是机器默认值。
- 第 2 行（engine/summarizer.js）记录两个 wire 字段离开选项对象时的原样值，外加解析后的服务商/模型；未打标的字段标注为 (absent…)。

有实证支撑：针对本地 llama.cpp 端点探测，基线请求返回了带内容的 reasoning_content（模型默认会思考），而同一请求加上顶层 reasoning_effort:"none" 后返回的内容为空 —— 该字段确实能在那里关闭思考，而业务调用（省略该字段）则保持思考。

LiveUI 状态

一个极简的宿主→客户端消息器（liveUi 设置字段实时镜像到浏览器）替换官方运行标签中位于轮次旁的开头短语。只改文本：harness 自带的耗时文本、字体和颜色完全保持出厂状态。

状态文本报告当前运行的是哪一类耗时智能体操作，一类对应一个阶段。共三个阶段，每个阶段由一个智能体接缝驱动：

| 状态 | 含义 | 插入点 |
| 模型请求中 (Requesting model) | 智能体发出模型请求，正在等待首个 token | agent/request waterfall |
| 模型响应中 (Model responding) | 首个 token 已到达；持续到响应结束 | agent/assistant-stream 的首个 chunk（index === 0） |
| 工具执行中 (Running tool) | 正在运行非模型、智能体内部的操作 | tools/pre-execute waterfall |

responding 挂在首个 chunk 上，而不是该次尝试的 start 帧：start 在任何 token 到达之前就已发出（紧跟在 llm.stream(request) 调用之后），而那一刻仍属于 requesting 的区间。

压缩摘要请求从不发布这三个状态中的任何一个（用户要求排除压缩期间的请求）。这是结构性排除，不是过滤：插件（以及官方引擎）的摘要器直接调用 ctx.llm.stream，因此不经过任何 agent/request 瀑布流，不产生 agent/assistant-stream 帧，也不派发任何工具。

压缩横幅保留：

- [强制压缩中>>>] —— 就在压缩提交之前；
- [压缩完成!] —— 压缩落地的瞬间；下一个智能体动作（通常是继续循环的 模型请求中）随即覆盖它。不再有 3 秒兜底定时器；
- 会话结束时恢复 —— 当智能体进入 idle（本轮彻底结束），会推入一段空文本：客户端把官方标签放回去，并去掉自己的替换前缀。

Harness 0.2.0 把这一行移进了它自己的 RunningStatus 组件 —— 旧的 button[data-turn-process] > span 现在只渲染已结束的轮次 —— 锚定在容器属性 data-chat-running 上：

深度求索中 ← visually-hidden announcement

…whale animation (APNG mask + SVG fallback)…
<TextShimmer data-shimmer>深度求索中，用时1分14秒 ···</TextShimmer>

所以客户端这一半只替换开头那句：它拿公告节点的文本当锚点，按两者的公共前缀切分文本，保留剩余部分 —— harness 时钟尾巴、官方结尾的 ··· 都算在内 —— 原样照抄。鲸鱼动画图标和分隔线完全不动：不改颜色，不改字体，不改布局。公告节点从不触碰，所以屏幕阅读器读到的仍是官方文本。

MutationObserver 只在某个阶段活跃时连接，同时写入句子的两份副本：TextShimmer 会渲染两次（一个真实文本节点，加一个 aria-hidden 的动画高亮副本，其字形来自 CSS ::after { content: attr(data-shimmer-text) }），所以只补文本节点的话，扫光效果会露出官方措辞。观察者在 React 重写标签的同一个微任务里重新应用，所以时钟继续走，且无需轮询。

标签文本跟随应用语言：宿主写入一个与语言环境无关的 textId（阶段名）加上规范中文文本，客户端这一半通过自己的 ctx.locale zh/en/ja/ko 词典解析 —— 英文界面显示 Requesting model / Model responding / Running tool，中文界面保留原文。

徽章文本跟随应用语言：宿主写入一个与语言环境无关的 textId（阶段名或 working.N）以及规范文本，客户端这一半通过自己的 ctx.locale 词典映射到 zh/en —— 英文界面显示英文短句，中文界面显示原中文。

发布方是故障安全的：信使出故障也绝不会干扰真正的压缩。

工作原理

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 接缝无法承载 wire 字段。无导出。
- src/engine/region.js — 头/尾锚定的区域选择（带官方配对台账）。
- src/engine/summarizer.js — 一次性 LLM 摘要器，在结构上与官方 compaction-basic 对齐（目标解析、前缀缓存对齐、 purpose:'compaction' 标签、失败即关闭的结束分类、用量捕获）；摘要指令文本已本地化为中文（结构一致，文案本地化，两个 <compacted-summary> 标签原样保留）。官方引擎仍使用英文指令——见 AGENTS.md 中的「摘要指令中文化」一节。
- src/engine/builtin.js — 内置持久化事务（官方 compaction/ 词汇）。
- src/engine/checkpoint.js — 预览 + 收缩闸门 + 委托给压缩服务。
- src/core/projected.js — 服务商锚定的 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 <absolute path>

命令可用性 — /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 → <provider>/<model>: reasoningEffort='off' + reasoning_effort="none" (…)

（最后两行是「可观测性」一节描述的逐次尝试审计对。）

Settings

命名空间 falling-ts-force-compact（配置档条目的 loader id）；值写入配置档的 cordis.patch.yml（harness 0.1.7 起；此前为 $DSH_HOME/settings.yaml）：

| key | type | default | meaning |
| disableThinking | boolean | true | 只有插件自身的摘要调用携带 reasoningEffort:'off'；其余一切不变。 |
| autoThresholdTokens | number ≥ 32000 | 32000 | 门控的默认投影 token 触发值。每个没有自身覆盖值的会话都用这个值；下限 32000（读取时向上钳制）。见 Per-session threshold。 |
| retainLatestTokens | positive int ≥ 8000 | 8000 | 原样保留最新的 N 个 token；更早的历史一次性摘要。下限 8000。 同时驱动自动门控和 /force-compact。 |
| turnEndForceCompactionEnabled | boolean | true | 在智能体的 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 ms。超出范围的值会被夹紧，小数部分截断。 |

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

falling-ts-force-compact:
disableThinking: true
autoThresholdTokens: 40000 # compact sooner ⇒ keep the live prompt small
retainLatestTokens: 8000
turnEndForceCompactionEnabled: true

没有 settings 服务时，插件回退到同一套默认值，照样能压缩——这个命名空间是可选的，从来不是硬依赖。

上面每个 token 计数字段在设置表单里也接受 K / M 后缀（32K、1M，或直接写数字）；解析按十进制（32K = 32000，1M = 1000000），上面的下限和上限依然会夹紧。按会话的控制走的是同一个解析器。

按会话阈值

autoThresholdTokens 只是默认值。单个会话可以覆盖它，不用动共享的设置文档：

- 控件是输入框底部条里、上下文用量百分比右侧的那枚 chip（就是承载内置统计 pill 的同一行）。
它显示固定文案——图标加「Force-compact threshold」——这样每一行在每个会话里读起来都一样，数字也不会撑动布局。生效值、所属会话和覆盖状态放在它的 tooltip 里（面板里也有）。
- 点它打开小面板：输入阈值后点 Save，或点 use global default 撤掉覆盖。回车提交。
- 输入框接受纯数字或 K / M 后缀（123K、1M、32000）。解析不了的会被拒绝，并给出内联提示，什么也不写入；清空则回退到默认值。32000 的下限对覆盖值同样适用。
- 当 threshold < contextWindow 时，插件还会画出压缩将在哪里触发：输入框上下文圆环上的红点，位置在 threshold / contextWindow 对应的圆环角度（从十二点方向顺时针，与圆环填充方向一致），外加展开明细条上同一比例的红色竖线（高度与条本身一致）。阈值等于或高于上下文窗口时什么也不画——占用永远到不了那里，也就没有触发点可标。
- 覆盖值按会话 id 存在这个命名空间的 sessionThresholds 下，只有所属会话会读它。
每一道闸门（自动压缩、/force-compact、区域压缩、检查点、空闲）都按
sessionThresholds[sessionId] ?? autoThresholdTokens 解析。
- 键不存在本身就有意义：删掉这个键即恢复默认值，所以覆盖值永远不会伪装成全局改动。
- 芯片在两种性能与用量显示模式下都会渲染（紧凑和详细）。
内置的统计胶囊在无内容可报告时会自动隐藏；阈值胶囊则始终显示。

为低上下文 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 兜底已移除，连同它重绘的随机状态文本一并删除（见 AGENTS.md 中的 LiveUI 部分）。除此之外，插件就是纯监听器 + 一个进程本地的 Map 强制标志。

截图

设置面板 — Force Compact 区，所有旋钮均可实时编辑

设置页 — Force Compact 区；上面九个字段全部可实时编辑，无需重启。

会话页 — 状态文本替换官方标签的开头短语

会话页 — LiveUI 信号把每个运行中轮次的标签改写为当前智能体动作（模型请求中 / 模型响应中 / 工具执行中；压缩期间为 [强制压缩中>>>] / [压缩完成!]），而 harness 时钟在其后继续走动；会话结束时恢复官方标签。
截图早于 2026-09 修订：现在会显示那三个真实阶段，徽章保持官方字体的纯灰色文本。

License

MIT（见 LICENSE）。