相关性压缩 YYTbit/dsh-plugin-jev-compaction

dsh-plugin-jev-compaction

为 DeepSeek Harness 提供 Jev 打分的上下文压缩。保留重要的消息，压缩不重要的。

为什么需要它

上下文窗口填满时，harness 按时间新旧来压缩。最旧的消息先走，要么被摘要，要么直接丢弃。这个排序跟工作本身需要什么毫无关系。

一个跑了一小时的会话长这样。

turn 2 user "do not change the public API of the parser" <- dropped
turn 7 user Traceback ... File "src/ingest/parser.py", line 118 <- dropped
turn 11 assistant "the fix belongs in src/ingest/parser.py" <- dropped
turn 31 user "ok sounds good"
turn 32 assistant "running the tests now" <- kept

后面步骤依赖的三条消息没了，因为它们旧。一分钟前的闲聊留了下来，因为它新。想恢复就得重读仓库，更糟的是，会基于一条已经不在上下文里的约束给出一个自信满满的答案。

相关性用新旧来衡量，这个代理指标一旦会话跨度变长就失效。Jev 直接给消息打分。TypeSafe System One 用一次前向传播回答一个关于某个状态的类型化问题，不生成任何输出 token，所以给一条消息打分的成本只是补全的一小部分。新旧被放回它该待的位置，当平局时的裁决。

按新旧对比按 Jev 打分

| | 按新旧（原生） | 按 Jev 打分 |
| 排序信号 | 在对话记录里的位置 | 跟当前任务的相关性 |
| 早期说过的约束 | 够旧就丢 | 保留，读起来像约束就钉住 |
| 当前故障背后的 traceback | 故障解决前就丢 | 原样保留，并钉住 |
| 上一轮的闲聊 | 保留 | 预算紧张时丢弃 |
| 端点拿不准的消息 | 没有这种状态 | 由置信度闸门保留 |
| 决策成本 | 零 | 每条消息一个类型化问题，无输出 token |
| 端点不可达时 | 不适用 | 按新旧排序，跟原生一致 |

安装

dsh plugin --profile your-profile add dsh-plugin-jev-compaction

或者从 npm 装：

npm install dsh-plugin-jev-compaction

插件需要环境里有 JEV_API_KEY。其他都有可用的默认值。

export JEV_API_KEY=...

工作原理

1. 切分。 每条消息被归约为文本、字节数和一个 SHA-256 哈希。工具调用消息、内容部分数组、纯字符串都走同一个提取器。
2. 保护。 系统消息、最后 keepRecent 条消息、以及任何匹配钉住模式的内容都原样保留，从不打分。
3. 打分。 剩下的消息被打包成批次。一个批次变成一个状态块，Jev 对每条消息问一个 score 问题，所以一批八条只花一次请求，而不是八次。
4. 闸门。 答案低于 minConfidence，说明端点拿不准，而不是这条消息可以丢掉。有疑问时，倾向于保留消息。
5. 选择。 消息按价值排序，价值相同时按新旧程度打破平局，然后逐字保留，直到字节预算用完。
6. 摘要。 没装下的内容，替换成一份抽取式摘要，放在第一条被丢弃消息的位置。摘要按价值顺序引用价值最高的被省略消息，大小取剩余预算的四分之一，并受 summaryBytes 上限约束。

字节统计基于完整消息文本的 UTF-8 字节数，而发给 Jev 的状态会把每条消息截断到 stateMessageBytes。打分时只看长消息的有界前缀，但预算仍按整条消息计算。

分数归约

请求体是 {state, question, type: 'score', levels}。question 对单条消息是字符串，对一批消息是数组。响应若给出各档位的 probabilities，就归约为均匀间隔档位上的期望值，置信度取峰值概率。响应若给出选定的 level 或直接的 score，也接受。任何无法归约为 [0, 1] 区间内数值的响应，都按失败处理。

固定保留

固定保留是确定性的，会覆盖分数。默认自带五种模式。

| 模式 | 覆盖内容 |
| 文件路径 | src/ingest/parser.py、C:\app\main.ts、configs/run.yaml |
| 堆栈跟踪 | Python traceback、File "...", line N、at fn (file:1:2) |
| 错误码 | HTTP 429 Too Many Requests、HTTP 500、status: 503、0x8007 |
| URL | 任何以 http:// 或 https:// 开头的内容 |
| 约束 | 行首或句首的 you must、do not、never、always、Important:、Note: |

pinPatterns 会追加到这些模式之后。enablePinning: false 会彻底关闭固定保留。模式编译时带 i 标志，pinFlags 可以改这个标志。ENOENT 这类 errno 风格常量只匹配大写，所以需要区分大小写的模式，并设置 pinFlags: ''。

兜底

压缩从不抛异常，也从不把消息列表弄成不可用。

- 某批失败时，改用新旧程度打分，并在报告中把这次运行标为降级。
- 如果每一批都失败，或者缺少 API key，这次运行就按时间新旧处理，也就是默认行为。
- 回执路径失败或不可写，会在统计信息里报告，不影响结果。
- 网络错误、超时、非 200 响应、无法解析的响应体，处理方式都一样。
- 受保护的消息从不丢弃，所以如果仅受保护集合就超过 targetBytes，就保留它们，并在 overBudgetBytes 里报告超出量。

