bojansandhaus/jev-lcm-dsh-compaction

适用于 DeepSeek Harness 的 Jev-LCM 压缩插件

License: MIT Node.js Status: RC

适用于 DeepSeek Harness 的 Jev-LCM 压缩插件 是一个实验性的 dsh-plugin 包，它在 DSH 压缩流程之前加入 Jev 评分，并在其旁边保留一个本地 SQLite 证据面。它的存在是为了回应 hermes-agent PR #116246 中报告的失败模式：仅使用 Jev 的压缩遗漏了助手文本标识符，耗尽了其状态预算，并最终遇到了不断增长的文本下限。此代码检出并不声称已在真实提供商上成功运行、达到生产环境对等性、已发布到 npm 或与 LCM 完全等价。

hermes-agent PR 116246 指出了什么问题？

PR #116246 针对生产路径评估了仅使用 Jev 的压缩，并拒绝将其作为直接替代方案。其报告的发现如下：

| 报告的发现 | 此处所代表的纠正性设计 | 当前证据 |
|---|---|---|
| 固定的 keep_threshold: 0.5 在所引用的工作负载中丢弃了全部 851 个已评分候选。 | 使用 0.15 低样本回退、0.40 上限和 0.10 最低保留率目标进行滚动校准。 | 确定性本地测试覆盖了校准。此处未复现 PR 中的分布。 |
| 工具调用排序在一个匹配预算下与近期性基线持平。 | 对选定的助手文本锚点以及调用和结果进行评分。 | 锚点测试已存在。宿主级召回率尚未验证。 |
| 仅使用 Jev 的保留留下了不断增长的文本下限，并在长时间运行中衰减。 | 保留原生 DSH 压缩作为主要宿主压缩器；Jev 仍作为排序预处理。 | 该架构已在源码中。生产环境对等性尚未验证。 |
| 25K 状态上限迫使做出盲目决策，包括一个 541 次调用的溢出案例。 | 使用 T0 到 T4 收缩阶梯，并将溢出标记为 jev_unscored。 | 541 次调用的测试夹具已在本地覆盖。 |
| 召回缺口存在于助手文本中，而不仅仅是工具结果中。 | 将标识符、约束、决策、路径和版本固定提取为锚点候选。 | 提取已在本地测试。提示接受情况尚未验证。 |
| 每轮调用干扰了提示缓存。 | 将候选按三轮批处理，并带有紧急、关闭和重置刷新。 | 批处理已在本地测试。实时缓存影响尚未测量。 |

第一列中的数字属于所引用的 PR。它们不是来自此仓库的最新测量结果。

此插件做什么？

- 在 Jev 评分之前，将原始材料摄取到该包的 SQLite 归档中。
- 对匹配的工具结果对和选定的助手文本锚点进行评分。
- 保持原始行不变。归档拥有原始证据；Jev 从不重写它。
- 使用校准，而不是被拒绝的固定 0.5 默认值。
- 对候选进行批量评分，并将超出状态上限的候选标记为 jev_unscored。
- 接受 TYPESAFE_API_KEY、OPENROUTER_API_KEY 或两者，并在 auto 模式下自动回退。
- 将 lcm_grep、lcm_expand、lcm_nodes、jev_stats、jev_providers、jev_scores、jev_anchors 和 jev_calibrate 作为会话作用域工具暴露。
- 当 Jev 被禁用或失败时，保持普通宿主压缩可用。

归档和工具属于包行为。它们并不证明每个 DSH 宿主提示都会像 Hermes LCM 那样精确消费组装后的提示。

DeepSeek Harness 上下文引擎流水线如何工作？

new turn
|
v
archive raw messages and tool material
|
v
extract assistant-text anchors
|
v
batch Jev candidates
|       T0..T4 state shaping and provider fallback
v
rank calls, results, and anchors
|
v
native DSH compaction plus bounded evidence hints
|
v
active-session tools: lcm_grep, lcm_expand, lcm_nodes

Jev 是一个排序层。它不会总结或修改原始行。候选操作包括保留、截断、延迟/丢弃或未评分。达到或超过实时阈值的候选有资格被保护性纳入，但受引擎的提示预算和宿主自身提示预算约束。被截断的候选保留有界头部和指向原始行的指针。当存储健康时，被延迟和未评分的材料仍保留在本地归档中。

