压缩续接增强 Menghuan1918/dsh-better-compact

dsh-better-compact

独立的 DSH 压缩插件。保留原生检查点事务，新增两种面向续接的摘要模式：goal（默认）和 file handoff，另带内嵌可视化设置页和只读的 inspect/models API。不需要 Apollo，不需要第二个历史数据库，也不需要自定义写入 API。

- 包名：dsh-better-compact 0.1.2
- 协议：GPL-3.0-or-later（改编自 DSH 的部分仍为 MIT；见 third-party/NOTICE）
- 宿主基线：DSH >=0.2.1-rc.2 <0.3.0（0.2.1-rc.2 为已验证构建）
- Node.js：^22.19.0 || >=24.0.0
- 纯 ESM，无构建步骤。

改动内容

BasicCompactionEngine 仍然负责 token 计量、安全截断点选择、工具配对边界、保留策略、加锁、重试、溢出恢复、持久化的 compaction/start → compaction/summary → checkpoint replacement → compaction/end 序列，以及手动 /compact。本包只定制它公开的 summarize() 钩子，以及成功后的手动续接：

| 模式 | 摘要输入 | 输出 |
| native | 已安装的原生摘要器，不做改动。 | 原生检查点；不读取 goal，不生成临时文件。 |
| goal（默认） | 重放的对话 + 当前权威的 goal/todo/questions/running jobs/children。 | 结构化的续接检查点。 |
| handoff | 同样的权威状态。 | 每次尝试生成一个临时 Markdown handoff 文件，并把同样的 Markdown 正文嵌入原生检查点；一次成功的实时手动压缩之后，可以安排一次同会话的普通后续跟进。 |

所有模式共用原生的选择、保留、计费和持久化逻辑。任何模式都不会新建会话、回答待处理问题，也不会改动 goal 状态。

安装

独立安装（不依赖 Apollo）：

dsh plugin --profile <profile> add dsh-better-compact@0.1.2

从 GitHub main 安装（次要入口）：

dsh plugin --profile <profile> add github:Menghuan1918/dsh-better-compact

安装完成或修改加载期设置后，重启 DSH 配置档（重启 DSH 进程）。刷新 Web 页面只会重载 UI，不会替换正在运行的引擎。见 apply-on-reload。

在 Web UI 中配置

在 Web 的 Plugins 页面打开 dsh-better-compact 行。它的页面就是 可视化设置页 里描述的可视化设置编辑器：三张策略卡片、摘要模型/effort、预算与保留可视化、缓存优先级、可折叠的高级选项，以及最近的原生压缩状态。它嵌入宿主现有的配置槽位，通过宿主的 configForms revision/CAS 路径保存。

同样的值也可以手动编辑配置档里的 cordis.patch.yml（宿主设置服务写入的也是这个文件）；无论用哪种方式修改，之后都要重启配置档：

- id: dsh-better-compact
config:
mode: handoff # native | goal | handoff
auto: true
thresholdRatio: 0.8
headroomTokens: 65536
retainRatio: 0.16
maxTokens: 65536

retainTokens 会取代 retainRatio（两者不要同时设置）。省略的字段采用文档给出的默认值，页面显示的是这些实际生效的值，而不是写死的示意数字。

Web：选择 better-compact 预设

随包发布的 Web 组合会禁用宿主平面的压缩行，把压缩挂载到每个智能体预设内部。bundle 补丁无法编辑预设行，所以本包自带一个可选预设：

- 创建会话时选择 Better Compact，或在 Settings → General → Agent preset 中把它设为默认预设；
- 其他预设保留各自的原生压缩引擎；宿主平面引擎检测到预设自带的引擎后会主动避让，不会重复压缩。

该预设逐字复制自已安装的 DSH 0.2.1-rc.2 standard 预设，只在压缩组内改动了一行（compaction-basic → dsh-better-compact/engine）。如果上游改动了 standard 预设，这份副本必须针对该宿主版本刷新；它不是动态引用。这份副本是 rc.2 时期的已知限制，并不代表预设组合在 DSH 各版本之间是稳定的。

Headless / TUI / 非预设组合

