dsh-compact-provider

dsh-compact-provider — 压缩入口（挂载 + 显式工具）

一句话：把自研压缩引擎（dsh-agent-compact）挂成宿主 compaction 服务，并注册 session_compact 工具——压缩何时发生由 agent 自主决策，框架零强制。

为什么值得用：引擎是压缩事务的执行者，本插件是它的入口与门房——管前置判据、管决策留痕。主路径其实不需要这个工具：在任意一轮输出里直接写 checkpoint 块即可（零额外请求）；工具是「不想把 checkpoint 写进正文」或「需要显式可控入口」时的第二入口。

⚠ 本插件与引擎是回退对（provider 0.3.0 ↔ 引擎 0.2.1），同进同退，禁止单侧回退。

定位与反定位

• 管：入口约束（summary 必填 → compaction seam 在位 → agent 上下文在位）、显式入口、请求侧留痕。
• 不管：压缩事务（识别/换血/幂等 → 引擎）；压缩前存档（→ 引擎，2026-09-27 移交）；「什么时候压」的决策（→ agent 自主，本插件只提供原语）。
• 不是自动压缩：本插件无任何定时器/阈值触发。

能力

快速开始

# 预设行（与引擎成对挂载）
- id: compact-provider
  name: dsh-compact-provider
  config:
    enabled: true
    minCheckpointChars: 200

安装走 self-plugins/ link 依赖 + 预设行（详见生态中心仓）。必须与 dsh-agent-compact 同挂同停——provider 单独拉起会在 seam 缺失时报错。

配置

复用引擎的 CompactConfig schema（只有两项：enabled 与 minCheckpointChars，全表见引擎 README 与 docs/semantic.md §4.1）。本插件自身无独立配置——这是刻意的：入口与引擎共享同一批裁决参数，不存在两处漂移。

⚠ 引擎 0.2.0 起旧策略键已全部删除（thresholdRatio / retainRatio / auto / modelPolicies …）。组合里留着旧键会装载失败——升级时先清 config。

落盘与自证

每次 session_compact 调用，请求侧落这些阶段（与引擎侧 detected→committed / rejected / abort 按 atMs 天然 join 成一笔）：

grep '"side":"provider"' "$DSH_HOME/compaction-trace.jsonl" | tail -3
# ② 谁发起 → agentId + commandId + reason
# ③ 断在哪 → rejected（判据没过）vs failed（seam 抛错）vs completed（往下看引擎阶段）
# ④ 结果质量 → chars

判据单一真源：路径解析/序列化/追加实现全部从引擎转出（import { compactTrace } from 'dsh-agent-compact'），本插件不自己实现第二套。

生效判据与回退

生效判据：

1. 调一次 session_compact {}（缺 summary 即触发 rejected）→ grep '"phase":"rejected"' "$DSH_HOME/compaction-trace.jsonl" 应出现该行；
2. plugin_boot_status 的 liveNow 含本插件；
3. 行为级：真压缩一次 compaction/end 无 error + 上下文 token 实际下降。

重新构建 ≠ 生效；且注意 C7：新增源文件（如引擎的 src/marker.ts）不会自动出现在本插件 node_modules 里对引擎的 pnpm hardlink 副本中——改了引擎新增文件后必须先查消费方副本文件集再重启（预检会替你拦）。

回退：

• 源码级：git revert <commit> → 重建 → preflight_check（full）→ 重启；
• 组合级：disabled: true（引擎同步停）；
• 版本级：与引擎是回退对（0.3.0 ↔ 0.2.1），不可只回退一侧。

测试

npm test        # node --test "tests/*.test.mjs"

29 例离线测试：policy.test.mjs（前置判据 / 非字符串 summary 的形状防御——模型给 JSON 不得抛错 / 文案构造）+ trace-request.test.mjs（阶段条目构造、reason 摘要、agent 标识安全取用、serialize→parse 往返证明与引擎判据同源、两写者按 atMs join、尸体测试——父路径是普通文件时 appendTraceEntry 返回 false 且不抛）。

设计要点

• summary 必填：本工具的语义是「用这份 checkpoint 替换历史」——旧契约「调用后等下轮输出」需要指令投递链，那条链已整体删除。缺参会得到明确的 rejected 而不是静默无事发生。
• 不传 exec.signal：工具回合被打断（abort）会触发 agent 取消导致 seam 永不 resolve——用独立 controller 让压缩事务与工具回合解耦。
• 观测绝不反噬：compactTrace 返回 bool，一律忽略——它只影响证据，绝不影响压缩是否发生。

相关文档

License

MIT © jonah791

---

本插件属于爱丽丝 DSH 自研插件生态（见 alice-digital-life）。