收缩阶梯从完整状态开始，然后缩短工具输入和结果正文，最后折叠旧消息。如果仍然无法满足硬上限，剩余部分会被标记为 jev_unscored，而不是分配一个捏造的分数。校准从 keep_threshold 开始，然后在达到最小样本数后使用配置的滚动保留率分位数。DSH 的原生 BasicCompactionEngine 仍是宿主压缩路径；此包不是 Hermes LCM 的完整 TypeScript 移植。

我可以在此插件中使用 TypeSafe、OpenRouter 或两者吗？

可以，在配置和适配器层面可以。该仓库接受任一密钥单独使用或两者同时使用。在 auto 模式下，它会将配置的顺序过滤为具有存在密钥的提供方，尝试第一个可用的提供方，并可以针对配置的传输、超时、身份验证、速率限制或服务器故障尝试下一个提供方。一条典型的已脱敏回退行如下：

jev_provider_fallback from=typesafe to=openrouter reason=429

密钥值绝不会被打印。Jev 提供方回退仅涵盖配置的传输、超时、身份验证、速率限制和服务器故障。当前的 OpenRouter 适配器针对仓库的 /alpha/decisions 路径。在发送真实对话数据之前，请针对你打算使用的提供方验证该端点。此处不声称任何实时提供方成功。

Jev-LCM 与 Jev-alone 和 LCM-alone 相比如何？

| 方法 | 证据存储 | 助手文本定向 | 主要压缩 | 失败边界 |
|---|---|---|---|---|
| Jev-alone | 取决于宿主集成 | 原始仅工具设计会遗漏它 | 文本下限仍然存在 | 宿主相关 |
| LCM-alone | 无损存储与召回 | 没有 Jev 排序提示 | LCM 摘要 | 宿主相关 |
| Jev-LCM for DSH | 本地原始归档与恢复工具 | 提取的、有界锚点 | 原生 DSH 压缩 | 在没有 Jev 评分的情况下继续 |

这是一项架构比较，而非基准测试结果。DSH 的归档并未声称等同于 Hermes LCM 的 SQLite DAG。

PR #116246 之后发生了什么变化？

该项目遵循该 PR 的结论，即仍然需要一条摘要路径。FIX-1 增加了阈值校准。FIX-2 触及助手文本锚点。FIX-3 保持宿主压缩为主。FIX-4 增加了硬上限收缩阶梯。FIX-5 对请求进行批处理。FIX-6 暴露了 provider、threshold、unscored、freed-space 和 recall 字段。provider 链接受 TypeSafe 和 OpenRouter 凭据并带有回退。这些是实现目标和本地行为，而非与该 PR 参考路径达到生产级对等的证明。

我如何发现并将插件安装到 DSH 中？

DeepSeek Harness 是开发者预览版软件。在更改真实安装之前，请先确认 CLI 和配置文件：

dsh --help
dsh plugin --help
dsh plugin --profile web list

对于源代码检出，请使用仓库固定的工具链：

git clone https://github.com/bojansandhaus/jev-lcm-dsh-compaction.git
cd jev-lcm-dsh-compaction
npm install
npm run build
npm test
npm pack

本地测试结果和包归档并不能证明全新安装成功。并未声称已发布到注册表。在一个一次性的 DSH 配置文件中，使用宿主的插件命令安装该检出或经过审查的包。文档记载的形式为：

dsh plugin --profile web add github:bojansandhaus/jev-lcm-dsh-compaction
dsh --profile web --dump-config

经验证的 CLI 使用 dsh --profile web --dump-config。插件管理需要显式的配置文件。配置转储仅显示组合情况。它并不能证明运行时加载器已挂载、压缩已提交、provider 可实时访问或提示词对等。

仅启用一个压缩所有者。该 bundle 补丁会禁用原生 compaction-basic 行并插入 jev-lcm-compaction。请勿将此包与另一个替换同一行的 bundle 一起加载。

DSH bundle 暴露了哪些配置？

src/index.ts 中的 bundle schema 目前暴露以下 DSH 级别的值：

| 设置 | 默认值 | 含义 |
|---|---:|---|
| databasePath | jev-lcm.sqlite | 本地归档路径。 |
| thresholdRatio | 0.8 | 宿主压缩触发比率。 |
| retainRatio | 0.16 | 宿主保留比率。 |
| maxTokens | 8192 | 引擎上下文预算。 |
| auto | true | 启用自动引擎行为。 |
| jev | 宿主提供的值 | 传递给实现的 Jev 引擎配置。 |
src/settings.ts 中的引擎默认值包括 jev_provider: auto、TypeSafe 基础地址 https://api.typesafe.ai/v1、OpenRouter 基础地址 https://openrouter.ai/api、TypeSafe 路径 /systemone、OpenRouter 模型 ~typesafe/jev-latest、0.15 回退阈值、0.40 阈值上限、0.10 最低保留率、500 样本校准窗口、50 样本校准下限、三轮批处理窗口、300 候选批处理上限、25,000 token 状态上限，以及 30,000 token 请求上限。完整表格和验证规则见 docs/reference.md。