这些组合没有可挂载的智能体预设，因此宿主平面的引擎行就是生效的压缩服务商。/compact、自动压力触发和溢出恢复在这里无需选择预设即可工作。inspect 的 HTTP 路由在 headless 组合中不存在（没有 webserver）；这是预期行为，不影响压缩。

Apollo

Apollo 会在自己的 eng / eng-ptc 预设中声明同样的稳定行（dsh-better-compact 伴随行和 dsh-better-compact/engine 引擎行）。浏览器端在三个行键下注册同一个配置页，因此独立装配和 Apollo 装配共用一份实现：

- dsh-better-compact#dsh-better-compact
- @menghuan1918/dsh-apollo#dsh-better-compact
- dsh-apollo#dsh-better-compact

不要为了启用压缩而同时安装两个 bundle 来源；建议只保留一个显式条目。

可视化设置页

浏览器端是一个零构建的 React 闭包，由 Host 模块加载器加载（id: dsh-better-compact，只 require('react')）。它在规范行键和两个 Apollo 别名下注册同一个组件，因此独立装配和 Apollo 装配共用同一个页面和同一份 Host 表单。页面从不导入 Apollo，从不新增图表或构建依赖，只对 /better-compact/api/inspect 和 /better-compact/api/models 发起只读 GET 请求。

布局与模式

顺序是先概览、后折叠的高级项：三张模式卡片、摘要模型/强度、上下文预算与保留、缓存优先级、高级设置，最后是最近的原生压缩状态。每张卡片都有自己的内联 SVG 策略示意图，不是共用一张图或一个图标：

| 卡片 | 示意图展示的内容 |
| DSH 原生 | 较早的历史 → 原生摘要；近期原文保留；结果是原生检查点。 |
| 目标增强（默认） | 较早历史加上外部权威目标/待办 → 目标/约束/进度/下一步摘要；近期原文保留；目标保持只读。 |
| 文件交接 | 对话/状态 → 本次尝试的临时交接文件 → 原生事件存储同一正文 → 同一会话继续；近期原文保留。 |

这些卡片同属一个 role="radiogroup"；每张卡片是 role="radio"，带 aria-checked，支持鼠标和键盘选择（方向键、Home/End、空格/回车）、 focus-visible 样式和禁用状态。选中状态不只靠颜色传达：选中的卡片还会显示「✓ Selected」标签和实心单选圆点。
该区域标注为「策略示意图，不是实时 token 流或缓存命中率」。
如果选中/保存的模式与当前生效的引擎快照不一致，卡片和生效配置横幅会提示需要重新加载配置档。

会话选择与只读状态

行页面没有 session prop，因此页面使用客户端 sessions 服务快照（ids/byId）提供选择器。它会自动选中第一个可用会话，可以切回仅插件状态（无会话），并且绝不会凭空编造会话 id。选中的 id 会成为 inspect GET 上的 ?sessionId=；切换选择会中止过期请求。页面渲染原生 lastCompaction 投影（触发方式、状态、耗时、前后 token 数、模式、真实缓存用量、错误）、handoffContinuation（已调度/已跳过，外加阻塞项和「等待用户」）以及去重后的 diagnostics。它还会标明实际服务的引擎：对于外部预设的会话，页面会说明运行的是另一个压缩引擎，不绘制虚假的预算/预览，但仍显示该会话真实的压缩记录。未知值保持未知；只显示服务商上报的缓存用量，绝不显示估算的节省率。

模型、effort、预算、缓存与高级字段

