dsh-plugin-jev-compaction: 基於相關性評分的上下文壓縮

DeepSeek Harness（DSH）默認通過消息的時間順序來管理上下文窗口。當窗口填滿時，系統會丟棄最舊的消息。這種基於年齡的排序往往不精準：一條早前提到的關鍵約束、報錯堆棧或文件路徑可能因爲時間過久而被誤刪，而最近的無意義閒聊卻被保留，導致後續推理需要重新讀取倉庫或基於過時的約束給出錯誤答案。

dsh-plugin-jev-compaction 通過引入相關性評分機制解決這個問題。它利用 Jev（TypeSafe System One）直接對每條消息進行相關性打分，而非依賴時間。只有當上下文字節數超出預算時，纔會根據分數丟棄低價值消息。

核心功能¶

該插件主要解決上下文壓縮中的“誤刪”問題，提供以下能力：

Jev-scored 相關性評分
每條消息會收到一個相關性分數。系統不會盲目丟棄舊消息，而是根據分數和設定的置信度閾值（minConfidence）來決定保留或丟棄。低於閾值的消息會被保留，因爲不確定它們是否重要。
可配置的字節預算
設置 targetBytes 作爲上下文輸出的總大小上限。系統會按分數排序，優先保留高價值消息，直到填滿預算。
消息保護機制
支持通過正則模式“釘住”特定類型的消息，使其永遠不會被丟棄。默認包含五種模式：
- 文件路徑：如 src/ingest/parser.py、C:\app\main.ts。
- 堆棧跟蹤：Python 報錯、File "...", line N 等。
- 錯誤代碼：如 HTTP 429、HTTP 500、status: 503。
- URL：任何以 http:// 或 https:// 開頭的鏈接。
- 約束語句：如行首或句首的 you must、do not、never、always、Important:。
降級與容錯
如果 Jev 服務不可達、API Key 缺失或評分請求失敗，插件會自動降級爲基於時間的排序（即 DSH 默認行爲），確保上下文列表始終可用，不會報錯。
憑證日誌與重放
啓用 receiptPath 後，插件會記錄每條消息的哈希值、分數、決策及原因。這些憑證可以用於在後續推理中以零成本重放之前的評分決策。
直接 API 導出
除了作爲 DSH 策略插件運行外，插件導出的核心函數可被其他插件或測試直接調用。

安裝與啓用¶

在安裝前，請確保已配置好 Jev 的 API 密鑰環境變量 JEV_API_KEY。插件會使用 JEV_API_URL 作爲默認端點。

方式一：通過 DSH 插件管理器

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

方式二：通過 npm

npm install dsh-plugin-jev-compaction

典型用法¶

命令行工具¶

插件提供了 CLI 工具 jev-compact，用於手動處理消息列表。

# 壓縮 messages.l 文件，目標字節數爲 60000，並讀取之前的評分憑證
jev-compact compact messages.l --target-bytes 60000 --scores receipts.l

程序化調用¶

在 DSH 的代碼或其他腳本中，可以直接導入並調用壓縮函數。

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

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

配置參數¶

在 DSH 的插件配置文件中，需定義 config 字段。以下是常用參數：

- id: jev-compaction
  name: dsh-plugin-jev-compaction
  inject: []
  config:
    targetBytes: 262144        # 輸出字節預算，默認 262144
    keepRecent: 4              # 無論分數如何，始終保留最近的 N 條消息
    batchSize: 8               # 每次發送給 Jev 的消息批次大小
    minConfidence: 0.35        # 低於此置信度視爲不確定，傾向於保留
    summaryBytes: 1024         # 填充丟棄消息的摘要最大字節數
    summaryRole: system        # 摘要消息的角色
    stateMessageBytes: 2000    # 發送給 Jev 的消息截斷長度
    enablePinning: true        # 啓用消息保護（默認 true）
    receiptPath: ~/.dsh/jev-compaction/receipts.jsonl  # 憑證日誌路徑
    pinPatterns: []            # 額外的保護正則模式
    pinFlags: i                # 正則編譯標誌（默認大小寫不敏感）

適用場景與注意¶

適用場景：適用於長對話或長時間運行的推理任務，當上下文窗口即將溢出，且需要確保關鍵的約束條件、錯誤信息不被誤刪時。
環境依賴：插件需要 JEV_API_KEY 環境變量。如果環境變量缺失或 API 調用失敗，系統會退回到基於年齡的默認壓縮策略，不會中斷流程。
權限檢查：receiptPath 指定的目錄必須具有寫權限，否則僅會在統計中記錄錯誤而不影響壓縮結果。
生態背景：DSH 採用插件化架構。此插件由社區開發者 YYTbit 維護，可在 SkillHub 插件目錄查看更多詳情，源碼託管在 GitHub。