提供方的环境变量为：

export TYPESAFE_API_KEY='set-through-your-secret-manager'
or:
export OPENROUTER_API_KEY='set-through-your-secret-manager'
with both keys, leave jev_provider at auto for fallback

不要将真实凭据放入配置文件、补丁、issue、测试夹具或日志中。上面的示例值是占位符，不是凭据。

有哪些命令和工具可用？

该插件通过 Cordis 注册这些会话作用域工具：

- lcm_grep：在活动会话中搜索已归档的证据。
- lcm_expand：按存储 id 展开已归档的行。
- lcm_nodes：检查归档节点状态。
- jev_stats：读取计数器和阈值状态。
- jev_providers：检查提供方顺序、环境变量是否存在、冷却时间和经过脱敏的错误。
- jev_scores：检查候选 id、分数、操作和 jev_unscored 状态。
- jev_anchors：检查锚点候选。
- jev_calibrate：读取实时阈值和校准状态，或传入 dry_run，为每个已配置的提供方执行一次带延迟和状态的合成探测。

用于调用工具的确切 DSH 命令取决于宿主 CLI。源码注册位于 src/index.ts。将工具结果视为会话作用域的证据，而不是宿主已提交压缩的证明。

可观测性显示了什么？

jev_stats 可以暴露候选总数、保留计数、锚点计数、未评分计数、Jev 调用次数、回退次数、当前阈值和校准阈值、最后一个提供方、LCM 节点计数、文本下限估计、每次压缩释放的空间，以及未评估的召回字段。jev_providers 报告提供方顺序和存在的环境变量名称，绝不报告键值。连续三次压缩释放空间低于 20% 时，会在指标实现中产生警告。

本地测试覆盖确定性校准、提供方回退、精确跨度、溢出处理、并发和 Cordis 加载器组合。它们不验证全新安装、实时提供方质量、真实计费、生产延迟、持续会话或比较召回。

为什么为 DSH 的 Jev 压缩使用这种设计？
边界保持可见。归档保留原始证据。原生 DSH 仍负责宿主压缩。Jev 对候选进行排序，并可在其提供方不可用时退出。这为操作者提供了一个可恢复的证据面，而不会假装此包为 DeepSeek Harness 提供了具有完整 Hermes LCM 语义的无损上下文管理。

这与我的 DSH 安装兼容吗？

该包声明了 Node >=22.19.0、Cordis 4.0.2 和 DSH 0.1.6-alpha.2 对等包。DeepSeek Harness 是开发者预览版软件，因此预计会出现破坏兼容性的变更。请固定你的测试套件所使用的 DSH 范围。该仓库针对其已安装依赖具有本地构建和测试覆盖。2026-09-21 验证：一个一次性 DSH 配置文件通过宿主加载器加载了该 bundle（tests/loader.test.ts），打包的归档可从 tarball 安装，并且两个提供方面均仅使用合成文本响应了实时评分请求（见 docs/verification.md）。已针对 Node >=22.19.0、Cordis 4.0.2 和 DSH 0.1.6-alpha.2 进行测试；请固定该范围，因为该 harness 处于开发者预览阶段，可能会更改其接口。

DSH 插件约定是什么？

package.json 声明了 dsh.bundle.patch 清单，并将其指向 cordis.patch.yml。该补丁禁用了 compaction-basic 并插入了一个独特的 jev-lcm-compaction 行。src/index.ts 导出了 apply(ctx, config)，声明了 llm、tokenMeter、sessions 和 tools 注入，注册了引擎的工具，并使用了 Cordis 生命周期。示例补丁为 examples/cordis.patch.yml。请确保其行在配置文件中是唯一的。

这个项目背后的想法是谁创造的？

- Tamara Tran, fast-jev-compaction，MIT：状态塑造以及 keep/truncate/drop 谱系。
- TheEpTic, hermes-jev-compact，MIT：Hermes 集成谱系。
- Stephen Schoettler, hermes-lcm，MIT：SQLite、DAG、活动上下文和召回谱系。
- Bojan Sandhaus, jev-decisions，MIT：Decisions 形态的上下文和文档谱系。
- TypeSafe：Jev 模型和 Decisions API 谱系。
- OpenRouter：适配器使用的备用提供方面。
- Ehrlich and Blackman, Voltropy PBC：LCM 论文谱系。
- DeepSeek Harness 和 Cordis：DSH 宿主和插件生命周期。
- Hermes 维护者及 PR #116246：评估发现以及此预通过设计的原因。