- 模型/effort。 空的 provider/model 对跟随会话；显式指定的对会原子保存，且绝不改变主会话模型。不在宿主允许候选列表中的模型会保留并标记（该列表是宿主元数据，不是静默替换规则），已知不支持的 effort 会标记为错误。
空 effort 表示所选模型的默认值。候选元数据来自 GET /better-compact/api/models；当它不可用时，页面会说明能力未知，并保留可自由输入的 provider/model/effort。
- 原生模式。 增强推理 effort 和缓存优先级可见但禁用，提示「不适用：由原生实现决定」；已保存的增强值会保留以便切回，但不会声称已生效。
- 预算/保留。 图表只使用 inspect.budget：上下文窗口、当前 token 数、固定的系统/工具前缀、较早历史区域、保留尾部、配置的 thresholdRatio 与生效的 thresholdTokens，以及触发后的输出预留/余量区。页面会说明：payload 不暴露输出预留与余量的精确划分。保留量可以是比例或绝对 token 数（保存其中一个时，另一个会写成 unset 操作）；解析出的安全切点来自 inspect.preview，否则页面显示「无可计算的安全切点」。自动压力保留与更激进的手动/溢出跨度形成对比，保留尾部称为预算，不是永久固定。前后组成与 afterUpperBoundTokens 标注为上限估计，不是预测。容量、固定前缀、保留量与触发条件、无安全区域这几类诊断会指出该调整哪个控件。
- 缓存优先级。 开关文案固定为「优先复用缓存（尽可能保留 KV Cache 前缀）」。说明覆盖前缀复用、模型切换开销、替换后的前缀失效；绝不声称无损 KV 复用或零缓存丢失。
- 高级。 auto、headroomTokens、maxTokens、compactionRetries（压缩后压力重试）和 maxOverflowRetries（上下文溢出恢复）可编辑，两种重试的含义分别说明。生效的 modelPolicies 只读展示；全局表单从不写入或丢弃它们。没有 handoff 目录、压缩历史、记忆或 sidecar 控件。

保存与重载时应用

页面编辑一份本地草稿，只通过 form.mutate(ops, expectedRevision) 保存——每次保存一次原子变更，一个预期修订号，没有插件自有的写入路由。它遵守 Host 表单的加载中/不可用/只读状态。如果草稿有暂存编辑时 Host 修订号变化，页面会明确报冲突并禁用保存，提供「重载 host 值」操作；不会静默覆盖更新的配置。保存被拒或传输错误会保留草稿，绝不显示成功。成功后页面显示 saved — reload profile，并说明刷新网页不会重载引擎：重启 DSH 进程才能应用新快照。

无障碍与已知限制

使用中性 host 表面和细边框，只用一种强调色，状态色仅用于错误/警告，数字用等宽数字，单位可见。窄屏下布局纵向堆叠；SVG 保持可读；浅色/深色表面来自 host 主题 token；prefers-reduced-motion 会禁用过渡。每个控件都有无障碍标签，图表有等价文本。页面由 React 组件测试覆盖（react-test-renderer、伪造 form/fetch），没有当前 GUI 的视觉检查；那项验收属于 S4。策略图是语义示意，不能作为实时 token 流、缓存命中率或成功压缩的证据。

Configuration
宿主配套行 dsh-better-compact 负责管理 schema。原生键名、单位和含义沿用 @deepseek-ai/dsh-compaction-basic 0.2.1-rc.2；仅增强版才有的键会在原生基础层看到它们之前被剥离。

| 键 | 默认值 | 约束 / 含义 |
| mode | goal | native / goal / handoff。 |
| auto | true | 开启或关闭自动压力/溢出恢复；手动 /compact 仍然可用。 |
| thresholdRatio | 0.8 | 请求压力占比，取值在 (0, 1) 内；触发点为 floor(min(W × ratio, W − O − headroom))。 |
| headroomTokens | 65536 | 非负的额外压力余量，叠加在已路由的输出预留 O 之上。 |
| retainRatio / retainTokens | ratio 0.16 | 近期尾部预算，两者互斥；绝对 token 数必须低于解析后的触发点。只存其中一种形式。 |
| summarizationProvider / summarizationModel | 两者均为 "" | 空对 = 继承路由（最近一次路由请求，然后是 AgentOptions）。非空对必须一起设置。 |
| reasoningEffort | "" | 空 = 所选摘要模型自身的默认值。非空时必须是该模型实际公布的 effort id。 |
| cachePriority | true | 优先保留对话的 system/tools/history 前缀，让辅助调用成为真正的前缀；false 则发送更精简的请求，不带工具声明。 |
| maxTokens | 跟随解析后的 headroomTokens | 正的摘要输出上限，与输入一起计入模型上下文窗口。 |
| compactionRetries | 1 | 压缩成功后压力仍存在时的额外尝试次数（不是网络重试次数）。 |
| maxOverflowRetries | 1 | 服务商确认的上下文溢出恢复次数上限；0 表示禁用恢复。 |
| modelPolicies | [] | 精确的 {provider, model, ...native partial policy} 覆盖，沿用原生语义；本版本没有可视化规则编辑器。 |