回执

设置 receiptPath 后，每条消息写一行 JSON，包含内容哈希、分数、置信度、保留或丢弃的决定，以及原因，最后再写一行本次运行的摘要。只有运行确实发生了压缩才会写回执，所以预算没用完的一轮不会写任何东西。
记录下来的评分可以按不同的预算或置信度阈值重放，推理成本为零。

jev-compact compact messages.jsonl --target-bytes 60000 --scores receipts.jsonl

重放按内容哈希匹配，所以即使消息列表在回执写入之后发生了变动，也依然能对上。

接入 Harness

插件在系统提示词里注册一个策略区段，并通过 shell 环境发布自己的非机密设置。它还会探测 ctx.compaction 和 ctx.prune 上的压缩服务，一旦找到，就注册 compact(messages, task) 钩子。

核心函数已导出，所以没有压缩服务时，harness、测试或另一个插件都可以直接调用：

import { compactMessages } from 'dsh-plugin-jev-compaction'

const result = await compactMessages(messages, 'finish the parser fix', {
targetBytes: 65536,
keepRecent: 6,
})

配置

- id: jev-compaction
name: dsh-plugin-jev-compaction
inject: []
config:
targetBytes: 262144
keepRecent: 4
batchSize: 8
minConfidence: 0.35
summaryBytes: 1024
enablePinning: true
receiptPath: ~/.dsh/jev-compaction/receipts.jsonl

| 选项 | 默认值 | 含义 |
| targetBytes | 262144 | 输出字节预算 |
| keepRecent | 4 | 末尾保留的消息，无论评分多少都原样保留 |
| batchSize | 8 | 每次 Jev 请求处理的消息数 |
| minConfidence | 0.35 | 低于此值，消息出于谨慎予以保留 |
| summaryBytes | 1024 | 替换被丢弃消息的摘要上限 |
| summaryRole | system | 摘要消息的角色 |
| stateMessageBytes | 2000 | 每条消息进入 Jev 状态的字节数 |
| pinPatterns | [] | 额外的固定模式，追加到内置的五条之后 |
| enablePinning | true | 设为 false 可关闭固定 |
| pinFlags | i | 编译固定模式所用的标志 |
| endpoint | JEV_API_URL | Jev 端点 |
| apiKey | JEV_API_KEY | Jev API 密钥 |
| timeoutMs | 15000 | 单次请求超时 |
| levels | none, low, medium, high, critical | 发送给 Jev 的有序评分标签 |
| pricePerMillionTokens | 0.1 | 用于成本估算的输入价格 |
| receiptPath | 已禁用 | JSONL 决策回执路径，也会从 DSH_JEV_COMPACT_RECEIPT 读取 |
| task | 通用续写提示词 | 发送给 Jev 的任务描述 |
| runId | 自动生成 | 写入回执的标识符 |

API 密钥不会发布到 shell 环境。

命令行

jev-compact score <file.jsonl> Score messages and print a value table
jev-compact compact <file.jsonl> Compact a conversation, JSONL on stdout
jev-compact receipts <path> Summarise a decision receipts file
jev-compact doctor Check endpoint, key and effective config

输入可以是 JSON 数组、带 messages 数组的对象，或每行一个 JSON 对象。compact 把压缩后的对话写到 stdout，其统计信息写到 stderr，所以能接进管道。留下来的消息就是原始对象，原样不动。

jev-compact score session.jsonl --batch-size 8
jev-compact compact session.jsonl --target-bytes 64000 --receipt run.jsonl
jev-compact receipts run.jsonl
jev-compact doctor --probe

doctor 会把密钥打码，报告端点是否可达；加上 --probe 还会发一次真实的评分请求，端到端确认线上格式。

成本

评分只算输入。System One 不生成任何输出 token，所以一次运行的成本就是状态块的大小，每 token 四字节。默认的 pricePerMillionTokens 是 0.1，这只是个占位值，实际收多少要看端点怎么定价；命令行打印的估算和统计里记下的估算都用它。一段 24 条消息的对话，分两次请求评分，按这个占位费率算下来大约是 $0.0003。

省钱不是重点。重点是：一条消息如果丢掉，之后要恢复就得让仓库重新读一遍；现在花不到一美分就能把它留下。

相关项目

- metajev —— 这个插件逐条消息做的评分，它给出了通用形式。决策以状态、问题、模型为键；阈值放在一份策略里，策略读记录，所以换一条保留/丢弃的分界线不需要任何模型调用。
- dsh-plugin-jev-router —— 同一个上下文问题的另一端。那个插件决定一轮对话由哪个模型来服务；这个插件决定哪些消息能活到那一步。
- dsh-plugin-meta-memory 生成简要和完整两种记忆对，这个插件则负责让它们扛住压缩。
- TypeSafe System One 是评分端点背后的模型，应答地址在 https://api.typesafe.ai/v1/systemone。

License

MIT —— YYTbit