本仓库是一个独立的社区集成。它不声称对上述项目拥有著作权。

常见问题
如果 Jev 宕机会发生什么？

提供方链会记录一次经过脱敏的失败，引擎可以在没有 Jev 分数的情况下继续运行。原生宿主压缩仍然可用；原始归档行为取决于本地存储是否健康。

插件会存储更多数据吗？

会。它会维护一个本地 SQLite 归档和用于恢复的元数据。该归档不会被此包加密。请设置一个私有的 databasePath，并将其排除在源代码控制之外。

我可以使用 OpenRouter 吗？

可以。设置 OPENROUTER_API_KEY 并选择 jev_provider: openrouter，或者保持启用 auto。在发送生产数据之前，请验证适配器端点和模型契约。

我可以同时使用两个密钥吗？

可以。在启用 auto 和回退的情况下，配置的顺序会选择第一个可用的提供方，并可在配置的失败情况下尝试下一个提供方。

如果 TypeSafe 被限流会发生什么？

匹配的 429 可以让 TypeSafe 进入冷却，并在存在第二个密钥时尝试 OpenRouter。该仓库会在本地测试这条链。实时提供方行为尚未验证。

它在没有 Hermes LCM 的情况下能工作吗？

这是 DSH 移植版。它包含自己的 SQLite 证据面，并与原生 DSH 压缩并行运行。它不要求外部 Hermes LCM，也不声称实现了所有 Hermes LCM 语义。

我该如何禁用它？

从一次性配置文件中移除该插件，或恢复先前的压缩行，然后在重启前转储配置文件配置。不要运行两个压缩所有者。特定于宿主的 /reset 可能会刷新待处理的引擎状态，但它不是归档删除。

它会让每一轮都变慢吗？

评分是批处理的，因此提供方调用发生在刷新时，而不一定发生在每一轮。这里不做实时延迟声明。请用你实际部署的宿主和提供方测量你的工作负载。

我可以调整阈值吗？

可以。keep_threshold 是低样本回退值。校准可以用由 keep_threshold_max 限制的滚动分位数替换它，而 min_keep_rate 设置目标下限。

缩减比例是多少？

没有通用的比例。thresholdRatio、retainRatio 和 Jev 阈值控制流水线的不同部分。请使用本地指标和你的工作负载；该仓库不发布缩减声明。

Jev 阈值校准是如何执行的？

校准器会收集观测到的概率，直到达到 jev_calibration_window。在达到 jev_calibration_min_samples 之前，它使用 keep_threshold。一旦满足最小值，它就使用配置的保留率分位数，并应用 keep_threshold_max。

为什么插件会对助手文本评分，而不是只对工具调用评分？

PR #116246 将召回缺口定位在助手文本标识符、决策和约束中。仅对工具调用评分无法对它从未接收到的材料进行排序。锚点提取器会针对这些片段进行处理，而不会重写它们。

这与 fast-jev-compaction 有何不同？
本包将 Jev 用作原生 DSH 压缩和本地归档之前的预处理步骤。它并未将 Jev 呈现为唯一的压缩器，也未声称上游项目在引用的评估之外会失败。

PR #116246 实际证明了什么？

它报告了其测试工作负载的阈值、召回率、文本下限、状态上限、助手文本和缓存发现。此检出尚未复现 PR 的主要数字。

被丢弃的结果会被删除吗？

延迟或丢弃操作会改变活动显著性。本包旨在保持原始行可恢复。操作员仍须保护 SQLite 文件，并使用 lcm_grep 和 lcm_expand 验证恢复。

本包在 npm 上可用吗？

该仓库具有包元数据，并可通过 npm pack 生成本地 tarball。未声称已发布到 npm。在注册表发布经过独立验证之前，请从经过审查的检出或归档进行安装。

这是生产就绪的吗？

不是。这是一个实验性发布候选版本。在维护的检出中，本地确定性测试通过，而干净配置文件安装、实时提供程序、宿主提示一致性、持续会话和生产基准等效性仍是未完成的验证工作。

许可证

MIT。这是一个独立的、由社区维护的集成。请参阅 LICENSE 和 THIRD_PARTY_NOTICES.md。