未解析的检查在加载/重载时强制执行，可视化设置表单也会校验：互斥的保留形式、摘要对为空/非空、retainRatio < thresholdRatio、正的输出上限、重复/未知的模型策略、没有显式 maxTokens 时余量为零，以及正整数计数。未知的顶层键和 modelPolicies 条目内的未知键会在加载时被拒绝，并给出违规键和支持的键列表，因此手动 cordis.patch.yml 路径里的拼写错误不会被静默忽略。保存的值无效时，行重载会失败并给出可操作的提示，而不是静默强制转换。

重载时应用

所有字段都是易变的：原生设置服务可以保存它们而无需重新挂载该行，revision/CAS 可防止静默覆盖。因此引擎在加载时取一份冻结快照：

- inspect 响应中的 activeConfig 是运行中引擎实际持有的配置；
- 保存的值与该快照不同时，requiresReload 变为 true；
- 保存绝不会重新配置运行中的引擎；
- 重启 DSH 配置档，让新快照生效。

这是对 DSH 0.2.1-rc.2 最贴近实情的对应说明：该版本自身没有宿主「已保存但需要重新加载」这种状态。

推理强度与缓存优先级

- native 模式把这些选项报告为不适用：继承来的原生摘要器自行决定请求形态。已保存的增强值会保留，方便切回时使用。
- 在 goal/handoff 下，非空的推理强度会针对确切的摘要模型，用 ctx.llm.resolveModelInfo() 校验。不支持的 id 会在服务商 I/O 之前被拒绝，绝不会被替换成 off/high/其他模型。能力未知时，对显式取值按不支持处理。
- cachePriority: true 复用原生前缀形态（系统提示词、工具 schema/工具历史、被遮蔽的消息，最后是末尾的指令）。cachePriority: false 省略工具声明和工具历史；这不代表服务商会关闭缓存。
- 更换摘要模型/服务商可能让热前缀失效；这是真实的取舍，插件无法隐藏这笔开销。

容量与预算诊断

摘要请求受实际选中的模型路由约束：

- 触发/保留严格遵循原生公式，不引入第二套 token 单位；
- 辅助请求用同一套固定估算器计价（estimateMessage / estimateToolsTokens）；
- 如果完整的权威状态放不下，就按固定顺序缩减状态——先丢掉通常很大的 todo 列表，同时保留待处理的问题/任务/运行中的子代理，然后只留目标，最后不留状态——指令里会带上明确的 ## Budget note，逐项说明省略了什么。省略内容也会在 inspect 的 diagnostics 中暴露；
- 如果连不带状态的请求都放不下，本次尝试以 BETTER_COMPACT_BUDGET 失败，并给出可操作的提示（压缩更小的区间、调低 maxTokens，或换更大的模型）。插件绝不会悄悄截断或缩小历史。

保留的真实情况

retainRatio/retainTokens 只作用于自动压力路径。原生手动 compactNow 和上下文溢出恢复有意使用 retainTokens = 0（最大程度的均衡缩减），与已安装引擎保持一致。保留的尾部是预算，不是永久钉住：溢出恢复可能选择更激进的安全区间。inspect API 中的预览只反映自动压力规则，不承诺手动/溢出时的范围。

模式详解

goal（默认）

摘要器读取实时的权威目标（存在时用 ctx.goals.get(agent)）、当前 todo 投影、待处理的用户问题、会话拥有的任务，以及运行中的子代理；全部只读且可选。指令要求给出：

- 当前目标与未解决的用户请求；
- 约束、偏好与已批准的边界；
- 决策及其理由；
- 已完成 / 进行中 / 受阻的工作；
- 已验证与未验证的结果；
- 确切的产物、文件、命令、错误、标识符；
- 下一步操作。

提示词与输出检查强制执行的规则：较新的历史记录优先于较旧的检查点；先前检查点的目标状态不具备权威性；未完成的工作不得标记为完成；待处理的问题、任务、子代理是需要等待的事实，而不是要回答或停止的事项；机密信息应当脱敏；确切的标识符应当保留；输出必须包含每个必需章节。该检查是一道退化/截断防护，并非没有丢失任何事实的证明。

