dsh-argp

dsh plugin --profile web add dsh-argp

[English](README.en.md) | 中文

dsh-argp — 双引擎上下文压缩：逐原子守卫压缩 + 引用图确定性剪枝






dsh-argp 是 DeepSeek Harness（dsh）的第三方上下文压缩引擎：替换"让模型自由改写历史"的摘要式压缩——LLM 只提方案、确定性守卫负责处置，被压缩 / 被剪枝的原文保留在 append-only 日志、可按 seq 召回（文本块逐字；工具调用参数为 JSON 语义等价重建），压缩目标按字符口径收敛（0-LLM 图规则；字符 ≠ provider 实际 token，估算误差见「已知限制」）。双引擎形态、安装即挂、无需手工配置；显式 peratom: false 可退回纯 0-LLM 图剪枝（见[安装与挂载](#安装与挂载)）。

dsh plugin --profile <name> add dsh-argp    # 安装即挂；装好后在会话里输入 /argp 查看实时状态

三个核心机制：

• Stage-1 逐原子压缩（eager，每轮）——轮末对当轮原子做"缩放"而非丢弃：模型按原子自选 extract（逐字摘录）/ summary（概括，丢弃项入账审计）/ false（保留原文），确定性守卫裁定提案能否落地——extract 缺任一高信号 token 即整体拒绝。LLM 只提议；原文保留在只追加日志（守卫覆盖编码在内的高信号 token，非全量无损承诺）。
• Stage-2 引用图剪枝（lazy，三级触发）——原子引用图（确定性 A→R 配对边 + 模型声明的语义 cites 边）上按反向拓扑序整原子摘除，压缩阶段 0 次 LLM 调用，剪枝量按字符口径收敛到预算；触发为三级阶梯：轮初主动 / 轮中压力剪 / 截断自动续写（见"三级触发"）。
• append-only 日志是唯一事实源——被压/被剪内容原文永远在日志里，两级召回 recall_summary / recall_detail 随取随回（text 块逐字字面量，哈希测试锁定；tool-call 参数为对象时 JSON 语义等价重建并精确标注；保真仅保证结构化承重 token 逐字，散文级不保证逐字；大节点 from/limit 分页续读）。上下文是日志的一个渲染视图，不是历史本身。

为什么

摘要式压缩（LLM 重写历史）有三重代价：

1. 信息有损——精确 token（路径、错误码、配置值）在改写中最先死，且不可找回；

2. 缓存全断——重写后的历史使 system+前缀逐轮变化，跨轮 KV/prefix cache 从变化点起全部失效；

3. 压缩率失控——摘要长度由模型心情决定，预算不可兑现。

ARGP 的回答：LLM 在环内、但戴着镣铐——它的输出永远是"不可信输入提案"，守卫按 verbatim 纪律裁决；遗忘是确定性的——0-LLM 图规则保证收敛与预算；历史不可变——append-only 日志承载全部原文，召回契约（never guess）兜底。

实测（30 轮合成多轮编码任务，四臂对照，spike 37）：四臂中唯一同时达成 7/7 探针保真且成本低于现役基线的臂是双引擎全开臂（A）；传统摘要基线（D）最便宜但探针 5/7——吞掉精确字符串与关键大意。卖点不是"最便宜"，是"保真前提下最省"（A 全成本分量 ≤ 基线 C；比 D 贵 3.39×——这个差距就是保真的价格，明码标价）。

实现方式（双引擎管线、反向拓扑剪枝、shadow-price 契约、模块职责）见 [ARCHITECTURE.md](ARCHITECTURE.md)。

核心机制

Stage-1：PeratomCompressor（eager 熵降）

1. 确定性门控（gate.ts）：纯谓词判定"该轮是否可压"（长 user 消息 / 超 512 字符 tool result / 非版本链成员）；LLM 只执行"怎么压"。

2. 逐原子决策：单次 LLM 调用返回 {seq, level, text} 决策——extract（逐字子集拷贝，守卫硬拒缺失）/ summary（概括放行，丢弃 token 逐条入账 summaryDropped 供审核）/ false（显式不压，保原文）；长 user 消息走拆分（dialog 逐字抄写 + 余量聚合 U-info，空隙归 info）。

3. no-op 守卫：收益 ≤5% 的"全文照抄"副本视同 false，不 emit replace（0 收益替换白花 surface 换代）。

4. tail-only 替换：只允许 sourceEventSeqs ⊆ 当轮区间（越界即 bug，断言锁定）；前缀指纹测试证明 N 轮逐轮压缩后请求前缀稳定（缓存经济的生命线）。

Stage-2：ArgpGraphEngine（lazy 图剪枝，0-LLM）

1. 原子化 + 建图：确定性边（assistant → 其 tool result，经 toolCallId）+ 语义边（模型按契约输出的 {"cites":[{"t":"前缀","l":"c|s|x"}]}，四级分级 critical/supporting/contextual/isolated）。

2. 拓扑剪枝：反复摘除入度为 0 的原子（边等级 → 有效重要性 → 最近引用轮次排序），被剪引用方的出边消失、下游逐 pass 解锁；闭包生命周期（ACTIVE→COMPLETED→PRUNABLE→PRUNED）整闭包退休已完成任务。

3. 压缩目标按字符口径收敛（trigger/retain 均为字符×charsPerToken 估算，真实 token 以 provider usage 锚点为准，不构成逐 token 精确承诺）：触发线 window = contextWindow×0.8（默认）；保留目标 retain = 可压缩内容 × 0.2（1.5.1 起：可压缩内容 = 完整请求 − system/tools/MCP 固定开销 = 剪枝目标量 visible，恒定压缩率 80%；旧公式 retain = window×0.2 = 0.16W 把固定开销算进基数，与目标量不含固定开销不对称）。触发时机是三级阶梯（见下节"三级触发"）；降级链 lifecycle→force→fail（1.11.0-beta.1 起 summarize 档与 enableSummarize 旋钮已撤——原为恒返回 null 的 stub，与"可选降级"宣称不符）+ 反应式补救阶梯（第 2 次起放宽 recency/turn 守卫）收敛到预算或显式失败。

三级触发（Stage-2 触发阶梯）

Stage-2 的"lazy"不是单一阈值检查，而是三级阶梯（1.4.0 引入、1.5.0 修订）：

1. 轮初主动（L1）：只在每轮首个 pre-step（step === 1）做压力判定，阈值 = window（默认 contextWindow×0.8）。估值计入本步已 claim、尚未落盘进 surface 的 user 消息——宿主先 claim 新 user 消息再 dispatch pre-step，轮初拿到的是精确内容而非预测，用户轮初的大段粘贴不会漏；轮初同时跑 per-atom LLM pass（原子降熵）+ 图剪。

2. 轮中压力剪（L1'，0-LLM）：midTurnPrune 默认 true——step > 1 且压力达标时只做 0-LLM 图剪（不跑 per-atom LLM pass——那是 79s–3min 的阻塞，轮内不划算），并把 turnGuard 放宽到 midTurnTurnGuard（默认 0，允许剪本轮的旧 A/R；recencyGuard 照常保护最新节点）。超额的来源恰恰是本轮的 tool result，旧守卫（turnGuard=1）把整轮保护起来正是 1.3.x 轮中剪"几乎无效"的根因；剪落在那个 pre-step ⇒ 同一个 step 的请求即已瘦身 ⇒ 天然自动继续本 turn。

3. 截断自动续写（L3）：输出被外部钳制（finish=max-tokens 且 outputTokens < 本次请求的 maxTokens = 宿主/适配器把输出预算啃小了，容量压力的真信号）时：若本 turn 随后要结束（agent/turn-stopping 钩子）⇒ 就地强制剪 + steer 一条续写消息，同一个 turn 继续推进（用户不必再发"继续"）；否则（turn 还在跑）⇒ 下一个 pre-step 强制剪。续写文案可用 continuationNotice 覆盖（空串 = 只剪不续）；上限 reactiveRetries（默认 2，每次"连续被钳" episode 内，第 2 次起放宽 recency/turn 守卫，用尽交回 overflow 路径）。

配置旋钮：midTurnPrune（默认 true）/ midTurnTurnGuard（默认 0）/ continuationNotice（默认内置一句）/ reactiveRetries（默认 2）；1.4.0 的 midTurnActive 保留为兼容别名（true = 轮中剪开 + 沿用默认守卫的 1.3.x 对照档，false = 关）。

桥接与召回

• CiteDeclarer（每轮）：模型按窗口声明跨轮引用边，经 injectEdges 通道喂给 Stage-2——实测召回效率 ≈ 无边臂的 2.6×（zoom 精准定位）。
• RecallZoom：recall_summary(seq)（读压缩态）/ recall_detail(seq, from?, limit?)（日志原文：text 块逐字，tool-call 参数对象时 JSON 语义等价重建并标注；大节点分页续读）；4 倍制预算（summary 预算 = 4×detail），超限返回引导文案而非硬拒。历史被剪原子另有 recall_pruned / list_pruned。

模型要求

per-atom 的拆分/压缩决策质量依赖模型指令遵循能力；守卫保证任何模型上都"不会压坏"（错误方向只往少压错），但收益随服从率缩放：

• 实测基准：本地 Qwen3.6-35B-A3B / Qwen3.8-27B 全链路 30/60 轮 0 error、探针 7/7；拆分抄写表示法解析失败 0%（vs 区间定位法 72%）。
• DeepSeek 系模型的已知特性：系统提示词与用户指令冲突时（如任务 prompt 写 "nothing else"）cites 声明可为 0——语义选择性归零，但 Stage-1 守卫压缩与 Stage-2 确定性剪枝照常工作、不变式全过（50 轮 v4-flash 实证）。任务 prompt 给 cites 留出口后声明率恢复（10 轮实测 43.6%）。

安装与挂载

从 npm 安装。安装即挂、双引擎全开：peratom 缺省 = 挂（默认值落在代码里、不受各层 patch 整块替换影响，见下文「Stage-1（双引擎）：缺省即挂」），Stage-1 三管线与 Stage-2 图引擎同时生效，无需任何手工配置：

dsh plugin --profile <name> add dsh-argp

⚠️ 新版发布后 24 小时内安装，请显式指定版本。 pnpm 11 起 minimumReleaseAge 默认为 1440 分钟（24h）：刚发布的版本会被跳过，pnpm 静默回落到上一个已过冷却期的旧版本——不报错，只是装错版本。dsh-argp 每次发新版后，旧版本的 peerDeps 往往已不匹配当前宿主，于是宿主抛 Plugin dsh-argp@<旧版本> is incompatible with dsh <宿主版本>。**

…(truncated)