如果没有目标服务，或者不存在目标，压缩仍会正常运行；提示词明确说明不要从旧检查点文本推断目标。原生 todo 投影的作用域是单个轮次（turn/start 会重置它），因此轮次开始时触发的自动压力压缩通常没有 todo 列表可注入；手动空闲压缩通常能看到上一轮的列表。没有任何变通做法会把该列表复制到另一个存储中。

handoff

模型会为另一个智能体写一份交接文档，让它继续同一个会话，遵循同样的权威规则，并额外包含一个 Suggested Skills 章节，该章节仅供参考。然后：

1. 在操作系统临时目录下（os.tmpdir()，即 Unix 的 TMPDIR 或 /tmp）创建一个全新的按尝试划分的目录；
2. 最终文档——包括实际文件路径、会话 id 和创建时间，放在确定性的头部——以仅所有者可访问的权限写入，逐字节读回，并按平台验证：在 POSIX 上，文件必须报告模式 0600，尝试目录为 0700； Windows 没有 POSIX 模式位（stat.mode 只反映只读属性），因此在那里跳过 POSIX 断言，证据是每用户的操作系统临时目录加上精确的读回结果。用 Node 标准库做 ACL 检查不现实，因此不作此声明；
3. 同一份文档作为摘要正文返回，因此原生检查点替换是自包含的；之后删除文件不会破坏重放；
4. 当且仅当这是一次实时、成功的手动 compactNow，智能体处于空闲且没有排队输入，目标未暂停/阻塞，并且没有待处理的用户问题、正在运行的任务或正在运行的子代理时，通过原生同智能体输入机制（agent.followup(createUserMessage(...))）恰好入队一个普通后续消息。

该续接绝不会恢复/重新武装目标、回答问题、在轮次进行中启动必需的轮次、创建/切换会话，或使用 sidecar。重放、页面刷新或插件重载都无法重新触发它，因为触发条件是实时的手动调用，而不是会话事件。如果进程在成功提交与入队之间死亡，检查点已经持久化，但续接没有；这个缺口是真实存在的，不声称其具备原子性。用户可以在同一会话中手动继续。

交接文件不会安排清理；它们与操作系统临时目录。它们只是方便使用的副本，从来不是唯一的恢复来源。密钥脱敏采用保守的模式匹配（sk-、GitHub/Slack/AWS/Google token、bearer token、私钥块、赋值式密码/密钥）；它无法识别所有凭据格式。

失败、取消与恢复

| 情况 | 行为 |
| 自动压力摘要在替换前失败 | 发出警告；保留最新的持久化表面（修剪或更早的替换可能已经落地），本轮继续。后续轮次可能压缩成功。 |
| 手动摘要失败 | 原生命令报出基于 ManualCompactionError 的错误（could not produce a useful summary）；记录本次尝试；不安装检查点。 |
| 服务商确认上下文溢出 | 原生有界恢复（maxOverflowRetries）；失败时保留真实请求错误。 |
| 替换已追加，持久化刷写失败 | 原生 ManualCompactionError('persistence')：历史可能已改变，但保存失败；不声称回滚。若本进程观察到该情况，lastCompaction.status 为 persistence-error。 |
| compaction/end 无法追加 | 原生提交阶段失败：摘要/替换可能已经持久化，而括号仍未闭合；命令报出「did not finish cleanly」。inspect 报告 failed 并附带记录的错误；不声称回滚，也不伪造 completed。 |
| 取消 / 待处理用户 / 暂停目标 | 摘要或续写停止；不复活任何目标；不为用户回答任何问题。 |
| 没有安全可用的范围 | 原生 no-op/null 并附带原因；不伪造检查点。 |
| 无效的模型/effort/容量 | 给出可操作的错误；绝不静默回退到原生或模型。 |
| 增强输出为空/截断/退化 | 在安装前拒绝（BETTER_COMPACT_STRUCTURE、MAX_TOKENS）；走原生错误路径。 |

增强模式绝不自动回退到原生模式。原生模式本身就是继承的实现，与同一原生配置字节兼容。正如设计要求：外部原生恢复监听器（compaction/summary-error）可能在后续失败之前已经写入持久化变更；因此「自动压缩失败」绝不意味着「会话没有副作用」。inspect 保留记录的尝试及其错误，而不是声称干净回滚。

只读 inspect 与 models API

GET /better-compact/api/inspect，可选 ?sessionId=<id>。

GET /better-compact/api/models（无会话）返回宿主允许的候选路由及其公布的推理 effort： json { "enabled": true,
"routes": [{ "provider": "p", "model": "m", "efforts": ["low", "high"], "defaultEffort": "low" }]
}

models 投影读取可选的宿主 subagentModelSelection 服务的 current().allowedModels，并用 ctx.llm.resolveModelInfo(provider, model).reasoning.efforts 丰富每个条目。它属于元数据只在页面加载时：不进行服务商 I/O，不调用命令行，也不枚举模型。如果服务不存在或没有目录，响应为 { "enabled": false, "routes": [] }；单条路由的能力查询失败，只会清空该路由的 efforts，可视化页面回退到自由文本填写服务商/模型/effort，并附上「unknown」能力说明。该列表是宿主允许的候选元数据，并不证明某条路由在当前会话中可用。

只有 同时 存在 Host webserver 和 Host connection 信任围栏时，两条路由才会注册。有 webserver 但没有围栏时按失败关闭处理：路由不注册；若围栏消失，已注册的处理器返回 503。每个请求都要过 connection.requestRejection(req)（401/403）；只接受 GET（405）；inspect 查询要校验（sessionId 未知/重复/为空返回 400）；会话未知或不可见返回 404；每个 JSON 响应都带 cache-control: no-store。models 路由不依赖会话，忽略查询参数。没有写 API，不允许跨源，也没有插件自带的信任开关。可视化设置页把这些响应体当作 token/会话/状态值的唯一事实来源。

响应字段（未知值为 null，绝不为 0）：

| 字段 | 含义 |
| activeConfig | 当前引擎实例持有的冻结配置。不含凭据。 |
| requiresReload | 已保存的值与 activeConfig 不同（包括已保存的值不再能归一化的情况）。 |
| sessionId | 回显请求的会话；没有会话时为 null。 |
| diagnostics | 始终是只读字符串数组，供可视化设置页使用。它承载 token 计量/模型信息失败、预算容量原因、上次摘要的预算省略项，以及引擎适用性原因（一切可用时为空）。 |
| engine | 没有会话时为 null，否则为 {owner, inspectApplies, reason}。owner 取值为 host、better-compact-preset、foreign-preset 或 unknown。外部预设（例如随附的 Web standard 预设）运行自己的原生引擎，因此 inspectApplies: false，budget/preview 为 null，lastCompaction 仍从该会话的真实事件投影得出。冷会话/非活动会话无法证明归属，报告为 unknown，并附带当前配置。 |
| budget | 没有会话时为 null，否则为 {contextWindow, currentTokens, measurement, fixedTokens, thresholdTokens, retainTokens, summaryMaxTokens}。measurement 取值为 measured（服务商用量锚点）、estimated（固定启发式）或 unavailable。 |
| preview | 没有可用会话时为 null，否则为 {beforeTokens, afterUpperBoundTokens, rangeStart, rangeEnd, reason}。rangeStart/rangeEnd 是自动压力安全截断规则给出的原生表面 seq；afterUpperBoundTokens 包含摘要输出预算，是上界估计，不是预测。reason 说明低于触发阈值/无范围/不可用。 |
| lastCompaction | 没有压缩记录时为 null，否则为 {id, trigger, status, mode, beforeTokens, afterTokens, durationMs, cacheReadTokens, cacheWriteTokens, error}，只从真实事件和用量数据投影得出。 |
| handoffContinuation | 本进程尚未做出手动交接续接决定前为 null，否则为 {compactionId, status: 'scheduled'\|'skipped', blockers, at}。blockers 会列出排队中的输入、已暂停或阻塞的目标、待回答问题、运行中的任务、运行中的子进程、取消操作或队列故障，让可视化设置页能显示为什么没有继续。 |

lastCompaction 规则：

- trigger：独立压缩（turn: null）为 manual，归属某一轮的压缩为 automatic；日志无法区分压力触发和溢出触发，因此两者都是 automatic。
- status：running | completed | failed | cancelled | persistence-error。只有内存中正在进行的摘要尝试才标记为 running；孤立且未匹配到结束事件的开始记录报告为 failed，而不是伪装成活跃进程。cancelled 从记录的 abort/cancel 错误识别。persistence-error 只有本进程在成功追加后 flush 失败时才能观察到；仅看已持久化的日志，它看起来是 completed。
- 只有检查点结构能证明时，mode 才是 native/goal/handoff；更早或外来的记录为 null。
- 未闭合括号上记录的 commit/append 失败会显示在 error 中，而不是静默报告为 failed 且 error: null。
- 只有摘要事件携带真实服务商用量时，才报告 cacheReadTokens/cacheWriteTokens；缺失不等于零。不编造「节省百分比」。

只读保证：检查过程不生成 LLM 内容、不执行压缩、不调用命令行、不写临时文件、不改动目标或会话。冷会话通过 ctx.sessionQuery.observeSession 读取，并重放进一个独立的 Session，复用同一个单例 token 计量器；如果重建或计量器失败，相关数字标记为不可用，而不是用第二套算法计算。

宿主漂移与限制（DSH 0.2.1-rc.2）

- Web 压缩归预设所有；本包无法全局替换它。宿主平面引擎用于无头/TUI 场景，以及没有压缩组的预设，并会检测预设自有的引擎以避免重复工作。
- 没有宿主重载状态。保存是易失且立即生效的；加载时快照的变更需要重启配置档。
- 随包提供的 preset-better-compact 是 rc.2 标准预设的固定副本。更改 DSH 基线时需重新验证/刷新它。
- 检查 API 除 Host 信任围栏外没有单独认证。
- 每个上下文/领域只能有一个压缩服务商。不要在本包旁边再挂一行压缩引擎；不建议使用两个显式包。

许可

本包采用 GPL-3.0-or-later。少量实质性部分改编自 MIT DeepSeek Harness 软件包（预算公式、摘要请求结构、详细输出）

preset copy) remain under MIT; copyright and license text are preserved in
third-party/LICENSE-MIT-dsh and described in
third-party/NOTICE. The goal/handoff prompt text is new;
pi-atlas, xbot, OpenCode, and Codex are cited design references, not copied
source.

Verification status

Verified in this repository (see docs/DEVELOPMENT.md):

- unit tests (node --test) for config validation/defaults, native budget
formulas and safe-cut selection, prompt/state/redaction, handoff file
permissions/read-back, engine routing/effort/failure/continuation gating,
inspect projection/null semantics/fence, models-route projection/fence,
preset copy, and the visual client's mode cards, model/effort, budget,
retention, save/revision/conflict/transport, status and accessibility states
with fake form/fetch;
- a real-profile smoke with a temp DSH_HOME, scripted LLM adapter, real
AgentLoop/session log/token meter/commands/settings/config-editor/webserver,
real Connection authentication, real job registry, and real child agents:
automatic pressure, manual /compact, native event sequence, authenticated
inspect over HTTP (401/400/404/405/no-store), the models route over the same
fence and its real allowed-model catalog (401/405/no-store), failure/recovery,
handoff file + redacted raw output + one continuation + replay after file
deletion, a real standard-preset foreign-engine session, injected
durability-flush failure (session/flush listener; the real JSONL writer still
runs), in-flight cancellation, commit-stage append failure, pending-
question/job/child continuation gates, preset isolation/no double-compaction,
and save → reload → activeConfig update. Manual handoff continuation is
exercised on the host-plane engine; the preset engine's automatic path is
covered, and the preset manual path shares the same engine code. Run the exact
commands for the current test counts.

The current build was verified with 115 unit/component tests and 45
real-profile smoke checks* at commit time; always prefer the fresh command
output over these numbers.

Not verified here: real-model summary fidelity, reasoning-effort quality,
provider cache-read/write hit rates against a real provider, and a visual/
keyboard acceptance pass in the current GUI. The visual settings behavior above
is covered by React component tests and the backend routes by the real-profile
smoke; the current GUI/URL check belongs to S4. Do not infer GUI acceptance from
the controlled-provider or component tests.